fix(workflow): add --repo flag to tea pr create in worktree dirs

Fixes #474

.workflows/solve-issue.yaml

@@ -38,19 +38,26 @@ roles:
     capabilities:
       - coding
     procedure: |
-      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 and rebase onto latest main:
-           `git checkout main && git pull && git checkout <branch> && git rebase main`
+      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+
+      Before starting any work, set up an isolated worktree:
+      1. `cd ~/repos/workflow && git fetch origin` to get latest refs
+      2. First time (no existing branch):
+         - `git worktree add ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
+         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> && bun install`
+      3. If bounced back from reviewer or tester (branch already exists):
+         - The worktree should already exist at `~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
+         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
+         - `git fetch origin && git rebase origin/main`
+      4. ALL subsequent work must happen inside the worktree directory.
 
       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)
-      4. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
-      5. Write tests first based on the spec
-      6. Implement the code to make tests pass
-      7. Ensure `bun run build` passes with no errors
-      8. Run `bun test` to verify all tests pass
+      5. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
+      6. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
+      7. Write tests first based on the spec
+      8. Implement the code to make tests pass
+      9. Ensure `bun run build` passes with no errors
+      10. Run `bun test` to verify all tests pass
     output: "List all files changed and provide a summary. Frontmatter must include: status (done or failed)."
     frontmatter:
       type: object
@@ -66,6 +73,8 @@ roles:
       - code-review
       - static-analysis
     procedure: |
+      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+
       Before reviewing, verify the git branch:
       1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
       2. If the branch doesn't correspond to the issue, flag it in your output and reject
@@ -99,6 +108,8 @@ roles:
     capabilities:
       - testing
     procedure: |
+      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+
       1. Run `bun test` for automated test verification
       2. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
       3. Verify each scenario in the spec is covered and passing
@@ -119,13 +130,21 @@ roles:
     goal: "You are a committer agent. You create a clean commit and push a PR linking the original issue."
     capabilities: []
     procedure: |
+      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)
+
       Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
       1. Stage all changes: `git add -A`
       2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
       3. Push the branch: `git push -u origin <branch-name>`
          - If push hook fails: capture the error log in your output, mark hook_failed
-      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
+      4. On push success: create a PR via `tea pr create --repo uncaged/workflow --title "..." --description "..."`
+         - The `--repo` flag is required to work in worktree directories (fixes #474 "path segment [0] is empty" error)
+         - If working on a different repo, extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
          - PR description must follow the project template: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+         - On tea failure: capture stderr/stdout, log the error clearly, include PR details (title, description, branch) for manual creation, and mark success=false
+      5. After PR creation, clean up the worktree:
+         - `cd ~/repos/workflow`
+         - `git worktree remove ~/repos/workflow-worktrees/fix/<issue-number>-<slug>`
     output: "Include PR URL on success or error log on failure. Frontmatter must include: success (true or false)."
     frontmatter:
       type: object

examples/solve-issue.yaml

@@ -44,7 +44,8 @@ roles:
       2. cd to the repoPath before making any changes.
       3. Create a feature branch from the default branch.
       4. Implement the plan — write code, tests, and ensure existing tests pass.
-      5. Commit your changes with a descriptive message referencing the issue.
+      5. Run the project's lint/check command (e.g. `bun run check`, `npm run lint`) and fix ALL errors before proceeding. Build and lint must pass cleanly.
+      6. Commit your changes with a descriptive message referencing the issue.
     output: "List all files changed and provide a summary of the implementation."
     frontmatter:
       type: object
@@ -62,7 +63,10 @@ roles:
     capabilities:
       - code-review
       - static-analysis
-    procedure: "Review the implementation against the plan. Check for bugs, edge cases, and style."
+    procedure: |
+      1. Run hard checks first — build (`bun run build` or equivalent) and lint (`bunx biome check .` or equivalent) MUST pass with zero errors. If they fail, reject immediately.
+      2. Then review code quality: correctness, edge cases, naming, project conventions (CLAUDE.md), and test coverage.
+      3. Only reject for hard check failures or genuine correctness/security issues. Style suggestions alone should not block approval.
     output: "Approve or reject with detailed comments explaining your decision."
     frontmatter:
       type: object

legacy-packages/workflow-execute/src/engine/engine.ts

@@ -531,13 +531,25 @@ export async function executeThread(
       timestamp: nowMs,
       parentState: options.parentStateHash,
     },
-    steps: input.steps.map((out, i) => ({
-      role: out.role,
-      contentHash: out.contentHash,
-      meta: out.meta,
-      refs: out.refs,
-      timestamp: replayTs?.[i] ?? prefilled?.[i]?.timestamp ?? nowMs + i,
-    })),
+    steps: await Promise.all(
+      input.steps.map(async (out, i) => {
+        // Resolve content for the last step (most relevant for the next agent).
+        // Earlier steps only carry meta summaries to avoid bloating the prompt.
+        const isLast = i === input.steps.length - 1;
+        let content: string | null = null;
+        if (isLast) {
+          content = await getContentMerklePayload(io.cas, out.contentHash);
+        }
+        return {
+          role: out.role,
+          contentHash: out.contentHash,
+          content,
+          meta: out.meta,
+          refs: out.refs,
+          timestamp: replayTs?.[i] ?? prefilled?.[i]?.timestamp ?? nowMs + i,
+        };
+      }),
+    ),
   };
 
   const runtime: WorkflowRuntime = {

legacy-packages/workflow-protocol/src/types.ts

@@ -71,6 +71,7 @@ export type RoleStep<M extends RoleMeta> = {
     role: K;
     meta: M[K];
     contentHash: string;
+    content: string | null;
     refs: string[];
     timestamp: number;
   };

legacy-packages/workflow-runtime/src/build-context.ts

@@ -71,7 +71,8 @@ async function buildRoleStepsFromStates<M extends RoleMeta>(
   cas: CasStore,
 ): Promise<RoleStep<M>[]> {
   const steps: RoleStep<M>[] = [];
-  for (const st of chronologicalStates) {
+  for (let idx = 0; idx < chronologicalStates.length; idx++) {
+    const st = chronologicalStates[idx];
     if (st.payload.role === END) {
       continue;
     }
@@ -79,10 +80,13 @@ async function buildRoleStepsFromStates<M extends RoleMeta>(
     if (contentParsed === null || contentParsed.kind !== "content") {
       throw new Error(`buildThreadContext: expected content node at ${st.payload.content}`);
     }
+    // Resolve full text content for the last step only
+    const isLast = idx === chronologicalStates.length - 1;
     steps.push({
       role: st.payload.role,
       meta: st.payload.meta,
       contentHash: st.payload.content,
+      content: isLast ? contentParsed.node.payload : null,
       refs: [...contentParsed.node.refs],
       timestamp: st.payload.timestamp,
     } as RoleStep<M>);

legacy-packages/workflow-runtime/src/create-workflow.ts

@@ -88,6 +88,7 @@ async function advanceOneRound<M extends RoleMeta>(
   const step = {
     role: next,
     contentHash,
+    content: contentPayload,
     meta,
     refs,
     timestamp: Date.now(),

legacy-packages/workflow-util-agent/__tests__/build-agent-prompt.test.ts

@@ -30,7 +30,7 @@ describe("buildAgentPrompt", () => {
     expect(text).not.toContain("## Tools");
   });
 
-  test("single step shows hash and meta, and includes tools", async () => {
+  test("single step shows meta and content, and includes tools", async () => {
     const onlyHash = "01HASHSINGLESTEP0000000001";
     const ctx: AgentContext = {
       start: startTask("user task"),
@@ -42,6 +42,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "coder",
           contentHash: onlyHash,
+          content: "Here is my implementation of the feature.",
           meta: { files: ["a.ts"] },
           refs: [onlyHash],
           timestamp: 2,
@@ -52,13 +53,39 @@ describe("buildAgentPrompt", () => {
     expect(text).toContain("## Task");
     expect(text).toContain("user task");
     expect(text).toContain("## Step: coder");
-    expect(text).toContain(`ContentHash: ${onlyHash}`);
     expect(text).toContain('Meta: {"files":["a.ts"]}');
+    expect(text).toContain("<output>");
+    expect(text).toContain("Here is my implementation of the feature.");
+    expect(text).toContain("</output>");
     expect(text).toContain("## Tools");
     expect(text).toContain("uncaged-workflow thread 01TEST000000000000000000TR");
   });
 
-  test("two or more steps: previous steps are meta-only; latest step includes hash", async () => {
+  test("single step with null content omits output tag", async () => {
+    const onlyHash = "01HASHSINGLESTEP0000000001";
+    const ctx: AgentContext = {
+      start: startTask("user task"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: "coder", systemPrompt: "Be helpful." },
+      steps: [
+        {
+          role: "coder",
+          contentHash: onlyHash,
+          content: null,
+          meta: { files: ["a.ts"] },
+          refs: [onlyHash],
+          timestamp: 2,
+        },
+      ],
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).not.toContain("<output>");
+    expect(text).toContain('Meta: {"files":["a.ts"]}');
+  });
+
+  test("two or more steps: previous steps are meta-only; latest step includes content", async () => {
     const plannerHash = "01HASHPLANNER0000000000001";
     const coderHash = "01HASHCODER0000000000000001";
     const ctx: AgentContext = {
@@ -71,6 +98,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "planner",
           contentHash: plannerHash,
+          content: null,
           meta: { plan: "short" },
           refs: [plannerHash],
           timestamp: 2,
@@ -78,6 +106,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "coder",
           contentHash: coderHash,
+          content: "I reviewed the code and found 4 lint issues:\n1. Missing semicolon on line 42\n2. Unused import on line 3",
           meta: { done: true },
           refs: [coderHash],
           timestamp: 3,
@@ -90,10 +119,11 @@ describe("buildAgentPrompt", () => {
     expect(text).toContain("### Step 1: planner");
     expect(text).toContain('Summary: {"plan":"short"}');
     expect(text).toContain("## Latest Step: coder");
-    expect(text).toContain(`ContentHash: ${coderHash}`);
     expect(text).toContain('Meta: {"done":true}');
+    expect(text).toContain("<output>");
+    expect(text).toContain("I reviewed the code and found 4 lint issues:");
+    expect(text).toContain("</output>");
     expect(text).toContain("## Tools");
-    expect(text).toContain("uncaged-workflow thread 01TEST000000000000000000TR");
   });
 
   test("parentState null omits Parent Context section", async () => {
@@ -125,7 +155,7 @@ describe("buildAgentPrompt", () => {
     expect(text).toContain(`uncaged-workflow cas get ${parentHash}`);
   });
 
-  test("middle steps show meta summary only and latest shows hash", async () => {
+  test("middle steps show meta summary only and latest shows content", async () => {
     const ha = "01HASHA00000000000000000001";
     const hb = "01HASHB00000000000000000001";
     const hc = "01HASHC00000000000000000001";
@@ -139,6 +169,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "a",
           contentHash: ha,
+          content: null,
           meta: { n: 1 },
           refs: [ha],
           timestamp: 2,
@@ -146,6 +177,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "b",
           contentHash: hb,
+          content: null,
           meta: { n: 2 },
           refs: [hb],
           timestamp: 3,
@@ -153,6 +185,7 @@ describe("buildAgentPrompt", () => {
         {
           role: "c",
           contentHash: hc,
+          content: "Final output from role c",
           meta: { n: 3 },
           refs: [hc],
           timestamp: 4,
@@ -162,7 +195,35 @@ describe("buildAgentPrompt", () => {
     const text = await buildAgentPrompt(ctx);
     expect(text).toContain('Summary: {"n":1}');
     expect(text).toContain('Summary: {"n":2}');
-    expect(text).toContain(`ContentHash: ${hc}`);
     expect(text).toContain("## Latest Step: c");
+    expect(text).toContain("<output>");
+    expect(text).toContain("Final output from role c");
+    expect(text).toContain("</output>");
+  });
+
+  test("content is truncated when exceeding quota", async () => {
+    const longContent = "x".repeat(20_000);
+    const hash = "01HASHLONG000000000000000001";
+    const ctx: AgentContext = {
+      start: startTask("task"),
+      depth: 0,
+      bundleHash: "TESTHASH00001",
+      threadId: "01TEST000000000000000000TR",
+      currentRole: { name: "r", systemPrompt: "S" },
+      steps: [
+        {
+          role: "r",
+          contentHash: hash,
+          content: longContent,
+          meta: {},
+          refs: [],
+          timestamp: 2,
+        },
+      ],
+    };
+    const text = await buildAgentPrompt(ctx);
+    expect(text).toContain("<output>");
+    expect(text).toContain("... (truncated)");
+    expect(text.length).toBeLessThan(20_000);
   });
 });

packages/cli-workflow/README.md

@@ -6,6 +6,18 @@
 
 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`).
 
+### Four-Layer Architecture
+
+```
+workflow → thread → step → turn
+模板定义   执行实例   单步结果   agent内部交互
+```
+
+- **Workflow** (layer 1): YAML template with roles and routing graph
+- **Thread** (layer 2): Single workflow execution instance
+- **Step** (layer 3): One moderator→agent→extract cycle
+- **Turn** (layer 4): Agent-internal interactions (use `step show` or CAS to inspect)
+
 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`
@@ -30,34 +42,51 @@ bun link packages/cli-workflow
 -h, --help             Show help
 ```
 
-### Thread
+### Thread (Layer 2: Execution Instances)
 
 | 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 exec <thread-id> [--agent <cmd>] [-c <count>] [--background]` | 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 list [--status <idle\|running\|completed>]` | List threads, optionally filtered by status |
 | `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 |
+| `uwf thread stop <thread-id>` | Stop background execution (keep thread active) |
+| `uwf thread cancel <thread-id>` | Cancel thread (stop + archive to history) |
 
 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 exec 01ARZ3NDEKTSV4RRFFQ69G5FAV
+uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin
+uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV --background
+uwf thread list --status running
 uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000
+uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV
 ```
 
-### Workflow
+### Step (Layer 3: Single Cycle Results)
 
 | Command | Description |
 |---------|-------------|
-| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
+| `uwf step list <thread-id>` | List all steps in a thread chronologically |
+| `uwf step show <step-hash>` | Show step metadata and frontmatter |
+| `uwf step fork <step-hash>` | Fork a thread from a specific step |
+
+Examples:
+
+```bash
+uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV
+uwf step show 32GCDE899RRQ3
+uwf step fork 32GCDE899RRQ3
+```
+
+### Workflow (Layer 1: Templates)
+
+| Command | Description |
+|---------|-------------|
+| `uwf workflow add <file.yaml>` | Register a workflow from YAML |
 | `uwf workflow show <name-or-hash>` | Show workflow definition |
 | `uwf workflow list` | List registered workflows |
 
@@ -99,6 +128,52 @@ Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`.
 | `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 |
 
