feat(cli): add background thread execution and running threads query

This commit implements issue #456, adding two related capabilities to the uwf CLI:

1. **Background execution mode** for `uwf thread step` (via `--background` flag)
   - Spawns agent execution in a detached background process
   - Returns immediately with thread ID and background status
   - Maintains marker files to track running processes
   - Supports `--count` option to run multiple steps in background
   - Prevents concurrent execution of the same thread

2. **Running threads query** command (`uwf thread running`)
   - Lists all threads currently executing in background
   - Returns thread ID, workflow, current role, PID, and start time
   - Automatically filters out stale markers (dead processes)
   - Empty list when no threads are running

**Key changes:**

- **workflow-protocol**: Added `RunningThreadItem`, `RunningThreadsOutput` types
  Updated `StepOutput` to include `background: boolean | null` field

- **cli-workflow/background**: New module for process management
  - Marker file creation/deletion (atomic operations)
  - PID liveness checking
  - Stale marker cleanup
  - Running threads query

- **cli-workflow/commands/thread**:
  - Updated `cmdThreadStep` to support `--background` and `--_background-worker` flags
  - Added `cmdThreadStepBackground` for spawning detached processes
  - Added `cmdThreadRunning` to list running threads
  - Updated `cmdThreadKill` to terminate background processes

- **cli-workflow/cli**: Added CLI routing for new commands and flags

**Integration:**
- `uwf thread kill` now terminates background processes before archiving
- Foreground execution checks for existing background process and fails if found
- Background worker creates/cleans up marker files automatically
- Marker files stored in `~/.uncaged/workflow/running/*.json`

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

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

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

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

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

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

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

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

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

packages/cli-workflow/src/cli.ts

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

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

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

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

