fix: cursor agent workspace from config instead of type assertion

Address review feedback: remove unsafe `as unknown as` cast on
currentRole. CursorAgentConfig now takes workspace directly instead
of using ExtractFn to infer it from thread context.

Refs #180

.gitignore

@@ -4,3 +4,4 @@ bun.lock
 *.tgz
 tsconfig.tsbuildinfo
 .npmrc
+

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

@@ -50,7 +50,6 @@ const greeterMetaSchema = z.object({
 export const greeterRole: RoleDefinition<HelloTemplateMeta["greeter"]> = {
   description: "Says hello — replace with your first role.",
   systemPrompt: "You are a helpful assistant. Reply with one short friendly sentence.",
-  extractPrompt: "Extract the assistant's greeting as message.",
   schema: greeterMetaSchema,
   extractRefs: null,
 };

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

@@ -93,18 +93,18 @@ Init 生成的骨架：\`templates/\` 下放可复用定义，\`workflows/\` 下
 ## 2. 核心概念
 
 - **RoleMeta**：\`Record<string, Record<string, unknown>>\`，角色名 → 该角色结构化 meta 的形状约定。
-- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`extractPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
+- **RoleDefinition<Meta>**：纯数据——\`description\`、\`systemPrompt\`、\`schema\`（Zod v4）。不含执行逻辑。
 - **WorkflowDefinition<M extends RoleMeta>**：\`description\` + \`roles\`（各角色定义）+ **Moderator**。
 - **Moderator**：\`(ctx: ModeratorContext<M>) => (角色名) | END\`。同步、纯函数，只做路由。
 - **AgentFn**：\`(ctx: AgentContext) => Promise<string>\`，原始文本输出；从上下文读取当前角色的 \`systemPrompt\`。
-- **ExtractFn**：从上下文与 prompt 解析结构化数据（引擎与 Agent 都可使用）。
+- **ExtractFn**：从 CAS content hash 解析结构化数据（引擎与 Agent 都可使用）。
 
 引擎循环简述：**Moderator** → 选角色 → **Agent** 产出文本 → **Extract** 写入 **meta** → 追加 step，重复直至 **END**。详见 \`docs/architecture.md\` 中的三阶段说明。
 
 ## 3. 开发流程
 
 1. **定义 RoleMeta**：为每个角色约定 meta 的 TypeScript 类型（与 Zod schema 对齐）。
-2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`extractPrompt\` / \`description\`。
+2. **编写 RoleDefinition**：为每个角色写 Zod \`schema\`，补齐 \`systemPrompt\` / \`description\`。
 3. **编写 Moderator**：根据 \`ctx.steps\` 与业务状态返回下一个角色名或 \`END\`。
 4. **组装 WorkflowDefinition**：在模板 \`index\` 中导出 definition（以及必要的角色 / moderator 导出）。
 5. **实例化**：在 workflow 包中使用 \`createWorkflow(def, binding)\`（或项目约定的封装）绑定 **AgentFn**；**ExtractFn** 由引擎从 **workflow.yaml** 注入 \`WorkflowRuntime\`。

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

@@ -8,7 +8,7 @@ import { createWorkflowRoutes } from "./routes-workflow.js";
 
 const MAX_BODY_SIZE = 1_048_576; // 1 MB
 
-export function createApp(storageRoot: string): Hono {
+export function createApp(storageRoot: string, agentToken: string | null): Hono {
   const app = new Hono();
 
   app.onError((_err, c) => {
@@ -37,7 +37,19 @@ export function createApp(storageRoot: string): Hono {
     await next();
   });
 
+  // ── Agent token auth (skip healthz) ───────────────────────────────
+  if (agentToken !== null) {
+    app.use("/api/*", async (c, next) => {
+      const token = c.req.header("X-Agent-Token");
+      if (token !== agentToken) {
+        return c.json({ error: "unauthorized" }, 401);
+      }
+      await next();
+    });
+  }
+
   app.get("/healthz", (c) => c.json({ ok: true }));
+  app.get("/api/healthz", (c) => c.json({ ok: true }));
 
   app.route("/api/workflows", createWorkflowRoutes(storageRoot));
   app.route("/api/threads", createThreadRoutes(storageRoot));

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

@@ -1,4 +1,4 @@
-import { statSync, watch } from "node:fs";
+import { existsSync, statSync, watch } from "node:fs";
 import { join } from "node:path";
 import { createCasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
 import {
@@ -118,7 +118,12 @@ async function emitRecordsForHead(params: {
         params.eventId.n++;
         await params.stream.writeSSE({
           event: "record",
-          data: JSON.stringify({ type: "workflow-result", ...wf }),
+          data: JSON.stringify({
+            type: "workflow-result",
+            returnCode: wf.returnCode,
+            content: wf.summary,
+            timestamp: null,
+          }),
           id: String(params.eventId.n),
         });
         return true;
@@ -307,6 +312,18 @@ export function createLiveRoutes(storageRoot: string): Hono {
         return;
       }
 
+      // If thread is not actively running, emit all records and close — don't keep SSE open
+      const runningPath = join(storageRoot, "logs", threadTarget.bundleHash, `${threadId}.running`);
+      if (!existsSync(runningPath)) {
+        eventId.n++;
+        await stream.writeSSE({
+          event: "done",
+          data: JSON.stringify({ reason: "not-running" }),
+          id: String(eventId.n),
+        });
+        return;
+      }
+
       const controller = new AbortController();
       let completed = false;
 

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

@@ -1,36 +1,60 @@
 import { join } from "node:path";
-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 { END } from "@uncaged/workflow-runtime";
 import { getGlobalCasDir } from "@uncaged/workflow-util";
 import { Hono } from "hono";
 
 import { pathExists } from "../../fs-utils.js";
-import type { ResolvedThreadRecord } from "../../thread-scan.js";
+import type { HistoricalThreadRow, ResolvedThreadRecord } from "../../thread-scan.js";
 import {
   listHistoricalThreads,
   listRunningThreads,
+  resolveThreadListStatus,
   resolveThreadRecord,
 } from "../../thread-scan.js";
 import { cmdKill, cmdPause, cmdResume } from "../thread/control.js";
 import { cmdRun } from "../thread/run.js";
 
+async function readStartInfo(
+  cas: ReturnType<typeof createCasStore>,
+  startHash: string,
+): Promise<{ name: string | null; prompt: string | null }> {
+  const raw = await cas.get(startHash);
+  if (raw === null) return { name: null, prompt: null };
+  const parsed = parseCasThreadNode(raw);
+  if (parsed === null || parsed.kind !== "start") return { name: null, prompt: null };
+  const name = parsed.node.payload.name;
+  const promptHash = parsed.node.refs[0] ?? null;
+  let prompt: string | null = null;
+  if (promptHash !== null) {
+    prompt = await getContentMerklePayload(cas, promptHash);
+  }
+  return { name, prompt };
+}
+
 async function buildThreadDetailRecords(
   storageRoot: string,
   resolved: ResolvedThreadRecord,
+  runningMarkerPresent: boolean,
+  statusRow: HistoricalThreadRow,
 ): Promise<unknown[]> {
   const cas = createCasStore(getGlobalCasDir(storageRoot));
   const frames = await walkStateFramesNewestFirst(cas, resolved.head);
   const chronological = [...frames].reverse();
 
+  const { name: workflowName, prompt } = await readStartInfo(cas, resolved.start);
+
+  const status = await resolveThreadListStatus(storageRoot, statusRow, runningMarkerPresent);
+
   const records: unknown[] = [
     {
       type: "thread-start",
+      workflow: workflowName ?? "unknown",
+      prompt: prompt ?? null,
       threadId: resolved.threadId,
-      bundleHash: resolved.bundleHash,
-      head: resolved.head,
-      start: resolved.start,
-      source: resolved.source,
+      status,
+      timestamp: null,
     },
   ];
 
@@ -42,7 +66,12 @@ async function buildThreadDetailRecords(
       const returnCode = fr.payload.meta.returnCode;
       const summary = fr.payload.meta.summary;
       if (typeof returnCode === "number" && typeof summary === "string") {
-        records.push({ type: "workflow-result", returnCode, summary });
+        records.push({
+          type: "workflow-result",
+          returnCode,
+          content: summary,
+          timestamp: fr.payload.timestamp,
+        });
       }
       continue;
     }
@@ -73,8 +102,8 @@ export function createThreadRoutes(storageRoot: string): Hono {
     const threads = await Promise.all(
       rows.map(async (r) => {
         const runningPath = join(storageRoot, "logs", r.hash, `${r.threadId}.running`);
-        const isRunning = await pathExists(runningPath);
-        const status = r.source === "history" ? "completed" : isRunning ? "running" : "active";
+        const runningMarkerPresent = await pathExists(runningPath);
+        const status = await resolveThreadListStatus(storageRoot, r, runningMarkerPresent);
         return {
           threadId: r.threadId,
           workflow: r.workflowName,
@@ -98,7 +127,22 @@ export function createThreadRoutes(storageRoot: string): Hono {
     if (resolved === null) {
       return c.json({ error: `thread not found: ${threadId}` }, 404);
     }
-    const records = await buildThreadDetailRecords(storageRoot, resolved);
+    const runningPath = join(storageRoot, "logs", resolved.bundleHash, `${threadId}.running`);
+    const runningMarkerPresent = await pathExists(runningPath);
+    const statusRow = {
+      threadId: resolved.threadId,
+      hash: resolved.bundleHash,
+      workflowName: null,
+      source: resolved.source,
+      activityTs: 0,
+      head: resolved.head,
+    };
+    const records = await buildThreadDetailRecords(
+      storageRoot,
+      resolved,
+      runningMarkerPresent,
+      statusRow,
+    );
     return c.json({ threadId, records });
   });
 

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

@@ -1,12 +1,27 @@
+import { randomUUID } from "node:crypto";
+import { hostname as osHostname } from "node:os";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 import { serve } from "bun";
 
 import { printCliLine } from "../../cli-output.js";
 import { createApp } from "./app.js";
+import {
+  registerWithGateway,
+  startHeartbeat,
+  startTunnel,
+  unregisterFromGateway,
+} from "./tunnel.js";
 import type { ServeOptions } from "./types.js";
 
-export function startServer(storageRoot: string, options: ServeOptions): void {
-  const app = createApp(storageRoot);
+const DEFAULT_GATEWAY_URL = "https://workflow-gateway.shazhou.workers.dev";
+const HEARTBEAT_INTERVAL_MS = 60_000;
+
+export function startServer(
+  storageRoot: string,
+  options: ServeOptions,
+  agentToken: string | null,
+): void {
+  const app = createApp(storageRoot, agentToken);
 
   const server = serve({
     fetch: app.fetch,
@@ -28,30 +43,51 @@ function parsePortValue(value: string | undefined): Result<number, string> {
   return ok(parsed);
 }
 
+function requireNextArg(argv: string[], i: number, flag: string): Result<string, string> {
+  const next = argv[i + 1];
+  if (next === undefined) {
+    return err(`${flag} requires a value`);
+  }
+  return ok(next);
+}
+
 function parseServeArgv(argv: string[]): Result<ServeOptions, string> {
   let port = 7860;
   let hostname = "127.0.0.1";
+  let name = osHostname().split(".")[0].toLowerCase();
+  let noTunnel = false;
+  let gatewayUrl = DEFAULT_GATEWAY_URL;
+  const gatewaySecret = process.env.WORKFLOW_GATEWAY_SECRET ?? "";
+  const stringFlags: Record<string, (v: string) => void> = {
+    "--host": (v) => {
+      hostname = v;
+    },
+    "--name": (v) => {
+      name = v;
+    },
+    "--gateway": (v) => {
+      gatewayUrl = v;
+    },
+  };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--port" || arg === "-p") {
       const portResult = parsePortValue(argv[i + 1]);
-      if (!portResult.ok) {
-        return portResult;
-      }
+      if (!portResult.ok) return portResult;
       port = portResult.value;
       i++;
-    } else if (arg === "--host") {
-      const next = argv[i + 1];
-      if (next === undefined) {
-        return err("--host requires a value");
-      }
-      hostname = next;
+    } else if (arg === "--no-tunnel") {
+      noTunnel = true;
+    } else if (arg in stringFlags) {
+      const r = requireNextArg(argv, i, arg);
+      if (!r.ok) return r;
+      stringFlags[arg](r.value);
       i++;
     }
   }
 
-  return ok({ port, hostname });
+  return ok({ port, hostname, name, noTunnel, gatewayUrl, gatewaySecret });
 }
 
 export async function dispatchServe(storageRoot: string, argv: string[]): Promise<number> {
@@ -61,7 +97,65 @@ export async function dispatchServe(storageRoot: string, argv: string[]): Promis
     return 1;
   }
 
-  startServer(storageRoot, parsed.value);
+  const options = parsed.value;
+  const agentToken = options.noTunnel ? null : randomUUID();
+  startServer(storageRoot, options, agentToken);
+
+  if (options.noTunnel) {
+    printCliLine("tunnel disabled (--no-tunnel)");
+    await new Promise(() => {});
+    return 0;
+  }
+
+  // Start cloudflared quick tunnel
+  printCliLine("starting cloudflared quick tunnel...");
+  const tunnel = await startTunnel(options.port);
+
+  if (!tunnel) {
+    printCliLine("failed to create tunnel — continuing without gateway registration");
+    await new Promise(() => {});
+    return 0;
+  }
+
+  printCliLine(`tunnel: ${tunnel.url}`);
+
+  // Register with gateway
+  if (options.gatewaySecret) {
+    const registered = await registerWithGateway(
+      options.gatewayUrl,
+      options.name,
+      tunnel.url,
+      options.gatewaySecret,
+      agentToken!,
+    );
+    if (registered) {
+      printCliLine(`registered with gateway as "${options.name}"`);
+    }
+
+    // Start heartbeat
+    const heartbeatTimer = startHeartbeat(
+      options.gatewayUrl,
+      options.name,
+      tunnel.url,
+      options.gatewaySecret,
+      agentToken!,
+      HEARTBEAT_INTERVAL_MS,
+    );
+
+    // Cleanup on exit
+    const cleanup = async () => {
+      clearInterval(heartbeatTimer);
+      printCliLine("unregistering from gateway...");
+      await unregisterFromGateway(options.gatewayUrl, options.name, options.gatewaySecret);
+      tunnel.process.kill();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  } else {
+    printCliLine("WORKFLOW_GATEWAY_SECRET not set — skipping gateway registration");
+  }
 
   // Keep process alive
   await new Promise(() => {});

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

@@ -0,0 +1,88 @@
+import { printCliLine } from "../../cli-output.js";
+
+type TunnelHandle = {
+  process: ReturnType<typeof Bun.spawn>;
+  url: string;
+};
+
+export async function startTunnel(port: number): Promise<TunnelHandle | null> {
+  const proc = Bun.spawn(["cloudflared", "tunnel", "--url", `http://localhost:${port}`], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  // cloudflared prints the URL to stderr
+  const reader = proc.stderr.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  const deadline = Date.now() + 30_000;
+
+  while (Date.now() < deadline) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const match = buffer.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/);
+    if (match) {
+      // Release the reader so stderr keeps flowing without backpressure
+      reader.releaseLock();
+      return { process: proc, url: match[0] };
+    }
+  }
+
+  reader.releaseLock();
+  proc.kill();
+  return null;
+}
+
+export async function registerWithGateway(
+  gatewayUrl: string,
+  name: string,
+  tunnelUrl: string,
+  secret: string,
+  agentToken: string,
+): Promise<boolean> {
+  try {
+    const resp = await fetch(`${gatewayUrl}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, url: tunnelUrl, secret, agentToken }),
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      printCliLine(`gateway registration failed: ${resp.status} ${body}`);
+      return false;
+    }
+    return true;
+  } catch (e) {
+    printCliLine(`gateway registration error: ${e}`);
+    return false;
+  }
+}
+
+export async function unregisterFromGateway(
+  gatewayUrl: string,
+  name: string,
+  secret: string,
+): Promise<void> {
+  try {
+    await fetch(`${gatewayUrl}/register/${name}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${secret}` },
+    });
+  } catch {
+    // Best effort — process is exiting
+  }
+}
+
+export function startHeartbeat(
+  gatewayUrl: string,
+  name: string,
+  tunnelUrl: string,
+  secret: string,
+  agentToken: string,
+  intervalMs: number,
+): ReturnType<typeof setInterval> {
+  return setInterval(() => {
+    registerWithGateway(gatewayUrl, name, tunnelUrl, secret, agentToken).catch(() => {});
+  }, intervalMs);
+}

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

@@ -1,4 +1,8 @@
 export type ServeOptions = {
   port: number;
   hostname: string;
+  name: string;
+  noTunnel: boolean;
+  gatewayUrl: string;
+  gatewaySecret: string;
 };

packages/cli-workflow/src/run-argv.ts

@@ -34,7 +34,7 @@ function parseFlagAt(argv: string[], index: number): Result<FlagOk, string> | nu
 export function parseRunArgv(argv: string[]): Result<ParsedRunArgv, string> {
   let name: string | undefined;
   let prompt = "";
-  let maxRounds = 5;
+  let maxRounds = 10;
 
   let i = 0;
   const first = argv[0];

packages/cli-workflow/src/skill.ts

@@ -85,6 +85,12 @@ ${commandSections.join("\n\n")}
 | \`run\` | \`thread run\` | Shortcut to start a thread |
 | \`live\` | \`thread live\` | Shortcut to attach to a thread |
 
+### serve
+
+| Command | Args | Description |
+|---------|------|-------------|
+| \`serve\` | \`[--port N] [--host ADDR] [--name NAME]\` | Start HTTP API server with auto-tunnel. \`--name\` registers with the gateway. |
+
 ## Typical Workflow
 
 1. \`uncaged-workflow workflow add my-wf ./my-wf.esm.js\` — register a workflow
@@ -92,6 +98,21 @@ ${commandSections.join("\n\n")}
 3. \`uncaged-workflow live --latest\` — attach and watch output
 4. \`uncaged-workflow thread show <thread-id>\` — inspect completed thread
 
+## Thread Status
+
+| Status | Meaning |
+|--------|---------|
+| \`running\` | Worker process is alive (\`.running\` marker + live PID) |
+| \`active\` | In \`threads.json\` but not currently running (paused or waiting) |
+| \`completed\` | Finished with \`returnCode === 0\` (has \`__end__\` frame in CAS) |
+| \`failed\` | Finished with non-zero return code, or worker crashed (dead PID / no ctl) |
+
+## Defaults
+
+| Setting | CLI | HTTP API |
+|---------|-----|----------|
+| \`maxRounds\` | 10 | 10 |
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -103,7 +124,9 @@ ${commandSections.join("\n\n")}
 
 | Variable | Description |
 |----------|-------------|
-| \`UNCAGED_WORKFLOW_STORAGE_ROOT\` | Override the default storage directory for all workflow data |
+| \`WORKFLOW_STORAGE_ROOT\` | Override the default storage directory for all workflow data |
+| \`UNCAGED_WORKFLOW_STORAGE_ROOT\` | Same as above (takes priority) |
+| \`WORKFLOW_LLM_API_KEY\` | API key for LLM calls during workflow execution |
 `;
 }
 
@@ -200,7 +223,6 @@ Each role has:
 |-------|------|---------|
 | \`description\` | string | What the role does |
 | \`systemPrompt\` | string | System prompt for the agent |
-| \`extractPrompt\` | string | Instruction for extracting structured meta |
 | \`schema\` | ZodSchema | Validates the extracted meta |
 | \`extractRefs\` | fn or null | Extracts CAS hashes from meta for DAG linking |
 

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

@@ -5,10 +5,13 @@ import {
   readThreadsIndex,
   type ThreadHistoryEntry,
   type ThreadIndex,
+  walkStateFramesNewestFirst,
 } from "@uncaged/workflow-execute";
+import { END } from "@uncaged/workflow-runtime";
 import { getGlobalCasDir } from "@uncaged/workflow-util";
 
 import { pathExists, readTextFileIfExists } from "./fs-utils.js";
+import { readWorkerCtl } from "./worker-spawn.js";
 
 async function readWorkflowNameFromStartHash(
   storageRoot: string,
@@ -98,6 +101,8 @@ export type HistoricalThreadRow = {
   source: "active" | "history";
   /** `updatedAt` for active threads; `completedAt` for history (ms since epoch). */
   activityTs: number;
+  /** Current CAS head (`threads.json` / history row). */
+  head: string;
 };
 
 export type ResolvedThreadRecord = {
@@ -172,6 +177,95 @@ export async function resolveThreadRecord(
   return null;
 }
 
+export type ThreadHeadTerminal =
+  | { kind: "non-terminal" }
+  | { kind: "terminal"; returnCode: number };
+
+/** True when the newest frame at `headHash` is `__end__` (workflow finished in CAS). */
+export async function readThreadTerminalFromHead(
+  storageRoot: string,
+  headHash: string,
+): Promise<ThreadHeadTerminal> {
+  const cas = createCasStore(getGlobalCasDir(storageRoot));
+  const frames = await walkStateFramesNewestFirst(cas, headHash);
+  const newest = frames[0];
+  if (newest === undefined) {
+    return { kind: "non-terminal" };
+  }
+  if (newest.payload.role !== END) {
+    return { kind: "non-terminal" };
+  }
+  const rc = newest.payload.meta.returnCode;
+  if (typeof rc !== "number") {
+    return { kind: "terminal", returnCode: 1 };
+  }
+  return { kind: "terminal", returnCode: rc };
+}
+
+export type ThreadListStatus = "running" | "active" | "completed" | "failed";
+
+/** Combines `.running` marker with CAS head: stale markers do not imply `running`. */
+export async function resolveThreadListStatus(
+  storageRoot: string,
+  row: HistoricalThreadRow,
+  runningMarkerPresent: boolean,
+): Promise<ThreadListStatus> {
+  const terminal = await readThreadTerminalFromHead(storageRoot, row.head);
+  if (terminal.kind === "terminal") {
+    return terminal.returnCode !== 0 ? "failed" : "completed";
+  }
+  if (row.source === "history") {
+    return "completed";
+  }
+  if (runningMarkerPresent) {
+    const ctlResult = await readWorkerCtl(storageRoot, row.hash);
+    if (ctlResult.ok) {
+      try {
+        process.kill(ctlResult.value.pid, 0);
+        return "running";
+      } catch {
+        // Worker PID is dead but .running marker remains — crashed thread
+        return "failed";
+      }
+    }
+    return "running";
+  }
+  // No .running marker + no __end__ + source "active" → check if worker is dead (crashed)
+  const ctlResult = await readWorkerCtl(storageRoot, row.hash);
+  if (!ctlResult.ok) {
+    // No ctl file means worker never registered or was already cleaned up — dead thread
+    return "failed";
+  }
+  try {
+    process.kill(ctlResult.value.pid, 0);
+  } catch {
+    // Worker PID is dead, thread never finished — crashed
+    return "failed";
+  }
+  return "active";
+}
+
+async function appendRunningThreadRowIfLive(
+  storageRoot: string,
+  hash: string,
+  threadId: string,
+  out: RunningThreadRow[],
+): Promise<void> {
+  const resolved = await resolveThreadRecord(storageRoot, threadId);
+  if (resolved !== null && resolved.bundleHash !== hash) {
+    return;
+  }
+  if (resolved !== null) {
+    const terminal = await readThreadTerminalFromHead(storageRoot, resolved.head);
+    if (terminal.kind === "terminal") {
+      return;
+    }
+  }
+  const workflowName =
+    resolved !== null ? await readWorkflowNameFromStartHash(storageRoot, resolved.start) : null;
+  out.push({ threadId, hash, workflowName });
+}
+
 /** Threads currently executing — identified via `<threadId>.running` markers. */
 export async function listRunningThreads(storageRoot: string): Promise<RunningThreadRow[]> {
   const logsRoot = join(storageRoot, "logs");
@@ -196,10 +290,7 @@ export async function listRunningThreads(storageRoot: string): Promise<RunningTh
         continue;
       }
       const threadId = fileName.slice(0, -".running".length);
-      const resolved = await resolveThreadRecord(storageRoot, threadId);
-      const workflowName =
-        resolved !== null ? await readWorkflowNameFromStartHash(storageRoot, resolved.start) : null;
-      out.push({ threadId, hash, workflowName });
+      await appendRunningThreadRowIfLive(storageRoot, hash, threadId, out);
     }
   }
 
@@ -253,6 +344,7 @@ export async function listHistoricalThreads(
         workflowName,
         source: "active",
         activityTs: entry.updatedAt,
+        head: entry.head,
       });
     }
 
@@ -287,6 +379,7 @@ export async function listHistoricalThreads(
           workflowName,
           source: "history",
           activityTs: e.completedAt,
+          head: e.head,
         });
       }
     }

packages/cli-workflow/src/worker-spawn.ts

@@ -6,6 +6,7 @@ import { getWorkerHostScriptPath } from "@uncaged/workflow-execute";
 import { err, ok, type Result } from "@uncaged/workflow-protocol";
 
 import { pathExists, readTextFileIfExists } from "./fs-utils.js";
+import { readThreadTerminalFromHead, resolveThreadRecord } from "./thread-scan.js";
 
 export type WorkerCtl = {
   pid: number;
@@ -269,7 +270,25 @@ export async function resolveRunningHashForThread(
   if (!(await pathExists(logsRoot))) {
     return err(`thread not running (no logs dir): ${threadId}`);
   }
-  const hashes = await readdir(logsRoot);
+  const resolved = await resolveThreadRecord(storageRoot, threadId);
+  if (resolved !== null) {
+    const runningPath = join(logsRoot, resolved.bundleHash, `${threadId}.running`);
+    if (!(await pathExists(runningPath))) {
+      return err(`thread not running: ${threadId}`);
+    }
+    const terminal = await readThreadTerminalFromHead(storageRoot, resolved.head);
+    if (terminal.kind === "terminal") {
+      return err(`thread not running: ${threadId}`);
+    }
+    return ok(resolved.bundleHash);
+  }
+
+  let hashes: string[];
+  try {
+    hashes = await readdir(logsRoot);
+  } catch {
+    return err(`thread not running: ${threadId}`);
+  }
   for (const hash of hashes) {
     const runningPath = join(logsRoot, hash, `${threadId}.running`);
     if (await pathExists(runningPath)) {

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

@@ -1,24 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import type { ExtractContext, ExtractFn } from "@uncaged/workflow-runtime";
-import type * as z from "zod/v4";
 import { createCursorAgent, validateCursorAgentConfig } from "../src/index.js";
 
-const testExtract: ExtractFn = async <T extends Record<string, unknown>>(
-  _schema: z.ZodType<T>,
-  _prompt: string,
-  _ctx: ExtractContext,
-): Promise<{ meta: T; contentPayload: string; refs: string[] }> => ({
-  meta: { workspace: "/tmp" } as unknown as T,
-  contentPayload: "",
-  refs: [],
-});
-
 describe("validateCursorAgentConfig", () => {
   test("accepts valid config", () => {
     const r = validateCursorAgentConfig({
       model: null,
       timeout: 0,
-      extract: testExtract,
+      workspace: "/tmp/test-project",
     });
     expect(r.ok).toBe(true);
   });
@@ -27,11 +15,11 @@ describe("validateCursorAgentConfig", () => {
     const r = validateCursorAgentConfig({
       model: null,
       timeout: 0,
-      extract: null as unknown as ExtractFn,
+      workspace: "",
     });
     expect(r.ok).toBe(false);
     if (!r.ok) {
-      expect(r.error).toContain("extract");
+      expect(r.error).toContain("workspace");
     }
   });
 
@@ -39,7 +27,7 @@ describe("validateCursorAgentConfig", () => {
     const r = validateCursorAgentConfig({
       model: null,
       timeout: -1,
-      extract: testExtract,
+      workspace: "/tmp/test-project",
     });
     expect(r.ok).toBe(false);
   });
@@ -50,7 +38,7 @@ describe("createCursorAgent", () => {
     const agent = createCursorAgent({
       model: null,
       timeout: 0,
-      extract: testExtract,
+      workspace: "/tmp/test-project",
     });
     expect(typeof agent).toBe("function");
   });
@@ -60,7 +48,7 @@ describe("createCursorAgent", () => {
       createCursorAgent({
         model: null,
         timeout: -1,
-        extract: testExtract,
+        workspace: "/tmp/test-project",
       }),
     ).toThrow();
   });

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

@@ -1,6 +1,5 @@
-import type { AgentFn, ExtractContext } from "@uncaged/workflow-runtime";
+import type { AgentFn } from "@uncaged/workflow-runtime";
 import { buildAgentPrompt, type SpawnCliError, spawnCli } from "@uncaged/workflow-util-agent";
-import * as z from "zod/v4";
 
 import type { CursorAgentConfig } from "./types.js";
 import { validateCursorAgentConfig } from "./validate-config.js";
@@ -8,12 +7,6 @@ import { validateCursorAgentConfig } from "./validate-config.js";
 export type { CursorAgentConfig } from "./types.js";
 export { validateCursorAgentConfig } from "./validate-config.js";
 
-const cursorWorkspaceSchema = z.object({
-  workspace: z
-    .string()
-    .describe("Absolute path to the project/repository directory the agent should work in"),
-});
-
 function throwCursorSpawnError(error: SpawnCliError): never {
   if (error.kind === "non_zero_exit") {
     throw new Error(
@@ -44,16 +37,7 @@ export function createCursorAgent(config: CursorAgentConfig): AgentFn {
   const timeoutMs = config.timeout > 0 ? config.timeout : null;
 
   return async (ctx) => {
-    const extractCtx: ExtractContext = {
-      ...ctx,
-      agentContent: "",
-    };
-    const extracted = await config.extract(
-      cursorWorkspaceSchema,
-      "From the thread context, determine the absolute filesystem path where the project/repository is located.",
-      extractCtx,
-    );
-    const { workspace } = extracted.meta;
+    const workspace = config.workspace;
     const fullPrompt = await buildAgentPrompt(ctx);
     const args = [
       "-p",

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

@@ -1,7 +1,5 @@
-import type { ExtractFn } from "@uncaged/workflow-runtime";
-
 export type CursorAgentConfig = {
   model: string | null;
   timeout: number;
-  extract: ExtractFn;
+  workspace: string;
 };

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

@@ -3,8 +3,8 @@ import { err, ok, type Result } from "@uncaged/workflow-runtime";
 import type { CursorAgentConfig } from "./types.js";
 
 export function validateCursorAgentConfig(config: CursorAgentConfig): Result<void, string> {
-  if (typeof config.extract !== "function") {
-    return err("extract must be a function");
+  if (typeof config.workspace !== "string" || config.workspace.length === 0) {
+    return err("workspace must be a non-empty string (absolute path)");
   }
   if (config.timeout < 0) {
     return err("timeout must be a non-negative number (milliseconds); use 0 for no limit");

packages/workflow-cas/src/merkle.ts

@@ -1,8 +1,41 @@
 import { parse, stringify } from "yaml";
 
-import type { CasStore, MerkleNode, StepMerklePayload, ThreadMerklePayload } from "./types.js";
+import type {
+  CasStore,
+  MerkleNode,
+  MerkleNodeType,
+  StepMerklePayload,
+  ThreadMerklePayload,
+} from "./types.js";
+
+function requireStringHashArray(value: unknown, notArrayMessage: string): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error(notArrayMessage);
+  }
+  const out: string[] = [];
+  for (const c of value) {
+    if (typeof c !== "string") {
+      throw new Error("merkle: hash entry must be a string");
+    }
+    out.push(c);
+  }
+  return out;
+}
+
+function edgeListRaw(rec: Record<string, unknown>, type: MerkleNodeType): unknown {
+  if (type === "content") {
+    return rec.refs !== undefined ? rec.refs : rec.children;
+  }
+  return rec.children;
+}
 
 export function serializeMerkleNode(node: MerkleNode): string {
+  if (node.type === "content") {
+    return stringify(
+      { type: node.type, payload: node.payload, refs: node.children },
+      { indent: 2 },
+    );
+  }
   return stringify(
     { type: node.type, payload: node.payload, children: node.children },
     { indent: 2 },
@@ -17,23 +50,18 @@ export function parseMerkleNode(yamlText: string): MerkleNode {
   const rec = raw as Record<string, unknown>;
   const type = rec.type;
   const payload = rec.payload;
-  const children = rec.children;
   if (type !== "content" && type !== "step" && type !== "thread") {
     throw new Error("merkle: invalid or missing type");
   }
   if (typeof payload !== "string" && (payload === null || typeof payload !== "object")) {
     throw new Error("merkle: payload must be a string or object");
   }
-  if (!Array.isArray(children)) {
-    throw new Error("merkle: children must be an array");
-  }
-  const childHashes: string[] = [];
-  for (const c of children) {
-    if (typeof c !== "string") {
-      throw new Error("merkle: child hash must be a string");
-    }
-    childHashes.push(c);
-  }
+
+  const notArrayMsg =
+    type === "content"
+      ? "merkle: content node requires refs or children array"
+      : "merkle: children must be an array";
+  const childHashes = requireStringHashArray(edgeListRaw(rec, type), notArrayMsg);
   return {
     type,
     payload: typeof payload === "string" ? payload : (payload as Record<string, unknown>),
@@ -85,8 +113,8 @@ export async function putContentMerkleNode(store: CasStore, content: string): Pr
 /**
  * Loads a CAS blob and returns the payload string for a `content` node.
  *
- * Accepts both the legacy `{type:content, payload, children}` Merkle layout
- * and the RFC v3 `{type:content, payload, refs}` content node layout.
+ * Accepts both the legacy `{ type:content, payload, children }` Merkle layout
+ * and the RFC-aligned `{ type:content, payload, refs }` content node layout.
  */
 export async function getContentMerklePayload(
   store: CasStore,

packages/workflow-cas/src/reachable.ts

@@ -9,7 +9,10 @@ function refsFromBlob(content: string): string[] {
       return [];
     }
     const rec = raw as Record<string, unknown>;
-    const refs = rec.refs;
+    let refs = rec.refs;
+    if (!Array.isArray(refs) && Array.isArray(rec.children)) {
+      refs = rec.children;
+    }
     if (!Array.isArray(refs)) {
       return [];
     }

packages/workflow-dashboard/.env.production

@@ -0,0 +1 @@
+VITE_GATEWAY_URL=https://workflow-gateway.shazhou.workers.dev

packages/workflow-dashboard/package.json

@@ -10,7 +10,9 @@
   },
   "dependencies": {
     "react": "^19.2.6",
-    "react-dom": "^19.2.6"
+    "react-dom": "^19.2.6",
+    "react-markdown": "^10.1.0",
+    "shiki": "^4.0.2"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.2.4",

packages/workflow-dashboard/src/api.ts

@@ -1,9 +1,43 @@
-const BASE = "/api";
+const GATEWAY_URL = import.meta.env.VITE_GATEWAY_URL || "";
 
-async function postJson<T>(path: string, body: unknown): Promise<T> {
-  const res = await fetch(`${BASE}${path}`, {
+export function getApiKey(): string | null {
+  try {
+    return localStorage.getItem("workflow-api-key");
+  } catch {
+    return null;
+  }
+}
+
+export function setApiKey(key: string): void {
+  localStorage.setItem("workflow-api-key", key);
+}
+
+export function clearApiKey(): void {
+  localStorage.removeItem("workflow-api-key");
+}
+
+export function hasApiKey(): boolean {
+  return getApiKey() !== null && getApiKey() !== "";
+}
+
+function authHeaders(): Record<string, string> {
+  const key = getApiKey();
+  if (key) return { Authorization: `Bearer ${key}` };
+  return {};
+}
+
+function agentBase(agent: string): string {
+  if (GATEWAY_URL) {
+    return `${GATEWAY_URL}/api/${agent}`;
+  }
+  // Local dev: proxy via vite, no agent prefix
+  return "/api";
+}
+
+async function postJson<T>(base: string, path: string, body: unknown): Promise<T> {
+  const res = await fetch(`${base}${path}`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: { "Content-Type": "application/json", ...authHeaders() },
     body: JSON.stringify(body),
   });
   if (!res.ok) {
@@ -13,14 +47,23 @@ async function postJson<T>(path: string, body: unknown): Promise<T> {
   return res.json() as Promise<T>;
 }
 
-async function fetchJson<T>(path: string): Promise<T> {
-  const res = await fetch(`${BASE}${path}`);
+async function fetchJson<T>(base: string, path: string): Promise<T> {
+  const res = await fetch(`${base}${path}`, { headers: authHeaders() });
   if (!res.ok) {
     throw new Error(`API ${res.status}: ${path}`);
   }
   return res.json() as Promise<T>;
 }
 
+// ── Endpoint types ──────────────────────────────────────────────────
+
+export type AgentEndpoint = {
+  name: string;
+  url: string;
+  status: string;
+  lastHeartbeat: number;
+};
+
 export type WorkflowSummary = {
   name: string;
   currentHash: string;
@@ -35,50 +78,78 @@ export type ThreadSummary = {
   status: string | null;
 };
 
-export type ThreadRecord = {
-  type: string;
-  role: string | null;
-  content: string | null;
-  timestamp: number | null;
-  [key: string]: unknown;
+export type ThreadStartRecord = {
+  type: "thread-start";
+  workflow: string;
+  prompt: string | null;
+  threadId: string;
+  status: string;
+  timestamp: null;
 };
 
-export function listWorkflows(): Promise<{ workflows: WorkflowSummary[] }> {
-  return fetchJson("/workflows");
+export type RoleRecord = {
+  type: "role";
+  role: string;
+  content: string;
+  timestamp: number | null;
+  meta: Record<string, unknown>;
+};
+
+export type WorkflowResultRecord = {
+  type: "workflow-result";
+  returnCode: number;
+  content: string;
+  timestamp: number | null;
+};
+
+export type ThreadRecord = ThreadStartRecord | RoleRecord | WorkflowResultRecord;
+
+// ── Gateway endpoints ───────────────────────────────────────────────
+
+export function listAgents(): Promise<AgentEndpoint[]> {
+  const url = GATEWAY_URL || "";
+  return fetchJson(url, "/endpoints");
 }
 
-export function listThreads(): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson("/threads");
+// ── Agent-scoped endpoints ──────────────────────────────────────────
+
+export function listWorkflows(agent: string): Promise<{ workflows: WorkflowSummary[] }> {
+  return fetchJson(agentBase(agent), "/workflows");
 }
 
-export function listRunningThreads(): Promise<{ threads: ThreadSummary[] }> {
-  return fetchJson("/threads/running");
+export function listThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(agentBase(agent), "/threads");
 }
 
-export function getThread(id: string): Promise<{ records: ThreadRecord[] }> {
-  return fetchJson(`/threads/${id}`);
+export function listRunningThreads(agent: string): Promise<{ threads: ThreadSummary[] }> {
+  return fetchJson(agentBase(agent), "/threads/running");
+}
+
+export function getThread(agent: string, id: string): Promise<{ records: ThreadRecord[] }> {
+  return fetchJson(agentBase(agent), `/threads/${id}`);
 }
 
 export function runThread(
+  agent: string,
   workflow: string,
   prompt: string,
   maxRounds: number = 10,
 ): Promise<{ threadId: string }> {
-  return postJson("/threads", { workflow, prompt, maxRounds });
+  return postJson(agentBase(agent), "/threads", { workflow, prompt, maxRounds });
 }
 
-export function killThread(threadId: string): Promise<{ ok: boolean }> {
-  return postJson(`/threads/${threadId}/kill`, {});
+export function killThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/kill`, {});
 }
 