+## Migration Guide
+
+### Breaking Changes (v0.x → v1.x)
+
+The CLI was reorganized to clarify the four-layer architecture. **No backward compatibility** — old commands have been removed.
+
+#### Renamed Commands
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `workflow put` | `workflow add` | More intuitive verb |
+| `thread step` | `thread exec` | Eliminates ambiguity with "step" noun |
+| `thread list --all` | `thread list --status completed` | Unified status filtering |
+
+#### Removed Commands (Merged)
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `thread running` | `thread list --status running` | Merged into unified list |
+
+#### Removed Commands (Split)
+
+| Old Command | New Commands | Notes |
+|------------|-------------|-------|
+| `thread kill` | `thread stop` or `thread cancel` | `stop` keeps thread active, `cancel` archives it |
+
+#### Moved Commands
+
+| Old Command | New Command | Notes |
+|------------|-------------|-------|
+| `thread steps` | `step list` | Moved to step layer |
+| `thread step-details` | `step show` | Moved to step layer |
+| `thread fork` | `step fork` | Moved to step layer (forks are step-based) |
+
+#### Deprecation Errors
+
+Old commands now show helpful error messages:
+
+```bash
+$ uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV
+Error: Command 'thread step' has been removed.
+Use 'thread exec' instead.
+
+For more information, see: uwf help thread exec
+```
+
 ## Internal Structure
 
 ```
@@ -109,8 +184,9 @@ src/
 ├── 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)
+    ├── thread.ts       Thread lifecycle and exec
+    ├── step.ts         Step operations (list/show/read/fork)
+    ├── workflow.ts     Workflow registry (add/show/list)
     ├── cas.ts          CAS inspection and schema ops
     ├── setup.ts        Interactive/non-interactive setup
     ├── skill.ts        Built-in skill references

packages/cli-workflow/src/__tests__/resolve-head-hash.test.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { resolveHeadHash } from "../commands/shared.js";
+import { appendThreadHistory, saveThreadsIndex } from "../store.js";
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-resolve-head-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("resolveHeadHash", () => {
+  test("returns head hash from threads.yaml for active thread", async () => {
+    const threadId = "01JTEST0000000000000000001" as ThreadId;
+    const headHash = "active_hash_123" as CasRef;
+
+    await saveThreadsIndex(tmpDir, { [threadId]: headHash });
+
+    const result = await resolveHeadHash(tmpDir, threadId);
+
+    expect(result).toBe(headHash);
+  });
+
+  test("falls back to history.jsonl when thread not in threads.yaml", async () => {
+    const threadId = "01JTEST0000000000000000002" as ThreadId;
+    const headHash = "completed_hash_456" as CasRef;
+    const workflowHash = "workflow_hash_789" as CasRef;
+
+    // No entry in threads.yaml, only in history.jsonl
+    await saveThreadsIndex(tmpDir, {});
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: headHash,
+      completedAt: Date.now(),
+    });
+
+    const result = await resolveHeadHash(tmpDir, threadId);
+
+    expect(result).toBe(headHash);
+  });
+
+  // Note: Testing the error case requires CLI-level testing because resolveHeadHash
+  // calls fail() which does process.exit(1), terminating the test runner.
+  // The error behavior is tested in integration tests below via CLI invocation.
+
+  test("prioritizes active thread over history when thread exists in both", async () => {
+    const threadId = "01JTEST0000000000000000004" as ThreadId;
+    const activeHash = "active_hash_v2" as CasRef;
+    const historicalHash = "historical_hash_v1" as CasRef;
+    const workflowHash = "workflow_hash_xyz" as CasRef;
+
+    // Thread exists in both locations (should not happen normally, but test the precedence)
+    await saveThreadsIndex(tmpDir, { [threadId]: activeHash });
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: historicalHash,
+      completedAt: Date.now(),
+    });
+
+    const result = await resolveHeadHash(tmpDir, threadId);
+
+    // Should return the active head, not the historical one
+    expect(result).toBe(activeHash);
+  });
+
+  test("finds thread from multiple history entries", async () => {
+    const threadId1 = "01JTEST0000000000000000005" as ThreadId;
+    const threadId2 = "01JTEST0000000000000000006" as ThreadId;
+    const threadId3 = "01JTEST0000000000000000007" as ThreadId;
+    const hash1 = "hash_thread1" as CasRef;
+    const hash2 = "hash_thread2" as CasRef;
+    const hash3 = "hash_thread3" as CasRef;
+    const workflowHash = "workflow_hash_abc" as CasRef;
+
+    await saveThreadsIndex(tmpDir, {});
+    await appendThreadHistory(tmpDir, {
+      thread: threadId1,
+      workflow: workflowHash,
+      head: hash1,
+      completedAt: Date.now() - 2000,
+    });
+    await appendThreadHistory(tmpDir, {
+      thread: threadId2,
+      workflow: workflowHash,
+      head: hash2,
+      completedAt: Date.now() - 1000,
+    });
+    await appendThreadHistory(tmpDir, {
+      thread: threadId3,
+      workflow: workflowHash,
+      head: hash3,
+      completedAt: Date.now(),
+    });
+
+    const result = await resolveHeadHash(tmpDir, threadId2);
+
+    expect(result).toBe(hash2);
+  });
+});

packages/cli-workflow/src/__tests__/solve-issue-tea-worktree.test.ts

@@ -0,0 +1,98 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { WorkflowPayload } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { parse } from "yaml";
+
+/**
+ * Test: Issue #474 - tea pr create fails in git worktree directories
+ *
+ * This test verifies that the solve-issue workflow's committer role
+ * includes the --repo flag when running tea pr create, which fixes
+ * the "path segment [0] is empty" error in worktree directories.
+ */
+
+describe("solve-issue workflow: tea pr create worktree fix", () => {
+  // Navigate up from packages/cli-workflow to repo root
+  const workflowPath = join(process.cwd(), "..", "..", ".workflows", "solve-issue.yaml");
+
+  test("committer procedure should include --repo flag in tea pr create command", async () => {
+    const yamlContent = await readFile(workflowPath, "utf-8");
+    const workflow = parse(yamlContent) as WorkflowPayload;
+
+    expect(workflow.roles.committer).toBeDefined();
+    const committerProcedure = workflow.roles.committer?.procedure;
+    expect(committerProcedure).toBeDefined();
+
+    // Verify the procedure includes tea pr create with --repo flag
+    expect(committerProcedure).toContain("tea pr create");
+    expect(committerProcedure).toContain("--repo");
+
+    // Verify the --repo flag appears before or together with tea pr create
+    // This ensures the command is: tea pr create --repo <owner/repo> ...
+    const teaPrCreateMatch = committerProcedure?.match(/tea pr create[^\n]*/);
+    expect(teaPrCreateMatch).not.toBeNull();
+
+    if (teaPrCreateMatch) {
+      const teaCommandLine = teaPrCreateMatch[0];
+      expect(teaCommandLine).toContain("--repo");
+    }
+  });
+
+  test("committer procedure should mention repo extraction from git remote", async () => {
+    const yamlContent = await readFile(workflowPath, "utf-8");
+    const workflow = parse(yamlContent) as WorkflowPayload;
+
+    const committerProcedure = workflow.roles.committer?.procedure;
+    expect(committerProcedure).toBeDefined();
+
+    // Verify the procedure mentions extracting repo info from git remote
+    // This ensures fallback logic is documented
+    expect(committerProcedure).toMatch(/git remote/i);
+  });
+
+  test("committer procedure should include error handling for tea failures", async () => {
+    const yamlContent = await readFile(workflowPath, "utf-8");
+    const workflow = parse(yamlContent) as WorkflowPayload;
+
+    const committerProcedure = workflow.roles.committer?.procedure;
+    expect(committerProcedure).toBeDefined();
+
+    // Verify the procedure includes error handling guidance
+    // This ensures we capture failures and provide actionable output
+    expect(committerProcedure).toMatch(/error|fail/i);
+  });
+
+  test("workflow should be parseable as valid WorkflowPayload", async () => {
+    const yamlContent = await readFile(workflowPath, "utf-8");
+    const workflow = parse(yamlContent) as WorkflowPayload;
+
+    // Basic structure validation
+    expect(workflow.name).toBe("solve-issue");
+    expect(workflow.roles).toBeDefined();
+    expect(workflow.conditions).toBeDefined();
+    expect(workflow.graph).toBeDefined();
+
+    // Verify committer role exists with required fields
+    expect(workflow.roles.committer).toBeDefined();
+    expect(workflow.roles.committer?.description).toBeDefined();
+    expect(workflow.roles.committer?.goal).toBeDefined();
+    expect(workflow.roles.committer?.procedure).toBeDefined();
+    expect(workflow.roles.committer?.output).toBeDefined();
+    expect(workflow.roles.committer?.frontmatter).toBeDefined();
+  });
+
+  test("committer frontmatter schema should require success field", async () => {
+    const yamlContent = await readFile(workflowPath, "utf-8");
+    // Parse as any to access the raw YAML structure (frontmatter is inline JSON Schema in YAML)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const workflow = parse(yamlContent) as any;
+
+    const frontmatter = workflow.roles.committer?.frontmatter;
+    expect(frontmatter).toBeDefined();
+    expect(frontmatter?.type).toBe("object");
+    expect(frontmatter?.properties?.success).toBeDefined();
+    expect(frontmatter?.properties?.success?.type).toBe("boolean");
+    expect(frontmatter?.required).toContain("success");
+  });
+});

packages/cli-workflow/src/__tests__/thread-list-filters.test.ts

@@ -0,0 +1,550 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { extractUlidTimestamp, generateUlid } from "@uncaged/workflow-util";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createMarker, deleteMarker } from "../background/index.js";
+import { cmdThreadList } from "../commands/thread.js";
+import { parseTimeInput } from "../commands/thread-time-parser.js";
+import type { UwfStore } from "../store.js";
+import { appendThreadHistory, createUwfStore, saveThreadsIndex } from "../store.js";
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
+  const casDir = join(storageRoot, "cas");
+  await mkdir(casDir, { recursive: true });
+  return createUwfStore(storageRoot);
+}
+
+async function createTestWorkflow(uwf: UwfStore): Promise<CasRef> {
+  const workflowPayload = {
+    name: "test-workflow",
+    roles: {
+      role1: {
+        goal: "test goal",
+        outputSchema: { type: "object" as const, properties: {} },
+      },
+    },
+    graph: { start: "role1" },
+    conditions: {},
+  };
+  return await uwf.store.put(uwf.schemas.workflow, workflowPayload);
+}
+
+async function createTestThread(
+  uwf: UwfStore,
+  storageRoot: string,
+  workflowHash: CasRef,
+  timestamp: number,
+): Promise<ThreadId> {
+  const threadId = generateUlid(timestamp) as ThreadId;
+  const startPayload = {
+    workflow: workflowHash,
+    prompt: "test prompt",
+  };
+  const headHash = await uwf.store.put(uwf.schemas.startNode, startPayload);
+  const index = await import("../store.js").then((m) => m.loadThreadsIndex(storageRoot));
+  index[threadId] = headHash;
+  await saveThreadsIndex(storageRoot, index);
+  return threadId;
+}
+
+async function markThreadRunning(storageRoot: string, threadId: ThreadId, workflow: CasRef) {
+  await createMarker(storageRoot, {
+    thread: threadId,
+    workflow,
+    pid: process.pid, // Use current process PID so isPidAlive returns true
+    startedAt: Date.now(),
+  });
+}
+
+async function completeThread(
+  storageRoot: string,
+  threadId: ThreadId,
+  workflowHash: CasRef,
+  headHash: CasRef,
+) {
+  const index = await import("../store.js").then((m) => m.loadThreadsIndex(storageRoot));
+  delete index[threadId];
+  await saveThreadsIndex(storageRoot, index);
+  await appendThreadHistory(storageRoot, {
+    thread: threadId,
+    workflow: workflowHash,
+    head: headHash,
+    completedAt: Date.now(),
+  });
+}
+
+// ── test setup ────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "thread-list-filters-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ── status filter tests ───────────────────────────────────────────────────────
+
+describe("cmdThreadList status filter", () => {
+  test("should return idle and running threads when status=active", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    const thread3Head = index[thread3];
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, ["idle", "running"], null, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2].sort());
+
+    // Clean up marker after test
+    await deleteMarker(tmpDir, thread2);
+  });
+
+  test("should support comma-separated status values", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    const thread3Head = index[thread3];
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, ["idle", "completed"], null, null, null, null);
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+
+    // thread2 is running (not idle), so should not be included
+    // Expected: thread1 (idle) and thread3 (completed)
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread3].sort());
+  });
+
+  test("should support single status filter (backward compat)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const _thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    const thread3Head = index[thread3];
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, ["completed"], null, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(thread3);
+    expect(result[0]?.status).toBe("completed");
+  });
+
+  test("should return all threads when no status filter provided", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    const thread3Head = index[thread3];
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+
+    expect(result).toHaveLength(3);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2, thread3].sort());
+  });
+});
+
+// ── time range filtering tests ────────────────────────────────────────────────
+
+describe("cmdThreadList time filters", () => {
+  test("should filter threads created after given timestamp", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+
+    const _threadA = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const threadB = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const threadC = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+
+    // Use a timestamp slightly before ts2 to include threadB
+    const afterMs = Date.UTC(2026, 4, 20, 12, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, afterMs, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([threadB, threadC].sort());
+  });
+
+  test("should filter threads created before given timestamp", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+
+    const threadA = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const threadB = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const _threadC = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+
+    const beforeMs = Date.UTC(2026, 4, 22, 0, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, null, beforeMs, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([threadA, threadB].sort());
+  });
+
+  test("should support both after and before filters (time range)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+
+    const _threadA = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const threadB = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const _threadC = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+
+    const afterMs = Date.UTC(2026, 4, 20, 12, 0, 0);
+    const beforeMs = Date.UTC(2026, 4, 22, 0, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, afterMs, beforeMs, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(threadB);
+  });
+});
+
+// ── pagination tests ──────────────────────────────────────────────────────────
+
+describe("cmdThreadList pagination", () => {
+  test("should limit results with --take", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threads: ThreadId[] = [];
+    for (let i = 0; i < 10; i++) {
+      threads.push(await createTestThread(uwf, tmpDir, workflowHash, Date.now() - i * 1000));
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 5);
+
+    expect(result).toHaveLength(5);
+  });
+
+  test("should skip first N threads with --skip", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threads: ThreadId[] = [];
+    // Create threads in chronological order, but they'll be sorted newest first
+    for (let i = 0; i < 10; i++) {
+      threads.push(await createTestThread(uwf, tmpDir, workflowHash, Date.now() + i * 100));
+      // Small delay to ensure distinct timestamps
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 3, null);
+
+    expect(result).toHaveLength(7);
+    // The 3 newest threads should be skipped, so we should get the 7 oldest
+  });
+
+  test("should support skip + take for pagination", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threads: ThreadId[] = [];
+    for (let i = 0; i < 10; i++) {
+      threads.push(await createTestThread(uwf, tmpDir, workflowHash, Date.now() + i * 100));
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 5, 3);
+
+    expect(result).toHaveLength(3);
+    // Should skip first 5 (newest), then take 3
+  });
+
+  test("should handle take > available threads", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const _thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    const _thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const _thread3 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, null, 10);
+
+    expect(result).toHaveLength(3);
+  });
+
+  test("should return empty array when skip >= thread count", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 3000);
+    await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    const result = await cmdThreadList(tmpDir, null, null, null, 5, null);
+
+    expect(result).toHaveLength(0);
+  });
+});
+
+// ── combined filters tests ────────────────────────────────────────────────────
+
+describe("combined filters", () => {
+  test("should combine status and time range filters", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const ts1 = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ts2 = Date.UTC(2026, 4, 21, 0, 0, 0);
+    const ts3 = Date.UTC(2026, 4, 22, 0, 0, 0);
+    const ts4 = Date.UTC(2026, 4, 23, 0, 0, 0);
+
+    const _thread1 = await createTestThread(uwf, tmpDir, workflowHash, ts1);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, ts2);
+    const thread3 = await createTestThread(uwf, tmpDir, workflowHash, ts3);
+    const thread4 = await createTestThread(uwf, tmpDir, workflowHash, ts4);
+
+    await markThreadRunning(tmpDir, thread2, workflowHash);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    const thread3Head = index[thread3];
+    if (thread3Head === undefined) throw new Error("thread3 head not found");
+    await completeThread(tmpDir, thread3, workflowHash, thread3Head);
+
+    const afterMs = Date.UTC(2026, 4, 20, 12, 0, 0);
+    const result = await cmdThreadList(tmpDir, ["idle"], afterMs, null, null, null);
+
+    expect(result).toHaveLength(1);
+    expect(result[0]?.thread).toBe(thread4);
+    expect(result[0]?.status).toBe("idle");
+
+    // Clean up marker
+    await deleteMarker(tmpDir, thread2);
+  });
+
+  test("should combine status filter and pagination", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threads: ThreadId[] = [];
+    for (let i = 9; i >= 0; i--) {
+      const thread = await createTestThread(uwf, tmpDir, workflowHash, Date.now() + i * 1000);
+      threads.push(thread);
+      const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+      const headHash = index[thread];
+      if (headHash === undefined) throw new Error("head not found");
+      await completeThread(tmpDir, thread, workflowHash, headHash);
+    }
+
+    const result = await cmdThreadList(tmpDir, ["completed"], null, null, 3, 5);
+
+    expect(result).toHaveLength(5);
+    for (const r of result) {
+      expect(r.status).toBe("completed");
+    }
+  });
+
+  test("should combine time range and pagination", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const threads: ThreadId[] = [];
+    for (let i = 0; i < 20; i++) {
+      const ts = Date.UTC(2026, 4, 1 + i, 0, 0, 0);
+      threads.push(await createTestThread(uwf, tmpDir, workflowHash, ts));
+    }
+
+    const afterMs = Date.UTC(2026, 4, 10, 0, 0, 0);
+    const result = await cmdThreadList(tmpDir, null, afterMs, null, 2, 5);
+
+    expect(result).toHaveLength(5);
+    for (const r of result) {
+      const ts = extractUlidTimestamp(r.thread);
+      expect(ts).not.toBeNull();
+      if (ts !== null) {
+        expect(ts).toBeGreaterThan(afterMs);
+      }
+    }
+  });
+
+  async function setupMixedStatusThreads(
+    uwf: UwfStore,
+    workflowHash: string,
+    count: number,
+  ): Promise<ThreadId[]> {
+    const threads: ThreadId[] = [];
+    for (let i = 0; i < count; i++) {
+      const ts = Date.UTC(2026, 4, 10 + i, 0, 0, 0);
+      const thread = await createTestThread(uwf, tmpDir, workflowHash, ts);
+      threads.push(thread);
+
+      if (i % 2 === 0) {
+        const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+        const headHash = index[thread];
+        if (headHash === undefined) throw new Error("head not found");
+        await completeThread(tmpDir, thread, workflowHash, headHash);
+      } else {
+        await markThreadRunning(tmpDir, thread, workflowHash);
+      }
+    }
+    return threads;
+  }
+
+  async function cleanupRunningMarkers(threads: ThreadId[]): Promise<void> {
+    for (let i = 0; i < threads.length; i++) {
+      if (i % 2 !== 0) {
+        await deleteMarker(tmpDir, threads[i] as ThreadId);
+      }
+    }
+  }
+
+  test("should combine all filters (status + time + pagination)", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+    const threads = await setupMixedStatusThreads(uwf, workflowHash, 15);
+
+    const afterMs = Date.UTC(2026, 4, 14, 12, 0, 0);
+    const beforeMs = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const result = await cmdThreadList(tmpDir, ["idle", "running"], afterMs, beforeMs, 1, 3);
+
+    expect(result.length).toBeLessThanOrEqual(3);
+    for (const r of result) {
+      expect(["idle", "running"]).toContain(r.status);
+      const ts = extractUlidTimestamp(r.thread);
+      if (ts !== null) {
+        expect(ts).toBeGreaterThan(afterMs);
+        expect(ts).toBeLessThan(beforeMs);
+      }
+    }
+
+    await cleanupRunningMarkers(threads);
+  });
+});
+
+// ── edge cases tests ──────────────────────────────────────────────────────────
+
+describe("edge cases", () => {
+  test("should handle empty thread list", async () => {
+    await makeUwfStore(tmpDir);
+    const result = await cmdThreadList(tmpDir, null, null, null, null, null);
+    expect(result).toHaveLength(0);
+  });
+
+  test("should skip threads with invalid ULID when time filtering", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const workflowHash = await createTestWorkflow(uwf);
+
+    const thread1 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 2000);
+    const thread2 = await createTestThread(uwf, tmpDir, workflowHash, Date.now() - 1000);
+
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(tmpDir));
+    index["INVALID_ULID_FORMAT_HERE" as ThreadId] = "01J6HMVRNQKJV2";
+    await saveThreadsIndex(tmpDir, index);
+
+    const afterMs = Date.now() - 3000;
+    const result = await cmdThreadList(tmpDir, null, afterMs, null, null, null);
+
+    expect(result).toHaveLength(2);
+    expect(result.map((r) => r.thread).sort()).toEqual([thread1, thread2].sort());
+  });
+});
+
+// ── time parsing tests ────────────────────────────────────────────────────────
+
+describe("relative time parsing", () => {
+  test("should parse '7d' as 7 days ago", () => {
+    const nowMs = Date.UTC(2026, 4, 24, 12, 0, 0);
+    const result = parseTimeInput("7d", nowMs);
+    const expected = Date.UTC(2026, 4, 17, 12, 0, 0);
+    expect(result).toBe(expected);
+  });
+
+  test("should parse '24h' as 24 hours ago", () => {
+    const nowMs = Date.UTC(2026, 4, 24, 12, 0, 0);
+    const result = parseTimeInput("24h", nowMs);
+    const expected = Date.UTC(2026, 4, 23, 12, 0, 0);
+    expect(result).toBe(expected);
+  });
+
+  test("should parse '30m' as 30 minutes ago", () => {
+    const nowMs = Date.UTC(2026, 4, 24, 12, 30, 0);
+    const result = parseTimeInput("30m", nowMs);
+    const expected = Date.UTC(2026, 4, 24, 12, 0, 0);
+    expect(result).toBe(expected);
+  });
+
+  test("should parse '1d' as 1 day ago", () => {
+    const nowMs = Date.UTC(2026, 4, 24, 0, 0, 0);
+    const result = parseTimeInput("1d", nowMs);
+    const expected = Date.UTC(2026, 4, 23, 0, 0, 0);
+    expect(result).toBe(expected);
+  });
+});
+
+describe("ISO date parsing", () => {
+  test("should parse ISO date (YYYY-MM-DD)", () => {
+    const nowMs = Date.now();
+    const result = parseTimeInput("2026-05-20", nowMs);
+    const expected = Date.UTC(2026, 4, 20, 0, 0, 0);
+    expect(result).toBe(expected);
+  });
+
+  test("should parse ISO datetime (YYYY-MM-DDTHH:MM:SS)", () => {
+    const nowMs = Date.now();
+    const result = parseTimeInput("2026-05-20T14:30:00", nowMs);
+    const expected = Date.parse("2026-05-20T14:30:00");
+    expect(result).toBe(expected);
+  });
+
+  test("should parse ISO datetime with Z suffix", () => {
+    const nowMs = Date.now();
+    const result = parseTimeInput("2026-05-20T14:30:00Z", nowMs);
+    const expected = Date.UTC(2026, 4, 20, 14, 30, 0);
+    expect(result).toBe(expected);
+  });
+
+  test("should reject invalid date formats", () => {
+    const nowMs = Date.now();
+    expect(() => parseTimeInput("not-a-date", nowMs)).toThrow();
+    expect(() => parseTimeInput("2026-13-01", nowMs)).toThrow();
+    expect(() => parseTimeInput("invalid", nowMs)).toThrow();
+  });
+});

packages/cli-workflow/src/__tests__/thread-step-count.test.ts

@@ -22,48 +22,48 @@ function runCli(args: string[]): { stdout: string; stderr: string; exitCode: num
   }
 }
 
-describe("thread step --count CLI parsing", () => {
+describe("thread exec --count CLI parsing", () => {
   test("--help shows -c/--count option", () => {
-    const result = runCli(["thread", "step", "--help"]);
+    const result = runCli(["thread", "exec", "--help"]);
     expect(result.stdout).toContain("--count");
     expect(result.stdout).toContain("-c");
   });
 
   test("description says 'one or more steps'", () => {
-    const result = runCli(["thread", "step", "--help"]);
+    const result = runCli(["thread", "exec", "--help"]);
     expect(result.stdout).toContain("one or more steps");
   });
 });
 
-describe("cmdThreadStep count logic", () => {
+describe("cmdThreadExec count logic", () => {
   test("count=0 fails with validation error", () => {
-    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "0"]);
+    const result = runCli(["thread", "exec", "FAKE_THREAD_ID", "-c", "0"]);
     expect(result.exitCode).not.toBe(0);
     expect(result.stderr).toContain("positive integer");
   });
 
   test("negative count fails with validation error", () => {
-    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "-1"]);
+    const result = runCli(["thread", "exec", "FAKE_THREAD_ID", "-c", "-1"]);
     expect(result.exitCode).not.toBe(0);
     expect(result.stderr).toContain("positive integer");
   });
 
   test("non-integer count fails with validation error", () => {
-    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "1.5"]);
+    const result = runCli(["thread", "exec", "FAKE_THREAD_ID", "-c", "1.5"]);
     expect(result.exitCode).not.toBe(0);
     expect(result.stderr).toContain("positive integer");
   });
 
   test("count=1 is the default (no -c flag)", () => {
     // Without -c, it should attempt to run 1 step (failing on missing thread, not on count validation)
-    const result = runCli(["thread", "step", "FAKE_THREAD_ID"]);
+    const result = runCli(["thread", "exec", "FAKE_THREAD_ID"]);
     expect(result.exitCode).not.toBe(0);
     // Should NOT contain "positive integer" error — should fail on thread lookup instead
     expect(result.stderr).not.toContain("positive integer");
   });
 
   test("count=3 passes validation (fails on thread lookup)", () => {
-    const result = runCli(["thread", "step", "FAKE_THREAD_ID", "-c", "3"]);
+    const result = runCli(["thread", "exec", "FAKE_THREAD_ID", "-c", "3"]);
     expect(result.exitCode).not.toBe(0);
     // Should NOT contain "positive integer" error — should fail on thread/storage lookup
     expect(result.stderr).not.toContain("positive integer");

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

@@ -5,15 +5,15 @@ import { bootstrap, putSchema } from "@uncaged/json-cas";
 import { createFsStore } from "@uncaged/json-cas-fs";
 import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdStepList, cmdStepShow } from "../commands/step.js";
 import {
   cmdThreadRead,
-  cmdThreadStepDetails,
   extractLastAssistantContent,
   THREAD_READ_DEFAULT_QUOTA,
 } from "../commands/thread.js";
 import { registerUwfSchemas } from "../schemas.js";
 import type { UwfStore } from "../store.js";
-import { saveThreadsIndex } from "../store.js";
+import { appendThreadHistory, saveThreadsIndex } from "../store.js";
 
 // ── schemas used in tests ────────────────────────────────────────────────────
 
@@ -315,9 +315,9 @@ describe("cmdThreadRead <output> section", () => {
   });
 });
 
-// ── cmdThreadStepDetails ──────────────────────────────────────────────────────
+// ── cmdStepShow ───────────────────────────────────────────────────────────────
 
-describe("cmdThreadStepDetails", () => {
+describe("cmdStepShow", () => {
   test("returns expanded detail node with turns inlined", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const detailSchemas = await registerDetailSchemas(uwf.store);
@@ -365,7 +365,7 @@ describe("cmdThreadStepDetails", () => {
       agent: "uwf-hermes",
     });
 
-    const result = await cmdThreadStepDetails(tmpDir, stepHash);
+    const result = await cmdStepShow(tmpDir, stepHash);
 
     expect(result).toMatchObject({
       sessionId: "sess42",
@@ -586,9 +586,9 @@ describe("cmdThreadRead start section / before / quota", () => {
 
 // ── Tests that call process.exit must be last ─────────────────────────────────
 
-describe("cmdThreadStepDetails (process.exit tests - must be last)", () => {
+describe("cmdStepShow (process.exit tests - must be last)", () => {
   test("throws when step hash does not exist", async () => {
-    await expect(cmdThreadStepDetails(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
+    await expect(cmdStepShow(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
   });
 
   test("before with unknown hash rejects", async () => {
@@ -647,3 +647,383 @@ describe("cmdThreadStepDetails (process.exit tests - must be last)", () => {
     ).rejects.toThrow();
   });
 });
+
+// ── cmdStepList / cmdStepShow: completed threads ──────────────────────────────
+
+describe("cmdStepList with completed threads", () => {
+  test("lists steps from active thread", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-active",
+      description: "desc",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Start prompt",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const step1Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "role1",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    const step2Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: step1Hash,
+      role: "role2",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    const step3Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: step2Hash,
+      role: "role3",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+
+    const threadId = "01JTEST0000000000000000A1" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: step3Hash });
+
+    const result = await cmdStepList(tmpDir, threadId);
+
+    expect(result.thread).toBe(threadId);
+    expect(result.steps).toHaveLength(4); // start + 3 steps
+    expect(result.steps[1].role).toBe("role1");
+    expect(result.steps[2].role).toBe("role2");
+    expect(result.steps[3].role).toBe("role3");
+  });
+
+  test("lists steps from completed thread", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-completed",
+      description: "desc",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Start prompt",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const step1Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "roleA",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    const step2Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: step1Hash,
+      role: "roleB",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+
+    const threadId = "01JTEST0000000000000000A2" as ThreadId;
+    // Thread is NOT in threads.yaml (simulating completed thread)
+    await saveThreadsIndex(tmpDir, {});
+    // But it IS in history.jsonl
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: step2Hash,
+      completedAt: Date.now(),
+    });
+
+    const result = await cmdStepList(tmpDir, threadId);
+
+    expect(result.thread).toBe(threadId);
+    expect(result.steps).toHaveLength(3); // start + 2 steps
+    expect(result.steps[1].role).toBe("roleA");
+    expect(result.steps[2].role).toBe("roleB");
+  });
+});
+
+describe("cmdStepShow with completed threads", () => {
+  test("shows step detail from active thread", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const detailSchemas = await registerDetailSchemas(uwf.store);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-step-active",
+      description: "desc",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "p",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const turnHash = await uwf.store.put(detailSchemas.turn, {
+      index: 0,
+      role: "assistant",
+      content: "Active thread response",
+      toolCalls: null,
+      reasoning: null,
+    });
+    const detailHash = await uwf.store.put(detailSchemas.detail, {
+      sessionId: "sess-active",
+      model: "model-x",
+      duration: 1234,
+      turnCount: 1,
+      turns: [turnHash],
+    });
+
+    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "coder",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-hermes",
+    });
+
+    const threadId = "01JTEST0000000000000000B1" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
+
+    const result = await cmdStepShow(tmpDir, stepHash);
+
+    expect(result).toMatchObject({
+      sessionId: "sess-active",
+      model: "model-x",
+      duration: 1234,
+      turnCount: 1,
+    });
+  });
+
+  test("shows step detail from completed thread", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+    const detailSchemas = await registerDetailSchemas(uwf.store);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-step-completed",
+      description: "desc",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "p",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const turnHash = await uwf.store.put(detailSchemas.turn, {
+      index: 0,
+      role: "assistant",
+      content: "Completed thread response",
+      toolCalls: null,
+      reasoning: null,
+    });
+    const detailHash = await uwf.store.put(detailSchemas.detail, {
+      sessionId: "sess-completed",
+      model: "model-y",
+      duration: 5678,
+      turnCount: 1,
+      turns: [turnHash],
+    });
+
+    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "reviewer",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-hermes",
+    });
+
+    const threadId = "01JTEST0000000000000000B2" as ThreadId;
+    // Thread is NOT in threads.yaml
+    await saveThreadsIndex(tmpDir, {});
+    // But it IS in history.jsonl
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: stepHash,
+      completedAt: Date.now(),
+    });
+
+    const result = await cmdStepShow(tmpDir, stepHash);
+
+    expect(result).toMatchObject({
+      sessionId: "sess-completed",
+      model: "model-y",
+      duration: 5678,
+      turnCount: 1,
+    });
+  });
+});
+
+describe("cmdThreadRead with completed threads", () => {
+  test("reads completed thread context", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-read-completed",
+      description: "desc",
+      roles: {
+        writer: {
+          description: "Write",
+          goal: "You are a writer.",
+          capabilities: [],
+          procedure: "Write content.",
+          output: "Summary.",
+          meta: "placeholder00" as CasRef,
+        },
+      },
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Write something",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "writer",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-hermes",
+    });
+
+    const threadId = "01JTEST0000000000000000C1" as ThreadId;
+    // Thread is NOT in threads.yaml
+    await saveThreadsIndex(tmpDir, {});
+    // But it IS in history.jsonl
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: stepHash,
+      completedAt: Date.now(),
+    });
+
+    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
+
+    expect(markdown).toContain("writer");
+    expect(markdown).toContain("Write something");
+  });
+
+  test("reads completed thread with before filter", async () => {
+    const uwf = await makeUwfStore(tmpDir);
+
+    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "test-wf-read-before",
+      description: "desc",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+    const startHash = await uwf.store.put(uwf.schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Do task",
+    });
+    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
+      name: "out",
+      description: "",
+      roles: {},
+      conditions: {},
+      graph: {},
+    });
+
+    const step1Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "roleX",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    const step2Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: step1Hash,
+      role: "roleY",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+    const step3Hash = await uwf.store.put(uwf.schemas.stepNode, {
+      start: startHash,
+      prev: step2Hash,
+      role: "roleZ",
+      output: outputHash,
+      detail: null,
+      agent: "uwf-test",
+    });
+
+    const threadId = "01JTEST0000000000000000C2" as ThreadId;
+    await saveThreadsIndex(tmpDir, {});
+    await appendThreadHistory(tmpDir, {
+      thread: threadId,
+      workflow: workflowHash,
+      head: step3Hash,
+      completedAt: Date.now(),
+    });
+
+    const markdown = await cmdThreadRead(
+      tmpDir,
+      threadId,
+      THREAD_READ_DEFAULT_QUOTA,
+      step2Hash,
+      false,
+    );
+
+    // Should contain step1 (roleX) but not step2 (roleY) or step3 (roleZ)
+    expect(markdown).toContain("roleX");
+    expect(markdown).not.toContain("roleY");
+    expect(markdown).not.toContain("roleZ");
+  });
+});

packages/cli-workflow/src/cli.ts

@@ -1,8 +1,7 @@
 #!/usr/bin/env bun
 
-import type { ThreadId } from "@uncaged/workflow-protocol";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
 import { Command } from "commander";
-import { stringify as yamlStringify } from "yaml";
 import {
   cmdCasGet,
   cmdCasHas,
@@ -17,20 +16,20 @@ import {
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import { cmdSkillCli } from "./commands/skill.js";
+import { cmdStepFork, cmdStepList, cmdStepShow } from "./commands/step.js";
 import {
-  cmdThreadFork,
-  cmdThreadKill,
+  cmdThreadCancel,
+  cmdThreadExec,
   cmdThreadList,
   cmdThreadRead,
-  cmdThreadRunning,
   cmdThreadShow,
   cmdThreadStart,
-  cmdThreadStep,
-  cmdThreadStepDetails,
-  cmdThreadSteps,
+  cmdThreadStop,
   THREAD_READ_DEFAULT_QUOTA,
+  type ThreadStatus,
 } from "./commands/thread.js";
-import { cmdWorkflowList, cmdWorkflowPut, cmdWorkflowShow } from "./commands/workflow.js";
+import { parseTimeInput } from "./commands/thread-time-parser.js";
+import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow } from "./commands/workflow.js";
 import { formatOutput, type OutputFormat } from "./format.js";
 import { resolveStorageRoot } from "./store.js";
 
@@ -53,20 +52,27 @@ const program = new Command();
 const pkg = await import("../package.json", { with: { type: "json" } });
 program
   .name("uwf")
-  .description("Stateless workflow CLI")
+  .description(
+    "Stateless workflow CLI\n\n" +
+      "Four-layer architecture:\n" +
+      "  workflow → thread → step → turn\n" +
+      "  模板定义   执行实例   单步结果   agent内部交互",
+  )
   .version(pkg.default.version, "-V, --version");
 program.option("--format <fmt>", "Output format: json or yaml", "json");
 
-const workflow = program.command("workflow").description("Workflow registry and CAS");
+const workflow = program
+  .command("workflow")
+  .description("Workflow definitions (layer 1: templates)");
 
 workflow
-  .command("put")
+  .command("add")
   .description("Register a workflow from YAML")
   .argument("<file>", "Workflow YAML file")
   .action((file: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdWorkflowPut(storageRoot, file);
+      const result = await cmdWorkflowAdd(storageRoot, file);
       writeOutput(result);
     });
   });
@@ -94,7 +100,7 @@ workflow
     });
   });
 
-const thread = program.command("thread").description("Thread lifecycle and execution");
+const thread = program.command("thread").description("Thread execution (layer 2: instances)");
 
 thread
   .command("start")
@@ -110,7 +116,7 @@ thread
   });
 
 thread
-  .command("step")
+  .command("exec")
   .description("Execute one or more steps")
   .argument("<thread-id>", "Thread ULID")
   .option("--agent <cmd>", "Override agent command")
@@ -134,7 +140,7 @@ thread
         const background = opts.background ?? false;
         const backgroundWorker = opts._backgroundWorker ?? false;
 
-        const results = await cmdThreadStep(
+        const results = await cmdThreadExec(
           storageRoot,
           threadId,
           agentOverride,
@@ -163,49 +169,124 @@ thread
     });
   });
 
+// Helper functions for thread list command parsing
+function parseStatusFilter(status: string | undefined): ThreadStatus[] | null {
+  if (status === undefined) return null;
+  const raw = status.trim();
+  if (raw === "active") return ["idle", "running"];
+
+  const parts = raw.split(",").map((s) => s.trim());
+  const validStatuses: ThreadStatus[] = ["idle", "running", "completed"];
+  for (const part of parts) {
+    if (!validStatuses.includes(part as ThreadStatus)) {
+      process.stderr.write(
+        `Invalid status: ${part}. Must be one of: idle, running, completed, active\n`,
+      );
+      process.exit(1);
+    }
+  }
+  return parts as ThreadStatus[];
+}
+
+function parseTimeFilters(
+  after: string | undefined,
+  before: string | undefined,
+  nowMs: number,
+): { afterMs: number | null; beforeMs: number | null } {
+  try {
+    const afterMs = after !== undefined ? parseTimeInput(after, nowMs) : null;
+    const beforeMs = before !== undefined ? parseTimeInput(before, nowMs) : null;
+    return { afterMs, beforeMs };
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+  }
+}
+
+function parsePaginationOptions(
+  skip: string | undefined,
+  take: string | undefined,
+): { skip: number | null; take: number | null } {
+  let skipVal: number | null = null;
+  let takeVal: number | null = null;
+
+  if (skip !== undefined) {
+    skipVal = Number.parseInt(skip, 10);
+    if (!Number.isInteger(skipVal) || skipVal < 0) {
+      process.stderr.write("--skip must be a non-negative integer\n");
+      process.exit(1);
+    }
+  }
+  if (take !== undefined) {
+    takeVal = Number.parseInt(take, 10);
+    if (!Number.isInteger(takeVal) || takeVal < 1) {
+      process.stderr.write("--take must be a positive integer\n");
+      process.exit(1);
+    }
+  }
+  return { skip: skipVal, take: takeVal };
+}
+
 thread
   .command("list")
-  .description("List active threads")
-  .option("--all", "Include archived threads")
-  .action((opts: { all: boolean }) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-      const result = await cmdThreadList(storageRoot, opts.all);
-      writeOutput(result);
-    });
-  });
+  .description("List threads")
+  .option(
+    "--status <status>",
+    "Filter by status: idle, running, completed, active (idle+running), or comma-separated values",
+  )
+  .option("--after <date>", "Filter threads created after this date (ISO or relative like '7d')")
+  .option("--before <date>", "Filter threads created before this date (ISO or relative like '7d')")
+  .option("--skip <n>", "Skip first n threads")
+  .option("--take <n>", "Return at most n threads")
+  .action(
+    (opts: {
+      status: string | undefined;
+      after: string | undefined;
+      before: string | undefined;
+      skip: string | undefined;
+      take: string | undefined;
+    }) => {
+      const storageRoot = resolveStorageRoot();
+      runAction(async () => {
+        const statusFilter = parseStatusFilter(opts.status);
+        const nowMs = Date.now();
+        const { afterMs, beforeMs } = parseTimeFilters(opts.after, opts.before, nowMs);
+        const { skip, take } = parsePaginationOptions(opts.skip, opts.take);
+
+        const result = await cmdThreadList(
+          storageRoot,
+          statusFilter,
+          afterMs,
+          beforeMs,
+          skip,
+          take,
+        );
+        writeOutput(result);
+      });
+    },
+  );
 
 thread
-  .command("running")
-  .description("List threads currently executing in the background")
-  .action(() => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-      const result = await cmdThreadRunning(storageRoot);
-      writeOutput(result);
-    });
-  });
-
-thread
-  .command("kill")
-  .description("Terminate and archive a thread")
+  .command("stop")
+  .description("Stop background execution of a thread (keep thread active)")
   .argument("<thread-id>", "Thread ULID")
   .action((threadId: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadKill(storageRoot, threadId);
+      const result = await cmdThreadStop(storageRoot, threadId);
       writeOutput(result);
     });
   });
 
 thread
-  .command("steps")
-  .description("List all steps in a thread")
+  .command("cancel")
+  .description("Cancel a thread (stop execution and move to history)")
   .argument("<thread-id>", "Thread ULID")
   .action((threadId: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadSteps(storageRoot, threadId);
+      const result = await cmdThreadCancel(storageRoot, threadId);
       writeOutput(result);
     });
   });
@@ -239,28 +320,141 @@ thread
     },
   );
 
-thread
+const step = program.command("step").description("Step results (layer 3: single cycle)");
+
+step
+  .command("list")
+  .description("List all steps in a thread")
+  .argument("<thread-id>", "Thread ULID")
+  .action((threadId: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const result = await cmdStepList(storageRoot, threadId);
+      writeOutput(result);
+    });
+  });
+
+step
+  .command("show")
+  .description("Show details of a specific step")
+  .argument("<step-hash>", "CAS hash of the StepNode")
+  .action((stepHash: string) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const detail = await cmdStepShow(storageRoot, stepHash as CasRef);
+      writeOutput(detail);
+    });
+  });
+
+// step read is not yet registered (half-baked, see step.ts cmdStepRead)
+
+step
   .command("fork")
   .description("Fork a thread from a specific step")
   .argument("<step-hash>", "CAS hash of the StartNode or StepNode to fork from")
   .action((stepHash: string) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadFork(storageRoot, stepHash);
+      const result = await cmdStepFork(storageRoot, stepHash as CasRef);
       writeOutput(result);
     });
   });
 
+// ── Deprecation Handlers ──────────────────────────────────────────────────────
+// These commands have been removed. Show helpful error messages.
+
+workflow
+  .command("put")
+  .description("[DEPRECATED] Use 'workflow add' instead")
+  .argument("<file>", "Workflow YAML file")
+  .action(() => {
+    process.stderr.write(`Error: Command 'workflow put' has been removed.
+Use 'workflow add' instead.
+
+For more information, see: uwf help workflow add
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("step")
+  .description("[DEPRECATED] Use 'thread exec' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .allowUnknownOption()
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread step' has been removed.
+Use 'thread exec' instead.
+
+For more information, see: uwf help thread exec
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("steps")
+  .description("[DEPRECATED] Use 'step list' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread steps' has been removed.
+Use 'step list' instead.
+
+For more information, see: uwf help step list
+`);
+    process.exit(1);
+  });
+
 thread
   .command("step-details")
-  .description("Dump the full detail node of a step as YAML")
-  .argument("<step-hash>", "CAS hash of the StepNode")
-  .action((stepHash: string) => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-      const detail = await cmdThreadStepDetails(storageRoot, stepHash);
-      process.stdout.write(yamlStringify(detail));
-    });
+  .description("[DEPRECATED] Use 'step show' instead")
+  .argument("<step-hash>", "Step hash")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread step-details' has been removed.
+Use 'step show' instead.
+
+For more information, see: uwf help step show
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("fork")
+  .description("[DEPRECATED] Use 'step fork' instead")
+  .argument("<step-hash>", "Step hash")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread fork' has been removed.
+Use 'step fork' instead.
+
+For more information, see: uwf help step fork
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("kill")
+  .description("[DEPRECATED] Use 'thread stop' or 'thread cancel' instead")
+  .argument("<thread-id>", "Thread ULID")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread kill' has been removed.
+Use 'thread stop' to stop background execution (keep thread active),
+or 'thread cancel' to cancel and archive the thread.
+
+For more information, see:
+  uwf help thread stop
+  uwf help thread cancel
+`);
+    process.exit(1);
+  });
+
+thread
+  .command("running")
+  .description("[DEPRECATED] Use 'thread list --status running' instead")
+  .action(() => {
+    process.stderr.write(`Error: Command 'thread running' has been removed.
+Use 'thread list --status running' instead.
+
+For more information, see: uwf help thread list
+`);
+    process.exit(1);
   });
 
 const skill = program.command("skill").description("Built-in skill references for agents");

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

