feat: engine injects extract provider at runtime (Phase 2)

- createWorkflow(def, binding) — no more extract/llmProvider params
- Engine resolves extract provider from workflow.yaml via resolveModel
- WorkflowFnOptions now carries extract + llmProvider (engine-injected)
- Delete extract-provider.ts, inline maxDepth helper
- Template packages simplified: only take agent binding
- Breaking change: bundles no longer carry provider config

Refs #110

CLAUDE.md

@@ -97,6 +97,36 @@ type WorkflowEntry = {
 
 Workflow bundles (`.esm.js`) follow the same rule: export `const run` and `const descriptor`, not `export default`.
 
+### Folder Module Discipline
+
+Every folder under `src/` is a **module boundary**. Four rules:
+
+| # | Rule | Rationale |
+|---|------|-----------|
+| 1 | **Every folder exports via `index.ts`** | Single entry point for the module |
+| 2 | **Types live in `types.ts`** | Each folder's type definitions go in `<folder>/types.ts`, not scattered across files |
+| 3 | **Single export source** | Only `index.ts` may re-export. No file may re-export from another module's internals. Cross-module imports must go through `index.ts` — never reach past it to import a specific file |
+| 4 | **`index.ts` is pure re-exports** | No type definitions, no function implementations — only `export { ... } from` statements |
+
+```typescript
+// ✅ Good — import through module boundary
+import { createCasStore } from "../cas/index.js";
+import type { CasStore } from "../cas/index.js";
+
+// ❌ Bad — reaching past index.ts
+import { createCasStore } from "../cas/cas.js";
+
+// ❌ Bad — re-exporting from non-index file
+// in engine/engine.ts:
+export { createCasStore } from "../cas/cas.js";
+
+// ❌ Bad — types defined in index.ts
+// in cas/index.ts:
+export type CasStore = { ... };  // should be in cas/types.ts
+```
+
+**Exception**: The package-level `src/index.ts` is the public API surface and re-exports from folder `index.ts` files. Files that remain at `src/` root (e.g. `types.ts`, `workflow-as-agent.ts`) are not inside a folder module and follow normal rules.
+
 ## Naming
 
 | Type | Style | Example |
@@ -197,9 +227,8 @@ Test files (`__tests__/**`) are exempt.
 ### Commands
 
 ```bash
-bun run check       # biome check (lint + format)
+bun run check       # tsc --build + biome check
 bun run format      # biome format --write
-bun run build       # full build
 bun test            # run tests
 ```
 

README.md

@@ -0,0 +1,71 @@
+# @uncaged/workflow
+
+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).
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **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`. |
+| **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. |
+
+## Monorepo Packages
+
+```
+packages/
+  workflow/                      # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
+  cli-workflow/                  # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
+  workflow-template-develop/     # @uncaged/workflow-template-develop — develop workflow template (includes roles)
+  workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
+  workflow-agent-hermes/         # @uncaged/workflow-agent-hermes — Hermes agent adapter
+  workflow-agent-cursor/         # @uncaged/workflow-agent-cursor — Cursor agent adapter
+  workflow-agent-llm/            # @uncaged/workflow-agent-llm — LLM agent adapter
+  workflow-util-agent/           # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
+```
+
+Managed with **bun workspace** using the `workspace:*` protocol.
+
+## Quick Start
+
+```bash
+# Install dependencies
+bun install
+
+# Build all packages
+bun run build
+
+# Register a workflow bundle
+uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
+
+# Run a workflow
+uncaged-workflow run solve-issue --prompt "Fix bug #42"
+```
+
+## CLI Usage
+
+```bash
+uncaged-workflow help              # Show all commands
+uncaged-workflow workflow list     # List registered workflows
+uncaged-workflow run <name>        # Start a workflow thread
+uncaged-workflow thread list       # List all threads
+uncaged-workflow thread show <id>  # Inspect a thread
+uncaged-workflow skill             # Agent-consumable reference docs
+```
+
+See `uncaged-workflow help` for the full command reference.
+
+## Development
+
+```bash
+bun run check    # Biome lint + format check
+bun run format   # Auto-format with Biome
+bun test         # Run tests
+```
+
+## Architecture
+
+See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.

docs/architecture.md

@@ -17,11 +17,8 @@ A workflow engine that executes single-file ESM bundles. Each workflow is a self
 | `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-role-planner` | `@uncaged/workflow-role-planner` | Pure data: phased planning prompt + schema |
-| `workflow-role-coder` | `@uncaged/workflow-role-coder` | Pure data: coding prompt + schema |
-| `workflow-role-reviewer` | `@uncaged/workflow-role-reviewer` | Pure data: code review prompt + schema |
-| `workflow-role-committer` | `@uncaged/workflow-role-committer` | Pure data: git commit prompt + schema |
-| `workflow-template-solve-issue` | `@uncaged/workflow-template-solve-issue` | Composes roles + moderator into a complete workflow |
+| `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 |
 
 Monorepo with **bun workspace**, `workspace:*` protocol.

examples/hello-world.ts

@@ -1,4 +1,4 @@
-import { createExtract, createWorkflow, END, type RoleDefinition } from "@uncaged/workflow";
+import { createWorkflow, END, type RoleDefinition } from "@uncaged/workflow";
 import * as z from "zod/v4";
 
 type Roles = {
@@ -32,12 +32,6 @@ const greeter: RoleDefinition<Roles["greeter"]> = {
   extractMode: "single",
 };
 
-const extract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "",
-  model: "",
-});
-
 export const run = createWorkflow<Roles>(
   {
     roles: { greeter },
@@ -48,6 +42,4 @@ export const run = createWorkflow<Roles>(
   {
     agent: async (ctx) => `Hello, ${ctx.start.content}`,
   },
-  extract,
-  null,
 );

package.json

@@ -6,7 +6,6 @@
     "examples"
   ],
   "scripts": {
-    "build": "bun run --filter '*' build",
     "check": "bunx tsc --build && biome check .",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",

packages/cli-workflow/__tests__/bundle-fixture.ts

@@ -1,4 +1,4 @@
-import type { ParsedAddArgv } from "../src/commands/workflow/add.js";
+import type { ParsedAddArgv } from "../src/commands/workflow/index.js";
 
 export function addCliArgs(name: string, filePath: string): ParsedAddArgv {
   return { name, filePath, typesPath: null };

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

@@ -4,16 +4,16 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { getGlobalCasDir, getRegisteredWorkflow, readWorkflowRegistry } from "@uncaged/workflow";
-import { cmdCasGet } from "../src/commands/cas/get.js";
-import { cmdCasList } from "../src/commands/cas/list.js";
-import { cmdCasPut } from "../src/commands/cas/put.js";
-import { cmdCasRm } from "../src/commands/cas/rm.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
-import { cmdHistory } from "../src/commands/workflow/history.js";
-import { cmdList, formatListLines } from "../src/commands/workflow/list.js";
-import { cmdRemove } from "../src/commands/workflow/rm.js";
-import { cmdRollback } from "../src/commands/workflow/rollback.js";
-import { cmdShow } from "../src/commands/workflow/show.js";
+import { cmdCasGet, cmdCasList, cmdCasPut, cmdCasRm } from "../src/commands/cas/index.js";
+import {
+  cmdAdd,
+  cmdHistory,
+  cmdList,
+  cmdRemove,
+  cmdRollback,
+  cmdShow,
+  formatListLines,
+} from "../src/commands/workflow/index.js";
 import { addCliArgs } from "./bundle-fixture.js";
 
 const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {} };
@@ -402,7 +402,7 @@ export const run = async function* (input, options) {
   });
 
   test("cas put/get/list/rm use global cas dir (thread id not required for storage)", async () => {
-    const put = await cmdCasPut(storageRoot, "nonexistent-thread-id", "phase doc");
+    const put = await cmdCasPut(storageRoot, "phase doc");
     expect(put.ok).toBe(true);
     if (!put.ok) {
       return;
@@ -411,24 +411,24 @@ export const run = async function* (input, options) {
     const blobPath = join(getGlobalCasDir(storageRoot), `${hash}.txt`);
     expect(await readFile(blobPath, "utf8")).toBe("phase doc");
 
-    const got = await cmdCasGet(storageRoot, "other-thread", hash);
+    const got = await cmdCasGet(storageRoot, hash);
     expect(got.ok).toBe(true);
     if (!got.ok) {
       return;
     }
     expect(got.value).toBe("phase doc");
 
-    const listed = await cmdCasList(storageRoot, "another-thread");
+    const listed = await cmdCasList(storageRoot);
     expect(listed.ok).toBe(true);
     if (!listed.ok) {
       return;
     }
     expect(listed.value).toContain(hash);
 
-    const removed = await cmdCasRm(storageRoot, "rm-thread", hash);
+    const removed = await cmdCasRm(storageRoot, hash);
     expect(removed.ok).toBe(true);
 
-    const missing = await cmdCasGet(storageRoot, "after-rm", hash);
+    const missing = await cmdCasGet(storageRoot, hash);
     expect(missing.ok).toBe(false);
   });
 

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

@@ -3,11 +3,11 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createCasStore, getContentMerklePayload, getGlobalCasDir } from "@uncaged/workflow";
-import { cmdFork } from "../src/commands/thread/fork.js";
-import { cmdRun } from "../src/commands/thread/run.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
+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 { 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";
@@ -78,6 +78,7 @@ describe("cli fork", () => {
     prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
     storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-fork-"));
     process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await ensureTestWorkflowRegistryConfig(storageRoot);
   });
 
   afterEach(async () => {

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

@@ -10,7 +10,7 @@ import {
   getGlobalCasDir,
   putContentMerkleNode,
 } from "@uncaged/workflow";
-import { cmdThreadRemove } from "../src/commands/thread/rm.js";
+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));

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

@@ -4,8 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { runCli } from "../src/cli-dispatch.js";
-import { cmdInitTemplate } from "../src/commands/init/template.js";
-import { cmdInitWorkspace } from "../src/commands/init/workspace.js";
+import { cmdInitTemplate, cmdInitWorkspace } from "../src/commands/init/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 describe("init template", () => {

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

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { formatCliUsage, runCli } from "../src/cli-dispatch.js";
-import { cmdInitWorkspace } from "../src/commands/init/workspace.js";
+import { cmdInitWorkspace } from "../src/commands/init/index.js";
 import { pathExists } from "../src/fs-utils.js";
 
 describe("init workspace", () => {

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

@@ -13,7 +13,7 @@ import {
   LIVE_CONTENT_MAX_LINES,
   type LiveRoleRow,
   renderLiveRoleStepLines,
-} from "../src/commands/thread/live.js";
+} from "../src/commands/thread/index.js";
 import { parseLiveArgv } from "../src/live-argv.js";
 
 const cliEntryPath = fileURLToPath(new URL("../src/cli.ts", import.meta.url));

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

@@ -5,18 +5,21 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getGlobalCasDir } from "@uncaged/workflow";
-import { cmdCasPut } from "../src/commands/cas/put.js";
-import { cmdKill } from "../src/commands/thread/kill.js";
-import { cmdThreads } from "../src/commands/thread/list.js";
-import { cmdPause } from "../src/commands/thread/pause.js";
-import { cmdPs } from "../src/commands/thread/ps.js";
-import { cmdResume } from "../src/commands/thread/resume.js";
-import { cmdThreadRemove } from "../src/commands/thread/rm.js";
-import { cmdRun } from "../src/commands/thread/run.js";
-import { cmdThreadShow } from "../src/commands/thread/show.js";
-import { cmdAdd } from "../src/commands/workflow/add.js";
+import { cmdCasPut } from "../src/commands/cas/index.js";
+import {
+  cmdKill,
+  cmdPause,
+  cmdPs,
+  cmdResume,
+  cmdRun,
+  cmdThreadRemove,
+  cmdThreadShow,
+  cmdThreads,
+} from "../src/commands/thread/index.js";
+import { cmdAdd } from "../src/commands/workflow/index.js";
 import { pathExists, readTextFileIfExists } from "../src/fs-utils.js";
 import { addCliArgs } from "./bundle-fixture.js";
+import { ensureTestWorkflowRegistryConfig } from "./workflow-registry-fixture.js";
 
 const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow";
 `;
@@ -140,6 +143,7 @@ describe("cli thread commands", () => {
     prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
     storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-thread-"));
     process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await ensureTestWorkflowRegistryConfig(storageRoot);
   });
 
   afterEach(async () => {
@@ -234,7 +238,7 @@ describe("cli thread commands", () => {
     const runningPath = join(dirname(dataPath), `${threadId}.running`);
     await waitUntilRunningFileAbsent(runningPath, 120);
 
-    const put = await cmdCasPut(storageRoot, threadId, "keep-after-thread-rm");
+    const put = await cmdCasPut(storageRoot, "keep-after-thread-rm");
     expect(put.ok).toBe(true);
     if (!put.ok) {
       return;

packages/cli-workflow/__tests__/workflow-registry-fixture.ts

@@ -0,0 +1,18 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/** Minimal valid global config so {@link executeThread} can resolve the extract scene (CLI integration tests). */
+export const TEST_WORKFLOW_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`;
+
+export async function ensureTestWorkflowRegistryConfig(storageRoot: string): Promise<void> {
+  await writeFile(join(storageRoot, "workflow.yaml"), TEST_WORKFLOW_REGISTRY_YAML, "utf8");
+}

packages/cli-workflow/package.json

@@ -10,7 +10,6 @@
     "yaml": "^2.8.4"
   },
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   }
 }

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