-export function pauseThread(threadId: string): Promise<{ ok: boolean }> {
-  return postJson(`/threads/${threadId}/pause`, {});
+export function pauseThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/pause`, {});
 }
 
-export function resumeThread(threadId: string): Promise<{ ok: boolean }> {
-  return postJson(`/threads/${threadId}/resume`, {});
+export function resumeThread(agent: string, threadId: string): Promise<{ ok: boolean }> {
+  return postJson(agentBase(agent), `/threads/${threadId}/resume`, {});
 }
 
-export function getHealth(): Promise<{ ok: boolean }> {
-  return fetchJson("/healthz");
+export function getAgentHealth(agent: string): Promise<{ ok: boolean }> {
+  return fetchJson(agentBase(agent), "/healthz");
 }

packages/workflow-dashboard/src/app.tsx

@@ -1,4 +1,6 @@
 import { useState } from "react";
+import { hasApiKey, clearApiKey } from "./api.ts";
+import { LoginPage } from "./components/login.tsx";
 import { RunDialog } from "./components/run-dialog.tsx";
 import { Sidebar } from "./components/sidebar.tsx";
 import { StatusBar } from "./components/status-bar.tsx";
@@ -8,24 +10,48 @@ import { WorkflowList } from "./components/workflow-list.tsx";
 import { useHashRoute } from "./use-hash-route.ts";
 
 export function App() {
-  const { view, threadId, setView, setThreadId } = useHashRoute();
+  const [authed, setAuthed] = useState(hasApiKey());
+  const { view, agent, threadId, setView, setAgent, setThreadId } = useHashRoute();
   const [showRun, setShowRun] = useState(false);
 
+  if (!authed) {
+    return <LoginPage onLogin={() => setAuthed(true)} />;
+  }
+
   return (
     <div className="flex h-screen">
-      <Sidebar view={view} onViewChange={setView} />
+      <Sidebar
+        view={view}
+        agent={agent}
+        onViewChange={setView}
+        onAgentChange={setAgent}
+        onLogout={() => {
+          clearApiKey();
+          setAuthed(false);
+        }}
+      />
       <main className="flex-1 overflow-hidden flex flex-col">
-        <StatusBar onRun={() => setShowRun(true)} />
+        <StatusBar agent={agent} onRun={() => setShowRun(true)} />
         <div className="flex-1 overflow-auto p-6">
-          {view === "threads" && threadId === null && <ThreadList onSelect={setThreadId} />}
-          {view === "threads" && threadId !== null && (
-            <ThreadDetail threadId={threadId} onBack={() => setThreadId(null)} />
+          {!agent && (
+            <div className="flex items-center justify-center h-full">
+              <p style={{ color: "var(--color-text-muted)" }}>
+                Select an agent from the sidebar to get started.
+              </p>
+            </div>
           )}
-          {view === "workflows" && <WorkflowList />}
+          {agent && view === "threads" && threadId === null && (
+            <ThreadList agent={agent} onSelect={setThreadId} />
+          )}
+          {agent && view === "threads" && threadId !== null && (
+            <ThreadDetail agent={agent} threadId={threadId} onBack={() => setThreadId(null)} />
+          )}
+          {agent && view === "workflows" && <WorkflowList agent={agent} />}
         </div>
       </main>
-      {showRun && (
+      {showRun && agent && (
         <RunDialog
+          agent={agent}
           onClose={() => setShowRun(false)}
           onCreated={(id) => {
             setShowRun(false);

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

@@ -0,0 +1,96 @@
+import { useState } from "react";
+import { setApiKey } from "../api.ts";
+
+type Props = {
+  onLogin: () => void;
+};
+
+export function LoginPage({ onLogin }: Props) {
+  const [key, setKey] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    if (!key.trim()) return;
+
+    setLoading(true);
+    setError(null);
+
+    // Test the key by hitting the endpoints list
+    const gatewayUrl = import.meta.env.VITE_GATEWAY_URL || "";
+    try {
+      const res = await fetch(`${gatewayUrl}/endpoints`, {
+        headers: { Authorization: `Bearer ${key.trim()}` },
+      });
+      if (res.status === 401) {
+        setError("Invalid API key");
+        setLoading(false);
+        return;
+      }
+      if (!res.ok) {
+        setError(`Server error: ${res.status}`);
+        setLoading(false);
+        return;
+      }
+    } catch (err) {
+      setError(`Connection failed: ${err instanceof Error ? err.message : String(err)}`);
+      setLoading(false);
+      return;
+    }
+
+    setApiKey(key.trim());
+    onLogin();
+  }
+
+  return (
+    <div
+      className="min-h-screen flex items-center justify-center"
+      style={{ background: "var(--color-bg)" }}
+    >
+      <div
+        className="p-8 rounded-lg border w-full max-w-sm"
+        style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+      >
+        <h1 className="text-xl font-bold mb-1" style={{ color: "var(--color-accent)" }}>
+          ⚙ Workflow Dashboard
+        </h1>
+        <p className="text-sm mb-6" style={{ color: "var(--color-text-muted)" }}>
+          Enter your API key to continue
+        </p>
+        <form onSubmit={handleSubmit}>
+          <input
+            type="password"
+            value={key}
+            onChange={(e) => setKey(e.target.value)}
+            placeholder="API Key"
+            className="w-full px-3 py-2 rounded border text-sm mb-3 outline-none"
+            style={{
+              background: "var(--color-bg)",
+              borderColor: "var(--color-border)",
+              color: "var(--color-text)",
+            }}
+            autoFocus
+          />
+          {error && (
+            <p className="text-xs mb-3" style={{ color: "var(--color-error)" }}>
+              {error}
+            </p>
+          )}
+          <button
+            type="submit"
+            disabled={loading || !key.trim()}
+            className="w-full px-3 py-2 rounded text-sm font-medium"
+            style={{
+              background: "var(--color-accent)",
+              color: "var(--color-bg)",
+              opacity: loading || !key.trim() ? 0.5 : 1,
+            }}
+          >
+            {loading ? "Verifying..." : "Login"}
+          </button>
+        </form>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,127 @@
+import ReactMarkdown from "react-markdown";
+import { useEffect, useState } from "react";
+import {
+  createHighlighter,
+  type HighlighterGeneric,
+  type BundledLanguage,
+  type BundledTheme,
+} from "shiki";
+
+let highlighterPromise: Promise<HighlighterGeneric<BundledLanguage, BundledTheme>> | null = null;
+
+const LANGS: BundledLanguage[] = [
+  "typescript",
+  "javascript",
+  "json",
+  "yaml",
+  "bash",
+  "python",
+  "markdown",
+];
+
+function getHighlighter(): Promise<HighlighterGeneric<BundledLanguage, BundledTheme>> {
+  if (highlighterPromise === null) {
+    highlighterPromise = createHighlighter({
+      themes: ["github-dark"],
+      langs: LANGS,
+    });
+  }
+  return highlighterPromise;
+}
+
+function CodeBlock({ className, children }: { className?: string; children?: React.ReactNode }) {
+  const [html, setHtml] = useState<string | null>(null);
+  const code = String(children).replace(/\n$/, "");
+  const lang = className?.replace("language-", "") ?? "text";
+
+  useEffect(() => {
+    let cancelled = false;
+    getHighlighter().then((hl) => {
+      if (cancelled) return;
+      try {
+        const result = hl.codeToHtml(code, { lang, theme: "github-dark" });
+        setHtml(result);
+      } catch {
+        setHtml(null);
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [code, lang]);
+
+  if (html !== null) {
+    return (
+      <div
+        className="rounded overflow-x-auto text-xs my-2"
+        // biome-ignore lint/security/noDangerouslySetInnerHtml: shiki output is safe
+        dangerouslySetInnerHTML={{ __html: html }}
+      />
+    );
+  }
+
+  return (
+    <pre
+      className="rounded overflow-x-auto text-xs my-2 p-3"
+      style={{ background: "var(--color-bg)" }}
+    >
+      <code>{code}</code>
+    </pre>
+  );
+}
+
+export function Markdown({ content }: { content: string }) {
+  return (
+    <div className="prose prose-invert prose-sm max-w-none">
+      <ReactMarkdown
+        components={{
+          code({ className, children, ...props }) {
+            const isInline = !className;
+            if (isInline) {
+              return (
+                <code
+                  className="text-xs px-1 py-0.5 rounded"
+                  style={{ background: "var(--color-border)", color: "var(--color-accent)" }}
+                  {...props}
+                >
+                  {children}
+                </code>
+              );
+            }
+            return <CodeBlock className={className}>{children}</CodeBlock>;
+          },
+          p({ children }) {
+            return <p className="my-1.5 leading-relaxed">{children}</p>;
+          },
+          ul({ children }) {
+            return <ul className="list-disc pl-4 my-1.5">{children}</ul>;
+          },
+          ol({ children }) {
+            return <ol className="list-decimal pl-4 my-1.5">{children}</ol>;
+          },
+          h1({ children }) {
+            return <h1 className="text-lg font-bold mt-3 mb-1">{children}</h1>;
+          },
+          h2({ children }) {
+            return <h2 className="text-base font-bold mt-2 mb-1">{children}</h2>;
+          },
+          h3({ children }) {
+            return <h3 className="text-sm font-bold mt-2 mb-1">{children}</h3>;
+          },
+          blockquote({ children }) {
+            return (
+              <blockquote
+                className="border-l-2 pl-3 my-2 text-sm"
+                style={{ borderColor: "var(--color-accent)", color: "var(--color-text-muted)" }}
+              >
+                {children}
+              </blockquote>
+            );
+          },
+        }}
+      >
+        {content}
+      </ReactMarkdown>
+    </div>
+  );
+}

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

@@ -0,0 +1,126 @@
+import type { ThreadStartRecord, RoleRecord, WorkflowResultRecord, ThreadRecord } from "../api.ts";
+import { Markdown } from "./markdown.tsx";
+
+const ROLE_COLORS: Record<string, string> = {
+  preparer: "#8b5cf6",
+  agent: "#3b82f6",
+  extractor: "#f59e0b",
+};
+
+function roleColor(role: string): string {
+  return ROLE_COLORS[role] ?? "var(--color-accent)";
+}
+
+function formatTime(ts: number | null): string | null {
+  if (ts === null) return null;
+  return new Date(ts).toLocaleTimeString();
+}
+
+function StartCard({ record }: { record: ThreadStartRecord }) {
+  return (
+    <div
+      className="p-4 rounded-lg border"
+      style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+    >
+      <div className="flex items-center gap-2 mb-2">
+        <span className="text-lg">🚀</span>
+        <span className="font-semibold" style={{ color: "var(--color-accent)" }}>
+          {record.workflow}
+        </span>
+        <span
+          className="text-xs px-2 py-0.5 rounded"
+          style={{
+            background: record.status === "active" ? "var(--color-success)" : "var(--color-border)",
+            color: record.status === "active" ? "var(--color-bg)" : "var(--color-text-muted)",
+          }}
+        >
+          {record.status}
+        </span>
+      </div>
+      {record.prompt !== null && (
+        <div
+          className="mt-2 p-3 rounded text-sm border-l-2"
+          style={{
+            background: "var(--color-bg)",
+            borderColor: "var(--color-accent)",
+            color: "var(--color-text)",
+          }}
+        >
+          <div className="text-xs mb-1" style={{ color: "var(--color-text-muted)" }}>
+            Prompt
+          </div>
+          <Markdown content={record.prompt} />
+        </div>
+      )}
+    </div>
+  );
+}
+
+function RoleMessage({ record }: { record: RoleRecord }) {
+  const color = roleColor(record.role);
+  return (
+    <div
+      className="p-3 rounded-lg border text-sm"
+      style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
+    >
+      <div className="flex items-center gap-2 mb-2">
+        <span
+          className="text-xs px-2 py-0.5 rounded font-mono font-medium"
+          style={{ background: color, color: "#fff" }}
+        >
+          {record.role}
+        </span>
+        {formatTime(record.timestamp) !== null && (
+          <span className="text-xs ml-auto" style={{ color: "var(--color-text-muted)" }}>
+            {formatTime(record.timestamp)}
+          </span>
+        )}
+      </div>
+      <Markdown content={record.content} />
+    </div>
+  );
+}
+
+function ResultCard({ record }: { record: WorkflowResultRecord }) {
+  const success = record.returnCode === 0;
+  return (
+    <div
+      className="p-4 rounded-lg border"
+      style={{
+        background: "var(--color-surface)",
+        borderColor: success ? "var(--color-success)" : "var(--color-error)",
+      }}
+    >
+      <div className="flex items-center gap-2 mb-2">
+        <span className="text-lg">{success ? "✅" : "❌"}</span>
+        <span className="font-semibold text-sm">{success ? "Completed" : "Failed"}</span>
+        <span
+          className="text-xs px-2 py-0.5 rounded font-mono"
+          style={{
+            background: success ? "var(--color-success)" : "var(--color-error)",
+            color: "#fff",
+          }}
+        >
+          exit {record.returnCode}
+        </span>
+        {formatTime(record.timestamp) !== null && (
+          <span className="text-xs ml-auto" style={{ color: "var(--color-text-muted)" }}>
+            {formatTime(record.timestamp)}
+          </span>
+        )}
+      </div>
+      <Markdown content={record.content} />
+    </div>
+  );
+}
+
+export function RecordCard({ record }: { record: ThreadRecord }) {
+  switch (record.type) {
+    case "thread-start":
+      return <StartCard record={record} />;
+    case "role":
+      return <RoleMessage record={record} />;
+    case "workflow-result":
+      return <ResultCard record={record} />;
+  }
+}

packages/workflow-dashboard/src/components/run-dialog.tsx

@@ -3,12 +3,13 @@ import { listWorkflows, runThread } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
 type Props = {
+  agent: string;
   onClose: () => void;
   onCreated: (threadId: string) => void;
 };
 
-export function RunDialog({ onClose, onCreated }: Props) {
-  const workflows = useFetch(() => listWorkflows(), []);
+export function RunDialog({ agent, onClose, onCreated }: Props) {
+  const workflows = useFetch(() => listWorkflows(agent), [agent]);
   const [workflow, setWorkflow] = useState("");
   const [prompt, setPrompt] = useState("");
   const [maxRounds, setMaxRounds] = useState(10);
@@ -21,7 +22,7 @@ export function RunDialog({ onClose, onCreated }: Props) {
     setSubmitting(true);
     setError(null);
     try {
-      const result = await runThread(workflow, prompt, maxRounds);
+      const result = await runThread(agent, workflow, prompt, maxRounds);
       onCreated(result.threadId);
     } catch (err) {
       setError(err instanceof Error ? err.message : String(err));
@@ -38,7 +39,7 @@ export function RunDialog({ onClose, onCreated }: Props) {
         className="w-full max-w-lg p-6 rounded-lg border"
         style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
       >
-        <h3 className="text-lg font-semibold mb-4">Run Thread</h3>
+        <h3 className="text-lg font-semibold mb-4">Run Thread on {agent}</h3>
         <form onSubmit={handleSubmit} className="space-y-4">
           <div>
             <label

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

@@ -1,10 +1,29 @@
+import { useEffect } from "react";
+import type { AgentEndpoint } from "../api.ts";
+import { listAgents } from "../api.ts";
+import { useFetch } from "../hooks.ts";
+
 type Props = {
   view: "threads" | "workflows";
+  agent: string | null;
   onViewChange: (v: "threads" | "workflows") => void;
+  onAgentChange: (a: string | null) => void;
+  onLogout: () => void;
 };
 
-export function Sidebar({ view, onViewChange }: Props) {
-  const items = [
+export function Sidebar({ view, agent, onViewChange, onAgentChange, onLogout }: Props) {
+  const { status, data } = useFetch(() => listAgents(), []);
+
+  const agents: AgentEndpoint[] = status === "ok" ? data : [];
+
+  // Auto-select first agent when none is selected
+  useEffect(() => {
+    if (agent === null && agents.length > 0) {
+      onAgentChange(agents[0].name);
+    }
+  }, [agent, agents, onAgentChange]);
+
+  const viewItems = [
     { key: "threads" as const, label: "Threads", icon: "⚡" },
     { key: "workflows" as const, label: "Workflows", icon: "📦" },
   ];
@@ -22,8 +41,45 @@ export function Sidebar({ view, onViewChange }: Props) {
           Dashboard
         </p>
       </div>
+
+      {/* Agent selector */}
+      <div className="px-4 py-3 border-b" style={{ borderColor: "var(--color-border)" }}>
+        <label
+          className="block text-xs font-medium mb-1"
+          style={{ color: "var(--color-text-muted)" }}
+          htmlFor="agent-select"
+        >
+          Agent
+        </label>
+        <select
+          id="agent-select"
+          className="w-full rounded px-2 py-1.5 text-xs"
+          style={{
+            background: "var(--color-bg)",
+            color: "var(--color-text)",
+            border: "1px solid var(--color-border)",
+          }}
+          value={agent ?? ""}
+          onChange={(e) => onAgentChange(e.target.value || null)}
+          disabled={status === "loading"}
+        >
+          {status === "loading" ? (
+            <option value="">Loading…</option>
+          ) : agents.length === 0 ? (
+            <option value="">No agents online</option>
+          ) : (
+            agents.map((a) => (
+              <option key={a.name} value={a.name}>
+                {a.status === "online" ? "🟢" : "🔴"} {a.name}
+              </option>
+            ))
+          )}
+        </select>
+      </div>
+
+      {/* View navigation */}
       <nav className="flex-1 p-2 space-y-1">
-        {items.map((item) => (
+        {viewItems.map((item) => (
           <button
             type="button"
             key={item.key}
@@ -38,6 +94,17 @@ export function Sidebar({ view, onViewChange }: Props) {
           </button>
         ))}
       </nav>
+
+      <div className="p-2 border-t" style={{ borderColor: "var(--color-border)" }}>
+        <button
+          type="button"
+          onClick={onLogout}
+          className="w-full text-left px-3 py-2 rounded text-xs transition-colors"
+          style={{ color: "var(--color-text-muted)" }}
+        >
+          🚪 Logout
+        </button>
+      </div>
     </aside>
   );
 }

packages/workflow-dashboard/src/components/status-bar.tsx

@@ -1,9 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { getHealth } from "../api.ts";
+import { getAgentHealth } from "../api.ts";
 
 type HealthStatus = "connected" | "disconnected" | "reconnecting";
 
 type Props = {
+  agent: string | null;
   onRun: () => void;
 };
 
@@ -17,13 +18,17 @@ function statusLabel(status: HealthStatus): { text: string; color: string } {
   return { text: "● Offline", color: "var(--color-error)" };
 }
 
-export function StatusBar({ onRun }: Props) {
+export function StatusBar({ agent, onRun }: Props) {
   const [status, setStatus] = useState<HealthStatus>("disconnected");
   const wasConnectedRef = useRef(false);
 
   const checkHealth = useCallback(async () => {
+    if (!agent) {
+      setStatus("disconnected");
+      return;
+    }
     try {
-      await getHealth();
+      await getAgentHealth(agent);
       wasConnectedRef.current = true;
       setStatus("connected");
     } catch {
@@ -33,9 +38,11 @@ export function StatusBar({ onRun }: Props) {
         setStatus("disconnected");
       }
     }
-  }, []);
+  }, [agent]);
 
   useEffect(() => {
+    wasConnectedRef.current = false;
+    setStatus("disconnected");
     checkHealth();
     const interval = setInterval(checkHealth, 10_000);
     return () => clearInterval(interval);
@@ -49,12 +56,19 @@ export function StatusBar({ onRun }: Props) {
       style={{ borderColor: "var(--color-border)", background: "var(--color-surface)" }}
     >
       <div className="flex items-center gap-4">
-        <span style={{ color: "var(--color-text-muted)" }}>Local API: 127.0.0.1:7860</span>
+        <span style={{ color: "var(--color-text-muted)" }}>
+          {agent ? `Agent: ${agent}` : "No agent selected"}
+        </span>
         <button
           type="button"
           onClick={onRun}
+          disabled={!agent}
           className="px-3 py-1 rounded text-xs font-medium"
-          style={{ background: "var(--color-accent)", color: "#fff" }}
+          style={{
+            background: agent ? "var(--color-accent)" : "var(--color-border)",
+            color: "#fff",
+            opacity: agent ? 1 : 0.5,
+          }}
         >
           ▶ Run Thread
         </button>

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

@@ -2,15 +2,17 @@ import { useEffect, useRef, useState } from "react";
 import { getThread, killThread, pauseThread, resumeThread } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 import { useSSE } from "../use-sse.ts";
+import { RecordCard } from "./record-card.tsx";
 
 type Props = {
+  agent: string;
   threadId: string;
   onBack: () => void;
 };
 
-export function ThreadDetail({ threadId, onBack }: Props) {
-  const sse = useSSE(threadId);
-  const { status, data, error } = useFetch(() => getThread(threadId), [threadId]);
+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);
 
@@ -30,7 +32,7 @@ export function ThreadDetail({ threadId, onBack }: Props) {
     setActionStatus(`${action}ing...`);
     try {
       const fn = action === "kill" ? killThread : action === "pause" ? pauseThread : resumeThread;
-      await fn(threadId);
+      await fn(agent, threadId);
       setActionStatus(`${action} sent ✓`);
     } catch (e) {
       setActionStatus(`${action} failed: ${e instanceof Error ? e.message : String(e)}`);
@@ -78,7 +80,7 @@ export function ThreadDetail({ threadId, onBack }: Props) {
 
       <h2 className="text-xl font-semibold mb-2 font-mono flex items-center gap-2 flex-wrap">
         <span>{threadId}</span>
-        {sse.connected && (
+        {sse.connected && !sse.completed && (
           <span
             className="text-xs font-medium px-2 py-0.5 rounded"
             style={{ background: "var(--color-success)", color: "var(--color-bg)" }}
@@ -101,39 +103,8 @@ export function ThreadDetail({ threadId, onBack }: Props) {
       )}
       {(status === "ok" || liveActive || records.length > 0) && (
         <div className="space-y-3">
-          {records.map((r) => (
-            <div
-              key={`${threadId}-${r.type}-${String(r.timestamp)}-${r.role ?? ""}-${r.content ?? ""}`}
-              className="p-3 rounded border text-sm"
-              style={{ background: "var(--color-surface)", borderColor: "var(--color-border)" }}
-            >
-              <div className="flex items-center gap-2 mb-1">
-                <span
-                  className="text-xs px-1.5 py-0.5 rounded font-mono"
-                  style={{ background: "var(--color-border)", color: "var(--color-accent)" }}
-                >
-                  {r.type}
-                </span>
-                {r.role && (
-                  <span className="text-xs" style={{ color: "var(--color-text-muted)" }}>
-                    {r.role}
-                  </span>
-                )}
-                {r.timestamp !== null && (
-                  <span className="text-xs ml-auto" style={{ color: "var(--color-text-muted)" }}>
-                    {new Date(r.timestamp).toLocaleTimeString()}
-                  </span>
-                )}
-              </div>
-              {r.content && (
-                <pre
-                  className="whitespace-pre-wrap text-xs mt-1"
-                  style={{ color: "var(--color-text)" }}
-                >
-                  {typeof r.content === "string" ? r.content : JSON.stringify(r.content, null, 2)}
-                </pre>
-              )}
-            </div>
+          {records.map((r, i) => (
+            <RecordCard key={`${threadId}-${i}`} record={r} />
           ))}
           <div ref={recordsEndRef} aria-hidden />
         </div>

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

@@ -2,11 +2,12 @@ import { listThreads } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
 type Props = {
+  agent: string;
   onSelect: (id: string) => void;
 };
 
-export function ThreadList({ onSelect }: Props) {
-  const { status, data, error } = useFetch(() => listThreads(), []);
+export function ThreadList({ agent, onSelect }: Props) {
+  const { status, data, error } = useFetch(() => listThreads(agent), [agent]);
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading threads...</p>;

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

@@ -1,8 +1,12 @@
 import { listWorkflows } from "../api.ts";
 import { useFetch } from "../hooks.ts";
 
-export function WorkflowList() {
-  const { status, data, error } = useFetch(() => listWorkflows(), []);
+type Props = {
+  agent: string;
+};
+
+export function WorkflowList({ agent }: Props) {
+  const { status, data, error } = useFetch(() => listWorkflows(agent), [agent]);
 
   if (status === "loading")
     return <p style={{ color: "var(--color-text-muted)" }}>Loading workflows...</p>;

packages/workflow-dashboard/src/use-hash-route.ts

@@ -4,37 +4,50 @@ type View = "threads" | "workflows";
 
 type HashRoute = {
   view: View;
+  agent: string | null;
   threadId: string | null;
 };
 
 function parseHash(hash: string): HashRoute {
   const raw = hash.replace(/^#\/?/, "");
-  if (raw.startsWith("threads/")) {
-    const id = raw.slice("threads/".length);
-    if (id.length > 0) {
-      return { view: "threads", threadId: id };
-    }
+  // Format: #agent/threads/id or #agent/workflows or #threads or #workflows
+  const parts = raw.split("/");
+
+  // Check if first part is a known view
+  if (parts[0] === "threads" || parts[0] === "workflows") {
+    return {
+      view: parts[0] as View,
+      agent: null,
+      threadId: parts[0] === "threads" && parts.length > 1 ? parts.slice(1).join("/") : null,
+    };
   }
-  if (raw === "workflows") {
-    return { view: "workflows", threadId: null };
-  }
-  return { view: "threads", threadId: null };
+
+  // First part is agent name
+  const agent = parts[0] || null;
+  const viewPart = parts[1] ?? "threads";
+  const view: View = viewPart === "workflows" ? "workflows" : "threads";
+  const threadId = view === "threads" && parts.length > 2 ? parts.slice(2).join("/") : null;
+
+  return { view, agent, threadId };
 }
 
 function buildHash(route: HashRoute): string {
+  const prefix = route.agent ? `${route.agent}/` : "";
   if (route.view === "workflows") {
-    return "#workflows";
+    return `#${prefix}workflows`;
   }
   if (route.threadId !== null) {
-    return `#threads/${route.threadId}`;
+    return `#${prefix}threads/${route.threadId}`;
   }