@@ -0,0 +1,231 @@
+import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
+import { getSchema } from "@uncaged/json-cas";
+import type {
+  CasRef,
+  StartNodePayload,
+  StepNodePayload,
+  ThreadId,
+} from "@uncaged/workflow-protocol";
+import { findThreadInHistory, loadThreadsIndex, type UwfStore } from "../store.js";
+
+type ChainState = {
+  startHash: CasRef;
+  start: StartNodePayload;
+  stepsNewestFirst: StepNodePayload[];
+  headIsStart: boolean;
+};
+
+type OrderedStepItem = {
+  hash: CasRef;
+  payload: StepNodePayload;
+  timestamp: number;
+};
+
+function fail(message: string): never {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function walkChain(uwf: UwfStore, headHash: CasRef): ChainState {
+  const headNode = uwf.store.get(headHash);
+  if (headNode === null) {
+    fail(`CAS node not found: ${headHash}`);
+  }
+
+  if (headNode.type === uwf.schemas.startNode) {
+    return {
+      startHash: headHash,
+      start: headNode.payload as StartNodePayload,
+      stepsNewestFirst: [],
+      headIsStart: true,
+    };
+  }
+
+  if (headNode.type !== uwf.schemas.stepNode) {
+    fail(`head ${headHash} is not a StartNode or StepNode`);
+  }
+
+  const stepsNewestFirst: StepNodePayload[] = [];
+  let hash: CasRef | null = headHash;
+
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null) {
+      fail(`CAS node not found while walking chain: ${hash}`);
+    }
+    if (node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    stepsNewestFirst.push(payload);
+    hash = payload.prev;
+  }
+
+  const newest = stepsNewestFirst[0];
+  if (newest === undefined) {
+    fail(`empty step chain at head ${headHash}`);
+  }
+
+  const startNode = uwf.store.get(newest.start);
+  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
+    fail(`StartNode not found: ${newest.start}`);
+  }
+
+  return {
+    startHash: newest.start,
+    start: startNode.payload as StartNodePayload,
+    stepsNewestFirst,
+    headIsStart: false,
+  };
+}
+
+function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
+  const node = uwf.store.get(outputRef);
+  if (node === null) {
+    return {};
+  }
+  return node.payload;
+}
+
+/**
+ * Recursively expand all cas_ref fields in a CAS node's payload,
+ * replacing hash strings with the referenced node's expanded payload.
+ */
+function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unknown {
+  const seen = visited ?? new Set<string>();
+  if (seen.has(hash)) return hash; // cycle guard
+  seen.add(hash);
+
+  const node = store.get(hash);
+  if (node === null) return hash;
+
+  const schema = getSchema(store, node.type);
+  if (schema === null) return node.payload;
+
+  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 (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(
+  uwf: UwfStore,
+  headHash: CasRef,
+  chain: ChainState,
+): OrderedStepItem[] {
+  let hash: CasRef | null = headHash;
+  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
+  while (hash !== null) {
+    const node = uwf.store.get(hash);
+    if (node === null || node.type !== uwf.schemas.stepNode) {
+      break;
+    }
+    const payload = node.payload as StepNodePayload;
+    hashToNode.set(hash, { payload, timestamp: node.timestamp });
+    hash = payload.prev;
+  }
+
+  let cur: CasRef | null = chain.headIsStart ? null : headHash;
+  const ordered: OrderedStepItem[] = [];
+  while (cur !== null) {
+    const entry = hashToNode.get(cur);
+    if (entry === undefined) {
+      break;
+    }
+    ordered.push({ hash: cur, ...entry });
+    cur = entry.payload.prev;
+  }
+
+  ordered.reverse();
+  return ordered;
+}
+
+async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise<CasRef> {
+  const index = await loadThreadsIndex(storageRoot);
+  const activeHead = index[threadId];
+  if (activeHead !== undefined) {
+    return activeHead;
+  }
+  const hist = await findThreadInHistory(storageRoot, threadId);
+  if (hist !== null) {
+    return hist.head;
+  }
+  fail(`thread not found: ${threadId}`);
+}
+
+export {
+  type ChainState,
+  collectOrderedSteps,
+  expandAnyOfField,
+  expandArrayField,
+  expandCasRefField,
+  expandDeep,
+  expandObjectField,
+  expandOutput,
+  expandValue,
+  fail,
+  type OrderedStepItem,
+  resolveHeadHash,
+  walkChain,
+};

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

@@ -0,0 +1,145 @@
+import type {
+  CasRef,
+  StartEntry,
+  StepEntry,
+  StepNodePayload,
+  ThreadForkOutput,
+  ThreadId,
+  ThreadStepsOutput,
+} from "@uncaged/workflow-protocol";
+import { generateUlid } from "@uncaged/workflow-util";
+import { createUwfStore, loadThreadsIndex, saveThreadsIndex } from "../store.js";
+import {
+  collectOrderedSteps,
+  expandDeep,
+  expandOutput,
+  fail,
+  resolveHeadHash,
+  walkChain,
+} from "./shared.js";
+
+/**
+ * List all steps in a thread (previously: thread steps)
+ */
+export async function cmdStepList(
+  storageRoot: string,
+  threadId: ThreadId,
+): Promise<ThreadStepsOutput> {
+  const headHash = await resolveHeadHash(storageRoot, threadId);
+  const uwf = await createUwfStore(storageRoot);
+  const chain = walkChain(uwf, headHash);
+
+  const startNode = uwf.store.get(chain.startHash);
+  if (startNode === null) {
+    fail(`StartNode not found: ${chain.startHash}`);
+  }
+
+  const startEntry: StartEntry = {
+    hash: chain.startHash,
+    workflow: chain.start.workflow,
+    prompt: chain.start.prompt,
+    timestamp: startNode.timestamp,
+  };
+
+  const stepEntries: StepEntry[] = [];
+  const ordered = collectOrderedSteps(uwf, headHash, chain);
+
+  for (const item of ordered) {
+    stepEntries.push({
+      hash: item.hash,
+      role: item.payload.role,
+      output: expandOutput(uwf, item.payload.output),
+      detail: item.payload.detail ?? null,
+      agent: item.payload.agent,
+      timestamp: item.timestamp,
+    });
+  }
+
+  return {
+    thread: threadId,
+    workflow: chain.start.workflow,
+    steps: [startEntry, ...stepEntries],
+  };
+}
+
+/**
+ * Show details of a specific step (previously: thread step-details)
+ */
+export async function cmdStepShow(storageRoot: string, stepHash: CasRef): Promise<unknown> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StepNode`);
+  }
+  const payload = node.payload as StepNodePayload;
+  if (!payload.detail) {
+    fail(`step ${stepHash} has no detail`);
+  }
+  return expandDeep(uwf.store, payload.detail);
+}
+
+/**
+ * Fork a thread from a specific step (previously: thread fork)
+ */
+export async function cmdStepFork(
+  storageRoot: string,
+  stepHash: CasRef,
+): Promise<ThreadForkOutput> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.startNode && node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StartNode or StepNode`);
+  }
+
+  const newThreadId = generateUlid(Date.now()) as ThreadId;
+  const index = await loadThreadsIndex(storageRoot);
+  index[newThreadId] = stepHash;
+  await saveThreadsIndex(storageRoot, index);
+
+  return {
+    thread: newThreadId,
+    forkedFrom: {
+      step: stepHash,
+    },
+  };
+}
+
+/**
+ * Read a step's agent output as markdown (new command - requires #462)
+ * TODO: Implement once unified agent detail/turn schema is available
+ */
+export async function cmdStepRead(
+  storageRoot: string,
+  stepHash: CasRef,
+  _before: number | null = null,
+): Promise<string> {
+  const uwf = await createUwfStore(storageRoot);
+  const node = uwf.store.get(stepHash);
+  if (node === null) {
+    fail(`CAS node not found: ${stepHash}`);
+  }
+  if (node.type !== uwf.schemas.stepNode) {
+    fail(`node ${stepHash} is not a StepNode`);
+  }
+  const payload = node.payload as StepNodePayload;
+  if (!payload.output) {
+    fail(`step ${stepHash} has no output`);
+  }
+
+  // TODO: Implement progressive turn reading with --before N
+  // For now, return a placeholder
+  const outputNode = uwf.store.get(payload.output);
+  if (outputNode === null) {
+    fail(`output node not found: ${payload.output}`);
+  }
+
+  // Return the output as JSON for now
+  // Once #462 is implemented, this will properly format frontmatter + markdown
+  return JSON.stringify(outputNode.payload, null, 2);
+}

