feat(cli): unify uwf CAS store with global json-cas store

This resolves issue #573 by moving uwf's CAS directory from
~/.uncaged/workflow/cas/ to the shared ~/.uncaged/json-cas/ location.

Changes:
- Added getGlobalCasDir() function with UNCAGED_CAS_DIR support
- Updated createUwfStore() to use global CAS directory
- Added comprehensive test coverage (11 new tests)
- Updated all existing tests for environment isolation
- Updated documentation (CLAUDE.md, README.md)

Benefits:
- Cross-tool visibility: json-cas CLI can read uwf-created nodes
- Schema sharing: both tools access same schema registry
- Future-proofing: enables json-cas render/verbose for uwf data

Fixes #573

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.changeset/env-api-unify.md

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

.changeset/fix-internal-deps.md

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

.changeset/fix-publish-src.md

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

.changeset/fix-workspace-deps.md

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

.changeset/pre.json

@@ -1,5 +1,5 @@
 {
-  "mode": "pre",
+  "mode": "exit",
   "tag": "alpha",
   "initialVersions": {
     "@uncaged/cli-workflow": "0.4.5",

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

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

.gitea/workflows/ci.yml

@@ -7,19 +7,20 @@ on:
     branches: [main]
 
 jobs:
-  test:
+  check:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - uses: oven-sh/setup-bun@v2
 
-      - name: Install dependencies
-        run: bun install
+      - run: bun install
 
-      - name: Check
+      - name: Build
+        run: bun run build
+
+      - name: Lint
         run: bun run check
 
       - name: Test
-        run: bun test
+        run: bun run test:ci

.plan/335-setup-validate.md

@@ -1,83 +0,0 @@
-# Test Spec: uwf setup model connectivity validation (#335)
-
-## Context
-
-File: `packages/cli-workflow/src/commands/setup.ts`
-Test file: `packages/cli-workflow/src/__tests__/setup-validate.test.ts`
-
-After `cmdSetup` writes config, it should send a test chat completion request to verify the configured model is reachable. If validation fails, warn the user (don't abort — config is already saved).
-
-## Implementation Notes
-
-- Add a `validateModel(baseUrl, apiKey, model)` function that sends a minimal chat completion request (`POST /chat/completions` with `messages: [{role:"user",content:"hi"}]`, `max_tokens: 1`)
-- Returns `Result<void, string>` — ok if 2xx response, error with reason string otherwise
-- Use `AbortSignal.timeout(15_000)` for the request
-- Both `cmdSetup` and `cmdSetupInteractive` should call it after saving config
-- `cmdSetup` returns validation result in its return object: `{ ...existing, validation: { ok: true } | { ok: false, error: string } }`
-- `cmdSetupInteractive` prints a warning to console if validation fails, success message if it passes
-- Use the project logger (`createLogger`) — no raw `console.log` except in interactive CLI output (per CLAUDE.md)
-
-## Test Cases (vitest)
-
-### 1. `validateModel` — success path
-- Mock `fetch` to return `{ status: 200, ok: true, json: () => ({}) }`
-- Call `validateModel(baseUrl, apiKey, model)`
-- Assert returns `{ ok: true, value: undefined }`
-- Assert fetch was called with correct URL (`${baseUrl}/chat/completions`), correct headers (`Authorization: Bearer ${apiKey}`), correct body (model, messages, max_tokens: 1)
-
-### 2. `validateModel` — HTTP error (401 unauthorized)
-- Mock `fetch` to return `{ status: 401, ok: false, statusText: "Unauthorized" }`
-- Call `validateModel(baseUrl, apiKey, model)`
-- Assert returns `{ ok: false, error: <string containing "401"> }`
-
-### 3. `validateModel` — HTTP error (404 model not found)
-- Mock `fetch` to return `{ status: 404, ok: false, statusText: "Not Found" }`
-- Assert returns `{ ok: false, error: <string containing "404"> }`
-
-### 4. `validateModel` — network timeout
-- Mock `fetch` to throw `DOMException` with name `AbortError`
-- Assert returns `{ ok: false, error: <string containing "timeout" or "unreachable"> }`
-
-### 5. `validateModel` — network error (DNS failure, connection refused)
-- Mock `fetch` to throw `TypeError("fetch failed")`
-- Assert returns `{ ok: false, error: <string mentioning connectivity> }`
-
-### 6. `cmdSetup` — includes validation result on success
-- Mock global `fetch` for `/chat/completions` to succeed
-- Call `cmdSetup({ provider, baseUrl, apiKey, model, storageRoot })`
-- Assert returned object has `validation: { ok: true, value: undefined }`
-- Assert config files are still written (existing behavior preserved)
-
-### 7. `cmdSetup` — includes validation result on failure (config still saved)
-- Mock global `fetch` for `/chat/completions` to return 401
-- Call `cmdSetup({ ... })`
-- Assert returned object has `validation: { ok: false, error: ... }`
-- Assert `config.yaml` and `.env` are still written (validation failure doesn't prevent saving)
-
-### 8. `cmdSetupInteractive` — prints success message on validation pass
-- Mock `fetch` for both `/models` and `/chat/completions` to succeed
-- Mock stdin to provide valid selections
-- Capture console output
-- Assert output contains a success message like "Model verified" or "✓"
-
-### 9. `cmdSetupInteractive` — prints warning on validation failure
-- Mock `fetch`: `/models` succeeds, `/chat/completions` returns 401
-- Mock stdin for valid selections
-- Capture console output
-- Assert output contains a warning about model not being reachable and suggests trying a different model
-
-### 10. `validateModel` — request body correctness
-- Mock `fetch` to capture the request body
-- Call `validateModel(baseUrl, apiKey, "test-model")`
-- Assert body is `{ model: "test-model", messages: [{role: "user", content: "hi"}], max_tokens: 1 }`
-
-## Export Requirements
-
-- `validateModel` must be exported (for direct unit testing)
-- Signature: `async function validateModel(baseUrl: string, apiKey: string, model: string): Promise<Result<void, string>>`
-- `Result` type: `{ ok: true; value: T } | { ok: false; error: E }` (project convention)
-
-## Files to Create/Modify
-
-- **New**: `packages/cli-workflow/src/__tests__/setup-validate.test.ts` — all test cases above
-- **Modify**: `packages/cli-workflow/src/commands/setup.ts` — add `validateModel`, integrate into `cmdSetup` and `cmdSetupInteractive`

.workflows/e2e-walkthrough.yaml

@@ -0,0 +1,269 @@
+name: "e2e-walkthrough"
+description: "End-to-end walkthrough of uwf CLI. Dogfooding: uwf tests uwf. Each role validates a phase of the CLI surface inside an isolated Docker container."
+roles:
+  bootstrap:
+    description: "Start Docker container with isolated storage, verify uwf is runnable"
+    goal: "You are an E2E test runner. Set up an isolated Docker environment and verify basic uwf functionality."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      1. Start a Docker container with isolated storage:
+         ```
+         docker run -d --name uwf-e2e-$$ \
+           -v $HOME:$HOME \
+           -e HOME=$HOME \
+           -e UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage \
+           -w ~/repos/workflow \
+           node:22-bookworm \
+           sleep infinity
+         ```
+      2. Inside the container, install bun, install deps, then `bun link` all packages
+         so that `uwf`, `uwf-hermes`, `uwf-builtin` are on PATH (from source):
+         ```
+         docker exec uwf-e2e-$$ bash -c '
+           # Install bun
+           curl -fsSL https://bun.sh/install | bash
+           export PATH="$HOME/.bun/bin:$PATH"
+
+           # Isolated storage
+           mkdir -p $UNCAGED_WORKFLOW_STORAGE_ROOT
+
+           # Install workspace deps
+           cd ~/repos/workflow && bun install --frozen-lockfile
+
+           # bun link each package that has a bin entry
+           cd packages/cli-workflow && bun link && cd ../..
+           cd packages/workflow-agent-hermes && bun link && cd ../..
+           cd packages/workflow-agent-builtin && bun link && cd ../..
+         '
+         ```
+      3. Verify all three commands are available inside the container:
+         ```
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf --version'
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf-hermes --help'
+         docker exec uwf-e2e-$$ bash -c 'export PATH="$HOME/.bun/bin:$PATH" && uwf-builtin --help'
+         ```
+      4. Copy host config if it exists:
+         ```
+         docker exec uwf-e2e-$$ bash -c '
+           if [ -f $HOME/.uncaged/workflow/config.yaml ]; then
+             cp $HOME/.uncaged/workflow/config.yaml $UNCAGED_WORKFLOW_STORAGE_ROOT/config.yaml
+           fi
+         '
+         ```
+
+      Report the container name and confirm uwf + agents are working.
+      Set containerName to the Docker container name for subsequent roles.
+    output: "Report uwf version and container readiness. Set $status to pass with containerName, or fail with error."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            containerName: { type: string }
+          required: [$status, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+          required: [$status, error]
+
+  config-and-registry:
+    description: "Validate uwf config commands and workflow registration"
+    goal: "You are an E2E test runner. Validate uwf config operations and workflow registration inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container from the previous step (containerName is in your prompt).
+      All commands run via: `docker exec <containerName> bash -c '...'`
+      All commands use `uwf` (installed via `bun link` inside the container).
+      Remember to set env vars in each exec:
+        export PATH="$HOME/.bun/bin:$PATH"
+        export UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Config tests:
+      1. `uwf config list` — verify it returns valid JSON
+      2. `uwf config set models.test.name test-model` — set a test key
+      3. `uwf config get models.test.name` — verify it returns "test-model"
+
+      Workflow registration tests:
+      4. `uwf workflow add ~/repos/workflow/examples/solve-issue.yaml` — register workflow
+      5. Verify the output contains a hash
+      6. `uwf workflow list` — verify non-empty array
+      7. Capture the workflow name from the list
+      8. `uwf workflow show <name>` — verify it returns roles
+
+      Report all test results with pass/fail counts.
+    output: "Report test results. Set $status to pass (with workflowName and containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  thread-ops:
+    description: "Test thread start, list, show, and exec"
+    goal: "You are an E2E test runner. Validate thread creation and execution inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container (containerName) and workflow (workflowName) from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      1. `uwf thread start <workflowName> -p 'E2E test: what is 2+2?'` — capture thread ID from JSON output
+      2. `uwf thread list` — verify the thread appears in the list
+      3. `uwf thread show <threadId>` — verify head pointer exists
+      4. `uwf thread exec <threadId> --agent uwf-builtin` — execute one step
+      5. Verify exec returns JSON with a head field
+
+      Report results. Pass threadId and containerName forward.
+    output: "Report test results. Set $status to pass (with threadId, workflowName, containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            threadId: { type: string }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, threadId, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  inspect:
+    description: "Test step list/show, thread read, and CAS operations"
+    goal: "You are an E2E test runner. Validate read and inspect operations inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use the container (containerName) and threadId from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Step inspection:
+      1. `uwf step list <threadId>` — verify steps array has length > 1
+      2. Capture the last step hash from the output
+      3. `uwf step show <lastStepHash>` — verify it returns a role field
+
+      Thread read:
+      4. `uwf thread read <threadId>` — verify non-empty output
+
+      CAS operations:
+      5. `uwf cas get <lastStepHash>` — verify returns a type field
+      6. `uwf cas has <lastStepHash>` — verify exits 0
+      7. `uwf cas refs <lastStepHash>` — list refs (may be empty)
+      8. `uwf cas walk <lastStepHash>` — verify returns non-empty array
+
+      Report results. Pass threadId, lastStepHash, workflowName, containerName forward.
+    output: "Report test results. Set $status to pass (with threadId, lastStepHash, workflowName, containerName) or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            threadId: { type: string }
+            lastStepHash: { type: string }
+            workflowName: { type: string }
+            containerName: { type: string }
+          required: [$status, threadId, lastStepHash, workflowName, containerName]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  cancel-and-fork:
+    description: "Test thread cancel, step fork, and log inspection"
+    goal: "You are an E2E test runner. Validate cancel, fork, and log operations inside the Docker container."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Use containerName, threadId, lastStepHash, and workflowName from your prompt.
+      All commands via: `docker exec <containerName> bash -c '...'`
+      Set env: PATH="$HOME/.bun/bin:$PATH" UNCAGED_WORKFLOW_STORAGE_ROOT=/tmp/uwf-e2e-storage
+
+      Cancel:
+      1. Start a second thread: `uwf thread start <workflowName> -p 'E2E cancel test'`
+      2. Cancel it: `uwf thread cancel <secondThreadId>`
+      3. Verify it appears in completed list: `uwf thread list --status completed`
+
+      Fork:
+      4. Fork from the first thread's last step: `uwf step fork <lastStepHash>`
+      5. Verify fork creates a new thread with a different ID
+
+      Logs:
+      6. `uwf log list` — verify output (may be empty)
+      7. `uwf log show --thread <threadId>` — verify runs without error
+
+      Report results with summary.
+    output: "Report test results with summary. Set $status to pass or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            containerName: { type: string }
+            summary: { type: string }
+          required: [$status, containerName, summary]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+            containerName: { type: string }
+          required: [$status, error, containerName]
+
+  cleanup:
+    description: "Remove Docker container"
+    goal: "You are an E2E test runner. Clean up the Docker container used for testing."
+    capabilities:
+      - docker
+      - shell
+    procedure: |
+      Remove the Docker container (containerName is in your prompt):
+      1. `docker rm -f <containerName>`
+      2. Verify the container is gone: `docker ps -a --filter name=<containerName> --format '{{.Names}}'` should return empty
+
+      Report cleanup result.
+    output: "Report cleanup result. Set $status to pass or fail."
+    frontmatter:
+      oneOf:
+        - properties:
+            $status: { const: "pass" }
+            summary: { type: string }
+          required: [$status, summary]
+        - properties:
+            $status: { const: "fail" }
+            error: { type: string }
+          required: [$status, error]
+
+graph:
+  $START:
+    _: { role: "bootstrap", prompt: "Set up the Docker container and verify uwf is runnable." }
+  bootstrap:
+    pass: { role: "config-and-registry", prompt: "Container {{{containerName}}} is ready. Validate config and workflow registration." }
+    fail: { role: "$END", prompt: "Bootstrap failed: {{{error}}}. No container was created." }
+  config-and-registry:
+    pass: { role: "thread-ops", prompt: "Config and registry OK. Workflow '{{{workflowName}}}' registered. Container: {{{containerName}}}. Now test thread operations." }
+    fail: { role: "cleanup", prompt: "Config/registry failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  thread-ops:
+    pass: { role: "inspect", prompt: "Thread ops OK. threadId={{{threadId}}}, workflowName={{{workflowName}}}, containerName={{{containerName}}}. Now test inspect operations." }
+    fail: { role: "cleanup", prompt: "Thread ops failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  inspect:
+    pass: { role: "cancel-and-fork", prompt: "Inspect OK. threadId={{{threadId}}}, lastStepHash={{{lastStepHash}}}, workflowName={{{workflowName}}}, containerName={{{containerName}}}. Now test cancel, fork, and logs." }
+    fail: { role: "cleanup", prompt: "Inspect failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  cancel-and-fork:
+    pass: { role: "cleanup", prompt: "All tests passed! {{{summary}}}. Clean up container {{{containerName}}}." }
+    fail: { role: "cleanup", prompt: "Cancel/fork failed: {{{error}}}. Clean up container {{{containerName}}}." }
+  cleanup:
+    pass: { role: "$END", prompt: "E2E walkthrough complete. {{{summary}}}" }
+    fail: { role: "$END", prompt: "Cleanup failed: {{{error}}}. Manual cleanup may be needed." }

BOOTSTRAP.md

@@ -0,0 +1,183 @@
+# UWF Bootstrap Guide
+
+This guide helps any AI agent set up `uwf` (Uncaged Workflow) from scratch — or self-check and upgrade an existing installation.
+
+## Prerequisites
+
+- **bun** — `uwf` is built with bun. Install: `curl -fsSL https://bun.sh/install | bash`
+- **Network access** — to install npm packages
+
+> **Already have uwf?** Jump to [Self-Check & Upgrade](#self-check--upgrade).
+
+---
+
+## Fresh Install
+
+### 1. Install uwf CLI
+
+```bash
+bun install -g @uncaged/cli-workflow
+```
+
+✅ **Check:** `uwf --version` prints a version number (e.g. `0.5.1`).
+
+### 2. Install Agent Adapter
+
+Install the adapter that matches your agent runtime. Pick **one**:
+
+| Agent | Package | Binary |
+|-------|---------|--------|
+| Hermes | `@uncaged/workflow-agent-hermes` | `uwf-hermes` |
+
+```bash
+# Example: Hermes agent
+bun install -g @uncaged/workflow-agent-hermes
+```
+
+✅ **Check:** `uwf-hermes --version` prints a version number.
+
+### 3. Setup
+
+Run the interactive wizard:
+
+```bash
+uwf setup
+```
+
+Or configure non-interactively:
+
+```bash
+uwf setup \
+  --provider <name> \
+  --base-url <url> \
+  --api-key <key> \
+  --model <model-name> \
+  --agent hermes
+```
+
+This creates `~/.uncaged/workflow/config.yaml` with your provider, model, and default agent.
+
+#### Config Structure
+
+```yaml
+providers:
+  my-provider:
+    baseUrl: https://api.example.com/v1
+    apiKey: sk-xxx
+models:
+  default:
+    provider: my-provider
+    name: my-model
+agents:
+  hermes:
+    command: uwf-hermes
+    args: []
+defaultAgent: hermes
+defaultModel: default
+```
+
+✅ **Check:** `cat ~/.uncaged/workflow/config.yaml` shows valid provider, model, and agent config.
+
+### 4. Verify Installation
+
+```bash
+uwf workflow list    # should return empty array or existing workflows
+uwf skill user       # prints usage guide
+uwf skill author     # prints workflow authoring guide
+```
+
+✅ **Check:** All three commands run without errors.
+
+### 5. Add the uwf Skill
+
+```bash
+mkdir -p ~/.hermes/skills/devops/uwf
+uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md
+```
+
+✅ **Check:** `cat ~/.hermes/skills/devops/uwf/SKILL.md` shows the skill content with triggers `uwf`, `workflow`, `工作流`.
+
+### 6. Smoke Test
+
+```bash
+# Register an example workflow
+uwf workflow add examples/analyze-topic.yaml
+
+# Start a thread
+uwf thread start analyze-topic -p "Analyze the concept of technical debt"
+
+# Execute it (one moderator → agent → extract cycle)
+uwf thread exec <thread-id>
+```
+
+✅ **Check:** Thread reaches `completed` status. Verify with `uwf thread list`.
+
+---
+
+## Self-Check & Upgrade
+
+Already have uwf installed? Run through this checklist to verify and upgrade.
+
+### Version Check
+
+```bash
+uwf --version
+uwf-hermes --version   # or your agent adapter
+```
+
+Compare with latest published versions:
+
+```bash
+bun pm ls -g | grep -E "cli-workflow|workflow-agent"
+npm info @uncaged/cli-workflow version
+npm info @uncaged/workflow-agent-hermes version
+```
+
+If local version < published version, upgrade:
+
+```bash
+bun install -g @uncaged/cli-workflow@latest
+bun install -g @uncaged/workflow-agent-hermes@latest
+```
+
+✅ **Check:** `uwf --version` matches `npm info @uncaged/cli-workflow version`.
+
+### Config Check
+
+```bash
+cat ~/.uncaged/workflow/config.yaml
+```
+
+Verify:
+- [ ] `providers` has at least one entry with valid `baseUrl` and `apiKey`
+- [ ] `models.default` references an existing provider
+- [ ] `agents` has your adapter configured
+- [ ] `defaultAgent` and `defaultModel` are set
+
+### Skill Check
+
+```bash
+cat ~/.hermes/skills/devops/uwf/SKILL.md
+```
+
+Verify the skill is up to date:
+
+```bash
+uwf skill bootstrap | diff - ~/.hermes/skills/devops/uwf/SKILL.md
+```
+
+If `diff` produces any output, the local skill is outdated. Update:
+
+```bash
+uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md
+```
+
+### Functional Check
+
+```bash
+uwf workflow list      # should not error
+uwf skill user         # should print usage guide
+uwf skill author       # should print authoring guide
+```
+
+✅ All green? You're good to go.

CLAUDE.md

@@ -270,7 +270,7 @@ node scripts/publish-all.mjs --dry-run    # preview without publishing
 examples/solve-issue.yaml       — write a workflow YAML definition
   │  uwf workflow put
   ▼
-~/.uncaged/workflow/cas/        — Workflow stored as CAS node
+~/.uncaged/json-cas/            — Workflow stored as CAS node (unified CAS store)
 ~/.uncaged/workflow/registry.yaml — name → hash mapping updated
   │  uwf thread start <name> -p "..."
   ▼

biome.json

@@ -39,7 +39,8 @@
       "linter": {
         "rules": {
           "suspicious": {
-            "noExplicitAny": "off"
+            "noExplicitAny": "off",
+            "noConsole": "off"
           },
           "style": {
             "noNonNullAssertion": "off"

package.json

@@ -1,11 +1,14 @@
 {
   "name": "@uncaged/workflow-monorepo",
   "private": true,
+  "packageManager": "bun@1.3.14",
   "workspaces": [
     "packages/*"
   ],
   "scripts": {
     "uwf": "bun packages/cli-workflow/src/cli.ts",
+    "preinstall": "npx only-allow bun",
+    "prepublishOnly": "echo 'Use bun run release instead' && exit 1",
     "build": "bunx tsc --build",
     "check": "bunx tsc --build && biome check . && bash scripts/lint-log-tags.sh",
     "typecheck": "bunx tsc --build",
@@ -14,7 +17,7 @@
     "test:ci": "bun run --filter './packages/*' test:ci",
     "changeset": "bunx changeset",
     "version": "bunx changeset version",
-    "release": "bun run build && bun test && node scripts/publish-all.mjs"
+    "release": "bun run build && bun run test && node scripts/publish-all.mjs"
   },
   "devDependencies": {
     "@agentclientprotocol/sdk": "^0.22.1",
@@ -23,7 +26,10 @@
     "@types/node": "^25.7.0",
     "@types/xxhashjs": "^0.2.4",
     "@uncaged/workflow-agent-hermes": "workspace:*",
-    "bun-types": "^1.3.13"
+    "bun-types": "^1.3.13",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.7",
+    "yaml": "^2.9.0"
   },
   "repository": {
     "type": "git",

packages/cli-workflow/README.md

@@ -209,4 +209,13 @@ src/
 | `~/.uncaged/workflow/.env` | API keys (referenced by `apiKeyEnv` in config) |
 | `~/.uncaged/workflow/registry.yaml` | Workflow name → CAS hash |
 | `~/.uncaged/workflow/threads.yaml` | Active thread head pointers |
-| `~/.uncaged/workflow/cas/` | Content-addressed node storage |
+| `~/.uncaged/json-cas/` | Content-addressed node storage (unified CAS store, shared with `json-cas` CLI) |
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `UNCAGED_CAS_DIR` | Override the global CAS directory location | `~/.uncaged/json-cas` |
+| `UNCAGED_WORKFLOW_STORAGE_ROOT` | Internal override for workflow metadata storage | `~/.uncaged/workflow` |
+| `WORKFLOW_STORAGE_ROOT` | User override for workflow metadata storage | `~/.uncaged/workflow` |
+

packages/cli-workflow/package.json

@@ -22,6 +22,7 @@
     "yaml": "^2.8.4"
   },
   "scripts": {
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
     "test": "vitest run",
     "test:ci": "vitest run"
   },
@@ -34,12 +35,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/cli-workflow"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

packages/cli-workflow/src/__tests__/adapter-json-roundtrip.test.ts

@@ -0,0 +1,178 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, StepNodePayload, ThreadId } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { registerUwfSchemas } from "../schemas.js";
+import { saveThreadsIndex } from "../store.js";
+
+// ── schemas ──────────────────────────────────────────────────────────────────
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const, enum: ["done", "failed"] },
+    result: { type: "string" as const },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+// ── fixture ──────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-roundtrip-test-"));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe("C1: adapter JSON round-trip integration", () => {
+  test("mock agent outputs JSON, CLI parses it and updates thread head in CAS", async () => {
+    // 1. Set up CAS store with workflow, start node, and output schema
+    const casDir = join(tmpDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    const store = createFsStore(casDir);
+    const schemas = await registerUwfSchemas(store);
+
+    const outputSchemaHash = await putSchema(store, OUTPUT_SCHEMA);
+
+    const workflowHash = await store.put(schemas.workflow, {
+      name: "test-roundtrip",
+      description: "roundtrip integration test",
+      roles: {
+        worker: {
+          description: "Worker role",
+          goal: "Do work",
+          capabilities: [],
+          procedure: "work",
+          output: "result",
+          frontmatter: outputSchemaHash,
+        },
+      },
+      graph: {
+        $START: { _: { role: "worker", prompt: "Do the work", location: null } },
+        worker: { done: { role: "$END", prompt: "completed", location: null } },
+      },
+    });
+
+    const startHash = await store.put(schemas.startNode, {
+      workflow: workflowHash,
+      prompt: "Test round-trip task",
+    });
+
+    const threadId = "01ROUNDTRIPTEST0000000000" as ThreadId;
+    await saveThreadsIndex(tmpDir, { [threadId]: startHash });
+
+    // 2. Pre-create CAS nodes that the mock agent would produce
+    const outputHash = await store.put(outputSchemaHash, {
+      $status: "done",
+      result: "test-ok",
+    });
+
+    // Use text schema for detail (simple placeholder)
+    const detailHash = await store.put(schemas.text, "mock detail");
+
+    const startedAtMs = 1716600000000;
+    const completedAtMs = 1716600001500;
+
+    const stepHash = await store.put(schemas.stepNode, {
+      start: startHash,
+      prev: null,
+      role: "worker",
+      output: outputHash,
+      detail: detailHash,
+      agent: "uwf-mock",
+      edgePrompt: "Do the work",
+      startedAtMs,
+      completedAtMs,
+      cwd: tmpDir,
+    });
+
+    // 3. Create a minimal mock agent shell script that just outputs JSON
+    //    The step node is already in CAS — the agent just needs to print the JSON line
+    const mockAgentPath = join(tmpDir, "mock-agent.sh");
+    const adapterJson = JSON.stringify({
+      stepHash,
+      detailHash,
+      role: "worker",
+      frontmatter: { $status: "done", result: "test-ok" },
+      body: "",
+      startedAtMs,
+      completedAtMs,
+    });
+    await writeFile(mockAgentPath, `#!/bin/sh\necho '${adapterJson}'\n`, { mode: 0o755 });
+
+    // 4. Write config.yaml
+    const configPath = join(tmpDir, "config.yaml");
+    await writeFile(
+      configPath,
+      `defaultAgent: uwf-hermes\ndefaultModel: test-model\nagentOverrides: null\nagents: {}\nproviders: {}\nmodels: {}\n`,
+    );
+
+    // 5. Run CLI with agent override pointing to our mock
+    const cliPath = join(import.meta.dirname, "..", "cli.js");
+    let stdout: string;
+    let stderr: string;
+    let exitCode: number;
+
+    try {
+      stdout = execFileSync(
+        "bun",
+        ["run", cliPath, "thread", "exec", threadId, "--agent", mockAgentPath],
+        {
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+          env: {
+            ...process.env,
+            WORKFLOW_STORAGE_ROOT: tmpDir,
+            UNCAGED_CAS_DIR: casDir,
+          },
+          cwd: tmpDir,
+          timeout: 30000,
+        },
+      );
+      stderr = "";
+      exitCode = 0;
+    } catch (e: unknown) {
+      const err = e as NodeJS.ErrnoException & {
+        stdout?: string;
+        stderr?: string;
+        status?: number;
+      };
+      stdout = err.stdout ?? "";
+      stderr = err.stderr ?? "";
+      exitCode = err.status ?? 1;
+    }
+
+    // 6. Verify
+    if (exitCode !== 0) {
+      throw new Error(`CLI exited with code ${exitCode}\nstdout: ${stdout}\nstderr: ${stderr}`);
+    }
+
+    // Parse CLI output
+    const cliOutput = JSON.parse(stdout.trim());
+    expect(cliOutput).toHaveProperty("thread", threadId);
+    expect(cliOutput).toHaveProperty("head", stepHash);
+    expect(cliOutput.head).toMatch(/^[0-9A-HJ-NP-TV-Z]{13}$/);
+
+    // Verify the CAS step node exists and has correct metadata
+    const storeAfter = createFsStore(casDir);
+    const stepNode = storeAfter.get(cliOutput.head as CasRef);
+    expect(stepNode).not.toBeNull();
+
+    const payload = stepNode!.payload as StepNodePayload;
+    expect(payload.role).toBe("worker");
+    expect(payload.agent).toBe("uwf-mock");
+    expect(payload.startedAtMs).toBe(1716600000000);
+    expect(payload.completedAtMs).toBe(1716600001500);
+    expect(payload.output).toBe(outputHash);
+    expect(payload.detail).toBe(detailHash);
+  });
+});

packages/cli-workflow/src/__tests__/cas-exit-code.test.ts

@@ -6,14 +6,22 @@ import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { cmdCasPutText } from "../commands/cas.js";
 
 let storageRoot: string;
+let casDir: string;
 let uwfPath: string;
+let originalEnv: string | undefined;
 
 beforeEach(async () => {
   storageRoot = join(
     tmpdir(),
     `uwf-cas-exit-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
   );
+  casDir = join(storageRoot, "cas");
   await mkdir(storageRoot, { recursive: true });
+  await mkdir(casDir, { recursive: true });
+
+  // Set UNCAGED_CAS_DIR for this test
+  originalEnv = process.env.UNCAGED_CAS_DIR;
+  process.env.UNCAGED_CAS_DIR = casDir;
 
   // Find the uwf CLI path
   uwfPath = join(__dirname, "../../src/cli.ts");
@@ -21,6 +29,13 @@ beforeEach(async () => {
 
 afterEach(async () => {
   await rm(storageRoot, { recursive: true, force: true });
+
+  // Restore original environment
+  if (originalEnv === undefined) {
+    delete process.env.UNCAGED_CAS_DIR;
+  } else {
+    process.env.UNCAGED_CAS_DIR = originalEnv;
+  }
 });
 
 type ExecResult = {
@@ -32,7 +47,11 @@ type ExecResult = {
 function execUwf(args: string[]): ExecResult {
   try {
     const stdout = execSync(`bun ${uwfPath} ${args.join(" ")}`, {
-      env: { ...process.env, WORKFLOW_STORAGE_ROOT: storageRoot },
+      env: {
+        ...process.env,
+        WORKFLOW_STORAGE_ROOT: storageRoot,
+        UNCAGED_CAS_DIR: casDir,
+      },
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
     });

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

@@ -143,6 +143,44 @@ defaultModel: default
         const masked = maskApiKeys(config);
         expect(masked).toEqual(config);
       });
+
+      test("does not mask non-provider apiKey fields", () => {
+        const config = {
+          apiKey: "root-level-key",
+          providers: {
+            dashscope: { apiKey: "sk-secret" },
+          },
+          models: {
+            default: { provider: "dashscope" },
+          },
+        };
+        const masked = maskApiKeys(config);
+        // Root-level apiKey should NOT be masked
+        expect(masked.apiKey).toBe("root-level-key");
+        // Provider apiKey SHOULD be masked
+        const providers = masked.providers as Record<string, Record<string, unknown>>;
+        expect(providers.dashscope.apiKey).toBe("***MASKED***");
+      });
+
+      test("handles empty provider object", () => {
+        const config = {
+          providers: { dashscope: {} },
+        };
+        const masked = maskApiKeys(config);
+        expect(masked).toEqual({ providers: { dashscope: {} } });
+      });
+
+      test("handles provider with null apiKey", () => {
+        const config = {
+          providers: {
+            dashscope: { apiKey: null, baseUrl: "https://example.com" },
+          },
+        };
+        const masked = maskApiKeys(config);
+        const providers = masked.providers as Record<string, Record<string, unknown>>;
+        expect(providers.dashscope.apiKey).toBe("***MASKED***");
+        expect(providers.dashscope.baseUrl).toBe("https://example.com");
+      });
     });
   });
 
@@ -618,5 +656,82 @@ defaultModel: default
         rmSync(tempDir, { recursive: true, force: true });
       }
     });
+
+    test("agentOverrides — accepts valid 3-segment path", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "agentOverrides.solve-issue.planner", "claude-code");
+        const value = await cmdConfigGet(tempDir, "agentOverrides.solve-issue.planner");
+        expect(value).toBe("claude-code");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("agentOverrides — rejects incomplete path (2 segments)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "agentOverrides.solve-issue", "hermes")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("modelOverrides — accepts valid 2-segment path", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await cmdConfigSet(tempDir, "modelOverrides.extract", "gpt4");
+        const value = await cmdConfigGet(tempDir, "modelOverrides.extract");
+        expect(value).toBe("gpt4");
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("modelOverrides — rejects incomplete path (1 segment only)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "modelOverrides", "gpt4")).rejects.toThrow(
+          /incomplete path|must specify a field/i,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+
+    test("rejects unknown top-level key (regression)", async () => {
+      const tempDir = mkdtempSync(join(tmpdir(), "test-config-"));
+      try {
+        createTestConfig(tempDir, sampleConfig);
+        await expect(cmdConfigSet(tempDir, "randomKey", "value")).rejects.toThrow(
+          /Unknown config key/,
+        );
+      } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("no legacy apiKeyEnv references", () => {
+    test("config.ts has no references to apiKeyEnv", () => {
+      const configSource = readFileSync(join(__dirname, "..", "commands", "config.ts"), "utf8");
+      expect(configSource).not.toContain("apiKeyEnv");
+    });
+
+    test("config.test.ts has no references to apiKeyEnv (except this test)", () => {
+      const testSource = readFileSync(__filename, "utf8");
+      // Remove this test block's own mentions before checking
+      const withoutThisTest = testSource.replace(
+        /describe\("no legacy apiKeyEnv references"[\s\S]*$/,
+        "",
+      );
+      expect(withoutThisTest).not.toContain("apiKeyEnv");
+    });
   });
 });

packages/cli-workflow/src/__tests__/current-role.test.ts

@@ -0,0 +1,456 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { putSchema } from "@uncaged/json-cas";
+import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { createMarker, deleteMarker } from "../background/index.js";
+import { cmdThreadList, cmdThreadShow, cmdThreadStart } from "../commands/thread.js";
+import {
+  appendThreadHistory,
+  createUwfStore,
+  loadThreadsIndex,
+  saveThreadsIndex,
+} from "../store.js";
+
+const OUTPUT_SCHEMA = {
+  type: "object" as const,
+  properties: {
+    $status: { type: "string" as const },
+  },
+};
+
+const SIMPLE_WORKFLOW_YAML = `
+name: test-current-role
+description: Test workflow for currentRole
+roles:
+  roleA:
+    description: First role
+    goal: Do A
+    capabilities: ["coding"]
+    procedure: Do A
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string, enum: ["ready", "not-ready"] }
+  roleB:
+    description: Second role
+    goal: Do B
+    capabilities: ["coding"]
+    procedure: Do B
+    output: |
+      $status: "done"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: roleA
+      prompt: "Do A"
+      location: null
+  roleA:
+    ready:
+      role: roleB
+      prompt: "Do B"
+      location: null
+    not-ready:
+      role: roleA
+      prompt: "Try again"
+      location: null
+  roleB:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+const CONDITIONAL_WORKFLOW_YAML = `
+name: test-conditional-role
+description: Conditional routing workflow
+roles:
+  roleA:
+    description: First role
+    goal: Do A
+    capabilities: ["coding"]
+    procedure: Do A
+    output: |
+      $status: "pass"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string, enum: ["pass", "fail"] }
+  roleB:
+    description: Pass role
+    goal: Do B
+    capabilities: ["coding"]
+    procedure: Do B
+    output: |
+      $status: "done"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+  roleC:
+    description: Fail role
+    goal: Do C
+    capabilities: ["coding"]
+    procedure: Do C
+    output: |
+      $status: "done"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: roleA
+      prompt: "Do A"
+      location: null
+  roleA:
+    pass:
+      role: roleB
+      prompt: "Do B (pass)"
+      location: null
+    fail:
+      role: roleC
+      prompt: "Do C (fail)"
+      location: null
+  roleB:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+  roleC:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+const SINGLE_ROLE_WORKFLOW_YAML = `
+name: test-single-role
+description: Single role that goes to END
+roles:
+  worker:
+    description: Worker
+    goal: Work
+    capabilities: ["coding"]
+    procedure: Work
+    output: |
+      $status: "done"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: worker
+      prompt: "Work"
+      location: null
+  worker:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+/** Helper: insert a completed step node after the current head. */
+async function insertStepNode(
+  storageRoot: string,
+  threadId: ThreadId,
+  role: string,
+  outputPayload: Record<string, unknown>,
+): Promise<void> {
+  const uwf = await createUwfStore(storageRoot);
+  const index = await loadThreadsIndex(storageRoot);
+  const head = index[threadId];
+  if (head === undefined) throw new Error(`thread ${threadId} not in index`);
+
+  const outputSchemaHash = await putSchema(uwf.store, OUTPUT_SCHEMA);
+  const outputHash = await uwf.store.put(outputSchemaHash, outputPayload);
+
+  // Use text schema for detail (simple placeholder)
+  const detailHash = await uwf.store.put(uwf.schemas.text, "detail-placeholder");
+
+  // Resolve start hash from head
+  const headNode = uwf.store.get(head);
+  if (headNode === null) throw new Error(`head ${head} not found`);
+  const isStart = headNode.type === uwf.schemas.startNode;
+  const startHash = isStart ? head : (headNode.payload as { start: CasRef }).start;
+
+  const stepHash = (await uwf.store.put(uwf.schemas.stepNode, {
+    start: startHash,
+    prev: isStart ? null : head,
+    role,
+    prompt: `Do ${role}`,
+    output: outputHash,
+    detail: detailHash,
+  })) as CasRef;
+
+  index[threadId] = stepHash;
+  await saveThreadsIndex(storageRoot, index);
+}
+
+describe("currentRole field", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+  let casDir: string;
+  let originalEnv: string | undefined;
+
+  async function setup() {
+    tmpDir = join(
+      tmpdir(),
+      `uwf-test-current-role-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+    storageRoot = join(tmpDir, "storage");
+    casDir = join(tmpDir, "cas");
+    await mkdir(storageRoot, { recursive: true });
+    await mkdir(casDir, { recursive: true });
+
+    // Set UNCAGED_CAS_DIR for this test
+    originalEnv = process.env.UNCAGED_CAS_DIR;
+    process.env.UNCAGED_CAS_DIR = casDir;
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+    // Restore original environment
+    if (originalEnv === undefined) {
+      delete process.env.UNCAGED_CAS_DIR;
+    } else {
+      process.env.UNCAGED_CAS_DIR = originalEnv;
+    }
+  }
+
+  // T1: idle at start — currentRole = first role from graph
+  test("thread show — idle at start returns first role as currentRole", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+
+      const result = await cmdThreadShow(storageRoot, thread as ThreadId);
+      expect(result.status).toBe("idle");
+      expect(result.currentRole).toBe("roleA");
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T2: idle after one step — currentRole = next role
+  test("thread show — idle after step returns next role as currentRole", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+
+      await insertStepNode(storageRoot, thread as ThreadId, "roleA", { $status: "ready" });
+
+      const result = await cmdThreadShow(storageRoot, thread as ThreadId);
+      expect(result.status).toBe("idle");
+      expect(result.currentRole).toBe("roleB");
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T3: completed → currentRole = null
+  test("thread show — completed thread returns null currentRole", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread, workflow } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+      const tid = thread as ThreadId;
+
+      const index = await loadThreadsIndex(storageRoot);
+      const head = index[tid]!;
+      delete index[tid];
+      await saveThreadsIndex(storageRoot, index);
+      await appendThreadHistory(storageRoot, {
+        thread: tid,
+        workflow,
+        head,
+        completedAt: Date.now(),
+        reason: "completed",
+      });
+
+      const result = await cmdThreadShow(storageRoot, tid);
+      expect(result.status).toBe("completed");
+      expect(result.currentRole).toBe(null);
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T4: cancelled → currentRole = null
+  test("thread show — cancelled thread returns null currentRole", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread, workflow } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+      const tid = thread as ThreadId;
+
+      const index = await loadThreadsIndex(storageRoot);
+      const head = index[tid]!;
+      delete index[tid];
+      await saveThreadsIndex(storageRoot, index);
+      await appendThreadHistory(storageRoot, {
+        thread: tid,
+        workflow,
+        head,
+        completedAt: Date.now(),
+        reason: "cancelled",
+      });
+
+      const result = await cmdThreadShow(storageRoot, tid);
+      expect(result.status).toBe("cancelled");
+      expect(result.currentRole).toBe(null);
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T5: running → currentRole = role being executed
+  test("thread show — running thread returns current role", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread, workflow } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+      const tid = thread as ThreadId;
+
+      await createMarker(storageRoot, {
+        thread: tid,
+        workflow,
+        pid: process.pid,
+        startedAt: Date.now(),
+      });
+
+      try {
+        const result = await cmdThreadShow(storageRoot, tid);
+        expect(result.status).toBe("running");
+        expect(result.currentRole).toBe("roleA");
+      } finally {
+        await deleteMarker(storageRoot, tid);
+      }
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T6: thread list — mixed statuses with correct currentRole
+  test("thread list — returns correct currentRole for each status", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+
+      // idle thread
+      const idle = await cmdThreadStart(storageRoot, wf, "idle", tmpDir);
+      const idleId = idle.thread as ThreadId;
+
+      // completed thread
+      const comp = await cmdThreadStart(storageRoot, wf, "completed", tmpDir);
+      const compId = comp.thread as ThreadId;
+      const index = await loadThreadsIndex(storageRoot);
+      const compHead = index[compId]!;
+      delete index[compId];
+      await saveThreadsIndex(storageRoot, index);
+      await appendThreadHistory(storageRoot, {
+        thread: compId,
+        workflow: comp.workflow,
+        head: compHead,
+        completedAt: Date.now(),
+        reason: "completed",
+      });
+
+      const list = await cmdThreadList(storageRoot, null, null, null, 0, 100);
+
+      const idleItem = list.find((i) => i.thread === idleId);
+      expect(idleItem).toBeDefined();
+      expect(idleItem!.currentRole).toBe("roleA");
+
+      const compItem = list.find((i) => i.thread === compId);
+      expect(compItem).toBeDefined();
+      expect(compItem!.currentRole).toBe(null);
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T7: thread list — idle at start has correct currentRole
+  test("thread list — idle thread at start has correct currentRole", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-current-role.yaml");
+      await writeFile(wf, SIMPLE_WORKFLOW_YAML, "utf8");
+      const { thread } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+
+      const list = await cmdThreadList(storageRoot, null, null, null, 0, 100);
+      const item = list.find((i) => i.thread === (thread as ThreadId));
+      expect(item).toBeDefined();
+      expect(item!.currentRole).toBe("roleA");
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T8: conditional routing — $status=pass vs fail
+  test("thread show — conditional routing selects correct next role", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-conditional-role.yaml");
+      await writeFile(wf, CONDITIONAL_WORKFLOW_YAML, "utf8");
+
+      // pass path
+      const t1 = await cmdThreadStart(storageRoot, wf, "pass test", tmpDir);
+      await insertStepNode(storageRoot, t1.thread as ThreadId, "roleA", { $status: "pass" });
+      const r1 = await cmdThreadShow(storageRoot, t1.thread as ThreadId);
+      expect(r1.currentRole).toBe("roleB");
+
+      // fail path
+      const t2 = await cmdThreadStart(storageRoot, wf, "fail test", tmpDir);
+      await insertStepNode(storageRoot, t2.thread as ThreadId, "roleA", { $status: "fail" });
+      const r2 = await cmdThreadShow(storageRoot, t2.thread as ThreadId);
+      expect(r2.currentRole).toBe("roleC");
+    } finally {
+      await teardown();
+    }
+  });
+
+  // T9: next role is $END → currentRole = null
+  test("thread show — when next is $END, currentRole is null", async () => {
+    await setup();
+    try {
+      const wf = join(tmpDir, "test-single-role.yaml");
+      await writeFile(wf, SINGLE_ROLE_WORKFLOW_YAML, "utf8");
+
+      const { thread } = await cmdThreadStart(storageRoot, wf, "test", tmpDir);
+      // worker → _ maps to $END
+      await insertStepNode(storageRoot, thread as ThreadId, "worker", {});
+
+      const result = await cmdThreadShow(storageRoot, thread as ThreadId);
+      expect(result.currentRole).toBe(null);
+    } finally {
+      await teardown();
+    }
+  });
+});

packages/cli-workflow/src/__tests__/moderator-evaluate.test.ts

@@ -5,17 +5,17 @@ import { evaluate } from "../moderator/evaluate.js";
 
 const solveIssueGraph: WorkflowPayload["graph"] = {
   $START: {
-    _: { role: "planner", prompt: "Start planning from the issue in the task." },
+    _: { role: "planner", prompt: "Start planning from the issue in the task.", location: null },
   },
   planner: {
-    _: { role: "developer", prompt: "Implement the plan: {{plan}}" },
+    _: { role: "developer", prompt: "Implement the plan: {{plan}}", location: null },
   },
   developer: {
-    _: { role: "reviewer", prompt: "Review the changes: {{summary}}" },
+    _: { role: "reviewer", prompt: "Review the changes: {{summary}}", location: null },
   },
   reviewer: {
-    approved: { role: "$END", prompt: "Done." },
-    rejected: { role: "developer", prompt: "Fix: {{comments}}" },
+    approved: { role: "$END", prompt: "Done.", location: null },
+    rejected: { role: "developer", prompt: "Fix: {{comments}}", location: null },
   },
 };
 
@@ -24,7 +24,11 @@ describe("evaluate", () => {
     const result = evaluate(solveIssueGraph, "$START", { $status: "_" });
     expect(result).toEqual({
       ok: true,
-      value: { role: "planner", prompt: "Start planning from the issue in the task." },
+      value: {
+        role: "planner",
+        prompt: "Start planning from the issue in the task.",
+        location: null,
+      },
     });
   });
 
@@ -35,7 +39,7 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Fix: missing tests" },
+      value: { role: "developer", prompt: "Fix: missing tests", location: null },
     });
   });
 
@@ -43,7 +47,7 @@ describe("evaluate", () => {
     const result = evaluate(solveIssueGraph, "reviewer", { $status: "approved" });
     expect(result).toEqual({
       ok: true,
-      value: { role: "$END", prompt: "Done." },
+      value: { role: "$END", prompt: "Done.", location: null },
     });
   });
 
@@ -70,7 +74,11 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Implement the plan: Add auth middleware" },
+      value: {
+        role: "developer",
+        prompt: "Implement the plan: Add auth middleware",
+        location: null,
+      },
     });
   });
 
@@ -81,14 +89,14 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: 'Fix: use <T> & "Result<T, E>" types' },
+      value: { role: "developer", prompt: 'Fix: use <T> & "Result<T, E>" types', location: null },
     });
   });
 
   test("triple mustache also works for unescaped output", () => {
     const graph: Record<string, Record<string, Target>> = {
       reviewer: {
-        _: { role: "developer", prompt: "Fix: {{{comments}}}" },
+        _: { role: "developer", prompt: "Fix: {{{comments}}}", location: null },
       },
     };
     const result = evaluate(graph, "reviewer", {
@@ -97,7 +105,7 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Fix: <script>alert(1)</script>" },
+      value: { role: "developer", prompt: "Fix: <script>alert(1)</script>", location: null },
     });
   });
 
@@ -107,7 +115,11 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Implement the plan: Add auth middleware" },
+      value: {
+        role: "developer",
+        prompt: "Implement the plan: Add auth middleware",
+        location: null,
+      },
     });
   });
 
@@ -117,6 +129,7 @@ describe("evaluate", () => {
         _: {
           role: "developer",
           prompt: "Address: {{review.comments}}",
+          location: null,
         },
       },
     };
@@ -126,7 +139,7 @@ describe("evaluate", () => {
     });
     expect(result).toEqual({
       ok: true,
-      value: { role: "developer", prompt: "Address: refactor the handler" },
+      value: { role: "developer", prompt: "Address: refactor the handler", location: null },
     });
   });
 });

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

@@ -6,60 +6,63 @@ import { describe, expect, test } from "vitest";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 import {
-  cmdSkillArchitecture,
-  cmdSkillCli,
+  cmdSkillAdapter,
+  cmdSkillAuthor,
+  cmdSkillDeveloper,
   cmdSkillList,
-  cmdSkillModerator,
-  cmdSkillYaml,
+  cmdSkillUser,
 } from "../commands/skill.js";
 
 describe("skill commands", () => {
   test("skill list returns all skill names", () => {
     const result = cmdSkillList();
     expect(result).toBeInstanceOf(Array);
-    expect(result).toContain("cli");
-    expect(result).toContain("architecture");
-    expect(result).toContain("yaml");
-    expect(result).toContain("moderator");
+    expect(result).toContain("user");
+    expect(result).toContain("author");
+    expect(result).toContain("developer");
+    expect(result).toContain("adapter");
     for (const name of result) {
-      expect(typeof name).toBe("string");
       expect(name).toMatch(/^\S+$/);
     }
   });
 
-  test("skill architecture returns non-empty markdown string", () => {
-    const result = cmdSkillArchitecture();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("CAS");
-    expect(result).toContain("Thread");
-    expect(result).toContain("Workflow");
-    expect(result).toContain("Step");
-    expect(result.length).toBeGreaterThan(200);
-  });
-
-  test("skill yaml returns non-empty markdown string", () => {
-    const result = cmdSkillYaml();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("roles");
-    expect(result).toContain("graph");
-    expect(result).toContain("frontmatter");
-    expect(result.length).toBeGreaterThan(200);
-  });
-
-  test("skill moderator returns non-empty markdown string", () => {
-    const result = cmdSkillModerator();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("routing");
-    expect(result).toContain("status");
-    expect(result.length).toBeGreaterThan(200);
-    // Check for edge or graph
-    expect(result).toMatch(/edge|graph/i);
-  });
-
-  test("skill cli returns CLI reference markdown", () => {
-    const result = cmdSkillCli();
+  test("skill user returns non-empty markdown string", () => {
+    const result = cmdSkillUser();
     expect(typeof result).toBe("string");
     expect(result).toContain("uwf");
+    expect(result).toContain("thread");
+    expect(result).toContain("workflow");
+    expect(result).toContain("Quick Start");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill author returns non-empty markdown string", () => {
+    const result = cmdSkillAuthor();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("frontmatter");
+    expect(result).toContain("graph");
+    expect(result).toContain("$START");
+    expect(result).toContain("$END");
+    expect(result).toContain("$status");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill developer returns non-empty markdown string", () => {
+    const result = cmdSkillDeveloper();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("Monorepo");
+    expect(result).toContain("CAS");
+    expect(result).toContain("Biome");
+    expect(result.length).toBeGreaterThan(500);
+  });
+
+  test("skill adapter returns non-empty markdown string", () => {
+    const result = cmdSkillAdapter();
+    expect(typeof result).toBe("string");
+    expect(result).toContain("createAgent");
+    expect(result).toContain("AgentContext");
+    expect(result).toContain("frontmatter");
+    expect(result.length).toBeGreaterThan(500);
   });
 
   test("skill help subcommand is suppressed", () => {
@@ -69,10 +72,10 @@ describe("skill commands", () => {
       env: { ...process.env, PATH: `/opt/homebrew/bin:${process.env.PATH}` },
     });
     expect(output).not.toMatch(/help\s+\[command\]/i);
-    expect(output).toContain("cli");
-    expect(output).toContain("architecture");
-    expect(output).toContain("yaml");
-    expect(output).toContain("moderator");
+    expect(output).toContain("user");
+    expect(output).toContain("author");
+    expect(output).toContain("developer");
+    expect(output).toContain("adapter");
     expect(output).toContain("list");
   });
 });

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

@@ -98,7 +98,7 @@ describe("solve-issue workflow: tea pr create worktree fix", () => {
     expect(frontmatter).toBeDefined();
     expect(frontmatter?.oneOf).toBeDefined();
     const committedVariant = frontmatter.oneOf.find(
-      (v: any) => v.properties?.["$status"]?.const === "committed",
+      (v: any) => v.properties?.$status?.const === "committed",
     );
     expect(committedVariant).toBeDefined();
     expect(committedVariant.required).toContain("$status");

packages/cli-workflow/src/__tests__/spawn-agent-json.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "vitest";
+
+/**
+ * B-group tests: validate JSON parsing logic used by spawnAgent.
+ *
+ * We test the parsing logic inline since spawnAgent is a private function.
+ * These tests verify the contract: last line of stdout must be valid JSON
+ * with a valid stepHash CasRef.
+ */
+
+const CASREF_PATTERN = /^[0-9A-HJ-NP-TV-Z]{13}$/;
+
+function isCasRef(s: string): boolean {
+  return CASREF_PATTERN.test(s);
+}
+
+type AdapterOutput = {
+  stepHash: string;
+  detailHash: string;
+  role: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  startedAtMs: number;
+  completedAtMs: number;
+};
+
+function parseAgentStdout(stdout: string): AdapterOutput {
+  const line = stdout.trim().split("\n").pop()?.trim() ?? "";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    throw new Error(`agent stdout last line is not valid JSON: ${line || "(empty)"}`);
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (
+    typeof obj !== "object" ||
+    obj === null ||
+    typeof obj.stepHash !== "string" ||
+    !isCasRef(obj.stepHash as string)
+  ) {
+    throw new Error(`agent stdout JSON missing valid stepHash: ${line}`);
+  }
+  return obj as unknown as AdapterOutput;
+}
+
+const VALID_OUTPUT: AdapterOutput = {
+  stepHash: "0123456789ABC",
+  detailHash: "DEFGH12345678",
+  role: "planner",
+  frontmatter: { $status: "ready", plan: "somehash" },
+  body: "Plan body",
+  startedAtMs: 1000,
+  completedAtMs: 2000,
+};
+
+describe("spawnAgent JSON parsing", () => {
+  test("B1. parses valid JSON from agent stdout", () => {
+    const stdout = `${JSON.stringify(VALID_OUTPUT)}\n`;
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+    expect(result.detailHash).toBe("DEFGH12345678");
+    expect(result.role).toBe("planner");
+    expect(result.frontmatter).toEqual({ $status: "ready", plan: "somehash" });
+    expect(result.body).toBe("Plan body");
+    expect(result.startedAtMs).toBe(1000);
+    expect(result.completedAtMs).toBe(2000);
+  });
+
+  test("B2. extracts stepHash for head pointer", () => {
+    const stdout = `${JSON.stringify(VALID_OUTPUT)}\n`;
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+    expect(isCasRef(result.stepHash)).toBe(true);
+  });
+
+  test("B3. handles debug lines before JSON", () => {
+    const debugLines = "[debug] loading context...\n[debug] running agent...\n";
+    const stdout = `${debugLines + JSON.stringify(VALID_OUTPUT)}\n`;
+    const result = parseAgentStdout(stdout);
+    expect(result.stepHash).toBe("0123456789ABC");
+  });
+
+  test("B4. rejects non-JSON last line", () => {
+    const stdout = "not-json-at-all\n";
+    expect(() => parseAgentStdout(stdout)).toThrow("not valid JSON");
+  });
+
+  test("B5. rejects JSON missing stepHash", () => {
+    const incomplete = { detailHash: "DEFGH12345678", role: "planner" };
+    const stdout = `${JSON.stringify(incomplete)}\n`;
+    expect(() => parseAgentStdout(stdout)).toThrow("missing valid stepHash");
+  });
+
+  test("B6. rejects JSON with invalid stepHash", () => {
+    const bad = { ...VALID_OUTPUT, stepHash: "not-a-hash" };
+    const stdout = `${JSON.stringify(bad)}\n`;
+    expect(() => parseAgentStdout(stdout)).toThrow("missing valid stepHash");
+  });
+});

packages/cli-workflow/src/__tests__/step-read.test.ts

@@ -66,13 +66,21 @@ function generateContent(size: number, prefix = "Content"): string {
 // ── fixture ───────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let originalEnv: string | undefined;
 
 beforeEach(async () => {
   tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-step-read-test-"));
+  originalEnv = process.env.UNCAGED_CAS_DIR;
 });
 
 afterEach(async () => {
   await rm(tmpDir, { recursive: true, force: true });
+  // Restore original environment
+  if (originalEnv === undefined) {
+    delete process.env.UNCAGED_CAS_DIR;
+  } else {
+    process.env.UNCAGED_CAS_DIR = originalEnv;
+  }
 });
 
 // ── step read tests ───────────────────────────────────────────────────────────
@@ -80,7 +88,10 @@ afterEach(async () => {
 describe("step read", () => {
   test("test 1: basic single-step read with 3 turns", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     const detailSchemas = await registerDetailSchemas(store);
@@ -146,10 +157,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with large quota
-    const markdown = await cmdStepRead(tmpDir, stepHash, 10000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 10000, false);
 
     // Assert structure
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -165,7 +177,9 @@ describe("step read", () => {
 
   test("test 2: quota enforcement - multiple turns", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     const detailSchemas = await registerDetailSchemas(store);
@@ -231,10 +245,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with limited quota (700 chars)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 700);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 700, false);
 
     // Assert only most recent turns fit
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -248,7 +263,9 @@ describe("step read", () => {
 
   test("test 3: minimal quota edge case - always show at least one turn", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     const detailSchemas = await registerDetailSchemas(store);
@@ -310,10 +327,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step with minimal quota (1 char)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 1);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 1, false);
 
     // Assert at least one turn is always shown
     expect(markdown).toContain("LongTurn");
@@ -322,7 +340,9 @@ describe("step read", () => {
 
   test("test 4: step with no detail field", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
 
@@ -365,10 +385,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step - should return metadata only (no error)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert metadata is present
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -380,7 +401,9 @@ describe("step read", () => {
 
   test("test 5: step with detail but no turns array", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     await registerDetailSchemas(store);
@@ -441,10 +464,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step - should return metadata only (no error)
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert metadata is present
     expect(markdown).toContain(`# Step ${stepHash}`);
@@ -455,7 +479,9 @@ describe("step read", () => {
 
   test("test 6: displays role and tool calls in turn body", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     const detailSchemas = await registerDetailSchemas(store);
@@ -515,9 +541,10 @@ describe("step read", () => {
       agent: "uwf-hermes",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     expect(markdown).toContain("**Turn role:** assistant");
     expect(markdown).toContain("**terminal**");
@@ -526,7 +553,9 @@ describe("step read", () => {
 
   test("test 7: turn content with special characters", async () => {
     const casDir = join(tmpDir, "cas");
+    process.env.UNCAGED_CAS_DIR = casDir;
     await mkdir(casDir, { recursive: true });
+    process.env.UNCAGED_CAS_DIR = casDir;
     const store = createFsStore(casDir);
     const schemas = await registerUwfSchemas(store);
     const detailSchemas = await registerDetailSchemas(store);
@@ -588,10 +617,11 @@ describe("step read", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     // Read step
-    const markdown = await cmdStepRead(tmpDir, stepHash, 4000);
+    const markdown = await cmdStepRead(tmpDir, stepHash, 4000, false);
 
     // Assert content is rendered correctly without corruption
     expect(markdown).toContain("`backticks`");

packages/cli-workflow/src/__tests__/step-show-json.test.ts

@@ -0,0 +1,372 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap, type Hash, type JSONSchema, putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import type { CasRef, StepNodePayload } from "@uncaged/workflow-protocol";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { cmdStepShow } from "../commands/step.js";
+import { formatOutput } from "../format.js";
+import { registerUwfSchemas } from "../schemas.js";
+
+const TURN_SCHEMA: JSONSchema = {
+  title: "test-turn",
+  type: "object",
+  required: ["index", "role", "content"],
+  properties: {
+    index: { type: "integer" },
+    role: { type: "string", enum: ["assistant", "tool"] },
+    content: { type: "string" },
+    toolCalls: {
+      anyOf: [
+        {
+          type: "array",
+          items: {
+            type: "object",
+            required: ["name", "args"],
+            properties: {
+              name: { type: "string" },
+              args: { type: "string" },
+            },
+            additionalProperties: false,
+          },
+        },
+        { type: "null" },
+      ],
+    },
+  },
+  additionalProperties: false,
+};
+
+const DETAIL_SCHEMA: JSONSchema = {
+  title: "test-detail",
+  type: "object",
+  required: ["turns"],
+  properties: {
+    turns: {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+    },
+  },
+  additionalProperties: false,
+};
+
+type TestSetup = {
+  store: ReturnType<typeof createFsStore>;
+  schemas: {
+    workflow: Hash;
+    startNode: Hash;
+    stepNode: Hash;
+    text: Hash;
+  };
+  turnType: Hash;
+  detailType: Hash;
+};
+
+async function setupTest(casDir: string): Promise<TestSetup> {
+  const store = createFsStore(casDir);
+  await bootstrap(store);
+  const schemas = await registerUwfSchemas(store);
+  const [turnType, detailType] = await Promise.all([
+    putSchema(store, TURN_SCHEMA),
+    putSchema(store, DETAIL_SCHEMA),
+  ]);
+  return { store, schemas, turnType, detailType };
+}
+
+async function createTestStep(
+  setup: TestSetup,
+  turnPayloads: Array<{
+    index: number;
+    role: string;
+    content: string;
+    toolCalls: Array<{ name: string; args: string }> | null;
+  }>,
+): Promise<CasRef> {
+  const { store, schemas, turnType, detailType } = setup;
+
+  // Create turn nodes
+  const turnHashes: CasRef[] = [];
+  for (const payload of turnPayloads) {
+    const turnHash = await store.put(turnType, payload);
+    turnHashes.push(turnHash);
+  }
+
+  // Create detail node
+  const detailHash = await store.put(detailType, { turns: turnHashes });
+
+  // Create dummy start node
+  const startHash = await store.put(schemas.startNode, {
+    workflow: "0000000000000" as CasRef,
+    prompt: "test prompt",
+    cwd: "/tmp",
+  });
+
+  // Create dummy output node
+  const outputHash = await store.put(schemas.text, { $status: "done" });
+
+  // Create step node
+  const stepPayload: StepNodePayload = {
+    prev: null,
+    start: startHash,
+    role: "test-role",
+    agent: "test-agent",
+    output: outputHash,
+    detail: detailHash,
+    edgePrompt: "",
+    startedAtMs: Date.now(),
+    completedAtMs: Date.now() + 1000,
+    assembledPrompt: null,
+    cwd: "/tmp",
+  };
+  return store.put(schemas.stepNode, stepPayload);
+}
+
+describe("cmdStepShow JSON serialization", () => {
+  let testDir: string;
+  let casDir: string;
+  let originalEnv: string | undefined;
+
+  beforeEach(async () => {
+    testDir = await mkdtemp(join(tmpdir(), "uwf-test-"));
+    casDir = join(testDir, "cas");
+    await mkdir(casDir, { recursive: true });
+    originalEnv = process.env.UNCAGED_CAS_DIR;
+    process.env.UNCAGED_CAS_DIR = casDir;
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    if (originalEnv === undefined) {
+      delete process.env.UNCAGED_CAS_DIR;
+    } else {
+      process.env.UNCAGED_CAS_DIR = originalEnv;
+    }
+  });
+
+  test("escapes newlines in tool call args", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Running command",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo 'line1'\necho 'line2'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\n");
+
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns[0].toolCalls[0].args).toContain("\n");
+  });
+
+  test("escapes tabs in tool call args", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "cat <<EOF\nfield1\tfield2\tfield3\nEOF",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\t");
+  });
+
+  test("escapes carriage returns", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Committing changes",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: 'git commit -m "First line\r\nSecond line"',
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    expect(jsonOutput).toContain("\\r\\n");
+  });
+
+  test("escapes backslashes and quotes", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: 'echo "He said \\"hello\\""',
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toBeDefined();
+  });
+
+  test("handles Unicode control characters", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo '\u0001\u001F'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+  });
+
+  test("handles nested CAS refs with control characters", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "First turn\nwith newline",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "cmd1\nline2",
+          },
+        ],
+      },
+      {
+        index: 1,
+        role: "assistant",
+        content: "Second turn\twith tab",
+        toolCalls: null,
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toHaveLength(2);
+  });
+
+  test("YAML output format is unaffected", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "Running command",
+        toolCalls: [
+          {
+            name: "Bash",
+            args: "echo 'line1'\necho 'line2'",
+          },
+        ],
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const yamlOutput = formatOutput(result, "yaml");
+
+    expect(yamlOutput).toContain("turns:");
+    expect(yamlOutput.length).toBeGreaterThan(0);
+  });
+
+  test("handles empty and null values", async () => {
+    const setup = await setupTest(casDir);
+    const stepHash = await createTestStep(setup, [
+      {
+        index: 0,
+        role: "assistant",
+        content: "",
+        toolCalls: null,
+      },
+    ]);
+
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toBeDefined();
+  });
+
+  test("handles large step with multiple tool calls", async () => {
+    const setup = await setupTest(casDir);
+
+    const turns = [];
+    for (let i = 0; i < 25; i++) {
+      turns.push({
+        index: i,
+        role: "assistant" as const,
+        content: `Turn ${i}\nwith newline`,
+        toolCalls: [
+          {
+            name: "Bash",
+            args: `command${i}\nline2\tfield${i}`,
+          },
+          {
+            name: "Read",
+            args: `/path/to/file${i}`,
+          },
+        ],
+      });
+    }
+
+    const stepHash = await createTestStep(setup, turns);
+
+    const startTime = Date.now();
+    const result = await cmdStepShow(testDir, stepHash);
+    const jsonOutput = formatOutput(result, "json");
+    const duration = Date.now() - startTime;
+
+    expect(duration).toBeLessThan(2000);
+    expect(() => JSON.parse(jsonOutput)).not.toThrow();
+
+    const parsed = JSON.parse(jsonOutput);
+    expect(parsed.turns).toHaveLength(25);
+  });
+});

packages/cli-workflow/src/__tests__/step-timing.test.ts

@@ -63,13 +63,22 @@ async function registerDetailSchemas(store: ReturnType<typeof createFsStore>) {
 // ── fixture ──────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let originalEnv: string | undefined;
 
 beforeEach(async () => {
   tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-step-timing-test-"));
+  originalEnv = process.env.UNCAGED_CAS_DIR;
+  process.env.UNCAGED_CAS_DIR = join(tmpDir, "cas");
+  await mkdir(process.env.UNCAGED_CAS_DIR, { recursive: true });
 });
 
 afterEach(async () => {
   await rm(tmpDir, { recursive: true, force: true });
+  if (originalEnv === undefined) {
+    delete process.env.UNCAGED_CAS_DIR;
+  } else {
+    process.env.UNCAGED_CAS_DIR = originalEnv;
+  }
 });
 
 // ── 1. Protocol types (compile-time) ─────────────────────────────────────────
@@ -85,6 +94,8 @@ describe("protocol types", () => {
       edgePrompt: "",
       startedAtMs: 1000,
       completedAtMs: 2000,
+      assembledPrompt: null,
+      cwd: "/test/path",
     };
     expect(record.startedAtMs).toBe(1000);
     expect(record.completedAtMs).toBe(2000);
@@ -152,6 +163,7 @@ describe("StepNode JSON schema", () => {
       edgePrompt: "",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
     expect(hash).toBeTruthy();
   });
@@ -239,8 +251,8 @@ describe("thread read timing", () => {
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "go" } },
-        worker: { _: { role: "$END", prompt: "" } },
+        $START: { _: { role: "worker", prompt: "go", location: null } },
+        worker: { _: { role: "$END", prompt: "", location: null } },
       },
     });
 
@@ -305,8 +317,8 @@ describe("thread read timing", () => {
         },
       },
       graph: {
-        $START: { _: { role: "worker", prompt: "go" } },
-        worker: { _: { role: "$END", prompt: "" } },
+        $START: { _: { role: "worker", prompt: "go", location: null } },
+        worker: { _: { role: "$END", prompt: "", location: null } },
       },
     });
 

packages/cli-workflow/src/__tests__/store-global-cas.test.ts

@@ -0,0 +1,224 @@
+import { mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { createUwfStore, getCasDir, getGlobalCasDir } from "../store.js";
+
+describe("Global CAS directory", () => {
+  let tmpDir: string;
+  let originalEnv: string | undefined;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `uwf-test-global-cas-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+    originalEnv = process.env.UNCAGED_CAS_DIR;
+  });
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+    if (originalEnv === undefined) {
+      delete process.env.UNCAGED_CAS_DIR;
+    } else {
+      process.env.UNCAGED_CAS_DIR = originalEnv;
+    }
+  });
+
+  test("getGlobalCasDir returns default path when no env var set", () => {
+    delete process.env.UNCAGED_CAS_DIR;
+    const casDir = getGlobalCasDir();
+    // Should return ~/.uncaged/json-cas
+    expect(casDir).toContain(".uncaged");
+    expect(casDir).toContain("json-cas");
+  });
+
+  test("getGlobalCasDir respects UNCAGED_CAS_DIR environment variable", () => {
+    const customPath = join(tmpDir, "custom-cas");
+    process.env.UNCAGED_CAS_DIR = customPath;
+    const casDir = getGlobalCasDir();
+    expect(casDir).toBe(customPath);
+  });
+
+  test("getGlobalCasDir ignores empty UNCAGED_CAS_DIR", () => {
+    process.env.UNCAGED_CAS_DIR = "";
+    const casDir = getGlobalCasDir();
+    expect(casDir).toContain(".uncaged");
+    expect(casDir).toContain("json-cas");
+  });
+
+  test("getCasDir is deprecated but still works for backward compatibility", () => {
+    const storageRoot = join(tmpDir, "storage");
+    const casDir = getCasDir(storageRoot);
+    expect(casDir).toBe(join(storageRoot, "cas"));
+  });
+
+  test("createUwfStore uses global CAS directory", async () => {
+    const globalCasDir = join(tmpDir, "global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    const uwf = await createUwfStore(storageRoot);
+
+    // Verify the store was created in the global CAS directory
+    expect(uwf.storageRoot).toBe(storageRoot);
+    expect(uwf.store).toBeDefined();
+    expect(uwf.schemas).toBeDefined();
+
+    // The global CAS directory should be created
+    const { stat } = await import("node:fs/promises");
+    const stats = await stat(globalCasDir);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  test("createUwfStore creates global CAS directory if it does not exist", async () => {
+    const globalCasDir = join(tmpDir, "new-global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    await createUwfStore(storageRoot);
+
+    // Verify the directory was created
+    const { stat } = await import("node:fs/promises");
+    const stats = await stat(globalCasDir);
+    expect(stats.isDirectory()).toBe(true);
+  });
+
+  test("multiple uwfStore instances share the same global CAS filesystem", async () => {
+    const globalCasDir = join(tmpDir, "shared-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot1 = join(tmpDir, "storage1");
+    const storageRoot2 = join(tmpDir, "storage2");
+    await mkdir(storageRoot1, { recursive: true });
+    await mkdir(storageRoot2, { recursive: true });
+
+    const uwf1 = await createUwfStore(storageRoot1);
+    const uwf2 = await createUwfStore(storageRoot2);
+
+    // Both should use the same global CAS directory
+    expect(uwf1.store).toBeDefined();
+    expect(uwf2.store).toBeDefined();
+
+    // Store a node in the first store
+    const testData = { test: "data" };
+    const _hash = uwf1.store.put(uwf1.schemas.text, JSON.stringify(testData));
+
+    // Both stores share the same CAS filesystem directory
+    // Since schemas are registered idempotently, they should have the same hash
+    expect(uwf2.schemas.text).toBe(uwf1.schemas.text);
+
+    // Verify the CAS files are written to the shared directory
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(globalCasDir);
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  test("workflow metadata remains in storageRoot, not global CAS", async () => {
+    const globalCasDir = join(tmpDir, "global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    const _uwf = await createUwfStore(storageRoot);
+
+    // Write workflow registry file
+    const { saveWorkflowRegistry } = await import("../store.js");
+    await saveWorkflowRegistry(storageRoot, { "test-workflow": "ABC123" });
+
+    // Verify registry is in storageRoot, not global CAS
+    const { readFile } = await import("node:fs/promises");
+    const registryPath = join(storageRoot, "workflows.yaml");
+    const content = await readFile(registryPath, "utf8");
+    expect(content).toContain("test-workflow");
+    expect(content).toContain("ABC123");
+
+    // Verify registry is NOT in global CAS directory
+    const globalRegistryPath = join(globalCasDir, "workflows.yaml");
+    await expect(readFile(globalRegistryPath, "utf8")).rejects.toThrow();
+  });
+
+  test("thread metadata remains in storageRoot", async () => {
+    const globalCasDir = join(tmpDir, "global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    await createUwfStore(storageRoot);
+
+    // Write threads index
+    const { saveThreadsIndex } = await import("../store.js");
+    await saveThreadsIndex(storageRoot, { "thread-123": "hash-456" });
+
+    // Verify threads.yaml is in storageRoot, not global CAS
+    const { readFile } = await import("node:fs/promises");
+    const threadsPath = join(storageRoot, "threads.yaml");
+    const content = await readFile(threadsPath, "utf8");
+    expect(content).toContain("thread-123");
+    expect(content).toContain("hash-456");
+
+    // Verify threads.yaml is NOT in global CAS directory
+    const globalThreadsPath = join(globalCasDir, "threads.yaml");
+    await expect(readFile(globalThreadsPath, "utf8")).rejects.toThrow();
+  });
+
+  test("history remains in storageRoot", async () => {
+    const globalCasDir = join(tmpDir, "global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    await createUwfStore(storageRoot);
+
+    // Write history
+    const { appendThreadHistory } = await import("../store.js");
+    await appendThreadHistory(storageRoot, {
+      thread: "thread-123" as any,
+      workflow: "workflow-456",
+      head: "hash-789",
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    // Verify history.jsonl is in storageRoot, not global CAS
+    const { readFile } = await import("node:fs/promises");
+    const historyPath = join(storageRoot, "history.jsonl");
+    const content = await readFile(historyPath, "utf8");
+    expect(content).toContain("thread-123");
+    expect(content).toContain("workflow-456");
+
+    // Verify history.jsonl is NOT in global CAS directory
+    const globalHistoryPath = join(globalCasDir, "history.jsonl");
+    await expect(readFile(globalHistoryPath, "utf8")).rejects.toThrow();
+  });
+
+  test("CAS nodes are stored in global directory", async () => {
+    const globalCasDir = join(tmpDir, "global-cas");
+    process.env.UNCAGED_CAS_DIR = globalCasDir;
+
+    const storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+
+    const uwf = await createUwfStore(storageRoot);
+
+    // Store a CAS node
+    const testPayload = JSON.stringify({ test: "node" });
+    const _hash = uwf.store.put(uwf.schemas.text, testPayload);
+
+    // Verify the node is in global CAS directory
+    const { readdir } = await import("node:fs/promises");
+    const files = await readdir(globalCasDir);
+    expect(files.length).toBeGreaterThan(0);
+
+    // Verify the node is NOT in the old storageRoot/cas location
+    const oldCasDir = join(storageRoot, "cas");
+    await expect(readdir(oldCasDir)).rejects.toThrow();
+  });
+});

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

@@ -15,6 +15,8 @@ import { appendThreadHistory, createUwfStore, saveThreadsIndex } from "../store.
 async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
   const casDir = join(storageRoot, "cas");
   await mkdir(casDir, { recursive: true });
+  // Set UNCAGED_CAS_DIR to use the test's CAS directory
+  process.env.UNCAGED_CAS_DIR = casDir;
   return createUwfStore(storageRoot);
 }
 

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

@@ -0,0 +1,188 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, StartNodePayload, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { cmdThreadStart } from "../commands/thread.js";
+import { createUwfStore } from "../store.js";
+
+describe("Thread and edge location integration", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+  let casDir: string;
+  let originalEnv: string | undefined;
+
+  async function setupTestEnv() {
+    tmpDir = join(tmpdir(), `uwf-test-location-${Date.now()}`);
+    storageRoot = join(tmpDir, "storage");
+    casDir = join(tmpDir, "cas");
+    await mkdir(storageRoot, { recursive: true });
+    await mkdir(casDir, { recursive: true });
+
+    // Set UNCAGED_CAS_DIR for this test
+    originalEnv = process.env.UNCAGED_CAS_DIR;
+    process.env.UNCAGED_CAS_DIR = casDir;
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+    // Restore original environment
+    if (originalEnv === undefined) {
+      delete process.env.UNCAGED_CAS_DIR;
+    } else {
+      process.env.UNCAGED_CAS_DIR = originalEnv;
+    }
+  }
+
+  test("thread start captures cwd in StartNode", async () => {
+    await setupTestEnv();
+
+    const workflowYaml = `
+name: test-location
+description: Test workflow for location feature
+roles:
+  planner:
+    description: Plans the work
+    goal: Plan implementation
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan the work"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+    const workflowPath = join(tmpDir, "test-location.yaml");
+    await writeFile(workflowPath, workflowYaml, "utf8");
+
+    const testCwd = "/test/project/path";
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir, testCwd);
+
+    expect(result.thread).toBeDefined();
+    expect(result.workflow).toBeDefined();
+
+    // Verify StartNode has the cwd field
+    const uwf = await createUwfStore(storageRoot);
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(storageRoot));
+    const headHash = index[result.thread as ThreadId];
+    expect(headHash).toBeDefined();
+
+    const startNode = uwf.store.get(headHash as CasRef);
+    expect(startNode).not.toBe(null);
+    expect(startNode?.type).toBe(uwf.schemas.startNode);
+
+    const startPayload = startNode?.payload as StartNodePayload;
+    expect(startPayload.cwd).toBe(testCwd);
+
+    await teardown();
+  });
+
+  test("thread start validates cwd is absolute path", async () => {
+    await setupTestEnv();
+
+    const workflowYaml = `
+name: test-location
+description: Test workflow
+roles:
+  planner:
+    description: Plans
+    goal: Plan
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+    const workflowPath = join(tmpDir, "test-location.yaml");
+    await writeFile(workflowPath, workflowYaml, "utf8");
+
+    // Relative path should fail (process.exit is wrapped by vitest)
+    await expect(
+      cmdThreadStart(storageRoot, workflowPath, "test", tmpDir, "relative/path"),
+    ).rejects.toThrow();
+
+    await teardown();
+  });
+
+  test("thread start uses process.cwd() as default", async () => {
+    await setupTestEnv();
+
+    const workflowYaml = `
+name: test-default-cwd
+description: Test default cwd
+roles:
+  planner:
+    description: Plans
+    goal: Plan
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+    const workflowPath = join(tmpDir, "test-default-cwd.yaml");
+    await writeFile(workflowPath, workflowYaml, "utf8");
+
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test", tmpDir);
+
+    const uwf = await createUwfStore(storageRoot);
+    const index = await import("../store.js").then((m) => m.loadThreadsIndex(storageRoot));
+    const headHash = index[result.thread as ThreadId];
+
+    const startNode = uwf.store.get(headHash as CasRef);
+    const startPayload = startNode?.payload as StartNodePayload;
+
+    // Should default to process.cwd()
+    expect(startPayload.cwd).toBe(process.cwd());
+
+    await teardown();
+  });
+});

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

@@ -67,13 +67,22 @@ function generateContent(size: number, prefix = "Content"): string {
 // ── fixture ───────────────────────────────────────────────────────────────────
 
 let tmpDir: string;
+let originalEnv: string | undefined;
 
 beforeEach(async () => {
   tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-quota-test-"));
+  originalEnv = process.env.UNCAGED_CAS_DIR;
+  process.env.UNCAGED_CAS_DIR = join(tmpDir, "cas");
+  await mkdir(process.env.UNCAGED_CAS_DIR, { recursive: true });
 });
 
 afterEach(async () => {
   await rm(tmpDir, { recursive: true, force: true });
+  if (originalEnv === undefined) {
+    delete process.env.UNCAGED_CAS_DIR;
+  } else {
+    process.env.UNCAGED_CAS_DIR = originalEnv;
+  }
 });
 
 // ── thread read quota enforcement ─────────────────────────────────────────────
@@ -143,6 +152,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+        assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -225,6 +235,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2Content = generateContent(600, "Second");
@@ -251,6 +262,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ1" as ThreadId;
@@ -336,6 +348,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+        assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -415,6 +428,7 @@ describe("thread read --quota flag", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01HX2Q3R4S5T6V7W8X9YZ4" as ThreadId;
@@ -492,6 +506,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+        assembledPrompt: null,
       });
       steps.push(stepHash);
     }
@@ -573,6 +588,7 @@ describe("thread read --quota flag", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+        assembledPrompt: null,
       });
       steps.push(stepHash);
     }

packages/cli-workflow/src/__tests__/thread-read-xml-tags.test.ts

@@ -53,6 +53,8 @@ const DETAIL_SCHEMA = {
 async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
   const casDir = join(storageRoot, "cas");
   await mkdir(casDir, { recursive: true });
+  // Set UNCAGED_CAS_DIR to use the test's CAS directory
+  process.env.UNCAGED_CAS_DIR = casDir;
   const store = createFsStore(casDir);
   const schemas = await registerUwfSchemas(store);
   return { storageRoot, store, schemas };
@@ -141,6 +143,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-claude-code",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000001" as ThreadId;
@@ -218,6 +221,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-claude-code",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000002" as ThreadId;
@@ -280,6 +284,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -291,6 +296,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000003" as ThreadId;
@@ -345,6 +351,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000004" as ThreadId;
@@ -399,6 +406,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000005" as ThreadId;
@@ -453,6 +461,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000006" as ThreadId;
@@ -527,6 +536,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step2 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -538,6 +548,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const step3 = await uwf.store.put(uwf.schemas.stepNode, {
@@ -549,6 +560,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000007" as ThreadId;
@@ -629,6 +641,7 @@ describe("thread read XML tag isolation", () => {
       agent: "uwf-test",
       startedAtMs: 1000000000000,
       completedAtMs: 1000000005000,
+      assembledPrompt: null,
     });
 
     const threadId = "01JTEST0000000000000008" as ThreadId;
@@ -685,6 +698,7 @@ describe("thread read XML tag isolation", () => {
         agent: "uwf-test",
         startedAtMs: 1000000000000,
         completedAtMs: 1000000005000,
+        assembledPrompt: null,
       })) as CasRef;
       steps.push(step);
       prev = step;

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

@@ -0,0 +1,227 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { createMarker, deleteMarker } from "../background/index.js";
+import { cmdThreadShow, cmdThreadStart } from "../commands/thread.js";
+import { appendThreadHistory, loadThreadsIndex } from "../store.js";
+
+const TEST_WORKFLOW_YAML = `
+name: test-status
+description: Test workflow for status field
+roles:
+  planner:
+    description: Plans the work
+    goal: Plan implementation
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan the work"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+describe("thread show status field", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+
+  async function setupTestEnv() {
+    tmpDir = join(tmpdir(), `uwf-test-status-${Date.now()}`);
+    storageRoot = join(tmpDir, "storage");
+    await mkdir(storageRoot, { recursive: true });
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  test("active idle thread shows status 'idle'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+
+    // Show the thread (should be idle)
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("idle");
+    expect(result.done).toBe(false);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("active running thread shows status 'running'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Create a running marker
+    await createMarker(storageRoot, {
+      thread: threadId,
+      workflow,
+      pid: process.pid,
+      startedAt: Date.now(),
+    });
+
+    try {
+      const result = await cmdThreadShow(storageRoot, threadId);
+
+      expect(result.status).toBe("running");
+      expect(result.done).toBe(false);
+      expect(result.background).toBe(null);
+      expect(result.thread).toBe(threadId);
+    } finally {
+      // Cleanup: delete marker
+      await deleteMarker(storageRoot, threadId);
+      await teardown();
+    }
+  });
+
+  test("completed thread shows status 'completed'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason 'completed'
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: "completed",
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("completed");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("cancelled thread shows status 'cancelled'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason 'cancelled'
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: "cancelled",
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("cancelled");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+    expect(result.thread).toBe(threadId);
+
+    await teardown();
+  });
+
+  test("legacy completed thread without reason shows status 'completed'", async () => {
+    await setupTestEnv();
+
+    const workflowPath = join(tmpDir, "test-status.yaml");
+    await writeFile(workflowPath, TEST_WORKFLOW_YAML, "utf8");
+
+    // Create a thread
+    const startResult = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+    const threadId = startResult.thread as ThreadId;
+    const workflow = startResult.workflow;
+
+    // Get the head hash before moving to history
+    const index = await loadThreadsIndex(storageRoot);
+    const head = index[threadId];
+    if (!head) throw new Error("Thread not found in index");
+
+    // Move thread to history with reason null (legacy format)
+    const { saveThreadsIndex } = await import("../store.js");
+    const newIndex = { ...index };
+    delete newIndex[threadId];
+    await saveThreadsIndex(storageRoot, newIndex);
+
+    await appendThreadHistory(storageRoot, {
+      thread: threadId,
+      workflow,
+      head,
+      completedAt: Date.now(),
+      reason: null,
+    });
+
+    const result = await cmdThreadShow(storageRoot, threadId);
+
+    expect(result.status).toBe("completed");
+    expect(result.done).toBe(true);
+    expect(result.background).toBe(null);
+
+    await teardown();
+  });
+});

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

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasRef, StartNodePayload, ThreadId } from "@uncaged/workflow-protocol";
+import { describe, expect, test } from "vitest";
+import { cmdThreadStart } from "../commands/thread.js";
+import { createUwfStore, loadThreadsIndex } from "../store.js";
+
+describe("thread start --cwd CLI option", () => {
+  let tmpDir: string;
+  let storageRoot: string;
+  let casDir: string;
+  let originalEnv: string | undefined;
+
+  async function setupTestEnv() {
+    tmpDir = join(tmpdir(), `uwf-test-cwd-cli-${Date.now()}`);
+    storageRoot = join(tmpDir, "storage");
+    casDir = join(tmpDir, "cas");
+    await mkdir(storageRoot, { recursive: true });
+    await mkdir(casDir, { recursive: true });
+
+    // Set UNCAGED_CAS_DIR for this test
+    originalEnv = process.env.UNCAGED_CAS_DIR;
+    process.env.UNCAGED_CAS_DIR = casDir;
+  }
+
+  async function teardown() {
+    if (tmpDir) {
+      await rm(tmpDir, { recursive: true, force: true });
+    }
+    // Restore original environment
+    if (originalEnv === undefined) {
+      delete process.env.UNCAGED_CAS_DIR;
+    } else {
+      process.env.UNCAGED_CAS_DIR = originalEnv;
+    }
+  }
+
+  async function createTestWorkflow(): Promise<string> {
+    const workflowYaml = `
+name: test-cwd-cli
+description: Test workflow for CLI cwd option
+roles:
+  planner:
+    description: Plans the work
+    goal: Plan implementation
+    capabilities: ["planning"]
+    procedure: Plan
+    output: |
+      $status: "ready"
+    frontmatter:
+      type: object
+      required: ["$status"]
+      properties:
+        $status: { type: string }
+graph:
+  $START:
+    _:
+      role: planner
+      prompt: "Plan the work"
+      location: null
+  planner:
+    _:
+      role: $END
+      prompt: "Done"
+      location: null
+`;
+
+    const workflowPath = join(tmpDir, "test-cwd-cli.yaml");
+    await writeFile(workflowPath, workflowYaml, "utf8");
+    return workflowPath;
+  }
+
+  async function getStartNodeCwd(threadId: string): Promise<string> {
+    const uwf = await createUwfStore(storageRoot);
+    const index = await loadThreadsIndex(storageRoot);
+    const headHash = index[threadId as ThreadId];
+    expect(headHash).toBeDefined();
+
+    const startNode = uwf.store.get(headHash as CasRef);
+    expect(startNode).not.toBe(null);
+    expect(startNode?.type).toBe(uwf.schemas.startNode);
+
+    const startPayload = startNode?.payload as StartNodePayload;
+    return startPayload.cwd;
+  }
+
+  test("thread start with custom cwd via cmdThreadStart", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+    const testCwd = "/test/custom/path";
+
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir, testCwd);
+
+    expect(result.thread).toBeDefined();
+    const actualCwd = await getStartNodeCwd(result.thread);
+    expect(actualCwd).toBe(testCwd);
+
+    await teardown();
+  });
+
+  test("thread start without cwd defaults to process.cwd()", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+
+    // Call without cwd parameter (it defaults to process.cwd())
+    const result = await cmdThreadStart(storageRoot, workflowPath, "test prompt", tmpDir);
+
+    expect(result.thread).toBeDefined();
+    const actualCwd = await getStartNodeCwd(result.thread);
+    expect(actualCwd).toBe(process.cwd());
+
+    await teardown();
+  });
+
+  test("thread start with relative path fails", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+
+    await expect(
+      cmdThreadStart(storageRoot, workflowPath, "test", tmpDir, "relative/path"),
+    ).rejects.toThrow();
+
+    await teardown();
+  });
+
+  test("CLI accepts --cwd option without error", async () => {
+    await setupTestEnv();
+
+    const workflowPath = await createTestWorkflow();
+    const testCwd = "/test/cli/path";
+    const uwfBin = join(process.cwd(), "dist", "cli.js");
+
+    // Register the workflow
+    execFileSync("node", [uwfBin, "workflow", "add", workflowPath], {
+      env: { ...process.env, UWF_STORAGE_ROOT: storageRoot, UNCAGED_CAS_DIR: casDir },
+      encoding: "utf8",
+    });
+
+    // Verify CLI accepts --cwd option (no error thrown)
+    const output = execFileSync(
+      "node",
+      [uwfBin, "thread", "start", "test-cwd-cli", "-p", "test prompt", "--cwd", testCwd],
+      {
+        env: { ...process.env, UWF_STORAGE_ROOT: storageRoot, UNCAGED_CAS_DIR: casDir },
+        encoding: "utf8",
+      },
+    );
+
+    const result = JSON.parse(output);
+    expect(result.thread).toBeDefined();
+    expect(result.workflow).toBeDefined();
+
+    // The fact that we got here without throwing means CLI accepted the --cwd option
+    // The actual cwd functionality is tested by the other tests using cmdThreadStart directly
+    await teardown();
+  });
+});

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

@@ -58,6 +58,8 @@ const DETAIL_SCHEMA = {
 async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
   const casDir = join(storageRoot, "cas");
   await mkdir(casDir, { recursive: true });
+  // Set UNCAGED_CAS_DIR to use the test's CAS directory
+  process.env.UNCAGED_CAS_DIR = casDir;
   const store = createFsStore(casDir);
   const schemas = await registerUwfSchemas(store);
   return { storageRoot, store, schemas };

packages/cli-workflow/src/__tests__/validate-semantic.test.ts

@@ -51,11 +51,11 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
       },
     },
     graph: {
-      $START: { _: { role: "writer", prompt: "Begin writing" } },
-      writer: { _: { role: "reviewer", prompt: "Review this: {{{plan}}}" } },
+      $START: { _: { role: "writer", prompt: "Begin writing", location: null } },
+      writer: { _: { role: "reviewer", prompt: "Review this: {{{plan}}}", location: null } },
       reviewer: {
-        approved: { role: "$END", prompt: "Done: {{{summary}}}" },
-        rejected: { role: "writer", prompt: "Fix: {{{reason}}}" },
+        approved: { role: "$END", prompt: "Done: {{{summary}}}", location: null },
+        rejected: { role: "writer", prompt: "Fix: {{{reason}}}", location: null },
       },
     },
   };
@@ -67,7 +67,7 @@ function makeWorkflow(overrides?: Partial<WorkflowPayload>): WorkflowPayload {
 describe("Suite 1: Role Reference Integrity", () => {
   test("1.1 graph references unknown role", () => {
     const wf = makeWorkflow();
-    wf.graph.nonexistent = { _: { role: "$END", prompt: "done" } };
+    wf.graph.nonexistent = { _: { role: "$END", prompt: "done", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes('unknown role "nonexistent"'))).toBe(true);
   });
@@ -138,8 +138,8 @@ describe("Suite 2: Graph Structure", () => {
   test("2.2 $START has multiple status keys", () => {
     const wf = makeWorkflow();
     wf.graph.$START = {
-      _: { role: "writer", prompt: "Begin" },
-      other: { role: "reviewer", prompt: "Also" },
+      _: { role: "writer", prompt: "Begin", location: null },
+      other: { role: "reviewer", prompt: "Also", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
@@ -149,7 +149,7 @@ describe("Suite 2: Graph Structure", () => {
 
   test("2.3 $START edge uses non-_ status", () => {
     const wf = makeWorkflow();
-    wf.graph.$START = { ready: { role: "writer", prompt: "Begin" } };
+    wf.graph.$START = { ready: { role: "writer", prompt: "Begin", location: null } };
     const errors = validateWorkflow(wf);
     expect(
       errors.some((e) => e.includes('$START must have exactly one edge with status "_"')),
@@ -158,7 +158,7 @@ describe("Suite 2: Graph Structure", () => {
 
   test("2.4 $END has outgoing edges", () => {
     const wf = makeWorkflow();
-    wf.graph.$END = { _: { role: "writer", prompt: "Loop" } };
+    wf.graph.$END = { _: { role: "writer", prompt: "Loop", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes("$END must not have outgoing edges"))).toBe(true);
   });
@@ -177,7 +177,7 @@ describe("Suite 2: Graph Structure", () => {
         required: ["$status"],
       } as unknown as string,
     };
-    wf.graph.isolated = { _: { role: "$END", prompt: "done" } };
+    wf.graph.isolated = { _: { role: "$END", prompt: "done", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes('role "isolated" is not reachable from $START'))).toBe(
       true,
@@ -186,7 +186,7 @@ describe("Suite 2: Graph Structure", () => {
 
   test("2.6 edge target references invalid role", () => {
     const wf = makeWorkflow();
-    wf.graph.writer = { _: { role: "ghost", prompt: "Go to ghost" } };
+    wf.graph.writer = { _: { role: "ghost", prompt: "Go to ghost", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes('unknown target role "ghost"'))).toBe(true);
   });
@@ -196,8 +196,8 @@ describe("Suite 3: Status-Edge Consistency", () => {
   test("3.1 single-exit role with multiple graph keys", () => {
     const wf = makeWorkflow();
     wf.graph.writer = {
-      _: { role: "reviewer", prompt: "Review" },
-      extra: { role: "$END", prompt: "Done" },
+      _: { role: "reviewer", prompt: "Review", location: null },
+      extra: { role: "$END", prompt: "Done", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
@@ -209,7 +209,7 @@ describe("Suite 3: Status-Edge Consistency", () => {
 
   test("3.2 single-exit role missing _ key", () => {
     const wf = makeWorkflow();
-    wf.graph.writer = { done: { role: "reviewer", prompt: "Review" } };
+    wf.graph.writer = { done: { role: "reviewer", prompt: "Review", location: null } };
     const errors = validateWorkflow(wf);
     expect(
       errors.some((e) => e.includes('role "writer" is single-exit but graph has no "_" key')),
@@ -219,9 +219,9 @@ describe("Suite 3: Status-Edge Consistency", () => {
   test("3.3 multi-exit role with extra statuses", () => {
     const wf = makeWorkflow();
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done" },
-      rejected: { role: "writer", prompt: "Fix" },
-      timeout: { role: "$END", prompt: "Timed out" },
+      approved: { role: "$END", prompt: "Done", location: null },
+      rejected: { role: "writer", prompt: "Fix", location: null },
+      timeout: { role: "$END", prompt: "Timed out", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
@@ -232,7 +232,7 @@ describe("Suite 3: Status-Edge Consistency", () => {
   test("3.4 multi-exit role missing a status", () => {
     const wf = makeWorkflow();
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done" },
+      approved: { role: "$END", prompt: "Done", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
@@ -242,7 +242,7 @@ describe("Suite 3: Status-Edge Consistency", () => {
 
   test("3.5 multi-exit role with _ key", () => {
     const wf = makeWorkflow();
-    wf.graph.reviewer = { _: { role: "$END", prompt: "Done" } };
+    wf.graph.reviewer = { _: { role: "$END", prompt: "Done", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes('role "reviewer" is multi-exit but graph uses "_"'))).toBe(
       true,
@@ -265,8 +265,8 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
       } as unknown as string,
     };
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done" },
-      rejected: { role: "writer", prompt: "Fix: {{{comments}}}" },
+      approved: { role: "$END", prompt: "Done", location: null },
+      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(errors).toEqual([]);
@@ -286,9 +286,9 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
       } as unknown as string,
     };
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done" },
-      rejected: { role: "writer", prompt: "Fix" },
-      timeout: { role: "$END", prompt: "Timed out" },
+      approved: { role: "$END", prompt: "Done", location: null },
+      rejected: { role: "writer", prompt: "Fix", location: null },
+      timeout: { role: "$END", prompt: "Timed out", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes("extra status keys: timeout"))).toBe(true);
@@ -308,7 +308,7 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
       } as unknown as string,
     };
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done" },
+      approved: { role: "$END", prompt: "Done", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes("missing status keys: rejected"))).toBe(true);
@@ -327,7 +327,7 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
         required: ["$status", "plan"],
       } as unknown as string,
     };
-    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{plan}}}" } };
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{plan}}}", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors).toEqual([]);
   });
@@ -346,8 +346,8 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
       } as unknown as string,
     };
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done: {{{nonexistent}}}" },
-      rejected: { role: "writer", prompt: "Fix: {{{comments}}}" },
+      approved: { role: "$END", prompt: "Done: {{{nonexistent}}}", location: null },
+      rejected: { role: "writer", prompt: "Fix: {{{comments}}}", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(errors.some((e) => e.includes("nonexistent") && e.includes("not found"))).toBe(true);
@@ -357,7 +357,7 @@ describe("Suite 3b: Enum-Based Multi-Exit", () => {
 describe("Suite 4: Mustache Template Variable Existence", () => {
   test("4.1 prompt references nonexistent variable (single-exit)", () => {
     const wf = makeWorkflow();
-    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{branch}}}" } };
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Review: {{{branch}}}", location: null } };
     const errors = validateWorkflow(wf);
     expect(
       errors.some((e) =>
@@ -369,8 +369,8 @@ describe("Suite 4: Mustache Template Variable Existence", () => {
   test("4.2 prompt references nonexistent variable (multi-exit)", () => {
     const wf = makeWorkflow();
     wf.graph.reviewer = {
-      approved: { role: "$END", prompt: "Done: {{{branch}}}" },
-      rejected: { role: "writer", prompt: "Fix: {{{reason}}}" },
+      approved: { role: "$END", prompt: "Done: {{{branch}}}", location: null },
+      rejected: { role: "writer", prompt: "Fix: {{{reason}}}", location: null },
     };
     const errors = validateWorkflow(wf);
     expect(
@@ -388,7 +388,7 @@ describe("Suite 4: Mustache Template Variable Existence", () => {
 
   test("4.4 $status variable is always valid", () => {
     const wf = makeWorkflow();
-    wf.graph.writer = { _: { role: "reviewer", prompt: "Status: {{$status}}" } };
+    wf.graph.writer = { _: { role: "reviewer", prompt: "Status: {{$status}}", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors).toEqual([]);
   });
@@ -461,9 +461,9 @@ describe("Suite 6: Multiple Errors Collection", () => {
       } as unknown as string,
     };
     // unknown graph reference
-    wf.graph.nonexistent = { _: { role: "$END", prompt: "done" } };
+    wf.graph.nonexistent = { _: { role: "$END", prompt: "done", location: null } };
     // bad mustache var
-    wf.graph.writer = { _: { role: "reviewer", prompt: "{{{badvar}}}" } };
+    wf.graph.writer = { _: { role: "reviewer", prompt: "{{{badvar}}}", location: null } };
     const errors = validateWorkflow(wf);
     expect(errors.length).toBeGreaterThanOrEqual(3);
   });

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

@@ -15,6 +15,8 @@ import { loadWorkflowRegistry, saveWorkflowRegistry } from "../store.js";
 async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
   const casDir = join(storageRoot, "cas");
   await mkdir(casDir, { recursive: true });
+  // Set UNCAGED_CAS_DIR to use the test's CAS directory
+  process.env.UNCAGED_CAS_DIR = casDir;
   const store = createFsStore(casDir);
   const schemas = await registerUwfSchemas(store);
   return { storageRoot, store, schemas };
@@ -41,8 +43,8 @@ function makeMinimalPayload(name: string, description: string): WorkflowPayload
       },
     },
     graph: {
-      $START: { _: { role: "worker", prompt: "start working" } },
-      worker: { _: { role: "$END", prompt: "done" } },
+      $START: { _: { role: "worker", prompt: "start working", location: null } },
+      worker: { _: { role: "$END", prompt: "done", location: null } },
     },
   };
 }

packages/cli-workflow/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
+import type { CasRef, ThreadId, ThreadStatus } from "@uncaged/workflow-protocol";
 import { Command } from "commander";
 import {
   cmdCasGet,
@@ -17,11 +17,12 @@ import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js"
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import {
-  cmdSkillArchitecture,
-  cmdSkillCli,
+  cmdSkillAdapter,
+  cmdSkillAuthor,
+  cmdSkillBootstrap,
+  cmdSkillDeveloper,
   cmdSkillList,
-  cmdSkillModerator,
-  cmdSkillYaml,
+  cmdSkillUser,
 } from "./commands/skill.js";
 import { cmdStepFork, cmdStepList, cmdStepRead, cmdStepShow } from "./commands/step.js";
 import {
@@ -33,7 +34,6 @@ import {
   cmdThreadStart,
   cmdThreadStop,
   THREAD_READ_DEFAULT_QUOTA,
-  type ThreadStatus,
 } from "./commands/thread.js";
 import { parseTimeInput } from "./commands/thread-time-parser.js";
 import { cmdWorkflowAdd, cmdWorkflowList, cmdWorkflowShow } from "./commands/workflow.js";
@@ -113,10 +113,17 @@ thread
   .description("Create a thread without executing")
   .argument("<workflow>", "Workflow name or hash")
   .requiredOption("-p, --prompt <text>", "User prompt")
-  .action((workflow: string, opts: { prompt: string }) => {
+  .option("--cwd <path>", "Working directory for thread execution (default: process.cwd())")
+  .action((workflow: string, opts: { prompt: string; cwd: string | undefined }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      const result = await cmdThreadStart(storageRoot, workflow, opts.prompt, process.cwd());
+      const result = await cmdThreadStart(
+        storageRoot,
+        workflow,
+        opts.prompt,
+        process.cwd(),
+        opts.cwd ?? process.cwd(),
+      );
       writeOutput(result);
     });
   });
@@ -357,7 +364,8 @@ step
   .description("Read a step's turns as human-readable markdown")
   .argument("<step-hash>", "CAS hash of the StepNode")
   .option("--quota <chars>", "Max output characters", "4000")
-  .action((stepHash: string, opts: { quota: string }) => {
+  .option("--prompt", "Show the assembled prompt sent to the agent instead of turns")
+  .action((stepHash: string, opts: { quota: string; prompt: boolean }) => {
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const quota = Number.parseInt(opts.quota, 10);
@@ -365,7 +373,12 @@ step
         process.stderr.write("invalid --quota: must be a positive integer\n");
         process.exit(1);
       }
-      const markdown = await cmdStepRead(storageRoot, stepHash as CasRef, quota);
+      const markdown = await cmdStepRead(
+        storageRoot,
+        stepHash as CasRef,
+        quota,
+        opts.prompt === true,
+      );
       process.stdout.write(markdown.endsWith("\n") ? markdown : `${markdown}\n`);
     });
   });
@@ -483,31 +496,38 @@ const skill = program.command("skill").description("Built-in skill references fo
 skill.addHelpCommand(false);
 
 skill
-  .command("cli")
-  .description("Print a markdown reference of all uwf commands")
+  .command("adapter")
+  .description("Print the adapter reference (building agent adapters)")
   .action(() => {
-    console.log(cmdSkillCli());
+    console.log(cmdSkillAdapter());
   });
 
 skill
-  .command("architecture")
-  .description("Print the architecture reference")
+  .command("author")
+  .description("Print the author reference (workflow YAML design guide)")
   .action(() => {
-    console.log(cmdSkillArchitecture());
+    console.log(cmdSkillAuthor());
   });
 
 skill
-  .command("yaml")
-  .description("Print the workflow YAML schema reference")
+  .command("developer")
+  .description("Print the developer reference (coding conventions + architecture)")
   .action(() => {
-    console.log(cmdSkillYaml());
+    console.log(cmdSkillDeveloper());
   });
 
 skill
-  .command("moderator")
-  .description("Print the moderator reference")
+  .command("user")
+  .description("Print the user reference (CLI guide + typical workflows)")
   .action(() => {
-    console.log(cmdSkillModerator());
+    console.log(cmdSkillUser());
+  });
+
+skill
+  .command("bootstrap")
+  .description("Print the bootstrap skill YAML for Hermes agents")
+  .action(() => {
+    console.log(cmdSkillBootstrap());
   });
 
 skill
@@ -524,7 +544,7 @@ program
   .option("--base-url <url>", "OpenAI-compatible API base URL")
   .option("--api-key <key>", "API key")
   .option("--model <name>", "Default model name")
-  .option("--agent <name>", "Default agent alias")
+  .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
   .action(
     (opts: {
       provider?: string;

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

@@ -5,7 +5,10 @@ import { parse, stringify } from "yaml";
 /**
  * Valid configuration key schema
  */
-const VALID_CONFIG_KEYS: Record<string, { nested: boolean; knownFields?: string[] }> = {
+const VALID_CONFIG_KEYS: Record<
+  string,
+  { nested: boolean; knownFields?: string[]; minDepth?: number }
+> = {
   providers: {
     nested: true,
     knownFields: ["baseUrl", "apiKey"],
@@ -18,6 +21,17 @@ const VALID_CONFIG_KEYS: Record<string, { nested: boolean; knownFields?: string[
     nested: true,
     knownFields: ["command", "args"],
   },
+  agentOverrides: {
+    nested: true,
+    // agentOverrides.<workflowName>.<roleName> = agentAlias (string value)
+    // No knownFields — workflow/role names are user-defined
+  },
+  modelOverrides: {
+    nested: true,
+    minDepth: 2,
+    // modelOverrides.<scenario> = modelAlias (string value)
+    // No knownFields — scenarios are user-defined
+  },
   defaultAgent: { nested: false },
   defaultModel: { nested: false },
 };
@@ -43,8 +57,9 @@ function validateConfigKey(path: string[]): void {
     throw new Error(`${topLevel} is a scalar key and cannot have nested properties`);
   }
 
-  // Nested keys must have at least 3 segments (e.g., providers.myProvider.baseUrl)
-  if (schema.nested && path.length < 3) {
+  // Nested keys must have at least minDepth segments (default 3)
+  const minDepth = schema.minDepth ?? 3;
+  if (schema.nested && path.length < minDepth) {
     const fields = schema.knownFields?.join(", ") ?? "";
     throw new Error(
       `Incomplete path for ${topLevel}. Must specify a field (e.g., ${topLevel}.<name>.<field>). Valid fields: ${fields}`,

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

@@ -1,11 +1,12 @@
 export {
-  generateArchitectureReference as cmdSkillArchitecture,
-  generateCliReference as cmdSkillCli,
-  generateModeratorReference as cmdSkillModerator,
-  generateYamlReference as cmdSkillYaml,
+  generateAdapterReference as cmdSkillAdapter,
+  generateAuthorReference as cmdSkillAuthor,
+  generateBootstrapReference as cmdSkillBootstrap,
+  generateDeveloperReference as cmdSkillDeveloper,
+  generateUserReference as cmdSkillUser,
 } from "@uncaged/workflow-util";
 
-const SKILL_NAMES = ["cli", "architecture", "yaml", "moderator"] as const;
+const SKILL_NAMES = ["user", "author", "developer", "adapter", "bootstrap"] as const;
 
 export function cmdSkillList(): ReadonlyArray<string> {
   return [...SKILL_NAMES];

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

@@ -289,6 +289,7 @@ export async function cmdStepRead(
   storageRoot: string,
   stepHash: CasRef,
   quota: number,
+  showPrompt: boolean,
 ): Promise<string> {
   const uwf = await createUwfStore(storageRoot);
   const node = uwf.store.get(stepHash);
@@ -300,6 +301,23 @@ export async function cmdStepRead(
   }
   const payload = node.payload as StepNodePayload;
 
+  // --prompt mode: show the assembled prompt that was sent to the agent
+  if (showPrompt) {
+    const promptRef = (payload as Record<string, unknown>).assembledPrompt;
+    if (typeof promptRef !== "string") {
+      return `# Step ${stepHash}\n\n_Prompt not recorded (legacy step)._`;
+    }
+    const promptNode = uwf.store.get(promptRef as CasRef);
+    if (promptNode === null) {
+      return `# Step ${stepHash}\n\n_Prompt CAS node not found: ${promptRef}_`;
+    }
+    const promptText =
+      typeof promptNode.payload === "string"
+        ? promptNode.payload
+        : JSON.stringify(promptNode.payload);
+    return `# Step ${stepHash}\n\n**Role:** ${payload.role}\n**Agent:** ${payload.agent}\n\n## Prompt\n\n${promptText}`;
+  }
+
   if (payload.detail === null) {
     return formatStepMarkdown(stepHash, payload.role, payload.agent, [], []);
   }

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

@@ -12,6 +12,7 @@ import type {
   StepOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStatus,
   ThreadsIndex,
   WorkflowConfig,
   WorkflowPayload,
@@ -22,6 +23,7 @@ import {
   generateUlid,
   type ProcessLogger,
 } from "@uncaged/workflow-util";
+import type { AdapterOutput } from "@uncaged/workflow-util-agent";
 import { getEnvPath, loadWorkflowConfig } from "@uncaged/workflow-util-agent";
 import { config as loadDotenv } from "dotenv";
 import { parse } from "yaml";
@@ -55,6 +57,21 @@ const END_ROLE = "$END";
 const START_ROLE = "$START";
 export const THREAD_READ_DEFAULT_QUOTA = 4000;
 
+/**
+ * Derive the current/next role from the workflow graph and chain state.
+ * Returns null when the next role is $END or evaluation fails.
+ */
+function resolveCurrentRole(uwf: UwfStore, head: CasRef, workflowRef: CasRef): string | null {
+  const chain = walkChain(uwf, head);
+  const { lastRole, lastOutput } = resolveEvaluateArgs(uwf, chain);
+  const workflow = loadWorkflowPayload(uwf, workflowRef);
+  const result = evaluate(workflow.graph, lastRole, lastOutput);
+  if (!result.ok) {
+    return null;
+  }
+  return result.value.role === END_ROLE ? null : result.value.role;
+}
+
 const PL_THREAD_START = "7HNQ4B2X";
 const PL_MODERATOR = "M3K8V9T1";
 const PL_AGENT_SPAWN = "R5J2W8N4";
@@ -266,7 +283,13 @@ export async function cmdThreadStart(
   workflowId: string,
   prompt: string,
   projectRoot: string,
+  cwd: string = process.cwd(),
 ): Promise<StartOutput> {
+  // Validate cwd is an absolute path
+  if (!isAbsolute(cwd)) {
+    fail("cwd must be an absolute path");
+  }
+
   const uwf = await createUwfStore(storageRoot);
   const workflowHash = await resolveWorkflowCasRef(uwf, storageRoot, workflowId, projectRoot);
 
@@ -278,6 +301,7 @@ export async function cmdThreadStart(
   const startPayload: StartNodePayload = {
     workflow: workflowHash,
     prompt,
+    cwd,
   };
 
   const headHash = await uwf.store.put(uwf.schemas.startNode, startPayload);
@@ -308,10 +332,18 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
     if (workflow === null) {
       fail(`failed to resolve workflow from head: ${activeHead}`);
     }
+
+    // Check if thread is running
+    const runningMarker = await isThreadRunning(storageRoot, threadId);
+    const status: ThreadStatus = runningMarker !== null ? "running" : "idle";
+    const currentRole = resolveCurrentRole(uwf, activeHead, workflow);
+
     return {
       workflow,
       thread: threadId,
       head: activeHead,
+      status,
+      currentRole,
       done: false,
       background: null,
     };
@@ -319,10 +351,14 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
 
   const hist = await findThreadInHistory(storageRoot, threadId);
   if (hist !== null) {
+    const status: ThreadStatus = hist.reason === "cancelled" ? "cancelled" : "completed";
+
     return {
       workflow: hist.workflow,
       thread: threadId,
       head: hist.head,
+      status,
+      currentRole: null,
       done: true,
       background: null,
     };
@@ -331,10 +367,9 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
   fail(`thread not found: ${threadId}`);
 }
 
-export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
-
 export type ThreadListItemWithStatus = ThreadListItem & {
   status: ThreadStatus;
+  currentRole: string | null;
 };
 
 async function threadListItemFromActive(
@@ -352,7 +387,13 @@ async function threadListItemFromActive(
   const runningMarker = await isThreadRunning(storageRoot, threadId);
   const status: ThreadStatus = runningMarker !== null ? "running" : "idle";
 
-  return { thread: threadId, workflow, head, status };
+  return {
+    thread: threadId,
+    workflow,
+    head,
+    status,
+    currentRole: resolveCurrentRole(uwf, head, workflow),
+  };
 }
 
 async function collectActiveThreads(
@@ -390,6 +431,7 @@ async function collectCompletedThreads(
         workflow: entry.workflow,
         head: entry.head,
         status: entry.reason === "cancelled" ? "cancelled" : "completed",
+        currentRole: null,
       });
     }
   }
@@ -772,7 +814,8 @@ function spawnAgent(
   threadId: ThreadId,
   role: string,
   edgePrompt: string,
-): CasRef {
+  cwd: string,
+): AdapterOutput {
   const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
   let stdout: string;
   try {
@@ -780,6 +823,7 @@ function spawnAgent(
       encoding: "utf8",
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
+      cwd,
     });
   } catch (e) {
     const err = e as NodeJS.ErrnoException & { stderr?: Buffer | string | null };
@@ -794,10 +838,22 @@ function spawnAgent(
   }
 
   const line = stdout.trim().split("\n").pop()?.trim() ?? "";
-  if (!isCasRef(line)) {
-    failStep(plog, `agent stdout is not a valid CAS hash: ${line || "(empty)"}`);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    failStep(plog, `agent stdout last line is not valid JSON: ${line || "(empty)"}`);
   }
-  return line;
+  const obj = parsed as Record<string, unknown>;
+  if (
+    typeof obj !== "object" ||
+    obj === null ||
+    typeof obj.stepHash !== "string" ||
+    !isCasRef(obj.stepHash as string)
+  ) {
+    failStep(plog, `agent stdout JSON missing valid stepHash: ${line}`);
+  }
+  return obj as unknown as AdapterOutput;
 }
 
 async function archiveThread(
@@ -908,6 +964,8 @@ async function cmdThreadStepBackground(
     failStep(plog, `thread not active: ${threadId}`);
   }
 
+  const uwf = await createUwfStore(storageRoot);
+
   // Spawn detached background process
   const scriptPath = process.argv[1];
   if (scriptPath === undefined) {
@@ -938,6 +996,8 @@ async function cmdThreadStepBackground(
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
+      status: "running",
+      currentRole: resolveCurrentRole(uwf, headHash, workflowHash),
       done: false,
       background: true,
     },
@@ -980,6 +1040,8 @@ async function cmdThreadStepOnce(
       workflow: workflowHash,
       thread: threadId,
       head: headHash,
+      status: "completed",
+      currentRole: null,
       done: true,
       background: null,
     };
@@ -987,6 +1049,11 @@ async function cmdThreadStepOnce(
 
   const role = nextResult.value.role;
   const edgePrompt = nextResult.value.prompt;
+
+  // Resolve cwd: use edge location if provided, otherwise inherit thread.cwd
+  const threadCwd = chain.start.cwd;
+  const effectiveCwd = nextResult.value.location !== null ? nextResult.value.location : threadCwd;
+
   const config = await loadWorkflowConfig(storageRoot);
   const agent = resolveAgentConfig(config, workflow, role, agentOverride);
 
@@ -995,7 +1062,8 @@ async function cmdThreadStepOnce(
   });
 
   loadDotenv({ path: getEnvPath(storageRoot) });
-  const newHead = spawnAgent(plog, agent, threadId, role, edgePrompt);
+  const agentResult = spawnAgent(plog, agent, threadId, role, edgePrompt, effectiveCwd);
+  const newHead = agentResult.stepHash as CasRef;
 
   plog.log(PL_AGENT_DONE, `agent returned head=${newHead}`, null);
 
@@ -1027,10 +1095,16 @@ async function cmdThreadStepOnce(
     await archiveThread(storageRoot, threadId, workflowHash, newHead);
   }
 
+  // Determine status based on whether thread is done and running state
+  const status: ThreadStatus = done ? "completed" : "idle";
+  const currentRole = done ? null : afterResult.value.role;
+
   return {
     workflow: workflowHash,
     thread: threadId,
     head: newHead,
+    status,
+    currentRole,
     done,
     background: null,
   };

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

@@ -61,6 +61,7 @@ function normalizeGraph(
       normalized[status] = {
         role: target.role,
         prompt: target.prompt,
+        location: target.location ?? null,
       };
     }
     result[node] = normalized;

packages/cli-workflow/src/moderator/__tests__/evaluate.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, test } from "vitest";
+import { evaluate } from "../evaluate.js";
+
+describe("Edge prompt template variable resolution", () => {
+  test("returns error when rendered prompt is empty string", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("returns error when rendered prompt is whitespace-only", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "  {{{userPrompt}}}  ", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.message).toContain("prompt");
+      expect(result.error.message).toContain("empty");
+    }
+  });
+
+  test("succeeds when all template variables resolve to non-empty values", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", { userPrompt: "Fix the bug" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Fix the bug");
+    }
+  });
+
+  test("succeeds with static (no-variable) prompt", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Classify this input", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Classify this input");
+    }
+  });
+
+  test("succeeds when prompt has mix of static text and unresolved variables", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "Please handle: {{{userPrompt}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.prompt).toBe("Please handle: ");
+    }
+  });
+
+  test("returns error when ALL variables missing and no static text remains", () => {
+    const graph = {
+      $START: {
+        _: { role: "classifier", prompt: "{{{a}}}{{{b}}}", location: null },
+      },
+    };
+
+    const result = evaluate(graph, "$START", {});
+
+    expect(result.ok).toBe(false);
+  });
+});
+
+describe("Moderator location resolution", () => {
+  test("returns null location when edge has no location field", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: null,
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.location).toBe(null);
+    }
+  });
+
+  test("resolves static location string", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "/static/path",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.location).toBe("/static/path");
+    }
+  });
+
+  test("resolves mustache template location", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{repoPath}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", {
+      $status: "ready",
+      repoPath: "/home/user/repo",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.location).toBe("/home/user/repo");
+    }
+  });
+
+  test("resolves mustache template with multiple variables", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{basePath}}}/{{{projectName}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", {
+      $status: "ready",
+      basePath: "/home/user",
+      projectName: "myproject",
+    });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.location).toBe("/home/user/myproject");
+    }
+  });
+
+  test("handles missing template variable gracefully", () => {
+    const graph = {
+      planner: {
+        ready: {
+          role: "coder",
+          prompt: "Implement the code",
+          location: "{{{repoPath}}}",
+        },
+      },
+    };
+
+    const result = evaluate(graph, "planner", { $status: "ready" });
+
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Mustache renders missing variables as empty string
+      expect(result.value.location).toBe("");
+    }
+  });
+});