-  return "#threads";
+  return `#${prefix}threads`;
 }
 
 export function useHashRoute(): {
   view: View;
+  agent: string | null;
   threadId: string | null;
   setView: (v: View) => void;
+  setAgent: (a: string | null) => void;
   setThreadId: (id: string | null) => void;
 } {
   const [route, setRoute] = useState<HashRoute>(() => parseHash(window.location.hash));
@@ -53,12 +66,27 @@ export function useHashRoute(): {
     setRoute(next);
   }, []);
 
-  const setView = useCallback((v: View) => navigate({ view: v, threadId: null }), [navigate]);
-
-  const setThreadId = useCallback(
-    (id: string | null) => navigate({ view: "threads", threadId: id }),
-    [navigate],
+  const setView = useCallback(
+    (v: View) => navigate({ view: v, agent: route.agent, threadId: null }),
+    [navigate, route.agent],
   );
 
-  return { view: route.view, threadId: route.threadId, setView, setThreadId };
+  const setAgent = useCallback(
+    (a: string | null) => navigate({ view: route.view, agent: a, threadId: null }),
+    [navigate, route.view],
+  );
+
+  const setThreadId = useCallback(
+    (id: string | null) => navigate({ view: "threads", agent: route.agent, threadId: id }),
+    [navigate, route.agent],
+  );
+
+  return {
+    view: route.view,
+    agent: route.agent,
+    threadId: route.threadId,
+    setView,
+    setAgent,
+    setThreadId,
+  };
 }

