fix(#447): fix biome format in loop.test.ts

.cursor/rules/sync-readme.mdc

@@ -1,67 +0,0 @@
-# Sync README
-
-When updating README.md files in this monorepo, follow these conventions.
-
-## Scope
-
-- Root `README.md` — project overview and navigation hub
-- Per-package `packages/*/README.md` — each package self-contained
-
-## Root README Structure
-
-The root README should have these sections in order:
-
-1. **Title and one-liner** — stateless workflow engine driven by single-step CLI
-2. **Overview** — 2-3 paragraphs explaining what it does and key concepts
-3. **Architecture** — dependency layer diagram (text-based)
-4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib/agent/app)
-5. **Quick Start** — install, build, register workflow, start thread, run step
-6. **CLI Reference** — brief command list, detailed usage in cli-workflow README
-7. **Development** — bun install / build / check / test
-
-## Per-Package README Structure
-
-Each package README should have:
-
-1. **Title** — package name
-2. **One-line description** — matching package.json
-3. **Overview** — what it does, where it sits in the architecture, dependencies
-4. **Installation** — bun add (for libs) or "included as binary" (for cli/agents)
-5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
-6. **CLI Usage** (cli/agent packages) — command reference with examples
-7. **Internal Structure** — brief src/ file organization
-8. **Configuration** (if applicable)
-
-## Execution Steps
-
-### Step 1: Gather current state
-For each package read:
-- package.json (name, version, description, dependencies, bin)
-- src/index.ts (public API exports)
-- Existing README.md (preserve hand-written content worth keeping)
-
-### Step 2: Update root README
-- Ensure ALL packages in packages/ directory are listed in the table
-- Update CLI command reference from uwf --help output
-- Keep Quick Start examples valid
-
-### Step 3: Write/update each package README
-- Follow the per-package structure
-- API section MUST match actual src/index.ts exports — never invent
-- For agent packages: document CLI binary name, how it is invoked
-- For lib packages: document exported types and functions
-- Internal structure: list actual files in src/
-
-### Step 4: Verify
-- All relative links work
-- Package names match package.json
-- No references to removed/renamed packages
-- bun run build still passes
-
-## Guidelines
-
-- Only document what src/index.ts actually exports
-- Root README summarizes, package READMEs go into detail
-- Verify CLI examples against actual commands
-- Preserve existing good prose when updating
-- English for all README content

README.md

@@ -2,102 +2,92 @@
 
 A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, JSONata routing conditions, and a directed graph. Threads are immutable CAS-linked chains — each `uwf thread step` runs one moderator→agent→extract cycle and exits.
 
-## Overview
+## Package Map
 
-This monorepo implements **uwf**, a workflow engine with no long-running daemon. You register YAML workflow definitions in a content-addressed store (CAS), start a thread with an initial prompt, then invoke `uwf thread step` repeatedly until the moderator routes to `$END`. Each step is a complete process: the moderator evaluates JSONata conditions to pick the next role, an external agent CLI produces frontmatter markdown output, and an extract pipeline validates or structures that output against the role's JSON Schema.
+| Package | npm | Role |
+|---------|-----|------|
+| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI binary — thread lifecycle, workflow registry, CAS inspection, setup |
+| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `WorkflowConfig`, etc.) |
+| `workflow-moderator` | `@uncaged/workflow-moderator` | JSONata graph evaluator — determines next role or `$END` |
+| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, two-layer extract pipeline |
+| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` agent — spawns Hermes chat, captures session |
+| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing |
 
-Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes for definitions and step payloads, `registry.yaml` for workflow name→hash mappings, and `threads.yaml` for active thread head pointers. Completed threads are archived to `history.jsonl`. Because there is no server process, workflows are easy to debug, fork, and inspect with ordinary CLI tools.
-
-Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `<thread-id>` and `<role>`, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay.
-
-## Architecture
-
-Dependency layers (lower layers have no dependency on higher layers):
-
-```
-Layer 0 — Contract
-  workflow-protocol          Shared types and JSON Schema definitions
-
-Layer 1 — Shared infra
-  workflow-util              Encoding, IDs, logging, frontmatter, paths
-  workflow-moderator         JSONata graph evaluator
-
-Layer 2 — Agent framework
-  workflow-agent-kit         createAgent factory, context builder, extract pipeline
-
-Layer 3 — Agent implementations
-  workflow-agent-hermes      Hermes ACP agent (uwf-hermes)
-  workflow-agent-builtin     Built-in LLM + tools agent (uwf-builtin)
-  workflow-agent-claude-code Claude Code agent (uwf-claude-code)
-
-Layer 4 — CLI
-  cli-workflow               uwf binary — thread lifecycle, registry, CAS, setup
-
-App (uses protocol; not in the runtime engine stack)
-  workflow-dashboard         Web UI for visual workflow editing
-```
-
-External CAS: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (store API, hashing, schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
-
-See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.
-
-## Packages
-
-| Package | npm | Description | Type | README |
-|---------|-----|-------------|------|--------|
-| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI — thread lifecycle, workflow registry, CAS inspection, setup | cli | [README](packages/cli-workflow/README.md) |
-| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types and JSON Schema constants | lib | [README](packages/workflow-protocol/README.md) |
-| `workflow-moderator` | `@uncaged/workflow-moderator` | JSONata graph evaluator — next role or `$END` | lib | [README](packages/workflow-moderator/README.md) |
-| `workflow-agent-kit` | `@uncaged/workflow-agent-kit` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-agent-kit/README.md) |
-| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | [README](packages/workflow-util/README.md) |
-| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` — spawns Hermes chat via ACP | agent | [README](packages/workflow-agent-hermes/README.md) |
-| `workflow-agent-builtin` | `@uncaged/workflow-agent-builtin` | `uwf-builtin` — built-in LLM agent with file/shell tools | agent | [README](packages/workflow-agent-builtin/README.md) |
-| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) |
-| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) |
+External: [`@uncaged/json-cas`](https://www.npmjs.com/package/@uncaged/json-cas) (CAS store + JSON Schema validation) + `@uncaged/json-cas-fs` (filesystem backend).
 
 ## Quick Start
 
 ```bash
-# 1. Configure provider, model, and default agent
+# 1. Configure provider and model
 uwf setup
 
 # 2. Register a workflow from YAML
 uwf workflow put examples/solve-issue.yaml
 
-# 3. Start a thread (creates head pointer; does not execute)
+# 3. Start a thread
 uwf thread start solve-issue -p "Fix the login redirect bug"
 
 # 4. Execute steps (one at a time, until done)
 uwf thread step <thread-id>
 ```
 
-Use `-c, --count <number>` on `thread step` to run multiple steps in one invocation. Override the agent with `--agent <cmd>`.
+## CLI Commands
 
-## CLI Reference
+### Thread
 
-Global options: `-V, --version`, `--format <json|yaml>`, `-h, --help`.
+| Command | Description |
+|---------|-------------|
+| `uwf thread start <workflow> -p <prompt>` | Create a thread (no execution) |
+| `uwf thread step <thread-id> [--agent <cmd>]` | Execute one moderator→agent→extract cycle |
+| `uwf thread show <thread-id>` | Show head pointer and done status |
+| `uwf thread list [--all]` | List threads (`--all` includes archived) |
+| `uwf thread steps <thread-id>` | List all steps chronologically |
+| `uwf thread read <thread-id> [--quota N]` | Render thread as readable markdown |
+| `uwf thread fork <step-hash>` | Fork from a specific step |
+| `uwf thread step-details <step-hash>` | Dump full detail node |
+| `uwf thread kill <thread-id>` | Terminate and archive |
 
-| Group | Commands |
-|-------|----------|
-| **thread** | `start`, `step`, `show`, `list`, `kill`, `steps`, `read`, `fork`, `step-details` |
-| **workflow** | `put`, `show`, `list` |
-| **cas** | `get`, `put`, `put-text`, `has`, `refs`, `walk`, `reindex`, `schema list`, `schema get` |
-| **setup** | Interactive or `--provider`, `--base-url`, `--api-key`, `--model`, `--agent` |
-| **skill** | `cli` — print markdown reference of all uwf commands |
-| **log** | `list`, `show`, `clean` — process-level debug logs |
+### Workflow
 
-Config is stored in `~/.uncaged/workflow/config.yaml`. API keys go in `~/.uncaged/workflow/.env`.
+| Command | Description |
+|---------|-------------|
+| `uwf workflow put <file.yaml>` | Register a workflow from YAML |
+| `uwf workflow show <name-or-hash>` | Show workflow definition |
+| `uwf workflow list` | List registered workflows |
 
-Detailed command usage, options, and examples: [packages/cli-workflow/README.md](packages/cli-workflow/README.md).
+### CAS
+
+| Command | Description |
+|---------|-------------|
+| `uwf cas get <hash>` | Read a CAS node |
+| `uwf cas put <type-hash> <data>` | Store a node |
+| `uwf cas has <hash>` | Check existence |
+| `uwf cas refs <hash>` | List direct references |
+| `uwf cas walk <hash>` | Recursive traversal |
+| `uwf cas reindex` | Rebuild type index |
+| `uwf cas schema list` | List schemas |
+| `uwf cas schema get <hash>` | Show a schema |
+
+### Setup
+
+| Command | Description |
+|---------|-------------|
+| `uwf setup` | Interactive provider/model/agent configuration |
+| `uwf setup --provider ... --base-url ... --api-key ... --model ...` | Non-interactive setup |
+
+Config stored in `~/.uncaged/workflow/config.yaml`. API keys in `~/.uncaged/workflow/.env`.
 
 ## Development
 
 ```bash
 bun install --no-cache     # Install dependencies
-bun run build              # tsc --build (all packages)
 bun run check              # tsc + biome + lint-log-tags
 bun run format             # Auto-format with Biome
 bun test                   # Run all tests
 ```
 
 Managed with **bun workspace**. See [CLAUDE.md](CLAUDE.md) for coding conventions.
+
+## Architecture
+
+See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, CAS node types, storage layout, agent CLI protocol, and design decisions.

packages/cli-workflow/README.md

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

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

@@ -1,381 +0,0 @@
-import { mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, test, vi } from "vitest";
-import {
-  _discoverAgents,
-  _isBackspace,
-  _isTerminator,
-  _parseWhichOutput,
-  _printModelMenu,
-  _printProviderMenu,
-  _printValidationResult,
-  _resolveModelChoice,
-  _resolveProviderChoice,
-  _searchPathDirs,
-} from "../commands/setup.js";
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 1a. _searchPathDirs
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_searchPathDirs", () => {
-  test("returns empty array for empty PATH", async () => {
-    const result = await _searchPathDirs("");
-    expect(result).toEqual([]);
-  });
-
-  test("finds uwf-hermes in a single dir", async () => {
-    const dir = mkdirSync(join(tmpdir(), `uwf-test-${Date.now()}`), { recursive: true }) as
-      | string
-      | undefined;
-    const actualDir = dir ?? join(tmpdir(), `uwf-test-${Date.now()}`);
-    mkdirSync(actualDir, { recursive: true });
-    const filePath = join(actualDir, "uwf-hermes");
-    writeFileSync(filePath, "#!/bin/sh\n", { mode: 0o755 });
-    const result = await _searchPathDirs(actualDir);
-    expect(result).toContain("uwf-hermes");
-  });
-
-  test("skips non-uwf- prefixed binaries", async () => {
-    const dir = join(tmpdir(), `uwf-test-${Date.now()}-2`);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "hermes"), "#!/bin/sh\n", { mode: 0o755 });
-    writeFileSync(join(dir, "uwf-hermes"), "#!/bin/sh\n", { mode: 0o755 });
-    const result = await _searchPathDirs(dir);
-    expect(result).toEqual(["uwf-hermes"]);
-  });
-
-  test("skips entry named exactly 'uwf'", async () => {
-    const dir = join(tmpdir(), `uwf-test-${Date.now()}-3`);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "uwf"), "#!/bin/sh\n", { mode: 0o755 });
-    writeFileSync(join(dir, "uwf-hermes"), "#!/bin/sh\n", { mode: 0o755 });
-    const result = await _searchPathDirs(dir);
-    expect(result).toEqual(["uwf-hermes"]);
-  });
-
-  test("skips non-executable files", async () => {
-    const dir = join(tmpdir(), `uwf-test-${Date.now()}-4`);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "uwf-foo"), "#!/bin/sh\n", { mode: 0o644 });
-    const result = await _searchPathDirs(dir);
-    expect(result).toEqual([]);
-  });
-
-  test("deduplicates across PATH dirs", async () => {
-    const dir1 = join(tmpdir(), `uwf-test-${Date.now()}-5a`);
-    const dir2 = join(tmpdir(), `uwf-test-${Date.now()}-5b`);
-    mkdirSync(dir1, { recursive: true });
-    mkdirSync(dir2, { recursive: true });
-    writeFileSync(join(dir1, "uwf-hermes"), "#!/bin/sh\n", { mode: 0o755 });
-    writeFileSync(join(dir2, "uwf-hermes"), "#!/bin/sh\n", { mode: 0o755 });
-    const result = await _searchPathDirs(`${dir1}:${dir2}`);
-    expect(result).toEqual(["uwf-hermes"]);
-  });
-
-  test("returns sorted array", async () => {
-    const dir = join(tmpdir(), `uwf-test-${Date.now()}-6`);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "uwf-zoo"), "#!/bin/sh\n", { mode: 0o755 });
-    writeFileSync(join(dir, "uwf-alpha"), "#!/bin/sh\n", { mode: 0o755 });
-    writeFileSync(join(dir, "uwf-mid"), "#!/bin/sh\n", { mode: 0o755 });
-    const result = await _searchPathDirs(dir);
-    expect(result).toEqual(["uwf-alpha", "uwf-mid", "uwf-zoo"]);
-  });
-
-  test("skips inaccessible/nonexistent directories silently", async () => {
-    const result = await _searchPathDirs("/nonexistent-dir-xyz-abc-12345");
-    expect(result).toEqual([]);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 1b. _parseWhichOutput
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_parseWhichOutput", () => {
-  test("returns empty array for empty string", () => {
-    expect(_parseWhichOutput("")).toEqual([]);
-  });
-
-  test("parses single path", () => {
-    expect(_parseWhichOutput("/usr/local/bin/uwf-hermes")).toEqual(["uwf-hermes"]);
-  });
-
-  test("parses multiple paths", () => {
-    expect(_parseWhichOutput("/usr/local/bin/uwf-hermes\n/usr/bin/uwf-claude-code")).toEqual([
-      "uwf-claude-code",
-      "uwf-hermes",
-    ]);
-  });
-
-  test("deduplicates identical basenames from different dirs", () => {
-    expect(_parseWhichOutput("/a/uwf-hermes\n/b/uwf-hermes")).toEqual(["uwf-hermes"]);
-  });
-
-  test("skips blank lines", () => {
-    expect(_parseWhichOutput("/a/uwf-hermes\n\n/b/uwf-cursor")).toEqual([
-      "uwf-cursor",
-      "uwf-hermes",
-    ]);
-  });
-
-  test("skips entry named exactly 'uwf'", () => {
-    expect(_parseWhichOutput("/usr/bin/uwf")).toEqual([]);
-  });
-
-  test("skips basenames not starting with uwf-", () => {
-    expect(_parseWhichOutput("/usr/bin/node")).toEqual([]);
-  });
-
-  test("returns sorted array", () => {
-    expect(_parseWhichOutput("/a/uwf-zoo\n/a/uwf-alpha")).toEqual(["uwf-alpha", "uwf-zoo"]);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 2a. _isTerminator
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_isTerminator", () => {
-  test("\\n is a terminator", () => {
-    expect(_isTerminator("\n")).toBe(true);
-  });
-  test("\\r is a terminator", () => {
-    expect(_isTerminator("\r")).toBe(true);
-  });
-  test("\\u0004 (EOT) is a terminator", () => {
-    expect(_isTerminator("")).toBe(true);
-  });
-  test("regular char is not a terminator", () => {
-    expect(_isTerminator("a")).toBe(false);
-  });
-  test("empty string is not a terminator", () => {
-    expect(_isTerminator("")).toBe(false);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 2b. _isBackspace
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_isBackspace", () => {
-  test("\\u007F is a backspace", () => {
-    expect(_isBackspace("")).toBe(true);
-  });
-  test("\\b is a backspace", () => {
-    expect(_isBackspace("\b")).toBe(true);
-  });
-  test("regular char is not a backspace", () => {
-    expect(_isBackspace("x")).toBe(false);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 3a. _printProviderMenu
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_printProviderMenu", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  const providers = [
-    { name: "openai", label: "OpenAI", baseUrl: "https://api.openai.com/v1" },
-    { name: "xai", label: "xAI", baseUrl: "https://api.x.ai/v1" },
-  ] as const;
-
-  test("prints correct number of lines (one per provider + custom)", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printProviderMenu(providers);
-    // 2 providers + 1 custom = 3 lines
-    expect(lines.length).toBe(3);
-  });
-
-  test("custom option number = providers.length + 1", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printProviderMenu(providers);
-    const lastLine = lines[lines.length - 1] ?? "";
-    expect(lastLine).toMatch(/3\)/);
-  });
-
-  test("each provider line contains its label and baseUrl", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printProviderMenu(providers);
-    expect(lines[0]).toContain("OpenAI");
-    expect(lines[0]).toContain("https://api.openai.com/v1");
-    expect(lines[1]).toContain("xAI");
-    expect(lines[1]).toContain("https://api.x.ai/v1");
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 3b. _resolveProviderChoice
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_resolveProviderChoice", () => {
-  const providers = [
-    { name: "openai", label: "OpenAI", baseUrl: "https://api.openai.com/v1" },
-    { name: "xai", label: "xAI", baseUrl: "https://api.x.ai/v1" },
-    { name: "deepseek", label: "DeepSeek", baseUrl: "https://api.deepseek.com/v1" },
-  ] as const;
-
-  test("valid index 1 returns first provider", () => {
-    const result = _resolveProviderChoice("1", providers);
-    expect(result).toEqual({ providerName: "openai", baseUrl: "https://api.openai.com/v1" });
-  });
-
-  test("valid index N (last preset) returns last provider", () => {
-    const result = _resolveProviderChoice("3", providers);
-    expect(result).toEqual({ providerName: "deepseek", baseUrl: "https://api.deepseek.com/v1" });
-  });
-
-  test("index providers.length+1 (custom) returns null", () => {
-    const result = _resolveProviderChoice("4", providers);
-    expect(result).toBeNull();
-  });
-
-  test("non-numeric string returns null", () => {
-    expect(_resolveProviderChoice("abc", providers)).toBeNull();
-  });
-
-  test("0 returns null (out of range)", () => {
-    expect(_resolveProviderChoice("0", providers)).toBeNull();
-  });
-
-  test("N+2 returns null (out of range)", () => {
-    expect(_resolveProviderChoice("5", providers)).toBeNull();
-  });
-
-  test("negative number returns null", () => {
-    expect(_resolveProviderChoice("-1", providers)).toBeNull();
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 3c. _resolveModelChoice
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_resolveModelChoice", () => {
-  test("numeric input within range returns model at that index", () => {
-    expect(_resolveModelChoice("2", ["a", "b", "c"])).toBe("b");
-  });
-
-  test("numeric input out of range returns input as-is", () => {
-    expect(_resolveModelChoice("5", ["a"])).toBe("5");
-  });
-
-  test("non-numeric input returns input as-is", () => {
-    expect(_resolveModelChoice("gpt-4o", ["a", "b"])).toBe("gpt-4o");
-  });
-
-  test("numeric input 1 returns first model", () => {
-    expect(_resolveModelChoice("1", ["alpha", "beta"])).toBe("alpha");
-  });
-
-  test("empty models list with numeric input returns input as-is", () => {
-    expect(_resolveModelChoice("1", [])).toBe("1");
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 3d. _printModelMenu
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_printModelMenu", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  test("prints all models — each model name appears in output", () => {
-    const output: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      output.push(msg);
-    });
-    const models = ["model-a", "model-b", "model-c"];
-    _printModelMenu(models, 100);
-    const combined = output.join("\n");
-    for (const m of models) {
-      expect(combined).toContain(m);
-    }
-  });
-
-  test("single column when termCols is very small", () => {
-    const output: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      output.push(msg);
-    });
-    _printModelMenu(["a", "b", "c"], 1);
-    // Each model on its own row → 3 lines
-    expect(output.length).toBe(3);
-  });
-
-  test("wide terminal fits multiple columns", () => {
-    const output: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      output.push(msg);
-    });
-    const models = Array.from({ length: 6 }, (_, i) => `m${i}`);
-    _printModelMenu(models, 200);
-    // With wide terminal and short names, should fit in fewer than 6 rows
-    expect(output.length).toBeLessThan(6);
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 3e. _printValidationResult
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_printValidationResult", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  test("ok=true prints success message containing '✓'", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printValidationResult({ ok: true, error: null });
-    expect(lines.join("\n")).toContain("✓");
-  });
-
-  test("ok=false prints warning message containing '⚠'", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printValidationResult({ ok: false, error: "HTTP 401" });
-    expect(lines.join("\n")).toContain("⚠");
-  });
-
-  test("ok=false includes the error string in output", () => {
-    const lines: string[] = [];
-    vi.spyOn(console, "log").mockImplementation((msg: string) => {
-      lines.push(msg);
-    });
-    _printValidationResult({ ok: false, error: "HTTP 401" });
-    expect(lines.join("\n")).toContain("HTTP 401");
-  });
-});
-
-// ──────────────────────────────────────────────────────────────────────────────
-// 4. Regression
-// ──────────────────────────────────────────────────────────────────────────────
-
-describe("_discoverAgents regression", () => {
-  test("returns an array (may be empty) — never throws", async () => {
-    const result = await _discoverAgents();
-    expect(Array.isArray(result)).toBe(true);
-  });
-});

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

