feat: WS request proxy — Gateway proxies HTTP via WebSocket (#210 Phase 2)

- Add ws-protocol.ts with WsRequest/WsResponse types + parsers
- AgentSocket DO: proxy POST handler, pending request map, 30s timeout
- /api/agents/:agent/* routes through DO WS when connected, falls back to HTTP
- ws-client handles incoming WsRequest, fetches local serve, returns WsResponse
- startGatewayWsClient accepts localPort for request handling

Testing: #213

CLAUDE.md

@@ -245,6 +245,64 @@ bun run format      # biome format --write
 bun test            # run tests
 ```
 
+### Publishing to Gitea npm Registry
+
+All public `@uncaged/*` packages are published to the Gitea npm registry at `git.shazhou.work`. Workflow workspaces consume packages from this registry via `bunfig.toml`.
+
+```bash
+# Publish all packages (bun pm pack resolves workspace:* → actual versions)
+bun run publish:gitea
+
+# Dry run — see what would be published
+bun run publish:gitea:dry
+```
+
+Prerequisites: `.npmrc` in monorepo root with Gitea auth token (`//git.shazhou.work/api/packages/shazhou/npm/:_authToken=<token>`).
+
+### Workflow Workspace Setup
+
+External workflow repos (e.g. `xingyue-workflows`) use the Gitea registry for `@uncaged/*` packages. Add a `bunfig.toml`:
+
+```toml
+[install.scopes]
+"@uncaged" = "https://git.shazhou.work/api/packages/shazhou/npm/"
+```
+
+Then `bun install` resolves `@uncaged/*` from Gitea, all other packages from npmjs.
+
+### Cross-repo Development (bun link)
+
+Alternative for development against un-published local changes:
+
+```bash
+bun run link            # Register all packages (from monorepo root)
+bun run link:consume    # Link into CWD's project (⚠️ don't bun install after)
+bun run link:unlink     # Restore original deps
+```
+
+### End-to-end: Monorepo → Registry → Workspace → Bundle
+
+The recommended development flow for building workflows:
+
+```
+workflow/ (monorepo)           — engine, runtime, templates, agents
+  │  bun run publish:gitea     — auto topo-sort, bun pm pack → npm publish
+  ▼
+git.shazhou.work npm registry  — @uncaged/* scoped packages
+  │  bun install               — via bunfig.toml scoped registry
+  ▼
+my-workflows/ (workspace)     — bunfig.toml + normal package.json
+  │  bun run build:develop     — bun build → single .esm.js
+  ▼
+uncaged-workflow workflow add  — register bundle locally
+uncaged-workflow run           — execute workflow
+```
+
+1. **Monorepo changes** → `bun run publish:gitea` (packages auto-discovered from `packages/*/`, topologically sorted, `workspace:*` resolved to real versions)
+2. **Workspace** → `bun install` fetches latest from Gitea, `bun install` is safe to run anytime
+3. **Build** → produces single-file ESM bundle with `@uncaged/*` as externals
+4. **Register & Run** → `uncaged-workflow workflow add <name> <bundle>` then `uncaged-workflow run <name>`
+
 ## Commit Convention
 
 ```

docs/plans/2026-05-11-merkle-call-stack.md

@@ -0,0 +1,197 @@
+# RFC: Merkle Call Stack — Cross-Thread DAG Linking
+
+**Author:** 小橘 🍊（NEKO Team）
+**Date:** 2026-05-11
+**Status:** Draft
+
+## Problem
+
+当 `workflowAsAgent` 在父 workflow 中 spawn 子 workflow 时，父子 thread 之间没有任何 Merkle 链接：
+
+1. **子 thread 不知道自己从哪来** — start node 只有 prompt hash，无法追溯父 thread 的上下文（preparer 分析出的 repoPath、conventions 等）
+2. **父 thread 不知道子 thread 在哪** — developer role 的 state node 里只有 agent 返回的文本，child thread root hash 埋在字符串里，不是结构化 ref
+3. **上下文传递靠序列化到 prompt** — 父 workflow 前置 role 的产出只能通过拼字符串传给子 workflow，丢失了 Merkle DAG 的可遍历性
+
+## Proposal
+
+在 CAS 节点中建立父子 thread 之间的 **双向 Merkle 链接**，形成调用栈结构。
+
+### 新增字段
+
+#### StartNodePayload（子 → 父）
+
+```typescript
+type StartNodePayload = {
+  name: string;
+  hash: string;
+  depth: number;
+  parentState: string | null;   // NEW: 父 thread 调用时的 head state hash
+};
+```
+
+`parentState` 指向子 workflow 被 spawn 时，父 thread 的最后一个 state node hash。这是"调用发生时的调用栈帧"。
+
+#### StateNodePayload（父 → 子）
+
+```typescript
+type StateNodePayload = {
+  role: string;
+  meta: Record<string, unknown>;
+  start: string;
+  content: string;
+  ancestors: string[];
+  compact: string | null;
+  timestamp: number;
+  childThread: string | null;   // NEW: 子 thread 最终 state hash（执行结果）
+};
+```
+
+`childThread` 指向子 thread 完成后的**最终 state hash**（不是 start）——语义上是"函数返回值"，从这里沿 ancestors 可回溯子 thread 的完整执行历史。
+
+### refs 同步
+
+新增的 hash 也必须放进 `refs[]`：
+
+- `StartNode.refs`: `[promptHash, parentState]`（parentState 非 null 时）
+- `StateNode.refs`: `[...existingRefs, childThread]`（childThread 非 null 时）
+
+原因：GC 的 `findReachableHashes` 只走 `refs`，不解析 payload 字段。字段提供语义，refs 保证可达性。
+
+### 具体 DAG 结构
+
+以 `solve-issue`（fix #191）为例，developer role 委托给 `develop` 子 workflow：
+
+```
+父 thread: solve-issue
+═══════════════════════════════════════════════════════════
+
+content("fix #191")
+  hash: ABCD1234
+
+start(solve-issue)
+  hash: START001
+  payload: { name: "solve-issue", hash: BUNDLE_SI, depth: 0, parentState: null }
+  refs: [ABCD1234]
+
+state(preparer)
+  hash: STATE_P1
+  payload: { role: "preparer", meta: { repoPath: "...", ... }, childThread: null, ... }
+  refs: [PREP_CONTENT]
+
+state(developer)                          ──────── 父→子 ────────
+  hash: STATE_D1                                                 │
+  payload: { role: "developer", meta: { ... }, childThread: ★CSTATE_END, ... }
+  refs: [DEV_CONTENT, ★CSTATE_END]                               │
+                                                                  │
+state(submitter)                                                  │
+  hash: STATE_S1                                                  │
+  payload: { role: "submitter", ..., childThread: null }          │
+                                                                  │
+                                                                  │
+子 thread: develop                                                │
+═══════════════════════════════════════════════════════════        │
+                                                                  │
+content("fix #191")          (CAS 去重，可能同 ABCD1234)           │
+  hash: CPROMPT1                                                  │
+                              ──────── 子→父 ────────             │
+start(develop)                          │                         │
+  hash: CHILD_START                     │                         │
+  payload: { name: "develop", hash: BUNDLE_DEV, depth: 1,        │
+             parentState: ★STATE_P1 }   │                         │
+  refs: [CPROMPT1, ★STATE_P1]          │                         │
+                                        │                         │
+state(planner)                          │                         │
+  hash: CSTATE_1                        │                         │
+  ...                                   │                         │
+                                        │                         │
+state(coder)                            │                         │
+  hash: CSTATE_2                        │                         │
+  ...                                   │                         │
+                                        │                         │
+state(reviewer) → state(tester) → state(committer)                │
+                                        │                         │
+  hash: ★CSTATE_END  ◄─────────────────┼─────────────────────────┘
+```
+
+### 遍历路径
+
+**子 thread agent 获取父上下文（上行）：**
+```
+当前 step → start(CHILD_START)
+  → refs[1] = STATE_P1（父 preparer 的 state）
+    → payload.meta.repoPath = "/home/.../workflow"
+    → refs → PREP_CONTENT（完整 preparer 输出）
+    → payload.start = START001（父的 start node）
+      → refs[0] = ABCD1234（原始 prompt）
+```
+
+**从父 thread 追踪子 thread 执行（下行）：**
+```
+STATE_D1（父 developer state）
+  → payload.childThread = CSTATE_END
+    → 子 thread 最终 state
+    → 沿 ancestors 回溯：committer → tester → reviewer → coder → planner
+    → payload.start = CHILD_START（子 thread 入口）
+```
+
+**完整调用栈还原：**
+```
+任意节点 → 沿 start 找到所属 thread 的 StartNode
+  → parentState 非 null？沿 parentState 进入父 thread
+  → 递归直到 parentState = null（顶层 workflow）
+```
+
+## Implementation Plan
+
+### Phase 1: Protocol + CAS 层
+
+1. `workflow-protocol/src/cas-types.ts` — `StartNodePayload` 加 `parentState: string | null`，`StateNodePayload` 加 `childThread: string | null`
+2. `workflow-cas/src/nodes.ts` — `putStartNode` 接受可选 `parentStateHash`，放入 refs；`putStateNode` 接受可选 `childThreadHash`，放入 refs
+3. `workflow-cas/src/nodes.ts` — 解析逻辑兼容新字段（缺失时视为 null）
+
+### Phase 2: Engine 层
+
+4. `workflow-execute/src/engine/engine.ts` — `executeThread` 接受 `parentStateHash: string | null`，传给 `putStartNode`
+5. `workflow-execute/src/workflow-as-agent.ts` — spawn 子 thread 时传入父 thread 当前 head state hash 作为 `parentStateHash`；子 thread 完成后返回最终 state hash
+6. Engine 写 developer role 的 state node 时，把子 thread 最终 hash 写入 `childThread` 字段
+
+### Phase 3: Agent 可观测性
+
+7. Agent prompt 构建（`buildAgentPrompt`）— 当 start node 有 `parentState` 时，提示 agent 可通过 `cas get` 遍历父上下文
+8. CLI `thread show` — 显示 parentState / childThread 链接关系
+
+### Phase 4: 验证
+
+9. 已有测试适配新字段（向后兼容，旧节点 parentState/childThread 为 null）
+10. 新增集成测试：workflowAsAgent 场景下验证双向链接正确写入
+
+## Design Decisions
+
+### 为什么 childThread 指向 end 而不是 start？
+
+- 语义是"函数返回值"——父 role 执行完才产出 state，此时子 thread 已跑完
+- 从 end 沿 ancestors 可回溯到 start；反过来 start 写入时子 thread 还没跑完，无法知道 end
+
+### 为什么 parentState 指向 state 而不是 start？
+
+- 指向父 thread 调用点的**前一个 state**（即调用发生时的 head）
+- 这是子 workflow 能看到的父上下文的"切面"——所有已完成的前置 role 都可达
+- 如果是第一个 role 就 spawn 子 workflow（没有前置 state），parentState 指向父的 start node
+
+### 为什么同时放字段和 refs？
+
+- `refs[]` 服务于 GC（`findReachableHashes` 只遍历 refs）和通用 DAG 遍历
+- `payload.parentState` / `payload.childThread` 服务于语义读取（明确知道哪个 ref 是什么）
+- 不改 GC 逻辑，只加字段，GC 自然正确
+
+### 向后兼容
+
+- 新字段默认 `null`，旧节点解析时缺失字段视为 `null`
+- 不影响已有 thread 的遍历和 GC
+- `depth` 可通过沿 parentState 链上溯来交叉验证（数据自证）
+
+## Open Questions
+
+1. **多子 thread** — 如果一个 role 需要 spawn 多个子 workflow（目前不存在这个场景），`childThread` 应该改成 `childThreads: string[]` 还是保持单个？
+2. **Agent prompt 注入深度** — 子 workflow 的 agent 应该自动遍历多少层父上下文？全部还是限制深度？
+3. **CLI 展示** — `thread show` 要不要递归展示整个调用栈，还是只显示直接链接？

docs/plans/2026-05-12-dashboard-workflow-graph.md

@@ -0,0 +1,224 @@
+# Dashboard Workflow Graph Visualization
+
+**Issue**: #198
+**Status**: In Progress
+**Author**: xingyue
+
+## Overview
+
+在 Dashboard 的 ThreadDetail 页面中嵌入一个交互式流程图，将 workflow 的 `ModeratorTable` 可视化为有向图。用户可以一眼看到角色流转结构和当前执行进度。
+
+## 数据层（✅ 已完成 — PR #201）
+
+### WorkflowGraph 类型
+
+`WorkflowDefinition.moderator`（函数）已替换为 `WorkflowDefinition.table`（声明式 `ModeratorTable`），`buildDescriptor` 自动从 table 提取 graph：
+
+```ts
+type WorkflowGraphEdge = {
+  from: string;              // source role 或 "__start__"
+  to: string;                // target role 或 "__end__"
+  condition: string;         // condition.name 或 "FALLBACK"
+  conditionDescription: string | null;
+};
+
+type WorkflowGraph = {
+  edges: readonly WorkflowGraphEdge[];
+};
+
+type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+  graph: WorkflowGraph;      // 必填，新 bundle 自动生成
+};
+```
+
+### 数据流
+
+```
+ModeratorTable (WorkflowDefinition.table)
+  → buildDescriptor() 自动提取 graph
+    → descriptor.yaml 持久化（hash.yaml）
+      → CLI serve /workflows/:name API 返回 descriptor
+        → Dashboard 前端拿到 graph
+```
+
+### 剩余数据层工作
+
+**serve API 需要返回 descriptor**：当前 `GET /workflows/:name` 只返回 registry entry（hash + timestamp），不含 descriptor。需要从 `bundles/{hash}.yaml` 读取 descriptor 并返回给前端。
+
+方案：在 `routes-workflow.ts` 的 `GET /workflows/:name` 响应中附带 `descriptor` 字段。或者：thread-detail 发现 workflow name 后，请求 `GET /workflows/:name/descriptor` 拿到 graph。
+
+## 前端渲染
+
+### 库选型：React Flow + dagre
+
+| 库 | 优势 | 劣势 |
+|---|---|---|
+| **React Flow** ✅ | React 原生、自定义节点/边、dagre 自动布局、~50KB gzip | 需要学 API |
+| Mermaid | 声明式简单 | 无交互、无法高亮当前步骤 |
+| D3 | 完全控制 | 太底层，手撸成本高 |
+| Cytoscape | 图论强 | React 集成差 |
+
+**依赖新增**：
+
+```json
+{
+  "@xyflow/react": "^12",
+  "@dagrejs/dagre": "^1"
+}
+```
+
+### 图结构映射
+
+```
+WorkflowGraph.edges → React Flow nodes + edges
+
+节点（自动从 edges 推导）:
+  - __start__  → 圆形小节点（入口）
+  - role       → 圆角矩形，显示 role name + description
+  - __end__    → 圆形小节点（终止）
+
+边:
+  - FALLBACK   → 虚线（dashed），无 label
+  - condition  → 实线，label = condition
+                  hover tooltip = conditionDescription
+```
+
+### 布局
+
+使用 dagre 自动计算 TB（top-to-bottom）方向布局：
+
+```ts
+import Dagre from "@dagrejs/dagre";
+
+function layoutGraph(nodes, edges) {
+  const g = new Dagre.graphlib.Graph().setDefaultEdgeLabel(() => ({}));
+  g.setGraph({ rankdir: "TB", nodesep: 60, ranksep: 80 });
+
+  for (const node of nodes) {
+    g.setNode(node.id, { width: 180, height: 60 });
+  }
+  for (const edge of edges) {
+    g.setEdge(edge.source, edge.target);
+  }
+
+  Dagre.layout(g);
+
+  return nodes.map((node) => {
+    const pos = g.node(node.id);
+    return { ...node, position: { x: pos.x - 90, y: pos.y - 30 } };
+  });
+}
+```
+
+### 运行时高亮
+
+ThreadDetail 已有 `records: ThreadRecord[]`，其中 `RoleRecord.role` 就是当前/历史执行的 role。
+
+高亮逻辑：
+
+```ts
+function getNodeStates(records: ThreadRecord[]): Map<string, "completed" | "active"> {
+  const states = new Map<string, "completed" | "active">();
+  const roleRecords = records.filter((r) => r.type === "role");
+
+  for (let i = 0; i < roleRecords.length; i++) {
+    const role = roleRecords[i].role;
+    states.set(role, i === roleRecords.length - 1 ? "active" : "completed");
+  }
+
+  // 如果有 workflow-result，最后一个 role 也是 completed
+  if (records.some((r) => r.type === "workflow-result")) {
+    for (const [k] of states) {
+      states.set(k, "completed");
+    }
+    states.set("__end__", "completed");
+  }
+
+  states.set("__start__", "completed");
+  return states;
+}
+```
+
+节点样式：
+
+| 状态 | 样式 |
+|------|------|
+| default | `border: var(--color-border)`, 暗色背景 |
+| completed | `border: var(--color-success)`, 绿色边框 + ✓ 图标 |
+| active | `border: var(--color-accent)`, 蓝色边框 + 脉冲动画 |
+
+边高亮：当 source 和 target 都至少 completed 时，边变绿。
+
+## 组件结构
+
+```
+workflow-dashboard/src/
+  components/
+    workflow-graph/
+      types.ts           — NodeState 等前端类型
+      index.ts           — export { WorkflowGraph }
+      workflow-graph.tsx  — 主组件，React Flow canvas
+      role-node.tsx       — 自定义 role 节点
+      terminal-node.tsx   — START/END 圆形节点
+      condition-edge.tsx  — 自定义边（虚线/实线 + label）
+      use-layout.ts       — dagre 布局 hook
+```
+
+### 集成到 ThreadDetail
+
+在 ThreadDetail 中，records 列表上方插入可折叠的图面板：
+
+```tsx
+// thread-detail.tsx
+{graph && (
+  <div className="mb-4 border rounded-lg overflow-hidden" style={{ height: 300 }}>
+    <WorkflowGraph graph={graph} nodeStates={getNodeStates(records)} />
+  </div>
+)}
+```
+
+图高度固定 300px，React Flow 支持 pan + zoom，不影响下方 records 滚动。
+
+## 实施计划
+
+### ~~Phase 0: 数据层~~ ✅ Done (PR #201)
+
+- [x] `WorkflowDefinition.moderator` → `table` (ModeratorTable)
+- [x] `WorkflowDescriptor` 新增 `graph: WorkflowGraph`
+- [x] `buildDescriptor` 自动提取 graph
+- [x] `validateWorkflowDescriptor` 校验 graph
+
+### Phase 1: API + 静态图渲染
+
+1. serve API：`GET /workflows/:name` 返回 descriptor（含 graph），或新增 `GET /workflows/:name/descriptor`
+2. Dashboard `api.ts` 新增 `getWorkflowDescriptor(agent, name)` 函数
+3. 安装 `@xyflow/react` + `@dagrejs/dagre`
+4. 实现 `workflow-graph/` 组件集
+5. ThreadDetail 中集成：从 thread-start record 拿 workflow name → 请求 descriptor → 渲染图
+
+**产出**：打开 ThreadDetail 看到 workflow 流程图，无高亮。
+
+### Phase 2: 运行时高亮
+
+1. ThreadDetail 根据 records 计算 nodeStates
+2. 节点/边样式响应状态变化
+3. SSE live 模式下实时更新高亮
+
+**产出**：正在运行的 thread 能看到当前执行到哪个 role。
+
+### Phase 3: 交互增强
+
+1. 点击节点滚动到对应 role 的 RecordCard
+2. 边 hover 显示 conditionDescription tooltip
+3. 节点 hover 显示 role description + schema summary
+
+**产出**：图和记录列表联动。
+
+## 注意事项
+
+- **自循环边**：如 `coder → coder (FALLBACK)`，React Flow 支持自循环，dagre 需要特殊处理（self-edge 用 loop 路径）
+- **大图性能**：dagre 在 <50 节点时性能无忧，workflow 通常 <10 个 role
+- **暗色主题**：Dashboard 已使用 CSS variables，节点/边样式复用现有色板
+- **不提交 pnpm-lock.yaml**

package.json

@@ -9,7 +9,12 @@
     "check": "bunx tsc --build && biome check .",
     "typecheck": "bunx tsc --build",
     "format": "biome format --write .",
-    "test": "bun run --filter '*' test"
+    "test": "bun run --filter '*' test",
+    "link": "./scripts/link-all.sh",
+    "link:consume": "./scripts/link-all.sh --consume",
+    "link:unlink": "./scripts/link-all.sh --unlink",
+    "publish:gitea": "./scripts/publish-all.sh",
+    "publish:gitea:dry": "./scripts/publish-all.sh --dry-run"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",

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

@@ -17,7 +17,7 @@ import {
 } from "../src/commands/workflow/index.js";
 import { addCliArgs } from "./bundle-fixture.js";
 
-const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {} };
+const fixtureDescriptor = `export const descriptor = { description: "fixture", roles: {}, graph: { edges: [] } };
 `;
 
 const wfPutImport = `import { putContentMerkleNode } from "@uncaged/workflow-cas";
@@ -153,6 +153,7 @@ export const run = async function* (input) { return { returnCode: 0, summary: in
       schema: { type: "object", properties: { greeting: { type: "string" } } },
     },
   },
+  graph: { edges: [] },
 };
 ${wfPutImport}
 export const run = async function* (input, options) {

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

@@ -24,6 +24,7 @@ export const descriptor = {
     coder: { description: "coder", schema: {} },
     reviewer: { description: "reviewer", schema: {} },
   },
+  graph: { edges: [] },
 };
 export const run = async function* (input, options) {
   const cas = options.cas;

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

@@ -45,8 +45,8 @@ describe("gc cli and garbageCollectCas", () => {
       {
         name: "demo",
         hash: bundleHash,
-
         depth: 0,
+        parentState: null,
       },
       promptHash,
     );
@@ -100,8 +100,8 @@ describe("gc cli and garbageCollectCas", () => {
       {
         name: "demo",
         hash: bundleHash,
-
         depth: 0,
+        parentState: null,
       },
       promptHash,
     );
@@ -135,8 +135,8 @@ describe("gc cli and garbageCollectCas", () => {
       {
         name: "demo",
         hash: bundleHash,
-
         depth: 0,
+        parentState: null,
       },
       promptHash,
     );

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

@@ -58,6 +58,11 @@ describe("--help flag on groups", () => {
     const code = await runCli(STORAGE_ROOT, ["init", "--help"]);
     expect(code).toBe(0);
   });
+
+  test("setup --help returns 0", async () => {
+    const code = await runCli(STORAGE_ROOT, ["setup", "--help"]);
+    expect(code).toBe(0);
+  });
 });
 
 describe("getSkillTopics", () => {
@@ -90,6 +95,8 @@ describe("formatCliUsage", () => {
     expect(u).toContain("Thread execution:");
     expect(u).toContain("Content-addressable storage:");
     expect(u).toContain("Development:");
+    expect(u).toContain("Configuration:");
+    expect(u).toContain("setup [--provider <name>]");
     expect(u).toContain("Shortcuts:");
     expect(u).toContain("Reference:");
     expect(u).toContain("skill [topic]");
@@ -128,6 +135,7 @@ describe("formatSkillTopic('cli')", () => {
     expect(doc).toContain("### thread");
     expect(doc).toContain("### cas");
     expect(doc).toContain("### init");
+    expect(doc).toContain("### setup");
     expect(doc).toContain("### Top-level shortcuts");
   });
 

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

@@ -64,6 +64,7 @@ describe("init template", () => {
 
     const moder = await readFile(join(tdir, "src", "moderator.ts"), "utf8");
     expect(moder).not.toContain("export default");
+    expect(moder).toContain("ModeratorTable");
   });
 
   test("finds workspace walking up from nested cwd", async () => {

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

@@ -38,8 +38,16 @@ describe("init workspace", () => {
 
     const rootPkg = JSON.parse(await readFile(join(root, "package.json"), "utf8")) as {
       workspaces: string[];
+      scripts: { bundle: string };
     };
     expect(rootPkg.workspaces).toEqual(["templates/*", "workflows"]);
+    expect(rootPkg.scripts.bundle).toBe("bun run scripts/bundle.ts");
+
+    expect(await pathExists(join(root, "scripts", "bundle.ts"))).toBe(true);
+    const bundleSrc = await readFile(join(root, "scripts", "bundle.ts"), "utf8");
+    expect(bundleSrc).toContain("Bun.build");
+    expect(bundleSrc).toContain("-entry.ts");
+    expect(bundleSrc).toContain("distDir");
 
     const wfPkg = JSON.parse(await readFile(join(root, "workflows", "package.json"), "utf8")) as {
       type: string;
@@ -82,7 +90,7 @@ describe("init workspace", () => {
     for (const term of [
       "RoleDefinition",
       "WorkflowDefinition",
-      "Moderator",
+      "ModeratorTable",
       "AgentFn",
       "ExtractFn",
       "RoleMeta",
@@ -117,9 +125,6 @@ describe("init workspace", () => {
   });
 
   test("errors on invalid workspace name", async () => {
-    const slash = await cmdInitWorkspace(parent, "a/b");
-    expect(slash.ok).toBe(false);
-
     const dots = await cmdInitWorkspace(parent, "..");
     expect(dots.ok).toBe(false);
 
@@ -127,6 +132,14 @@ describe("init workspace", () => {
     expect(empty.ok).toBe(false);
   });
 
+  test("accepts nested path as workspace name", async () => {
+    const nested = await cmdInitWorkspace(parent, "a/b");
+    expect(nested.ok).toBe(true);
+    if (nested.ok) {
+      expect(nested.value.rootPath).toContain("a/b");
+    }
+  });
+
   test("usage lists init subcommands", () => {
     const u = formatCliUsage();
     expect(u).toContain("init workspace <name>");

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

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readWorkflowRegistry } from "@uncaged/workflow-register";
+
+import { runCli } from "../src/cli-dispatch.js";
+import { cmdSetup } from "../src/commands/setup/index.js";
+
+describe("setup command (CLI mode)", () => {
+  let prevEnv: string | undefined;
+  let storageRoot: string;
+
+  beforeEach(async () => {
+    prevEnv = process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    storageRoot = await mkdtemp(join(tmpdir(), "uncaged-setup-"));
+    process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = storageRoot;
+    await mkdir(storageRoot, { recursive: true });
+  });
+
+  afterEach(async () => {
+    if (prevEnv === undefined) {
+      delete process.env.UNCAGED_WORKFLOW_STORAGE_ROOT;
+    } else {
+      process.env.UNCAGED_WORKFLOW_STORAGE_ROOT = prevEnv;
+    }
+    await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  test("writes workflow.yaml with provider, models.default, and depth defaults", async () => {
+    const r = await cmdSetup(storageRoot, {
+      provider: "dashscope",
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-test123",
+      defaultModel: "dashscope/qwen-plus",
+      initWorkspaceName: null,
+    });
+    expect(r.ok).toBe(true);
+    if (!r.ok) {
+      return;
+    }
+
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok) {
+      return;
+    }
+    expect(reg.value.config).not.toBeNull();
+    if (reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.dashscope).toEqual({
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-test123",
+    });
+    expect(reg.value.config.models.default).toBe("dashscope/qwen-plus");
+    expect(reg.value.config.maxDepth).toBe(3);
+    expect(reg.value.config.supervisorInterval).toBe(3);
+
+    const raw = await readFile(join(storageRoot, "workflow.yaml"), "utf8");
+    expect(raw).toContain("dashscope");
+    expect(raw).toContain("qwen-plus");
+  });
+
+  test("idempotent: second run updates apiKey and preserves workflows", async () => {
+    const initialYaml = `config:
+  maxDepth: 7
+  supervisorInterval: 2
+  providers:
+    dashscope:
+      baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+      apiKey: sk-old
+  models:
+    default: dashscope/qwen-plus
+workflows:
+  keep-me:
+    hash: "0000000000000"
+    timestamp: 1
+    history: []
+`;
+    await writeFile(join(storageRoot, "workflow.yaml"), initialYaml, "utf8");
+
+    const r2 = await cmdSetup(storageRoot, {
+      provider: "dashscope",
+      baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+      apiKey: "sk-newkey",
+      defaultModel: "dashscope/qwen-plus",
+      initWorkspaceName: null,
+    });
+    expect(r2.ok).toBe(true);
+    if (!r2.ok) {
+      return;
+    }
+
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok || reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.dashscope.apiKey).toBe("sk-newkey");
+    expect(reg.value.config.maxDepth).toBe(7);
+    expect(reg.value.config.supervisorInterval).toBe(2);
+    expect(reg.value.workflows["keep-me"]).toBeDefined();
+    if (reg.value.workflows["keep-me"] === undefined) {
+      return;
+    }
+    expect(reg.value.workflows["keep-me"].hash).toBe("0000000000000");
+  });
+
+  test("runCli setup dispatches with flags and exits 0", async () => {
+    const code = await runCli(storageRoot, [
+      "setup",
+      "--provider",
+      "openai",
+      "--base-url",
+      "https://api.openai.com/v1",
+      "--api-key",
+      "sk-test",
+      "--default-model",
+      "openai/gpt-4o",
+    ]);
+    expect(code).toBe(0);
+    const reg = await readWorkflowRegistry(storageRoot);
+    expect(reg.ok).toBe(true);
+    if (!reg.ok || reg.value.config === null) {
+      return;
+    }
+    expect(reg.value.config.providers.openai.apiKey).toBe("sk-test");
+    expect(reg.value.config.models.default).toBe("openai/gpt-4o");
+  });
+});

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

@@ -36,6 +36,7 @@ const threadFixtureDescriptor = `export const descriptor = {
     only: { description: "only", schema: {} },
     noop: { description: "noop", schema: {} },
   },
+  graph: { edges: [] },
 };
 `;
 
@@ -186,6 +187,14 @@ describe("cli thread commands", () => {
     }
     expect(shown.value.includes('"threadId"')).toBe(true);
 
+    const parsed = JSON.parse(shown.value) as Record<string, unknown>;
+    expect(parsed.parentState).toBeNull();
+    const parsedSteps = parsed.steps as Array<Record<string, unknown>>;
+    for (const step of parsedSteps) {
+      expect(step).toHaveProperty("childThread");
+      expect(step.childThread).toBeNull();
+    }
+
     const removed = await cmdThreadRemove(storageRoot, threadId);
     expect(removed.ok).toBe(true);
 
@@ -305,8 +314,13 @@ describe("cli thread commands", () => {
     }
 
     const threadId = ran.value.threadId;
+    const killBundleDir = getBundleDir(storageRoot, added.value.hash);
 
-    await new Promise((r) => setTimeout(r, 50));
+    await waitUntilPredicate(async () => {
+      const idx = await readThreadsIndex(killBundleDir);
+      const ent = idx[threadId];
+      return ent !== undefined && ent.head !== ent.start;
+    }, 80);
 
     const killed = await cmdKill(storageRoot, threadId);
     expect(killed.ok).toBe(true);

packages/cli-workflow/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@uncaged/cli-workflow",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "bin": {
     "uncaged-workflow": "src/cli.ts"
   },
   "dependencies": {
+    "@uncaged/workflow-gateway": "workspace:*",
     "@uncaged/workflow-protocol": "workspace:*",
     "@uncaged/workflow-util": "workspace:*",
     "@uncaged/workflow-cas": "workspace:*",

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

@@ -5,6 +5,7 @@ import { formatCliUsage as formatCliUsageWithGroups } from "./cli-usage.js";
 import { createCasDispatcher } from "./commands/cas/index.js";
 import { createInitDispatcher } from "./commands/init/index.js";
 import { dispatchServe } from "./commands/serve/index.js";
+import { dispatchSetup } from "./commands/setup/index.js";
 import { createThreadDispatcher, dispatchLive, dispatchRun } from "./commands/thread/index.js";
 import { createWorkflowDispatcher } from "./commands/workflow/index.js";
 import { formatSkillIndex, formatSkillTopic, getSkillTopics } from "./skill.js";
@@ -66,6 +67,7 @@ const COMMAND_TABLE: Record<string, DispatchFn> = {
   thread: dispatchThread,
   cas: dispatchCas,
   init: dispatchInit,
+  setup: dispatchSetup,
   skill: dispatchSkill,
   run: dispatchRun,
   live: dispatchLive,

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

@@ -5,6 +5,15 @@ import { INIT_SUBCOMMAND_TABLE } from "./commands/init/index.js";
 import { THREAD_SUBCOMMAND_TABLE } from "./commands/thread/index.js";
 import { WORKFLOW_SUBCOMMAND_TABLE } from "./commands/workflow/index.js";
 
+const SETUP_USAGE_COMMANDS = [
+  {
+    name: "",
+    args: "[--provider <name>] [--base-url <url>] [--api-key <key>] [--default-model <provider/model>] [--init-workspace <name>]",
+    description:
+      "Configure workflow.yaml LLM providers and default model (interactive when no flags)",
+  },
+] as const;
+
 export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
   return [
     {
@@ -39,6 +48,10 @@ export function getCommandRegistry(): ReadonlyArray<CommandGroup> {
         description: e.description,
       })),
     },
+    {
+      name: "setup",
+      commands: [...SETUP_USAGE_COMMANDS],
+    },
   ];
 }
 

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

@@ -12,6 +12,7 @@ const USAGE_SECTION_BY_GROUP: Record<string, string> = {
   thread: "Thread execution:",
   cas: "Content-addressable storage:",
   init: "Development:",
+  setup: "Configuration:",
 };
 
 export function formatUsageCommandLines(
@@ -38,9 +39,10 @@ export function formatCliUsage(
     }
     lines.push(sectionTitle);
     const rows = group.commands.map((cmd) => {
+      const namePart = cmd.name === "" ? "" : ` ${cmd.name}`;
       const args = cmd.args ? ` ${cmd.args}` : "";
       return {
-        prefix: `${group.name} ${cmd.name}${args}`,
+        prefix: `${group.name}${namePart}${args}`,
         description: cmd.description,
       };
     });

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

@@ -6,7 +6,7 @@ export function templatePackageJson(templateName: string): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow-runtime": "^0.1.0",
+        "@uncaged/workflow-runtime": "^0.3.1",
         zod: "^4.0.0",
       },
     },
@@ -57,17 +57,13 @@ export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
 }
 
 export function templateModeratorTs(): string {
-  return `import { END, type Moderator, type ModeratorContext } from "@uncaged/workflow-runtime";
+  return `import { END, START, type ModeratorTable } from "@uncaged/workflow-runtime";
 
 import type { HelloTemplateMeta } from "./roles.js";
 
-export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
-  ctx: ModeratorContext<HelloTemplateMeta>,
-) => {
-  if (ctx.steps.length === 0) {
-    return "greeter";
-  }
-  return END;
+export const helloTemplateTable: ModeratorTable<HelloTemplateMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "greeter" }],
+  greeter: [{ condition: "FALLBACK", role: END }],
 };
 `;
 }
@@ -75,7 +71,7 @@ export const helloTemplateModerator: Moderator<HelloTemplateMeta> = (
 export function templateIndexTs(): string {
   return `import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
 
-import { helloTemplateModerator } from "./moderator.js";
+import { helloTemplateTable } from "./moderator.js";
 import {
   HELLO_TEMPLATE_DESCRIPTION,
   type HelloTemplateMeta,
@@ -87,14 +83,14 @@ export {
   type HelloTemplateMeta,
   greeterRole,
 } from "./roles.js";
-export { helloTemplateModerator } from "./moderator.js";
+export { helloTemplateTable } from "./moderator.js";
 
 export const helloTemplateWorkflowDefinition: WorkflowDefinition<HelloTemplateMeta> = {
   description: HELLO_TEMPLATE_DESCRIPTION,
   roles: {
     greeter: greeterRole,
   },
-  moderator: helloTemplateModerator,
+  table: helloTemplateTable,
 };
 `;
 }

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

@@ -1,5 +1,5 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join, resolve } from "node:path";
 
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
@@ -14,6 +14,9 @@ function rootPackageJson(workspaceName: string): string {
       private: true,
       type: "module",
       workspaces: ["templates/*", "workflows"],
+      scripts: {
+        bundle: "bun run scripts/bundle.ts",
+      },
     },
     null,
     2,
@@ -28,7 +31,7 @@ function workflowsPackageJson(): string {
       private: true,
       type: "module",
       dependencies: {
-        "@uncaged/workflow-runtime": "^0.1.0",
+        "@uncaged/workflow-runtime": "^0.3.1",
         zod: "^4.0.0",
       },
     },
@@ -42,7 +45,9 @@ function biomeJson(): string {
     {
       $schema: "https://biomejs.dev/schemas/2.4.14/schema.json",
       files: {
-        includes: ["**", "!**/node_modules", "!**/dist"],
+        // Exclude generated bundle script — it uses Bun globals and console that
+        // conflict with the workspace's Biome rules (noConsole, etc.).
+        includes: ["**", "!**/node_modules", "!**/dist", "!scripts/bundle.ts"],
       },
       formatter: {
         indentWidth: 2,
@@ -85,7 +90,7 @@ function agentsMd(): string {
 | 层级 | 目录 / 产物 | 职责 |
 |------|----------------|------|
 | **Workspace** | 仓库根（\`package.json\` 含 \`workspaces: ["templates/*", "workflows"]\`） | Bun monorepo：统一管理本地模板包与 workflow 实例 |
-| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **Moderator**），**不绑定**具体 Agent |
+| **Template** | \`templates/<name>/\`（如 \`src/roles.ts\`、\`src/moderator.ts\`、\`src/index.ts\`） | 纯数据：**WorkflowDefinition**（各 **RoleDefinition** + **ModeratorTable**），**不绑定**具体 Agent |
 | **Workflow instance** | \`workflows/\`（或单独包） | 把模板与运行时 **AgentFn** / **ExtractFn** 组合，产出可注册的 **单文件 ESM bundle**（\`run\` + \`descriptor\` 命名导出） |
 
 Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下放绑定与打包入口。
@@ -94,19 +99,19 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 
 - **RoleMeta**：\`Record<string, Record<string, unknown>>\`，角色名 → 该角色结构化 meta 的形状约定。
 - **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
-- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **Moderator**。
-- **Moderator**：\`(ctx: ModeratorContext<M>) => (角色名) | END\`。同步、纯函数，只做路由。
+- **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **ModeratorTable**（声明式路由表）。
+- **ModeratorTable**：从 \`START\` 与各角色名映射到有序 transition 列表（条件 + 下一角色或 \`END\`）；可序列化，供描述符提取 **graph**。
 - **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
 - **ExtractFn**：从 CAS content hash 解析结构化数据（引擎与 Agent 都可使用）。
 
-引擎循环简述：**Moderator** → 选角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
+引擎循环简述：按 **ModeratorTable** 选下一角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
 
 ## 3. 开发流程
 
 1. **定义 RoleMeta**：为每个角色约定 meta 的 TypeScript 类型（与 Zod schema 对齐）。
 2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`description\`。
-3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
-4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
+3. **编写 ModeratorTable**：为 \`START\` 与各角色声明 transition（\`FALLBACK\` 或命名条件 + \`check\`）。
+4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / table 导出）。
 5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowRuntime\`。
 6. **构建**：打包为单个 **.esm.js** bundle，使用 **uncaged-workflow add** 注册。
 
@@ -153,7 +158,13 @@ uncaged-workflow add <name> <path/to/bundle.esm.js>
 
 ---
 
-编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ Moderator → 绑定 → 单文件 bundle**，再对照本节规范自检。
+编写新 workflow 时，先对齐 **RoleMeta → RoleDefinition（Zod）→ ModeratorTable → 绑定 → 单文件 bundle**，再对照本节规范自检。
+`;
+}
+
+function bunfigToml(): string {
+  return `[install.scopes]
+"@uncaged" = "https://git.shazhou.work/api/packages/shazhou/npm/"
 `;
 }
 
@@ -164,7 +175,7 @@ Local workflow development workspace (Bun monorepo).
 
 ## Layout
 
-- \`templates/\` — reusable workflow definition packages (roles + moderator), no agent binding
+- \`templates/\` — reusable workflow definition packages (roles + ModeratorTable), no agent binding
 - \`workflows/\` — workflow instances that bind templates to agents and export \`run\` + \`descriptor\`
 
 ## Commands
@@ -184,32 +195,137 @@ uncaged-workflow init workspace ${workspaceName}
 `;
 }
 
