refactor: merge cas get/cat into get, default hides timestamp

- Remove `cas cat` command
- `cas get` now returns {type, payload} by default
- Add `--timestamp` flag to include timestamp

Refs #328

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [["@uncaged/*"]],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": ["@uncaged/workflow-dashboard"]
+}

.changeset/env-api-unify.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util": patch
+---
+
+Replace optionalEnv/requireEnv with unified env(name, fallback) API

.changeset/fix-internal-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: correct internal dependency versions for prerelease

.changeset/fix-publish-src.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-util-agent": patch
+---
+
+fix: include create-agent-adapter.ts in published src

.changeset/fix-workspace-deps.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": patch
+---
+
+fix: use npm publish with pinned deps instead of bun publish (workspace:^ resolution bug)

.changeset/pre.json

@@ -0,0 +1,30 @@
+{
+  "mode": "pre",
+  "tag": "alpha",
+  "initialVersions": {
+    "@uncaged/cli-workflow": "0.4.5",
+    "@uncaged/workflow-agent-cursor": "0.4.5",
+    "@uncaged/workflow-agent-hermes": "0.4.5",
+    "@uncaged/workflow-agent-llm": "0.4.5",
+    "@uncaged/workflow-agent-react": "0.4.5",
+    "@uncaged/workflow-cas": "0.4.5",
+    "@uncaged/workflow-dashboard": "0.1.0",
+    "@uncaged/workflow-execute": "0.4.5",
+    "@uncaged/workflow-gateway": "0.4.5",
+    "@uncaged/workflow-protocol": "0.4.5",
+    "@uncaged/workflow-reactor": "0.4.5",
+    "@uncaged/workflow-register": "0.4.5",
+    "@uncaged/workflow-runtime": "0.4.5",
+    "@uncaged/workflow-template-develop": "0.4.5",
+    "@uncaged/workflow-template-solve-issue": "0.4.5",
+    "@uncaged/workflow-util": "0.4.5",
+    "@uncaged/workflow-util-agent": "0.4.5"
+  },
+  "changesets": [
+    "env-api-unify",
+    "fix-internal-deps",
+    "fix-publish-src",
+    "fix-workspace-deps",
+    "rfc-252-agent-fn"
+  ]
+}

.changeset/rfc-252-agent-fn.md

@@ -0,0 +1,5 @@
+---
+"@uncaged/workflow-protocol": minor
+---
+
+feat: AgentFn<Opt> type boundary and createAgentAdapter bridging function (RFC #252)

.env.example

@@ -0,0 +1,40 @@
+# ──────────────────────────────────────────────
+# Workflow Engine — Environment Variables
+# ──────────────────────────────────────────────
+# Copy this file to .env and fill in the values.
+
+# ── Cursor Agent ──
+
+# CLI command to invoke the Cursor agent (required for develop workflow)
+WORKFLOW_CURSOR_COMMAND=
+
+# Model override for Cursor agent
+WORKFLOW_CURSOR_MODEL=
+
+# Timeout in milliseconds for Cursor agent operations
+WORKFLOW_CURSOR_TIMEOUT=
+
+# ── Hermes Agent (used by develop tester/committer + solve-issue) ──
+
+# CLI command to invoke the Hermes agent (absolute path required)
+WORKFLOW_HERMES_COMMAND=
+
+# Model override for Hermes agent
+WORKFLOW_HERMES_MODEL=
+
+# Timeout in milliseconds for Hermes agent operations
+WORKFLOW_HERMES_TIMEOUT=
+
+# ── Storage ──
+
+# Override the workflow storage root directory
+# Default: ~/.uncaged/workflow
+WORKFLOW_STORAGE_ROOT=
+
+# Gateway secret for the serve command
+WORKFLOW_DASHBOARD_SECRET=
+
+# ── Display ──
+
+# Set to any value to disable colored output
+# NO_COLOR=1

.githooks/pre-push

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "🔍 Running check (tsc + biome + lint-log-tags)..."
+bun run check
+
+echo "🧪 Running tests..."
+bun run test
+
+echo "✅ All checks passed!"

.gitignore

@@ -4,3 +4,9 @@ bun.lock
 *.tgz
 tsconfig.tsbuildinfo
 .npmrc
+
+bunfig.toml
+xiaoju/
+solve-issue-entry.ts
+packages/workflow-template-develop/develop.esm.js
+.DS_Store

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-**@uncaged/workflow** is a workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file with an XXH64 hash as its version identifier.
+This monorepo implements a workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file with an XXH64 hash as its version identifier. Shared types live in `@uncaged/workflow-protocol`; bundle authors typically depend on `@uncaged/workflow-runtime`.
 
 ### Key Terms
 
@@ -10,7 +10,7 @@
 |---------|-----------|
 | **Workflow** | A single-file ESM module that exports `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash (Crockford Base32). |
 | **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
-| **Thread** | A single execution of a workflow, identified by a ULID. Persisted as `.data.jsonl` + `.info.jsonl`. |
+| **Thread** | A single execution of a workflow, identified by a ULID. State lives in CAS (linked nodes); active threads indexed in `threads.json`; completed rows in `history/*.jsonl`. Debug logs use `.info.jsonl`. |
 | **Role** | A named actor within a workflow. Each role produces output with typed `meta`. |
 | **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
 
@@ -19,15 +19,29 @@
 ```
 workflow/
   packages/
-    workflow/       # @uncaged/workflow — core lib (types, hash, ULID, JSONL, registry)
-    cli-workflow/   # @uncaged/cli-workflow — CLI (uncaged-workflow command)
+    workflow-protocol/              # @uncaged/workflow-protocol — shared types + Result
+    workflow-runtime/               # @uncaged/workflow-runtime — createWorkflow, type re-exports
+    workflow-util/                  # @uncaged/workflow-util — Base32, ULID, logger, storage paths, refs helpers
+    workflow-reactor/               # @uncaged/workflow-reactor — LLM fn + thread reactor (tool calls)
+    workflow-cas/                   # @uncaged/workflow-cas — CAS store, hash, Merkle
+    workflow-register/              # @uncaged/workflow-register — bundle validation, registry YAML, model resolution
+    workflow-execute/               # @uncaged/workflow-execute — engine, extract, fork, GC, workflowAsAgent
+    cli-workflow/                   # @uncaged/cli-workflow — uncaged-workflow CLI
+    workflow-agent-cursor/          # @uncaged/workflow-agent-cursor
+    workflow-agent-hermes/          # @uncaged/workflow-agent-hermes
+    workflow-agent-llm/             # @uncaged/workflow-agent-llm
+    workflow-agent-react/             # @uncaged/workflow-agent-react
+    workflow-util-agent/            # @uncaged/workflow-util-agent — buildAgentPrompt, spawnCli
+    workflow-template-develop/      # @uncaged/workflow-template-develop
+    workflow-template-solve-issue/  # @uncaged/workflow-template-solve-issue
+    workflow-dashboard/             # @uncaged/workflow-dashboard — React dashboard (private app)
   docs/             # RFCs, conventions
   biome.json        # root Biome config
   tsconfig.json     # root TypeScript config
 ```
 
-- `workflow` is the core; `cli-workflow` depends on it
-- Packages use `workspace:*` protocol
+- Execution stack layers: `workflow-protocol` → (`workflow-runtime`, `workflow-util`, `workflow-reactor`) → (`workflow-cas`, `workflow-register`) → `workflow-execute` → `cli-workflow`
+- Packages use `workspace:^` protocol (resolves to `^x.y.z` on publish)
 
 ## Language & Paradigm
 
@@ -167,10 +181,10 @@ type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
 
 Never use `console.log/warn/error` directly — Biome's `noConsole` rule enforces this.
 
-All logging goes through the structured logger from `@uncaged/workflow`:
+All logging goes through the structured logger from `@uncaged/workflow-util`:
 
 ```typescript
-import { createLogger } from "@uncaged/workflow";
+import { createLogger } from "@uncaged/workflow-util";
 
 const log = createLogger();
 
@@ -232,6 +246,50 @@ bun run format      # biome format --write
 bun test            # run tests
 ```
 
+### Version Management & Publishing
+
+All public `@uncaged/*` packages are published to **npmjs.org** via `@changesets/cli` with **fixed mode** (all packages share the same version number). `workflow-dashboard` is private and excluded.
+
+```bash
+# 1. After making changes, add a changeset describing the change
+bun changeset
+
+# 2. Before release, bump all package versions + generate CHANGELOGs
+bun version
+
+# 3. Build, test, and publish to npmjs
+bun release
+```
+
+- `workspace:^` dependencies resolve to `^x.y.z` on publish
+- Changesets config: `.changeset/config.json` (fixed mode, public access)
+- Each package has auto-generated `CHANGELOG.md`
+
+### Consuming @uncaged/* Packages
+
+External workflow repos just `bun install` — packages come from npmjs like any other dependency. No special registry config needed.
+
+### End-to-end: Monorepo → Registry → Workspace → Bundle
+
+```
+workflow/ (monorepo)           — engine, runtime, templates, agents
+  │  bun release               — build + test + changeset publish
+  ▼
+npmjs.org                      — @uncaged/* scoped packages (public)
+  │  bun install
+  ▼
+my-workflows/ (workspace)     — normal package.json
+  │  bun run build:develop     — bun build → single .esm.js
+  ▼
+uncaged-workflow workflow add  — register bundle locally
+uncaged-workflow run           — execute workflow
+```
+
+1. **Monorepo changes** → `bun changeset` (describe change) → `bun version` (bump) → `bun release` (publish)
+2. **Workspace** → `bun install` fetches latest from npmjs
+3. **Build** → produces single-file ESM bundle with `@uncaged/*` as externals
+4. **Register & Run** → `uncaged-workflow workflow add <name> <bundle>` then `uncaged-workflow run <name>`
+
 ## Commit Convention
 
 ```

README.md

@@ -8,7 +8,7 @@ A workflow engine that executes single-file ESM bundles. Each workflow is a self
 |---------|-------------|
 | **Workflow** | A single-file ESM module exporting `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash. |
 | **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
-| **Thread** | A single execution of a workflow, identified by a ULID. Persisted as `.data.jsonl` + `.info.jsonl`. |
+| **Thread** | A single execution of a workflow, identified by a ULID. CAS-backed chain plus `threads.json` / `history/*.jsonl`; `.info.jsonl` for debug logs. |
 | **Role** | A named actor within a workflow. Each role produces output with typed `meta`. Roles live inside template packages (`src/roles/`). |
 | **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
 | **CAS** | Content-Addressed Storage — bundles are immutable and addressed by hash. |

biome.json

@@ -1,7 +1,13 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.4.15/schema.json",
   "files": {
-    "includes": ["**", "!**/dist", "!**/node_modules"]
+    "includes": [
+      "**",
+      "!**/dist",
+      "!**/node_modules",
+      "!packages/workflow/workflow",
+      "!xiaoju/scripts/bundle.ts"
+    ]
   },
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "formatter": {

bunfig.toml

@@ -1,2 +0,0 @@
-[test]
-pathIgnorePatterns = ["dist/**"]

docs/architecture.md

@@ -1,6 +1,6 @@
-# @uncaged/workflow — Architecture
+# Uncaged workflow — Architecture
 
-**Last updated:** 2026-05-06 by 小橘 🍊（NEKO Team）
+**Last updated:** 2026-05-09
 
 ---
 
@@ -8,72 +8,109 @@
 
 A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32). No daemon — processes start on demand and exit when done.
 
-## Package Structure
+The implementation lives in **21** Bun workspace packages under `packages/`, using the `workspace:*` protocol.
 
-| Package | npm Name | Purpose |
-|---------|----------|---------|
-| `workflow` | `@uncaged/workflow` | Core: types, engine, ExtractFn, hash/ULID/registry |
-| `cli-workflow` | `@uncaged/cli-workflow` | CLI: `uncaged-workflow` command |
-| `workflow-agent-cursor` | `@uncaged/workflow-agent-cursor` | Cursor CLI agent (extracts workspace from ctx) |
-| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | Hermes CLI agent |
-| `workflow-agent-llm` | `@uncaged/workflow-agent-llm` | OpenAI-compatible LLM agent |
-| `workflow-template-develop` | `@uncaged/workflow-template-develop` | Develop workflow template (roles in `src/roles/`) |
-| `workflow-template-solve-issue` | `@uncaged/workflow-template-solve-issue` | Solve-issue workflow template (roles in `src/roles/`) |
-| `workflow-util-agent` | `@uncaged/workflow-util-agent` | `buildAgentPrompt` + `spawnCli` utilities |
+## Package map
 
-Monorepo with **bun workspace**, `workspace:*` protocol.
+Grouped by responsibility (npm name → folder).
 
-## Core Types
+| Layer | Package | One-line role |
+|-------|---------|----------------|
+| Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types and `Result` helpers; peer `zod` only — no other workspace deps. |
+| Author API | `@uncaged/workflow-runtime` → `workflow-runtime` | `createWorkflow` and re-exports of protocol workflow types for bundle authors. |
+| Shared infra | `@uncaged/workflow-util` → `workflow-util` | Base32/ULID, logger, storage root paths, global CAS dir, ref-field helpers. |
+| LLM plumbing | `@uncaged/workflow-reactor` → `workflow-reactor` | `createLlmFn`, `createThreadReactor`, and related tool-call types for threaded LLM invocation. |
+| CAS | `@uncaged/workflow-cas` → `workflow-cas` | `CasStore` implementation, XXH64 hashing, Merkle helpers over CAS payloads. |
+| Registry / bundles | `@uncaged/workflow-register` → `workflow-register` | Bundle validation & dynamic export extraction, `workflow.yaml` registry I/O, provider/model resolution. |
+| Engine | `@uncaged/workflow-execute` → `workflow-execute` | Thread execution, worker entry path, fork/GC, extract pipeline, `workflowAsAgent`. |
+| CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uncaged-workflow` binary (depends on engine, registry, CAS, protocol, util, runtime). |
+| Agent adapters | `@uncaged/workflow-agent-cursor` → `workflow-agent-cursor` | `AgentFn` via `cursor-agent` CLI + workspace extraction. |
+| | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `AgentFn` via `hermes chat` CLI. |
+| | `@uncaged/workflow-agent-office` → `workflow-agent-office` | `AdapterFn` via `office-agent` CLI; generates or edits Word documents, stores outputs per threadId. |
+| | `@uncaged/workflow-agent-docx-diff` → `workflow-agent-docx-diff` | `AdapterFn` via `docx-diff` CLI; produces Word-format diff reports for document edit workflows. |
+| | `@uncaged/workflow-agent-llm` → `workflow-agent-llm` | `AgentFn` via OpenAI-compatible HTTP (`LlmProvider` from runtime). |
+| Agent shared | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `buildAgentPrompt`, `spawnCli` for CLI-backed agents. |
+| Templates | `@uncaged/workflow-template-develop` → `workflow-template-develop` | Develop workflow definition, roles, descriptor builder. |
+| | `@uncaged/workflow-template-solve-issue` → `workflow-template-solve-issue` | Solve-issue workflow definition, roles, descriptor builder. |
+| | `@uncaged/workflow-template-document` → `workflow-template-document` | Document generation/editing workflow definition (writer + differ roles, moderator table, descriptor). |
+| Dashboard | `@uncaged/workflow-dashboard` → `workflow-dashboard` | Private Vite + React app (`src/main.tsx`); only `react` / `react-dom` dependencies — no workspace packages. |
 
-```typescript
-// --- Sentinel values ---
-const START = "__start__";
-const END = "__end__";
+## Dependency graph (workspace packages)
 
-// --- RoleMeta: maps role names → their meta types ---
-type RoleMeta = Record<string, Record<string, unknown>>;
+Bottom-up layering for the execution stack:
 
-// --- Role Definition: pure data, no execution logic ---
-type RoleDefinition<Meta> = {
-  description: string;      // human-readable
-  systemPrompt: string;     // given to agent
-  extractPrompt: string;    // given to extractor
-  schema: z.ZodType<Meta>;  // meta shape (Zod v4)
-};
-
-// --- Workflow Definition: pure data, no agent binding ---
-type WorkflowDefinition<M extends RoleMeta> = {
-  description: string;
-  roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
-  moderator: Moderator<M>;
-};
-
-// --- Agent: raw string output, reads role info from context ---
-type AgentFn = (ctx: AgentContext) => Promise<string>;
-
-// --- Agent Binding: runtime assignment ---
-type AgentBinding = {
-  agent: AgentFn;
-  overrides?: Partial<Record<string, AgentFn>>;
-};
-
-// --- Extract: structured data from context ---
-type ExtractFn = <T>(schema: z.ZodType<T>, prompt: string, ctx: ExtractContext) => Promise<T>;
-
-// --- Moderator: pure routing function ---
-type Moderator<M extends RoleMeta> = (ctx: ModeratorContext<M>) => (keyof M & string) | typeof END;
-
-// --- Composition ---
-// createWorkflow(def, binding, extract) => WorkflowFn
+```mermaid
+flowchart BT
+  subgraph L0["Layer 0 — contract"]
+    protocol["@uncaged/workflow-protocol"]
+  end
+  subgraph L1["Layer 1 — on protocol"]
+    runtime["@uncaged/workflow-runtime"]
+    util["@uncaged/workflow-util"]
+    reactor["@uncaged/workflow-reactor"]
+  end
+  subgraph L2["Layer 2 — protocol + util"]
+    cas["@uncaged/workflow-cas"]
+    register["@uncaged/workflow-register"]
+  end
+  subgraph L3["Layer 3 — engine"]
+    execute["@uncaged/workflow-execute"]
+  end
+  subgraph L4["Layer 4 — CLI"]
+    cli["@uncaged/cli-workflow"]
+  end
+  runtime --> protocol
+  util --> protocol
+  reactor --> protocol
+  cas --> protocol
+  cas --> util
+  register --> protocol
+  register --> util
+  execute --> protocol
+  execute --> runtime
+  execute --> util
+  execute --> cas
+  execute --> reactor
+  execute --> register
+  cli --> protocol
+  cli --> util
+  cli --> cas
+  cli --> execute
+  cli --> register
+  cli --> runtime
 ```
 
-## Three-Phase Engine Loop
+**Adjacent consumers** (not in the main CLI stack):
 
-Each role execution has three distinct phases with progressive context:
+- `@uncaged/workflow-util-agent` → `@uncaged/workflow-runtime`
+- `@uncaged/workflow-agent-llm` → `@uncaged/workflow-runtime`
+- `@uncaged/workflow-agent-cursor` → `@uncaged/workflow-runtime`, `@uncaged/workflow-util-agent`, `zod`
+- `@uncaged/workflow-agent-hermes` → `@uncaged/workflow-runtime`, `@uncaged/workflow-util-agent`
+- `@uncaged/workflow-template-develop` → `@uncaged/workflow-register`, `@uncaged/workflow-runtime`, `zod`
+- `@uncaged/workflow-template-solve-issue` → `@uncaged/workflow-register`, `@uncaged/workflow-runtime`, `zod` (dev-only workspace deps: `@uncaged/workflow-cas`, `@uncaged/workflow-execute` for tests/tooling per `package.json`)
+
+## Package roles (detail)
+
+- **`workflow-protocol`** — Pure types (`WorkflowFn`, contexts, `CasStore` interface, descriptor shapes), `START` / `END`, `ok` / `err`. Depends only on peer `zod` for schema-related types in signatures.
+- **`workflow-runtime`** — Workflow author surface: `createWorkflow` from `src/create-workflow.js`, re-exports protocol types/constants used when authoring bundles.
+- **`workflow-util`** — Cross-cutting utilities: Crockford Base32, ULID, `createLogger`, `getDefaultWorkflowStorageRoot`, `getGlobalCasDir`, ref normalization; re-exports `ok`/`err` from protocol.
+- **`workflow-cas`** — Filesystem CAS (`createCasStore`), `hashString` / `hashWorkflowBundleBytes`, Merkle node serialization and helpers (`merkle.js`).
+- **`workflow-register`** — Bundle pipeline (`validateWorkflowBundle`, `extractBundleExports`, descriptor builders), registry YAML read/write, `resolveModel` / `splitProviderModelRef`.
+- **`workflow-execute`** — `executeThread`, supervisor/worker wiring (`engine/`), fork/GC/pause gate, `createExtract` + LLM extract helpers (`extract/`), `workflowAsAgent`. Imports `@uncaged/workflow-reactor` for LLM-backed extract/supervisor paths (`extract-fn.ts`, `supervisor.ts`).
+- **`workflow-reactor`** — `createLlmFn`, `createThreadReactor`, and thread tool-invocation types — consumed by `workflow-execute`.
+- **`cli-workflow`** — CLI commands and HTTP/dashboard-related wiring (`hono`, `yaml`); composes register + execute + CAS + util.
+- **`workflow-agent-*`** — Replaceable `AgentFn` implementations (Cursor / Hermes CLIs, or HTTP LLM).
+- **`workflow-util-agent`** — Shared prompt assembly and subprocess spawning for CLI agents.
+- **`workflow-template-*`** — Concrete `WorkflowDefinition` graphs + Zod role schemas + descriptor builders for publishing bundles.
+- **`workflow-dashboard`** — Standalone React UI; no published library entry matching `src/index.ts`.
+
+## Three-phase engine loop
+
+Each role round is implemented in `packages/workflow-runtime/src/create-workflow.ts` (`advanceOneRound`): moderator → agent → extractor, with progressive context types from `@uncaged/workflow-protocol`.
 
 ```
 ┌─→ Phase 1: MODERATOR
-│   Context: ModeratorContext { threadId, start, steps }
+│   Context: ModeratorContext { threadId, depth, start, steps }
 │   Action:  moderator(ctx) → role name | END
 │
 │   Phase 2: AGENT
@@ -82,98 +119,92 @@ Each role execution has three distinct phases with progressive context:
 │
 │   Phase 3: EXTRACTOR
 │   Context: ExtractContext = AgentCtx + { agentContent }
-│   Action:  extract(schema, extractPrompt, ctx) → typed meta
+│   Action:  runtime.extract(schema, extractPrompt, ctx) → typed meta
 │
-│   Merge: RoleStep { role, content, meta, timestamp }
+│   Merge: RoleStep { role, contentHash, meta, refs, timestamp }
 │   Append to steps
 └─────────────────────────────────────────────────────┘
 ```
 
-### Context Types (progressive)
+### Context types (progressive)
+
+Defined in `packages/workflow-protocol/src/types.ts`:
 
 ```typescript
-// Phase 1: Moderator sees accumulated state only
-type ModeratorContext<M> = {
-  threadId: string;
-  start: StartStep;
-  steps: RoleStep<M>[];
-};
-
-// Phase 2: Agent knows its identity
+type ModeratorContext<M> = ThreadContext<M>;
 type AgentContext<M> = ModeratorContext<M> & {
   currentRole: { name: string; systemPrompt: string };
 };
-
-// Phase 3: Extractor has agent output
-type ExtractContext<M> = AgentContext<M> & {
-  agentContent: string;
-};
-
-// ThreadContext is an alias for AgentContext (backward compat)
-type ThreadContext<M> = AgentContext<M>;
+type ExtractContext<M> = AgentContext<M> & { agentContent: string };
 ```
 
-### Key Properties
+### Key properties
 
-- **Moderator is synchronous and pure** — no I/O, no state mutation
-- **Agent gets context, not instructions** — reads `ctx.currentRole.systemPrompt`
-- **Extractor is a general tool** — not limited to post-agent extraction; agents can use it too (e.g. Cursor agent extracts workspace path before execution)
-- **extractPrompt is a call parameter**, not context state — different callers use different prompts
+- **Moderator is synchronous and pure** — no I/O, no state mutation inside `createWorkflow`’s moderator call path.
+- **Agent receives `AgentContext`** — reads `ctx.currentRole.systemPrompt`; raw output becomes `agentContent` for extract.
+- **Extractor is `WorkflowRuntime.extract`** — supplied by the engine from registry-resolved LLM config (`workflow-execute`); stores agent body in CAS and yields `contentHash` + `refs` on each step (`create-workflow.ts`).
+- **`extractPrompt` is a call parameter** on `RoleDefinition`, not implicit context state.
 
-## Agent Information Sources
+## Agent information sources
 
 An agent has exactly three information sources:
 
 1. **Prior knowledge** — LLM training, agent memory, agent skills
-2. **Thread context** — `AgentContext` (start, steps, currentRole)
+2. **Thread context** — `AgentContext` (`start`, `steps`, `currentRole`)
 3. **Derived information** — from 1 & 2 (e.g. tool calls, shell commands)
 
-No hidden environment parameters. If an agent needs something (like a workspace path), it extracts it from context using `ExtractFn`.
+No hidden environment parameters. If an agent needs something (like a workspace path), it obtains it via `ExtractFn` (e.g. Cursor agent).
 
-## Bundle Contract
+## Bundle contract
 
-A workflow bundle is a single `.esm.js` file with two named exports:
+A workflow bundle is a single `.esm.js` file with two named exports (see `WorkflowFn` / `WorkflowDescriptor` in `packages/workflow-protocol/src/types.ts`):
 
 ```typescript
-// Named exports (no default export)
 export const descriptor: WorkflowDescriptor;
 export const run: WorkflowFn;
 
 type WorkflowFn = (
-  input: { prompt: string; steps: RoleOutput[] },
-  options: { threadId: string; maxRounds: number },
-) => AsyncGenerator<RoleOutput, WorkflowResult>;
+  thread: ThreadContext,
+  runtime: WorkflowRuntime,
+) => AsyncGenerator<RoleOutput, WorkflowCompletion>;
 ```
 
+`RoleOutput` carries `contentHash`, `meta`, and `refs` (agent text lives in CAS, addressed by hash).
+
 ### Constraints
 
 - Single `.esm.js` file
-- No dynamic `import()`
-- All static imports must be Node built-in modules only
-- XXH64 hash (Crockford Base32) = globally unique version ID
+- No dynamic `import()` in bundles (loader exempt in engine)
+- Portable bundle static imports are constrained by validation in `@uncaged/workflow-register` (`validateWorkflowBundle`)
+- XXH64 hash (Crockford Base32) = version ID
 
 ### Why AsyncGenerator?
 
-- Each `yield` → engine writes to `.data.jsonl`, checks abort/pause
-- `return` → engine marks thread complete
-- Fork = pass historical steps as `input.steps` to a new generator
-- Zero injection — bundle doesn't import from the engine
+- Each `yield` lets `workflow-execute` persist state, CAS rows, and enforce pause/abort
+- `return` supplies `WorkflowCompletion`
+- Fork replays historical steps into a new thread context
+- Bundle does not import the engine — only protocol/runtime types at build time
 
-## Storage Layout
+## Storage layout
 
 ```
 ~/.uncaged/workflow/
+├── cas/                           # Global content-addressed blobs (see getGlobalCasDir)
 ├── bundles/
-│   ├── C9NMV6V2TQT81.esm.js     # Crockford Base32 of XXH64
-│   └── C9NMV6V2TQT81.yaml       # Role descriptor
+│   ├── C9NMV6V2TQT81.esm.js       # Crockford Base32 of XXH64
+│   ├── C9NMV6V2TQT81.yaml         # Role descriptor sidecar (when present)
+│   └── C9NMV6V2TQT81/             # Per-hash bundle dir (alongside or instead of loose files)
+│       ├── threads.json           # Active threads: threadId → { head, start, updatedAt }
+│       └── history/
+│           └── 2026-05-09.jsonl   # Completed threads (one JSON object per line)
 ├── logs/                          # One folder per bundle hash
 │   └── C9NMV6V2TQT81/
-│       ├── 01KQXKW…YG.data.jsonl  # Thread state
-│       └── 01KQXKW…YG.info.jsonl  # Debug log
+│       ├── 01KQXKW…YG.running     # Present while worker executes this thread (optional)
+│       └── 01KQXKW…YG.info.jsonl   # Debug log
 └── workflow.yaml                  # Registry
 ```
 
-### ID Encoding: Crockford Base32
+### ID encoding: Crockford Base32
 
 - Case-insensitive, filesystem-safe, no ambiguous chars (0/O, 1/I/L)
 - Bundle hash: XXH64 → 13-char