@@ -1,16 +1,9 @@
-import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { err, ok, type Result } from "@uncaged/workflow";
 
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await stat(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
+import { pathExists } from "./fs-utils.js";
 
 export type BundleFileSource = { kind: "text"; text: string } | { kind: "path"; path: string };
 

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

@@ -0,0 +1,17 @@
+export function shouldUseColor(): boolean {
+  return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+}
+
+export function highlightLiveRole(name: string): string {
+  if (!shouldUseColor()) {
+    return name;
+  }
+  return `\x1b[1m\x1b[36m${name}\x1b[0m`;
+}
+
+export function dimGreyLine(line: string): string {
+  if (!shouldUseColor()) {
+    return line;
+  }
+  return `\x1b[2m\x1b[90m${line}\x1b[0m`;
+}

packages/cli-workflow/src/cli-command-types.ts

@@ -0,0 +1,19 @@
+export type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
+
+export type CommandEntry = {
+  handler: DispatchFn;
+  args: string;
+  description: string;
+};
+
+export type CommandGroup = {
+  name: string;
+  commands: ReadonlyArray<{ name: string; args: string; description: string }>;
+};
+
+export type DispatchGroupFn = (
+  tableName: string,
+  table: Record<string, CommandEntry>,
+  storageRoot: string,
+  argv: string[],
+) => Promise<number> | null;

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

@@ -1,613 +1,33 @@
+import type { CommandEntry, DispatchFn } from "./cli-command-types.js";
 import { printCliError, printCliLine, printCliWarn } from "./cli-output.js";
-import { cmdGc } from "./commands/cas/gc.js";
-import { cmdCasGet } from "./commands/cas/get.js";
-import { cmdCasList } from "./commands/cas/list.js";
-import { cmdCasPut } from "./commands/cas/put.js";
-import { cmdCasRm } from "./commands/cas/rm.js";
-import { cmdInitTemplate } from "./commands/init/template.js";
-import { cmdInitWorkspace } from "./commands/init/workspace.js";
-import { cmdFork, parseForkArgv } from "./commands/thread/fork.js";
-import { cmdKill } from "./commands/thread/kill.js";
-import { cmdThreads } from "./commands/thread/list.js";
-import { cmdLive } from "./commands/thread/live.js";
-import { cmdPause } from "./commands/thread/pause.js";
-import { cmdPs } from "./commands/thread/ps.js";
-import { cmdResume } from "./commands/thread/resume.js";
-import { cmdThreadRemove } from "./commands/thread/rm.js";
-import { cmdRun } from "./commands/thread/run.js";
-import { cmdThreadShow } from "./commands/thread/show.js";
-import { cmdAdd, formatAddSuccess, parseAddArgv } from "./commands/workflow/add.js";
-import { cmdHistory } from "./commands/workflow/history.js";
-import { cmdList, formatListLines } from "./commands/workflow/list.js";
-import { cmdRemove } from "./commands/workflow/rm.js";
-import { cmdRollback } from "./commands/workflow/rollback.js";
-import { cmdShow, formatShowYaml } from "./commands/workflow/show.js";
-import { parseLiveArgv } from "./live-argv.js";
-import { parseRunArgv } from "./run-argv.js";
+import { getCommandRegistry } from "./cli-registry.js";
+import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
+import { createCasDispatcher, dispatchGc } from "./commands/cas/index.js";
+import { createInitDispatcher } from "./commands/init/index.js";
+import {
+  createThreadDispatcher,
+  dispatchFork,
+  dispatchKill,
+  dispatchLive,
+  dispatchPause,
+  dispatchPs,
+  dispatchResume,
+  dispatchRun,
+  dispatchThreadList,
+} from "./commands/thread/index.js";
+import {
+  createWorkflowDispatcher,
+  dispatchAdd,
+  dispatchHistory,
+  dispatchList,
+  dispatchRemove,
+  dispatchRollback,
+  dispatchShow,
+} from "./commands/workflow/index.js";
 import { formatSkillIndex, formatSkillTopic, getSkillTopics } from "./skill.js";
 
-type DispatchFn = (storageRoot: string, argv: string[]) => Promise<number>;
-
-type CommandEntry = {
-  handler: DispatchFn;
-  args: string;
-  description: string;
-};
-
-type CommandGroup = {
-  name: string;
-  commands: ReadonlyArray<{ name: string; args: string; description: string }>;
-};
-
-// ── Individual dispatch functions ──────────────────────────────────────
-
-async function dispatchInitWorkspace(_storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: init workspace requires <name>`);
-    return 1;
-  }
-  const result = await cmdInitWorkspace(process.cwd(), name);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`initialized workflow workspace at ${result.value.rootPath}`);
-  return 0;
-}
-
-async function dispatchInitTemplate(_storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: init template requires <name>`);
-    return 1;
-  }
-  const result = await cmdInitTemplate(process.cwd(), name);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`initialized template at ${result.value.templatePath}`);
-  return 0;
-}
-
-async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseAddArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
-    return 1;
-  }
-  const result = await cmdAdd(storageRoot, parsed.value);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  for (const w of result.value.warnings) {
-    printCliWarn(w);
-  }
-  printCliLine(formatAddSuccess(parsed.value.name, parsed.value.filePath, result.value.hash));
-  return 0;
-}
-
-async function dispatchList(storageRoot: string, argv: string[]): Promise<number> {
-  if (argv.length > 0) {
-    printCliError(`${formatCliUsage()}\n\nerror: list takes no arguments`);
-    return 1;
-  }
-  const result = await cmdList(storageRoot);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  for (const line of formatListLines(result.value)) {
-    printCliLine(line);
-  }
-  return 0;
-}
-
-async function dispatchShow(storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: show requires <name>`);
-    return 1;
-  }
-  const result = await cmdShow(storageRoot, name);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(formatShowYaml(name, result.value));
-  return 0;
-}
-
-async function dispatchRemove(storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: remove requires <name>`);
-    return 1;
-  }
-  const result = await cmdRemove(storageRoot, name);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`removed workflow "${name}" from registry`);
-  return 0;
-}
-
-async function dispatchRun(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseRunArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
-    return 1;
-  }
-
-  const result = await cmdRun(
-    storageRoot,
-    parsed.value.name,
-    parsed.value.prompt,
-    parsed.value.maxRounds,
-  );
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-
-  printCliLine(result.value.threadId);
-  return 0;
-}
-
-async function dispatchPs(storageRoot: string, argv: string[]): Promise<number> {
-  if (argv.length > 0) {
-    printCliError(`${formatCliUsage()}\n\nerror: ps takes no arguments`);
-    return 1;
-  }
-  for (const line of await cmdPs(storageRoot)) {
-    printCliLine(line);
-  }
-  return 0;
-}
-
-async function dispatchKill(storageRoot: string, argv: string[]): Promise<number> {
-  const threadId = argv[0];
-  if (threadId === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: kill requires <thread-id>`);
-    return 1;
-  }
-  const result = await cmdKill(storageRoot, threadId);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`kill sent for thread ${threadId}`);
-  return 0;
-}
-
-async function dispatchLive(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseLiveArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
-    return 1;
-  }
-  return cmdLive(storageRoot, parsed.value);
-}
-
-async function dispatchHistory(storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: history requires <name>`);
-    return 1;
-  }
-  const result = await cmdHistory(storageRoot, name);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  for (const line of result.value) {
-    printCliLine(line);
-  }
-  return 0;
-}
-
-async function dispatchRollback(storageRoot: string, argv: string[]): Promise<number> {
-  const name = argv[0];
-  if (name === undefined || argv.length > 2) {
-    printCliError(`${formatCliUsage()}\n\nerror: rollback requires <name> [hash]`);
-    return 1;
-  }
-  const hashArg = argv[1];
-  const result = await cmdRollback(storageRoot, name, hashArg === undefined ? null : hashArg);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`rolled back workflow "${name}"`);
-  return 0;
-}
-
-async function dispatchPause(storageRoot: string, argv: string[]): Promise<number> {
-  const threadId = argv[0];
-  if (threadId === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: pause requires <thread-id>`);
-    return 1;
-  }
-  const result = await cmdPause(storageRoot, threadId);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`pause sent for thread ${threadId}`);
-  return 0;
-}
-
-async function dispatchResume(storageRoot: string, argv: string[]): Promise<number> {
-  const threadId = argv[0];
-  if (threadId === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: resume requires <thread-id>`);
-    return 1;
-  }
-  const result = await cmdResume(storageRoot, threadId);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`resume sent for thread ${threadId}`);
-  return 0;
-}
-
-async function dispatchThreadList(storageRoot: string, argv: string[]): Promise<number> {
-  const result = await cmdThreads(storageRoot, argv);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  for (const line of result.value) {
-    printCliLine(line);
-  }
-  return 0;
-}
-
-async function dispatchThreadShow(storageRoot: string, argv: string[]): Promise<number> {
-  const id = argv[0];
-  if (id === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: thread show requires <id>`);
-    return 1;
-  }
-  const result = await cmdThreadShow(storageRoot, id);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(result.value);
-  return 0;
-}
-
-async function dispatchThreadRm(storageRoot: string, argv: string[]): Promise<number> {
-  const id = argv[0];
-  if (id === undefined || argv.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: thread rm requires <id>`);
-    return 1;
-  }
-  const result = await cmdThreadRemove(storageRoot, id);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`removed thread ${id}`);
-  return 0;
-}
-
-async function dispatchGc(storageRoot: string, argv: string[]): Promise<number> {
-  if (argv.length > 0) {
-    printCliError(`${formatCliUsage()}\n\nerror: gc takes no arguments`);
-    return 1;
-  }
-  const result = await cmdGc(storageRoot);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  const stats = result.value;
-  printCliLine(
-    `scanned ${stats.scannedThreads} threads, ${stats.activeRefs} active refs, deleted ${stats.deletedEntries} entries`,
-  );
-  return 0;
-}
-
-async function dispatchFork(storageRoot: string, argv: string[]): Promise<number> {
-  const parsed = parseForkArgv(argv);
-  if (!parsed.ok) {
-    printCliError(`${formatCliUsage()}\n\nerror: ${parsed.error}`);
-    return 1;
-  }
-  const result = await cmdFork(storageRoot, parsed.value.threadId, parsed.value.fromRole);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(result.value.threadId);
-  return 0;
-}
-
-// ── CAS subcommand table ───────────────────────────────────────────────
-
-async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const hash = rest[1];
-  if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${formatCliUsage()}\n\nerror: cas get requires <thread-id> <hash>`);
-    return 1;
-  }
-  const result = await cmdCasGet(storageRoot, threadId, hash);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(result.value);
-  return 0;
-}
-
-async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const content = rest[1];
-  if (threadId === undefined || content === undefined || rest.length > 2) {
-    printCliError(`${formatCliUsage()}\n\nerror: cas put requires <thread-id> <content>`);
-    return 1;
-  }
-  const result = await cmdCasPut(storageRoot, threadId, content);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(result.value);
-  return 0;
-}
-
-async function dispatchCasList(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  if (threadId === undefined || rest.length > 1) {
-    printCliError(`${formatCliUsage()}\n\nerror: cas list requires <thread-id>`);
-    return 1;
-  }
-  const result = await cmdCasList(storageRoot, threadId);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  for (const hash of result.value) {
-    printCliLine(hash);
-  }
-  return 0;
-}
-
-async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<number> {
-  const threadId = rest[0];
-  const hash = rest[1];
-  if (threadId === undefined || hash === undefined || rest.length > 2) {
-    printCliError(`${formatCliUsage()}\n\nerror: cas rm requires <thread-id> <hash>`);
-    return 1;
-  }
-  const result = await cmdCasRm(storageRoot, threadId, hash);
-  if (!result.ok) {
-    printCliError(result.error);
-    return 1;
-  }
-  printCliLine(`removed cas entry ${hash}`);
-  return 0;
-}
-
-// ── Subcommand tables with metadata ────────────────────────────────────
-
-const WORKFLOW_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
-  add: {
-    handler: dispatchAdd,
-    args: "<name> <file.esm.js> [--types <path>]",
-    description: "Register a workflow bundle in the registry",
-  },
-  list: { handler: dispatchList, args: "", description: "List all registered workflows" },
-  show: {
-    handler: dispatchShow,
-    args: "<name>",
-    description: "Show details of a registered workflow",
-  },
-  rm: {
-    handler: dispatchRemove,
-    args: "<name>",
-    description: "Remove a workflow from the registry",
-  },
-  history: {
-    handler: dispatchHistory,
-    args: "<name>",
-    description: "Show version history of a workflow",
-  },
-  rollback: {
-    handler: dispatchRollback,
-    args: "<name> [hash]",
-    description: "Rollback a workflow to a previous version",
-  },
-};
-
-const THREAD_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
-  run: {
-    handler: dispatchRun,
-    args: "<name> [--prompt <text>] [--max-rounds N]",
-    description: "Start a new thread executing a workflow",
-  },
-  list: {
-    handler: dispatchThreadList,
-    args: "[name]",
-    description: "List threads, optionally filtered by workflow name",
-  },
-  show: { handler: dispatchThreadShow, args: "<id>", description: "Show thread details and state" },
-  rm: { handler: dispatchThreadRm, args: "<id>", description: "Remove a thread" },
-  fork: {
-    handler: dispatchFork,
-    args: "<thread-id> [--from-role <role>]",
-    description: "Fork a thread, optionally from a specific role",
-  },
-  ps: { handler: dispatchPs, args: "", description: "List running threads" },
-  kill: { handler: dispatchKill, args: "<thread-id>", description: "Kill a running thread" },
-  live: {
-    handler: dispatchLive,
-    args: "<thread-id> | --latest [--debug] [--role <name>]",
-    description: "Attach to a thread and stream output live",
-  },
-  pause: { handler: dispatchPause, args: "<thread-id>", description: "Pause a running thread" },
-  resume: { handler: dispatchResume, args: "<thread-id>", description: "Resume a paused thread" },
-};
-
-const CAS_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
-  get: {
-    handler: dispatchCasGet,
-    args: "<thread-id> <hash>",
-    description: "Retrieve content by hash from a thread's CAS",
-  },
-  put: {
-    handler: dispatchCasPut,
-    args: "<thread-id> <content>",
-    description: "Store content in a thread's CAS, returns hash",
-  },
-  list: {
-    handler: dispatchCasList,
-    args: "<thread-id>",
-    description: "List all CAS entries for a thread",
-  },
-  rm: { handler: dispatchCasRm, args: "<thread-id> <hash>", description: "Remove a CAS entry" },
-  gc: { handler: dispatchGc, args: "", description: "Garbage-collect unreferenced CAS entries" },
-};
-
-const INIT_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
-  workspace: {
-    handler: dispatchInitWorkspace,
-    args: "<name>",
-    description: "Initialize a new workflow workspace",
-  },
-  template: {
-    handler: dispatchInitTemplate,
-    args: "<name>",
-    description: "Initialize a new workflow template",
-  },
-};
-
-// ── Command registry ───────────────────────────────────────────────────
-
-export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
-  return [
-    {
-      name: "workflow",
-      commands: Object.entries(WORKFLOW_SUBCOMMAND_TABLE).map(([name, e]) => ({
-        name,
-        args: e.args,
-        description: e.description,
-      })),
-    },
-    {
-      name: "thread",
-      commands: Object.entries(THREAD_SUBCOMMAND_TABLE).map(([name, e]) => ({
-        name,
-        args: e.args,
-        description: e.description,
-      })),
-    },
-    {
-      name: "cas",
-      commands: Object.entries(CAS_SUBCOMMAND_TABLE).map(([name, e]) => ({
-        name,
-        args: e.args,
-        description: e.description,
-      })),
-    },
-    {
-      name: "init",
-      commands: Object.entries(INIT_SUBCOMMAND_TABLE).map(([name, e]) => ({
-        name,
-        args: e.args,
-        description: e.description,
-      })),
-    },
-  ];
-}
-
-// ── Auto-generated CLI usage ───────────────────────────────────────────
-
-const USAGE_SECTION_BY_GROUP: Record<string, string> = {
-  workflow: "Workflow registry:",
-  thread: "Thread execution:",
-  cas: "Content-addressable storage:",
-  init: "Development:",
-};
-
-function formatUsageCommandLines(
-  rows: ReadonlyArray<{ prefix: string; description: string }>,
-): string[] {
-  const maxPrefix = rows.reduce((max, row) => Math.max(max, row.prefix.length), 0);
-  const gap = 2;
-  return rows.map((row) => {
-    const pad = " ".repeat(maxPrefix - row.prefix.length + gap);
-    return `  ${row.prefix}${pad}${row.description}`;
-  });
-}
-
-export function formatCliUsage(): string {
-  const groups = getCommandRegistry();
-  const lines: string[] = ["uncaged-workflow — workflow engine CLI", ""];
-
-  for (const group of groups) {
-    const sectionTitle = USAGE_SECTION_BY_GROUP[group.name];
-    if (sectionTitle === undefined) {
-      throw new Error(`BUG: missing usage section title for group "${group.name}"`);
-    }
-    lines.push(sectionTitle);
-    const rows = group.commands.map((cmd) => {
-      const args = cmd.args ? ` ${cmd.args}` : "";
-      return {
-        prefix: `${group.name} ${cmd.name}${args}`,
-        description: cmd.description,
-      };
-    });
-    lines.push(...formatUsageCommandLines(rows));
-    lines.push("");
-  }
-
-  lines.push("Shortcuts:");
-  lines.push(
-    ...formatUsageCommandLines([
-      { prefix: "run <name> [...]", description: "→ thread run" },
-      { prefix: "live <id> [...]", description: "→ thread live" },
-    ]),
-  );
-  lines.push("");
-
-  lines.push("Reference:");
-  const skillTopicNames = getSkillTopics()
-    .map((t) => t.name)
-    .join(", ");
-  lines.push(
-    ...formatUsageCommandLines([
-      {
-        prefix: "skill [topic]",
-        description: `Agent-consumable docs (${skillTopicNames})`,
-      },
-    ]),
-  );
-  lines.push("");
-  lines.push("Use <command> --help for subcommand details.");
-  lines.push("");
-  lines.push("Environment variables:");
-  lines.push(
-    "  WORKFLOW_STORAGE_ROOT              Override storage directory (default: ~/.uncaged/workflow)",
-  );
-  lines.push(
-    "  UNCAGED_WORKFLOW_STORAGE_ROOT      Internal override (takes priority over WORKFLOW_STORAGE_ROOT)",
-  );
-  return lines.join("\n");
-}
-
-function printDeprecation(oldCmd: string, newCmd: string): void {
-  printCliWarn(`⚠ "${oldCmd}" is deprecated, use "${newCmd}" instead`);
-}
-
-// ── Group dispatchers ──────────────────────────────────────────────────
+export type { CommandEntry, CommandGroup, DispatchFn } from "./cli-command-types.js";
+export { getCommandRegistry } from "./cli-registry.js";
 
 function dispatchGroup(
   tableName: string,
@@ -634,54 +54,20 @@ function dispatchGroup(
   return entry.handler(storageRoot, argv.slice(1));
 }
 
-async function dispatchInit(storageRoot: string, argv: string[]): Promise<number> {
-  const result = dispatchGroup("init", INIT_SUBCOMMAND_TABLE, storageRoot, argv);
-  if (result !== null) {
-    return result;
-  }
-  const sub = argv[0];
-  printCliError(`${formatCliUsage()}\n\nerror: unknown init subcommand: ${sub}`);
-  return 1;
+function printDeprecation(oldCmd: string, newCmd: string): void {
+  printCliWarn(`⚠ "${oldCmd}" is deprecated, use "${newCmd}" instead`);
 }
 
-async function dispatchWorkflow(storageRoot: string, argv: string[]): Promise<number> {
-  const result = dispatchGroup("workflow", WORKFLOW_SUBCOMMAND_TABLE, storageRoot, argv);
-  if (result !== null) {
-    return result;
-  }
-  const sub = argv[0];
-  if (sub === "remove") {
-    printDeprecation("workflow remove", "workflow rm");
-    return dispatchRemove(storageRoot, argv.slice(1));
-  }
-  printCliError(`${formatCliUsage()}\n\nerror: unknown workflow subcommand: ${sub}`);
-  return 1;
+export function formatCliUsage(): string {
+  return formatCliUsageWithGroups(getCommandRegistry(), getSkillTopics());
 }
 
-async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
-  const result = dispatchGroup("thread", THREAD_SUBCOMMAND_TABLE, storageRoot, argv);
-  if (result !== null) {
-    return result;
-  }
-  const sub = argv[0];
-  printCliError(`${formatCliUsage()}\n\nerror: unknown thread subcommand: ${sub}`);
-  return 1;
-}
+const dispatchWorkflow = createWorkflowDispatcher({ dispatchGroup, printDeprecation });
+const dispatchThread = createThreadDispatcher({ dispatchGroup });
+const dispatchCas = createCasDispatcher({ dispatchGroup });
+const dispatchInit = createInitDispatcher({ dispatchGroup });
 
-async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
-  const result = dispatchGroup("cas", CAS_SUBCOMMAND_TABLE, storageRoot, argv);
-  if (result !== null) {
-    return result;
-  }
-  const sub = argv[0];
-  printCliError(`${formatCliUsage()}\n\nerror: unknown cas subcommand: ${sub}`);
-  return 1;
-}
-
-// ── Help ────────────────────────────────────────────────────────────────
-
-async function dispatchSkill(_storageRoot: string, argv: string[]): Promise<number> {
-  const topic = argv[0];
+async function showSkillDocOrIndex(topic: string | undefined): Promise<number> {
   if (topic === undefined) {
     printCliLine(formatSkillIndex());
     return 0;
@@ -695,44 +81,31 @@ async function dispatchSkill(_storageRoot: string, argv: string[]): Promise<numb
   return 0;
 }
 
+async function dispatchSkill(_storageRoot: string, argv: string[]): Promise<number> {
+  return showSkillDocOrIndex(argv[0]);
+}
+
 async function dispatchHelp(_storageRoot: string, argv: string[]): Promise<number> {
-  // Legacy compat: help --skill [topic] → skill [topic]
+  printCliWarn('⚠ "help" is deprecated, use "skill" instead');
   const skillIdx = argv.indexOf("--skill");
   if (skillIdx !== -1) {
-    const topic = argv[skillIdx + 1];
-    if (topic === undefined) {
-      printCliLine(formatSkillIndex());
-      return 0;
-    }
-    const doc = formatSkillTopic(topic);
-    if (doc === null) {
-      printCliError(`unknown skill topic: ${topic}\n\n${formatSkillIndex()}`);
-      return 1;
-    }
-    printCliLine(doc);
-    return 0;
+    return showSkillDocOrIndex(argv[skillIdx + 1]);
   }
   printCliLine(formatCliUsage());
   return 0;
 }
 
-// ── Top-level command table (Phase 3) ──────────────────────────────────
-
 const COMMAND_TABLE: Record<string, DispatchFn> = {
-  // Grouped commands (primary)
   workflow: dispatchWorkflow,
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
   help: dispatchHelp,
   skill: dispatchSkill,
-
-  // Top-level shortcuts (no deprecation)
   run: dispatchRun,
   live: dispatchLive,
 };
 
-// Deprecated flat commands that delegate to grouped commands
 const DEPRECATED_ALIASES: Record<string, { newCmd: string; handler: DispatchFn }> = {
   add: { newCmd: "workflow add", handler: dispatchAdd },
   list: { newCmd: "workflow list", handler: dispatchList },

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

@@ -0,0 +1,45 @@
+import type { CommandGroup } from "./cli-command-types.js";
+import { setCommandGroupsForUsage } from "./cli-usage-context.js";
+import { CAS_SUBCOMMAND_TABLE } from "./commands/cas/index.js";
+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";
+
+export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
+  return [
+    {
+      name: "workflow",
+      commands: Object.entries(WORKFLOW_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "thread",
+      commands: Object.entries(THREAD_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "cas",
+      commands: Object.entries(CAS_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+    {
+      name: "init",
+      commands: Object.entries(INIT_SUBCOMMAND_TABLE).map(([name, e]) => ({
+        name,
+        args: e.args,
+        description: e.description,
+      })),
+    },
+  ];
+}
+
+setCommandGroupsForUsage(getCommandRegistry());

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

@@ -0,0 +1,14 @@
+import type { CommandGroup } from "./cli-command-types.js";
+
+let commandGroupsForUsage: ReadonlyArray<CommandGroup> | null = null;
+
+export function setCommandGroupsForUsage(groups: ReadonlyArray<CommandGroup>): void {
+  commandGroupsForUsage = groups;
+}
+
+export function getCommandGroupsForUsage(): ReadonlyArray<CommandGroup> {
+  if (commandGroupsForUsage === null) {
+    throw new Error("BUG: command groups for usage not initialized");
+  }
+  return commandGroupsForUsage;
+}

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

@@ -0,0 +1,81 @@
+import type { CommandGroup } from "./cli-command-types.js";
+
+/** Keep aligned with `getSkillTopics()` in skill.ts (names only, for error usage lines). */
+export const USAGE_SKILL_TOPIC_ROWS: ReadonlyArray<{ name: string }> = [
+  { name: "cli" },
+  { name: "develop" },
+  { name: "author" },
+];
+
+const USAGE_SECTION_BY_GROUP: Record<string, string> = {
+  workflow: "Workflow registry:",
+  thread: "Thread execution:",
+  cas: "Content-addressable storage:",
+  init: "Development:",
+};
+
+export function formatUsageCommandLines(
+  rows: ReadonlyArray<{ prefix: string; description: string }>,
+): string[] {
+  const maxPrefix = rows.reduce((max, row) => Math.max(max, row.prefix.length), 0);
+  const gap = 2;
+  return rows.map((row) => {
+    const pad = " ".repeat(maxPrefix - row.prefix.length + gap);
+    return `  ${row.prefix}${pad}${row.description}`;
+  });
+}
+
+export function formatCliUsage(
+  groups: ReadonlyArray<CommandGroup>,
+  skillTopics: ReadonlyArray<{ name: string }>,
+): string {
+  const lines: string[] = ["uncaged-workflow — workflow engine CLI", ""];
+
+  for (const group of groups) {
+    const sectionTitle = USAGE_SECTION_BY_GROUP[group.name];
+    if (sectionTitle === undefined) {
+      throw new Error(`BUG: missing usage section title for group "${group.name}"`);
+    }
+    lines.push(sectionTitle);
+    const rows = group.commands.map((cmd) => {
+      const args = cmd.args ? ` ${cmd.args}` : "";
+      return {
+        prefix: `${group.name} ${cmd.name}${args}`,
+        description: cmd.description,
+      };
+    });
+    lines.push(...formatUsageCommandLines(rows));
+    lines.push("");
+  }
+
+  lines.push("Shortcuts:");
+  lines.push(
+    ...formatUsageCommandLines([
+      { prefix: "run <name> [...]", description: "→ thread run" },
+      { prefix: "live <id> [...]", description: "→ thread live" },
+    ]),
+  );
+  lines.push("");
+
+  lines.push("Reference:");
+  const skillTopicNames = skillTopics.map((t) => t.name).join(", ");
+  lines.push(
+    ...formatUsageCommandLines([
+      {
+        prefix: "skill [topic]",
+        description: `Agent-consumable docs (${skillTopicNames})`,
+      },
+    ]),
+  );
+  lines.push("");
+  lines.push("Use <command> --help for subcommand details.");
+  lines.push("");
+  lines.push("Environment variables:");
+  lines.push(
+    "  WORKFLOW_STORAGE_ROOT              Override storage directory (default: ~/.uncaged/workflow)",
+  );
+  lines.push(
+    "  UNCAGED_WORKFLOW_STORAGE_ROOT      Internal override (takes priority over WORKFLOW_STORAGE_ROOT)",
+  );
+  return lines.join("\n");
+}

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

@@ -0,0 +1,125 @@
+import type { CommandEntry } from "../../cli-command-types.js";
+import { printCliError, printCliLine } from "../../cli-output.js";
+import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
+import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
+import { cmdGc } from "./gc.js";
+import { cmdCasGet } from "./get.js";
+import { cmdCasList } from "./list.js";
+import { cmdCasPut } from "./put.js";
+import { cmdCasRm } from "./rm.js";
+import type { CasDispatchDeps } from "./types.js";
+
+function usageText(): string {
+  return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
+}
+
+export async function dispatchGc(storageRoot: string, argv: string[]): Promise<number> {
+  if (argv.length > 0) {
+    printCliError(`${usageText()}\n\nerror: gc takes no arguments`);
+    return 1;
+  }
+  const result = await cmdGc(storageRoot);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  const stats = result.value;
+  printCliLine(
+    `scanned ${stats.scannedThreads} threads, ${stats.activeRefs} active refs, deleted ${stats.deletedEntries} entries`,
+  );
+  return 0;
+}
+
+export async function dispatchCasGet(storageRoot: string, rest: string[]): Promise<number> {
+  const hash = rest[0];
+  if (hash === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas get requires <hash>`);
+    return 1;
+  }
+  const result = await cmdCasGet(storageRoot, hash);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(result.value);
+  return 0;
+}
+
+export async function dispatchCasPut(storageRoot: string, rest: string[]): Promise<number> {
+  const content = rest[0];
+  if (content === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas put requires <content>`);
+    return 1;
+  }
+  const result = await cmdCasPut(storageRoot, content);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(result.value);
+  return 0;
+}
+
+export async function dispatchCasList(storageRoot: string, rest: string[]): Promise<number> {
+  if (rest.length > 0) {
+    printCliError(`${usageText()}\n\nerror: cas list takes no arguments`);
+    return 1;
+  }
+  const result = await cmdCasList(storageRoot);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  for (const hash of result.value) {
+    printCliLine(hash);
+  }
+  return 0;
+}
+
+export async function dispatchCasRm(storageRoot: string, rest: string[]): Promise<number> {
+  const hash = rest[0];
+  if (hash === undefined || rest.length > 1) {
+    printCliError(`${usageText()}\n\nerror: cas rm requires <hash>`);
+    return 1;
+  }
+  const result = await cmdCasRm(storageRoot, hash);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`removed cas entry ${hash}`);
+  return 0;
+}
+
+export const CAS_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  get: {
+    handler: dispatchCasGet,
+    args: "<hash>",
+    description: "Retrieve content by hash from CAS",
+  },
+  put: {
+    handler: dispatchCasPut,
+    args: "<content>",
+    description: "Store content in CAS, prints hash",
+  },
+  list: {
+    handler: dispatchCasList,
+    args: "",
+    description: "List all hashes in CAS",
+  },
+  rm: { handler: dispatchCasRm, args: "<hash>", description: "Remove a CAS entry by hash" },
+  gc: { handler: dispatchGc, args: "", description: "Garbage-collect unreferenced CAS entries" },
+};
+
+export function createCasDispatcher(deps: CasDispatchDeps) {
+  const { dispatchGroup } = deps;
+  return async function dispatchCas(storageRoot: string, argv: string[]): Promise<number> {
+    const result = dispatchGroup("cas", CAS_SUBCOMMAND_TABLE, storageRoot, argv);
+    if (result !== null) {
+      return result;
+    }
+    const sub = argv[0];
+    printCliError(`${usageText()}\n\nerror: unknown cas subcommand: ${sub}`);
+    return 1;
+  };
+}

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

@@ -2,7 +2,6 @@ import { createCasStore, err, getGlobalCasDir, ok, type Result } from "@uncaged/
 
 export async function cmdCasGet(
   storageRoot: string,
-  _threadId: string,
   hash: string,
 ): Promise<Result<string, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

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

@@ -1,3 +1,12 @@
+export {
+  CAS_SUBCOMMAND_TABLE,
+  createCasDispatcher,
+  dispatchCasGet,
+  dispatchCasList,
+  dispatchCasPut,
+  dispatchCasRm,
+  dispatchGc,
+} from "./dispatch.js";
 export { cmdGc } from "./gc.js";
 export { cmdCasGet } from "./get.js";
 export { cmdCasList } from "./list.js";

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

@@ -1,9 +1,6 @@
 import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
 
-export async function cmdCasList(
-  storageRoot: string,
-  _threadId: string,
-): Promise<Result<string[], string>> {
+export async function cmdCasList(storageRoot: string): Promise<Result<string[], string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));
   const hashes = await cas.list();
   return ok(hashes);

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

@@ -2,7 +2,6 @@ import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workf
 
 export async function cmdCasPut(
   storageRoot: string,
-  _threadId: string,
   content: string,
 ): Promise<Result<string, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));

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

@@ -1,10 +1,6 @@
 import { createCasStore, getGlobalCasDir, ok, type Result } from "@uncaged/workflow";
 
-export async function cmdCasRm(
-  storageRoot: string,
-  _threadId: string,
-  hash: string,
-): Promise<Result<void, string>> {
+export async function cmdCasRm(storageRoot: string, hash: string): Promise<Result<void, string>> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));
   await cas.delete(hash);
   return ok(undefined);

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

@@ -0,0 +1,5 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type CasDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

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

@@ -0,0 +1,67 @@
+import type { CommandEntry } from "../../cli-command-types.js";
+import { printCliError, printCliLine } from "../../cli-output.js";
+import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
+import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
+import { cmdInitTemplate } from "./template.js";
+import type { InitDispatchDeps } from "./types.js";
+import { cmdInitWorkspace } from "./workspace.js";
+
+function usageText(): string {
+  return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
+}
+
+export async function dispatchInitWorkspace(_storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: init workspace requires <name>`);
+    return 1;
+  }
+  const result = await cmdInitWorkspace(process.cwd(), name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`initialized workflow workspace at ${result.value.rootPath}`);
+  return 0;
+}
+
+export async function dispatchInitTemplate(_storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: init template requires <name>`);
+    return 1;
+  }
+  const result = await cmdInitTemplate(process.cwd(), name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`initialized template at ${result.value.templatePath}`);
+  return 0;
+}
+
+export const INIT_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  workspace: {
+    handler: dispatchInitWorkspace,
+    args: "<name>",
+    description: "Initialize a new workflow workspace",
+  },
+  template: {
+    handler: dispatchInitTemplate,
+    args: "<name>",
+    description: "Initialize a new workflow template",
+  },
+};
+
+export function createInitDispatcher(deps: InitDispatchDeps) {
+  const { dispatchGroup } = deps;
+  return async function dispatchInit(storageRoot: string, argv: string[]): Promise<number> {
+    const result = dispatchGroup("init", INIT_SUBCOMMAND_TABLE, storageRoot, argv);
+    if (result !== null) {
+      return result;
+    }
+    const sub = argv[0];
+    printCliError(`${usageText()}\n\nerror: unknown init subcommand: ${sub}`);
+    return 1;
+  };
+}

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

@@ -1,4 +1,9 @@
-export type { CmdInitTemplateSuccess } from "./template.js";
+export {
+  createInitDispatcher,
+  dispatchInitTemplate,
+  dispatchInitWorkspace,
+  INIT_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
 export { cmdInitTemplate } from "./template.js";
-export type { CmdInitWorkspaceSuccess } from "./workspace.js";
+export type { CmdInitTemplateSuccess, CmdInitWorkspaceSuccess } from "./types.js";
 export { cmdInitWorkspace } from "./workspace.js";

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

@@ -5,22 +5,15 @@ import { err, ok, type Result } from "@uncaged/workflow";
 
 import { pathExists } from "../../fs-utils.js";
 
-export type CmdInitTemplateSuccess = {
-  templatePath: string;
-};
-
-function validateWorkspaceSegment(name: string): Result<void, string> {
-  if (name.length === 0) {
-    return err("workspace name must not be empty");
-  }
-  if (name === "." || name === "..") {
-    return err("invalid workspace name");
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    return err("workspace name must not contain path separators");
-  }
-  return ok(undefined);
-}
+import {
+  templateIndexTs,
+  templateModeratorTs,
+  templatePackageJson,
+  templateRolesTs,
+  templateTsconfigJson,
+} from "./templates.js";
+import type { CmdInitTemplateSuccess } from "./types.js";
+import { validateWorkspaceSegment } from "./validate.js";
 
 function hasTemplatesWorkspaceGlob(workspaces: unknown): boolean {
   return Array.isArray(workspaces) && workspaces.includes("templates/*");
@@ -67,108 +60,6 @@ async function findWorkflowWorkspaceRoot(startDir: string): Promise<Result<strin
   }
 }
 
-function templatePackageJson(templateName: string): string {
-  return `${JSON.stringify(
-    {
-      name: `template-${templateName}`,
-      version: "0.0.0",
-      private: true,
-      type: "module",
-      dependencies: {
-        "@uncaged/workflow": "^0.1.0",
-        zod: "^4.0.0",
-      },
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function templateTsconfigJson(): string {
-  return `${JSON.stringify(
-    {
-      extends: "../../tsconfig.json",
-      compilerOptions: {
-        rootDir: "src",
-        outDir: "dist",
-      },
-      include: ["src/**/*.ts"],
-    },
-    null,
-    2,
-  )}\n`;
-}
-
-function templateRolesTs(): string {
-  return `import type { RoleDefinition } from "@uncaged/workflow";
-import * as z from "zod/v4";
-
-export const HELLO_TEMPLATE_DESCRIPTION =
-  "Minimal starter template: one greeter role, then END.";
-
-export type HelloTemplateMeta = {
-  greeter: {
-    message: string;
-  };
-};
-
-const greeterMetaSchema = z.object({
-  message: z.string(),
-});
-
-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,
-};
-`;
-}
-
-function templateModeratorTs(): string {
-  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow";
-
-import type { HelloTemplateMeta } from "./roles.js";
-
-export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
-  ctx: ModeratorContext<HelloTemplateMeta>,
-) => {
-  if (ctx.steps.length === 0) {
-    return "greeter";
-  }
-  return END;
-};
-`;
-}
-
-function templateIndexTs(): string {
-  return `import type { WorkflowDefinition } from "@uncaged/workflow";
-
-import { helloTemplateModerator } from "./moderator.js";
-import {
-  HELLO_TEMPLATE_DESCRIPTION,
-  type HelloTemplateMeta,
-  greeterRole,
-} from "./roles.js";
-
-export {
-  HELLO_TEMPLATE_DESCRIPTION,
-  type HelloTemplateMeta,
-  greeterRole,
-} from "./roles.js";
-export { helloTemplateModerator } from "./moderator.js";
-
-export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
-  description: HELLO_TEMPLATE_DESCRIPTION,
-  roles: {
-    greeter: greeterRole,
-  },
-  moderator: helloTemplateModerator,
-};
-`;
-}
-
 export async function cmdInitTemplate(
   startDir: string,
   templateName: string,

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

@@ -0,0 +1,101 @@
+export function templatePackageJson(templateName: string): string {
+  return `${JSON.stringify(
+    {
+      name: `template-${templateName}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      dependencies: {
+        "@uncaged/workflow": "^0.1.0",
+        zod: "^4.0.0",
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export function templateTsconfigJson(): string {
+  return `${JSON.stringify(
+    {
+      extends: "../../tsconfig.json",
+      compilerOptions: {
+        rootDir: "src",
+        outDir: "dist",
+      },
+      include: ["src/**/*.ts"],
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+export function templateRolesTs(): string {
+  return `import type { RoleDefinition } from "@uncaged/workflow";
+import * as z from "zod/v4";
+
+export const HELLO_TEMPLATE_DESCRIPTION =
+  "Minimal starter template: one greeter role, then END.";
+
+export type HelloTemplateMeta = {
+  greeter: {
+    message: string;
+  };
+};
+
+const greeterMetaSchema = z.object({
+  message: z.string(),
+});
+
+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";
+
+import type { HelloTemplateMeta } from "./roles.js";
+
+export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
+  ctx: ModeratorContext<HelloTemplateMeta>,
+) => {
+  if (ctx.steps.length === 0) {
+    return "greeter";
+  }
+  return END;
+};
+`;
+}
+
+export function templateIndexTs(): string {
+  return `import type { WorkflowDefinition } from "@uncaged/workflow";
+
+import { helloTemplateModerator } from "./moderator.js";
+import {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+
+export {
+  HELLO_TEMPLATE_DESCRIPTION,
+  type HelloTemplateMeta,
+  greeterRole,
+} from "./roles.js";
+export { helloTemplateModerator } from "./moderator.js";
+
+export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
+  description: HELLO_TEMPLATE_DESCRIPTION,
+  roles: {
+    greeter: greeterRole,
+  },
+  moderator: helloTemplateModerator,
+};
+`;
+}

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

@@ -0,0 +1,13 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type CmdInitTemplateSuccess = {
+  templatePath: string;
+};
+
+export type CmdInitWorkspaceSuccess = {
+  rootPath: string;
+};
+
+export type InitDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

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

@@ -0,0 +1,15 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+/** Validates a single path segment for workspace / template names (no separators, not `.` / `..`). */
+export function validateWorkspaceSegment(name: string): Result<void, string> {
+  if (name.length === 0) {
+    return err("workspace name must not be empty");
+  }
+  if (name === "." || name === "..") {
+    return err("invalid workspace name");
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    return err("workspace name must not contain path separators");
+  }
+  return ok(undefined);
+}

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

@@ -4,23 +4,8 @@ import { join } from "node:path";
 import { err, ok, type Result } from "@uncaged/workflow";
 
 import { pathExists } from "../../fs-utils.js";
-
-export type CmdInitWorkspaceSuccess = {
-  rootPath: string;
-};
-
-function validateWorkspaceSegment(name: string): Result<void, string> {
-  if (name.length === 0) {
-    return err("workspace name must not be empty");
-  }
-  if (name === "." || name === "..") {
-    return err("invalid workspace name");
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    return err("workspace name must not contain path separators");
-  }
-  return ok(undefined);
-}
+import type { CmdInitWorkspaceSuccess } from "./types.js";
+import { validateWorkspaceSegment } from "./validate.js";
 
 function rootPackageJson(workspaceName: string): string {
   return `${JSON.stringify(
@@ -122,7 +107,7 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`extractPrompt\` / \`description\`。
 3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
 4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
-5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding, extract)\`（或项目约定的封装）绑定 **AgentFn** / **ExtractFn**。
+5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowFnOptions\`。
 6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
 
 ## 4. 编码规范

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

@@ -0,0 +1,52 @@
+import type { Result } from "@uncaged/workflow";
+
+import {
+  readWorkerCtl,
+  resolveRunningHashForThread,
+  sendWorkerTcpCommand,
+} from "../../worker-spawn.js";
+
+type ThreadControlAction = "kill" | "pause" | "resume";
+
+async function cmdThreadControl(
+  storageRoot: string,
+  threadId: string,
+  action: ThreadControlAction,
+): Promise<Result<void, string>> {
+  const hashResult = await resolveRunningHashForThread(storageRoot, threadId);
+  if (!hashResult.ok) {
+    return hashResult;
+  }
+
+  const ctlResult = await readWorkerCtl(storageRoot, hashResult.value);
+  if (!ctlResult.ok) {
+    return ctlResult;
+  }
+
+  return await sendWorkerTcpCommand(
+    ctlResult.value.port,
+    { type: action, threadId },
+    { awaitResponseLine: true },
+  );
+}
+
+export async function cmdKill(
+  storageRoot: string,
+  threadId: string,
+): Promise<Result<void, string>> {
+  return cmdThreadControl(storageRoot, threadId, "kill");
+}
+
+export async function cmdPause(
+  storageRoot: string,
+  threadId: string,
+): Promise<Result<void, string>> {
+  return cmdThreadControl(storageRoot, threadId, "pause");
+}
+
+export async function cmdResume(
+  storageRoot: string,
+  threadId: string,
+): Promise<Result<void, string>> {
+  return cmdThreadControl(storageRoot, threadId, "resume");
+}

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

@@ -0,0 +1,206 @@
+import type { CommandEntry } from "../../cli-command-types.js";
+import { printCliError, printCliLine } from "../../cli-output.js";
+import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
+import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
+import { parseLiveArgv } from "../../live-argv.js";
+import { parseRunArgv } from "../../run-argv.js";
+import { cmdKill, cmdPause, cmdResume } from "./control.js";
+import { cmdFork } from "./fork.js";
+import { parseForkArgv } from "./fork-argv.js";
+import { cmdThreads } from "./list.js";
+import { cmdLive } from "./live.js";
+import { cmdPs } from "./ps.js";
+import { cmdThreadRemove } from "./rm.js";
+import { cmdRun } from "./run.js";
+import { cmdThreadShow } from "./show.js";
+import type { ThreadDispatchDeps } from "./types.js";
+
+function usageText(): string {
+  return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
+}
+
+export async function dispatchRun(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseRunArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${usageText()}\n\nerror: ${parsed.error}`);
+    return 1;
+  }
+
+  const result = await cmdRun(
+    storageRoot,
+    parsed.value.name,
+    parsed.value.prompt,
+    parsed.value.maxRounds,
+  );
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+
+  printCliLine(result.value.threadId);
+  return 0;
+}
+
+export async function dispatchPs(storageRoot: string, argv: string[]): Promise<number> {
+  if (argv.length > 0) {
+    printCliError(`${usageText()}\n\nerror: ps takes no arguments`);
+    return 1;
+  }
+  for (const line of await cmdPs(storageRoot)) {
+    printCliLine(line);
+  }
+  return 0;
+}
+
+export async function dispatchKill(storageRoot: string, argv: string[]): Promise<number> {
+  const threadId = argv[0];
+  if (threadId === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: kill requires <thread-id>`);
+    return 1;
+  }
+  const result = await cmdKill(storageRoot, threadId);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`kill sent for thread ${threadId}`);
+  return 0;
+}
+
+export async function dispatchLive(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseLiveArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${usageText()}\n\nerror: ${parsed.error}`);
+    return 1;
+  }
+  return cmdLive(storageRoot, parsed.value);
+}
+
+export async function dispatchPause(storageRoot: string, argv: string[]): Promise<number> {
+  const threadId = argv[0];
+  if (threadId === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: pause requires <thread-id>`);
+    return 1;
+  }
+  const result = await cmdPause(storageRoot, threadId);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`pause sent for thread ${threadId}`);
+  return 0;
+}
+
+export async function dispatchResume(storageRoot: string, argv: string[]): Promise<number> {
+  const threadId = argv[0];
+  if (threadId === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: resume requires <thread-id>`);
+    return 1;
+  }
+  const result = await cmdResume(storageRoot, threadId);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`resume sent for thread ${threadId}`);
+  return 0;
+}
+
+export async function dispatchThreadList(storageRoot: string, argv: string[]): Promise<number> {
+  const result = await cmdThreads(storageRoot, argv);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  for (const line of result.value) {
+    printCliLine(line);
+  }
+  return 0;
+}
+
+export async function dispatchThreadShow(storageRoot: string, argv: string[]): Promise<number> {
+  const id = argv[0];
+  if (id === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: thread show requires <id>`);
+    return 1;
+  }
+  const result = await cmdThreadShow(storageRoot, id);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(result.value);
+  return 0;
+}
+
+export async function dispatchThreadRm(storageRoot: string, argv: string[]): Promise<number> {
+  const id = argv[0];
+  if (id === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: thread rm requires <id>`);
+    return 1;
+  }
+  const result = await cmdThreadRemove(storageRoot, id);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`removed thread ${id}`);
+  return 0;
+}
+
+export async function dispatchFork(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseForkArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${usageText()}\n\nerror: ${parsed.error}`);
+    return 1;
+  }
+  const result = await cmdFork(storageRoot, parsed.value.threadId, parsed.value.fromRole);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(result.value.threadId);
+  return 0;
+}
+
+export const THREAD_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  run: {
+    handler: dispatchRun,
+    args: "<name> [--prompt <text>] [--max-rounds N]",
+    description: "Start a new thread executing a workflow",
+  },
+  list: {
+    handler: dispatchThreadList,
+    args: "[name]",
+    description: "List threads, optionally filtered by workflow name",
+  },
+  show: { handler: dispatchThreadShow, args: "<id>", description: "Show thread details and state" },
+  rm: { handler: dispatchThreadRm, args: "<id>", description: "Remove a thread" },
+  fork: {
+    handler: dispatchFork,
+    args: "<thread-id> [--from-role <role>]",
+    description: "Fork a thread, optionally from a specific role",
+  },
+  ps: { handler: dispatchPs, args: "", description: "List running threads" },
+  kill: { handler: dispatchKill, args: "<thread-id>", description: "Kill a running thread" },
+  live: {
+    handler: dispatchLive,
+    args: "<thread-id> | --latest [--debug] [--role <name>]",
+    description: "Attach to a thread and stream output live",
+  },
+  pause: { handler: dispatchPause, args: "<thread-id>", description: "Pause a running thread" },
+  resume: { handler: dispatchResume, args: "<thread-id>", description: "Resume a paused thread" },
+};
+
+export function createThreadDispatcher(deps: ThreadDispatchDeps) {
+  const { dispatchGroup } = deps;
+  return async function dispatchThread(storageRoot: string, argv: string[]): Promise<number> {
+    const result = dispatchGroup("thread", THREAD_SUBCOMMAND_TABLE, storageRoot, argv);
+    if (result !== null) {
+      return result;
+    }
+    const sub = argv[0];
+    printCliError(`${usageText()}\n\nerror: unknown thread subcommand: ${sub}`);
+    return 1;
+  };
+}

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

@@ -0,0 +1,28 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+import type { ParsedForkArgv } from "./types.js";
+
+export function parseForkArgv(argv: string[]): Result<ParsedForkArgv, string> {
+  if (argv.length === 0) {
+    return err("fork requires <thread-id>");
+  }
+  const threadId = argv[0];
+  if (threadId === undefined || threadId === "") {
+    return err("fork requires <thread-id>");
+  }
+  let fromRole: string | null = null;
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--from-role") {
+      const r = argv[i + 1];
+      if (r === undefined || r === "") {
+        return err("--from-role requires a role name");
+      }
+      fromRole = r;
+      i++;
+      continue;
+    }
+    return err(`unexpected argument: ${a}`);
+  }
+  return ok({ threadId, fromRole });
+}

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

@@ -6,33 +6,6 @@ import { pathExists, readTextFileIfExists } from "../../fs-utils.js";
 import { resolveThreadDataPath } from "../../thread-scan.js";
 import { ensureWorkerForHash, sendWorkerTcpCommand } from "../../worker-spawn.js";
 
-export function parseForkArgv(
-  argv: string[],
-): Result<{ threadId: string; fromRole: string | null }, string> {
-  if (argv.length === 0) {
-    return err("fork requires <thread-id>");
-  }
-  const threadId = argv[0];
-  if (threadId === undefined || threadId === "") {
-    return err("fork requires <thread-id>");
-  }
-  let fromRole: string | null = null;
-  for (let i = 1; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--from-role") {
-      const r = argv[i + 1];
-      if (r === undefined || r === "") {
-        return err("--from-role requires a role name");
-      }
-      fromRole = r;
-      i++;
-      continue;
-    }
-    return err(`unexpected argument: ${a}`);
-  }
-  return ok({ threadId, fromRole });
-}
-
 export async function cmdFork(
   storageRoot: string,
   threadId: string,

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

@@ -1,7 +1,21 @@
-export { cmdFork, parseForkArgv } from "./fork.js";
-export { cmdKill } from "./kill.js";
+export { cmdKill, cmdPause, cmdResume } from "./control.js";
+export {
+  createThreadDispatcher,
+  dispatchFork,
+  dispatchKill,
+  dispatchLive,
+  dispatchPause,
+  dispatchPs,
+  dispatchResume,
+  dispatchRun,
+  dispatchThreadList,
+  dispatchThreadRm,
+  dispatchThreadShow,
+  THREAD_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
+export { cmdFork } from "./fork.js";
+export { parseForkArgv } from "./fork-argv.js";
 export { cmdThreads } from "./list.js";
-export type { LiveRoleRow } from "./live.js";
 export {
   cmdLive,
   formatLiveDebugLine,
@@ -9,9 +23,8 @@ export {
   LIVE_CONTENT_MAX_LINES,
   renderLiveRoleStepLines,
 } from "./live.js";
-export { cmdPause } from "./pause.js";
 export { cmdPs } from "./ps.js";
-export { cmdResume } from "./resume.js";
 export { cmdThreadRemove } from "./rm.js";
 export { cmdRun } from "./run.js";
 export { cmdThreadShow } from "./show.js";
+export type { LiveRoleRow } from "./types.js";

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

@@ -1,43 +0,0 @@
-import { join } from "node:path";
-
-import { err, type Result } from "@uncaged/workflow";
-
-import { readTextFileIfExists } from "../../fs-utils.js";
-import {
-  resolveRunningHashForThread,
-  sendWorkerTcpCommand,
-  type WorkerCtl,
-} from "../../worker-spawn.js";
-
-export async function cmdKill(
-  storageRoot: string,
-  threadId: string,
-): Promise<Result<void, string>> {
-  const hashResult = await resolveRunningHashForThread(storageRoot, threadId);
-  if (!hashResult.ok) {
-    return hashResult;
-  }
-
-  const ctlPath = join(storageRoot, "workers", `${hashResult.value}.json`);
-  const ctlText = await readTextFileIfExists(ctlPath);
-  if (ctlText === null) {
-    return err(`worker control file missing for bundle hash ${hashResult.value}`);
-  }
-
-  let ctl: WorkerCtl;
-  try {
-    ctl = JSON.parse(ctlText) as WorkerCtl;
-  } catch {
-    return err(`corrupt worker control file: ${ctlPath}`);
-  }
-
-  if (typeof ctl.port !== "number" || ctl.port <= 0) {
-    return err(`invalid worker control file: ${ctlPath}`);
-  }
-
-  return await sendWorkerTcpCommand(
-    ctl.port,
-    { type: "kill", threadId },
-    { awaitResponseLine: true },
-  );
-}

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

@@ -12,20 +12,15 @@ import {
   type WorkflowCompletion,
 } from "@uncaged/workflow";
 
+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 type { LiveRoleRow } from "./types.js";
 
 export const LIVE_CONTENT_MAX_LINES = 10;
 
-export type LiveRoleRow = {
-  role: string;
-  content: string;
-  meta: Record<string, unknown>;
-  timestamp: number;
-};
-
 export function formatLiveTimeLabel(timestampMs: number): string {
   const d = new Date(timestampMs);
   const hh = String(d.getHours()).padStart(2, "0");
@@ -34,24 +29,6 @@ export function formatLiveTimeLabel(timestampMs: number): string {
   return `${hh}:${mm}:${ss}`;
 }
 
-function shouldUseColor(): boolean {
-  return process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
-}
-
-function highlightLiveRole(name: string): string {
-  if (!shouldUseColor()) {
-    return name;
-  }
-  return `\x1b[1m\x1b[36m${name}\x1b[0m`;
-}
-
-function dimGreyLine(line: string): string {
-  if (!shouldUseColor()) {
-    return line;
-  }
-  return `\x1b[2m\x1b[90m${line}\x1b[0m`;
-}
-
 export function formatLiveDebugLine(timestampMs: number, tag: string, message: string): string {
   const label = `[${formatLiveTimeLabel(timestampMs)}] [${tag}] ${message.replace(/\n/g, " ")}`;
   return dimGreyLine(label);

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

@@ -1,43 +0,0 @@
-import { join } from "node:path";
-
-import { err, type Result } from "@uncaged/workflow";
-
-import { readTextFileIfExists } from "../../fs-utils.js";
-import {
-  resolveRunningHashForThread,
-  sendWorkerTcpCommand,
-  type WorkerCtl,
-} from "../../worker-spawn.js";
-
-export async function cmdPause(
-  storageRoot: string,
-  threadId: string,
-): Promise<Result<void, string>> {
-  const hashResult = await resolveRunningHashForThread(storageRoot, threadId);
-  if (!hashResult.ok) {
-    return hashResult;
-  }
-
-  const ctlPath = join(storageRoot, "workers", `${hashResult.value}.json`);
-  const ctlText = await readTextFileIfExists(ctlPath);
-  if (ctlText === null) {
-    return err(`worker control file missing for bundle hash ${hashResult.value}`);
-  }
-
-  let ctl: WorkerCtl;
-  try {
-    ctl = JSON.parse(ctlText) as WorkerCtl;
-  } catch {
-    return err(`corrupt worker control file: ${ctlPath}`);
-  }
-
-  if (typeof ctl.port !== "number" || ctl.port <= 0) {
-    return err(`invalid worker control file: ${ctlPath}`);
-  }
-
-  return await sendWorkerTcpCommand(
-    ctl.port,
-    { type: "pause", threadId },
-    { awaitResponseLine: true },
-  );
-}

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

@@ -1,43 +0,0 @@
-import { join } from "node:path";
-
-import { err, type Result } from "@uncaged/workflow";
-
-import { readTextFileIfExists } from "../../fs-utils.js";
-import {
-  resolveRunningHashForThread,
-  sendWorkerTcpCommand,
-  type WorkerCtl,
-} from "../../worker-spawn.js";
-
-export async function cmdResume(
-  storageRoot: string,
-  threadId: string,
-): Promise<Result<void, string>> {
-  const hashResult = await resolveRunningHashForThread(storageRoot, threadId);
-  if (!hashResult.ok) {
-    return hashResult;
-  }
-
-  const ctlPath = join(storageRoot, "workers", `${hashResult.value}.json`);
-  const ctlText = await readTextFileIfExists(ctlPath);
-  if (ctlText === null) {
-    return err(`worker control file missing for bundle hash ${hashResult.value}`);
-  }
-
-  let ctl: WorkerCtl;
-  try {
-    ctl = JSON.parse(ctlText) as WorkerCtl;
-  } catch {
-    return err(`corrupt worker control file: ${ctlPath}`);
-  }
-
-  if (typeof ctl.port !== "number" || ctl.port <= 0) {
-    return err(`invalid worker control file: ${ctlPath}`);
-  }
-
-  return await sendWorkerTcpCommand(
-    ctl.port,
-    { type: "resume", threadId },
-    { awaitResponseLine: true },
-  );
-}

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

@@ -0,0 +1,17 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type LiveRoleRow = {
+  role: string;
+  content: string;
+  meta: Record<string, unknown>;
+  timestamp: number;
+};
+
+export type ParsedForkArgv = {
+  threadId: string;
+  fromRole: string | null;
+};
+
+export type ThreadDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+};

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

@@ -0,0 +1,72 @@
+import { err, ok, type Result } from "@uncaged/workflow";
+
+import type { ParsedAddArgv } from "./types.js";
+
+type ParsedLongFlag = { advance: 2; kind: "types"; value: string };
+
+function tryParseAddLongFlag(argv: string[], index: number): Result<ParsedLongFlag | null, string> {
+  const tok = argv[index];
+  if (tok !== "--types") {
+    return ok(null);
+  }
+  const value = argv[index + 1];
+  if (value === undefined || value.startsWith("--")) {
+    return err("missing value for --types");
+  }
+  return ok({ advance: 2, kind: "types", value });
+}
+
+type PositionalSlots = {
+  name: string | undefined;
+  filePath: string | undefined;
+};
+
+function assignPositional(tok: string, slots: PositionalSlots): Result<void, string> {
+  if (slots.name === undefined) {
+    slots.name = tok;
+    return ok(undefined);
+  }
+  if (slots.filePath === undefined) {
+    slots.filePath = tok;
+    return ok(undefined);
+  }
+  return err("too many arguments");
+}
+
+export function parseAddArgv(argv: string[]): Result<ParsedAddArgv, string> {
+  const slots: PositionalSlots = { name: undefined, filePath: undefined };
+  let typesPath: string | null = null;
+
+  let i = 0;
+  while (i < argv.length) {
+    const flag = tryParseAddLongFlag(argv, i);
+    if (!flag.ok) {
+      return flag;
+    }
+    if (flag.value !== null) {
+      typesPath = flag.value.value;
+      i += flag.value.advance;
+      continue;
+    }
+
+    const tok = argv[i];
+    if (tok?.startsWith("--")) {
+      return err(`unknown add flag: ${tok}`);
+    }
+    if (tok === undefined) {
+      break;
+    }
+    const placed = assignPositional(tok, slots);
+    if (!placed.ok) {
+      return placed;
+    }
+    i += 1;
+  }
+
+  const { name, filePath } = slots;
+  if (name === undefined || name === "" || filePath === undefined || filePath === "") {
+    return err("add requires <name> <file>");
+  }
+
+  return ok({ name, filePath, typesPath });
+}

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

@@ -17,17 +17,7 @@ import {
 import { storeWorkflowBundleArtifacts } from "../../bundle-store.js";
 import { validateCliWorkflowName } from "../../workflow-name.js";
 
-export type ParsedAddArgv = {
-  name: string;
-  filePath: string;
-  /** Override path to `.d.ts` when adding a bundle. */
-  typesPath: string | null;
-};
-
-export type CmdAddSuccess = {
-  hash: string;
-  warnings: ReadonlyArray<string>;
-};
+import type { CmdAddSuccess, ParsedAddArgv } from "./types.js";
 
 function isEsmBundle(path: string): boolean {
   return path.endsWith(".esm.js");
@@ -37,75 +27,6 @@ function defaultTypesPath(bundlePath: string): string {
   return bundlePath.replace(/\.esm\.js$/i, ".d.ts");
 }
 
-type ParsedLongFlag = { advance: 2; kind: "types"; value: string };
-
-function tryParseAddLongFlag(argv: string[], index: number): Result<ParsedLongFlag | null, string> {
-  const tok = argv[index];
-  if (tok !== "--types") {
-    return ok(null);
-  }
-  const value = argv[index + 1];
-  if (value === undefined || value.startsWith("--")) {
-    return err("missing value for --types");
-  }
-  return ok({ advance: 2, kind: "types", value });
-}
-
-type PositionalSlots = {
-  name: string | undefined;
-  filePath: string | undefined;
-};
-
-function assignPositional(tok: string, slots: PositionalSlots): Result<void, string> {
-  if (slots.name === undefined) {
-    slots.name = tok;
-    return ok(undefined);
-  }
-  if (slots.filePath === undefined) {
-    slots.filePath = tok;
-    return ok(undefined);
-  }
-  return err("too many arguments");
-}
-
-export function parseAddArgv(argv: string[]): Result<ParsedAddArgv, string> {
-  const slots: PositionalSlots = { name: undefined, filePath: undefined };
-  let typesPath: string | null = null;
-
-  let i = 0;
-  while (i < argv.length) {
-    const flag = tryParseAddLongFlag(argv, i);
-    if (!flag.ok) {
-      return flag;
-    }
-    if (flag.value !== null) {
-      typesPath = flag.value.value;
-      i += flag.value.advance;
-      continue;
-    }
-
-    const tok = argv[i];
-    if (tok?.startsWith("--")) {
-      return err(`unknown add flag: ${tok}`);
-    }
-    if (tok === undefined) {
-      break;
-    }
-    const placed = assignPositional(tok, slots);
-    if (!placed.ok) {
-      return placed;
-    }
-    i += 1;
-  }
-
-  const { name, filePath } = slots;
-  if (name === undefined || name === "" || filePath === undefined || filePath === "") {
-    return err("add requires <name> <file>");
-  }
-
-  return ok({ name, filePath, typesPath });
-}
-
 async function registerHash(
   storageRoot: string,
   name: string,

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

@@ -0,0 +1,159 @@
+import type { CommandEntry } from "../../cli-command-types.js";
+import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
+import { formatCliUsage, USAGE_SKILL_TOPIC_ROWS } from "../../cli-usage.js";
+import { getCommandGroupsForUsage } from "../../cli-usage-context.js";
+import { cmdAdd, formatAddSuccess } from "./add.js";
+import { parseAddArgv } from "./add-argv.js";
+import { cmdHistory } from "./history.js";
+import { cmdList, formatListLines } from "./list.js";
+import { cmdRemove } from "./rm.js";
+import { cmdRollback } from "./rollback.js";
+import { cmdShow, formatShowYaml } from "./show.js";
+import type { WorkflowDispatchDeps } from "./types.js";
+
+function usageText(): string {
+  return formatCliUsage(getCommandGroupsForUsage(), USAGE_SKILL_TOPIC_ROWS);
+}
+
+export async function dispatchAdd(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseAddArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${usageText()}\n\nerror: ${parsed.error}`);
+    return 1;
+  }
+  const result = await cmdAdd(storageRoot, parsed.value);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  for (const w of result.value.warnings) {
+    printCliWarn(w);
+  }
+  printCliLine(formatAddSuccess(parsed.value.name, parsed.value.filePath, result.value.hash));
+  return 0;
+}
+
+export async function dispatchList(storageRoot: string, argv: string[]): Promise<number> {
+  if (argv.length > 0) {
+    printCliError(`${usageText()}\n\nerror: list takes no arguments`);
+    return 1;
+  }
+  const result = await cmdList(storageRoot);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  for (const line of formatListLines(result.value)) {
+    printCliLine(line);
+  }
+  return 0;
+}
+
+export async function dispatchShow(storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: show requires <name>`);
+    return 1;
+  }
+  const result = await cmdShow(storageRoot, name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(formatShowYaml(name, result.value));
+  return 0;
+}
+
+export async function dispatchRemove(storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: remove requires <name>`);
+    return 1;
+  }
+  const result = await cmdRemove(storageRoot, name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`removed workflow "${name}" from registry`);
+  return 0;
+}
+
+export async function dispatchHistory(storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 1) {
+    printCliError(`${usageText()}\n\nerror: history requires <name>`);
+    return 1;
+  }
+  const result = await cmdHistory(storageRoot, name);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  for (const line of result.value) {
+    printCliLine(line);
+  }
+  return 0;
+}
+
+export async function dispatchRollback(storageRoot: string, argv: string[]): Promise<number> {
+  const name = argv[0];
+  if (name === undefined || argv.length > 2) {
+    printCliError(`${usageText()}\n\nerror: rollback requires <name> [hash]`);
+    return 1;
+  }
+  const hashArg = argv[1];
+  const result = await cmdRollback(storageRoot, name, hashArg === undefined ? null : hashArg);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printCliLine(`rolled back workflow "${name}"`);
+  return 0;
+}
+
+export const WORKFLOW_SUBCOMMAND_TABLE: Record<string, CommandEntry> = {
+  add: {
+    handler: dispatchAdd,
+    args: "<name> <file.esm.js> [--types <path>]",
+    description: "Register a workflow bundle in the registry",
+  },
+  list: { handler: dispatchList, args: "", description: "List all registered workflows" },
+  show: {
+    handler: dispatchShow,
+    args: "<name>",
+    description: "Show details of a registered workflow",
+  },
+  rm: {
+    handler: dispatchRemove,
+    args: "<name>",
+    description: "Remove a workflow from the registry",
+  },
+  history: {
+    handler: dispatchHistory,
+    args: "<name>",
+    description: "Show version history of a workflow",
+  },
+  rollback: {
+    handler: dispatchRollback,
+    args: "<name> [hash]",
+    description: "Rollback a workflow to a previous version",
+  },
+};
+
+export function createWorkflowDispatcher(deps: WorkflowDispatchDeps) {
+  const { dispatchGroup, printDeprecation } = deps;
+  return async function dispatchWorkflow(storageRoot: string, argv: string[]): Promise<number> {
+    const result = dispatchGroup("workflow", WORKFLOW_SUBCOMMAND_TABLE, storageRoot, argv);
+    if (result !== null) {
+      return result;
+    }
+    const sub = argv[0];
+    if (sub === "remove") {
+      printDeprecation("workflow remove", "workflow rm");
+      return dispatchRemove(storageRoot, argv.slice(1));
+    }
+    printCliError(`${usageText()}\n\nerror: unknown workflow subcommand: ${sub}`);
+    return 1;
+  };
+}

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

@@ -1,7 +1,18 @@
-export type { CmdAddSuccess, ParsedAddArgv } from "./add.js";
-export { cmdAdd, formatAddSuccess, parseAddArgv } from "./add.js";
+export { cmdAdd, formatAddSuccess } from "./add.js";
+export { parseAddArgv } from "./add-argv.js";
+export {
+  createWorkflowDispatcher,
+  dispatchAdd,
+  dispatchHistory,
+  dispatchList,
+  dispatchRemove,
+  dispatchRollback,
+  dispatchShow,
+  WORKFLOW_SUBCOMMAND_TABLE,
+} from "./dispatch.js";
 export { cmdHistory } from "./history.js";
 export { cmdList, formatListLines } from "./list.js";
 export { cmdRemove } from "./rm.js";
 export { cmdRollback } from "./rollback.js";
 export { cmdShow, formatShowYaml } from "./show.js";
+export type { CmdAddSuccess, ParsedAddArgv } from "./types.js";

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

@@ -0,0 +1,18 @@
+import type { DispatchGroupFn } from "../../cli-command-types.js";
+
+export type ParsedAddArgv = {
+  name: string;
+  filePath: string;
+  /** Override path to `.d.ts` when adding a bundle. */
+  typesPath: string | null;
+};
+
+export type CmdAddSuccess = {
+  hash: string;
+  warnings: ReadonlyArray<string>;
+};
+
+export type WorkflowDispatchDeps = {
+  dispatchGroup: DispatchGroupFn;
+  printDeprecation: (oldCmd: string, newCmd: string) => void;
+};

packages/cli-workflow/src/skill.ts

@@ -1,4 +1,4 @@
-import { getCommandRegistry } from "./cli-dispatch.js";
+import { getCommandRegistry } from "./cli-registry.js";
 
 type SkillTopic = {
   name: string;
@@ -126,13 +126,13 @@ uncaged-workflow thread list
 
 ## CAS (Content-Addressable Storage)
 
-Store and retrieve content by hash, scoped to the current thread.
+Store and retrieve content by hash in workflow storage (global CAS directory).
 
 | Operation | Command |
 |-----------|---------|
-| **Store** | \`uncaged-workflow cas put <THREAD_ID> '<content>'\` → prints hash |
-| **Read** | \`uncaged-workflow cas get <THREAD_ID> <HASH>\` → prints content |
-| **List** | \`uncaged-workflow cas list <THREAD_ID>\` |
+| **Store** | \`uncaged-workflow cas put '<content>'\` → prints hash |
+| **Read** | \`uncaged-workflow cas get <HASH>\` → prints content |
+| **List** | \`uncaged-workflow cas list\` |
 
 CAS is the **only** supported way to persist structured data (phase plans, review notes, etc.) within a thread. Do not use temp files.
 

packages/cli-workflow/src/thread-scan.ts

@@ -3,6 +3,23 @@ import { join } from "node:path";
 
 import { pathExists, readTextFileIfExists } from "./fs-utils.js";
 
+function parseFirstJsonLineObject(text: string): Record<string, unknown> | null {
+  const firstLine = text.split("\n")[0];
+  if (firstLine === undefined || firstLine.trim() === "") {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(firstLine) as unknown;
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return null;
+  }
+  return parsed as Record<string, unknown>;
+}
+
 export type RunningThreadRow = {
   threadId: string;
   hash: string;
@@ -20,20 +37,11 @@ async function readThreadStartTimestampMs(dataPath: string): Promise<number | nu
   if (text === null) {
     return null;
   }
-  const firstLine = text.split("\n")[0];
-  if (firstLine === undefined || firstLine.trim() === "") {
+  const parsed = parseFirstJsonLineObject(text);
+  if (parsed === null) {
     return null;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(firstLine) as unknown;
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return null;
-  }
-  const ts = (parsed as Record<string, unknown>).timestamp;
+  const ts = parsed.timestamp;
   return typeof ts === "number" && Number.isFinite(ts) ? ts : null;
 }
 
@@ -42,20 +50,11 @@ async function readWorkflowNameFromDataJsonl(dataPath: string): Promise<string |
   if (text === null) {
     return null;
   }
-  const firstLine = text.split("\n")[0];
-  if (firstLine === undefined || firstLine.trim() === "") {
+  const parsed = parseFirstJsonLineObject(text);
+  if (parsed === null) {
     return null;
   }
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(firstLine) as unknown;
-  } catch {
-    return null;
-  }
-  if (parsed === null || typeof parsed !== "object") {
-    return null;
-  }
-  const name = (parsed as Record<string, unknown>).name;
+  const name = parsed.name;
   return typeof name === "string" ? name : null;
 }
 

packages/cli-workflow/src/worker-spawn.ts

@@ -237,6 +237,30 @@ export async function sendWorkerTcpCommand(
   });
 }
 
+export async function readWorkerCtl(
+  storageRoot: string,
+  hash: string,
+): Promise<Result<WorkerCtl, string>> {
+  const ctlPath = join(storageRoot, "workers", `${hash}.json`);
+  const ctlText = await readTextFileIfExists(ctlPath);
+  if (ctlText === null) {
+    return err(`worker control file missing for bundle hash ${hash}`);
+  }
+
+  let ctl: WorkerCtl;
+  try {
+    ctl = JSON.parse(ctlText) as WorkerCtl;
+  } catch {
+    return err(`corrupt worker control file: ${ctlPath}`);
+  }
+
+  if (typeof ctl.port !== "number" || ctl.port <= 0) {
+    return err(`invalid worker control file: ${ctlPath}`);
+  }
+
+  return ok(ctl);
+}
+
 export async function resolveRunningHashForThread(
   storageRoot: string,
   threadId: string,

packages/workflow-agent-cursor/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow-agent-hermes/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow-agent-llm/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow-template-develop/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow-template-develop/src/index.ts

@@ -1,8 +1,6 @@
 import {
   type AgentBinding,
   createWorkflow,
-  type ExtractFn,
-  type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
 } from "@uncaged/workflow";
@@ -43,10 +41,6 @@ export const developWorkflowDefinition: WorkflowDefinition<DevelopMeta> = {
   moderator: developModerator,
 };
 
-export function createDevelopRun(
-  binding: AgentBinding,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
-): WorkflowFn {
-  return createWorkflow(developWorkflowDefinition, binding, extract, llmProvider);
+export function createDevelopRun(binding: AgentBinding): WorkflowFn {
+  return createWorkflow(developWorkflowDefinition, binding);
 }

packages/workflow-template-develop/src/roles/reviewer.ts

@@ -12,8 +12,27 @@ export const reviewerMetaSchema = z.discriminatedUnion("status", [
 ]);
 export type ReviewerMeta = z.infer<typeof reviewerMetaSchema>;
 
-const REVIEWER_SYSTEM = `You are a code reviewer. Review the current git diff. Give a clear approve or reject verdict.
-Only reject for blocking issues. End with your verdict.`;
+const REVIEWER_SYSTEM = `You are a code reviewer. Review the git diff for correctness, consistency, and adherence to project conventions.
+
+## Review process
+
+1. Read the **preparer**'s output in the thread for project conventions (coding style, naming, commit format, etc.).
+2. Review the diff against these conventions.
+3. For documentation changes, verify that names, paths, and references match the actual codebase.
+
+## Review checklist
+
+- **Correctness** — does the code do what it claims? Logic bugs, off-by-one, missing returns?
+- **Conventions** — naming, imports, code style per project rules?
+- **Consistency** — do docs/comments match actual code? Are references current and accurate?
+- **Edge cases** — missing error handling, null checks, boundary conditions?
+
+## Verdict
+
+- **Approve** only if there are zero issues
+- **Reject** with specific issues that must be fixed — every issue you find is blocking
+
+Be thorough. A false approve costs more than a false reject.`;
 
 export const reviewerRole: RoleDefinition<ReviewerMeta> = {
   description: "Runs git diff checks and sets approved when the change is ready.",

packages/workflow-template-solve-issue/__tests__/solve-issue-template.test.ts

@@ -250,17 +250,20 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     // Override developer so the test does not spin up a child workflow.
-    const run = createSolveIssueRun(
-      {
-        agent: async () => "",
-        overrides: { developer: async () => "stub-root-hash" },
-      },
-      stubExtract,
-      stubLlmProvider,
-    );
+    const run = createSolveIssueRun({
+      agent: async () => "",
+      overrides: { developer: async () => "stub-root-hash" },
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     const first = await gen.next();
     expect(first.done).toBe(false);
@@ -294,33 +297,36 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     const calls: string[] = [];
-    const run = createSolveIssueRun(
-      {
-        agent: async () => {
-          calls.push("default");
+    const run = createSolveIssueRun({
+      agent: async () => {
+        calls.push("default");
+        return "";
+      },
+      overrides: {
+        preparer: async () => {
+          calls.push("preparer");
           return "";
         },
-        overrides: {
-          preparer: async () => {
-            calls.push("preparer");
-            return "";
-          },
-          developer: async () => {
-            calls.push("developer");
-            return "stub-root-hash";
-          },
-          submitter: async () => {
-            calls.push("submitter");
-            return "";
-          },
+        developer: async () => {
+          calls.push("developer");
+          return "stub-root-hash";
+        },
+        submitter: async () => {
+          calls.push("submitter");
+          return "";
         },
       },
-      stubExtract,
-      stubLlmProvider,
-    );
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     await gen.next();
     expect(calls).toEqual(["preparer"]);
@@ -353,22 +359,25 @@ describe("createSolveIssueRun", () => {
     const cas = createCasStore(casDir);
 
     let developerInvocations = 0;
-    const run = createSolveIssueRun(
-      {
-        agent: async () => "",
-        overrides: {
-          developer: async () => {
-            developerInvocations += 1;
-            return "stub-root-hash";
-          },
+    const run = createSolveIssueRun({
+      agent: async () => "",
+      overrides: {
+        developer: async () => {
+          developerInvocations += 1;
+          return "stub-root-hash";
         },
       },
-      stubExtract,
-      stubLlmProvider,
-    );
+    });
     const gen = run(
       { prompt: "task", steps: [] },
-      { threadId: "01TEST000000000000000000TR", maxRounds: 20, depth: 0, cas },
+      {
+        threadId: "01TEST000000000000000000TR",
+        maxRounds: 20,
+        depth: 0,
+        cas,
+        extract: stubExtract,
+        llmProvider: stubLlmProvider,
+      },
     );
     // preparer
     await gen.next();

packages/workflow-template-solve-issue/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow-template-solve-issue/src/index.ts

@@ -1,8 +1,6 @@
 import {
   type AgentBinding,
   createWorkflow,
-  type ExtractFn,
-  type LlmProvider,
   type WorkflowDefinition,
   type WorkflowFn,
   workflowAsAgent,
@@ -46,11 +44,7 @@ export const solveIssueWorkflowDefinition: WorkflowDefinition<SolveIssueMeta> =
  * {@link workflowAsAgent}; if the caller supplies their own `developer` override in
  * `binding.overrides`, it takes precedence so tests and custom hosts can stub it.
  */
-export function createSolveIssueRun(
-  binding: AgentBinding,
-  extract: ExtractFn,
-  llmProvider: LlmProvider | null,
-): WorkflowFn {
+export function createSolveIssueRun(binding: AgentBinding): WorkflowFn {
   const developerOverride = binding.overrides?.developer ?? workflowAsAgent("develop");
   const mergedBinding: AgentBinding = {
     agent: binding.agent,
@@ -59,5 +53,5 @@ export function createSolveIssueRun(
       developer: developerOverride,
     },
   };
-  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding, extract, llmProvider);
+  return createWorkflow(solveIssueWorkflowDefinition, mergedBinding);
 }

packages/workflow-util-agent/package.json

@@ -11,7 +11,6 @@
     }
   },
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow/__tests__/base32.test.ts

@@ -5,7 +5,7 @@ import {
   decodeCrockfordToUint64,
   encodeCrockfordBase32Bits,
   encodeUint64AsCrockford,
-} from "../src/base32.js";
+} from "../src/util/base32.js";
 
 describe("Crockford Base32", () => {
   test("roundtrip 64-bit hash encoding", () => {

packages/workflow/__tests__/build-descriptor.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import * as z from "zod/v4";
 
-import { buildDescriptor } from "../src/build-descriptor.js";
+import { buildDescriptor } from "../src/bundle/build-descriptor.js";
+import { validateWorkflowDescriptor } from "../src/bundle/workflow-descriptor.js";
 import { END } from "../src/types.js";
-import { validateWorkflowDescriptor } from "../src/workflow-descriptor.js";
 
 describe("buildDescriptor", () => {
   test("produces a descriptor that validates and includes JSON schemas per role", () => {

packages/workflow/__tests__/bundle-validator.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { validateWorkflowBundle } from "../src/bundle-validator.js";
+import { validateWorkflowBundle } from "../src/bundle/bundle-validator.js";
 
 const minimalDescriptor = `export const descriptor = { description: "x", roles: {} };
 `;

packages/workflow/__tests__/cas.test.ts

@@ -3,8 +3,8 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore, createThreadCas } from "../src/cas.js";
-import { hashString } from "../src/hash.js";
+import { createCasStore, createThreadCas } from "../src/cas/cas.js";
+import { hashString } from "../src/cas/hash.js";
 
 describe("cas module exports", () => {
   test("createThreadCas is a deprecated alias of createCasStore", () => {

packages/workflow/__tests__/engine.test.ts

@@ -1,21 +1,20 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { createLogger } from "../src/logger.js";
+import { createCasStore } from "../src/cas/cas.js";
 import {
   createContentMerkleNode,
   getContentMerklePayload,
   parseMerkleNode,
   serializeMerkleNode,
-} from "../src/merkle.js";
-import { END, type LlmProvider } from "../src/types.js";
+} from "../src/cas/merkle.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
+import { END } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 
 const plannerMetaSchema = z.object({
   plan: z.string(),
@@ -82,11 +81,20 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const demoExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const EXTRACT_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
+
+async function writeExtractRegistryConfig(storageRoot: string): Promise<void> {
+  await writeFile(join(storageRoot, "workflow.yaml"), EXTRACT_REGISTRY_YAML, "utf8");
+}
 
 const demoWorkflow = createWorkflow<DemoMeta>(
   {
@@ -125,8 +133,6 @@ const demoWorkflow = createWorkflow<DemoMeta>(
       coder: async () => "code-body",
     },
   },
-  demoExtract,
-  null,
 );
 
 describe("executeThread", () => {
@@ -150,6 +156,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -166,6 +173,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -258,6 +266,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
       const plannerHash = await cas.put(serializeMerkleNode(createContentMerkleNode("plan-body")));
 
@@ -295,6 +304,7 @@ describe("executeThread", () => {
               timestamp: histTs,
             },
           ],
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -354,6 +364,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -391,6 +402,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -407,6 +419,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,
@@ -549,9 +562,6 @@ describe("executeThread", () => {
         { preconnect: origFetch.preconnect.bind(origFetch) },
       ) as typeof fetch;
 
-      const llm: LlmProvider = { baseUrl: "http://127.0.0.1:9", apiKey: "test", model: "test" };
-      const extractFn = createExtract(llm);
-
       const dagWorkflow = createWorkflow<DagDemoMeta>(
         {
           roles: {
@@ -568,8 +578,6 @@ describe("executeThread", () => {
           moderator: (ctx) => (ctx.steps.length === 0 ? "walker" : END),
         },
         { agent: async () => dagRootHash },
-        extractFn,
-        llm,
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
@@ -577,6 +585,7 @@ describe("executeThread", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeExtractRegistryConfig(root);
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
       const ac = new AbortController();
@@ -592,6 +601,7 @@ describe("executeThread", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/extract-provider.test.ts

@@ -1,87 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { getExtractProvider } from "../src/extract-provider.js";
-
-describe("getExtractProvider", () => {
-  test("returns provider when config.extract is present", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-ok-"));
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(
-        join(root, "workflow.yaml"),
-        `config:
-  maxDepth: 3
-  extract:
-    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-    model: qwen-plus
-    apiKey: literal-key
-workflows: {}
-`,
-        "utf8",
-      );
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(true);
-      if (!r.ok) {
-        return;
-      }
-      expect(r.value.baseUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
-      expect(r.value.model).toBe("qwen-plus");
-      expect(r.value.apiKey).toBe("literal-key");
-    } finally {
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-
-  test("errs when registry has no config section", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-missing-"));
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(join(root, "workflow.yaml"), "workflows: {}\n", "utf8");
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(false);
-      if (r.ok) {
-        return;
-      }
-      expect(r.error).toContain("no global config");
-    } finally {
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-
-  test("resolves apiKey from env at registry read time", async () => {
-    const root = await mkdtemp(join(tmpdir(), "wf-ext-prov-env-"));
-    const prev = process.env.WF_GET_EXTRACT_PROVIDER_KEY;
-    process.env.WF_GET_EXTRACT_PROVIDER_KEY = "resolved-secret";
-    try {
-      await mkdir(root, { recursive: true });
-      await writeFile(
-        join(root, "workflow.yaml"),
-        `config:
-  maxDepth: 1
-  extract:
-    baseUrl: https://example.com
-    model: m
-    apiKey: env:WF_GET_EXTRACT_PROVIDER_KEY
-workflows: {}
-`,
-        "utf8",
-      );
-      const r = await getExtractProvider(root);
-      expect(r.ok).toBe(true);
-      if (!r.ok) {
-        return;
-      }
-      expect(r.value.apiKey).toBe("resolved-secret");
-    } finally {
-      if (prev === undefined) {
-        delete process.env.WF_GET_EXTRACT_PROVIDER_KEY;
-      } else {
-        process.env.WF_GET_EXTRACT_PROVIDER_KEY = prev;
-      }
-      await rm(root, { recursive: true, force: true });
-    }
-  });
-});

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

@@ -4,7 +4,7 @@ import {
   buildForkPlan,
   parseThreadDataJsonl,
   selectForkHistoricalSteps,
-} from "../src/fork-thread.js";
+} from "../src/engine/fork-thread.js";
 
 const sampleDataJsonl = `{"name":"demo","hash":"C9NMV6V2TQT81","threadId":"01AAA1111111111111111111","parameters":{"prompt":"hi","options":{"maxRounds":5}},"timestamp":100}
 {"role":"planner","contentHash":"HP0000000000000000000001","meta":{},"refs":[],"timestamp":101}

packages/workflow/__tests__/hash.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, test } from "bun:test";
-
-import { decodeCrockfordToUint64 } from "../src/base32.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { decodeCrockfordToUint64 } from "../src/util/base32.js";
 
 describe("hashWorkflowBundleBytes", () => {
   test("matches XXH64 reference for empty input", () => {

packages/workflow/__tests__/logger.test.ts

@@ -3,7 +3,7 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createLogger } from "../src/logger.js";
+import { createLogger } from "../src/util/logger.js";
 
 describe("createLogger", () => {
   test("writes JSONL records to a file sink", async () => {

packages/workflow/__tests__/merkle.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
-import { createContentMerkleNode, parseMerkleNode, serializeMerkleNode } from "../src/merkle.js";
+import {
+  createContentMerkleNode,
+  parseMerkleNode,
+  serializeMerkleNode,
+} from "../src/cas/merkle.js";
 
 describe("merkle", () => {
   test("content node roundtrips through YAML", () => {

packages/workflow/__tests__/react-extract.test.ts

@@ -4,9 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
-import { reactExtract } from "../src/react-extract.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
+import { reactExtract } from "../src/extract/react-extract.js";
 import type { LlmProvider } from "../src/types.js";
 
 const metaSchema = z.object({ seen: z.string() });

packages/workflow/__tests__/refs-tracking.test.ts

@@ -1,16 +1,15 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { buildForkPlan, parseThreadDataJsonl } from "../src/fork-thread.js";
-import { createLogger } from "../src/logger.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
+import { buildForkPlan, parseThreadDataJsonl } from "../src/engine/fork-thread.js";
 import { END } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 
 const phaseSchema = z.object({
   hash: z.string(),
@@ -76,11 +75,16 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const refsDemoExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const EXTRACT_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
 
 const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
   {
@@ -99,8 +103,6 @@ const refsDemoWorkflow = createWorkflow<RefsDemoMeta>(
   {
     agent: async () => "plan-output",
   },
-  refsDemoExtract,
-  null,
 );
 
 describe("RoleStep refs tracking", () => {
@@ -142,6 +144,7 @@ describe("RoleStep refs tracking", () => {
       const dataPath = join(root, "logs", hash, `${threadId}.data.jsonl`);
       const infoPath = join(root, "logs", hash, `${threadId}.info.jsonl`);
       await mkdir(join(root, "logs", hash), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), EXTRACT_REGISTRY_YAML, "utf8");
       const cas = createCasStore(join(root, "cas"));
 
       const logger = createLogger({ sink: { kind: "file", path: infoPath } });
@@ -158,6 +161,7 @@ describe("RoleStep refs tracking", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/registry.test.ts

@@ -10,7 +10,7 @@ import {
   rollbackWorkflowToHistoryHash,
   unregisterWorkflow,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 
 describe("workflow registry", () => {
   test("roundtrips through workflow.yaml", async () => {
@@ -105,10 +105,13 @@ describe("workflow registry", () => {
     const yaml = `
 config:
   maxDepth: 3
-  extract:
-    baseUrl: https://example.com/v1
-    model: qwen-plus
-    apiKey: secret-key
+  providers:
+    dashscope:
+      baseUrl: https://example.com/v1
+      apiKey: secret-key
+  models:
+    default: dashscope/qwen-turbo
+    extract: dashscope/qwen-plus
 workflows:
   solve-issue:
     hash: SPVR4BDMSGC1W
@@ -125,9 +128,10 @@ workflows:
       return;
     }
     expect(r.value.config.maxDepth).toBe(3);
-    expect(r.value.config.extract.baseUrl).toBe("https://example.com/v1");
-    expect(r.value.config.extract.model).toBe("qwen-plus");
-    expect(r.value.config.extract.apiKey).toBe("secret-key");
+    expect(r.value.config.providers.dashscope?.baseUrl).toBe("https://example.com/v1");
+    expect(r.value.config.providers.dashscope?.apiKey).toBe("secret-key");
+    expect(r.value.config.models.extract).toBe("dashscope/qwen-plus");
+    expect(r.value.config.models.default).toBe("dashscope/qwen-turbo");
   });
 
   test("parses config apiKey env: prefix from process.env", () => {
@@ -137,10 +141,13 @@ workflows:
       const yaml = `
 config:
   maxDepth: 1
-  extract:
-    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
-    model: qwen-plus
-    apiKey: env:WF_REGISTRY_TEST_API_KEY
+  providers:
+    dashscope:
+      baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+      apiKey: env:WF_REGISTRY_TEST_API_KEY
+  models:
+    default: dashscope/qwen-plus
+    extract: dashscope/qwen-plus
 workflows: {}
 `;
       const r = parseWorkflowRegistryYaml(yaml);
@@ -148,7 +155,7 @@ workflows: {}
       if (!r.ok) {
         return;
       }
-      expect(r.value.config?.extract.apiKey).toBe("from-env");
+      expect(r.value.config?.providers.dashscope?.apiKey).toBe("from-env");
     } finally {
       if (prev === undefined) {
         delete process.env.WF_REGISTRY_TEST_API_KEY;
@@ -165,10 +172,12 @@ workflows: {}
       const yaml = `
 config:
   maxDepth: 1
-  extract:
-    baseUrl: https://example.com
-    model: m
-    apiKey: env:WF_REGISTRY_TEST_API_KEY_UNSET
+  providers:
+    p:
+      baseUrl: https://example.com
+      apiKey: env:WF_REGISTRY_TEST_API_KEY_UNSET
+  models:
+    default: p/m
 workflows: {}
 `;
       const r = parseWorkflowRegistryYaml(yaml);

packages/workflow/__tests__/resolve-model.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+
+import { resolveModel } from "../src/config/resolve-model.js";
+import type { WorkflowConfig } from "../src/registry/index.js";
+
+function sampleConfig(): WorkflowConfig {
+  return {
+    maxDepth: 3,
+    providers: {
+      dashscope: {
+        baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        apiKey: "secret",
+      },
+      other: {
+        baseUrl: "https://other.example/v1",
+        apiKey: "k2",
+      },
+    },
+    models: {
+      default: "dashscope/qwen-plus",
+      extract: "other/foo/bar-model",
+    },
+  };
+}
+
+describe("resolveModel", () => {
+  test("uses explicit scene mapping", () => {
+    const config = sampleConfig();
+    const r = resolveModel(config, "extract");
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value.baseUrl).toBe("https://other.example/v1");
+    expect(r.value.apiKey).toBe("k2");
+    expect(r.value.model).toBe("foo/bar-model");
+  });
+
+  test("falls back to models.default when scene is missing", () => {
+    const config = sampleConfig();
+    const r = resolveModel(config, "unknown-scene");
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+    expect(r.value.model).toBe("qwen-plus");
+    expect(r.value.baseUrl).toBe("https://dashscope.aliyuncs.com/compatible-mode/v1");
+  });
+
+  test("errs when scene missing and no default", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        extract: "p/m",
+      },
+    };
+    const r = resolveModel(config, "other");
+    expect(r.ok).toBe(false);
+    if (r.ok) {
+      return;
+    }
+    expect(r.error).toContain("no model mapping");
+    expect(r.error).toContain("default");
+  });
+
+  test("errs when provider is unknown", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        default: "missing/m",
+      },
+    };
+    const r = resolveModel(config, "any");
+    expect(r.ok).toBe(false);
+    if (r.ok) {
+      return;
+    }
+    expect(r.error).toContain("unknown provider");
+  });
+
+  test("errs on invalid model reference shape", () => {
+    const config: WorkflowConfig = {
+      maxDepth: 1,
+      providers: {
+        p: { baseUrl: "https://x", apiKey: "k" },
+      },
+      models: {
+        default: "no-slash-model",
+      },
+    };
+    const r = resolveModel(config, "x");
+    expect(r.ok).toBe(false);
+  });
+});

packages/workflow/__tests__/result.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { err, ok } from "../src/result.js";
+import { err, ok } from "../src/util/result.js";
 
 describe("result helpers", () => {
   test("ok wraps value", () => {

packages/workflow/__tests__/storage-root.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import { join } from "node:path";
 
-import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "../src/storage-root.js";
+import { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "../src/util/storage-root.js";
 
 describe("getGlobalCasDir", () => {
   test("joins cas segment under explicit storage root", () => {

packages/workflow/__tests__/thread-pause-gate.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import { createThreadPauseGate } from "../src/thread-pause-gate.js";
+import { createThreadPauseGate } from "../src/engine/thread-pause-gate.js";
 
 describe("createThreadPauseGate", () => {
   test("pause blocks awaitAfterYield until resume", async () => {

packages/workflow/__tests__/ulid.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
-import { decodeCrockfordBase32Bits } from "../src/base32.js";
-import { generateUlid } from "../src/ulid.js";
+import { decodeCrockfordBase32Bits } from "../src/util/base32.js";
+import { generateUlid } from "../src/util/ulid.js";
 
 describe("generateUlid", () => {
   test("length and decodable Crockford payload", () => {

packages/workflow/__tests__/worker.test.ts

@@ -5,9 +5,20 @@ import { createConnection } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore } from "../src/cas.js";
-import { createContentMerkleNode, serializeMerkleNode } from "../src/merkle.js";
-import { getWorkerHostScriptPath } from "../src/worker-entry-path.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { createContentMerkleNode, serializeMerkleNode } from "../src/cas/merkle.js";
+import { getWorkerHostScriptPath } from "../src/engine/worker-entry-path.js";
+
+const WORKER_REGISTRY_YAML = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/model
+workflows: {}
+`;
 
 const bundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
 
@@ -89,6 +100,7 @@ describe("worker process", () => {
     try {
       const hash = "C9NMV6V2TQT81";
       await mkdir(join(root, "bundles"), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), WORKER_REGISTRY_YAML, "utf8");
       const bundlePath = join(root, "bundles", `${hash}.esm.js`);
       await writeFile(bundlePath, bundleSource, "utf8");
 
@@ -136,6 +148,7 @@ describe("worker process", () => {
     try {
       const hash = "C9NMV6V2TQT81";
       await mkdir(join(root, "bundles"), { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), WORKER_REGISTRY_YAML, "utf8");
       const bundlePath = join(root, "bundles", `${hash}.esm.js`);
       await writeFile(bundlePath, bundleSource, "utf8");
 

packages/workflow/__tests__/workflow-as-agent-integration.test.ts

@@ -4,19 +4,18 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import * as z from "zod/v4";
 
-import { createCasStore } from "../src/cas.js";
-import { createWorkflow } from "../src/create-workflow.js";
-import { executeThread } from "../src/engine.js";
-import { createExtract } from "../src/extract-fn.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
-import { createLogger } from "../src/logger.js";
-import { getContentMerklePayload, parseMerkleNode } from "../src/merkle.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { getContentMerklePayload, parseMerkleNode } from "../src/cas/merkle.js";
+import { createWorkflow } from "../src/engine/create-workflow.js";
+import { executeThread } from "../src/engine/engine.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 import { END } from "../src/types.js";
+import { createLogger } from "../src/util/logger.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 
 const callerMetaSchema = z.object({ done: z.literal(true) });
@@ -76,11 +75,16 @@ function installMockChatCompletions(sequence: ReadonlyArray<Record<string, unkno
   };
 }
 
-const parentExtract = createExtract({
-  baseUrl: "http://127.0.0.1:9",
-  apiKey: "test",
-  model: "test",
-});
+const PARENT_REGISTRY_WITH_CONFIG = `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`;
 
 const childBundleSource = `import { putContentMerkleNode } from "@uncaged/workflow";
 
@@ -131,6 +135,8 @@ describe("workflowAsAgent integration", () => {
 
     const root = await mkdtemp(join(tmpdir(), "wf-waa-int-"));
     try {
+      await mkdir(root, { recursive: true });
+      await writeFile(join(root, "workflow.yaml"), PARENT_REGISTRY_WITH_CONFIG, "utf8");
       const { hash: childHash } = await installChildWorkflow(root);
 
       const parentWorkflow = createWorkflow<ParentMeta>(
@@ -148,8 +154,6 @@ describe("workflowAsAgent integration", () => {
           moderator: (ctx) => (ctx.steps.length === 0 ? "caller" : END),
         },
         { agent: workflowAsAgent("child-wf", { storageRoot: root }) },
-        parentExtract,
-        null,
       );
 
       const threadId = "01KQXKW18CT8G75T53R8F4G7YG";
@@ -173,6 +177,7 @@ describe("workflowAsAgent integration", () => {
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: null,
           prefilledDiskSteps: null,
+          storageRoot: root,
         },
         { threadId, hash: parentHash, dataJsonlPath: dataPath, infoJsonlPath: infoPath, cas },
         logger,

packages/workflow/__tests__/workflow-as-agent.test.ts

@@ -3,14 +3,14 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { createCasStore } from "../src/cas.js";
-import { hashWorkflowBundleBytes } from "../src/hash.js";
-import { parseMerkleNode } from "../src/merkle.js";
+import { createCasStore } from "../src/cas/cas.js";
+import { hashWorkflowBundleBytes } from "../src/cas/hash.js";
+import { parseMerkleNode } from "../src/cas/merkle.js";
 import {
   readWorkflowRegistry,
   registerWorkflowVersion,
   writeWorkflowRegistry,
-} from "../src/registry.js";
+} from "../src/registry/registry.js";
 import { type AgentContext, START } from "../src/types.js";
 import { workflowAsAgent } from "../src/workflow-as-agent.js";
 
@@ -93,6 +93,21 @@ describe("workflowAsAgent", () => {
   test("runs registered workflow and returns child thread root CAS hash", async () => {
     const root = await mkdtemp(join(tmpdir(), "wf-waa-ok-"));
     try {
+      await mkdir(root, { recursive: true });
+      await writeFile(
+        join(root, "workflow.yaml"),
+        `config:
+  maxDepth: 3
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`,
+        "utf8",
+      );
       await installChildWorkflow(root);
       const agent = workflowAsAgent("child-wf", { storageRoot: root });
       const out = await agent(
@@ -140,10 +155,15 @@ describe("workflowAsAgent", () => {
         ...reg.value,
         config: {
           maxDepth: 2,
-          extract: {
-            baseUrl: "http://127.0.0.1:9",
-            model: "m",
-            apiKey: "k",
+          providers: {
+            local: {
+              baseUrl: "http://127.0.0.1:9",
+              apiKey: "k",
+            },
+          },
+          models: {
+            default: "local/m",
+            extract: "local/m",
           },
         },
       };

packages/workflow/__tests__/workflow-descriptor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { validateWorkflowDescriptor } from "../src/workflow-descriptor.js";
+import { validateWorkflowDescriptor } from "../src/bundle/workflow-descriptor.js";
 
 describe("validateWorkflowDescriptor", () => {
   // 1. Valid minimal descriptor

packages/workflow/package.json

@@ -5,7 +5,6 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "scripts": {
-    "build": "echo 'TODO'",
     "test": "bun test"
   },
   "dependencies": {

packages/workflow/src/bundle/build-descriptor.ts

@@ -1,7 +1,7 @@
 import * as z from "zod/v4";
 
-import type { RoleMeta, WorkflowDefinition } from "./types.js";
-import type { WorkflowDescriptor, WorkflowRoleSchema } from "./workflow-descriptor.js";
+import type { RoleMeta, WorkflowDefinition } from "../types.js";
+import type { WorkflowDescriptor, WorkflowRoleSchema } from "./types.js";
 
 function stripJsonSchemaMeta(json: Record<string, unknown>): WorkflowRoleSchema {
   const { $schema: _drop, ...rest } = json;

packages/workflow/src/bundle/bundle-validator.ts

@@ -10,6 +10,11 @@ import type {
   Program,
   VariableDeclaration,
 } from "acorn";
+import * as acorn from "acorn";
+
+import { err, ok, type Result } from "../util/index.js";
+
+import type { WorkflowBundleValidationInput } from "./types.js";
 
 /** Acorn Node with index-access for property traversal. */
 type AcornNode = Node & { [key: string]: unknown };
@@ -22,17 +27,6 @@ function narrowNode<T extends Node>(node: Node): T {
   return node as unknown as T;
 }
 
-import * as acorn from "acorn";
-
-import { err, ok, type Result } from "./result.js";
-
-export type WorkflowBundleValidationInput = {
-  /** Absolute or relative path (used for `.esm.js` suffix checks). */
-  filePath: string;
-  /** UTF-8 source of the bundle. */
-  source: string;
-};
-
 function endsWithEsmJs(path: string): boolean {
   return path.endsWith(".esm.js");
 }

packages/workflow/src/bundle/ensure-uncaged-workflow-symlink.ts

@@ -2,9 +2,9 @@ import { mkdir, readlink, symlink, unlink } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** This module lives in `@uncaged/workflow/src`; parent dir is the package root. */
+/** This module lives in `@uncaged/workflow/src/bundle`; grandparent dir is the package root. */
 function installedWorkflowPackageDir(): string {
-  return fileURLToPath(new URL("..", import.meta.url));
+  return fileURLToPath(new URL("../..", import.meta.url));
 }
 
 /**

packages/workflow/src/bundle/extract-bundle-exports.ts

@@ -1,20 +1,10 @@
+import type { WorkflowFn } from "../types.js";
+import { err, ok, type Result } from "../util/index.js";
 import { importWorkflowBundleModule } from "./bundle-import-env.js";
 import { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";
-import { err, ok, type Result } from "./result.js";
-import type { WorkflowFn } from "./types.js";
-import type { WorkflowDescriptor } from "./workflow-descriptor.js";
+import type { ExtractBundleExportsOptions, ExtractedBundleExports } from "./types.js";
 import { validateWorkflowDescriptor } from "./workflow-descriptor.js";
 
-export type ExtractedBundleExports = {
-  run: WorkflowFn;
-  descriptor: WorkflowDescriptor;
-};
-
-export type ExtractBundleExportsOptions = {
-  /** When set, ensures `node_modules/@uncaged/workflow` exists under this root before import. */
-  storageRoot: string | null;
-};
-
 /** Load a workflow `.esm.js` bundle and read its named exports (`run`, `descriptor`). */
 export async function extractBundleExports(
   bundlePath: string,

packages/workflow/src/bundle/generate-descriptor.ts

@@ -1,6 +1,6 @@
 import { stringify } from "yaml";
 
-import type { WorkflowDescriptor } from "./workflow-descriptor.js";
+import type { WorkflowDescriptor } from "./types.js";
 
 /** Serialize a validated workflow descriptor to YAML for storage next to the bundle. */
 export function stringifyWorkflowDescriptor(descriptor: WorkflowDescriptor): string {

packages/workflow/src/bundle/index.ts

@@ -0,0 +1,15 @@
+export { buildDescriptor } from "./build-descriptor.js";
+export { importWorkflowBundleModule } from "./bundle-import-env.js";
+export { validateWorkflowBundle } from "./bundle-validator.js";
+export { ensureUncagedWorkflowSymlink } from "./ensure-uncaged-workflow-symlink.js";
+export { extractBundleExports } from "./extract-bundle-exports.js";
+export { stringifyWorkflowDescriptor } from "./generate-descriptor.js";
+export type {
+  ExtractBundleExportsOptions,
+  ExtractedBundleExports,
+  WorkflowBundleValidationInput,
+  WorkflowDescriptor,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
+} from "./types.js";
+export { validateWorkflowDescriptor } from "./workflow-descriptor.js";

packages/workflow/src/bundle/types.ts

@@ -0,0 +1,32 @@
+import type { WorkflowFn } from "../types.js";
+
+/** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
+export type WorkflowRoleSchema = Record<string, unknown>;
+
+export type WorkflowRoleDescriptor = {
+  description: string;
+  schema: WorkflowRoleSchema;
+};
+
+/** Workflow metadata exported as `export const descriptor` from `.esm.js` bundles. */
+export type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+};
+
+export type WorkflowBundleValidationInput = {
+  /** Absolute or relative path (used for `.esm.js` suffix checks). */
+  filePath: string;
+  /** UTF-8 source of the bundle. */
+  source: string;
+};
+
+export type ExtractedBundleExports = {
+  run: WorkflowFn;
+  descriptor: WorkflowDescriptor;
+};
+
+export type ExtractBundleExportsOptions = {
+  /** When set, ensures `node_modules/@uncaged/workflow` exists under this root before import. */
+  storageRoot: string | null;
+};

packages/workflow/src/bundle/workflow-descriptor.ts

@@ -1,18 +1,6 @@
-import { err, ok, type Result } from "./result.js";
+import { err, ok, type Result } from "../util/index.js";
 
-/** JSON Schema fragment describing one role's `meta` shape (subset supported by code generation). */
-export type WorkflowRoleSchema = Record<string, unknown>;
-
-export type WorkflowRoleDescriptor = {
-  description: string;
-  schema: WorkflowRoleSchema;
-};
-
-/** Workflow metadata exported as `export const descriptor` from `.esm.js` bundles. */
-export type WorkflowDescriptor = {
-  description: string;
-  roles: Record<string, WorkflowRoleDescriptor>;
-};
+import type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
 
 export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescriptor, string> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {

packages/workflow/src/cas/cas.ts

@@ -2,13 +2,7 @@ import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/pro
 import { join } from "node:path";
 
 import { hashString } from "./hash.js";
-
-export type CasStore = {
-  put(content: string): Promise<string>;
-  get(hash: string): Promise<string | null>;
-  delete(hash: string): Promise<void>;
-  list(): Promise<string[]>;
-};
+import type { CasStore } from "./types.js";
 
 export function createCasStore(casDir: string): CasStore {
   async function ensureDir(): Promise<void> {

packages/workflow/src/cas/hash.ts

@@ -2,7 +2,7 @@ import { Buffer } from "node:buffer";
 
 import XXH from "xxhashjs";
 
-import { encodeUint64AsCrockford } from "./base32.js";
+import { encodeUint64AsCrockford } from "../util/index.js";
 
 function digestToUint64(digest: { toString(radix?: number): string }): bigint {
   const hex = digest.toString(16).padStart(16, "0");

packages/workflow/src/cas/index.ts

@@ -0,0 +1,18 @@
+export { createCasStore, createThreadCas } from "./cas.js";
+export { hashString, hashWorkflowBundleBytes } from "./hash.js";
+export {
+  createContentMerkleNode,
+  getContentMerklePayload,
+  parseMerkleNode,
+  putContentMerkleNode,
+  putStepMerkleNode,
+  putThreadMerkleNode,
+  serializeMerkleNode,
+} from "./merkle.js";
+export type {
+  CasStore,
+  MerkleNode,
+  MerkleNodeType,
+  StepMerklePayload,
+  ThreadMerklePayload,
+} from "./types.js";

packages/workflow/src/cas/merkle.ts

@@ -1,14 +1,6 @@
 import { parse, stringify } from "yaml";
 
-import type { CasStore } from "./cas.js";
-
-export type MerkleNodeType = "content" | "step" | "thread";
-
-export type MerkleNode = {
-  type: MerkleNodeType;
-  payload: string | Record<string, unknown>;
-  children: string[];
-};
+import type { CasStore, MerkleNode, StepMerklePayload, ThreadMerklePayload } from "./types.js";
 
 export function serializeMerkleNode(node: MerkleNode): string {
   return stringify(
@@ -53,20 +45,6 @@ export function createContentMerkleNode(payload: string): MerkleNode {
   return { type: "content", payload, children: [] };
 }
 
-export type StepMerklePayload = {
-  role: string;
-  meta: Record<string, unknown>;
-};
-
-export type ThreadMerklePayload = {
-  workflow: string;
-  threadId: string;
-  result: {
-    returnCode: number;
-    summary: string;
-  };
-};
-
 /** Serializes a step Merkle node (role + meta + content child) and stores it in CAS. */
 export async function putStepMerkleNode(
   store: CasStore,