@@ -1,683 +0,0 @@
-import { mkdir, mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { bootstrap, putSchema } from "@uncaged/json-cas";
-import { createFsStore } from "@uncaged/json-cas-fs";
-import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
-import { cmdThreadRead, THREAD_READ_DEFAULT_QUOTA } from "../commands/thread.js";
-import { registerUwfSchemas } from "../schemas.js";
-import type { UwfStore } from "../store.js";
-import { saveThreadsIndex } from "../store.js";
-
-// ── schemas used in tests ────────────────────────────────────────────────────
-
-const TURN_SCHEMA = {
-  title: "hermes-turn",
-  type: "object" as const,
-  required: ["index", "role", "content"],
-  properties: {
-    index: { type: "integer" as const },
-    role: { type: "string" as const },
-    content: { type: "string" as const },
-    toolCalls: {
-      anyOf: [
-        { type: "array" as const, items: { type: "object" as const } },
-        { type: "null" as const },
-      ],
-    },
-    reasoning: { anyOf: [{ type: "string" as const }, { type: "null" as const }] },
-  },
-  additionalProperties: false,
-};
-
-const DETAIL_SCHEMA = {
-  title: "hermes-detail",
-  type: "object" as const,
-  required: ["sessionId", "model", "duration", "turnCount", "turns"],
-  properties: {
-    sessionId: { type: "string" as const },
-    model: { type: "string" as const },
-    duration: { type: "integer" as const },
-    turnCount: { type: "integer" as const },
-    turns: {
-      type: "array" as const,
-      items: { type: "string" as const, format: "cas_ref" },
-    },
-  },
-  additionalProperties: false,
-};
-
-// ── helpers ───────────────────────────────────────────────────────────────────
-
-async function makeUwfStore(storageRoot: string): Promise<UwfStore> {
-  const casDir = join(storageRoot, "cas");
-  await mkdir(casDir, { recursive: true });
-  const store = createFsStore(casDir);
-  const schemas = await registerUwfSchemas(store);
-  return { storageRoot, store, schemas };
-}
-
-async function registerDetailSchemas(store: ReturnType<typeof createFsStore>) {
-  await bootstrap(store);
-  const [turn, detail] = await Promise.all([
-    putSchema(store, TURN_SCHEMA),
-    putSchema(store, DETAIL_SCHEMA),
-  ]);
-  return { turn, detail };
-}
-
-// ── fixture ───────────────────────────────────────────────────────────────────
-
-let tmpDir: string;
-
-beforeEach(async () => {
-  tmpDir = await mkdtemp(join(tmpdir(), "cli-uwf-test-"));
-});
-
-afterEach(async () => {
-  await rm(tmpDir, { recursive: true, force: true });
-});
-
-// ── thread read XML tag isolation ─────────────────────────────────────────────
-
-describe("thread read XML tag isolation", () => {
-  test("scenario 1: wraps output in XML tags instead of heading", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const detailSchemas = await registerDetailSchemas(uwf.store);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        planner: {
-          description: "Planner",
-          goal: "You are a planning agent. Your task is to...",
-          capabilities: [],
-          procedure: "Plan the work.",
-          output: "Summarize the plan.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Fix issue #459",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const turnHash = await uwf.store.put(detailSchemas.turn, {
-      index: 0,
-      role: "assistant",
-      content:
-        "---\nstatus: ready\nplan: CMWGHQKT58RY4\n---\n\n# Analysis Complete\n## Issue Summary\nThe issue requires XML tag isolation.",
-      toolCalls: null,
-      reasoning: null,
-    });
-    const detailHash = await uwf.store.put(detailSchemas.detail, {
-      sessionId: "sx",
-      model: "mx",
-      duration: 500,
-      turnCount: 1,
-      turns: [turnHash],
-    });
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "planner",
-      output: outputHash,
-      detail: detailHash,
-      agent: "uwf-claude-code",
-    });
-
-    const threadId = "01JTEST0000000000000001" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Should wrap output in XML tags
-    expect(markdown).toContain("<output>");
-    expect(markdown).toContain("</output>");
-
-    // Should not have ### Content heading
-    expect(markdown).not.toContain("### Content");
-
-    // Should preserve markdown headings inside output tags
-    expect(markdown).toContain("# Analysis Complete");
-    expect(markdown).toContain("## Issue Summary");
-  });
-
-  test("scenario 2: wraps prompt in XML tags", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const detailSchemas = await registerDetailSchemas(uwf.store);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        planner: {
-          description: "Planner",
-          goal: "You are a planning agent. Your task is to analyze and plan.",
-          capabilities: [],
-          procedure: "Plan the work.",
-          output: "Summarize the plan.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Fix issue",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const turnHash = await uwf.store.put(detailSchemas.turn, {
-      index: 0,
-      role: "assistant",
-      content: "---\nstatus: ready\n---\n\nContent here...",
-      toolCalls: null,
-      reasoning: null,
-    });
-    const detailHash = await uwf.store.put(detailSchemas.detail, {
-      sessionId: "sx",
-      model: "mx",
-      duration: 500,
-      turnCount: 1,
-      turns: [turnHash],
-    });
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "planner",
-      output: outputHash,
-      detail: detailHash,
-      agent: "uwf-claude-code",
-    });
-
-    const threadId = "01JTEST0000000000000002" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Should wrap prompt in XML tags
-    expect(markdown).toContain("<prompt>");
-    expect(markdown).toContain("</prompt>");
-    expect(markdown).toContain("You are a planning agent. Your task is to analyze and plan.");
-
-    // Should not have ### Prompt heading
-    expect(markdown).not.toContain("### Prompt");
-
-    // Should wrap output in XML tags
-    expect(markdown).toContain("<output>");
-    expect(markdown).toContain("</output>");
-  });
-
-  test("scenario 3: same role repeated does not show prompt twice", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        writer: {
-          description: "Writer",
-          goal: "You are a writer agent.",
-          capabilities: [],
-          procedure: "Write content.",
-          output: "Summarize writing.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Write something",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const step1 = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "writer",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const step2 = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: step1 as CasRef,
-      role: "writer",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000003" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: step2 });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Should only show prompt tags once
-    const promptCount = (markdown.match(/<prompt>/g) ?? []).length;
-    expect(promptCount).toBe(1);
-  });
-
-  test("scenario 4: step with no detail shows no output tags", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        worker: {
-          description: "Worker",
-          goal: "You are a worker agent.",
-          capabilities: [],
-          procedure: "Do work.",
-          output: "Summarize work.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Do stuff",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "worker",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000004" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Should not have output tags
-    expect(markdown).not.toContain("<output>");
-    expect(markdown).not.toContain("</output>");
-
-    // Step header should still be displayed
-    expect(markdown).toContain("## Step 1: worker");
-
-    // Prompt should still be shown
-    expect(markdown).toContain("<prompt>");
-  });
-
-  test("scenario 5: empty content shows no output tags", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Do stuff",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    // A detail ref that doesn't exist → extractLastAssistantContent returns null
-    const missingDetailRef = "missingdetail0" as CasRef;
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "worker",
-      output: outputHash,
-      detail: missingDetailRef,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000005" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Should not have output tags
-    expect(markdown).not.toContain("<output>");
-    expect(markdown).not.toContain("</output>");
-  });
-
-  test("scenario 6: thread read with --start flag shows task section", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        roleA: {
-          description: "Role A",
-          goal: "Goal for roleA",
-          capabilities: [],
-          procedure: "Do stuff.",
-          output: "Output.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Initial prompt",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "roleA",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000006" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, true);
-
-    // Should include task section
-    expect(markdown).toContain("# Thread");
-    expect(markdown).toContain("## Task");
-    expect(markdown).toContain("Initial prompt");
-
-    // Prompts should use XML tags
-    expect(markdown).toContain("<prompt>");
-  });
-
-  test("scenario 7: thread read with --before parameter", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        roleA: {
-          description: "Role A",
-          goal: "Goal for roleA",
-          capabilities: [],
-          procedure: "Do stuff.",
-          output: "Output.",
-          meta: "placeholder00" as CasRef,
-        },
-        roleB: {
-          description: "Role B",
-          goal: "Goal for roleB",
-          capabilities: [],
-          procedure: "Do stuff.",
-          output: "Output.",
-          meta: "placeholder00" as CasRef,
-        },
-        roleC: {
-          description: "Role C",
-          goal: "Goal for roleC",
-          capabilities: [],
-          procedure: "Do stuff.",
-          output: "Output.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Initial prompt",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const step1 = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "roleA",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const step2 = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: step1 as CasRef,
-      role: "roleB",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const step3 = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: step2 as CasRef,
-      role: "roleC",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000007" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: step3 });
-
-    const markdown = await cmdThreadRead(
-      tmpDir,
-      threadId,
-      THREAD_READ_DEFAULT_QUOTA,
-      step2 as CasRef,
-      false,
-    );
-
-    // Should only show roleA
-    expect(markdown).toContain("roleA");
-    expect(markdown).not.toContain("roleB");
-    expect(markdown).not.toContain("roleC");
-
-    // Should use XML tags
-    expect(markdown).toContain("<prompt>");
-  });
-
-  test("scenario 9: special characters in content are preserved", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const detailSchemas = await registerDetailSchemas(uwf.store);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        writer: {
-          description: "Writer",
-          goal: "You are a writer.",
-          capabilities: [],
-          procedure: "Write content.",
-          output: "Summarize.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Write something",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const turnHash = await uwf.store.put(detailSchemas.turn, {
-      index: 0,
-      role: "assistant",
-      content: "Content with <special> & characters > like <this>",
-      toolCalls: null,
-      reasoning: null,
-    });
-    const detailHash = await uwf.store.put(detailSchemas.detail, {
-      sessionId: "sx",
-      model: "mx",
-      duration: 500,
-      turnCount: 1,
-      turns: [turnHash],
-    });
-
-    const stepHash = await uwf.store.put(uwf.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "writer",
-      output: outputHash,
-      detail: detailHash,
-      agent: "uwf-test",
-    });
-
-    const threadId = "01JTEST0000000000000008" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHash });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-
-    // Special characters should be preserved as-is
-    expect(markdown).toContain("Content with <special> & characters > like <this>");
-  });
-
-  test("scenario 10: quota limit with XML tags", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "test-wf",
-      description: "desc",
-      roles: {
-        roleA: {
-          description: "Role A",
-          goal: "Goal for roleA",
-          capabilities: [],
-          procedure: "Do stuff.",
-          output: "Output.",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-
-    const startHash = await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Initial prompt",
-    });
-
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const steps: CasRef[] = [];
-    let prev: CasRef | null = null;
-    for (let i = 0; i < 5; i++) {
-      const step = (await uwf.store.put(uwf.schemas.stepNode, {
-        start: startHash,
-        prev,
-        role: "roleA",
-        output: outputHash,
-        detail: null,
-        agent: "uwf-test",
-      })) as CasRef;
-      steps.push(step);
-      prev = step;
-    }
-
-    const threadId = "01JTEST0000000000000009" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: steps[steps.length - 1]! });
-
-    // Use very small quota
-    const markdown = await cmdThreadRead(tmpDir, threadId, 1, null, false);
-
-    // Should have skip hint
-    expect(markdown).toContain("earlier step");
-
-    // Should have XML tags for displayed steps
-    if (markdown.includes("<prompt>")) {
-      expect(markdown).toContain("</prompt>");
-    }
-  });
-});

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

@@ -198,10 +198,10 @@ describe("extractLastAssistantContent", () => {
   });
 });
 
-// ── cmdThreadRead: <output> section ──────────────────────────────────────────
+// ── cmdThreadRead: ### Content section ───────────────────────────────────────
 