+function bundleTs(): string {
+  return [
+    'import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";',
+    'import { join } from "node:path";',
+    "",
+    'const rootDir = join(import.meta.dir, "..");',
+    'const workflowsDir = join(rootDir, "workflows");',
+    'const distDir = join(rootDir, "dist");',
+    "",
+    "type JsonDeps = {",
+    "  dependencies: Record<string, string> | null;",
+    "  devDependencies: Record<string, string> | null;",
+    "};",
+    "",
+    "function isEntryFile(name: string): boolean {",
+    '  return name.endsWith("-entry.ts");',
+    "}",
+    "",
+    "function entryStem(name: string): string {",
+    '  return name.slice(0, -".ts".length);',
+    "}",
+    "",
+    "async function uncagedWorkflowExternals(): Promise<string[]> {",
+    "  const names = new Set<string>();",
+    '  const paths = [join(rootDir, "package.json"), join(workflowsDir, "package.json")];',
+    "  for (const pkgPath of paths) {",
+    "    let raw: string;",
+    "    try {",
+    '      raw = await readFile(pkgPath, "utf8");',
+    "    } catch {",
+    "      continue;",
+    "    }",
+    "    const parsed = JSON.parse(raw) as JsonDeps;",
+    "    const blocks = [parsed.dependencies, parsed.devDependencies];",
+    "    for (const block of blocks) {",
+    "      if (block == null) {",
+    "        continue;",
+    "      }",
+    "      for (const key of Object.keys(block)) {",
+    '        if (key.startsWith("@uncaged/workflow")) {',
+    "          names.add(key);",
+    "        }",
+    "      }",
+    "    }",
+    "  }",
+    "  if (names.size === 0) {",
+    '    names.add("@uncaged/workflow-runtime");',
+    '    names.add("@uncaged/workflow-protocol");',
+    "  }",
+    "  return [...names];",
+    "}",
+    "",
+    "async function main(): Promise<void> {",
+    "  await mkdir(distDir, { recursive: true });",
+    "  let files: string[];",
+    "  try {",
+    "    files = await readdir(workflowsDir);",
+    "  } catch {",
+    '    console.error("bundle: missing workflows/ directory");',
+    "    process.exitCode = 1;",
+    "    return;",
+    "  }",
+    "  const entries = files.filter(isEntryFile);",
+    "  if (entries.length === 0) {",
+    '    console.warn("bundle: no *-entry.ts files under workflows/");',
+    "    return;",
+    "  }",
+    "  const external = await uncagedWorkflowExternals();",
+    "  for (const file of entries) {",
+    "    const stem = entryStem(file);",
+    "    const entryPath = join(workflowsDir, file);",
+    "    const result = await Bun.build({",
+    "      entrypoints: [entryPath],",
+    "      outdir: distDir,",
+    '      format: "esm",',
+    '      target: "node",',
+    "      splitting: false,",
+    '      naming: { entry: "[name].esm.js" },',
+    "      external,",
+    "    });",
+    "    if (!result.success) {",
+    "      for (const log of result.logs) {",
+    "        console.error(log);",
+    "      }",
+    `      throw new Error(\`bundle failed for \${file}\`);`,
+    "    }",
+    "    const dts =",
+    `      'export { run, descriptor } from "../workflows/' + stem + '.js";\\n';`,
+    `    await writeFile(join(distDir, \`\${stem}.d.ts\`), dts, "utf8");`,
+    `    console.log(\`bundle: \${stem} -> dist/\${stem}.esm.js\`);`,
+    "  }",
+    "}",
+    "",
+    "await main();",
+    "",
+  ].join("\n");
+}
+
 export async function cmdInitWorkspace(
   parentDir: string,
   workspaceName: string,
 ): Promise<Result<CmdInitWorkspaceSuccess, string>> {
-  const validated = validateWorkspaceSegment(workspaceName);
-  if (!validated.ok) {
-    return validated;
+  // Accept a relative/absolute path: resolve it and derive the dir name for package.json.
+  const resolved = resolve(parentDir, workspaceName);
+  const rootPath = resolved;
+  const dirName = basename(resolved);
+
+  if (dirName === "" || dirName === "." || dirName === "..") {
+    return err(`invalid workspace path: ${workspaceName}`);
   }
 
-  const rootPath = join(parentDir, workspaceName);
   if (await pathExists(rootPath)) {
     return err(`directory already exists: ${rootPath}`);
   }
 
-  await mkdir(rootPath, { recursive: false });
-  await mkdir(join(rootPath, "templates"), { recursive: false });
-  await mkdir(join(rootPath, "workflows"), { recursive: false });
+  await mkdir(rootPath, { recursive: true });
+  await mkdir(join(rootPath, "templates"), { recursive: true });
+  await mkdir(join(rootPath, "workflows"), { recursive: true });
+  await mkdir(join(rootPath, "scripts"), { recursive: true });
 
   await Promise.all([
-    writeFile(join(rootPath, "package.json"), rootPackageJson(workspaceName), "utf8"),
+    writeFile(join(rootPath, "package.json"), rootPackageJson(dirName), "utf8"),
     writeFile(join(rootPath, "biome.json"), biomeJson(), "utf8"),
     writeFile(join(rootPath, "tsconfig.json"), tsconfigJson(), "utf8"),
     writeFile(join(rootPath, "AGENTS.md"), agentsMd(), "utf8"),
-    writeFile(join(rootPath, "README.md"), readmeMd(workspaceName), "utf8"),
+    writeFile(join(rootPath, "README.md"), readmeMd(dirName), "utf8"),
     writeFile(join(rootPath, "templates", ".gitkeep"), "", "utf8"),
     writeFile(join(rootPath, "workflows", "package.json"), workflowsPackageJson(), "utf8"),
+    writeFile(join(rootPath, "workflows", ".gitkeep"), "", "utf8"),
+    writeFile(join(rootPath, "bunfig.toml"), bunfigToml(), "utf8"),
+    writeFile(join(rootPath, "scripts", "bundle.ts"), bundleTs(), "utf8"),
   ]);
 
   return ok({ rootPath });

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

@@ -1,9 +1,14 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { WorkflowDescriptor } from "@uncaged/workflow-protocol";
 import {
   getRegisteredWorkflow,
   listRegisteredWorkflowNames,
   readWorkflowRegistry,
+  validateWorkflowDescriptor,
 } from "@uncaged/workflow-register";
 import { Hono } from "hono";
+import { parse as parseYaml } from "yaml";
 
 export function createWorkflowRoutes(storageRoot: string): Hono {
   const app = new Hono();
@@ -35,7 +40,17 @@ export function createWorkflowRoutes(storageRoot: string): Hono {
     if (entry === null) {
       return c.json({ error: `workflow not found: ${name}` }, 404);
     }
-    return c.json({ name, ...entry });
+    let descriptor: WorkflowDescriptor | null = null;
+    try {
+      const yamlPath = join(storageRoot, "bundles", `${entry.hash}.yaml`);
+      const yamlText = await readFile(yamlPath, "utf8");
+      const parsed: unknown = parseYaml(yamlText);
+      const validated = validateWorkflowDescriptor(parsed);
+      descriptor = validated.ok ? validated.value : null;
+    } catch {
+      descriptor = null;
+    }
+    return c.json({ name, ...entry, descriptor });
   });
 
   app.get("/:name/history", async (c) => {

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

@@ -1,17 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { hostname as osHostname } from "node:os";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
+import { createLogger } from "@uncaged/workflow-util";
 import { serve } from "bun";
 
 import { printCliLine } from "../../cli-output.js";
 import { createApp } from "./app.js";
-import {
-  registerWithGateway,
-  startHeartbeat,
-  startTunnel,
-  unregisterFromGateway,
-} from "./tunnel.js";
+import { registerWithGateway, startHeartbeat, unregisterFromGateway } from "./tunnel.js";
 import type { ServeOptions } from "./types.js";
+import { startGatewayWsClient } from "./ws-client.js";
 
 const DEFAULT_GATEWAY_URL = "https://workflow-gateway.shazhou.workers.dev";
 const HEARTBEAT_INTERVAL_MS = 60_000;
@@ -56,6 +53,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
   let hostname = "127.0.0.1";
   let name = osHostname().split(".")[0].toLowerCase();
   let noTunnel = false;
+  let tunnelUrl: string | null = null;
   let gatewayUrl = DEFAULT_GATEWAY_URL;
   const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
   const stringFlags: Record<string, (v: string) => void> = {
@@ -68,6 +66,9 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     "--gateway": (v) => {
       gatewayUrl = v;
     },
+    "--tunnel-url": (v) => {
+      tunnelUrl = v;
+    },
   };
 
   for (let i = 0; i < argv.length; i++) {
@@ -87,7 +88,7 @@ function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
     }
   }
 
-  return ok({ port, hostname, name, noTunnel, gatewayUrl, gatewaySecret });
+  return ok({ port, hostname, name, noTunnel, tunnelUrl, gatewayUrl, gatewaySecret });
 }
 
 export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
@@ -107,47 +108,64 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     return 0;
   }
 
-  // Start cloudflared quick tunnel
-  printCliLine("starting cloudflared quick tunnel...");
-  const tunnel = await startTunnel(options.port);
+  let resolvedTunnelUrl: string;
+  let stopWsClient: (() => void) | null = null;
 
-  if (!tunnel) {
-    printCliLine("failed to create tunnel — continuing without gateway registration");
-    await new Promise(() => {});
-    return 0;
+  if (options.tunnelUrl !== null) {
+    resolvedTunnelUrl = options.tunnelUrl;
+    printCliLine(`using tunnel URL: ${resolvedTunnelUrl}`);
+  } else {
+    if (options.gatewaySecret === "") {
+      printCliLine(
+        "WORKFLOW_GATEWAY_SECRET not set — cannot use WebSocket gateway connection (set env or pass --tunnel-url)",
+      );
+      await new Promise(() => {});
+      return 0;
+    }
+    resolvedTunnelUrl = `http://127.0.0.1:${options.port}`;
+    const log = createLogger({ sink: { kind: "stderr" } });
+    stopWsClient = startGatewayWsClient({
+      gatewayUrl: options.gatewayUrl,
+      name: options.name,
+      secret: options.gatewaySecret,
+      localPort: options.port,
+      log,
+    });
+    printCliLine("gateway WebSocket reverse connection (no cloudflared)");
   }
 
-  printCliLine(`tunnel: ${tunnel.url}`);
-
-  // Register with gateway
   if (options.gatewaySecret) {
+    if (agentToken === null) {
+      printCliLine("internal error: agent token missing");
+      await new Promise(() => {});
+      return 1;
+    }
+    const token = agentToken;
     const registered = await registerWithGateway(
       options.gatewayUrl,
       options.name,
-      tunnel.url,
+      resolvedTunnelUrl,
       options.gatewaySecret,
-      agentToken!,
+      token,
     );
     if (registered) {
       printCliLine(`registered with gateway as "${options.name}"`);
     }
 
-    // Start heartbeat
     const heartbeatTimer = startHeartbeat(
       options.gatewayUrl,
       options.name,
-      tunnel.url,
+      resolvedTunnelUrl,
       options.gatewaySecret,
-      agentToken!,
+      token,
       HEARTBEAT_INTERVAL_MS,
     );
 
-    // Cleanup on exit
     const cleanup = async () => {
       clearInterval(heartbeatTimer);
+      stopWsClient?.();
       printCliLine("unregistering from gateway...");
       await unregisterFromGateway(options.gatewayUrl, options.name, options.gatewaySecret);
-      tunnel.process.kill();
       process.exit(0);
     };
 
@@ -157,7 +175,6 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     printCliLine("WORKFLOW_GATEWAY_SECRET not set — skipping gateway registration");
   }
 
-  // Keep process alive
   await new Promise(() => {});
   return 0;
 }

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

@@ -3,6 +3,7 @@ export type ServeOptions = {
   hostname: string;
   name: string;
   noTunnel: boolean;
+  tunnelUrl: string | null;
   gatewayUrl: string;
   gatewaySecret: string;
 };

packages/cli-workflow/src/commands/serve/ws-client.ts

@@ -0,0 +1,165 @@
+import { parseWsRequestJson, type WsResponse } from "@uncaged/workflow-gateway/ws-protocol";
+import type { LogFn } from "@uncaged/workflow-util";
+
+export type GatewayWsClientParams = {
+  gatewayUrl: string;
+  name: string;
+  secret: string;
+  localPort: number;
+  log: LogFn;
+};
+
+const INITIAL_BACKOFF_MS = 1000;
+const MAX_BACKOFF_MS = 30_000;
+
+export function buildGatewayWsConnectUrl(gatewayUrl: string, name: string, secret: string): string {
+  const u = new URL(gatewayUrl);
+  if (u.protocol === "https:") {
+    u.protocol = "wss:";
+  } else if (u.protocol === "http:") {
+    u.protocol = "ws:";
+  }
+  u.pathname = "/ws/connect";
+  u.search = "";
+  u.searchParams.set("name", name);
+  u.searchParams.set("secret", secret);
+  return u.href;
+}
+
+function headersToRecord(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of h) {
+    out[k] = v;
+  }
+  return out;
+}
+
+async function handleGatewayMessage(
+  ws: WebSocket,
+  raw: string,
+  params: GatewayWsClientParams,
+): Promise<void> {
+  const req = parseWsRequestJson(raw);
+  if (req === null) {
+    params.log("ZM8K2PQ1", "gateway WebSocket dropped non-request message");
+    return;
+  }
+  const localUrl = `http://127.0.0.1:${String(params.localPort)}${req.path}`;
+  const initHeaders = new Headers();
+  for (const [k, v] of Object.entries(req.headers)) {
+    initHeaders.set(k, v);
+  }
+  let resp: Response;
+  try {
+    resp = await fetch(localUrl, {
+      method: req.method,
+      headers: initHeaders,
+      body: req.body === null ? undefined : req.body,
+    });
+  } catch (e) {
+    params.log("R4N7BQ3C", `local proxy fetch failed: ${String(e)}`);
+    const errBody: WsResponse = {
+      id: req.id,
+      status: 502,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ error: "local fetch failed", detail: String(e) }),
+    };
+    ws.send(JSON.stringify(errBody));
+    return;
+  }
+  const bodyText = await resp.text();
+  const headerRecord = headersToRecord(resp.headers);
+  const out: WsResponse = {
+    id: req.id,
+    status: resp.status,
+    headers: headerRecord,
+    body: bodyText,
+  };
+  ws.send(JSON.stringify(out));
+}
+
+/** Maintains a reverse WebSocket to the workflow gateway; reconnects with exponential backoff. */
+export function startGatewayWsClient(params: GatewayWsClientParams): () => void {
+  const wsUrl = buildGatewayWsConnectUrl(params.gatewayUrl, params.name, params.secret);
+  let socket: WebSocket | null = null;
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  let stopped = false;
+  let attempt = 0;
+
+  const clearReconnectTimer = (): void => {
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  };
+
+  const scheduleReconnect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    const delayMs = Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
+    attempt++;
+    params.log("6CJX2RLP", `gateway WebSocket reconnect in ${delayMs}ms (attempt ${attempt})`);
+    reconnectTimer = setTimeout(connect, delayMs);
+  };
+
+  const connect = (): void => {
+    if (stopped) {
+      return;
+    }
+    clearReconnectTimer();
+    params.log("2XK7HM9Q", "gateway WebSocket connecting...");
+    try {
+      socket = new WebSocket(wsUrl);
+    } catch (e) {
+      params.log("7NQW4HBT", `gateway WebSocket create failed: ${String(e)}`);
+      scheduleReconnect();
+      return;
+    }
+
+    const ws = socket;
+
+    ws.addEventListener("open", () => {
+      attempt = 0;
+      params.log("4PWN3V82", "gateway WebSocket connected");
+    });
+
+    ws.addEventListener("close", (ev) => {
+      socket = null;
+      params.log(
+        "8QTR6ZKC",
+        `gateway WebSocket closed code=${String(ev.code)} reason=${ev.reason} wasClean=${String(ev.wasClean)}`,
+      );
+      if (!stopped) {
+        scheduleReconnect();
+      }
+    });
+
+    ws.addEventListener("error", () => {
+      params.log("9BWS1M7F", "gateway WebSocket error");
+    });
+
+    ws.addEventListener("message", (ev) => {
+      const data = ev.data;
+      if (typeof data !== "string") {
+        params.log("T9W2KL5H", "gateway WebSocket non-text frame ignored");
+        return;
+      }
+      void handleGatewayMessage(ws, data, params).catch((e: unknown) => {
+        params.log("V7KX2M9P", `gateway WebSocket handler error: ${String(e)}`);
+      });
+    });
+  };
+
+  connect();
+
+  return (): void => {
+    stopped = true;
+    clearReconnectTimer();
+    if (socket !== null && socket.readyState === WebSocket.OPEN) {
+      socket.close(1000, "shutdown");
+    }
+    socket = null;
+  };
+}

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