packages/workflow-dashboard/src/use-sse.ts

@@ -8,6 +8,7 @@ import {
 } from "react";
 
 import type { ThreadRecord } from "./api.ts";
+import { getApiKey } from "./api.ts";
 
 export type UseSSEReturn = {
   records: ThreadRecord[];
@@ -56,7 +57,17 @@ function handleRecordEvent(ev: Event, ctx: RecordEventContext): void {
   ctx.cleanupEs();
 }
 
-export function useSSE(threadId: string | null): UseSSEReturn {
+function sseUrl(agent: string, threadId: string): string {
+  const gatewayUrl = import.meta.env.VITE_GATEWAY_URL || "";
+  const key = getApiKey();
+  const keyParam = key ? `?key=${encodeURIComponent(key)}` : "";
+  if (gatewayUrl) {
+    return `${gatewayUrl}/api/${agent}/threads/${encodeURIComponent(threadId)}/live${keyParam}`;
+  }
+  return `/api/threads/${encodeURIComponent(threadId)}/live`;
+}
+
+export function useSSE(agent: string | null, threadId: string | null): UseSSEReturn {
   const [records, setRecords] = useState<ThreadRecord[]>([]);
   const [connected, setConnected] = useState(false);
   const [completed, setCompleted] = useState(false);
@@ -65,7 +76,7 @@ export function useSSE(threadId: string | null): UseSSEReturn {
   const reconnectAttemptsRef = useRef(0);
 
   useEffect(() => {
-    if (threadId === null) {
+    if (threadId === null || agent === null) {
       completedRef.current = false;
       reconnectAttemptsRef.current = 0;
       setRecords([]);
@@ -75,6 +86,7 @@ export function useSSE(threadId: string | null): UseSSEReturn {
     }
 
     const tid = threadId;
+    const agentName = agent;
 
     completedRef.current = false;
     reconnectAttemptsRef.current = 0;
@@ -113,7 +125,7 @@ export function useSSE(threadId: string | null): UseSSEReturn {
       }
 
       cleanupEs();
-      const url = `/api/threads/${encodeURIComponent(tid)}/live`;
+      const url = sseUrl(agentName, tid);
       es = new EventSource(url);
 
       es.onopen = () => {
@@ -136,6 +148,16 @@ export function useSSE(threadId: string | null): UseSSEReturn {
         }),
       );
 
+      es.addEventListener("done", () => {
+        if (cancelled) {
+          return;
+        }
+        completedRef.current = true;
+        setCompleted(true);
+        setConnected(false);
+        cleanupEs();
+      });
+
       es.onerror = () => {
         if (cancelled || completedRef.current) {
           return;
@@ -155,7 +177,7 @@ export function useSSE(threadId: string | null): UseSSEReturn {
       }
       cleanupEs();
     };
-  }, [threadId]);
+  }, [agent, threadId]);
 
   return { records, connected, completed };
 }

packages/workflow-execute/__tests__/extract-refs.test.ts

@@ -2,8 +2,7 @@ import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createCasStore } from "@uncaged/workflow-cas";
-import { type ExtractContext, START } from "@uncaged/workflow-runtime";
+import { createCasStore, putContentNodeWithRefs } from "@uncaged/workflow-cas";
 import * as z from "zod/v4";
 
 import { createExtract } from "../src/extract/extract-fn.js";
@@ -45,21 +44,9 @@ describe("createExtract — ExtractResult shape", () => {
       );
 
       const schema = z.object({ confidence: z.number() });
-      const ctx: ExtractContext = {
-        threadId: "01THREADTESTAAAAAAAAAAAAAA",
-        depth: 0,
-        start: {
-          role: START,
-          content: "task text",
-          meta: { maxRounds: 10 },
-          timestamp: 100,
-        },
-        steps: [],
-        currentRole: { name: "analyst", systemPrompt: "be precise" },
-        agentContent: "model says hello",
-      };
+      const contentHash = await putContentNodeWithRefs(cas, "model says hello", []);
 
-      const out = await extract(schema, "extract fields", ctx);
+      const out = await extract(schema, contentHash);
 
       expect(out.meta).toEqual({ confidence: 0.9 });
       expect(out.contentPayload).toBe("model says hello");

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

@@ -211,17 +211,17 @@ async function maybeSupervisorHaltsThread(params: {
     params.logger("K6PW9NYT", `supervisor skipped: ${sup.error}`);
     return null;
   }
-  if (sup.value !== "stop") {
+  if (sup.value !== "kill") {
     return null;
   }
-  params.logger("M4QX8VHN", `thread ${params.threadId} stopped by supervisor`);
+  params.logger("M4QX8VHN", `thread ${params.threadId} killed by supervisor`);
   return finalizeThread({
     cas: params.cas,
     bundleDir: params.bundleDir,
     threadId: params.threadId,
     startHash: params.startHash,
     chain: params.chain,
-    completion: { returnCode: 0, summary: "completed: supervisor stopped thread" },
+    completion: { returnCode: 1, summary: "killed: supervisor detected pathological behavior" },
   });
 }
 

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

@@ -12,12 +12,12 @@ const SUPERVISOR_MAX_REACT_ROUNDS = 4;
 
 const supervisorDecisionSchema = z
   .object({
-    decision: z.enum(["continue", "stop"]),
+    decision: z.enum(["continue", "kill"]),
   })
   .meta({
     title: "supervisor_decision",
     description:
-      'Workflow supervisor decision. "continue" when the thread is making progress; "stop" when done, looping, or stuck.',
+      'Workflow supervisor decision. "continue" when the thread is making progress or following its normal role sequence; "kill" only when the thread is stuck in an infinite loop, producing no meaningful progress, or has gone off the rails. Normal workflow completion is handled by the moderator — the supervisor should NOT kill a thread just because it looks done.',
   });
 
 type SupervisorThreadContext = Record<string, never>;
@@ -63,7 +63,7 @@ export async function runSupervisor(
       };
     },
     systemPromptForStructuredTool: (structuredToolName) =>
-      `You supervise a multi-step workflow. Decide whether the thread should keep running or halt. Reply with "continue" when the thread is making progress toward the task, or "stop" when it is finished, looping, or no longer making progress. Call the ${structuredToolName} tool with JSON arguments matching the schema, or reply with only a JSON object such as {"decision":"stop"}.`,
+      `You supervise a multi-step workflow. Your job is to detect pathological situations — NOT to decide when the workflow is "done" (that is the moderator's job). Reply with "continue" when the thread is making progress or following its normal role sequence. Reply with "kill" ONLY when the thread is stuck in an infinite loop, producing repetitive/meaningless output, or has clearly gone off the rails. Call the ${structuredToolName} tool with JSON arguments matching the schema, or reply with only a JSON object such as {"decision":"continue"}.`,
     toolHandler: async (call) => `Unknown tool: ${call.function.name}`,
   });
 

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

@@ -2,7 +2,7 @@ import type { CasStore } from "@uncaged/workflow-cas";
 import type { RoleOutput } from "@uncaged/workflow-runtime";
 import type { Result } from "@uncaged/workflow-util";
 
-export type SupervisorDecision = "continue" | "stop";
+export type SupervisorDecision = "continue" | "kill";
 
 export type ExecuteThreadIo = {
   threadId: string;

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

@@ -1,3 +1,4 @@
+import { unlinkSync } from "node:fs";
 import { mkdir, unlink, writeFile } from "node:fs/promises";
 import { createServer, type Socket } from "node:net";
 import { dirname, join } from "node:path";
@@ -382,6 +383,23 @@ async function main(): Promise<void> {
   let activeThreads = 0;
   let shutdownTimer: ReturnType<typeof setTimeout> | null = null;
 
+  function cleanupAllRunningMarkersSync(): void {
+    for (const threadId of threads.keys()) {
+      try {
+        unlinkSync(join(storageRoot, "logs", hash, `${threadId}.running`));
+      } catch {
+        // ignore missing file or other fs errors
+      }
+    }
+  }
+
+  for (const sig of ["SIGINT", "SIGTERM"] as const) {
+    process.on(sig, () => {
+      cleanupAllRunningMarkersSync();
+      process.exit(sig === "SIGINT" ? 130 : 143);
+    });
+  }
+
   const cas = createCasStore(getGlobalCasDir(storageRoot));
 
   const workerCtlPath = join(storageRoot, "workers", `${hash}.json`);
@@ -498,8 +516,8 @@ async function main(): Promise<void> {
       const message = e instanceof Error ? e.message : String(e);
       bootLog("Q3MN8YKW", `thread ${threadId} failed: ${message}`);
     } finally {
-      threads.delete(threadId);
       await unlink(runningPath).catch(() => {});
+      threads.delete(threadId);
       bumpDone();
       socket?.end();
     }

packages/workflow-execute/src/extract/extract-fn.ts

@@ -1,7 +1,6 @@
 import { type CasStore, getContentMerklePayload } from "@uncaged/workflow-cas";
 import { createLlmFn, createThreadReactor } from "@uncaged/workflow-reactor";
 import type {
-  ExtractContext,
   ExtractFn,
   ExtractResult,
   LlmProvider,
@@ -20,7 +19,7 @@ const CAS_GET_TOOL_DEFINITION = {
   function: {
     name: "cas_get",
     description:
-      "Read a Merkle DAG node from content-addressed storage by its hash. Returns YAML-formatted node with type, payload, and children fields.",
+      "Read a Merkle DAG node from content-addressed storage by its hash. Returns YAML-formatted node with type, payload, and refs or children fields (content nodes use refs).",
     parameters: {
       type: "object",
       properties: {
@@ -31,7 +30,7 @@ const CAS_GET_TOOL_DEFINITION = {
   },
 };
 
-export type ExtractThreadContext = {
+type ExtractThreadContext = {
   cas: CasStore;
 };
 
@@ -39,41 +38,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-/** Builds the user-side extraction prompt (thread + agent output + instruction). */
-export async function buildExtractUserContent(
-  ctx: ExtractContext,
-  prompt: string,
-  deps: ExtractDeps,
-): Promise<string> {
-  const lines: string[] = [];
-  lines.push(`## Role: ${ctx.currentRole.name}`);
-  lines.push(ctx.currentRole.systemPrompt);
-  lines.push("");
-  lines.push("## Task");
-  lines.push(ctx.start.content);
-  lines.push("");
-  if (ctx.steps.length > 0) {
-    lines.push("## Thread History");
-    for (const step of ctx.steps) {
-      const body = await getContentMerklePayload(deps.cas, step.contentHash);
-      if (body === null) {
-        throw new Error(`extract: missing CAS blob for step ${step.role}: ${step.contentHash}`);
-      }
-      lines.push(`### ${step.role}`);
-      lines.push(body);
-      lines.push(`Meta: ${JSON.stringify(step.meta)}`);
-      lines.push("");
-    }
-  }
-  lines.push("## Agent Output");
-  lines.push(ctx.agentContent);
-  lines.push("");
-  lines.push("## Extraction Instruction");
-  lines.push(prompt);
-
-  return lines.join("\n");
-}
-
 /**
  * Create an ExtractFn backed by an LLM provider.
  *
@@ -102,7 +66,7 @@ export function createExtract(provider: LlmProvider, deps: ExtractDeps): Extract
       };
     },
     systemPromptForStructuredTool: (structuredToolName) =>
-      `You extract structured metadata from the agent output below. Use cas_get to read Merkle DAG nodes from CAS (YAML: type, payload, children) when the agent output references hashes you must traverse. When you have the complete structured object, call the ${structuredToolName} tool with JSON arguments matching the schema. You may instead reply with only a JSON object (no prose) when no tools are needed.`,
+      `You extract structured metadata from content. The content is from a CAS node. Use cas_get to read referenced nodes if needed. When ready, call the ${structuredToolName} tool with JSON matching the schema. You may instead reply with only a JSON object (no prose) when no tools are needed.`,
     toolHandler: async (call, thread) => {
       if (call.function.name !== "cas_get") {
         return `Unexpected tool routed to handler: ${call.function.name}`;
@@ -124,10 +88,13 @@ export function createExtract(provider: LlmProvider, deps: ExtractDeps): Extract
 
   return async <T extends Record<string, unknown>>(
     schema: z.ZodType<T>,
-    prompt: string,
-    ctx: ExtractContext,
+    contentHash: string,
   ): Promise<ExtractResult<T>> => {
-    const text = await buildExtractUserContent(ctx, prompt, deps);
+    const payload = await getContentMerklePayload(deps.cas, contentHash);
+    if (payload === null) {
+      throw new Error(`extract: missing CAS content node for hash ${contentHash}`);
+    }
+    const text = `${payload}\n\nExtract structured metadata according to the schema.`;
     const result = await reactor({
       thread: { cas: deps.cas },
       input: text,
@@ -138,7 +105,7 @@ export function createExtract(provider: LlmProvider, deps: ExtractDeps): Extract
     }
     return {
       meta: result.value,
-      contentPayload: ctx.agentContent,
+      contentPayload: payload,
       refs: [],
     };
   };

packages/workflow-execute/src/extract/index.ts

@@ -1,8 +1,4 @@
-export {
-  buildExtractUserContent,
-  createExtract,
-  type ExtractThreadContext,
-} from "./extract-fn.js";
+export { createExtract } from "./extract-fn.js";
 export {
   extractFunctionToolFromZodSchema,
   llmErrorToCause,

packages/workflow-execute/src/index.ts

@@ -37,9 +37,7 @@ export { EMPTY_CHAIN_STATE } from "./engine/types.js";
 export { getWorkerHostScriptPath } from "./engine/worker-entry-path.js";
 export type { ExtractFn, LlmError, LlmExtractArgs } from "./extract/index.js";
 export {
-  buildExtractUserContent,
   createExtract,
-  type ExtractThreadContext,
   extractFunctionToolFromZodSchema,
   llmErrorToCause,
   llmExtract,

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

@@ -108,7 +108,7 @@ export function workflowAsAgent(
         io,
         logger,
       );
-      return result.rootHash;
+      return `Child workflow "${workflowName}" completed (returnCode=${result.returnCode}).\n\nSummary: ${result.summary}\n\nChild thread root hash: ${result.rootHash}`;
     } catch (e) {
       const message = e instanceof Error ? e.message : String(e);
       return `ERROR: ${message}`;

packages/workflow-gateway/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@uncaged/workflow-gateway",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "hono": "^4.7.11"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260425.1",
+    "wrangler": "^4.20.0"
+  }
+}

packages/workflow-gateway/src/index.ts

@@ -0,0 +1,156 @@
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+type Env = {
+  Bindings: {
+    ENDPOINTS: KVNamespace;
+    GATEWAY_SECRET: string;
+    DASHBOARD_API_KEY: string;
+  };
+};
+
+type EndpointRecord = {
+  name: string;
+  url: string;
+  agentToken: string;
+  registeredAt: number;
+  lastHeartbeat: number;
+};
+
+const TTL_SECONDS = 300; // 5 min — offline if no heartbeat
+
+const app = new Hono<Env>();
+
+app.use("*", cors());
+
+// ── Dashboard API key auth (skip healthz + register) ─────────────
+app.use("/endpoints", async (c, next) => {
+  if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
+  await next();
+});
+app.use("/api/*", async (c, next) => {
+  if (!checkDashboardAuth(c)) return c.json({ error: "unauthorized" }, 401);
+  await next();
+});
+
+function checkDashboardAuth(c: {
+  req: { header: (n: string) => string | undefined; query: (n: string) => string | undefined };
+  env: Env["Bindings"];
+}): boolean {
+  const bearer = c.req.header("Authorization")?.replace("Bearer ", "");
+  const query = c.req.query("key");
+  const key = bearer ?? query;
+  return key === c.env.DASHBOARD_API_KEY;
+}
+
+// ── Health ──────────────────────────────────────────────────────────
+app.get("/healthz", (c) => c.json({ ok: true }));
+
+// ── Register / heartbeat ────────────────────────────────────────────
+app.post("/register", async (c) => {
+  const body = await c.req.json<{
+    name?: string;
+    url?: string;
+    secret?: string;
+    agentToken?: string;
+  }>();
+  const { name, url, secret, agentToken } = body;
+
+  if (!name || !url) {
+    return c.json({ error: "name and url required" }, 400);
+  }
+  if (secret !== c.env.GATEWAY_SECRET) {
+    return c.json({ error: "unauthorized" }, 401);
+  }
+
+  const existing = await c.env.ENDPOINTS.get<EndpointRecord>(name, "json");
+  const now = Date.now();
+
+  const record: EndpointRecord = {
+    name,
+    url: url.replace(/\/+$/, ""), // strip trailing slash
+    agentToken: agentToken ?? existing?.agentToken ?? "",
+    registeredAt: existing?.registeredAt ?? now,
+    lastHeartbeat: now,
+  };
+
+  await c.env.ENDPOINTS.put(name, JSON.stringify(record), {
+    expirationTtl: TTL_SECONDS,
+  });
+
+  const status = existing ? 200 : 201;
+  return c.json({ registered: name }, status);
+});
+
+// ── Unregister ──────────────────────────────────────────────────────
+app.delete("/register/:name", async (c) => {
+  const auth = c.req.header("Authorization");
+  if (auth !== `Bearer ${c.env.GATEWAY_SECRET}`) {
+    return c.json({ error: "unauthorized" }, 401);
+  }
+
+  const name = c.req.param("name");
+  await c.env.ENDPOINTS.delete(name);
+  return c.json({ unregistered: name });
+});
+
+// ── List endpoints ──────────────────────────────────────────────────
+app.get("/endpoints", async (c) => {
+  const list = await c.env.ENDPOINTS.list();
+  const endpoints: Array<{ name: string; url: string; status: string; lastHeartbeat: number }> = [];
+
+  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;
+      endpoints.push({
+        name: record.name,
+        url: record.url,
+        status: age < TTL_SECONDS * 1000 ? "online" : "offline",
+        lastHeartbeat: record.lastHeartbeat,
+      });
+    }
+  }
+
+  return c.json(endpoints);
+});
+
+// ── API proxy: /api/:agent/* → agent's tunnel URL ───────────────────
+app.all("/api/:agent/*", async (c) => {
+  const agent = c.req.param("agent");
+  const record = await c.env.ENDPOINTS.get<EndpointRecord>(agent, "json");
+
+  if (!record) {
+    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/${agent}`, "");
+  const targetUrl = `${record.url}/api${pathAfterAgent}${url.search}`;
+
+  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);
+  }
+
+  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
+    return new Response(resp.body, {
+      status: resp.status,
+      headers: resp.headers,
+    });
+  } catch (err) {
+    return c.json({ error: "agent unreachable", detail: String(err) }, 502);
+  }
+});
+
+export default app;

packages/workflow-gateway/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

packages/workflow-gateway/wrangler.toml

@@ -0,0 +1,9 @@
+name = "workflow-gateway"
+main = "src/index.ts"
+compatibility_date = "2025-04-01"
+
+[[kv_namespaces]]
+binding = "ENDPOINTS"
+id = "88b118d1cfab4c049f9c1684848811a3"
+
+# GATEWAY_SECRET is set via `wrangler secret put`

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

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+
+import { tableToModerator } from "../src/moderator-table.js";
+import type { ModeratorContext, ModeratorTable, StartStep } from "../src/types.js";
+import { END, START } from "../src/types.js";
+
+type TestMeta = {
+  planner: { plan: string };
+  coder: { code: string };
+  reviewer: { approved: boolean };
+};
+
+function makeCtx(roles: (keyof TestMeta & string)[]): ModeratorContext<TestMeta> {
+  const steps = roles.map((role, i) => ({
+    role,
+    meta: {} as TestMeta[typeof role],
+    contentHash: `hash-${i}`,
+    refs: [],
+    timestamp: Date.now() + i,
+  }));
+  return {
+    threadId: "test-thread",
+    depth: 0,
+    start: {
+      role: START,
+      content: "test",
+      meta: { maxRounds: 10 },
+      timestamp: Date.now(),
+    } as StartStep,
+    steps,
+  };
+}
+
+describe("tableToModerator", () => {
+  test("START -> role A (FALLBACK) returns A on first call", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [{ condition: "FALLBACK", role: "planner" }],
+      planner: [],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    expect(mod(makeCtx([]))).toBe("planner");
+  });
+
+  test("condition true wins over FALLBACK", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [
+        {
+          condition: {
+            name: "always",
+            description: "always true",
+            check: () => true,
+          },
+          role: "planner",
+        },
+        { condition: "FALLBACK", role: "coder" },
+      ],
+      planner: [],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    expect(mod(makeCtx([]))).toBe("planner");
+  });
+
+  test("condition false falls through to FALLBACK", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [
+        {
+          condition: {
+            name: "never",
+            description: "always false",
+            check: () => false,
+          },
+          role: "planner",
+        },
+        { condition: "FALLBACK", role: "coder" },
+      ],
+      planner: [],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    expect(mod(makeCtx([]))).toBe("coder");
+  });
+
+  test("no matching transitions returns END", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [
+        {
+          condition: {
+            name: "never",
+            description: "always false",
+            check: () => false,
+          },
+          role: "planner",
+        },
+      ],
+      planner: [],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    expect(mod(makeCtx([]))).toBe(END);
+  });
+
+  test("multi-step: A -> FALLBACK END returns END after A", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [{ condition: "FALLBACK", role: "planner" }],
+      planner: [{ condition: "FALLBACK", role: END }],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    expect(mod(makeCtx(["planner"]))).toBe(END);
+  });
+
+  test("role not in table returns END", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [{ condition: "FALLBACK", role: "planner" }],
+      planner: [{ condition: "FALLBACK", role: "coder" }],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    // coder has empty transitions array
+    expect(mod(makeCtx(["planner", "coder"]))).toBe(END);
+  });
+
+  test("condition receives ctx", () => {
+    const table: ModeratorTable<TestMeta> = {
+      [START]: [
+        {
+          condition: {
+            name: "has-steps",
+            description: "checks ctx.steps",
+            check: (ctx) => ctx.steps.length > 0,
+          },
+          role: "coder",
+        },
+        { condition: "FALLBACK", role: "planner" },
+      ],
+      planner: [],
+      coder: [],
+      reviewer: [],
+    };
+    const mod = tableToModerator(table);
+    // No steps -> condition false -> FALLBACK -> planner
+    expect(mod(makeCtx([]))).toBe("planner");
+  });
+});

packages/workflow-protocol/src/index.ts

@@ -14,12 +14,15 @@ export type {
   AgentContext,
   AgentFn,
   CasStore,
-  ExtractContext,
   ExtractFn,
   ExtractResult,
+  FALLBACK,
   LlmProvider,
   Moderator,
+  ModeratorCondition,
   ModeratorContext,
+  ModeratorTable,
+  ModeratorTransition,
   ProviderConfig,
   ResolvedModel,
   Result,
@@ -47,3 +50,7 @@ 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/moderator-table.ts

@@ -0,0 +1,22 @@
+import type { Moderator, ModeratorTable, RoleMeta } from "./types.js";
+import { END, START } from "./types.js";
+
+export function tableToModerator<M extends RoleMeta>(table: ModeratorTable<M>): Moderator<M> {
+  return (ctx) => {
+    const lastStep = ctx.steps.length > 0 ? ctx.steps[ctx.steps.length - 1] : null;
+    const currentRole: string = lastStep ? lastStep.role : START;
+
+    const transitions = (table as Record<string, (typeof table)[string]>)[currentRole];
+    if (!transitions) {
+      return END;
+    }
+
+    for (const transition of transitions) {
+      if (transition.condition === "FALLBACK" || transition.condition.check(ctx)) {
+        return transition.role;
+      }
+    }
+
+    return END;
+  };
+}

packages/workflow-protocol/src/types.ts

@@ -76,10 +76,6 @@ export type AgentContext<M extends RoleMeta = RoleMeta> = ModeratorContext<M> &
   };
 };
 
-export type ExtractContext<M extends RoleMeta = RoleMeta> = AgentContext<M> & {
-  agentContent: string;
-};
-
 // ── Workflow Completion ────────────────────────────────────────────
 
 export type WorkflowCompletion = {
@@ -128,8 +124,7 @@ export type ExtractResult<T extends Record<string, unknown>> = {
 
 export type ExtractFn = <T extends Record<string, unknown>>(
   schema: z.ZodType<T>,
-  prompt: string,
-  ctx: ExtractContext,
+  contentHash: string,
 ) => Promise<ExtractResult<T>>;
 
 export type AgentFn = (ctx: AgentContext) => Promise<string>;
@@ -154,7 +149,6 @@ export type WorkflowFn = (
 export type RoleDefinition<Meta extends Record<string, unknown>> = {
   description: string;
   systemPrompt: string;
-  extractPrompt: string;
   schema: z.ZodType<Meta>;
   extractRefs: ((meta: Meta) => string[]) | null;
 };
@@ -169,6 +163,28 @@ export type WorkflowDefinition<M extends RoleMeta> = {
   moderator: Moderator<M>;
 };
 
+// ── Declarative Moderator Table ────────────────────────────────────
+
+export type ModeratorCondition<M extends RoleMeta> = {
+  name: string;
+  description: string;
+  check: (ctx: ModeratorContext<M>) => boolean;
+};
+
+export type FALLBACK = "FALLBACK";
+
+export type ModeratorTransition<M extends RoleMeta> = {
+  condition: ModeratorCondition<M> | FALLBACK;
+  role: (keyof M & string) | typeof END;
+};
+
+export type ModeratorTable<M extends RoleMeta> = Record<
+  (keyof M & string) | typeof START,
+  ModeratorTransition<M>[]
+>;
+
+// ── Advance Outcome ────────────────────────────────────────────────
+
 export type AdvanceOutcome<M extends RoleMeta> =
   | { kind: "complete"; completion: WorkflowCompletion }
   | { kind: "yield"; output: RoleOutput; step: RoleStep<M> };

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

@@ -40,7 +40,9 @@ function isAllowedImportSpecifier(spec: string): boolean {
   if (
     spec === "@uncaged/workflow" ||
     spec === "@uncaged/workflow-runtime" ||
-    spec === "@uncaged/workflow-cas"
+    spec === "@uncaged/workflow-protocol" ||
+    spec === "@uncaged/workflow-cas" ||
+    spec === "@uncaged/workflow-util"
   ) {
     return true;
   }

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

@@ -7,7 +7,6 @@ import {
   type AgentContext,
   type AgentFn,
   END,
-  type ExtractContext,
   type ModeratorContext,
   type RoleDefinition,
   type RoleMeta,
@@ -89,15 +88,11 @@ async function advanceOneRound<M extends RoleMeta>(
   const agent = agentForRole(binding, next);
   const raw = await agent(agentCtx as unknown as AgentContext);
 
-  const extractCtx: ExtractContext<M> = {
-    ...agentCtx,
-    agentContent: raw,
-  };
+  const agentContentHash = await putContentNodeWithRefs(runtime.cas, raw, []);
 
   const extracted = await runtime.extract(
     roleDef.schema as z.ZodType<Record<string, unknown>>,
-    roleDef.extractPrompt,
-    extractCtx as unknown as ExtractContext,
+    agentContentHash,
   );
 
   const refsFromMeta = resolveExtractedRefs(
@@ -106,11 +101,9 @@ async function advanceOneRound<M extends RoleMeta>(
   );
   const artifactRefs = mergeUniqueHashes(extracted.refs, refsFromMeta);
 
-  const contentHash = await putContentNodeWithRefs(
-    runtime.cas,
-    extracted.contentPayload,
-    artifactRefs,
-  );
+  const contentHash = artifactRefs.length === 0
+    ? agentContentHash
+    : await putContentNodeWithRefs(runtime.cas, extracted.contentPayload, artifactRefs);
   const refs = artifactRefs.includes(contentHash) ? artifactRefs : [...artifactRefs, contentHash];
 
   const step = {

packages/workflow-runtime/src/index.ts

@@ -6,12 +6,15 @@ export type {
   AgentContext,
   AgentFn,
   CasStore,
-  ExtractContext,
   ExtractFn,
   ExtractResult,
+  FALLBACK,
   LlmProvider,
   Moderator,
+  ModeratorCondition,
   ModeratorContext,
+  ModeratorTable,
+  ModeratorTransition,
   Result,
   RoleDefinition,
   RoleMeta,
@@ -28,4 +31,4 @@ export type {
   WorkflowRoleSchema,
   WorkflowRuntime,
 } from "./types.js";
-export { END, START } from "./types.js";
+export { END, START, tableToModerator } from "./types.js";

packages/workflow-runtime/src/types.ts

@@ -8,12 +8,17 @@ export type {
   AgentContext,
   AgentFn,
   CasStore,
-  ExtractContext,
   ExtractFn,
   ExtractResult,
+  FALLBACK,
   LlmProvider,
   Moderator,
+  ModeratorCondition,
   ModeratorContext,
+  ModeratorTable,
+  ModeratorTransition,
+  ProviderConfig,
+  ResolvedModel,
   Result,
   RoleDefinition,
   RoleMeta,
@@ -31,4 +36,4 @@ export type {
   WorkflowRuntime,
 } from "@uncaged/workflow-protocol";
 
-export { END, START } from "@uncaged/workflow-protocol";
+export { END, START, tableToModerator } from "@uncaged/workflow-protocol";

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

@@ -0,0 +1,44 @@
+/**
+ * develop bundle entry — 小橘 🍊
+ */
+import { createHermesAgent } from "@uncaged/workflow-agent-hermes";
+import { createExtract } from "@uncaged/workflow-execute";
+import { createWorkflow } from "@uncaged/workflow-runtime";
+import { buildDevelopDescriptor, developWorkflowDefinition } from "./src/index.js";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`missing required env var: ${name}`);
+  }
+  return value;
+}
+
+function optionalEnv(name: string): string | null {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    return null;
+  }
+  return value;
+}
+
+const provider = {
+  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 extract = createExtract(provider);
+
+const wf = createWorkflow(developWorkflowDefinition, { agent }, extract);
+
+export const descriptor = buildDevelopDescriptor();
+export const run = wf.run;

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

@@ -1,8 +1,15 @@
-import type { Moderator, ModeratorContext } from "@uncaged/workflow-runtime";
-import { END } from "@uncaged/workflow-runtime";
+import {
+  END,
+  type ModeratorCondition,
+  type ModeratorTable,
+  START,
+  tableToModerator,
+} from "@uncaged/workflow-runtime";
 
 import type { DevelopMeta } from "./roles.js";
 
+// ── Helpers ────────────────────────────────────────────────────────
+
 function coderFinishedAllPlannedPhases(
   phases: ReadonlyArray<{ hash: string }>,
   coderCompletedPhases: ReadonlyArray<string>,
@@ -22,68 +29,72 @@ function coderFinishedAllPlannedPhases(
   return false;
 }
 
-function nextAfterCoder(
-  ctx: ModeratorContext<DevelopMeta>,
-  maxRounds: number,
-): (keyof DevelopMeta & string) | typeof END {
-  const plannerStep = ctx.steps.find((s) => s.role === "planner");
-  if (plannerStep === undefined) {
-    return "reviewer";
-  }
-  const phases = plannerStep.meta.phases;
-  const coderCompletedPhases = ctx.steps
-    .filter((s) => s.role === "coder")
-    .map((s) => s.meta.completedPhase);
-  const allDone = coderFinishedAllPlannedPhases(phases, coderCompletedPhases);
-  if (allDone) {
-    return "reviewer";
-  }
-  if (ctx.steps.length < maxRounds - 1) {
-    return "coder";
-  }
-  return END;
-}
+// ── Conditions ─────────────────────────────────────────────────────
 
-export const developModerator: Moderator<DevelopMeta> = (ctx) => {
-  const maxRounds = ctx.start.meta.maxRounds;
-
-  if (ctx.steps.length === 0) {
-    return "planner";
-  }
-
-  const last = ctx.steps[ctx.steps.length - 1];
-
-  if (last.role === "planner") {
-    return "coder";
-  }
-
-  if (last.role === "coder") {
-    return nextAfterCoder(ctx, maxRounds);
-  }
-
-  if (last.role === "reviewer") {
-    if (last.meta.status === "approved") {
-      return "tester";
+const allPhasesComplete: ModeratorCondition<DevelopMeta> = {
+  name: "allPhasesComplete",
+  description: "All planned phases have been completed by the coder",
+  check: (ctx) => {
+    const plannerStep = ctx.steps.find((s) => s.role === "planner");
+    if (plannerStep === undefined) {
+      return true;
     }
-    if (ctx.steps.length < maxRounds - 1) {
-      return "coder";
+    const phases = plannerStep.meta.phases;
+    if (!Array.isArray(phases)) {
+      return true;
     }
-    return END;
-  }
-
-  if (last.role === "tester") {
-    if (last.meta.status === "passed") {
-      return "committer";
-    }
-    if (ctx.steps.length < maxRounds - 1) {
-      return "coder";
-    }
-    return END;
-  }
-
-  if (last.role === "committer") {
-    return END;
-  }
-
-  return END;
+    const coderCompletedPhases = ctx.steps
+      .filter((s) => s.role === "coder")
+      .map((s) => s.meta.completedPhase);
+    return coderFinishedAllPlannedPhases(phases, coderCompletedPhases);
+  },
 };
+
+const hasRoundsRemaining: ModeratorCondition<DevelopMeta> = {
+  name: "hasRoundsRemaining",
+  description: "There are rounds remaining before hitting maxRounds",
+  check: (ctx) => ctx.steps.length < ctx.start.meta.maxRounds - 1,
+};
+
+const reviewApproved: ModeratorCondition<DevelopMeta> = {
+  name: "reviewApproved",
+  description: "The last reviewer approved the changes",
+  check: (ctx) => {
+    const last = ctx.steps[ctx.steps.length - 1];
+    return last.role === "reviewer" && last.meta.status === "approved";
+  },
+};
+
+const testsPassed: ModeratorCondition<DevelopMeta> = {
+  name: "testsPassed",
+  description: "The last tester reported tests passed",
+  check: (ctx) => {
+    const last = ctx.steps[ctx.steps.length - 1];
+    return last.role === "tester" && last.meta.status === "passed";
+  },
+};
+
+// ── Transition Table ───────────────────────────────────────────────
+
+const table: ModeratorTable<DevelopMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "planner" }],
+  planner: [{ condition: "FALLBACK", role: "coder" }],
+  coder: [
+    { condition: allPhasesComplete, role: "reviewer" },
+    { condition: hasRoundsRemaining, role: "coder" },
+    { condition: "FALLBACK", role: END },
+  ],
+  reviewer: [
+    { condition: reviewApproved, role: "tester" },
+    { condition: hasRoundsRemaining, role: "coder" },
+    { condition: "FALLBACK", role: END },
+  ],
+  tester: [
+    { condition: testsPassed, role: "committer" },
+    { condition: hasRoundsRemaining, role: "coder" },
+    { condition: "FALLBACK", role: END },
+  ],
+  committer: [{ condition: "FALLBACK", role: END }],
+};
+
+export const developModerator = tableToModerator(table);

packages/workflow-template-develop/src/roles/coder.ts

@@ -2,7 +2,7 @@ import type { RoleDefinition } from "@uncaged/workflow-runtime";
 import * as z from "zod/v4";
 
 export const coderMetaSchema = z.object({
-  completedPhase: z.string(),
+  completedPhase: z.string().describe("The planner phase hash finished this round. If multiple phases were completed, use the last finished phase hash."),
   filesChanged: z.array(z.string()),
   summary: z.string(),
 });
@@ -27,8 +27,6 @@ export const coderRole: RoleDefinition<CoderMeta> = {
   description:
     "Implements the next incomplete planner phase and reports structured completion metadata.",
   systemPrompt: CODER_SYSTEM,
-  extractPrompt:
-    "Extract completedPhase: the planner phase hash finished this round (exact hash string from the plan). If multiple phases were finished in one round, use the last finished phase hash. Extract filesChanged and a summary of the work.",
   schema: coderMetaSchema,
   extractRefs: (meta) => [meta.completedPhase],
 };

packages/workflow-template-develop/src/roles/committer.ts

@@ -28,8 +28,6 @@ Do not attempt to fix failures yourself.`;
 export const committerRole: RoleDefinition<CommitterMeta> = {
   description: "Creates a branch and commits changes.",
   systemPrompt: COMMITTER_SYSTEM,
-  extractPrompt:
-    "Extract the commit result: committed (with branch and SHA), recoverable failure, or unrecoverable failure. Include error details and log references if applicable.",
   schema: committerMetaSchema,
   extractRefs: null,
 };

packages/workflow-template-develop/src/roles/planner.ts

@@ -44,8 +44,6 @@ Order phases so earlier steps unblock later ones. Cover root cause, edge cases,
 export const plannerRole: RoleDefinition<PlannerMeta> = {
   description: "Breaks the task into sequential phases for the coder.",
   systemPrompt: PLANNER_SYSTEM,
-  extractPrompt:
-    "Extract the implementation phases from the agent's output. Each phase has a hash (the CAS content-hash returned by the cas put command) and a title (one-line summary).",
   schema: plannerMetaSchema,
   extractRefs: (meta) => meta.phases.map((p) => p.hash),
 };

packages/workflow-template-develop/src/roles/reviewer.ts

@@ -37,8 +37,6 @@ Be thorough. A false approve costs more than a false reject.`;
 export const reviewerRole: RoleDefinition<ReviewerMeta> = {
   description: "Runs git diff checks and sets approved when the change is ready.",
   systemPrompt: REVIEWER_SYSTEM,
-  extractPrompt:
-    "Extract the review verdict: approved or rejected. If rejected, list the blocking issues.",
   schema: reviewerMetaSchema,
   extractRefs: null,
 };

packages/workflow-template-develop/src/roles/tester.ts

@@ -19,8 +19,6 @@ const TESTER_SYSTEM = `You are a tester. Run the project's test suite, build, an
 export const testerRole: RoleDefinition<TesterMeta> = {
   description: "Runs test, build, and lint commands and reports pass or fail with details.",
   systemPrompt: TESTER_SYSTEM,
-  extractPrompt:
-    "Extract the verification result: passed with summary details, or failed with details of what broke.",
   schema: testerMetaSchema,
   extractRefs: null,
 };

packages/workflow-template-solve-issue/src/developer.ts

@@ -16,21 +16,10 @@ The actual implementation (planning → coding → reviewing → testing → com
 
 Pass through the task and let the child workflow do the work.`;
 
-const DEVELOPER_EXTRACT_PROMPT = `The agent output is the root CAS hash of a child workflow thread. Use the cas_get tool to traverse the Merkle DAG and extract the developer summary.
-
-Procedure:
-1. cas_get(<rootHash>) — the root node lists all child step hashes (planner, coder, reviewer, tester, committer).
-2. Find the committer step. cas_get its hash to read the committer's meta — extract branch and commitSha from there.
-3. Find every coder step. cas_get each to read the coder's filesChanged. Union all filesChanged across coder steps.
-4. Compose a short human-readable summary describing what the develop child workflow accomplished (drawn from the coder summaries, or a synthesis of them).
-
-Return: { branch, commitSha, filesChanged, summary }.`;
-
 export const developerRole: RoleDefinition<DeveloperMeta> = {
   description:
     "Delegates the actual implementation to the develop workflow (workflow-as-agent). Produces a summary by traversing the child thread's Merkle DAG.",
   systemPrompt: DEVELOPER_SYSTEM,
-  extractPrompt: DEVELOPER_EXTRACT_PROMPT,
   schema: developerMetaSchema,
   extractRefs: () => [],
 };

packages/workflow-template-solve-issue/src/moderator.ts

@@ -1,26 +1,12 @@
-import type { Moderator } from "@uncaged/workflow-runtime";
-import { END } from "@uncaged/workflow-runtime";
+import { END, type ModeratorTable, START, tableToModerator } from "@uncaged/workflow-runtime";
 
 import type { SolveIssueMeta } from "./roles.js";
 
-export const solveIssueModerator: Moderator<SolveIssueMeta> = (ctx) => {
-  if (ctx.steps.length === 0) {
-    return "preparer";
-  }
-
-  const last = ctx.steps[ctx.steps.length - 1];
-
-  if (last.role === "preparer") {
-    return "developer";
-  }
-
-  if (last.role === "developer") {
-    return "submitter";
-  }
-
-  if (last.role === "submitter") {
-    return END;
-  }
-
-  return END;
+const table: ModeratorTable<SolveIssueMeta> = {
+  [START]: [{ condition: "FALLBACK", role: "preparer" }],
+  preparer: [{ condition: "FALLBACK", role: "developer" }],
+  developer: [{ condition: "FALLBACK", role: "submitter" }],
+  submitter: [{ condition: "FALLBACK", role: END }],
 };
+
+export const solveIssueModerator = tableToModerator(table);

packages/workflow-template-solve-issue/src/roles/preparer.ts

@@ -44,8 +44,6 @@ export const preparerRole: RoleDefinition<PreparerMeta> = {
   description:
     "Locates or clones the target repository, ensures it is up to date, and gathers project context (conventions, toolchain).",
   systemPrompt: PREPARER_SYSTEM,
-  extractPrompt:
-    "Extract repoPath (absolute path), defaultBranch, conventions (summary string or null), and toolchain (packageManager, testCommand, lintCommand, buildCommand — each string or null).",
   schema: preparerMetaSchema,
   extractRefs: null,
 };

packages/workflow-template-solve-issue/src/roles/submitter.ts

@@ -31,13 +31,9 @@ Read the thread for context:
 
 On any failure (push rejected, gh not authenticated, PR creation failed, etc.), report status="failed" with a short error message. Do not retry — surface the error so the moderator can decide.`;
 
-const SUBMITTER_EXTRACT_PROMPT =
-  "Extract the submission result. status='submitted' with prUrl on success, or status='failed' with a short error message on failure.";
-
 export const submitterRole: RoleDefinition<SubmitterMeta> = {
   description: "Pushes the developer's branch to the remote and opens a pull request.",
   systemPrompt: SUBMITTER_SYSTEM,
-  extractPrompt: SUBMITTER_EXTRACT_PROMPT,
   schema: submitterMetaSchema,
   extractRefs: null,
 };