-describe("cmdThreadRead <output> section", () => {
-  test("includes <output> tags when detail has assistant turns", async () => {
+describe("cmdThreadRead ### Content section", () => {
+  test("includes ### Content before ### Output when detail has assistant turns", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const detailSchemas = await registerDetailSchemas(uwf.store);
 
@@ -264,13 +264,12 @@ describe("cmdThreadRead <output> section", () => {
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
 
-    expect(markdown).toContain("<output>");
-    expect(markdown).toContain("</output>");
+    expect(markdown).toContain("### Content");
     expect(markdown).toContain("The assistant response text");
-    expect(markdown).not.toContain("### Content");
+    expect(markdown).not.toContain("### Output");
   });
 
-  test("omits <output> tags when detail has no matching assistant turns", async () => {
+  test("omits ### Content when detail has no matching assistant turns", async () => {
     const uwf = await makeUwfStore(tmpDir);
 
     const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
@@ -309,9 +308,8 @@ describe("cmdThreadRead <output> section", () => {
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
 
-    expect(markdown).not.toContain("<output>");
-    expect(markdown).not.toContain("</output>");
     expect(markdown).not.toContain("### Content");
+    expect(markdown).not.toContain("### Output");
   });
 });
 
@@ -384,11 +382,15 @@ describe("cmdThreadStepDetails", () => {
       content: "done",
     });
   });
+
+  test("throws when step hash does not exist", async () => {
+    await expect(cmdThreadStepDetails(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
+  });
 });
 
-// ── cmdThreadRead: <prompt> deduplication ────────────────────────────────────
+// ── cmdThreadRead: ### Prompt deduplication ───────────────────────────────────
 
-describe("cmdThreadRead <prompt> deduplication", () => {
+describe("cmdThreadRead ### Prompt deduplication", () => {
   async function makeThreadWithRoles(uwf: UwfStore, roles: string[]): Promise<string> {
     const roleMap: Record<string, unknown> = {};
     for (const r of [...new Set(roles)]) {
@@ -436,214 +438,36 @@ describe("cmdThreadRead <prompt> deduplication", () => {
     return stepHash;
   }
 
-  test("same consecutive role shows <prompt> once", async () => {
+  test("same consecutive role shows ### Prompt once", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const headHash = await makeThreadWithRoles(uwf, ["writer", "writer"]);
     const threadId = "01JTEST0000000000000003" as ThreadId;
     await saveThreadsIndex(tmpDir, { [threadId]: headHash });
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-    const count = (markdown.match(/<prompt>/g) ?? []).length;
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
     expect(count).toBe(1);
   });
 
-  test("different consecutive roles each show <prompt>", async () => {
+  test("different consecutive roles each show ### Prompt", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const headHash = await makeThreadWithRoles(uwf, ["planner", "coder"]);
     const threadId = "01JTEST0000000000000004" as ThreadId;
     await saveThreadsIndex(tmpDir, { [threadId]: headHash });
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-    const count = (markdown.match(/<prompt>/g) ?? []).length;
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
     expect(count).toBe(2);
   });
 
-  test("non-consecutive same role shows <prompt> twice", async () => {
+  test("non-consecutive same role shows ### Prompt twice", async () => {
     const uwf = await makeUwfStore(tmpDir);
     const headHash = await makeThreadWithRoles(uwf, ["roleA", "roleB", "roleA"]);
     const threadId = "01JTEST0000000000000005" as ThreadId;
     await saveThreadsIndex(tmpDir, { [threadId]: headHash });
 
     const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-    const count = (markdown.match(/<prompt>/g) ?? []).length;
+    const count = (markdown.match(/### Prompt/g) ?? []).length;
     expect(count).toBe(2);
   });
 });
-
-// ── cmdThreadRead: showStart / before / quota ─────────────────────────────────
-
-describe("cmdThreadRead start section / before / quota", () => {
-  async function makeSimpleThread(
-    uwf: UwfStore,
-    roles: string[],
-  ): Promise<{ startHash: CasRef; stepHashes: CasRef[] }> {
-    const uniqueRoles = [...new Set(roles)];
-    const workflowHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "simple-wf",
-      description: "desc",
-      roles: Object.fromEntries(
-        uniqueRoles.map((r) => [
-          r,
-          {
-            description: r,
-            goal: `Goal for ${r}`,
-            capabilities: [],
-            procedure: "Do stuff.",
-            output: "Output.",
-            meta: "placeholder00" as CasRef,
-          },
-        ]),
-      ),
-      conditions: {},
-      graph: {},
-    });
-    const startHash = (await uwf.store.put(uwf.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "Initial prompt",
-    })) as CasRef;
-    const outputHash = await uwf.store.put(uwf.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-
-    const stepHashes: CasRef[] = [];
-    let prev: CasRef | null = null;
-    for (const role of roles) {
-      const stepHash = (await uwf.store.put(uwf.schemas.stepNode, {
-        start: startHash,
-        prev,
-        role,
-        output: outputHash,
-        detail: null,
-        agent: "uwf-test",
-      })) as CasRef;
-      stepHashes.push(stepHash);
-      prev = stepHash;
-    }
-    return { startHash, stepHashes };
-  }
-
-  test("showStart=true includes # Thread header and ## Task section", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
-    const threadId = "01JTEST0000000000000006" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, true);
-    expect(markdown).toContain("# Thread");
-    expect(markdown).toContain("## Task");
-    expect(markdown).toContain("Initial prompt");
-  });
-
-  test("showStart=false with before=null still shows # Thread header (default behavior)", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
-    const threadId = "01JTEST0000000000000007" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
-
-    // When before=null, the start section is always shown regardless of showStart
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-    expect(markdown).toContain("# Thread");
-    expect(markdown).toContain("## Task");
-  });
-
-  test("before filter: only steps before the given hash appear", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const { stepHashes } = await makeSimpleThread(uwf, ["roleA", "roleB", "roleC"]);
-    const [_hashA, hashB, hashC] = stepHashes as [CasRef, CasRef, CasRef];
-    const threadId = "01JTEST0000000000000008" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: hashC });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, hashB, false);
-    expect(markdown).toContain("roleA");
-    expect(markdown).not.toContain("roleB");
-    expect(markdown).not.toContain("roleC");
-  });
-
-  test("quota=1 limits output and includes skip hint", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const { stepHashes } = await makeSimpleThread(uwf, ["roleA", "roleB", "roleC"]);
-    const threadId = "01JTEST000000000000000A" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[stepHashes.length - 1]! });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, 1, null, false);
-    expect(markdown).toContain("earlier step");
-  });
-
-  test("all steps fit in quota: no skip hint", async () => {
-    const uwf = await makeUwfStore(tmpDir);
-    const { stepHashes } = await makeSimpleThread(uwf, ["roleA"]);
-    const threadId = "01JTEST000000000000000B" as ThreadId;
-    await saveThreadsIndex(tmpDir, { [threadId]: stepHashes[0]! });
-
-    const markdown = await cmdThreadRead(tmpDir, threadId, THREAD_READ_DEFAULT_QUOTA, null, false);
-    expect(markdown).not.toContain("earlier step");
-  });
-});
-
-// ── Tests that call process.exit must be last ─────────────────────────────────
-
-describe("cmdThreadStepDetails (process.exit tests - must be last)", () => {
-  test("throws when step hash does not exist", async () => {
-    await expect(cmdThreadStepDetails(tmpDir, "nonexistenth0" as CasRef)).rejects.toThrow();
-  });
-
-  test("before with unknown hash rejects", async () => {
-    const _uwf = await makeUwfStore(tmpDir);
-    const casDir = join(tmpDir, "cas");
-    await mkdir(casDir, { recursive: true });
-    const store = createFsStore(casDir);
-    const schemas = await registerUwfSchemas(store);
-    const uwfStore: UwfStore = { storageRoot: tmpDir, store, schemas };
-
-    const workflowHash = await uwfStore.store.put(uwfStore.schemas.workflow, {
-      name: "wf2",
-      description: "",
-      roles: {
-        roleA: {
-          description: "r",
-          goal: "g",
-          capabilities: [],
-          procedure: "p",
-          output: "o",
-          meta: "placeholder00" as CasRef,
-        },
-      },
-      conditions: {},
-      graph: {},
-    });
-    const startHash = await uwfStore.store.put(uwfStore.schemas.startNode, {
-      workflow: workflowHash,
-      prompt: "p",
-    });
-    const outputHash = await uwfStore.store.put(uwfStore.schemas.workflow, {
-      name: "out",
-      description: "",
-      roles: {},
-      conditions: {},
-      graph: {},
-    });
-    const stepHash = await uwfStore.store.put(uwfStore.schemas.stepNode, {
-      start: startHash,
-      prev: null,
-      role: "roleA",
-      output: outputHash,
-      detail: null,
-      agent: "uwf-test",
-    });
-    await saveThreadsIndex(tmpDir, { ["01JTEST000000000000000C" as ThreadId]: stepHash as CasRef });
-
-    await expect(
-      cmdThreadRead(
-        tmpDir,
-        "01JTEST000000000000000C" as ThreadId,
-        THREAD_READ_DEFAULT_QUOTA,
-        "unknownhash0" as CasRef,
-        false,
-      ),
-    ).rejects.toThrow();
-  });
-});

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

@@ -1,147 +0,0 @@
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import type { RunningThreadItem, ThreadId } from "@uncaged/workflow-protocol";
-
-import type { RunningMarker } from "./types.js";
-
-/**
- * Get the path to the running markers directory.
- */
-export function getRunningDir(storageRoot: string): string {
-  return join(storageRoot, "running");
-}
-
-/**
- * Get the path to a specific thread's marker file.
- */
-export function getMarkerPath(storageRoot: string, threadId: ThreadId): string {
-  return join(getRunningDir(storageRoot), `${threadId}.json`);
-}
-
-/**
- * Check if a PID is still running.
- * Returns true if the process exists, false otherwise.
- */
-export function isPidAlive(pid: number): boolean {
-  try {
-    // process.kill with signal 0 checks existence without killing
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    // ESRCH means process doesn't exist
-    return false;
-  }
-}
-
-/**
- * Create a marker file for a running thread.
- * Writes to a temp file in the same directory, then atomically renames.
- */
-export async function createMarker(storageRoot: string, marker: RunningMarker): Promise<void> {
-  const runningDir = getRunningDir(storageRoot);
-  await mkdir(runningDir, { recursive: true });
-
-  const markerPath = getMarkerPath(storageRoot, marker.thread);
-  const tempPath = join(runningDir, `.${marker.thread}-${process.pid}.tmp`);
-
-  const content = JSON.stringify(marker, null, 2);
-  await writeFile(tempPath, content, "utf8");
-  await rename(tempPath, markerPath);
-}
-
-/**
- * Delete a marker file for a thread.
- */
-export async function deleteMarker(storageRoot: string, threadId: ThreadId): Promise<void> {
-  const markerPath = getMarkerPath(storageRoot, threadId);
-  try {
-    await rm(markerPath);
-  } catch {
-    // Ignore errors if file doesn't exist
-  }
-}
-
-/**
- * Read a marker file. Returns null if file doesn't exist or is invalid.
- */
-export async function readMarker(
-  storageRoot: string,
-  threadId: ThreadId,
-): Promise<RunningMarker | null> {
-  const markerPath = getMarkerPath(storageRoot, threadId);
-  try {
-    const content = await readFile(markerPath, "utf8");
-    const marker = JSON.parse(content) as RunningMarker;
-    return marker;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * List all running threads, filtering out stale markers.
- */
-export async function listRunningThreads(storageRoot: string): Promise<RunningThreadItem[]> {
-  const runningDir = getRunningDir(storageRoot);
-
-  let files: string[];
-  try {
-    files = await readdir(runningDir);
-  } catch {
-    // Directory doesn't exist or can't be read
-    return [];
-  }
-
-  const results: RunningThreadItem[] = [];
-
-  for (const filename of files) {
-    if (!filename.endsWith(".json")) {
-      continue;
-    }
-
-    const threadId = filename.slice(0, -5) as ThreadId;
-    const marker = await readMarker(storageRoot, threadId);
-
-    if (marker === null) {
-      // Invalid marker file
-      continue;
-    }
-
-    if (!isPidAlive(marker.pid)) {
-      // Stale marker - process no longer exists
-      await deleteMarker(storageRoot, threadId);
-      continue;
-    }
-
-    results.push({
-      thread: marker.thread,
-      workflow: marker.workflow,
-      pid: marker.pid,
-      startedAt: marker.startedAt,
-    });
-  }
-
-  return results;
-}
-
-/**
- * Check if a thread is currently executing in the background.
- * Returns the marker if running, null otherwise.
- */
-export async function isThreadRunning(
-  storageRoot: string,
-  threadId: ThreadId,
-): Promise<RunningMarker | null> {
-  const marker = await readMarker(storageRoot, threadId);
-  if (marker === null) {
-    return null;
-  }
-
-  if (!isPidAlive(marker.pid)) {
-    // Stale marker
-    await deleteMarker(storageRoot, threadId);
-    return null;
-  }
-
-  return marker;
-}

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

@@ -1,11 +0,0 @@
-export {
-  createMarker,
-  deleteMarker,
-  getMarkerPath,
-  getRunningDir,
-  isPidAlive,
-  isThreadRunning,
-  listRunningThreads,
-  readMarker,
-} from "./background.js";
-export type { RunningMarker } from "./types.js";

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

@@ -1,9 +0,0 @@
-import type { CasRef, ThreadId } from "@uncaged/workflow-protocol";
-
-/** Marker file stored at ~/.uncaged/workflow/running/<thread-id>.json */
-export type RunningMarker = {
-  thread: ThreadId;
-  workflow: CasRef;
-  pid: number;
-  startedAt: number;
-};

packages/cli-workflow/src/cli.ts

@@ -22,7 +22,6 @@ import {
   cmdThreadKill,
   cmdThreadList,
   cmdThreadRead,
-  cmdThreadRunning,
   cmdThreadShow,
   cmdThreadStart,
   cmdThreadStep,
@@ -115,41 +114,19 @@ thread
   .argument("<thread-id>", "Thread ULID")
   .option("--agent <cmd>", "Override agent command")
   .option("-c, --count <number>", "Number of steps to run (default: 1)")
-  .option("--background", "Run in background and return immediately")
-  .option("--_background-worker", "Internal flag for background worker process", false)
-  .action(
-    (
-      threadId: string,
-      opts: {
-        agent: string | undefined;
-        count: string | undefined;
-        background: boolean;
-        _backgroundWorker: boolean;
-      },
-    ) => {
-      const storageRoot = resolveStorageRoot();
-      runAction(async () => {
-        const agentOverride = opts.agent ?? null;
-        const count = opts.count !== undefined ? Number(opts.count) : 1;
-        const background = opts.background ?? false;
-        const backgroundWorker = opts._backgroundWorker ?? false;
-
-        const results = await cmdThreadStep(
-          storageRoot,
-          threadId,
-          agentOverride,
-          count,
-          background,
-          backgroundWorker,
-        );
-        if (results.length === 1) {
-          writeOutput(results[0]);
-        } else {
-          writeOutput(results);
-        }
-      });
-    },
-  );
+  .action((threadId: string, opts: { agent: string | undefined; count: string | undefined }) => {
+    const storageRoot = resolveStorageRoot();
+    runAction(async () => {
+      const agentOverride = opts.agent ?? null;
+      const count = opts.count !== undefined ? Number(opts.count) : 1;
+      const results = await cmdThreadStep(storageRoot, threadId, agentOverride, count);
+      if (results.length === 1) {
+        writeOutput(results[0]);
+      } else {
+        writeOutput(results);
+      }
+    });
+  });
 
 thread
   .command("show")
@@ -175,17 +152,6 @@ thread
     });
   });
 
-thread
-  .command("running")
-  .description("List threads currently executing in the background")
-  .action(() => {
-    const storageRoot = resolveStorageRoot();
-    runAction(async () => {
-      const result = await cmdThreadRunning(storageRoot);
-      writeOutput(result);
-    });
-  });
-
 thread
   .command("kill")
   .description("Terminate and archive a thread")

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

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
@@ -137,182 +137,75 @@ function apiKeyEnvName(providerName: string): string {
   return `${providerName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
 }
 
-// ──────────────────────────────────────────────────────────────────────────────
-// Extracted helpers — _discoverAgents
-// ──────────────────────────────────────────────────────────────────────────────
-
-/**
- * Scans directories from a PATH string for uwf-* executables.
- */
-export async function _searchPathDirs(pathEnv: string): Promise<string[]> {
-  if (!pathEnv) return [];
-  const dirs = pathEnv.split(":").filter((d) => d.length > 0);
-  const agents = new Set<string>();
-  for (const dir of dirs) {
-    _scanDirForAgents(dir, agents);
-  }
-  return Array.from(agents).sort();
-}
-
-function _scanDirForAgents(dir: string, agents: Set<string>): void {
-  try {
-    if (!existsSync(dir)) return;
-    const entries = readdirSync(dir);
-    for (const entry of entries) {
-      if (!entry.startsWith("uwf-") || entry === "uwf") continue;
-      if (_isExecutableFile(join(dir, entry))) {
-        agents.add(entry);
-      }
-    }
-  } catch {
-    // Skip inaccessible directories
-  }
-}
-
-function _isExecutableFile(fullPath: string): boolean {
-  try {
-    const s = statSync(fullPath);
-    return s.isFile() && (s.mode & 0o111) !== 0;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Parses the stdout of `which -a` into sorted unique basenames.
- */
-export function _parseWhichOutput(text: string): string[] {
-  if (!text) return [];
-  const agents = new Set<string>();
-  for (const line of text.trim().split("\n")) {
-    if (!line) continue;
-    const basename = line.split("/").pop() ?? "";
-    if (basename.startsWith("uwf-") && basename !== "uwf") {
-      agents.add(basename);
-    }
-  }
-  return Array.from(agents).sort();
-}
-
 /**
  * Discover uwf-* agent binaries in PATH.
  * Returns sorted list of binary names (e.g., ["uwf-hermes", "uwf-claude-code"]).
  */
-export async function _discoverAgents(): Promise<string[]> {
-  try {
-    const agents = await _tryWhichDiscovery();
-    if (agents !== null) return agents;
-    return await _searchPathDirs(process.env.PATH ?? "");
-  } catch {
-    return [];
-  }
-}
-
-async function _tryWhichDiscovery(): Promise<string[] | null> {
+async function _discoverAgents(): Promise<string[]> {
   try {
+    // Use which -a to find all uwf-* binaries in PATH
     const proc = Bun.spawn(["which", "-a", "uwf-hermes", "uwf-claude-code", "uwf-cursor"], {
       stdout: "pipe",
       stderr: "pipe",
     });
+
     const text = await new Response(proc.stdout).text();
     await proc.exited;
-    if (proc.exitCode !== 0) return null;
-    return _parseWhichOutput(text);
-  } catch {
-    return null;
-  }
-}
 
-// ──────────────────────────────────────────────────────────────────────────────
-// Extracted helpers — onData closure (promptSecret)
-// ──────────────────────────────────────────────────────────────────────────────
+    if (proc.exitCode !== 0) {
+      // Try alternative approach: search PATH directories manually
+      const pathEnv = process.env.PATH || "";
+      const pathDirs = pathEnv.split(":").filter((d) => d.length > 0);
+      const agents = new Set<string>();
 
-/** Returns true for newline, carriage return, or EOF (EOT). */
-export function _isTerminator(c: string): boolean {
-  return c === "\n" || c === "\r" || c === "";
-}
+      for (const dir of pathDirs) {
+        try {
+          if (!existsSync(dir)) continue;
+          const { readdirSync, statSync } = await import("node:fs");
+          const entries = readdirSync(dir);
 
-/** Returns true for DEL or backspace. */
-export function _isBackspace(c: string): boolean {
-  return c === "" || c === "\b";
-}
+          for (const entry of entries) {
+            if (!entry.startsWith("uwf-") || entry === "uwf") continue;
+            const fullPath = join(dir, entry);
+            try {
+              const stat = statSync(fullPath);
+              // Check if executable (owner, group, or other has execute bit)
+              if (stat.isFile() && (stat.mode & 0o111) !== 0) {
+                agents.add(entry);
+              }
+            } catch {
+              // Skip if can't stat
+            }
+          }
+        } catch {
+          // Skip inaccessible directories
+        }
+      }
 
-// ──────────────────────────────────────────────────────────────────────────────
-// Extracted helpers — cmdSetupInteractive
-// ──────────────────────────────────────────────────────────────────────────────
-
-type ProviderEntry = { name: string; label: string; baseUrl: string };
-
-/** Prints the numbered provider list and custom option to stdout. */
-export function _printProviderMenu(providers: readonly ProviderEntry[]): void {
-  const numWidth = String(providers.length + 1).length;
-  for (let i = 0; i < providers.length; i++) {
-    const p = providers[i];
-    if (!p) continue;
-    const num = String(i + 1).padStart(numWidth);
-    console.log(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
-  }
-  const customNum = String(providers.length + 1).padStart(numWidth);
-  console.log(`  ${customNum}) Custom (enter name and URL manually)\n`);
-}
-
-/** Resolves a numeric choice string to a preset provider, or null for custom/invalid. */
-export function _resolveProviderChoice(
-  choice: string,
-  providers: readonly ProviderEntry[],
-): { providerName: string; baseUrl: string } | null {
-  const n = Number.parseInt(choice, 10);
-  if (Number.isNaN(n) || n < 1 || n > providers.length) return null;
-  const p = providers[n - 1];
-  if (!p) return null;
-  return { providerName: p.name, baseUrl: p.baseUrl };
-}
-
-/** Resolves numeric index or literal model name to a model string. */
-export function _resolveModelChoice(input: string, models: string[]): string {
-  const n = Number.parseInt(input, 10);
-  if (!Number.isNaN(n) && n >= 1 && n <= models.length) {
-    return models[n - 1] ?? input;
-  }
-  return input;
-}
-
-/** Prints the multi-column model list to stdout. */
-export function _printModelMenu(models: string[], termCols: number): void {
-  const nw = String(models.length).length;
-  const maxLen = models.reduce((m, s) => Math.max(m, s.length), 0);
-  const colWidth = nw + 2 + maxLen + 4;
-  const cols = Math.max(1, Math.floor(termCols / colWidth));
-  const rows = Math.ceil(models.length / cols);
-  for (let r = 0; r < rows; r++) {
-    let line = "";
-    for (let c = 0; c < cols; c++) {
-      const idx = c * rows + r;
-      if (idx >= models.length) break;
-      const num = String(idx + 1).padStart(nw);
-      const name = (models[idx] ?? "").padEnd(maxLen);
-      line += `  ${num}) ${name}  `;
+      return Array.from(agents).sort();
     }
-    console.log(line.trimEnd());
+
+    // Parse which output - each line is a path to a binary
+    const paths = text
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0);
+    const agents = new Set<string>();
+
+    for (const path of paths) {
+      const basename = path.split("/").pop();
+      if (basename?.startsWith("uwf-") && basename !== "uwf") {
+        agents.add(basename);
+      }
+    }
+
+    return Array.from(agents).sort();
+  } catch {
+    // If all fails, return empty array
+    return [];
   }
 }
 
-type ValidationResult = { ok: boolean; error: string | null };
-
-/** Prints the model validation result to stdout. */
-export function _printValidationResult(validation: ValidationResult): void {
-  if (validation.ok) {
-    console.log("✓ Model verified — connection successful.\n");
-  } else {
-    console.log(`\n⚠ Warning: Could not reach model — ${validation.error}`);
-    console.log(
-      "  Config saved, but you may want to try a different model or check your API key.\n",
-    );
-  }
-}
-
-// ──────────────────────────────────────────────────────────────────────────────
-
 /**
  * Merge setup args into config.yaml structure. Non-destructive — preserves existing entries.
  */
@@ -388,46 +281,6 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
   };
 }
 
-type SecretState = {
-  buf: string;
-  rawWasSet: boolean;
-  resolve: (value: string) => void;
-  onData: (chunk: string) => void;
-};
-
-function _handleSecretTerminator(state: SecretState): void {
-  if (process.stdin.isTTY) process.stdin.setRawMode(state.rawWasSet);
-  process.stdin.pause();
-  process.stdin.removeListener("data", state.onData);
-  process.stdout.write("\n");
-  state.resolve(state.buf.trim());
-}
-
-function _handleSecretBackspace(state: SecretState): void {
-  if (state.buf.length > 0) {
-    state.buf = state.buf.slice(0, -1);
-    process.stdout.write("\b \b");
-  }
-}
-
-function _handleSecretChar(c: string, state: SecretState): boolean {
-  if (_isTerminator(c)) {
-    _handleSecretTerminator(state);
-    return true;
-  }
-  if (_isBackspace(c)) {
-    _handleSecretBackspace(state);
-    return false;
-  }
-  if (c === "") {
-    if (process.stdin.isTTY) process.stdin.setRawMode(state.rawWasSet);
-    process.exit(130);
-  }
-  state.buf += c;
-  process.stdout.write("*");
-  return false;
-}
-
 /** Read a line with terminal echo disabled (for secrets). */
 async function promptSecret(label: string): Promise<string> {
   process.stdout.write(label);
@@ -439,13 +292,33 @@ async function promptSecret(label: string): Promise<string> {
     process.stdin.resume();
     process.stdin.setEncoding("utf8");
 
-    const state: SecretState = { buf: "", rawWasSet, resolve, onData: () => {} };
-    state.onData = (chunk: string) => {
+    let buf = "";
+    const onData = (chunk: string) => {
       for (const c of chunk.toString()) {
-        if (_handleSecretChar(c, state)) return;
+        if (c === "\n" || c === "\r" || c === "\u0004") {
+          if (process.stdin.isTTY) process.stdin.setRawMode(rawWasSet);
+          process.stdin.pause();
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          resolve(buf.trim());
+          return;
+        }
+        if (c === "\u007F" || c === "\b") {
+          if (buf.length > 0) {
+            buf = buf.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (c === "\u0003") {
+          if (process.stdin.isTTY) process.stdin.setRawMode(rawWasSet);
+          process.exit(130);
+        }
+        buf += c;
+        process.stdout.write("*");
       }
     };
-    process.stdin.on("data", state.onData);
+    process.stdin.on("data", onData);
   });
 }
 
@@ -471,56 +344,6 @@ async function fetchModels(baseUrl: string, apiKey: string): Promise<string[]> {
   }
 }
 
-async function _promptProviderSelection(
-  rl: ReturnType<typeof createInterface>,
-): Promise<{ providerName: string; baseUrl: string }> {
-  console.log("Select a provider:\n");
-  _printProviderMenu(PRESET_PROVIDERS);
-
-  const choice = (await rl.question(`Choose [1-${PRESET_PROVIDERS.length + 1}]: `)).trim();
-  const choiceNum = Number.parseInt(choice, 10);
-  if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > PRESET_PROVIDERS.length + 1) {
-    throw new Error(`Invalid choice: ${choice}`);
-  }
-
-  const preset = _resolveProviderChoice(choice, PRESET_PROVIDERS);
-  if (preset) {
-    const selected = PRESET_PROVIDERS[choiceNum - 1];
-    if (selected) {
-      console.log(`\n  → ${selected.label} (${selected.baseUrl})\n`);
-    }
-    return preset;
-  }
-
-  const providerName = (await rl.question("Provider name (e.g. my-proxy): ")).trim();
-  if (!providerName) throw new Error("Provider name required");
-  const baseUrl = (await rl.question("OpenAI-compatible API base URL: ")).trim();
-  if (!baseUrl) throw new Error("Base URL required");
-  return { providerName, baseUrl };
-}
-
-async function _promptModelSelection(
-  rl: ReturnType<typeof createInterface>,
-  baseUrl: string,
-  apiKey: string,
-): Promise<string> {
-  console.log("\nFetching available models...");
-  const models = await fetchModels(baseUrl, apiKey);
-
-  if (models.length === 0) {
-    console.log("Could not fetch models. Enter model name manually.");
-    const model = (await rl.question("Default model (e.g. qwen-plus, gpt-4o): ")).trim();
-    if (!model) throw new Error("Model required");
-    return model;
-  }
-  console.log(`\nAvailable models (${models.length}):\n`);
-  _printModelMenu(models, process.stdout.columns || 100);
-  console.log(`\nChoose a number, or type a model name directly.`);
-  const modelInput = (await rl.question(`Default model [1-${models.length}]: `)).trim();
-  if (!modelInput) throw new Error("Model required");
-  return _resolveModelChoice(modelInput, models);
-}
-
 /**
  * Interactive setup — prompts user for provider, API key, model.
  */
@@ -530,7 +353,39 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
   try {
     console.log("Configure LLM provider for uwf workflow agents.\n");
 
-    const { providerName, baseUrl } = await _promptProviderSelection(rl);
+    // 1. Provider selection
+    const numWidth = String(PRESET_PROVIDERS.length + 1).length;
+    console.log("Select a provider:\n");
+    for (let i = 0; i < PRESET_PROVIDERS.length; i++) {
+      const p = PRESET_PROVIDERS[i];
+      if (!p) continue;
+      const num = String(i + 1).padStart(numWidth);
+      console.log(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
+    }
+    const customNum = String(PRESET_PROVIDERS.length + 1).padStart(numWidth);
+    console.log(`  ${customNum}) Custom (enter name and URL manually)\n`);
+
+    const choice = (await rl.question(`Choose [1-${PRESET_PROVIDERS.length + 1}]: `)).trim();
+    const choiceNum = Number.parseInt(choice, 10);
+    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > PRESET_PROVIDERS.length + 1) {
+      throw new Error(`Invalid choice: ${choice}`);
+    }
+
+    let providerName: string;
+    let baseUrl: string;
+
+    if (choiceNum <= PRESET_PROVIDERS.length) {
+      const selected = PRESET_PROVIDERS[choiceNum - 1];
+      if (!selected) throw new Error("Invalid selection");
+      providerName = selected.name;
+      baseUrl = selected.baseUrl;
+      console.log(`\n  → ${selected.label} (${selected.baseUrl})\n`);
+    } else {
+      providerName = (await rl.question("Provider name (e.g. my-proxy): ")).trim();
+      if (!providerName) throw new Error("Provider name required");
+      baseUrl = (await rl.question("OpenAI-compatible API base URL: ")).trim();
+      if (!baseUrl) throw new Error("Base URL required");
+    }
 
     // 2. API key
     rl.close();
@@ -539,8 +394,47 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
 
     // 3. Model selection
     const rl2 = createInterface({ input, output });
-    const model = await _promptModelSelection(rl2, baseUrl, apiKey);
+    console.log("\nFetching available models...");
+    const models = await fetchModels(baseUrl, apiKey);
+
+    let model: string;
+    if (models.length > 0) {
+      console.log(`\nAvailable models (${models.length}):\n`);
+      const nw = String(models.length).length;
+      // Multi-column layout
+      const maxLen = models.reduce((m, s) => Math.max(m, s.length), 0);
+      const colWidth = nw + 2 + maxLen + 4; // "  N) name    "
+      const termCols = process.stdout.columns || 100;
+      const cols = Math.max(1, Math.floor(termCols / colWidth));
+      const rows = Math.ceil(models.length / cols);
+      for (let r = 0; r < rows; r++) {
+        let line = "";
+        for (let c = 0; c < cols; c++) {
+          const idx = c * rows + r;
+          if (idx >= models.length) break;
+          const num = String(idx + 1).padStart(nw);
+          const name = (models[idx] ?? "").padEnd(maxLen);
+          line += `  ${num}) ${name}  `;
+        }
+        console.log(line.trimEnd());
+      }
+      console.log(`\nChoose a number, or type a model name directly.`);
+      const modelInput = (await rl2.question(`Default model [1-${models.length}]: `)).trim();
+      if (!modelInput) throw new Error("Model required");
+      const modelNum = Number.parseInt(modelInput, 10);
+      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+        model = models[modelNum - 1] ?? modelInput;
+      } else {
+        model = modelInput;
+      }
+    } else {
+      console.log("Could not fetch models. Enter model name manually.");
+      model = (await rl2.question("Default model (e.g. qwen-plus, gpt-4o): ")).trim();
+      if (!model) throw new Error("Model required");
+    }
+
     rl2.close();
+
     console.log(`  → ${providerName}/${model}\n`);
 
     const setupResult = await cmdSetup({
@@ -553,8 +447,17 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
 
     // Show validation result
     if (setupResult.validation && typeof setupResult.validation === "object") {
-      _printValidationResult(setupResult.validation as ValidationResult);
+      const v = setupResult.validation as { ok: boolean; error?: string };
+      if (v.ok) {
+        console.log("✓ Model verified — connection successful.\n");
+      } else {
+        console.log(`\n⚠ Warning: Could not reach model — ${v.error}`);
+        console.log(
+          "  Config saved, but you may want to try a different model or check your API key.\n",
+        );
+      }
     }
+
     console.log("Setup complete! Get started:\n");
     console.log("  uwf workflow put <workflow.yaml>   Register a workflow");
     console.log('  uwf thread start <name> -p "..."   Start a thread');

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

@@ -1,4 +1,4 @@
-import { execFileSync, spawn } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { access, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
@@ -10,7 +10,6 @@ import type {
   AgentConfig,
   CasRef,
   ModeratorContext,
-  RunningThreadsOutput,
   StartEntry,
   StartNodePayload,
   StartOutput,
@@ -28,12 +27,7 @@ import type {
 import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
 import { parse, stringify } from "yaml";
-import {
-  createMarker,
-  deleteMarker,
-  isThreadRunning,
-  listRunningThreads,
-} from "../background/index.js";
+
 import {
   appendThreadHistory,
   createUwfStore,
@@ -58,7 +52,6 @@ const PL_AGENT_SPAWN = "R5J2W8N4";
 const PL_AGENT_DONE = "C6P9E3H7";
 const PL_THREAD_ARCHIVED = "F4D8Q2K5";
 const PL_STEP_ERROR = "B8T5N1V6";
-const PL_BACKGROUND_START = "X7Q4W9M2";
 
 function failStep(plog: ProcessLogger, message: string): never {
   plog.log(PL_STEP_ERROR, message, null);
@@ -328,7 +321,6 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
       thread: threadId,
       head: activeHead,
       done: false,
-      background: null,
     };
   }
 
@@ -339,7 +331,6 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
       thread: threadId,
       head: hist.head,
       done: true,
-      background: null,
     };
   }
 
@@ -471,68 +462,49 @@ function expandDeep(store: CasStore, hash: CasRef, visited?: Set<string>): unkno
   return expandValue(store, schema, node.payload, seen);
 }
 
-function expandCasRefField(store: CasStore, value: unknown, visited: Set<string>): unknown {
-  if (typeof value === "string") {
-    return expandDeep(store, value as CasRef, visited);
-  }
-  return value;
-}
-
-function expandAnyOfField(
-  store: CasStore,
-  schema: JSONSchema,
-  value: unknown,
-  visited: Set<string>,
-): unknown {
-  if (!Array.isArray(schema.anyOf)) return value;
-  for (const sub of schema.anyOf as JSONSchema[]) {
-    if (sub.format === "cas_ref" && typeof value === "string") {
-      return expandDeep(store, value as CasRef, visited);
-    }
-  }
-  return value;
-}
-
-function expandArrayField(
-  store: CasStore,
-  schema: JSONSchema,
-  value: unknown,
-  visited: Set<string>,
-): unknown {
-  if (!schema.items || !Array.isArray(value)) return value;
-  const itemSchema = schema.items as JSONSchema;
-  return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
-}
-
-function expandObjectField(
-  store: CasStore,
-  schema: JSONSchema,
-  value: unknown,
-  visited: Set<string>,
-): unknown {
-  if (value === null || typeof value !== "object" || Array.isArray(value) || !schema.properties) {
-    return value;
-  }
-  const props = schema.properties as Record<string, JSONSchema>;
-  const obj = value as Record<string, unknown>;
-  const result: Record<string, unknown> = {};
-  for (const [key, val] of Object.entries(obj)) {
-    const propSchema = props[key];
-    result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
-  }
-  return result;
-}
-
 function expandValue(
   store: CasStore,
   schema: JSONSchema,
   value: unknown,
   visited: Set<string>,
 ): unknown {
-  if (schema.format === "cas_ref") return expandCasRefField(store, value, visited);
-  if (Array.isArray(schema.anyOf)) return expandAnyOfField(store, schema, value, visited);
-  if (schema.type === "array") return expandArrayField(store, schema, value, visited);
-  return expandObjectField(store, schema, value, visited);
+  // If this field is a cas_ref, expand it
+  if (schema.format === "cas_ref") {
+    if (typeof value === "string") {
+      return expandDeep(store, value as CasRef, visited);
+    }
+    return value;
+  }
+
+  // anyOf (nullable refs)
+  if (Array.isArray(schema.anyOf)) {
+    for (const sub of schema.anyOf as JSONSchema[]) {
+      if (sub.format === "cas_ref" && typeof value === "string") {
+        return expandDeep(store, value as CasRef, visited);
+      }
+    }
+    return value;
+  }
+
+  // Array of cas_ref items
+  if (schema.type === "array" && schema.items && Array.isArray(value)) {
+    const itemSchema = schema.items as JSONSchema;
+    return (value as unknown[]).map((item) => expandValue(store, itemSchema, item, visited));
+  }
+
+  // Object with properties
+  if (value !== null && typeof value === "object" && !Array.isArray(value) && schema.properties) {
+    const props = schema.properties as Record<string, JSONSchema>;
+    const obj = value as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(obj)) {
+      const propSchema = props[key];
+      result[key] = propSchema ? expandValue(store, propSchema, val, visited) : val;
+    }
+    return result;
+  }
+
+  return value;
 }
 
 function collectOrderedSteps(
@@ -616,85 +588,6 @@ export function extractLastAssistantContent(uwf: UwfStore, detailRef: CasRef): s
   return null;
 }
 
-function sliceBeforeHash(
-  candidates: OrderedStepItem[],
-  before: CasRef,
-  threadId: ThreadId,
-): OrderedStepItem[] {
-  const idx = candidates.findIndex((s) => s.hash === before);
-  if (idx === -1) {
-    fail(`step ${before} not found in thread ${threadId}`);
-  }
-  return candidates.slice(0, idx);
-}
-
-function selectByQuota(
-  candidates: OrderedStepItem[],
-  uwf: UwfStore,
-  quota: number,
-): { selected: OrderedStepItem[]; skippedCount: number } {
-  const selected: OrderedStepItem[] = [];
-  let totalChars = 0;
-  for (let i = candidates.length - 1; i >= 0; i--) {
-    const item = candidates[i];
-    if (item === undefined) continue;
-    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
-    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
-    selected.unshift(item);
-    totalChars += blockLen;
-    if (totalChars > quota) break;
-  }
-  return { selected, skippedCount: candidates.length - selected.length };
-}
-
-function formatStepHeader(stepNum: number, item: OrderedStepItem): string {
-  const ts = new Date(item.timestamp)
-    .toISOString()
-    .replace("T", " ")
-    .replace(/\.\d+Z$/, "");
-  return [
-    `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
-    `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
-  ].join("\n");
-}
-
-function formatStepPrompt(
-  roleDef: WorkflowPayload["roles"][string] | undefined,
-  role: string,
-  shownPromptRoles: Set<string>,
-): string {
-  if (!roleDef || shownPromptRoles.has(role)) return "";
-  shownPromptRoles.add(role);
-  return ["", "", "<prompt>", roleDef.goal, "</prompt>"].join("\n");
-}
-
-function formatStepContent(uwf: UwfStore, item: OrderedStepItem): string {
-  if (!item.payload.detail) return "";
-  const content = extractLastAssistantContent(uwf, item.payload.detail);
-  if (content === null) return "";
-  return ["", "", "<output>", content, "</output>"].join("\n");
-}
-
-function formatStartSection(options: {
-  threadId: ThreadId;
-  workflowName: string;
-  workflowHash: CasRef;
-  prompt: string;
-  before: CasRef | null;
-  showStart: boolean;
-}): string {
-  if (options.before !== null && !options.showStart) return "";
-  return [
-    `# Thread \`${options.threadId}\``,
-    "",
-    `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
-    "",
-    "## Task",
-    "",
-    options.prompt,
-  ].join("\n");
-}
-
 function formatThreadReadMarkdown(options: {
   threadId: ThreadId;
   workflowName: string;
@@ -707,16 +600,50 @@ function formatThreadReadMarkdown(options: {
   before: CasRef | null;
   showStart: boolean;
 }): string {
-  const { ordered, uwf, workflow, quota, before } = options;
+  const { ordered, uwf, workflow, quota, before, showStart } = options;
 
-  const candidates = before !== null ? sliceBeforeHash(ordered, before, options.threadId) : ordered;
-  const { selected, skippedCount } = selectByQuota(candidates, uwf, quota);
+  // Determine which steps to consider
+  let candidates = ordered;
+  if (before !== null) {
+    const idx = candidates.findIndex((s) => s.hash === before);
+    if (idx === -1) {
+      fail(`step ${before} not found in thread ${options.threadId}`);
+    }
+    candidates = candidates.slice(0, idx);
+  }
 
+  // Walk backward from newest, accumulating chars until quota exceeded
+  const selected: OrderedStepItem[] = [];
+  let totalChars = 0;
+  for (let i = candidates.length - 1; i >= 0; i--) {
+    const item = candidates[i];
+    if (item === undefined) continue;
+    const outputYaml = formatYaml(expandOutput(uwf, item.payload.output));
+    const blockLen = formatCompactStep(i + 1, item, outputYaml).length;
+    selected.unshift(item);
+    totalChars += blockLen;
+    if (totalChars > quota) break;
+  }
+
+  const skippedCount = candidates.length - selected.length;
   const parts: string[] = [];
 
-  const startSection = formatStartSection(options);
-  if (startSection !== "") parts.push(startSection);
+  // Start section
+  if (before === null || showStart) {
+    parts.push(
+      [
+        `# Thread \`${options.threadId}\``,
+        "",
+        `**Workflow:** ${options.workflowName} (\`${options.workflowHash}\`)`,
+        "",
+        "## Task",
+        "",
+        options.prompt,
+      ].join("\n"),
+    );
+  }
 