@@ -181,45 +212,31 @@ type WorkflowFn = (
 
 ### Registry (`workflow.yaml`)
 
-```yaml
-workflows:
-  solve-issue:
-    hash: "C9NMV6V2TQT81"
-    timestamp: 1714963200000
-    history:
-      - hash: "A7BKR3M1NPQ40"
-        timestamp: 1714876800000
-```
+Managed by `@uncaged/workflow-register` (`readWorkflowRegistry`, `writeWorkflowRegistry`, …). Shape includes workflow entries and a top-level `config` section used for extract/supervisor model resolution.
 
-### Thread JSONL
+### Thread storage (CAS + index)
 
-**`.data.jsonl`** — Line 1: start record, Line 2+: role outputs
+Thread execution state is a chain of immutable CAS nodes (`StartNode`, `StateNode`, content Merkle blobs). Per bundle:
 
-```jsonc
-// Start record
-{ "name": "solve-issue", "hash": "C9NMV6V2TQT81", "threadId": "01KQXKW…",
-  "parameters": { "prompt": "Fix bug #3", "options": { "maxRounds": 5 } },
-  "timestamp": 1714963200000 }
-// Role output
-{ "role": "planner", "content": "...", "meta": { "phases": [...] }, "timestamp": ... }
-```
+- **`threads.json`** — only in-flight threads (`head`, `start`, `updatedAt`).
+- **`history/{YYYY-MM-DD}.jsonl`** — completed threads (`threadId`, `head`, `start`, `completedAt`).
+- **CAS (`cas/`)** — payloads and refs for replay, GC, and fork sharing.
 
-**`.info.jsonl`** — Structured debug log
+**`.info.jsonl`** — Structured debug log via `@uncaged/workflow-util` `createLogger`:
 
 ```jsonc
 { "tag": "4KNMR2PX", "content": "Loading bundle...", "timestamp": ... }
 ```
 
-Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNMR2PX"` → instant code location.
+Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNMR2PX"` → code location.
 
-## Execution Model
+## Execution model
 
-- **No daemon.** `uncaged-workflow run <name>` starts a worker process
-- Same bundle's threads share one process (memory efficiency)
-- Process exits when all threads complete
-- Thread termination via IPC within the process
+- **No daemon.** `uncaged-workflow run <name>` starts a worker process (`workflow-execute` worker entry via `getWorkerHostScriptPath`)
+- Threads share bundle-scoped workers as implemented in CLI/engine
+- Pause/resume/abort via engine IPC and pause gate (`createThreadPauseGate`)
 
-## CLI Commands
+## CLI commands
 
 | Priority | Command | Description |
 |----------|---------|-------------|
@@ -239,18 +256,16 @@ Tags are 8-char Crockford Base32 (40-bit random), one per call site. `grep "4KNM
 | P2 | `resume <thread-id>` | Resume a paused thread |
 | P3 | `fork <thread-id> [--from-role <role>]` | Fork from historical state |
 
-All commands implemented and tested. ✅
-
-## Design Decisions
+## Design decisions
 
 | Decision | Rationale |
 |----------|-----------|
 | **Role = pure data** | Decouples definition from execution; same role with different agents |
-| **Agent bound at runtime** | WorkflowDefinition is reusable; agent choice is deployment concern |
-| **Three-phase context** | Each phase sees only what it needs; clean separation |
-| **ExtractFn as general tool** | Agents use it for pre-execution extraction; engine uses it for meta |
-| **Single-file ESM** | Hash = version, no dependency hell, self-contained |
-| **No daemon** | OS handles process lifecycle; unnecessary complexity |
+| **Agent bound at runtime** | `WorkflowDefinition` is reusable; agent choice is deployment concern |
+| **Three-phase context** | Each phase sees only what it needs; types live in `workflow-protocol` |
+| **`WorkflowRuntime.extract` + CAS `contentHash`** | Large agent bodies deduplicated globally; Merkle roots summarize threads |
+| **`workflow-reactor` split** | LLM tool-calling loop isolated from filesystem/registry concerns |
+| **Single-file ESM** | Hash = version, self-contained bundle |
+| **No daemon** | OS handles process lifecycle |
 | **Crockford Base32** | Filesystem-safe, readable, compact |
-| **No concurrency in registry** | Different workflows have different constraints; belongs at workflow/role level |
-| **No dryRun** | Tests use mock agents + mock fetch; simpler architecture |
+| **21-package split** | Clear boundaries: protocol ↔ runtime author API ↔ util/CAS/register ↔ execute ↔ CLI ↔ agents/templates/UI |

docs/plans/2025-05-07-workflow-as-agent.md

@@ -1,5 +1,7 @@
 # Workflow-as-Agent Implementation Plan
 
+> ⚠️ This plan references the pre-split package structure. File paths have changed.
+
 > **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
 
 **Goal:** Enable workflows to invoke other workflows as agents, backed by global CAS and refs tracking.

docs/plans/2026-05-09-cas-thread-storage.md

@@ -0,0 +1,262 @@
+# RFC: CAS-Based Thread Storage
+
+> Status: Draft
+> Author: 小橘 🍊（NEKO Team）
+> Date: 2026-05-09
+
+## Summary
+
+Replace `.data.jsonl` with a fully CAS-based thread state chain. Threads become linked lists of immutable CAS nodes, indexed by a per-bundle `threads.json`.
+
+## Motivation
+
+`.data.jsonl` is a flat append-only file with three different row formats (start, role step, end). This makes forking expensive (copy file), deduplication impossible (forked threads repeat shared history), and GC complex (must parse every row to find CAS refs).
+
+Threads are inherently immutable append-only sequences — a natural fit for CAS hash chains, similar to git's commit DAG.
+
+## Design
+
+### Node Types
+
+Two CAS node types, using the existing `{ type, payload, refs }` CAS blob structure:
+
+#### StartNode
+
+Contains workflow-level parameters. **No threadId** (because the same StartNode can be shared across forks). Prompt is stored as a CAS blob and referenced via `refs[0]`.
+
+```
+CAS blob:
+{
+  type: "start",
+  payload: {
+    name: "solve-issue",
+    hash: "BUNDLE_HASH",
+    maxRounds: 10,
+    depth: 0
+  },
+  refs: [
+    <prompt_hash>    // refs[0]: initial task prompt (CAS blob)
+  ]
+}
+```
+
+- No `role`, `content`, `meta` — this is not a step, it's workflow metadata
+- Prompt is **not** inline — it lives in CAS and is referenced by hash
+
+#### StateNode
+
+One per role step (including `__end__`).
+
+```
+CAS blob:
+{
+  type: "state",
+  payload: {
+    role: "coder",
+    meta: { ... },
+    start: "<start_hash>",
+    content: "<content_merkle_hash>",
+    ancestors: ["<parent_hash>", "<grandparent_hash>", ...],
+    compact: null,
+    timestamp: 1234567890
+  },
+  refs: [<start_hash>, <content_hash>, <parent_hash>, ...]
+}
+```
+
+**Payload is the source of truth.** Application code reads named fields from payload. `refs[]` is a **GC index** — automatically derived from payload by collecting all CAS hashes. GC only scans `refs[]` without understanding payload structure.
+
+**Payload fields:**
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `role` | `string` | Role name, or `"__end__"` for completion |
+| `meta` | `object` | Structured metadata extracted from agent output |
+| `start` | `string` | StartNode hash |
+| `content` | `string` | Content Merkle node hash (carries role artifact refs) |
+| `ancestors` | `string[]` | `[parent, grandparent, ...]` — up to 11 entries (1 parent + 10 skip-list). Empty for first step after start. `ancestors[0]` is the direct parent. |
+| `compact` | `string \| null` | CAS hash of a compacted summary of all nodes before this one. When present, LLM context assembly can use this instead of walking the full chain. |
+| `timestamp` | `number` | Unix timestamp in ms |
+
+### Content Merkle Node
+
+The content at `refs[2]` of each StateNode is itself a CAS Merkle node. This is where **role artifact references** live:
+
+```
+CAS blob:
+{
+  type: "content",
+  payload: "<role output text>",
+  refs: [
+    <artifact_hash_1>,   // e.g. a commit, a file, a sub-result
+    <artifact_hash_2>,
+    ...
+  ]
+}
+```
+
+The Extractor is responsible for producing both `meta` and `refs` from raw agent output:
+
+```
+Agent raw output
+    ↓
+Extractor → { meta, contentPayload, refs[] }
+    ↓
+CAS put content Merkle: { type: "content", payload: contentPayload, refs }
+    ↓ contentHash
+StateNode: { ..., refs: [start, parent, contentHash, ...ancestors] }
+```
+
+This keeps StateNode refs fixed and simple. All role-specific artifact references are encapsulated in the content Merkle node. GC follows: `thread head → StateNode.refs → content Merkle.refs → artifacts`, full chain recursive.
+
+### End Node
+
+An end is just a StateNode with `role: "__end__"`:
+
+```
+{
+  type: "state",
+  payload: {
+    role: "__end__",
+    meta: { returnCode: 0, summary: "completed successfully" },
+    start: "<start_hash>",
+    content: "<content_hash>",
+    ancestors: ["<parent_hash>", ...],
+    compact: null,
+    timestamp: 1234567891
+  },
+  refs: [<start_hash>, <content_hash>, <parent_hash>, ...]
+}
+```
+
+### Thread Index: `threads.json`
+
+Per-bundle directory, one `threads.json` file. **Only active (in-progress) threads** live here:
+
+```
+~/.uncaged/workflow/bundles/<hash>/threads.json
+```
+
+```json
+{
+  "01JTHREAD1AAAAAAAAAAAAAAA": {
+    "head": "<latest_state_node_hash>",
+    "start": "<start_node_hash>",
+    "updatedAt": 1234567891
+  }
+}
+```
+
+When a thread completes (`__end__`), it is **removed from `threads.json`** and appended to a date-partitioned history file:
+
+```
+~/.uncaged/workflow/bundles/<hash>/history/{YYYY-MM-DD}.jsonl
+```
+
+Each line:
+
+```json
+{"threadId":"01JTHREAD1AAAAAAAAAAAAAAA","head":"<end_node_hash>","start":"<start_node_hash>","completedAt":1234567891}
+```
+
+Benefits:
+- `threads.json` stays small — only in-flight threads
+- Dashboard watches `threads.json` for real-time updates; completed threads don't trigger watches
+- History is queryable by date but not actively monitored
+- GC roots = all heads from `threads.json` + all heads from `history/*.jsonl`
+
+### Ancestor Skip-List
+
+Each StateNode carries up to 11 entries in `payload.ancestors` (1 parent + 10 skip-list, newest first):
+
+```
+Node 15: ancestors = [node14, node13, node12, node11, node10, node9, node8, node7, node6, node5, node4]
+                      ^parent  ^--- skip-list (10 most recent) ---^
+```
+
+This enables:
+- **Paginated fetch**: jump to any recent ancestor without walking the full chain
+- **Partial replay**: fetch last N steps without loading the entire history
+- The list is capped at 10 to keep node size bounded
+
+### Fork
+
+Forking a thread at step N:
+
+1. Create new threadId
+2. Create a new StateNode whose `parent` (refs[1]) points to the fork point's StateNode
+3. Register the new threadId in `threads.json` with its own head
+4. **Zero data duplication** — the forked thread shares all ancestor nodes via CAS
+
+### Compact
+
+When a StateNode has `payload.compact` set:
+
+```json
+{
+  "type": "state",
+  "payload": {
+    "role": "coder",
+    "meta": { ... },
+    "compact": "<cas_hash_of_summary>",
+    "timestamp": 1234
+  },
+  "refs": [...]
+}
+```
+
+This means: "everything before this node has been summarized into the blob at `compact`". When building LLM context:
+
+1. Walk back from head
+2. If a node has `compact`, stop walking — use the compact summary + all nodes after it
+3. If no compact found, use full chain
+
+This enables long-running threads without unbounded context growth.
+
+### GC
+
+Simple mark-and-sweep:
+
+1. **Roots**: all `head` and `start` hashes from `threads.json` + all `history/*.jsonl` files
+2. **Mark**: from each root, recursively mark all reachable hashes via `refs[]` (including content Merkle → artifact refs)
+3. **Sweep**: delete unmarked CAS blobs
+
+No per-row format parsing needed. GC only needs to understand `refs[]`.
+
+### refs[] Derivation
+
+`refs[]` is auto-derived from payload at write time via a `collectRefs(payload)` function that extracts all CAS hash strings from named fields (`start`, `content`, `ancestors`, `compact`). Application code never reads `refs[]` — it reads named payload fields. This makes `refs[]` a pure GC optimization with zero semantic coupling.
+
+### Extract Phase
+
+The Extractor is expanded from the current design. Currently it only extracts `meta` from agent output. In the new design it extracts:
+
+| Output | Purpose |
+|--------|---------|
+| `meta` | Structured metadata (same as before) |
+| `contentPayload` | The text payload for the content Merkle node |
+| `refs[]` | CAS hashes of artifacts produced by this role step |
+
+The `refs[]` become the content Merkle node's refs, enabling GC to trace all role-produced artifacts.
+
+## What Stays Unchanged
+
+- `.info.jsonl` — debug logging stays as-is (high-frequency append, not suitable for CAS)
+- CAS blob storage format (`~/.uncaged/workflow/cas/`)
+- Bundle registry (`workflow.yaml`)
+
+## Migration
+
+Breaking change. Old `.data.jsonl` files become incompatible. No backward compat fallback (per project convention).
+
+## Changes by Package
+
+| Package | Changes |
+|---------|---------|
+| `workflow-protocol` | Replace `StartStep`, `RoleStep` types with `StartNode`, `StateNode`. Add `ContentMerkleNode` type. Expand `ExtractResult` to include `refs[]`. |
+| `workflow-cas` | Add `findReachableHashes(roots)` for GC mark phase |
+| `workflow-execute` | Rewrite engine to write CAS nodes + update `threads.json` instead of appending JSONL. Move completed threads to `history/`. Simplify `gc.ts`. Simplify `fork-thread.ts`. Expand extract phase to produce refs. |
+| `workflow-runtime` | `ThreadContext` built by walking chain from head. `start.prompt` resolved from CAS via StartNode.refs[0]. |
+| `cli-workflow` | `thread list/show/rm` read from `threads.json` + `history/`. SSE watches `threads.json`. |
+| `workflow-dashboard` | Watch `threads.json` instead of `.data.jsonl` |
+| Templates & Agents | Update extract definitions to produce `refs[]`. Update `ctx.start.content` → CAS resolved. |

docs/plans/2026-05-11-merkle-call-stack.md

@@ -0,0 +1,197 @@
+# RFC: Merkle Call Stack — Cross-Thread DAG Linking
+
+**Author:** 小橘 🍊（NEKO Team）
+**Date:** 2026-05-11
+**Status:** Draft
+
+## Problem
+
+当 `workflowAsAgent` 在父 workflow 中 spawn 子 workflow 时，父子 thread 之间没有任何 Merkle 链接：
+
+1. **子 thread 不知道自己从哪来** — start node 只有 prompt hash，无法追溯父 thread 的上下文（preparer 分析出的 repoPath、conventions 等）
+2. **父 thread 不知道子 thread 在哪** — developer role 的 state node 里只有 agent 返回的文本，child thread root hash 埋在字符串里，不是结构化 ref
+3. **上下文传递靠序列化到 prompt** — 父 workflow 前置 role 的产出只能通过拼字符串传给子 workflow，丢失了 Merkle DAG 的可遍历性
+
+## Proposal
+
+在 CAS 节点中建立父子 thread 之间的 **双向 Merkle 链接**，形成调用栈结构。
+
+### 新增字段
+
+#### StartNodePayload（子 → 父）
+
+```typescript
+type StartNodePayload = {
+  name: string;
+  hash: string;
+  depth: number;
+  parentState: string | null;   // NEW: 父 thread 调用时的 head state hash
+};
+```
+
+`parentState` 指向子 workflow 被 spawn 时，父 thread 的最后一个 state node hash。这是"调用发生时的调用栈帧"。
+
+#### StateNodePayload（父 → 子）
+
+```typescript
+type StateNodePayload = {
+  role: string;
+  meta: Record<string, unknown>;
+  start: string;
+  content: string;
+  ancestors: string[];
+  compact: string | null;
+  timestamp: number;
+  childThread: string | null;   // NEW: 子 thread 最终 state hash（执行结果）
+};
+```
+
+`childThread` 指向子 thread 完成后的**最终 state hash**（不是 start）——语义上是"函数返回值"，从这里沿 ancestors 可回溯子 thread 的完整执行历史。
+
+### refs 同步
+
+新增的 hash 也必须放进 `refs[]`：
+
+- `StartNode.refs`: `[promptHash, parentState]`（parentState 非 null 时）
+- `StateNode.refs`: `[...existingRefs, childThread]`（childThread 非 null 时）
+
+原因：GC 的 `findReachableHashes` 只走 `refs`，不解析 payload 字段。字段提供语义，refs 保证可达性。
+
+### 具体 DAG 结构
+
+以 `solve-issue`（fix #191）为例，developer role 委托给 `develop` 子 workflow：
+
+```
+父 thread: solve-issue
+═══════════════════════════════════════════════════════════
+
+content("fix #191")
+  hash: ABCD1234
+
+start(solve-issue)
+  hash: START001
+  payload: { name: "solve-issue", hash: BUNDLE_SI, depth: 0, parentState: null }
+  refs: [ABCD1234]
+
+state(preparer)
+  hash: STATE_P1
+  payload: { role: "preparer", meta: { repoPath: "...", ... }, childThread: null, ... }
+  refs: [PREP_CONTENT]
+
+state(developer)                          ──────── 父→子 ────────
+  hash: STATE_D1                                                 │
+  payload: { role: "developer", meta: { ... }, childThread: ★CSTATE_END, ... }
+  refs: [DEV_CONTENT, ★CSTATE_END]                               │
+                                                                  │
+state(submitter)                                                  │
+  hash: STATE_S1                                                  │
+  payload: { role: "submitter", ..., childThread: null }          │
+                                                                  │
+                                                                  │
+子 thread: develop                                                │
+═══════════════════════════════════════════════════════════        │
+                                                                  │
+content("fix #191")          (CAS 去重，可能同 ABCD1234)           │
+  hash: CPROMPT1                                                  │
+                              ──────── 子→父 ────────             │
+start(develop)                          │                         │
+  hash: CHILD_START                     │                         │
+  payload: { name: "develop", hash: BUNDLE_DEV, depth: 1,        │
+             parentState: ★STATE_P1 }   │                         │
+  refs: [CPROMPT1, ★STATE_P1]          │                         │
+                                        │                         │
+state(planner)                          │                         │
+  hash: CSTATE_1                        │                         │
+  ...                                   │                         │
+                                        │                         │
+state(coder)                            │                         │
+  hash: CSTATE_2                        │                         │
+  ...                                   │                         │
+                                        │                         │
+state(reviewer) → state(tester) → state(committer)                │
+                                        │                         │
+  hash: ★CSTATE_END  ◄─────────────────┼─────────────────────────┘
+```
+
+### 遍历路径
+
+**子 thread agent 获取父上下文（上行）：**
+```
+当前 step → start(CHILD_START)
+  → refs[1] = STATE_P1（父 preparer 的 state）
+    → payload.meta.repoPath = "/home/.../workflow"
+    → refs → PREP_CONTENT（完整 preparer 输出）
+    → payload.start = START001（父的 start node）
+      → refs[0] = ABCD1234（原始 prompt）
+```
+
+**从父 thread 追踪子 thread 执行（下行）：**
+```
+STATE_D1（父 developer state）
+  → payload.childThread = CSTATE_END
+    → 子 thread 最终 state
+    → 沿 ancestors 回溯：committer → tester → reviewer → coder → planner
+    → payload.start = CHILD_START（子 thread 入口）
+```
+
+**完整调用栈还原：**
+```
+任意节点 → 沿 start 找到所属 thread 的 StartNode
+  → parentState 非 null？沿 parentState 进入父 thread
+  → 递归直到 parentState = null（顶层 workflow）
+```
+
+## Implementation Plan
+
+### Phase 1: Protocol + CAS 层
+
+1. `workflow-protocol/src/cas-types.ts` — `StartNodePayload` 加 `parentState: string | null`，`StateNodePayload` 加 `childThread: string | null`
+2. `workflow-cas/src/nodes.ts` — `putStartNode` 接受可选 `parentStateHash`，放入 refs；`putStateNode` 接受可选 `childThreadHash`，放入 refs
+3. `workflow-cas/src/nodes.ts` — 解析逻辑兼容新字段（缺失时视为 null）
+
+### Phase 2: Engine 层
+
+4. `workflow-execute/src/engine/engine.ts` — `executeThread` 接受 `parentStateHash: string | null`，传给 `putStartNode`
+5. `workflow-execute/src/workflow-as-agent.ts` — spawn 子 thread 时传入父 thread 当前 head state hash 作为 `parentStateHash`；子 thread 完成后返回最终 state hash
+6. Engine 写 developer role 的 state node 时，把子 thread 最终 hash 写入 `childThread` 字段
+
+### Phase 3: Agent 可观测性
+
+7. Agent prompt 构建（`buildAgentPrompt`）— 当 start node 有 `parentState` 时，提示 agent 可通过 `cas get` 遍历父上下文
+8. CLI `thread show` — 显示 parentState / childThread 链接关系
+
+### Phase 4: 验证
+
+9. 已有测试适配新字段（向后兼容，旧节点 parentState/childThread 为 null）
+10. 新增集成测试：workflowAsAgent 场景下验证双向链接正确写入
+
+## Design Decisions
+
+### 为什么 childThread 指向 end 而不是 start？
+
+- 语义是"函数返回值"——父 role 执行完才产出 state，此时子 thread 已跑完
+- 从 end 沿 ancestors 可回溯到 start；反过来 start 写入时子 thread 还没跑完，无法知道 end
+
+### 为什么 parentState 指向 state 而不是 start？
+
+- 指向父 thread 调用点的**前一个 state**（即调用发生时的 head）
+- 这是子 workflow 能看到的父上下文的"切面"——所有已完成的前置 role 都可达
+- 如果是第一个 role 就 spawn 子 workflow（没有前置 state），parentState 指向父的 start node
+
+### 为什么同时放字段和 refs？
+
+- `refs[]` 服务于 GC（`findReachableHashes` 只遍历 refs）和通用 DAG 遍历
+- `payload.parentState` / `payload.childThread` 服务于语义读取（明确知道哪个 ref 是什么）
+- 不改 GC 逻辑，只加字段，GC 自然正确
+
+### 向后兼容
+
+- 新字段默认 `null`，旧节点解析时缺失字段视为 `null`
+- 不影响已有 thread 的遍历和 GC
+- `depth` 可通过沿 parentState 链上溯来交叉验证（数据自证）
+
+## Open Questions
+
+1. **多子 thread** — 如果一个 role 需要 spawn 多个子 workflow（目前不存在这个场景），`childThread` 应该改成 `childThreads: string[]` 还是保持单个？
+2. **Agent prompt 注入深度** — 子 workflow 的 agent 应该自动遍历多少层父上下文？全部还是限制深度？
+3. **CLI 展示** — `thread show` 要不要递归展示整个调用栈，还是只显示直接链接？

docs/plans/2026-05-12-dashboard-workflow-graph.md

@@ -0,0 +1,224 @@
+# Dashboard Workflow Graph Visualization
+
+**Issue**: #198
+**Status**: In Progress
+**Author**: xingyue
+
+## Overview
+
+在 Dashboard 的 ThreadDetail 页面中嵌入一个交互式流程图，将 workflow 的 `ModeratorTable` 可视化为有向图。用户可以一眼看到角色流转结构和当前执行进度。
+
+## 数据层（✅ 已完成 — PR #201）
+
+### WorkflowGraph 类型
+
+`WorkflowDefinition.moderator`（函数）已替换为 `WorkflowDefinition.table`（声明式 `ModeratorTable`），`buildDescriptor` 自动从 table 提取 graph：
+
+```ts
+type WorkflowGraphEdge = {
+  from: string;              // source role 或 "__start__"
+  to: string;                // target role 或 "__end__"
+  condition: string;         // condition.name 或 "FALLBACK"
+  conditionDescription: string | null;
+};
+
+type WorkflowGraph = {
+  edges: readonly WorkflowGraphEdge[];
+};
+
+type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+  graph: WorkflowGraph;      // 必填，新 bundle 自动生成
+};
+```
+
+### 数据流
+
+```
+ModeratorTable (WorkflowDefinition.table)
+  → buildDescriptor() 自动提取 graph
+    → descriptor.yaml 持久化（hash.yaml）
+      → CLI serve /workflows/:name API 返回 descriptor
+        → Dashboard 前端拿到 graph
+```
+
+### 剩余数据层工作
+
+**serve API 需要返回 descriptor**：当前 `GET /workflows/:name` 只返回 registry entry（hash + timestamp），不含 descriptor。需要从 `bundles/{hash}.yaml` 读取 descriptor 并返回给前端。
+
+方案：在 `routes-workflow.ts` 的 `GET /workflows/:name` 响应中附带 `descriptor` 字段。或者：thread-detail 发现 workflow name 后，请求 `GET /workflows/:name/descriptor` 拿到 graph。
+
+## 前端渲染
+
+### 库选型：React Flow + dagre
+
+| 库 | 优势 | 劣势 |
+|---|---|---|
+| **React Flow** ✅ | React 原生、自定义节点/边、dagre 自动布局、~50KB gzip | 需要学 API |
+| Mermaid | 声明式简单 | 无交互、无法高亮当前步骤 |
+| D3 | 完全控制 | 太底层，手撸成本高 |
+| Cytoscape | 图论强 | React 集成差 |
+
+**依赖新增**：
+
+```json
+{
+  "@xyflow/react": "^12",
+  "@dagrejs/dagre": "^1"
+}
+```
+
+### 图结构映射
+
+```
+WorkflowGraph.edges → React Flow nodes + edges
+
+节点（自动从 edges 推导）:
+  - __start__  → 圆形小节点（入口）
+  - role       → 圆角矩形，显示 role name + description
+  - __end__    → 圆形小节点（终止）
+
+边:
+  - FALLBACK   → 虚线（dashed），无 label
+  - condition  → 实线，label = condition
+                  hover tooltip = conditionDescription
+```
+
+### 布局
+
+使用 dagre 自动计算 TB（top-to-bottom）方向布局：
+
+```ts
+import Dagre from "@dagrejs/dagre";
+
+function layoutGraph(nodes, edges) {
+  const g = new Dagre.graphlib.Graph().setDefaultEdgeLabel(() => ({}));
+  g.setGraph({ rankdir: "TB", nodesep: 60, ranksep: 80 });
+
+  for (const node of nodes) {
+    g.setNode(node.id, { width: 180, height: 60 });
+  }
+  for (const edge of edges) {
+    g.setEdge(edge.source, edge.target);
+  }
+
+  Dagre.layout(g);
+
+  return nodes.map((node) => {
+    const pos = g.node(node.id);
+    return { ...node, position: { x: pos.x - 90, y: pos.y - 30 } };
+  });
+}
+```
+
+### 运行时高亮
+
+ThreadDetail 已有 `records: ThreadRecord[]`，其中 `RoleRecord.role` 就是当前/历史执行的 role。
+
+高亮逻辑：
+
+```ts
+function getNodeStates(records: ThreadRecord[]): Map<string, "completed" | "active"> {
+  const states = new Map<string, "completed" | "active">();
+  const roleRecords = records.filter((r) => r.type === "role");
+
+  for (let i = 0; i < roleRecords.length; i++) {
+    const role = roleRecords[i].role;
+    states.set(role, i === roleRecords.length - 1 ? "active" : "completed");
+  }
+
+  // 如果有 workflow-result，最后一个 role 也是 completed
+  if (records.some((r) => r.type === "workflow-result")) {
+    for (const [k] of states) {
+      states.set(k, "completed");
+    }
+    states.set("__end__", "completed");
+  }
+
+  states.set("__start__", "completed");
+  return states;
+}
+```
+
+节点样式：
+
+| 状态 | 样式 |
+|------|------|
+| default | `border: var(--color-border)`, 暗色背景 |
+| completed | `border: var(--color-success)`, 绿色边框 + ✓ 图标 |
+| active | `border: var(--color-accent)`, 蓝色边框 + 脉冲动画 |
+
+边高亮：当 source 和 target 都至少 completed 时，边变绿。
+
+## 组件结构
+
+```
+workflow-dashboard/src/
+  components/
+    workflow-graph/
+      types.ts           — NodeState 等前端类型
+      index.ts           — export { WorkflowGraph }
+      workflow-graph.tsx  — 主组件，React Flow canvas
+      role-node.tsx       — 自定义 role 节点
+      terminal-node.tsx   — START/END 圆形节点
+      condition-edge.tsx  — 自定义边（虚线/实线 + label）
+      use-layout.ts       — dagre 布局 hook
+```
+
+### 集成到 ThreadDetail
+
+在 ThreadDetail 中，records 列表上方插入可折叠的图面板：
+
+```tsx
+// thread-detail.tsx
+{graph && (
+  <div className="mb-4 border rounded-lg overflow-hidden" style={{ height: 300 }}>
+    <WorkflowGraph graph={graph} nodeStates={getNodeStates(records)} />
+  </div>
+)}
+```
+
+图高度固定 300px，React Flow 支持 pan + zoom，不影响下方 records 滚动。
+
+## 实施计划
+
+### ~~Phase 0: 数据层~~ ✅ Done (PR #201)
+
+- [x] `WorkflowDefinition.moderator` → `table` (ModeratorTable)
+- [x] `WorkflowDescriptor` 新增 `graph: WorkflowGraph`
+- [x] `buildDescriptor` 自动提取 graph
+- [x] `validateWorkflowDescriptor` 校验 graph
+
+### Phase 1: API + 静态图渲染
+
+1. serve API：`GET /workflows/:name` 返回 descriptor（含 graph），或新增 `GET /workflows/:name/descriptor`
+2. Dashboard `api.ts` 新增 `getWorkflowDescriptor(agent, name)` 函数
+3. 安装 `@xyflow/react` + `@dagrejs/dagre`
+4. 实现 `workflow-graph/` 组件集
+5. ThreadDetail 中集成：从 thread-start record 拿 workflow name → 请求 descriptor → 渲染图
+
+**产出**：打开 ThreadDetail 看到 workflow 流程图，无高亮。
+
+### Phase 2: 运行时高亮
+
+1. ThreadDetail 根据 records 计算 nodeStates
+2. 节点/边样式响应状态变化
+3. SSE live 模式下实时更新高亮
+
+**产出**：正在运行的 thread 能看到当前执行到哪个 role。
+
+### Phase 3: 交互增强
+
+1. 点击节点滚动到对应 role 的 RecordCard
+2. 边 hover 显示 conditionDescription tooltip
+3. 节点 hover 显示 role description + schema summary
+
+**产出**：图和记录列表联动。
+
+## 注意事项
+
+- **自循环边**：如 `coder → coder (FALLBACK)`，React Flow 支持自循环，dagre 需要特殊处理（self-edge 用 loop 路径）
+- **大图性能**：dagre 在 <50 节点时性能无忧，workflow 通常 <10 个 role
+- **暗色主题**：Dashboard 已使用 CSS variables，节点/边样式复用现有色板
+- **不提交 pnpm-lock.yaml**

docs/plans/2026-05-12-react-agent.md

@@ -0,0 +1,191 @@
+# workflow-agent-react — ReAct Agent Package
+
+**Status**: RFC v3
+**Author**: 小橘 🍊
+
+## Problem
+
+现有的 agent 包都依赖外部 CLI 进程：
+
+| Package | 机制 | 能力 |
+|---------|------|------|
+| `workflow-agent-hermes` | spawn `hermes chat` | 完整工具链（文件、终端、浏览器…） |
+| `workflow-agent-cursor` | spawn `cursor-agent` | IDE 级别代码编辑 |
+| `workflow-agent-llm` | 单轮 chat completion | 纯文本，无工具 |
+
+缺少一个 **内置 ReAct agent**：用 LLM + tool calling 循环执行任务，不依赖外部 CLI，工具集由调用方注入。
+
+## 核心设计变更：AdapterFn 替代 AgentFn
+
+### 现状的问题
+
+当前 `AgentFn` 返回 `string`，engine 再用额外一轮 LLM 调用 extract meta：
+
+```
+Agent(ctx) → string → Extract(string, schema) → meta   // 浪费一轮 LLM
+```
+
+### 新抽象：AdapterFn
+
+```typescript
+type RoleFn<T> = (ctx: ThreadContext) => Promise<T>;
+
+type AdapterFn = <T>(prompt: string, schema: z.ZodType<T>) => RoleFn<T>;
+```
+
+- **`prompt`** — role 的 system prompt，描述角色职责和输出要求
+- **`schema`** — role 的 meta schema，定义输出格式
+- **`ThreadContext`** — threadId, depth, bundleHash, start, steps
+
+prompt 和 schema 是一对：prompt 说"你要输出什么"，schema 定义"输出的格式"。它们属于 role definition，由 `createWorkflow` 在每个 role 执行时传给 adapter。
+
+### AgentContext 不再需要
+
+`AgentContext` 在 `ThreadContext` 上扩展了 `currentRole: { name, systemPrompt }`。prompt 现在直接传给 adapter，`AgentContext` 可以删除。
+
+### createWorkflow 签名变更
+
+```typescript
+// Before
+type AgentBinding = {
+  agent: AgentFn;
+  overrides: Partial<Record<string, AgentFn>> | null;
+};
+
+// After
+type AdapterBinding = {
+  adapter: AdapterFn;
+  overrides: Partial<Record<string, AdapterFn>> | null;
+};
+```
+
+engine 对每个 role 的执行逻辑：
+
+```typescript
+// Before
+const result = await agent({ ...threadCtx, currentRole: { name, systemPrompt } });
+const meta = await extract(result, role.metaSchema, provider);  // 额外一轮 LLM
+
+// After
+const roleFn = adapter(role.systemPrompt, role.metaSchema);
+const meta = await roleFn(threadCtx);  // 直接拿到类型安全的 T
+```
+
+## `createReactAdapter` — 复用 workflow-reactor
+
+AdapterFn 的终止条件是"拿到符合 schema 的 T"——和 `workflow-reactor` 的 `ThreadReactorFn` 完全一致。因此 react adapter 是对 reactor 的**薄包装**，不需要自己实现 ReAct 循环。
+
+```typescript
+import { createLlmFn, createThreadReactor } from "@uncaged/workflow-reactor";
+import type { ThreadContext, LlmProvider } from "@uncaged/workflow-protocol";
+import type { ToolDefinition } from "@uncaged/workflow-reactor";
+
+type ReactToolHandler = (name: string, args: string) => Promise<string>;
+
+type ReactAdapterConfig = {
+  provider: LlmProvider;
+  tools: readonly ToolDefinition[];
+  toolHandler: ReactToolHandler;
+  maxRounds: number;
+};
+
+function createReactAdapter(config: ReactAdapterConfig): AdapterFn {
+  return <T>(prompt: string, schema: z.ZodType<T>) => {
+    const reactor = createThreadReactor<ThreadContext>({
+      llm: createLlmFn(config.provider),
+      staticTools: config.tools,
+      structuredToolFromSchema: (s) => buildStructuredTool(s),
+      systemPromptForStructuredTool: () => prompt,
+      toolHandler: (call, ctx) =>
+        config.toolHandler(call.function.name, call.function.arguments),
+      maxRounds: config.maxRounds,
+    });
+
+    return async (ctx: ThreadContext): Promise<T> => {
+      const input = buildThreadInput(ctx);
+      const result = await reactor({ thread: ctx, input, schema });
+      if (!result.ok) throw new Error(result.error);
+      return result.value;
+    };
+  };
+}
+```
+
+整个包就是：**一个工厂函数 + 类型定义 + thread 输入构造**。
+
+## `agentToAdapter` — 向后兼容
+
+把现有 `AgentFn`（hermes/cursor）包装成 `AdapterFn`：
+
+```typescript
+function agentToAdapter(agent: AgentFn, extractProvider: LlmProvider): AdapterFn {
+  return <T>(prompt: string, schema: z.ZodType<T>): RoleFn<T> => {
+    return async (ctx: ThreadContext): Promise<T> => {
+      const agentCtx = { ...ctx, currentRole: { name: "agent", systemPrompt: prompt } };
+      const result = await agent(agentCtx);
+      const output = typeof result === "string" ? result : result.output;
+      return extract(output, schema, extractProvider);
+    };
+  };
+}
+```
+
+hermes/cursor agent 内部不改，bundle-entry 层多包一层即可。
+
+## 包结构
+
+```
+packages/workflow-agent-react/
+  src/
+    types.ts                 # ReactAdapterConfig, ReactToolHandler
+    create-react-adapter.ts  # AdapterFn 工厂（包装 reactor）
+    thread-input.ts          # ThreadContext → user message string
+    index.ts
+  __tests__/
+    create-react-adapter.test.ts
+  package.json
+```
+
+依赖：
+- `@uncaged/workflow-protocol` — `ThreadContext`, `LlmProvider`
+- `@uncaged/workflow-reactor` — `createLlmFn`, `createThreadReactor`, types
+
+## 影响范围
+
+### Breaking Changes
+
+| 改动 | 影响 |
+|------|------|
+| `AgentBinding` → `AdapterBinding` | `createWorkflow` 调用方（所有 bundle-entry） |
+| `AgentContext` 删除 | `buildAgentPrompt`（util-agent）改为接收 `ThreadContext` |
+| extract 从 engine 下沉到 adapter | `workflow-execute` 简化 |
+
+### 需修改的包
+
+1. `workflow-protocol` — 删除 `AgentContext`/`AgentFn`/`AgentFnResult`/`AgentBinding`，新增 `AdapterFn`/`RoleFn`/`AdapterBinding`
+2. `workflow-runtime` — 更新 re-export
+3. `workflow-execute` — engine 调用 `adapter(prompt, schema)` 替代 `agent(ctx) + extract`
+4. `workflow-util-agent` — `buildAgentPrompt` → `buildThreadInput`，接收 `ThreadContext`
+5. 所有 bundle-entry — `agent:` → `adapter:`
+
+### 不受影响
+
+- `workflow-cas` / `workflow-register` / `workflow-reactor` / `workflow-dashboard`
+- `workflow-agent-hermes` / `workflow-agent-cursor`（内部不改，外部用 `agentToAdapter` 包装）
+
+## Phases
+
+1. **Phase 1**: protocol 类型 + `createWorkflow` 签名变更 + `agentToAdapter`
+2. **Phase 2**: `workflow-agent-react` 包（包装 reactor）
+3. **Phase 3**: 工具集实现（read/write/patch/shell） + smoke test 闭环
+
+## 工具集（后续讨论）
+
+| 工具 | 说明 | 优先级 |
+|------|------|--------|
+| `read_file` | 读文件 | P0 |
+| `write_file` | 写文件 | P0 |
+| `patch_file` | find-and-replace 编辑 | P0 |
+| `shell_exec` | 执行 shell 命令 | P0 |
+| `search_files` | grep / find | P1 |
+| `list_files` | ls | P1 |

docs/superpowers/specs/2026-05-18-office-agent-document-template.md

@@ -0,0 +1,387 @@
+# 设计文档：office-agent 文档生成/编辑 Workflow 体系
+
+**日期：** 2026-05-18
+
+---
+
+## 概述
+
+在 monorepo 中新增三个包，实现通过 `office-agent` CLI 生成或编辑 Word 文档的完整 workflow 体系。
+
+| 包 | npm name | 职责 |
+|---|---|---|
+| `workflow-template-document` | `@uncaged/workflow-template-document` | 纯结构：角色定义、meta schema、调度表、descriptor |
+| `workflow-agent-office` | `@uncaged/workflow-agent-office` | writer 角色执行器：调用 `office-agent` CLI |
+| `workflow-agent-docx-diff` | `@uncaged/workflow-agent-docx-diff` | differ 角色执行器：调用 `docx-diff` CLI |
+
+Template 只定义结构，不含执行逻辑。执行器与 template 解耦。
+
+---
+
+## 一、`workflow-template-document`
+
+### Thread 启动输入
+
+```typescript
+// src/types.ts
+type DocumentStartInput = {
+  prompt: string;           // 用户指令
+  inputDocx: string | null; // null = 生成模式；本机绝对路径 = 编辑模式
+};
+```
+
+start.content 为 JSON `{ prompt, inputDocx }` 或纯文本（fallback：generate 模式，整段作为 prompt）。
+
+### 角色与 Meta
+
+`WriterMeta` 使用 discriminated union，在 schema 层区分两种模式：
+
+```typescript
+const writerMetaSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("generate"),
+    outputDocx: z.string(),   // 生成产物绝对路径
+    sourceDocx: z.null(),
+  }),
+  z.object({
+    mode: z.literal("edit"),
+    outputDocx: z.string(),   // 修改后产物：<outputDir>/modified.docx
+    sourceDocx: z.string(),   // 原始副本：<outputDir>/original.docx
+  }),
+]);
+type WriterMeta = z.infer<typeof writerMetaSchema>;
+
+// differ：仅编辑模式执行
+const differMetaSchema = z.object({
+  sourceDocx: z.string(),
+  modifiedDocx: z.string(),
+  diffDocx: z.string(),
+});
+type DifferMeta = z.infer<typeof differMetaSchema>;
+```
+
+两个角色的 `systemPrompt` 均为 `""`。
+
+### 调度表
+
+```
+START → writer ──(mode = "edit")──→ differ → END
+               ↘(mode = "generate")→ END
+```
+
+### 公开导出
+
+template 导出两个对象供消费方使用：
+
+- `documentWorkflowDefinition: WorkflowDefinition<DocumentMeta>` — 传入 `createWorkflow` 的 `def` 参数
+- `buildDocumentDescriptor(): WorkflowDescriptor` — bundle 导出用
+
+```typescript
+// bundle 侧用法
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, { adapter, overrides });
+```
+
+### 包文件结构
+
+```
+packages/workflow-template-document/
+  src/
+    types.ts           # DocumentStartInput
+    roles/
+      writer.ts        # writerMetaSchema, WriterMeta, writerRole
+      differ.ts        # differMetaSchema, DifferMeta, differRole
+      index.ts
+    roles.ts           # DocumentMeta, documentRoles
+    moderator.ts       # writerIsEditMode condition + documentTable
+    definition.ts      # documentWorkflowDefinition
+    descriptor.ts      # buildDocumentDescriptor()
+    index.ts
+  __tests__/
+    moderator.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-runtime": "workspace:^",
+  "@uncaged/workflow-register": "workspace:^",
+  "zod": "^4.0.0"
+}
+```
+
+---
+
+## 二、`workflow-agent-office`
+
+### office-agent CLI 接口
+
+```bash
+# 生成模式：在 CWD 生成 output.docx
+office-agent create "<prompt>" -o output.docx
+
+# 编辑模式：在 CWD 对 modified.docx 进行修改（覆写）
+office-agent edit modified.docx "<instruction>"
+```
+
+- 两个命令均为阻塞调用（CLI 内部消费 SSE，退出即完成）
+- 输出文件落到调用方设定的 CWD
+- 退出码 0 = 成功，非零 = 失败
+
+### 文件命名约定
+
+| 模式 | 文件 | 路径 |
+|---|---|---|
+| generate | 输出 | `<outputDir>/output.docx` |
+| edit | 原始副本（workflow-owned 快照） | `<outputDir>/original.docx` |
+| edit | 修改后产物 | `<outputDir>/modified.docx` |
+
+edit 模式先将 `inputDocx` 复制为 `original.docx`（不可变快照），再复制为 `modified.docx`，对 `modified.docx` 调用 CLI。agent 覆写 `modified.docx`，`original.docx` 保持不变。differ 对比这两个 workflow-owned 文件，不依赖用户原始路径。
+
+### 执行流程
+
+**生成模式（`inputDocx = null`）：**
+1. `mkdir -p <outputDir>`（`<config.outputDir>/<ctx.threadId>`）
+2. `const command = config.command ?? "office-agent"`
+3. `spawnCli(command, ["create", prompt, "-o", "output.docx"], { cwd: outputDir, timeoutMs })`
+4. 验证 `outputDir/output.docx` 存在
+5. 返回 `JSON.stringify({ mode: "generate", outputDocx, sourceDocx: null })`
+
+**编辑模式（`inputDocx ≠ null`）：**
+1. `mkdir -p <outputDir>`
+2. `copyFile(inputDocx, <outputDir>/original.docx)`
+3. `copyFile(inputDocx, <outputDir>/modified.docx)`
+4. `const command = config.command ?? "office-agent"`
+5. `spawnCli(command, ["edit", "modified.docx", prompt], { cwd: outputDir, timeoutMs })`
+6. 验证 `outputDir/modified.docx` 存在
+7. 返回 `JSON.stringify({ mode: "edit", outputDocx: modifiedPath, sourceDocx: originalPath })`
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+CLI 产出确定性 JSON，直接 `schema.parse(JSON.parse(raw))` 跳过 LLM extraction：
+
+```typescript
+export function createOfficeAgent(config: OfficeAgentConfig): AdapterFn {
+  return <T>(_systemPrompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const { prompt, inputDocx } = parseStartInput(ctx.start.content);
+      const raw = await runOfficeAgent(config, ctx.threadId, prompt, inputDocx);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+`_systemPrompt` 为 writer 角色的 systemPrompt（空字符串），实际指令从 `ctx.start.content` 解析。
+
+### 配置
+
+```typescript
+type OfficeAgentConfig = {
+  outputDir: string;        // 输出根目录，runner 在此下按 threadId 建子目录
+  command: string | null;   // null → runner 内 resolve 为 "office-agent"
+  timeout: number | null;   // null → 不设超时；单位 ms
+};
+```
+
+### 错误处理
+
+```typescript
+if (!result.ok) {
+  const e = result.error;
+  if (e.kind === "non_zero_exit")
+    throw new Error(`office-agent failed (exit ${e.exitCode}): ${e.stderr}`);
+  if (e.kind === "timeout")
+    throw new Error("office-agent: timed out");
+  // "spawn_failed"
+  throw new Error(`office-agent: spawn failed: ${e.message}`);
+}
+if (!existsSync(expectedPath))
+  throw new Error(`office-agent: output file not found: ${expectedPath}`);
+```
+
+### packageDescriptor
+
+```typescript
+// src/package-descriptor.ts
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-office",
+  version: "0.1.0",
+  capabilities: ["office-agent-cli", "docx-generate", "docx-edit"],
+  configSchema: {
+    type: "object",
+    required: ["outputDir"],
+    properties: {
+      outputDir: { type: "string", description: "Root directory for workflow outputs." },
+      command:   { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to office-agent CLI; null uses PATH." },
+      timeout:   { anyOf: [{ type: "number" }, { type: "null" }], description: "Timeout in ms; null means no limit." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-office/
+  src/
+    types.ts                # OfficeAgentConfig, OfficeAgentOpt
+    runner.ts               # runOfficeAgent()（spawnCli 封装 + 文件验证）
+    agent.ts                # createOfficeAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^"
+}
+```
+
+---
+
+## 三、`workflow-agent-docx-diff`
+
+`differ` 角色专用执行器。从 `ctx.steps` 读取 `WriterMeta`，调用本地 `docx-diff` CLI。
+
+### docx-diff 退出码约定
+
+| 退出码 | 含义 | runner 处理 |
+|---|---|---|
+| 0 | 无差异 | 正常，验证 diffDocx 存在 |
+| 1 | 有差异 | 正常（显式处理为成功），验证 diffDocx 存在 |
+| 2+ | 错误 | throw |
+
+runner 收到 `SpawnCliError { kind: "non_zero_exit", exitCode: 1 }` 时视为成功，验证文件后继续；`exitCode >= 2` 才 throw。
+
+### 执行流程
+
+```
+1. 从 ctx.steps 找到 writer 步骤，读取 WriterMeta
+2. 验证 mode === "edit"（否则 throw）
+3. diffDocx = join(dirname(writer.outputDocx), "diff.docx")
+4. const command = config.command ?? "docx-diff"
+5. spawnCli(command,
+     [writer.sourceDocx, writer.outputDocx, "--output", "docx", "--out-file", diffDocx],
+     { cwd: null, timeoutMs: null })
+   exit 0 或 1 → 验证 diffDocx 存在
+   exit 2+ → throw
+6. 返回 JSON.stringify({ sourceDocx, modifiedDocx: writer.outputDocx, diffDocx })
+```
+
+### AdapterFn 实现（直接实现，不经过 runtime.extract）
+
+```typescript
+export function createDocxDiffAgent(config: DocxDiffAgentConfig = { command: null }): AdapterFn {
+  return <T>(_prompt: string, schema: z.ZodType<T>) =>
+    async (ctx: ThreadContext, _runtime: WorkflowRuntime): Promise<RoleResult<T>> => {
+      const writerStep = ctx.steps.find(s => s.role === "writer");
+      if (!writerStep) throw new Error("differ: no writer step found");
+      const writerMeta = writerStep.meta as WriterMeta;
+      if (writerMeta.mode !== "edit")
+        throw new Error("differ: writer did not run in edit mode");
+      const raw = await runDocxDiff(config, writerMeta);
+      const meta = schema.parse(JSON.parse(raw)) as T;
+      return { meta, childThread: null };
+    };
+}
+```
+
+### 配置
+
+```typescript
+type DocxDiffAgentConfig = {
+  command: string | null;   // null → runner 内 resolve 为 "docx-diff"
+};
+```
+
+### packageDescriptor
+
+```typescript
+export const packageDescriptor: PackageDescriptor = {
+  name: "@uncaged/workflow-agent-docx-diff",
+  version: "0.1.0",
+  capabilities: ["docx-diff-cli", "docx-diff-report"],
+  configSchema: {
+    type: "object",
+    properties: {
+      command: { anyOf: [{ type: "string" }, { type: "null" }], description: "Path to docx-diff CLI; null uses PATH." },
+    },
+    additionalProperties: false,
+  },
+};
+```
+
+### 包文件结构
+
+```
+packages/workflow-agent-docx-diff/
+  src/
+    types.ts                # DocxDiffAgentConfig
+    runner.ts               # runDocxDiff()（exit 1 处理 + 文件验证）
+    agent.ts                # createDocxDiffAgent(): AdapterFn
+    package-descriptor.ts   # packageDescriptor
+    index.ts
+  __tests__/
+    runner.test.ts
+    agent.test.ts
+  package.json
+  tsconfig.json
+```
+
+### 依赖
+
+```json
+{
+  "@uncaged/workflow-protocol": "workspace:^",
+  "@uncaged/workflow-util-agent": "workspace:^",
+  "@uncaged/workflow-template-document": "workspace:^"
+}
+```
+
+---
+
+## 四、外部 bundle（外部 workspace 消费）
+
+```typescript
+import { createOfficeAgent } from "@uncaged/workflow-agent-office";
+import { createDocxDiffAgent } from "@uncaged/workflow-agent-docx-diff";
+import {
+  buildDocumentDescriptor,
+  documentWorkflowDefinition,
+} from "@uncaged/workflow-template-document";
+import { createWorkflow } from "@uncaged/workflow-runtime";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow-util";
+import { join } from "node:path";
+
+const outputDir = join(getDefaultWorkflowStorageRoot(), "outputs");
+
+export const descriptor = buildDocumentDescriptor();
+export const run = createWorkflow(documentWorkflowDefinition, {
+  adapter: createOfficeAgent({ outputDir, command: null, timeout: null }),
+  overrides: { differ: createDocxDiffAgent() },
+});
+```
+
+---
+
+## 不在范围内
+
+- 重试逻辑（失败直接 throw）
+- office-agent server 的启停管理（假设 server 已在运行）
+- docx-diff HTML/terminal 格式输出（仅 docx）
+- 跨机器执行（`inputDocx` 须为本机有效绝对路径）

docs/wf-stateless-design.md

@@ -0,0 +1,527 @@
+# `uwf` — Stateless Workflow CLI
+
+> 将 workflow 引擎降维为无状态单步 CLI。Workflow 是纯数据（CAS 节点），执行是单步原子操作，agent 是可插拔外部命令。
+
+---
+
+## 1. CLI Design
+
+### 1.1 命令总览
+
+```
+# thread 组
+uwf thread start <workflow> -p <prompt>     # 创建 thread，不执行
+uwf thread step  <thread-id> [--agent]      # 单步执行
+uwf thread show  <thread-id>                # thread-id → head 查询
+uwf thread list  [--all]                    # 列出活跃 threads（--all 含已归档）
+uwf thread kill  <thread-id>                # 终结 thread，归档
+
+# workflow 组
+uwf workflow put   <file.yaml>              # 注册 workflow（YAML → CAS）
+uwf workflow show  <workflow-id>            # 查看 workflow 定义
+uwf workflow list                           # 列出已注册 workflows
+```
+
+两组对称，各 3-4 个子命令。CAS 操作交给 `json-cas` CLI，不在 `uwf` 中重复。
+
+### 1.2 `uwf thread start`
+
+```bash
+uwf thread start <workflow> -p "Fix the login bug described in issue #42"
+```
+
+- `<workflow>` — workflow 名或 CAS hash
+- `-p` — 用户 prompt（必填）
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",   // workflow CAS hash (XXH64, 13-char Crockford Base32)
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T"      // ULID
+}
+```
+
+**做的事：**
+1. 解析 workflow（名字查 registry → CAS hash）
+2. 生成 thread ULID
+3. 写 StartNode 到 CAS
+4. 在 threads.yaml 中记录链头 → StartNode hash
+5. 输出 JSON
+
+### 1.3 `uwf thread step`
+
+```bash
+uwf thread step 01J7K9M2XNPQR5VWBCDF8G3H4T
+uwf thread step 01J7K9M2XNPQR5VWBCDF8G3H4T --agent "bunx uwf-cursor"
+```
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T",
+  "head": "8FWKR3TN5V1QA",       // 新链头 StepNode 的 CAS hash
+  "done": false                    // true = moderator 返回 END，thread 已归档
+}
+```
+
+`done: true` 时 head 仍然有值（最后一个 StepNode），但 thread 已从 threads.yaml 移除。
+对已结束或不存在的 thread 调用 step 会报错（非 active thread）。
+
+详细信息通过 `uwf thread show <thread-id>` 或 `json-cas get <head>` 查看。
+
+**做的事：**
+1. 读链头 → 当前 StepNode（或 StartNode）
+2. 收集 thread 历史（遍历链）
+3. 调 moderator：评估 JSONata conditions → 得到下一个 role（或 END）
+4. 若 END → 归档 thread，输出最后链头，退出
+5. 确定 agent command（`--agent` override > config.yaml per-workflow/role > config.yaml defaultAgent）
+6. 调用：`<agent-cmd> <thread-id> <role>`，捕获 stdout 得到新 StepNode hash
+7. 更新链头指针
+8. 再次调 moderator（基于新 StepNode）判断 done
+9. 输出 JSON
+
+### 1.4 `uwf thread show`
+
+```bash
+uwf thread show 01J7K9M2XNPQR5VWBCDF8G3H4T
+```
+
+**输出（JSON to stdout）：**
+
+```jsonc
+{
+  "workflow": "4KNM2PXR3B1QW",
+  "thread": "01J7K9M2XNPQR5VWBCDF8G3H4T",
+  "head": "8FWKR3TN5V1QA",
+  "done": false
+}
+```
+
+纯 thread-id → head 查询。详细内容用 `json-cas get <head>` 或 `json-cas walk <head>` 查看。
+
+### 1.5 Agent CLI 协议
+
+每个 agent 是一个命令，接受 thread-id 和 role 两个参数：
+
+```bash
+uwf-hermes <thread-id> <role>
+```
+
+**约定：**
+- `uwf step` 负责 moderator 决策，将 role 传给 agent CLI
+- agent-kit 根据 thread + role 从 CAS 读 systemPrompt / outputSchema
+- agent-kit 组装完整 prompt（role systemPrompt + thread context + user prompt from StartNode）
+- agent 执行实际逻辑，agent-kit 负责 extract
+- agent 将 StepNode 写入 CAS（含 output、detail、agent、prev），但**不挪链头指针**
+- stdout 输出新 StepNode 的 CAS hash（纯文本，一行）
+- 所有配置从环境变量读（LLM model、API key、extractor config）
+- exit 0 = 成功，非 0 = 失败
+
+**stdout 输出：**
+
+```
+8FWKR3TN5V1QA
+```
+
+`uwf step` 拿到这个 hash 后更新链头指针、判断 done。
+
+---
+
+## 2. CAS 结构定义
+
+### 2.1 类型层级
+
+沿用 json-cas 的三层：bootstrap meta-schema → JSON Schema nodes → data nodes。
+
+下面所有 CAS 节点都遵循 `{ type: cas_ref, payload: T, timestamp: number }` 的标准格式。
+`cas_ref` 类型的字符串字段在 json-cas 中已内置支持，不需要额外的 `$ref` 包装。
+
+### 2.2 数据节点
+
+#### `Workflow`
+
+Roles 和 moderator 内联在 Workflow 中，只有 outputSchema 独立为 CAS 节点（方便 json-cas 校验）。
+
+```yaml
+type: <workflow-schema-hash>
+payload:
+  name: "solve-issue"
+  description: "End-to-end issue resolution"
+  roles:
+    planner:
+      description: "Creates implementation plan"
+      systemPrompt: "You are a planning agent..."
+      outputSchema: "5GWKR8TN1V3JA"    # cas_ref → JSON Schema 节点（json-cas 内置）
+    developer:
+      description: "Implements code changes"
+      systemPrompt: "You are a developer agent..."
+      outputSchema: "8CNWT4KR6D1HV"    # cas_ref → JSON Schema 节点
+    reviewer:
+      description: "Reviews code changes"
+      systemPrompt: "You are a code reviewer..."
+      outputSchema: "1VPBG9SM5E7WK"    # cas_ref → JSON Schema 节点
+  conditions:
+    needsClarification:
+      description: "Planner requests clarification from user"
+      expression: "$exists(steps[-1].output.needsClarification)"
+    notApproved:
+      description: "Reviewer rejected the implementation"
+      expression: "steps[-1].output.approved = false"
+  graph:
+    $START:
+      - role: "planner"
+        condition: null                  # 无条件（fallback）
+    planner:
+      - role: "developer"
+        condition: "needsClarification"
+      - role: "$END"
+        condition: null
+    developer:
+      - role: "reviewer"
+        condition: null
+    reviewer:
+      - role: "developer"
+        condition: "notApproved"
+      - role: "$END"
+        condition: null
+```
+
+- `roles` — 内联定义，每个 role 的 `outputSchema` 是独立的 cas_ref（指向 json-cas 内置 JSON Schema 节点）
+- `conditions` — `Record<Name, JSONata>`，命名条件，方便画图描述
+- `graph` — `Record<Role | "$START", Transition[]>`，每个 Transition = `{ role, condition }`
+- `condition` 引用 conditions 中的 key，`null` = fallback
+- 按数组顺序求值，第一个匹配的 transition 胜出
+- 不含 agent binding — agent 配置在 `~/.uncaged/workflow/config.yaml` 中管理
+
+JSONata 表达式的求值上下文：
+
+```jsonc
+{
+  "start": {                          // StartNode 信息
+    "workflow": "4KNM2PXR3B1QW",
+    "prompt": "Fix the login bug..."
+  },
+  "steps": [                          // 所有已完成 steps，从旧到新
+    { "role": "planner", "output": { "phases": [...] }, "detail": "7BQST3VW9F2MA", "agent": "uwf-hermes" },
+    { "role": "developer", "output": { "filesChanged": ["src/auth.ts"], "summary": "Fixed redirect" }, "detail": "9KRVW3TN5F1QA", "agent": "uwf-cursor" },
+    { "role": "reviewer", "output": { "approved": false }, "detail": "2MXBG6PN4A8JR", "agent": "uwf-hermes" }
+  ]
+}
+```
+
+注：`output` 在上下文中会被自动展开为实际的 CAS 节点内容（而非 hash），方便 JSONata 表达式直接访问字段。
+
+#### `StartNode`（Thread 起点）
+
+```yaml
+type: <start-node-schema-hash>
+payload:
+  workflow: "4KNM2PXR3B1QW"        # cas_ref → Workflow
+  prompt: "Fix the login bug..."
+```
+
+- 没有 thread-id — thread-id 是索引层面的事，不进 CAS 内容
+- 没有 agent binding — 运行时从 config.yaml 解析
+
+#### `StepNode`（Thread 每一步）
+
+```yaml
+type: <step-node-schema-hash>
+payload:
+  start: "4TNVW8KR2B3MA"          # cas_ref → StartNode（每个 step 都引用）
+  prev: "2MXBG6PN4A8JR"           # cas_ref → 前一个 StepNode，第一步为 null
+  role: "developer"
+  output: "9KRVW3TN5F1QA"         # cas_ref → 结构化输出节点（符合 role 的 outputSchema）
+  detail: "7BQST3VW9F2MA"         # cas_ref → 执行详情（content node / 子 workflow terminal StepNode / ...）
+  agent: "uwf-cursor"              # 实际使用的 agent 命令（纯字符串）
+```
+
+- `start` — 每个 StepNode 都直接引用 StartNode，方便随机访问
+- `prev` — 前一个 StepNode 的 cas_ref，第一步为 `null`（不指向 StartNode）
+- `output` — cas_ref，指向符合 role outputSchema 的 CAS 节点，可用 json-cas 校验
+- `detail` — cas_ref，指向执行详情。可以是原始 agent 输出（content node），也可以是子 workflow thread 的 terminal StepNode（workflowAsAgent 场景）
+- `agent` — 纯字符串，不是 CAS 节点
+
+### 2.3 链式结构
+
+```
+threads.yaml: { "01J7K9M2XNPQR5VWBCDF8G3H4T": "8FWKR3TN5V1QA" }
+                                      │
+                                      ▼
+                              StepNode (step 3)
+                              ├── start ──→ StartNode
+                              │              ├── workflow → CAS(Workflow)
+                              │              └── prompt: "Fix..."
+                              ├── prev ──→ StepNode (step 2)
+                              │             ├── start ──→ (same StartNode)
+                              │             ├── prev ──→ StepNode (step 1)
+                              │             │             ├── start ──→ (same StartNode)
+                              │             │             ├── prev: null
+                              │             │             ├── role: "planner"
+                              │             │             └── ...
+                              │             ├── role: "developer"
+                              │             └── ...
+                              ├── role: "reviewer"
+                              ├── output → CAS({ approved: true })
+                              ├── detail → CAS(raw output | sub-workflow terminal node)
+                              └── agent: "uwf-hermes"
+```
+
+### 2.4 可变状态
+
+系统两个顶层 YAML 文件和一个 env 文件：
+
+```yaml
+# ~/.uncaged/workflow/config.yaml — 全局配置
+providers:
+  openai:
+    baseUrl: "https://api.openai.com/v1"
+    apiKeyEnv: "OPENAI_API_KEY"
+  anthropic:
+    baseUrl: "https://api.anthropic.com/v1"
+    apiKeyEnv: "ANTHROPIC_API_KEY"
+  openrouter:
+    baseUrl: "https://openrouter.ai/api/v1"
+    apiKeyEnv: "OPENROUTER_API_KEY"
+
+models:
+  sonnet:
+    provider: "openrouter"
+    name: "anthropic/claude-sonnet-4"
+  gpt4o-mini:
+    provider: "openai"
+    name: "gpt-4o-mini"
+
+agents:
+  hermes:
+    command: "uwf-hermes"
+    args: []
+  cursor:
+    command: "uwf-cursor"
+    args: []
+
+defaultAgent: "hermes"
+agentOverrides:
+  solve-issue:
+    developer: "cursor"
+
+defaultModel: "sonnet"
+modelOverrides:
+  extract: "gpt4o-mini"
+```
+
+```yaml
+# ~/.uncaged/workflow/threads.yaml — active thread 链头指针
+01J7K9M2XNPQR5VWBCDF8G3H4T: "8FWKR3TN5V1QA"
+01J8AB3QRMSTV6WKXZ2C4DF7GN: "3CNWT9KR6D2HV"
+```
+
+Thread 结束时从 threads.yaml 移除。可选：追加到 `history.jsonl` 做归档。
+
+```bash
+# ~/.uncaged/workflow/.env — 敏感信息（API keys）
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
+```
+
+- `config.yaml` — 非敏感配置（agent 命令、model 名、provider 名）
+- `.env` — 敏感信息（API keys），agent-kit 启动时自动加载
+- `threads.yaml` — 运行时状态
+
+---
+
+## 3. 包结构
+
+全新包，不复用现有 packages，避免命名冲突。CAS 直接依赖 `@uncaged/json-cas`。
+
+```
+packages/
+├── cli-uwf/              # @uncaged/cli-uwf — uwf CLI（thread/workflow 命令）
+├── uwf-moderator/        # @uncaged/uwf-moderator — JSONata moderator 引擎
+├── uwf-agent-kit/        # @uncaged/uwf-agent-kit — Agent CLI 框架（含 extractor）
+├── uwf-agent-hermes/     # @uncaged/uwf-agent-hermes — uwf-hermes CLI
+├── uwf-agent-cursor/     # @uncaged/uwf-agent-cursor — uwf-cursor CLI
+└── uwf-protocol/         # @uncaged/uwf-protocol — 共享类型定义
+```
+
+**外部依赖：**
+- `@uncaged/json-cas` — CAS 存储、hash、schema 校验
+- `@uncaged/json-cas-fs` — 文件系统 CAS 后端
+
+**现有包全部保留不动**，新旧并存，逐步迁移。
+
+---
+
+## 4. 关键数据类型
+
+JSONata 求值上下文本质上是 thread 链表的线性化表达。StepNode payload 和上下文中的 step 共享大量字段，提取为公共类型。
+
+### 4.1 公共类型
+
+```typescript
+/** CAS hash — XXH64, 13-char Crockford Base32 */
+type CasRef = string;
+
+/** Thread ID — ULID, 26-char Crockford Base32 */
+type ThreadId = string;
+
+/** 一个 step 的核心数据，被 StepNode payload 和 JSONata 上下文共享 */
+type StepRecord = {
+  role: string;
+  output: CasRef;                    // cas_ref → 结构化输出节点（符合 role outputSchema）
+  detail: CasRef;                    // cas_ref → 执行详情（content node / 子 workflow terminal StepNode）
+  agent: string;                     // 实际使用的 agent 命令（纯字符串）
+};
+```
+
+### 4.2 Workflow 定义
+
+```typescript
+type RoleDefinition = {
+  description: string;
+  systemPrompt: string;
+  outputSchema: CasRef;              // cas_ref → json-cas 内置 JSON Schema 节点
+};
+
+type Transition = {
+  role: string;                      // 目标 role 名 或 "$END"
+  condition: string | null;          // 引用 conditions 中的 key，null = fallback
+};
+
+type ConditionDefinition = {
+  description: string;
+  expression: string;                           // JSONata expression
+};
+
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;          // Record<Role | "$START", Transition[]>
+};
+```
+
+### 4.3 Thread 节点
+
+```typescript
+type StartNodePayload = {
+  workflow: CasRef;                  // cas_ref → Workflow
+  prompt: string;
+};
+
+type StepNodePayload = StepRecord & {
+  start: CasRef;                     // cas_ref → StartNode（每个 step 都引用）
+  prev: CasRef | null;               // cas_ref → 前一个 StepNode，第一步为 null
+};
+```
+
+### 4.4 JSONata 求值上下文
+
+Thread 链表的线性化。`steps[n]` 的字段和 `StepRecord` 一致，但 `output` 被展开为实际内容。
+
+```typescript
+/** JSONata 上下文中的 step — output 被展开 */
+type StepContext = Omit<StepRecord, "output"> & {
+  output: unknown;                   // 展开后的 CAS 节点内容，非 hash
+};
+
+type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];              // 从旧到新
+};
+```
+
+### 4.5 CLI 输出
+
+```typescript
+/** uwf thread start */
+type StartOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+};
+
+/** uwf thread step / uwf thread show */
+type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+/** uwf thread list */
+type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+```
+
+### 4.6 配置
+
+```typescript
+/** Alias types for config references */
+type AgentAlias = string;
+type ModelAlias = string;
+type ProviderAlias = string;
+type WorkflowName = string;
+type RoleName = string;
+type Scenario = string;              // e.g. "extract"
+
+type ProviderConfig = {
+  baseUrl: string;
+  apiKeyEnv: string;                 // env var name to read API key from
+};
+
+type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;                      // e.g. "anthropic/claude-sonnet-4", "gpt-4o-mini"
+};
+
+type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+/** ~/.uncaged/workflow/config.yaml */
+type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+
+/** ~/.uncaged/workflow/threads.yaml */
+type ThreadsIndex = Record<ThreadId, CasRef>;
+//                         ^ thread-id  ^ head StepNode/StartNode hash
+```
+
+### 4.7 类型关系图
+
+```
+WorkflowConfig (config.yaml)
+ThreadsIndex (threads.yaml)          ← 唯二可变状态
+    │
+    │ thread-id → head hash
+    ▼
+StepNodePayload ──extends──→ StepRecord ←──maps to──→ StepContext
+    │                           │                          │
+    ├── start → StartNodePayload│                          │ (output 展开)
+    ├── prev → StepNodePayload  │                          │
+    │                           ├── role                   ├── role
+    │                           ├── output (CasRef)        ├── output (展开)
+    │                           ├── detail (CasRef)        ├── detail (CasRef)
+    │                           └── agent (string)         └── agent (string)
+    │
+    └── start.workflow → WorkflowPayload
+                             ├── roles: Record<name, RoleDefinition>
+                             ├── conditions: Record<name, JSONata>
+                             └── graph: Record<role, Transition[]>
+```

package.json

@@ -6,13 +6,18 @@
   ],
   "scripts": {
     "build": "bunx tsc --build",
-    "check": "bunx tsc --build && biome check .",
+    "check": "bunx tsc --build && biome check . && bash scripts/lint-log-tags.sh",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",
-    "test": "bun run --filter '*' test"
+    "test": "bun run --filter '*' test",
+    "changeset": "bunx changeset",
+    "version": "bunx changeset version",
+    "release": "bun run build && bun test && npx changeset publish --no-git-tag"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@changesets/cli": "^2.31.0",
+    "@types/node": "^25.7.0",
     "@types/xxhashjs": "^0.2.4",
     "bun-types": "^1.3.13"
   }

packages/cli-uwf/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@uncaged/cli-uwf",
+  "version": "0.1.0",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
+  "type": "module",
+  "bin": {
+    "uwf": "./src/cli.ts"
+  },
+  "dependencies": {
+    "@uncaged/json-cas": "^0.1.3",
+    "@uncaged/json-cas-fs": "^0.1.2",
+    "@uncaged/uwf-agent-kit": "workspace:^",
+    "@uncaged/uwf-moderator": "workspace:^",
+    "@uncaged/uwf-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "commander": "^14.0.3",
+    "dotenv": "^16.6.1",
+    "yaml": "^2.8.4"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/cli-uwf/src/cli.ts

@@ -0,0 +1,269 @@
+#!/usr/bin/env bun
+
+import { Command } from "commander";
+
+import {
+  cmdThreadKill,
+  cmdThreadList,
+  cmdThreadShow,
+  cmdThreadStart,
+  cmdThreadStep,
+} from "./commands/thread.js";
+import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
+import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
+import {
+  cmdCasGet,
+  cmdCasHas,
+  cmdCasPut,
+  cmdCasRefs,
+  cmdCasSchemaGet,
+  cmdCasSchemaList,
+  cmdCasWalk,
+} from "./commands/cas.js";
+import { resolveStorageRoot } from "./store.js";
+import { type OutputFormat, formatOutput } from "./format.js";
+
+function writeOutput(data: unknown): void {
+  const fmt = program.opts().format as OutputFormat;
+  process.stdout.write(`${formatOutput(data, fmt)}\n`);
+}
+
+function runAction(action: () => Promise<void>): void {
+  action().catch((e: unknown) => {
+    const message = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  });
+}
+
+const program = new Command();
+
+program.name("uwf").description("Stateless workflow CLI");
+program.option("--format <fmt>", "Output format: json or yaml", "json");
+
+const workflow = program.command("workflow").description("Workflow registry and CAS");
+
+workflow
+  .command("put")
+  .description("Register a workflow from YAML")
+  .argument("<file>", "Workflow YAML file")
+  .action((file: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowPut(storageRoot, file);
+      writeOutput(result);
+    });
+  });
+
+workflow
+  .command("show")
+  .description("Show a workflow by name or CAS hash")
+  .argument("<id>", "Workflow name or hash")
+  .action((id: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowShow(storageRoot, id);
+      writeOutput(result);
+    });
+  });
+
+workflow
+  .command("list")
+  .description("List registered workflows")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdWorkflowList(storageRoot);
+      writeOutput(result);
+    });
+  });
+
+const thread = program.command("thread").description("Thread lifecycle and execution");
+
+thread
+  .command("start")
+  .description("Create a thread without executing")
+  .argument("<workflow>", "Workflow name or hash")
+  .requiredOption("-p, --prompt <text>", "User prompt")
+  .action((workflow: string, opts: { prompt: string }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("step")
+  .description("Execute one step")
+  .argument("<thread-id>", "Thread ULID")
+  .option("--agent <cmd>", "Override agent command")
+  .action((threadId: string, opts: { agent: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const agentOverride = opts.agent ?? null;
+      const result = await cmdThreadStep(storageRoot, threadId, agentOverride);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("show")
+  .description("Show thread head pointer")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadShow(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("list")
+  .description("List active threads")
+  .option("--all", "Include archived threads")
+  .action((opts: { all: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadList(storageRoot, opts.all);
+      writeOutput(result);
+    });
+  });
+
+thread
+  .command("kill")
+  .description("Terminate and archive a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdThreadKill(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+program
+  .command("setup")
+  .description("Configure provider, model, and agent")
+  .option("--provider <name>", "Provider name")
+  .option("--base-url <url>", "OpenAI-compatible API base URL")
+  .option("--api-key <key>", "API key")
+  .option("--model <name>", "Default model name")
+  .option("--agent <name>", "Default agent alias")
+  .action((opts: {
+    provider?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    model?: string;
+    agent?: string;
+  }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      if (opts.provider && opts.baseUrl && opts.apiKey && opts.model) {
+        const result = await cmdSetup({
+          provider: opts.provider,
+          baseUrl: opts.baseUrl,
+          apiKey: opts.apiKey,
+          model: opts.model,
+          agent: opts.agent ?? undefined,
+          storageRoot,
+        });
+        writeOutput(result);
+      } else if (!opts.provider && !opts.baseUrl && !opts.apiKey && !opts.model) {
+        await cmdSetupInteractive(storageRoot);
+      } else {
+        throw new Error(
+          "Non-interactive setup requires all of: --provider, --base-url, --api-key, --model",
+        );
+      }
+    });
+  });
+
+const cas = program.command("cas").description("Content-addressable storage operations");
+
+cas
+  .command("get")
+  .description("Read a CAS node (type + payload; use --timestamp to include timestamp)")
+  .argument("<hash>", "CAS hash (13 char)")
+  .option("--timestamp", "Include timestamp in output")
+  .action((hash: string, opts: { timestamp?: boolean }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasGet(storageRoot, hash, opts));
+    });
+  });
+
+cas
+  .command("put")
+  .description("Store a node, print its hash")
+  .argument("<type-hash>", "Type (schema) hash")
+  .argument("<data>", "JSON file path or inline JSON string")
+  .action((typeHash: string, data: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasPut(storageRoot, typeHash, data));
+    });
+  });
+
+cas
+  .command("has")
+  .description("Check if a hash exists")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasHas(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("refs")
+  .description("List direct CAS references from a node")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasRefs(storageRoot, hash));
+    });
+  });
+
+cas
+  .command("walk")
+  .description("Recursive traversal from a node")
+  .argument("<hash>", "CAS hash (13 char)")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasWalk(storageRoot, hash));
+    });
+  });
+
+const casSchema = cas.command("schema").description("CAS schema operations");
+
+casSchema
+  .command("list")
+  .description("List all registered schemas")
+  .action(() => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaList(storageRoot));
+    });
+  });
+
+casSchema
+  .command("get")
+  .description("Show a schema by its type hash")
+  .argument("<hash>", "Schema type hash")
+  .action((hash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      writeOutput(await cmdCasSchemaGet(storageRoot, hash));
+    });
+  });
+
+program.parseAsync(process.argv).catch((e: unknown) => {
+  const message = e instanceof Error ? e.message : String(e);
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+});

packages/cli-uwf/src/commands/cas.ts

@@ -0,0 +1,128 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Hash, JSONSchema, Store } from "@uncaged/json-cas";
+import { bootstrap, getSchema, refs, walk } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+
+// ---- Helpers ----
+
+function openStore(storageRoot: string): Store {
+  return createFsStore(join(storageRoot, "cas"));
+}
+
+function readJsonArg(fileOrInline: string): unknown {
+  try {
+    return JSON.parse(fileOrInline);
+  } catch {
+    try {
+      return JSON.parse(readFileSync(fileOrInline, "utf-8"));
+    } catch (e) {
+      throw new Error(`Cannot parse JSON from "${fileOrInline}": ${e}`);
+    }
+  }
+}
+
+// ---- Commands (all return JSON-serializable data) ----
+
+export async function cmdCasGet(
+  storageRoot: string,
+  hash: string,
+  opts: { timestamp?: boolean },
+): Promise<unknown> {
+  const store = openStore(storageRoot);
+  const node = store.get(hash);
+  if (node === null) {
+    throw new Error(`Node not found: ${hash}`);
+  }
+  if (opts.timestamp) {
+    return node;
+  }
+  const { timestamp: _, ...rest } = node as Record<string, unknown>;
+  return rest;
+}
+
+export async function cmdCasPut(
+  storageRoot: string,
+  typeHash: string,
+  data: string,
+): Promise<{ hash: string }> {
+  const store = openStore(storageRoot);
+  const payload = readJsonArg(data);
+  const hash = await store.put(typeHash, payload);
+  return { hash };
+}
+
+export async function cmdCasHas(
+  storageRoot: string,
+  hash: string,
+): Promise<{ exists: boolean }> {
+  const store = openStore(storageRoot);
+  return { exists: store.has(hash) };
+}
+
+export async function cmdCasRefs(
+  storageRoot: string,
+  hash: string,
+): Promise<{ refs: string[] }> {
+  const store = openStore(storageRoot);
+  const node = store.get(hash);
+  if (node === null) {
+    throw new Error(`Node not found: ${hash}`);
+  }
+  return { refs: refs(store, node) };
+}
+
+export async function cmdCasWalk(
+  storageRoot: string,
+  hash: string,
+): Promise<{ hashes: string[] }> {
+  const store = openStore(storageRoot);
+  const result: string[] = [];
+  walk(store, hash, (h) => {
+    result.push(h);
+  });
+  return { hashes: result };
+}
+
+export type SchemaListEntry = {
+  hash: string;
+  title: string;
+};
+
+export async function cmdCasSchemaList(
+  storageRoot: string,
+): Promise<SchemaListEntry[]> {
+  const store = openStore(storageRoot);
+  const metaHash = await bootstrap(store);
+  const entries: SchemaListEntry[] = [];
+
+  // Include meta-schema itself
+  entries.push({ hash: metaHash, title: "(meta-schema)" });
+
+  for (const hash of store.list()) {
+    if (hash === metaHash) continue;
+    const node = store.get(hash);
+    if (node !== null && node.type === metaHash) {
+      const schema = node.payload as JSONSchema;
+      const title =
+        (schema.title as string | undefined) ??
+        (schema.description as string | undefined) ??
+        "(unnamed)";
+      entries.push({ hash, title });
+    }
+  }
+  return entries;
+}
+
+export async function cmdCasSchemaGet(
+  storageRoot: string,
+  hash: string,
+): Promise<unknown> {
+  const store = openStore(storageRoot);
+  const schema = getSchema(store, hash);
+  if (schema === null) {
+    throw new Error(`Schema not found: ${hash}`);
+  }
+  return schema;
+}

packages/cli-uwf/src/commands/setup.ts

@@ -0,0 +1,332 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+import { stringify, parse } from "yaml";
+
+/**
+ * Preset provider list — embedded to avoid runtime YAML loading dependency.
+ * Keep in sync with providers.yaml in cli-workflow.
+ */
+const PRESET_PROVIDERS = [
+  // International
+  { name: "openai", label: "OpenAI", baseUrl: "https://api.openai.com/v1" },
+  { name: "xai", label: "xAI", baseUrl: "https://api.x.ai/v1" },
+  { name: "openrouter", label: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1" },
+  { name: "venice", label: "Venice", baseUrl: "https://api.venice.ai/api/v1" },
+  // China
+  { name: "dashscope", label: "DashScope (Alibaba)", baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1" },
+  { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1" },
+  { name: "siliconflow", label: "SiliconFlow", baseUrl: "https://api.siliconflow.cn/v1" },
+  { name: "volcengine", label: "Volcengine (ByteDance)", baseUrl: "https://ark.cn-beijing.volces.com/api/v3" },
+  { name: "kimi", label: "Kimi (Moonshot)", baseUrl: "https://api.moonshot.cn/v1" },
+  { name: "glm", label: "GLM (Zhipu AI)", baseUrl: "https://open.bigmodel.cn/api/paas/v4" },
+  { name: "stepfun", label: "StepFun", baseUrl: "https://api.stepfun.com/v1" },
+  { name: "minimax", label: "MiniMax", baseUrl: "https://api.minimax.io/v1" },
+  // Local
+  { name: "ollama", label: "Ollama (local)", baseUrl: "http://localhost:11434/v1" },
+] as const;
+
+type SetupArgs = {
+  provider: string;
+  baseUrl: string;
+  apiKey: string;
+  model: string;
+  agent?: string | undefined;
+  storageRoot: string;
+};
+
+function getConfigPath(root: string): string {
+  return join(root, "config.yaml");
+}
+
+function getEnvPath(root: string): string {
+  return join(root, ".env");
+}
+
+/**
+ * Load existing config.yaml or return empty structure.
+ */
+function loadExistingConfig(configPath: string): Record<string, unknown> {
+  try {
+    if (existsSync(configPath)) {
+      const raw = parse(readFileSync(configPath, "utf8")) as unknown;
+      if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+        return raw as Record<string, unknown>;
+      }
+    }
+  } catch {
+    // ignore parse errors, start fresh
+  }
+  return {};
+}
+
+/**
+ * Load existing .env as key=value map.
+ */
+function loadEnvFile(envPath: string): Record<string, string> {
+  const env: Record<string, string> = {};
+  try {
+    if (existsSync(envPath)) {
+      for (const line of readFileSync(envPath, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "" || trimmed.startsWith("#")) continue;
+        const eq = trimmed.indexOf("=");
+        if (eq > 0) {
+          env[trimmed.slice(0, eq)] = trimmed.slice(eq + 1);
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return env;
+}
+
+function saveEnvFile(envPath: string, env: Record<string, string>): void {
+  const lines = Object.entries(env).map(([k, v]) => `${k}=${v}`);
+  writeFileSync(envPath, `${lines.join("\n")}\n`, "utf8");
+}
+
+function apiKeyEnvName(providerName: string): string {
+  return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
+}
+
+/**
+ * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
+ */
+function mergeConfig(existing: Record<string, unknown>, args: SetupArgs): Record<string, unknown> {
+  const providers = (typeof existing.providers === "object" && existing.providers !== null
+    ? { ...(existing.providers as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+
+  const envName = apiKeyEnvName(args.provider);
+  providers[args.provider] = { baseUrl: args.baseUrl, apiKeyEnv: envName };
+
+  const models = (typeof existing.models === "object" && existing.models !== null
+    ? { ...(existing.models as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+  models.default = { provider: args.provider, name: args.model };
+
+  const agents = (typeof existing.agents === "object" && existing.agents !== null
+    ? { ...(existing.agents as Record<string, unknown>) }
+    : {}) as Record<string, unknown>;
+
+  const agentName = args.agent ?? "hermes";
+  if (Object.keys(agents).length === 0) {
+    agents.hermes = { command: "uwf-hermes", args: [] };
+  }
+
+  return {
+    ...existing,
+    providers,
+    models,
+    agents,
+    defaultAgent: existing.defaultAgent ?? agentName,
+    defaultModel: existing.defaultModel ?? "default",
+  };
+}
+
+/**
+ * Non-interactive setup. All required args provided via CLI flags.
+ */
+export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>> {
+  const { storageRoot } = args;
+  mkdirSync(storageRoot, { recursive: true });
+
+  const configPath = getConfigPath(storageRoot);
+  const envPath = getEnvPath(storageRoot);
+
+  const existing = loadExistingConfig(configPath);
+  const merged = mergeConfig(existing, args);
+
+  writeFileSync(configPath, stringify(merged, { indent: 2 }), "utf8");
+
+  // Write API key to .env
+  const envName = apiKeyEnvName(args.provider);
+  const envData = loadEnvFile(envPath);
+  envData[envName] = args.apiKey;
+  saveEnvFile(envPath, envData);
+
+  return {
+    configPath,
+    envPath,
+    provider: args.provider,
+    model: args.model,
+    defaultAgent: merged.defaultAgent,
+  };
+}
+
+/** Read a line with terminal echo disabled (for secrets). */
+async function promptSecret(label: string): Promise<string> {
+  process.stdout.write(label);
+  return new Promise((resolve) => {
+    const rawWasSet = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    let buf = "";
+    const onData = (chunk: string) => {
+      for (const c of chunk.toString()) {
+        if (c === "\n" || c === "\r" || c === "\u0004") {
+          if (process.stdin.isTTY) process.stdin.setRawMode(rawWasSet);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          resolve(buf.trim());
+          return;
+        }
+        if (c === "\u007F" || c === "\b") {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (c === "\u0003") {
+          if (process.stdin.isTTY) process.stdin.setRawMode(rawWasSet);
+          process.exit(130);
+        }
+        buf += c;
+        process.stdout.write("*");
+      }
+    };
+    process.stdin.on("data", onData);
+  });
+}
+
+/** Fetch available models from an OpenAI-compatible /models endpoint. */
+async function fetchModels(baseUrl: string, apiKey: string): Promise<string[]> {
+  try {
+    const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return [];
+    const body = (await res.json()) as { data?: { id: string }[] };
+    if (!Array.isArray(body.data)) return [];
+    const NON_CHAT = /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|gui-/i;
+    return body.data.map((m) => m.id).filter((id) => !NON_CHAT.test(id)).sort();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Interactive setup — prompts user for provider, API key, model.
+ */
+export async function cmdSetupInteractive(storageRoot: string): Promise<Record<string, unknown>> {
+  const rl = createInterface({ input, output });
+
+  try {
+    console.log("Configure LLM provider for uwf workflow agents.\n");
+
+    // 1. Provider selection
+    const numWidth = String(PRESET_PROVIDERS.length + 1).length;
+    console.log("Select a provider:\n");
+    for (let i = 0; i < PRESET_PROVIDERS.length; i++) {
+      const p = PRESET_PROVIDERS[i];
+      if (!p) continue;
+      const num = String(i + 1).padStart(numWidth);
+      console.log(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
+    }
+    const customNum = String(PRESET_PROVIDERS.length + 1).padStart(numWidth);
+    console.log(`  ${customNum}) Custom (enter name and URL manually)\n`);
+
+    const choice = (await rl.question(`Choose [1-${PRESET_PROVIDERS.length + 1}]: `)).trim();
+    const choiceNum = Number.parseInt(choice, 10);
+    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > PRESET_PROVIDERS.length + 1) {
+      throw new Error(`Invalid choice: ${choice}`);
+    }
+
+    let providerName: string;
+    let baseUrl: string;
+
+    if (choiceNum <= PRESET_PROVIDERS.length) {
+      const selected = PRESET_PROVIDERS[choiceNum - 1];
+      if (!selected) throw new Error("Invalid selection");
+      providerName = selected.name;
+      baseUrl = selected.baseUrl;
+      console.log(`\n  → ${selected.label} (${selected.baseUrl})\n`);
+    } else {
+      providerName = (await rl.question("Provider name (e.g. my-proxy): ")).trim();
+      if (!providerName) throw new Error("Provider name required");
+      baseUrl = (await rl.question("OpenAI-compatible API base URL: ")).trim();
+      if (!baseUrl) throw new Error("Base URL required");
+    }
+
+    // 2. API key
+    rl.close();
+    const apiKey = await promptSecret("API key: ");
+    if (!apiKey) throw new Error("API key required");
+
+    // 3. Model selection
+    const rl2 = createInterface({ input, output });
+    console.log("\nFetching available models...");
+    const models = await fetchModels(baseUrl, apiKey);
+
+    let model: string;
+    if (models.length > 0) {
+      console.log(`\nAvailable models (${models.length}):\n`);
+      const nw = String(models.length).length;
+      // Multi-column layout
+      const maxLen = models.reduce((m, s) => Math.max(m, s.length), 0);
+      const colWidth = nw + 2 + maxLen + 4; // "  N) name    "
+      const termCols = process.stdout.columns || 100;
+      const cols = Math.max(1, Math.floor(termCols / colWidth));
+      const rows = Math.ceil(models.length / cols);
+      for (let r = 0; r < rows; r++) {
+        let line = "";
+        for (let c = 0; c < cols; c++) {
+          const idx = c * rows + r;
+          if (idx >= models.length) break;
+          const num = String(idx + 1).padStart(nw);
+          const name = (models[idx] ?? "").padEnd(maxLen);
+          line += `  ${num}) ${name}  `;
+        }
+        console.log(line.trimEnd());
+      }
+      console.log(`\nChoose a number, or type a model name directly.`);
+      const modelInput = (await rl2.question(`Default model [1-${models.length}]: `)).trim();
+      if (!modelInput) throw new Error("Model required");
+      const modelNum = Number.parseInt(modelInput, 10);
+      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+        model = models[modelNum - 1] ?? modelInput;
+      } else {
+        model = modelInput;
+      }
+    } else {
+      console.log("Could not fetch models. Enter model name manually.");
+      model = (await rl2.question("Default model (e.g. qwen-plus, gpt-4o): ")).trim();
+      if (!model) throw new Error("Model required");
+    }
+
+    rl2.close();
+
+    console.log(`  → ${providerName}/${model}\n`);
+
+    await cmdSetup({
+      provider: providerName,
+      baseUrl,
+      apiKey,
+      model,
+      storageRoot,
+    });
+
+    console.log("Setup complete! Get started:\n");
+    console.log("  uwf workflow put <workflow.yaml>   Register a workflow");
+    console.log('  uwf thread start <name> -p "..."   Start a thread');
+    console.log("  uwf thread step <thread-id>        Execute next step");
+    console.log("");
+
+    return null as unknown as Record<string, unknown>;
+  } finally {
+    rl.close();
+  }
+}

packages/cli-uwf/src/commands/thread.ts

@@ -0,0 +1,465 @@
+import { execFileSync } from "node:child_process";
+
+import { validate } from "@uncaged/json-cas";
+import { getEnvPath, loadWorkflowConfig } from "@uncaged/uwf-agent-kit";
+import { evaluate } from "@uncaged/uwf-moderator";
+import type {
+  AgentAlias,
+  AgentConfig,
+  CasRef,
+  ModeratorContext,
+  StartNodePayload,
+  StartOutput,
+  StepContext,
+  StepNodePayload,
+  StepOutput,
+  ThreadId,
+  ThreadListItem,
+  WorkflowConfig,
+  WorkflowPayload,
+} from "@uncaged/uwf-protocol";
+import { generateUlid } from "@uncaged/workflow-util";
+import { config as loadDotenv } from "dotenv";
+
+import {
+  appendThreadHistory,
+  createUwfStore,
+  findThreadInHistory,
+  loadThreadHistory,
+  loadThreadsIndex,
+  loadWorkflowRegistry,
+  resolveWorkflowHash,
+  saveThreadsIndex,
+  type ThreadHistoryLine,
+  type UwfStore,
+} from "../store.js";
+import { isCasRef } from "../validate.js";
+
+const END_ROLE = "$END";
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+export type KillOutput = {
+  thread: ThreadId;
+  archived: boolean;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+async function resolveWorkflowCasRef(
+  uwf: UwfStore,
+  storageRoot: string,
+  workflowId: string,
+): Promise<CasRef> {
+  const registry = await loadWorkflowRegistry(storageRoot);
+  const hash = resolveWorkflowHash(registry, workflowId);
+  if (!isCasRef(hash)) {
+    fail(`workflow not found: ${workflowId}`);
+  }
+  const node = uwf.store.get(hash);
+  if (node === null) {
+    fail(`CAS node not found: ${hash}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${hash} is not a Workflow (type ${node.type})`);
+  }
+  return hash;
+}
+
+function resolveWorkflowFromHead(uwf: UwfStore, head: CasRef): CasRef | null {
+  const node = uwf.store.get(head);
+  if (node === null) {
+    return null;
+  }
+
+  if (node.type === uwf.schemas.startNode) {
+    const payload = node.payload as StartNodePayload;
+    return payload.workflow;
+  }
+
+  const payload = node.payload as StepNodePayload;
+  if (typeof payload.start !== "string") {
+    return null;
+  }
+
+  const startNode = uwf.store.get(payload.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    return null;
+  }
+
+  return (startNode.payload as StartNodePayload).workflow;
+}
+
+export async function cmdThreadStart(
+  storageRoot: string,
+  workflowId: string,
+  prompt: string,
+): Promise<StartOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId);
+
+  const threadId = generateUlid(Date.now()) as ThreadId;
+  const startPayload: StartNodePayload = {
+    workflow: workflowHash,
+    prompt,
+  };
+
+  const headHash = await uwf.store.put(uwf.schemas.startNode, startPayload);
+  const node = uwf.store.get(headHash);
+  if (node === null || !validate(uwf.store, node)) {
+    fail("stored StartNode failed schema validation");
+  }
+
+  const index = await loadThreadsIndex(storageRoot);
+  index[threadId] = headHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return { workflow: workflowHash, thread: threadId };
+}
+
+export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    const uwf = await createUwfStore(storageRoot);
+    const workflow = resolveWorkflowFromHead(uwf, activeHead);
+    if (workflow === null) {
+      fail(`failed to resolve workflow from head: ${activeHead}`);
+    }
+    return {
+      workflow,
+      thread: threadId,
+      head: activeHead,
+      done: false,
+    };
+  }
+
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return {
+      workflow: hist.workflow,
+      thread: threadId,
+      head: hist.head,
+      done: true,
+    };
+  }
+
+  fail(`thread not found: ${threadId}`);
+}
+
+async function threadListItemFromActive(
+  uwf: UwfStore,
+  threadId: ThreadId,
+  head: CasRef,
+): Promise<ThreadListItem | null> {
+  const workflow = resolveWorkflowFromHead(uwf, head);
+  if (workflow === null) {
+    return null;
+  }
+  return { thread: threadId, workflow, head };
+}
+
+export async function cmdThreadList(
+  storageRoot: string,
+  includeAll: boolean,
+): Promise<ThreadListItem[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const index = await loadThreadsIndex(storageRoot);
+  const items: ThreadListItem[] = [];
+
+  for (const [threadId, head] of Object.entries(index)) {
+    const item = await threadListItemFromActive(uwf, threadId as ThreadId, head);
+    if (item !== null) {
+      items.push(item);
+    }
+  }
+
+  if (!includeAll) {
+    return items;
+  }
+
+  const activeIds = new Set(items.map((i) => i.thread));
+  const history = await loadThreadHistory(storageRoot);
+  for (const entry of history) {
+    if (!activeIds.has(entry.thread)) {
+      items.push({
+        thread: entry.thread,
+        workflow: entry.workflow,
+        head: entry.head,
+      });
+    }
+  }
+
+  return items;
+}
+
+function walkChain(uwf: UwfStore, headHash: CasRef): ChainState {
+  const headNode = uwf.store.get(headHash);
+  if (headNode === null) {
+    fail(`CAS node not found: ${headHash}`);
+  }
+
+  if (headNode.type === uwf.schemas.startNode) {
+    return {
+      startHash: headHash,
+      start: headNode.payload as StartNodePayload,
+      stepsNewestFirst: [],
+      headIsStart: true,
+    };
+  }
+
+  if (headNode.type !== uwf.schemas.stepNode) {
+    fail(`head ${headHash} is not a StartNode or StepNode`);
+  }
+
+  const stepsNewestFirst: StepNodePayload[] = [];
+  let hash: CasRef | null = headHash;
+
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null) {
+      fail(`CAS node not found while walking chain: ${hash}`);
+    }
+    if (node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    stepsNewestFirst.push(payload);
+    hash = payload.prev;
+  }
+
+  const newest = stepsNewestFirst[0];
+  if (newest === undefined) {
+    fail(`empty step chain at head ${headHash}`);
+  }
+
+  const startNode = uwf.store.get(newest.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    fail(`StartNode not found: ${newest.start}`);
+  }
+
+  return {
+    startHash: newest.start,
+    start: startNode.payload as StartNodePayload,
+    stepsNewestFirst,
+    headIsStart: false,
+  };
+}
+
+function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
+  const node = uwf.store.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorContext {
+  const chronological = [...chain.stepsNewestFirst].reverse();
+  const steps: StepContext[] = chronological.map((step) => ({
+    role: step.role,
+    output: expandOutput(uwf, step.output),
+    detail: step.detail,
+    agent: step.agent,
+  }));
+  return { start: chain.start, steps };
+}
+
+function loadWorkflowPayload(uwf: UwfStore, workflowRef: CasRef): WorkflowPayload {
+  const node = uwf.store.get(workflowRef);
+  if (node === null) {
+    fail(`workflow CAS node not found: ${workflowRef}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${workflowRef} is not a Workflow`);
+  }
+  return node.payload as WorkflowPayload;
+}
+
+function parseAgentOverride(override: string): AgentConfig {
+  const parts = override
+    .trim()
+    .split(/\s+/)
+    .filter((p) => p.length > 0);
+  const command = parts[0];
+  if (command === undefined) {
+    fail("agent override must not be empty");
+  }
+  return { command, args: parts.slice(1) };
+}
+
+function resolveAgentConfig(
+  config: WorkflowConfig,
+  workflow: WorkflowPayload,
+  role: string,
+  agentOverride: string | null,
+): AgentConfig {
+  if (agentOverride !== null) {
+    return parseAgentOverride(agentOverride);
+  }
+
+  let alias: AgentAlias = config.defaultAgent;
+  if (config.agentOverrides !== null) {
+    const roleOverrides = config.agentOverrides[workflow.name];
+    if (roleOverrides !== undefined && roleOverrides[role] !== undefined) {
+      alias = roleOverrides[role];
+    }
+  }
+
+  const agentConfig = config.agents[alias];
+  if (agentConfig === undefined) {
+    fail(`unknown agent alias in config: ${alias}`);
+  }
+  return agentConfig;
+}
+
+function spawnAgent(agent: AgentConfig, threadId: ThreadId, role: string): CasRef {
+  const argv = [...agent.args, threadId, role];
+  let stdout: string;
+  try {
+    stdout = execFileSync(agent.command, argv, {
+      encoding: "utf8",
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string };
+    const stderr =
+      err.stderr === undefined
+        ? ""
+        : typeof err.stderr === "string"
+          ? err.stderr
+          : err.stderr.toString("utf8");
+    const detail = stderr.trim() !== "" ? `: ${stderr.trim()}` : "";
+    fail(`agent command failed (${agent.command})${detail}`);
+  }
+
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  if (!isCasRef(line)) {
+    fail(`agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  }
+  return line;
+}
+
+async function archiveThread(
+  storageRoot: string,
+  threadId: ThreadId,
+  workflow: CasRef,
+  head: CasRef,
+): Promise<void> {
+  const index = await loadThreadsIndex(storageRoot);
+  delete index[threadId];
+  await saveThreadsIndex(storageRoot, index);
+  await appendThreadHistory(storageRoot, {
+    thread: threadId,
+    workflow,
+    head,
+    completedAt: Date.now(),
+  });
+}
+
+export async function cmdThreadStep(
+  storageRoot: string,
+  threadId: ThreadId,
+  agentOverride: string | null,
+): Promise<StepOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+  const workflowHash = chain.start.workflow;
+  const workflow = loadWorkflowPayload(uwf, workflowHash);
+  const context = buildModeratorContext(uwf, chain);
+
+  const nextResult = await evaluate(workflow, context);
+  if (!nextResult.ok) {
+    fail(nextResult.error.message);
+  }
+
+  if (nextResult.value === END_ROLE) {
+    await archiveThread(storageRoot, threadId, workflowHash, headHash);
+    return {
+      workflow: workflowHash,
+      thread: threadId,
+      head: headHash,
+      done: true,
+    };
+  }
+
+  const role = nextResult.value;
+  const config = await loadWorkflowConfig(storageRoot);
+  const agent = resolveAgentConfig(config, workflow, role, agentOverride);
+
+  loadDotenv({ path: getEnvPath(storageRoot) });
+  const newHead = spawnAgent(agent, threadId, role);
+
+  // Re-create store to pick up nodes written by the agent subprocess
+  const uwfAfter = await createUwfStore(storageRoot);
+  const newNode = uwfAfter.store.get(newHead);
+  if (newNode === null || newNode.type !== uwfAfter.schemas.stepNode) {
+    fail(`agent returned hash that is not a StepNode: ${newHead}`);
+  }
+
+  // Reload threads index to avoid overwriting changes made by the agent subprocess
+  const freshIndex = await loadThreadsIndex(storageRoot);
+  freshIndex[threadId] = newHead;
+  await saveThreadsIndex(storageRoot, freshIndex);
+
+  const chainAfter = walkChain(uwfAfter, newHead);
+  const contextAfter = buildModeratorContext(uwfAfter, chainAfter);
+  const afterResult = await evaluate(workflow, contextAfter);
+  if (!afterResult.ok) {
+    fail(afterResult.error.message);
+  }
+
+  const done = afterResult.value === END_ROLE;
+  if (done) {
+    await archiveThread(storageRoot, threadId, workflowHash, newHead);
+  }
+
+  return {
+    workflow: workflowHash,
+    thread: threadId,
+    head: newHead,
+    done,
+  };
+}
+
+export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Promise<KillOutput> {
+  const index = await loadThreadsIndex(storageRoot);
+  const head = index[threadId];
+  if (head === undefined) {
+    fail(`thread not active: ${threadId}`);
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const workflow = resolveWorkflowFromHead(uwf, head);
+  if (workflow === null) {
+    fail(`failed to resolve workflow from head: ${head}`);
+  }
+
+  delete index[threadId];
+  await saveThreadsIndex(storageRoot, index);
+
+  const historyEntry: ThreadHistoryLine = {
+    thread: threadId,
+    workflow,
+    head,
+    completedAt: Date.now(),
+  };
+  await appendThreadHistory(storageRoot, historyEntry);
+
+  return { thread: threadId, archived: true };
+}

packages/cli-uwf/src/commands/workflow.ts

@@ -0,0 +1,153 @@
+import { readFile } from "node:fs/promises";
+
+import type { JSONSchema } from "@uncaged/json-cas";
+import { putSchema, validate } from "@uncaged/json-cas";
+import type { CasRef, RoleDefinition, WorkflowPayload } from "@uncaged/uwf-protocol";
+import { parse } from "yaml";
+
+import {
+  createUwfStore,
+  findRegistryName,
+  loadWorkflowRegistry,
+  resolveWorkflowHash,
+  saveWorkflowRegistry,
+  type UwfStore,
+} from "../store.js";
+import { parseWorkflowPayload } from "../validate.js";
+
+export type WorkflowListEntry = {
+  name: string;
+  hash: CasRef;
+};
+
+export type WorkflowPutOutput = {
+  name: string;
+  hash: CasRef;
+};
+
+export type WorkflowShowOutput = {
+  hash: CasRef;
+  name: string | null;
+  type: CasRef;
+  payload: WorkflowPayload;
+  timestamp: number;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function isJsonSchema(value: unknown): value is JSONSchema {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function resolveOutputSchemaRef(
+  uwf: UwfStore,
+  roleName: string,
+  outputSchema: unknown,
+): Promise<CasRef> {
+  if (!isJsonSchema(outputSchema)) {
+    fail(`role "${roleName}": outputSchema must be a JSON Schema object`);
+  }
+  const schema: JSONSchema = outputSchema.title === undefined
+    ? { ...outputSchema, title: roleName }
+    : outputSchema;
+  return putSchema(uwf.store, schema);
+}
+
+async function materializeWorkflowPayload(
+  uwf: UwfStore,
+  raw: WorkflowPayload,
+): Promise<WorkflowPayload> {
+  const roles: Record<string, RoleDefinition> = {};
+  for (const [roleName, role] of Object.entries(raw.roles)) {
+    const outputSchema = await resolveOutputSchemaRef(
+      uwf,
+      `${raw.name}.${roleName}`,
+      role.outputSchema,
+    );
+    roles[roleName] = {
+      description: role.description,
+      systemPrompt: role.systemPrompt,
+      outputSchema,
+    };
+  }
+  return {
+    name: raw.name,
+    description: raw.description,
+    roles,
+    conditions: raw.conditions,
+    graph: raw.graph,
+  };
+}
+
+export async function cmdWorkflowPut(
+  storageRoot: string,
+  filePath: string,
+): Promise<WorkflowPutOutput> {
+  let text: string;
+  try {
+    text = await readFile(filePath, "utf8");
+  } catch {
+    fail(`file not found: ${filePath}`);
+  }
+
+  let raw: unknown;
+  try {
+    raw = parse(text) as unknown;
+  } catch (e) {
+    fail(`invalid YAML: ${e instanceof Error ? e.message : String(e)}`);
+  }
+
+  const payload = parseWorkflowPayload(raw);
+  if (payload === null) {
+    fail("invalid workflow YAML: expected WorkflowPayload shape");
+  }
+
+  const uwf = await createUwfStore(storageRoot);
+  const materialized = await materializeWorkflowPayload(uwf, payload);
+
+  const hash = await uwf.store.put(uwf.schemas.workflow, materialized);
+  const node = uwf.store.get(hash);
+  if (node === null || !validate(uwf.store, node)) {
+    fail("stored workflow failed schema validation");
+  }
+
+  const registry = await loadWorkflowRegistry(storageRoot);
+  registry[materialized.name] = hash;
+  await saveWorkflowRegistry(storageRoot, registry);
+
+  return { name: materialized.name, hash };
+}
+
+export async function cmdWorkflowShow(
+  storageRoot: string,
+  id: string,
+): Promise<WorkflowShowOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const registry = await loadWorkflowRegistry(storageRoot);
+  const hash = resolveWorkflowHash(registry, id);
+
+  const node = uwf.store.get(hash);
+  if (node === null) {
+    fail(`CAS node not found: ${hash}`);
+  }
+  if (node.type !== uwf.schemas.workflow) {
+    fail(`node ${hash} is not a Workflow (type ${node.type})`);
+  }
+
+  const payload = node.payload as WorkflowPayload;
+  return {
+    hash,
+    name: findRegistryName(registry, hash),
+    type: node.type,
+    payload,
+    timestamp: node.timestamp,
+  };
+}
+
+export async function cmdWorkflowList(storageRoot: string): Promise<WorkflowListEntry[]> {
+  const registry = await loadWorkflowRegistry(storageRoot);
+  return Object.entries(registry).map(([name, hash]) => ({ name, hash }));
+}

packages/cli-uwf/src/format.ts

@@ -0,0 +1,12 @@
+import { stringify } from "yaml";
+
+export type OutputFormat = "json" | "yaml";
+
+export function formatOutput(data: unknown, format: OutputFormat): string {
+  switch (format) {
+    case "json":
+      return JSON.stringify(data);
+    case "yaml":
+      return stringify(data).trimEnd();
+  }
+}

packages/cli-uwf/src/schemas.ts

@@ -0,0 +1,26 @@
+import type { Hash, Store } from "@uncaged/json-cas";
+import { putSchema } from "@uncaged/json-cas";
+import {
+  START_NODE_SCHEMA,
+  STEP_NODE_SCHEMA,
+  WORKFLOW_SCHEMA,
+} from "@uncaged/uwf-protocol";
+
+export type UwfSchemaHashes = {
+  workflow: Hash;
+  startNode: Hash;
+  stepNode: Hash;
+};
+
+/**
+ * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
+ * Idempotent: safe to call on every CLI invocation.
+ */
+export async function registerUwfSchemas(store: Store): Promise<UwfSchemaHashes> {
+  const [workflow, startNode, stepNode] = await Promise.all([
+    putSchema(store, WORKFLOW_SCHEMA),
+    putSchema(store, START_NODE_SCHEMA),
+    putSchema(store, STEP_NODE_SCHEMA),
+  ]);
+  return { workflow, startNode, stepNode };
+}

packages/cli-uwf/src/store.ts

@@ -0,0 +1,212 @@
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { Hash, Store } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, ThreadId, ThreadListItem, ThreadsIndex } from "@uncaged/uwf-protocol";
+import { parse, stringify } from "yaml";
+
+import { registerUwfSchemas, type UwfSchemaHashes } from "./schemas.js";
+
+export type WorkflowRegistry = Record<string, CasRef>;
+
+/** Default filesystem root for uwf data (`~/.uncaged/workflow`). */
+export function getDefaultStorageRoot(): string {
+  return join(homedir(), ".uncaged", "workflow");
+}
+
+/**
+ * Resolve storage root.
+ * Priority: `UNCAGED_WORKFLOW_STORAGE_ROOT` → `WORKFLOW_STORAGE_ROOT` → default.
+ */
+export function resolveStorageRoot(): string {
+  const internal = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+  if (internal !== undefined && internal !== "") {
+    return internal;
+  }
+  const userOverride = process.env.WORKFLOW_STORAGE_ROOT;
+  if (userOverride !== undefined && userOverride !== "") {
+    return userOverride;
+  }
+  return getDefaultStorageRoot();
+}
+
+export function getCasDir(storageRoot: string): string {
+  return join(storageRoot, "cas");
+}
+
+export function getRegistryPath(storageRoot: string): string {
+  return join(storageRoot, "workflows.yaml");
+}
+
+export function getThreadsPath(storageRoot: string): string {
+  return join(storageRoot, "threads.yaml");
+}
+
+export function getHistoryPath(storageRoot: string): string {
+  return join(storageRoot, "history.jsonl");
+}
+
+export type ThreadHistoryLine = ThreadListItem & {
+  completedAt: number;
+};
+
+export type UwfStore = {
+  storageRoot: string;
+  store: Store;
+  schemas: UwfSchemaHashes;
+};
+
+export async function createUwfStore(storageRoot: string): Promise<UwfStore> {
+  const casDir = getCasDir(storageRoot);
+  await mkdir(casDir, { recursive: true });
+  const store = createFsStore(casDir);
+  const schemas = await registerUwfSchemas(store);
+  return { storageRoot, store, schemas };
+}
+
+export async function loadWorkflowRegistry(storageRoot: string): Promise<WorkflowRegistry> {
+  const path = getRegistryPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = parse(text) as unknown;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return {};
+    }
+    const registry: WorkflowRegistry = {};
+    for (const [name, hash] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof hash === "string") {
+        registry[name] = hash;
+      }
+    }
+    return registry;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+export async function saveWorkflowRegistry(
+  storageRoot: string,
+  registry: WorkflowRegistry,
+): Promise<void> {
+  const path = getRegistryPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const text = stringify(registry, { indent: 2 });
+  await writeFile(path, text, "utf8");
+}
+
+export function resolveWorkflowHash(registry: WorkflowRegistry, id: string): CasRef {
+  return registry[id] !== undefined ? registry[id] : id;
+}
+
+export function findRegistryName(registry: WorkflowRegistry, hash: Hash): string | null {
+  for (const [name, h] of Object.entries(registry)) {
+    if (h === hash) {
+      return name;
+    }
+  }
+  return null;
+}
+
+export async function loadThreadsIndex(storageRoot: string): Promise<ThreadsIndex> {
+  const path = getThreadsPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const raw = parse(text) as unknown;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      return {};
+    }
+    const index: ThreadsIndex = {};
+    for (const [threadId, head] of Object.entries(raw as Record<string, unknown>)) {
+      if (typeof head === "string") {
+        index[threadId as ThreadId] = head;
+      }
+    }
+    return index;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return {};
+    }
+    throw e;
+  }
+}
+
+export async function saveThreadsIndex(storageRoot: string, index: ThreadsIndex): Promise<void> {
+  const path = getThreadsPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const text = stringify(index, { indent: 2 });
+  await writeFile(path, text, "utf8");
+}
+
+export async function loadThreadHistory(storageRoot: string): Promise<ThreadHistoryLine[]> {
+  const path = getHistoryPath(storageRoot);
+  try {
+    const text = await readFile(path, "utf8");
+    const lines: ThreadHistoryLine[] = [];
+    for (const line of text.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed === "") {
+        continue;
+      }
+      let raw: unknown;
+      try {
+        raw = JSON.parse(trimmed) as unknown;
+      } catch {
+        continue;
+      }
+      if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        continue;
+      }
+      const rec = raw as Record<string, unknown>;
+      const thread = rec.thread;
+      const workflow = rec.workflow;
+      const head = rec.head;
+      const completedAt = rec.completedAt;
+      if (
+        typeof thread === "string" &&
+        typeof workflow === "string" &&
+        typeof head === "string" &&
+        typeof completedAt === "number"
+      ) {
+        lines.push({ thread: thread as ThreadId, workflow, head, completedAt });
+      }
+    }
+    return lines;
+  } catch (e) {
+    const err = e as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw e;
+  }
+}
+
+export async function findThreadInHistory(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadHistoryLine | null> {
+  const history = await loadThreadHistory(storageRoot);
+  for (let i = history.length - 1; i >= 0; i--) {
+    const entry = history[i];
+    if (entry !== undefined && entry.thread === threadId) {
+      return entry;
+    }
+  }
+  return null;
+}
+
+export async function appendThreadHistory(
+  storageRoot: string,
+  entry: ThreadHistoryLine,
+): Promise<void> {
+  const path = getHistoryPath(storageRoot);
+  await mkdir(storageRoot, { recursive: true });
+  const line = `${JSON.stringify(entry)}\n`;
+  await appendFile(path, line, "utf8");
+}

packages/cli-uwf/src/validate.ts

@@ -0,0 +1,71 @@
+import type { CasRef, WorkflowPayload } from "@uncaged/uwf-protocol";
+
+const CAS_REF_PATTERN = /^[0-9A-HJKMNP-TV-Z]{13}$/;
+
+export function isCasRef(value: string): value is CasRef {
+  return CAS_REF_PATTERN.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isRoleDefinition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const outputSchema = value.outputSchema;
+  const schemaOk = isRecord(outputSchema) && typeof outputSchema.type === "string";
+  return (
+    typeof value.description === "string" && typeof value.systemPrompt === "string" && schemaOk
+  );
+}
+
+function isConditionDefinition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return typeof value.description === "string" && typeof value.expression === "string";
+}
+
+function isTransition(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const condition = value.condition;
+  return typeof value.role === "string" && (condition === null || typeof condition === "string");
+}
+
+function isStringRecord(value: unknown, itemCheck: (item: unknown) => boolean): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every(itemCheck);
+}
+
+function isGraph(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  return Object.values(value).every(
+    (transitions) => Array.isArray(transitions) && transitions.every((t) => isTransition(t)),
+  );
+}
+
+/** Validate YAML-parsed workflow document shape (outputSchema may be inline JSON Schema). */
+export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  if (typeof raw.name !== "string" || typeof raw.description !== "string") {
+    return null;
+  }
+  if (
+    !isStringRecord(raw.roles, isRoleDefinition) ||
+    !isStringRecord(raw.conditions, isConditionDefinition) ||
+    !isGraph(raw.graph)
+  ) {
+    return null;
+  }
+  return raw as WorkflowPayload;
+}

