refactor(cli): reduce cognitive complexity in thread.ts

Extract helper functions (resolveThreadId, getThreadHead, listThreadSteps, displayStepDetails, displayThreadRead) to reduce nesting and improve readability. Also adds test coverage for the refactored functions. Fixes #446
docs: add sync-readme rule for consistent README updates
2026-05-23 23:47:54 +08:00 · 2026-05-23 15:09:25 +00:00 · 2026-05-23 15:03:56 +00:00 · 2026-05-23 15:00:05 +00:00 · 2026-05-23 22:58:09 +08:00 · 2026-05-23 22:45:09 +08:00
25 changed files with 2485 additions and 219 deletions
@@ -0,0 +1,67 @@
+# Sync README
+
+When updating README.md files in this monorepo, follow these conventions.
+
+## Scope
+
+- Root `README.md` — project overview and navigation hub
+- Per-package `packages/*/README.md` — each package self-contained
+
+## Root README Structure
+
+The root README should have these sections in order:
+
+1. **Title and one-liner** — stateless workflow engine driven by single-step CLI
+2. **Overview** — 2-3 paragraphs explaining what it does and key concepts
+3. **Architecture** — dependency layer diagram (text-based)
+4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app)
+5. **Quick Start** — install, build, register workflow, start thread, run step
+6. **CLI Reference** — brief command list, detailed usage in cli-workflow README
+7. **Development** — bun install / build / check / test
+
+## Per-Package README Structure
+
+Each package README should have:
+
+1. **Title** — package name
+2. **One-line description** — matching package.json
+3. **Overview** — what it does, where it sits in the architecture, dependencies
+4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents)
+5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
+6. **CLI Usage** (cli/agent packages) — command reference with examples
+7. **Internal Structure** — brief src/ file organization
+8. **Configuration** (if applicable)
+
+## Execution Steps
+
+### Step 1: Gather current state
+For each package read:
+- package.json (name, version, description, dependencies, bin)
+- src/index.ts (public API exports)
+- Existing README.md (preserve hand-written content worth keeping)
+
+### Step 2: Update root README
+- Ensure ALL packages in packages/ directory are listed in the table
+- Update CLI command reference from uwf --help output
+- Keep Quick Start examples valid
+
+### Step 3: Write/update each package README
+- Follow the per-package structure
+- API section MUST match actual src/index.ts exports — never invent
+- For agent packages: document CLI binary name, how it is invoked
+- For lib packages: document exported types and functions
+- Internal structure: list actual files in src/
+
+### Step 4: Verify
+- All relative links work
+- Package names match package.json
+- No references to removed/renamed packages
+- bun run build still passes
+
+## Guidelines
+
+- Only document what src/index.ts actually exports
+- Root README summarizes, package READMEs go into detail
+- Verify CLI examples against actual commands
+- Preserve existing good prose when updating
+- English for all README content
@@ -41,7 +41,8 @@ roles:
      Before starting any work, ensure a clean worktree:
      1. `git checkout main && git pull` to get the latest code
      2. `git checkout -b fix/<issue-number>-<short-description>` to create a fresh branch
-         - If bounced back from reviewer or tester, reuse the existing branch instead
+         - If bounced back from reviewer or tester, reuse the existing branch and rebase onto latest main:
+           `git checkout main && git pull && git checkout <branch> && git rebase main`

      Then implement TDD:
      3. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
@@ -2,92 +2,102 @@

 A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, JSONata routing conditions, and a directed graph. Threads are immutable CAS-linked chains — each `uwf thread step` runs one moderator→agent→extract cycle and exits.

-## Package Map
+## Overview

-| Package | npm | Role |
-|---------|-----|------|
-| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI binary — thread lifecycle, workflow registry, CAS inspection, setup |
-| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `WorkflowConfig`, etc.) |
-| `workflow-moderator` | `@uncaged/workflow-moderator` | JSONata graph evaluator — determines next role or `$END` |
-| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, two-layer extract pipeline |
-| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` agent — spawns Hermes chat, captures session |
-| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing |
+This monorepo implements **uwf**, a workflow engine with no long-running daemon. You register YAML workflow definitions in a content-addressed store (CAS), start a thread with an initial prompt, then invoke `uwf thread step` repeatedly until the moderator routes to `$END`. Each step is a complete process: the moderator evaluates JSONata conditions to pick the next role, an external agent CLI produces frontmatter markdown output, and an extract pipeline validates or structures that output against the role's JSON Schema.

-External: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (CAS store + JSON Schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
+Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes for definitions and step payloads, `registry.yaml` for workflow name→hash mappings, and `threads.yaml` for active thread head pointers. Completed threads are archived to `history.jsonl`. Because there is no server process, workflows are easy to debug, fork, and inspect with ordinary CLI tools.
+
+Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `<thread-id>` and `<role>`, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay.
+
+## Architecture
+
+Dependency layers (lower layers have no dependency on higher layers):
+
+```
+Layer 0 — Contract
+  workflow-protocol          Shared types and JSON Schema definitions
+
+Layer 1 — Shared infra
+  workflow-util              Encoding, IDs, logging, frontmatter, paths
+  workflow-moderator         JSONata graph evaluator
+
+Layer 2 — Agent framework
+  workflow-agent-kit         createAgent factory, context builder, extract pipeline
+
+Layer 3 — Agent implementations
+  workflow-agent-hermes      Hermes ACP agent (uwf-hermes)
+  workflow-agent-builtin     Built-in LLM + tools agent (uwf-builtin)
+  workflow-agent-claude-code Claude Code agent (uwf-claude-code)
+
+Layer 4 — CLI
+  cli-workflow               uwf binary — thread lifecycle, registry, CAS, setup
+
+App (uses protocol; not in the runtime engine stack)
+  workflow-dashboard         Web UI for visual workflow editing
+```
+
+External CAS: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
+
+See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
+
+## Packages
+
+| Package | npm | Description | Type | README |
+|---------|-----|-------------|------|--------|
+| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI — thread lifecycle, workflow registry, CAS inspection, setup | cli | [README](packages/cli-workflow/README.md) |
+| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types and JSON Schema constants | lib | [README](packages/workflow-protocol/README.md) |
+| `workflow-moderator` | `@uncaged/workflow-moderator` | JSONata graph evaluator — next role or `$END` | lib | [README](packages/workflow-moderator/README.md) |
+| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-agent-kit/README.md) |
+| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | [README](packages/workflow-util/README.md) |
+| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` — spawns Hermes chat via ACP | agent | [README](packages/workflow-agent-hermes/README.md) |
+| `workflow-agent-builtin` | `@uncaged/workflow-agent-builtin` | `uwf-builtin` — built-in LLM agent with file/shell tools | agent | [README](packages/workflow-agent-builtin/README.md) |
+| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) |
+| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) |

 ## Quick Start

 ```bash
-# 1. Configure provider and model
+# 1. Configure provider, model, and default agent
 uwf setup

 # 2. Register a workflow from YAML
 uwf workflow put examples/solve-issue.yaml

-# 3. Start a thread
+# 3. Start a thread (creates head pointer; does not execute)
 uwf thread start solve-issue -p "Fix the login redirect bug"

 # 4. Execute steps (one at a time, until done)
 uwf thread step <thread-id>
 ```

-## CLI Commands
+Use `-c, --count <number>` on `thread step` to run multiple steps in one invocation. Override the agent with `--agent <cmd>`.

-### Thread
+## CLI Reference

-| Command | Description |
-|---------|-------------|
-| `uwf thread start <workflow> -p <prompt>` | Create a thread (no execution) |
-| `uwf thread step <thread-id> [--agent <cmd>]` | Execute one moderator→agent→extract cycle |
-| `uwf thread show <thread-id>` | Show head pointer and done status |
-| `uwf thread list [--all]` | List threads (`--all` includes archived) |
-| `uwf thread steps <thread-id>` | List all steps chronologically |
-| `uwf thread read <thread-id> [--quota N]` | Render thread as readable markdown |
-| `uwf thread fork <step-hash>` | Fork from a specific step |
-| `uwf thread step-details <step-hash>` | Dump full detail node |
-| `uwf thread kill <thread-id>` | Terminate and archive |
+Global options: `-V, --version`, `--format <json|yaml>`, `-h, --help`.

-### Workflow
+| Group | Commands |
+|-------|----------|
+| **thread** | `start`, `step`, `show`, `list`, `kill`, `steps`, `read`, `fork`, `step-details` |
+| **workflow** | `put`, `show`, `list` |
+| **cas** | `get`, `put`, `put-text`, `has`, `refs`, `walk`, `reindex`, `schema list`, `schema get` |
+| **setup** | Interactive or `--provider`, `--base-url`, `--api-key`, `--model`, `--agent` |
+| **skill** | `cli` — print markdown reference of all uwf commands |
+| **log** | `list`, `show`, `clean` — process-level debug logs |

-| Command | Description |
-|---------|-------------|
-| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
-| `uwf workflow show <name-or-hash>` | Show workflow definition |
-| `uwf workflow list` | List registered workflows |
+Config is stored in `~/.uncaged/workflow/config.yaml`. API keys go in `~/.uncaged/workflow/.env`.

-### CAS
-
-| Command | Description |
-|---------|-------------|
-| `uwf cas get <hash>` | Read a CAS node |
-| `uwf cas put <type-hash> <data>` | Store a node |
-| `uwf cas has <hash>` | Check existence |
-| `uwf cas refs <hash>` | List direct references |
-| `uwf cas walk <hash>` | Recursive traversal |
-| `uwf cas reindex` | Rebuild type index |
-| `uwf cas schema list` | List schemas |
-| `uwf cas schema get <hash>` | Show a schema |
-
-### Setup
-
-| Command | Description |
-|---------|-------------|
-| `uwf setup` | Interactive provider/model/agent configuration |
-| `uwf setup --provider ... --base-url ... --api-key ... --model ...` | Non-interactive setup |
-
-Config stored in `~/.uncaged/workflow/config.yaml`. API keys in `~/.uncaged/workflow/.env`.
+Detailed command usage, options, and examples: [packages/cli-workflow/README.md](packages/cli-workflow/README.md).

 ## Development

 ```bash
 bun install --no-cache     # Install dependencies
+bun run build              # tsc --build (all packages)
 bun run check              # tsc + biome + lint-log-tags
 bun run format             # Auto-format with Biome
 bun test                   # Run all tests
 ```

 Managed with **bun workspace**. See [CLAUDE.md](CLAUDE.md) for coding conventions.
-
-## Architecture
-
-See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
@@ -9,7 +9,7 @@
    "check": "bunx tsc --build && biome check . && bash scripts/lint-log-tags.sh",
    "typecheck": "bunx tsc --build",
    "format": "biome format --write .",
-    "test": "bun run --filter '*' test",
+    "test": "bun run --filter './packages/*' test",
    "changeset": "bunx changeset",
    "version": "bunx changeset version",
    "release": "bun run build && bun test && node scripts/publish-all.mjs"