@@ -0,0 +1,399 @@
+import { existsSync } from "node:fs";
+import { stdin as input, stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { resolve as resolvePath } from "node:path";
+
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
+
+import { createLogger } from "@uncaged/workflow-util";
+
+import { printCliError, printCliLine, printCliWarn } from "../../cli-output.js";
+
+const setupDispatchLog = createLogger({ sink: { kind: "stderr" } });
+import { loadPresetProviders } from "./preset-providers.js";
+import { cmdSetup, printSetupSummary } from "./setup.js";
+import type { SetupCliArgs } from "./types.js";
+
+type OpenAiModelEntry = {
+  id: string;
+};
+
+type OpenAiModelsResponse = {
+  data: OpenAiModelEntry[];
+};
+
+function usageSetup(): string {
+  return [
+    "uncaged-workflow setup — configure workflow.yaml providers and default model",
+    "",
+    "Non-interactive (agent mode):",
+    "  uncaged-workflow setup \\",
+    "    --provider <name> \\",
+    "    --base-url <url> \\",
+    "    --api-key <key> \\",
+    "    --default-model <provider/model> \\",
+    "    [--init-workspace <name>]",
+    "",
+    "Interactive: run with no flags (prompts for each value).",
+    "",
+    "Storage: uses the same root as other commands (see UNCAGED_WORKFLOW_STORAGE_ROOT).",
+  ].join("\n");
+}
+
+function requireNext(argv: string[], i: number, flag: string): Result<string, string> {
+  const next = argv[i + 1];
+  if (next === undefined || next.startsWith("--")) {
+    return err(`${flag} requires a value`);
+  }
+  return ok(next);
+}
+
+type ParsedSetup = SetupCliArgs | "interactive" | "help";
+
+type SetupFlagField = "provider" | "baseUrl" | "apiKey" | "defaultModel" | "initWorkspaceName";
+
+const SETUP_FLAG_TO_FIELD: Record<string, SetupFlagField> = {
+  "--provider": "provider",
+  "--base-url": "baseUrl",
+  "--api-key": "apiKey",
+  "--default-model": "defaultModel",
+  "--init-workspace": "initWorkspaceName",
+};
+
+function emptyFlagState(): Record<SetupFlagField, string | null> {
+  return {
+    provider: null,
+    baseUrl: null,
+    apiKey: null,
+    defaultModel: null,
+    initWorkspaceName: null,
+  };
+}
+
+function finalizeParsedSetup(
+  state: Record<SetupFlagField, string | null>,
+): Result<ParsedSetup, string> {
+  const hasAnyFlag =
+    state.provider !== null ||
+    state.baseUrl !== null ||
+    state.apiKey !== null ||
+    state.defaultModel !== null ||
+    state.initWorkspaceName !== null;
+
+  if (!hasAnyFlag) {
+    return ok("interactive");
+  }
+
+  if (state.provider === null) {
+    return err(
+      "non-interactive setup requires --provider (or omit all flags for interactive mode)",
+    );
+  }
+
+  const missing: string[] = [];
+  if (state.baseUrl === null) {
+    missing.push("--base-url");
+  }
+  if (state.apiKey === null) {
+    missing.push("--api-key");
+  }
+  if (state.defaultModel === null) {
+    missing.push("--default-model");
+  }
+  if (missing.length > 0) {
+    return err(`missing required flag(s): ${missing.join(", ")}`);
+  }
+
+  const b = state.baseUrl;
+  const k = state.apiKey;
+  const m = state.defaultModel;
+  if (b === null || k === null || m === null) {
+    return err("internal: missing required flags after validation");
+  }
+
+  return ok({
+    provider: state.provider,
+    baseUrl: b,
+    apiKey: k,
+    defaultModel: m,
+    initWorkspaceName: state.initWorkspaceName,
+  });
+}
+
+function parseSetupArgv(argv: string[]): Result<ParsedSetup, string> {
+  const state = emptyFlagState();
+
+  for (let i = 0; i < argv.length; i++) {
+    const tok = argv[i];
+    if (tok === undefined) {
+      break;
+    }
+    if (tok === "--help" || tok === "-h") {
+      return ok("help");
+    }
+    const field = SETUP_FLAG_TO_FIELD[tok];
+    if (field === undefined) {
+      return err(`unknown argument: ${tok}`);
+    }
+    const v = requireNext(argv, i, tok);
+    if (!v.ok) {
+      return v;
+    }
+    state[field] = v.value;
+    i++;
+  }
+
+  return finalizeParsedSetup(state);
+}
+
+async function promptLine(
+  rl: { question: (q: string) => Promise<string> },
+  label: string,
+): Promise<string> {
+  const raw = await rl.question(label);
+  return raw.trim();
+}
+
+/** Read a line with terminal echo disabled (for secrets). */
+async function promptSecret(label: string): Promise<string> {
+  process.stdout.write(label);
+  return new Promise((fulfill) => {
+    let buf = "";
+    const rawWasSet = process.stdin.isRaw;
+    if (process.stdin.isTTY) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    const onData = (chunk: string) => {
+      for (const c of chunk.toString()) {
+        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");
+          fulfill(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", onData);
+  });
+}
+
+/** Fetch available models from an OpenAI-compatible /models endpoint. */
+async function fetchAvailableModels(
+  baseUrl: string,
+  apiKey: string,
+): Promise<string[]> {
+  const url = baseUrl.replace(/\/+$/, "") + "/models";
+  try {
+    const res = await fetch(url, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) {
+      setupDispatchLog("R5KH7WM3", `GET ${url} returned ${res.status}`);
+      return [];
+    }
+    const body = (await res.json()) as OpenAiModelsResponse;
+    if (!Array.isArray(body.data)) {
+      return [];
+    }
+    // Filter out non-chat models. Some patterns are DashScope-specific (sambert, cosyvoice,
+    // wordart, wanx, wan2, paraformer) but harmless for other providers.
+    const NON_CHAT_RE =
+      /speech|embed|image|video|audio|ocr|rerank|tts|asr|paraformer|sambert|cosyvoice|wordart|wanx|wan2|flux|stable-diffusion|z-image|s2s|livetranslate|realtime|gui-/i;
+    return body.data
+      .map((m) => m.id)
+      .filter((id) => !NON_CHAT_RE.test(id))
+      .sort();
+  } catch (e) {
+    setupDispatchLog("V8NQ4JT6", `fetch models failed: ${e instanceof Error ? e.message : String(e)}`);
+    return [];
+  }
+}
+
+async function collectInteractiveSetup(): Promise<Result<SetupCliArgs, string>> {
+  const rl = createInterface({ input, output });
+  try {
+    printCliLine("Configure the LLM provider that workflow agents will use.\n");
+
+    const presets = loadPresetProviders();
+    const numWidth = String(presets.length + 1).length;
+    printCliLine("Select a provider:\n");
+    for (let i = 0; i < presets.length; i++) {
+      const p = presets[i]!;
+      const num = String(i + 1).padStart(numWidth);
+      printCliLine(`  ${num}) ${p.label.padEnd(28)} ${p.baseUrl}`);
+    }
+    const customNum = String(presets.length + 1).padStart(numWidth);
+    printCliLine(`  ${customNum}) Custom (enter name and URL manually)`);
+    printCliLine("");
+
+    const choice = await promptLine(rl, `Choose [1-${presets.length + 1}]: `);
+    const choiceNum = Number.parseInt(choice, 10);
+    if (Number.isNaN(choiceNum) || choiceNum < 1 || choiceNum > presets.length + 1) {
+      rl.close();
+      return err(`invalid choice: ${choice}`);
+    }
+
+    let provider: string;
+    let baseUrl: string;
+    if (choiceNum <= presets.length) {
+      const selected = presets[choiceNum - 1]!;
+      provider = selected.name;
+      baseUrl = selected.baseUrl;
+      printCliLine(`\n  → ${selected.label} (${baseUrl})\n`);
+    } else {
+      provider = await promptLine(rl, "Provider name (e.g. my-proxy): ");
+      if (provider === "") {
+        return err("provider name must not be empty");
+      }
+      baseUrl = await promptLine(rl, "OpenAI-compatible API base URL: ");
+      if (baseUrl === "") {
+        return err("base URL must not be empty");
+      }
+    }
+
+    // Close readline before raw-mode secret prompt, reopen after.
+    rl.close();
+    const apiKey = await promptSecret("API key for this provider: ");
+    if (apiKey === "") {
+      return err("API key must not be empty");
+    }
+    const rl2 = createInterface({ input, output });
+
+    // Try to list available models from the provider.
+    printCliLine("\nFetching available models...");
+    const models = await fetchAvailableModels(baseUrl, apiKey);
+    let selectedModel: string;
+    if (models.length > 0) {
+      printCliLine(`\nAvailable models (${models.length}):\n`);
+      const cols = process.stdout.columns || 80;
+      const nw = String(models.length).length; // number width
+      // Each cell: "  <num>) <model>  " — prefix is 2 + nw + 2 = nw+4
+      const prefixLen = nw + 4;
+      const maxModelLen = Math.max(...models.map((m) => m.length));
+      const cellWidth = prefixLen + maxModelLen + 2; // +2 gap between columns
+      const numCols = Math.max(1, Math.floor(cols / cellWidth));
+      for (let i = 0; i < models.length; i += numCols) {
+        const cells: string[] = [];
+        for (let j = i; j < Math.min(i + numCols, models.length); j++) {
+          const num = String(j + 1).padStart(nw);
+          cells.push(`  ${num}) ${(models[j]!).padEnd(maxModelLen + 2)}`);
+        }
+        printCliLine(cells.join(""));
+      }
+      printCliLine(`\nChoose a number, or type a model name directly.`);
+      const modelInput = await promptLine(rl2, `Default model [1-${models.length}]: `);
+      if (modelInput === "") {
+        rl2.close();
+        return err("default model must not be empty");
+      }
+      const modelNum = Number.parseInt(modelInput, 10);
+      if (!Number.isNaN(modelNum) && modelNum >= 1 && modelNum <= models.length) {
+        selectedModel = models[modelNum - 1]!;
+      } else {
+        // Treat as a literal model name.
+        selectedModel = modelInput;
+      }
+    } else {
+      printCliWarn("Could not fetch models (API may not support /models endpoint).");
+      const modelInput = await promptLine(rl2, `Default model (e.g. qwen-plus, gpt-4o): `);
+      if (modelInput === "") {
+        rl2.close();
+        return err("default model must not be empty");
+      }
+      selectedModel = modelInput;
+    }
+    // Strip provider prefix if user included one (e.g. pasted "MiniMax/MiniMax-M2.7").
+    const bare = selectedModel.includes("/") ? selectedModel.split("/").pop()! : selectedModel;
+    const defaultModel = `${provider}/${bare}`;
+    printCliLine(`  → ${defaultModel}`);
+
+    let initWorkspaceName: string | null = null;
+    // Loop until a valid workspace path is provided or the user skips.
+    while (true) {
+      const wsPath = await promptLine(
+        rl2,
+        "\nWorkflow workspace path (default: ./workflows, type 'skip' to skip): ",
+      );
+      if (wsPath.toLowerCase() === "skip") {
+        break;
+      }
+      const candidate = wsPath === "" ? "./workflows" : wsPath;
+      // Validate path before passing to cmdSetup.
+      const resolved = resolvePath(process.cwd(), candidate);
+      if (existsSync(resolved)) {
+        printCliWarn(`directory already exists: ${resolved}`);
+        printCliLine("Please enter a different path, or type 'skip' to skip.");
+        continue;
+      }
+      initWorkspaceName = candidate;
+      break;
+    }
+    rl2.close();
+
+    return ok({
+      provider,
+      baseUrl,
+      apiKey,
+      defaultModel,
+      initWorkspaceName,
+    });
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}
+
+export async function dispatchSetup(storageRoot: string, argv: string[]): Promise<number> {
+  const parsed = parseSetupArgv(argv);
+  if (!parsed.ok) {
+    printCliError(`${parsed.error}\n\n${usageSetup()}`);
+    return 1;
+  }
+  if (parsed.value === "help") {
+    printCliLine(usageSetup());
+    return 0;
+  }
+
+  let args: SetupCliArgs;
+  if (parsed.value === "interactive") {
+    const collected = await collectInteractiveSetup();
+    if (!collected.ok) {
+      printCliError(collected.error);
+      return 1;
+    }
+    args = collected.value;
+  } else {
+    args = parsed.value;
+  }
+
+  const result = await cmdSetup(storageRoot, args);
+  if (!result.ok) {
+    printCliError(result.error);
+    return 1;
+  }
+  printSetupSummary(result.value);
+  return 0;
+}

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

@@ -0,0 +1,4 @@
+export { dispatchSetup } from "./dispatch.js";
+export { loadPresetProviders } from "./preset-providers.js";
+export { cmdSetup, printSetupSummary } from "./setup.js";
+export type { CmdSetupSuccess, PresetProvider, SetupCliArgs } from "./types.js";

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

@@ -0,0 +1,49 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import type { PresetProvider } from "./types.js";
+
+
+
+type RawPresetEntry = {
+	name: unknown;
+	label: unknown;
+	baseUrl: unknown;
+};
+
+function isRawEntry(v: unknown): v is RawPresetEntry {
+	if (typeof v !== "object" || v === null) return false;
+	const o = v as Record<string, unknown>;
+	return typeof o.name === "string" && typeof o.label === "string" && typeof o.baseUrl === "string";
+}
+
+let cached: ReadonlyArray<PresetProvider> | null = null;
+
+export function loadPresetProviders(): ReadonlyArray<PresetProvider> {
+	if (cached !== null) return cached;
+
+	const yamlPath = join(import.meta.dirname, "providers.yaml");
+	const raw = readFileSync(yamlPath, "utf8");
+	const parsed: unknown = parseYaml(raw);
+
+	if (!Array.isArray(parsed)) {
+		throw new Error(`providers.yaml: expected array, got ${typeof parsed}`);
+	}
+
+	const result: PresetProvider[] = [];
+	for (const entry of parsed) {
+		if (!isRawEntry(entry)) {
+			throw new Error(`providers.yaml: invalid entry: ${JSON.stringify(entry)}`);
+		}
+		result.push({
+			name: entry.name as string,
+			label: entry.label as string,
+			baseUrl: entry.baseUrl as string,
+		});
+	}
+
+	cached = result;
+	return result;
+}

packages/cli-workflow/src/commands/setup/providers.yaml

@@ -0,0 +1,73 @@
+# Preset LLM providers for `uncaged-workflow setup`.
+# Each entry needs a provider name (used in workflow.yaml) and an OpenAI-compatible base URL.
+# Add new providers here — no code changes required.
+
+# ── International ──────────────────────────────────────────
+
+- name: openai
+  label: OpenAI
+  baseUrl: https://api.openai.com/v1
+
+- name: xai
+  label: xAI
+  baseUrl: https://api.x.ai/v1
+
+- name: openrouter
+  label: OpenRouter
+  baseUrl: https://openrouter.ai/api/v1
+
+- name: venice
+  label: Venice
+  baseUrl: https://api.venice.ai/api/v1
+
+# ── China ──────────────────────────────────────────────────
+
+- name: dashscope
+  label: DashScope (Alibaba)
+  baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
+
+- name: deepseek
+  label: DeepSeek
+  baseUrl: https://api.deepseek.com/v1
+
+- name: siliconflow
+  label: SiliconFlow
+  baseUrl: https://api.siliconflow.cn/v1
+
+- name: volcengine
+  label: Volcengine (ByteDance)
+  baseUrl: https://ark.cn-beijing.volces.com/api/v3
+
+- name: kimi
+  label: Kimi (Moonshot)
+  baseUrl: https://api.moonshot.cn/v1
+
+- name: glm
+  label: GLM (Zhipu AI)
+  baseUrl: https://open.bigmodel.cn/api/paas/v4
+
+- name: glm-intl
+  label: GLM (Zhipu AI Intl)
+  baseUrl: https://api.z.ai/api/paas/v4
+
+- name: stepfun
+  label: StepFun
+  baseUrl: https://api.stepfun.com/v1
+
+- name: minimax
+  label: MiniMax
+  baseUrl: https://api.minimax.io/v1
+
+- name: tencent
+  label: Tencent TokenHub
+  baseUrl: https://tokenhub.tencentmaas.com/v1
+
+- name: xiaomi
+  label: Xiaomi MiMo
+  baseUrl: https://api.xiaomimimo.com/v1
+
+# ── Local ──────────────────────────────────────────────────
+
+- name: ollama
+  label: Ollama (local)
+  baseUrl: http://localhost:11434/v1

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

@@ -0,0 +1,105 @@
+import { err, ok, type Result, type WorkflowConfig } from "@uncaged/workflow-protocol";
+import {
+  readWorkflowRegistry,
+  splitProviderModelRef,
+  workflowRegistryPath,
+  writeWorkflowRegistry,
+} from "@uncaged/workflow-register";
+import { createLogger } from "@uncaged/workflow-util";
+
+import { printCliLine } from "../../cli-output.js";
+import { cmdInitWorkspace } from "../init/index.js";
+import type { CmdSetupSuccess, SetupCliArgs } from "./types.js";
+
+const setupLog = createLogger({ sink: { kind: "stderr" } });
+
+
+
+function mergeWorkflowConfig(
+  prev: WorkflowConfig | null,
+  input: SetupCliArgs,
+): Result<WorkflowConfig, string> {
+  const modelSplit = splitProviderModelRef(input.defaultModel);
+  if (!modelSplit.ok) {
+    return err(modelSplit.error);
+  }
+  if (modelSplit.value.providerName !== input.provider) {
+    return err(
+      `default model provider "${modelSplit.value.providerName}" must match --provider "${input.provider}"`,
+    );
+  }
+
+  const maxDepth = prev === null ? 3 : prev.maxDepth;
+  const supervisorInterval = prev === null ? 3 : prev.supervisorInterval;
+  const providers = {
+    ...(prev === null ? {} : prev.providers),
+    [input.provider]: { baseUrl: input.baseUrl, apiKey: input.apiKey },
+  };
+  const models = { ...(prev === null ? {} : prev.models), default: input.defaultModel };
+
+  return ok({
+    maxDepth,
+    supervisorInterval,
+    providers,
+    models,
+  });
+}
+
+export async function cmdSetup(
+  storageRoot: string,
+  input: SetupCliArgs,
+): Promise<Result<CmdSetupSuccess, string>> {
+  const readResult = await readWorkflowRegistry(storageRoot);
+  if (!readResult.ok) {
+    setupLog("W8JH4Q2K", `read workflow registry failed: ${readResult.error.message}`);
+    return err(readResult.error.message);
+  }
+
+  const current = readResult.value;
+  const merged = mergeWorkflowConfig(current.config, input);
+  if (!merged.ok) {
+    return merged;
+  }
+  const nextConfig = merged.value;
+  const nextRegistry = {
+    config: nextConfig,
+    workflows: current.workflows,
+  };
+
+  const written = await writeWorkflowRegistry(storageRoot, nextRegistry);
+  if (!written.ok) {
+    setupLog("M2NB5VX9", `write workflow registry failed: ${written.error.message}`);
+    return err(written.error.message);
+  }
+
+  const registryPath = workflowRegistryPath(storageRoot);
+
+  let initWorkspaceRootPath: string | null = null;
+  if (input.initWorkspaceName !== null) {
+    const initResult = await cmdInitWorkspace(process.cwd(), input.initWorkspaceName);
+    if (!initResult.ok) {
+      setupLog("T7QC4HWP", `init workspace failed: ${initResult.error}`);
+      return err(initResult.error);
+    }
+    initWorkspaceRootPath = initResult.value.rootPath;
+  }
+
+  return ok({
+    registryPath,
+    provider: input.provider,
+    defaultModel: input.defaultModel,
+    maxDepth: nextConfig.maxDepth,
+    supervisorInterval: nextConfig.supervisorInterval,
+    initWorkspaceRootPath,
+  });
+}
+
+export function printSetupSummary(result: CmdSetupSuccess): void {
+  printCliLine(`wrote registry: ${result.registryPath}`);
+  printCliLine(`provider "${result.provider}" (baseUrl + apiKey updated)`);
+  printCliLine(`config.models.default = "${result.defaultModel}"`);
+  printCliLine(`maxDepth=${result.maxDepth}, supervisorInterval=${result.supervisorInterval}`);
+  if (result.initWorkspaceRootPath !== null) {
+    printCliLine(`initialized workflow workspace at ${result.initWorkspaceRootPath}`);
+  }
+}

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

@@ -0,0 +1,23 @@
+/** Parsed non-interactive `setup` CLI arguments (all fields required for agent mode). */
+export type SetupCliArgs = {
+  provider: string;
+  baseUrl: string;
+  apiKey: string;
+  defaultModel: string;
+  initWorkspaceName: string | null;
+};
+
+export type PresetProvider = {
+  name: string;
+  label: string;
+  baseUrl: string;
+};
+
+export type CmdSetupSuccess = {
+  registryPath: string;
+  provider: string;
+  defaultModel: string;
+  maxDepth: number;
+  supervisorInterval: number;
+  initWorkspaceRootPath: string | null;
+};

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

@@ -1,4 +1,4 @@
-import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
+import { createCasStore, getContentMerklePayload, parseCasThreadNode } from "@uncaged/workflow-cas";
 import { FORK_BRANCH_ROLE, walkStateFramesNewestFirst } from "@uncaged/workflow-execute";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import { END } from "@uncaged/workflow-runtime";
@@ -6,6 +6,21 @@ import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 import { resolveThreadRecord } from "../../thread-scan.js";
 
+async function readParentStateFromStartNode(
+  cas: { get(hash: string): Promise<string | null> },
+  startHash: string,
+): Promise<string | null> {
+  const yamlText = await cas.get(startHash);
+  if (yamlText === null) {
+    return null;
+  }
+  const parsed = parseCasThreadNode(yamlText);
+  if (parsed === null || parsed.kind !== "start") {
+    return null;
+  }
+  return parsed.node.payload.parentState;
+}
+
 export async function cmdThreadShow(
   storageRoot: string,
   threadId: string,
@@ -19,7 +34,15 @@ export async function cmdThreadShow(
   const frames = await walkStateFramesNewestFirst(cas, resolved.head);
   const chronological = [...frames].reverse();
 
-  const steps: Array<{ role: string; hash: string; timestamp: number; content: string }> = [];
+  const parentState = await readParentStateFromStartNode(cas, resolved.start);
+
+  const steps: Array<{
+    role: string;
+    hash: string;
+    timestamp: number;
+    content: string;
+    childThread: string | null;
+  }> = [];
   for (const fr of chronological) {
     if (fr.payload.role === END || fr.payload.role === FORK_BRANCH_ROLE) {
       continue;
@@ -33,6 +56,7 @@ export async function cmdThreadShow(
         payloadText !== null
           ? payloadText
           : `(content not in CAS; contentHash=${fr.payload.content})`,
+      childThread: fr.payload.childThread,
     });
   }
 
@@ -41,6 +65,7 @@ export async function cmdThreadShow(
     bundleHash: resolved.bundleHash,
     head: resolved.head,
     start: resolved.start,
+    parentState,
     source: resolved.source,
     steps,
   };

packages/cli-workflow/src/skill.ts

@@ -54,8 +54,9 @@ function formatSkillCli(): string {
   const commandSections: string[] = [];
   for (const group of groups) {
     const rows = group.commands.map((cmd) => {
+      const namePart = cmd.name === "" ? "" : ` ${cmd.name}`;
       const args = cmd.args ? `\`${cmd.args}\`` : "(none)";
-      return `| \`${group.name} ${cmd.name}\` | ${args} | ${cmd.description} |`;
+      return `| \`${group.name}${namePart}\` | ${args} | ${cmd.description} |`;
     });
     commandSections.push(
       `### ${group.name}\n\n| Command | Args | Description |\n|---------|------|-------------|\n${rows.join("\n")}`,
@@ -189,25 +190,28 @@ export const run: WorkflowRun;
 
 ## WorkflowDescriptor
 
-Defines the workflow's metadata and role sequence:
+Serialized metadata for the registry (per-role JSON Schema plus a static routing graph):
 
 \`\`\`typescript
 type WorkflowDescriptor = {
-  name: string;           // verb-first kebab-case, e.g. "solve-issue"
-  description: string;    // one-line summary
-  roles: string[];        // ordered role names, e.g. ["planner", "coder", "reviewer"]
+  description: string;
+  roles: Record<string, { description: string; schema: unknown /* JSON Schema */ }>;
+  graph: {
+    edges: Array<{
+      from: string;
+      to: string;
+      condition: string;
+      conditionDescription: string | null;
+    }>;
+  };
 };
 \`\`\`
 
 ## WorkflowRun
 
-The main function that creates and returns a moderator:
+Async generator from \`createWorkflow(definition, binding)\` (**@uncaged/workflow-runtime**) — yields each role output until the workflow completes.
 
-\`\`\`typescript
-type WorkflowRun = (ctx: WorkflowContext) => Moderator;
-\`\`\`
-
-The **Moderator** controls the flow — it decides which role runs next, handles retries, and determines when the workflow is complete.
+The **ModeratorTable** on **WorkflowDefinition** is declarative routing (from each role and \`START\` to the next role or \`END\`); the engine evaluates conditions at runtime.
 
 ## Role Definition
 
@@ -226,7 +230,7 @@ Each role has:
 # 1. Initialize a workspace
 uncaged-workflow init workspace my-workflow
 
-# 2. Write your template (roles + moderator + descriptor)
+# 2. Write your template (roles + ModeratorTable + descriptor)
 
 # 3. Build the ESM bundle
 bun run build

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

@@ -2,20 +2,49 @@ import { describe, expect, test } from "bun:test";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 
 describe("validateCursorAgentConfig", () => {
-  test("accepts valid config", () => {
+  test("accepts valid config with explicit workspace", () => {
     const r = validateCursorAgentConfig({
+      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "/tmp/test-project",
+      llmProvider: null,
     });
     expect(r.ok).toBe(true);
   });
 
-  test("rejects non-function extract", () => {
+  test("accepts valid config with null workspace and llmProvider", () => {
     const r = validateCursorAgentConfig({
+      command: "/usr/local/bin/cursor-agent",
+      model: null,
+      timeout: 0,
+      workspace: null,
+      llmProvider: { baseUrl: "http://localhost", apiKey: "test", model: "test" },
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  test("rejects non-absolute command", () => {
+    const r = validateCursorAgentConfig({
+      command: "cursor-agent",
+      model: null,
+      timeout: 0,
+      workspace: "/tmp/test-project",
+      llmProvider: null,
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("absolute path");
+    }
+  });
+
+  test("rejects empty workspace string", () => {
+    const r = validateCursorAgentConfig({
+      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "",
+      llmProvider: null,
     });
     expect(r.ok).toBe(false);
     if (!r.ok) {
@@ -23,33 +52,74 @@ describe("validateCursorAgentConfig", () => {
     }
   });
 
+  test("rejects null workspace without llmProvider", () => {
+    const r = validateCursorAgentConfig({
+      command: "/usr/local/bin/cursor-agent",
+      model: null,
+      timeout: 0,
+      workspace: null,
+      llmProvider: null,
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("llmProvider");
+    }
+  });
+
   test("rejects negative timeout", () => {
     const r = validateCursorAgentConfig({
+      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: -1,
       workspace: "/tmp/test-project",
+      llmProvider: null,
     });
     expect(r.ok).toBe(false);
   });
 });
 
 describe("createCursorAgent", () => {
-  test("returns an AgentFn", () => {
+  test("returns an AgentFn with explicit workspace", () => {
     const agent = createCursorAgent({
+      command: "/usr/local/bin/cursor-agent",
       model: null,
       timeout: 0,
       workspace: "/tmp/test-project",
+      llmProvider: null,
     });
     expect(typeof agent).toBe("function");
   });
 
-  test("throws on invalid config at construction", () => {
-    expect(() =>
-      createCursorAgent({
-        model: null,
-        timeout: -1,
-        workspace: "/tmp/test-project",
-      }),
-    ).toThrow();
+  test("returns an AgentFn with null workspace and llmProvider", () => {
+    const agent = createCursorAgent({
+      command: "/usr/local/bin/cursor-agent",
+      model: null,
+      timeout: 0,
+      workspace: null,
+      llmProvider: { baseUrl: "http://localhost", apiKey: "test", model: "test" },
+    });
+    expect(typeof agent).toBe("function");
+  });
+
+  test("defers validation to call time (invalid config does not throw at construction)", () => {
+    const agent = createCursorAgent({
+      command: "/usr/local/bin/cursor-agent",
+      model: null,
+      timeout: -1,
+      workspace: "/tmp/test-project",
+      llmProvider: null,
+    });
+    expect(typeof agent).toBe("function");
+  });
+
+  test("defers validation — null workspace without llmProvider does not throw at construction", () => {
+    const agent = createCursorAgent({
+      command: "/usr/local/bin/cursor-agent",
+      model: null,
+      timeout: 0,
+      workspace: null,
+      llmProvider: null,
+    });
+    expect(typeof agent).toBe("function");
   });
 });

packages/workflow-agent-cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-cursor",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -8,7 +8,10 @@
     "test": "bun test"
   },
   "dependencies": {
+    "@uncaged/workflow-protocol": "workspace:*",
+    "@uncaged/workflow-reactor": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
+    "@uncaged/workflow-util": "workspace:*",
     "@uncaged/workflow-util-agent": "workspace:*",
     "zod": "^4.0.0"
   }

packages/workflow-agent-cursor/src/extract-workspace.ts

@@ -0,0 +1,73 @@
+import type { AgentContext, LlmProvider } from "@uncaged/workflow-protocol";
+import { createLlmFn, createThreadReactor } from "@uncaged/workflow-reactor";
+import type { LogFn } from "@uncaged/workflow-util";
+import * as z from "zod/v4";
+
+const workspaceSchema = z.object({
+  workspace: z.string().describe("Absolute filesystem path of the project workspace"),
+});
+
+const EXTRACT_SYSTEM_FN = (_toolName: string) =>
+  `You are a workspace-path extractor. Given a workflow agent context (task description and previous step outputs), identify the absolute filesystem path of the project workspace where code changes should be made. Call the tool with the absolute path.`;
+
+function buildExtractionInput(ctx: AgentContext): string {
+  const lines: string[] = [];
+  lines.push("## Task");
+  lines.push(ctx.start.content);
+
+  for (const step of ctx.steps) {
+    lines.push("");
+    lines.push(`## Step: ${step.role}`);
+    lines.push(`Meta: ${JSON.stringify(step.meta)}`);
+  }
+
+  return lines.join("\n");
+}
+
+export async function extractWorkspacePath(
+  ctx: AgentContext,
+  provider: LlmProvider,
+  logger: LogFn,
+): Promise<string | null> {
+  const reactor = createThreadReactor<null>({
+    llm: createLlmFn(provider),
+    maxRounds: 2,
+    staticTools: [],
+    structuredToolFromSchema: (schema) => {
+      const jsonSchema = z.toJSONSchema(schema);
+      return {
+        name: "set_workspace",
+        tool: {
+          type: "function" as const,
+          function: {
+            name: "set_workspace",
+            description: "Set the extracted workspace path",
+            parameters: jsonSchema as Record<string, unknown>,
+          },
+        },
+      };
+    },
+    systemPromptForStructuredTool: EXTRACT_SYSTEM_FN,
+    toolHandler: async () => "unknown tool",
+  });
+
+  const result = await reactor({
+    thread: null,
+    input: buildExtractionInput(ctx),
+    schema: workspaceSchema,
+  });
+
+  if (!result.ok) {
+    logger("W8KN3QYT", `workspace extraction failed: ${result.error}`);
+    return null;
+  }
+
+  const workspace = result.value.workspace.trim();
+  if (!workspace.startsWith("/")) {
+    logger("H4PM7RXV", `workspace extraction returned non-absolute path: ${workspace}`);
+    return null;
+  }
+
+  logger("V3KM8QWP", `extracted workspace: ${workspace}`);
+  return workspace;
+}

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

@@ -1,6 +1,8 @@
 import type { AgentFn } from "@uncaged/workflow-runtime";
+import { createLogger } from "@uncaged/workflow-util";
 import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
 
+import { extractWorkspacePath } from "./extract-workspace.js";
 import type { CursorAgentConfig } from "./types.js";
 import { validateCursorAgentConfig } from "./validate-config.js";
 
@@ -26,18 +28,36 @@ function resolveCursorModel(model: string | null): string {
   return model === null ? "auto" : model;
 }
 
-/** Runs `cursor-agent` with workspace from {@link CursorAgentConfig.extract} and prompt from context. */
+/** Runs `cursor-agent` with workspace from config or extracted from context via LLM. */
 export function createCursorAgent(config: CursorAgentConfig): AgentFn {
-  const validated = validateCursorAgentConfig(config);
-  if (!validated.ok) {
-    throw new Error(validated.error);
-  }
-
   const modelFlag = resolveCursorModel(config.model);
   const timeoutMs = config.timeout > 0 ? config.timeout : null;
+  const logger = createLogger({ sink: { kind: "stderr" } });
 
   return async (ctx) => {
-    const workspace = config.workspace;
+    const validated = validateCursorAgentConfig(config);
+    if (!validated.ok) {
+      throw new Error(validated.error);
+    }
+
+    let workspace: string;
+
+    if (config.workspace !== null) {
+      workspace = config.workspace;
+    } else {
+      if (config.llmProvider === null) {
+        throw new Error("cursor-agent: llmProvider is required when workspace is null");
+      }
+      const extracted = await extractWorkspacePath(ctx, config.llmProvider, logger);
+      if (extracted === null) {
+        throw new Error(
+          "cursor-agent: failed to extract workspace path from context. Provide an explicit workspace or ensure previous steps include a repoPath.",
+        );
+      }
+      workspace = extracted;
+    }
+
+    logger("R5HN3YKQ", `cursor-agent workspace: ${workspace}`);
     const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "-p",
@@ -51,7 +71,7 @@ export function createCursorAgent(config: CursorAgentConfig): AgentFn {
       "--trust",
       "--force",
     ];
-    const run = await spawnCli("cursor-agent", args, {
+    const run = await spawnCli(config.command, args, {
       cwd: workspace,
       timeoutMs,
     });

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

@@ -1,5 +1,12 @@
+import type { LlmProvider } from "@uncaged/workflow-protocol";
+
 export type CursorAgentConfig = {
+  /** Absolute path to the cursor-agent CLI binary. */
+  command: string;
   model: string | null;
   timeout: number;
-  workspace: string;
+  /** Explicit workspace path. When `null`, the agent extracts workspace from AgentContext via a ReAct LLM call. */
+  workspace: string | null;
+  /** Required when `workspace` is `null` — LLM provider used for workspace extraction. */
+  llmProvider: LlmProvider | null;
 };

packages/workflow-agent-cursor/src/validate-config.ts

@@ -1,10 +1,18 @@
-import { err, ok, type Result } from "@uncaged/workflow-runtime";
+import { isAbsolute } from "node:path";
+
+import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import type { CursorAgentConfig } from "./types.js";
 
 export function validateCursorAgentConfig(config: CursorAgentConfig): Result<void, string> {
-  if (typeof config.workspace !== "string" || config.workspace.length === 0) {
-    return err("workspace must be a non-empty string (absolute path)");
+  if (!isAbsolute(config.command)) {
+    return err("command must be an absolute path to the cursor-agent CLI binary");
+  }
+  if (config.workspace !== null && config.workspace.length === 0) {
+    return err("workspace must be a non-empty string (absolute path) or null for auto-detection");
+  }
+  if (config.workspace === null && config.llmProvider === null) {
+    return err("llmProvider is required when workspace is null (needed for workspace extraction)");
   }
   if (config.timeout < 0) {
     return err("timeout must be a non-negative number (milliseconds); use 0 for no limit");

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

@@ -4,14 +4,28 @@ import { createHermesAgent, validateHermesAgentConfig } from "../src/index.js";
 describe("validateHermesAgentConfig", () => {
   test("accepts valid config", () => {
     const r = validateHermesAgentConfig({
+      command: "/usr/local/bin/hermes",
       model: null,
       timeout: null,
     });
     expect(r.ok).toBe(true);
   });
 
+  test("rejects non-absolute command", () => {
+    const r = validateHermesAgentConfig({
+      command: "hermes",
+      model: null,
+      timeout: null,
+    });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toContain("absolute path");
+    }
+  });
+
   test("rejects negative timeout", () => {
     const r = validateHermesAgentConfig({
+      command: "/usr/local/bin/hermes",
       model: null,
       timeout: -5,
     });
@@ -23,10 +37,11 @@ describe("validateHermesAgentConfig", () => {
 });
 
 describe("createHermesAgent", () => {
-  test("returns an AgentFn", () => {
+  test("returns an AgentFn even with invalid config (validation deferred to call)", () => {
     const agent = createHermesAgent({
+      command: "/usr/local/bin/hermes",
       model: null,
-      timeout: null,
+      timeout: -5,
     });
     expect(typeof agent).toBe("function");
   });

packages/workflow-agent-hermes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-hermes",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

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

@@ -26,14 +26,14 @@ function throwHermesSpawnError(error: SpawnCliError): never {
 
 /** Runs `hermes chat` non-interactively with the Nerve-style argv contract (`-q`, `--yolo`, `--quiet`). */
 export function createHermesAgent(config: HermesAgentConfig): AgentFn {
-  const validated = validateHermesAgentConfig(config);
-  if (!validated.ok) {
-    throw new Error(validated.error);
-  }
-
   const timeoutMs = config.timeout;
 
   return async (ctx) => {
+    const validated = validateHermesAgentConfig(config);
+    if (!validated.ok) {
+      throw new Error(validated.error);
+    }
+
     const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "chat",
@@ -47,7 +47,7 @@ export function createHermesAgent(config: HermesAgentConfig): AgentFn {
     if (config.model !== null) {
       args.push("--model", config.model);
     }
-    const run = await spawnCli("hermes", args, {
+    const run = await spawnCli(config.command, args, {
       cwd: null,
       timeoutMs,
     });

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

@@ -1,4 +1,6 @@
 export type HermesAgentConfig = {
+  /** Absolute path to the hermes CLI binary. */
+  command: string;
   model: string | null;
   timeout: number | null;
 };

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

@@ -1,8 +1,13 @@
+import { isAbsolute } from "node:path";
+
 import { err, ok, type Result } from "@uncaged/workflow-runtime";
 
 import type { HermesAgentConfig } from "./types.js";
 
 export function validateHermesAgentConfig(config: HermesAgentConfig): Result<void, string> {
+  if (!isAbsolute(config.command)) {
+    return err("command must be an absolute path to the hermes CLI binary");
+  }
   if (config.timeout !== null && config.timeout < 0) {
     return err("timeout must be null or a non-negative number (milliseconds)");
   }

packages/workflow-agent-llm/__tests__/create-llm-adapter.test.ts

@@ -10,8 +10,10 @@ function makeCtx(userContent: string): AgentContext {
       content: userContent,
       meta: {},
       timestamp: 1,
+      parentState: null,
     },
     depth: 0,
+    bundleHash: "TESTHASH00001",
     steps: [],
     threadId: "01TEST000000000000000000TR",
     currentRole: { name: "planner", systemPrompt: "system instructions" },

packages/workflow-agent-llm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-agent-llm",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

packages/workflow-cas/__tests__/collect-refs.test.ts

@@ -14,6 +14,7 @@ function payload(
     ancestors: partial.ancestors ?? [],
     compact: partial.compact ?? null,
     timestamp: partial.timestamp ?? 0,
+    childThread: partial.childThread ?? null,
   };
 }
 
@@ -62,4 +63,32 @@ describe("collectRefs", () => {
     );
     expect(refs).toEqual(["S2", "C2"]);
   });
+
+  test("includes childThread hash when childThread is non-null", () => {
+    const refs = collectRefs(
+      payload({
+        role: "developer",
+        start: "S3",
+        content: "C3",
+        ancestors: ["A3"],
+        compact: null,
+        childThread: "CHILDEND000000000000001",
+      }),
+    );
+    expect(refs).toEqual(["S3", "C3", "A3", "CHILDEND000000000000001"]);
+  });
+
+  test("does not include childThread when childThread is null", () => {
+    const refs = collectRefs(
+      payload({
+        role: "developer",
+        start: "S4",
+        content: "C4",
+        ancestors: [],
+        compact: null,
+        childThread: null,
+      }),
+    );
+    expect(refs).toEqual(["S4", "C4"]);
+  });
 });

packages/workflow-cas/__tests__/nodes.test.ts

@@ -0,0 +1,161 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stringify } from "yaml";
+
+import { createCasStore } from "../src/cas.js";
+import { parseCasThreadNode, putStartNode, putStateNode } from "../src/nodes.js";
+
+describe("putStartNode — parentState in refs", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "wf-cas-nodes-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("refs contains only promptHash when parentState is null", async () => {
+    const cas = createCasStore(join(dir, "cas"));
+    const promptHash = await cas.put("hello");
+    const startHash = await putStartNode(
+      cas,
+      { name: "demo", hash: "BUNDLEAAAAAAAAA", depth: 0, parentState: null },
+      promptHash,
+    );
+
+    const blob = await cas.get(startHash);
+    expect(blob).not.toBeNull();
+    const parsed = parseCasThreadNode(blob ?? "");
+    expect(parsed).not.toBeNull();
+    expect(parsed?.kind).toBe("start");
+    if (parsed?.kind !== "start") return;
+
+    expect(parsed.node.refs).toEqual([promptHash]);
+    expect(parsed.node.payload.parentState).toBeNull();
+  });
+
+  test("refs contains [promptHash, parentStateHash] when parentState is set", async () => {
+    const cas = createCasStore(join(dir, "cas"));
+    const parentStateHash = await cas.put("fake-parent-state");
+    const promptHash = await cas.put("child-prompt");
+    const startHash = await putStartNode(
+      cas,
+      { name: "develop", hash: "BUNDLEBBBBBBBBB", depth: 1, parentState: parentStateHash },
+      promptHash,
+    );
+
+    const blob = await cas.get(startHash);
+    expect(blob).not.toBeNull();
+    const parsed = parseCasThreadNode(blob ?? "");
+    expect(parsed).not.toBeNull();
+    expect(parsed?.kind).toBe("start");
+    if (parsed?.kind !== "start") return;
+
+    expect(parsed.node.refs).toEqual([promptHash, parentStateHash]);
+    expect(parsed.node.payload.parentState).toBe(parentStateHash);
+  });
+});
+
+describe("putStateNode — childThread in refs", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "wf-cas-nodes-state-"));
+  });
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("refs does not include childThread when childThread is null", async () => {
+    const cas = createCasStore(join(dir, "cas"));
+    const startHash = await cas.put("start");
+    const contentHash = await cas.put("content");
+    const stateHash = await putStateNode(cas, {
+      role: "planner",
+      meta: {},
+      start: startHash,
+      content: contentHash,
+      ancestors: [],
+      compact: null,
+      timestamp: 1000,
+      childThread: null,
+    });
+
+    const blob = await cas.get(stateHash);
+    expect(blob).not.toBeNull();
+    const parsed = parseCasThreadNode(blob ?? "");
+    expect(parsed?.kind).toBe("state");
+    if (parsed?.kind !== "state") return;
+
+    expect(parsed.node.refs).not.toContain("anything-else");
+    expect(parsed.node.refs).toEqual([startHash, contentHash]);
+    expect(parsed.node.payload.childThread).toBeNull();
+  });
+
+  test("refs includes childThread hash when childThread is set", async () => {
+    const cas = createCasStore(join(dir, "cas"));
+    const startHash = await cas.put("start");
+    const contentHash = await cas.put("content");
+    const childEndHash = await cas.put("child-end-state");
+    const stateHash = await putStateNode(cas, {
+      role: "developer",
+      meta: { pr: 42 },
+      start: startHash,
+      content: contentHash,
+      ancestors: [],
+      compact: null,
+      timestamp: 2000,
+      childThread: childEndHash,
+    });
+
+    const blob = await cas.get(stateHash);
+    expect(blob).not.toBeNull();
+    const parsed = parseCasThreadNode(blob ?? "");
+    expect(parsed?.kind).toBe("state");
+    if (parsed?.kind !== "state") return;
+
+    expect(parsed.node.refs).toContain(childEndHash);
+    expect(parsed.node.payload.childThread).toBe(childEndHash);
+  });
+});
+
+describe("parseCasThreadNode — legacy node compatibility", () => {
+  test("start node without parentState field defaults to null", () => {
+    const yaml = stringify({
+      type: "start",
+      payload: { name: "demo", hash: "BUNDLEAAAAAAAAA", depth: 0 },
+      refs: ["PROMPTHASH00001"],
+    });
+    const parsed = parseCasThreadNode(yaml);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.kind).toBe("start");
+    if (parsed?.kind !== "start") return;
+    expect(parsed.node.payload.parentState).toBeNull();
+  });
+
+  test("state node without childThread field defaults to null", () => {
+    const yaml = stringify({
+      type: "state",
+      payload: {
+        role: "planner",
+        meta: {},
+        start: "STARTHASH00001",
+        content: "CONTENTHASH0001",
+        ancestors: [],
+        compact: null,
+        timestamp: 1000,
+      },
+      refs: ["STARTHASH00001", "CONTENTHASH0001"],
+    });
+    const parsed = parseCasThreadNode(yaml);
+    expect(parsed).not.toBeNull();
+    expect(parsed?.kind).toBe("state");
+    if (parsed?.kind !== "state") return;
+    expect(parsed.node.payload.childThread).toBeNull();
+  });
+});

packages/workflow-cas/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-cas",
-  "version": "0.1.0",
+  "version": "0.3.5",
   "type": "module",
   "scripts": {
     "test": "bun test"

packages/workflow-cas/src/collect-refs.ts

@@ -9,5 +9,8 @@ export function collectRefs(payload: StateNode["payload"]): string[] {
   if (payload.compact !== null) {
     out.push(payload.compact);
   }
+  if (payload.childThread !== null) {
+    out.push(payload.childThread);
+  }
   return out;
 }

packages/workflow-cas/src/nodes.ts

@@ -18,6 +18,10 @@ function isStartPayload(value: unknown): value is StartNodePayload {
   if (!isRecord(value)) {
     return false;
   }
+  const parentState = value.parentState;
+  if (parentState !== undefined && parentState !== null && typeof parentState !== "string") {
+    return false;
+  }
   return (
     typeof value.name === "string" &&
     typeof value.hash === "string" &&
@@ -25,6 +29,16 @@ function isStartPayload(value: unknown): value is StartNodePayload {
   );
 }
 
+/** Normalizes a raw start payload, defaulting `parentState` to `null` for legacy nodes. */
+function normalizeStartPayload(raw: StartNodePayload): StartNodePayload {
+  return {
+    name: raw.name,
+    hash: raw.hash,
+    depth: raw.depth,
+    parentState: raw.parentState ?? null,
+  };
+}
+
 function isStatePayload(value: unknown): value is StateNodePayload {
   if (!isRecord(value)) {
     return false;
@@ -41,6 +55,10 @@ function isStatePayload(value: unknown): value is StateNodePayload {
   if (!isRecord(meta)) {
     return false;
   }
+  const childThread = value.childThread;
+  if (childThread !== undefined && childThread !== null && typeof childThread !== "string") {
+    return false;
+  }
   return (
     typeof value.role === "string" &&
     typeof value.start === "string" &&
@@ -49,6 +67,20 @@ function isStatePayload(value: unknown): value is StateNodePayload {
   );
 }
 
+/** Normalizes a raw state payload, defaulting `childThread` to `null` for legacy nodes. */
+function normalizeStatePayload(raw: StateNodePayload): StateNodePayload {
+  return {
+    role: raw.role,
+    meta: raw.meta,
+    start: raw.start,
+    content: raw.content,
+    ancestors: raw.ancestors,
+    compact: raw.compact,
+    timestamp: raw.timestamp,
+    childThread: raw.childThread ?? null,
+  };
+}
+
 /** Parses a YAML CAS blob into a typed RFC v3 thread node (or legacy content layout with `children`). */
 export function parseCasThreadNode(yamlText: string): ParsedCasThreadNode | null {
   let raw: unknown;
@@ -86,14 +118,22 @@ export function parseCasThreadNode(yamlText: string): ParsedCasThreadNode | null
     if (!isStartPayload(raw.payload)) {
       return null;
     }
-    const node: StartNode = { type: "start", payload: raw.payload, refs: [...refs] };
+    const node: StartNode = {
+      type: "start",
+      payload: normalizeStartPayload(raw.payload),
+      refs: [...refs],
+    };
     return { kind: "start", node };
   }
 
   if (!isStatePayload(raw.payload)) {
     return null;
   }
-  const node: StateNode = { type: "state", payload: raw.payload, refs: [...refs] };
+  const node: StateNode = {
+    type: "state",
+    payload: normalizeStatePayload(raw.payload),
+    refs: [...refs],
+  };
   return { kind: "state", node };
 }
 
@@ -143,10 +183,14 @@ export async function putStartNode(
   payload: StartNode["payload"],
   promptHash: string,
 ): Promise<string> {
+  const refs = [promptHash];
+  if (payload.parentState !== null) {
+    refs.push(payload.parentState);
+  }
   const node: StartNode = {
     type: "start",
     payload,
-    refs: [promptHash],
+    refs,
   };
   return store.put(serializeCasNode(node));
 }

packages/workflow-dashboard/package.json

@@ -9,6 +9,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
+    "@dagrejs/dagre": "^3.0.0",
+    "@xyflow/react": "^12.10.2",
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "react-markdown": "^10.1.0",

packages/workflow-dashboard/src/api.ts

@@ -66,8 +66,13 @@ export type AgentEndpoint = {
 
 export type WorkflowSummary = {
   name: string;
-  currentHash: string;
-  versions: number;
+  hash: string | null;
+  timestamp: number | null;
+};
+
+export type WorkflowHistoryEntry = {
+  hash: string;
+  timestamp: number;
 };
 
 export type ThreadSummary = {
@@ -104,6 +109,36 @@ export type WorkflowResultRecord = {
 
 export type ThreadRecord = ThreadStartRecord | RoleRecord | WorkflowResultRecord;
 
+export type WorkflowGraphEdge = {
+  from: string;
+  to: string;
+  condition: string;
+  conditionDescription: string | null;
+};
+
+export type WorkflowGraph = {
+  edges: readonly WorkflowGraphEdge[];
+};
+
+export type WorkflowRoleDescriptor = {
+  description: string;
+  schema: Record<string, unknown>;
+};
+
+export type WorkflowDescriptor = {
+  description: string;
+  roles: Record<string, WorkflowRoleDescriptor>;
+  graph: WorkflowGraph;
+};
+
+export type WorkflowDetail = {
+  name: string;
+  hash: string;
+  timestamp: number;
+  history: readonly WorkflowHistoryEntry[];
+  descriptor: WorkflowDescriptor | null;
+};
+
 // ── Gateway endpoints ───────────────────────────────────────────────
 
 export function listAgents(): Promise<AgentEndpoint[]> {
@@ -117,6 +152,18 @@ export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSumma
   return fetchJson(agentBase(agent), "/workflows");
 }
 
+export async function getWorkflowDetail(agent: string, name: string): Promise<WorkflowDetail> {
+  return fetchJson<WorkflowDetail>(agentBase(agent), `/workflows/${encodeURIComponent(name)}`);
+}
+
+export async function getWorkflowDescriptor(
+  agent: string,
+  name: string,
+): Promise<WorkflowDescriptor | null> {
+  const res = await getWorkflowDetail(agent, name);
+  return res.descriptor;
+}
+
 export function listThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
   return fetchJson(agentBase(agent), "/threads");
 }

packages/workflow-dashboard/src/components/record-card.tsx

@@ -56,11 +56,11 @@ function StartCard({ record }: { record: ThreadStartRecord }) {
   );
 }
 
-function RoleMessage({ record }: { record: RoleRecord }) {
+function RoleMessage({ record, highlighted }: { record: RoleRecord; highlighted: boolean }) {
   const color = roleColor(record.role);
   return (
     <div
-      className="p-3 rounded-lg border text-sm"
+      className={`p-3 rounded-lg border text-sm ${highlighted ? "wf-record-card-highlight" : ""}`}
       style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
     >
       <div className="flex items-center gap-2 mb-2">
@@ -114,12 +114,17 @@ function ResultCard({ record }: { record: WorkflowResultRecord }) {
   );
 }
 
-export function RecordCard({ record }: { record: ThreadRecord }) {
+type RecordCardProps = {
+  record: ThreadRecord;
+  highlighted: boolean;
+};
+
+export function RecordCard({ record, highlighted }: RecordCardProps) {
   switch (record.type) {
     case "thread-start":
       return <StartCard record={record} />;
     case "role":
-      return <RoleMessage record={record} />;
+      return <RoleMessage record={record} highlighted={highlighted} />;
     case "workflow-result":
       return <ResultCard record={record} />;
   }

packages/workflow-dashboard/src/components/thread-detail.tsx

@@ -1,8 +1,17 @@
-import { useEffect, useRef, useState } from "react";
-import { getThread, killThread, pauseThread, resumeThread } from "../api.ts";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  getThread,
+  getWorkflowDescriptor,
+  killThread,
+  pauseThread,
+  resumeThread,
+  type ThreadRecord,
+  type WorkflowDescriptor,
+} from "../api.ts";
 import { useFetch } from "../hooks.ts";
 import { useSSE } from "../use-sse.ts";
 import { RecordCard } from "./record-card.tsx";
+import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";
 
 type Props = {
   agent: string;
@@ -10,11 +19,94 @@ type Props = {
   onBack: () => void;
 };
 
+function extractWorkflowName(records: readonly ThreadRecord[]): string | null {
+  for (const r of records) {
+    if (r.type === "thread-start") return r.workflow;
+  }
+  return null;
+}
+
+type GraphPanelProps = {
+  descriptor: WorkflowDescriptor;
+  workflowName: string | null;
+  nodeStates: Map<string, NodeState>;
+  onNodeClick: ((roleName: string) => void) | null;
+};
+
+function GraphPanel({ descriptor, workflowName, nodeStates, onNodeClick }: GraphPanelProps) {
+  const [open, setOpen] = useState(true);
+  const edgeCount = descriptor.graph.edges.length;
+  return (
+    <div
+      className="mb-4 rounded-lg border overflow-hidden"
+      style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
+    >
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        className="w-full flex items-center justify-between px-3 py-2 text-xs"
+        style={{ color: "var(--color-text-muted)" }}
+      >
+        <span className="font-mono">
+          {open ? "▼" : "▶"} Workflow graph
+          {workflowName !== null && (
+            <span className="ml-2" style={{ color: "var(--color-text)" }}>
+              {workflowName}
+            </span>
+          )}
+        </span>
+        <span>
+          {edgeCount} edge{edgeCount === 1 ? "" : "s"}
+        </span>
+      </button>
+      {open && (
+        <div style={{ height: 300, width: "100%" }}>
+          <WorkflowGraph
+            graph={descriptor.graph}
+            roles={descriptor.roles}
+            nodeStates={nodeStates}
+            onNodeClick={onNodeClick}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function computeNodeStates(records: readonly ThreadRecord[]): Map<string, NodeState> {
+  const states = new Map<string, NodeState>();
+  const roleRecords = records.filter(
+    (r): r is Extract<ThreadRecord, { type: "role" }> => r.type === "role",
+  );
+  const hasResult = records.some((r) => r.type === "workflow-result");
+
+  for (let i = 0; i < roleRecords.length; i++) {
+    const role = roleRecords[i].role;
+    const isLast = i === roleRecords.length - 1;
+    states.set(role, !hasResult && isLast ? "active" : "completed");
+  }
+
+  if (roleRecords.length > 0) {
+    states.set("__start__", "completed");
+  }
+  if (hasResult) {
+    states.set("__end__", "completed");
+    for (const [k, v] of states) {
+      if (v === "active") states.set(k, "completed");
+    }
+  }
+
+  return states;
+}
+
 export function ThreadDetail({ agent, threadId, onBack }: Props) {
   const sse = useSSE(agent, threadId);
   const { status, data, error } = useFetch(() => getThread(agent, threadId), [agent, threadId]);
   const [actionStatus, setActionStatus] = useState<string | null>(null);
   const recordsEndRef = useRef<HTMLDivElement>(null);
+  const firstCardByRoleRef = useRef<Map<string, HTMLDivElement>>(new Map());
+  const highlightTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [highlightedRole, setHighlightedRole] = useState<string | null>(null);
 
   const liveActive = sse.connected && !sse.completed;
   const records = liveActive
@@ -23,6 +115,46 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
       ? data.records
       : ([] as typeof sse.records);
 
+  const workflowName = useMemo(() => extractWorkflowName(records), [records]);
+
+  const descriptorFetch = useFetch<WorkflowDescriptor | null>(
+    () =>
+      workflowName === null ? Promise.resolve(null) : getWorkflowDescriptor(agent, workflowName),
+    [agent, workflowName],
+  );
+
+  const descriptor = descriptorFetch.status === "ok" ? descriptorFetch.data : null;
+  const nodeStates = useMemo(() => computeNodeStates(records), [records]);
+
+  const firstIndexByRole = useMemo(() => {
+    const m = new Map<string, number>();
+    for (let i = 0; i < records.length; i++) {
+      const r = records[i];
+      if (r.type === "role" && !m.has(r.role)) {
+        m.set(r.role, i);
+      }
+    }
+    return m;
+  }, [records]);
+
+  const handleGraphNodeClick = useCallback((roleName: string) => {
+    const el = firstCardByRoleRef.current.get(roleName);
+    if (el == null) return;
+    el.scrollIntoView({ behavior: "smooth", block: "center" });
+    if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+    setHighlightedRole(roleName);
+    highlightTimerRef.current = setTimeout(() => {
+      setHighlightedRole(null);
+      highlightTimerRef.current = null;
+    }, 1500);
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (highlightTimerRef.current !== null) clearTimeout(highlightTimerRef.current);
+    };
+  }, []);
+
   // biome-ignore lint/correctness/useExhaustiveDependencies: scroll when the rendered record list grows
   useEffect(() => {
     recordsEndRef.current?.scrollIntoView({ behavior: "smooth" });
@@ -95,6 +227,15 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
         </p>
       )}
 
+      {descriptor !== null && descriptor.graph.edges.length > 0 && (
+        <GraphPanel
+          descriptor={descriptor}
+          workflowName={workflowName}
+          nodeStates={nodeStates}
+          onNodeClick={handleGraphNodeClick}
+        />
+      )}
+
       {status === "loading" && !liveActive && records.length === 0 && (
         <p style={{ color: "var(--color-text-muted)" }}>Loading...</p>
       )}
@@ -103,9 +244,26 @@ export function ThreadDetail({ agent, threadId, onBack }: Props) {
       )}
       {(status === "ok" || liveActive || records.length > 0) && (
         <div className="space-y-3">
-          {records.map((r, i) => (
-            <RecordCard key={`${threadId}-${i}`} record={r} />
-          ))}
+          {records.map((r, i) => {
+            const key = `${threadId}-${i}`;
+            if (r.type === "role") {
+              const isFirstForRole = firstIndexByRole.get(r.role) === i;
+              const flash = highlightedRole === r.role;
+              return (
+                <div
+                  key={key}
+                  ref={(el) => {
+                    if (!isFirstForRole) return;
+                    if (el !== null) firstCardByRoleRef.current.set(r.role, el);
+                    else firstCardByRoleRef.current.delete(r.role);
+                  }}
+                >
+                  <RecordCard record={r} highlighted={flash} />
+                </div>
+              );
+            }
+            return <RecordCard key={key} record={r} highlighted={false} />;
+          })}
           <div ref={recordsEndRef} aria-hidden />
         </div>
       )}

packages/workflow-dashboard/src/components/thread-list.tsx

@@ -13,7 +13,12 @@ export function ThreadList({ agent, onSelect }: Props) {
     return <p style={{ color: "var(--color-text-muted)" }}>Loading threads...</p>;
   if (status === "error") return <p style={{ color: "var(--color-error)" }}>Error: {error}</p>;
 
-  const threads = data.threads;
+  const threads = [...data.threads].sort((a, b) => {
+    if (!a.startedAt && !b.startedAt) return 0;
+    if (!a.startedAt) return 1;
+    if (!b.startedAt) return -1;
+    return b.startedAt.localeCompare(a.startedAt);
+  });
 
   return (
     <div>
@@ -39,11 +44,11 @@ export function ThreadList({ agent, onSelect }: Props) {
                     className="text-xs px-2 py-0.5 rounded"
                     style={{
                       background:
-                        t.status === "running"
+                        t.status === "completed"
                           ? "var(--color-success)"
                           : t.status === "failed"
                             ? "var(--color-error)"
-                            : "var(--color-text-muted)",
+                            : "var(--color-accent)",
                       color: "#000",
                     }}
                   >

packages/workflow-dashboard/src/components/workflow-graph/condition-edge.tsx

@@ -0,0 +1,76 @@
+import {
+  BaseEdge,
+  EdgeLabelRenderer,
+  type EdgeProps,
+  getBezierPath,
+  getSmoothStepPath,
+} from "@xyflow/react";
+import type { ConditionEdgeData } from "./types.ts";
+
+export function ConditionEdge(props: EdgeProps) {
+  const {
+    id,
+    source,
+    target,
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition,
+    data,
+    markerEnd,
+  } = props;
+  const edgeData = data as ConditionEdgeData | undefined;
+  const isFallback = edgeData?.isFallback ?? false;
+  const isSelfLoop = source === target;
+
+  const [path, labelX, labelY] = isSelfLoop
+    ? getSmoothStepPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+        borderRadius: 20,
+      })
+    : getBezierPath({
+        sourceX,
+        sourceY,
+        targetX,
+        targetY,
+        sourcePosition,
+        targetPosition,
+      });
+
+  const stroke = isFallback ? "var(--color-text-muted)" : "var(--color-text)";
+  const strokeDasharray = isFallback ? "5 4" : undefined;
+
+  return (
+    <>
+      <BaseEdge
+        id={id}
+        path={path}
+        markerEnd={markerEnd}
+        style={{ stroke, strokeWidth: 1.5, strokeDasharray }}
+      />
+      {edgeData && !isFallback && edgeData.condition !== "" && (
+        <EdgeLabelRenderer>
+          <div
+            className="absolute px-1.5 py-0.5 rounded text-[10px] font-mono pointer-events-auto"
+            style={{
+              transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`,
+              background: "var(--color-bg)",
+              border: "1px solid var(--color-border)",
+              color: "var(--color-text)",
+            }}
+            title={edgeData.conditionDescription ?? undefined}
+          >
+            {edgeData.condition}
+          </div>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  );
+}

packages/workflow-dashboard/src/components/workflow-graph/index.ts

@@ -0,0 +1,2 @@
+export type { NodeState } from "./types.ts";
+export { WorkflowGraph } from "./workflow-graph.tsx";

packages/workflow-dashboard/src/components/workflow-graph/role-node.tsx

@@ -0,0 +1,69 @@
+import { Handle, type NodeProps, Position } from "@xyflow/react";
+import type { RoleNodeData } from "./types.ts";
+
+function borderColor(state: RoleNodeData["state"]): string {
+  switch (state) {
+    case "completed":
+      return "var(--color-success)";
+    case "active":
+      return "var(--color-accent)";
+    default:
+      return "var(--color-border)";
+  }
+}
+
+function stateIcon(state: RoleNodeData["state"]): string | null {
+  if (state === "completed") return "✓";
+  if (state === "active") return "●";
+  return null;
+}
+
+export function RoleNode(props: NodeProps) {
+  const data = props.data as RoleNodeData;
+  const icon = stateIcon(data.state);
+  const isActive = data.state === "active";
+  const handleStyle = {
+    background: "var(--color-text-muted)",
+    width: 6,
+    height: 6,
+    border: "none",
+  } as const;
+
+  return (
+    <div
+      className={`px-3 py-2 rounded-md border-2 text-xs font-medium cursor-pointer ${isActive ? "wf-node-pulse" : ""}`}
+      style={{
+        width: 180,
+        height: 60,
+        background: "var(--color-surface)",
+        borderColor: borderColor(data.state),
+        color: "var(--color-text)",
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: "center",
+        boxSizing: "border-box",
+      }}
+      title={data.description}
+    >
+      <Handle type="target" position={Position.Top} style={handleStyle} isConnectable={false} />
+      <div className="flex items-center gap-1.5 font-mono">
+        {icon !== null && (
+          <span
+            style={{
+              color: data.state === "active" ? "var(--color-accent)" : "var(--color-success)",
+            }}
+          >
+            {icon}
+          </span>
+        )}
+        <span className="truncate">{data.label}</span>
+      </div>
+      {data.description !== "" && (
+        <div className="text-[10px] truncate mt-0.5" style={{ color: "var(--color-text-muted)" }}>
+          {data.description}
+        </div>
+      )}
+      <Handle type="source" position={Position.Bottom} style={handleStyle} isConnectable={false} />
+    </div>
+  );
+}

packages/workflow-dashboard/src/components/workflow-graph/terminal-node.tsx

@@ -0,0 +1,57 @@
+import { Handle, type NodeProps, Position } from "@xyflow/react";
+import type { TerminalNodeData } from "./types.ts";
+
+function borderColor(state: TerminalNodeData["state"]): string {
+  switch (state) {
+    case "completed":
+      return "var(--color-success)";
+    case "active":
+      return "var(--color-accent)";
+    default:
+      return "var(--color-border)";
+  }
+}
+
+function bgColor(state: TerminalNodeData["state"]): string {
+  if (state === "completed") return "var(--color-success)";
+  if (state === "active") return "var(--color-accent)";
+  return "var(--color-surface)";
+}
+
+export function TerminalNode(props: NodeProps) {
+  const data = props.data as TerminalNodeData;
+  const isStart = data.kind === "start";
+  const isActive = data.state === "active";
+  const handleStyle = {
+    background: "var(--color-text-muted)",
+    width: 6,
+    height: 6,
+    border: "none",
+  } as const;
+
+  return (
+    <div
+      className={`rounded-full border-2 flex items-center justify-center text-[10px] font-bold ${isActive ? "wf-node-pulse" : ""}`}
+      style={{
+        width: 40,
+        height: 40,
+        background: bgColor(data.state),
+        borderColor: borderColor(data.state),
+        color: data.state === "default" ? "var(--color-text-muted)" : "var(--color-bg)",
+      }}
+      title={isStart ? "Start" : "End"}
+    >
+      {isStart ? (
+        <Handle
+          type="source"
+          position={Position.Bottom}
+          style={handleStyle}
+          isConnectable={false}
+        />
+      ) : (
+        <Handle type="target" position={Position.Top} style={handleStyle} isConnectable={false} />
+      )}
+      {isStart ? "▶" : "■"}
+    </div>
+  );
+}

packages/workflow-dashboard/src/components/workflow-graph/types.ts

@@ -0,0 +1,29 @@
+import type { WorkflowGraphEdge } from "../../api.ts";
+
+export type NodeState = "default" | "completed" | "active";
+
+export type TerminalKind = "start" | "end";
+
+export type RoleNodeData = {
+  label: string;
+  description: string;
+  state: NodeState;
+  [key: string]: unknown;
+};
+
+export type TerminalNodeData = {
+  kind: TerminalKind;
+  state: NodeState;
+  [key: string]: unknown;
+};
+
+export type ConditionEdgeData = {
+  condition: string;
+  conditionDescription: string | null;
+  isFallback: boolean;
+  [key: string]: unknown;
+};
+
+export type GraphInput = {
+  edges: readonly WorkflowGraphEdge[];
+};

packages/workflow-dashboard/src/components/workflow-graph/use-layout.ts

@@ -0,0 +1,127 @@
+import Dagre from "@dagrejs/dagre";
+import type { Edge, Node } from "@xyflow/react";
+import { useMemo } from "react";
+import type { WorkflowGraphEdge } from "../../api.ts";
+import type { ConditionEdgeData, NodeState, RoleNodeData, TerminalNodeData } from "./types.ts";
+
+const START_ID = "__start__";
+const END_ID = "__end__";
+const ROLE_NODE_WIDTH = 180;
+const ROLE_NODE_HEIGHT = 60;
+const TERMINAL_NODE_SIZE = 40;
+
+type LayoutInput = {
+  edges: readonly WorkflowGraphEdge[];
+  roles: Record<string, { description: string }>;
+  nodeStates: Map<string, NodeState>;
+};
+
+type LayoutResult = {
+  nodes: Node[];
+  edges: Edge[];
+};
+
+function collectNodeIds(edges: readonly WorkflowGraphEdge[]): Set<string> {
+  const ids = new Set<string>();
+  for (const e of edges) {
+    ids.add(e.from);
+    ids.add(e.to);
+  }
+  return ids;
+}
+
+function nodeSize(id: string): { width: number; height: number } {
+  if (id === START_ID || id === END_ID) {
+    return { width: TERMINAL_NODE_SIZE, height: TERMINAL_NODE_SIZE };
+  }
+  return { width: ROLE_NODE_WIDTH, height: ROLE_NODE_HEIGHT };
+}
+
+function buildRoleNode(
+  id: string,
+  pos: { x: number; y: number },
+  roles: Record<string, { description: string }>,
+  state: NodeState,
+): Node<RoleNodeData> {
+  const description = roles[id]?.description ?? "";
+  return {
+    id,
+    type: "role",
+    position: pos,
+    data: { label: id, description, state },
+    draggable: false,
+  };
+}
+
+function buildTerminalNode(
+  id: string,
+  pos: { x: number; y: number },
+  state: NodeState,
+): Node<TerminalNodeData> {
+  return {
+    id,
+    type: "terminal",
+    position: pos,
+    data: { kind: id === START_ID ? "start" : "end", state },
+    draggable: false,
+    selectable: false,
+  };
+}
+
+function edgeKey(e: WorkflowGraphEdge): string {
+  return `${e.from}->${e.to}::${e.condition}`;
+}
+
+function buildEdge(e: WorkflowGraphEdge): Edge<ConditionEdgeData> {
+  const isFallback = e.condition === "FALLBACK";
+  return {
+    id: edgeKey(e),
+    source: e.from,
+    target: e.to,
+    type: "condition",
+    data: {
+      condition: e.condition,
+      conditionDescription: e.conditionDescription,
+      isFallback,
+    },
+  };
+}
+
+export function useLayout(input: LayoutInput): LayoutResult {
+  return useMemo(() => {
+    const ids = collectNodeIds(input.edges);
+
+    const g = new Dagre.graphlib.Graph({ multigraph: true }).setDefaultEdgeLabel(() => ({}));
+    g.setGraph({ rankdir: "TB", nodesep: 60, ranksep: 80 });
+
+    for (const id of ids) {
+      const size = nodeSize(id);
+      g.setNode(id, { width: size.width, height: size.height });
+    }
+    for (const e of input.edges) {
+      if (e.from === e.to) {
+        continue;
+      }
+      g.setEdge(e.from, e.to, {}, edgeKey(e));
+    }
+
+    Dagre.layout(g);
+
+    const nodes: Node[] = [];
+    for (const id of ids) {
+      const dagNode = g.node(id);
+      const size = nodeSize(id);
+      const pos = { x: dagNode.x - size.width / 2, y: dagNode.y - size.height / 2 };
+      const state = input.nodeStates.get(id) ?? "default";
+      if (id === START_ID || id === END_ID) {
+        nodes.push(buildTerminalNode(id, pos, state));
+      } else {
+        nodes.push(buildRoleNode(id, pos, input.roles, state));
+      }
+    }
+
+    const edges: Edge[] = input.edges.map(buildEdge);
+
+    return { nodes, edges };
+  }, [input.edges, input.roles, input.nodeStates]);
+}

packages/workflow-dashboard/src/components/workflow-graph/workflow-graph.tsx

@@ -0,0 +1,79 @@
+import {
+  Background,
+  type EdgeTypes,
+  MarkerType,
+  type Node,
+  type NodeTypes,
+  type OnNodeClick,
+  ReactFlow,
+} from "@xyflow/react";
+import "@xyflow/react/dist/style.css";
+import { useMemo } from "react";
+import type { WorkflowGraph as WorkflowGraphData } from "../../api.ts";
+import { ConditionEdge } from "./condition-edge.tsx";
+import { RoleNode } from "./role-node.tsx";
+import { TerminalNode } from "./terminal-node.tsx";
+import type { NodeState } from "./types.ts";
+import { useLayout } from "./use-layout.ts";
+
+type Props = {
+  graph: WorkflowGraphData;
+  roles: Record<string, { description: string }>;
+  nodeStates: Map<string, NodeState>;
+  onNodeClick: ((roleName: string) => void) | null;
+};
+
+const nodeTypes: NodeTypes = {
+  role: RoleNode,
+  terminal: TerminalNode,
+};
+
+const edgeTypes: EdgeTypes = {
+  condition: ConditionEdge,
+};
+
+function handleRoleNodeClick(onRoleClick: (roleName: string) => void, node: Node): void {
+  if (node.type !== "role") return;
+  onRoleClick(node.id);
+}
+
+export function WorkflowGraph({ graph, roles, nodeStates, onNodeClick }: Props) {
+  const layout = useLayout({ edges: graph.edges, roles, nodeStates });
+
+  const onNodeClickHandler: OnNodeClick | undefined =
+    onNodeClick !== null ? (_e, node) => handleRoleNodeClick(onNodeClick, node) : undefined;
+
+  const styledEdges = useMemo(
+    () =>
+      layout.edges.map((e) => ({
+        ...e,
+        markerEnd: {
+          type: MarkerType.ArrowClosed,
+          width: 14,
+          height: 14,
+          color: "var(--color-text)",
+        },
+      })),
+    [layout.edges],
+  );
+
+  return (
+    <ReactFlow
+      nodes={layout.nodes}
+      edges={styledEdges}
+      nodeTypes={nodeTypes}
+      edgeTypes={edgeTypes}
+      onNodeClick={onNodeClickHandler}
+      fitView
+      fitViewOptions={{ padding: 0.15 }}
+      nodesDraggable={false}
+      nodesConnectable={false}
+      elementsSelectable={false}
+      proOptions={{ hideAttribution: true }}
+      colorMode="dark"
+      style={{ background: "var(--color-bg)" }}
+    >
+      <Background color="var(--color-border)" gap={20} size={1} />
+    </ReactFlow>
+  );
+}

packages/workflow-dashboard/src/components/workflow-list.tsx

@@ -1,12 +1,168 @@
-import { listWorkflows } from "../api.ts";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { WorkflowDetail } from "../api.ts";
+import { getWorkflowDetail, listWorkflows } from "../api.ts";
 import { useFetch } from "../hooks.ts";
+import { type NodeState, WorkflowGraph } from "./workflow-graph/index.ts";
 
 type Props = {
   agent: string;
 };
 
+type DetailCacheEntry =
+  | { status: "loading" }
+  | { status: "error"; message: string }
+  | { status: "ok"; detail: WorkflowDetail };
+
+function versionCount(detail: WorkflowDetail): number {
+  return detail.history.length + 1;
+}
+
+function ExpandedWorkflowBody({
+  cacheEntry,
+  staticNodeStates,
+}: {
+  cacheEntry: DetailCacheEntry | undefined;
+  staticNodeStates: Map<string, NodeState>;
+}) {
+  if (cacheEntry === undefined || cacheEntry.status === "loading") {
+    return (
+      <p className="text-sm py-2" style={{ color: "var(--color-text-muted)" }}>
+        Loading workflow details...
+      </p>
+    );
+  }
+
+  if (cacheEntry.status === "error") {
+    return (
+      <p className="text-sm py-2" style={{ color: "var(--color-error)" }}>
+        {cacheEntry.message}
+      </p>
+    );
+  }
+
+  const { detail } = cacheEntry;
+  const descriptor = detail.descriptor;
+  const edgeCount = descriptor !== null ? descriptor.graph.edges.length : 0;
+  const vc = versionCount(detail);
+
+  return (
+    <div className="pt-3 space-y-3 border-t" style={{ borderColor: "var(--color-border)" }}>
+      <div>
+        <p className="text-sm font-medium" style={{ color: "var(--color-text)" }}>
+          {detail.name}
+        </p>
+        <p className="text-xs mt-1 mb-1" style={{ color: "var(--color-text-muted)" }}>
+          Hash
+        </p>
+        <code className="text-xs font-mono block" style={{ color: "var(--color-accent)" }}>
+          {detail.hash}
+        </code>
+      </div>
+      <p className="text-xs" style={{ color: "var(--color-text-muted)" }}>
+        {vc} version{vc !== 1 ? "s" : ""}
+      </p>
+      <div>
+        <p className="text-xs mb-1 font-medium" style={{ color: "var(--color-text-muted)" }}>
+          Description
+        </p>
+        <p className="text-sm whitespace-pre-wrap" style={{ color: "var(--color-text)" }}>
+          {descriptor !== null && descriptor.description !== ""
+            ? descriptor.description
+            : descriptor !== null
+              ? "—"
+              : "No descriptor available for this workflow version."}
+        </p>
+      </div>
+      {descriptor !== null && edgeCount > 0 ? (
+        <div
+          className="rounded-lg border overflow-hidden"
+          style={{ borderColor: "var(--color-border)", background: "var(--color-bg)" }}
+        >
+          <div
+            className="px-3 py-2 text-xs flex justify-between items-center"
+            style={{ color: "var(--color-text-muted)", background: "var(--color-surface)" }}
+          >
+            <span className="font-mono">Workflow graph</span>
+            <span>
+              {edgeCount} edge{edgeCount === 1 ? "" : "s"}
+            </span>
+          </div>
+          <div style={{ height: 300, width: "100%" }}>
+            <WorkflowGraph
+              graph={descriptor.graph}
+              roles={descriptor.roles}
+              nodeStates={staticNodeStates}
+              onNodeClick={null}
+            />
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
 export function WorkflowList({ agent }: Props) {
   const { status, data, error } = useFetch(() => listWorkflows(agent), [agent]);
+  const [expanded, setExpanded] = useState<Set<string>>(() => new Set());
+  const [detailsByName, setDetailsByName] = useState<Map<string, DetailCacheEntry>>(
+    () => new Map(),
+  );
+
+  const staticNodeStates = useMemo(() => new Map<string, NodeState>(), []);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: reset expansion when switching agents
+  useEffect(() => {
+    setExpanded(new Set());
+    setDetailsByName(new Map());
+  }, [agent]);
+
+  const ensureDetailLoaded = useCallback(
+    (name: string) => {
+      setDetailsByName((prev) => {
+        const cur = prev.get(name);
+        if (cur !== undefined && (cur.status === "ok" || cur.status === "loading")) {
+          return prev;
+        }
+        return new Map(prev).set(name, { status: "loading" });
+      });
+
+      void (async () => {
+        try {
+          const detail = await getWorkflowDetail(agent, name);
+          setDetailsByName((prev) => {
+            const next = new Map(prev);
+            next.set(name, { status: "ok", detail });
+            return next;
+          });
+        } catch (e) {
+          const message = e instanceof Error ? e.message : String(e);
+          setDetailsByName((prev) => {
+            const next = new Map(prev);
+            next.set(name, { status: "error", message });
+            return next;
+          });
+        }
+      })();
+    },
+    [agent],
+  );
+
+  function toggleExpanded(name: string) {
+    let shouldLoad = false;
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(name)) {
+        next.delete(name);
+        return next;
+      }
+      next.add(name);
+      shouldLoad = true;
+      return next;
+    });
+    if (shouldLoad) {
+      ensureDetailLoaded(name);
+    }
+  }
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading workflows...</p>;
@@ -21,26 +177,58 @@ export function WorkflowList({ agent }: Props) {
         <p style={{ color: "var(--color-text-muted)" }}>No workflows registered.</p>
       ) : (
         <div className="space-y-2">
-          {workflows.map((w) => (
-            <div
-              key={w.name}
-              className="p-4 rounded-lg border"
-              style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
-            >
-              <div className="flex items-center justify-between">
-                <span className="font-medium">{w.name}</span>
-                <span className="text-xs" style={{ color: "var(--color-text-muted)" }}>
-                  {w.versions} version{w.versions !== 1 ? "s" : ""}
-                </span>
-              </div>
-              <code
-                className="text-xs mt-1 block font-mono"
-                style={{ color: "var(--color-accent)" }}
+          {workflows.map((w) => {
+            const isOpen = expanded.has(w.name);
+            return (
+              <div
+                key={w.name}
+                className="rounded-lg border overflow-hidden"
+                style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
               >
-                {w.currentHash}
-              </code>
-            </div>
-          ))}
+                <button
+                  type="button"
+                  onClick={() => toggleExpanded(w.name)}
+                  className="w-full text-left p-4 flex items-start justify-between gap-3 hover:opacity-90"
+                  style={{ color: "var(--color-text)" }}
+                  aria-expanded={isOpen}
+                >
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <span
+                        className="text-xs font-mono"
+                        style={{ color: "var(--color-text-muted)" }}
+                      >
+                        {isOpen ? "▼" : "▶"}
+                      </span>
+                      <span className="font-medium">{w.name}</span>
+                    </div>
+                    <code
+                      className="text-xs mt-1 block font-mono truncate"
+                      style={{ color: "var(--color-accent)" }}
+                    >
+                      {w.hash !== null ? w.hash : "—"}
+                    </code>
+                    {w.timestamp !== null ? (
+                      <span
+                        className="text-xs mt-1 block"
+                        style={{ color: "var(--color-text-muted)" }}
+                      >
+                        Updated {new Date(w.timestamp).toLocaleString()}
+                      </span>
+                    ) : null}
+                  </div>
+                </button>
+                {isOpen ? (
+                  <div className="px-4 pb-4">
+                    <ExpandedWorkflowBody
+                      cacheEntry={detailsByName.get(w.name)}
+                      staticNodeStates={staticNodeStates}
+                    />
+                  </div>
+                ) : null}
+              </div>
+            );
+          })}
         </div>
       )}
     </div>

packages/workflow-dashboard/src/index.css

@@ -19,3 +19,33 @@ body {
   color: var(--color-text);
   font-family: "Inter", system-ui, -apple-system, sans-serif;
 }
+
+@keyframes wf-node-pulse {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(124, 109, 240, 0.55);
+  }
+  50% {
+    box-shadow: 0 0 0 6px rgba(124, 109, 240, 0);
+  }
+}
+
+.wf-node-pulse {
+  animation: wf-node-pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes wf-record-card-highlight {
+  0% {
+    border-color: var(--color-accent);
+  }
+  35% {
+    border-color: var(--color-accent);
+  }
+  100% {
+    border-color: var(--color-border);
+  }
+}
+
+.wf-record-card-highlight {
+  animation: wf-record-card-highlight 1.5s ease-out forwards;
+}

packages/workflow-execute/__tests__/engine.test.ts

@@ -35,6 +35,7 @@ function noLogger(): (tag: string, content: string) => void {
 function makeOptions(overrides: Partial<ExecuteThreadOptions>): ExecuteThreadOptions {
   return {
     depth: 0,
+    parentStateHash: null,
     signal: new AbortController().signal,
     awaitAfterEachYield: async () => {},
     forkSourceThreadId: null,
@@ -144,9 +145,9 @@ describe("executeThread (Phase 2 — CAS thread storage)", () => {
       runtime: WorkflowRuntime,
     ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
       const h1 = await runtime.cas.put("plan-text");
-      yield { role: "planner", contentHash: h1, meta: { plan: 1 }, refs: [h1] };
+      yield { role: "planner", contentHash: h1, meta: { plan: 1 }, refs: [h1], childThread: null };
       const h2 = await runtime.cas.put("code-text");
-      yield { role: "coder", contentHash: h2, meta: { diff: "y" }, refs: [h2] };
+      yield { role: "coder", contentHash: h2, meta: { diff: "y" }, refs: [h2], childThread: null };
       return { returnCode: 0, summary: "done" };
     };
 
@@ -210,7 +211,7 @@ describe("executeThread (Phase 2 — CAS thread storage)", () => {
       runtime: WorkflowRuntime,
     ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
       const h = await runtime.cas.put("only-step");
-      yield { role: "only", contentHash: h, meta: {}, refs: [h] };
+      yield { role: "only", contentHash: h, meta: {}, refs: [h], childThread: null };
       return { returnCode: 0, summary: "completed" };
     };
 
@@ -261,7 +262,7 @@ describe("executeThread (Phase 2 — CAS thread storage)", () => {
       runtime: WorkflowRuntime,
     ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
       const h = await runtime.cas.put("step");
-      yield { role: "only", contentHash: h, meta: {}, refs: [h] };
+      yield { role: "only", contentHash: h, meta: {}, refs: [h], childThread: null };
       return { returnCode: 0, summary: "done" };
     };
 

packages/workflow-execute/__tests__/gc-mark-sweep.test.ts

@@ -46,6 +46,7 @@ describe("garbageCollectCas (mark-and-sweep)", () => {
         name: "demo",
         hash: bundleHash,
         depth: 0,
+        parentState: null,
       },
       promptHash,
     );
@@ -59,6 +60,7 @@ describe("garbageCollectCas (mark-and-sweep)", () => {
       ancestors: [],
       compact: null,
       timestamp: 1,
+      childThread: null,
     } satisfies StateNodePayload);
 
     const c2 = await putContentNodeWithRefs(cas, "c1", []);
@@ -70,6 +72,7 @@ describe("garbageCollectCas (mark-and-sweep)", () => {
       ancestors: [h1],
       compact: null,
       timestamp: 2,
+      childThread: null,
     } satisfies StateNodePayload);
 
     const ec = await putContentNodeWithRefs(cas, "", []);
@@ -81,6 +84,7 @@ describe("garbageCollectCas (mark-and-sweep)", () => {
       ancestors: [h1],
       compact: null,
       timestamp: 3,
+      childThread: null,
     } satisfies StateNodePayload);
 
     await upsertThreadEntry(bundleDir, "THREAD_AAAAAAA", {

packages/workflow-execute/__tests__/merkle-call-stack.test.ts

@@ -0,0 +1,306 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CasStore } from "@uncaged/workflow-cas";
+import { createCasStore, parseCasThreadNode } from "@uncaged/workflow-cas";
+import type { StartNode, StateNode } from "@uncaged/workflow-protocol";
+import type {
+  RoleOutput,
+  ThreadContext,
+  WorkflowCompletion,
+  WorkflowFn,
+  WorkflowRuntime,
+} from "@uncaged/workflow-runtime";
+
+import { executeThread } from "../src/engine/engine.js";
+import type { ExecuteThreadIo, ExecuteThreadOptions } from "../src/engine/types.js";
+
+const TEST_REGISTRY_YAML = `config:
+  maxDepth: 3
+  supervisorInterval: 0
+  providers:
+    stub:
+      baseUrl: http://127.0.0.1:9
+      apiKey: test
+  models:
+    default: stub/m
+workflows: {}
+`;
+
+function noLogger(): (tag: string, content: string) => void {
+  return () => {};
+}
+
+function makeOptions(overrides: Partial<ExecuteThreadOptions>): ExecuteThreadOptions {
+  return {
+    depth: 0,
+    parentStateHash: null,
+    signal: new AbortController().signal,
+    awaitAfterEachYield: async () => {},
+    forkSourceThreadId: null,
+    prefilledDiskSteps: null,
+    forkContinuation: null,
+    replayTimestamps: null,
+    storageRoot: "/tmp/never",
+    ...overrides,
+  };
+}
+
+async function setupStorage(): Promise<{
+  storageRoot: string;
+  casDir: string;
+}> {
+  const storageRoot = await mkdtemp(join(tmpdir(), "uncaged-wf-merkle-"));
+  await writeFile(join(storageRoot, "workflow.yaml"), TEST_REGISTRY_YAML, "utf8");
+  const casDir = join(storageRoot, "cas");
+  await mkdir(casDir, { recursive: true });
+  return { storageRoot, casDir };
+}
+
+async function loadStartNode(cas: CasStore, endHash: string): Promise<StartNode> {
+  const endBlob = await cas.get(endHash);
+  const endParsed = parseCasThreadNode(endBlob ?? "");
+  if (endParsed?.kind !== "state") throw new Error("expected state node");
+  const startBlob = await cas.get(endParsed.node.payload.start);
+  const startParsed = parseCasThreadNode(startBlob ?? "");
+  if (startParsed?.kind !== "start") throw new Error("expected start node");
+  return startParsed.node;
+}
+
+async function loadStateNode(cas: CasStore, hash: string): Promise<StateNode> {
+  const blob = await cas.get(hash);
+  const parsed = parseCasThreadNode(blob ?? "");
+  if (parsed?.kind !== "state") throw new Error("expected state node");
+  return parsed.node;
+}
+
+describe("Merkle call stack — cross-thread DAG linking (Phase 2)", () => {
+  let storageRoot: string;
+  let casDir: string;
+
+  beforeEach(async () => {
+    const setup = await setupStorage();
+    storageRoot = setup.storageRoot;
+    casDir = setup.casDir;
+  });
+
+  afterEach(async () => {
+    await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  test("parentStateHash is written into child start node's parentState and refs", async () => {
+    const cas = createCasStore(casDir);
+
+    // biome-ignore lint/correctness/useYield: testing start-only path
+    const parentWf: WorkflowFn = async function* (
+      _thread: ThreadContext,
+      _runtime: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      return { returnCode: 0, summary: "parent done" };
+    };
+
+    const parentResult = await executeThread(
+      parentWf,
+      "parent-wf",
+      { prompt: "parent task", steps: [] },
+      makeOptions({ storageRoot }),
+      {
+        threadId: "P_THREAD_01",
+        hash: "PARENTHASH0001",
+        infoJsonlPath: join(storageRoot, "logs", "PARENTHASH0001", "P1.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    // biome-ignore lint/correctness/useYield: testing start-only path
+    const childWf: WorkflowFn = async function* (
+      _thread: ThreadContext,
+      _runtime: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      return { returnCode: 0, summary: "child done" };
+    };
+
+    const childResult = await executeThread(
+      childWf,
+      "child-wf",
+      { prompt: "child task", steps: [] },
+      makeOptions({ storageRoot, depth: 1, parentStateHash: parentResult.rootHash }),
+      {
+        threadId: "C_THREAD_01",
+        hash: "CHILDHASH00001",
+        infoJsonlPath: join(storageRoot, "logs", "CHILDHASH00001", "C1.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    const childStart = await loadStartNode(cas, childResult.rootHash);
+    expect(childStart.payload.parentState).toBe(parentResult.rootHash);
+    expect(childStart.refs).toContain(parentResult.rootHash);
+  });
+
+  test("childThread on parent state node points to child's final state and is in refs", async () => {
+    const cas = createCasStore(casDir);
+    const childFinalHash = "CHILD_FINAL_001";
+
+    const parentWf: WorkflowFn = async function* (
+      _thread: ThreadContext,
+      runtime: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      const h = await runtime.cas.put("developer output");
+      yield {
+        role: "developer",
+        contentHash: h,
+        meta: { action: "delegate" },
+        refs: [h],
+        childThread: childFinalHash,
+      };
+      return { returnCode: 0, summary: "parent complete" };
+    };
+
+    const result = await executeThread(
+      parentWf,
+      "parent-wf",
+      { prompt: "parent task", steps: [] },
+      makeOptions({ storageRoot }),
+      {
+        threadId: "P_THREAD_02",
+        hash: "CTHREAD_TEST01",
+        infoJsonlPath: join(storageRoot, "logs", "CTHREAD_TEST01", "P2.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    const endNode = await loadStateNode(cas, result.rootHash);
+    const devStateHash = endNode.payload.ancestors[0] ?? "";
+    const devNode = await loadStateNode(cas, devStateHash);
+
+    expect(devNode.payload.role).toBe("developer");
+    expect(devNode.payload.childThread).toBe(childFinalHash);
+    expect(devNode.refs).toContain(childFinalHash);
+  });
+
+  test("parent state with no child has childThread: null", async () => {
+    const cas = createCasStore(casDir);
+
+    const wf: WorkflowFn = async function* (
+      _thread: ThreadContext,
+      runtime: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      const h = await runtime.cas.put("prep output");
+      yield { role: "preparer", contentHash: h, meta: {}, refs: [h], childThread: null };
+      return { returnCode: 0, summary: "done" };
+    };
+
+    const result = await executeThread(
+      wf,
+      "test-wf",
+      { prompt: "task", steps: [] },
+      makeOptions({ storageRoot }),
+      {
+        threadId: "NULL_CT_01",
+        hash: "NULLCT_TEST001",
+        infoJsonlPath: join(storageRoot, "logs", "NULLCT_TEST001", "N1.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    const endNode = await loadStateNode(cas, result.rootHash);
+    const prepHash = endNode.payload.ancestors[0] ?? "";
+    const prepNode = await loadStateNode(cas, prepHash);
+
+    expect(prepNode.payload.childThread).toBeNull();
+    expect(prepNode.refs).not.toContain(null);
+  });
+
+  test("full bidirectional: child parentState is traversable to parent's context", async () => {
+    const cas = createCasStore(casDir);
+    const parentHash = "BIDIR_PARENT01";
+
+    const parentWf: WorkflowFn = async function* (
+      _thread: ThreadContext,
+      runtime: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      const h1 = await runtime.cas.put("preparation output");
+      yield {
+        role: "preparer",
+        contentHash: h1,
+        meta: { repoPath: "/test" },
+        refs: [h1],
+        childThread: null,
+      };
+      const h2 = await runtime.cas.put("developer output");
+      yield {
+        role: "developer",
+        contentHash: h2,
+        meta: { action: "code" },
+        refs: [h2],
+        childThread: "CHILD_END_HASH1",
+      };
+      return { returnCode: 0, summary: "all done" };
+    };
+
+    const observedHeads: string[] = [];
+    const opts = makeOptions({
+      storageRoot,
+      awaitAfterEachYield: async () => {
+        const bundleDir = join(storageRoot, "bundles", parentHash);
+        const text = await readFile(join(bundleDir, "threads.json"), "utf8");
+        const parsed = JSON.parse(text) as Record<string, { head: string }>;
+        const head = parsed.BIDIR_T_001?.head ?? null;
+        if (head !== null) observedHeads.push(head);
+      },
+    });
+
+    await executeThread(
+      parentWf,
+      "bidir-wf",
+      { prompt: "bidir test", steps: [] },
+      opts,
+      {
+        threadId: "BIDIR_T_001",
+        hash: parentHash,
+        infoJsonlPath: join(storageRoot, "logs", parentHash, "BD1.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    expect(observedHeads.length).toBe(2);
+    const preparerStateHash = observedHeads[0] ?? "";
+
+    // Execute child with parentState pointing to parent's preparer state
+    // biome-ignore lint/correctness/useYield: testing start-only path
+    const childWf: WorkflowFn = async function* (
+      _t: ThreadContext,
+      _r: WorkflowRuntime,
+    ): AsyncGenerator<RoleOutput, WorkflowCompletion> {
+      return { returnCode: 0, summary: "child ok" };
+    };
+
+    const childResult = await executeThread(
+      childWf,
+      "bidir-child",
+      { prompt: "child bidir", steps: [] },
+      makeOptions({ storageRoot, depth: 1, parentStateHash: preparerStateHash }),
+      {
+        threadId: "BIDIR_C_001",
+        hash: "BIDIR_CHILD001",
+        infoJsonlPath: join(storageRoot, "logs", "BIDIR_CHILD001", "BC1.info.jsonl"),
+        cas,
+      },
+      noLogger(),
+    );
+
+    // Upward traversal: child start → parentState → preparer state → meta.repoPath
+    const childStart = await loadStartNode(cas, childResult.rootHash);
+    expect(childStart.payload.parentState).toBe(preparerStateHash);
+
+    const parentPrep = await loadStateNode(cas, preparerStateHash);
+    expect(parentPrep.payload.meta.repoPath).toBe("/test");
+  });
+});

packages/workflow-execute/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-execute",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": {

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

@@ -94,6 +94,7 @@ async function appendStateForStep(params: {
   meta: Record<string, unknown>;
   refs: readonly string[];
   timestamp: number;
+  childThread: string | null;
 }): Promise<{ stateHash: string; chain: ChainState }> {
   const text = await getContentMerklePayload(params.cas, params.contentHash);
   if (text === null) {
@@ -112,6 +113,7 @@ async function appendStateForStep(params: {
     ancestors,
     compact: null,
     timestamp: params.timestamp,
+    childThread: params.childThread,
   };
   const stateHash = await putStateNode(params.cas, payload);
   return {
@@ -137,6 +139,7 @@ async function appendEndState(params: {
     ancestors,
     compact: null,
     timestamp: params.timestamp,
+    childThread: null,
   };
   return putStateNode(params.cas, payload);
 }
@@ -329,6 +332,7 @@ async function driveWorkflowGenerator(params: {
       meta: step.meta,
       refs: step.refs,
       timestamp: ts,
+      childThread: step.childThread ?? null,
     });
     chain = written_.chain;
     await publishHead({ bundleDir, threadId, startHash, headHash: written_.stateHash });
@@ -439,6 +443,7 @@ export async function executeThread(
         name: workflowName,
         hash: io.hash,
         depth: options.depth,
+        parentState: options.parentStateHash,
       },
       promptHash,
     );
@@ -466,6 +471,7 @@ export async function executeThread(
         meta: row.meta,
         refs: row.refs,
         timestamp: row.timestamp,
+        childThread: null,
       });
       chain = written.chain;
       await publishHead({
@@ -487,11 +493,13 @@ export async function executeThread(
   const thread: ThreadContext = {
     threadId: io.threadId,
     depth: options.depth,
+    bundleHash: io.hash,
     start: {
       role: START,
       content: input.prompt,
       meta: {},
       timestamp: nowMs,
+      parentState: options.parentStateHash,
     },
     steps: input.steps.map((out, i) => ({
       role: out.role,

packages/workflow-execute/src/engine/fork-thread.ts

@@ -144,6 +144,7 @@ async function payloadToRoleOutput(cas: CasStore, payload: StateNodePayload): Pr
     contentHash: payload.content,
     meta: payload.meta,
     refs,
+    childThread: payload.childThread,
   };
 }
 
@@ -240,6 +241,7 @@ async function buildForkContinuation(params: {
     ancestors: ancestorsMarker,
     compact: null,
     timestamp: Date.now(),
+    childThread: null,
   };
   const markerHash = await putStateNode(cas, markerPayload);
 

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

@@ -41,6 +41,8 @@ export type PrefilledDiskStep = {
 export type ExecuteThreadOptions = {
   /** Passed to the bundle thread context as `ThreadContext.depth`. */
   depth: number;
+  /** Parent thread's head state hash at spawn time; `null` for top-level threads. */
+  parentStateHash: string | null;
   signal: AbortSignal;
   /** Invoked after each successful yield (and outer-loop checks); used for pause/resume. */
   awaitAfterEachYield: () => Promise<void>;

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

@@ -72,11 +72,13 @@ function parseRoleOutputRecord(obj: Record<string, unknown>): RoleOutput | null
   if (meta === null || typeof meta !== "object") {
     return null;
   }
+  const childThread = obj.childThread;
   return {
     role,
     contentHash,
     meta: meta as Record<string, unknown>,
     refs: normalizeRefsField(obj.refs),
+    childThread: typeof childThread === "string" ? childThread : null,
   };
 }
 
@@ -497,6 +499,7 @@ async function main(): Promise<void> {
         { prompt: cmd.prompt, steps: cmd.steps },
         {
           ...cmd.options,
+          parentStateHash: null,
           signal: ac.signal,
           awaitAfterEachYield: () => pauseGate.awaitAfterYield(),
           forkSourceThreadId: cmd.forkSourceThreadId,

packages/workflow-execute/src/workflow-as-agent.ts

@@ -6,7 +6,7 @@ import {
   getRegisteredWorkflow,
   readWorkflowRegistry,
 } from "@uncaged/workflow-register";
-import type { AgentContext, AgentFn } from "@uncaged/workflow-runtime";
+import type { AgentContext, AgentFn, AgentFnResult } from "@uncaged/workflow-runtime";
 import {
   createLogger,
   generateUlid,
@@ -14,7 +14,7 @@ import {
   getGlobalCasDir,
 } from "@uncaged/workflow-util";
 import type { ExecuteThreadIo } from "./engine/index.js";
-import { executeThread } from "./engine/index.js";
+import { executeThread, getBundleDir, readThreadsIndex } from "./engine/index.js";
 
 const DEFAULT_WORKFLOW_AS_AGENT_MAX_DEPTH = 3;
 
@@ -37,6 +37,13 @@ function resolveWorkflowAsAgentStorageRoot(options: WorkflowAsAgentOptions | nul
   return getDefaultWorkflowStorageRoot();
 }
 
+async function readParentHeadState(storageRoot: string, ctx: AgentContext): Promise<string | null> {
+  const bundleDir = getBundleDir(storageRoot, ctx.bundleHash);
+  const index = await readThreadsIndex(bundleDir);
+  const entry = index[ctx.threadId] ?? null;
+  return entry !== null ? entry.head : null;
+}
+
 /**
  * Returns an {@link AgentFn} that runs another registered workflow in a new thread,
  * using the parent thread's initial prompt (`ctx.start.content`) as the child prompt.
@@ -45,30 +52,30 @@ export function workflowAsAgent(
   workflowName: string,
   options: WorkflowAsAgentOptions | null = null,
 ): AgentFn {
-  return async (ctx: AgentContext): Promise<string> => {
+  return async (ctx: AgentContext): Promise<AgentFnResult> => {
     const nextDepth = ctx.depth + 1;
 
     const storageRoot = resolveWorkflowAsAgentStorageRoot(options);
 
     const registryResult = await readWorkflowRegistry(storageRoot);
     if (!registryResult.ok) {
-      return `ERROR: failed to read workflow registry: ${registryResult.error.message}`;
+      return { output: `ERROR: failed to read workflow registry: ${registryResult.error.message}`, childThread: null };
     }
 
     const maxDepth = workflowAsAgentMaxDepth(registryResult.value.config);
     if (nextDepth > maxDepth) {
-      return `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`;
+      return { output: `ERROR: workflow-as-agent depth limit exceeded (max ${maxDepth})`, childThread: null };
     }
 
     const entry = getRegisteredWorkflow(registryResult.value, workflowName);
     if (entry === null) {
-      return `ERROR: workflow "${workflowName}" not found in registry`;
+      return { output: `ERROR: workflow "${workflowName}" not found in registry`, childThread: null };
     }
 
     const bundlePath = join(storageRoot, "bundles", `${entry.hash}.esm.js`);
     const bundleExportsResult = await extractBundleExports(bundlePath, { storageRoot });
     if (!bundleExportsResult.ok) {
-      return `ERROR: ${bundleExportsResult.error}`;
+      return { output: `ERROR: ${bundleExportsResult.error}`, childThread: null };
     }
 
     const input = {
@@ -89,6 +96,8 @@ export function workflowAsAgent(
     const logger = createLogger({ sink: { kind: "file", path: infoJsonlPath } });
     const signalNever = new AbortController();
 
+    const parentHeadState = await readParentHeadState(storageRoot, ctx);
+
     try {
       const result = await executeThread(
         bundleExportsResult.value.run,
@@ -96,6 +105,7 @@ export function workflowAsAgent(
         input,
         {
           depth: nextDepth,
+          parentStateHash: parentHeadState,
           signal: signalNever.signal,
           awaitAfterEachYield: async () => {},
           forkSourceThreadId: ctx.threadId,
@@ -107,10 +117,11 @@ export function workflowAsAgent(
         io,
         logger,
       );
-      return `Child workflow "${workflowName}" completed (returnCode=${result.returnCode}).\n\nSummary: ${result.summary}\n\nChild thread root hash: ${result.rootHash}`;
+      const summary = `Child workflow "${workflowName}" completed (returnCode=${result.returnCode}).\n\nSummary: ${result.summary}\n\nChild thread root hash: ${result.rootHash}`;
+      return { output: summary, childThread: result.rootHash };
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
-      return `ERROR: ${message}`;
+      return { output: `ERROR: ${message}`, childThread: null };
     }
   };
 }

packages/workflow-gateway/package.json

@@ -3,6 +3,10 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./ws-protocol": "./src/ws-protocol.ts"
+  },
   "scripts": {
     "dev": "wrangler dev",
     "deploy": "wrangler deploy"

packages/workflow-gateway/src/agent-socket.ts

@@ -0,0 +1,162 @@
+/** One Durable Object instance per agent name; holds the reverse WebSocket from the agent CLI. */
+import { DurableObject } from "cloudflare:workers";
+
+import { parseWsRequestJson, parseWsResponseJson, type WsResponse } from "./ws-protocol.js";
+
+type AgentSocketEnv = {
+  GATEWAY_SECRET: string;
+};
+
+export const AGENT_SOCKET_INTERNAL_STATUS_PATH = "/internal/agent-socket/status";
+export const AGENT_SOCKET_INTERNAL_PROXY_PATH = "/internal/agent-socket/proxy";
+
+const PROXY_TIMEOUT_MS = 30_000;
+
+type PendingEntry = {
+  resolve: (r: Response) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+function jsonResponse(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function wsResponseToHttp(wr: WsResponse): Response {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(wr.headers)) {
+    headers.set(k, v);
+  }
+  return new Response(wr.body, { status: wr.status, headers });
+}
+
+export class AgentSocket extends DurableObject<AgentSocketEnv> {
+  private readonly pending = new Map<string, PendingEntry>();
+
+  private requireAuth(request: Request): Response | null {
+    const auth = request.headers.get("Authorization");
+    if (auth !== `Bearer ${this.env.GATEWAY_SECRET}`) {
+      return jsonResponse(401, { error: "unauthorized" });
+    }
+    return null;
+  }
+
+  private handleStatusGet(request: Request): Response {
+    const denied = this.requireAuth(request);
+    if (denied !== null) {
+      return denied;
+    }
+    const sockets = this.ctx.getWebSockets();
+    const connected = sockets.length > 0;
+    return new Response(JSON.stringify({ connected, connectedCount: sockets.length }), {
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  private async handleProxyPost(request: Request): Promise<Response> {
+    const denied = this.requireAuth(request);
+    if (denied !== null) {
+      return denied;
+    }
+    const raw = await request.text();
+    const wsRequest = parseWsRequestJson(raw);
+    if (wsRequest === null) {
+      return jsonResponse(400, { error: "invalid proxy body" });
+    }
+
+    const sockets = this.ctx.getWebSockets();
+    const ws = sockets[0];
+    if (ws === undefined) {
+      return jsonResponse(503, { error: "no active websocket" });
+    }
+
+    return await new Promise<Response>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(wsRequest.id);
+        resolve(jsonResponse(504, { error: "gateway timeout" }));
+      }, PROXY_TIMEOUT_MS);
+
+      this.pending.set(wsRequest.id, {
+        resolve: (r: Response) => {
+          clearTimeout(timer);
+          this.pending.delete(wsRequest.id);
+          resolve(r);
+        },
+        timer,
+      });
+
+      try {
+        ws.send(JSON.stringify(wsRequest));
+      } catch {
+        clearTimeout(timer);
+        this.pending.delete(wsRequest.id);
+        resolve(jsonResponse(502, { error: "websocket send failed" }));
+      }
+    });
+  }
+
+  async fetch(request: Request): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === AGENT_SOCKET_INTERNAL_STATUS_PATH && request.method === "GET") {
+      return this.handleStatusGet(request);
+    }
+
+    if (url.pathname === AGENT_SOCKET_INTERNAL_PROXY_PATH && request.method === "POST") {
+      return this.handleProxyPost(request);
+    }
+
+    if (request.headers.get("Upgrade") !== "websocket") {
+      return new Response("expected WebSocket upgrade", { status: 426 });
+    }
+
+    for (const ws of this.ctx.getWebSockets()) {
+      ws.close(1000, "replaced by new connection");
+    }
+
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    this.ctx.acceptWebSocket(server);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  async webSocketMessage(_ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+    const text = typeof message === "string" ? message : new TextDecoder().decode(message);
+    const wr = parseWsResponseJson(text);
+    if (wr === null) {
+      return;
+    }
+    const entry = this.pending.get(wr.id);
+    if (entry === undefined) {
+      return;
+    }
+    clearTimeout(entry.timer);
+    this.pending.delete(wr.id);
+    entry.resolve(wsResponseToHttp(wr));
+  }
+
+  async webSocketClose(
+    _ws: WebSocket,
+    _code: number,
+    _reason: string,
+    _wasClean: boolean,
+  ): Promise<void> {
+    this.rejectAllPending("agent websocket closed");
+  }
+
+  async webSocketError(_ws: WebSocket, _error: unknown): Promise<void> {
+    this.rejectAllPending("agent websocket error");
+  }
+
+  private rejectAllPending(message: string): void {
+    const entries = [...this.pending.values()];
+    this.pending.clear();
+    for (const entry of entries) {
+      clearTimeout(entry.timer);
+      entry.resolve(jsonResponse(502, { error: message }));
+    }
+  }
+}

packages/workflow-gateway/src/index.ts

@@ -1,11 +1,21 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 
+import {
+  AGENT_SOCKET_INTERNAL_PROXY_PATH,
+  AGENT_SOCKET_INTERNAL_STATUS_PATH,
+  AgentSocket,
+} from "./agent-socket.js";
+import type { WsRequest } from "./ws-protocol.js";
+
+export { AgentSocket };
+
 type Env = {
   Bindings: {
     ENDPOINTS: KVNamespace;
     GATEWAY_SECRET: string;
     DASHBOARD_API_KEY: string;
+    AGENT_SOCKET: DurableObjectNamespace<AgentSocket>;
   };
 };
 
@@ -33,9 +43,165 @@ function checkDashboardAuth(c: {
   return key === c.env.DASHBOARD_API_KEY;
 }
 
+function isLocalAgentUrl(url: string): boolean {
+  try {
+    const u = new URL(url);
+    return u.hostname === "localhost" || u.hostname === "127.0.0.1";
+  } catch {
+    return false;
+  }
+}
+
+function buildForwardHeaders(raw: Headers, agentToken: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of raw) {
+    const lower = key.toLowerCase();
+    if (lower === "host" || lower === "authorization") {
+      continue;
+    }
+    if (
+      lower === "connection" ||
+      lower === "keep-alive" ||
+      lower === "proxy-connection" ||
+      lower === "transfer-encoding" ||
+      lower === "upgrade"
+    ) {
+      continue;
+    }
+    out[key] = value;
+  }
+  if (agentToken !== "") {
+    out["X-Agent-Token"] = agentToken;
+  }
+  return out;
+}
+
+function buildDashboardProxyHeaders(raw: Headers, token: string): Headers {
+  const headers = new Headers(raw);
+  headers.delete("host");
+  headers.delete("Authorization");
+  if (token !== "") {
+    headers.set("X-Agent-Token", token);
+  }
+  return headers;
+}
+
+async function readBodyForWsProxy(method: string, req: Request): Promise<string | null> {
+  if (method === "GET" || method === "HEAD") {
+    return null;
+  }
+  const buf = await req.arrayBuffer();
+  return buf.byteLength === 0 ? null : new TextDecoder().decode(buf);
+}
+
+async function fetchThroughAgentSocket(
+  bindings: Env["Bindings"],
+  agent: string,
+  gateSecret: string,
+  wsRequest: WsRequest,
+): Promise<Response> {
+  const stub = bindings.AGENT_SOCKET.get(bindings.AGENT_SOCKET.idFromName(agent));
+  return stub.fetch(
+    new Request(`https://do.internal${AGENT_SOCKET_INTERNAL_PROXY_PATH}`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${gateSecret}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(wsRequest),
+    }),
+  );
+}
+
+async function fetchAgentWithRecordHeaders(
+  targetUrl: string,
+  method: string,
+  forwardRecord: Record<string, string>,
+  bodyStr: string | null,
+): Promise<Response> {
+  const headers = new Headers();
+  for (const [k, v] of Object.entries(forwardRecord)) {
+    headers.set(k, v);
+  }
+  return fetch(targetUrl, {
+    method,
+    headers,
+    body: method !== "GET" && method !== "HEAD" ? (bodyStr ?? undefined) : undefined,
+  });
+}
+
+async function fetchAgentWithDashboardHeaders(
+  targetUrl: string,
+  method: string,
+  headers: Headers,
+  rawBody: BodyInit | null | undefined,
+): Promise<Response> {
+  return fetch(targetUrl, {
+    method,
+    headers,
+    body: method !== "GET" && method !== "HEAD" ? rawBody : undefined,
+  });
+}
+
+async function fetchAgentSocketStatus(
+  env: Env["Bindings"],
+  name: string,
+): Promise<{ ok: true; connected: boolean } | { ok: false }> {
+  try {
+    const id = env.AGENT_SOCKET.idFromName(name);
+    const stub = env.AGENT_SOCKET.get(id);
+    const resp = await stub.fetch(
+      new Request(`https://do${AGENT_SOCKET_INTERNAL_STATUS_PATH}`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${env.GATEWAY_SECRET}` },
+      }),
+    );
+    if (!resp.ok) {
+      return { ok: false };
+    }
+    const body = (await resp.json()) as { connected: boolean };
+    return { ok: true, connected: body.connected };
+  } catch {
+    return { ok: false };
+  }
+}
+
+function endpointStatusFromKvAndDo(record: EndpointRecord, doConnected: boolean | null): string {
+  if (doConnected === true) {
+    return "online";
+  }
+  if (doConnected === false) {
+    if (isLocalAgentUrl(record.url)) {
+      return "offline";
+    }
+    const age = Date.now() - record.lastHeartbeat;
+    return age < TTL_SECONDS * 1000 ? "online" : "offline";
+  }
+  const age = Date.now() - record.lastHeartbeat;
+  return age < TTL_SECONDS * 1000 ? "online" : "offline";
+}
+
 // ── Health ──────────────────────────────────────────────────────────
 app.get("/healthz", (c) => c.json({ ok: true }));
 
+// ── Agent reverse WebSocket (GATEWAY_SECRET query param) ────────────
+app.get("/ws/connect", async (c) => {
+  const secret = c.req.query("secret");
+  const name = c.req.query("name");
+  if (name === undefined || name === "") {
+    return c.json({ error: "name required" }, 400);
+  }
+  if (secret !== c.env.GATEWAY_SECRET) {
+    return c.json({ error: "unauthorized" }, 401);
+  }
+  if (c.req.header("Upgrade") !== "websocket") {
+    return c.text("expected WebSocket upgrade", 426);
+  }
+  const id = c.env.AGENT_SOCKET.idFromName(name);
+  const stub = c.env.AGENT_SOCKET.get(id);
+  return stub.fetch(c.req.raw);
+});
+
 // ── Gateway management (GATEWAY_SECRET auth) ────────────────────────
 const gateway = new Hono<Env>();
 
@@ -95,11 +261,12 @@ gateway.get("/endpoints", async (c) => {
   for (const key of list.keys) {
     const record = await c.env.ENDPOINTS.get<EndpointRecord>(key.name, "json");
     if (record) {
-      const age = Date.now() - record.lastHeartbeat;
+      const doStatus = await fetchAgentSocketStatus(c.env, record.name);
+      const doConnected = doStatus.ok ? doStatus.connected : null;
       endpoints.push({
         name: record.name,
         url: record.url,
-        status: age < TTL_SECONDS * 1000 ? "online" : "offline",
+        status: endpointStatusFromKvAndDo(record, doConnected),
         lastHeartbeat: record.lastHeartbeat,
       });
     }
@@ -110,7 +277,7 @@ gateway.get("/endpoints", async (c) => {
 
 app.route("/api/gateway", gateway);
 
-// ── API proxy: /api/agents/:agent/* → agent's tunnel URL (dashboard auth) ──
+// ── API proxy: /api/agents/:agent/* → WebSocket (preferred) or agent tunnel URL (dashboard auth) ──
 app.all("/api/agents/:agent/*", async (c) => {
   if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
   const agent = c.req.param("agent");
@@ -120,26 +287,45 @@ app.all("/api/agents/:agent/*", async (c) => {
     return c.json({ error: "agent not found" }, 404);
   }
 
-  // Build target URL: strip /api/:agent prefix, forward the rest
   const url = new URL(c.req.url);
   const pathAfterAgent = url.pathname.replace(`/api/agents/${agent}`, "");
   const targetUrl = `${record.url}/api${pathAfterAgent}${url.search}`;
+  const proxyPath = `/api${pathAfterAgent}${url.search}`;
+  const method = c.req.method;
+  const token = record.agentToken ?? "";
+  const forwardRecord = buildForwardHeaders(c.req.raw.headers, token);
 
-  const headers = new Headers(c.req.raw.headers);
-  headers.delete("host");
-  headers.delete("Authorization"); // don't forward dashboard key to agent
-  if (record.agentToken) {
-    headers.set("X-Agent-Token", record.agentToken);
+  const doStatus = await fetchAgentSocketStatus(c.env, agent);
+  if (doStatus.ok && doStatus.connected) {
+    const bodyStr = await readBodyForWsProxy(method, c.req.raw);
+    const wsRequest: WsRequest = {
+      id: crypto.randomUUID(),
+      method,
+      path: proxyPath,
+      headers: forwardRecord,
+      body: bodyStr,
+    };
+    const proxyResp = await fetchThroughAgentSocket(c.env, agent, c.env.GATEWAY_SECRET, wsRequest);
+    if (proxyResp.status !== 503) {
+      return new Response(proxyResp.body, {
+        status: proxyResp.status,
+        headers: proxyResp.headers,
+      });
+    }
+    try {
+      const resp = await fetchAgentWithRecordHeaders(targetUrl, method, forwardRecord, bodyStr);
+      return new Response(resp.body, {
+        status: resp.status,
+        headers: resp.headers,
+      });
+    } catch (err) {
+      return c.json({ error: "agent unreachable", detail: String(err) }, 502);
+    }
   }
 
+  const headers = buildDashboardProxyHeaders(c.req.raw.headers, token);
   try {
-    const resp = await fetch(targetUrl, {
-      method: c.req.method,
-      headers,
-      body: c.req.method !== "GET" && c.req.method !== "HEAD" ? c.req.raw.body : undefined,
-    });
-
-    // Stream response back
+    const resp = await fetchAgentWithDashboardHeaders(targetUrl, method, headers, c.req.raw.body);
     return new Response(resp.body, {
       status: resp.status,
       headers: resp.headers,
@@ -149,4 +335,5 @@ app.all("/api/agents/:agent/*", async (c) => {
   }
 });
 
+// biome-ignore lint/style/noDefaultExport: Cloudflare Workers entry expects default export
 export default app;

packages/workflow-gateway/src/ws-protocol.ts

@@ -0,0 +1,93 @@
+/** Wire format for HTTP-over-WebSocket proxy between gateway Durable Object and local serve. */
+
+export type WsRequest = {
+  id: string;
+  method: string;
+  path: string;
+  headers: Record<string, string>;
+  body: string | null;
+};
+
+export type WsResponse = {
+  id: string;
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Parse and validate a JSON payload as {@link WsRequest}. */
+export function parseWsRequestJson(raw: string): WsRequest | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    return null;
+  }
+  const id = parsed.id;
+  const method = parsed.method;
+  const path = parsed.path;
+  const headers = parsed.headers;
+  const body = parsed.body;
+  if (!isNonEmptyString(id) || !isNonEmptyString(method) || !isNonEmptyString(path)) {
+    return null;
+  }
+  if (!isRecord(headers)) {
+    return null;
+  }
+  const headerRecord: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string") {
+      return null;
+    }
+    headerRecord[k] = v;
+  }
+  if (body !== null && typeof body !== "string") {
+    return null;
+  }
+  return { id, method, path, headers: headerRecord, body: body === null ? null : body };
+}
+
+/** Parse and validate a JSON payload as {@link WsResponse}. */
+export function parseWsResponseJson(raw: string): WsResponse | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) {
+    return null;
+  }
+  const id = parsed.id;
+  const status = parsed.status;
+  const headers = parsed.headers;
+  const respBody = parsed.body;
+  if (!isNonEmptyString(id) || typeof status !== "number" || !Number.isFinite(status)) {
+    return null;
+  }
+  if (!isRecord(headers)) {
+    return null;
+  }
+  const headerRecord: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (typeof v !== "string") {
+      return null;
+    }
+    headerRecord[k] = v;
+  }
+  if (typeof respBody !== "string") {
+    return null;
+  }
+  return { id, status: Math.trunc(status), headers: headerRecord, body: respBody };
+}

packages/workflow-gateway/wrangler.toml

@@ -6,4 +6,11 @@ compatibility_date = "2025-04-01"
 binding = "ENDPOINTS"
 id = "88b118d1cfab4c049f9c1684848811a3"
 
+[durable_objects]
+bindings = [{ name = "AGENT_SOCKET", class_name = "AgentSocket" }]
+
+[[migrations]]
+tag = "add-agent-socket"
+new_sqlite_classes = ["AgentSocket"]
+
 # GATEWAY_SECRET is set via `wrangler secret put`

packages/workflow-protocol/__tests__/moderator-table.test.ts

@@ -21,11 +21,13 @@ function makeCtx(roles: (keyof TestMeta & string)[]): ModeratorContext<TestMeta>
   return {
     threadId: "test-thread",
     depth: 0,
+    bundleHash: "TESTHASH00001",
     start: {
       role: START,
       content: "test",
       meta: {},
       timestamp: Date.now(),
+      parentState: null,
     } as StartStep,
     steps,
   };

packages/workflow-protocol/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@uncaged/workflow-protocol",
-  "version": "0.1.0",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./src/index.ts"
+    },
+    "./moderator-table.js": {
+      "types": "./dist/moderator-table.d.ts",
+      "import": "./src/moderator-table.ts"
     }
   },
   "peerDependencies": {

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

@@ -4,6 +4,8 @@ export type StartNodePayload = {
   name: string;
   hash: string;
   depth: number;
+  /** Parent thread's head state hash at spawn time. `null` for top-level workflows. */
+  parentState: string | null;
 };
 
 export type StartNode = {
@@ -20,6 +22,8 @@ export type StateNodePayload = {
   ancestors: string[];
   compact: string | null;
   timestamp: number;
+  /** Child thread's final state hash (workflow-as-agent). `null` when no child spawned. */
+  childThread: string | null;
 };
 
 export type StateNode = {

packages/workflow-protocol/src/index.ts

@@ -13,12 +13,12 @@ export type {
   AgentBinding,
   AgentContext,
   AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
   FALLBACK,
   LlmProvider,
-  Moderator,
   ModeratorCondition,
   ModeratorContext,
   ModeratorTable,
@@ -37,6 +37,8 @@ export type {
   WorkflowDefinition,
   WorkflowDescriptor,
   WorkflowFn,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowResult,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
@@ -50,7 +52,3 @@ export { END, START } from "./types.js";
 // ── Constructor functions ──────────────────────────────────────────
 
 export { err, ok } from "./result.js";
-
-// ── Moderator Table ────────────────────────────────────────────────
-
-export { tableToModerator } from "./moderator-table.js";

packages/workflow-protocol/src/types.ts

@@ -27,9 +27,22 @@ export type WorkflowRoleDescriptor = {
   schema: WorkflowRoleSchema;
 };
 
+/** Serializable routing edges derived from a moderator transition table. */
+export type WorkflowGraphEdge = {
+  from: string;
+  to: string;
+  condition: string;
+  conditionDescription: string | null;
+};
+
+export type WorkflowGraph = {
+  edges: readonly WorkflowGraphEdge[];
+};
+
 export type WorkflowDescriptor = {
   description: string;
   roles: Record<string, WorkflowRoleDescriptor>;
+  graph: WorkflowGraph;
 };
 
 // ── Role & Thread ──────────────────────────────────────────────────
@@ -41,6 +54,7 @@ export type RoleOutput = {
   contentHash: string;
   meta: Record<string, unknown>;
   refs: string[];
+  childThread: string | null;
 };
 
 export type StartStep = {
@@ -48,6 +62,7 @@ export type StartStep = {
   content: string;
   meta: Record<string, never>;
   timestamp: number;
+  parentState: string | null;
 };
 
 export type RoleStep<M extends RoleMeta> = {
@@ -63,6 +78,7 @@ export type RoleStep<M extends RoleMeta> = {
 export type ThreadContext<M extends RoleMeta = RoleMeta> = {
   threadId: string;
   depth: number;
+  bundleHash: string;
   start: StartStep;
   steps: RoleStep<M>[];
 };
@@ -127,7 +143,9 @@ export type ExtractFn = <T extends Record<string, unknown>>(
   contentHash: string,
 ) => Promise<ExtractResult<T>>;
 
-export type AgentFn = (ctx: AgentContext) => Promise<string>;
+export type AgentFnResult = string | { output: string; childThread: string | null };
+
+export type AgentFn = (ctx: AgentContext) => Promise<AgentFnResult>;
 
 export type AgentBinding = {
   agent: AgentFn;
@@ -160,7 +178,7 @@ export type Moderator<M extends RoleMeta> = (
 export type WorkflowDefinition<M extends RoleMeta> = {
   description: string;
   roles: { [K in keyof M & string]: RoleDefinition<M[K]> };
-  moderator: Moderator<M>;
+  table: ModeratorTable<M>;
 };
 
 // ── Declarative Moderator Table ────────────────────────────────────

packages/workflow-reactor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-reactor",
-  "version": "0.1.0",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": {

packages/workflow-register/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-register",
-  "version": "0.1.0",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": {

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

@@ -1,12 +1,35 @@
-import type { RoleMeta, WorkflowDefinition } from "@uncaged/workflow-protocol";
+import type {
+  ModeratorTable,
+  ModeratorTransition,
+  RoleMeta,
+  WorkflowDefinition,
+  WorkflowDescriptor,
+  WorkflowGraph,
+  WorkflowGraphEdge,
+} from "@uncaged/workflow-protocol";
+import { END } from "@uncaged/workflow-protocol";
 import * as z from "zod/v4";
-import type { WorkflowDescriptor, WorkflowRoleSchema } from "./types.js";
+import type { WorkflowRoleSchema } from "./types.js";
 
 function stripJsonSchemaMeta(json: Record<string, unknown>): WorkflowRoleSchema {
   const { $schema: _drop, ...rest } = json;
   return rest as WorkflowRoleSchema;
 }
 
+function graphFromTable<M extends RoleMeta>(table: ModeratorTable<M>): WorkflowGraph {
+  const edges: WorkflowGraphEdge[] = [];
+  const entries = Object.entries(table) as Array<[string, ModeratorTransition<M>[]]>;
+  for (const [from, transitions] of entries) {
+    for (const t of transitions) {
+      const conditionName = t.condition === "FALLBACK" ? "FALLBACK" : t.condition.name;
+      const conditionDescription = t.condition === "FALLBACK" ? null : t.condition.description;
+      const to = t.role === END ? END : t.role;
+      edges.push({ from, to, condition: conditionName, conditionDescription });
+    }
+  }
+  return { edges };
+}
+
 export function buildDescriptor<M extends RoleMeta>(
   def: WorkflowDefinition<M>,
 ): WorkflowDescriptor {
@@ -20,5 +43,9 @@ export function buildDescriptor<M extends RoleMeta>(
       schema: stripJsonSchemaMeta(rawJsonSchema),
     };
   }
-  return { description: def.description, roles };
+  return {
+    description: def.description,
+    roles,
+    graph: graphFromTable(def.table),
+  };
 }

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

@@ -37,13 +37,7 @@ function isAllowedImportSpecifier(spec: string): boolean {
   if (spec.startsWith(".") || spec.startsWith("/") || spec.startsWith("file:")) {
     return false;
   }
-  if (
-    spec === "@uncaged/workflow" ||
-    spec === "@uncaged/workflow-runtime" ||
-    spec === "@uncaged/workflow-protocol" ||
-    spec === "@uncaged/workflow-cas" ||
-    spec === "@uncaged/workflow-util"
-  ) {
+  if (spec.startsWith("@uncaged/workflow")) {
     return true;
   }
   return isBuiltin(spec);
@@ -114,7 +108,8 @@ function bindingInitializerIsCallable(init: Node): boolean {
   return (
     init.type === "FunctionExpression" ||
     init.type === "ArrowFunctionExpression" ||
-    init.type === "CallExpression"
+    init.type === "CallExpression" ||
+    init.type === "Identifier"
   );
 }
 
@@ -404,7 +399,7 @@ export function validateWorkflowBundle(input: WorkflowBundleValidationInput): Re
 
   if (!descriptorExportExists(program)) {
     return err(
-      'workflow bundle must export descriptor (e.g. "export const descriptor = { description, roles }")',
+      'workflow bundle must export descriptor (e.g. "export const descriptor = { description, roles, graph }")',
     );
   }
 

packages/workflow-register/src/bundle/index.ts

@@ -9,6 +9,8 @@ export type {
   ExtractedBundleExports,
   WorkflowBundleValidationInput,
   WorkflowDescriptor,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
 } from "./types.js";

packages/workflow-register/src/bundle/types.ts

@@ -3,6 +3,8 @@ import type { WorkflowDescriptor, WorkflowFn } from "@uncaged/workflow-protocol"
 export type {
   WorkflowDescriptor,
   WorkflowFn,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
 } from "@uncaged/workflow-protocol";

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

@@ -1,6 +1,64 @@
 import { err, ok, type Result } from "@uncaged/workflow-util";
 
-import type { WorkflowDescriptor, WorkflowRoleDescriptor, WorkflowRoleSchema } from "./types.js";
+import type {
+  WorkflowDescriptor,
+  WorkflowGraph,
+  WorkflowGraphEdge,
+  WorkflowRoleDescriptor,
+  WorkflowRoleSchema,
+} from "./types.js";
+
+function validateDescriptorGraphEdge(
+  item: unknown,
+  index: number,
+): Result<WorkflowGraphEdge, string> {
+  if (item === null || typeof item !== "object" || Array.isArray(item)) {
+    return err(`descriptor.graph.edges[${index}] must be a non-array object`);
+  }
+  const e = item as Record<string, unknown>;
+  if (typeof e.from !== "string") {
+    return err(`descriptor.graph.edges[${index}].from must be a string`);
+  }
+  if (typeof e.to !== "string") {
+    return err(`descriptor.graph.edges[${index}].to must be a string`);
+  }
+  if (typeof e.condition !== "string") {
+    return err(`descriptor.graph.edges[${index}].condition must be a string`);
+  }
+  const cdRaw = e.conditionDescription;
+  if (cdRaw !== null && cdRaw !== undefined && typeof cdRaw !== "string") {
+    return err(`descriptor.graph.edges[${index}].conditionDescription must be a string or null`);
+  }
+  const conditionDescription: string | null = cdRaw === undefined || cdRaw === null ? null : cdRaw;
+  return ok({
+    from: e.from,
+    to: e.to,
+    condition: e.condition,
+    conditionDescription,
+  });
+}
+
+function validateDescriptorGraph(graphRaw: unknown): Result<WorkflowGraph, string> {
+  if (graphRaw === null || typeof graphRaw !== "object" || Array.isArray(graphRaw)) {
+    return err("descriptor.graph must be a non-array object");
+  }
+  const graphRecord = graphRaw as Record<string, unknown>;
+  const edgesRaw = graphRecord.edges;
+  if (!Array.isArray(edgesRaw)) {
+    return err("descriptor.graph.edges must be an array");
+  }
+
+  const edges: WorkflowGraphEdge[] = [];
+  for (let i = 0; i < edgesRaw.length; i++) {
+    const edgeResult = validateDescriptorGraphEdge(edgesRaw[i], i);
+    if (!edgeResult.ok) {
+      return edgeResult;
+    }
+    edges.push(edgeResult.value);
+  }
+
+  return ok({ edges });
+}
 
 export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescriptor, string> {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -36,5 +94,10 @@ export function validateWorkflowDescriptor(value: unknown): Result<WorkflowDescr
     };
   }
 
-  return ok({ description, roles });
+  const graphResult = validateDescriptorGraph(root.graph);
+  if (!graphResult.ok) {
+    return graphResult;
+  }
+
+  return ok({ description, roles, graph: graphResult.value });
 }

packages/workflow-register/src/index.ts

@@ -3,6 +3,8 @@ export type {
   ExtractedBundleExports,
   WorkflowBundleValidationInput,
   WorkflowDescriptor,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
 } from "./bundle/index.js";

packages/workflow-runtime/__tests__/build-context.test.ts

@@ -27,7 +27,7 @@ describe("buildThreadContext", () => {
     const bundleHash = "BHAAAAAAAAAAA";
     const startHash = await putStartNode(
       cas,
-      { name: "demo", hash: bundleHash, depth: 2 },
+      { name: "demo", hash: bundleHash, depth: 2, parentState: null },
       promptHash,
     );
 
@@ -41,6 +41,7 @@ describe("buildThreadContext", () => {
       ancestors: [],
       compact: null,
       timestamp: 1000,
+      childThread: null,
     });
 
     const chCode = await putContentNodeWithRefs(cas, "code body", []);
@@ -52,6 +53,7 @@ describe("buildThreadContext", () => {
       ancestors: [statePlan],
       compact: null,
       timestamp: 2000,
+      childThread: null,
     });
 
     const ctx = await buildThreadContext(stateCode, cas);
@@ -71,7 +73,7 @@ describe("buildThreadContext", () => {
     const promptHash = await cas.put("only-prompt");
     const startHash = await putStartNode(
       cas,
-      { name: "solo", hash: "BHBBBBBBBBBBB", depth: 1 },
+      { name: "solo", hash: "BHBBBBBBBBBBB", depth: 1, parentState: null },
       promptHash,
     );
 
@@ -87,7 +89,7 @@ describe("buildThreadContext", () => {
     const bundleHash = "BHCCCCCCCCCCC";
     const startHash = await putStartNode(
       cas,
-      { name: "demo", hash: bundleHash, depth: 0 },
+      { name: "demo", hash: bundleHash, depth: 0, parentState: null },
       promptHash,
     );
 
@@ -100,6 +102,7 @@ describe("buildThreadContext", () => {
       ancestors: [],
       compact: null,
       timestamp: 500,
+      childThread: null,
     });
 
     const endContent = await putContentNodeWithRefs(cas, "finished", []);
@@ -111,6 +114,7 @@ describe("buildThreadContext", () => {
       ancestors: [state1],
       compact: null,
       timestamp: 600,
+      childThread: null,
     });
 
     const ctx = await buildThreadContext(endState, cas);

packages/workflow-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-runtime",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

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

@@ -54,11 +54,13 @@ async function threadFromStartHead<M extends RoleMeta>(
   return {
     threadId: "",
     depth: p.depth,
+    bundleHash: p.hash,
     start: {
       role: START,
       content: prompt,
       meta: {},
       timestamp: 0,
+      parentState: p.parentState,
     },
     steps: [],
   };
@@ -113,11 +115,13 @@ async function threadFromStateHead<M extends RoleMeta>(
   return {
     threadId: "",
     depth: sp.depth,
+    bundleHash: sp.hash,
     start: {
       role: START,
       content: prompt,
       meta: {},
       timestamp: firstTs,
+      parentState: sp.parentState,
     },
     steps,
   };

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

@@ -1,4 +1,5 @@
 import { putContentNodeWithRefs } from "@uncaged/workflow-cas";
+import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js";
 import type * as z from "zod/v4";
 
 import {
@@ -6,6 +7,7 @@ import {
   type AgentBinding,
   type AgentContext,
   type AgentFn,
+  type AgentFnResult,
   END,
   type ModeratorContext,
   type RoleDefinition,
@@ -49,6 +51,16 @@ function mergeUniqueHashes(a: readonly string[], b: readonly string[]): string[]
   return out;
 }
 
+function normalizeAgentResult(result: AgentFnResult): {
+  output: string;
+  childThread: string | null;
+} {
+  if (typeof result === "string") {
+    return { output: result, childThread: null };
+  }
+  return result;
+}
+
 function agentForRole(binding: AgentBinding, roleName: string): AgentFn {
   const overrides = binding.overrides;
   const overrideFn: AgentFn | undefined =
@@ -57,7 +69,9 @@ function agentForRole(binding: AgentBinding, roleName: string): AgentFn {
 }
 
 async function advanceOneRound<M extends RoleMeta>(
-  def: Pick<WorkflowDefinition<M>, "roles" | "moderator">,
+  def: Pick<WorkflowDefinition<M>, "roles"> & {
+    pickNext: (ctx: ModeratorContext<M>) => (keyof M & string) | typeof END;
+  },
   binding: AgentBinding,
   params: {
     thread: ModeratorContext<M>;
@@ -67,7 +81,7 @@ async function advanceOneRound<M extends RoleMeta>(
   const { thread, runtime } = params;
   const modCtx: ModeratorContext<M> = thread;
 
-  const next = def.moderator(modCtx);
+  const next = def.pickNext(modCtx);
   if (!isRoleNext(next)) {
     return {
       kind: "complete",
@@ -86,9 +100,9 @@ async function advanceOneRound<M extends RoleMeta>(
   };
 
   const agent = agentForRole(binding, next);
-  const raw = await agent(agentCtx as unknown as AgentContext);
+  const agentResult = normalizeAgentResult(await agent(agentCtx as unknown as AgentContext));
 
-  const agentContentHash = await putContentNodeWithRefs(runtime.cas, raw, []);
+  const agentContentHash = await putContentNodeWithRefs(runtime.cas, agentResult.output, []);
 
   const extracted = await runtime.extract(
     roleDef.schema as z.ZodType<Record<string, unknown>>,
@@ -122,22 +136,26 @@ async function advanceOneRound<M extends RoleMeta>(
       contentHash: step.contentHash,
       meta: step.meta,
       refs: step.refs,
+      childThread: agentResult.childThread,
     },
     step,
   };
 }
 
 /**
- * Binds pure role definitions + moderator to runtime agents.
+ * Binds pure role definitions + moderator table to runtime agents.
  * Assign with `export const run = createWorkflow(def, binding)`.
  *
  * Structured meta extraction is delegated to {@link WorkflowRuntime.extract}, which the
  * engine resolves from the workflow registry's `extract` scene.
  */
 export function createWorkflow<M extends RoleMeta>(
-  def: Pick<WorkflowDefinition<M>, "roles" | "moderator">,
+  def: Pick<WorkflowDefinition<M>, "roles" | "table">,
   binding: AgentBinding,
 ): WorkflowFn {
+  const pickNext = tableToModerator(def.table);
+  const loopDef = { roles: def.roles, pickNext };
+
   return async function* workflowLoop(
     thread: ThreadContext,
     runtime: WorkflowRuntime,
@@ -148,7 +166,7 @@ export function createWorkflow<M extends RoleMeta>(
     let currentThread = thread as ModeratorContext<M>;
 
     while (true) {
-      const outcome = await advanceOneRound(def, binding, {
+      const outcome = await advanceOneRound(loopDef, binding, {
         thread: currentThread,
         runtime,
       });

packages/workflow-runtime/src/index.ts

@@ -5,12 +5,12 @@ export type {
   AgentBinding,
   AgentContext,
   AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
   FALLBACK,
   LlmProvider,
-  Moderator,
   ModeratorCondition,
   ModeratorContext,
   ModeratorTable,
@@ -26,9 +26,11 @@ export type {
   WorkflowDefinition,
   WorkflowDescriptor,
   WorkflowFn,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowResult,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
   WorkflowRuntime,
 } from "./types.js";
-export { END, START, tableToModerator } from "./types.js";
+export { END, START } from "./types.js";

packages/workflow-runtime/src/types.ts

@@ -7,12 +7,12 @@ export type {
   AgentBinding,
   AgentContext,
   AgentFn,
+  AgentFnResult,
   CasStore,
   ExtractFn,
   ExtractResult,
   FALLBACK,
   LlmProvider,
-  Moderator,
   ModeratorCondition,
   ModeratorContext,
   ModeratorTable,
@@ -30,10 +30,12 @@ export type {
   WorkflowDefinition,
   WorkflowDescriptor,
   WorkflowFn,
+  WorkflowGraph,
+  WorkflowGraphEdge,
   WorkflowResult,
   WorkflowRoleDescriptor,
   WorkflowRoleSchema,
   WorkflowRuntime,
 } from "@uncaged/workflow-protocol";
 
-export { END, START, tableToModerator } from "@uncaged/workflow-protocol";
+export { END, START } from "@uncaged/workflow-protocol";

packages/workflow-template-develop/__tests__/develop-template.test.ts

@@ -1,11 +1,14 @@
 import { describe, expect, test } from "bun:test";
+import { tableToModerator } from "@uncaged/workflow-protocol/moderator-table.js";
 import { validateWorkflowDescriptor } from "@uncaged/workflow-register";
 import { END, type ModeratorContext, type RoleStep, START } from "@uncaged/workflow-runtime";
 import { buildDevelopDescriptor } from "../src/descriptor.js";
-import { developModerator } from "../src/index.js";
+import { developTable } from "../src/moderator.js";
 import type { CommitterMeta, PlannerMeta } from "../src/roles/index.js";
 import type { DevelopMeta } from "../src/roles.js";
 
+const developModerator = tableToModerator(developTable);
+
 const DEFAULT_PHASES: PlannerMeta["phases"] = [
   {
     hash: "4KNMR2PX",
@@ -19,6 +22,7 @@ function makeStart(): ModeratorContext<DevelopMeta>["start"] {
     content: "Implement the feature",
     meta: {},
     timestamp: 0,
+    parentState: null,
   };
 }
 
@@ -26,6 +30,7 @@ function makeCtx(steps: ModeratorContext<DevelopMeta>["steps"]): ModeratorContex
   return {
     threadId: "01TEST000000000000000000TR",
     depth: 0,
+    bundleHash: "TESTHASH00001",
     start: makeStart(),
     steps,
   };
@@ -232,6 +237,7 @@ describe("buildDevelopDescriptor", () => {
       "reviewer",
       "tester",
     ]);
+    expect(validated.value.graph.edges.length).toBeGreaterThan(0);
     for (const key of ["planner", "coder", "reviewer", "tester", "committer"] as const) {
       const role = validated.value.roles[key];
       expect(role).toBeDefined();

packages/workflow-template-develop/bundle-entry.ts

@@ -1,8 +1,9 @@
 /**
  * develop bundle entry — 小橘 🍊
+ *
+ * All roles use cursor-agent with workspace auto-extracted from context.
  */
-import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
-import { createExtract } from "@uncaged/workflow-execute";
+import { createCursorAgent } from "@uncaged/workflow-agent-cursor";
 import { createWorkflow } from "@uncaged/workflow-runtime";
 import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
 
@@ -22,23 +23,24 @@ function optionalEnv(name: string): string | null {
   return value;
 }
 
-const provider = {
+const llmProvider = {
   baseUrl:
     optionalEnv("WORKFLOW_LLM_BASE_URL") ?? "https://dashscope.aliyuncs.com/compatible-mode/v1",
   apiKey: requireEnv("WORKFLOW_LLM_API_KEY"),
   model: optionalEnv("WORKFLOW_LLM_MODEL") ?? "qwen-plus",
 };
 
-const agent = createHermesAgent({
-  model: optionalEnv("WORKFLOW_HERMES_MODEL"),
-  timeout: optionalEnv("WORKFLOW_HERMES_TIMEOUT")
-    ? Number(optionalEnv("WORKFLOW_HERMES_TIMEOUT"))
-    : null,
+const agent = createCursorAgent({
+  command: requireEnv("WORKFLOW_CURSOR_COMMAND"),
+  model: optionalEnv("WORKFLOW_CURSOR_MODEL"),
+  timeout: optionalEnv("WORKFLOW_CURSOR_TIMEOUT")
+    ? Number(optionalEnv("WORKFLOW_CURSOR_TIMEOUT"))
+    : 0,
+  workspace: null,
+  llmProvider,
 });
 
-const extract = createExtract(provider);
-
-const wf = createWorkflow(developWorkflowDefinition, { agent }, extract);
+const wf = createWorkflow(developWorkflowDefinition, { agent, overrides: null });
 
 export const descriptor = buildDevelopDescriptor();
-export const run = wf.run;
+export const run = wf;

packages/workflow-template-develop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uncaged/workflow-template-develop",
-  "version": "0.2.0",
+  "version": "0.3.5",
   "type": "module",
   "exports": {
     ".": {
@@ -15,5 +15,8 @@
     "@uncaged/workflow-register": "workspace:*",
     "@uncaged/workflow-runtime": "workspace:*",
     "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@uncaged/workflow-protocol": "workspace:*"
   }
 }

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

@@ -1,12 +1,12 @@
 import { buildDescriptor } from "@uncaged/workflow-register";
 
-import { developModerator } from "./moderator.js";
+import { developTable } from "./moderator.js";
 import { DEVELOP_WORKFLOW_DESCRIPTION, developRoles } from "./roles.js";
 
 export function buildDevelopDescriptor() {
   return buildDescriptor({
     description: DEVELOP_WORKFLOW_DESCRIPTION,
     roles: developRoles,
-    moderator: developModerator,
+    table: developTable,
   });
 }

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

@@ -1,10 +1,10 @@
 import type { WorkflowDefinition } from "@uncaged/workflow-runtime";
 
-import { developModerator } from "./moderator.js";
+import { developTable } from "./moderator.js";
 import { DEVELOP_WORKFLOW_DESCRIPTION, type DevelopMeta, developRoles } from "./roles.js";
 
 export { buildDevelopDescriptor } from "./descriptor.js";
-export { developModerator } from "./moderator.js";
+export { developTable } from "./moderator.js";
 export {
   type CoderMeta,
   type CommitterMeta,
@@ -33,5 +33,5 @@ export {
 export const developWorkflowDefinition: WorkflowDefinition<DevelopMeta> = {
   description: DEVELOP_WORKFLOW_DESCRIPTION,
   roles: developRoles,
-  moderator: developModerator,
+  table: developTable,
 };