packages/cli-workflow/src/moderator/evaluate.ts

@@ -43,7 +43,16 @@ export function evaluate(
 
   try {
     const prompt = mustache.render(target.prompt, lastOutput);
-    return { ok: true, value: { role: target.role, prompt } };
+    if (prompt.trim() === "") {
+      return {
+        ok: false,
+        error: new Error(
+          `edge prompt resolved to empty string for role "${target.role}" (template: "${target.prompt}"). Check that upstream output includes required variables.`,
+        ),
+      };
+    }
+    const location = target.location !== null ? mustache.render(target.location, lastOutput) : null;
+    return { ok: true, value: { role: target.role, prompt, location } };
   } catch (error) {
     return {
       ok: false,

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

@@ -4,4 +4,6 @@ export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
 export type EvaluateResult = {
   role: string;
   prompt: string;
+  /** Resolved working directory from edge location field (null = inherit thread cwd). */
+  location: string | null;
 };

packages/cli-workflow/src/store.ts

@@ -70,10 +70,26 @@ export function resolveStorageRoot(): string {
   return getDefaultStorageRoot();
 }
 
+/**
+ * Deprecated: Use `getGlobalCasDir()` instead.
+ * Returns the old CAS directory for backward compatibility.
+ */
 export function getCasDir(storageRoot: string): string {
   return join(storageRoot, "cas");
 }
 
+/**
+ * Returns the global CAS directory shared by all uwf and json-cas tools.
+ * Priority: UNCAGED_CAS_DIR environment variable → default ~/.uncaged/json-cas
+ */
+export function getGlobalCasDir(): string {
+  const envPath = process.env.UNCAGED_CAS_DIR;
+  if (envPath !== undefined && envPath !== "") {
+    return envPath;
+  }
+  return join(homedir(), ".uncaged", "json-cas");
+}
+
 export function getRegistryPath(storageRoot: string): string {
   return join(storageRoot, "workflows.yaml");
 }
@@ -98,7 +114,7 @@ export type UwfStore = {
 };
 
 export async function createUwfStore(storageRoot: string): Promise<UwfStore> {
-  const casDir = getCasDir(storageRoot);
+  const casDir = getGlobalCasDir();
   await mkdir(casDir, { recursive: true });
   const store = createFsStore(casDir);
   const schemas = await registerUwfSchemas(store);

packages/cli-workflow/src/validate.ts

@@ -36,8 +36,13 @@ function isTarget(value: unknown): boolean {
   if (!isRecord(value)) {
     return false;
   }
+  const hasValidLocation =
+    value.location === undefined || value.location === null || typeof value.location === "string";
   return (
-    typeof value.role === "string" && typeof value.prompt === "string" && value.prompt.trim() !== ""
+    typeof value.role === "string" &&
+    typeof value.prompt === "string" &&
+    value.prompt.trim() !== "" &&
+    hasValidLocation
   );
 }
 
@@ -95,5 +100,22 @@ export function parseWorkflowPayload(raw: unknown): WorkflowPayload | null {
   if (!isStringRecord(raw.roles, isRoleDefinition) || !isGraph(raw.graph)) {
     return null;
   }
-  return raw as WorkflowPayload;
+
+  // Normalize location field: undefined → null
+  const normalized = { ...raw } as WorkflowPayload;
+  for (const roleName of Object.keys(normalized.graph)) {
+    const statusMap = normalized.graph[roleName];
+    if (statusMap !== undefined) {
+      for (const status of Object.keys(statusMap)) {
+        const target = statusMap[status];
+        if (target !== undefined) {
+          if (target.location === undefined) {
+            target.location = null;
+          }
+        }
+      }
+    }
+  }
+
+  return normalized;
 }

packages/cli-workflow/vitest.config.ts

@@ -3,5 +3,6 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   test: {
     include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
   },
 });

packages/workflow-agent-builtin/package.json

@@ -18,8 +18,9 @@
     }
   },
   "scripts": {
-    "test": "bun test",
-    "test:ci": "bun test"
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",
@@ -34,12 +35,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-agent-builtin"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

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

@@ -82,7 +82,7 @@ async function runBuiltinWithMessages(
 
   if (loopResult.turnCount === 0) {
     log("5RWTK9NB", "no turns produced, returning empty output");
-    return { output: "", detailHash: "", sessionId: session.sessionId };
+    return { output: "", detailHash: "", sessionId: session.sessionId, assembledPrompt: "" };
   }
 
   // Read jsonl → persist turns to CAS → store detail
@@ -94,7 +94,12 @@ async function runBuiltinWithMessages(
     session.startedAtMs,
   );
 
-  return { output: stripPreamble(loopResult.finalText), detailHash, sessionId: session.sessionId };
+  return {
+    output: stripPreamble(loopResult.finalText),
+    detailHash,
+    sessionId: session.sessionId,
+    assembledPrompt: "",
+  };
 }
 
 async function runBuiltin(ctx: AgentContext): Promise<AgentRunResult> {

packages/workflow-agent-builtin/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

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

@@ -18,8 +18,9 @@
     }
   },
   "scripts": {
-    "test": "bun test",
-    "test:ci": "bun test"
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",
@@ -34,12 +35,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-agent-claude-code"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

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

@@ -120,12 +120,16 @@ function spawnClaudeResume(
   return spawnClaude(args);
 }
 
-async function processClaudeOutput(stdout: string, store: Store): Promise<AgentRunResult> {
+async function processClaudeOutput(
+  stdout: string,
+  store: Store,
+  assembledPrompt: string,
+): Promise<AgentRunResult> {
   const parsed = parseClaudeCodeStreamOutput(stdout);
 
   if (parsed !== null) {
     const { detailHash, output, sessionId } = await storeClaudeCodeDetail(store, parsed);
-    return { output, detailHash, sessionId };
+    return { output, detailHash, sessionId, assembledPrompt };
   }
 
   throw new Error(
@@ -144,7 +148,7 @@ async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
     if (cachedSessionId !== null) {
       try {
         const { stdout } = await spawnClaudeResume(cachedSessionId, fullPrompt);
-        const result = await processClaudeOutput(stdout, ctx.store);
+        const result = await processClaudeOutput(stdout, ctx.store, fullPrompt);
         if (result.sessionId !== undefined && result.sessionId !== "") {
           await setCachedSessionId("claude-code", ctx.threadId, ctx.role, result.sessionId);
         }
@@ -152,16 +156,14 @@ async function runClaudeCode(ctx: AgentContext): Promise<AgentRunResult> {
       } catch (err) {
         log(
           "5VKR8N3Q",
-          "resume failed for session %s, falling back to fresh run: %s",
-          cachedSessionId,
-          err,
+          `resume failed for session ${cachedSessionId}, falling back to fresh run: ${err}`,
         );
       }
     }
   }
 
   const { stdout } = await spawnClaudeRun(fullPrompt);
-  const result = await processClaudeOutput(stdout, ctx.store);
+  const result = await processClaudeOutput(stdout, ctx.store, fullPrompt);
   if (result.sessionId !== undefined && result.sessionId !== "") {
     await setCachedSessionId("claude-code", ctx.threadId, ctx.role, result.sessionId);
   }
@@ -174,7 +176,7 @@ async function continueClaudeCode(
   store: Store,
 ): Promise<AgentRunResult> {
   const { stdout } = await spawnClaudeResume(sessionId, message);
-  return processClaudeOutput(stdout, store);
+  return processClaudeOutput(stdout, store, "");
 }
 
 /** Agent CLI factory: parses argv, runs Claude Code, extracts output, writes StepNode. */

packages/workflow-agent-claude-code/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

packages/workflow-agent-hermes/README.md

@@ -1,10 +1,12 @@
 # @uncaged/workflow-agent-hermes
 
-`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
+`uwf-hermes` — an **agent adapter** that bridges the `uwf` workflow engine and the Hermes CLI.
 
 ## Overview
 
-Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
+`uwf-hermes` is an adapter (not the Hermes CLI itself). The `uwf` engine speaks a generic agent protocol (stdin/stdout frontmatter contract); `uwf-hermes` translates that protocol into Hermes ACP (Agent Client Protocol) calls. Other adapters (e.g. `uwf-claude-code`, `uwf-cursor`) do the same for their respective CLIs.
+
+On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
 
 **Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-util-agent`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
 

packages/workflow-agent-hermes/__tests__/issue-551.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const PKG_ROOT = join(import.meta.dir, "..");
+
+describe("Issue #551 — bin entry & engines", () => {
+  test("package.json declares bun in engines", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    expect(pkg.engines).toBeDefined();
+    expect(pkg.engines.bun).toBeDefined();
+    expect(pkg.engines.bun).toMatch(/^>=?\s*[\d.]+/);
+  });
+
+  test("bin entry file has bun shebang", () => {
+    const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8"));
+    const binPath = pkg.bin["uwf-hermes"];
+    const content = readFileSync(join(PKG_ROOT, binPath), "utf-8");
+    expect(content.startsWith("#!/usr/bin/env bun")).toBe(true);
+  });
+
+  test("README.md explains uwf-hermes is an adapter", () => {
+    const readme = readFileSync(join(PKG_ROOT, "README.md"), "utf-8");
+    expect(readme.toLowerCase()).toContain("adapter");
+    expect(readme).toMatch(/uwf-hermes/);
+    expect(readme).toMatch(/hermes/);
+  });
+});

packages/workflow-agent-hermes/__tests__/session-detail.test.ts

@@ -1,9 +1,15 @@
+import { Database } from "bun:sqlite";
 import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { createMemoryStore, refs, validate, walk } from "@uncaged/json-cas";
 
 import {
   computeDurationMs,
   extractLastAssistantContent,
+  getHermesDbPath,
+  loadHermesSessionFromDb,
   messageToTurnPayload,
   parseSessionIdFromStdout,
   storeHermesSessionDetail,
@@ -124,3 +130,236 @@ describe("storeHermesSessionDetail", () => {
     }
   });
 });
+
+// ── SQLite fallback tests ──────────────────────────────────────────
+
+function createTestDb(dbPath: string): Database {
+  const db = new Database(dbPath);
+  db.run(`CREATE TABLE sessions (
+    id TEXT PRIMARY KEY,
+    model TEXT NOT NULL,
+    started_at INTEGER NOT NULL
+  )`);
+  db.run(`CREATE TABLE messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    content TEXT,
+    reasoning TEXT,
+    tool_calls TEXT,
+    FOREIGN KEY (session_id) REFERENCES sessions(id)
+  )`);
+  return db;
+}
+
+describe("getHermesDbPath", () => {
+  test("returns correct path", () => {
+    const { homedir } = require("node:os");
+    const { join } = require("node:path");
+    expect(getHermesDbPath()).toBe(join(homedir(), ".hermes", "state.db"));
+  });
+});
+
+describe("loadHermesSessionFromDb", () => {
+  test("returns session data from SQLite", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-session-001";
+    const startedAt = 1748099519;
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "claude-opus-4.6",
+      startedAt,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "hello", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "hi there", "thinking...", null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.session_id).toBe(sessionId);
+    expect(result!.model).toBe("claude-opus-4.6");
+    expect(result!.messages).toHaveLength(2);
+    expect(result!.messages[0]!.role).toBe("user");
+    expect(result!.messages[0]!.content).toBe("hello");
+    expect(result!.messages[1]!.role).toBe("assistant");
+    expect(result!.messages[1]!.content).toBe("hi there");
+    expect(result!.messages[1]!.reasoning).toBe("thinking...");
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("returns null when no session exists in DB", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+    db.close();
+
+    const result = await loadHermesSessionFromDb("nonexistent", dbPath);
+    expect(result).toBeNull();
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("returns null when DB file does not exist", async () => {
+    const result = await loadHermesSessionFromDb("any-id", "/tmp/nonexistent-hermes-db.db");
+    expect(result).toBeNull();
+  });
+
+  test("correctly parses tool_calls from DB JSON string", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-tool-calls";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "gpt-4",
+      1748099519,
+    ]);
+    const toolCallsJson = JSON.stringify([
+      { function: { name: "read_file", arguments: '{"path":"x"}' } },
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "", null, toolCallsJson],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.messages[0]!.tool_calls).toEqual([
+      { function: { name: "read_file", arguments: '{"path":"x"}' } },
+    ]);
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("handles null fields in DB messages gracefully", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-nulls";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", null, null, null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    const msg = result!.messages[0]!;
+    expect(msg.content).toBeNull();
+    expect(msg.reasoning).toBeNull();
+    expect(msg.tool_calls).toBeNull();
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("messages ordered by insertion order", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-order";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "first", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "assistant", "second", null, null],
+    );
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "third", null, null],
+    );
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.messages.map((m) => m.content)).toEqual(["first", "second", "third"]);
+
+    await rm(tmpDir, { recursive: true });
+  });
+
+  test("converts unix timestamp to ISO string for session_start", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const db = createTestDb(dbPath);
+
+    const sessionId = "test-timestamp";
+    const startedAt = 1748099519;
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "model",
+      startedAt,
+    ]);
+    db.close();
+
+    const result = await loadHermesSessionFromDb(sessionId, dbPath);
+    expect(result).not.toBeNull();
+    expect(result!.session_start).toBe(new Date(startedAt * 1000).toISOString());
+
+    await rm(tmpDir, { recursive: true });
+  });
+});
+
+describe("loadHermesSession with SQLite fallback", () => {
+  test("JSON file takes priority over DB", async () => {
+    const tmpDir = await mkdtemp(join(tmpdir(), "hermes-test-"));
+    const dbPath = join(tmpDir, "state.db");
+    const jsonPath = join(tmpDir, "session.json");
+
+    // Create DB with one model value
+    const db = createTestDb(dbPath);
+    const sessionId = "test-priority";
+    db.run("INSERT INTO sessions (id, model, started_at) VALUES (?, ?, ?)", [
+      sessionId,
+      "db-model",
+      1748099519,
+    ]);
+    db.run(
+      "INSERT INTO messages (session_id, role, content, reasoning, tool_calls) VALUES (?, ?, ?, ?, ?)",
+      [sessionId, "user", "from db", null, null],
+    );
+    db.close();
+
+    // Create JSON file with a different model value
+    const jsonData: HermesSessionJson = {
+      session_id: sessionId,
+      model: "json-model",
+      session_start: "2026-05-24T12:00:00.000Z",
+      messages: [{ role: "user", content: "from json", reasoning: null, tool_calls: null }],
+    };
+    await writeFile(jsonPath, JSON.stringify(jsonData));
+
+    // loadHermesSession reads from JSON path, so we test the existing function directly
+    // The JSON-first priority is inherent in the implementation
+    const { readFile } = await import("node:fs/promises");
+    const text = await readFile(jsonPath, "utf8");
+    const parsed = JSON.parse(text);
+    expect(parsed.model).toBe("json-model");
+
+    await rm(tmpDir, { recursive: true });
+  });
+});