@@ -0,0 +1,128 @@
+# @uncaged/cli-workflow
+
+`uwf` CLI — thread lifecycle, workflow registry, CAS inspection, and setup.
+
+## Overview
+
+Layer 4 entry point for the workflow engine. The `uwf` binary orchestrates one step per invocation: load thread head from `threads.yaml`, run the moderator, spawn the configured agent CLI, run extract, append a CAS step node, and update the head pointer (or archive when `$END`).
+
+This package has no library `src/index.ts` — it is consumed as a CLI binary only.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-moderator`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `yaml`
+
+## Installation
+
+Included as the `uwf` binary when you install `@uncaged/cli-workflow`:
+
+```bash
+bun add -g @uncaged/cli-workflow
+# or from the monorepo:
+bun link packages/cli-workflow
+```
+
+## CLI Usage
+
+### Global options
+
+```
+-V, --version          Show version
+--format <json|yaml>   Output format (default: json)
+-h, --help             Show help
+```
+
+### Thread
+
+| Command | Description |
+|---------|-------------|
+| `uwf thread start <workflow> -p <prompt>` | Create a thread without executing |
+| `uwf thread step <thread-id> [--agent <cmd>] [-c <count>]` | Execute one or more moderator→agent→extract cycles |
+| `uwf thread show <thread-id>` | Show thread head pointer |
+| `uwf thread list [--all]` | List active threads (`--all` includes archived) |
+| `uwf thread steps <thread-id>` | List all steps chronologically |
+| `uwf thread read <thread-id> [--quota N] [--before <hash>] [--start]` | Render thread as readable markdown |
+| `uwf thread fork <step-hash>` | Fork from a specific step |
+| `uwf thread step-details <step-hash>` | Dump full detail node as YAML |
+| `uwf thread kill <thread-id>` | Terminate and archive |
+
+Examples:
+
+```bash
+uwf thread start solve-issue -p "Fix the login redirect bug"
+uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
+uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
+uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
+```
+
+### Workflow
+
+| Command | Description |
+|---------|-------------|
+| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
+| `uwf workflow show <name-or-hash>` | Show workflow definition |
+| `uwf workflow list` | List registered workflows |
+
+### CAS
+
+| Command | Description |
+|---------|-------------|
+| `uwf cas get <hash> [--timestamp]` | Read a CAS node |
+| `uwf cas put <type-hash> <data>` | Store a node, print hash |
+| `uwf cas put-text <text>` | Store plain text, print hash |
+| `uwf cas has <hash>` | Check existence |
+| `uwf cas refs <hash>` | List direct references |
+| `uwf cas walk <hash>` | Recursive traversal |
+| `uwf cas reindex` | Rebuild type index |
+| `uwf cas schema list` | List registered schemas |
+| `uwf cas schema get <hash>` | Show a schema |
+
+### Setup
+
+```bash
+uwf setup
+uwf setup --provider openai --base-url https://api.openai.com/v1 \
+  --api-key sk-... --model gpt-4o --agent hermes
+```
+
+Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
+
+### Skill
+
+| Command | Description |
+|---------|-------------|
+| `uwf skill cli` | Print markdown reference of all uwf commands (for agent skills) |
+
+### Log
+
+| Command | Description |
+|---------|-------------|
+| `uwf log list` | List log files with sizes |
+| `uwf log show [--thread <id>] [--process <pid>] [--date YYYY-MM-DD]` | Show filtered log entries |
+| `uwf log clean [--before YYYY-MM-DD]` | Delete old log files |
+
+## Internal Structure
+
+```
+src/
+├── cli.ts              Commander entrypoint, command registration
+├── format.ts           JSON/YAML output formatting
+├── store.ts            CAS store + registry initialization
+├── validate.ts         Workflow YAML validation
+├── schemas.ts          CLI-local schema registration
+└── commands/
+    ├── thread.ts       Thread lifecycle and step execution
+    ├── workflow.ts     Workflow registry (put/show/list)
+    ├── cas.ts          CAS inspection and schema ops
+    ├── setup.ts        Interactive/non-interactive setup
+    ├── skill.ts        Built-in skill references
+    └── log.ts          Process debug log management
+```
+
+## Configuration
+
+| File | Purpose |
+|------|---------|
+| `~/.uncaged/workflow/config.yaml` | Providers, models, default agent |
+| `~/.uncaged/workflow/.env` | API keys (referenced by `apiKeyEnv` in config) |
+| `~/.uncaged/workflow/registry.yaml` | Workflow name → CAS hash |
+| `~/.uncaged/workflow/threads.yaml` | Active thread head pointers |
+| `~/.uncaged/workflow/cas/` | Content-addressed node storage |
@@ -266,12 +266,7 @@ describe("cmdThreadRead ### Content section", () => {

    expect(markdown).toContain("### Content");
    expect(markdown).toContain("The assistant response text");
-
-    const contentIdx = markdown.indexOf("### Content");
-    const outputIdx = markdown.indexOf("### Output");
-    expect(contentIdx).toBeGreaterThanOrEqual(0);
-    expect(outputIdx).toBeGreaterThanOrEqual(0);
-    expect(contentIdx).toBeLessThan(outputIdx);
+    expect(markdown).not.toContain("### Output");
  });

  test("omits ### Content when detail has no matching assistant turns", async () => {
@@ -314,7 +309,7 @@ describe("cmdThreadRead ### Content section", () => {
    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);

    expect(markdown).not.toContain("### Content");
-    expect(markdown).toContain("### Output");
+    expect(markdown).not.toContain("### Output");
  });
 });

@@ -387,8 +382,266 @@ describe("cmdThreadStepDetails", () => {
      content: "done",
    });
  });
+});

+// ── cmdThreadRead: ### Prompt deduplication ───────────────────────────────────
+
+describe("cmdThreadRead ### Prompt deduplication", () => {
+  async function makeThreadWithRoles(uwf: UwfStore, roles: string[]): Promise<string> {
+    const roleMap: Record<string, unknown> = {};
+    for (const r of [...new Set(roles)]) {
+      roleMap[r] = {
+        description: r,
+        goal: `Goal for ${r}`,
+        capabilities: [],
+        procedure: "Do stuff.",
+        output: "Output.",
+        meta: "placeholder00" as CasRef,
+      };
+    }
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "dedup-wf",
+      description: "desc",
+      roles: roleMap,
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Start",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    let prev: string | null = null;
+    let stepHash = "";
+    for (const role of roles) {
+      stepHash = await uwf.store.put(uwf.schemas.stepNode, {
+        start: startHash,
+        prev: prev as CasRef | null,
+        role,
+        output: outputHash,
+        detail: null,
+        agent: "uwf-test",
+      });
+      prev = stepHash;
+    }
+    return stepHash;
+  }
+
+  test("same consecutive role shows ### Prompt once", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["writer", "writer"]);
+    const threadId = "01JTEST0000000000000003" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(1);
+  });
+
+  test("different consecutive roles each show ### Prompt", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["planner", "coder"]);
+    const threadId = "01JTEST0000000000000004" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(2);
+  });
+
+  test("non-consecutive same role shows ### Prompt twice", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const headHash = await makeThreadWithRoles(uwf, ["roleA", "roleB", "roleA"]);
+    const threadId = "01JTEST0000000000000005" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
+    expect(count).toBe(2);
+  });
+});
+
+// ── cmdThreadRead: showStart / before / quota ─────────────────────────────────
+
+describe("cmdThreadRead start section / before / quota", () => {
+  async function makeSimpleThread(
+    uwf: UwfStore,
+    roles: string[],
+  ): Promise<{ startHash: CasRef; stepHashes: CasRef[] }> {
+    const uniqueRoles = [...new Set(roles)];
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "simple-wf",
+      description: "desc",
+      roles: Object.fromEntries(
+        uniqueRoles.map((r) => [
+          r,
+          {
+            description: r,
+            goal: `Goal for ${r}`,
+            capabilities: [],
+            procedure: "Do stuff.",
+            output: "Output.",
+            meta: "placeholder00" as CasRef,
+          },
+        ]),
+      ),
+      conditions: {},
+      graph: {},
+    });
+    const startHash = (await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Initial prompt",
+    })) as CasRef;
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const stepHashes: CasRef[] = [];
+    let prev: CasRef | null = null;
+    for (const role of roles) {
+      const stepHash = (await uwf.store.put(uwf.schemas.stepNode, {
+        start: startHash,
+        prev,
+        role,
+        output: outputHash,
+        detail: null,
+        agent: "uwf-test",
+      })) as CasRef;
+      stepHashes.push(stepHash);
+      prev = stepHash;
+    }
+    return { startHash, stepHashes };
+  }
+
+  test("showStart=true includes # Thread header and ## Task section", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
+    const threadId = "01JTEST0000000000000006" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, true);
+    expect(markdown).toContain("# Thread");
+    expect(markdown).toContain("## Task");
+    expect(markdown).toContain("Initial prompt");
+  });
+
+  test("showStart=false with before=null still shows # Thread header (default behavior)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
+    const threadId = "01JTEST0000000000000007" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
+
+    // When before=null, the start section is always shown regardless of showStart
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    expect(markdown).toContain("# Thread");
+    expect(markdown).toContain("## Task");
+  });
+
+  test("before filter: only steps before the given hash appear", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const { stepHashes } = await makeSimpleThread(uwf, ["roleA", "roleB", "roleC"]);
+    const [_hashA, hashB, hashC] = stepHashes as [CasRef, CasRef, CasRef];
+    const threadId = "01JTEST0000000000000008" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: hashC });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, hashB, false);
+    expect(markdown).toContain("roleA");
+    expect(markdown).not.toContain("roleB");
+    expect(markdown).not.toContain("roleC");
+  });
+
+  test("quota=1 limits output and includes skip hint", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const { stepHashes } = await makeSimpleThread(uwf, ["roleA", "roleB", "roleC"]);
+    const threadId = "01JTEST000000000000000A" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, 1, null, false);
+    expect(markdown).toContain("earlier step");
+  });
+
+  test("all steps fit in quota: no skip hint", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
+    const threadId = "01JTEST000000000000000B" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[0]! });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+    expect(markdown).not.toContain("earlier step");
+  });
+});
+
+// ── Tests that call process.exit must be last ─────────────────────────────────
+
+describe("cmdThreadStepDetails (process.exit tests - must be last)", () => {
  test("throws when step hash does not exist", async () => {
    await expect(cmdThreadStepDetails(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
  });
+
+  test("before with unknown hash rejects", async () => {
+    const _uwf = await makeUwfStore(tmpDir);
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = createFsStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+    const uwfStore: UwfStore = { storageRoot: tmpDir, store, schemas };
+
+    const workflowHash = await uwfStore.store.put(uwfStore.schemas.workflow, {
+      name: "wf2",
+      description: "",
+      roles: {
+        roleA: {
+          description: "r",
+          goal: "g",
+          capabilities: [],
+          procedure: "p",
+          output: "o",
+          meta: "placeholder00" as CasRef,
+        },
+      },
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwfStore.store.put(uwfStore.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "p",
+    });
+    const outputHash = await uwfStore.store.put(uwfStore.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const stepHash = await uwfStore.store.put(uwfStore.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "roleA",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    await saveThreadsIndex(tmpDir, { ["01JTEST000000000000000C" as ThreadId]: stepHash as CasRef });
+
+    await expect(
+      cmdThreadRead(
+        tmpDir,
+        "01JTEST000000000000000C" as ThreadId,
+        THREAD_READ_DEFAULT_QUOTA,
+        "unknownhash0" as CasRef,
+        false,
+      ),
+    ).rejects.toThrow();
+  });
 });
@@ -0,0 +1,367 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, WorkflowPayload } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { stringify } from "yaml";
+import { cmdThreadStart } from "../commands/thread.js";
+import { registerUwfSchemas } from "../schemas.js";
+import type { UwfStore } from "../store.js";
+import { loadWorkflowRegistry, saveWorkflowRegistry } from "../store.js";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
+  const casDir = join(storageRoot, "cas");
+  await mkdir(casDir, { recursive: true });
+  const store = createFsStore(casDir);
+  const schemas = await registerUwfSchemas(store);
+  return { storageRoot, store, schemas };
+}
+
+async function storeWorkflow(uwf: UwfStore, name: string): Promise<CasRef> {
+  const payload: WorkflowPayload = {
+    name,
+    description: "Test workflow",
+    roles: {},
+    conditions: {},
+    graph: {},
+  };
+  return await uwf.store.put(uwf.schemas.workflow, payload);
+}
+
+async function createWorkflowYaml(name: string, version: string | null = null): Promise<string> {
+  const payload: WorkflowPayload = {
+    name,
+    description: version !== null ? `Test workflow (${version})` : "Test workflow",
+    roles: {},
+    conditions: {},
+    graph: {},
+  };
+  const yaml = stringify(payload);
+  return yaml;
+}
+
+// ── fixture ───────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+let storageRoot: string;
+let projectRoot: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-wf-resolve-test-"));
+  storageRoot = join(tmpDir, "storage");
+  projectRoot = join(tmpDir, "project");
+  await mkdir(storageRoot, { recursive: true });
+  await mkdir(projectRoot, { recursive: true });
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── Strategy 1: CAS Hash Resolution ───────────────────────────────────────────
+
+describe("Strategy 1: CAS Hash Resolution", () => {
+  test("should resolve valid 13-char Crockford Base32 hash", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+    const hash = await storeWorkflow(uwf, "test-workflow");
+
+    const result = await cmdThreadStart(storageRoot, hash, "test prompt", projectRoot);
+
+    expect(result.workflow).toBe(hash);
+    expect(result.thread).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+  });
+
+  test("should fail on invalid hash format (non-Crockford characters)", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(
+      cmdThreadStart(storageRoot, "123456789ABCD", "prompt", projectRoot),
+    ).rejects.toThrow();
+  });
+
+  test("should fail on valid-format hash not present in CAS", async () => {
+    await makeUwfStore(storageRoot);
+    const fakeHash = "0000000000000"; // valid format, doesn't exist
+
+    await expect(cmdThreadStart(storageRoot, fakeHash, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should reject 40-char hex hash (legacy format not supported)", async () => {
+    await makeUwfStore(storageRoot);
+    const hexHash = "a".repeat(40);
+
+    await expect(cmdThreadStart(storageRoot, hexHash, "prompt", projectRoot)).rejects.toThrow();
+  });
+});
+
+// ── Strategy 2: File Path Resolution ──────────────────────────────────────────
+
+describe("Strategy 2: File Path Resolution", () => {
+  test("should load workflow from absolute file path", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "test-workflow.yaml");
+    await writeFile(yamlPath, await createWorkflowYaml("test-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).name).toBe("test-workflow");
+    }
+  });
+
+  test("should load workflow from relative file path", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = "test-workflow.yaml";
+    await writeFile(join(projectRoot, yamlPath), await createWorkflowYaml("test-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should fail when file path does not exist", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(
+      cmdThreadStart(storageRoot, "./nonexistent.yaml", "prompt", projectRoot),
+    ).rejects.toThrow();
+  });
+
+  test("should fail on invalid YAML syntax in file", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "bad-syntax.yaml");
+    await writeFile(yamlPath, "invalid: yaml: : :");
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should fail on valid YAML with invalid WorkflowPayload shape", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "invalid-workflow.yaml");
+    await writeFile(yamlPath, "name: test\n# missing roles, conditions, and graph");
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should enforce filename matches workflow name", async () => {
+    await makeUwfStore(storageRoot);
+    const yamlPath = join(tmpDir, "solve-issue.yaml");
+    await writeFile(yamlPath, await createWorkflowYaml("wrong-name"));
+
+    await expect(cmdThreadStart(storageRoot, yamlPath, "prompt", projectRoot)).rejects.toThrow();
+  });
+});
+
+// ── Strategy 3: Local Discovery (Parent Traversal) ────────────────────────────
+
+describe("Strategy 3: Local Discovery", () => {
+  test("should find workflow in current directory .workflow/", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yaml"), await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).name).toBe("solve-issue");
+    }
+  });
+
+  test("should find workflow in parent directory .workflow/", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yaml"), await createWorkflowYaml("solve-issue"));
+
+    const subdir = join(projectRoot, "packages", "cli-workflow", "src");
+    await mkdir(subdir, { recursive: true });
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", subdir);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should stop at filesystem root when traversing", async () => {
+    await makeUwfStore(storageRoot);
+    const deepPath = join(tmpDir, "deep", "path", "that", "does", "not", "have", "workflow");
+    await mkdir(deepPath, { recursive: true });
+
+    await expect(cmdThreadStart(storageRoot, "nonexistent", "prompt", deepPath)).rejects.toThrow();
+  });
+
+  test("should prefer .workflow/ over .workflows/ directory", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    const workflowsDir = join(projectRoot, ".workflows");
+    await mkdir(workflowDir, { recursive: true });
+    await mkdir(workflowsDir, { recursive: true });
+
+    await writeFile(
+      join(workflowDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "1"),
+    );
+    await writeFile(
+      join(workflowsDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "2"),
+    );
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (1)");
+    }
+  });
+
+  test("should support .yml extension in local discovery", async () => {
+    await makeUwfStore(storageRoot);
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(join(workflowDir, "solve-issue.yml"), await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+});
+
+// ── Strategy 4: Global Registry Fallback ──────────────────────────────────────
+
+describe("Strategy 4: Global Registry Resolution", () => {
+  test("should resolve workflow from global registry when not found locally", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+    const hash = await storeWorkflow(uwf, "deploy-pipeline");
+    const registry = await loadWorkflowRegistry(storageRoot);
+    registry["deploy-pipeline"] = hash;
+    await saveWorkflowRegistry(storageRoot, registry);
+
+    const isolatedRoot = join(tmpDir, "isolated");
+    await mkdir(isolatedRoot, { recursive: true });
+
+    const result = await cmdThreadStart(storageRoot, "deploy-pipeline", "prompt", isolatedRoot);
+
+    expect(result.workflow).toBe(hash);
+  });
+
+  test("should fail when workflow not found in any strategy", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "nonexistent", "prompt", tmpDir)).rejects.toThrow();
+  });
+});
+
+// ── Strategy Priority Order ───────────────────────────────────────────────────
+
+describe("Resolution Priority", () => {
+  test("should use explicit file path over local discovery", async () => {
+    await makeUwfStore(storageRoot);
+
+    // Setup: Create workflow in .workflow/ AND as explicit file
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    await writeFile(
+      join(workflowDir, "solve-issue.yaml"),
+      await createWorkflowYaml("solve-issue", "discovery"),
+    );
+
+    const explicitPath = join(projectRoot, "custom-solve-issue.yaml");
+    await writeFile(explicitPath, await createWorkflowYaml("custom-solve-issue", "explicit"));
+
+    // Execute with explicit path
+    const result = await cmdThreadStart(storageRoot, explicitPath, "prompt", projectRoot);
+
+    const uwf = await makeUwfStore(storageRoot);
+    const node = uwf.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (explicit)");
+    }
+  });
+
+  test("should use local discovery over global registry", async () => {
+    const uwf = await makeUwfStore(storageRoot);
+
+    // Setup: Register globally
+    const globalHash = await storeWorkflow(uwf, "solve-issue");
+    const registry = await loadWorkflowRegistry(storageRoot);
+    registry["solve-issue"] = globalHash;
+    await saveWorkflowRegistry(storageRoot, registry);
+
+    // Setup: Create local .workflow/
+    const workflowDir = join(projectRoot, ".workflow");
+    await mkdir(workflowDir, { recursive: true });
+    const localYaml = await createWorkflowYaml("solve-issue", "local");
+    await writeFile(join(workflowDir, "solve-issue.yaml"), localYaml);
+
+    const result = await cmdThreadStart(storageRoot, "solve-issue", "prompt", projectRoot);
+
+    const uwf2 = await makeUwfStore(storageRoot);
+    const node = uwf2.store.get(result.workflow);
+    expect(node).not.toBeNull();
+    if (node !== null) {
+      expect((node.payload as WorkflowPayload).description).toBe("Test workflow (local)");
+    }
+  });
+});
+
+// ── Edge Cases ────────────────────────────────────────────────────────────────
+
+describe("Edge Cases", () => {
+  test("should treat '13-char-string.yaml' as file path, not CAS hash", async () => {
+    await makeUwfStore(storageRoot);
+    const fileName = "0123456789ABC.yaml"; // 13 chars + .yaml
+    await writeFile(join(projectRoot, fileName), await createWorkflowYaml("0123456789ABC"));
+
+    const result = await cmdThreadStart(storageRoot, fileName, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should handle workflow names containing slashes as file paths", async () => {
+    await makeUwfStore(storageRoot);
+    const filePath = "subdir/solve-issue.yaml";
+    const fullPath = join(projectRoot, filePath);
+    await mkdir(join(projectRoot, "subdir"), { recursive: true });
+    await writeFile(fullPath, await createWorkflowYaml("solve-issue"));
+
+    const result = await cmdThreadStart(storageRoot, filePath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should handle absolute paths correctly", async () => {
+    await makeUwfStore(storageRoot);
+    const absPath = join(tmpDir, "abs-workflow.yaml");
+    await writeFile(absPath, await createWorkflowYaml("abs-workflow"));
+
+    const result = await cmdThreadStart(storageRoot, absPath, "prompt", projectRoot);
+
+    expect(result.workflow).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("should fail on empty workflow ID", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "", "prompt", projectRoot)).rejects.toThrow();
+  });
+
+  test("should fail on whitespace-only workflow ID", async () => {
+    await makeUwfStore(storageRoot);
+
+    await expect(cmdThreadStart(storageRoot, "   ", "prompt", projectRoot)).rejects.toThrow();
+  });
+});
@@ -137,6 +137,75 @@ function apiKeyEnvName(providerName: string): string {
  return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
 }

+/**
+ * Discover uwf-* agent binaries in PATH.
+ * Returns sorted list of binary names (e.g., ["uwf-hermes", "uwf-claude-code"]).
+ */
+async function _discoverAgents(): Promise<string[]> {
+  try {
+    // Use which -a to find all uwf-* binaries in PATH
+    const proc = Bun.spawn(["which", "-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+
+    if (proc.exitCode !== 0) {
+      // Try alternative approach: search PATH directories manually
+      const pathEnv = process.env.PATH || "";
+      const pathDirs = pathEnv.split(":").filter((d) => d.length > 0);
+      const agents = new Set<string>();
+
+      for (const dir of pathDirs) {
+        try {
+          if (!existsSync(dir)) continue;
+          const { readdirSync, statSync } = await import("node:fs");
+          const entries = readdirSync(dir);
+
+          for (const entry of entries) {
+            if (!entry.startsWith("uwf-") || entry === "uwf") continue;
+            const fullPath = join(dir, entry);
+            try {
+              const stat = statSync(fullPath);
+              // Check if executable (owner, group, or other has execute bit)
+              if (stat.isFile() && (stat.mode & 0o111) !== 0) {
+                agents.add(entry);
+              }
+            } catch {
+              // Skip if can't stat
+            }
+          }
+        } catch {
+          // Skip inaccessible directories
+        }
+      }
+
+      return Array.from(agents).sort();
+    }
+
+    // Parse which output - each line is a path to a binary
+    const paths = text
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0);
+    const agents = new Set<string>();
+
+    for (const path of paths) {
+      const basename = path.split("/").pop();
+      if (basename?.startsWith("uwf-") && basename !== "uwf") {
+        agents.add(basename);
+      }
+    }
+
+    return Array.from(agents).sort();
+  } catch {
+    // If all fails, return empty array
+    return [];
+  }
+}
+
 /**
 * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
 */
@@ -1,5 +1,6 @@
 import { execFileSync } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { access, readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
 import { getSchema, validate } from "@uncaged/json-cas";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
@@ -30,12 +31,10 @@ import { parse, stringify } from "yaml";
 import {
  appendThreadHistory,
  createUwfStore,
-  discoverProjectWorkflows,
  findThreadInHistory,
  loadThreadHistory,
  loadThreadsIndex,
  loadWorkflowRegistry,
-  resolveProjectWorkflowFile,
  resolveWorkflowHash,
  saveThreadsIndex,
  type ThreadHistoryLine,
@@ -82,6 +81,83 @@ function fail(message: string): never {
  process.exit(1);
 }

+/**
+ * Check if a string looks like a file path (contains path separators or has .yaml/.yml extension).
+ */
+function isFilePath(input: string): boolean {
+  return (
+    input.includes("/") || input.includes("\\") || input.endsWith(".yaml") || input.endsWith(".yml")
+  );
+}
+
+/**
+ * Check if a workflow file exists at the given path.
+ */
+async function workflowFileExists(dir: string, name: string, ext: string): Promise<string | null> {
+  const candidate = resolvePath(dir, `${name}${ext}`);
+  try {
+    await access(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Search for a workflow file in a given directory (checks both .workflow/ and .workflows/).
+ */
+async function findWorkflowInDir(dir: string, name: string): Promise<string | null> {
+  // Check .workflow/ directory first (preferred)
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(resolvePath(dir, ".workflow"), name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  // Check .workflows/ directory as fallback (legacy)
+  for (const ext of [".yaml", ".yml"]) {
+    const result = await workflowFileExists(resolvePath(dir, ".workflows"), name, ext);
+    if (result !== null) {
+      return result;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Traverse parent directories looking for `.workflow/<name>.yaml` or `.workflow/<name>.yml`.
+ * Returns the absolute path if found, otherwise null.
+ * Stops at filesystem root or .git directory.
+ */
+async function findWorkflowInParents(startDir: string, name: string): Promise<string | null> {
+  let currentDir = resolvePath(startDir);
+  const root = resolvePath("/");
+
+  while (true) {
+    const found = await findWorkflowInDir(currentDir, name);
+    if (found !== null) {
+      return found;
+    }
+
+    // Stop at filesystem root
+    if (currentDir === root) {
+      break;
+    }
+
+    // Move to parent directory
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      // Reached filesystem root
+      break;
+    }
+    currentDir = parentDir;
+  }
+
+  return null;
+}
+
 async function materializeLocalWorkflow(uwf: UwfStore, filePath: string): Promise<CasRef> {
  let text: string;
  try {
@@ -123,18 +199,41 @@ async function resolveWorkflowCasRef(
  workflowId: string,
  projectRoot: string,
 ): Promise<CasRef> {
-  // Project-local resolution: check .workflows/<workflowId>.yaml first
-  const localEntries = await discoverProjectWorkflows(projectRoot);
-  const localFile = resolveProjectWorkflowFile(localEntries, workflowId);
-  if (localFile !== null) {
-    return materializeLocalWorkflow(uwf, localFile);
+  // Validate input
+  const trimmed = workflowId.trim();
+  if (trimmed === "") {
+    fail("workflow ID cannot be empty");
  }

-  // Global registry fallback
+  // Strategy 1: Direct CAS hash
+  if (isCasRef(trimmed)) {
+    const node = uwf.store.get(trimmed);
+    if (node === null) {
+      fail(`CAS node not found: ${trimmed}`);
+    }
+    if (node.type !== uwf.schemas.workflow) {
+      fail(`node ${trimmed} is not a Workflow (type ${node.type})`);
+    }
+    return trimmed;
+  }
+
+  // Strategy 2: Explicit file path (relative or absolute)
+  if (isFilePath(trimmed)) {
+    const absolutePath = isAbsolute(trimmed) ? trimmed : resolvePath(projectRoot, trimmed);
+    return materializeLocalWorkflow(uwf, absolutePath);
+  }
+
+  // Strategy 3: Local discovery (parent directory traversal)
+  const localPath = await findWorkflowInParents(projectRoot, trimmed);
+  if (localPath !== null) {
+    return materializeLocalWorkflow(uwf, localPath);
+  }
+
+  // Strategy 4: Global registry fallback
  const registry = await loadWorkflowRegistry(storageRoot);
-  const hash = resolveWorkflowHash(registry, workflowId);
+  const hash = resolveWorkflowHash(registry, trimmed);
  if (!isCasRef(hash)) {
-    fail(`workflow not found: ${workflowId}`);
+    fail(`workflow not found: ${trimmed}`);
  }
  const node = uwf.store.get(hash);
  if (node === null) {
@@ -363,49 +462,68 @@ function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unkno
  return expandValue(store, schema, node.payload, seen);
 }

+function expandCasRefField(store: CasStore, value: unknown, visited: Set<string>): unknown {
+  if (typeof value === "string") {
+    return expandDeep(store, value as CasRef, visited);
+  }
+  return value;
+}
+
+function expandAnyOfField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (!Array.isArray(schema.anyOf)) return value;
+  for (const sub of schema.anyOf as JSONSchema[]) {
+    if (sub.format === "cas_ref" && typeof value === "string") {
+      return expandDeep(store, value as CasRef, visited);
+    }
+  }
+  return value;
+}
+
+function expandArrayField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (!schema.items || !Array.isArray(value)) return value;
+  const itemSchema = schema.items as JSONSchema;
+  return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
+}
+
+function expandObjectField(
+  store: CasStore,
+  schema: JSONSchema,
+  value: unknown,
+  visited: Set<string>,
+): unknown {
+  if (value === null || typeof value !== "object" || Array.isArray(value) || !schema.properties) {
+    return value;
+  }
+  const props = schema.properties as Record<string, JSONSchema>;
+  const obj = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(obj)) {
+    const propSchema = props[key];
+    result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
+  }
+  return result;
+}
+
 function expandValue(
  store: CasStore,
  schema: JSONSchema,
  value: unknown,
  visited: Set<string>,
 ): unknown {
-  // If this field is a cas_ref, expand it
-  if (schema.format === "cas_ref") {
-    if (typeof value === "string") {
-      return expandDeep(store, value as CasRef, visited);
-    }
-    return value;
-  }
-
-  // anyOf (nullable refs)
-  if (Array.isArray(schema.anyOf)) {
-    for (const sub of schema.anyOf as JSONSchema[]) {
-      if (sub.format === "cas_ref" && typeof value === "string") {
-        return expandDeep(store, value as CasRef, visited);
-      }
-    }
-    return value;
-  }
-
-  // Array of cas_ref items
-  if (schema.type === "array" && schema.items && Array.isArray(value)) {
-    const itemSchema = schema.items as JSONSchema;
-    return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
-  }
-
-  // Object with properties
-  if (value !== null && typeof value === "object" && !Array.isArray(value) && schema.properties) {
-    const props = schema.properties as Record<string, JSONSchema>;
-    const obj = value as Record<string, unknown>;
-    const result: Record<string, unknown> = {};
-    for (const [key, val] of Object.entries(obj)) {
-      const propSchema = props[key];
-      result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
-    }
-    return result;
-  }
-
-  return value;
+  if (schema.format === "cas_ref") return expandCasRefField(store, value, visited);
+  if (Array.isArray(schema.anyOf)) return expandAnyOfField(store, schema, value, visited);
+  if (schema.type === "array") return expandArrayField(store, schema, value, visited);
+  return expandObjectField(store, schema, value, visited);
 }

 function collectOrderedSteps(
@@ -440,7 +558,7 @@ function collectOrderedSteps(
 }

 function formatYaml(value: unknown): string {
-  return stringify(value).trimEnd();
+  return stringify(value, { aliasDuplicateObjects: false }).trimEnd();
 }

 function formatCompactStep(index: number, item: OrderedStepItem, outputYaml: string): string {
@@ -489,6 +607,85 @@ export function extractLastAssistantContent(uwf: UwfStore, detailRef: CasRef): s
  return null;
 }

+function sliceBeforeHash(
+  candidates: OrderedStepItem[],
+  before: CasRef,
+  threadId: ThreadId,
+): OrderedStepItem[] {
+  const idx = candidates.findIndex((s) => s.hash === before);
+  if (idx === -1) {
+    fail(`step ${before} not found in thread ${threadId}`);
+  }
+  return candidates.slice(0, idx);
+}
+
+function selectByQuota(
+  candidates: OrderedStepItem[],
+  uwf: UwfStore,
+  quota: number,
+): { selected: OrderedStepItem[]; skippedCount: number } {
+  const selected: OrderedStepItem[] = [];
+  let totalChars = 0;
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const item = candidates[i];
+    if (item === undefined) continue;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
+    selected.unshift(item);
+    totalChars += blockLen;
+    if (totalChars > quota) break;
+  }
+  return { selected, skippedCount: candidates.length - selected.length };
+}
+
+function formatStepHeader(stepNum: number, item: OrderedStepItem): string {
+  const ts = new Date(item.timestamp)
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d+Z$/, "");
+  return [
+    `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
+    `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
+  ].join("\n");
+}
+
+function formatStepPrompt(
+  roleDef: WorkflowPayload["roles"][string] | undefined,
+  role: string,
+  shownPromptRoles: Set<string>,
+): string {
+  if (!roleDef || shownPromptRoles.has(role)) return "";
+  shownPromptRoles.add(role);
+  return ["", "", "### Prompt", "", roleDef.goal].join("\n");
+}
+
+function formatStepContent(uwf: UwfStore, item: OrderedStepItem): string {
+  if (!item.payload.detail) return "";
+  const content = extractLastAssistantContent(uwf, item.payload.detail);
+  if (content === null) return "";
+  return ["", "", "### Content", "", content].join("\n");
+}
+
+function formatStartSection(options: {
+  threadId: ThreadId;
+  workflowName: string;
+  workflowHash: CasRef;
+  prompt: string;
+  before: CasRef | null;
+  showStart: boolean;
+}): string {
+  if (options.before !== null && !options.showStart) return "";
+  return [
+    `# Thread \`${options.threadId}\``,
+    "",
+    `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
+    "",
+    "## Task",
+    "",
+    options.prompt,
+  ].join("\n");
+}
+
 function formatThreadReadMarkdown(options: {
  threadId: ThreadId;
  workflowName: string;
@@ -501,50 +698,16 @@ function formatThreadReadMarkdown(options: {
  before: CasRef | null;
  showStart: boolean;
 }): string {
-  const { ordered, uwf, workflow, quota, before, showStart } = options;
+  const { ordered, uwf, workflow, quota, before } = options;

-  // Determine which steps to consider
-  let candidates = ordered;
-  if (before !== null) {
-    const idx = candidates.findIndex((s) => s.hash === before);
-    if (idx === -1) {
-      fail(`step ${before} not found in thread ${options.threadId}`);
-    }
-    candidates = candidates.slice(0, idx);
-  }
+  const candidates = before !== null ? sliceBeforeHash(ordered, before, options.threadId) : ordered;
+  const { selected, skippedCount } = selectByQuota(candidates, uwf, quota);

-  // Walk backward from newest, accumulating chars until quota exceeded
-  const selected: OrderedStepItem[] = [];
-  let totalChars = 0;
-  for (let i = candidates.length - 1; i >= 0; i--) {
-    const item = candidates[i];
-    if (item === undefined) continue;
-    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
-    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
-    selected.unshift(item);
-    totalChars += blockLen;
-    if (totalChars > quota) break;
-  }
-
-  const skippedCount = candidates.length - selected.length;
  const parts: string[] = [];

-  // Start section
-  if (before === null || showStart) {
-    parts.push(
-      [
-        `# Thread \`${options.threadId}\``,
-        "",
-        `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
-        "",
-        "## Task",
-        "",
-        options.prompt,
-      ].join("\n"),
-    );
-  }
+  const startSection = formatStartSection(options);
+  if (startSection !== "") parts.push(startSection);

-  // Skip hint
  if (skippedCount > 0 && selected.length > 0) {
    const firstSelected = selected[0];
    if (firstSelected !== undefined) {
@@ -554,34 +717,21 @@ function formatThreadReadMarkdown(options: {
    }
  }

-  // Step blocks
  const startIndex = candidates.length - selected.length;
+  const shownPromptRoles = new Set<string>();
  for (let i = 0; i < selected.length; i++) {
    const item = selected[i];
    if (item === undefined) continue;
    const stepNum = startIndex + i + 1;
-    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
-    const ts = new Date(item.timestamp)
-      .toISOString()
-      .replace("T", " ")
-      .replace(/\.\d+Z$/, "");
-    const stepLines = [
-      `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
-      `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
-    ];
    const roleDef = workflow.roles[item.payload.role];
-    if (roleDef) {
-      const prompt = roleDef.goal;
-      stepLines.push("", "### Prompt", "", prompt);
-    }
-    if (item.payload.detail) {
-      const content = extractLastAssistantContent(uwf, item.payload.detail);
-      if (content !== null) {
-        stepLines.push("", "### Content", "", content);
-      }
-    }
-    stepLines.push("", "### Output", "", "```yaml", outputYaml, "```");
-    parts.push(stepLines.join("\n"));
+    const stepBlock = [
+      formatStepHeader(stepNum, item),
+      formatStepPrompt(roleDef, item.payload.role, shownPromptRoles),
+      formatStepContent(uwf, item),
+    ]
+      .filter((s) => s !== "")
+      .join("");
+    parts.push(stepBlock);
  }

  return parts.join("\n\n---\n\n");
@@ -7,6 +7,6 @@ export function formatOutput(data: unknown, format: OutputFormat): string {
    case "json":
      return JSON.stringify(data);
    case "yaml":
-      return stringify(data).trimEnd();
+      return stringify(data, { aliasDuplicateObjects: false }).trimEnd();
  }
 }
@@ -0,0 +1,141 @@
+# @uncaged/workflow-agent-builtin
+
+`uwf-builtin` agent — built-in LLM agent with file read/write and shell tools.
+
+## Overview
+
+Layer 3 agent implementation. Runs an OpenAI-compatible chat completion loop with built-in tools (`read_file`, `write_file`, `run_command`). Uses the configured provider/model from `config.yaml`. Produces frontmatter markdown output and stores turn-by-turn session detail in CAS.
+
+Useful when you want a self-contained agent without an external CLI like Hermes or Claude Code.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-util`
+
+## Installation
+
+Included as the `uwf-builtin` binary when you install `@uncaged/workflow-agent-builtin`:
+
+```bash
+bun add -g @uncaged/workflow-agent-builtin
+```
+
+## CLI Usage
+
+Invoked by `uwf thread step`:
+
+```bash
+uwf-builtin <thread-id> <role>
+```
+
+Configure as default agent:
+
+```bash
+uwf setup --agent builtin
+```
+
+Override per step:
+
+```bash
+uwf thread step <thread-id> --agent uwf-builtin
+```
+
+Environment variables set by the engine:
+
+| Variable | Purpose |
+|----------|---------|
+| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
+
+## API
+
+All exports come from `src/index.ts`.
+
+### Agent factory
+
+```typescript
+function createBuiltinAgent(): () => Promise<void>
+function buildBuiltinMessages(ctx: AgentContext): ChatMessage[]
+```
+
+### LLM loop
+
+```typescript
+const BUILTIN_MAX_TURNS = 30;
+const BUILTIN_CONTINUE_MAX_TURNS = 5;
+
+function runBuiltinLoop(/* options: RunBuiltinLoopOptions */): Promise<RunBuiltinLoopResult>
+function chatCompletionWithTools(
+  provider: ResolvedLlmProvider,
+  messages: ChatMessage[],
+  tools: OpenAiToolDefinition[],
+): Promise<LlmAssistantResponse>
+```
+
+`RunBuiltinLoopOptions` and `RunBuiltinLoopResult` are internal to `loop.ts` and not re-exported from `index.ts`.
+
+### Tools
+
+```typescript
+function getBuiltinTools(): readonly BuiltinTool[]
+function executeBuiltinTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string>
+```
+
+### Session and detail
+
+```typescript
+function initSessionDir(storageRoot: string): Promise<void>
+function appendSessionTurn(storageRoot: string, sessionId: string, turn: BuiltinTurnPayload): Promise<void>
+function readSessionTurns(storageRoot: string, sessionId: string): Promise<BuiltinTurnPayload[]>
+function removeSession(storageRoot: string, sessionId: string): Promise<void>
+function registerBuiltinSchemas(store: Store): Promise<BuiltinSchemaHashes>
+function storeBuiltinDetail(store: Store, payload: BuiltinDetailPayload): Promise<string>
+```
+
+### Types
+
+```typescript
+type ChatMessage = /* system | user | assistant | tool */;
+type LlmAssistantResponse = { content: string | null; toolCalls: LlmToolCall[] | null };
+type LlmToolCall = { id: string; name: string; arguments: string };
+type BuiltinTool = { name: string; description: string; parameters: Record<string, unknown> };
+type ToolContext = { cwd: string; storageRoot: string };
+type BuiltinDetailPayload = { /* session turns, model, timestamps */ };
+type BuiltinLoopTurn = { /* single loop iteration record */ };
+type BuiltinToolCallRecord = { /* tool call audit */ };
+type BuiltinToolResultRecord = { /* tool result audit */ };
+type BuiltinTurnPayload = { /* persisted turn */ };
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts
+├── cli.ts              Binary entrypoint
+├── agent.ts            createBuiltinAgent
+├── loop.ts             Multi-turn LLM + tool loop
+├── prompt.ts           buildBuiltinMessages
+├── session.ts          Session directory persistence
+├── detail.ts           CAS detail node storage
+├── schemas.ts          Builtin CAS schemas
+├── types.ts            Detail and turn payload types
+├── llm/
+│   ├── index.ts
+│   ├── llm.ts          chatCompletionWithTools
+│   └── types.ts        ChatMessage, LlmToolCall, etc.
+└── tools/
+    ├── index.ts        getBuiltinTools, executeBuiltinTool
+    ├── read-file.ts
+    ├── write-file.ts
+    ├── run-command.ts
+    ├── path.ts
+    └── types.ts
+```
+
+## Configuration
+
+Requires a configured OpenAI-compatible provider and model in `~/.uncaged/workflow/config.yaml` (via `uwf setup`). API keys are loaded from `~/.uncaged/workflow/.env`.
+
+Tools run with the current working directory as `ToolContext.cwd` (typically the directory where `uwf thread step` was invoked).
@@ -0,0 +1,156 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const mockChatCompletionWithTools = mock(async () => ({
+  content: "---\nstatus: done\n---",
+  toolCalls: [],
+}));
+const mockAppendSessionTurn = mock(async () => {});
+const mockExecuteBuiltinTool = mock(async () => "tool-result");
+
+mock.module("../src/llm/index.js", () => ({
+  chatCompletionWithTools: mockChatCompletionWithTools,
+}));
+mock.module("../src/session.js", () => ({
+  appendSessionTurn: mockAppendSessionTurn,
+}));
+mock.module("../src/tools/index.js", () => ({
+  builtinToolsToOpenAi: () => [],
+  executeBuiltinTool: mockExecuteBuiltinTool,
+  getBuiltinTools: () => [],
+}));
+
+import { executeTurnTools, runBuiltinLoop, shouldNudge } from "../src/loop.js";
+
+const fakeProvider = {} as any;
+const fakeToolCtx = {} as any;
+
+function makeOptions(overrides: Partial<Parameters<typeof runBuiltinLoop>[0]> = {}) {
+  return {
+    provider: fakeProvider,
+    messages: [{ role: "system" as const, content: "sys" }],
+    toolCtx: fakeToolCtx,
+    maxTurns: 5,
+    storageRoot: "/tmp",
+    sessionId: "sess",
+    noTools: false,
+    ...overrides,
+  };
+}
+
+beforeEach(() => {
+  mockChatCompletionWithTools.mockReset();
+  mockAppendSessionTurn.mockReset();
+  mockExecuteBuiltinTool.mockReset();
+});
+
+describe("shouldNudge", () => {
+  test("2.1 returns true when all conditions met", () => {
+    expect(shouldNudge({ noTools: false, text: "some text", turn: 0, maxTurns: 5 })).toBe(true);
+  });
+  test("2.2 returns false when noTools=true", () => {
+    expect(shouldNudge({ noTools: true, text: "some text", turn: 0, maxTurns: 5 })).toBe(false);
+  });
+  test("2.3 returns false when text starts with ---", () => {
+    expect(shouldNudge({ noTools: false, text: "---\nstatus: done", turn: 0, maxTurns: 5 })).toBe(
+      false,
+    );
+  });
+  test("2.4 returns false on last turn", () => {
+    expect(shouldNudge({ noTools: false, text: "some text", turn: 4, maxTurns: 5 })).toBe(false);
+  });
+  test("2.5 returns true on second-to-last turn", () => {
+    expect(shouldNudge({ noTools: false, text: "some text", turn: 3, maxTurns: 5 })).toBe(true);
+  });
+  test("2.6 leading whitespace before --- suppresses nudge", () => {
+    expect(shouldNudge({ noTools: false, text: "  ---\nstatus: done", turn: 0, maxTurns: 5 })).toBe(
+      false,
+    );
+  });
+});
+
+describe("executeTurnTools", () => {
+  test("4.1 executes each tool call and pushes tool result messages", async () => {
+    mockExecuteBuiltinTool.mockResolvedValue("result");
+    const messages: any[] = [];
+    const calls = [
+      { id: "c1", name: "tool_a", arguments: "{}" },
+      { id: "c2", name: "tool_b", arguments: "{}" },
+    ];
+    const count = await executeTurnTools(calls, fakeToolCtx, messages, "/tmp", "sess");
+    expect(messages.length).toBe(2);
+    expect(messages[0].role).toBe("tool");
+    expect(messages[1].role).toBe("tool");
+    expect(count).toBe(2);
+  });
+  test("4.2 tool result content matches executeBuiltinTool return value", async () => {
+    mockExecuteBuiltinTool.mockResolvedValue("result-A");
+    const messages: any[] = [];
+    await executeTurnTools(
+      [{ id: "c1", name: "read_file", arguments: "{}" }],
+      fakeToolCtx,
+      messages,
+      "/tmp",
+      "sess",
+    );
+    expect(messages[0].content).toBe("result-A");
+  });
+});
+
+describe("runBuiltinLoop integration", () => {
+  test("3.1 single text-only response returns finalText immediately", async () => {
+    mockChatCompletionWithTools.mockResolvedValue({
+      content: "---\nstatus: done\n---",
+      toolCalls: [],
+    });
+    const result = await runBuiltinLoop(makeOptions());
+    expect(result.finalText).toBe("---\nstatus: done\n---");
+    expect(result.turnCount).toBe(1);
+  });
+  test("3.2 noTools=true suppresses tool calls", async () => {
+    mockChatCompletionWithTools.mockResolvedValue({
+      content: "ok",
+      toolCalls: [{ id: "c1", name: "read_file", arguments: "{}" }],
+    });
+    const result = await runBuiltinLoop(makeOptions({ noTools: true }));
+    expect(result.finalText).toBe("ok");
+    expect(result.turnCount).toBe(1);
+  });
+  test("3.3 tool call followed by text response", async () => {
+    mockChatCompletionWithTools
+      .mockResolvedValueOnce({
+        content: null,
+        toolCalls: [{ id: "c1", name: "read_file", arguments: "{}" }],
+      })
+      .mockResolvedValueOnce({ content: "---\nstatus: done\n---", toolCalls: [] });
+    mockExecuteBuiltinTool.mockResolvedValue("file contents");
+    const result = await runBuiltinLoop(makeOptions());
+    expect(result.finalText).toBe("---\nstatus: done\n---");
+    expect(result.turnCount).toBe(3);
+  });
+  test("3.4 nudge cycle inserts nudge message", async () => {
+    mockChatCompletionWithTools
+      .mockResolvedValueOnce({ content: "I am thinking", toolCalls: [] })
+      .mockResolvedValueOnce({ content: "---\nstatus: done\n---", toolCalls: [] });
+    const result = await runBuiltinLoop(makeOptions());
+    expect(result.finalText).toBe("---\nstatus: done\n---");
+    const nudgeMsg = result.messages.find(
+      (m) =>
+        m.role === "user" && typeof m.content === "string" && m.content.includes("frontmatter"),
+    );
+    expect(nudgeMsg).toBeDefined();
+  });
+  test("3.5 maxTurns exhaustion falls back to last assistant content", async () => {
+    mockChatCompletionWithTools.mockResolvedValue({ content: "still thinking", toolCalls: [] });
+    const result = await runBuiltinLoop(makeOptions({ maxTurns: 3 }));
+    expect(result.finalText).toBe("still thinking");
+  });
+  test("3.6 original messages array is not mutated", async () => {
+    mockChatCompletionWithTools.mockResolvedValue({
+      content: "---\nstatus: done\n---",
+      toolCalls: [],
+    });
+    const original = [{ role: "system" as const, content: "sys" }];
+    await runBuiltinLoop(makeOptions({ messages: original }));
+    expect(original.length).toBe(1);
+  });
+});
@@ -13,10 +13,28 @@ import { storeBuiltinDetail } from "./detail.js";
 import type { ChatMessage } from "./llm/index.js";
 import { BUILTIN_CONTINUE_MAX_TURNS, BUILTIN_MAX_TURNS, runBuiltinLoop } from "./loop.js";
 import { buildBuiltinMessages } from "./prompt.js";