packages/cli-uwf/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../uwf-protocol" },
+    { "path": "../uwf-moderator" },
+    { "path": "../uwf-agent-kit" }
+  ]
+}

packages/cli-workflow/CHANGELOG.md

@@ -0,0 +1,138 @@
+# @uncaged/cli-workflow
+
+## 0.5.0-alpha.4
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f74b482]
+- Updated dependencies [f74b482]
+  - @uncaged/workflow-util@0.5.0-alpha.4
+  - @uncaged/workflow-protocol@0.5.0-alpha.4
+  - @uncaged/workflow-cas@0.5.0-alpha.4
+  - @uncaged/workflow-execute@0.5.0-alpha.4
+  - @uncaged/workflow-gateway@0.5.0-alpha.4
+  - @uncaged/workflow-register@0.5.0-alpha.4
+  - @uncaged/workflow-runtime@0.5.0-alpha.4
+
+## 0.5.0-alpha.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.3
+  - @uncaged/workflow-cas@0.5.0-alpha.3
+  - @uncaged/workflow-execute@0.5.0-alpha.3
+  - @uncaged/workflow-gateway@0.5.0-alpha.3
+  - @uncaged/workflow-register@0.5.0-alpha.3
+  - @uncaged/workflow-runtime@0.5.0-alpha.3
+  - @uncaged/workflow-util@0.5.0-alpha.3
+
+## 0.5.0-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.2
+  - @uncaged/workflow-cas@0.5.0-alpha.2
+  - @uncaged/workflow-execute@0.5.0-alpha.2
+  - @uncaged/workflow-gateway@0.5.0-alpha.2
+  - @uncaged/workflow-register@0.5.0-alpha.2
+  - @uncaged/workflow-runtime@0.5.0-alpha.2
+  - @uncaged/workflow-util@0.5.0-alpha.2
+
+## 0.5.0-alpha.1
+
+### Patch Changes
+
+- @uncaged/workflow-cas@0.5.0-alpha.1
+- @uncaged/workflow-execute@0.5.0-alpha.1
+- @uncaged/workflow-gateway@0.5.0-alpha.1
+- @uncaged/workflow-protocol@0.5.0-alpha.1
+- @uncaged/workflow-register@0.5.0-alpha.1
+- @uncaged/workflow-runtime@0.5.0-alpha.1
+- @uncaged/workflow-util@0.5.0-alpha.1
+
+## 0.5.0-alpha.0
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.5.0-alpha.0
+  - @uncaged/workflow-cas@0.5.0-alpha.0
+  - @uncaged/workflow-execute@0.5.0-alpha.0
+  - @uncaged/workflow-register@0.5.0-alpha.0
+  - @uncaged/workflow-runtime@0.5.0-alpha.0
+  - @uncaged/workflow-util@0.5.0-alpha.0
+  - @uncaged/workflow-gateway@0.5.0-alpha.0
+
+## 0.4.5
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.4.5
+  - @uncaged/workflow-cas@0.4.5
+  - @uncaged/workflow-execute@0.4.5
+  - @uncaged/workflow-gateway@0.4.5
+  - @uncaged/workflow-register@0.4.5
+  - @uncaged/workflow-runtime@0.4.5
+  - @uncaged/workflow-util@0.4.5
+
+## 0.4.4
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-protocol@0.4.4
+  - @uncaged/workflow-cas@0.4.4
+  - @uncaged/workflow-execute@0.4.4
+  - @uncaged/workflow-gateway@0.4.4
+  - @uncaged/workflow-register@0.4.4
+  - @uncaged/workflow-runtime@0.4.4
+  - @uncaged/workflow-util@0.4.4
+
+## 0.4.3
+
+### Patch Changes
+
+- Include src/ in published packages so bun runtime can resolve the 'bun' exports condition.
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.3
+  - @uncaged/workflow-execute@0.4.3
+  - @uncaged/workflow-gateway@0.4.3
+  - @uncaged/workflow-protocol@0.4.3
+  - @uncaged/workflow-register@0.4.3
+  - @uncaged/workflow-runtime@0.4.3
+  - @uncaged/workflow-util@0.4.3
+
+## 0.4.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution: use workspace:^ so published packages resolve to compatible versions instead of exact (non-existent) versions.
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.2
+  - @uncaged/workflow-execute@0.4.2
+  - @uncaged/workflow-gateway@0.4.2
+  - @uncaged/workflow-protocol@0.4.2
+  - @uncaged/workflow-register@0.4.2
+  - @uncaged/workflow-runtime@0.4.2
+  - @uncaged/workflow-util@0.4.2
+
+## 0.4.0
+
+### Minor Changes
+
+- Fix package exports for published packages and adopt changesets for version management.
+
+### Patch Changes
+
+- Updated dependencies
+  - @uncaged/workflow-cas@0.4.0
+  - @uncaged/workflow-execute@0.4.0
+  - @uncaged/workflow-gateway@0.4.0
+  - @uncaged/workflow-protocol@0.4.0
+  - @uncaged/workflow-register@0.4.0
+  - @uncaged/workflow-runtime@0.4.0
+  - @uncaged/workflow-util@0.4.0