packages/workflow-agent-hermes/package.json

@@ -18,8 +18,9 @@
     }
   },
   "scripts": {
-    "test": "bun test",
-    "test:ci": "bun test __tests__/*.test.ts"
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",
@@ -35,12 +36,15 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-agent-hermes"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
+  },
+  "engines": {
+    "bun": ">= 1.0.0"
   },
   "license": "MIT"
 }

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

@@ -117,7 +117,7 @@ export function createHermesAgent(): () => Promise<void> {
       await setCachedSessionId(ctx.threadId, ctx.role, sessionId);
     }
 
-    return { output: text, detailHash, sessionId };
+    return { output: text, detailHash, sessionId, assembledPrompt: fullPrompt };
   }
 
   async function runHermes(ctx: AgentContext): Promise<AgentRunResult> {
@@ -148,7 +148,7 @@ export function createHermesAgent(): () => Promise<void> {
     // so the agent sees the full conversation history (crucial for retries).
     const { text, sessionId } = await client.prompt(message);
     const { detailHash } = await storePromptResult(store, sessionId);
-    return { output: text, detailHash, sessionId };
+    return { output: text, detailHash, sessionId, assembledPrompt: "" };
   }
 
   const agentMain = createAgent({

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

@@ -1,3 +1,4 @@
+import { Database } from "bun:sqlite";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -108,15 +109,99 @@ function parseSessionJson(raw: unknown): HermesSessionJson | null {
   return { session_id, model, session_start, messages };
 }
 
+export function getHermesDbPath(): string {
+  return join(homedir(), ".hermes", "state.db");
+}
+
+type DbSessionRow = {
+  id: string;
+  model: string;
+  started_at: number;
+};
+
+type DbMessageRow = {
+  role: string;
+  content: string | null;
+  reasoning: string | null;
+  tool_calls: string | null;
+};
+
+function parseDbToolCalls(raw: string | null): HermesSessionMessage["tool_calls"] {
+  if (raw === null) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return parseToolCalls(parsed);
+  } catch {
+    return null;
+  }
+}
+
+function dbMessageToSessionMessage(row: DbMessageRow): HermesSessionMessage {
+  return {
+    role: row.role,
+    content: row.content ?? null,
+    reasoning: row.reasoning ?? null,
+    tool_calls: parseDbToolCalls(row.tool_calls),
+  };
+}
+
+export function loadHermesSessionFromDb(
+  sessionId: string,
+  dbPath: string | null = null,
+): HermesSessionJson | null {
+  const resolvedPath = dbPath ?? getHermesDbPath();
+  let db: InstanceType<typeof Database> | null = null;
+  try {
+    db = new Database(resolvedPath, { readonly: true });
+    const session = db
+      .query("SELECT id, model, started_at FROM sessions WHERE id = ?")
+      .get(sessionId) as DbSessionRow | null;
+    if (session === null) {
+      return null;
+    }
+    const rows = db
+      .query(
+        "SELECT role, content, reasoning, tool_calls FROM messages WHERE session_id = ? ORDER BY id",
+      )
+      .all(sessionId) as DbMessageRow[];
+
+    const messages: HermesSessionMessage[] = [];
+    for (const row of rows) {
+      const role = row.role;
+      if (role !== "user" && role !== "assistant" && role !== "tool") {
+        continue;
+      }
+      messages.push(dbMessageToSessionMessage(row));
+    }
+
+    return {
+      session_id: session.id,
+      model: session.model,
+      session_start: new Date(session.started_at * 1000).toISOString(),
+      messages,
+    };
+  } catch {
+    return null;
+  } finally {
+    db?.close();
+  }
+}
+
 export async function loadHermesSession(sessionId: string): Promise<HermesSessionJson | null> {
   const path = getHermesSessionPath(sessionId);
   try {
     const text = await readFile(path, "utf8");
     const raw = JSON.parse(text) as unknown;
-    return parseSessionJson(raw);
+    const result = parseSessionJson(raw);
+    if (result !== null) {
+      return result;
+    }
   } catch {
-    return null;
+    // JSON file not available, fall through to DB
   }
+  return loadHermesSessionFromDb(sessionId);
 }
 
 export function computeDurationMs(sessionStart: string, nowMs: number = Date.now()): number {

packages/workflow-agent-hermes/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

packages/workflow-dashboard/package.json

@@ -5,7 +5,9 @@
   "type": "module",
   "scripts": {
     "dev": "bun server.ts",
-    "build": "vite build"
+    "build": "vite build",
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "dependencies": {
     "@base-ui/react": "^1.5.0",

packages/workflow-dashboard/src/editor/model/edit-node-view.ts

@@ -14,7 +14,7 @@ export const editNodeViewModel = define.view("editNodeView", editNodeView, (set,
   function start(nodeId: string) {
     const [nodes] = model.use(nodesModel);
     const node = nodes.find((n) => n.id === nodeId);
-    if (!node || node.type !== "role") return;
+    if (node?.type !== "role") return;
     set({ node: node as WorkNode<"role"> });
   }
 

packages/workflow-dashboard/src/editor/trans/trans-out.ts

@@ -40,7 +40,7 @@ function traverse(
   visited.add(nodeId);
 
   const node = nodeMap.get(nodeId);
-  if (!node || node.type !== "role") return;
+  if (node?.type !== "role") return;
 
   const roleNode = node as WorkNode<"role">;
   const outEdges = outgoingEdges.get(nodeId) ?? [];

packages/workflow-protocol/package.json

@@ -14,6 +14,11 @@
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
+  },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",
     "@uncaged/json-cas-fs": "^0.5.3"
@@ -26,12 +31,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-protocol"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

packages/workflow-protocol/src/__tests__/types.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, test } from "vitest";
+import type { StartNodePayload, StepRecord, Target } from "../types.js";
+
+describe("Protocol types for thread/edge location", () => {
+  describe("StartNodePayload", () => {
+    test("has required cwd field", () => {
+      const payload: StartNodePayload = {
+        workflow: "0123456789ABC",
+        prompt: "Test prompt",
+        cwd: "/home/user/project",
+      };
+
+      expect(payload.cwd).toBe("/home/user/project");
+      expect(typeof payload.cwd).toBe("string");
+    });
+  });
+
+  describe("StepRecord", () => {
+    test("has required cwd field", () => {
+      const record: StepRecord = {
+        role: "planner",
+        output: "0123456789ABC",
+        detail: "DEF0123456789",
+        agent: "uwf-hermes",
+        edgePrompt: "Plan the implementation",
+        startedAtMs: Date.now(),
+        completedAtMs: Date.now() + 1000,
+        assembledPrompt: null,
+        cwd: "/home/user/project",
+      };
+
+      expect(record.cwd).toBe("/home/user/project");
+      expect(typeof record.cwd).toBe("string");
+    });
+  });
+
+  describe("Target", () => {
+    test("has location field that accepts string", () => {
+      const target: Target = {
+        role: "coder",
+        prompt: "Implement the code",
+        location: "/custom/path",
+      };
+
+      expect(target.location).toBe("/custom/path");
+      expect(typeof target.location).toBe("string");
+    });
+
+    test("has location field that accepts null", () => {
+      const target: Target = {
+        role: "coder",
+        prompt: "Implement the code",
+        location: null,
+      };
+
+      expect(target.location).toBe(null);
+    });
+
+    test("location supports mustache template syntax", () => {
+      const target: Target = {
+        role: "coder",
+        prompt: "Implement the code",
+        location: "{{{repoPath}}}",
+      };
+
+      expect(target.location).toBe("{{{repoPath}}}");
+    });
+  });
+});

packages/workflow-protocol/src/index.ts

@@ -29,6 +29,7 @@ export type {
   ThreadForkOutput,
   ThreadId,
   ThreadListItem,
+  ThreadStatus,
   ThreadStepsOutput,
   ThreadsIndex,
   WorkflowConfig,

packages/workflow-protocol/src/schemas.ts

@@ -20,6 +20,9 @@ const TARGET: JSONSchema = {
   properties: {
     role: { type: "string" },
     prompt: { type: "string" },
+    location: {
+      anyOf: [{ type: "string" }, { type: "null" }],
+    },
   },
   additionalProperties: false,
 };
@@ -49,10 +52,11 @@ export const WORKFLOW_SCHEMA: JSONSchema = {
 export const START_NODE_SCHEMA: JSONSchema = {
   title: "StartNode",
   type: "object",
-  required: ["workflow", "prompt"],
+  required: ["workflow", "prompt", "cwd"],
   properties: {
     workflow: { type: "string", format: "cas_ref" },
     prompt: { type: "string" },
+    cwd: { type: "string" },
   },
   additionalProperties: false,
 };
@@ -60,7 +64,17 @@ export const START_NODE_SCHEMA: JSONSchema = {
 export const STEP_NODE_SCHEMA: JSONSchema = {
   title: "StepNode",
   type: "object",
-  required: ["start", "prev", "role", "output", "detail", "agent", "startedAtMs", "completedAtMs"],
+  required: [
+    "start",
+    "prev",
+    "role",
+    "output",
+    "detail",
+    "agent",
+    "startedAtMs",
+    "completedAtMs",
+    "cwd",
+  ],
   properties: {
     start: { type: "string", format: "cas_ref" },
     prev: {
@@ -73,6 +87,10 @@ export const STEP_NODE_SCHEMA: JSONSchema = {
     edgePrompt: { type: "string" },
     startedAtMs: { type: "integer" },
     completedAtMs: { type: "integer" },
+    cwd: { type: "string" },
+    assembledPrompt: {
+      anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
+    },
   },
   additionalProperties: false,
 };

packages/workflow-protocol/src/types.ts

@@ -18,6 +18,10 @@ export type StepRecord = {
   startedAtMs: number;
   /** Date.now() after agent returns */
   completedAtMs: number;
+  /** Working directory where the agent executed. Missing in legacy nodes → "". */
+  cwd: string;
+  /** CAS ref to the fully assembled prompt sent to the agent. null for legacy steps. */
+  assembledPrompt: CasRef | null;
 };
 
 // ── 4.2 Workflow 定义 ───────────────────────────────────────────────
@@ -34,6 +38,8 @@ export type RoleDefinition = {
 export type Target = {
   role: string;
   prompt: string;
+  /** Optional working directory override via mustache template. */
+  location: string | null;
 };
 
 export type WorkflowPayload = {
@@ -48,6 +54,8 @@ export type WorkflowPayload = {
 export type StartNodePayload = {
   workflow: CasRef;
   prompt: string;
+  /** Working directory where the thread was created. */
+  cwd: string;
 };
 
 export type StepNodePayload = StepRecord & {
@@ -70,17 +78,29 @@ export type ModeratorContext = {
 
 // ── 4.5 CLI 输出 ────────────────────────────────────────────────────
 
+/** Thread status — unified status representation */
+export type ThreadStatus = "idle" | "running" | "completed" | "cancelled";
+
 /** uwf thread start */
 export type StartOutput = {
   workflow: CasRef;
   thread: ThreadId;
 };
 
-/** uwf thread step / uwf thread show */
+/**
+ * Output from thread show and thread exec commands.
+ *
+ * @property status - Current thread status (idle/running/completed/cancelled)
+ * @property done - @deprecated Use status field instead. True if thread is completed or cancelled.
+ * @property background - @deprecated Use status field instead. Always null in current implementation.
+ */
 export type StepOutput = {
   workflow: CasRef;
   thread: ThreadId;
   head: CasRef;
+  status: ThreadStatus;
+  /** The current or next role. Null when completed, cancelled, or next is $END. */
+  currentRole: string | null;
   done: boolean;
   background: boolean | null;
 };

packages/workflow-protocol/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

packages/workflow-util-agent/__tests__/adapter-retry.test.ts

@@ -0,0 +1,73 @@
+import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
+
+import { tryFrontmatterFastPath } from "../src/frontmatter.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    $status: { type: "string", enum: ["ready", "failed"] },
+    plan: { type: "string" },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+describe("adapter-stdout: A4 retry loop survives JSON output", () => {
+  test("A4. first extraction fails, second succeeds — final result has correct data", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    // Simulate the retry loop from createAgent (run.ts lines 163-173):
+    // First attempt: agent outputs garbage (no frontmatter)
+    const badOutput = "Here is my response without frontmatter.\nJust plain text.";
+    const firstAttempt = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    expect(firstAttempt).toBeNull();
+
+    // Second attempt (after correction message): agent outputs valid frontmatter
+    const goodOutput = `---\n$status: ready\nplan: corrected-hash\n---\nCorrected body with valid frontmatter.`;
+    const secondAttempt = await tryFrontmatterFastPath(goodOutput, schemaHash, store);
+
+    expect(secondAttempt).not.toBeNull();
+    expect(secondAttempt!.outputHash).toMatch(/^[0-9A-Z]{13}$/);
+    expect(secondAttempt!.frontmatter).toEqual({ $status: "ready", plan: "corrected-hash" });
+    expect(secondAttempt!.body).toBe("Corrected body with valid frontmatter.");
+
+    // Verify the final AdapterOutput shape would be correct
+    const adapterOutput = {
+      stepHash: "MOCK_STEP_HASH",
+      detailHash: "MOCK_DETAIL_HA",
+      role: "planner",
+      frontmatter: secondAttempt!.frontmatter,
+      body: secondAttempt!.body,
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+      assembledPrompt: null,
+    };
+
+    const json = JSON.stringify(adapterOutput);
+    const parsed = JSON.parse(json);
+    expect(parsed.frontmatter).toEqual({ $status: "ready", plan: "corrected-hash" });
+    expect(parsed.body).toBe("Corrected body with valid frontmatter.");
+    expect(parsed.completedAtMs).toBeGreaterThanOrEqual(parsed.startedAtMs);
+  });
+
+  test("A4. all retries fail — extraction returns null on every attempt", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const MAX_RETRIES = 2;
+    const badOutput = "No frontmatter here";
+
+    // Simulate MAX_FRONTMATTER_RETRIES iterations all failing
+    let extracted = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    for (let retry = 0; retry < MAX_RETRIES && extracted === null; retry++) {
+      // Each retry also gets bad output
+      extracted = await tryFrontmatterFastPath(badOutput, schemaHash, store);
+    }
+
+    expect(extracted).toBeNull();
+  });
+});

packages/workflow-util-agent/__tests__/adapter-stdout.test.ts

@@ -0,0 +1,105 @@
+import { createMemoryStore, putSchema } from "@uncaged/json-cas";
+import { describe, expect, test } from "vitest";
+
+import { tryFrontmatterFastPath } from "../src/frontmatter.js";
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const PLANNER_SCHEMA = {
+  type: "object",
+  properties: {
+    $status: { type: "string", enum: ["ready", "failed"] },
+    plan: { type: "string" },
+  },
+  required: ["$status"],
+  additionalProperties: false,
+};
+
+const FRONTMATTER_SCHEMA = {
+  type: "object",
+  properties: {
+    status: { anyOf: [{ type: "string" }, { type: "null" }] },
+    next: { anyOf: [{ type: "string" }, { type: "null" }] },
+    confidence: { anyOf: [{ type: "number" }, { type: "null" }] },
+    artifacts: { type: "array", items: { type: "string" } },
+    scope: { type: "string" },
+  },
+  required: ["status", "next", "confidence", "artifacts", "scope"],
+  additionalProperties: false,
+};
+
+describe("adapter-stdout: FrontmatterFastPathResult includes frontmatter", () => {
+  test("A2. frontmatter field contains the parsed YAML frontmatter object", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const raw = `---\n$status: ready\nplan: abc123\n---\nSome body text`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.frontmatter).toEqual({ $status: "ready", plan: "abc123" });
+  });
+
+  test("A3. body field contains the markdown body after frontmatter", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, PLANNER_SCHEMA);
+
+    const raw = `---\n$status: ready\nplan: hash123\n---\nHere is the body.\n\nWith multiple paragraphs.`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.body).toBe("Here is the body.\n\nWith multiple paragraphs.");
+  });
+
+  test("A1. result contains outputHash as valid CasRef", async () => {
+    const store = createMemoryStore();
+    const schemaHash = await putSchema(store, FRONTMATTER_SCHEMA);
+
+    const raw = `---\nstatus: done\nnext: null\nconfidence: 0.9\nartifacts: []\nscope: test\n---\nBody`;
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+
+    expect(result).not.toBeNull();
+    expect(result!.outputHash).toMatch(/^[0-9A-Z]{13}$/);
+    expect(result!.frontmatter).toBeDefined();
+    expect(result!.body).toBe("Body");
+  });
+});
+
+describe("adapter-stdout: AdapterOutput JSON shape", () => {
+  test("A5. JSON.stringify produces valid parseable JSON with all fields", () => {
+    const output = {
+      stepHash: "0123456789ABC",
+      detailHash: "DEFGH12345678",
+      role: "planner",
+      frontmatter: { $status: "ready", plan: "somehash" },
+      body: "Plan body text",
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+
+    const json = JSON.stringify(output);
+    const parsed = JSON.parse(json);
+
+    expect(parsed.stepHash).toBe("0123456789ABC");
+    expect(parsed.detailHash).toBe("DEFGH12345678");
+    expect(parsed.role).toBe("planner");
+    expect(parsed.frontmatter).toEqual({ $status: "ready", plan: "somehash" });
+    expect(parsed.body).toBe("Plan body text");
+    expect(parsed.startedAtMs).toBe(1000);
+    expect(parsed.completedAtMs).toBe(2000);
+  });
+
+  test("completedAtMs >= startedAtMs", () => {
+    const output = {
+      stepHash: "0123456789ABC",
+      detailHash: "DEFGH12345678",
+      role: "planner",
+      frontmatter: {},
+      body: "",
+      startedAtMs: 1000,
+      completedAtMs: 2000,
+    };
+
+    expect(output.completedAtMs).toBeGreaterThanOrEqual(output.startedAtMs);
+  });
+});

packages/workflow-util-agent/__tests__/frontmatter-fast-path.test.ts

@@ -5,17 +5,13 @@ import { tryFrontmatterFastPath } from "../src/frontmatter.js";
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-/** JSON Schema that exactly matches the AgentFrontmatter fields. */
-const FRONTMATTER_SCHEMA = {
+/** JSON Schema that matches the new status-only AgentFrontmatter. */
+const STATUS_ONLY_SCHEMA = {
   type: "object",
   properties: {
     status: { anyOf: [{ type: "string" }, { type: "null" }] },
-    next: { anyOf: [{ type: "string" }, { type: "null" }] },
-    confidence: { anyOf: [{ type: "number" }, { type: "null" }] },
-    artifacts: { type: "array", items: { type: "string" } },
-    scope: { type: "string" },
   },
-  required: ["status", "next", "confidence", "artifacts", "scope"],
+  required: ["status"],
   additionalProperties: false,
 };
 
@@ -56,24 +52,41 @@ async function makeStoreWithSchema(schema: Record<string, unknown>) {
   return { store, schemaHash };
 }
 
+// ── STANDARD_KEYS ────────────────────────────────────────────────────────────
+
+describe("STANDARD_KEYS contains only status", () => {
+  test("STANDARD_KEYS is ['status']", async () => {
+    // We verify indirectly: defaultCandidate (no schema fields) returns only { status }
+    const { store, schemaHash } = await makeStoreWithSchema({
+      type: "object",
+      properties: {
+        status: { anyOf: [{ type: "string" }, { type: "null" }] },
+      },
+    });
+
+    const raw = "---\nstatus: done\n---\n\nBody.";
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    expect(node).not.toBeNull();
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("done");
+    // Legacy fields must NOT be present
+    expect(payload.next).toBeUndefined();
+    expect(payload.confidence).toBeUndefined();
+    expect(payload.artifacts).toBeUndefined();
+    expect(payload.scope).toBeUndefined();
+  });
+});
+
 // ── Happy path ─────────────────────────────────────────────────────────────────
 
 describe("tryFrontmatterFastPath — happy path", () => {
   test("parses valid frontmatter and returns outputHash + stripped body", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
-    const raw = [
-      "---",
-      "status: done",
-      "next: reviewer",
-      "confidence: 0.9",
-      "artifacts: [src/foo.ts]",
-      "scope: role",
-      "---",
-      "",
-      "## Summary",
-      "Work is complete.",
-    ].join("\n");
+    const raw = ["---", "status: done", "---", "", "## Summary", "Work is complete."].join("\n");
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
 
@@ -85,11 +98,10 @@ describe("tryFrontmatterFastPath — happy path", () => {
     expect((result?.outputHash ?? "").length).toBeGreaterThan(0);
   });
 
-  test("stored CAS node payload matches frontmatter fields", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+  test("stored CAS node payload has only status", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
-    const raw =
-      "---\nstatus: done\nnext: null\nconfidence: null\nartifacts: []\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).not.toBeNull();
@@ -98,10 +110,29 @@ describe("tryFrontmatterFastPath — happy path", () => {
     expect(node).not.toBeNull();
     const payload = node!.payload as Record<string, unknown>;
     expect(payload.status).toBe("done");
-    expect(payload.next).toBeNull();
-    expect(payload.confidence).toBeNull();
-    expect(payload.artifacts).toEqual([]);
-    expect(payload.scope).toBe("role");
+    expect(Object.keys(payload)).toEqual(["status"]);
+  });
+});
+
+// ── Legacy fields in input are ignored ──────────────────────────────────────
+
+describe("tryFrontmatterFastPath — legacy fields ignored", () => {
+  test("legacy fields in input do not appear in CAS output", async () => {
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
+
+    const raw =
+      "---\nstatus: done\nnext: reviewer\nconfidence: 0.9\nartifacts: [a.ts]\nscope: thread\n---\n\nBody.";
+
+    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
+    expect(result).not.toBeNull();
+
+    const node = store.get(result!.outputHash);
+    const payload = node!.payload as Record<string, unknown>;
+    expect(payload.status).toBe("done");
+    expect(payload.next).toBeUndefined();
+    expect(payload.confidence).toBeUndefined();
+    expect(payload.artifacts).toBeUndefined();
+    expect(payload.scope).toBeUndefined();
   });
 });
 
@@ -109,7 +140,7 @@ describe("tryFrontmatterFastPath — happy path", () => {
 
 describe("tryFrontmatterFastPath — fallback: no frontmatter", () => {
   test("returns null for plain markdown without frontmatter block", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
+    const { store, schemaHash } = await makeStoreWithSchema(STATUS_ONLY_SCHEMA);
 
     const result = await tryFrontmatterFastPath(
       "This is plain markdown without any frontmatter.",
@@ -121,35 +152,13 @@ describe("tryFrontmatterFastPath — fallback: no frontmatter", () => {
   });
 });
 
-// ── Fallback: invalid frontmatter ─────────────────────────────────────────────
-
-describe("tryFrontmatterFastPath — fallback: invalid frontmatter", () => {
-  test("returns null when confidence is out of range [0, 1]", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
-
-    const raw = "---\nstatus: done\nconfidence: 1.5\nscope: role\n---\n\nBody.";
-
-    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
-    expect(result).toBeNull();
-  });
-
-  test("returns null when next contains whitespace", async () => {
-    const { store, schemaHash } = await makeStoreWithSchema(FRONTMATTER_SCHEMA);
-
-    const raw = "---\nstatus: done\nnext: some role\nscope: role\n---\n\nBody.";
-
-    const result = await tryFrontmatterFastPath(raw, schemaHash, store);
-    expect(result).toBeNull();
-  });
-});
-
 // ── Fallback: schema mismatch ─────────────────────────────────────────────────
 
 describe("tryFrontmatterFastPath — fallback: schema mismatch", () => {
   test("returns null when outputSchema requires fields not in frontmatter", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(STRICT_SCHEMA);
 
-    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).toBeNull();
@@ -194,7 +203,7 @@ describe("tryFrontmatterFastPath — role-specific fields", () => {
   test("returns null when required role-specific field is missing", async () => {
     const { store, schemaHash } = await makeStoreWithSchema(REVIEWER_SCHEMA);
 
-    const raw = "---\nstatus: done\nscope: role\n---\n\nBody.";
+    const raw = "---\nstatus: done\n---\n\nBody.";
 
     const result = await tryFrontmatterFastPath(raw, schemaHash, store);
     expect(result).toBeNull();

packages/workflow-util-agent/package.json

@@ -15,8 +15,9 @@
     }
   },
   "scripts": {
-    "test": "bun test",
-    "test:ci": "bun test"
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
   },
   "dependencies": {
     "@uncaged/json-cas": "^0.5.3",
@@ -34,12 +35,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-util-agent"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

packages/workflow-util-agent/src/__tests__/parseArgv.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+
+describe("parseArgv empty prompt error message", () => {
+  let stderrOutput: string;
+  let _exitCode: number | null;
+  const originalExit = process.exit;
+  const originalStderrWrite = process.stderr.write;
+
+  beforeEach(() => {
+    stderrOutput = "";
+    _exitCode = null;
+    process.exit = ((code?: number) => {
+      _exitCode = code ?? 1;
+      throw new Error("process.exit called");
+    }) as any;
+    process.stderr.write = ((chunk: string) => {
+      stderrOutput += chunk;
+      return true;
+    }) as any;
+  });
+
+  afterEach(() => {
+    process.exit = originalExit;
+    process.stderr.write = originalStderrWrite;
+  });
+
+  test("empty prompt produces error message mentioning template variables", async () => {
+    const { parseArgv } = await import("../run.js");
+    const argv = [
+      "node",
+      "uwf-hermes",
+      "--thread",
+      "01ABCDEFGHIJKLMNOPQRSTUVWX",
+      "--role",
+      "classifier",
+      "--prompt",
+      "",
+    ];
+
+    expect(() => parseArgv(argv)).toThrow("process.exit called");
+    expect(stderrOutput).toContain("prompt");
+    expect(stderrOutput).toContain("empty");
+    expect(stderrOutput).toContain("template");
+  });
+});

packages/workflow-util-agent/src/build-output-format-instruction.ts

@@ -214,7 +214,7 @@ function getConstValue(propSchema: JSONSchema): string {
 function buildVariantBlock(variant: JSONSchema, discriminant: string): string {
   const props = extractSchemaProperties(variant);
   const value = getConstValue(
-    ((variant.properties as Record<string, JSONSchema>) ?? {})[discriminant] ?? {},
+    (variant.properties as Record<string, JSONSchema>)?.[discriminant] ?? {},
   );
   const yamlExample = buildYamlExampleBlock(props);
   const fieldList = buildFieldList(props);

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

@@ -130,6 +130,8 @@ async function buildHistory(
       edgePrompt: step.edgePrompt ?? "",
       startedAtMs: step.startedAtMs,
       completedAtMs: step.completedAtMs,
+      cwd: step.cwd ?? "",
+      assembledPrompt: step.assembledPrompt ?? null,
       content,
     });
   }

packages/workflow-util-agent/src/frontmatter.ts

@@ -13,13 +13,14 @@ import { extractSchemaFields } from "./build-output-format-instruction.js";
 
 const log = createLogger({ sink: { kind: "stderr" } });
 
-const STANDARD_KEYS = ["status", "next", "confidence", "artifacts", "scope"] as const;
+const STANDARD_KEYS = ["status"] as const;
 
 type StandardKey = (typeof STANDARD_KEYS)[number];
 
 export type FrontmatterFastPathResult = {
   body: string;
   outputHash: CasRef;
+  frontmatter: Record<string, unknown>;
 };
 
 function extractYamlBlock(raw: string): string | null {
@@ -62,10 +63,6 @@ function parseRawFrontmatterFields(raw: string): Record<string, unknown> {
 function defaultCandidate(frontmatter: AgentFrontmatter): Record<string, unknown> {
   return {
     status: frontmatter.status,
-    next: frontmatter.next,
-    confidence: frontmatter.confidence,
-    artifacts: [...frontmatter.artifacts],
-    scope: frontmatter.scope,
   };
 }
 
@@ -73,14 +70,6 @@ function pickStandardField(frontmatter: AgentFrontmatter, key: StandardKey): unk
   switch (key) {
     case "status":
       return frontmatter.status;
-    case "next":
-      return frontmatter.next;
-    case "confidence":
-      return frontmatter.confidence;
-    case "artifacts":
-      return [...frontmatter.artifacts];
-    case "scope":
-      return frontmatter.scope;
   }
 }
 
@@ -98,9 +87,6 @@ function pickFieldValue(
   }
 
   const coerced = pickStandardField(frontmatter, field);
-  if (field === "artifacts" || field === "scope") {
-    return coerced;
-  }
   if (coerced !== null) {
     return coerced;
   }
@@ -110,8 +96,8 @@ function pickFieldValue(
 /**
  * Build a CAS candidate object from schema property keys and parsed frontmatter.
  *
- * When the schema has no inspectable properties, falls back to the five standard
- * agent frontmatter fields for backward compatibility.
+ * When the schema has no inspectable properties, falls back to the standard
+ * agent frontmatter field (status only).
  */
 function buildCandidate(
   frontmatter: AgentFrontmatter,
@@ -191,5 +177,5 @@ export async function tryFrontmatterFastPath(
     return null;
   }
 
-  return { body, outputHash };
+  return { body, outputHash, frontmatter: candidate };
 }

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

@@ -11,10 +11,11 @@ export {
 } from "./extract.js";
 export type { FrontmatterFastPathResult } from "./frontmatter.js";
 export { tryFrontmatterFastPath } from "./frontmatter.js";
-export { createAgent } from "./run.js";
+export { createAgent, parseArgv } from "./run.js";
 export { getCachedSessionId, getCachePath, setCachedSessionId } from "./session-cache.js";
 export { getConfigPath, getEnvPath, loadWorkflowConfig, resolveStorageRoot } from "./storage.js";
 export type {
+  AdapterOutput,
   AgentContext,
   AgentContinueFn,
   AgentOptions,

packages/workflow-util-agent/src/run.ts

@@ -6,7 +6,7 @@ import { buildContextWithMeta } from "./context.js";
 import { tryFrontmatterFastPath } from "./frontmatter.js";
 import type { AgentStore } from "./storage.js";
 import { getEnvPath, resolveStorageRoot } from "./storage.js";
-import type { AgentOptions } from "./types.js";
+import type { AdapterOutput, AgentOptions } from "./types.js";
 
 const MAX_FRONTMATTER_RETRIES = 2;
 
@@ -32,13 +32,16 @@ function getNamedArg(argv: string[], name: string): string {
   return argv[idx + 1];
 }
 
-function parseArgv(argv: string[]): { threadId: ThreadId; role: string; prompt: string } {
+export function parseArgv(argv: string[]): { threadId: ThreadId; role: string; prompt: string } {
   const threadId = getNamedArg(argv, "--thread");
   const role = getNamedArg(argv, "--role");
   const prompt = getNamedArg(argv, "--prompt");
   if (threadId === "") fail(USAGE);
   if (role === "") fail(USAGE);
-  if (prompt === "") fail(USAGE);
+  if (prompt === "")
+    fail(
+      `--prompt is empty. If this agent was spawned by uwf, the edge prompt template may have unresolved variables. ${USAGE}`,
+    );
   return { threadId: threadId as ThreadId, role, prompt };
 }
 
@@ -61,6 +64,7 @@ async function writeStepNode(options: {
   edgePrompt: string;
   startedAtMs: number;
   completedAtMs: number;
+  assembledPromptHash: CasRef | null;
 }): Promise<CasRef> {
   const payload: StepNodePayload = {
     start: options.startHash,
@@ -72,6 +76,8 @@ async function writeStepNode(options: {
     edgePrompt: options.edgePrompt,
     startedAtMs: options.startedAtMs,
     completedAtMs: options.completedAtMs,
+    cwd: process.cwd(),
+    assembledPrompt: options.assembledPromptHash,
   };
   const hash = await options.store.put(options.schemas.stepNode, payload);
   const node = options.store.get(hash);
@@ -81,14 +87,24 @@ async function writeStepNode(options: {
   return hash;
 }
 
+type ExtractedOutput = {
+  outputHash: CasRef;
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
 async function tryExtractOutput(
   rawOutput: string,
   outputSchema: CasRef,
   ctx: Awaited<ReturnType<typeof buildContextWithMeta>>,
-): Promise<CasRef | null> {
+): Promise<ExtractedOutput | null> {
   const fastPath = await tryFrontmatterFastPath(rawOutput, outputSchema, ctx.meta.store);
   if (fastPath !== null) {
-    return fastPath.outputHash;
+    return {
+      outputHash: fastPath.outputHash,
+      frontmatter: fastPath.frontmatter,
+      body: fastPath.body,
+    };
   }
   return null;
 }
@@ -100,6 +116,7 @@ async function persistStep(options: {
   agentName: string;
   startedAtMs: number;
   completedAtMs: number;
+  assembledPromptHash: CasRef | null;
 }): Promise<CasRef> {
   const { store, schemas, chain, headHash } = options.ctx.meta;
   return writeStepNode({
@@ -114,6 +131,7 @@ async function persistStep(options: {
     edgePrompt: options.ctx.edgePrompt,
     startedAtMs: options.startedAtMs,
     completedAtMs: options.completedAtMs,
+    assembledPromptHash: options.assembledPromptHash,
   });
 }
 
@@ -137,6 +155,7 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
 
     const startedAtMs = Date.now();
     let agentResult = await runWithMessage("agent run failed", () => options.run(ctx));
+    agentResult.output = agentResult.output.trimStart();
 
     // Preserve the primary detail from the first run — it contains the full
     // tool-call turn history.  Continuation retries only fix frontmatter
@@ -144,9 +163,9 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
     const primaryDetailHash = agentResult.detailHash;
 
     // Try to extract frontmatter; retry via continue if it fails
-    let outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+    let extracted = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
 
-    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && outputHash === null; retry++) {
+    for (let retry = 0; retry < MAX_FRONTMATTER_RETRIES && extracted === null; retry++) {
       const correctionMessage =
         "Your previous response did not contain valid YAML frontmatter matching the role schema.\n" +
         "You MUST begin your response with a YAML frontmatter block (--- delimited).\n" +
@@ -155,10 +174,11 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       agentResult = await runWithMessage("agent continue failed", () =>
         options.continue(agentResult.sessionId, correctionMessage, ctx.meta.store),
       );
-      outputHash = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
+      agentResult.output = agentResult.output.trimStart();
+      extracted = await tryExtractOutput(agentResult.output, roleDef.frontmatter, ctx);
     }
 
-    if (outputHash === null) {
+    if (extracted === null) {
       fail(
         "Agent output does not contain valid YAML frontmatter matching the role schema " +
           `after ${MAX_FRONTMATTER_RETRIES} retries.\n` +
@@ -166,15 +186,33 @@ export function createAgent(options: AgentOptions): () => Promise<void> {
       );
     }
     const completedAtMs = Date.now();
+
+    // Store the assembled prompt in CAS for later inspection via `step read --prompt`
+    const promptText = agentResult.assembledPrompt;
+    const assembledPromptHash =
+      promptText !== ""
+        ? await ctx.meta.store.put(ctx.meta.schemas.text, promptText).catch(() => null)
+        : null;
+
     const stepHash = await persistStep({
       ctx,
-      outputHash,
+      outputHash: extracted.outputHash,
       detailHash: primaryDetailHash,
       agentName: agentLabel(options.name),
       startedAtMs,
       completedAtMs,
+      assembledPromptHash,
     });
 
-    process.stdout.write(`${stepHash}\n`);
+    const adapterOutput: AdapterOutput = {
+      stepHash,
+      detailHash: primaryDetailHash,
+      role,
+      frontmatter: extracted.frontmatter,
+      body: extracted.body,
+      startedAtMs,
+      completedAtMs,
+    };
+    process.stdout.write(`${JSON.stringify(adapterOutput)}\n`);
   };
 }

packages/workflow-util-agent/src/schemas.ts

@@ -6,17 +6,21 @@ export type UwfAgentSchemaHashes = {
   workflow: Hash;
   startNode: Hash;
   stepNode: Hash;
+  text: Hash;
 };
 
+const TEXT_SCHEMA = { type: "string" as const };
+
 /**
  * Register Workflow, StartNode, and StepNode JSON Schemas in the CAS store.
  * Idempotent: safe to call on every agent invocation.
  */
 export async function registerAgentSchemas(store: Store): Promise<UwfAgentSchemaHashes> {
-  const [workflow, startNode, stepNode] = await Promise.all([
+  const [workflow, startNode, stepNode, text] = await Promise.all([
     putSchema(store, WORKFLOW_SCHEMA),
     putSchema(store, START_NODE_SCHEMA),
     putSchema(store, STEP_NODE_SCHEMA),
+    putSchema(store, TEXT_SCHEMA),
   ]);
-  return { workflow, startNode, stepNode };
+  return { workflow, startNode, stepNode, text };
 }

packages/workflow-util-agent/src/types.ts

@@ -27,6 +27,8 @@ export type AgentRunResult = {
   output: string;
   detailHash: string;
   sessionId: string;
+  /** The fully assembled prompt that was sent to the agent. */
+  assembledPrompt: string;
 };
 
 export type AgentContinueFn = (
@@ -37,6 +39,16 @@ export type AgentContinueFn = (
 
 export type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
 
+export type AdapterOutput = {
+  stepHash: string;
+  detailHash: string;
+  role: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  startedAtMs: number;
+  completedAtMs: number;
+};
+
 export type AgentOptions = {
   name: string;
   run: AgentRunFn;

packages/workflow-util-agent/tsconfig.json

@@ -5,5 +5,5 @@
     "outDir": "dist"
   },
   "include": ["src"],
-  "references": [{ "path": "../workflow-protocol" }]
+  "references": [{ "path": "../workflow-protocol" }, { "path": "../workflow-util" }]
 }

packages/workflow-util-agent/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

packages/workflow-util/CHANGELOG.md

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

packages/workflow-util/__tests__/frontmatter-markdown.test.ts

@@ -41,31 +41,13 @@ describe("parseFrontmatterMarkdown", () => {
     });
   });
 
-  describe("full frontmatter document", () => {
-    it("parses all fields from a well-formed document", () => {
-      const raw = `---
-status: done
-next: reviewer
-confidence: 0.9
-artifacts:
-  - src/foo.ts
-  - src/bar.ts
-scope: thread
----
-
-## Summary
-
-Everything looks good.`;
-
+  describe("status-only frontmatter", () => {
+    it("parses status-only frontmatter", () => {
+      const raw = "---\nstatus: done\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter).not.toBeNull();
-      const fm = result.frontmatter!;
-      expect(fm.status).toBe("done");
-      expect(fm.next).toBe("reviewer");
-      expect(fm.confidence).toBe(0.9);
-      expect(fm.artifacts).toEqual(["src/foo.ts", "src/bar.ts"]);
-      expect(fm.scope).toBe("thread");
-      expect(result.body).toBe("## Summary\n\nEverything looks good.");
+      expect(result.frontmatter).toEqual({ status: "done" });
+      expect(result.body).toBe("body");
     });
 
     it("strips leading newline from body", () => {
@@ -87,6 +69,22 @@ Everything looks good.`;
     });
   });
 
+  describe("ignores legacy fields", () => {
+    it("legacy fields next/confidence/artifacts/scope are NOT present on result", () => {
+      const raw =
+        "---\nstatus: done\nnext: reviewer\nconfidence: 0.9\nartifacts:\n  - src/foo.ts\nscope: thread\n---\n\nBody.";
+      const result = parseFrontmatterMarkdown(raw);
+      expect(result.frontmatter).not.toBeNull();
+      const fm = result.frontmatter!;
+      expect(fm.status).toBe("done");
+      // Legacy fields must not exist on the object at all
+      expect("next" in fm).toBe(false);
+      expect("confidence" in fm).toBe(false);
+      expect("artifacts" in fm).toBe(false);
+      expect("scope" in fm).toBe(false);
+    });
+  });
+
   describe("status field", () => {
     it.each([
       "done",
@@ -106,109 +104,18 @@ Everything looks good.`;
     });
 
     it("returns null status when omitted", () => {
-      const raw = "---\nconfidence: 0.5\n---\nbody";
+      const raw = "---\nfoo: bar\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter?.status).toBeNull();
     });
   });
 
-  describe("confidence field", () => {
-    it("parses integer as number", () => {
-      const raw = "---\nconfidence: 1\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBe(1);
-    });
-
-    it("parses decimal", () => {
-      const raw = "---\nconfidence: 0.75\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBe(0.75);
-    });
-
-    it("returns null when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBeNull();
-    });
-
-    it("returns null for non-numeric value", () => {
-      const raw = "---\nconfidence: high\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.confidence).toBeNull();
-    });
-  });
-
-  describe("artifacts field", () => {
-    it("parses block sequence", () => {
-      const raw = "---\nartifacts:\n  - a.ts\n  - b.ts\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
-    });
-
-    it("parses inline sequence", () => {
-      const raw = "---\nartifacts: [a.ts, b.ts]\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["a.ts", "b.ts"]);
-    });
-
-    it("returns empty array when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual([]);
-    });
-
-    it("wraps single scalar in array", () => {
-      const raw = "---\nartifacts: only-one.ts\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.artifacts).toEqual(["only-one.ts"]);
-    });
-  });
-
-  describe("scope field", () => {
-    it('parses scope "role"', () => {
-      const raw = "---\nscope: role\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-
-    it('parses scope "thread"', () => {
-      const raw = "---\nscope: thread\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("thread");
-    });
-
-    it('defaults to "role" when omitted', () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-
-    it('defaults to "role" for unknown scope value', () => {
-      const raw = "---\nscope: global\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.scope).toBe("role");
-    });
-  });
-
-  describe("next field", () => {
-    it("parses a role name", () => {
-      const raw = "---\nnext: planner\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.next).toBe("planner");
-    });
-
-    it("returns null when omitted", () => {
-      const raw = "---\nstatus: done\n---\nbody";
-      const result = parseFrontmatterMarkdown(raw);
-      expect(result.frontmatter?.next).toBeNull();
-    });
-  });
-
   describe("unknown fields", () => {
     it("ignores unknown keys silently", () => {
       const raw = "---\nunknown_field: some_value\nstatus: done\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter?.status).toBe("done");
+      expect(Object.keys(result.frontmatter!)).toEqual(["status"]);
     });
   });
 
@@ -221,123 +128,58 @@ Everything looks good.`;
   });
 
   describe("empty frontmatter block", () => {
-    it("parses empty frontmatter and uses all defaults", () => {
+    it("parses empty frontmatter with status null", () => {
       const raw = "---\n---\nbody";
       const result = parseFrontmatterMarkdown(raw);
       expect(result.frontmatter).not.toBeNull();
       const fm = result.frontmatter!;
       expect(fm.status).toBeNull();
-      expect(fm.next).toBeNull();
-      expect(fm.confidence).toBeNull();
-      expect(fm.artifacts).toEqual([]);
-      expect(fm.scope).toBe("role");
+      expect(Object.keys(fm)).toEqual(["status"]);
       expect(result.body).toBe("body");
     });
   });
+
+  describe("AgentFrontmatter has exactly one field", () => {
+    it("has only status key", () => {
+      const fm: AgentFrontmatter = { status: null };
+      expect(Object.keys(fm)).toEqual(["status"]);
+    });
+  });
+
+  describe("FrontmatterValidationError only has status variant", () => {
+    it("status variant is valid", () => {
+      const err: import("../src/index.js").FrontmatterValidationError = {
+        field: "status",
+        message: "test",
+      };
+      expect(err.field).toBe("status");
+    });
+  });
 });
 
 // ── validateFrontmatter ──────────────────────────────────────────────────────
 
-function validFm(overrides: Partial<AgentFrontmatter> = {}): AgentFrontmatter {
-  return {
-    status: "done",
-    next: null,
-    confidence: null,
-    artifacts: [],
-    scope: "role",
-    ...overrides,
-  };
-}
-
 describe("validateFrontmatter", () => {
-  it("returns no errors for a fully valid frontmatter", () => {
-    const errors = validateFrontmatter(validFm());
+  it("returns no errors for a valid status", () => {
+    const errors = validateFrontmatter({ status: "done" });
     expect(errors).toHaveLength(0);
   });
 
-  it("returns no errors when all nullable fields are null", () => {
-    const fm: AgentFrontmatter = {
-      status: null,
-      next: null,
-      confidence: null,
-      artifacts: [],
-      scope: "role",
-    };
+  it("returns no errors when status is null", () => {
+    const errors = validateFrontmatter({ status: null });
+    expect(errors).toHaveLength(0);
+  });
+
+  it("returns error for invalid status", () => {
+    const errors = validateFrontmatter({ status: "bogus" as never });
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.field).toBe("status");
+  });
+
+  it("no validation for next/confidence/artifacts/scope — fields do not exist", () => {
+    // AgentFrontmatter only has status — verify at runtime
+    const fm: AgentFrontmatter = { status: "done" };
+    expect(Object.keys(fm)).toEqual(["status"]);
     expect(validateFrontmatter(fm)).toHaveLength(0);
   });
-
-  describe("confidence validation", () => {
-    it("accepts 0.0", () => {
-      expect(validateFrontmatter(validFm({ confidence: 0 }))).toHaveLength(0);
-    });
-
-    it("accepts 1.0", () => {
-      expect(validateFrontmatter(validFm({ confidence: 1 }))).toHaveLength(0);
-    });
-
-    it("rejects value below 0", () => {
-      const errors = validateFrontmatter(validFm({ confidence: -0.1 }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("confidence");
-    });
-
-    it("rejects value above 1", () => {
-      const errors = validateFrontmatter(validFm({ confidence: 1.01 }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("confidence");
-    });
-  });
-
-  describe("next validation", () => {
-    it("accepts a simple role name", () => {
-      expect(validateFrontmatter(validFm({ next: "reviewer" }))).toHaveLength(0);
-    });
-
-    it("accepts kebab-case role name", () => {
-      expect(validateFrontmatter(validFm({ next: "code-reviewer" }))).toHaveLength(0);
-    });
-
-    it("rejects role name with whitespace", () => {
-      const errors = validateFrontmatter(validFm({ next: "role name" }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("next");
-    });
-  });
-
-  describe("artifacts validation", () => {
-    it("accepts non-empty path strings", () => {
-      expect(
-        validateFrontmatter(validFm({ artifacts: ["src/foo.ts", "src/bar.ts"] })),
-      ).toHaveLength(0);
-    });
-
-    it("rejects empty string artifact entries", () => {
-      const errors = validateFrontmatter(validFm({ artifacts: [""] }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("artifacts");
-    });
-
-    it("rejects whitespace-only artifact entries", () => {
-      const errors = validateFrontmatter(validFm({ artifacts: ["   "] }));
-      expect(errors).toHaveLength(1);
-      expect(errors[0]?.field).toBe("artifacts");
-    });
-  });
-
-  describe("multiple errors", () => {
-    it("reports multiple violations at once", () => {
-      const fm: AgentFrontmatter = {
-        status: "done",
-        next: "bad role",
-        confidence: 2,
-        artifacts: [""],
-        scope: "role",
-      };
-      const errors = validateFrontmatter(fm);
-      const fields = errors.map((e) => e.field);
-      expect(fields).toContain("next");
-      expect(fields).toContain("confidence");
-      expect(fields).toContain("artifacts");
-    });
-  });
 });

packages/workflow-util/package.json

@@ -14,6 +14,11 @@
       "import": "./dist/index.js"
     }
   },
+  "scripts": {
+    "prepublishOnly": "echo 'Use bun run release from repo root' && exit 1",
+    "test": "vitest run",
+    "test:ci": "vitest run"
+  },
   "dependencies": {},
   "devDependencies": {
     "typescript": "^5.8.3"
@@ -23,12 +28,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/shazhou-ww/uncaged-workflow.git",
+    "url": "https://git.shazhou.work/uncaged/workflow.git",
     "directory": "packages/workflow-util"
   },
-  "homepage": "https://github.com/shazhou-ww/uncaged-workflow#readme",
+  "homepage": "https://git.shazhou.work/uncaged/workflow#readme",
   "bugs": {
-    "url": "https://github.com/shazhou-ww/uncaged-workflow/issues"
+    "url": "https://git.shazhou.work/uncaged/workflow/issues"
   },
   "license": "MIT"
 }

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "bun:test";
+import { describe, expect, it } from "vitest";
 import { extractUlidTimestamp, generateUlid } from "../ulid.js";
 
 describe("extractUlidTimestamp", () => {

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

@@ -0,0 +1,68 @@
+export function generateActorReference(): string {
+  return `# Actor Reference
+
+You are executing a workflow role. Your system prompt defines your goal, procedure, and output requirements. This reference covers two things you need to know about the workflow engine.
+
+## 1. Frontmatter Output Protocol
+
+Your response **MUST** begin with a YAML frontmatter block at byte position 0 — no preamble text before it.
+
+\`\`\`
+---
+status: done
+myField: some value
+---
+
+... markdown body (your work, explanation, notes) ...
+\`\`\`
+
+### Standard Field
+
+| Field | Values | Default | Description |
+|-------|--------|---------|-------------|
+| \`status\` | \`done\`, \`needs_input\`, \`in_progress\`, \`failed\` | \`done\` | Completion signal — determines which graph edge the moderator follows next |
+
+### Schema-Defined Fields
+
+Your role's output schema (shown in the system prompt under "Deliverable Format") defines additional fields. Output **only** the fields listed there — do not invent extra fields.
+
+### Body
+
+Everything after the closing \`---\` fence is the markdown body. Use it for explanations, logs, or human-readable notes. The body is stored but not parsed by the engine.
+
+### Retry
+
+If the engine cannot parse your frontmatter, it will ask you to retry (up to 2 times). Just output the corrected frontmatter block — don't panic.
+
+## 2. CAS (Content-Addressable Store)
+
+Your frontmatter output is automatically stored in CAS. You can also **use CAS directly** to store intermediate artifacts, build merkle DAGs for large outputs, or reference data from previous steps.
+
+### Commands
+
+\`\`\`
+uwf cas put-text <text>           # store plain text, print hash
+uwf cas put <type-hash> <json>    # store typed JSON data, print hash
+uwf cas get <hash>                # read a CAS node (type + payload)
+uwf cas has <hash>                # check if a hash exists
+uwf cas refs <hash>               # list direct references from a node
+uwf cas walk <hash>               # recursive traversal from a node
+uwf cas schema list               # list registered schemas
+uwf cas schema get <hash>         # show a schema definition
+\`\`\`
+
+### Merkle DAG Pattern
+
+For large outputs, store parts individually and reference their hashes:
+
+\`\`\`bash
+# Store individual sections
+HASH1=$(uwf cas put-text "section 1 content")
+HASH2=$(uwf cas put-text "section 2 content")
+
+# Reference hashes in your frontmatter or in a parent node
+\`\`\`
+
+This enables progressive loading — consumers can fetch the root and resolve children on demand.
+`;
+}

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

@@ -0,0 +1,163 @@
+export function generateAdapterReference(): string {
+  return `# Adapter Reference
+
+Guide for building a new agent adapter (CLI binary) for the workflow engine.
+
+## What Is an Adapter
+
+An adapter is a CLI command (e.g. \`uwf-hermes\`, \`uwf-builtin\`) that the engine spawns to execute a role. It bridges the workflow engine and an LLM/agent backend. The engine calls it with:
+
+\`\`\`
+uwf-<name> --thread <id> --role <role> --prompt <text>
+\`\`\`
+
+The adapter must produce frontmatter markdown output. The engine handles argument parsing, context building, output extraction, and CAS persistence — you just implement the LLM interaction.
+
+## Quick Start
+
+\`\`\`typescript
+import { createAgent } from "@uncaged/workflow-util-agent";
+import type { AgentContext, AgentRunResult, AgentContinueFn, AgentRunFn } from "@uncaged/workflow-util-agent";
+
+const run: AgentRunFn = async (ctx: AgentContext): Promise<AgentRunResult> => {
+  // 1. Build your prompt from ctx
+  // 2. Call your LLM backend
+  // 3. Return the result
+  return { output: rawMarkdown, detailHash, sessionId };
+};
+
+const continue_: AgentContinueFn = async (sessionId, message, store) => {
+  // Resume an existing session with a correction message
+  return { output: correctedMarkdown, detailHash, sessionId };
+};
+
+const main = createAgent({ name: "my-agent", run, continue: continue_ });
+main();
+\`\`\`
+
+## The \`createAgent\` Factory
+
+\`createAgent(options)\` returns an async \`main()\` function that handles the full lifecycle:
+
+1. Parses CLI args (\`--thread\`, \`--role\`, \`--prompt\`)
+2. Loads \`.env\` from storage root
+3. Builds \`AgentContext\` (thread history, workflow definition, role prompt)
+4. Injects \`outputFormatInstruction\` from the role's frontmatter schema
+5. Calls your \`run(ctx)\` function
+6. Extracts frontmatter from your output via \`tryFrontmatterFastPath()\`
+7. If extraction fails, calls your \`continue(sessionId, correctionMessage, store)\` up to 2 times
+8. Persists the validated output as a CAS step node
+9. Prints the step hash to stdout
+
+You only implement \`run\` and \`continue\`.
+
+## AgentOptions
+
+\`\`\`typescript
+type AgentOptions = {
+  name: string;           // Adapter name (used in step records as "uwf-<name>")
+  run: AgentRunFn;        // Execute a role from scratch
+  continue: AgentContinueFn;  // Resume a session for frontmatter correction
+};
+\`\`\`
+
+## AgentContext
+
+The \`ctx\` object passed to your \`run\` function:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`threadId\` | \`string\` | Thread ULID |
+| \`role\` | \`string\` | Role name being executed |
+| \`edgePrompt\` | \`string\` | Moderator's task instruction for this step |
+| \`workflow\` | \`WorkflowPayload\` | Full workflow definition (roles, graph) |
+| \`start\` | \`StartNodePayload\` | Thread start data (workflow hash, user prompt) |
+| \`steps\` | \`StepContext[]\` | Previous steps with expanded outputs |
+| \`store\` | \`Store\` | CAS store for reading/writing data |
+| \`outputFormatInstruction\` | \`string\` | Frontmatter format instruction (inject into system prompt) |
+| \`isFirstVisit\` | \`boolean\` | True if this role hasn't run before in this thread |
+
+## AgentRunResult
+
+Your \`run\` and \`continue\` functions must return:
+
+\`\`\`typescript
+type AgentRunResult = {
+  output: string;       // Raw markdown with frontmatter (must start with ---)
+  detailHash: string;   // CAS hash of session detail (turn history, metadata)
+  sessionId: string;    // Session ID for potential continue() calls
+};
+\`\`\`
+
+## Building the Prompt
+
+Use helpers from \`@uncaged/workflow-util-agent\`:
+
+| Helper | Purpose |
+|--------|---------|
+| \`buildRolePrompt(roleDef)\` | Assemble Goal/Capabilities/Prepare/Procedure/Output sections |
+| \`buildContinuationPrompt(steps, role, edgePrompt)\` | For re-entry: steps since last visit + edge prompt |
+| \`ctx.outputFormatInstruction\` | Pre-built frontmatter format block (inject into system prompt) |
+
+Typical system prompt structure:
+\`\`\`
+[outputFormatInstruction]
+[rolePrompt from buildRolePrompt()]
+[workflow metadata]
+\`\`\`
+
+## Storing Session Detail
+
+Store your turn history as a CAS merkle DAG for debugging and replay:
+
+\`\`\`typescript
+// Store each turn as a CAS text node
+const turnHash = await store.put(textSchema, { content: turnData });
+
+// Build a detail node referencing all turns
+const detailHash = await store.put(detailSchema, { turns: turnHashes });
+\`\`\`
+
+The \`detailHash\` is preserved from the first \`run()\` call — retry \`continue()\` calls don't overwrite it.
+
+## Registration
+
+Register your adapter in \`~/.uncaged/workflow/config.yaml\`:
+
+\`\`\`yaml
+agents:
+  my-agent:
+    command: uwf-my-agent
+    args: []
+\`\`\`
+
+Use it:
+\`\`\`bash
+uwf thread exec <thread-id> --agent my-agent
+\`\`\`
+
+Or set as default:
+\`\`\`yaml
+defaultAgent: my-agent
+\`\`\`
+
+## Existing Adapters
+
+| Adapter | Package | Backend |
+|---------|---------|---------|
+| \`uwf-hermes\` | \`@uncaged/workflow-agent-hermes\` | Hermes ACP (chat sessions) |
+| \`uwf-builtin\` | \`@uncaged/workflow-agent-builtin\` | Direct OpenAI API (tools + loop) |
+| \`uwf-claude-code\` | \`@uncaged/workflow-agent-claude-code\` | Claude Code CLI |
+
+Study these for patterns on prompt building, session management, and detail storage.
+
+## Checklist
+
+1. Implement \`run(ctx)\` — build prompt, call LLM, return output + detailHash + sessionId
+2. Implement \`continue(sessionId, message, store)\` — resume session for frontmatter correction
+3. Store session detail as CAS nodes (for debugging)
+4. Ensure output starts with \`---\` frontmatter block
+5. Add a \`bin\` entry in \`package.json\` for the CLI command
+6. Register in config.yaml and test with \`uwf thread exec --agent <name>\`
+`;
+}

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

@@ -0,0 +1,183 @@
+export function generateAuthorReference(): string {
+  return `# Author Reference
+
+Guide for designing and writing workflow YAML definitions.
+
+## Workflow Structure
+
+\`\`\`yaml
+name: solve-issue              # verb-first kebab-case
+description: "..."             # human-readable summary
+
+roles:                         # named actors
+  planner:
+    description: "..."         # short purpose
+    goal: "..."                # system-level goal for the agent
+    capabilities: [...]        # skill keywords the agent should load
+    procedure: |               # step-by-step instructions
+      1. Do this
+      2. Do that
+    output: "..."              # what the agent should produce
+    frontmatter:               # JSON Schema for structured output
+      oneOf:
+        - properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+          required: [$status, plan]
+        - properties:
+            $status: { const: "failed" }
+            error: { type: string }
+          required: [$status, error]
+
+graph:                         # status-based routing
+  $START:
+    _: { role: planner, prompt: "Analyze the issue." }
+  planner:
+    ready: { role: developer, prompt: "Implement {{{plan}}}." }
+    failed: { role: $END, prompt: "Failed: {{{error}}}" }
+\`\`\`
+
+## Role Definition
+
+| Field | Purpose |
+|-------|---------|
+| \`description\` | Short description for humans and moderator context |
+| \`goal\` | Injected as the agent's system-level objective |
+| \`capabilities\` | Keyword tags — agent loads matching skills before starting |
+| \`procedure\` | Step-by-step instructions the agent follows |
+| \`output\` | Describes what to produce and which \`$status\` values to use |
+| \`frontmatter\` | JSON Schema defining the structured output fields |
+
+### Role Design Principles
+
+- **Single responsibility** — each role does one thing well
+- **Minimal context** — don't overload a role with too many steps; split if needed
+- **Clear status values** — each status should map to a distinct graph edge
+- **Explicit output** — tell the agent exactly what \`$status\` values are valid
+
+## Frontmatter Schema
+
+The \`frontmatter\` field is a standard JSON Schema. It defines the structured fields the agent must output in YAML frontmatter.
+
+### \`$status\` Field
+
+\`$status\` is the only standard field. Its value determines which graph edge the moderator follows. Use \`const\` to constrain each variant:
+
+\`\`\`yaml
+frontmatter:
+  oneOf:
+    - properties:
+        $status: { const: "done" }
+        result: { type: string }
+      required: [$status, result]
+    - properties:
+        $status: { const: "failed" }
+        error: { type: string }
+      required: [$status, error]
+\`\`\`
+
+### Custom Fields
+
+Add any fields you need for data passing between roles. These are available in edge prompts via Mustache templates.
+
+### Flat Schema (Single Status)
+
+When a role has only one outcome:
+
+\`\`\`yaml
+frontmatter:
+  properties:
+    $status: { const: "done" }
+    summary: { type: string }
+  required: [$status, summary]
+\`\`\`
+
+## Graph Routing
+
+The graph maps each role's \`$status\` values to the next role:
+
+\`\`\`
+graph[role][$status] → { role: nextRole, prompt: edgePrompt }
+\`\`\`
+
+### Special Nodes
+
+| Node | Purpose |
+|------|---------|
+| \`$START\` | Entry point — status key is always \`_\` (unconditional) |
+| \`$END\` | Terminal — thread completes and is archived |
+
+### Edge Prompts
+
+Use triple-brace Mustache (\`{{{field}}}\`) to pass data from the previous step's output:
+
+\`\`\`yaml
+graph:
+  planner:
+    ready: { role: developer, prompt: "Implement plan {{{plan}}} in {{{repoPath}}}." }
+\`\`\`
+
+The fields referenced must exist in the source role's frontmatter schema.
+
+### Loops and Branching
+
+Roles can route back to previous roles (loops) or to different roles based on status (branching):
+
+\`\`\`yaml
+graph:
+  reviewer:
+    approved: { role: tester, prompt: "Run tests." }
+    rejected: { role: developer, prompt: "Fix: {{{comments}}}" }  # loop back
+\`\`\`
+
+### Fail Routing
+
+Route failures to a cleanup role or \`$END\`:
+
+\`\`\`yaml
+graph:
+  developer:
+    done: { role: reviewer, prompt: "Review changes." }
+    failed: { role: cleanup, prompt: "Clean up: {{{error}}}" }
+\`\`\`
+
+## Self-Testing
+
+### Step-by-Step Verification
+
+\`\`\`bash
+# Start a thread directly from YAML file (no registration needed)
+uwf thread start my-workflow.yaml -p "Test prompt"
+
+# Or register first, then start by name
+uwf workflow add my-workflow.yaml
+uwf thread start my-workflow -p "Test prompt"
+
+# Execute one step at a time to verify routing
+uwf thread exec <thread-id>
+
+# Inspect step output
+uwf step list <thread-id>
+uwf step show <step-hash>
+
+# Check the CAS data
+uwf cas get <output-hash>
+\`\`\`
+
+### Validation Checklist
+
+1. Every \`$status\` value in a role's frontmatter has a matching edge in the graph
+2. Every field referenced in edge prompts (\`{{{field}}}\`) exists in the source role's schema
+3. Every role referenced in the graph exists in \`roles\`
+4. \`$START\` has exactly one edge with key \`_\`
+5. At least one path leads to \`$END\`
+6. No orphan roles (defined but never routed to)
+
+## Common Pitfalls
+
+- **Missing graph edge** — if a role can produce \`$status: failed\` but the graph has no \`failed\` edge, the moderator will error
+- **Mustache field mismatch** — referencing \`{{{branch}}}\` in an edge prompt but the source schema has \`branchName\` instead
+- **Overly complex roles** — a role with 20 steps should be split; each role should be completable in one agent turn
+- **No fail path** — always handle failure; route to cleanup or \`$END\`
+`;
+}

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

@@ -0,0 +1,39 @@
+export function generateBootstrapReference(): string {
+  return `---
+name: uwf
+description: "Uncaged Workflow (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。"
+tags: [workflow, uwf, uncaged]
+triggers:
+  - uwf
+  - workflow
+  - 工作流
+---
+
+# uwf (Uncaged Workflow)
+
+YAML 状态机工作流引擎。当用户提到「workflow」「工作流」时，指的是 **uwf workflow**（YAML 定义的状态机），不是 Hermes skill。用 \`uwf\` CLI 操作，不要混淆。
+
+## 首次使用
+
+运行以下命令获取完整用法：
+
+\`\`\`bash
+uwf skill user    # 用户使用手册（CLI 命令、thread 生命周期）
+uwf skill author  # workflow 编写指南（role 定义、graph 路由、schema）
+\`\`\`
+
+## 快速参考
+
+\`\`\`bash
+uwf workflow list                          # 查看已注册 workflow
+uwf workflow add <file.yaml>               # 注册 workflow
+uwf thread start <workflow> -p "prompt"    # 创建 thread
+uwf thread exec <thread-id> -c 10          # 执行最多 10 步
+uwf thread list                            # 查看所有 thread
+\`\`\`
+
+## 示例 workflow
+
+参考项目 \`examples/\` 目录下的 YAML 文件（analyze-topic、debate、solve-issue）。
+`;
+}

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

@@ -0,0 +1,140 @@
+export function generateDeveloperReference(): string {
+  return `# Developer Reference
+
+Guide for contributing to the workflow engine codebase.
+
+## Monorepo Structure
+
+\`\`\`
+packages/
+  workflow-protocol/      # Shared types (WorkflowPayload, StepNodePayload, etc.)
+  workflow-util/          # Base32, ULID, logger, frontmatter parsing, skill references
+  workflow-util-agent/    # createAgent factory, context builder, extract pipeline
+  workflow-agent-hermes/  # uwf-hermes CLI (spawns Hermes chat sessions)
+  workflow-agent-builtin/ # uwf-builtin CLI (direct LLM calls via OpenAI API)
+  cli-workflow/           # uwf CLI (moderator, thread/step/cas/config commands)
+\`\`\`
+
+Dependency layers (each only imports from packages above it):
+\`\`\`
+protocol → util → util-agent → agent-hermes / agent-builtin / cli-workflow
+\`\`\`
+
+External CAS: \`@uncaged/json-cas\` (store API, hashing, schema validation) + \`@uncaged/json-cas-fs\` (filesystem backend).
+
+## Coding Conventions
+
+### Functional-first
+
+| Rule | Description |
+|------|-------------|
+| \`type\` over \`interface\` | All type definitions use \`type\` |
+| \`function\` over \`class\` | Pure functions + closures, no class |
+| No \`this\` | Functions must not depend on \`this\` context |
+| No inheritance | No \`extends\`, \`implements\`, \`abstract\` |
+| No optional properties | Use \`T \\| null\` instead of \`?:\` |
+| Immutability first | Use \`Readonly<T>\`, \`as const\`, avoid mutation |
+
+Classes allowed only when required by third-party libraries or for Error subclasses.
+
+### Error Handling
+
+- \`Result<T, E>\` type for expected failures (\`ok\`/\`err\` constructors from \`@uncaged/workflow-util\`)
+- \`throw\` only for unrecoverable bugs
+- No try-catch for flow control
+
+### Async
+
+Always \`async/await\`, never \`.then()\` chains.
+
+### Logging
+
+\`console.*\` is banned (Biome \`noConsole\` rule). Use the structured logger:
+
+\`\`\`typescript
+import { createLogger } from "@uncaged/workflow-util";
+const log = createLogger();
+log("4KNMR2PX", "Loading workflow...");  // 8-char Crockford Base32 tag
+\`\`\`
+
+Each call site gets a unique hand-written tag. \`grep "4KNMR2PX"\` in logs → instant code location.
+
+CLI package (\`@uncaged/cli-workflow\`) may use \`console.log\` for user-facing output with a biome-ignore comment.
+
+### No Dynamic Import
+
+No \`await import()\` in production code. Always static top-level \`import\`. Test files are exempt.
+
+### Naming
+
+- Workflow names: verb-first kebab-case (\`solve-issue\`, \`review-code\`)
+- IDs: Crockford Base32 — CAS hash (XXH64, 13-char), Thread ID (ULID, 26-char)
+
+## Development Workflow
+
+\`\`\`bash
+bun install                 # install all workspace deps
+bun run build               # tsc --build (all packages)
+bun run check               # tsc + biome check + lint-log-tags
+bun run format              # biome format --write
+bun test                    # run all tests
+\`\`\`
+
+Before committing: \`bun run check\` + \`bun test\` must both pass.
+
+### Testing
+
+- \`cli-workflow\`: vitest
+- Other packages: \`bun test\`
+- Test files live in \`__tests__/\` directories
+
+### Publishing
+
+Fixed-mode versioning — all \`@uncaged/*\` packages share the same version number.
+
+\`\`\`bash
+bun changeset               # describe the change
+bun version                 # bump versions + changelogs
+bun release                 # build + test + publish to npmjs
+\`\`\`
+
+## Key Modules
+
+### Moderator (\`cli-workflow/src/moderator/\`)
+
+Status-based graph evaluator. Reads \`graph[lastRole][output.$status]\` to determine the next role. Zero LLM cost.
+
+### Extract Pipeline (\`workflow-util-agent/src/\`)
+
+1. Agent produces frontmatter markdown
+2. \`parseFrontmatterMarkdown()\` extracts YAML frontmatter
+3. \`tryFrontmatterFastPath()\` validates against role's output schema
+4. If fast path fails, retries up to 2 times via agent continue
+5. Validated output stored as CAS node
+
+### createAgent Factory (\`workflow-util-agent/src/run.ts\`)
+
+Shared entry point for all agent CLIs. Handles:
+- Argument parsing (\`--thread\`, \`--role\`, \`--prompt\`)
+- Context building (thread history, workflow definition)
+- Output extraction and CAS persistence
+- Frontmatter retry loop
+
+### CAS Integration
+
+All data is CAS-addressed via \`@uncaged/json-cas\`:
+- \`store.put(schemaHash, data)\` → content hash
+- \`store.get(hash)\` → node
+- \`validate(store, node)\` → schema check
+- Schemas registered at workflow add time
+
+## Commit Convention
+
+\`\`\`
+<type>(<scope>): <description>
+
+type: feat | fix | refactor | docs | chore | test
+scope: workflow | cli | moderator | util-agent | hermes | util | protocol
+\`\`\`
+`;
+}

packages/workflow-util/src/frontmatter-markdown/frontmatter-markdown.ts

@@ -1,6 +1,5 @@
 import type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,
@@ -159,40 +158,12 @@ function parseMinimalYaml(yaml: string): Record<string, YamlValue> {
 
 const VALID_STATUS: readonly FrontmatterStatus[] = ["done", "needs_input", "in_progress", "failed"];
 
-const VALID_SCOPE: readonly FrontmatterScope[] = ["role", "thread"];
-
 function coerceStatus(raw: YamlValue): FrontmatterStatus | null {
   if (raw === null || raw === undefined) return null;
   const s = String(raw).trim().toLowerCase();
   return VALID_STATUS.includes(s as FrontmatterStatus) ? (s as FrontmatterStatus) : null;
 }
 
-function coerceNext(raw: YamlValue): string | null {
-  if (raw === null || raw === undefined) return null;
-  const s = String(raw).trim();
-  return s === "" ? null : s;
-}
-
-function coerceConfidence(raw: YamlValue): number | null {
-  if (raw === null || raw === undefined) return null;
-  const n = typeof raw === "number" ? raw : Number(String(raw).trim());
-  if (Number.isNaN(n)) return null;
-  return n;
-}
-
-function coerceArtifacts(raw: YamlValue): readonly string[] {
-  if (raw === null || raw === undefined) return [];
-  if (Array.isArray(raw)) return raw.map(String).filter((s) => s !== "");
-  const s = String(raw).trim();
-  return s === "" ? [] : [s];
-}
-
-function coerceScope(raw: YamlValue): FrontmatterScope {
-  if (raw === null || raw === undefined) return "role";
-  const s = String(raw).trim().toLowerCase();
-  return VALID_SCOPE.includes(s as FrontmatterScope) ? (s as FrontmatterScope) : "role";
-}
-
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /**
@@ -220,10 +191,6 @@ export function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
 
   const frontmatter: AgentFrontmatter = {
     status: coerceStatus(fields.status ?? null),
-    next: coerceNext(fields.next ?? null),
-    confidence: coerceConfidence(fields.confidence ?? null),
-    artifacts: coerceArtifacts(fields.artifacts ?? null),
-    scope: coerceScope(fields.scope ?? null),
   };
 
   return { frontmatter, body };
@@ -235,11 +202,7 @@ export function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
  * An empty array means the frontmatter is valid.
  *
  * Validated constraints:
- * - `status`     — must be one of the FrontmatterStatus literals (if non-null)
- * - `confidence` — must be in [0.0, 1.0] (if non-null)
- * - `next`       — must be a non-empty string with no whitespace (if non-null)
- * - `artifacts`  — each entry must be a non-empty string
- * - `scope`      — must be one of the FrontmatterScope literals
+ * - `status` — must be one of the FrontmatterStatus literals (if non-null)
  */
 export function validateFrontmatter(
   frontmatter: AgentFrontmatter,
@@ -253,39 +216,5 @@ export function validateFrontmatter(
     });
   }
 
-  if (frontmatter.confidence !== null) {
-    if (frontmatter.confidence < 0 || frontmatter.confidence > 1) {
-      errors.push({
-        field: "confidence",
-        message: `confidence ${frontmatter.confidence} is out of range; must be between 0.0 and 1.0 inclusive`,
-      });
-    }
-  }
-
-  if (frontmatter.next !== null) {
-    if (frontmatter.next.trim() === "") {
-      errors.push({ field: "next", message: "next must be a non-empty string when present" });
-    } else if (/\s/.test(frontmatter.next)) {
-      errors.push({
-        field: "next",
-        message: `next "${frontmatter.next}" must not contain whitespace`,
-      });
-    }
-  }
-
-  for (const artifact of frontmatter.artifacts) {
-    if (artifact.trim() === "") {
-      errors.push({ field: "artifacts", message: "artifact entries must be non-empty strings" });
-      break;
-    }
-  }
-
-  if (!VALID_SCOPE.includes(frontmatter.scope)) {
-    errors.push({
-      field: "scope",
-      message: `invalid scope "${frontmatter.scope}"; must be one of: ${VALID_SCOPE.join(", ")}`,
-    });
-  }
-
   return errors;
 }

packages/workflow-util/src/frontmatter-markdown/index.ts

@@ -1,7 +1,6 @@
 export { parseFrontmatterMarkdown, validateFrontmatter } from "./frontmatter-markdown.js";
 export type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,

packages/workflow-util/src/frontmatter-markdown/types.ts

@@ -1,5 +1,5 @@
 /**
- * Frontmatter Markdown — agent output format (RFC #351 Phase 1).
+ * Frontmatter Markdown — agent output format.
  *
  * An agent response is a Markdown document with an optional YAML frontmatter
  * block at the top.  The frontmatter carries structured signals that the
@@ -9,17 +9,12 @@
  *
  *   ---
  *   status: done
- *   next: reviewer
- *   confidence: 0.9
- *   artifacts:
- *     - src/foo.ts
- *   scope: role
  *   ---
  *
  *   ... free-form markdown body ...
  *
- * All frontmatter fields are optional at the parse level.  `validateFrontmatter`
- * enforces the constraints documented on each field below.
+ * Only `status` is a standard frontmatter field.  All other fields are
+ * role-specific and defined by the output schema.
  */
 
 // ── Vocabulary types ─────────────────────────────────────────────────────────
@@ -34,20 +29,12 @@
  */
 export type FrontmatterStatus = "done" | "needs_input" | "in_progress" | "failed";
 
-/**
- * Scope of frontmatter signals.
- *
- * - `role`   — signals apply to the current role execution only (default)
- * - `thread` — signals are suggestions for the entire thread moderator
- */
-export type FrontmatterScope = "role" | "thread";
-
 // ── Core frontmatter schema ──────────────────────────────────────────────────
 
 /**
  * Parsed and validated frontmatter from an agent response.
  *
- * All fields use explicit `T | null` (no optional `?:` per convention).
+ * Only `status` is a standard field.  All other fields are role-specific.
  */
 export type AgentFrontmatter = {
   /**
@@ -55,32 +42,6 @@ export type AgentFrontmatter = {
    * Null when omitted — engine treats it as "done" for backward compatibility.
    */
   status: FrontmatterStatus | null;
-
-  /**
-   * Suggested next role name for the moderator.
-   * The moderator is NOT obligated to follow this — it is advisory only.
-   * Null when the agent has no preference.
-   */
-  next: string | null;
-
-  /**
-   * Agent's self-assessed confidence in its output (0.0 – 1.0 inclusive).
-   * Null when omitted.
-   */
-  confidence: number | null;
-
-  /**
-   * Relative file paths or CAS hashes the agent considers its primary outputs.
-   * Used for GC ref-tracing and human-readable summaries.
-   * Empty array when omitted (never null — an absent list is an empty list).
-   */
-  artifacts: readonly string[];
-
-  /**
-   * Scope of the frontmatter signals.
-   * Defaults to "role" when omitted.
-   */
-  scope: FrontmatterScope;
 };
 
 // ── Parse output ─────────────────────────────────────────────────────────────
@@ -103,9 +64,4 @@ export type ParsedFrontmatterMarkdown = {
 
 // ── Validation error ─────────────────────────────────────────────────────────
 
-export type FrontmatterValidationError =
-  | { field: "status"; message: string }
-  | { field: "next"; message: string }
-  | { field: "confidence"; message: string }
-  | { field: "artifacts"; message: string }
-  | { field: "scope"; message: string };
+export type FrontmatterValidationError = { field: "status"; message: string };

packages/workflow-util/src/index.ts

@@ -1,10 +1,14 @@
+export { generateActorReference } from "./actor-reference.js";
+export { generateAdapterReference } from "./adapter-reference.js";
 export { generateArchitectureReference } from "./architecture-reference.js";
+export { generateAuthorReference } from "./author-reference.js";
 export { encodeUint64AsCrockford } from "./base32.js";
+export { generateBootstrapReference } from "./bootstrap-reference.js";
 export { generateCliReference } from "./cli-reference.js";
+export { generateDeveloperReference } from "./developer-reference.js";
 export { env } from "./env.js";
 export type {
   AgentFrontmatter,
-  FrontmatterScope,
   FrontmatterStatus,
   FrontmatterValidationError,
   ParsedFrontmatterMarkdown,
@@ -27,4 +31,5 @@ export { err, ok } from "./result.js";
 export { getDefaultWorkflowStorageRoot, getGlobalCasDir } from "./storage-root.js";
 export type { LogFn, Result } from "./types.js";
 export { extractUlidTimestamp, generateUlid } from "./ulid.js";
+export { generateUserReference } from "./user-reference.js";
 export { generateYamlReference } from "./yaml-reference.js";

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

@@ -0,0 +1,135 @@
+export function generateUserReference(): string {
+  return `# User Reference
+
+Guide for using the uwf CLI to manage workflows and threads.
+
+## Quick Start
+
+\`\`\`bash
+# 1. Configure provider and model
+uwf setup
+
+# 2. Register a workflow
+uwf workflow add my-workflow.yaml
+
+# 3. Start a thread (creates but does not execute)
+uwf thread start my-workflow -p "Build a login page"
+
+# 4. Execute the thread (runs moderator → agent → extract cycles)
+uwf thread exec <thread-id>          # one step
+uwf thread exec <thread-id> -c 10    # up to 10 steps
+uwf thread exec <thread-id> -c 10 --background  # run in background
+\`\`\`
+
+## Concepts
+
+- **Workflow** — YAML definition with roles and a routing graph; stored as a CAS node
+- **Thread** — A running instance of a workflow; a chain of step nodes in CAS
+- **Step** — One moderator → agent → extract cycle; contains the role's structured output
+- **CAS** — Content-addressable store; every artifact is hashed (XXH64, Crockford Base32)
+
+## Setup
+
+\`\`\`
+uwf setup                                          # interactive wizard
+uwf setup --provider <name> --base-url <url> \\
+           --api-key <key> --model <name>           # non-interactive
+           [--agent <name>]                         # optional default agent
+\`\`\`
+
+Config is stored at \`~/.uncaged/workflow/config.yaml\`. Override storage root with \`UNCAGED_WORKFLOW_STORAGE_ROOT\`.
+
+## Workflow Commands
+
+\`\`\`
+uwf workflow add <file>            # register from YAML file
+uwf workflow show <id>             # show by name or CAS hash
+uwf workflow list                  # list all registered workflows
+\`\`\`
+
+You can also pass a file path directly to \`uwf thread start\` without registering first.
+
+## Thread Lifecycle
+
+\`\`\`
+uwf thread start <workflow> -p <prompt>            # create thread
+uwf thread exec <thread-id>                        # execute one step
+               [--agent <cmd>]                     # override agent
+               [-c, --count <n>]                   # run n steps
+               [--background]                      # run in background
+uwf thread show <thread-id>                        # show head pointer
+uwf thread list                                    # list all threads
+               [--status <filter>]                 # idle, running, completed, cancelled, active (comma-separated)
+               [--after <thread-id>]               # pagination: after this thread
+               [--before <thread-id>]              # pagination: before this thread
+               [--skip <n>]                        # skip first n results
+               [--take <n>]                        # limit results
+uwf thread read <thread-id>                        # render context as markdown
+               [--quota <chars>]                   # max output chars (default 4000)
+               [--before <step-hash>]              # pagination
+               [--start]                           # include start step
+uwf thread stop <thread-id>                        # stop background execution
+uwf thread cancel <thread-id>                      # cancel and archive thread
+\`\`\`
+
+### Typical Lifecycle
+
+\`\`\`
+start → exec (repeat) → thread reaches $END → auto-completed
+                       → or: cancel to abort
+\`\`\`
+
+## Step Commands
+
+\`\`\`
+uwf step list <thread-id>         # list all steps
+uwf step show <step-hash>         # show step details
+uwf step fork <step-hash>         # fork thread from a step (branch)
+\`\`\`
+
+Forking creates a new thread that shares history up to the fork point — useful for retrying from a known-good state.
+
+## CAS Commands
+
+\`\`\`
+uwf cas get <hash>                 # read a node (type + payload)
+            [--timestamp]          # include timestamp
+uwf cas put <type-hash> <data>     # store typed JSON, print hash
+uwf cas put-text <text>            # store plain text, print hash
+uwf cas has <hash>                 # check existence
+uwf cas refs <hash>                # list direct references
+uwf cas walk <hash>                # recursive traversal
+uwf cas reindex                    # rebuild type index
+uwf cas schema list                # list schemas
+uwf cas schema get <hash>          # show schema definition
+\`\`\`
+
+## Log Commands
+
+\`\`\`
+uwf log list                       # list log files
+uwf log show                       # show log entries
+           [--thread <id>]         # filter by thread
+           [--process <pid>]       # filter by process
+           [--date <YYYY-MM-DD>]   # filter by date
+uwf log clean --before <date>      # delete old logs
+\`\`\`
+
+## Global Options
+
+\`\`\`
+uwf --format <json|yaml>           # output format (default: json)
+uwf -V, --version                  # print version
+\`\`\`
+
+## Other Skill References
+
+For specific scenarios, run the corresponding \`uwf skill\` command:
+
+| Scenario | Command | When to use |
+|----------|---------|-------------|
+| Writing workflow YAML | \`uwf skill author\` | Designing roles, conditions, graphs, and edge prompts |
+| Contributing to the engine | \`uwf skill developer\` | Modifying the workflow engine codebase itself |
+| Building a new agent adapter | \`uwf skill adapter\` | Creating a new \`uwf-<name>\` CLI adapter |
+`;
+}

packages/workflow-util/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/__tests__/**/*.test.ts"],
+    passWithNoTests: true,
+  },
+});

scripts/check-dev-env.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# Check development environment prerequisites for uncaged/workflow.
+# Non-interactive — prints actionable fix instructions on failure.
+# Exit 0 = all good, exit 1 = missing dependencies.
+set -euo pipefail
+
+errors=0
+
+check() {
+  local name="$1" check_cmd="$2" fix_msg="$3"
+  if eval "$check_cmd" >/dev/null 2>&1; then
+    echo "✅ $name"
+  else
+    echo "❌ $name"
+    echo "   Fix: $fix_msg"
+    errors=$((errors + 1))
+  fi
+}
+
+check_version() {
+  local name="$1" cmd="$2" fix_msg="$3"
+  local version
+  if version=$(eval "$cmd" 2>/dev/null | head -1); then
+    echo "✅ $name — $version"
+  else
+    echo "❌ $name"
+    echo "   Fix: $fix_msg"
+    errors=$((errors + 1))
+  fi
+}
+
+echo "=== Runtime ==="
+check_version "bun" "bun --version" \
+  "curl -fsSL https://bun.sh/install | bash"
+
+check_version "node" "node --version" \
+  "Install Node.js 20+: https://nodejs.org/"
+
+check_version "python3" "python3 --version" \
+  "Install Python 3.11+: https://www.python.org/ or use uv: curl -LsSf https://astral.sh/uv/install.sh | sh && uv python install 3.11"
+
+echo ""
+echo "=== Tools ==="
+check_version "hermes" "hermes --version" \
+  "See https://github.com/hermes-ai/hermes-agent for installation. Typical: pip install hermes-agent (or uv pip install -e . for dev)"
+
+check_version "claude" "claude --version" \
+  "npm install -g @anthropic-ai/claude-code"
+
+echo ""
+echo "=== Workflow ==="
+
+# Check repo location
+REPO_DIR="${WORKFLOW_REPO:-$(cd "$(dirname "$0")/.." && pwd)}"
+check "repo at ~/repos/workflow or WORKFLOW_REPO set" \
+  "[ -f '$REPO_DIR/packages/cli-workflow/src/cli.ts' ]" \
+  "Clone the repo: git clone https://git.shazhou.work/uncaged/workflow ~/repos/workflow"
+
+# Check bun install
+check "node_modules installed" \
+  "[ -d '$REPO_DIR/node_modules' ]" \
+  "cd $REPO_DIR && bun install"
+
+# Check build
+check "packages built (dist/)" \
+  "[ -f '$REPO_DIR/packages/cli-workflow/dist/cli.js' ]" \
+  "cd $REPO_DIR && bun run build"
+
+# Check uwf is runnable
+check_version "uwf" "bun $REPO_DIR/packages/cli-workflow/src/cli.ts --version" \
+  "cd $REPO_DIR && bun install && bun run build"
+
+# Check uwf symlink
+check "uwf in PATH" \
+  "command -v uwf" \
+  "sudo ln -sf $REPO_DIR/packages/cli-workflow/dist/cli.js /usr/bin/uwf && sudo chmod +x /usr/bin/uwf"
+
+# Check uwf-hermes
+check "uwf-hermes in PATH" \
+  "command -v uwf-hermes" \
+  "bun link in packages/workflow-agent-hermes, or: echo '#!/usr/bin/env bun' > ~/.local/bin/uwf-hermes && echo 'import \"$REPO_DIR/packages/workflow-agent-hermes/src/cli.ts\"' >> ~/.local/bin/uwf-hermes && chmod +x ~/.local/bin/uwf-hermes"
+
+# Check uwf-claude-code
+check "uwf-claude-code in PATH" \
+  "command -v uwf-claude-code" \
+  "Create wrapper: echo '#!/bin/bash\nexec bun run $REPO_DIR/packages/workflow-agent-claude-code/src/cli.ts \"\$@\"' > ~/.local/bin/uwf-claude-code && chmod +x ~/.local/bin/uwf-claude-code"
+
+echo ""
+echo "=== Config ==="
+
+# Check workflow config exists
+CONFIG_DIR="${UNCAGED_WORKFLOW_STORAGE_ROOT:-$HOME/.uncaged/workflow}"
+check "config.yaml exists" \
+  "[ -f '$CONFIG_DIR/config.yaml' ]" \
+  "Run: uwf setup"
+
+# Check config has apiKey (not apiKeyEnv)
+if [ -f "$CONFIG_DIR/config.yaml" ]; then
+  check "config uses apiKey (not legacy apiKeyEnv)" \
+    "grep -q 'apiKey:' '$CONFIG_DIR/config.yaml' && ! grep -q 'apiKeyEnv:' '$CONFIG_DIR/config.yaml'" \
+    "Run: uwf setup (re-configure to write apiKey directly)"
+fi
+
+echo ""
+echo "=== Docker (optional, for E2E tests) ==="
+check_version "docker" "docker --version" \
+  "sudo apt install -y docker.io && sudo usermod -aG docker \$USER"
+
+check "docker daemon running" \
+  "docker info" \
+  "sudo systemctl start docker"
+
+echo ""
+if [ "$errors" -gt 0 ]; then
+  echo "⚠️  $errors issue(s) found. Fix them and re-run this script."
+  exit 1
+else
+  echo "🎉 All checks passed!"
+  exit 0
+fi