@@ -1,4 +1,4 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { access, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
 import type { Store as CasStore, JSONSchema } from "@uncaged/json-cas";
@@ -10,6 +10,7 @@ import type {
   AgentConfig,
   CasRef,
   ModeratorContext,
+  RunningThreadsOutput,
   StartEntry,
   StartNodePayload,
   StartOutput,
@@ -27,7 +28,12 @@ import type {
 import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util";
 import { config as loadDotenv } from "dotenv";
 import { parse, stringify } from "yaml";
-
+import {
+  createMarker,
+  deleteMarker,
+  isThreadRunning,
+  listRunningThreads,
+} from "../background/index.js";
 import {
   appendThreadHistory,
   createUwfStore,
@@ -52,6 +58,7 @@ const PL_AGENT_SPAWN = "R5J2W8N4";
 const PL_AGENT_DONE = "C6P9E3H7";
 const PL_THREAD_ARCHIVED = "F4D8Q2K5";
 const PL_STEP_ERROR = "B8T5N1V6";
+const PL_BACKGROUND_START = "X7Q4W9M2";
 
 function failStep(plog: ProcessLogger, message: string): never {
   plog.log(PL_STEP_ERROR, message, null);
@@ -321,6 +328,7 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
       thread: threadId,
       head: activeHead,
       done: false,
+      background: null,
     };
   }
 
@@ -331,6 +339,7 @@ export async function cmdThreadShow(storageRoot: string, threadId: ThreadId): Pr
       thread: threadId,
       head: hist.head,
       done: true,
+      background: null,
     };
   }
 
@@ -804,13 +813,11 @@ function spawnAgent(
   role: string,
   edgePrompt: string,
 ): CasRef {
-  const argv = [...agent.args, threadId, role];
-  const env = { ...process.env, UWF_EDGE_PROMPT: edgePrompt };
+  const argv = [...agent.args, "--thread", threadId, "--role", role, "--prompt", edgePrompt];
   let stdout: string;
   try {
     stdout = execFileSync(agent.command, argv, {
       encoding: "utf8",
-      env,
       stdio: ["ignore", "pipe", "pipe"],
       maxBuffer: 50 * 1024 * 1024, // 50 MB — stream-json output can be large
     });
@@ -855,26 +862,60 @@ export async function cmdThreadStep(
   threadId: ThreadId,
   agentOverride: string | null,
   count: number,
+  background: boolean,
+  backgroundWorker: boolean,
 ): Promise<StepOutput[]> {
   if (count < 1 || !Number.isInteger(count)) {
     fail(`--count must be a positive integer, got: ${count}`);
   }
 
+  // Check if thread is already running in background (unless we ARE the background worker)
+  if (!backgroundWorker) {
+    const runningMarker = await isThreadRunning(storageRoot, threadId);
+    if (runningMarker !== null) {
+      fail(`thread already executing in background (PID: ${runningMarker.pid})`);
+    }
+  }
+
   const workflowHash = await resolveActiveThreadWorkflowHash(storageRoot, threadId);
   const plog = createProcessLogger({
     storageRoot,
     context: { thread: threadId, workflow: workflowHash },
   });
 
-  const results: StepOutput[] = [];
-  for (let i = 0; i < count; i++) {
-    const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
-    results.push(result);
-    if (result.done) {
-      break;
+  if (background && !backgroundWorker) {
+    // Spawn background process
+    return cmdThreadStepBackground(storageRoot, threadId, agentOverride, count, plog, workflowHash);
+  }
+
+  // If we're the background worker, create marker before execution
+  let markerCreated = false;
+  if (backgroundWorker) {
+    await createMarker(storageRoot, {
+      thread: threadId,
+      workflow: workflowHash,
+      pid: process.pid,
+      startedAt: Date.now(),
+    });
+    markerCreated = true;
+  }
+
+  try {
+    const results: StepOutput[] = [];
+    for (let i = 0; i < count; i++) {
+      const result = await cmdThreadStepOnce(storageRoot, threadId, agentOverride, plog);
+      results.push(result);
+      if (result.done) {
+        break;
+      }
+    }
+    return results;
+  } finally {
+    // Cleanup marker if we created one
+    if (markerCreated) {
+      await deleteMarker(storageRoot, threadId);
     }
   }
-  return results;
 }
 
 async function resolveActiveThreadWorkflowHash(
@@ -891,6 +932,57 @@ async function resolveActiveThreadWorkflowHash(
   return chain.start.workflow;
 }
 
+async function cmdThreadStepBackground(
+  storageRoot: string,
+  threadId: ThreadId,
+  agentOverride: string | null,
+  count: number,
+  plog: ProcessLogger,
+  workflowHash: CasRef,
+): Promise<StepOutput[]> {
+  // Get current head to return to caller
+  const index = await loadThreadsIndex(storageRoot);
+  const headHash = index[threadId];
+  if (headHash === undefined) {
+    failStep(plog, `thread not active: ${threadId}`);
+  }
+
+  // Spawn detached background process
+  const scriptPath = process.argv[1];
+  if (scriptPath === undefined) {
+    failStep(plog, "unable to determine script path for background execution");
+  }
+
+  const args = ["thread", "step", threadId, "--count", String(count)];
+
+  if (agentOverride !== null) {
+    args.push("--agent", agentOverride);
+  }
+
+  // Internal flag to signal the background worker to create/cleanup markers
+  args.push("--_background-worker");
+
+  plog.log(PL_BACKGROUND_START, `spawning background process count=${count}`, null);
+
+  const child = spawn(scriptPath, args, {
+    detached: true,
+    stdio: "ignore",
+  });
+
+  child.unref();
+
+  // Return immediately with current state and background flag
+  return [
+    {
+      workflow: workflowHash,
+      thread: threadId,
+      head: headHash,
+      done: false,
+      background: true,
+    },
+  ];
+}
+
 async function cmdThreadStepOnce(
   storageRoot: string,
   threadId: ThreadId,
@@ -928,6 +1020,7 @@ async function cmdThreadStepOnce(
       thread: threadId,
       head: headHash,
       done: true,
+      background: null,
     };
   }
 
@@ -975,6 +1068,7 @@ async function cmdThreadStepOnce(
     thread: threadId,
     head: newHead,
     done,
+    background: null,
   };
 }
 
@@ -1111,6 +1205,17 @@ export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Pr
     fail(`thread not active: ${threadId}`);
   }
 
+  // Check if thread is running in background and terminate it
+  const runningMarker = await isThreadRunning(storageRoot, threadId);
+  if (runningMarker !== null) {
+    try {
+      process.kill(runningMarker.pid, "SIGTERM");
+    } catch {
+      // Process may have already exited, ignore error
+    }
+    await deleteMarker(storageRoot, threadId);
+  }
+
   const uwf = await createUwfStore(storageRoot);
   const workflow = resolveWorkflowFromHead(uwf, head);
   if (workflow === null) {
@@ -1130,3 +1235,8 @@ export async function cmdThreadKill(storageRoot: string, threadId: ThreadId): Pr
 
   return { thread: threadId, archived: true };
 }
+
+export async function cmdThreadRunning(storageRoot: string): Promise<RunningThreadsOutput> {
+  const threads = await listRunningThreads(storageRoot);
+  return { threads };
+}

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

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

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

@@ -16,7 +16,7 @@ const log = createLogger({ sink: { kind: "stderr" } });
 
 const CLAUDE_COMMAND = "claude";
 const CLAUDE_MAX_TURNS = 90;
-const CLAUDE_MODEL = process.env["CLAUDE_MODEL"] ?? null;
+const CLAUDE_MODEL = process.env.CLAUDE_MODEL ?? null;
 
 function buildHistorySummary(steps: AgentContext["steps"]): string {
   if (steps.length === 0) {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

packages/workflow-dashboard/package.json

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

packages/workflow-dashboard/vitest.config.ts

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

packages/workflow-protocol/src/index.ts

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

packages/workflow-protocol/src/types.ts

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

scripts/batch-solve.sh

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