packages/cli-workflow/src/commands/thread-time-parser.ts

@@ -0,0 +1,23 @@
+/**
+ * Parse time input: ISO date (YYYY-MM-DD, YYYY-MM-DDTHH:MM:SS) or relative (7d, 24h, 30m)
+ * Returns Unix timestamp in milliseconds.
+ */
+export function parseTimeInput(input: string, nowMs: number): number {
+  const trimmed = input.trim();
+
+  // Relative time: 7d, 24h, 30m
+  const relativeMatch = /^(\d+)(d|h|m)$/.exec(trimmed);
+  if (relativeMatch !== null) {
+    const value = Number.parseInt(relativeMatch[1], 10);
+    const unit = relativeMatch[2];
+    const multiplier = unit === "d" ? 86400000 : unit === "h" ? 3600000 : 60000;
+    return nowMs - value * multiplier;
+  }
+
+  // ISO date: try parsing
+  const parsed = Date.parse(trimmed);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`invalid time format: ${trimmed} (expected ISO date or relative like '7d')`);
+  }
+  return parsed;
+}

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

@@ -1,8 +1,7 @@
 import { execFileSync, spawn } from "node:child_process";
 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 { validate } from "@uncaged/json-cas";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-agent-kit";
 import { evaluate } from "@uncaged/workflow-moderator";
 import type {
@@ -10,30 +9,26 @@ import type {
   AgentConfig,
   CasRef,
   ModeratorContext,
-  RunningThreadsOutput,
-  StartEntry,
   StartNodePayload,
   StartOutput,
   StepContext,
-  StepEntry,
   StepNodePayload,
   StepOutput,
-  ThreadForkOutput,
   ThreadId,
   ThreadListItem,
-  ThreadStepsOutput,
+  ThreadsIndex,
   WorkflowConfig,
   WorkflowPayload,
 } from "@uncaged/workflow-protocol";
-import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util";
+import {
+  createProcessLogger,
+  extractUlidTimestamp,
+  generateUlid,
+  type ProcessLogger,
+} from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
 import { parse, stringify } from "yaml";
-import {
-  createMarker,
-  deleteMarker,
-  isThreadRunning,
-  listRunningThreads,
-} from "../background/index.js";
+import { createMarker, deleteMarker, isThreadRunning } from "../background/index.js";
 import {
   appendThreadHistory,
   createUwfStore,
@@ -47,6 +42,14 @@ import {
   type UwfStore,
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
+import {
+  type ChainState,
+  collectOrderedSteps,
+  expandOutput,
+  fail,
+  type OrderedStepItem,
+  walkChain,
+} from "./shared.js";
 import { materializeWorkflowPayload } from "./workflow.js";
 
 const END_ROLE = "$END";
@@ -65,29 +68,6 @@ function failStep(plog: ProcessLogger, message: string): never {
   fail(message);
 }
 
-type ChainState = {
-  startHash: CasRef;
-  start: StartNodePayload;
-  stepsNewestFirst: StepNodePayload[];
-  headIsStart: boolean;
-};
-
-type OrderedStepItem = {
-  hash: CasRef;
-  payload: StepNodePayload;
-  timestamp: number;
-};
-
-export type KillOutput = {
-  thread: ThreadId;
-  archived: boolean;
-};
-
-function fail(message: string): never {
-  process.stderr.write(`${message}\n`);
-  process.exit(1);
-}
-
 /**
  * Check if a string looks like a file path (contains path separators or has .yaml/.yml extension).
  */
@@ -346,224 +326,139 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
   fail(`thread not found: ${threadId}`);
 }
 
+export type ThreadStatus = "idle" | "running" | "completed";
+
+export type ThreadListItemWithStatus = ThreadListItem & {
+  status: ThreadStatus;
+};
+
 async function threadListItemFromActive(
+  storageRoot: string,
   uwf: UwfStore,
   threadId: ThreadId,
   head: CasRef,
-): Promise<ThreadListItem | null> {
+): Promise<ThreadListItemWithStatus | null> {
   const workflow = resolveWorkflowFromHead(uwf, head);
   if (workflow === null) {
     return null;
   }
-  return { thread: threadId, workflow, head };
+
+  // Check if thread is currently running in background
+  const runningMarker = await isThreadRunning(storageRoot, threadId);
+  const status: ThreadStatus = runningMarker !== null ? "running" : "idle";
+
+  return { thread: threadId, workflow, head, status };
 }
 
-export async function cmdThreadList(
+async function collectActiveThreads(
   storageRoot: string,
-  includeAll: boolean,
-): Promise<ThreadListItem[]> {
-  const uwf = await createUwfStore(storageRoot);
-  const index = await loadThreadsIndex(storageRoot);
-  const items: ThreadListItem[] = [];
-
+  uwf: UwfStore,
+  index: ThreadsIndex,
+): Promise<ThreadListItemWithStatus[]> {
+  const items: ThreadListItemWithStatus[] = [];
   for (const [threadId, head] of Object.entries(index)) {
-    const item = await threadListItemFromActive(uwf, threadId as ThreadId, head);
+    const item = await threadListItemFromActive(
+      storageRoot,
+      uwf,
+      threadId as ThreadId,
+      head as CasRef,
+    );
     if (item !== null) {
       items.push(item);
     }
   }
+  return items;
+}
 
-  if (!includeAll) {
-    return items;
-  }
-
-  const activeIds = new Set(items.map((i) => i.thread));
+async function collectCompletedThreads(
+  storageRoot: string,
+  activeIds: Set<ThreadId>,
+): Promise<ThreadListItemWithStatus[]> {
+  const items: ThreadListItemWithStatus[] = [];
   const history = await loadThreadHistory(storageRoot);
+  const seen = new Set<ThreadId>(); // Deduplication (issue #470)
   for (const entry of history) {
-    if (!activeIds.has(entry.thread)) {
+    if (!activeIds.has(entry.thread) && !seen.has(entry.thread)) {
+      seen.add(entry.thread);
       items.push({
         thread: entry.thread,
         workflow: entry.workflow,
         head: entry.head,
+        status: "completed",
       });
     }
   }
-
   return items;
 }
 
-function walkChain(uwf: UwfStore, headHash: CasRef): ChainState {
-  const headNode = uwf.store.get(headHash);
-  if (headNode === null) {
-    fail(`CAS node not found: ${headHash}`);
-  }
-
-  if (headNode.type === uwf.schemas.startNode) {
-    return {
-      startHash: headHash,
-      start: headNode.payload as StartNodePayload,
-      stepsNewestFirst: [],
-      headIsStart: true,
-    };
-  }
-
-  if (headNode.type !== uwf.schemas.stepNode) {
-    fail(`head ${headHash} is not a StartNode or StepNode`);
-  }
-
-  const stepsNewestFirst: StepNodePayload[] = [];
-  let hash: CasRef | null = headHash;
-
-  while (hash !== null) {
-    const node = uwf.store.get(hash);
-    if (node === null) {
-      fail(`CAS node not found while walking chain: ${hash}`);
-    }
-    if (node.type !== uwf.schemas.stepNode) {
-      break;
-    }
-    const payload = node.payload as StepNodePayload;
-    stepsNewestFirst.push(payload);
-    hash = payload.prev;
-  }
-
-  const newest = stepsNewestFirst[0];
-  if (newest === undefined) {
-    fail(`empty step chain at head ${headHash}`);
-  }
-
-  const startNode = uwf.store.get(newest.start);
-  if (startNode === null || startNode.type !== uwf.schemas.startNode) {
-    fail(`StartNode not found: ${newest.start}`);
-  }
-
-  return {
-    startHash: newest.start,
-    start: startNode.payload as StartNodePayload,
-    stepsNewestFirst,
-    headIsStart: false,
-  };
+function applyTimeFilters(
+  items: ThreadListItemWithStatus[],
+  afterMs: number | null,
+  beforeMs: number | null,
+): ThreadListItemWithStatus[] {
+  if (afterMs === null && beforeMs === null) return items;
+  return items.filter((item) => {
+    const ts = extractUlidTimestamp(item.thread);
+    if (ts === null) return false;
+    if (afterMs !== null && ts <= afterMs) return false;
+    if (beforeMs !== null && ts >= beforeMs) return false;
+    return true;
+  });
 }
 
-function expandOutput(uwf: UwfStore, outputRef: CasRef): unknown {
-  const node = uwf.store.get(outputRef);
-  if (node === null) {
-    return {};
-  }
-  return node.payload;
+function sortByNewestFirst(items: ThreadListItemWithStatus[]): ThreadListItemWithStatus[] {
+  return items.sort((a, b) => {
+    const tsA = extractUlidTimestamp(a.thread) ?? 0;
+    const tsB = extractUlidTimestamp(b.thread) ?? 0;
+    return tsB - tsA;
+  });
 }
 
-/**
- * Recursively expand all cas_ref fields in a CAS node's payload,
- * replacing hash strings with the referenced node's expanded payload.
- */
-function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unknown {
-  const seen = visited ?? new Set<string>();
-  if (seen.has(hash)) return hash; // cycle guard
-  seen.add(hash);
-
-  const node = store.get(hash);
-  if (node === null) return hash;
-
-  const schema = getSchema(store, node.type);
-  if (schema === null) return node.payload;
-
-  return expandValue(store, schema, node.payload, seen);
+function applyPagination(
+  items: ThreadListItemWithStatus[],
+  skip: number | null,
+  take: number | null,
+): ThreadListItemWithStatus[] {
+  const skipCount = skip ?? 0;
+  const takeCount = take ?? items.length;
+  return items.slice(skipCount, skipCount + takeCount);
 }
 
-function expandCasRefField(store: CasStore, value: unknown, visited: Set<string>): unknown {
-  if (typeof value === "string") {
-    return expandDeep(store, value as CasRef, visited);
-  }
-  return value;
-}
+export async function cmdThreadList(
+  storageRoot: string,
+  statusFilter: ThreadStatus[] | null,
+  afterMs: number | null,
+  beforeMs: number | null,
+  skip: number | null,
+  take: number | null,
+): Promise<ThreadListItemWithStatus[]> {
+  const uwf = await createUwfStore(storageRoot);
+  const index = await loadThreadsIndex(storageRoot);
 
-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;
-}
+  // Collect active threads
+  let items = await collectActiveThreads(storageRoot, uwf, index);
 
-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 (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(
-  uwf: UwfStore,
-  headHash: CasRef,
-  chain: ChainState,
-): OrderedStepItem[] {
-  let hash: CasRef | null = headHash;
-  const hashToNode = new Map<string, { payload: StepNodePayload; timestamp: number }>();
-  while (hash !== null) {
-    const node = uwf.store.get(hash);
-    if (node === null || node.type !== uwf.schemas.stepNode) {
-      break;
-    }
-    const payload = node.payload as StepNodePayload;
-    hashToNode.set(hash, { payload, timestamp: node.timestamp });
-    hash = payload.prev;
+  // Collect completed threads (if relevant for status filter)
+  const includeCompleted = statusFilter === null || statusFilter.includes("completed");
+  if (includeCompleted) {
+    const activeIds = new Set(items.map((i) => i.thread));
+    const completedItems = await collectCompletedThreads(storageRoot, activeIds);
+    items = items.concat(completedItems);
   }
 
-  let cur: CasRef | null = chain.headIsStart ? null : headHash;
-  const ordered: OrderedStepItem[] = [];
-  while (cur !== null) {
-    const entry = hashToNode.get(cur);
-    if (entry === undefined) {
-      break;
-    }
-    ordered.push({ hash: cur, ...entry });
-    cur = entry.payload.prev;
+  // Apply status filter
+  if (statusFilter !== null) {
+    items = items.filter((item) => statusFilter.includes(item.status));
   }
-  ordered.reverse();
-  return ordered;
+
+  // Apply time range filters
+  items = applyTimeFilters(items, afterMs, beforeMs);
+
+  // Sort by timestamp descending (newest first)
+  items = sortByNewestFirst(items);
+
+  // Apply pagination
+  return applyPagination(items, skip, take);
 }
 
 function formatYaml(value: unknown): string {
@@ -754,6 +649,7 @@ function buildModeratorContext(uwf: UwfStore, chain: ChainState): ModeratorConte
     detail: step.detail,
     agent: step.agent,
     edgePrompt: step.edgePrompt ?? "",
+    content: null, // Moderator doesn't need content
   }));
   return { start: chain.start, steps };
 }
@@ -857,7 +753,7 @@ async function archiveThread(
   });
 }
 
-export async function cmdThreadStep(
+export async function cmdThreadExec(
   storageRoot: string,
   threadId: ThreadId,
   agentOverride: string | null,
@@ -953,7 +849,7 @@ async function cmdThreadStepBackground(
     failStep(plog, "unable to determine script path for background execution");
   }
 
-  const args = ["thread", "step", threadId, "--count", String(count)];
+  const args = ["thread", "exec", threadId, "--count", String(count)];
 
   if (agentOverride !== null) {
     args.push("--agent", agentOverride);
@@ -1085,47 +981,6 @@ async function resolveHeadHash(storageRoot: string, threadId: ThreadId): Promise
   fail(`thread not found: ${threadId}`);
 }
 
-export async function cmdThreadSteps(
-  storageRoot: string,
-  threadId: ThreadId,
-): Promise<ThreadStepsOutput> {
-  const headHash = await resolveHeadHash(storageRoot, threadId);
-  const uwf = await createUwfStore(storageRoot);
-  const chain = walkChain(uwf, headHash);
-
-  const startNode = uwf.store.get(chain.startHash);
-  if (startNode === null) {
-    fail(`StartNode not found: ${chain.startHash}`);
-  }
-
-  const startEntry: StartEntry = {
-    hash: chain.startHash,
-    workflow: chain.start.workflow,
-    prompt: chain.start.prompt,
-    timestamp: startNode.timestamp,
-  };
-
-  const stepEntries: StepEntry[] = [];
-  const ordered = collectOrderedSteps(uwf, headHash, chain);
-
-  for (const item of ordered) {
-    stepEntries.push({
-      hash: item.hash,
-      role: item.payload.role,
-      output: expandOutput(uwf, item.payload.output),
-      detail: item.payload.detail,
-      agent: item.payload.agent,
-      timestamp: item.timestamp,
-    });
-  }
-
-  return {
-    thread: threadId,
-    workflow: chain.start.workflow,
-    steps: [startEntry, ...stepEntries],
-  };
-}
-
 export async function cmdThreadRead(
   storageRoot: string,
   threadId: ThreadId,
@@ -1153,52 +1008,50 @@ export async function cmdThreadRead(
   });
 }
 
-export async function cmdThreadFork(
-  storageRoot: string,
-  stepHash: CasRef,
-): Promise<ThreadForkOutput> {
-  const uwf = await createUwfStore(storageRoot);
-  const node = uwf.store.get(stepHash);
-  if (node === null) {
-    fail(`CAS node not found: ${stepHash}`);
-  }
-  if (node.type !== uwf.schemas.startNode && node.type !== uwf.schemas.stepNode) {
-    fail(`node ${stepHash} is not a StartNode or StepNode`);
-  }
+export type StopOutput = {
+  thread: ThreadId;
+  stopped: boolean;
+};
 
-  const newThreadId = generateUlid(Date.now()) as ThreadId;
+export type CancelOutput = {
+  thread: ThreadId;
+  cancelled: boolean;
+};
+
+/**
+ * Stop background execution of a thread (but keep thread active)
+ */
+export async function cmdThreadStop(storageRoot: string, threadId: ThreadId): Promise<StopOutput> {
   const index = await loadThreadsIndex(storageRoot);
-  index[newThreadId] = stepHash;
-  await saveThreadsIndex(storageRoot, index);
+  const head = index[threadId];
+  if (head === undefined) {
+    fail(`thread not active: ${threadId}`);
+  }
 
-  return {
-    thread: newThreadId,
-    forkedFrom: {
-      step: stepHash,
-    },
-  };
+  // Check if thread is running in background and terminate it
+  const runningMarker = await isThreadRunning(storageRoot, threadId);
+  if (runningMarker === null) {
+    process.stderr.write(`Warning: thread ${threadId} is not currently running\n`);
+    return { thread: threadId, stopped: false };
+  }
+
+  try {
+    process.kill(runningMarker.pid, "SIGTERM");
+  } catch {
+    // Process may have already exited, ignore error
+  }
+  await deleteMarker(storageRoot, threadId);
+
+  return { thread: threadId, stopped: true };
 }
 
-export async function cmdThreadStepDetails(
+/**
+ * Cancel a thread (stop execution + move to history)
+ */
+export async function cmdThreadCancel(
   storageRoot: string,
-  stepHash: CasRef,
-): Promise<unknown> {
-  const uwf = await createUwfStore(storageRoot);
-  const node = uwf.store.get(stepHash);
-  if (node === null) {
-    fail(`CAS node not found: ${stepHash}`);
-  }
-  if (node.type !== uwf.schemas.stepNode) {
-    fail(`node ${stepHash} is not a StepNode`);
-  }
-  const payload = node.payload as StepNodePayload;
-  if (!payload.detail) {
-    fail(`step ${stepHash} has no detail`);
-  }
-  return expandDeep(uwf.store, payload.detail);
-}
-
-export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Promise<KillOutput> {
+  threadId: ThreadId,
+): Promise<CancelOutput> {
   const index = await loadThreadsIndex(storageRoot);
   const head = index[threadId];
   if (head === undefined) {
@@ -1233,10 +1086,5 @@ export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Pr
   };
   await appendThreadHistory(storageRoot, historyEntry);
 
-  return { thread: threadId, archived: true };
-}
-
-export async function cmdThreadRunning(storageRoot: string): Promise<RunningThreadsOutput> {
-  const threads = await listRunningThreads(storageRoot);
-  return { threads };
+  return { thread: threadId, cancelled: true };
 }

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

@@ -29,7 +29,7 @@ export type WorkflowListEntry = {
   origin: WorkflowOrigin;
 };
 
-export type WorkflowPutOutput = {
+export type WorkflowAddOutput = {
   name: string;
   hash: CasRef;
 };
@@ -111,10 +111,10 @@ export async function materializeWorkflowPayload(
   };
 }
 
-export async function cmdWorkflowPut(
+export async function cmdWorkflowAdd(
   storageRoot: string,
   filePath: string,
-): Promise<WorkflowPutOutput> {
+): Promise<WorkflowAddOutput> {
   let text: string;
   try {
     text = await readFile(filePath, "utf8");

packages/workflow-agent-claude-code/package.json

@@ -22,7 +22,8 @@
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.4.0",
-    "@uncaged/workflow-agent-kit": "workspace:^"
+    "@uncaged/workflow-agent-kit": "workspace:^",
+    "@uncaged/workflow-util": "workspace:^"
   },
   "devDependencies": {
     "typescript": "^5.8.3"

packages/workflow-agent-claude-code/src/claude-code.ts

@@ -146,13 +146,13 @@ async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
 
   // 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);
+    const cachedSessionId = await getCachedSessionId("claude-code", ctx.threadId, ctx.role);
     if (cachedSessionId !== null) {
       try {
         const { stdout } = await spawnClaudeResume(cachedSessionId, fullPrompt);
         const result = await processClaudeOutput(stdout, ctx.store);
         if (result.sessionId !== undefined && result.sessionId !== "") {
-          await setCachedSessionId(ctx.threadId, ctx.role, result.sessionId);
+          await setCachedSessionId("claude-code", ctx.threadId, ctx.role, result.sessionId);
         }
         return result;
       } catch (err) {
@@ -169,7 +169,7 @@ async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
   const { stdout } = await spawnClaudeRun(fullPrompt);
   const result = await processClaudeOutput(stdout, ctx.store);
   if (result.sessionId !== undefined && result.sessionId !== "") {
-    await setCachedSessionId(ctx.threadId, ctx.role, result.sessionId);
+    await setCachedSessionId("claude-code", ctx.threadId, ctx.role, result.sessionId);
   }
   return result;
 }

packages/workflow-agent-hermes/__tests__/hermes-prompt.test.ts

@@ -23,7 +23,7 @@ function makeCtx(overrides: Partial<AgentContext> = {}): AgentContext {
       graph: {},
     },
     role: "developer",
-    start: { prompt: "Fix the bug", workflowHash: "abc123", threadId: "t1" },
+    start: { prompt: "Fix the bug", workflow: "abc123" },
     steps: [],
     store: {} as AgentContext["store"],
     outputFormatInstruction: "Use YAML frontmatter",
@@ -55,6 +55,7 @@ describe("buildHermesPrompt", () => {
           agent: "uwf-hermes",
           detail: "detail-1",
           edgePrompt: "Implement the fix.",
+          content: null,
         },
         {
           role: "reviewer",
@@ -62,6 +63,7 @@ describe("buildHermesPrompt", () => {
           agent: "uwf-hermes",
           detail: "detail-2",
           edgePrompt: "Review the code.",
+          content: null,
         },
       ],
     });
@@ -85,6 +87,7 @@ describe("buildHermesPrompt", () => {
             agent: "uwf-hermes",
             detail: "detail-1",
             edgePrompt: "First attempt.",
+            content: null,
           },
         ],
         edgePrompt: "Retry with a fresh approach.",
@@ -95,4 +98,90 @@ describe("buildHermesPrompt", () => {
     expect(result).toContain("Retry with a fresh approach.");
     expect(result).not.toContain("## What Happened Since Your Last Turn");
   });
+
+  test("first visit includes content from previous steps", () => {
+    const ctx = makeCtx({
+      isFirstVisit: true,
+      steps: [
+        {
+          role: "planner",
+          output: { plan: "hash1" },
+          agent: "uwf-hermes",
+          detail: "detail-1",
+          edgePrompt: "Create the plan.",
+          content: "# Plan\nDetailed plan markdown...",
+        },
+        {
+          role: "developer",
+          output: { files: ["app.ts"] },
+          agent: "uwf-hermes",
+          detail: "detail-2",
+          edgePrompt: "Implement the code.",
+          content: "# Implementation\nCode changes...",
+        },
+        {
+          role: "reviewer",
+          output: { approved: true },
+          agent: "uwf-hermes",
+          detail: "detail-3",
+          edgePrompt: "Review the work.",
+          content: "# Review\nApproved!",
+        },
+      ],
+      role: "committer",
+      edgePrompt: "Commit the reviewed code.",
+    });
+
+    const result = buildHermesPrompt(ctx);
+
+    expect(result).toContain("Use YAML frontmatter");
+    expect(result).toContain("## Task");
+    expect(result).toContain("Fix the bug");
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("### Step 1: planner");
+    expect(result).toContain("#### Step Content");
+    expect(result).toContain("# Plan");
+    expect(result).toContain("Detailed plan markdown");
+    expect(result).toContain("### Step 2: developer");
+    expect(result).toContain("# Implementation");
+    expect(result).toContain("### Step 3: reviewer");
+    expect(result).toContain("# Review");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("Commit the reviewed code.");
+  });
+
+  test("re-entry omits content from previous steps", () => {
+    const ctx = makeCtx({
+      isFirstVisit: false,
+      steps: [
+        {
+          role: "developer",
+          output: { files: ["app.ts"] },
+          agent: "uwf-hermes",
+          detail: "detail-1",
+          edgePrompt: "Implement the code.",
+          content: "# Implementation\nCode changes...",
+        },
+        {
+          role: "reviewer",
+          output: { approved: false },
+          agent: "uwf-hermes",
+          detail: "detail-2",
+          edgePrompt: "Review the work.",
+          content: "# Review\nNot approved!",
+        },
+      ],
+      role: "developer",
+      edgePrompt: "Fix the issues.",
+    });
+
+    const result = buildHermesPrompt(ctx);
+
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("### Step 2: reviewer");
+    expect(result).toContain(JSON.stringify({ approved: false }));
+    expect(result).not.toContain("#### Step Content");
+    expect(result).not.toContain("# Review");
+    expect(result).not.toContain("Not approved!");
+  });
 });

packages/workflow-agent-hermes/src/hermes.ts

@@ -14,53 +14,39 @@ import { storeHermesSessionDetail } from "./session-detail.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
 
-function buildHistorySummary(steps: AgentContext["steps"]): string {
-  if (steps.length === 0) {
-    return "";
-  }
-
-  const lines: string[] = ["## Previous Steps"];
-  for (let i = 0; i < steps.length; i++) {
-    const step = steps[i];
-    if (step === undefined) {
-      continue;
-    }
-    lines.push("");
-    lines.push(`### Step ${i + 1}: ${step.role}`);
-    lines.push(`Output: ${JSON.stringify(step.output)}`);
-    lines.push(`Agent: ${step.agent}`);
-  }
-  return lines.join("\n");
-}
-
-function buildInitialPrompt(ctx: AgentContext): string {
-  const roleDef = ctx.workflow.roles[ctx.role];
-  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+/** Assemble system prompt, task, and prior step outputs for Hermes. */
+export function buildHermesPrompt(ctx: AgentContext): string {
   const parts: string[] = [];
+
   if (ctx.outputFormatInstruction !== "") {
     parts.push(ctx.outputFormatInstruction, "");
   }
-  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
-  const historyBlock = buildHistorySummary(ctx.steps);
-  if (historyBlock !== "") {
-    parts.push("", historyBlock);
-  }
-  parts.push("", "## Moderator Instruction", "", ctx.edgePrompt);
-  return parts.join("\n");
-}
 
-/** Assemble system prompt, task, and prior step outputs for Hermes. */
-export function buildHermesPrompt(ctx: AgentContext): string {
   if (!ctx.isFirstVisit) {
-    const parts: string[] = [];
-    if (ctx.outputFormatInstruction !== "") {
-      parts.push(ctx.outputFormatInstruction, "");
-    }
+    // Re-entry: show only steps since last visit, meta only
     parts.push(buildContinuationPrompt(ctx.steps, ctx.role, ctx.edgePrompt));
     return parts.join("\n");
   }
 
-  return buildInitialPrompt(ctx);
+  // First visit: show initial context with content for recent steps
+  const roleDef = ctx.workflow.roles[ctx.role];
+  const rolePrompt = roleDef !== undefined ? buildRolePrompt(roleDef) : "";
+  parts.push(rolePrompt, "", "## Task", ctx.start.prompt);
+
+  // Add history with content (last 2-3 steps within quota)
+  if (ctx.steps.length > 0) {
+    parts.push(
+      "",
+      buildContinuationPrompt(ctx.steps, ctx.role, ctx.edgePrompt, {
+        includeContent: true,
+        quota: 32000, // Use THREAD_READ_DEFAULT_QUOTA equivalent
+      }),
+    );
+  } else {
+    parts.push("", "## Moderator Instruction", "", ctx.edgePrompt);
+  }
+
+  return parts.join("\n");
 }
 
 async function storePromptResult(

packages/workflow-agent-hermes/src/session-cache.ts

@@ -1,5 +1,22 @@
-// Re-export session cache from the shared agent-kit package.
-export { getCachedSessionId, setCachedSessionId } from "@uncaged/workflow-agent-kit";
+// Re-export session cache from the shared agent-kit package with agent name injected.
+
+import {
+  getCachedSessionId as getCachedSessionIdBase,
+  setCachedSessionId as setCachedSessionIdBase,
+} from "@uncaged/workflow-agent-kit";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+
+export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
+  return getCachedSessionIdBase("hermes", threadId, role);
+}
+
+export async function setCachedSessionId(
+  threadId: ThreadId,
+  role: string,
+  sessionId: string,
+): Promise<void> {
+  return setCachedSessionIdBase("hermes", threadId, role, sessionId);
+}
 
 export function isResumeDisabled(): boolean {
   // Hermes ACP session/resume is broken: _restore fails for custom providers

packages/workflow-agent-kit/__tests__/build-continuation-prompt.test.ts

@@ -8,6 +8,7 @@ const reviewerStep: StepContext = {
   detail: "2MXBG6PN4A8JR",
   agent: "uwf-hermes",
   edgePrompt: "Review the developer's work.",
+  content: null,
 };
 
 const developerStep: StepContext = {
@@ -16,6 +17,7 @@ const developerStep: StepContext = {
   detail: "1VPBG9SM5E7WK",
   agent: "uwf-hermes",
   edgePrompt: "Implement the fix.",
+  content: null,
 };
 
 describe("buildContinuationPrompt", () => {
@@ -29,6 +31,7 @@ describe("buildContinuationPrompt", () => {
         detail: "7BQST3VW9F2MA",
         agent: "uwf-hermes",
         edgePrompt: "Revise the plan.",
+        content: null,
       },
     ];
 
@@ -70,4 +73,162 @@ describe("buildContinuationPrompt", () => {
     expect(result).toContain("## Moderator Instruction");
     expect(result).toContain("Please revise your work.");
   });
+
+  test("includes step content when includeContent option is true", () => {
+    const stepsWithContent: StepContext[] = [
+      {
+        role: "planner",
+        output: { plan: "hash123" },
+        detail: "detail1",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Plan\nDetailed plan markdown...",
+      },
+      {
+        role: "developer",
+        output: { filesChanged: ["app.ts"] },
+        detail: "detail2",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Implementation\nCode changes...",
+      },
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "detail3",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Review\nFeedback...",
+      },
+    ];
+
+    const result = buildContinuationPrompt(stepsWithContent, "committer", "Commit the changes.", {
+      includeContent: true,
+    });
+
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("### Step 1: planner");
+    expect(result).toContain("#### Step Content");
+    expect(result).toContain("# Plan");
+    expect(result).toContain("Detailed plan markdown");
+    expect(result).toContain("### Step 2: developer");
+    expect(result).toContain("# Implementation");
+    expect(result).toContain("### Step 3: reviewer");
+    expect(result).toContain("# Review");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("Commit the changes.");
+  });
+
+  test("omits step content when includeContent is false (default)", () => {
+    const stepsWithContent: StepContext[] = [
+      {
+        role: "developer",
+        output: { filesChanged: ["app.ts"] },
+        detail: "detail1",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Implementation\nCode changes...",
+      },
+      {
+        role: "reviewer",
+        output: { approved: false },
+        detail: "detail2",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Review\nFeedback...",
+      },
+    ];
+
+    const result = buildContinuationPrompt(stepsWithContent, "developer", "Fix the issues.");
+
+    expect(result).toContain("## What Happened Since Your Last Turn");
+    expect(result).toContain("### Step 2: reviewer");
+    expect(result).toContain(JSON.stringify(stepsWithContent[1]?.output));
+    expect(result).not.toContain("#### Step Content");
+    expect(result).not.toContain("# Review");
+  });
+
+  test("respects quota when includeContent is true", () => {
+    const largeContent = "x".repeat(5000);
+    const stepsWithContent: StepContext[] = [
+      {
+        role: "planner",
+        output: { plan: "hash1" },
+        detail: "detail1",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: largeContent,
+      },
+      {
+        role: "developer",
+        output: { files: ["app.ts"] },
+        detail: "detail2",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: largeContent,
+      },
+      {
+        role: "reviewer",
+        output: { approved: true },
+        detail: "detail3",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Review\nLooks good!",
+      },
+    ];
+
+    const result = buildContinuationPrompt(stepsWithContent, "committer", "Commit the changes.", {
+      includeContent: true,
+      quota: 1000,
+    });
+
+    // Should include most recent step(s) within quota
+    expect(result).toContain("### Step 1: reviewer"); // Showing 1 of 3, so step 3 becomes step 1
+    expect(result).toContain("#### Step Content");
+    expect(result).toContain("## Moderator Instruction");
+    expect(result).toContain("Showing 1 of 3 steps (2 omitted due to quota)");
+  });
+
+  test("handles null content gracefully when includeContent is true", () => {
+    const stepsWithMixedContent: StepContext[] = [
+      {
+        role: "planner",
+        output: { plan: "hash1" },
+        detail: "detail1",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Plan\nDetails...",
+      },
+      {
+        role: "developer",
+        output: { files: ["app.ts"] },
+        detail: "detail2",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: null, // No content available
+      },
+      {
+        role: "reviewer",
+        output: { approved: true },
+        detail: "detail3",
+        agent: "uwf-hermes",
+        edgePrompt: "",
+        content: "# Review\nApproved!",
+      },
+    ];
+
+    const result = buildContinuationPrompt(
+      stepsWithMixedContent,
+      "committer",
+      "Commit the changes.",
+      { includeContent: true },
+    );
+
+    expect(result).toContain("### Step 1: planner");
+    expect(result).toContain("# Plan");
+    expect(result).toContain("### Step 2: developer");
+    // Step 2 should not have content section since content is null
+    expect(result).toContain("### Step 3: reviewer");
+    expect(result).toContain("# Review");
+  });
 });

packages/workflow-agent-kit/__tests__/context.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+
+// We need to test buildHistory indirectly through buildContext
+// since buildHistory is not exported. For now, we'll test the integration
+// through the public API in a separate integration test.
+
+describe("context module - content extraction", () => {
+  test("placeholder - content extraction will be tested via integration tests", () => {
+    // This test is a placeholder. The actual testing of content extraction
+    // will be done through integration tests in build-continuation-prompt.test.ts
+    // where we can verify that StepContext objects have the correct content field.
+    expect(true).toBe(true);
+  });
+});

packages/workflow-agent-kit/__tests__/session-cache.test.ts

@@ -0,0 +1,247 @@
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+
+import { getCachedSessionId, getCachePath, setCachedSessionId } from "../src/session-cache.js";
+import { resolveStorageRoot } from "../src/storage.js";
+
+describe("session-cache", () => {
+  let originalStorageRoot: string;
+  let testStorageRoot: string;
+
+  beforeEach(async () => {
+    // Create a temporary test storage root
+    originalStorageRoot = resolveStorageRoot();
+    testStorageRoot = join(originalStorageRoot, "test-cache", `test-${Date.now()}`);
+    await mkdir(testStorageRoot, { recursive: true });
+
+    // Override the storage root for testing
+    process.env.WORKFLOW_STORAGE_ROOT = testStorageRoot;
+  });
+
+  afterEach(async () => {
+    // Clean up test storage root
+    await rm(testStorageRoot, { recursive: true, force: true });
+    delete process.env.WORKFLOW_STORAGE_ROOT;
+  });
+
+  describe("getCachePath", () => {
+    test("returns agent-specific file path", () => {
+      const path = getCachePath("claude-code");
+      expect(path).toMatch(/\/cache\/claude-code-sessions\.json$/);
+    });
+
+    test("returns different paths for different agents", () => {
+      const pathClaudeCode = getCachePath("claude-code");
+      const pathHermes = getCachePath("hermes");
+
+      expect(pathClaudeCode).not.toBe(pathHermes);
+      expect(pathClaudeCode).toMatch(/claude-code-sessions\.json$/);
+      expect(pathHermes).toMatch(/hermes-sessions\.json$/);
+    });
+
+    test("handles agent names with special characters", () => {
+      const path1 = getCachePath("my-agent");
+      const path2 = getCachePath("my_agent");
+
+      expect(path1).toMatch(/my-agent-sessions\.json$/);
+      expect(path2).toMatch(/my_agent-sessions\.json$/);
+    });
+  });
+
+  describe("session isolation", () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    test("sessions are isolated per agent", async () => {
+      // Cache different session IDs for each agent
+      await setCachedSessionId("claude-code", threadId, role, "session-cc-001");
+      await setCachedSessionId("hermes", threadId, role, "session-hermes-001");
+
+      // Each agent should retrieve its own session ID
+      const sessionCC = await getCachedSessionId("claude-code", threadId, role);
+      const sessionHermes = await getCachedSessionId("hermes", threadId, role);
+
+      expect(sessionCC).toBe("session-cc-001");
+      expect(sessionHermes).toBe("session-hermes-001");
+    });
+
+    test("updating one agent's cache does not affect another", async () => {
+      // Set initial sessions for both agents
+      await setCachedSessionId("claude-code", threadId, role, "session-cc-001");
+      await setCachedSessionId("hermes", threadId, role, "session-hermes-001");
+
+      // Update claude-code's session
+      await setCachedSessionId("claude-code", threadId, role, "session-cc-002");
+
+      // Hermes's session should remain unchanged
+      const sessionHermes = await getCachedSessionId("hermes", threadId, role);
+      expect(sessionHermes).toBe("session-hermes-001");
+
+      // Claude-code should have the new session
+      const sessionCC = await getCachedSessionId("claude-code", threadId, role);
+      expect(sessionCC).toBe("session-cc-002");
+    });
+
+    test("missing session returns null for specific agent", async () => {
+      const session = await getCachedSessionId("claude-code", threadId, role);
+      expect(session).toBeNull();
+    });
+
+    test("empty session ID is treated as missing", async () => {
+      await setCachedSessionId("claude-code", threadId, role, "");
+
+      const session = await getCachedSessionId("claude-code", threadId, role);
+      expect(session).toBeNull();
+    });
+  });
+
+  describe("file system operations", () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    test("cache directory is created if missing", async () => {
+      const cachePath = getCachePath("claude-code");
+      const cacheDir = dirname(cachePath);
+
+      // Ensure cache dir doesn't exist
+      await rm(cacheDir, { recursive: true, force: true });
+
+      // Write a session
+      await setCachedSessionId("claude-code", threadId, role, "session-001");
+
+      // Cache directory should be created
+      const stats = await stat(cacheDir);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    test("multiple agents create separate cache files", async () => {
+      // Cache sessions for multiple agents
+      await setCachedSessionId("claude-code", threadId, role, "session-cc-001");
+      await setCachedSessionId("hermes", threadId, role, "session-hermes-001");
+
+      // Separate cache files should exist
+      const pathCC = getCachePath("claude-code");
+      const pathHermes = getCachePath("hermes");
+
+      const contentCC = JSON.parse(await readFile(pathCC, "utf8")) as Record<string, string>;
+      const contentHermes = JSON.parse(await readFile(pathHermes, "utf8")) as Record<
+        string,
+        string
+      >;
+
+      expect(contentCC).toHaveProperty(`${threadId}:${role}`, "session-cc-001");
+      expect(contentHermes).toHaveProperty(`${threadId}:${role}`, "session-hermes-001");
+    });
+
+    test("atomic writes prevent partial reads", async () => {
+      // Write a session
+      await setCachedSessionId("claude-code", threadId, role, "session-001");
+
+      // The final file should exist (no .tmp files left behind)
+      const cachePath = getCachePath("claude-code");
+      const dir = dirname(cachePath);
+      const files = await readdir(dir);
+
+      expect(files).toContain("claude-code-sessions.json");
+      expect(files.every((f) => !f.endsWith(".tmp"))).toBe(true);
+    });
+  });
+
+  describe("legacy migration", () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    test("old agent-sessions.json is ignored", async () => {
+      // Create old agent-sessions.json file
+      const oldCachePath = join(resolveStorageRoot(), "cache", "agent-sessions.json");
+      await mkdir(dirname(oldCachePath), { recursive: true });
+      await writeFile(
+        oldCachePath,
+        JSON.stringify({
+          "01234567890123456789012345:developer": "old-session-001",
+        }),
+        "utf8",
+      );
+
+      // Query with the new per-agent cache
+      const session = await getCachedSessionId("claude-code", threadId, role);
+
+      // Should return null (old cache is ignored)
+      expect(session).toBeNull();
+    });
+
+    test("new per-agent cache takes precedence", async () => {
+      // Create both old and new cache files
+      const oldPath = join(resolveStorageRoot(), "cache", "agent-sessions.json");
+      await mkdir(dirname(oldPath), { recursive: true });
+      await writeFile(
+        oldPath,
+        JSON.stringify({
+          [`${threadId}:${role}`]: "old-session",
+        }),
+        "utf8",
+      );
+
+      await setCachedSessionId("claude-code", threadId, role, "new-session");
+
+      // The new per-agent cache value should be returned
+      const session = await getCachedSessionId("claude-code", threadId, role);
+      expect(session).toBe("new-session");
+    });
+  });
+
+  describe("error handling", () => {
+    const threadId = "01234567890123456789012345" as ThreadId;
+    const role = "developer";
+
+    test("invalid JSON in cache file returns empty cache", async () => {
+      // Create a corrupted cache file
+      const cachePath = getCachePath("claude-code");
+      await mkdir(dirname(cachePath), { recursive: true });
+      await writeFile(cachePath, "{ invalid json }", "utf8");
+
+      // Should return null (treating corrupted cache as empty)
+      const session = await getCachedSessionId("claude-code", threadId, role);
+      expect(session).toBeNull();
+    });
+
+    test("non-object JSON in cache file returns empty cache", async () => {
+      // Create a cache file with non-object JSON
+      const cachePath = getCachePath("claude-code");
+      await mkdir(dirname(cachePath), { recursive: true });
+      await writeFile(cachePath, JSON.stringify(["not", "an", "object"]), "utf8");
+
+      // Should return null
+      const session = await getCachedSessionId("claude-code", threadId, role);
+      expect(session).toBeNull();
+    });
+
+    test("cache entries with non-string values are ignored", async () => {
+      // Create a cache file with mixed types
+      const cachePath = getCachePath("claude-code");
+      const cacheData = {
+        "thread1:role1": "valid-session",
+        "thread2:role2": 12345, // number
+        "thread3:role3": null, // null
+        "thread4:role4": "", // empty string
+      };
+      await mkdir(dirname(cachePath), { recursive: true });
+      await writeFile(cachePath, JSON.stringify(cacheData), "utf8");
+
+      // Valid string entries should be returned
+      const session1 = await getCachedSessionId("claude-code", "thread1" as ThreadId, "role1");
+      expect(session1).toBe("valid-session");
+
+      // Invalid entries should return null
+      const session2 = await getCachedSessionId("claude-code", "thread2" as ThreadId, "role2");
+      const session3 = await getCachedSessionId("claude-code", "thread3" as ThreadId, "role3");
+      const session4 = await getCachedSessionId("claude-code", "thread4" as ThreadId, "role4");
+
+      expect(session2).toBeNull();
+      expect(session3).toBeNull();
+      expect(session4).toBeNull(); // empty string is treated as missing
+    });
+  });
+});

packages/workflow-agent-kit/src/build-continuation-prompt.ts

@@ -1,11 +1,20 @@
 import type { StepContext } from "@uncaged/workflow-protocol";
 
-function formatStep(step: StepContext, stepNumber: number): string {
-  return [
+function formatStep(step: StepContext, stepNumber: number, includeContent: boolean): string {
+  const lines = [
     `### Step ${stepNumber}: ${step.role}`,
     `Output: ${JSON.stringify(step.output)}`,
     `Agent: ${step.agent}`,
-  ].join("\n");
+  ];
+
+  if (includeContent && step.content !== null) {
+    lines.push("");
+    lines.push("#### Step Content");
+    lines.push("");
+    lines.push(step.content);
+  }
+
+  return lines.join("\n");
 }
 
 function findLastRoleIndex(steps: StepContext[], role: string): number {
@@ -18,6 +27,45 @@ function findLastRoleIndex(steps: StepContext[], role: string): number {
   return -1;
 }
 
+function selectStepsWithinQuota(steps: StepContext[], quota: number): StepContext[] {
+  const selected: StepContext[] = [];
+  let totalChars = 0;
+
+  // Work backwards (newest first)
+  for (let i = steps.length - 1; i >= 0; i--) {
+    const step = steps[i];
+    if (step === undefined) continue;
+
+    // Estimate size: meta + content
+    const metaSize = JSON.stringify({
+      role: step.role,
+      output: step.output,
+      agent: step.agent,
+    }).length;
+    const contentSize = step.content?.length ?? 0;
+    const stepSize = metaSize + contentSize;
+
+    if (totalChars + stepSize > quota && selected.length > 0) {
+      // Stop adding steps but keep at least 1
+      break;
+    }
+
+    selected.unshift(step); // Keep chronological order
+    totalChars += stepSize;
+
+    if (totalChars >= quota) {
+      break;
+    }
+  }
+
+  return selected;
+}
+
+type BuildContinuationPromptOptions = {
+  includeContent?: boolean;
+  quota?: number;
+};
+
 /**
  * Build a continuation prompt for a role re-entry.
  *
@@ -28,7 +76,11 @@ export function buildContinuationPrompt(
   steps: StepContext[],
   role: string,
   edgePrompt: string,
+  options?: BuildContinuationPromptOptions,
 ): string {
+  const includeContent = options?.includeContent ?? false;
+  const quota = options?.quota ?? Number.POSITIVE_INFINITY;
+
   const lastIndex = findLastRoleIndex(steps, role);
   const sinceSteps = lastIndex >= 0 ? steps.slice(lastIndex + 1) : steps;
 
@@ -37,13 +89,25 @@ export function buildContinuationPrompt(
   if (sinceSteps.length > 0) {
     parts.push("## What Happened Since Your Last Turn");
     const baseStepNumber = lastIndex >= 0 ? lastIndex + 2 : 1;
-    for (let i = 0; i < sinceSteps.length; i++) {
-      const step = sinceSteps[i];
+
+    // Select steps within quota (newest-first if includeContent = true)
+    const selectedSteps = includeContent ? selectStepsWithinQuota(sinceSteps, quota) : sinceSteps;
+
+    const skippedCount = sinceSteps.length - selectedSteps.length;
+    if (skippedCount > 0) {
+      parts.push("");
+      parts.push(
+        `_Showing ${selectedSteps.length} of ${sinceSteps.length} steps (${skippedCount} omitted due to quota)_`,
+      );
+    }
+
+    for (let i = 0; i < selectedSteps.length; i++) {
+      const step = selectedSteps[i];
       if (step === undefined) {
         continue;
       }
       parts.push("");
-      parts.push(formatStep(step, baseStepNumber + i));
+      parts.push(formatStep(step, baseStepNumber + i, includeContent));
     }
     parts.push("");
   }

packages/workflow-agent-kit/src/context.ts

@@ -82,6 +82,38 @@ function expandOutput(store: Store, outputRef: CasRef): unknown {
   return node.payload;
 }
 
+function extractStepContent(store: Store, detailRef: CasRef): string | null {
+  const detailNode = store.get(detailRef);
+  if (detailNode === null) {
+    return null;
+  }
+  const detail = detailNode.payload as Record<string, unknown>;
+  const turns = detail.turns;
+  if (!Array.isArray(turns) || turns.length === 0) {
+    return null;
+  }
+  // Find last assistant content (same logic as extractLastAssistantContent in cli-workflow)
+  for (let i = turns.length - 1; i >= 0; i--) {
+    const turnRef = turns[i];
+    if (typeof turnRef !== "string") {
+      continue;
+    }
+    const turnNode = store.get(turnRef as CasRef);
+    if (turnNode === null) {
+      continue;
+    }
+    const turn = turnNode.payload as Record<string, unknown>;
+    if (
+      turn.role === "assistant" &&
+      typeof turn.content === "string" &&
+      turn.content.trim() !== ""
+    ) {
+      return turn.content;
+    }
+  }
+  return null;
+}
+
 async function buildHistory(
   store: Store,
   stepsNewestFirst: StepNodePayload[],
@@ -89,12 +121,14 @@ async function buildHistory(
   const chronological = [...stepsNewestFirst].reverse();
   const history: StepContext[] = [];
   for (const step of chronological) {
+    const content = extractStepContent(store, step.detail);
     history.push({
       role: step.role,
       output: expandOutput(store, step.output),
       detail: step.detail,
       agent: step.agent,
       edgePrompt: step.edgePrompt ?? "",
+      content,
     });
   }
   return history;

packages/workflow-agent-kit/src/index.ts

@@ -12,7 +12,7 @@ export {
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
 export { createAgent } from "./run.js";
-export { getCachedSessionId, setCachedSessionId } from "./session-cache.js";
+export { getCachedSessionId, getCachePath, setCachedSessionId } from "./session-cache.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
 export type {
   AgentContext,

packages/workflow-agent-kit/src/session-cache.ts

@@ -8,8 +8,8 @@ import { resolveStorageRoot } from "./storage.js";
 
 type SessionCache = Record<string, string>;
 
-function getCachePath(): string {
-  return join(resolveStorageRoot(), "cache", "agent-sessions.json");
+export function getCachePath(agentName: string): string {
+  return join(resolveStorageRoot(), "cache", `${agentName}-sessions.json`);
 }
 
 function cacheKey(threadId: ThreadId, role: string): string {
@@ -20,8 +20,8 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-async function readCache(): Promise<SessionCache> {
-  const path = getCachePath();
+async function readCache(agentName: string): Promise<SessionCache> {
+  const path = getCachePath(agentName);
   try {
     const text = await readFile(path, "utf8");
     const raw = JSON.parse(text) as unknown;
@@ -40,36 +40,45 @@ async function readCache(): Promise<SessionCache> {
     if (err.code === "ENOENT") {
       return {};
     }
+    // Treat JSON parse errors as empty cache
+    if (err.name === "SyntaxError") {
+      return {};
+    }
     throw e;
   }
 }
 
-async function writeCache(cache: SessionCache): Promise<void> {
-  const path = getCachePath();
+async function writeCache(agentName: string, cache: SessionCache): Promise<void> {
+  const path = getCachePath(agentName);
   const dir = dirname(path);
   await mkdir(dir, { recursive: true });
   // Atomic write: write to temp file then rename to avoid partial reads on concurrent access.
   // NOTE: Current workflow execution is serial (execFileSync), so true concurrency doesn't occur.
   // This is a safety net for future parallel execution.
-  const tmpPath = join(dir, `.agent-sessions.${randomBytes(4).toString("hex")}.tmp`);
+  const tmpPath = join(dir, `.${agentName}-sessions.${randomBytes(4).toString("hex")}.tmp`);
   await writeFile(tmpPath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
   await rename(tmpPath, path);
 }
 
 /** Read the cached session ID for a thread+role pair. */
-export async function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null> {
-  const cache = await readCache();
+export async function getCachedSessionId(
+  agentName: string,
+  threadId: ThreadId,
+  role: string,
+): Promise<string | null> {
+  const cache = await readCache(agentName);
   const sessionId = cache[cacheKey(threadId, role)];
   return sessionId ?? null;
 }
 
 /** Write the session ID for a thread+role pair into the cache. */
 export async function setCachedSessionId(
+  agentName: string,
   threadId: ThreadId,
   role: string,
   sessionId: string,
 ): Promise<void> {
-  const cache = await readCache();
+  const cache = await readCache(agentName);
   cache[cacheKey(threadId, role)] = sessionId;
-  await writeCache(cache);
+  await writeCache(agentName, cache);
 }

packages/workflow-dashboard/vitest.config.ts

@@ -1,7 +1,6 @@
 import path from "node:path";
 import { defineConfig } from "vitest/config";
 
-// biome-ignore lint/style/noDefaultExport: Vitest loads config from default export.
 export default defineConfig({
   test: {
     environment: "node",

packages/workflow-protocol/src/types.ts

@@ -63,6 +63,7 @@ export type StepNodePayload = StepRecord & {
 /** JSONata 上下文中的 step — output 被展开 */
 export type StepContext = Omit<StepRecord, "output"> & {
   output: unknown;
+  content: string | null;
 };
 
 export type ModeratorContext = {

packages/workflow-util-agent/src/build-agent-prompt.ts

@@ -0,0 +1,64 @@
+import type { AgentContext } from "@uncaged/workflow-runtime";
+
+/** Max characters of step content to include in the prompt. */
+const CONTENT_QUOTA = 16_000;
+
+/** Builds the full agent prompt: system instructions plus summarized thread history. */
+export async function buildAgentPrompt(ctx: AgentContext): Promise<string> {
+  const lines: string[] = [];
+  lines.push(ctx.currentRole.systemPrompt);
+  lines.push("");
+  lines.push("## Task");
+  lines.push(ctx.start.content);
+
+  const { steps } = ctx;
+  if (steps.length === 0) {
+    return lines.join("\n");
+  }
+
+  if (steps.length === 1) {
+    const s = steps[0];
+    lines.push("");
+    lines.push(`## Step: ${s.role}`);
+    lines.push("");
+    lines.push(`Meta: ${JSON.stringify(s.meta)}`);
+    appendContent(lines, s.content);
+  } else {
+    lines.push("");
+    lines.push("## Previous Steps");
+    for (let i = 0; i < steps.length - 1; i++) {
+      const s = steps[i];
+      lines.push("");
+      lines.push(`### Step ${i + 1}: ${s.role}`);
+      lines.push(`Summary: ${JSON.stringify(s.meta)}`);
+    }
+    const last = steps[steps.length - 1];
+    lines.push("");
+    lines.push(`## Latest Step: ${last.role}`);
+    lines.push("");
+    lines.push(`Meta: ${JSON.stringify(last.meta)}`);
+    appendContent(lines, last.content);
+  }
+
+  lines.push("");
+  lines.push("## Tools");
+  lines.push(
+    `Use \`uncaged-workflow thread ${ctx.threadId}\` to read full details of any previous step.`,
+  );
+
+  return lines.join("\n");
+}
+
+function appendContent(lines: string[], content: string | null | undefined): void {
+  if (content === null || content === undefined || content.trim() === "") {
+    return;
+  }
+  const truncated =
+    content.length > CONTENT_QUOTA
+      ? `${content.slice(0, CONTENT_QUOTA)}\n... (truncated)`
+      : content;
+  lines.push("");
+  lines.push("<output>");
+  lines.push(truncated);
+  lines.push("</output>");
+}

packages/workflow-util/src/__tests__/ulid-timestamp.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "bun:test";
+import { extractUlidTimestamp, generateUlid } from "../ulid.js";
+
+describe("extractUlidTimestamp", () => {
+  it("should extract correct timestamp from ULID", () => {
+    const knownTimestamp = Date.UTC(2026, 4, 20, 0, 0, 0);
+    const ulid = generateUlid(knownTimestamp);
+    const extracted = extractUlidTimestamp(ulid);
+    expect(extracted).toBe(knownTimestamp);
+  });
+
+  it("should handle epoch timestamp (timestamp 0)", () => {
+    const ulid = generateUlid(0);
+    const extracted = extractUlidTimestamp(ulid);
+    expect(extracted).toBe(0);
+  });
+
+  it("should handle recent timestamps", () => {
+    const recentTimestamp = Date.now();
+    const ulid = generateUlid(recentTimestamp);
+    const extracted = extractUlidTimestamp(ulid);
+    expect(extracted).toBe(recentTimestamp);
+  });
+
+  it("should handle max 48-bit timestamp", () => {
+    const maxTimestamp = 2 ** 48 - 1;
+    const ulid = generateUlid(maxTimestamp);
+    const extracted = extractUlidTimestamp(ulid);
+    expect(extracted).toBe(maxTimestamp);
+  });
+
+  it("should return null for invalid ULID length", () => {
+    expect(extractUlidTimestamp("")).toBe(null);
+    expect(extractUlidTimestamp("TOOSHORT")).toBe(null);
+    expect(extractUlidTimestamp("TOOLONGAAAAAAAAAAAAAAAAAA")).toBe(null);
+  });
+
+  it("should return null for invalid Crockford Base32 characters", () => {
+    expect(extractUlidTimestamp("INVALID!@#$%^&CHARACTERS")).toBe(null);
+  });
+
+  it("should extract timestamps from multiple ULIDs correctly", () => {
+    const timestamps = [
+      Date.UTC(2020, 0, 1, 0, 0, 0),
+      Date.UTC(2023, 5, 15, 12, 30, 45),
+      Date.UTC(2026, 11, 31, 23, 59, 59),
+    ];
+
+    for (const ts of timestamps) {
+      const ulid = generateUlid(ts);
+      const extracted = extractUlidTimestamp(ulid);
+      expect(extracted).toBe(ts);
+    }
+  });
+});

packages/workflow-util/src/cli-reference.ts

@@ -15,7 +15,7 @@ uwf setup --provider <name> --base-url <url> \\
 ## Workflow Commands
 
 \`\`\`
-uwf workflow put <file>           # register a workflow from YAML file
+uwf workflow add <file>           # register a workflow from YAML file
 uwf workflow show <id>            # show workflow by name or CAS hash
 uwf workflow list                 # list all registered workflows
 \`\`\`
@@ -24,20 +24,27 @@ uwf workflow list                 # list all registered workflows
 
 \`\`\`
 uwf thread start <workflow> -p <prompt>           # create a thread (no execution)
-uwf thread step <thread-id>                       # execute one moderator→agent→extract cycle
+uwf thread exec <thread-id>                       # execute one moderator→agent→extract cycle
                [--agent <cmd>]                    # override agent command
                [-c, --count <number>]             # run multiple steps (default: 1)
+               [--background]                     # run in background
 uwf thread show <thread-id>                       # show thread head pointer
-uwf thread list                                   # list active threads
-               [--all]                            # include archived threads
-uwf thread kill <thread-id>                       # terminate and archive a thread
-uwf thread steps <thread-id>                      # list all steps in a thread
+uwf thread list                                   # list threads
+               [--status <status>]                # filter: idle, running, or completed
 uwf thread read <thread-id>                       # render thread context as markdown
                [--quota <chars>]                  # max output characters (default 32000)
                [--before <step-hash>]             # load steps before this hash (exclusive)
                [--start]                          # include start step in output
-uwf thread fork <step-hash>                       # fork a thread from a specific step
-uwf thread step-details <step-hash>               # dump full detail node of a step as YAML
+uwf thread stop <thread-id>                       # stop background execution (keep thread active)
+uwf thread cancel <thread-id>                     # cancel thread (stop + move to history)
+\`\`\`
+
+## Step Commands
+
+\`\`\`
+uwf step list <thread-id>        # list all steps in a thread
+uwf step show <step-hash>        # show details of a specific step
+uwf step fork <step-hash>        # fork a thread from a specific step
 \`\`\`
 
 ## CAS Commands
@@ -78,10 +85,9 @@ uwf -V, --version                 # print version
 ## Key Concepts
 
 - **Workflow**: YAML definition with roles, conditions, and a routing graph; stored as a CAS node identified by its XXH64 hash.
-- **Thread**: A single workflow execution (ULID). State is an immutable CAS chain; active threads are indexed in \`threads.yaml\`.
-- **Step**: One moderator→agent→extract cycle. Run \`uwf thread step\` repeatedly until \`$END\`.
-- **CAS**: Content-Addressed Storage — all nodes are immutable and identified by hash.
-- **Role**: Named actor with goal, capabilities, procedure, output, and frontmatter schema; the moderator routes between roles.
-- **Edge Prompt**: Required instruction on each graph edge — the moderator's dispatch message to the agent.
+- **Thread**: A running instance of a workflow; points to a chain of CAS step nodes.
+- **Step**: One moderator→agent→extract cycle; stored as a CAS node with output + detail refs.
+- **Turn**: Agent-internal interaction (within a single step); stored per-turn in the detail node.
+- **CAS**: Content-addressable store; every artifact (workflows, steps, details, turns) is hashed.
 `;
 }

packages/workflow-util/src/index.ts

@@ -24,4 +24,4 @@ export { normalizeRefsField } from "./refs-field.js";
 export { err, ok } from "./result.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
 export type { LogFn, Result } from "./types.js";
-export { generateUlid } from "./ulid.js";
+export { extractUlidTimestamp, generateUlid } from "./ulid.js";

packages/workflow-util/src/ulid.ts

@@ -1,4 +1,4 @@
-import { encodeCrockfordBase32Bits } from "./base32.js";
+import { decodeCrockfordBase32Bits, encodeCrockfordBase32Bits } from "./base32.js";
 
 const ULID_TIME_BITS = 48;
 const ULID_RANDOM_BITS = 80;
@@ -26,3 +26,19 @@ export function generateUlid(nowMs: number): string {
   const payload = (time << BigInt(ULID_RANDOM_BITS)) | rand;
   return encodeCrockfordBase32Bits(payload, ULID_TIME_BITS + ULID_RANDOM_BITS);
 }
+
+/**
+ * Extract the timestamp (in milliseconds) from a ULID string.
+ * Returns null if the ULID is invalid.
+ */
+export function extractUlidTimestamp(ulid: string): number | null {
+  if (ulid.length !== 26) {
+    return null;
+  }
+  const timestampPart = ulid.slice(0, 10);
+  const decoded = decodeCrockfordBase32Bits(timestampPart, ULID_TIME_BITS);
+  if (!decoded.ok) {
+    return null;
+  }
+  return Number(decoded.value);
+}