-import { initSessionDir, removeSession } from "./session.js";
+import { initSessionDir } from "./session.js";

 const log = createLogger({ sink: { kind: "stderr" } });

+const FRONTMATTER_FENCE = "---";
+
+/**
+ * Strip any text before the first `---` fence.
+ * LLMs sometimes emit preamble text before the frontmatter block.
+ */
+function stripPreamble(text: string): string {
+  if (text.startsWith(FRONTMATTER_FENCE)) {
+    return text;
+  }
+  const idx = text.indexOf(`\n${FRONTMATTER_FENCE}\n`);
+  if (idx !== -1) {
+    log("6GWRP3QX", `stripped ${idx + 1} chars of preamble before frontmatter`);
+    return text.slice(idx + 1);
+  }
+  return text;
+}
+
 type SessionRecord = {
  sessionId: string;
  model: string;
@@ -48,6 +66,7 @@ async function runBuiltinWithMessages(
  session: SessionRecord,
  store: Store,
  maxTurns: number,
+  noTools: boolean,
 ): Promise<AgentRunResult> {
  const loopResult = await runBuiltinLoop({
    provider,
@@ -56,13 +75,13 @@ async function runBuiltinWithMessages(
    maxTurns,
    storageRoot,
    sessionId: session.sessionId,
+    noTools,
  });

  session.messages = loopResult.messages;

  if (loopResult.turnCount === 0) {
    log("5RWTK9NB", "no turns produced, returning empty output");
-    await removeSession(storageRoot, session.sessionId);
    return { output: "", detailHash: "", sessionId: session.sessionId };
  }

@@ -75,10 +94,7 @@ async function runBuiltinWithMessages(
    session.startedAtMs,
  );

-  // Clean up session jsonl
-  await removeSession(storageRoot, session.sessionId);
-
-  return { output: loopResult.finalText, detailHash, sessionId: session.sessionId };
+  return { output: stripPreamble(loopResult.finalText), detailHash, sessionId: session.sessionId };
 }

 async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
@@ -105,6 +121,7 @@ async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {
    session,
    ctx.store,
    BUILTIN_MAX_TURNS,
+    false,
  );
 }

@@ -127,6 +144,7 @@ async function continueBuiltin(
    session,
    store,
    BUILTIN_CONTINUE_MAX_TURNS,
+    true,
  );
 }