+  // Skip hint
   if (skippedCount > 0 && selected.length > 0) {
     const firstSelected = selected[0];
     if (firstSelected !== undefined) {
@@ -726,21 +653,34 @@ function formatThreadReadMarkdown(options: {
     }
   }
 
+  // Step blocks
   const startIndex = candidates.length - selected.length;
   const shownPromptRoles = new Set<string>();
   for (let i = 0; i < selected.length; i++) {
     const item = selected[i];
     if (item === undefined) continue;
     const stepNum = startIndex + i + 1;
+    const ts = new Date(item.timestamp)
+      .toISOString()
+      .replace("T", " ")
+      .replace(/\.\d+Z$/, "");
+    const stepLines = [
+      `## Step ${stepNum}: ${item.payload.role} \`${item.hash}\``,
+      `**Agent:** ${item.payload.agent} | **Time:** ${ts}`,
+    ];
     const roleDef = workflow.roles[item.payload.role];
-    const stepBlock = [
-      formatStepHeader(stepNum, item),
-      formatStepPrompt(roleDef, item.payload.role, shownPromptRoles),
-      formatStepContent(uwf, item),
-    ]
-      .filter((s) => s !== "")
-      .join("");
-    parts.push(stepBlock);
+    if (roleDef && !shownPromptRoles.has(item.payload.role)) {
+      const prompt = roleDef.goal;
+      stepLines.push("", "### Prompt", "", prompt);
+      shownPromptRoles.add(item.payload.role);
+    }
+    if (item.payload.detail) {
+      const content = extractLastAssistantContent(uwf, item.payload.detail);
+      if (content !== null) {
+        stepLines.push("", "### Content", "", content);
+      }
+    }
+    parts.push(stepLines.join("\n"));
   }
 
   return parts.join("\n\n---\n\n");
@@ -813,11 +753,13 @@ function spawnAgent(
   role: string,
   edgePrompt: string,
 ): CasRef {
-  const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
+  const argv = [...agent.args, threadId, role];
+  const env = { ...process.env, UWF_EDGE_PROMPT: edgePrompt };
   let stdout: string;
   try {
     stdout = execFileSync(agent.command, argv, {
       encoding: "utf8",
+      env,
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
     });
@@ -862,60 +804,26 @@ export async function cmdThreadStep(
   threadId: ThreadId,
   agentOverride: string | null,
   count: number,
-  background: boolean,
-  backgroundWorker: boolean,
 ): Promise<StepOutput[]> {
   if (count < 1 || !Number.isInteger(count)) {
     fail(`--count must be a positive integer, got: ${count}`);
   }
 
-  // Check if thread is already running in background (unless we ARE the background worker)
-  if (!backgroundWorker) {
-    const runningMarker = await isThreadRunning(storageRoot, threadId);
-    if (runningMarker !== null) {
-      fail(`thread already executing in background (PID: ${runningMarker.pid})`);
-    }
-  }
-
   const workflowHash = await resolveActiveThreadWorkflowHash(storageRoot, threadId);
   const plog = createProcessLogger({
     storageRoot,
     context: { thread: threadId, workflow: workflowHash },
   });
 
-  if (background && !backgroundWorker) {
-    // Spawn background process
-    return cmdThreadStepBackground(storageRoot, threadId, agentOverride, count, plog, workflowHash);
-  }
-
-  // If we're the background worker, create marker before execution
-  let markerCreated = false;
-  if (backgroundWorker) {
-    await createMarker(storageRoot, {
-      thread: threadId,
-      workflow: workflowHash,
-      pid: process.pid,
-      startedAt: Date.now(),
-    });
-    markerCreated = true;
-  }
-
-  try {
-    const results: StepOutput[] = [];
-    for (let i = 0; i < count; i++) {
-      const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
-      results.push(result);
-      if (result.done) {
-        break;
-      }
-    }
-    return results;
-  } finally {
-    // Cleanup marker if we created one
-    if (markerCreated) {
-      await deleteMarker(storageRoot, threadId);
+  const results: StepOutput[] = [];
+  for (let i = 0; i < count; i++) {
+    const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
+    results.push(result);
+    if (result.done) {
+      break;
     }
   }
+  return results;
 }
 
 async function resolveActiveThreadWorkflowHash(
@@ -932,57 +840,6 @@ async function resolveActiveThreadWorkflowHash(
   return chain.start.workflow;
 }
 
-async function cmdThreadStepBackground(
-  storageRoot: string,
-  threadId: ThreadId,
-  agentOverride: string | null,
-  count: number,
-  plog: ProcessLogger,
-  workflowHash: CasRef,
-): Promise<StepOutput[]> {
-  // Get current head to return to caller
-  const index = await loadThreadsIndex(storageRoot);
-  const headHash = index[threadId];
-  if (headHash === undefined) {
-    failStep(plog, `thread not active: ${threadId}`);
-  }
-
-  // Spawn detached background process
-  const scriptPath = process.argv[1];
-  if (scriptPath === undefined) {
-    failStep(plog, "unable to determine script path for background execution");
-  }
-
-  const args = ["thread", "step", threadId, "--count", String(count)];
-
-  if (agentOverride !== null) {
-    args.push("--agent", agentOverride);
-  }
-
-  // Internal flag to signal the background worker to create/cleanup markers
-  args.push("--_background-worker");
-
-  plog.log(PL_BACKGROUND_START, `spawning background process count=${count}`, null);
-
-  const child = spawn(scriptPath, args, {
-    detached: true,
-    stdio: "ignore",
-  });
-
-  child.unref();
-
-  // Return immediately with current state and background flag
-  return [
-    {
-      workflow: workflowHash,
-      thread: threadId,
-      head: headHash,
-      done: false,
-      background: true,
-    },
-  ];
-}
-
 async function cmdThreadStepOnce(
   storageRoot: string,
   threadId: ThreadId,
@@ -1020,7 +877,6 @@ async function cmdThreadStepOnce(
       thread: threadId,
       head: headHash,
       done: true,
-      background: null,
     };
   }
 
@@ -1068,7 +924,6 @@ async function cmdThreadStepOnce(
     thread: threadId,
     head: newHead,
     done,
-    background: null,
   };
 }
 
@@ -1205,17 +1060,6 @@ export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Pr
     fail(`thread not active: ${threadId}`);
   }
 
-  // Check if thread is running in background and terminate it
-  const runningMarker = await isThreadRunning(storageRoot, threadId);
-  if (runningMarker !== null) {
-    try {
-      process.kill(runningMarker.pid, "SIGTERM");
-    } catch {
-      // Process may have already exited, ignore error
-    }
-    await deleteMarker(storageRoot, threadId);
-  }
-
   const uwf = await createUwfStore(storageRoot);
   const workflow = resolveWorkflowFromHead(uwf, head);
   if (workflow === null) {
@@ -1235,8 +1079,3 @@ export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Pr
 
   return { thread: threadId, archived: true };
 }
-
-export async function cmdThreadRunning(storageRoot: string): Promise<RunningThreadsOutput> {
-  const threads = await listRunningThreads(storageRoot);
-  return { threads };
-}

packages/workflow-agent-builtin/README.md

@@ -1,141 +0,0 @@
-# @uncaged/workflow-agent-builtin
-
-`uwf-builtin` agent — built-in LLM agent with file read/write and shell tools.
-
-## Overview
-
-Layer 3 agent implementation. Runs an OpenAI-compatible chat completion loop with built-in tools (`read_file`, `write_file`, `run_command`). Uses the configured provider/model from `config.yaml`. Produces frontmatter markdown output and stores turn-by-turn session detail in CAS.
-
-Useful when you want a self-contained agent without an external CLI like Hermes or Claude Code.
-
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-util`
-
-## Installation
-
-Included as the `uwf-builtin` binary when you install `@uncaged/workflow-agent-builtin`:
-
-```bash
-bun add -g @uncaged/workflow-agent-builtin
-```
-
-## CLI Usage
-
-Invoked by `uwf thread step`:
-
-```bash
-uwf-builtin <thread-id> <role>
-```
-
-Configure as default agent:
-
-```bash
-uwf setup --agent builtin
-```
-
-Override per step:
-
-```bash
-uwf thread step <thread-id> --agent uwf-builtin
-```
-
-Environment variables set by the engine:
-
-| Variable | Purpose |
-|----------|---------|
-| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
-
-## API
-
-All exports come from `src/index.ts`.
-
-### Agent factory
-
-```typescript
-function createBuiltinAgent(): () => Promise<void>
-function buildBuiltinMessages(ctx: AgentContext): ChatMessage[]
-```
-
-### LLM loop
-
-```typescript
-const BUILTIN_MAX_TURNS = 30;
-const BUILTIN_CONTINUE_MAX_TURNS = 5;
-
-function runBuiltinLoop(/* options: RunBuiltinLoopOptions */): Promise<RunBuiltinLoopResult>
-function chatCompletionWithTools(
-  provider: ResolvedLlmProvider,
-  messages: ChatMessage[],
-  tools: OpenAiToolDefinition[],
-): Promise<LlmAssistantResponse>
-```
-
-`RunBuiltinLoopOptions` and `RunBuiltinLoopResult` are internal to `loop.ts` and not re-exported from `index.ts`.
-
-### Tools
-
-```typescript
-function getBuiltinTools(): readonly BuiltinTool[]
-function executeBuiltinTool(
-  name: string,
-  args: Record<string, unknown>,
-  ctx: ToolContext,
-): Promise<string>
-```
-
-### Session and detail
-
-```typescript
-function initSessionDir(storageRoot: string): Promise<void>
-function appendSessionTurn(storageRoot: string, sessionId: string, turn: BuiltinTurnPayload): Promise<void>
-function readSessionTurns(storageRoot: string, sessionId: string): Promise<BuiltinTurnPayload[]>
-function removeSession(storageRoot: string, sessionId: string): Promise<void>
-function registerBuiltinSchemas(store: Store): Promise<BuiltinSchemaHashes>
-function storeBuiltinDetail(store: Store, payload: BuiltinDetailPayload): Promise<string>
-```
-
-### Types
-
-```typescript
-type ChatMessage = /* system | user | assistant | tool */;
-type LlmAssistantResponse = { content: string | null; toolCalls: LlmToolCall[] | null };
-type LlmToolCall = { id: string; name: string; arguments: string };
-type BuiltinTool = { name: string; description: string; parameters: Record<string, unknown> };
-type ToolContext = { cwd: string; storageRoot: string };
-type BuiltinDetailPayload = { /* session turns, model, timestamps */ };
-type BuiltinLoopTurn = { /* single loop iteration record */ };
-type BuiltinToolCallRecord = { /* tool call audit */ };
-type BuiltinToolResultRecord = { /* tool result audit */ };
-type BuiltinTurnPayload = { /* persisted turn */ };
-```
-
-## Internal Structure
-
-```
-src/
-├── index.ts
-├── cli.ts              Binary entrypoint
-├── agent.ts            createBuiltinAgent
-├── loop.ts             Multi-turn LLM + tool loop
-├── prompt.ts           buildBuiltinMessages
-├── session.ts          Session directory persistence
-├── detail.ts           CAS detail node storage
-├── schemas.ts          Builtin CAS schemas
-├── types.ts            Detail and turn payload types
-├── llm/
-│   ├── index.ts
-│   ├── llm.ts          chatCompletionWithTools
-│   └── types.ts        ChatMessage, LlmToolCall, etc.
-└── tools/
-    ├── index.ts        getBuiltinTools, executeBuiltinTool
-    ├── read-file.ts
-    ├── write-file.ts
-    ├── run-command.ts
-    ├── path.ts
-    └── types.ts
-```
-
-## Configuration
-
-Requires a configured OpenAI-compatible provider and model in `~/.uncaged/workflow/config.yaml` (via `uwf setup`). API keys are loaded from `~/.uncaged/workflow/.env`.
-
-Tools run with the current working directory as `ToolContext.cwd` (typically the directory where `uwf thread step` was invoked).

packages/workflow-agent-builtin/__tests__/loop.test.ts

@@ -19,14 +19,7 @@ mock.module("../src/tools/index.js", () => ({
   getBuiltinTools: () => [],
 }));
 
-import {
-  executeTurnTools,
-  extractFinalText,
-  runBuiltinLoop,
-  shouldInjectDeadlineWarning,
-  shouldNudge,
-  shouldProcessToolCalls,
-} from "../src/loop.js";
+import { executeTurnTools, runBuiltinLoop, shouldNudge } from "../src/loop.js";
 
 const fakeProvider = {} as any;
 const fakeToolCtx = {} as any;
@@ -161,96 +154,3 @@ describe("runBuiltinLoop integration", () => {
     expect(original.length).toBe(1);
   });
 });
-
-describe("shouldInjectDeadlineWarning", () => {
-  test("5.1 returns true when turn count reaches warning threshold and not yet warned", () => {
-    expect(shouldInjectDeadlineWarning(7, 10, false, false)).toBe(true);
-  });
-  test("5.2 returns false when already warned", () => {
-    expect(shouldInjectDeadlineWarning(7, 10, true, false)).toBe(false);
-  });
-  test("5.3 returns false when noTools is true", () => {
-    expect(shouldInjectDeadlineWarning(7, 10, false, true)).toBe(false);
-  });
-  test("5.4 returns false when turns remaining > DEADLINE_WARNING_TURNS", () => {
-    expect(shouldInjectDeadlineWarning(5, 10, false, false)).toBe(false);
-  });
-  test("5.5 returns true when exactly at warning threshold", () => {
-    expect(shouldInjectDeadlineWarning(7, 10, false, false)).toBe(true);
-  });
-  test("5.6 returns false when turns remaining is 0", () => {
-    expect(shouldInjectDeadlineWarning(10, 10, false, false)).toBe(false);
-  });
-});
-
-describe("shouldProcessToolCalls", () => {
-  test("6.1 returns true when toolCalls present and noTools=false", () => {
-    expect(shouldProcessToolCalls([{ id: "x", name: "read", arguments: "{}" }], false)).toBe(true);
-  });
-  test("6.2 returns false when toolCalls is null", () => {
-    expect(shouldProcessToolCalls(null, false)).toBe(false);
-  });
-  test("6.3 returns false when toolCalls is empty array", () => {
-    expect(shouldProcessToolCalls([], false)).toBe(false);
-  });
-  test("6.4 returns false when noTools=true", () => {
-    expect(shouldProcessToolCalls([{ id: "x", name: "read", arguments: "{}" }], true)).toBe(false);
-  });
-  test("6.5 returns true when multiple tool calls present", () => {
-    expect(
-      shouldProcessToolCalls(
-        [
-          { id: "x1", name: "read", arguments: "{}" },
-          { id: "x2", name: "write", arguments: "{}" },
-        ],
-        false,
-      ),
-    ).toBe(true);
-  });
-});
-
-describe("extractFinalText", () => {
-  test("7.1 returns last assistant message content", () => {
-    const messages = [
-      { role: "system" as const, content: "sys", tool_calls: null },
-      { role: "assistant" as const, content: "first", tool_calls: null },
-      { role: "assistant" as const, content: "last", tool_calls: null },
-    ];
-    expect(extractFinalText(messages)).toBe("last");
-  });
-  test("7.2 returns empty string when no assistant messages", () => {
-    expect(extractFinalText([{ role: "system" as const, content: "sys", tool_calls: null }])).toBe(
-      "",
-    );
-  });
-  test("7.3 skips assistant messages with null content", () => {
-    const messages = [
-      { role: "assistant" as const, content: "first", tool_calls: null },
-      {
-        role: "assistant" as const,
-        content: null,
-        tool_calls: [{ id: "x", name: "t", arguments: "{}" }],
-      },
-      { role: "assistant" as const, content: "second", tool_calls: null },
-    ];
-    expect(extractFinalText(messages)).toBe("second");
-  });
-  test("7.4 skips assistant messages with empty content", () => {
-    const messages = [
-      { role: "assistant" as const, content: "first", tool_calls: null },
-      { role: "assistant" as const, content: "", tool_calls: null },
-      { role: "user" as const, content: "nudge", tool_calls: null },
-    ];
-    expect(extractFinalText(messages)).toBe("first");
-  });
-  test("7.5 handles empty messages array", () => {
-    expect(extractFinalText([])).toBe("");
-  });
-  test("7.6 handles messages with only user and system roles", () => {
-    const messages = [
-      { role: "system" as const, content: "sys", tool_calls: null },
-      { role: "user" as const, content: "query", tool_calls: null },
-    ];
-    expect(extractFinalText(messages)).toBe("");
-  });
-});

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

@@ -1,12 +1,7 @@
 import type { ResolvedLlmProvider } from "@uncaged/workflow-agent-kit";
 import { createLogger } from "@uncaged/workflow-util";
 
-import {
-  type ChatMessage,
-  chatCompletionWithTools,
-  type LlmToolCall,
-  type OpenAiToolDefinition,
-} from "./llm/index.js";
+import { type ChatMessage, chatCompletionWithTools, type LlmToolCall } from "./llm/index.js";
 import { appendSessionTurn } from "./session.js";
 import {
   builtinToolsToOpenAi,
@@ -82,23 +77,53 @@ export type ShouldNudgeOptions = {
   maxTurns: number;
 };
 
-const MAX_NUDGES = 3;
-const DEADLINE_WARNING_TURNS = 3;
-
-export function shouldInjectDeadlineWarning(
-  turn: number,
-  maxTurns: number,
-  alreadyWarned: boolean,
-  noTools: boolean,
-): boolean {
-  const turnsRemaining = maxTurns - turn;
-  return (
-    !noTools && !alreadyWarned && turnsRemaining > 0 && turnsRemaining <= DEADLINE_WARNING_TURNS
-  );
+export function shouldNudge({ noTools, text, turn, maxTurns }: ShouldNudgeOptions): boolean {
+  return !noTools && !text.trimStart().startsWith("---") && turn < maxTurns - 1;
 }
 
-export function shouldProcessToolCalls(toolCalls: LlmToolCall[] | null, noTools: boolean): boolean {
-  return !noTools && toolCalls !== null && toolCalls.length > 0;
+async function handleTextTurn(
+  text: string,
+  turn: number,
+  noTools: boolean,
+  maxTurns: number,
+  storageRoot: string,
+  sessionId: string,
+  messages: ChatMessage[],
+): Promise<{ done: boolean; finalText: string }> {
+  await appendTurn(storageRoot, sessionId, {
+    role: "assistant",
+    content: text,
+    toolCalls: null,
+    reasoning: null,
+  });
+
+  if (shouldNudge({ noTools, text, turn, maxTurns })) {
+    log("7FXQM2KN", "text-only turn without frontmatter, nudging LLM to continue");
+    const nudge =
+      "You stopped calling tools but your response does not start with the required `---` YAML frontmatter. " +
+      "Either continue using tools to complete your work, or output your final response starting with `---`.";
+    messages.push({ role: "user", content: nudge });
+    return { done: false, finalText: "" };
+  }
+
+  return { done: true, finalText: text };
+}
+
+async function handleToolTurn(
+  content: string,
+  toolCalls: LlmToolCall[],
+  toolCtx: ToolContext,
+  messages: ChatMessage[],
+  storageRoot: string,
+  sessionId: string,
+): Promise<number> {
+  await appendTurn(storageRoot, sessionId, {
+    role: "assistant",
+    content,
+    toolCalls: mapToolCallsForPayload(toolCalls),
+    reasoning: null,
+  });
+  return executeTurnTools(toolCalls, toolCtx, messages, storageRoot, sessionId);
 }
 
 export function extractFinalText(messages: ChatMessage[]): string {
@@ -116,151 +141,47 @@ export function extractFinalText(messages: ChatMessage[]): string {
   return "";
 }
 
-function injectDeadlineWarning(messages: ChatMessage[], turnsRemaining: number): void {
-  log("4NRXW6KT", `${turnsRemaining} turns remaining, injecting deadline warning`);
-  messages.push({
-    role: "user",
-    content:
-      `⚠️ You have ${turnsRemaining} turns remaining. ` +
-      "Wrap up your work and output the YAML frontmatter starting with `---`. " +
-      "If you cannot finish in time, output frontmatter with `status: failed` and describe what remains.",
-  });
-}
+type LoopTurnResult = { done: boolean; finalText: string; extraTurns: number };
 
-type HandleTextOnlyTurnResult = {
-  shouldBreak: boolean;
-  finalText: string;
-  turnCount: number;
-  nudgeCount: number;
-  turnAdjustment: number;
-};
-
-async function handleTextOnlyTurn(
-  text: string,
-  messages: ChatMessage[],
-  storageRoot: string,
-  sessionId: string,
-  noTools: boolean,
+async function runLoopTurn(
   turn: number,
-  maxTurns: number,
-  currentNudgeCount: number,
-): Promise<HandleTextOnlyTurnResult> {
-  await appendTurn(storageRoot, sessionId, {
-    role: "assistant",
-    content: text,
-    toolCalls: null,
-    reasoning: null,
-  });
-  const turnCount = 1;
-  let nudgeCount = currentNudgeCount;
-  let turnAdjustment = 0;
-
-  if (shouldNudge({ noTools, text, turn, maxTurns })) {
-    nudgeCount += 1;
-    log("7FXQM2KN", `text-only turn without frontmatter, nudge ${nudgeCount}/${MAX_NUDGES}`);
-    const nudge =
-      "You stopped calling tools but your response does not start with the required `---` YAML frontmatter. " +
-      "Either continue using tools to complete your work, or output your final response starting with `---`.";
-    messages.push({ role: "user", content: nudge });
-    // Nudge doesn't consume turn budget (up to MAX_NUDGES)
-    if (nudgeCount <= MAX_NUDGES) {
-      turnAdjustment = -1;
-    }
-    return { shouldBreak: false, finalText: "", turnCount, nudgeCount, turnAdjustment };
-  }
-
-  return { shouldBreak: true, finalText: text, turnCount, nudgeCount, turnAdjustment };
-}
-
-async function handleToolCallTurn(
-  content: string,
-  toolCalls: LlmToolCall[],
-  messages: ChatMessage[],
-  storageRoot: string,
-  sessionId: string,
-  toolCtx: ToolContext,
-): Promise<number> {
-  await appendTurn(storageRoot, sessionId, {
-    role: "assistant",
-    content,
-    toolCalls: mapToolCallsForPayload(toolCalls),
-    reasoning: null,
-  });
-  let turnCount = 1;
-
-  // Execute tools
-  turnCount += await executeTurnTools(toolCalls, toolCtx, messages, storageRoot, sessionId);
-
-  return turnCount;
-}
-
-export function shouldNudge({ noTools, text, turn, maxTurns }: ShouldNudgeOptions): boolean {
-  return !noTools && !text.trimStart().startsWith("---") && turn < maxTurns - 1;
-}
-
-type ProcessLoopIterationResult = {
-  shouldBreak: boolean;
-  finalText: string;
-  turnCount: number;
-  nudgeCount: number;
-  turnAdjustment: number;
-};
-
-async function processLoopIteration(
   options: RunBuiltinLoopOptions,
   messages: ChatMessage[],
-  openAiTools: OpenAiToolDefinition[],
-  turn: number,
-  nudgeCount: number,
-): Promise<ProcessLoopIterationResult> {
+  openAiTools: ReturnType<typeof builtinToolsToOpenAi>,
+): Promise<LoopTurnResult> {
+  log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
   const response = await chatCompletionWithTools(
     options.provider,
     messages,
     openAiTools.length > 0 ? openAiTools : null,
   );
 
-  // When noTools is set, ignore any tool_calls the LLM might still return
   const effectiveToolCalls = options.noTools ? null : (response.toolCalls ?? null);
+  messages.push({ role: "assistant", content: response.content, tool_calls: effectiveToolCalls });
 
-  const assistantMessage: ChatMessage = {
-    role: "assistant",
-    content: response.content,
-    tool_calls: effectiveToolCalls,
-  };
-  messages.push(assistantMessage);
-
-  if (!shouldProcessToolCalls(effectiveToolCalls, options.noTools)) {
+  if (effectiveToolCalls === null || effectiveToolCalls.length === 0) {
     const text = response.content ?? "";
-    const result = await handleTextOnlyTurn(
+    const result = await handleTextTurn(
       text,
-      messages,
+      turn,
+      options.noTools,
+      options.maxTurns,
       options.storageRoot,
       options.sessionId,
-      options.noTools,
-      turn,
-      options.maxTurns,
-      nudgeCount,
+      messages,
     );
-    return result;
+    return { done: result.done, finalText: result.finalText, extraTurns: 0 };
   }
 
-  // At this point, effectiveToolCalls is guaranteed to be non-null and non-empty
-  const turnCount = await handleToolCallTurn(
+  const extra = await handleToolTurn(
     response.content ?? "",
-    effectiveToolCalls as LlmToolCall[],
+    effectiveToolCalls,
+    options.toolCtx,
     messages,
     options.storageRoot,
     options.sessionId,
-    options.toolCtx,
   );
-
-  return {
-    shouldBreak: false,
-    finalText: "",
-    turnCount,
-    nudgeCount,
-    turnAdjustment: 0,
-  };
+  return { done: false, finalText: "", extraTurns: extra };
 }
 
 /** Agent run loop: LLM ↔ tools until no tool_calls or maxTurns. */
@@ -271,31 +192,17 @@ export async function runBuiltinLoop(
   const openAiTools = options.noTools ? [] : builtinToolsToOpenAi(getBuiltinTools());
   let finalText = "";
   let turnCount = 0;
-  let nudgeCount = 0;
-  let deadlineWarned = false;
 
   for (let turn = 0; turn < options.maxTurns; turn++) {
-    log("8K2M4N7P", `builtin loop turn ${turn + 1}/${options.maxTurns}`);
-
-    // Warn agent when approaching turn limit
-    if (shouldInjectDeadlineWarning(turn, options.maxTurns, deadlineWarned, options.noTools)) {
-      deadlineWarned = true;
-      const turnsRemaining = options.maxTurns - turn;
-      injectDeadlineWarning(messages, turnsRemaining);
-    }
-
-    const result = await processLoopIteration(options, messages, openAiTools, turn, nudgeCount);
-    turnCount += result.turnCount;
-    nudgeCount = result.nudgeCount;
-    turn += result.turnAdjustment;
-
-    if (result.shouldBreak) {
+    const result = await runLoopTurn(turn, options, messages, openAiTools);
+    turnCount += 1 + result.extraTurns;
+    if (result.done) {
       finalText = result.finalText;
       break;
     }
   }
 
-  if (finalText === "") {
+  if (finalText === "" && messages.length > 0) {
     finalText = extractFinalText(messages);
   }
 

packages/workflow-agent-claude-code/README.md

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

packages/workflow-agent-claude-code/__tests__/session-detail.test.ts

@@ -154,99 +154,6 @@ describe("parseClaudeCodeStreamOutput", () => {
   });
 });
 
-describe("parseClaudeCodeStreamOutput — helper extraction", () => {
-  test("processSystemLine sets model from system message", () => {
-    const lines = [
-      JSON.stringify({ type: "system", model: "claude-opus-4" }),
-      JSON.stringify({
-        type: "result",
-        subtype: "success",
-        result: "ok",
-        session_id: "s1",
-        num_turns: 0,
-        total_cost_usd: 0,
-        duration_ms: 0,
-        stop_reason: "end_turn",
-      }),
-    ];
-    const parsed = parseClaudeCodeStreamOutput(lines.join("\n"));
-    expect(parsed).not.toBeNull();
-    expect(parsed!.model).toBe("claude-opus-4");
-  });
-
-  test("processAssistantLine skips empty content", () => {
-    const lines = [
-      JSON.stringify({ type: "assistant", message: { role: "assistant", content: [] } }),
-      JSON.stringify({
-        type: "result",
-        subtype: "success",
-        result: "ok",
-        session_id: "s1",
-        num_turns: 0,
-        total_cost_usd: 0,
-        duration_ms: 0,
-        stop_reason: "end_turn",
-      }),
-    ];
-    const parsed = parseClaudeCodeStreamOutput(lines.join("\n"));
-    expect(parsed).not.toBeNull();
-    expect(parsed!.turns).toHaveLength(0);
-  });
-
-  test("processUserLine skips when no tool_result items", () => {
-    const lines = [
-      JSON.stringify({
-        type: "user",
-        message: { role: "user", content: [{ type: "text", text: "hi" }] },
-      }),
-      JSON.stringify({
-        type: "result",
-        subtype: "success",
-        result: "ok",
-        session_id: "s1",
-        num_turns: 0,
-        total_cost_usd: 0,
-        duration_ms: 0,
-        stop_reason: "end_turn",
-      }),
-    ];
-    const parsed = parseClaudeCodeStreamOutput(lines.join("\n"));
-    expect(parsed).not.toBeNull();
-    expect(parsed!.turns).toHaveLength(0);
-  });
-
-  test("turn indices are sequential across mixed assistant and user lines", () => {
-    const lines = [
-      JSON.stringify({
-        type: "assistant",
-        message: { role: "assistant", content: [{ type: "text", text: "A" }] },
-      }),
-      JSON.stringify({
-        type: "user",
-        message: { role: "user", content: [{ type: "tool_result", content: "R" }] },
-      }),
-      JSON.stringify({
-        type: "assistant",
-        message: { role: "assistant", content: [{ type: "text", text: "B" }] },
-      }),
-      JSON.stringify({
-        type: "result",
-        subtype: "success",
-        result: "ok",
-        session_id: "s1",
-        num_turns: 3,
-        total_cost_usd: 0,
-        duration_ms: 0,
-        stop_reason: "end_turn",
-      }),
-    ];
-    const parsed = parseClaudeCodeStreamOutput(lines.join("\n"));
-    expect(parsed).not.toBeNull();
-    expect(parsed!.turns).toHaveLength(3);
-    expect(parsed!.turns.map((t) => t.index)).toEqual([0, 1, 2]);
-  });
-});
-
 describe("storeClaudeCodeDetail", () => {
   const baseParsed: ClaudeCodeParsedResult = {
     type: "result",

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

@@ -16,7 +16,6 @@ const log = createLogger({ sink: { kind: "stderr" } });
 
 const CLAUDE_COMMAND = "claude";
 const CLAUDE_MAX_TURNS = 90;
-const CLAUDE_MODEL = process.env.CLAUDE_MODEL ?? null;
 
 function buildHistorySummary(steps: AgentContext["steps"]): string {
   if (steps.length === 0) {
@@ -88,7 +87,7 @@ function spawnClaude(args: string[]): Promise<{ stdout: string; stderr: string }
 }
 
 function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: string }> {
-  const args = [
+  return spawnClaude([
     "-p",
     prompt,
     "--output-format",
@@ -97,18 +96,14 @@ function spawnClaudeRun(prompt: string): Promise<{ stdout: string; stderr: strin
     "--dangerously-skip-permissions",
     "--max-turns",
     String(CLAUDE_MAX_TURNS),
-  ];
-  if (CLAUDE_MODEL !== null) {
-    args.push("--model", CLAUDE_MODEL);
-  }
-  return spawnClaude(args);
+  ]);
 }
 
 function spawnClaudeResume(
   sessionId: string,
   message: string,
 ): Promise<{ stdout: string; stderr: string }> {
-  const args = [
+  return spawnClaude([
     "-p",
     message,
     "--resume",
@@ -119,11 +114,7 @@ function spawnClaudeResume(
     "--dangerously-skip-permissions",
     "--max-turns",
     String(CLAUDE_MAX_TURNS),
-  ];
-  if (CLAUDE_MODEL !== null) {
-    args.push("--model", CLAUDE_MODEL);
-  }
-  return spawnClaude(args);
+  ]);
 }
 
 async function processClaudeOutput(stdout: string, store: Store): Promise<AgentRunResult> {

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

@@ -34,7 +34,7 @@ export const CLAUDE_CODE_DETAIL_SCHEMA: JSONSchema = {
     },
     turns: {
       type: "array",
-      items: { type: "string", format: "cas_ref" },
+      items: { type: "string" },
     },
   },
   additionalProperties: false,

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

@@ -67,103 +67,99 @@ function extractToolResultContent(content: unknown[]): string {
   return results.join("\n");
 }
 
-type ParseState = {
-  turns: ClaudeCodeTurnPayload[];
-  resultLine: Record<string, unknown> | null;
-  model: string;
-  turnIndex: number;
-};
-
-function processSystemLine(parsed: Record<string, unknown>, state: ParseState): void {
-  if (typeof parsed.model === "string") {
-    state.model = parsed.model;
-  }
-}
-
-function processAssistantLine(parsed: Record<string, unknown>, state: ParseState): void {
-  if (!isRecord(parsed.message)) return;
-  const content = Array.isArray(parsed.message.content) ? parsed.message.content : [];
-  const textContent = extractTextContent(content as unknown[]);
-  const toolCalls = extractToolCalls(content as unknown[]);
-  if (textContent !== "" || toolCalls.length > 0) {
-    state.turns.push({
-      index: state.turnIndex++,
-      role: "assistant",
-      content: textContent,
-      toolCalls: toolCalls.length > 0 ? toolCalls : null,
-    });
-  }
-}
-
-function processUserLine(parsed: Record<string, unknown>, state: ParseState): void {
-  if (!isRecord(parsed.message)) return;
-  const content = Array.isArray(parsed.message.content) ? parsed.message.content : [];
-  const resultContent = extractToolResultContent(content as unknown[]);
-  if (resultContent !== "") {
-    state.turns.push({
-      index: state.turnIndex++,
-      role: "tool_result",
-      content: resultContent,
-      toolCalls: null,
-    });
-  }
-}
-
-function processLine(line: string, state: ParseState): void {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(line);
-  } catch {
-    return;
-  }
-  if (!isRecord(parsed)) return;
-  const type = parsed.type;
-  if (type === "system") processSystemLine(parsed, state);
-  else if (type === "assistant") processAssistantLine(parsed, state);
-  else if (type === "user") processUserLine(parsed, state);
-  else if (type === "result") state.resultLine = parsed;
-}
-
-function assembleResult(state: ParseState): ClaudeCodeParsedResult | null {
-  if (state.resultLine === null) return null;
-  const sessionId = state.resultLine.session_id;
-  const result = state.resultLine.result;
-  const subtype = state.resultLine.subtype;
-  if (typeof sessionId !== "string" || typeof result !== "string" || typeof subtype !== "string") {
-    return null;
-  }
-  const usage = isRecord(state.resultLine.usage) ? state.resultLine.usage : {};
-  return {
-    type: safeString(state.resultLine.type, "result"),
-    subtype: subtype as ClaudeCodeParsedResult["subtype"],
-    result,
-    sessionId,
-    numTurns: safeNumber(state.resultLine.num_turns),
-    totalCostUsd: safeNumber(state.resultLine.total_cost_usd),
-    durationMs: safeNumber(state.resultLine.duration_ms),
-    model: state.model,
-    stopReason: safeString(state.resultLine.stop_reason),
-    usage: {
-      inputTokens: safeNumber(usage.input_tokens),
-      outputTokens: safeNumber(usage.output_tokens),
-      cacheReadInputTokens: safeNumber(usage.cache_read_input_tokens),
-      cacheCreationInputTokens: safeNumber(usage.cache_creation_input_tokens),
-    },
-    turns: state.turns,
-  };
-}
-
 /**
  * Parse Claude Code stream-json (NDJSON) output.
  * Each line is a JSON object with type: "system" | "assistant" | "user" | "result".
  */
 export function parseClaudeCodeStreamOutput(stdout: string): ClaudeCodeParsedResult | null {
   const lines = stdout.trim().split("\n");
-  const state: ParseState = { turns: [], resultLine: null, model: "", turnIndex: 0 };
+  const turns: ClaudeCodeTurnPayload[] = [];
+  let resultLine: Record<string, unknown> | null = null;
+  let model = "";
+  let turnIndex = 0;
+
   for (const line of lines) {
-    processLine(line, state);
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!isRecord(parsed)) continue;
+
+    const type = parsed.type;
+
+    if (type === "system" && typeof parsed.model === "string") {
+      model = parsed.model;
+    }
+
+    if (type === "assistant" && isRecord(parsed.message)) {
+      const msg = parsed.message;
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      const textContent = extractTextContent(content as unknown[]);
+      const toolCalls = extractToolCalls(content as unknown[]);
+
+      // Only record turns that have actual content
+      if (textContent !== "" || toolCalls.length > 0) {
+        turns.push({
+          index: turnIndex++,
+          role: "assistant",
+          content: textContent,
+          toolCalls: toolCalls.length > 0 ? toolCalls : null,
+        });
+      }
+    }
+
+    if (type === "user" && isRecord(parsed.message)) {
+      const msg = parsed.message;
+      const content = Array.isArray(msg.content) ? msg.content : [];
+      const resultContent = extractToolResultContent(content as unknown[]);
+
+      if (resultContent !== "") {
+        turns.push({
+          index: turnIndex++,
+          role: "tool_result",
+          content: resultContent,
+          toolCalls: null,
+        });
+      }
+    }
+
+    if (type === "result") {
+      resultLine = parsed;
+    }
   }
-  return assembleResult(state);
+
+  if (resultLine === null) return null;
+
+  const sessionId = resultLine.session_id;
+  const result = resultLine.result;
+  const subtype = resultLine.subtype;
+
+  if (typeof sessionId !== "string" || typeof result !== "string" || typeof subtype !== "string") {
+    return null;
+  }
+
+  const usage = isRecord(resultLine.usage) ? resultLine.usage : {};
+
+  return {
+    type: safeString(resultLine.type, "result"),
+    subtype: subtype as ClaudeCodeParsedResult["subtype"],
+    result,
+    sessionId,
+    numTurns: safeNumber(resultLine.num_turns),
+    totalCostUsd: safeNumber(resultLine.total_cost_usd),
+    durationMs: safeNumber(resultLine.duration_ms),
+    model,
+    stopReason: safeString(resultLine.stop_reason),
+    usage: {
+      inputTokens: safeNumber(usage.input_tokens),
+      outputTokens: safeNumber(usage.output_tokens),
+      cacheReadInputTokens: safeNumber(usage.cache_read_input_tokens),
+      cacheCreationInputTokens: safeNumber(usage.cache_creation_input_tokens),
+    },
+    turns,
+  };
 }
 
 /**

packages/workflow-agent-hermes/README.md

@@ -1,90 +0,0 @@
-# @uncaged/workflow-agent-hermes
-
-`uwf-hermes` agent — spawns Hermes chat via ACP and captures session detail.
-
-## Overview
-
-Layer 3 agent implementation. Wraps the Hermes CLI using the Agent Client Protocol (ACP). On first visit to a role it sends a composed prompt (role definition, task, history, edge prompt); on continuation it resumes the cached session. Session transcripts and raw output are stored as CAS detail nodes.
-
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`
-
-## Installation
-
-Included as the `uwf-hermes` binary when you install `@uncaged/workflow-agent-hermes`:
-
-```bash
-bun add -g @uncaged/workflow-agent-hermes
-```
-
-Requires the `hermes` CLI on `PATH`.
-
-## CLI Usage
-
-Invoked by `uwf thread step` (not typically run directly):
-
-```bash
-uwf-hermes <thread-id> <role>
-```
-
-Environment variables set by the engine:
-
-| Variable | Purpose |
-|----------|---------|
-| `UWF_EDGE_PROMPT` | Moderator edge instruction for this step |
-
-Configure as the default agent via `uwf setup --agent hermes`.
-
-Override per step:
-
-```bash
-uwf thread step <thread-id> --agent uwf-hermes
-```
-
-## API
-
-All exports come from `src/index.ts`.
-
-### Agent factory
-
-```typescript
-function createHermesAgent(): () => Promise<void>
-function buildHermesPrompt(ctx: AgentContext): string
-```
-
-### ACP client
-
-```typescript
-class HermesAcpClient {
-  // Spawns hermes, handles JSON-RPC over stdio
-}
-```
-
-## Usage (library)
-
-```typescript
-import { createHermesAgent, buildHermesPrompt } from "@uncaged/workflow-agent-hermes";
-
-// CLI entry (src/cli.ts):
-const main = createHermesAgent();
-void main();
-```
-
-## Internal Structure
-
-```
-src/
-├── index.ts
-├── cli.ts              Binary entrypoint
-├── hermes.ts           createHermesAgent, buildHermesPrompt
-├── acp-client.ts       HermesAcpClient — ACP JSON-RPC over stdio
-├── session-cache.ts    Session ID cache (re-exports kit helpers + isResumeDisabled)
-├── session-detail.ts   Parse Hermes session JSON, store CAS detail nodes
-├── schemas.ts          Hermes detail CAS schemas
-└── types.ts            HermesSessionJson, HermesSessionMessage
-```
-
-## Configuration
-
-Uses workflow config from `~/.uncaged/workflow/config.yaml` (via agent-kit). Hermes session files are stored under the workflow storage root (see `session-detail.ts`).
-
-Set `UWF_HERMES_NO_RESUME=1` to disable session resume (see `isResumeDisabled` in `session-cache.ts`).

packages/workflow-agent-hermes/__tests__/acp-client.test.ts

@@ -4,96 +4,6 @@ import { HermesAcpClient } from "../src/acp-client.js";
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-describe("handleSessionUpdate — helper extraction", () => {
-  let client: HermesAcpClient;
-
-  beforeEach(() => {
-    client = new HermesAcpClient();
-  });
-
-  afterEach(async () => {
-    await client.close();
-  });
-
-  it("agent_message_chunk accumulates text in messageChunks", () => {
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "agent_message_chunk",
-      content: { type: "text", text: "hello" },
-    });
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "agent_message_chunk",
-      content: { type: "text", text: " world" },
-    });
-    expect((client as any).messageChunks).toEqual(["hello", " world"]);
-  });
-
-  it("agent_thought_chunk accumulates reasoning in reasoningChunks", () => {
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "agent_thought_chunk",
-      content: { type: "text", text: "thinking" },
-    });
-    expect((client as any).reasoningChunks).toEqual(["thinking"]);
-  });
-
-  it("tool_call registers a pending tool and flushes message chunks", () => {
-    (client as any).messageChunks = ["pre-tool text"];
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "tool_call",
-      title: "Bash",
-      rawInput: { command: "ls" },
-      toolCallId: "tc-1",
-    });
-    expect((client as any).pendingTools.get("tc-1")).toEqual({
-      name: "Bash",
-      args: JSON.stringify({ command: "ls" }),
-    });
-    expect((client as any).messageChunks).toEqual([]);
-    expect((client as any).messages).toHaveLength(1);
-    expect((client as any).messages[0].role).toBe("assistant");
-  });
-
-  it("tool_call_update completed pushes tool_call and tool messages", () => {
-    (client as any).pendingTools.set("tc-2", { name: "Read", args: '{"path":"/foo"}' });
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "tool_call_update",
-      status: "completed",
-      toolCallId: "tc-2",
-      rawOutput: "file contents",
-    });
-    const msgs = (client as any).messages as Array<{
-      role: string;
-      tool_calls: unknown;
-      content: string | null;
-    }>;
-    expect(msgs).toHaveLength(2);
-    expect(msgs[0].role).toBe("assistant");
-    expect(msgs[0].tool_calls).toEqual([
-      { function: { name: "Read", arguments: '{"path":"/foo"}' } },
-    ]);
-    expect(msgs[1].role).toBe("tool");
-    expect(msgs[1].content).toBe("file contents");
-    expect((client as any).pendingTools.has("tc-2")).toBe(false);
-  });
-
-  it("tool_call_update with non-string rawOutput JSON-stringifies it", () => {
-    (client as any).pendingTools.set("tc-3", { name: "Fetch", args: "" });
-    (client as any).handleSessionUpdate({
-      sessionUpdate: "tool_call_update",
-      status: "completed",
-      toolCallId: "tc-3",
-      rawOutput: { html: "<p>page</p>" },
-    });
-    const msgs = (client as any).messages as Array<{ role: string; content: string | null }>;
-    expect(msgs[1].content).toBe(JSON.stringify({ html: "<p>page</p>" }));
-  });
-
-  it("unknown updateType is a no-op", () => {
-    (client as any).handleSessionUpdate({ sessionUpdate: "unknown_type", data: {} });
-    expect((client as any).messages).toHaveLength(0);
-    expect((client as any).messageChunks).toHaveLength(0);
-  });
-});
-
 describe("HermesAcpClient", () => {
   let client: HermesAcpClient;
 

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

@@ -245,75 +245,72 @@ export class HermesAcpClient {
   // ---- Session update → structured messages ----
 
   private handleSessionUpdate(update: Record<string, unknown>): void {
-    switch (update.sessionUpdate as string) {
-      case "agent_message_chunk":
-        this.handleAgentMessageChunk(update);
+    const updateType = update.sessionUpdate as string;
+
+    switch (updateType) {
+      case "agent_message_chunk": {
+        const content = update.content as { type?: string; text?: string } | undefined;
+        if (content?.type === "text" && typeof content.text === "string") {
+          this.messageChunks.push(content.text);
+        }
         break;
-      case "agent_thought_chunk":
-        this.handleAgentThoughtChunk(update);
+      }
+
+      case "agent_thought_chunk": {
+        const content = update.content as { type?: string; text?: string } | undefined;
+        if (content?.type === "text" && typeof content.text === "string") {
+          this.reasoningChunks.push(content.text);
+        }
         break;
-      case "tool_call":
-        this.handleToolCall(update);
+      }
+
+      case "tool_call": {
+        const title = (update.title as string) ?? "";
+        const rawInput = update.rawInput;
+        const args = rawInput !== undefined && rawInput !== null ? JSON.stringify(rawInput) : "";
+        const toolCallId = update.toolCallId as string;
+        this.pendingTools.set(toolCallId, { name: title, args });
+
+        // Flush accumulated assistant text before tool call
+        this.flushAssistantMessage();
         break;
-      case "tool_call_update":
-        this.handleToolCallUpdate(update);
+      }
+
+      case "tool_call_update": {
+        const status = update.status as string | undefined;
+        if (status === "completed" || status === "failed") {
+          const toolCallId = update.toolCallId as string;
+          const pending = this.pendingTools.get(toolCallId);
+          const toolName = pending?.name ?? toolCallId;
+          const rawOutput = update.rawOutput;
+          const outputStr =
+            rawOutput !== undefined && rawOutput !== null
+              ? typeof rawOutput === "string"
+                ? rawOutput
+                : JSON.stringify(rawOutput)
+              : "";
+          this.messages.push({
+            role: "assistant",
+            content: null,
+            reasoning: null,
+            tool_calls: [{ function: { name: toolName, arguments: pending?.args ?? "" } }],
+          });
+          this.messages.push({
+            role: "tool",
+            content: outputStr,
+            reasoning: null,
+            tool_calls: null,
+          });
+          this.pendingTools.delete(toolCallId);
+        }
         break;
+      }
+
       default:
         break;
     }
   }
 
-  private handleAgentMessageChunk(update: Record<string, unknown>): void {
-    const content = update.content as { type?: string; text?: string } | undefined;
-    if (content?.type === "text" && typeof content.text === "string") {
-      this.messageChunks.push(content.text);
-    }
-  }
-
-  private handleAgentThoughtChunk(update: Record<string, unknown>): void {
-    const content = update.content as { type?: string; text?: string } | undefined;
-    if (content?.type === "text" && typeof content.text === "string") {
-      this.reasoningChunks.push(content.text);
-    }
-  }
-
-  private handleToolCall(update: Record<string, unknown>): void {
-    const title = (update.title as string) ?? "";
-    const rawInput = update.rawInput;
-    const args = rawInput !== undefined && rawInput !== null ? JSON.stringify(rawInput) : "";
-    const toolCallId = update.toolCallId as string;
-    this.pendingTools.set(toolCallId, { name: title, args });
-    this.flushAssistantMessage();
-  }
-
-  private handleToolCallUpdate(update: Record<string, unknown>): void {
-    const status = update.status as string | undefined;
-    if (status !== "completed" && status !== "failed") return;
-    const toolCallId = update.toolCallId as string;
-    const pending = this.pendingTools.get(toolCallId);
-    const toolName = pending?.name ?? toolCallId;
-    const rawOutput = update.rawOutput;
-    const outputStr =
-      rawOutput !== undefined && rawOutput !== null
-        ? typeof rawOutput === "string"
-          ? rawOutput
-          : JSON.stringify(rawOutput)
-        : "";
-    this.messages.push({
-      role: "assistant",
-      content: null,
-      reasoning: null,
-      tool_calls: [{ function: { name: toolName, arguments: pending?.args ?? "" } }],
-    });
-    this.messages.push({
-      role: "tool",
-      content: outputStr,
-      reasoning: null,
-      tool_calls: null,
-    });
-    this.pendingTools.delete(toolCallId);
-  }
-
   /** Flush any accumulated text/reasoning into an assistant message. */
   private flushAssistantMessage(): void {
     const text = this.messageChunks.join("");

packages/workflow-agent-kit/README.md

@@ -1,182 +0,0 @@
-# @uncaged/workflow-agent-kit
-
-Agent framework — `createAgent` factory, context builder, frontmatter fast-path, and LLM extract pipeline.
-
-## Overview
-
-Layer 2 agent framework. Provides the standard entrypoint for all agent CLIs: parse `<thread-id> <role>` from argv, load thread/workflow context from CAS, invoke the agent's `run`/`continue` functions, validate output via frontmatter fast-path or LLM extract, and write a `StepNodePayload` to CAS.
-
-Also exports prompt builders, config/storage helpers, and session ID caching for multi-turn agents.
-
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `dotenv`, `yaml`
-
-## Installation
-
-```bash
-bun add @uncaged/workflow-agent-kit
-```
-
-## API
-
-All exports come from `src/index.ts`.
-
-### Agent factory
-
-```typescript
-function createAgent(options: AgentOptions): () => Promise<void>
-
-type AgentOptions = {
-  name: string;
-  run: AgentRunFn;
-  continue: AgentContinueFn;
-};
-
-type AgentRunFn = (ctx: AgentContext) => Promise<AgentRunResult>;
-type AgentContinueFn = (
-  sessionId: string,
-  message: string,
-  store: AgentContext["store"],
-) => Promise<AgentRunResult>;
-
-type AgentRunResult = {
-  output: string;
-  detailHash: string;
-  sessionId: string;
-};
-```
-
-Agent CLIs call `createAgent(...)` and invoke the returned function as `main()`.
-
-### Context
-
-```typescript
-function buildContext(threadId: ThreadId, role: string): Promise<AgentContext>
-function buildContextWithMeta(
-  threadId: ThreadId,
-  role: string,
-): Promise<AgentContext & { meta: BuildContextMeta }>
-
-type AgentContext = ModeratorContext & {
-  threadId: ThreadId;
-  role: string;
-  store: Store;
-  workflow: WorkflowPayload;
-  outputFormatInstruction: string;
-  edgePrompt: string;
-  isFirstVisit: boolean;
-};
-
-type BuildContextMeta = {
-  storageRoot: string;
-  store: Store;
-  schemas: AgentStore["schemas"];
-  headHash: CasRef;
-  chain: ChainState;
-};
-```
-
-Requires `UWF_EDGE_PROMPT` in the environment (set by `uwf thread step`).
-
-### Prompt builders
-
-```typescript
-function buildRolePrompt(role: RoleDefinition): string
-function buildOutputFormatInstruction(schema: JSONSchema): string
-function buildContinuationPrompt(
-  ctx: AgentContext,
-  priorOutput: string,
-  instruction: string,
-): string
-```
-
-### Extract pipeline
-
-```typescript
-function resolveExtractModelAlias(config: WorkflowConfig): ModelAlias
-function resolveModel(config: WorkflowConfig, alias: ModelAlias): ResolvedLlmProvider
-function extract(
-  rawOutput: string,
-  outputSchema: CasRef,
-  config: WorkflowConfig,
-): Promise<ExtractResult>
-
-type ResolvedLlmProvider = { baseUrl: string; apiKey: string; model: string };
-type ExtractResult = { value: unknown; hash: CasRef };
-```
-
-### Frontmatter fast-path
-
-```typescript
-function tryFrontmatterFastPath(
-  rawOutput: string,
-  outputSchema: CasRef,
-  store: Store,
-): Promise<FrontmatterFastPathResult | null>
-
-type FrontmatterFastPathResult = { body: string; outputHash: CasRef };
-```
-
-### Session cache
-
-```typescript
-function getCachedSessionId(threadId: ThreadId, role: string): Promise<string | null>
-function setCachedSessionId(
-  threadId: ThreadId,
-  role: string,
-  sessionId: string,
-): Promise<void>
-```
-
-### Config and storage
-
-```typescript
-function getConfigPath(storageRoot: string): string
-function getEnvPath(storageRoot: string): string
-function resolveStorageRoot(): string
-function loadWorkflowConfig(storageRoot: string): Promise<WorkflowConfig>
-```
-
-## Usage
-
-```typescript
-import { createAgent, buildRolePrompt } from "@uncaged/workflow-agent-kit";
-import type { AgentContext, AgentRunResult } from "@uncaged/workflow-agent-kit";
-
-async function run(ctx: AgentContext): Promise<AgentRunResult> {
-  const prompt = buildRolePrompt(ctx.workflow.roles[ctx.role]!);
-  // ... spawn external process, capture output ...
-  return { output: markdown, detailHash: "...", sessionId: "..." };
-}
-
-async function continueSession(
-  sessionId: string,
-  message: string,
-): Promise<AgentRunResult> {
-  // ... continue multi-turn session ...
-  return { output: markdown, detailHash: "...", sessionId };
-}
-
-export const main = createAgent({ name: "my-agent", run, continue: continueSession });
-```
-
-## Internal Structure
-
-```
-src/
-├── index.ts
-├── run.ts                         createAgent entrypoint
-├── context.ts                     Thread chain walk, AgentContext builder
-├── extract.ts                     LLM structured extract fallback
-├── frontmatter.ts                 Frontmatter fast-path validation
-├── build-role-prompt.ts           Role definition → prompt text
-├── build-output-format-instruction.ts
-├── build-continuation-prompt.ts
-├── session-cache.ts               Per-thread/session ID persistence
-├── storage.ts                     CAS store, config, threads index
-├── schemas.ts                     Agent CAS schema registration
-└── types.ts                       AgentContext, AgentOptions, etc.
-```
-
-## Configuration
-
-Reads `config.yaml` and `.env` from the workflow storage root (`~/.uncaged/workflow` by default). See `@uncaged/workflow-protocol` for `WorkflowConfig` shape. Set via `uwf setup`.

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

@@ -21,6 +21,14 @@ function fail(message: string): never {
   throw new Error(message);
 }
 
+function readEdgePrompt(): string {
+  const value = process.env.UWF_EDGE_PROMPT;
+  if (value === undefined || value === "") {
+    fail("UWF_EDGE_PROMPT environment variable is required");
+  }
+  return value;
+}
+
 function walkChain(store: Store, schemas: AgentStore["schemas"], headHash: CasRef): ChainState {
   const headNode = store.get(headHash);
   if (headNode === null) {
@@ -115,11 +123,7 @@ async function loadWorkflow(store: Store, schemas: AgentStore["schemas"], workfl
  * Build agent execution context from thread head in threads.yaml.
  * Walks the CAS chain from head to StartNode and expands step outputs.
  */
-export async function buildContext(
-  threadId: ThreadId,
-  role: string,
-  edgePrompt: string,
-): Promise<AgentContext> {
+export async function buildContext(threadId: ThreadId, role: string): Promise<AgentContext> {
   const storageRoot = resolveStorageRoot();
   const agentStore = await createAgentStore(storageRoot);
   const { store, schemas } = agentStore;
@@ -138,6 +142,7 @@ export async function buildContext(
   }
 
   const steps = await buildHistory(store, chain.stepsNewestFirst);
+  const edgePrompt = readEdgePrompt();
   const isFirstVisit = !steps.some((s) => s.role === role);
 
   return {
@@ -167,7 +172,6 @@ export type BuildContextMeta = {
 export async function buildContextWithMeta(
   threadId: ThreadId,
   role: string,
-  edgePrompt: string,
 ): Promise<AgentContext & { meta: BuildContextMeta }> {
   const storageRoot = resolveStorageRoot();
   const agentStore = await createAgentStore(storageRoot);
@@ -187,6 +191,7 @@ export async function buildContextWithMeta(
   }
 
   const steps = await buildHistory(store, chain.stepsNewestFirst);
+  const edgePrompt = readEdgePrompt();
   const isFirstVisit = !steps.some((s) => s.role === role);
 
   return {

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

@@ -22,24 +22,16 @@ function agentLabel(name: string): string {
   return `uwf-${name}`;
 }
 
-const USAGE = "usage: <agent-cli> --thread <id> --role <role> --prompt <text>";
-
-function getNamedArg(argv: string[], name: string): string {
-  const idx = argv.indexOf(name);
-  if (idx === -1 || idx + 1 >= argv.length) {
-    return "";
+function parseArgv(argv: string[]): { threadId: ThreadId; role: string } {
+  const threadId = argv[2];
+  const role = argv[3];
+  if (threadId === undefined || threadId === "") {
+    fail("usage: <agent-cli> <thread-id> <role>");
   }
-  return argv[idx + 1];
-}
-
-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);
-  return { threadId: threadId as ThreadId, role, prompt };
+  if (role === undefined || role === "") {
+    fail("usage: <agent-cli> <thread-id> <role>");
+  }
+  return { threadId: threadId as ThreadId, role };
 }
 
 function runWithMessage<T>(label: string, fn: () => Promise<T>): Promise<T> {
@@ -111,11 +103,11 @@ async function persistStep(options: {
 
 export function createAgent(options: AgentOptions): () => Promise<void> {
   return async function main(): Promise<void> {
-    const { threadId, role, prompt } = parseArgv(process.argv);
+    const { threadId, role } = parseArgv(process.argv);
     const storageRoot = resolveStorageRoot();
     loadDotenv({ path: getEnvPath(storageRoot) });
 
-    const ctx = await runWithMessage("context", () => buildContextWithMeta(threadId, role, prompt));
+    const ctx = await runWithMessage("context", () => buildContextWithMeta(threadId, role));
 
     const roleDef = ctx.workflow.roles[role];
     if (roleDef === undefined) {

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

@@ -13,7 +13,7 @@ export type AgentContext = ModeratorContext & {
    */
   outputFormatInstruction: string;
   /**
-   * Edge prompt from the graph transition that led to this role (--prompt CLI arg).
+   * Edge prompt from the graph transition that led to this role (UWF_EDGE_PROMPT).
    * Always the real moderator instruction for this step.
    */
   edgePrompt: string;

packages/workflow-dashboard/README.md

@@ -1,84 +0,0 @@
-# @uncaged/workflow-dashboard
-
-Web graph editor for visualizing and editing workflow YAML definitions.
-
-## Overview
-
-A private alpha web app (not part of the runtime engine stack). Provides a React + `@xyflow/react` canvas for editing workflow roles, conditions, and graph transitions. Uses `@uncaged/workflow-protocol` types for validation and YAML round-tripping.
-
-Planned integration: local `uwf connect` over WebSocket to sync YAML between CLI and the browser editor. The REST API and Elysia backend are currently stubs for development.
-
-**Dependencies:** `@uncaged/workflow-protocol`, `@xyflow/react`, React 19, react-router v7, Vite 8, Tailwind CSS v4, Elysia
-
-## Installation
-
-Monorepo-only ( `"private": true` ). Not published to npm.
-
-```bash
-cd packages/workflow-dashboard
-bun install --no-cache
-```
-
-## CLI Usage
-
-Start the Vite dev server (port 3000):
-
-```bash
-cd packages/workflow-dashboard
-bun run dev
-```
-
-Build for production:
-
-```bash
-bun run build
-```
-
-Open `http://localhost:3000` in a browser.
-
-## Internal Structure
-
-```
-workflow-dashboard/
-├── server.ts                 Vite dev server entry (port 3000)
-├── vite.config.ts            Vite + React + Tailwind + Elysia plugin
-├── vite-dev.ts               Custom Vite plugin
-├── index.html
-├── components.json           shadcn configuration
-├── server/
-│   ├── api.ts                Elysia REST API (health + workflow CRUD stub)
-│   └── workflow.ts           Workflow file read/write + format conversion
-└── src/
-    ├── main.tsx              React DOM entry
-    ├── app.tsx               Root layout
-    ├── router.tsx            Hash-mode routes
-    ├── index.css
-    ├── lib/utils.ts          Tailwind cn() helper
-    ├── components/ui/        shadcn components (button, card, dialog, input, …)
-    ├── pages/
-    │   ├── home.tsx          Workflow list
-    │   ├── detail.tsx        Workflow detail view
-    │   └── editor.tsx        Full editor page
-    └── editor/               Core graph editor
-        ├── flow.tsx          FlowEditor component
-        ├── context.tsx       State (useSyncExternalStore + Immer)
-        ├── injection.ts      DI container
-        ├── type.ts             Internal editor types
-        ├── model/              Node/edge state model
-        ├── nodes/              Start, role, end node components
-        ├── edges/              Conditional edge rendering
-        ├── panel/              Toolbar, add/edit panels
-        ├── trans/              YAML ↔ graph conversion (trans-in, trans-out, validate)
-        ├── layout/             Auto-layout
-        └── utils/              Event helpers, click-outside hook
-```
-
-## Configuration
-
-| Setting | Default | Notes |
-|---------|---------|-------|
-| Dev server port | `3000` | Set in `server.ts` |
-| Workflow storage (dev) | `tmp/workflow/` | YAML files during development |
-| Path alias | `@/` → `src/` | Configured in `vite.config.ts` |
-
-No library API — this package is an application, not importable as a module.

packages/workflow-dashboard/package.json

@@ -31,10 +31,8 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
-    "@vitest/ui": "^4.1.7",
     "tailwindcss": "^4.2.4",
     "typescript": "^5.8.3",
-    "vite": "^8.0.13",
-    "vitest": "^4.1.7"
+    "vite": "^8.0.13"
   }
 }

packages/workflow-dashboard/src/editor/layout/__tests__/layout.test.ts

@@ -1,83 +0,0 @@
-import type { Edge, Node } from "@xyflow/react";
-import { describe, expect, it } from "vitest";
-import { LayoutLR } from "../index.js";
-
-function makeNode(id: string): Node {
-  return { id, type: "role", data: {}, position: { x: 0, y: 0 } } as Node;
-}
-
-function makeEdge(source: string, target: string): Edge {
-  return { id: `${source}-${target}`, source, target } as Edge;
-}
-
-describe("LayoutLR / assignLayers", () => {
-  it("1.1 Empty graph: start gets layer 0, end gets higher layer", () => {
-    const nodes = [makeNode("start"), makeNode("end")];
-    const result = LayoutLR(nodes, []);
-    const start = result.find((n) => n.id === "start");
-    const end = result.find((n) => n.id === "end");
-    // start has no position change necessarily, but positions should be assigned
-    expect(start).toBeDefined();
-    expect(end).toBeDefined();
-    // end should be to the right of start
-    expect((end?.position.x ?? 0) > (start?.position.x ?? 0)).toBe(true);
-  });
-
-  it("1.2 Linear chain: start → A → B → end — layers assigned in order", () => {
-    const nodes = [makeNode("start"), makeNode("A"), makeNode("B"), makeNode("end")];
-    const edges = [makeEdge("start", "A"), makeEdge("A", "B"), makeEdge("B", "end")];
-    const result = LayoutLR(nodes, edges);
-    const xOf = (id: string) => result.find((n) => n.id === id)?.position.x ?? 0;
-    expect(xOf("start") < xOf("A")).toBe(true);
-    expect(xOf("A") < xOf("B")).toBe(true);
-    expect(xOf("B") < xOf("end")).toBe(true);
-  });
-
-  it("1.3 Diamond: A and B share same layer", () => {
-    const nodes = [makeNode("start"), makeNode("A"), makeNode("B"), makeNode("C"), makeNode("end")];
-    const edges = [
-      makeEdge("start", "A"),
-      makeEdge("start", "B"),
-      makeEdge("A", "C"),
-      makeEdge("B", "C"),
-      makeEdge("C", "end"),
-    ];
-    const result = LayoutLR(nodes, edges);
-    const xOf = (id: string) => result.find((n) => n.id === id)?.position.x ?? 0;
-    expect(xOf("A")).toBe(xOf("B")); // same layer
-    expect(xOf("A") < xOf("C")).toBe(true);
-    expect(xOf("C") < xOf("end")).toBe(true);
-  });
-
-  it("1.4 Isolated node placed in middle layer (not layer 0, not end layer)", () => {
-    const nodes = [makeNode("start"), makeNode("A"), makeNode("isolated"), makeNode("end")];
-    const edges = [makeEdge("start", "A"), makeEdge("A", "end")];
-    const result = LayoutLR(nodes, edges);
-    const xOf = (id: string) => result.find((n) => n.id === id)?.position.x ?? 0;
-    const xIsolated = xOf("isolated");
-    expect(xIsolated > xOf("start")).toBe(true);
-    expect(xIsolated < xOf("end")).toBe(true);
-  });
-
-  it("1.5 end node is always last (highest x)", () => {
-    const nodes = [makeNode("start"), makeNode("A"), makeNode("B"), makeNode("end")];
-    const edges = [makeEdge("start", "A"), makeEdge("A", "B"), makeEdge("B", "end")];
-    const result = LayoutLR(nodes, edges);
-    const endX = result.find((n) => n.id === "end")?.position.x ?? 0;
-    for (const node of result) {
-      if (node.id !== "end") {
-        expect(node.position.x < endX).toBe(true);
-      }
-    }
-  });
-
-  it("1.6 start node is always first (x = 0 or smallest x)", () => {
-    const nodes = [makeNode("start"), makeNode("A"), makeNode("end")];
-    const edges = [makeEdge("start", "A"), makeEdge("A", "end")];
-    const result = LayoutLR(nodes, edges);
-    const startX = result.find((n) => n.id === "start")?.position.x ?? 0;
-    for (const node of result) {
-      expect(node.position.x >= startX).toBe(true);
-    }
-  });
-});

packages/workflow-dashboard/src/editor/layout/index.ts

@@ -43,65 +43,6 @@ function buildGraph(nodes: Node[], edges: Edge[]) {
   return { outgoing, incoming, inDegree };
 }
 
-function processTarget(
-  target: string,
-  newLayer: number,
-  layers: Map<string, number>,
-  inDegree: Map<string, number>,
-  queue: string[],
-): void {
-  const existingLayer = layers.get(target);
-  if (existingLayer === undefined) {
-    layers.set(target, newLayer);
-    inDegree.set(target, (inDegree.get(target) ?? 1) - 1);
-    if (inDegree.get(target) === 0) queue.push(target);
-  } else {
-    layers.set(target, Math.max(existingLayer, newLayer));
-  }
-}
-
-/**
- * BFS 分层（排除 end 节点，稍后单独处理）
- */
-function bfsLayers(
-  outgoing: Map<string, string[]>,
-  inDegree: Map<string, number>,
-  layers: Map<string, number>,
-): void {
-  const queue: string[] = ["start"];
-  while (queue.length > 0) {
-    const current = queue.shift() ?? "";
-    const currentLayer = layers.get(current) ?? 0;
-    for (const target of outgoing.get(current) ?? []) {
-      if (target === "end") continue;
-      processTarget(target, currentLayer + 1, layers, inDegree, queue);
-    }
-  }
-}
-
-/**
- * 处理孤立节点（没有被分配层级的非 start/end 节点），放在中间层
- */
-function placeIsolatedNodes(nodes: Node[], layers: Map<string, number>, maxLayer: number): void {
-  const middleLayer = Math.max(1, Math.floor((maxLayer + 1) / 2));
-  for (const node of nodes) {
-    if (node.id !== "start" && node.id !== "end" && !layers.has(node.id)) {
-      layers.set(node.id, middleLayer);
-    }
-  }
-}
-
-/**
- * 计算最大层级（排除 end 节点）
- */
-function maxLayerExcludingEnd(layers: Map<string, number>): number {
-  let max = 0;
-  for (const [id, layer] of layers) {
-    if (id !== "end") max = Math.max(max, layer);
-  }
-  return max;
-}
-
 /**
  * 使用拓扑排序将节点分层
  * - 'start' 节点固定在第 0 层
@@ -111,15 +52,62 @@ function maxLayerExcludingEnd(layers: Map<string, number>): number {
 function assignLayers(nodes: Node[], edges: Edge[]): Map<string, number> {
   const { outgoing, inDegree } = buildGraph(nodes, edges);
   const layers = new Map<string, number>();
+  const queue: string[] = [];
 
+  // 1. start 节点固定在第 0 层
   layers.set("start", 0);
-  bfsLayers(outgoing, inDegree, layers);
+  queue.push("start");
 
-  const afterBfsMax = maxLayerExcludingEnd(layers);
-  placeIsolatedNodes(nodes, layers, afterBfsMax);
+  // 2. BFS 分层（排除 end 节点，稍后单独处理）
+  while (queue.length > 0) {
+    const current = queue.shift() ?? "";
+    const currentLayer = layers.get(current) ?? 0;
 
-  const finalMax = maxLayerExcludingEnd(layers);
-  layers.set("end", finalMax + 1);
+    for (const target of outgoing.get(current) ?? []) {
+      // 跳过 end 节点，稍后处理
+      if (target === "end") continue;
+
+      const newLayer = currentLayer + 1;
+      const existingLayer = layers.get(target);
+
+      if (existingLayer === undefined) {
+        layers.set(target, newLayer);
+        inDegree.set(target, (inDegree.get(target) ?? 1) - 1);
+        if (inDegree.get(target) === 0) {
+          queue.push(target);
+        }
+      } else {
+        // 如果已有层级，取更大的值（确保所有前驱都在前面）
+        layers.set(target, Math.max(existingLayer, newLayer));
+      }
+    }
+  }
+
+  // 3. 找到当前最大层级
+  let maxLayer = 0;
+  for (const layer of layers.values()) {
+    maxLayer = Math.max(maxLayer, layer);
+  }
+
+  // 4. 处理孤立节点（没有被分配层级的非 start/end 节点）
+  // 把它们放在中间层
+  const middleLayer = Math.max(1, Math.floor((maxLayer + 1) / 2));
+  for (const node of nodes) {
+    if (node.id !== "start" && node.id !== "end" && !layers.has(node.id)) {
+      layers.set(node.id, middleLayer);
+    }
+  }
+
+  // 5. 重新计算最大层级（可能因为孤立节点而变化）
+  maxLayer = 0;
+  for (const [id, layer] of layers) {
+    if (id !== "end") {
+      maxLayer = Math.max(maxLayer, layer);
+    }
+  }
+
+  // 6. end 节点固定在最后一层
+  layers.set("end", maxLayer + 1);
 
   return layers;
 }

packages/workflow-dashboard/src/editor/model/handlers.ts

@@ -30,24 +30,23 @@ export const handlers = define.memoize((use, model) => {
     });
   };
 
-  function isProtectedNode(node: AnyWorkNode): boolean {
-    return node.type === "start" || node.type === "end";
-  }
-
-  function isFirstConditionalSibling(
-    edge: { id: string; source: string; type: string | null },
-    allEdges: { id: string; source: string; type: string | null }[],
-  ): boolean {
-    if (edge.type !== "conditional") return false;
-    const siblings = allEdges.filter((e) => e.source === edge.source && e.type === "conditional");
-    return siblings.length >= 2 && siblings[0].id === edge.id;
-  }
-
   const onBeforeDelete: OnBeforeDelete<AnyWorkNode> = async ({ nodes, edges }) => {
-    if (nodes.some(isProtectedNode)) return false;
+    for (const node of nodes) {
+      if (node.type === "start" || node.type === "end") {
+        return false;
+      }
+    }
     if (edges.length > 0) {
       const allEdges = use(edgesModel)[0];
-      if (edges.some((e) => isFirstConditionalSibling(e, allEdges))) return false;
+      for (const edge of edges) {
+        if (edge.type !== "conditional") continue;
+        const siblings = allEdges.filter(
+          (e) => e.source === edge.source && e.type === "conditional",
+        );
+        if (siblings.length >= 2 && siblings[0].id === edge.id) {
+          return false;
+        }
+      }
     }
     model.startTransaction();
     return true;
@@ -97,28 +96,25 @@ export const handlers = define.memoize((use, model) => {
     use(editNodeViewModel)[1].cancel();
   }
 
-  function handleEscape() {
-    const [addView, addViewActions] = use(addNodeViewModel);
-    const [editView, editViewActions] = use(editNodeViewModel);
-    if (addView) addViewActions.cancel();
-    if (editView) editViewActions.cancel();
-  }
-
-  function handleUndoRedo(event: React.KeyboardEvent<HTMLDivElement>) {
-    if (event.code === "KeyZ" && (event.ctrlKey || event.metaKey)) {
-      if (event.shiftKey) model.redo();
-      else model.undo();
-    } else if (event.code === "KeyY" && (event.ctrlKey || event.metaKey)) {
-      model.redo();
-    }
-  }
-
   function handleKeyDown(event: React.KeyboardEvent<HTMLDivElement>) {
     if (event.code === "Escape") {
-      handleEscape();
+      const [addView, addViewActions] = use(addNodeViewModel);
+      const [editView, editViewActions] = use(editNodeViewModel);
+      if (addView) addViewActions.cancel();
+      if (editView) editViewActions.cancel();
       return;
     }
-    handleUndoRedo(event);
+
+    if (event.code === "KeyZ") {
+      if (event.ctrlKey || event.metaKey) {
+        if (event.shiftKey) model.redo();
+        else model.undo();
+      }
+    } else if (event.code === "KeyY") {
+      if (event.ctrlKey || event.metaKey) {
+        model.redo();
+      }
+    }
   }
 
   function loadSteps(steps: WorkFlowSteps) {

packages/workflow-dashboard/src/editor/panel/add-node.tsx

@@ -10,15 +10,16 @@ import {
 import { Input } from "../../components/ui/input.tsx";
 import { Label } from "../../components/ui/label.tsx";
 import { Textarea } from "../../components/ui/textarea.tsx";
-import { addNodeViewModel } from "../model/index.ts";
+import { type AddNodeState, addNodeViewModel } from "../model/index.ts";
 import type { RoleNodeData } from "../type.ts";
 
 type FormProps = {
+  state: AddNodeState;
   onSubmit: (params: { data: RoleNodeData }) => void;
   onCancel: () => void;
 };
 
-function Form({ onSubmit, onCancel }: FormProps): ReactNode {
+function Form({ state, onSubmit, onCancel }: FormProps): ReactNode {
   const [name, setName] = useState("新角色");
   const [description, setDescription] = useState("");
   const [identity, setIdentity] = useState("");
@@ -136,7 +137,7 @@ export function AddNodeDialog(): ReactNode {
       }}
     >
       <DialogContent showCloseButton={false} className="sm:max-w-md">
-        {state && <Form onSubmit={commit} onCancel={cancel} />}
+        {state && <Form state={state} onSubmit={commit} onCancel={cancel} />}
       </DialogContent>
     </Dialog>
   );

packages/workflow-dashboard/src/editor/trans/__tests__/trans-in.test.ts

@@ -1,109 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { transIn } from "../trans-in.js";
-import type { WorkFlowStep } from "../type.js";
-
-function makeStep(name: string, transitions: WorkFlowStep["transitions"]): WorkFlowStep {
-  return {
-    role: {
-      name,
-      description: "",
-      identity: "",
-      prepare: "",
-      execute: "",
-      report: "",
-    },
-    transitions,
-  };
-}
-
-describe("transIn", () => {
-  it("4.1 Empty steps → start + end nodes, no edges", () => {
-    const { nodes, edges } = transIn([]);
-    expect(nodes).toHaveLength(2);
-    expect(nodes.find((n) => n.id === "start")).toBeDefined();
-    expect(nodes.find((n) => n.id === "end")).toBeDefined();
-    expect(edges).toHaveLength(0);
-  });
-
-  it("4.2 Single step with no END transition → start→role edge exists", () => {
-    const steps = [makeStep("A", [])];
-    const { nodes, edges } = transIn(steps);
-    expect(nodes).toHaveLength(3); // start, end, role-A
-    const startEdge = edges.find((e) => e.source === "start");
-    expect(startEdge).toBeDefined();
-    const roleNode = nodes.find((n) => n.type === "role");
-    expect(startEdge?.target).toBe(roleNode?.id);
-  });
-
-  it("4.3 Single step with END transition → edge to end node exists", () => {
-    const steps = [makeStep("A", [{ condition: null, target: "END" }])];
-    const { edges } = transIn(steps);
-    const endEdge = edges.find((e) => e.target === "end");
-    expect(endEdge).toBeDefined();
-  });
-
-  it("4.4 Two steps with default transitions chain", () => {
-    const steps = [
-      makeStep("A", [{ condition: null, target: "B" }]),
-      makeStep("B", [{ condition: null, target: "END" }]),
-    ];
-    const { edges } = transIn(steps);
-    // Should have start→A, A→B, B→end
-    expect(edges.find((e) => e.source === "start")).toBeDefined();
-    const nodeAId = edges.find((e) => e.source === "start")?.target;
-    expect(edges.find((e) => e.source === nodeAId && e.target !== "end")).toBeDefined();
-    expect(edges.find((e) => e.target === "end")).toBeDefined();
-    // No conditional edges
-    expect(edges.every((e) => e.type !== "conditional")).toBe(true);
-  });
-
-  it("4.5 Step with multiple transitions → conditional edges", () => {
-    const steps = [
-      makeStep("A", [
-        { condition: null, target: "B" },
-        { condition: "x>0", target: "C" },
-      ]),
-      makeStep("B", []),
-      makeStep("C", []),
-    ];
-    const { edges } = transIn(steps);
-    const nodeAId = edges.find((e) => e.source === "start")?.target;
-    const outEdges = edges.filter((e) => e.source === nodeAId);
-    expect(outEdges.every((e) => e.type === "conditional")).toBe(true);
-    // else-branch has empty condition
-    const elseEdge = outEdges.find(
-      (e) => (e as { data?: { condition?: string } }).data?.condition === "",
-    );
-    expect(elseEdge).toBeDefined();
-    // if-branch has condition
-    const ifEdge = outEdges.find(
-      (e) => (e as { data?: { condition?: string } }).data?.condition === "x>0",
-    );
-    expect(ifEdge).toBeDefined();
-  });
-
-  it("4.6 With 1 incoming edge: targetHandle = 'input'; with 2: first gets 'input'", () => {
-    const steps = [
-      makeStep("A", [{ condition: null, target: "END" }]),
-      makeStep("B", [{ condition: null, target: "END" }]),
-    ];
-    const { edges } = transIn(steps);
-    // start→A and start→B; end has 2 incoming edges
-    const incomingToEnd = edges.filter((e) => e.target === "end");
-    expect(incomingToEnd[0].targetHandle).toBe("input");
-  });
-
-  it("4.7 Same role name maps to same node id across steps", () => {
-    const steps = [
-      makeStep("A", [{ condition: null, target: "B" }]),
-      makeStep("B", [{ condition: null, target: "A" }]),
-    ];
-    const { edges } = transIn(steps);
-    const aId = edges.find((e) => e.source === "start")?.target;
-    // B→A edge target should be same node as start→A edge target
-    const bToAEdge = edges.find(
-      (e) => e.source !== "start" && e.target === aId && e.target !== "end",
-    );
-    expect(bToAEdge).toBeDefined();
-  });
-});

packages/workflow-dashboard/src/editor/trans/__tests__/validate.test.ts

@@ -1,137 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { AnyWorkEdge, AnyWorkNode } from "../../type.js";
-import { validate } from "../validate.js";
-
-function roleNode(id: string): AnyWorkNode {
-  return {
-    id,
-    type: "role",
-    data: { name: id, description: "", identity: "", prepare: "", execute: "", report: "" },
-    position: { x: 0, y: 0 },
-  } as AnyWorkNode;
-}
-
-function startNode(): AnyWorkNode {
-  return {
-    id: "start",
-    type: "start",
-    data: { label: "Start" },
-    position: { x: 0, y: 0 },
-  } as AnyWorkNode;
-}
-
-function endNode(): AnyWorkNode {
-  return {
-    id: "end",
-    type: "end",
-    data: { label: "End" },
-    position: { x: 0, y: 0 },
-  } as AnyWorkNode;
-}
-
-function defaultEdge(source: string, target: string): AnyWorkEdge {
-  return { id: `${source}-${target}`, source, target, animated: true } as AnyWorkEdge;
-}
-
-function conditionalEdge(source: string, target: string, condition: string): AnyWorkEdge {
-  return {
-    id: `${source}-${target}-cond`,
-    source,
-    target,
-    type: "conditional" as const,
-    data: { condition },
-    animated: true,
-  } as AnyWorkEdge;
-}
-
-// Helper: build a minimal valid graph with 2 role nodes for validateRoleNodes tests
-function baseNodes(...roles: AnyWorkNode[]): AnyWorkNode[] {
-  return [startNode(), ...roles, endNode()];
-}
-
-describe("validateRoleNodes (via validate)", () => {
-  it("5.1 Role node with no incoming edge → error about missing input", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const nodes = baseNodes(n1, n2);
-    // n1 has no incoming, n2 has incoming+outgoing
-    const edges = [defaultEdge("start", "n2"), defaultEdge("n1", "end"), defaultEdge("n2", "end")];
-    const result = validate(nodes, edges);
-    const nodeErrors = result.errors.filter((e) => e.nodeId === "n1");
-    expect(nodeErrors.some((e) => e.message.includes("缺少输入连接"))).toBe(true);
-  });
-
-  it("5.2 Role node with no outgoing edge → error about missing output", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const nodes = baseNodes(n1, n2);
-    const edges = [
-      defaultEdge("start", "n1"),
-      defaultEdge("start", "n2"),
-      defaultEdge("n2", "end"),
-      // n1 has no outgoing
-    ];
-    const result = validate(nodes, edges);
-    const nodeErrors = result.errors.filter((e) => e.nodeId === "n1");
-    expect(nodeErrors.some((e) => e.message.includes("缺少输出连接"))).toBe(true);
-  });
-
-  it("5.3 Empty condition on non-first conditional edge → error", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const n3 = roleNode("n3");
-    const nodes = baseNodes(n1, n2, n3);
-    const edges = [
-      defaultEdge("start", "n1"),
-      conditionalEdge("n1", "n2", ""), // else-branch (index 0) - exempt
-      conditionalEdge("n1", "n3", ""), // if-branch (index 1) - empty condition → error
-      defaultEdge("n2", "end"),
-      defaultEdge("n3", "end"),
-    ];
-    const result = validate(nodes, edges);
-    expect(result.errors.some((e) => e.message.includes("条件表达式不能为空"))).toBe(true);
-  });
-
-  it("5.4 Mix of conditional and non-conditional outgoing → error", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const n3 = roleNode("n3");
-    const nodes = baseNodes(n1, n2, n3);
-    const edges = [
-      defaultEdge("start", "n1"),
-      conditionalEdge("n1", "n2", "x>0"),
-      defaultEdge("n1", "n3"), // mix → error
-      defaultEdge("n2", "end"),
-      defaultEdge("n3", "end"),
-    ];
-    const result = validate(nodes, edges);
-    expect(result.errors.some((e) => e.message.includes("所有出边必须附带条件"))).toBe(true);
-  });
-
-  it("5.5 Valid role node (1 in, 1 out default) → no errors for that node", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const nodes = baseNodes(n1, n2);
-    const edges = [defaultEdge("start", "n1"), defaultEdge("n1", "n2"), defaultEdge("n2", "end")];
-    const result = validate(nodes, edges);
-    const roleErrors = result.errors.filter((e) => e.nodeId === "n1" || e.nodeId === "n2");
-    expect(roleErrors).toHaveLength(0);
-  });
-
-  it("5.6 Valid role node (1 in, 2 conditional out with conditions) → no errors", () => {
-    const n1 = roleNode("n1");
-    const n2 = roleNode("n2");
-    const n3 = roleNode("n3");
-    const nodes = baseNodes(n1, n2, n3);
-    const edges = [
-      defaultEdge("start", "n1"),
-      conditionalEdge("n1", "n2", ""), // else-branch
-      conditionalEdge("n1", "n3", "x>0"), // if-branch
-      defaultEdge("n2", "end"),
-      defaultEdge("n3", "end"),
-    ];
-    const result = validate(nodes, edges);
-    const n1Errors = result.errors.filter((e) => e.nodeId === "n1");
-    expect(n1Errors).toHaveLength(0);
-  });
-});

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

@@ -28,109 +28,6 @@ function assignHandles(
   }
 }
 
-function buildNodeMap(
-  steps: WorkFlowStep[],
-  nodes: AnyWorkNode[],
-): { nameToId: Map<string, string>; idToOrder: Map<string, number> } {
-  const nameToId = new Map<string, string>();
-  const idToOrder = new Map<string, number>();
-  nameToId.set("END", "end");
-  idToOrder.set("start", -1);
-  idToOrder.set("end", steps.length);
-  for (let si = 0; si < steps.length; si++) {
-    const step = steps[si];
-    const nodeId = `n${uuid()}`;
-    nameToId.set(step.role.name, nodeId);
-    idToOrder.set(nodeId, si);
-    nodes.push({ id: nodeId, type: "role", data: { ...step.role }, position: { x: 0, y: 0 } });
-  }
-  return { nameToId, idToOrder };
-}
-
-function sortTransitions(step: WorkFlowStep): WorkFlowStep["transitions"] {
-  if (step.transitions.length <= 1) return step.transitions;
-  return [...step.transitions].sort((a, b) => {
-    if (a.condition === null && b.condition !== null) return -1;
-    if (a.condition !== null && b.condition === null) return 1;
-    return 0;
-  });
-}
-
-function buildStepEdges(
-  sourceId: string,
-  step: WorkFlowStep,
-  nameToId: Map<string, string>,
-): { elseEdges: AnyWorkEdge[]; ifEdges: AnyWorkEdge[] } {
-  const hasMultiple = step.transitions.length > 1;
-  const sorted = sortTransitions(step);
-  const elseEdges: AnyWorkEdge[] = [];
-  const ifEdges: AnyWorkEdge[] = [];
-
-  for (let i = 0; i < sorted.length; i++) {
-    const t = sorted[i];
-    const targetId = nameToId.get(t.target);
-    if (!targetId) continue;
-    const edgeId = `e-${sourceId}-${targetId}-${i}`;
-    if (hasMultiple || t.condition !== null) {
-      const edge: ConditionalEdge = {
-        id: edgeId,
-        source: sourceId,
-        target: targetId,
-        sourceHandle: "output",
-        targetHandle: "input",
-        type: "conditional",
-        data: { condition: t.condition ?? "" },
-        animated: true,
-      };
-      if (hasMultiple && i === 0) elseEdges.push(edge);
-      else ifEdges.push(edge);
-    } else {
-      elseEdges.push({
-        id: edgeId,
-        source: sourceId,
-        target: targetId,
-        sourceHandle: "output",
-        targetHandle: "input",
-        animated: true,
-      });
-    }
-  }
-  return { elseEdges, ifEdges };
-}
-
-function pushStepEdges(
-  edges: AnyWorkEdge[],
-  elseEdges: AnyWorkEdge[],
-  ifEdges: AnyWorkEdge[],
-  idToOrder: Map<string, number>,
-): void {
-  for (const e of elseEdges) edges.push({ ...e, sourceHandle: "output" });
-  if (ifEdges.length > 0) {
-    const ifHandles = ["output-top", "output-bottom"] as const;
-    const sorted = [...ifEdges].sort(
-      (a, b) => (idToOrder.get(b.target) ?? 0) - (idToOrder.get(a.target) ?? 0),
-    );
-    for (let i = 0; i < sorted.length; i++) {
-      edges.push({ ...sorted[i], sourceHandle: ifHandles[i % ifHandles.length] });
-    }
-  }
-}
-
-function assignTargetHandles(edges: AnyWorkEdge[], idToOrder: Map<string, number>): void {
-  const incomingByTarget = new Map<string, number[]>();
-  for (let i = 0; i < edges.length; i++) {
-    const target = edges[i].target;
-    if (!incomingByTarget.has(target)) incomingByTarget.set(target, []);
-    incomingByTarget.get(target)?.push(i);
-  }
-  for (const indices of incomingByTarget.values()) {
-    indices.sort(
-      (a, b) => (idToOrder.get(edges[a].source) ?? 0) - (idToOrder.get(edges[b].source) ?? 0),
-    );
-    assignHandles(indices, edges, IN_HANDLES, "targetHandle");
-  }
-}
-
 export function transIn(steps: WorkFlowStep[]): Result {
   const startNode: AnyWorkNode = {
     id: "start",
@@ -145,12 +42,30 @@ export function transIn(steps: WorkFlowStep[]): Result {
     position: { x: 250, y: 0 },
   };
 
-  if (steps.length === 0) return { nodes: [startNode, endNode], edges: [] };
+  if (steps.length === 0) {
+    return { nodes: [startNode, endNode], edges: [] };
+  }
 
   const nodes: AnyWorkNode[] = [startNode, endNode];
   const edges: AnyWorkEdge[] = [];
+  const nameToId = new Map<string, string>();
+  const idToOrder = new Map<string, number>();
+  nameToId.set("END", "end");
+  idToOrder.set("start", -1);
+  idToOrder.set("end", steps.length);
 
-  const { nameToId, idToOrder } = buildNodeMap(steps, nodes);
+  for (let si = 0; si < steps.length; si++) {
+    const step = steps[si];
+    const nodeId = `n${uuid()}`;
+    nameToId.set(step.role.name, nodeId);
+    idToOrder.set(nodeId, si);
+    nodes.push({
+      id: nodeId,
+      type: "role",
+      data: { ...step.role },
+      position: { x: 0, y: 0 },
+    });
+  }
 
   const firstStepId = nameToId.get(steps[0].role.name) ?? "";
   edges.push({
@@ -164,11 +79,88 @@ export function transIn(steps: WorkFlowStep[]): Result {
 
   for (const step of steps) {
     const sourceId = nameToId.get(step.role.name) ?? "";
-    const { elseEdges, ifEdges } = buildStepEdges(sourceId, step, nameToId);
-    pushStepEdges(edges, elseEdges, ifEdges, idToOrder);
+    const _sourceOrder = idToOrder.get(sourceId) ?? 0;
+    const hasMultipleTransitions = step.transitions.length > 1;
+
+    const sorted = hasMultipleTransitions
+      ? [...step.transitions].sort((a, b) => {
+          if (a.condition === null && b.condition !== null) return -1;
+          if (a.condition !== null && b.condition === null) return 1;
+          return 0;
+        })
+      : step.transitions;
+
+    const elseEdges: AnyWorkEdge[] = [];
+    const ifEdges: AnyWorkEdge[] = [];
+
+    for (let i = 0; i < sorted.length; i++) {
+      const t = sorted[i];
+      const targetId = nameToId.get(t.target);
+      if (!targetId) continue;
+
+      const edgeId = `e-${sourceId}-${targetId}-${i}`;
+
+      if (hasMultipleTransitions || t.condition !== null) {
+        const edge: ConditionalEdge = {
+          id: edgeId,
+          source: sourceId,
+          target: targetId,
+          sourceHandle: "output",
+          targetHandle: "input",
+          type: "conditional",
+          data: { condition: t.condition ?? "" },
+          animated: true,
+        };
+        if (hasMultipleTransitions && i === 0) {
+          elseEdges.push(edge);
+        } else {
+          ifEdges.push(edge);
+        }
+      } else {
+        elseEdges.push({
+          id: edgeId,
+          source: sourceId,
+          target: targetId,
+          sourceHandle: "output",
+          targetHandle: "input",
+          animated: true,
+        });
+      }
+    }
+
+    // out: else → output (right); if → sort by target order desc (rightmost first), then top/bottom
+    for (const e of elseEdges) {
+      edges.push({ ...e, sourceHandle: "output" });
+    }
+    if (ifEdges.length > 0) {
+      const sortedIf = [...ifEdges].sort((a, b) => {
+        const oa = idToOrder.get(a.target) ?? 0;
+        const ob = idToOrder.get(b.target) ?? 0;
+        return ob - oa;
+      });
+      const ifHandles = ["output-top", "output-bottom"] as const;
+      for (let i = 0; i < sortedIf.length; i++) {
+        edges.push({ ...sortedIf[i], sourceHandle: ifHandles[i % ifHandles.length] });
+      }
+    }
   }
 
-  assignTargetHandles(edges, idToOrder);
+  // in: group by target, sort by source order asc (leftmost first), assign input > input-top > input-bottom
+  const incomingByTarget = new Map<string, number[]>();
+  for (let i = 0; i < edges.length; i++) {
+    const target = edges[i].target;
+    if (!incomingByTarget.has(target)) incomingByTarget.set(target, []);
+    incomingByTarget.get(target)?.push(i);
+  }
+
+  for (const indices of incomingByTarget.values()) {
+    indices.sort((a, b) => {
+      const oa = idToOrder.get(edges[a].source) ?? 0;
+      const ob = idToOrder.get(edges[b].source) ?? 0;
+      return oa - ob;
+    });
+    assignHandles(indices, edges, IN_HANDLES, "targetHandle");
+  }
 
   return { nodes, edges };
 }

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

@@ -91,36 +91,6 @@ function validateEndNode(
   }
 }
 
-function hasEmptyConditionOnIfEdge(conditionalEdges: AnyWorkEdge[]): boolean {
-  return conditionalEdges.slice(1).some((edge) => {
-    const cond = (edge as ConditionalEdge).data?.condition?.trim();
-    return !cond;
-  });
-}
-
-function validateRoleNodeEdges(
-  node: AnyWorkNode,
-  outEdges: AnyWorkEdge[],
-  inEdges: AnyWorkEdge[],
-  errors: ValidationError[],
-): void {
-  if (inEdges.length === 0) {
-    errors.push({ nodeId: node.id, message: "角色节点缺少输入连接" });
-  }
-  if (outEdges.length === 0) {
-    errors.push({ nodeId: node.id, message: "角色节点缺少输出连接" });
-    return;
-  }
-  if (outEdges.length <= 1) return;
-
-  const conditionalEdges = outEdges.filter((e) => e.type === "conditional");
-  if (conditionalEdges.length !== outEdges.length) {
-    errors.push({ nodeId: node.id, message: "多输出节点的所有出边必须附带条件" });
-  } else if (hasEmptyConditionOnIfEdge(conditionalEdges)) {
-    errors.push({ nodeId: node.id, message: "条件边的条件表达式不能为空" });
-  }
-}
-
 function validateRoleNodes(
   roleNodes: AnyWorkNode[],
   outgoing: Map<string, AnyWorkEdge[]>,
@@ -128,7 +98,31 @@ function validateRoleNodes(
   errors: ValidationError[],
 ): void {
   for (const node of roleNodes) {
-    validateRoleNodeEdges(node, outgoing.get(node.id) ?? [], incoming.get(node.id) ?? [], errors);
+    const inEdges = incoming.get(node.id) ?? [];
+    const outEdges = outgoing.get(node.id) ?? [];
+
+    if (inEdges.length === 0) {
+      errors.push({ nodeId: node.id, message: "角色节点缺少输入连接" });
+    }
+    if (outEdges.length === 0) {
+      errors.push({ nodeId: node.id, message: "角色节点缺少输出连接" });
+    }
+
+    if (outEdges.length > 1) {
+      const conditionalEdges = outEdges.filter((e) => e.type === "conditional");
+      if (conditionalEdges.length !== outEdges.length) {
+        errors.push({ nodeId: node.id, message: "多输出节点的所有出边必须附带条件" });
+      } else {
+        const ifEdges = conditionalEdges.slice(1);
+        for (const edge of ifEdges) {
+          const condEdge = edge as ConditionalEdge;
+          if (!condEdge.data?.condition?.trim()) {
+            errors.push({ nodeId: node.id, message: "条件边的条件表达式不能为空" });
+            break;
+          }
+        }
+      }
+    }
   }
 }
 

packages/workflow-dashboard/vitest.config.ts

@@ -1,15 +0,0 @@
-import path from "node:path";
-import { defineConfig } from "vitest/config";
-
-// biome-ignore lint/style/noDefaultExport: Vitest loads config from default export.
-export default defineConfig({
-  test: {
-    environment: "node",
-    include: ["src/**/__tests__/**/*.test.ts"],
-  },
-  resolve: {
-    alias: {
-      "@": path.resolve(import.meta.dirname, "./src"),
-    },
-  },
-});

packages/workflow-moderator/README.md

@@ -1,60 +0,0 @@
-# @uncaged/workflow-moderator
-
-JSONata-based graph evaluator — determines the next role or `$END` with zero LLM cost.
-
-## Overview
-
-The moderator (Layer 1) walks the workflow graph from the current role. For each outgoing transition it evaluates an optional JSONata condition against `ModeratorContext` (start prompt + prior step outputs). The first truthy transition wins; its target role and edge prompt are returned. When no transition matches, the workflow ends (`$END`).
-
-**Dependencies:** `@uncaged/workflow-protocol`, `jsonata`
-
-## Installation
-
-```bash
-bun add @uncaged/workflow-moderator
-```
-
-## API
-
-### Functions
-
-```typescript
-function evaluate(
-  workflow: WorkflowPayload,
-  context: ModeratorContext,
-): Promise<Result<EvaluateResult, Error>>
-```
-
-Returns `{ ok: true, value: { role, prompt } }` where `role` is the next role name or `"$END"`, and `prompt` is the edge instruction for the agent.
-
-### Types
-
-```typescript
-type EvaluateResult = {
-  role: string;
-  prompt: string;
-};
-```
-
-The `Result<T, E>` type is local to this package (`{ ok: true; value: T } | { ok: false; error: E }`), not re-exported from `index.ts`.
-
-## Usage
-
-```typescript
-import { evaluate } from "@uncaged/workflow-moderator";
-import type { ModeratorContext, WorkflowPayload } from "@uncaged/workflow-protocol";
-
-const result = await evaluate(workflow, context);
-if (result.ok && result.value.role !== "$END") {
-  console.log(`Next role: ${result.value.role}, prompt: ${result.value.prompt}`);
-}
-```
-
-## Internal Structure
-
-```
-src/
-├── index.ts      Public exports
-├── evaluate.ts   Graph walk + JSONata condition evaluation
-└── types.ts      EvaluateResult, Result
-```

packages/workflow-protocol/README.md

@@ -1,193 +0,0 @@
-# @uncaged/workflow-protocol
-
-Shared TypeScript types and JSON Schema constants for the workflow engine.
-
-## Overview
-
-This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@uncaged/json-cas`.
-
-**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`
-
-## Installation
-
-```bash
-bun add @uncaged/workflow-protocol
-```
-
-## API
-
-All exports come from `src/index.ts`.
-
-### JSON Schema constants
-
-```typescript
-START_NODE_SCHEMA: JSONSchema
-STEP_NODE_SCHEMA: JSONSchema
-WORKFLOW_SCHEMA: JSONSchema
-```
-
-### Core identifiers
-
-```typescript
-type CasRef = string      // XXH64 hash, 13-char Crockford Base32
-type ThreadId = string    // ULID, 26-char Crockford Base32
-type WorkflowName = string
-type RoleName = string
-```
-
-### Workflow definition
-
-```typescript
-type RoleDefinition = {
-  description: string;
-  goal: string;
-  capabilities: string[];
-  procedure: string;
-  output: string;
-  frontmatter: CasRef;
-};
-
-type Transition = {
-  role: string;
-  condition: string | null;
-  prompt: string;
-};
-
-type ConditionDefinition = {
-  description: string;
-  expression: string;
-};
-
-type WorkflowPayload = {
-  name: string;
-  description: string;
-  roles: Record<string, RoleDefinition>;
-  conditions: Record<string, ConditionDefinition>;
-  graph: Record<string, Transition[]>;
-};
-```
-
-### Thread nodes
-
-```typescript
-type StepRecord = {
-  role: string;
-  output: CasRef;
-  detail: CasRef;
-  agent: string;
-  edgePrompt: string;
-};
-
-type StartNodePayload = {
-  workflow: CasRef;
-  prompt: string;
-};
-
-type StepNodePayload = StepRecord & {
-  start: CasRef;
-  prev: CasRef | null;
-};
-```
-
-### Moderator context
-
-```typescript
-type StepContext = Omit<StepRecord, "output"> & { output: unknown };
-
-type ModeratorContext = {
-  start: StartNodePayload;
-  steps: StepContext[];
-};
-```
-
-### Configuration
-
-```typescript
-type ProviderAlias = string;
-type ModelAlias = string;
-type AgentAlias = string;
-
-type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
-type ModelConfig = {
-  provider: ProviderAlias;
-  name: string;
-};
-
-type AgentConfig = {
-  command: string;
-  args: string[];
-};
-
-type WorkflowConfig = {
-  providers: Record<ProviderAlias, ProviderConfig>;
-  models: Record<ModelAlias, ModelConfig>;
-  agents: Record<AgentAlias, AgentConfig>;
-  defaultAgent: AgentAlias;
-  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
-  defaultModel: ModelAlias;
-  modelOverrides: Record<Scenario, ModelAlias> | null;
-};
-```
-
-### CLI output types
-
-```typescript
-type StartOutput = { workflow: CasRef; thread: ThreadId };
-
-type StepOutput = {
-  workflow: CasRef;
-  thread: ThreadId;
-  head: CasRef;
-  done: boolean;
-};
-
-type StepEntry = {
-  hash: CasRef;
-  role: string;
-  output: unknown;
-  detail: CasRef;
-  agent: string;
-  timestamp: number;
-};
-
-type StartEntry = {
-  hash: CasRef;
-  workflow: CasRef;
-  prompt: string;
-  timestamp: number;
-};
-
-type ThreadStepsOutput = {
-  thread: ThreadId;
-  workflow: CasRef;
-  steps: [StartEntry, ...StepEntry[]];
-};
-
-type ThreadForkOutput = {
-  thread: ThreadId;
-  forkedFrom: { step: CasRef };
-};
-
-type ThreadListItem = {
-  thread: ThreadId;
-  workflow: CasRef;
-  head: CasRef;
-};
-
-type ThreadsIndex = Record<ThreadId, CasRef>;
-
-type Scenario = string;
-```
-
-## Internal Structure
-
-```
-src/
-├── index.ts      Public re-exports
-├── types.ts      All type definitions
-└── schemas.ts    START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA
-```
-
-## Configuration
-
-This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-agent-kit` (`loadWorkflowConfig`).

packages/workflow-protocol/src/index.ts

@@ -15,8 +15,6 @@ export type {
   ProviderConfig,
   RoleDefinition,
   RoleName,
-  RunningThreadItem,
-  RunningThreadsOutput,
   Scenario,
   StartEntry,
   StartNodePayload,

packages/workflow-protocol/src/types.ts

@@ -84,7 +84,6 @@ export type StepOutput = {
   thread: ThreadId;
   head: CasRef;
   done: boolean;
-  background: boolean | null;
 };
 
 /** uwf thread steps — single step entry */
@@ -127,19 +126,6 @@ export type ThreadListItem = {
   head: CasRef;
 };
 
-/** uwf thread running — single running thread entry */
-export type RunningThreadItem = {
-  thread: ThreadId;
-  workflow: CasRef;
-  pid: number;
-  startedAt: number;
-};
-
-/** uwf thread running output */
-export type RunningThreadsOutput = {
-  threads: RunningThreadItem[];
-};
-
 // ── 4.6 配置 ────────────────────────────────────────────────────────
 
 /** Alias types for config references */

packages/workflow-util/README.md

@@ -1,145 +1,32 @@
 # @uncaged/workflow-util
 
-Shared utilities: encoding, IDs, logging, frontmatter parsing, storage paths, and CLI reference generation.
+Shared utilities: encoding, IDs, logging, storage paths, and ref-field normalization.
 
-## Overview
+## What This Package Does
 
-Layer 1 shared infrastructure used across CLI, agent-kit, and agent packages. Provides Crockford Base32 encoding, ULID generation, structured logging with fixed 8-char tags, frontmatter markdown parsing/validation, process-level debug logging, and helpers for the default workflow data directory.
+It provides filesystem-safe Base32 and ULID generation, the structured logger used across packages, helpers for the default workflow data directory and global CAS path, and utilities to merge/normalize `refs` on steps. It re-exports `ok`/`err` from protocol for convenience.
 
-**Dependencies:** none (standalone)
+## Key Exports
 
-## Installation
+From `src/index.ts`:
 
-```bash
-bun add @uncaged/workflow-util
-```
+- **Base32:** `CROCKFORD_BASE32_ALPHABET`, `decodeCrockfordBase32Bits`, `decodeCrockfordToUint64`, `encodeCrockfordBase32Bits`, `encodeUint64AsCrockford`
+- **Logger:** `createLogger`
+- **Refs:** `mergeRefsWithContentHash`, `normalizeRefsField`
+- **Result:** `ok`, `err` (from `@uncaged/workflow-protocol`)
+- **Paths:** `getDefaultWorkflowStorageRoot`, `getGlobalCasDir`
+- **ULID:** `generateUlid`
+- **Types:** `CreateLoggerOptions`, `LogFn`, `LoggerSink`, `Result`
 
-## API
+## Dependencies
 
-All exports come from `src/index.ts`.
-
-### Encoding and IDs
-
-```typescript
-function encodeUint64AsCrockford(value: bigint): string
-function generateUlid(nowMs: number): string
-```
-
-### Logging
-
-```typescript
-function createLogger(options?: { sink: { kind: "stderr" } }): LogFn
-
-type LogFn = (tag: string, message: string) => void
-// CreateLoggerOptions and LoggerSink are internal types
-```
-
-### Process logger
-
-```typescript
-function createProcessLogger(options: CreateProcessLoggerOptions): ProcessLogger
-
-type ProcessLogger = {
-  pid: string;
-  log: ProcessLogFn;
-};
-
-type ProcessLoggerContext = {
-  thread: string | null;
-  workflow: string | null;
-};
-
-type CreateProcessLoggerOptions = {
-  storageRoot: string | null;
-  context: ProcessLoggerContext;
-};
-
-type ProcessLogFn = (
-  tag: string,
-  msg: string,
-  context: Record<string, string> | null,
-) => void;
-```
-
-### Frontmatter markdown
-
-```typescript
-function parseFrontmatterMarkdown(raw: string): ParsedFrontmatterMarkdown
-function validateFrontmatter(
-  parsed: ParsedFrontmatterMarkdown,
-  schema: Record<string, unknown>,
-): FrontmatterValidationError[]
-
-type ParsedFrontmatterMarkdown = {
-  frontmatter: Record<string, unknown>;
-  body: string;
-};
-
-type AgentFrontmatter = { /* standard agent frontmatter fields */ };
-type FrontmatterScope = string;
-type FrontmatterStatus = string;
-type FrontmatterValidationError = { path: string; message: string };
-```
-
-### Result helpers
-
-```typescript
-function ok<T>(value: T): Result<T, never>
-function err<E>(error: E): Result<never, E>
-
-type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }
-```
-
-### Storage paths
-
-```typescript
-function getDefaultWorkflowStorageRoot(): string
-function getGlobalCasDir(storageRoot: string | undefined): string
-```
-
-### Refs and misc
-
-```typescript
-function normalizeRefsField(value: unknown): string[]
-function generateCliReference(): string
-function env(name: string, fallback: string): string
-```
+- **Workspace:** `@uncaged/workflow-protocol` — `Result` and shared types used by helpers
 
 ## Usage
 
 ```typescript
-import {
-  createLogger,
-  generateUlid,
-  getDefaultWorkflowStorageRoot,
-  parseFrontmatterMarkdown,
-} from "@uncaged/workflow-util";
+import { createLogger, getDefaultWorkflowStorageRoot, generateUlid } from "@uncaged/workflow-util";
 
 const log = createLogger();
-log("4KNMR2PX", "Loading workflow...");
-
-const root = getDefaultWorkflowStorageRoot();
-const threadId = generateUlid(Date.now());
+log("4KNMR2PX", "example");
 ```
-
-## Internal Structure
-
-```
-src/
-├── index.ts
-├── base32.ts              Crockford Base32 encode/decode
-├── ulid.ts                  ULID generation
-├── logger.ts                Structured logger
-├── process-logger/          Process-level debug log files
-├── frontmatter-markdown/    Parse and validate agent frontmatter
-├── refs-field.ts            Normalize refs arrays on CAS nodes
-├── result.ts                ok / err helpers
-├── storage-root.ts          Default ~/.uncaged/workflow paths
-├── env.ts                   Environment variable helper
-├── cli-reference.ts         Markdown CLI reference generator
-└── types.ts                 LogFn, Result, logger options
-```
-
-## Configuration
-
-`getDefaultWorkflowStorageRoot()` resolves to `~/.uncaged/workflow` unless overridden by environment (see `storage-root.ts`).

scripts/batch-solve.sh

@@ -1,89 +0,0 @@
-#!/usr/bin/env bash
-# batch-solve.sh — solve multiple Gitea issues via solve-issue workflow
-#
-# Usage:
-#   ./scripts/batch-solve.sh [--agent CMD] [--repo OWNER/REPO] [--count N] ISSUE_NUM...
-#
-# Examples:
-#   ./scripts/batch-solve.sh 448 449
-#   ./scripts/batch-solve.sh --agent "bun run $(pwd)/packages/workflow-agent-claude-code/src/cli.ts" 448 449
-#   ./scripts/batch-solve.sh --repo uncaged/workflow --count 15 448 449
-
-set -euo pipefail
-
-AGENT=""
-REPO="uncaged/workflow"
-COUNT=10
-ISSUES=()
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --agent)  AGENT="$2"; shift 2 ;;
-    --repo)   REPO="$2"; shift 2 ;;
-    --count)  COUNT="$2"; shift 2 ;;
-    *)        ISSUES+=("$1"); shift ;;
-  esac
-done
-
-if [[ ${#ISSUES[@]} -eq 0 ]]; then
-  echo "Usage: $0 [--agent CMD] [--repo OWNER/REPO] [--count N] ISSUE_NUM..." >&2
-  exit 1
-fi
-
-AGENT_FLAG=""
-if [[ -n "$AGENT" ]]; then
-  AGENT_FLAG="--agent $AGENT"
-fi
-
-TOTAL=${#ISSUES[@]}
-PASSED=0
-FAILED=0
-RESULTS=()
-
-echo "━━━ Batch solve: ${TOTAL} issues ━━━"
-echo ""
-
-for i in "${!ISSUES[@]}"; do
-  ISSUE="${ISSUES[$i]}"
-  NUM=$((i + 1))
-  echo "┌─── [$NUM/$TOTAL] Issue #${ISSUE} ───"
-
-  # Read issue title
-  TITLE=$(tea issues "$ISSUE" -r "$REPO" 2>/dev/null | head -1 | sed 's/^# #[0-9]* //' | sed 's/ (.*//' || echo "unknown")
-  echo "│ Title: $TITLE"
-
-  # Start thread
-  PROMPT="Fix issue #${ISSUE} in ${REPO}. Read the issue first with 'tea issues ${ISSUE} -r ${REPO}' for full spec."
-  THREAD_JSON=$(uwf thread start solve-issue -p "$PROMPT" 2>&1)
-  THREAD_ID=$(echo "$THREAD_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin)['thread'])")
-  echo "│ Thread: $THREAD_ID"
-
-  # Run steps
-  echo "│ Running (max $COUNT steps)..."
-  # shellcheck disable=SC2086
-  if STEP_OUTPUT=$(uwf thread step "$THREAD_ID" $AGENT_FLAG -c "$COUNT" 2>&1); then
-    # Check if done
-    LAST_DONE=$(echo "$STEP_OUTPUT" | python3 -c "import json,sys; lines=sys.stdin.read().strip(); data=json.loads(lines); print(data[-1].get('done', False))")
-    if [[ "$LAST_DONE" == "True" ]]; then
-      echo "│ ✅ Done!"
-      PASSED=$((PASSED + 1))
-      RESULTS+=("✅ #${ISSUE} — ${TITLE}")
-    else
-      echo "│ ⚠️  Ran out of steps (not done)"
-      FAILED=$((FAILED + 1))
-      RESULTS+=("⚠️  #${ISSUE} — ${TITLE} (incomplete)")
-    fi
-  else
-    echo "│ ❌ Failed"
-    FAILED=$((FAILED + 1))
-    RESULTS+=("❌ #${ISSUE} — ${TITLE} (error)")
-  fi
-
-  echo "└───"
-  echo ""
-done
-
-echo "━━━ Results: ${PASSED}/${TOTAL} passed, ${FAILED} failed ━━━"
-for R in "${RESULTS[@]}"; do
-  echo "  $R"
-done