packages/cli-workflow/__tests__/commands.test.ts

@@ -2,14 +2,9 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-
-import {
-  createContentMerkleNode,
-  getGlobalCasDir,
-  getRegisteredWorkflow,
-  readWorkflowRegistry,
-  serializeMerkleNode,
-} from "@uncaged/workflow";
+import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow-cas";
+import { getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow-register";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "../src/commands/cas/index.js";
 import {
   cmdAdd,
@@ -22,10 +17,7 @@ import {
 } from "../src/commands/workflow/index.js";
 import { addCliArgs } from "./bundle-fixture.js";
 
-const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {} };
-`;
-
-const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow";
+const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {}, graph: { edges: [] } };
 `;
 
 function casStoredForm(raw: string): string {
@@ -57,12 +49,12 @@ describe("cli workflow commands", () => {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}import fs from "node:fs";
+      `${fixtureDescriptor}import fs from "node:fs";
 
 export const run = async function* (input, options) {
   fs.existsSync(".");
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, input.prompt);
+  const h = await cas.put(input.prompt);
   yield { role: "noop", contentHash: h, meta: { done: true }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 }
@@ -158,11 +150,11 @@ export const run = async function* (input) { return { returnCode: 0, summary: in
       schema: { type: "object", properties: { greeting: { type: "string" } } },
     },
   },
+  graph: { edges: [] },
 };
-${wfPutImport}
 export const run = async function* (input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, input.prompt);
+  const h = await cas.put( input.prompt);
   yield { role: "greeter", contentHash: h, meta: { greeting: "hi" }, refs: [h] };
   return { returnCode: 0, summary: "ok" };
 };
@@ -201,9 +193,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -232,9 +224,9 @@ export const run = async function* (input, options) {
     const dtsPath = join(bundleDir, "types.d.ts");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -265,9 +257,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -288,16 +280,16 @@ export const run = async function* (input, options) {
     const bundleDir = join(storageRoot, "src");
     await mkdir(bundleDir, { recursive: true });
     const bundlePath = join(bundleDir, "demo.esm.js");
-    const v1 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v1 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v1");
+  const h = await cas.put( "v1");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v1" };
 }
 `;
-    const v2 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v2 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v2");
+  const h = await cas.put( "v2");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v2" };
 }
@@ -330,16 +322,16 @@ export const run = async function* (input, options) {
     const bundleDir = join(storageRoot, "src");
     await mkdir(bundleDir, { recursive: true });
     const bundlePath = join(bundleDir, "demo.esm.js");
-    const v1 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v1 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v1");
+  const h = await cas.put( "v1");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v1" };
 }
 `;
-    const v2 = `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+    const v2 = `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "v2");
+  const h = await cas.put( "v2");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "v2" };
 }
@@ -382,9 +374,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -395,9 +387,9 @@ export const run = async function* (input, options) {
     expect(add1.ok).toBe(true);
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "y");
+  const h = await cas.put( "y");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "y" };
 }
@@ -450,9 +442,9 @@ export const run = async function* (input, options) {
     const bundlePath = join(bundleDir, "demo.esm.js");
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "x" };
 }
@@ -467,9 +459,9 @@ export const run = async function* (input, options) {
     const hash1 = add1.value.hash;
     await writeFile(
       bundlePath,
-      `${fixtureDescriptor}${wfPutImport}export const run = async function* (_input, options) {
+      `${fixtureDescriptor}export const run = async function* (_input, options) {
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "y");
+  const h = await cas.put( "y");
   yield { role: "a", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "y" };
 }

packages/cli-workflow/__tests__/connect.test.ts

@@ -1,15 +1,15 @@
 import { describe, expect, test } from "bun:test";
 
-import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow";
+import { createContentMerkleNode, serializeMerkleNode } from "@uncaged/workflow-cas";
 
-import { createApp } from "../src/commands/serve/app.js";
+import { createApp } from "../src/commands/connect/app.js";
 
 function casStoredForm(raw: string): string {
   return serializeMerkleNode(createContentMerkleNode(raw));
 }
 
 function buildApp(storageRoot: string) {
-  const app = createApp(storageRoot);
+  const app = createApp(storageRoot, null);
   return {
     fetch: (path: string, init?: RequestInit) =>
       app.fetch(new Request(`http://localhost${path}`, init)),
@@ -77,6 +77,83 @@ describe("serve /api/cas", () => {
   });
 });
 
+describe("serve error handling", () => {
+  test("POST /api/threads with invalid JSON body → 400", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/threads", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "not json",
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid JSON body");
+  });
+
+  test("POST /api/cas with invalid JSON body → 400", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/cas", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: "not json",
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("invalid JSON body");
+  });
+
+  test("POST /api/threads with missing required fields → 400", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const res = await fetch("/api/threads", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ foo: "bar" }),
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain("required");
+  });
+
+  test("global error handler returns 500 with JSON", async () => {
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
+    app.get("/test-error", () => {
+      throw new Error("boom");
+    });
+    const res = await app.fetch(new Request("http://localhost/test-error"));
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("Internal server error");
+  });
+});
+
+describe("serve security", () => {
+  test("CORS headers present on responses", async () => {
+    const app = createApp("/tmp/uncaged-serve-test-nonexistent", null);
+    const res2 = await app.fetch(
+      new Request("http://localhost/healthz", {
+        headers: { Origin: "http://localhost:5173" },
+      }),
+    );
+    expect(res2.headers.get("Access-Control-Allow-Origin")).toBe("http://localhost:5173");
+  });
+
+  test("POST with body > 1MB → 413", async () => {
+    const { fetch } = buildApp("/tmp/uncaged-serve-test-nonexistent");
+    const largeBody = "x".repeat(1_048_577);
+    const res = await fetch("/api/cas", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": String(largeBody.length),
+      },
+      body: largeBody,
+    });
+    expect(res.status).toBe(413);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("Payload too large");
+  });
+});
+
 describe("serve CAS round-trip", () => {
   const tmpDir = `/tmp/uncaged-serve-cas-test-${Date.now()}`;
 

packages/cli-workflow/__tests__/fork-cli.test.ts

@@ -1,66 +1,49 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createCasStore, getContentMerklePayload, getGlobalCasDir } from "@uncaged/workflow";
+import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
+import { FORK_BRANCH_ROLE, walkStateFramesNewestFirst } from "@uncaged/workflow-execute";
+import { END } from "@uncaged/workflow-runtime";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
+
 import { cmdFork, cmdRun } from "../src/commands/thread/index.js";
 import { cmdAdd } from "../src/commands/workflow/index.js";
 import { pathExists } from "../src/fs-utils.js";
+import { resolveThreadRecord } from "../src/thread-scan.js";
 import { addCliArgs } from "./bundle-fixture.js";
 import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
 /** Three-role workflow that respects `input.steps` for fork/resume. */
-const threeRoleBundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
-
-export const descriptor = {
+const threeRoleBundleSource = `export const descriptor = {
   description: "fork-cli",
   roles: {
     planner: { description: "planner", schema: {} },
     coder: { description: "coder", schema: {} },
     reviewer: { description: "reviewer", schema: {} },
   },
+  graph: { edges: [] },
 };
 export const run = async function* (input, options) {
   const cas = options.cas;
   const has = (r) => input.steps.some((s) => s.role === r);
   if (!has("planner")) {
-    const h = await putContentMerkleNode(cas, "p1");
+    const h = await cas.put( "p1");
     yield { role: "planner", contentHash: h, meta: { k: "planner" }, refs: [h] };
   }
   if (!has("coder")) {
-    const h = await putContentMerkleNode(cas, "c1");
+    const h = await cas.put( "c1");
     yield { role: "coder", contentHash: h, meta: { k: "coder" }, refs: [h] };
   }
   if (!has("reviewer")) {
     const body = "rev-" + String(input.steps.length);
-    const h = await putContentMerkleNode(cas, body);
+    const h = await cas.put( body);
     yield { role: "reviewer", contentHash: h, meta: { k: "reviewer" }, refs: [h] };
   }
   return { returnCode: 0, summary: "done" };
 };
 `;
 
-async function countDataJsonlLines(dataPath: string): Promise<number> {
-  try {
-    const text = await readFile(dataPath, "utf8");
-    return text
-      .trim()
-      .split("\n")
-      .filter((l) => l !== "").length;
-  } catch {
-    return 0;
-  }
-}
-
-async function waitUntilMinDataLines(dataPath: string, minLines: number): Promise<void> {
-  for (let attempt = 0; attempt < 120; attempt++) {
-    if ((await countDataJsonlLines(dataPath)) >= minLines) {
-      return;
-    }
-    await new Promise((r) => setTimeout(r, 25));
-  }
-}
-
 async function waitUntilRunningAbsent(runningPath: string): Promise<void> {
   for (let attempt = 0; attempt < 120; attempt++) {
     if (!(await pathExists(runningPath))) {
@@ -70,6 +53,41 @@ async function waitUntilRunningAbsent(runningPath: string): Promise<void> {
   }
 }
 
+async function waitUntilThreadCompletes(storageRoot: string, threadId: string): Promise<void> {
+  for (let attempt = 0; attempt < 120; attempt++) {
+    const row = await resolveThreadRecord(storageRoot, threadId);
+    if (row?.source === "history") {
+      return;
+    }
+    await new Promise((r) => setTimeout(r, 25));
+  }
+}
+
+async function listMeaningfulRoleContents(
+  storageRoot: string,
+  threadId: string,
+): Promise<Array<{ role: string; content: string }>> {
+  const row = await resolveThreadRecord(storageRoot, threadId);
+  if (row === null) {
+    return [];
+  }
+  const cas = createCasStore(getGlobalCasDir(storageRoot));
+  const frames = await walkStateFramesNewestFirst(cas, row.head);
+  const chronological = [...frames].reverse();
+  const out: Array<{ role: string; content: string }> = [];
+  for (const fr of chronological) {
+    if (fr.payload.role === END || fr.payload.role === FORK_BRANCH_ROLE) {
+      continue;
+    }
+    const content = await getContentMerklePayload(cas, fr.payload.content);
+    out.push({
+      role: fr.payload.role,
+      content: content ?? "",
+    });
+  }
+  return out;
+}
+
 describe("cli fork", () => {
   let prevEnv: string | undefined;
   let storageRoot: string;
@@ -109,10 +127,12 @@ describe("cli fork", () => {
       return;
     }
     const sourceId = ran.value.threadId;
-    const sourceData = join(storageRoot, "logs", hash, `${sourceId}.data.jsonl`);
     const sourceRunning = join(storageRoot, "logs", hash, `${sourceId}.running`);
     await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilThreadCompletes(storageRoot, sourceId);
+
+    const histBefore = await resolveThreadRecord(storageRoot, sourceId);
+    expect(histBefore?.source).toBe("history");
 
     const forked = await cmdFork(storageRoot, sourceId, "planner");
     expect(forked.ok).toBe(true);
@@ -120,25 +140,18 @@ describe("cli fork", () => {
       return;
     }
     const newId = forked.value.threadId;
-    const newData = join(storageRoot, "logs", hash, `${newId}.data.jsonl`);
     const newRunning = join(storageRoot, "logs", hash, `${newId}.running`);
     await waitUntilRunningAbsent(newRunning);
-    await waitUntilMinDataLines(newData, 5);
+    await waitUntilThreadCompletes(storageRoot, newId);
 
-    const text = await readFile(newData, "utf8");
-    const lines = text
-      .trim()
-      .split("\n")
-      .filter((l) => l !== "");
-    expect(lines.length).toBe(5);
-    const start = JSON.parse(lines[0] ?? "{}") as Record<string, unknown>;
-    expect(start.threadId).toBe(newId);
-    expect(start.forkFrom).toEqual({ threadId: sourceId });
+    const forkHist = await resolveThreadRecord(storageRoot, newId);
+    expect(forkHist?.source).toBe("history");
+    expect(forkHist?.start).toBe(histBefore?.start);
 
-    const lastRoleLine = JSON.parse(lines[lines.length - 2] ?? "{}") as Record<string, unknown>;
-    expect(lastRoleLine.role).toBe("reviewer");
-    const cas = createCasStore(getGlobalCasDir(storageRoot));
-    expect(await getContentMerklePayload(cas, String(lastRoleLine.contentHash))).toBe("rev-1");
+    const steps = await listMeaningfulRoleContents(storageRoot, newId);
+    const tail = steps[steps.length - 1];
+    expect(tail?.role).toBe("reviewer");
+    expect(tail?.content).toBe("rev-1");
   });
 
   test("fork without --from-role retries last role", async () => {
@@ -160,10 +173,8 @@ describe("cli fork", () => {
       return;
     }
     const sourceId = ran.value.threadId;
-    const sourceData = join(storageRoot, "logs", hash, `${sourceId}.data.jsonl`);
-    const sourceRunning = join(storageRoot, "logs", hash, `${sourceId}.running`);
-    await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilRunningAbsent(join(storageRoot, "logs", hash, `${sourceId}.running`));
+    await waitUntilThreadCompletes(storageRoot, sourceId);
 
     const forked = await cmdFork(storageRoot, sourceId, null);
     expect(forked.ok).toBe(true);
@@ -171,26 +182,17 @@ describe("cli fork", () => {
       return;
     }
     const newId = forked.value.threadId;
-    const newData = join(storageRoot, "logs", hash, `${newId}.data.jsonl`);
-    const newRunning = join(storageRoot, "logs", hash, `${newId}.running`);
-    await waitUntilRunningAbsent(newRunning);
-    await waitUntilMinDataLines(newData, 5);
+    await waitUntilRunningAbsent(join(storageRoot, "logs", hash, `${newId}.running`));
+    await waitUntilThreadCompletes(storageRoot, newId);
 
-    const text = await readFile(newData, "utf8");
-    const lines = text
-      .trim()
-      .split("\n")
-      .filter((l) => l !== "");
-    expect(lines.length).toBe(5);
-
-    const replayCoder = JSON.parse(lines[2] ?? "{}") as Record<string, unknown>;
-    expect(replayCoder.role).toBe("coder");
-    const cas = createCasStore(getGlobalCasDir(storageRoot));
-    expect(await getContentMerklePayload(cas, String(replayCoder.contentHash))).toBe("c1");
-
-    const lastRoleLine = JSON.parse(lines[lines.length - 2] ?? "{}") as Record<string, unknown>;
-    expect(lastRoleLine.role).toBe("reviewer");
-    expect(await getContentMerklePayload(cas, String(lastRoleLine.contentHash))).toBe("rev-2");
+    const steps = await listMeaningfulRoleContents(storageRoot, newId);
+    expect(steps.length).toBeGreaterThanOrEqual(3);
+    const coderReplay = steps[steps.length - 2];
+    expect(coderReplay?.role).toBe("coder");
+    expect(coderReplay?.content).toBe("c1");
+    const tail = steps[steps.length - 1];
+    expect(tail?.role).toBe("reviewer");
+    expect(tail?.content).toBe("rev-2");
   });
 
   test("fork rejects unknown role with available names", async () => {
@@ -211,10 +213,10 @@ describe("cli fork", () => {
       return;
     }
     const sourceId = ran.value.threadId;
-    const sourceData = join(storageRoot, "logs", added.value.hash, `${sourceId}.data.jsonl`);
-    const sourceRunning = join(storageRoot, "logs", added.value.hash, `${sourceId}.running`);
-    await waitUntilRunningAbsent(sourceRunning);
-    await waitUntilMinDataLines(sourceData, 5);
+    await waitUntilRunningAbsent(
+      join(storageRoot, "logs", added.value.hash, `${sourceId}.running`),
+    );
+    await waitUntilThreadCompletes(storageRoot, sourceId);
 
     const bad = await cmdFork(storageRoot, sourceId, "ghost-role");
     expect(bad.ok).toBe(false);

packages/cli-workflow/__tests__/gc-cli.test.ts

@@ -1,48 +1,17 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import {
-  createCasStore,
-  garbageCollectCas,
-  getGlobalCasDir,
-  putContentMerkleNode,
-} from "@uncaged/workflow";
+import { createCasStore, putStartNode } from "@uncaged/workflow-cas";
+import { garbageCollectCas, getBundleDir, upsertThreadEntry } from "@uncaged/workflow-execute";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 import { cmdThreadRemove } from "../src/commands/thread/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
 
-async function writeDemoDataJsonl(params: {
-  path: string;
-  threadId: string;
-  bundleHash: string;
-  cas: ReturnType<typeof createCasStore>;
-  activeHash: string;
-}): Promise<void> {
-  const bodyHash = await putContentMerkleNode(params.cas, "p");
-  const text = [
-    JSON.stringify({
-      name: "demo",
-      hash: params.bundleHash,
-      threadId: params.threadId,
-      parameters: { prompt: "hi", options: { maxRounds: 5 } },
-      timestamp: 100,
-    }),
-    JSON.stringify({
-      role: "planner",
-      contentHash: bodyHash,
-      meta: {},
-      refs: [params.activeHash, bodyHash],
-      timestamp: 101,
-    }),
-    "",
-  ].join("\n");
-  await writeFile(params.path, text, "utf8");
-}
-
 describe("gc cli and garbageCollectCas", () => {
   let prevEnv: string | undefined;
   let storageRoot: string;
@@ -62,22 +31,30 @@ describe("gc cli and garbageCollectCas", () => {
     await rm(storageRoot, { recursive: true, force: true });
   });
 
-  test("garbageCollectCas keeps CAS entries referenced by thread refs", async () => {
+  test("garbageCollectCas keeps CAS entries reachable from threads.json roots", async () => {
     const bundleHash = "C9NMV6V2TQT81";
     const threadId = "01AAA1111111111111111111";
-    const logsDir = join(storageRoot, "logs", bundleHash);
-    await mkdir(logsDir, { recursive: true });
+    const bundleDir = getBundleDir(storageRoot, bundleHash);
+    await mkdir(bundleDir, { recursive: true });
 
     const cas = createCasStore(getGlobalCasDir(storageRoot));
-    const activeHash = await cas.put("active-blob");
     const orphanHash = await cas.put("orphan-blob");
-
-    await writeDemoDataJsonl({
-      path: join(logsDir, `${threadId}.data.jsonl`),
-      threadId,
-      bundleHash,
+    const promptHash = await cas.put("prompt-text");
+    const startHash = await putStartNode(
       cas,
-      activeHash,
+      {
+        name: "demo",
+        hash: bundleHash,
+        depth: 0,
+        parentState: null,
+      },
+      promptHash,
+    );
+
+    await upsertThreadEntry(bundleDir, threadId, {
+      head: startHash,
+      start: startHash,
+      updatedAt: 100,
     });
 
     const gc = await garbageCollectCas(storageRoot);
@@ -85,12 +62,12 @@ describe("gc cli and garbageCollectCas", () => {
     if (!gc.ok) {
       return;
     }
-    expect(gc.value.scannedThreads).toBe(1);
-    expect(gc.value.activeRefs).toBe(2);
+    expect(gc.value.scannedThreads).toBe(2);
     expect(gc.value.deletedEntries).toBe(1);
     expect(gc.value.deletedHashes).toEqual([orphanHash]);
 
-    expect(await pathExists(join(getGlobalCasDir(storageRoot), `${activeHash}.txt`))).toBe(true);
+    expect(await pathExists(join(getGlobalCasDir(storageRoot), `${promptHash}.txt`))).toBe(true);
+    expect(await pathExists(join(getGlobalCasDir(storageRoot), `${startHash}.txt`))).toBe(true);
     expect(await pathExists(join(getGlobalCasDir(storageRoot), `${orphanHash}.txt`))).toBe(false);
   });
 
@@ -113,19 +90,27 @@ describe("gc cli and garbageCollectCas", () => {
   test("cli gc prints stats", async () => {
     const bundleHash = "C9NMV6V2TQT81";
     const threadId = "01BBB2222222222222222222";
-    const logsDir = join(storageRoot, "logs", bundleHash);
-    await mkdir(logsDir, { recursive: true });
+    const bundleDir = getBundleDir(storageRoot, bundleHash);
+    await mkdir(bundleDir, { recursive: true });
 
     const cas = createCasStore(getGlobalCasDir(storageRoot));
-    const activeHash = await cas.put("keep-me");
+    const promptHash = await cas.put("prompt-text");
+    const startHash = await putStartNode(
+      cas,
+      {
+        name: "demo",
+        hash: bundleHash,
+        depth: 0,
+        parentState: null,
+      },
+      promptHash,
+    );
     await cas.put("drop-me");
 
-    await writeDemoDataJsonl({
-      path: join(logsDir, `${threadId}.data.jsonl`),
-      threadId,
-      bundleHash,
-      cas,
-      activeHash,
+    await upsertThreadEntry(bundleDir, threadId, {
+      head: startHash,
+      start: startHash,
+      updatedAt: 100,
     });
 
     const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
@@ -134,23 +119,32 @@ describe("gc cli and garbageCollectCas", () => {
       encoding: "utf8",
     });
     expect(proc.status).toBe(0);
-    expect(String(proc.stdout).trim()).toBe("scanned 1 threads, 2 active refs, deleted 1 entries");
+    expect(String(proc.stdout).trim()).toBe("scanned 2 threads, 2 active refs, deleted 1 entries");
   });
 
   test("thread rm triggers gc so unreferenced CAS is removed", async () => {
     const bundleHash = "C9NMV6V2TQT81";
     const threadId = "01CCC3333333333333333333";
-    const logsDir = join(storageRoot, "logs", bundleHash);
-    await mkdir(logsDir, { recursive: true });
+    const bundleDir = getBundleDir(storageRoot, bundleHash);
+    await mkdir(bundleDir, { recursive: true });
 
     const cas = createCasStore(getGlobalCasDir(storageRoot));
-    const activeHash = await cas.put("pinned-by-ref");
-    await writeDemoDataJsonl({
-      path: join(logsDir, `${threadId}.data.jsonl`),
-      threadId,
-      bundleHash,
+    const promptHash = await cas.put("prompt-text");
+    const startHash = await putStartNode(
       cas,
-      activeHash,
+      {
+        name: "demo",
+        hash: bundleHash,
+        depth: 0,
+        parentState: null,
+      },
+      promptHash,
+    );
+
+    await upsertThreadEntry(bundleDir, threadId, {
+      head: startHash,
+      start: startHash,
+      updatedAt: 100,
     });
 
     const orphanHash = await cas.put("orphan-after-rm");
@@ -160,6 +154,6 @@ describe("gc cli and garbageCollectCas", () => {
     expect(removed.ok).toBe(true);
 
     expect(await pathExists(orphanPath)).toBe(false);
-    expect(await pathExists(join(getGlobalCasDir(storageRoot), `${activeHash}.txt`))).toBe(false);
+    expect(await pathExists(join(getGlobalCasDir(storageRoot), `${promptHash}.txt`))).toBe(false);
   });
 });

packages/cli-workflow/__tests__/help.test.ts

@@ -58,6 +58,11 @@ describe("--help flag on groups", () => {
     const code = await runCli(STORAGE_ROOT, ["init", "--help"]);
     expect(code).toBe(0);
   });
+
+  test("setup --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["setup", "--help"]);
+    expect(code).toBe(0);
+  });
 });
 
 describe("getSkillTopics", () => {
@@ -90,6 +95,8 @@ describe("formatCliUsage", () => {
     expect(u).toContain("Thread execution:");
     expect(u).toContain("Content-addressable storage:");
     expect(u).toContain("Development:");
+    expect(u).toContain("Configuration:");
+    expect(u).toContain("setup [--provider <name>]");
     expect(u).toContain("Shortcuts:");
     expect(u).toContain("Reference:");
     expect(u).toContain("skill [topic]");
@@ -128,6 +135,7 @@ describe("formatSkillTopic('cli')", () => {
     expect(doc).toContain("### thread");
     expect(doc).toContain("### cas");
     expect(doc).toContain("### init");
+    expect(doc).toContain("### setup");
     expect(doc).toContain("### Top-level shortcuts");
   });
 

packages/cli-workflow/__tests__/init-template.test.ts

@@ -50,7 +50,6 @@ describe("init template", () => {
       dependencies: Record<string, string>;
     };
     expect(pkg.type).toBe("module");
-    expect(pkg.dependencies["@uncaged/workflow"]).toBeDefined();
     expect(pkg.dependencies["@uncaged/workflow-runtime"]).toBeDefined();
     expect(pkg.dependencies.zod).toBeDefined();
     expect(pkg.name).toContain("review-pr");
@@ -65,6 +64,7 @@ describe("init template", () => {
 
     const moder = await readFile(join(tdir, "src", "moderator.ts"), "utf8");
     expect(moder).not.toContain("export default");
+    expect(moder).toContain("ModeratorTable");
   });
 
   test("finds workspace walking up from nested cwd", async () => {

packages/cli-workflow/__tests__/init-workspace.test.ts

@@ -38,15 +38,23 @@ describe("init workspace", () => {
 
     const rootPkg = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
       workspaces: string[];
+      scripts: { bundle: string };
     };
     expect(rootPkg.workspaces).toEqual(["templates/*", "workflows"]);
+    expect(rootPkg.scripts.bundle).toBe("bun run scripts/bundle.ts");
+
+    expect(await pathExists(join(root, "scripts", "bundle.ts"))).toBe(true);
+    const bundleSrc = await readFile(join(root, "scripts", "bundle.ts"), "utf8");
+    expect(bundleSrc).toContain("Bun.build");
+    expect(bundleSrc).toContain("-entry.ts");
+    expect(bundleSrc).toContain("distDir");
 
     const wfPkg = JSON.parse(await readFile(join(root, "workflows", "package.json"), "utf8")) as {
       type: string;
       dependencies: Record<string, string>;
     };
     expect(wfPkg.type).toBe("module");
-    expect(wfPkg.dependencies["@uncaged/workflow"]).toBeDefined();
+    expect(wfPkg.dependencies["@uncaged/workflow-runtime"]).toBeDefined();
     expect(wfPkg.dependencies.zod).toBeDefined();
 
     const tsconfig = JSON.parse(await readFile(join(root, "tsconfig.json"), "utf8")) as {
@@ -82,8 +90,8 @@ describe("init workspace", () => {
     for (const term of [
       "RoleDefinition",
       "WorkflowDefinition",
-      "Moderator",
-      "AgentFn",
+      "ModeratorTable",
+      "AdapterFn",
       "ExtractFn",
       "RoleMeta",
     ]) {
@@ -117,9 +125,6 @@ describe("init workspace", () => {
   });
 
   test("errors on invalid workspace name", async () => {
-    const slash = await cmdInitWorkspace(parent, "a/b");
-    expect(slash.ok).toBe(false);
-
     const dots = await cmdInitWorkspace(parent, "..");
     expect(dots.ok).toBe(false);
 
@@ -127,6 +132,14 @@ describe("init workspace", () => {
     expect(empty.ok).toBe(false);
   });
 
+  test("accepts nested path as workspace name", async () => {
+    const nested = await cmdInitWorkspace(parent, "a/b");
+    expect(nested.ok).toBe(true);
+    if (nested.ok) {
+      expect(nested.value.rootPath).toContain("a/b");
+    }
+  });
+
   test("usage lists init subcommands", () => {
     const u = formatCliUsage();
     expect(u).toContain("init workspace <name>");

packages/cli-workflow/__tests__/live.test.ts

@@ -1,12 +1,10 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { spawn, spawnSync } from "node:child_process";
-import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { createCasStore, getGlobalCasDir, putContentMerkleNode } from "@uncaged/workflow";
-
 import {
   formatLiveDebugLine,
   formatLiveTimeLabel,
@@ -17,11 +15,6 @@ import {
 import { parseLiveArgv } from "../src/live-argv.js";
 
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
-const fixtureRoot = fileURLToPath(new URL("./fixtures/live", import.meta.url));
-
-/** Bodies for Merkle content nodes; hashes must match `.data.jsonl` fixtures. */
-const LIVE_FIXTURE_PLANNER_BODY =
-  "alpha\nbeta\ngamma\nLINE4\nLINE5\nLINE6\nLINE7\nLINE8\nLINE9\nLINE10\nLINE11";
 
 describe("live helpers", () => {
   test("formatLiveTimeLabel pads HH:MM:SS", () => {
@@ -85,28 +78,6 @@ describe("live CLI", () => {
     prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
     storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-live-"));
     process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
-    await mkdir(join(storageRoot, "logs", "C9NMV6V2TQT81"), { recursive: true });
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.data.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.info.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVECMPLT01DDDDDDDDDDDDG.info.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl"),
-    );
-    await cp(
-      join(fixtureRoot, "logs", "C9NMV6V2TQT81", "01LIVEOLDER01DDDDDDDDDDDDG.data.jsonl"),
-      join(storageRoot, "logs", "C9NMV6V2TQT81", "01LIVEOLDER01DDDDDDDDDDDDG.data.jsonl"),
-    );
-
-    const cas = createCasStore(getGlobalCasDir(storageRoot));
-    await putContentMerkleNode(cas, LIVE_FIXTURE_PLANNER_BODY);
-    await putContentMerkleNode(cas, "patch");
-    await putContentMerkleNode(cas, "still running");
   });
 
   afterEach(async () => {
@@ -118,170 +89,6 @@ describe("live CLI", () => {
     await rm(storageRoot, { recursive: true, force: true });
   });
 
-  test("prints role steps and summary for a completed thread", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).toContain("coder");
-    expect(stdout).toContain("meta:");
-    expect(stdout).toContain('"phase":"plan"');
-    expect(stdout).toContain("LINE10");
-    expect(stdout).not.toContain("LINE11");
-    expect(stdout).toContain("more line");
-    expect(stdout).toContain("completed: returnCode=0");
-    expect(stdout).toContain("fixture completed");
-  });
-
-  test("--latest tails the newest thread by start timestamp", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "--latest"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("fixture completed");
-    expect(stdout).not.toContain("older thread");
-  });
-
-  test("--debug prints .info.jsonl records after data output", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG", "--debug"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("[DEBUGTAG1]");
-    expect(stdout).toContain("bundle loaded");
-    expect(stdout).toContain("[DEBUGTAG2]");
-    expect(stdout).toContain("multi line");
-  });
-
-  test("--role filters out non-matching roles", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "01LIVECMPLT01DDDDDDDDDDDDG", "--role", "planner"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).not.toContain("patch");
-    expect(stdout).toContain("completed: returnCode=0");
-  });
-
-  test("--latest --debug --role combine", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const proc = spawn(
-      process.execPath,
-      [cliEntryPath, "live", "--latest", "--debug", "--role", "planner"],
-      {
-        env,
-        stdio: ["ignore", "pipe", "pipe"],
-      },
-    );
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("[DEBUGTAG1]");
-    expect(stdout).toContain("planner");
-    expect(stdout).not.toContain("patch");
-    expect(stdout).toContain("fixture completed");
-  });
-
   test("unknown thread id exits 1", () => {
     const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
     const r = spawnSync(process.execPath, [cliEntryPath, "live", "01UNKNOWNXXXXXXXXXXXXXXXXX"], {
@@ -291,51 +98,6 @@ describe("live CLI", () => {
     expect(r.status).toBe(1);
     expect(String(r.stderr ?? "")).toContain("thread not found");
   });
-
-  test("follows file until WorkflowResult is appended", async () => {
-    const env = { ...process.env, UNCAGED_WORKFLOW_STORAGE_ROOT: storageRoot };
-    const dataPath = join(
-      storageRoot,
-      "logs",
-      "C9NMV6V2TQT81",
-      "01LIVEINFLY01DDDDDDDDDDDDG.data.jsonl",
-    );
-
-    const proc = spawn(process.execPath, [cliEntryPath, "live", "01LIVEINFLY01DDDDDDDDDDDDG"], {
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    await new Promise((r) => setTimeout(r, 120));
-    const prior = await readFile(dataPath, "utf8");
-    await writeFile(
-      dataPath,
-      `${prior.replace(/\s*$/, "")}\n${JSON.stringify({ returnCode: 0, summary: "caught up" })}\n`,
-      "utf8",
-    );
-
-    const stdout = await new Promise<string>((resolve, reject) => {
-      let buf = "";
-      proc.stdout?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.stderr?.on("data", (c: Buffer) => {
-        buf += c.toString("utf8");
-      });
-      proc.on("error", reject);
-      proc.on("exit", (code: number | null) => {
-        if (code === 0) {
-          resolve(buf);
-        } else {
-          reject(new Error(`exit ${code}: ${buf}`));
-        }
-      });
-    });
-
-    expect(stdout).toContain("planner");
-    expect(stdout).toContain("completed: returnCode=0");
-    expect(stdout).toContain("caught up");
-  });
 });
 
 describe("live --latest with empty storage", () => {

packages/cli-workflow/__tests__/setup-cli.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readWorkflowRegistry } from "@uncaged/workflow-register";
+
+import { runCli } from "../src/cli-dispatch.js";
+import { cmdSetup } from "../src/commands/setup/index.js";
+
+describe("setup command (CLI mode)", () => {
+  let prevEnv: string | undefined;
+  let storageRoot: string;
+
+  beforeEach(async () => {
+    prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    storageRoot = await mkdtemp(join(tmpdir(), "uncaged-setup-"));
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await mkdir(storageRoot, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (prevEnv === undefined) {
+      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = prevEnv;
+    }
+    await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  test("writes workflow.yaml with provider, models.default, and depth defaults", async () => {
+    const r = await cmdSetup(storageRoot, {
+      provider: "dashscope",
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-test123",
+      defaultModel: "dashscope/qwen-plus",
+      initWorkspaceName: null,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok) {
+      return;
+    }
+    expect(reg.value.config).not.toBeNull();
+    if (reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.dashscope).toEqual({
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-test123",
+    });
+    expect(reg.value.config.models.default).toBe("dashscope/qwen-plus");
+    expect(reg.value.config.maxDepth).toBe(3);
+    expect(reg.value.config.supervisorInterval).toBe(3);
+
+    const raw = await readFile(join(storageRoot, "workflow.yaml"), "utf8");
+    expect(raw).toContain("dashscope");
+    expect(raw).toContain("qwen-plus");
+  });
+
+  test("idempotent: second run updates apiKey and preserves workflows", async () => {
+    const initialYaml = `config:
+  maxDepth: 7
+  supervisorInterval: 2
+  providers:
+    dashscope:
+      baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+      apiKey: sk-old
+  models:
+    default: dashscope/qwen-plus
+workflows:
+  keep-me:
+    hash: "0000000000000"
+    timestamp: 1
+    history: []
+`;
+    await writeFile(join(storageRoot, "workflow.yaml"), initialYaml, "utf8");
+
+    const r2 = await cmdSetup(storageRoot, {
+      provider: "dashscope",
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-newkey",
+      defaultModel: "dashscope/qwen-plus",
+      initWorkspaceName: null,
+    });
+    expect(r2.ok).toBe(true);
+    if (!r2.ok) {
+      return;
+    }
+
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok || reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.dashscope.apiKey).toBe("sk-newkey");
+    expect(reg.value.config.maxDepth).toBe(7);
+    expect(reg.value.config.supervisorInterval).toBe(2);
+    expect(reg.value.workflows["keep-me"]).toBeDefined();
+    if (reg.value.workflows["keep-me"] === undefined) {
+      return;
+    }
+    expect(reg.value.workflows["keep-me"].hash).toBe("0000000000000");
+  });
+
+  test("runCli setup dispatches with flags and exits 0", async () => {
+    const code = await runCli(storageRoot, [
+      "setup",
+      "--provider",
+      "openai",
+      "--base-url",
+      "https://api.openai.com/v1",
+      "--api-key",
+      "sk-test",
+      "--default-model",
+      "openai/gpt-4o",
+    ]);
+    expect(code).toBe(0);
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok || reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.openai.apiKey).toBe("sk-test");
+    expect(reg.value.config.models.default).toBe("openai/gpt-4o");
+  });
+});

packages/cli-workflow/__tests__/storage-env.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow";
+import { getDefaultWorkflowStorageRoot } from "@uncaged/workflow-util";
 import { resolveWorkflowStorageRoot } from "../src/storage-env.js";
 
 describe("resolveWorkflowStorageRoot", () => {

packages/cli-workflow/__tests__/thread-cli.test.ts

@@ -1,10 +1,11 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { spawnSync } from "node:child_process";
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getGlobalCasDir } from "@uncaged/workflow";
+import { getBundleDir, readThreadsIndex } from "@uncaged/workflow-execute";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 import { cmdCasPut } from "../src/commands/cas/index.js";
 import {
   cmdKill,
@@ -18,12 +19,10 @@ import {
 } from "../src/commands/thread/index.js";
 import { cmdAdd } from "../src/commands/workflow/index.js";
 import { pathExists, readTextFileIfExists } from "../src/fs-utils.js";
+import { resolveThreadRecord } from "../src/thread-scan.js";
 import { addCliArgs } from "./bundle-fixture.js";
 import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
-const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow";
-`;
-
 const threadFixtureDescriptor = `export const descriptor = {
   description: "thread-cli",
   roles: {
@@ -34,29 +33,28 @@ const threadFixtureDescriptor = `export const descriptor = {
     only: { description: "only", schema: {} },
     noop: { description: "noop", schema: {} },
   },
+  graph: { edges: [] },
 };
 `;
 
 const fastBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  h = await putContentMerkleNode(cas, "code");
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const slowPlannerBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
   await new Promise((r) => setTimeout(r, 400));
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  h = await putContentMerkleNode(cas, "code");
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
@@ -65,70 +63,54 @@ export const run = async function* (input, options) {
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
 
 const abortablePlannerBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (input, options) {
-  await new Promise((r) => setTimeout(r, 600));
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "plan");
+  let h = await cas.put( "plan");
   yield { role: "planner", contentHash: h, meta: { plan: input.prompt }, refs: [h] };
-  h = await putContentMerkleNode(cas, "code");
+  await new Promise((r) => setTimeout(r, 10000));
+  h = await cas.put( "code");
   yield { role: "coder", contentHash: h, meta: { diff: "y" }, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const pauseResumeBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (_input, options) {
   const cas = options.cas;
-  let h = await putContentMerkleNode(cas, "f");
+  let h = await cas.put( "f");
   yield { role: "first", contentHash: h, meta: {}, refs: [h] };
   await new Promise((r) => setTimeout(r, 1500));
-  h = await putContentMerkleNode(cas, "s");
+  h = await cas.put( "s");
   yield { role: "second", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
 const delayedFirstYieldBundleSource = `${threadFixtureDescriptor}
-${wfPutImport}
 export const run = async function* (_input, options) {
   await new Promise((r) => setTimeout(r, 900));
   const cas = options.cas;
-  const h = await putContentMerkleNode(cas, "x");
+  const h = await cas.put( "x");
   yield { role: "only", contentHash: h, meta: {}, refs: [h] };
   return { returnCode: 0, summary: "done" };
 };
 `;
 
-async function countDataJsonlLines(dataPath: string): Promise<number> {
-  try {
-    const text = await readFile(dataPath, "utf8");
-    return text
-      .trim()
-      .split("\n")
-      .filter((l) => l !== "").length;
-  } catch {
-    return 0;
-  }
-}
-
-async function waitUntilMinDataLines(
-  dataPath: string,
-  minLines: number,
-  maxAttempts: number,
-): Promise<void> {
+async function waitUntilRunningFileAbsent(runningPath: string, maxAttempts: number): Promise<void> {
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    if ((await countDataJsonlLines(dataPath)) >= minLines) {
+    if (!(await pathExists(runningPath))) {
       return;
     }
     await new Promise((r) => setTimeout(r, 25));
   }
 }
 
-async function waitUntilRunningFileAbsent(runningPath: string, maxAttempts: number): Promise<void> {
+async function waitUntilPredicate(
+  predicate: () => Promise<boolean>,
+  maxAttempts: number,
+): Promise<void> {
   for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    if (!(await pathExists(runningPath))) {
+    if (await predicate()) {
       return;
     }
     await new Promise((r) => setTimeout(r, 25));
@@ -190,6 +172,9 @@ describe("cli thread commands", () => {
     }
     expect(threads.value.some((l) => l.includes(threadId))).toBe(true);
 
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
+    await waitUntilRunningFileAbsent(runningPath, 120);
+
     const shown = await cmdThreadShow(storageRoot, threadId);
     expect(shown.ok).toBe(true);
     if (!shown.ok) {
@@ -197,11 +182,18 @@ describe("cli thread commands", () => {
     }
     expect(shown.value.includes('"threadId"')).toBe(true);
 
+    const parsed = JSON.parse(shown.value) as Record<string, unknown>;
+    expect(parsed.parentState).toBeNull();
+    const parsedSteps = parsed.steps as Array<Record<string, unknown>>;
+    for (const step of parsedSteps) {
+      expect(step).toHaveProperty("childThread");
+      expect(step.childThread).toBeNull();
+    }
+
     const removed = await cmdThreadRemove(storageRoot, threadId);
     expect(removed.ok).toBe(true);
 
-    const dataPath = join(storageRoot, "logs", added.value.hash, `${threadId}.data.jsonl`);
-    expect(await pathExists(dataPath)).toBe(false);
+    expect(await resolveThreadRecord(storageRoot, threadId)).toBeNull();
   });
 
   test("thread rm runs GC and removes CAS blobs not referenced by any remaining thread", async () => {
@@ -234,9 +226,9 @@ describe("cli thread commands", () => {
       threads = await cmdThreads(storageRoot, []);
     }
 
-    const dataPath = join(storageRoot, "logs", added.value.hash, `${threadId}.data.jsonl`);
-    const runningPath = join(dirname(dataPath), `${threadId}.running`);
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
     await waitUntilRunningFileAbsent(runningPath, 120);
+    expect((await resolveThreadRecord(storageRoot, threadId))?.source).toBe("history");
 
     const put = await cmdCasPut(storageRoot, "keep-after-thread-rm");
     expect(put.ok).toBe(true);
@@ -317,30 +309,31 @@ describe("cli thread commands", () => {
     }
 
     const threadId = ran.value.threadId;
+    const killBundleDir = getBundleDir(storageRoot, added.value.hash);
 
-    await new Promise((r) => setTimeout(r, 50));
+    await waitUntilPredicate(async () => {
+      const idx = await readThreadsIndex(killBundleDir);
+      const ent = idx[threadId];
+      return ent !== undefined && ent.head !== ent.start;
+    }, 80);
 
     const killed = await cmdKill(storageRoot, threadId);
     expect(killed.ok).toBe(true);
 
-    await new Promise((r) => setTimeout(r, 900));
+    await waitUntilPredicate(async () => {
+      return (await resolveThreadRecord(storageRoot, threadId))?.source === "history";
+    }, 120);
 
-    const dataPath = join(storageRoot, "logs", added.value.hash, `${threadId}.data.jsonl`);
-    const text = await readFile(dataPath, "utf8");
-    const lines = text
-      .trim()
-      .split("\n")
-      .filter((l) => l !== "");
-    expect(lines.length).toBe(3);
+    expect((await resolveThreadRecord(storageRoot, threadId))?.source).toBe("history");
 
-    const runningPath = join(dirname(dataPath), `${threadId}.running`);
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
     expect(await pathExists(runningPath)).toBe(false);
   });
 
   test("pause stops between yields and resume completes thread", async () => {
-    const bundleDir = join(storageRoot, "src");
-    await mkdir(bundleDir, { recursive: true });
-    const bundlePath = join(bundleDir, "demo.esm.js");
+    const srcDir = join(storageRoot, "src");
+    await mkdir(srcDir, { recursive: true });
+    const bundlePath = join(srcDir, "demo.esm.js");
     await writeFile(bundlePath, pauseResumeBundleSource, "utf8");
 
     const added = await cmdAdd(storageRoot, addCliArgs("solve-issue", bundlePath));
@@ -356,24 +349,33 @@ describe("cli thread commands", () => {
     }
 
     const threadId = ran.value.threadId;
-    const dataPath = join(storageRoot, "logs", added.value.hash, `${threadId}.data.jsonl`);
+    const bundleDir = getBundleDir(storageRoot, added.value.hash);
 
-    await waitUntilMinDataLines(dataPath, 2, 80);
-    expect(await countDataJsonlLines(dataPath)).toBe(2);
+    await waitUntilPredicate(async () => {
+      const idx = await readThreadsIndex(bundleDir);
+      const ent = idx[threadId];
+      return ent !== undefined && ent.head !== ent.start;
+    }, 80);
+
+    const idxBeforePause = await readThreadsIndex(bundleDir);
+    const headAtPause = idxBeforePause[threadId]?.head;
 
     const paused = await cmdPause(storageRoot, threadId);
     expect(paused.ok).toBe(true);
 
     await new Promise((r) => setTimeout(r, 400));
-    expect(await countDataJsonlLines(dataPath)).toBe(2);
+    const idxPaused = await readThreadsIndex(bundleDir);
+    expect(idxPaused[threadId]?.head).toBe(headAtPause);
 
     const resumed = await cmdResume(storageRoot, threadId);
     expect(resumed.ok).toBe(true);
 
-    await waitUntilMinDataLines(dataPath, 4, 120);
-    expect(await countDataJsonlLines(dataPath)).toBe(4);
+    await waitUntilPredicate(async () => {
+      const row = await resolveThreadRecord(storageRoot, threadId);
+      return row?.source === "history";
+    }, 120);
 
-    const runningPath = join(dirname(dataPath), `${threadId}.running`);
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
     await waitUntilRunningFileAbsent(runningPath, 100);
     expect(await pathExists(runningPath)).toBe(false);
   });
@@ -397,8 +399,7 @@ describe("cli thread commands", () => {
     }
 
     const threadId = ran.value.threadId;
-    const dataPath = join(storageRoot, "logs", added.value.hash, `${threadId}.data.jsonl`);
-    const runningPath = join(dirname(dataPath), `${threadId}.running`);
+    const runningPath = join(storageRoot, "logs", added.value.hash, `${threadId}.running`);
 
     await waitUntilRunningFileAbsent(runningPath, 100);
     expect(await pathExists(runningPath)).toBe(false);

packages/cli-workflow/package.json

@@ -1,17 +1,30 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.2.0",
+  "version": "0.5.0-alpha.4",
+  "files": [
+    "src",
+    "dist",
+    "package.json"
+  ],
   "type": "module",
   "bin": {
     "uncaged-workflow": "src/cli.ts"
   },
   "dependencies": {
-    "@uncaged/workflow-runtime": "workspace:*",
-    "@uncaged/workflow": "workspace:*",
+    "@uncaged/workflow-gateway": "workspace:^",
+    "@uncaged/workflow-protocol": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^",
+    "@uncaged/workflow-cas": "workspace:^",
+    "@uncaged/workflow-execute": "workspace:^",
+    "@uncaged/workflow-register": "workspace:^",
+    "@uncaged/workflow-runtime": "workspace:^",
     "hono": "^4.12.18",
     "yaml": "^2.8.4"
   },
   "scripts": {
     "test": "bun test"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

packages/cli-workflow/pnpm-lock.yaml

@@ -0,0 +1,51 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@uncaged/workflow-cas':
+        specifier: workspace:*
+        version: link:../workflow-cas
+      '@uncaged/workflow-execute':
+        specifier: workspace:*
+        version: link:../workflow-execute
+      '@uncaged/workflow-protocol':
+        specifier: workspace:*
+        version: link:../workflow-protocol
+      '@uncaged/workflow-register':
+        specifier: workspace:*
+        version: link:../workflow-register
+      '@uncaged/workflow-runtime':
+        specifier: workspace:*
+        version: link:../workflow-runtime
+      '@uncaged/workflow-util':
+        specifier: workspace:*
+        version: link:../workflow-util
+      hono:
+        specifier: ^4.12.18
+        version: 4.12.18
+      yaml:
+        specifier: ^2.8.4
+        version: 2.8.4
+
+packages:
+
+  hono@4.12.18:
+    resolution: {integrity: sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==}
+    engines: {node: '>=16.9.0'}
+
+  yaml@2.8.4:
+    resolution: {integrity: sha512-ml/JPOj9fOQK8RNnWojA67GbZ0ApXAUlN2UQclwv2eVgTgn7O9gg9o7paZWKMp4g0H3nTLtS9LVzhkpOFIKzog==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+snapshots:
+
+  hono@4.12.18: {}
+
+  yaml@2.8.4: {}

packages/cli-workflow/src/bundle-store.ts

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { pathExists } from "./fs-utils.js";
 

packages/cli-workflow/src/cli-dispatch.ts

@@ -3,15 +3,13 @@ import { printCliError, printCliLine } from "./cli-output.js";
 import { getCommandRegistry } from "./cli-registry.js";
 import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
+import { dispatchConnect } from "./commands/connect/index.js";
 import { createInitDispatcher } from "./commands/init/index.js";
-import { dispatchServe } from "./commands/serve/index.js";
+import { dispatchSetup } from "./commands/setup/index.js";
 import { createThreadDispatcher, dispatchLive, dispatchRun } from "./commands/thread/index.js";
 import { createWorkflowDispatcher } from "./commands/workflow/index.js";
 import { formatSkillIndex, formatSkillTopic, getSkillTopics } from "./skill.js";
 
-export type { CommandEntry, CommandGroup, DispatchFn } from "./cli-command-types.js";
-export { getCommandRegistry } from "./cli-registry.js";
-
 function dispatchGroup(
   tableName: string,
   table: Record<string, CommandEntry>,
@@ -69,10 +67,11 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
+  setup: dispatchSetup,
   skill: dispatchSkill,
   run: dispatchRun,
   live: dispatchLive,
-  serve: dispatchServe,
+  connect: dispatchConnect,
 };
 
 export async function runCli(storageRoot: string, argv: string[]): Promise<number> {

packages/cli-workflow/src/cli-registry.ts

@@ -5,6 +5,15 @@ import { INIT_SUBCOMMAND_TABLE } from "./commands/init/index.js";
 import { THREAD_SUBCOMMAND_TABLE } from "./commands/thread/index.js";
 import { WORKFLOW_SUBCOMMAND_TABLE } from "./commands/workflow/index.js";
 
+const SETUP_USAGE_COMMANDS = [
+  {
+    name: "",
+    args: "[--provider <name>] [--base-url <url>] [--api-key <key>] [--default-model <provider/model>] [--init-workspace <name>]",
+    description:
+      "Configure workflow.yaml LLM providers and default model (interactive when no flags)",
+  },
+] as const;
+
 export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
   return [
     {
@@ -39,6 +48,10 @@ export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
         description: e.description,
       })),
     },
+    {
+      name: "setup",
+      commands: [...SETUP_USAGE_COMMANDS],
+    },
   ];
 }
 

packages/cli-workflow/src/cli-usage.ts

@@ -12,6 +12,7 @@ const USAGE_SECTION_BY_GROUP: Record<string, string> = {
   thread: "Thread execution:",
   cas: "Content-addressable storage:",
   init: "Development:",
+  setup: "Configuration:",
 };
 
 export function formatUsageCommandLines(
@@ -38,9 +39,10 @@ export function formatCliUsage(
     }
     lines.push(sectionTitle);
     const rows = group.commands.map((cmd) => {
+      const namePart = cmd.name === "" ? "" : ` ${cmd.name}`;
       const args = cmd.args ? ` ${cmd.args}` : "";
       return {
-        prefix: `${group.name} ${cmd.name}${args}`,
+        prefix: `${group.name}${namePart}${args}`,
         description: cmd.description,
       };
     });
@@ -57,12 +59,12 @@ export function formatCliUsage(
   );
   lines.push("");
 
-  lines.push("Server:");
+  lines.push("Gateway:");
   lines.push(
     ...formatUsageCommandLines([
       {
-        prefix: "serve [--port N] [--host ADDR]",
-        description: "Start HTTP API server (default: 127.0.0.1:7860)",
+        prefix: "connect [--name NAME] [--gateway URL]",
+        description: "Connect to workflow gateway via WebSocket",
       },
     ]),
   );

packages/cli-workflow/src/commands/cas/gc.ts

@@ -1,4 +1,5 @@
-import { type GcResult, garbageCollectCas, type Result } from "@uncaged/workflow";
+import { type GcResult, garbageCollectCas } from "@uncaged/workflow-execute";
+import type { Result } from "@uncaged/workflow-protocol";
 
 export async function cmdGc(storageRoot: string): Promise<Result<GcResult, string>> {
   return garbageCollectCas(storageRoot);

packages/cli-workflow/src/commands/cas/get.ts

@@ -1,4 +1,6 @@
-import { createCasStore, err, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 export async function cmdCasGet(
   storageRoot: string,

packages/cli-workflow/src/commands/cas/list.ts

@@ -1,4 +1,6 @@
-import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { ok, type Result } from "@uncaged/workflow-protocol";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 export async function cmdCasList(storageRoot: string): Promise<Result<string[], string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

packages/cli-workflow/src/commands/cas/put.ts

@@ -1,4 +1,6 @@
-import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { ok, type Result } from "@uncaged/workflow-protocol";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 export async function cmdCasPut(
   storageRoot: string,

packages/cli-workflow/src/commands/cas/rm.ts

@@ -1,4 +1,6 @@
-import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { ok, type Result } from "@uncaged/workflow-protocol";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 export async function cmdCasRm(storageRoot: string, hash: string): Promise<Result<void, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

packages/cli-workflow/src/commands/connect/app.ts

@@ -0,0 +1,60 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+import { createCasRoutes } from "./routes-cas.js";
+import { createLiveRoutes } from "./routes-live.js";
+import { createThreadRoutes } from "./routes-thread.js";
+import { createWorkflowRoutes } from "./routes-workflow.js";
+
+const MAX_BODY_SIZE = 1_048_576; // 1 MB
+
+export function createApp(storageRoot: string, clientToken: string | null): Hono {
+  const app = new Hono();
+
+  app.onError((_err, c) => {
+    return c.json({ error: "Internal server error" }, 500);
+  });
+
+  app.use(
+    "*",
+    cors({
+      origin: [
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+        "http://localhost:7860",
+        "http://127.0.0.1:7860",
+      ],
+    }),
+  );
+
+  app.use("*", async (c, next) => {
+    if (c.req.method === "POST") {
+      const contentLength = c.req.header("content-length");
+      if (contentLength !== undefined && Number(contentLength) > MAX_BODY_SIZE) {
+        return c.json({ error: "Payload too large" }, 413);
+      }
+    }
+    await next();
+  });
+
+  // ── Client token auth (skip healthz) ───────────────────────────────
+  if (clientToken !== null) {
+    app.use("/api/*", async (c, next) => {
+      const token = c.req.header("X-Client-Token");
+      if (token !== clientToken) {
+        return c.json({ error: "unauthorized" }, 401);
+      }
+      await next();
+    });
+  }
+
+  app.get("/healthz", (c) => c.json({ ok: true }));
+  app.get("/api/healthz", (c) => c.json({ ok: true }));
+
+  app.route("/api/workflows", createWorkflowRoutes(storageRoot));
+  app.route("/api/threads", createThreadRoutes(storageRoot));
+  app.route("/api/threads", createLiveRoutes(storageRoot));
+  app.route("/api/cas", createCasRoutes(storageRoot));
+
+  return app;
+}

packages/cli-workflow/src/commands/connect/connect.ts

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import { hostname as osHostname } from "node:os";
+import { ok, type Result } from "@uncaged/workflow-protocol";
+import { createLogger } from "@uncaged/workflow-util";
+
+import { printCliLine } from "../../cli-output.js";
+import { createApp } from "./app.js";
+import { registerWithGateway, startHeartbeat, unregisterFromGateway } from "./gateway.js";
+import type { ConnectOptions } from "./types.js";
+import { startGatewayWsClient } from "./ws-client.js";
+
+const DEFAULT_GATEWAY_URL = "https://workflow-gateway.shazhou.workers.dev";
+const HEARTBEAT_INTERVAL_MS = 60_000;
+
+function requireNextArg(argv: string[], i: number, flag: string): Result<string, string> {
+  const next = argv[i + 1];
+  if (next === undefined) {
+    return { ok: false, error: `${flag} requires a value` };
+  }
+  return ok(next);
+}
+
+function parseConnectArgv(argv: string[]): Result<ConnectOptions, string> {
+  let name = osHostname().split(".")[0].toLowerCase();
+  let gatewayUrl = DEFAULT_GATEWAY_URL;
+  const gatewaySecret = process.env.WORKFLOW_DASHBOARD_SECRET ?? "";
+  const stringFlags: Record<string, (v: string) => void> = {
+    "--name": (v) => {
+      name = v;
+    },
+    "--gateway": (v) => {
+      gatewayUrl = v;
+    },
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg in stringFlags) {
+      const r = requireNextArg(argv, i, arg);
+      if (!r.ok) return r;
+      stringFlags[arg](r.value);
+      i++;
+    }
+  }
+
+  return ok({ name, gatewayUrl, gatewaySecret });
+}
+
+export async function dispatchConnect(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseConnectArgv(argv);
+  if (!parsed.ok) {
+    printCliLine(`error: ${parsed.error}`);
+    return 1;
+  }
+
+  const options = parsed.value;
+
+  if (options.gatewaySecret === "") {
+    printCliLine("error: WORKFLOW_DASHBOARD_SECRET is required");
+    return 1;
+  }
+
+  const clientToken = randomUUID();
+  const app = createApp(storageRoot, clientToken);
+
+  const log = createLogger({ sink: { kind: "stderr" } });
+  const stopWsClient = startGatewayWsClient({
+    gatewayUrl: options.gatewayUrl,
+    name: options.name,
+    secret: options.gatewaySecret,
+    appFetch: app.fetch,
+    log,
+  });
+
+  printCliLine("connected to gateway via WebSocket");
+
+  // Register with gateway for discovery
+  const registered = await registerWithGateway(
+    options.gatewayUrl,
+    options.name,
+    `ws://${options.name}`,
+    options.gatewaySecret,
+    clientToken,
+  );
+  if (registered) {
+    printCliLine(`registered with gateway as "${options.name}"`);
+  }
+
+  const heartbeatTimer = startHeartbeat(
+    options.gatewayUrl,
+    options.name,
+    `ws://${options.name}`,
+    options.gatewaySecret,
+    clientToken,
+    HEARTBEAT_INTERVAL_MS,
+  );
+
+  const cleanup = async () => {
+    clearInterval(heartbeatTimer);
+    stopWsClient();
+    printCliLine("unregistering from gateway...");
+    await unregisterFromGateway(options.gatewayUrl, options.name, options.gatewaySecret);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+
+  await new Promise(() => {});
+  return 0;
+}

packages/cli-workflow/src/commands/connect/gateway.ts

@@ -0,0 +1,54 @@
+import { printCliLine } from "../../cli-output.js";
+
+export async function registerWithGateway(
+  gatewayUrl: string,
+  name: string,
+  localUrl: string,
+  secret: string,
+  clientToken: string,
+): Promise<boolean> {
+  try {
+    const resp = await fetch(`${gatewayUrl}/api/gateway/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, url: localUrl, secret, clientToken }),
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      printCliLine(`gateway registration failed: ${resp.status} ${body}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    printCliLine(`gateway registration error: ${e}`);
+    return false;
+  }
+}
+
+export async function unregisterFromGateway(
+  gatewayUrl: string,
+  name: string,
+  secret: string,
+): Promise<void> {
+  try {
+    await fetch(`${gatewayUrl}/api/gateway/register/${name}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${secret}` },
+    });
+  } catch {
+    // Best effort — process is exiting
+  }
+}
+
+export function startHeartbeat(
+  gatewayUrl: string,
+  name: string,
+  localUrl: string,
+  secret: string,
+  clientToken: string,
+  intervalMs: number,
+): ReturnType<typeof setInterval> {
+  return setInterval(() => {
+    registerWithGateway(gatewayUrl, name, localUrl, secret, clientToken).catch(() => {});
+  }, intervalMs);
+}

packages/cli-workflow/src/commands/connect/index.ts

@@ -0,0 +1,2 @@
+export { dispatchConnect } from "./connect.js";
+export type { ConnectOptions } from "./types.js";

packages/cli-workflow/src/commands/connect/routes-cas.ts

@@ -1,19 +1,19 @@
-import { createCasStore, garbageCollectCas, getGlobalCasDir } from "@uncaged/workflow";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { garbageCollectCas } from "@uncaged/workflow-execute";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 import { Hono } from "hono";
 
 export function createCasRoutes(storageRoot: string): Hono {
   const app = new Hono();
+  const casDir = getGlobalCasDir(storageRoot);
+  const cas = createCasStore(casDir);
 
   app.get("/", async (c) => {
-    const casDir = getGlobalCasDir(storageRoot);
-    const cas = createCasStore(casDir);
     const hashes = await cas.list();
     return c.json({ hashes });
   });
 
   app.get("/:hash", async (c) => {
-    const casDir = getGlobalCasDir(storageRoot);
-    const cas = createCasStore(casDir);
     const content = await cas.get(c.req.param("hash"));
     if (content === null) {
       return c.json({ error: "not found" }, 404);
@@ -22,19 +22,20 @@ export function createCasRoutes(storageRoot: string): Hono {
   });
 
   app.post("/", async (c) => {
-    const body = await c.req.json<{ content: string }>();
+    let body: { content: string };
+    try {
+      body = (await c.req.json()) as { content: string };
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
     if (typeof body.content !== "string") {
       return c.json({ error: "content field required" }, 400);
     }
-    const casDir = getGlobalCasDir(storageRoot);
-    const cas = createCasStore(casDir);
     const hash = await cas.put(body.content);
     return c.json({ hash }, 201);
   });
 
   app.delete("/:hash", async (c) => {
-    const casDir = getGlobalCasDir(storageRoot);
-    const cas = createCasStore(casDir);
     const hash = c.req.param("hash");
     const content = await cas.get(hash);
     if (content === null) {

packages/cli-workflow/src/commands/connect/routes-live.ts

@@ -0,0 +1,374 @@
+import { existsSync, statSync, watch } from "node:fs";
+import { join } from "node:path";
+import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
+import {
+  FORK_BRANCH_ROLE,
+  readThreadsIndex,
+  type ThreadIndex,
+  walkStateFramesNewestFirst,
+} from "@uncaged/workflow-execute";
+import { END } from "@uncaged/workflow-runtime";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+
+import { resolveThreadRecord } from "../../thread-scan.js";
+
+type PumpState = {
+  contentOffset: number;
+  carry: string;
+};
+
+function fileSize(path: string): number {
+  try {
+    return statSync(path).size;
+  } catch {
+    return 0;
+  }
+}
+
+async function readNewBytes(path: string, state: PumpState): Promise<string | null> {
+  const size = fileSize(path);
+  if (size < state.contentOffset) {
+    state.contentOffset = 0;
+    state.carry = "";
+  }
+  if (size <= state.contentOffset) {
+    return null;
+  }
+  const blob = Bun.file(path).slice(state.contentOffset, size);
+  const chunk = await blob.text();
+  state.contentOffset = size;
+  return chunk;
+}
+
+function parseJsonLine(line: string): unknown {
+  try {
+    return JSON.parse(line) as unknown;
+  } catch {
+    return { raw: line };
+  }
+}
+
+function parseNewLines(chunk: string, state: PumpState): string[] {
+  state.carry += chunk;
+
+  const parts = state.carry.split("\n");
+  state.carry = parts.pop() ?? "";
+
+  const lines: string[] = [];
+  for (const line of parts) {
+    const trimmed = line.trim();
+    if (trimmed !== "") {
+      lines.push(trimmed);
+    }
+  }
+  return lines;
+}
+
+type CasSseState = {
+  printedHashes: Set<string>;
+  lastHead: string | null;
+  completionEmitted: boolean;
+};
+
+type LiveSseStream = {
+  writeSSE: (opts: { event: string; data: string; id: string }) => Promise<void>;
+};
+
+function completionFromEndMeta(meta: Record<string, unknown>): {
+  returnCode: number;
+  summary: string;
+} | null {
+  const returnCode = meta.returnCode;
+  const summary = meta.summary;
+  if (typeof returnCode !== "number" || typeof summary !== "string") {
+    return null;
+  }
+  return { returnCode, summary };
+}
+
+async function emitRecordsForHead(params: {
+  storageRoot: string;
+  bundleDir: string;
+  threadId: string;
+  headHash: string;
+  sseState: CasSseState;
+  stream: LiveSseStream;
+  eventId: { n: number };
+}): Promise<boolean> {
+  const cas = createCasStore(getGlobalCasDir(params.storageRoot));
+  const frames = await walkStateFramesNewestFirst(cas, params.headHash);
+  const chronological = [...frames].reverse();
+
+  for (const fr of chronological) {
+    if (params.sseState.printedHashes.has(fr.hash)) {
+      continue;
+    }
+    params.sseState.printedHashes.add(fr.hash);
+
+    const role = fr.payload.role;
+    if (role === FORK_BRANCH_ROLE) {
+      continue;
+    }
+
+    if (role === END) {
+      const wf = completionFromEndMeta(fr.payload.meta);
+      if (wf !== null) {
+        params.eventId.n++;
+        await params.stream.writeSSE({
+          event: "record",
+          data: JSON.stringify({
+            type: "workflow-result",
+            returnCode: wf.returnCode,
+            content: wf.summary,
+            timestamp: null,
+          }),
+          id: String(params.eventId.n),
+        });
+        return true;
+      }
+      continue;
+    }
+
+    const payloadText = await getContentMerklePayload(cas, fr.payload.content);
+    const content =
+      payloadText !== null
+        ? payloadText
+        : `(content not in CAS; contentHash=${fr.payload.content})`;
+
+    params.eventId.n++;
+    await params.stream.writeSSE({
+      event: "record",
+      data: JSON.stringify({
+        type: "role",
+        role: fr.payload.role,
+        contentHash: fr.payload.content,
+        content,
+        meta: fr.payload.meta,
+        timestamp: fr.payload.timestamp,
+      }),
+      id: String(params.eventId.n),
+    });
+  }
+
+  return false;
+}
+
+async function pumpThreadsJsonSse(params: {
+  storageRoot: string;
+  bundleDir: string;
+  threadId: string;
+  sseState: CasSseState;
+  stream: LiveSseStream;
+  eventId: { n: number };
+}): Promise<boolean> {
+  let idx: ThreadIndex;
+  try {
+    idx = await readThreadsIndex(params.bundleDir);
+  } catch {
+    idx = {};
+  }
+
+  const active = idx[params.threadId];
+
+  if (active === undefined) {
+    if (params.sseState.completionEmitted) {
+      return false;
+    }
+    const hist = await resolveThreadRecord(params.storageRoot, params.threadId);
+    if (hist === null || hist.source !== "history") {
+      return false;
+    }
+    params.sseState.completionEmitted = true;
+    return await emitRecordsForHead({
+      storageRoot: params.storageRoot,
+      bundleDir: params.bundleDir,
+      threadId: params.threadId,
+      headHash: hist.head,
+      sseState: params.sseState,
+      stream: params.stream,
+      eventId: params.eventId,
+    });
+  }
+
+  const head = active.head;
+  if (params.sseState.lastHead === null) {
+    params.sseState.lastHead = head;
+    return await emitRecordsForHead({
+      storageRoot: params.storageRoot,
+      bundleDir: params.bundleDir,
+      threadId: params.threadId,
+      headHash: head,
+      sseState: params.sseState,
+      stream: params.stream,
+      eventId: params.eventId,
+    });
+  }
+
+  if (head !== params.sseState.lastHead) {
+    params.sseState.lastHead = head;
+    return await emitRecordsForHead({
+      storageRoot: params.storageRoot,
+      bundleDir: params.bundleDir,
+      threadId: params.threadId,
+      headHash: head,
+      sseState: params.sseState,
+      stream: params.stream,
+      eventId: params.eventId,
+    });
+  }
+
+  return false;
+}
+
+export function createLiveRoutes(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.get("/:threadId/live", async (c) => {
+    const threadId = c.req.param("threadId");
+    const resolved = await resolveThreadRecord(storageRoot, threadId);
+    if (resolved === null) {
+      return c.json({ error: `thread not found: ${threadId}` }, 404);
+    }
+
+    const threadTarget = resolved;
+    const threadsJsonPath = join(threadTarget.bundleDir, "threads.json");
+    const infoPath = join(storageRoot, "logs", threadTarget.bundleHash, `${threadId}.info.jsonl`);
+
+    return streamSSE(c, async (stream) => {
+      const infoState: PumpState = { contentOffset: 0, carry: "" };
+      const sseThreadState: CasSseState = {
+        printedHashes: new Set<string>(),
+        lastHead: null,
+        completionEmitted: false,
+      };
+      const eventId = { n: 0 };
+
+      async function pumpData(): Promise<boolean> {
+        const finished = await pumpThreadsJsonSse({
+          storageRoot,
+          bundleDir: threadTarget.bundleDir,
+          threadId,
+          sseState: sseThreadState,
+          stream,
+          eventId,
+        });
+        return finished;
+      }
+
+      // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: SSE newline framing mirrors legacy pump
+      async function pumpInfo(): Promise<void> {
+        let chunk: string | null;
+        try {
+          chunk = await readNewBytes(infoPath, infoState);
+        } catch {
+          return;
+        }
+        if (chunk === null) {
+          return;
+        }
+
+        const lines = parseNewLines(chunk, infoState);
+        for (const line of lines) {
+          const record = parseJsonLine(line);
+          if (
+            typeof record === "object" &&
+            record !== null &&
+            "raw" in (record as Record<string, unknown>)
+          ) {
+            continue;
+          }
+          eventId.n++;
+          await stream.writeSSE({
+            event: "info",
+            data: JSON.stringify(record),
+            id: String(eventId.n),
+          });
+        }
+      }
+
+      eventId.n++;
+      await stream.writeSSE({
+        event: "record",
+        data: JSON.stringify({
+          type: "thread-start",
+          threadId: threadTarget.threadId,
+          bundleHash: threadTarget.bundleHash,
+          head: threadTarget.head,
+          start: threadTarget.start,
+          source: threadTarget.source,
+        }),
+        id: String(eventId.n),
+      });
+
+      const done = await pumpData();
+      try {
+        await pumpInfo();
+      } catch {
+        // optional info file
+      }
+      if (done) {
+        return;
+      }
+
+      // If thread is not actively running, emit all records and close — don't keep SSE open
+      const runningPath = join(storageRoot, "logs", threadTarget.bundleHash, `${threadId}.running`);
+      if (!existsSync(runningPath)) {
+        eventId.n++;
+        await stream.writeSSE({
+          event: "done",
+          data: JSON.stringify({ reason: "not-running" }),
+          id: String(eventId.n),
+        });
+        return;
+      }
+
+      const controller = new AbortController();
+      let completed = false;
+
+      const threadsJsonWatcher = watch(threadsJsonPath, async () => {
+        if (completed) {
+          return;
+        }
+        const finished = await pumpData();
+        if (finished) {
+          completed = true;
+          controller.abort();
+        }
+      });
+
+      let infoWatcher: ReturnType<typeof watch> | null = null;
+      try {
+        infoWatcher = watch(infoPath, async () => {
+          if (completed) {
+            return;
+          }
+          await pumpInfo();
+        });
+      } catch {
+        // info file may not exist
+      }
+
+      stream.onAbort(() => {
+        completed = true;
+        threadsJsonWatcher.close();
+        infoWatcher?.close();
+      });
+
+      await new Promise<void>((resolve) => {
+        if (completed) {
+          resolve();
+          return;
+        }
+        controller.signal.addEventListener("abort", () => resolve(), { once: true });
+        stream.onAbort(() => resolve());
+      });
+
+      threadsJsonWatcher.close();
+      infoWatcher?.close();
+    });
+  });
+
+  return app;
+}

packages/cli-workflow/src/commands/connect/routes-thread.ts

@@ -0,0 +1,199 @@
+import { join } from "node:path";
+import { createCasStore, getContentMerklePayload, parseCasThreadNode } from "@uncaged/workflow-cas";
+import { FORK_BRANCH_ROLE, walkStateFramesNewestFirst } from "@uncaged/workflow-execute";
+import { END } from "@uncaged/workflow-runtime";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
+import { Hono } from "hono";
+
+import { pathExists } from "../../fs-utils.js";
+import type { HistoricalThreadRow, ResolvedThreadRecord } from "../../thread-scan.js";
+import {
+  listHistoricalThreads,
+  listRunningThreads,
+  resolveThreadListStatus,
+  resolveThreadRecord,
+} from "../../thread-scan.js";
+import { cmdKill, cmdPause, cmdResume } from "../thread/control.js";
+import { cmdRun } from "../thread/run.js";
+
+async function readStartInfo(
+  cas: ReturnType<typeof createCasStore>,
+  startHash: string,
+): Promise<{ name: string | null; prompt: string | null }> {
+  const raw = await cas.get(startHash);
+  if (raw === null) return { name: null, prompt: null };
+  const parsed = parseCasThreadNode(raw);
+  if (parsed === null || parsed.kind !== "start") return { name: null, prompt: null };
+  const name = parsed.node.payload.name;
+  const promptHash = parsed.node.refs[0] ?? null;
+  let prompt: string | null = null;
+  if (promptHash !== null) {
+    prompt = await getContentMerklePayload(cas, promptHash);
+  }
+  return { name, prompt };
+}
+
+async function buildThreadDetailRecords(
+  storageRoot: string,
+  resolved: ResolvedThreadRecord,
+  runningMarkerPresent: boolean,
+  statusRow: HistoricalThreadRow,
+): Promise<unknown[]> {
+  const cas = createCasStore(getGlobalCasDir(storageRoot));
+  const frames = await walkStateFramesNewestFirst(cas, resolved.head);
+  const chronological = [...frames].reverse();
+
+  const { name: workflowName, prompt } = await readStartInfo(cas, resolved.start);
+
+  const status = await resolveThreadListStatus(storageRoot, statusRow, runningMarkerPresent);
+
+  const records: unknown[] = [
+    {
+      type: "thread-start",
+      workflow: workflowName ?? "unknown",
+      prompt: prompt ?? null,
+      threadId: resolved.threadId,
+      status,
+      timestamp: null,
+    },
+  ];
+
+  for (const fr of chronological) {
+    if (fr.payload.role === FORK_BRANCH_ROLE) {
+      continue;
+    }
+    if (fr.payload.role === END) {
+      const returnCode = fr.payload.meta.returnCode;
+      const summary = fr.payload.meta.summary;
+      if (typeof returnCode === "number" && typeof summary === "string") {
+        records.push({
+          type: "workflow-result",
+          returnCode,
+          content: summary,
+          timestamp: fr.payload.timestamp,
+        });
+      }
+      continue;
+    }
+    const payloadText = await getContentMerklePayload(cas, fr.payload.content);
+    const content =
+      payloadText !== null
+        ? payloadText
+        : `(content not in CAS; contentHash=${fr.payload.content})`;
+    records.push({
+      type: "role",
+      role: fr.payload.role,
+      contentHash: fr.payload.content,
+      content,
+      meta: fr.payload.meta,
+      timestamp: fr.payload.timestamp,
+    });
+  }
+
+  return records;
+}
+
+export function createThreadRoutes(storageRoot: string): Hono {
+  const app = new Hono();
+
+  app.get("/", async (c) => {
+    const nameFilter = c.req.query("workflow") ?? null;
+    const rows = await listHistoricalThreads(storageRoot, nameFilter);
+    const threads = await Promise.all(
+      rows.map(async (r) => {
+        const runningPath = join(storageRoot, "logs", r.hash, `${r.threadId}.running`);
+        const runningMarkerPresent = await pathExists(runningPath);
+        const status = await resolveThreadListStatus(storageRoot, r, runningMarkerPresent);
+        return {
+          threadId: r.threadId,
+          workflow: r.workflowName,
+          hash: r.hash,
+          startedAt: new Date(r.activityTs).toISOString(),
+          status,
+        };
+      }),
+    );
+    return c.json({ threads });
+  });
+
+  app.get("/running", async (c) => {
+    const rows = await listRunningThreads(storageRoot);
+    return c.json({ threads: rows });
+  });
+
+  app.get("/:threadId", async (c) => {
+    const threadId = c.req.param("threadId");
+    const resolved = await resolveThreadRecord(storageRoot, threadId);
+    if (resolved === null) {
+      return c.json({ error: `thread not found: ${threadId}` }, 404);
+    }
+    const runningPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.running`);
+    const runningMarkerPresent = await pathExists(runningPath);
+    const statusRow = {
+      threadId: resolved.threadId,
+      hash: resolved.bundleHash,
+      workflowName: null,
+      source: resolved.source,
+      activityTs: 0,
+      head: resolved.head,
+    };
+    const records = await buildThreadDetailRecords(
+      storageRoot,
+      resolved,
+      runningMarkerPresent,
+      statusRow,
+    );
+    return c.json({ threadId, records });
+  });
+
+  app.post("/", async (c) => {
+    let body: Record<string, unknown>;
+    try {
+      body = (await c.req.json()) as Record<string, unknown>;
+    } catch {
+      return c.json({ error: "invalid JSON body" }, 400);
+    }
+
+    const name = body.workflow;
+    const prompt = body.prompt;
+
+    if (typeof name !== "string" || typeof prompt !== "string") {
+      return c.json({ error: "workflow (string) and prompt (string) are required" }, 400);
+    }
+
+    const result = await cmdRun(storageRoot, name, prompt);
+    if (!result.ok) {
+      return c.json({ error: result.error }, 400);
+    }
+    return c.json({ threadId: result.value.threadId }, 201);
+  });
+
+  app.post("/:threadId/kill", async (c) => {
+    const threadId = c.req.param("threadId");
+    const result = await cmdKill(storageRoot, threadId);
+    if (!result.ok) {
+      return c.json({ error: result.error }, 400);
+    }
+    return c.json({ ok: true });
+  });
+
+  app.post("/:threadId/pause", async (c) => {
+    const threadId = c.req.param("threadId");
+    const result = await cmdPause(storageRoot, threadId);
+    if (!result.ok) {
+      return c.json({ error: result.error }, 400);
+    }
+    return c.json({ ok: true });
+  });
+
+  app.post("/:threadId/resume", async (c) => {
+    const threadId = c.req.param("threadId");
+    const result = await cmdResume(storageRoot, threadId);
+    if (!result.ok) {
+      return c.json({ error: result.error }, 400);
+    }
+    return c.json({ ok: true });
+  });
+
+  return app;
+}

packages/cli-workflow/src/commands/connect/routes-workflow.ts

@@ -1,9 +1,14 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { WorkflowDescriptor } from "@uncaged/workflow-protocol";
 import {
   getRegisteredWorkflow,
   listRegisteredWorkflowNames,
   readWorkflowRegistry,
-} from "@uncaged/workflow";
+  validateWorkflowDescriptor,
+} from "@uncaged/workflow-register";
 import { Hono } from "hono";
+import { parse as parseYaml } from "yaml";
 
 export function createWorkflowRoutes(storageRoot: string): Hono {
   const app = new Hono();
@@ -35,7 +40,17 @@ export function createWorkflowRoutes(storageRoot: string): Hono {
     if (entry === null) {
       return c.json({ error: `workflow not found: ${name}` }, 404);
     }
-    return c.json({ name, ...entry });
+    let descriptor: WorkflowDescriptor | null = null;
+    try {
+      const yamlPath = join(storageRoot, "bundles", `${entry.hash}.yaml`);
+      const yamlText = await readFile(yamlPath, "utf8");
+      const parsed: unknown = parseYaml(yamlText);
+      const validated = validateWorkflowDescriptor(parsed);
+      descriptor = validated.ok ? validated.value : null;
+    } catch {
+      descriptor = null;
+    }
+    return c.json({ name, ...entry, descriptor });
   });
 
   app.get("/:name/history", async (c) => {

packages/cli-workflow/src/commands/connect/types.ts

@@ -0,0 +1,5 @@
+export type ConnectOptions = {
+  name: string;
+  gatewayUrl: string;
+  gatewaySecret: string;
+};

packages/cli-workflow/src/commands/connect/ws-client.ts

@@ -0,0 +1,164 @@
+import { parseWsRequestJson, type WsResponse } from "@uncaged/workflow-gateway/ws-protocol";
+import type { LogFn } from "@uncaged/workflow-util";
+
+export type GatewayWsClientParams = {
+  gatewayUrl: string;
+  name: string;
+  secret: string;
+  appFetch: (request: Request) => Response | Promise<Response>;
+  log: LogFn;
+};
+
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+
+export function buildGatewayWsConnectUrl(gatewayUrl: string, name: string, secret: string): string {
+  const u = new URL(gatewayUrl);
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  u.pathname = "/ws/connect";
+  u.search = "";
+  u.searchParams.set("name", name);
+  u.searchParams.set("secret", secret);
+  return u.href;
+}
+
+function headersToRecord(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of h) {
+    out[k] = v;
+  }
+  return out;
+}
+
+async function handleGatewayMessage(
+  ws: WebSocket,
+  raw: string,
+  params: GatewayWsClientParams,
+): Promise<void> {
+  const req = parseWsRequestJson(raw);
+  if (req === null) {
+    params.log("ZM8K2PQ1", "gateway WebSocket dropped non-request message");
+    return;
+  }
+  const localUrl = `http://localhost${req.path}`;
+  const headers = new Headers(req.headers);
+  let resp: Response;
+  try {
+    resp = await params.appFetch(
+      new Request(localUrl, {
+        method: req.method,
+        headers,
+        body: req.body === null ? undefined : req.body,
+      }),
+    );
+  } catch (e) {
+    params.log("R4N7BQ3C", `app.fetch failed: ${String(e)}`);
+    const errBody: WsResponse = {
+      id: req.id,
+      status: 502,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ error: "local fetch failed", detail: String(e) }),
+    };
+    ws.send(JSON.stringify(errBody));
+    return;
+  }
+  const bodyText = await resp.text();
+  const headerRecord = headersToRecord(resp.headers);
+  const out: WsResponse = {
+    id: req.id,
+    status: resp.status,
+    headers: headerRecord,
+    body: bodyText,
+  };
+  ws.send(JSON.stringify(out));
+}
+
+/** Maintains a reverse WebSocket to the workflow gateway; reconnects with exponential backoff. */
+export function startGatewayWsClient(params: GatewayWsClientParams): () => void {
+  const wsUrl = buildGatewayWsConnectUrl(params.gatewayUrl, params.name, params.secret);
+  let socket: WebSocket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  let attempt = 0;
+
+  const clearReconnectTimer = (): void => {
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const scheduleReconnect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    const delayMs = Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+    attempt++;
+    params.log("6CJX2R8P", `gateway WebSocket reconnect in ${delayMs}ms (attempt ${attempt})`);
+    reconnectTimer = setTimeout(connect, delayMs);
+  };
+
+  const connect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    params.log("2XK7HM9Q", "gateway WebSocket connecting...");
+    try {
+      socket = new WebSocket(wsUrl);
+    } catch (e) {
+      params.log("7NQW4HBT", `gateway WebSocket create failed: ${String(e)}`);
+      scheduleReconnect();
+      return;
+    }
+
+    const ws = socket;
+
+    ws.addEventListener("open", () => {
+      attempt = 0;
+      params.log("4PWN3V82", "gateway WebSocket connected");
+    });
+
+    ws.addEventListener("close", (ev) => {
+      socket = null;
+      params.log(
+        "8QTR6ZKC",
+        `gateway WebSocket closed code=${String(ev.code)} reason=${ev.reason} wasClean=${String(ev.wasClean)}`,
+      );
+      if (!stopped) {
+        scheduleReconnect();
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      params.log("9BWS1M7F", "gateway WebSocket error");
+    });
+
+    ws.addEventListener("message", (ev) => {
+      const data = ev.data;
+      if (typeof data !== "string") {
+        params.log("T9W2K35H", "gateway WebSocket non-text frame ignored");
+        return;
+      }
+      void handleGatewayMessage(ws, data, params).catch((e: unknown) => {
+        params.log("V7KX2M9P", `gateway WebSocket handler error: ${String(e)}`);
+      });
+    });
+  };
+
+  connect();
+
+  return (): void => {
+    stopped = true;
+    clearReconnectTimer();
+    if (socket !== null && socket.readyState === WebSocket.OPEN) {
+      socket.close(1000, "shutdown");
+    }
+    socket = null;
+  };
+}

packages/cli-workflow/src/commands/init/template.ts

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { pathExists } from "../../fs-utils.js";
 

packages/cli-workflow/src/commands/init/templates.ts

@@ -6,8 +6,7 @@ export function templatePackageJson(templateName: string): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow": "^0.1.0",
-        "@uncaged/workflow-runtime": "^0.1.0",
+        "@uncaged/workflow-runtime": "^0.3.1",
         zod: "^4.0.0",
       },
     },
@@ -51,25 +50,19 @@ const greeterMetaSchema = z.object({
 export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
   description: "Says hello — replace with your first role.",
   systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
-  extractPrompt: "Extract the assistant's greeting as message.",
   schema: greeterMetaSchema,
-  extractRefs: null,
 };
 `;
 }
 
 export function templateModeratorTs(): string {
-  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow-runtime";
+  return `import { END, START, type ModeratorTable } from "@uncaged/workflow-runtime";
 
 import type { HelloTemplateMeta } from "./roles.js";
 
-export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
-  ctx: ModeratorContext<HelloTemplateMeta>,
-) => {
-  if (ctx.steps.length === 0) {
-    return "greeter";
-  }
-  return END;
+export const helloTemplateTable: ModeratorTable<HelloTemplateMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "greeter" }],
+  greeter: [{ condition: "FALLBACK", role: END }],
 };
 `;
 }
@@ -77,7 +70,7 @@ export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
 export function templateIndexTs(): string {
   return `import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
 
-import { helloTemplateModerator } from "./moderator.js";
+import { helloTemplateTable } from "./moderator.js";
 import {
   HELLO_TEMPLATE_DESCRIPTION,
   type HelloTemplateMeta,
@@ -89,14 +82,14 @@ export {
   type HelloTemplateMeta,
   greeterRole,
 } from "./roles.js";
-export { helloTemplateModerator } from "./moderator.js";
+export { helloTemplateTable } from "./moderator.js";
 
 export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
   description: HELLO_TEMPLATE_DESCRIPTION,
   roles: {
     greeter: greeterRole,
   },
-  moderator: helloTemplateModerator,
+  table: helloTemplateTable,
 };
 `;
 }

packages/cli-workflow/src/commands/init/validate.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 /** Validates a single path segment for workspace / template names (no separators, not `.` / `..`). */
 export function validateWorkspaceSegment(name: string): Result<void, string> {

packages/cli-workflow/src/commands/init/workspace.ts

@@ -1,11 +1,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join, resolve } from "node:path";
 
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { pathExists } from "../../fs-utils.js";
 import type { CmdInitWorkspaceSuccess } from "./types.js";
-import { validateWorkspaceSegment } from "./validate.js";
 
 function rootPackageJson(workspaceName: string): string {
   return `${JSON.stringify(
@@ -14,6 +13,9 @@ function rootPackageJson(workspaceName: string): string {
       private: true,
       type: "module",
       workspaces: ["templates/*", "workflows"],
+      scripts: {
+        bundle: "bun run scripts/bundle.ts",
+      },
     },
     null,
     2,
@@ -28,7 +30,7 @@ function workflowsPackageJson(): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow": "^0.1.0",
+        "@uncaged/workflow-runtime": "^0.3.1",
         zod: "^4.0.0",
       },
     },
@@ -42,7 +44,9 @@ function biomeJson(): string {
     {
       $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
       files: {
-        includes: ["**", "!**/node_modules", "!**/dist"],
+        // Exclude generated bundle script — it uses Bun globals and console that
+        // conflict with the workspace's Biome rules (noConsole, etc.).
+        includes: ["**", "!**/node_modules", "!**/dist", "!scripts/bundle.ts"],
       },
       formatter: {
         indentWidth: 2,
@@ -85,29 +89,29 @@ function agentsMd(): string {
 | 层级 | 目录 / 产物 | 职责 |
 |------|----------------|------|
 | **Workspace** | 仓库根（\`package.json\` 含 \`workspaces: ["templates/*", "workflows"]\`） | Bun monorepo：统一管理本地模板包与 workflow 实例 |
-| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **Moderator**），**不绑定**具体 Agent |
-| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AgentFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
+| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **ModeratorTable**），**不绑定**具体 Agent |
+| **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AdapterFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
 
 Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下放绑定与打包入口。
 
 ## 2. 核心概念
 
 - **RoleMeta**：\`Record<string, Record<string, unknown>>\`，角色名 → 该角色结构化 meta 的形状约定。
-- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`extractPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
-- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **Moderator**。
-- **Moderator**：\`(ctx: ModeratorContext<M>) => (角色名) | END\`。同步、纯函数，只做路由。
-- **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
-- **ExtractFn**：从上下文与 prompt 解析结构化数据（引擎与 Agent 都可使用）。
+- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
+- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **ModeratorTable**（声明式路由表）。
+- **ModeratorTable**：从 \`START\` 与各角色名映射到有序 transition 列表（条件 + 下一角色或 \`END\`）；可序列化，供描述符提取 **graph**。
+- **AdapterFn**：接收系统提示词与 Zod schema，返回角色执行函数（RoleFn）。
+- **ExtractFn**：从 CAS content hash 解析结构化数据（引擎与 Adapter 都可使用）。
 
-引擎循环简述：**Moderator** → 选角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
+引擎循环简述：按 **ModeratorTable** 选下一角色 → **Adapter** 产出 typed meta → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
 
 ## 3. 开发流程
 
 1. **定义 RoleMeta**：为每个角色约定 meta 的 TypeScript 类型（与 Zod schema 对齐）。
-2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`extractPrompt\` / \`description\`。
-3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
-4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
-5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowFnOptions\`。
+2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`description\`。
+3. **编写 ModeratorTable**：为 \`START\` 与各角色声明 transition（\`FALLBACK\` 或命名条件 + \`check\`）。
+4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / table 导出）。
+5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AdapterFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowRuntime\`。
 6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
 
 ## 4. 编码规范
@@ -153,7 +157,13 @@ uncaged-workflow add <name> <path/to/bundle.esm.js>
 
 ---
 
-编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ Moderator → 绑定 → 单文件 bundle**，再对照本节规范自检。
+编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ ModeratorTable → 绑定 → 单文件 bundle**，再对照本节规范自检。
+`;
+}
+
+function bunfigToml(): string {
+  return `[install.scopes]
+"@uncaged" = "https://git.shazhou.work/api/packages/shazhou/npm/"
 `;
 }
 
@@ -164,7 +174,7 @@ Local workflow development workspace (Bun monorepo).
 
 ## Layout
 
-- \`templates/\` — reusable workflow definition packages (roles + moderator), no agent binding
+- \`templates/\` — reusable workflow definition packages (roles + ModeratorTable), no agent binding
 - \`workflows/\` — workflow instances that bind templates to agents and export \`run\` + \`descriptor\`
 
 ## Commands
@@ -184,32 +194,100 @@ uncaged-workflow init workspace ${workspaceName}
 `;
 }
 
+function bundleTs(): string {
+  return [
+    'import { mkdir, readdir, writeFile } from "node:fs/promises";',
+    'import { join } from "node:path";',
+    "",
+    'const rootDir = join(import.meta.dir, "..");',
+    'const workflowsDir = join(rootDir, "workflows");',
+    'const distDir = join(rootDir, "dist");',
+    "",
+    "function isEntryFile(name: string): boolean {",
+    '  return name.endsWith("-entry.ts");',
+    "}",
+    "",
+    "function entryStem(name: string): string {",
+    '  return name.slice(0, -".ts".length);',
+    "}",
+    "",
+    "async function main(): Promise<void> {",
+    "  await mkdir(distDir, { recursive: true });",
+    "  let files: string[];",
+    "  try {",
+    "    files = await readdir(workflowsDir);",
+    "  } catch {",
+    '    console.error("bundle: missing workflows/ directory");',
+    "    process.exitCode = 1;",
+    "    return;",
+    "  }",
+    "  const entries = files.filter(isEntryFile);",
+    "  if (entries.length === 0) {",
+    '    console.warn("bundle: no *-entry.ts files under workflows/");',
+    "    return;",
+    "  }",
+    "  for (const file of entries) {",
+    "    const stem = entryStem(file);",
+    "    const entryPath = join(workflowsDir, file);",
+    "    const result = await Bun.build({",
+    "      entrypoints: [entryPath],",
+    "      outdir: distDir,",
+    '      format: "esm",',
+    '      target: "node",',
+    "      splitting: false,",
+    '      naming: { entry: "[name].esm.js" },',
+    "    });",
+    "    if (!result.success) {",
+    "      for (const log of result.logs) {",
+    "        console.error(log);",
+    "      }",
+    `      throw new Error(\`bundle failed for \${file}\`);`,
+    "    }",
+    "    const dts =",
+    `      'export { run, descriptor } from "../workflows/' + stem + '.js";\\n';`,
+    `    await writeFile(join(distDir, \`\${stem}.d.ts\`), dts, "utf8");`,
+    `    console.log(\`bundle: \${stem} -> dist/\${stem}.esm.js\`);`,
+    "  }",
+    "}",
+    "",
+    "await main();",
+    "",
+  ].join("\n");
+}
+
 export async function cmdInitWorkspace(
   parentDir: string,
   workspaceName: string,
 ): Promise<Result<CmdInitWorkspaceSuccess, string>> {
-  const validated = validateWorkspaceSegment(workspaceName);
-  if (!validated.ok) {
-    return validated;
+  // Accept a relative/absolute path: resolve it and derive the dir name for package.json.
+  const resolved = resolve(parentDir, workspaceName);
+  const rootPath = resolved;
+  const dirName = basename(resolved);
+
+  if (dirName === "" || dirName === "." || dirName === "..") {
+    return err(`invalid workspace path: ${workspaceName}`);
   }
 
-  const rootPath = join(parentDir, workspaceName);
   if (await pathExists(rootPath)) {
     return err(`directory already exists: ${rootPath}`);
   }
 
-  await mkdir(rootPath, { recursive: false });
-  await mkdir(join(rootPath, "templates"), { recursive: false });
-  await mkdir(join(rootPath, "workflows"), { recursive: false });
+  await mkdir(rootPath, { recursive: true });
+  await mkdir(join(rootPath, "templates"), { recursive: true });
+  await mkdir(join(rootPath, "workflows"), { recursive: true });
+  await mkdir(join(rootPath, "scripts"), { recursive: true });
 
   await Promise.all([
-    writeFile(join(rootPath, "package.json"), rootPackageJson(workspaceName), "utf8"),
+    writeFile(join(rootPath, "package.json"), rootPackageJson(dirName), "utf8"),
     writeFile(join(rootPath, "biome.json"), biomeJson(), "utf8"),
     writeFile(join(rootPath, "tsconfig.json"), tsconfigJson(), "utf8"),
     writeFile(join(rootPath, "AGENTS.md"), agentsMd(), "utf8"),
-    writeFile(join(rootPath, "README.md"), readmeMd(workspaceName), "utf8"),
+    writeFile(join(rootPath, "README.md"), readmeMd(dirName), "utf8"),
     writeFile(join(rootPath, "templates", ".gitkeep"), "", "utf8"),
     writeFile(join(rootPath, "workflows", "package.json"), workflowsPackageJson(), "utf8"),
+    writeFile(join(rootPath, "workflows", ".gitkeep"), "", "utf8"),
+    writeFile(join(rootPath, "bunfig.toml"), bunfigToml(), "utf8"),
+    writeFile(join(rootPath, "scripts", "bundle.ts"), bundleTs(), "utf8"),
   ]);
 
   return ok({ rootPath });

packages/cli-workflow/src/commands/serve/app.ts

@@ -1,20 +0,0 @@
-import { Hono } from "hono";
-import { cors } from "hono/cors";
-
-import { createCasRoutes } from "./routes-cas.js";
-import { createThreadRoutes } from "./routes-thread.js";
-import { createWorkflowRoutes } from "./routes-workflow.js";
-
-export function createApp(storageRoot: string): Hono {
-  const app = new Hono();
-
-  app.use("*", cors());
-
-  app.get("/healthz", (c) => c.json({ ok: true }));
-
-  app.route("/api/workflows", createWorkflowRoutes(storageRoot));
-  app.route("/api/threads", createThreadRoutes(storageRoot));
-  app.route("/api/cas", createCasRoutes(storageRoot));
-
-  return app;
-}

packages/cli-workflow/src/commands/serve/index.ts

@@ -1,3 +0,0 @@
-export { createApp } from "./app.js";
-export { dispatchServe, startServer } from "./serve.js";
-export type { ServeOptions } from "./types.js";

packages/cli-workflow/src/commands/serve/routes-thread.ts

@@ -1,46 +0,0 @@
-import { Hono } from "hono";
-
-import { readTextFileIfExists } from "../../fs-utils.js";
-import {
-  listHistoricalThreads,
-  listRunningThreads,
-  resolveThreadDataPath,
-} from "../../thread-scan.js";
-
-export function createThreadRoutes(storageRoot: string): Hono {
-  const app = new Hono();
-
-  app.get("/", async (c) => {
-    const nameFilter = c.req.query("workflow") ?? null;
-    const rows = await listHistoricalThreads(storageRoot, nameFilter);
-    return c.json({ threads: rows });
-  });
-
-  app.get("/running", async (c) => {
-    const rows = await listRunningThreads(storageRoot);
-    return c.json({ threads: rows });
-  });
-
-  app.get("/:threadId", async (c) => {
-    const threadId = c.req.param("threadId");
-    const dataPath = await resolveThreadDataPath(storageRoot, threadId);
-    if (dataPath === null) {
-      return c.json({ error: `thread not found: ${threadId}` }, 404);
-    }
-    const text = await readTextFileIfExists(dataPath);
-    if (text === null) {
-      return c.json({ error: `thread data missing: ${threadId}` }, 404);
-    }
-    const lines = text.trim().split("\n");
-    const records = lines.map((line) => {
-      try {
-        return JSON.parse(line) as unknown;
-      } catch {
-        return { raw: line };
-      }
-    });
-    return c.json({ threadId, records });
-  });
-
-  return app;
-}

packages/cli-workflow/src/commands/serve/serve.ts

@@ -1,69 +0,0 @@
-import { err, ok, type Result } from "@uncaged/workflow";
-import { serve } from "bun";
-
-import { printCliLine } from "../../cli-output.js";
-import { createApp } from "./app.js";
-import type { ServeOptions } from "./types.js";
-
-export function startServer(storageRoot: string, options: ServeOptions): void {
-  const app = createApp(storageRoot);
-
-  const server = serve({
-    fetch: app.fetch,
-    port: options.port,
-    hostname: options.hostname,
-  });
-
-  printCliLine(`uncaged-workflow API server listening on http://${server.hostname}:${server.port}`);
-}
-
-function parsePortValue(value: string | undefined): Result<number, string> {
-  if (value === undefined) {
-    return err("--port requires a value");
-  }
-  const parsed = Number.parseInt(value, 10);
-  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 65535) {
-    return err(`invalid port: ${value}`);
-  }
-  return ok(parsed);
-}
-
-function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
-  let port = 7860;
-  let hostname = "127.0.0.1";
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--port" || arg === "-p") {
-      const portResult = parsePortValue(argv[i + 1]);
-      if (!portResult.ok) {
-        return portResult;
-      }
-      port = portResult.value;
-      i++;
-    } else if (arg === "--host") {
-      const next = argv[i + 1];
-      if (next === undefined) {
-        return err("--host requires a value");
-      }
-      hostname = next;
-      i++;
-    }
-  }
-
-  return ok({ port, hostname });
-}
-
-export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseServeArgv(argv);
-  if (!parsed.ok) {
-    printCliLine(`error: ${parsed.error}`);
-    return 1;
-  }
-
-  startServer(storageRoot, parsed.value);
-
-  // Keep process alive
-  await new Promise(() => {});
-  return 0;
-}

packages/cli-workflow/src/commands/serve/types.ts

@@ -1,4 +0,0 @@
-export type ServeOptions = {
-  port: number;
-  hostname: string;
-};

packages/cli-workflow/src/commands/setup/dispatch.ts

@@ -0,0 +1,451 @@
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+
+import { createLogger } from "@uncaged/workflow-util";
+
+import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
+
+const setupDispatchLog = createLogger({ sink: { kind: "stderr" } });
+
+import { loadPresetProviders } from "./preset-providers.js";
+import { cmdSetup, printSetupSummary } from "./setup.js";
+import type { SetupCliArgs } from "./types.js";
+
+type OpenAiModelEntry = {
+  id: string;
+};
+
+type OpenAiModelsResponse = {
+  data: OpenAiModelEntry[];
+};
+
+function usageSetup(): string {
+  return [
+    "uncaged-workflow setup — configure workflow.yaml providers and default model",
+    "",
+    "Non-interactive (agent mode):",
+    "  uncaged-workflow setup \\",
+    "    --provider <name> \\",
+    "    --base-url <url> \\",
+    "    --api-key <key> \\",
+    "    --default-model <provider/model> \\",
+    "    [--init-workspace <name>]",
+    "",
+    "Interactive: run with no flags (prompts for each value).",
+    "",
+    "Storage: uses the same root as other commands (see UNCAGED_WORKFLOW_STORAGE_ROOT).",
+  ].join("\n");
+}
+
+function requireNext(argv: string[], i: number, flag: string): Result<string, string> {
+  const next = argv[i + 1];
+  if (next === undefined || next.startsWith("--")) {
+    return err(`${flag} requires a value`);
+  }
+  return ok(next);
+}
+
+type ParsedSetup = SetupCliArgs | "interactive" | "help";
+
+type SetupFlagField = "provider" | "baseUrl" | "apiKey" | "defaultModel" | "initWorkspaceName";
+
+const SETUP_FLAG_TO_FIELD: Record<string, SetupFlagField> = {
+  "--provider": "provider",
+  "--base-url": "baseUrl",
+  "--api-key": "apiKey",
+  "--default-model": "defaultModel",
+  "--init-workspace": "initWorkspaceName",
+};
+
+function emptyFlagState(): Record<SetupFlagField, string | null> {
+  return {
+    provider: null,
+    baseUrl: null,
+    apiKey: null,
+    defaultModel: null,
+    initWorkspaceName: null,
+  };
+}
+
+function finalizeParsedSetup(
+  state: Record<SetupFlagField, string | null>,
+): Result<ParsedSetup, string> {
+  const hasAnyFlag =
+    state.provider !== null ||
+    state.baseUrl !== null ||
+    state.apiKey !== null ||
+    state.defaultModel !== null ||
+    state.initWorkspaceName !== null;
+
+  if (!hasAnyFlag) {
+    return ok("interactive");
+  }
+
+  if (state.provider === null) {
+    return err(
+      "non-interactive setup requires --provider (or omit all flags for interactive mode)",
+    );
+  }
+
+  const missing: string[] = [];
+  if (state.baseUrl === null) {
+    missing.push("--base-url");
+  }
+  if (state.apiKey === null) {
+    missing.push("--api-key");
+  }
+  if (state.defaultModel === null) {
+    missing.push("--default-model");
+  }
+  if (missing.length > 0) {
+    return err(`missing required flag(s): ${missing.join(", ")}`);
+  }
+
+  const b = state.baseUrl;
+  const k = state.apiKey;
+  const m = state.defaultModel;
+  if (b === null || k === null || m === null) {
+    return err("internal: missing required flags after validation");
+  }
+
+  return ok({
+    provider: state.provider,
+    baseUrl: b,
+    apiKey: k,
+    defaultModel: m,
+    initWorkspaceName: state.initWorkspaceName,
+  });
+}
+
+function parseSetupArgv(argv: string[]): Result<ParsedSetup, string> {
+  const state = emptyFlagState();
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === undefined) {
+      break;
+    }
+    if (tok === "--help" || tok === "-h") {
+      return ok("help");
+    }
+    const field = SETUP_FLAG_TO_FIELD[tok];
+    if (field === undefined) {
+      return err(`unknown argument: ${tok}`);
+    }
+    const v = requireNext(argv, i, tok);
+    if (!v.ok) {
+      return v;
+    }
+    state[field] = v.value;
+    i++;
+  }
+
+  return finalizeParsedSetup(state);
+}
+
+async function promptLine(
+  rl: { question: (q: string) => Promise<string> },
+  label: string,
+): Promise<string> {
+  const raw = await rl.question(label);
+  return raw.trim();
+}
+
+type SecretInputState = {
+  buf: string;
+  rawWasSet: boolean;
+  onData: (chunk: string) => void;
+  fulfill: (value: string) => void;
+};
+
+function isLineTerminator(c: string): boolean {
+  return c === "\n" || c === "\r" || c === "\u0004";
+}
+
+function handleLineTerminator(state: SecretInputState): void {
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(state.rawWasSet);
+  }
+  process.stdin.pause();
+  process.stdin.removeListener("data", state.onData);
+  process.stdout.write("\n");
+  state.fulfill(state.buf.trim());
+}
+
+function handleBackspace(state: SecretInputState): void {
+  if (state.buf.length > 0) {
+    state.buf = state.buf.slice(0, -1);
+    process.stdout.write("\b \b");
+  }
+}
+
+function handleInterrupt(rawWasSet: boolean): void {
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(rawWasSet);
+  }
+  process.exit(130);
+}
+
+function isBackspace(c: string): boolean {
+  return c === "\u007F" || c === "\b";
+}
+
+/** Process a single character in secret input. Returns "done" to stop reading. */
+function processSecretChar(c: string, state: SecretInputState): "done" | "skip" | "append" {
+  if (isLineTerminator(c)) {
+    handleLineTerminator(state);
+    return "done";
+  }
+  if (isBackspace(c)) {
+    handleBackspace(state);
+    return "skip";
+  }
+  if (c === "\u0003") {
+    handleInterrupt(state.rawWasSet);
+  }
+  state.buf += c;
+  process.stdout.write("*");
+  return "append";
+}
+
+/** Read a line with terminal echo disabled (for secrets). */
+async function promptSecret(label: string): Promise<string> {
+  process.stdout.write(label);
+  return new Promise((fulfill) => {
+    const rawWasSet = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const state: SecretInputState = { buf: "", rawWasSet, fulfill, onData: () => {} };
+
+    const onData = (chunk: string) => {
+      for (const c of chunk.toString()) {
+        if (processSecretChar(c, state) === "done") return;
+      }
+    };
+
+    state.onData = onData;
+    process.stdin.on("data", onData);
+  });
+}
+
+/** Fetch available models from an OpenAI-compatible /models endpoint. */
+async function fetchAvailableModels(baseUrl: string, apiKey: string): Promise<string[]> {
+  const url = `${baseUrl.replace(/\/+$/, "")}/models`;
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      setupDispatchLog("R5KH7WM3", `GET ${url} returned ${res.status}`);
+      return [];
+    }
+    const body = (await res.json()) as OpenAiModelsResponse;
+    if (!Array.isArray(body.data)) {
+      return [];
+    }
+    // Filter out non-chat models. Some patterns are DashScope-specific (sambert, cosyvoice,
+    // wordart, wanx, wan2, paraformer) but harmless for other providers.
+    const NON_CHAT_RE =
+      /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|z-image|s2s|livetranslate|realtime|gui-/i;
+    return body.data
+      .map((m) => m.id)
+      .filter((id) => !NON_CHAT_RE.test(id))
+      .sort();
+  } catch (e) {
+    setupDispatchLog(
+      "V8NQ4JT6",
+      `fetch models failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return [];
+  }
+}
+
+type PresetProvider = ReturnType<typeof loadPresetProviders>[number];
+
+function printProviderMenu(presets: readonly PresetProvider[]): void {
+  const numWidth = String(presets.length + 1).length;
+  printCliLine("Select a provider:\n");
+  for (let i = 0; i < presets.length; i++) {
+    const p = presets.at(i);
+    if (!p) continue;
+    const num = String(i + 1).padStart(numWidth);
+    printCliLine(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
+  }
+  const customNum = String(presets.length + 1).padStart(numWidth);
+  printCliLine(`  ${customNum}) Custom (enter name and URL manually)`);
+  printCliLine("");
+}
+
+async function selectProvider(
+  rl: { question: (q: string) => Promise<string> },
+  presets: readonly PresetProvider[],
+): Promise<Result<{ provider: string; baseUrl: string }, string>> {
+  const choice = await promptLine(rl, `Choose [1-${presets.length + 1}]: `);
+  const choiceNum = Number.parseInt(choice, 10);
+  if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > presets.length + 1) {
+    return err(`invalid choice: ${choice}`);
+  }
+
+  if (choiceNum <= presets.length) {
+    const selected = presets.at(choiceNum - 1);
+    if (!selected) return err(`invalid choice: ${choice}`);
+    printCliLine(`\n  → ${selected.label} (${selected.baseUrl})\n`);
+    return ok({ provider: selected.name, baseUrl: selected.baseUrl });
+  }
+
+  const provider = await promptLine(rl, "Provider name (e.g. my-proxy): ");
+  if (provider === "") return err("provider name must not be empty");
+  const baseUrl = await promptLine(rl, "OpenAI-compatible API base URL: ");
+  if (baseUrl === "") return err("base URL must not be empty");
+  return ok({ provider, baseUrl });
+}
+
+function printModelList(models: string[]): void {
+  const cols = process.stdout.columns || 80;
+  const nw = String(models.length).length;
+  const prefixLen = nw + 4;
+  const maxModelLen = Math.max(...models.map((m) => m.length));
+  const cellWidth = prefixLen + maxModelLen + 2;
+  const numCols = Math.max(1, Math.floor(cols / cellWidth));
+  for (let i = 0; i < models.length; i += numCols) {
+    const cells: string[] = [];
+    for (let j = i; j < Math.min(i + numCols, models.length); j++) {
+      const num = String(j + 1).padStart(nw);
+      const model = models.at(j) ?? "";
+      cells.push(`  ${num}) ${model.padEnd(maxModelLen + 2)}`);
+    }
+    printCliLine(cells.join(""));
+  }
+}
+
+async function selectModel(
+  rl: { question: (q: string) => Promise<string> },
+  models: string[],
+): Promise<Result<string, string>> {
+  if (models.length > 0) {
+    printCliLine(`\nAvailable models (${models.length}):\n`);
+    printModelList(models);
+    printCliLine(`\nChoose a number, or type a model name directly.`);
+    const modelInput = await promptLine(rl, `Default model [1-${models.length}]: `);
+    if (modelInput === "") return err("default model must not be empty");
+    const modelNum = Number.parseInt(modelInput, 10);
+    if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+      return ok(models.at(modelNum - 1) ?? modelInput);
+    }
+    return ok(modelInput);
+  }
+
+  printCliWarn("Could not fetch models (API may not support /models endpoint).");
+  const modelInput = await promptLine(rl, `Default model (e.g. qwen-plus, gpt-4o): `);
+  if (modelInput === "") return err("default model must not be empty");
+  return ok(modelInput);
+}
+
+async function selectWorkspace(rl: {
+  question: (q: string) => Promise<string>;
+}): Promise<string | null> {
+  while (true) {
+    const wsPath = await promptLine(
+      rl,
+      "\nWorkflow workspace path (default: ./workflows, type 'skip' to skip): ",
+    );
+    if (wsPath.toLowerCase() === "skip") return null;
+    const candidate = wsPath === "" ? "./workflows" : wsPath;
+    const resolved = resolvePath(process.cwd(), candidate);
+    if (existsSync(resolved)) {
+      printCliWarn(`directory already exists: ${resolved}`);
+      printCliLine("Please enter a different path, or type 'skip' to skip.");
+      continue;
+    }
+    return candidate;
+  }
+}
+
+function stripProviderPrefix(model: string): string {
+  if (model.includes("/")) {
+    return model.split("/").pop() ?? model;
+  }
+  return model;
+}
+
+async function collectInteractiveSetup(): Promise<Result<SetupCliArgs, string>> {
+  const rl = createInterface({ input, output });
+  try {
+    printCliLine("Configure the LLM provider that workflow agents will use.\n");
+
+    const presets = loadPresetProviders();
+    printProviderMenu(presets);
+
+    const providerResult = await selectProvider(rl, presets);
+    if (!providerResult.ok) {
+      rl.close();
+      return providerResult;
+    }
+    const { provider, baseUrl } = providerResult.value;
+
+    rl.close();
+    const apiKey = await promptSecret("API key for this provider: ");
+    if (apiKey === "") return err("API key must not be empty");
+    const rl2 = createInterface({ input, output });
+
+    printCliLine("\nFetching available models...");
+    const models = await fetchAvailableModels(baseUrl, apiKey);
+    const modelResult = await selectModel(rl2, models);
+    if (!modelResult.ok) {
+      rl2.close();
+      return modelResult;
+    }
+
+    const bare = stripProviderPrefix(modelResult.value);
+    const defaultModel = `${provider}/${bare}`;
+    printCliLine(`  → ${defaultModel}`);
+
+    const initWorkspaceName = await selectWorkspace(rl2);
+    rl2.close();
+
+    return ok({ provider, baseUrl, apiKey, defaultModel, initWorkspaceName });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}
+
+export async function dispatchSetup(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseSetupArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${parsed.error}\n\n${usageSetup()}`);
+    return 1;
+  }
+  if (parsed.value === "help") {
+    printCliLine(usageSetup());
+    return 0;
+  }
+
+  let args: SetupCliArgs;
+  if (parsed.value === "interactive") {
+    const collected = await collectInteractiveSetup();
+    if (!collected.ok) {
+      printCliError(collected.error);
+      return 1;
+    }
+    args = collected.value;
+  } else {
+    args = parsed.value;
+  }
+
+  const result = await cmdSetup(storageRoot, args);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printSetupSummary(result.value);
+  return 0;
+}

packages/cli-workflow/src/commands/setup/index.ts

@@ -0,0 +1,4 @@
+export { dispatchSetup } from "./dispatch.js";
+export { loadPresetProviders } from "./preset-providers.js";
+export { cmdSetup, printSetupSummary } from "./setup.js";
+export type { CmdSetupSuccess, PresetProvider, SetupCliArgs } from "./types.js";

packages/cli-workflow/src/commands/setup/preset-providers.ts

@@ -0,0 +1,47 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import type { PresetProvider } from "./types.js";
+
+type RawPresetEntry = {
+  name: unknown;
+  label: unknown;
+  baseUrl: unknown;
+};
+
+function isRawEntry(v: unknown): v is RawPresetEntry {
+  if (typeof v !== "object" || v === null) return false;
+  const o = v as Record<string, unknown>;
+  return typeof o.name === "string" && typeof o.label === "string" && typeof o.baseUrl === "string";
+}
+
+let cached: ReadonlyArray<PresetProvider> | null = null;
+
+export function loadPresetProviders(): ReadonlyArray<PresetProvider> {
+  if (cached !== null) return cached;
+
+  const yamlPath = join(import.meta.dirname, "providers.yaml");
+  const raw = readFileSync(yamlPath, "utf8");
+  const parsed: unknown = parseYaml(raw);
+
+  if (!Array.isArray(parsed)) {
+    throw new Error(`providers.yaml: expected array, got ${typeof parsed}`);
+  }
+
+  const result: PresetProvider[] = [];
+  for (const entry of parsed) {
+    if (!isRawEntry(entry)) {
+      throw new Error(`providers.yaml: invalid entry: ${JSON.stringify(entry)}`);
+    }
+    result.push({
+      name: entry.name as string,
+      label: entry.label as string,
+      baseUrl: entry.baseUrl as string,
+    });
+  }
+
+  cached = result;
+  return result;
+}

packages/cli-workflow/src/commands/setup/providers.yaml

@@ -0,0 +1,73 @@
+# Preset LLM providers for `uncaged-workflow setup`.
+# Each entry needs a provider name (used in workflow.yaml) and an OpenAI-compatible base URL.
+# Add new providers here — no code changes required.
+
+# ── International ──────────────────────────────────────────
+
+- name: openai
+  label: OpenAI
+  baseUrl: https://api.openai.com/v1
+
+- name: xai
+  label: xAI
+  baseUrl: https://api.x.ai/v1
+
+- name: openrouter
+  label: OpenRouter
+  baseUrl: https://openrouter.ai/api/v1
+
+- name: venice
+  label: Venice
+  baseUrl: https://api.venice.ai/api/v1
+
+# ── China ──────────────────────────────────────────────────
+
+- name: dashscope
+  label: DashScope (Alibaba)
+  baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+
+- name: deepseek
+  label: DeepSeek
+  baseUrl: https://api.deepseek.com/v1
+
+- name: siliconflow
+  label: SiliconFlow
+  baseUrl: https://api.siliconflow.cn/v1
+
+- name: volcengine
+  label: Volcengine (ByteDance)
+  baseUrl: https://ark.cn-beijing.volces.com/api/v3
+
+- name: kimi
+  label: Kimi (Moonshot)
+  baseUrl: https://api.moonshot.cn/v1
+
+- name: glm
+  label: GLM (Zhipu AI)
+  baseUrl: https://open.bigmodel.cn/api/paas/v4
+
+- name: glm-intl
+  label: GLM (Zhipu AI Intl)
+  baseUrl: https://api.z.ai/api/paas/v4
+
+- name: stepfun
+  label: StepFun
+  baseUrl: https://api.stepfun.com/v1
+
+- name: minimax
+  label: MiniMax
+  baseUrl: https://api.minimax.io/v1
+
+- name: tencent
+  label: Tencent TokenHub
+  baseUrl: https://tokenhub.tencentmaas.com/v1
+
+- name: xiaomi
+  label: Xiaomi MiMo
+  baseUrl: https://api.xiaomimimo.com/v1
+
+# ── Local ──────────────────────────────────────────────────
+
+- name: ollama
+  label: Ollama (local)
+  baseUrl: http://localhost:11434/v1

packages/cli-workflow/src/commands/setup/setup.ts

@@ -0,0 +1,103 @@
+import { err, ok, type Result, type WorkflowConfig } from "@uncaged/workflow-protocol";
+import {
+  readWorkflowRegistry,
+  splitProviderModelRef,
+  workflowRegistryPath,
+  writeWorkflowRegistry,
+} from "@uncaged/workflow-register";
+import { createLogger } from "@uncaged/workflow-util";
+
+import { printCliLine } from "../../cli-output.js";
+import { cmdInitWorkspace } from "../init/index.js";
+import type { CmdSetupSuccess, SetupCliArgs } from "./types.js";
+
+const setupLog = createLogger({ sink: { kind: "stderr" } });
+
+function mergeWorkflowConfig(
+  prev: WorkflowConfig | null,
+  input: SetupCliArgs,
+): Result<WorkflowConfig, string> {
+  const modelSplit = splitProviderModelRef(input.defaultModel);
+  if (!modelSplit.ok) {
+    return err(modelSplit.error);
+  }
+  if (modelSplit.value.providerName !== input.provider) {
+    return err(
+      `default model provider "${modelSplit.value.providerName}" must match --provider "${input.provider}"`,
+    );
+  }
+
+  const maxDepth = prev === null ? 3 : prev.maxDepth;
+  const supervisorInterval = prev === null ? 3 : prev.supervisorInterval;
+  const providers = {
+    ...(prev === null ? {} : prev.providers),
+    [input.provider]: { baseUrl: input.baseUrl, apiKey: input.apiKey },
+  };
+  const models = { ...(prev === null ? {} : prev.models), default: input.defaultModel };
+
+  return ok({
+    maxDepth,
+    supervisorInterval,
+    providers,
+    models,
+  });
+}
+
+export async function cmdSetup(
+  storageRoot: string,
+  input: SetupCliArgs,
+): Promise<Result<CmdSetupSuccess, string>> {
+  const readResult = await readWorkflowRegistry(storageRoot);
+  if (!readResult.ok) {
+    setupLog("W8JH4Q2K", `read workflow registry failed: ${readResult.error.message}`);
+    return err(readResult.error.message);
+  }
+
+  const current = readResult.value;
+  const merged = mergeWorkflowConfig(current.config, input);
+  if (!merged.ok) {
+    return merged;
+  }
+  const nextConfig = merged.value;
+  const nextRegistry = {
+    config: nextConfig,
+    workflows: current.workflows,
+  };
+
+  const written = await writeWorkflowRegistry(storageRoot, nextRegistry);
+  if (!written.ok) {
+    setupLog("M2NB5VX9", `write workflow registry failed: ${written.error.message}`);
+    return err(written.error.message);
+  }
+
+  const registryPath = workflowRegistryPath(storageRoot);
+
+  let initWorkspaceRootPath: string | null = null;
+  if (input.initWorkspaceName !== null) {
+    const initResult = await cmdInitWorkspace(process.cwd(), input.initWorkspaceName);
+    if (!initResult.ok) {
+      setupLog("T7QC4HWP", `init workspace failed: ${initResult.error}`);
+      return err(initResult.error);
+    }
+    initWorkspaceRootPath = initResult.value.rootPath;
+  }
+
+  return ok({
+    registryPath,
+    provider: input.provider,
+    defaultModel: input.defaultModel,
+    maxDepth: nextConfig.maxDepth,
+    supervisorInterval: nextConfig.supervisorInterval,
+    initWorkspaceRootPath,
+  });
+}
+
+export function printSetupSummary(result: CmdSetupSuccess): void {
+  printCliLine(`wrote registry: ${result.registryPath}`);
+  printCliLine(`provider "${result.provider}" (baseUrl + apiKey updated)`);
+  printCliLine(`config.models.default = "${result.defaultModel}"`);
+  printCliLine(`maxDepth=${result.maxDepth}, supervisorInterval=${result.supervisorInterval}`);
+  if (result.initWorkspaceRootPath !== null) {
+    printCliLine(`initialized workflow workspace at ${result.initWorkspaceRootPath}`);
+  }
+}

packages/cli-workflow/src/commands/setup/types.ts

@@ -0,0 +1,23 @@
+/** Parsed non-interactive `setup` CLI arguments (all fields required for agent mode). */
+export type SetupCliArgs = {
+  provider: string;
+  baseUrl: string;
+  apiKey: string;
+  defaultModel: string;
+  initWorkspaceName: string | null;
+};
+
+export type PresetProvider = {
+  name: string;
+  label: string;
+  baseUrl: string;
+};
+
+export type CmdSetupSuccess = {
+  registryPath: string;
+  provider: string;
+  defaultModel: string;
+  maxDepth: number;
+  supervisorInterval: number;
+  initWorkspaceRootPath: string | null;
+};

packages/cli-workflow/src/commands/thread/control.ts

@@ -1,4 +1,4 @@
-import type { Result } from "@uncaged/workflow";
+import type { Result } from "@uncaged/workflow-protocol";
 
 import {
   readWorkerCtl,

packages/cli-workflow/src/commands/thread/dispatch.ts

@@ -26,12 +26,7 @@ export async function dispatchRun(storageRoot: string, argv: string[]): Promise<
     return 1;
   }
 
-  const result = await cmdRun(
-    storageRoot,
-    parsed.value.name,
-    parsed.value.prompt,
-    parsed.value.maxRounds,
-  );
+  const result = await cmdRun(storageRoot, parsed.value.name, parsed.value.prompt);
   if (!result.ok) {
     printCliError(result.error);
     return 1;
@@ -166,7 +161,7 @@ export async function dispatchFork(storageRoot: string, argv: string[]): Promise
 export const THREAD_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
   run: {
     handler: dispatchRun,
-    args: "<name> [--prompt <text>] [--max-rounds N]",
+    args: "<name> [--prompt <text>]",
     description: "Start a new thread executing a workflow",
   },
   list: {

packages/cli-workflow/src/commands/thread/fork-argv.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import type { ParsedForkArgv } from "./types.js";
 

packages/cli-workflow/src/commands/thread/fork.ts

@@ -1,9 +1,11 @@
 import { join } from "node:path";
+import { createCasStore } from "@uncaged/workflow-cas";
+import { prepareCasFork } from "@uncaged/workflow-execute";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { generateUlid, getGlobalCasDir } from "@uncaged/workflow-util";
 
-import { buildForkPlan, err, generateUlid, ok, type Result } from "@uncaged/workflow";
-
-import { pathExists, readTextFileIfExists } from "../../fs-utils.js";
-import { resolveThreadDataPath } from "../../thread-scan.js";
+import { pathExists } from "../../fs-utils.js";
+import { resolveThreadRecord } from "../../thread-scan.js";
 import { ensureWorkerForHash, sendWorkerTcpCommand } from "../../worker-spawn.js";
 
 export async function cmdFork(
@@ -11,49 +13,51 @@ export async function cmdFork(
   threadId: string,
   fromRole: string | null,
 ): Promise<Result<{ threadId: string }, string>> {
-  const dataPath = await resolveThreadDataPath(storageRoot, threadId);
-  if (dataPath === null) {
+  const resolved = await resolveThreadRecord(storageRoot, threadId);
+  if (resolved === null) {
     return err(`thread not found: ${threadId}`);
   }
-  const text = await readTextFileIfExists(dataPath);
-  if (text === null) {
-    return err(`thread data missing: ${threadId}`);
+
+  const bundlePath = join(storageRoot, "bundles", `${resolved.bundleHash}.esm.js`);
+  if (!(await pathExists(bundlePath))) {
+    return err(`bundle file missing for thread hash ${resolved.bundleHash}`);
   }
 
-  const plan = buildForkPlan(text, fromRole);
+  const cas = createCasStore(getGlobalCasDir(storageRoot));
+  const newThreadId = generateUlid(Date.now());
+
+  const plan = await prepareCasFork({
+    cas,
+    bundleDir: resolved.bundleDir,
+    bundleHash: resolved.bundleHash,
+    sourceThreadId: threadId,
+    headHash: resolved.head,
+    startHash: resolved.start,
+    newThreadId,
+    fromRole,
+  });
   if (!plan.ok) {
     return plan;
   }
 
-  const bundlePath = join(storageRoot, "bundles", `${plan.value.hash}.esm.js`);
-  if (!(await pathExists(bundlePath))) {
-    return err(`bundle file missing for thread hash ${plan.value.hash}`);
-  }
-
   const worker = await ensureWorkerForHash(storageRoot, plan.value.hash, bundlePath);
   if (!worker.ok) {
     return worker;
   }
 
-  const newThreadId = generateUlid(Date.now());
-  const stepsOnWire = plan.value.historicalSteps.map((s) => ({
-    role: s.role,
-    contentHash: s.contentHash,
-    meta: s.meta,
-    refs: s.refs,
-    timestamp: s.timestamp,
-  }));
-
+  const p = plan.value;
   const sent = await sendWorkerTcpCommand(
     worker.value.port,
     {
       type: "run",
       threadId: newThreadId,
-      workflowName: plan.value.workflowName,
-      prompt: plan.value.prompt,
-      options: plan.value.runOptions,
-      steps: stepsOnWire,
-      forkSourceThreadId: plan.value.sourceThreadId,
+      workflowName: p.workflowName,
+      prompt: p.prompt,
+      options: p.runOptions,
+      steps: p.steps,
+      stepTimestamps: p.stepTimestamps.length > 0 ? p.stepTimestamps : null,
+      forkSourceThreadId: threadId,
+      forkContinuation: p.forkContinuation,
     },
     { awaitResponseLine: false },
   );

packages/cli-workflow/src/commands/thread/list.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { listHistoricalThreads } from "../../thread-scan.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";

packages/cli-workflow/src/commands/thread/live.ts

@@ -1,22 +1,26 @@
 import { watch } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-
+import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
 import {
-  type CasStore,
-  createCasStore,
-  getContentMerklePayload,
-  getGlobalCasDir,
-  tryParseRoleStepRecord,
-  tryParseWorkflowResultRecord,
-} from "@uncaged/workflow";
-import type { WorkflowCompletion } from "@uncaged/workflow-runtime";
+  FORK_BRANCH_ROLE,
+  readThreadsIndex,
+  type ThreadIndex,
+  walkStateFramesNewestFirst,
+} from "@uncaged/workflow-execute";
+import type { CasStore, WorkflowCompletion } from "@uncaged/workflow-protocol";
+import { END } from "@uncaged/workflow-runtime";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 import { dimGreyLine, highlightLiveRole } from "../../cli-color.js";
 import { printCliError, printCliLine } from "../../cli-output.js";
 import { pathExists } from "../../fs-utils.js";
 import type { ParsedLiveArgv } from "../../live-argv.js";
-import { findLatestThreadDataPath, resolveThreadDataPath } from "../../thread-scan.js";
+import {
+  findLatestThreadBundleTarget,
+  type LatestThreadTarget,
+  resolveThreadRecord,
+} from "../../thread-scan.js";
 import type { LiveRoleRow } from "./types.js";
 
 export const LIVE_CONTENT_MAX_LINES = 10;
@@ -54,16 +58,15 @@ function printSummary(result: WorkflowCompletion): void {
   printCliLine(`completed: returnCode=${result.returnCode} — ${result.summary}`);
 }
 
-type LiveSessionState = {
-  sawStart: boolean;
-  completed: boolean;
+type InfoLiveState = {
   carry: string;
   contentOffset: number;
 };
 
-type InfoLiveState = {
-  carry: string;
-  contentOffset: number;
+type CasLiveState = {
+  printedHashes: Set<string>;
+  lastHead: string | null;
+  completionEmitted: boolean;
 };
 
 function tryParseInfoRecord(obj: Record<string, unknown>): {
@@ -85,102 +88,140 @@ function tryParseInfoRecord(obj: Record<string, unknown>): {
   return { tag, content, timestamp };
 }
 
-async function handleJsonlLine(
-  rawLine: string,
-  state: LiveSessionState,
-  roleFilter: string | null,
-  cas: CasStore,
-): Promise<{ parseError: string | null; workflowResult: WorkflowCompletion | null }> {
-  const trimmed = rawLine.trim();
-  if (trimmed === "") {
-    return { parseError: null, workflowResult: null };
+function completionFromEndMeta(meta: Record<string, unknown>): WorkflowCompletion | null {
+  const returnCode = meta.returnCode;
+  const summary = meta.summary;
+  if (typeof returnCode !== "number" || typeof summary !== "string") {
+    return null;
   }
+  return { returnCode, summary };
+}
 
-  let rec: unknown;
-  try {
-    rec = JSON.parse(trimmed) as unknown;
-  } catch {
-    return { parseError: "invalid JSON in thread data file", workflowResult: null };
+async function emitRoleStepPrint(params: {
+  cas: CasStore;
+  role: string;
+  contentHash: string;
+  meta: Record<string, unknown>;
+  timestamp: number;
+  roleFilter: string | null;
+}): Promise<void> {
+  if (params.roleFilter !== null && params.role !== params.roleFilter) {
+    return;
   }
-  if (rec === null || typeof rec !== "object") {
-    return { parseError: "invalid record in thread data file", workflowResult: null };
-  }
-  const obj = rec as Record<string, unknown>;
-
-  if (!state.sawStart) {
-    state.sawStart = true;
-    return { parseError: null, workflowResult: null };
-  }
-
-  const wf = tryParseWorkflowResultRecord(obj);
-  if (wf !== null) {
-    state.completed = true;
-    return { parseError: null, workflowResult: wf };
-  }
-
-  const roleRow = tryParseRoleStepRecord(obj);
-  if (roleRow === null) {
-    return {
-      parseError: "unrecognized record in thread data (expected role step or result)",
-      workflowResult: null,
-    };
-  }
-
-  if (roleFilter !== null && roleRow.role !== roleFilter) {
-    return { parseError: null, workflowResult: null };
-  }
-
-  const payload = await getContentMerklePayload(cas, roleRow.contentHash);
+  const payload = await getContentMerklePayload(params.cas, params.contentHash);
   const content =
-    payload !== null ? payload : `(content not in CAS; contentHash=${roleRow.contentHash})`;
+    payload !== null ? payload : `(content not in CAS; contentHash=${params.contentHash})`;
 
   const row: LiveRoleRow = {
-    role: roleRow.role,
+    role: params.role,
     content,
-    meta: roleRow.meta,
-    timestamp: roleRow.timestamp,
+    meta: params.meta,
+    timestamp: params.timestamp,
   };
   for (const outLine of renderLiveRoleStepLines(row, highlightLiveRole(row.role))) {
     printCliLine(outLine);
   }
-  return { parseError: null, workflowResult: null };
 }
 
-async function pumpNewContent(
-  dataPath: string,
-  state: LiveSessionState,
-  roleFilter: string | null,
-  cas: CasStore,
-): Promise<number | null> {
-  let text: string;
+async function emitStatesReachableFromHead(params: {
+  cas: CasStore;
+  headHash: string;
+  state: CasLiveState;
+  roleFilter: string | null;
+}): Promise<WorkflowCompletion | null> {
+  const frames = await walkStateFramesNewestFirst(params.cas, params.headHash);
+  const chronological = [...frames].reverse();
+
+  for (const fr of chronological) {
+    if (params.state.printedHashes.has(fr.hash)) {
+      continue;
+    }
+    params.state.printedHashes.add(fr.hash);
+
+    const role = fr.payload.role;
+    if (role === FORK_BRANCH_ROLE) {
+      continue;
+    }
+
+    if (role === END) {
+      const wf = completionFromEndMeta(fr.payload.meta);
+      if (wf !== null) {
+        printSummary(wf);
+        return wf;
+      }
+      continue;
+    }
+
+    await emitRoleStepPrint({
+      cas: params.cas,
+      role,
+      contentHash: fr.payload.content,
+      meta: fr.payload.meta,
+      timestamp: fr.payload.timestamp,
+      roleFilter: params.roleFilter,
+    });
+  }
+
+  return null;
+}
+
+async function pumpThreadsJson(params: {
+  storageRoot: string;
+  bundleDir: string;
+  bundleHash: string;
+  threadId: string;
+  state: CasLiveState;
+  roleFilter: string | null;
+  cas: CasStore;
+}): Promise<number | null> {
+  let idx: ThreadIndex;
   try {
-    text = await readFile(dataPath, "utf8");
+    idx = await readThreadsIndex(params.bundleDir);
   } catch {
-    return null;
+    idx = {};
   }
 
-  if (text.length < state.contentOffset) {
-    state.contentOffset = 0;
-    state.carry = "";
+  const active = idx[params.threadId];
+
+  if (active === undefined) {
+    if (params.state.completionEmitted) {
+      return null;
+    }
+    const hist = await resolveThreadRecord(params.storageRoot, params.threadId);
+    if (hist === null || hist.source !== "history") {
+      return null;
+    }
+    params.state.completionEmitted = true;
+    const wf = await emitStatesReachableFromHead({
+      cas: params.cas,
+      headHash: hist.head,
+      state: params.state,
+      roleFilter: params.roleFilter,
+    });
+    return wf !== null ? 0 : null;
   }
 
-  const chunk = text.slice(state.contentOffset);
-  state.contentOffset = text.length;
-  state.carry += chunk;
+  const head = active.head;
+  if (params.state.lastHead === null) {
+    params.state.lastHead = head;
+    const wf = await emitStatesReachableFromHead({
+      cas: params.cas,
+      headHash: head,
+      state: params.state,
+      roleFilter: params.roleFilter,
+    });
+    return wf !== null ? 0 : null;
+  }
 
-  const parts = state.carry.split("\n");
-  state.carry = parts.pop() ?? "";
-
-  for (const line of parts) {
-    const { parseError, workflowResult } = await handleJsonlLine(line, state, roleFilter, cas);
-    if (parseError !== null) {
-      printCliError(parseError);
-      return 1;
-    }
-    if (workflowResult !== null) {
-      printSummary(workflowResult);
-      return 0;
-    }
+  if (head !== params.state.lastHead) {
+    params.state.lastHead = head;
+    const wf = await emitStatesReachableFromHead({
+      cas: params.cas,
+      headHash: head,
+      state: params.state,
+      roleFilter: params.roleFilter,
+    });
+    return wf !== null ? 0 : null;
   }
 
   return null;
@@ -297,9 +338,9 @@ function watchLivePaths(params: { tasks: WatchPumpTask[]; signal: AbortSignal })
         schedulePump(path, pump);
       });
       watchers.push(watcher);
-      watcher.on("error", (err: Error) => {
+      watcher.on("error", (errObj: Error) => {
         closeAll();
-        reject(err);
+        reject(errObj);
       });
     }
 
@@ -315,17 +356,14 @@ function watchLivePaths(params: { tasks: WatchPumpTask[]; signal: AbortSignal })
   });
 }
 
-type LiveThreadTarget = {
-  threadId: string;
-  dataPath: string;
-};
+type LiveThreadTarget = LatestThreadTarget;
 
 async function resolveLiveThreadTarget(
   storageRoot: string,
   parsed: ParsedLiveArgv,
 ): Promise<LiveThreadTarget | null> {
   if (parsed.latest) {
-    const found = await findLatestThreadDataPath(storageRoot);
+    const found = await findLatestThreadBundleTarget(storageRoot);
     if (found === null) {
       printCliError("live: no threads found");
       return null;
@@ -338,36 +376,56 @@ async function resolveLiveThreadTarget(
     printCliError("live: internal error: missing thread id");
     return null;
   }
-  const resolved = await resolveThreadDataPath(storageRoot, id);
+  const resolved = await resolveThreadRecord(storageRoot, id);
   if (resolved === null) {
     printCliError(`thread not found: ${id}`);
     return null;
   }
-  return { threadId: id, dataPath: resolved };
+  return {
+    threadId: id,
+    bundleHash: resolved.bundleHash,
+    bundleDir: resolved.bundleDir,
+    threadsJsonPath: join(resolved.bundleDir, "threads.json"),
+  };
 }
 
 async function buildLiveWatchTasks(params: {
-  dataPath: string;
-  infoPath: string;
+  storageRoot: string;
+  target: LiveThreadTarget;
   debug: boolean;
-  dataState: LiveSessionState;
+  dataState: CasLiveState;
   infoState: InfoLiveState;
   roleFilter: string | null;
   cas: CasStore;
 }): Promise<WatchPumpTask[]> {
-  const { dataPath, infoPath, debug, dataState, infoState, roleFilter, cas } = params;
+  const infoPath = join(
+    params.storageRoot,
+    "logs",
+    params.target.bundleHash,
+    `${params.target.threadId}.info.jsonl`,
+  );
+
   const tasks: WatchPumpTask[] = [
     {
-      path: dataPath,
-      pump: () => pumpNewContent(dataPath, dataState, roleFilter, cas),
+      path: params.target.threadsJsonPath,
+      pump: () =>
+        pumpThreadsJson({
+          storageRoot: params.storageRoot,
+          bundleDir: params.target.bundleDir,
+          bundleHash: params.target.bundleHash,
+          threadId: params.target.threadId,
+          state: params.dataState,
+          roleFilter: params.roleFilter,
+          cas: params.cas,
+        }),
     },
   ];
 
-  if (debug && (await pathExists(infoPath))) {
+  if (params.debug && (await pathExists(infoPath))) {
     tasks.push({
       path: infoPath,
       pump: async () => {
-        await pumpNewInfoContent(infoPath, infoState);
+        await pumpNewInfoContent(infoPath, params.infoState);
         return null;
       },
     });
@@ -382,16 +440,13 @@ export async function cmdLive(storageRoot: string, parsed: ParsedLiveArgv): Prom
     return 1;
   }
 
-  const { threadId, dataPath } = target;
   const roleFilter = parsed.role;
-  const infoPath = join(dirname(dataPath), `${threadId}.info.jsonl`);
   const cas = createCasStore(getGlobalCasDir(storageRoot));
 
-  const dataState: LiveSessionState = {
-    sawStart: false,
-    completed: false,
-    carry: "",
-    contentOffset: 0,
+  const dataState: CasLiveState = {
+    printedHashes: new Set<string>(),
+    lastHead: null,
+    completionEmitted: false,
   };
 
   const infoState: InfoLiveState = {
@@ -406,22 +461,29 @@ export async function cmdLive(storageRoot: string, parsed: ParsedLiveArgv): Prom
   process.on("SIGINT", onSigInt);
 
   try {
-    const firstData = await pumpNewContent(dataPath, dataState, roleFilter, cas);
-    if (firstData === 1) {
-      return 1;
-    }
+    await mkdir(dirname(target.threadsJsonPath), { recursive: true });
 
+    const firstData = await pumpThreadsJson({
+      storageRoot,
+      bundleDir: target.bundleDir,
+      bundleHash: target.bundleHash,
+      threadId: target.threadId,
+      state: dataState,
+      roleFilter,
+      cas,
+    });
+    const infoPath = join(storageRoot, "logs", target.bundleHash, `${target.threadId}.info.jsonl`);
     if (parsed.debug && (await pathExists(infoPath))) {
       await pumpNewInfoContent(infoPath, infoState);
     }
 
-    if (firstData === 0 || dataState.completed) {
+    if (firstData === 0) {
       return 0;
     }
 
     const tasks = await buildLiveWatchTasks({
-      dataPath,
-      infoPath,
+      storageRoot,
+      target,
       debug: parsed.debug,
       dataState,
       infoState,

packages/cli-workflow/src/commands/thread/rm.ts

@@ -1,24 +1,35 @@
 import { unlink } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
+import {
+  garbageCollectCas,
+  removeThreadEntry,
+  removeThreadHistoryEntries,
+} from "@uncaged/workflow-execute";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
-import { err, garbageCollectCas, ok, type Result } from "@uncaged/workflow";
-
-import { resolveThreadDataPath } from "../../thread-scan.js";
+import { resolveThreadRecord } from "../../thread-scan.js";
 
 export async function cmdThreadRemove(
   storageRoot: string,
   threadId: string,
 ): Promise<Result<void, string>> {
-  const dataPath = await resolveThreadDataPath(storageRoot, threadId);
-  if (dataPath === null) {
+  const resolved = await resolveThreadRecord(storageRoot, threadId);
+  if (resolved === null) {
     return err(`thread not found: ${threadId}`);
   }
 
-  const dir = dirname(dataPath);
-  const infoPath = join(dir, `${threadId}.info.jsonl`);
-  const runningPath = join(dir, `${threadId}.running`);
+  // Always clear both stores: between resolve and delete the worker may finish and
+  // move the thread from threads.json into history; branching only on resolved.source
+  // would skip history removal and leave a dangling row.
+  await removeThreadEntry(resolved.bundleDir, threadId);
+  const hist = await removeThreadHistoryEntries(resolved.bundleDir, threadId);
+  if (!hist.ok) {
+    return hist;
+  }
+
+  const infoPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.info.jsonl`);
+  const runningPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.running`);
 
-  await unlink(dataPath);
   await unlink(infoPath).catch(() => {});
   await unlink(runningPath).catch(() => {});
 

packages/cli-workflow/src/commands/thread/run.ts

@@ -1,13 +1,8 @@
 import { join } from "node:path";
 
-import {
-  err,
-  generateUlid,
-  getRegisteredWorkflow,
-  ok,
-  type Result,
-  readWorkflowRegistry,
-} from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow-register";
+import { generateUlid } from "@uncaged/workflow-util";
 import { ensureWorkerForHash, sendWorkerTcpCommand } from "../../worker-spawn.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";
 
@@ -15,7 +10,6 @@ export async function cmdRun(
   storageRoot: string,
   name: string,
   prompt: string,
-  maxRounds: number,
 ): Promise<Result<{ threadId: string }, string>> {
   const nameOk = validateCliWorkflowName(name);
   if (!nameOk.ok) {
@@ -46,7 +40,7 @@ export async function cmdRun(
       threadId,
       workflowName: name,
       prompt,
-      options: { maxRounds, depth: 0 },
+      options: { depth: 0 },
     },
     { awaitResponseLine: false },
   );

packages/cli-workflow/src/commands/thread/show.ts

@@ -1,19 +1,74 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { createCasStore, getContentMerklePayload, parseCasThreadNode } from "@uncaged/workflow-cas";
+import { FORK_BRANCH_ROLE, walkStateFramesNewestFirst } from "@uncaged/workflow-execute";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { END } from "@uncaged/workflow-runtime";
+import { getGlobalCasDir } from "@uncaged/workflow-util";
 
-import { readTextFileIfExists } from "../../fs-utils.js";
-import { resolveThreadDataPath } from "../../thread-scan.js";
+import { resolveThreadRecord } from "../../thread-scan.js";
+
+async function readParentStateFromStartNode(
+  cas: { get(hash: string): Promise<string | null> },
+  startHash: string,
+): Promise<string | null> {
+  const yamlText = await cas.get(startHash);
+  if (yamlText === null) {
+    return null;
+  }
+  const parsed = parseCasThreadNode(yamlText);
+  if (parsed === null || parsed.kind !== "start") {
+    return null;
+  }
+  return parsed.node.payload.parentState;
+}
 
 export async function cmdThreadShow(
   storageRoot: string,
   threadId: string,
 ): Promise<Result<string, string>> {
-  const dataPath = await resolveThreadDataPath(storageRoot, threadId);
-  if (dataPath === null) {
+  const resolved = await resolveThreadRecord(storageRoot, threadId);
+  if (resolved === null) {
     return err(`thread not found: ${threadId}`);
   }
-  const text = await readTextFileIfExists(dataPath);
-  if (text === null) {
-    return err(`thread data missing: ${threadId}`);
+
+  const cas = createCasStore(getGlobalCasDir(storageRoot));
+  const frames = await walkStateFramesNewestFirst(cas, resolved.head);
+  const chronological = [...frames].reverse();
+
+  const parentState = await readParentStateFromStartNode(cas, resolved.start);
+
+  const steps: Array<{
+    role: string;
+    hash: string;
+    timestamp: number;
+    content: string;
+    childThread: string | null;
+  }> = [];
+  for (const fr of chronological) {
+    if (fr.payload.role === END || fr.payload.role === FORK_BRANCH_ROLE) {
+      continue;
+    }
+    const payloadText = await getContentMerklePayload(cas, fr.payload.content);
+    steps.push({
+      role: fr.payload.role,
+      hash: fr.hash,
+      timestamp: fr.payload.timestamp,
+      content:
+        payloadText !== null
+          ? payloadText
+          : `(content not in CAS; contentHash=${fr.payload.content})`,
+      childThread: fr.payload.childThread,
+    });
   }
-  return ok(text.endsWith("\n") ? text.slice(0, -1) : text);
+
+  const payload = {
+    threadId: resolved.threadId,
+    bundleHash: resolved.bundleHash,
+    head: resolved.head,
+    start: resolved.start,
+    parentState,
+    source: resolved.source,
+    steps,
+  };
+
+  return ok(JSON.stringify(payload, null, 2));
 }

packages/cli-workflow/src/commands/workflow/add-argv.ts

@@ -1,4 +1,4 @@
-import { err, ok, type Result } from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import type { ParsedAddArgv } from "./types.js";
 

packages/cli-workflow/src/commands/workflow/add.ts

@@ -1,18 +1,15 @@
 import { readFile, stat } from "node:fs/promises";
 import { basename, resolve } from "node:path";
-
+import { hashWorkflowBundleBytes } from "@uncaged/workflow-cas";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import {
-  err,
   extractBundleExports,
-  hashWorkflowBundleBytes,
-  ok,
-  type Result,
   readWorkflowRegistry,
   registerWorkflowVersion,
   stringifyWorkflowDescriptor,
   validateWorkflowBundle,
   writeWorkflowRegistry,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-register";
 
 import { storeWorkflowBundleArtifacts } from "../../bundle-store.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";
@@ -113,7 +110,7 @@ export async function cmdAdd(
     return validated;
   }
 
-  const extracted = await extractBundleExports(resolvedPath, { storageRoot });
+  const extracted = await extractBundleExports(resolvedPath);
   if (!extracted.ok) {
     return extracted;
   }

packages/cli-workflow/src/commands/workflow/history.ts

@@ -1,10 +1,5 @@
-import {
-  err,
-  getRegisteredWorkflow,
-  ok,
-  type Result,
-  readWorkflowRegistry,
-} from "@uncaged/workflow";
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow-register";
 
 import { validateCliWorkflowName } from "../../workflow-name.js";
 

packages/cli-workflow/src/commands/workflow/list.ts

@@ -1,11 +1,9 @@
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import {
-  err,
   listRegisteredWorkflowNames,
-  ok,
-  type Result,
   readWorkflowRegistry,
   type WorkflowRegistryFile,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-register";
 
 export async function cmdList(storageRoot: string): Promise<Result<WorkflowRegistryFile, string>> {
   const reg = await readWorkflowRegistry(storageRoot);

packages/cli-workflow/src/commands/workflow/rm.ts

@@ -1,11 +1,9 @@
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import {
-  err,
-  ok,
-  type Result,
   readWorkflowRegistry,
   unregisterWorkflow,
   writeWorkflowRegistry,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-register";
 
 import { validateCliWorkflowName } from "../../workflow-name.js";
 

packages/cli-workflow/src/commands/workflow/rollback.ts

@@ -1,14 +1,12 @@
 import { join } from "node:path";
 
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import {
-  err,
   getRegisteredWorkflow,
-  ok,
-  type Result,
   readWorkflowRegistry,
   rollbackWorkflowToHistoryHash,
   writeWorkflowRegistry,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-register";
 
 import { pathExists } from "../../fs-utils.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";

packages/cli-workflow/src/commands/workflow/show.ts

@@ -1,11 +1,9 @@
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import {
-  err,
   getRegisteredWorkflow,
-  ok,
-  type Result,
   readWorkflowRegistry,
   type WorkflowRegistryEntry,
-} from "@uncaged/workflow";
+} from "@uncaged/workflow-register";
 import { stringify } from "yaml";
 
 import { validateCliWorkflowName } from "../../workflow-name.js";