@@ -96,8 +96,17 @@ function serializeMessage(message: ChatMessage): Record<string, unknown> {
 export async function chatCompletionWithTools(
  provider: ResolvedLlmProvider,
  messages: ChatMessage[],
-  tools: OpenAiToolDefinition[],
+  tools: OpenAiToolDefinition[] | null,
 ): Promise<LlmAssistantResponse> {
+  const body: Record<string, unknown> = {
+    model: provider.model,
+    messages: messages.map(serializeMessage),
+  };
+  if (tools !== null && tools.length > 0) {
+    body.tools = tools;
+    body.tool_choice = "auto";
+  }
+
  let response: Response;
  try {
    response = await fetch(chatUrl(provider.baseUrl), {
@@ -106,12 +115,7 @@ export async function chatCompletionWithTools(
        Authorization: `Bearer ${provider.apiKey}`,
        "Content-Type": "application/json",
      },
-      body: JSON.stringify({
-        model: provider.model,
-        messages: messages.map(serializeMessage),
-        tools,
-        tool_choice: "auto",
-      }),
+      body: JSON.stringify(body),
    });
  } catch (cause) {
    const message = cause instanceof Error ? cause.message : String(cause);
@@ -23,6 +23,8 @@ export type RunBuiltinLoopOptions = {
  maxTurns: number;
  storageRoot: string;
  sessionId: string;
+  /** When true, do not provide tools — force LLM to emit text only. */
+  noTools: boolean;
 };

 export type RunBuiltinLoopResult = {
@@ -46,7 +48,7 @@ async function appendTurn(
  await appendSessionTurn(storageRoot, sessionId, payload);
 }

-async function executeTurnTools(
+export async function executeTurnTools(
  calls: Array<{ id: string; name: string; arguments: string }>,
  toolCtx: ToolContext,
  messages: ChatMessage[],
@@ -68,35 +70,89 @@ async function executeTurnTools(
  return turnCount;
 }

+export type ShouldNudgeOptions = {
+  noTools: boolean;
+  text: string;
+  turn: number;
+  maxTurns: number;
+};
+
+const MAX_NUDGES = 3;
+const DEADLINE_WARNING_TURNS = 3;
+
+export function shouldNudge({ noTools, text, turn, maxTurns }: ShouldNudgeOptions): boolean {
+  return !noTools && !text.trimStart().startsWith("---") && turn < maxTurns - 1;
+}
+
 /** Agent run loop: LLM ↔ tools until no tool_calls or maxTurns. */
 export async function runBuiltinLoop(
  options: RunBuiltinLoopOptions,
 ): Promise<RunBuiltinLoopResult> {
  const messages = [...options.messages];
-  const openAiTools = builtinToolsToOpenAi(getBuiltinTools());
+  const openAiTools = options.noTools ? [] : builtinToolsToOpenAi(getBuiltinTools());
  let finalText = "";
  let turnCount = 0;
+  let nudgeCount = 0;
+  let deadlineWarned = false;

  for (let turn = 0; turn < options.maxTurns; turn++) {
    log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
-    const response = await chatCompletionWithTools(options.provider, messages, openAiTools);
+
+    // Warn agent when approaching turn limit
+    const turnsRemaining = options.maxTurns - turn;
+    if (!options.noTools && !deadlineWarned && turnsRemaining <= DEADLINE_WARNING_TURNS) {
+      deadlineWarned = true;
+      log("4NRXW6KT", `${turnsRemaining} turns remaining, injecting deadline warning`);
+      messages.push({
+        role: "user",
+        content:
+          `⚠️ You have ${turnsRemaining} turns remaining. ` +
+          "Wrap up your work and output the YAML frontmatter starting with `---`. " +
+          "If you cannot finish in time, output frontmatter with `status: failed` and describe what remains.",
+      });
+    }
+
+    const response = await chatCompletionWithTools(
+      options.provider,
+      messages,
+      openAiTools.length > 0 ? openAiTools : null,
+    );
+
+    // When noTools is set, ignore any tool_calls the LLM might still return
+    const effectiveToolCalls = options.noTools ? null : (response.toolCalls ?? null);

    const assistantMessage: ChatMessage = {
      role: "assistant",
      content: response.content,
-      tool_calls: response.toolCalls,
+      tool_calls: effectiveToolCalls,
    };
    messages.push(assistantMessage);

-    if (response.toolCalls === null || response.toolCalls.length === 0) {
-      finalText = response.content ?? "";
+    if (effectiveToolCalls === null || effectiveToolCalls.length === 0) {
+      const text = response.content ?? "";
      await appendTurn(options.storageRoot, options.sessionId, {
        role: "assistant",
-        content: response.content ?? "",
+        content: text,
        toolCalls: null,
        reasoning: null,
      });
      turnCount += 1;
+
+      if (shouldNudge({ noTools: options.noTools, text, turn, maxTurns: options.maxTurns })) {
+        nudgeCount += 1;
+        log("7FXQM2KN", `text-only turn without frontmatter, nudge ${nudgeCount}/${MAX_NUDGES}`);
+        const nudge =
+          "You stopped calling tools but your response does not start with the required `---` YAML frontmatter. " +
+          "Either continue using tools to complete your work, or output your final response starting with `---`.";
+        messages.push({ role: "user", content: nudge });
+        // Nudge doesn't consume turn budget (up to MAX_NUDGES)
+        if (nudgeCount <= MAX_NUDGES) {
+          turn -= 1;
+        }
+        continue;
+      }
+
+      finalText = text;
      break;
    }

@@ -104,14 +160,14 @@ export async function runBuiltinLoop(
    await appendTurn(options.storageRoot, options.sessionId, {
      role: "assistant",
      content: response.content ?? "",
-      toolCalls: mapToolCallsForPayload(response.toolCalls),
+      toolCalls: mapToolCallsForPayload(effectiveToolCalls),
      reasoning: null,
    });
    turnCount += 1;

    // Execute tools
    turnCount += await executeTurnTools(
-      response.toolCalls,
+      effectiveToolCalls,
      options.toolCtx,
      messages,
      options.storageRoot,
@@ -59,6 +59,22 @@ export function buildBuiltinMessages(ctx: AgentContext): ChatMessage[] {
  }
  systemParts.push(rolePrompt);

+  systemParts.push(
+    "",
+    "## Workflow",
+    "",
+    `Your working directory is: ${process.cwd()}`,
+    "",
+    "You have tools available (read_file, write_file, run_command). " +
+      "Use them to complete your task — read files, run commands, make changes as needed. " +
+      "Your task is described in the user message below — do NOT use uwf or workflow CLI commands to discover your task. " +
+      "When you are done, output your final response with the YAML frontmatter block as specified above. " +
+      "Do NOT output the frontmatter until you have completed all necessary work. " +
+      "If you are running low on turns and cannot finish, output the frontmatter with `status: failed` and explain what remains in the body. " +
+      "CRITICAL: Your final output MUST start with the `---` fence on the very first line — " +
+      "no preamble text, no explanation before it. The parser requires `---` at position 0.",
+  );
+
  const messages: ChatMessage[] = [{ role: "system", content: systemParts.join("\n") }];

  const roleVisitIndices: number[] = [];
@@ -0,0 +1,91 @@
+# @uncaged/workflow-agent-claude-code
+
+`uwf-claude-code` agent — spawns the Claude Code CLI and captures session detail.
+
+## Overview
+
+Layer 3 agent implementation. Spawns the `claude` CLI with a composed system prompt (role definition, task, prior steps, edge prompt). Parses stream or JSON stdout, caches session IDs for multi-turn continuation, and stores raw output plus structured detail in CAS.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`
+
+## Installation
+
+Included as the `uwf-claude-code` binary when you install `@uncaged/workflow-agent-claude-code`:
+
+```bash
+bun add -g @uncaged/workflow-agent-claude-code
+```
+
+Requires the `claude` CLI on `PATH`.
+
+## CLI Usage
+
+Invoked by `uwf thread step`:
+
+```bash
+uwf-claude-code <thread-id> <role>
+```
+
+Configure or override the agent:
+
+```bash
+uwf setup --agent claude-code
+uwf thread step <thread-id> --agent uwf-claude-code
+```
+
+Environment variables set by the engine:
+
+| Variable | Purpose |
+|----------|---------|
+| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
+
+## API
+
+All exports come from `src/index.ts`.
+
+### Agent factory
+
+```typescript
+function createClaudeCodeAgent(): () => Promise<void>
+function buildClaudeCodePrompt(ctx: AgentContext): string
+```
+
+### Session detail
+
+```typescript
+function parseClaudeCodeStreamOutput(stdout: string): ClaudeCodeParsedResult | null
+function parseClaudeCodeJsonOutput(stdout: string): ClaudeCodeParsedResult | null
+function storeClaudeCodeDetail(
+  store: Store,
+  parsed: ClaudeCodeParsedResult,
+  sessionId: string,
+): Promise<string>
+function storeClaudeCodeRawOutput(store: Store, rawOutput: string): Promise<string>
+```
+
+## Usage (library)
+
+```typescript
+import { createClaudeCodeAgent, buildClaudeCodePrompt } from "@uncaged/workflow-agent-claude-code";
+
+const main = createClaudeCodeAgent();
+void main();
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts
+├── cli.ts              Binary entrypoint
+├── claude-code.ts      createClaudeCodeAgent, buildClaudeCodePrompt, spawn logic
+├── session-detail.ts   Parse stdout, store CAS detail nodes
+├── schemas.ts          Claude Code detail CAS schemas
+└── types.ts            ClaudeCodeParsedResult, message shapes
+```
+
+## Configuration
+
+Uses session caching from `@uncaged/workflow-agent-kit` (`getCachedSessionId` / `setCachedSessionId`). No separate config file — relies on the Claude Code CLI's own authentication.
+
+Maximum turns per invocation: 90 (constant in `claude-code.ts`).
@@ -16,6 +16,7 @@ const log = createLogger({ sink: { kind: "stderr" } });

 const CLAUDE_COMMAND = "claude";
 const CLAUDE_MAX_TURNS = 90;
+const CLAUDE_MODEL = process.env["CLAUDE_MODEL"] ?? null;

 function buildHistorySummary(steps: AgentContext["steps"]): string {
  if (steps.length === 0) {
@@ -49,6 +50,7 @@ export function buildClaudeCodePrompt(ctx: AgentContext): string {
  if (historyBlock !== "") {
    parts.push("", historyBlock);
  }
+  parts.push("", "## Current Instruction", "", ctx.edgePrompt);
  return parts.join("\n");
 }

@@ -86,7 +88,7 @@ function spawnClaude(args: string[]): Promise<{ stdout: string; stderr: string }
 }

 function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: string }> {
-  return spawnClaude([
+  const args = [
    "-p",
    prompt,
    "--output-format",
@@ -95,14 +97,18 @@ function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: strin
    "--dangerously-skip-permissions",
    "--max-turns",
    String(CLAUDE_MAX_TURNS),
-  ]);
+  ];
+  if (CLAUDE_MODEL !== null) {
+    args.push("--model", CLAUDE_MODEL);
+  }
+  return spawnClaude(args);
 }

 function spawnClaudeResume(
  sessionId: string,
  message: string,
 ): Promise<{ stdout: string; stderr: string }> {
-  return spawnClaude([
+  const args = [
    "-p",
    message,
    "--resume",
@@ -113,7 +119,11 @@ function spawnClaudeResume(
    "--dangerously-skip-permissions",
    "--max-turns",
    String(CLAUDE_MAX_TURNS),
-  ]);
+  ];
+  if (CLAUDE_MODEL !== null) {
+    args.push("--model", CLAUDE_MODEL);
+  }
+  return spawnClaude(args);
 }

 async function processClaudeOutput(stdout: string, store: Store): Promise<AgentRunResult> {
@@ -132,6 +142,8 @@ async function processClaudeOutput(stdout: string, store: Store): Promise<AgentR
 async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
  const fullPrompt = buildClaudeCodePrompt(ctx);

+  log("K7R2M4N8", `prompt for role=${ctx.role} (length=${fullPrompt.length}):\n${fullPrompt}`);
+
  // Try resuming a cached session for re-entry scenarios (e.g. reviewer reject → developer re-entry).
  if (!ctx.isFirstVisit) {
    const cachedSessionId = await getCachedSessionId(ctx.threadId, ctx.role);
@@ -0,0 +1,90 @@
+# @uncaged/workflow-agent-hermes
+
+`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
+
+## Overview
+
+Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
+
+## Installation
+
+Included as the `uwf-hermes` binary when you install `@uncaged/workflow-agent-hermes`:
+
+```bash
+bun add -g @uncaged/workflow-agent-hermes
+```
+
+Requires the `hermes` CLI on `PATH`.
+
+## CLI Usage
+
+Invoked by `uwf thread step` (not typically run directly):
+
+```bash
+uwf-hermes <thread-id> <role>
+```
+
+Environment variables set by the engine:
+
+| Variable | Purpose |
+|----------|---------|
+| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
+
+Configure as the default agent via `uwf setup --agent hermes`.
+
+Override per step:
+
+```bash
+uwf thread step <thread-id> --agent uwf-hermes
+```
+
+## API
+
+All exports come from `src/index.ts`.
+
+### Agent factory
+
+```typescript
+function createHermesAgent(): () => Promise<void>
+function buildHermesPrompt(ctx: AgentContext): string
+```
+
+### ACP client
+
+```typescript
+class HermesAcpClient {
+  // Spawns hermes, handles JSON-RPC over stdio
+}
+```
+
+## Usage (library)
+
+```typescript
+import { createHermesAgent, buildHermesPrompt } from "@uncaged/workflow-agent-hermes";
+
+// CLI entry (src/cli.ts):
+const main = createHermesAgent();
+void main();
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts
+├── cli.ts              Binary entrypoint
+├── hermes.ts           createHermesAgent, buildHermesPrompt
+├── acp-client.ts       HermesAcpClient — ACP JSON-RPC over stdio
+├── session-cache.ts    Session ID cache (re-exports kit helpers + isResumeDisabled)
+├── session-detail.ts   Parse Hermes session JSON, store CAS detail nodes
+├── schemas.ts          Hermes detail CAS schemas
+└── types.ts            HermesSessionJson, HermesSessionMessage
+```
+
+## Configuration
+
+Uses workflow config from `~/.uncaged/workflow/config.yaml` (via agent-kit). Hermes session files are stored under the workflow storage root (see `session-detail.ts`).
+
+Set `UWF_HERMES_NO_RESUME=1` to disable session resume (see `isResumeDisabled` in `session-cache.ts`).
@@ -0,0 +1,182 @@
+# @uncaged/workflow-agent-kit
+
+Agent framework — `createAgent` factory, context builder, frontmatter fast-path, and LLM extract pipeline.
+
+## Overview
+
+Layer 2 agent framework. Provides the standard entrypoint for all agent CLIs: parse `<thread-id> <role>` from argv, load thread/workflow context from CAS, invoke the agent's `run`/`continue` functions, validate output via frontmatter fast-path or LLM extract, and write a `StepNodePayload` to CAS.
+
+Also exports prompt builders, config/storage helpers, and session ID caching for multi-turn agents.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `dotenv`, `yaml`
+
+## Installation
+
+```bash
+bun add @uncaged/workflow-agent-kit
+```
+
+## API
+
+All exports come from `src/index.ts`.
+
+### Agent factory
+
+```typescript
+function createAgent(options: AgentOptions): () => Promise<void>
+
+type AgentOptions = {
+  name: string;
+  run: AgentRunFn;
+  continue: AgentContinueFn;
+};
+
+type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
+type AgentContinueFn = (
+  sessionId: string,
+  message: string,
+  store: AgentContext["store"],
+) => Promise<AgentRunResult>;
+
+type AgentRunResult = {
+  output: string;
+  detailHash: string;
+  sessionId: string;
+};
+```
+
+Agent CLIs call `createAgent(...)` and invoke the returned function as `main()`.
+
+### Context
+
+```typescript
+function buildContext(threadId: ThreadId, role: string): Promise<AgentContext>
+function buildContextWithMeta(
+  threadId: ThreadId,
+  role: string,
+): Promise<AgentContext & { meta: BuildContextMeta }>
+
+type AgentContext = ModeratorContext & {
+  threadId: ThreadId;
+  role: string;
+  store: Store;
+  workflow: WorkflowPayload;
+  outputFormatInstruction: string;
+  edgePrompt: string;
+  isFirstVisit: boolean;
+};
+
+type BuildContextMeta = {
+  storageRoot: string;
+  store: Store;
+  schemas: AgentStore["schemas"];
+  headHash: CasRef;
+  chain: ChainState;
+};
+```
+
+Requires `UWF_EDGE_PROMPT` in the environment (set by `uwf thread step`).
+
+### Prompt builders
+
+```typescript
+function buildRolePrompt(role: RoleDefinition): string
+function buildOutputFormatInstruction(schema: JSONSchema): string
+function buildContinuationPrompt(
+  ctx: AgentContext,
+  priorOutput: string,
+  instruction: string,
+): string
+```
+
+### Extract pipeline
+
+```typescript
+function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias
+function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider
+function extract(
+  rawOutput: string,
+  outputSchema: CasRef,
+  config: WorkflowConfig,
+): Promise<ExtractResult>
+
+type ResolvedLlmProvider = { baseUrl: string; apiKey: string; model: string };
+type ExtractResult = { value: unknown; hash: CasRef };
+```
+
+### Frontmatter fast-path
+
+```typescript
+function tryFrontmatterFastPath(
+  rawOutput: string,
+  outputSchema: CasRef,
+  store: Store,
+): Promise<FrontmatterFastPathResult | null>
+
+type FrontmatterFastPathResult = { body: string; outputHash: CasRef };
+```
+
+### Session cache
+
+```typescript
+function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null>
+function setCachedSessionId(
+  threadId: ThreadId,
+  role: string,
+  sessionId: string,
+): Promise<void>
+```
+
+### Config and storage
+
+```typescript
+function getConfigPath(storageRoot: string): string
+function getEnvPath(storageRoot: string): string
+function resolveStorageRoot(): string
+function loadWorkflowConfig(storageRoot: string): Promise<WorkflowConfig>
+```
+
+## Usage
+
+```typescript
+import { createAgent, buildRolePrompt } from "@uncaged/workflow-agent-kit";
+import type { AgentContext, AgentRunResult } from "@uncaged/workflow-agent-kit";
+
+async function run(ctx: AgentContext): Promise<AgentRunResult> {
+  const prompt = buildRolePrompt(ctx.workflow.roles[ctx.role]!);
+  // ... spawn external process, capture output ...
+  return { output: markdown, detailHash: "...", sessionId: "..." };
+}
+
+async function continueSession(
+  sessionId: string,
+  message: string,
+): Promise<AgentRunResult> {
+  // ... continue multi-turn session ...
+  return { output: markdown, detailHash: "...", sessionId };
+}
+
+export const main = createAgent({ name: "my-agent", run, continue: continueSession });
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts
+├── run.ts                         createAgent entrypoint
+├── context.ts                     Thread chain walk, AgentContext builder
+├── extract.ts                     LLM structured extract fallback
+├── frontmatter.ts                 Frontmatter fast-path validation
+├── build-role-prompt.ts           Role definition → prompt text
+├── build-output-format-instruction.ts
+├── build-continuation-prompt.ts
+├── session-cache.ts               Per-thread/session ID persistence
+├── storage.ts                     CAS store, config, threads index
+├── schemas.ts                     Agent CAS schema registration
+└── types.ts                       AgentContext, AgentOptions, etc.
+```
+
+## Configuration
+
+Reads `config.yaml` and `.env` from the workflow storage root (`~/.uncaged/workflow` by default). See `@uncaged/workflow-protocol` for `WorkflowConfig` shape. Set via `uwf setup`.
@@ -121,6 +121,11 @@ export function createAgent(options: AgentOptions): () => Promise<void> {

    let agentResult = await runWithMessage("agent run failed", () => options.run(ctx));

+    // Preserve the primary detail from the first run — it contains the full
+    // tool-call turn history.  Continuation retries only fix frontmatter
+    // formatting and their 1-turn detail is not meaningful.
+    const primaryDetailHash = agentResult.detailHash;
+
    // Try to extract frontmatter; retry via continue if it fails
    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);

@@ -147,7 +152,7 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
    const stepHash = await persistStep({
      ctx,
      outputHash,
-      detailHash: agentResult.detailHash,
+      detailHash: primaryDetailHash,
      agentName: agentLabel(options.name),
    });

@@ -0,0 +1,84 @@
+# @uncaged/workflow-dashboard
+
+Web graph editor for visualizing and editing workflow YAML definitions.
+
+## Overview
+
+A private alpha web app (not part of the runtime engine stack). Provides a React + `@xyflow/react` canvas for editing workflow roles, conditions, and graph transitions. Uses `@uncaged/workflow-protocol` types for validation and YAML round-tripping.
+
+Planned integration: local `uwf connect` over WebSocket to sync YAML between CLI and the browser editor. The REST API and Elysia backend are currently stubs for development.
+
+**Dependencies:** `@uncaged/workflow-protocol`, `@xyflow/react`, React 19, react-router v7, Vite 8, Tailwind CSS v4, Elysia
+
+## Installation
+
+Monorepo-only ( `"private": true` ). Not published to npm.
+
+```bash
+cd packages/workflow-dashboard
+bun install --no-cache
+```
+
+## CLI Usage
+
+Start the Vite dev server (port 3000):
+
+```bash
+cd packages/workflow-dashboard
+bun run dev
+```
+
+Build for production:
+
+```bash
+bun run build
+```
+
+Open `http://localhost:3000` in a browser.
+
+## Internal Structure
+
+```
+workflow-dashboard/
+├── server.ts                 Vite dev server entry (port 3000)
+├── vite.config.ts            Vite + React + Tailwind + Elysia plugin
+├── vite-dev.ts               Custom Vite plugin
+├── index.html
+├── components.json           shadcn configuration
+├── server/
+│   ├── api.ts                Elysia REST API (health + workflow CRUD stub)
+│   └── workflow.ts           Workflow file read/write + format conversion
+└── src/
+    ├── main.tsx              React DOM entry
+    ├── app.tsx               Root layout
+    ├── router.tsx            Hash-mode routes
+    ├── index.css
+    ├── lib/utils.ts          Tailwind cn() helper
+    ├── components/ui/        shadcn components (button, card, dialog, input, …)
+    ├── pages/
+    │   ├── home.tsx          Workflow list
+    │   ├── detail.tsx        Workflow detail view
+    │   └── editor.tsx        Full editor page
+    └── editor/               Core graph editor
+        ├── flow.tsx          FlowEditor component
+        ├── context.tsx       State (useSyncExternalStore + Immer)
+        ├── injection.ts      DI container
+        ├── type.ts             Internal editor types
+        ├── model/              Node/edge state model
+        ├── nodes/              Start, role, end node components
+        ├── edges/              Conditional edge rendering
+        ├── panel/              Toolbar, add/edit panels
+        ├── trans/              YAML ↔ graph conversion (trans-in, trans-out, validate)
+        ├── layout/             Auto-layout
+        └── utils/              Event helpers, click-outside hook
+```
+
+## Configuration
+
+| Setting | Default | Notes |
+|---------|---------|-------|
+| Dev server port | `3000` | Set in `server.ts` |
+| Workflow storage (dev) | `tmp/workflow/` | YAML files during development |
+| Path alias | `@/` → `src/` | Configured in `vite.config.ts` |
+
+No library API — this package is an application, not importable as a module.
@@ -0,0 +1,60 @@
+# @uncaged/workflow-moderator
+
+JSONata-based graph evaluator — determines the next role or `$END` with zero LLM cost.
+
+## Overview
+
+The moderator (Layer 1) walks the workflow graph from the current role. For each outgoing transition it evaluates an optional JSONata condition against `ModeratorContext` (start prompt + prior step outputs). The first truthy transition wins; its target role and edge prompt are returned. When no transition matches, the workflow ends (`$END`).
+
+**Dependencies:** `@uncaged/workflow-protocol`, `jsonata`
+
+## Installation
+
+```bash
+bun add @uncaged/workflow-moderator
+```
+
+## API
+
+### Functions
+
+```typescript
+function evaluate(
+  workflow: WorkflowPayload,
+  context: ModeratorContext,
+): Promise<Result<EvaluateResult, Error>>
+```
+
+Returns `{ ok: true, value: { role, prompt } }` where `role` is the next role name or `"$END"`, and `prompt` is the edge instruction for the agent.
+
+### Types
+
+```typescript
+type EvaluateResult = {
+  role: string;
+  prompt: string;
+};
+```
+
+The `Result<T, E>` type is local to this package (`{ ok: true; value: T } | { ok: false; error: E }`), not re-exported from `index.ts`.
+
+## Usage
+
+```typescript
+import { evaluate } from "@uncaged/workflow-moderator";
+import type { ModeratorContext, WorkflowPayload } from "@uncaged/workflow-protocol";
+
+const result = await evaluate(workflow, context);
+if (result.ok && result.value.role !== "$END") {
+  console.log(`Next role: ${result.value.role}, prompt: ${result.value.prompt}`);
+}
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts      Public exports
+├── evaluate.ts   Graph walk + JSONata condition evaluation
+└── types.ts      EvaluateResult, Result
+```
@@ -0,0 +1,193 @@
+# @uncaged/workflow-protocol
+
+Shared TypeScript types and JSON Schema constants for the workflow engine.
+
+## Overview
+
+This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@uncaged/json-cas`.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`
+
+## Installation
+
+```bash
+bun add @uncaged/workflow-protocol
+```
+
+## API
+
+All exports come from `src/index.ts`.
+
+### JSON Schema constants
+
+```typescript
+START_NODE_SCHEMA: JSONSchema
+STEP_NODE_SCHEMA: JSONSchema
+WORKFLOW_SCHEMA: JSONSchema
+```
+
+### Core identifiers
+
+```typescript
+type CasRef = string      // XXH64 hash, 13-char Crockford Base32
+type ThreadId = string    // ULID, 26-char Crockford Base32
+type WorkflowName = string
+type RoleName = string
+```
+
+### Workflow definition
+
+```typescript
+type RoleDefinition = {
+  description: string;
+  goal: string;
+  capabilities: string[];
+  procedure: string;
+  output: string;
+  frontmatter: CasRef;
+};
+
+type Transition = {
+  role: string;
+  condition: string | null;
+  prompt: string;
+};
+
+type ConditionDefinition = {
+  description: string;
+  expression: string;
+};
+
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;
+};
+```
+
+### Thread nodes
+
+```typescript
+type StepRecord = {
+  role: string;
+  output: CasRef;
+  detail: CasRef;
+  agent: string;
+  edgePrompt: string;
+};
+
+type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+
+type StepNodePayload = StepRecord & {
+  start: CasRef;
+  prev: CasRef | null;
+};
+```
+
+### Moderator context
+
+```typescript
+type StepContext = Omit<StepRecord, "output"> & { output: unknown };
+
+type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+```
+
+### Configuration
+
+```typescript
+type ProviderAlias = string;
+type ModelAlias = string;
+type AgentAlias = string;
+
+type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
+type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+```
+
+### CLI output types
+
+```typescript
+type StartOutput = { workflow: CasRef; thread: ThreadId };
+
+type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+type StepEntry = {
+  hash: CasRef;
+  role: string;
+  output: unknown;
+  detail: CasRef;
+  agent: string;
+  timestamp: number;
+};
+
+type StartEntry = {
+  hash: CasRef;
+  workflow: CasRef;
+  prompt: string;
+  timestamp: number;
+};
+
+type ThreadStepsOutput = {
+  thread: ThreadId;
+  workflow: CasRef;
+  steps: [StartEntry, ...StepEntry[]];
+};
+
+type ThreadForkOutput = {
+  thread: ThreadId;
+  forkedFrom: { step: CasRef };
+};
+
+type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+
+type ThreadsIndex = Record<ThreadId, CasRef>;
+
+type Scenario = string;
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts      Public re-exports
+├── types.ts      All type definitions
+└── schemas.ts    START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA
+```
+
+## Configuration
+
+This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-agent-kit` (`loadWorkflowConfig`).
@@ -1,32 +1,145 @@
 # @uncaged/workflow-util

-Shared utilities: encoding, IDs, logging, storage paths, and ref-field normalization.
+Shared utilities: encoding, IDs, logging, frontmatter parsing, storage paths, and CLI reference generation.

-## What This Package Does
+## Overview

-It provides filesystem-safe Base32 and ULID generation, the structured logger used across packages, helpers for the default workflow data directory and global CAS path, and utilities to merge/normalize `refs` on steps. It re-exports `ok`/`err` from protocol for convenience.
+Layer 1 shared infrastructure used across CLI, agent-kit, and agent packages. Provides Crockford Base32 encoding, ULID generation, structured logging with fixed 8-char tags, frontmatter markdown parsing/validation, process-level debug logging, and helpers for the default workflow data directory.

-## Key Exports
+**Dependencies:** none (standalone)

-From `src/index.ts`:
+## Installation

- **Base32:** `CROCKFORD_BASE32_ALPHABET`, `decodeCrockfordBase32Bits`, `decodeCrockfordToUint64`, `encodeCrockfordBase32Bits`, `encodeUint64AsCrockford`
- **Logger:** `createLogger`
- **Refs:** `mergeRefsWithContentHash`, `normalizeRefsField`
- **Result:** `ok`, `err` (from `@uncaged/workflow-protocol`)
- **Paths:** `getDefaultWorkflowStorageRoot`, `getGlobalCasDir`
- **ULID:** `generateUlid`
- **Types:** `CreateLoggerOptions`, `LogFn`, `LoggerSink`, `Result`
+```bash
+bun add @uncaged/workflow-util
+```

-## Dependencies
+## API

- **Workspace:** `@uncaged/workflow-protocol` — `Result` and shared types used by helpers
+All exports come from `src/index.ts`.
+
+### Encoding and IDs
+
+```typescript
+function encodeUint64AsCrockford(value: bigint): string
+function generateUlid(nowMs: number): string
+```
+
+### Logging
+
+```typescript
+function createLogger(options?: { sink: { kind: "stderr" } }): LogFn
+
+type LogFn = (tag: string, message: string) => void
+// CreateLoggerOptions and LoggerSink are internal types
+```
+
+### Process logger
+
+```typescript
+function createProcessLogger(options: CreateProcessLoggerOptions): ProcessLogger
+
+type ProcessLogger = {
+  pid: string;
+  log: ProcessLogFn;
+};
+
+type ProcessLoggerContext = {
+  thread: string | null;
+  workflow: string | null;
+};
+
+type CreateProcessLoggerOptions = {
+  storageRoot: string | null;
+  context: ProcessLoggerContext;
+};
+
+type ProcessLogFn = (
+  tag: string,
+  msg: string,
+  context: Record<string, string> | null,
+) => void;
+```
+
+### Frontmatter markdown
+
+```typescript
+function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
+function validateFrontmatter(
+  parsed: ParsedFrontmatterMarkdown,
+  schema: Record<string, unknown>,
+): FrontmatterValidationError[]
+
+type ParsedFrontmatterMarkdown = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+type AgentFrontmatter = { /* standard agent frontmatter fields */ };
+type FrontmatterScope = string;
+type FrontmatterStatus = string;
+type FrontmatterValidationError = { path: string; message: string };
+```
+
+### Result helpers
+
+```typescript
+function ok<T>(value: T): Result<T, never>
+function err<E>(error: E): Result<never, E>
+
+type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
+```
+
+### Storage paths
+
+```typescript
+function getDefaultWorkflowStorageRoot(): string
+function getGlobalCasDir(storageRoot: string | undefined): string
+```
+
+### Refs and misc
+
+```typescript
+function normalizeRefsField(value: unknown): string[]
+function generateCliReference(): string
+function env(name: string, fallback: string): string
+```

 ## Usage

 ```typescript
-import { createLogger, getDefaultWorkflowStorageRoot, generateUlid } from "@uncaged/workflow-util";
+import {
+  createLogger,
+  generateUlid,
+  getDefaultWorkflowStorageRoot,
+  parseFrontmatterMarkdown,
+} from "@uncaged/workflow-util";

 const log = createLogger();
-log("4KNMR2PX", "example");
+log("4KNMR2PX", "Loading workflow...");
+
+const root = getDefaultWorkflowStorageRoot();
+const threadId = generateUlid(Date.now());
 ```
+
+## Internal Structure
+
+```
+src/
+├── index.ts
+├── base32.ts              Crockford Base32 encode/decode
+├── ulid.ts                  ULID generation
+├── logger.ts                Structured logger
+├── process-logger/          Process-level debug log files
+├── frontmatter-markdown/    Parse and validate agent frontmatter
+├── refs-field.ts            Normalize refs arrays on CAS nodes
+├── result.ts                ok / err helpers
+├── storage-root.ts          Default ~/.uncaged/workflow paths
+├── env.ts                   Environment variable helper
+├── cli-reference.ts         Markdown CLI reference generator
+└── types.ts                 LogFn, Result, logger options
+```
+
+## Configuration
+
+`getDefaultWorkflowStorageRoot()` resolves to `~/.uncaged/workflow` unless overridden by environment (see `storage-root.ts`).
Author	SHA1	Message	Date
xingyue	6481fc0cc5	refactor(cli): reduce cognitive complexity in thread.ts Extract helper functions (resolveThreadId, getThreadHead, listThreadSteps, displayStepDetails, displayThreadRead) to reduce nesting and improve readability. Also adds test coverage for the refactored functions. Fixes #446	2026-05-23 23:47:54 +08:00
xiaoju	3190e06ebe	docs: add sync-readme rule for consistent README updates 小橘 🍊（NEKO Team）	2026-05-23 15:09:25 +00:00
xiaomo	f8ae2fe25b	Merge pull request 'docs: sync all README.md files with current codebase' (#451 ) from docs/sync-readme into main	2026-05-23 15:03:56 +00:00
xiaoju	ffc31a8c19	docs: sync all README.md files with current codebase - Root README: add all 9 packages to table, update architecture diagram, refresh CLI reference from uwf --help - New READMEs for 8 packages (cli-workflow, workflow-protocol, workflow-moderator, workflow-agent-kit, workflow-agent-hermes, workflow-agent-builtin, workflow-agent-claude-code, workflow-dashboard) - Updated workflow-util README to match current exports - All API sections verified against src/index.ts exports 小橘 🍊（NEKO Team）	2026-05-23 15:00:05 +00:00
xingyue	48a274685b	fix(builtin): nudge budget + deadline warning - Nudge turns don't consume turn budget (up to MAX_NUDGES=3), prevents wasting agent work capacity on bookkeeping - Inject deadline warning when 3 turns remain, telling agent to wrap up - Agent can use status:failed to gracefully exit if it can't finish	2026-05-23 22:58:09 +08:00
xingyue	5b68359dfc	fix #447 : extract shouldNudge and export executeTurnTools from loop.ts, add tests	2026-05-23 22:45:09 +08:00
xingyue	c2ddfb8558	fix(builtin): deadline warning + graceful exit on turn limit - Inject user message when 3 turns remain, telling agent to wrap up - Prompt tells agent to use status:failed if it can't finish in time - Prevents wasting all turns without producing any frontmatter output - Remove stale test file from dogfood agent run	2026-05-23 22:44:42 +08:00
xingyue	603018caf2	fix(builtin): force-strip tool_calls when noTools is set copilot-api returns tool_calls even when tools field is omitted from the request (infers from message history). Now the loop explicitly nullifies tool_calls when noTools=true.	2026-05-23 22:35:20 +08:00
xiaomo	aff0ee6fea	Merge pull request 'fix(thread-read): remove ### Output section and deduplicate ### Prompt globally' (#442 ) from fix/440-thread-read-prompt-dedup into main	2026-05-23 14:15:40 +00:00
xiaomo	d37fa1393a	Merge pull request 'fix: preserve primary detail hash across frontmatter retries' (#443 ) from fix/439-detail-merge-and-acp into main	2026-05-23 14:14:53 +00:00
xiaoju	759c784267	fix: preserve primary detail hash across frontmatter retries When the agent's first run output fails frontmatter extraction, the retry loop (via options.continue) would replace agentResult entirely, causing the 1-turn continuation detail to overwrite the original multi-turn detail containing all tool-call history. Now we capture primaryDetailHash from the first run and always use it for the persisted StepNode, regardless of how many retries occur. Fixes #439	2026-05-23 14:02:51 +00:00
xingyue	52ffc7dcc1	fix(thread-read): remove ### Output section and deduplicate ### Prompt globally	2026-05-23 22:01:24 +08:00
xingyue	ac55a3e3d9	fix(builtin): nudge LLM when it stops tools without frontmatter LLM sometimes emits plain text (e.g. 'Now I'll write the tests...') without calling tools, which the loop treated as final output. Now the loop detects this and injects a user message nudging the LLM to either continue using tools or output frontmatter with ---.	2026-05-23 21:49:07 +08:00
xingyue	edb979baa9	fix(builtin): disable tools during continue/retry to force frontmatter output Agent was using all continue turns to keep calling tools instead of outputting the required frontmatter. Now continue runs with noTools=true, forcing LLM to emit text-only response. Also supports null tools in chatCompletionWithTools to omit tools from the API request entirely.	2026-05-23 21:40:30 +08:00
xingyue	3d1850ddbe	fix(builtin): tell agent not to use uwf CLI to discover its task Agent was wasting all 30 turns using uwf/tea CLI to explore threads instead of reading the task from its own user message.	2026-05-23 21:30:59 +08:00
xingyue	3c1f4a6dfa	fix(builtin): include cwd in system prompt Agent was wasting turns exploring the filesystem because it didn't know its working directory. Now the system prompt includes: 'Your working directory is: /path/to/cwd'	2026-05-23 21:27:24 +08:00
xiaomo	f07a6daa30	Merge pull request 'fix(builtin): session lifecycle + frontmatter preamble stripping' (#441 ) from fix/builtin-session-lifecycle into main	2026-05-23 13:20:04 +00:00
xingyue	0eeb4a8ed8	fix(builtin): strip preamble before frontmatter + stronger prompt - Add stripPreamble() to handle LLM output with text before --- - Strengthen system prompt: CRITICAL instruction for --- at position 0 - Fixes frontmatter parsing failures on first output turn	2026-05-23 20:37:14 +08:00
xingyue	a3fac708b6	fix(builtin-agent): don't delete session jsonl until process exits Previously runBuiltinWithMessages deleted the session jsonl after each run/continue call. This meant the createAgent retry mechanism (which calls continue on frontmatter validation failure) would lose all previous turn data — each continue started with an empty jsonl. Now the session jsonl accumulates across run + continue calls, so the final storeBuiltinDetail captures all turns. The jsonl file is left behind for debugging; it's small and can be cleaned up on next startup. Also add a workflow hint to the system prompt reminding the LLM to use tools before outputting frontmatter, preventing premature text-only responses on the first turn.	2026-05-23 20:32:38 +08:00
xiaomo	52879c0028	Merge pull request 'feat(cli-workflow): implement multi-strategy workflow resolution' (#438 ) from fix/428-multi-strategy-workflow-resolution into main	2026-05-23 11:12:56 +00:00
xiaoju	8720eb19af	feat(cli-workflow): implement multi-strategy workflow resolution for issue #428 - Add 4-strategy resolution priority: CAS hash → file path → local discovery → global registry - Add helper functions: isFilePath, workflowFileExists, findWorkflowInDir, findWorkflowInParents - Refactor resolveWorkflowCasRef to support direct hash, explicit paths, and parent traversal - Add comprehensive test suite with 24 tests covering all strategies and edge cases - Support .workflow/ and .workflows/ directories with .yaml/.yml extensions - All 60 tests pass across 5 test files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-05-23 11:11:37 +00:00
xiaomo	9e4527bb89	Merge pull request 'fix(cli): disable YAML anchor/alias in output' (#437 ) from fix/yaml-no-alias into main	2026-05-23 11:09:11 +00:00
xingyue	5209cfa7ac	fix(cli): disable YAML anchor/alias + fix biome errors in setup.ts - Disable aliasDuplicateObjects in YAML stringify to prevent &a1/*a1 anchors when multiple steps have identical output - Fix unused discoverAgents function (prefixed with _) and format issue in setup.ts	2026-05-23 19:07:36 +08:00
xiaoju	155b879d29	chore(workflow): developer must rebase main when bounced back Prevents duplicate lint fixes when main already has the fixes. 小橘 🍊（NEKO Team）	2026-05-23 10:57:44 +00:00
xiaomo	c1f04929f4	Merge pull request 'feat(builtin-agent): persist ReAct loop turns as session JSONL' (#434 ) from feat/turn-jsonl-session into main	2026-05-23 10:48:49 +00:00
xiaoju	211f38bc8d	fix(claude-code): include edge prompt in agent prompt as Current Instruction buildClaudeCodePrompt was dropping ctx.edgePrompt entirely — the graph transition instruction (e.g. 'Implement the plan') never reached the agent. Now appended as '## Current Instruction' at the end of the prompt.	2026-05-23 09:46:17 +00:00