@zhushanwen/pi-subagent-workflow 8.0.0 → 8.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.0.0",
+  "version": "8.1.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -22,6 +22,7 @@
     "agents/",
     "skills/",
     "workflows/",
+    "scripts/",
     "src/index.ts",
     "src/execution/",
     "src/injectors/",
@@ -29,6 +30,9 @@
     "src/interface/",
     "src/shared/"
   ],
+  "xyz-agent": {
+    "role": "universal"
+  },
   "pi": {
     "extensions": [
       "./index.ts"
@@ -41,18 +45,19 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.4.0",
     "ajv": "^8.20.0",
     "yaml": "^2.9.0",
-    "@zhushanwen/pi-extension-logger": "0.2.1"
+    "@xyz-agent/extension-protocol": "0.5.1",
+    "@zhushanwen/pi-extension-logger": "0.2.2",
+    "@zhushanwen/pi-file-lock": "0.1.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-ai": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.1",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.3.2",
-    "@zhushanwen/pi-structured-output": "5.0.1"
+    "@zhushanwen/pi-pending-notifications": "0.3.4",
+    "@zhushanwen/pi-structured-output": "5.0.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -64,6 +69,7 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "scripts": {

package/scripts/rfl.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+// rfl.mjs — review-fix-loop run 数据查询 CLI（tier-1 §7.4，零依赖 node 脚本）
+//
+// 读取 ~/.review-fix-loop/<repo-slug>/<runId>/state.json（workflow 脚本落盘），
+// 派生指标现算不落盘。M0 数据结构（calls/batches[].rounds[].phaseTimings）为全集，
+// M1/M2 字段（issues[].origin/dormant/scores）缺省容错显示。
+//
+// 用法：
+//   node rfl.mjs list [repoSlug]            run 清单（runId/时间/终止原因/轮数）
+//   node rfl.mjs stats <runId|latest>       单 run 全景（token/缓存/per-role/轮次时间线）
+//   node rfl.mjs trends [repoSlug]          跨 run 趋势表
+//   node rfl.mjs clean --older-than 30d [--yes]   清理（默认干跑）
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const ROOT = join(homedir(), ".review-fix-loop");
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function listRuns(repoSlug) {
+  if (!isDir(ROOT)) return [];
+  const repos = repoSlug ? [repoSlug] : readdirSync(ROOT).filter((d) => isDir(join(ROOT, d)));
+  const runs = [];
+  for (const repo of repos) {
+    const repoDir = join(ROOT, repo);
+    if (!isDir(repoDir)) continue;
+    for (const runId of readdirSync(repoDir)) {
+      const stateFile = join(repoDir, runId, "state.json");
+      if (!existsSync(stateFile)) continue;
+      try {
+        runs.push({ repo, runId, state: JSON.parse(readFileSync(stateFile, "utf8")), stateFile });
+      } catch { /* 损坏 state 跳过（半写入 run） */ }
+    }
+  }
+  return runs.sort((a, b) => String(a.state?.meta?.startedAt ?? "").localeCompare(String(b.state?.meta?.startedAt ?? "")));
+}
+
+function fmtTokens(n) {
+  if (n == null) return "-";
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M";
+  if (n >= 1_000) return Math.round(n / 1_000) + "k";
+  return String(n);
+}
+
+function fmtMs(ms) {
+  if (ms == null) return "-";
+  if (ms >= 60_000) return Math.floor(ms / 60_000) + "m" + Math.round((ms % 60_000) / 1000) + "s";
+  if (ms >= 1_000) return Math.round(ms / 1000) + "s";
+  return Math.round(ms) + "ms";
+}
+
+function fmtCost(c) {
+  if (c == null) return "-";
+  return "$" + (c >= 0.01 ? c.toFixed(2) : c.toFixed(4));
+}
+
+/** usage 容错取数：usage 缺失或字段缺省一律按 0 计。 */
+function usageOrZero(u, k) {
+  return (u && u[k]) || 0;
+}
+
+/** 累加单个 call 的 token 四分量与 cost（无 usage 的 call 跳过）。 */
+function addUsageSums(sum, u) {
+  if (!u) return;
+  sum.input += u.input || 0;
+  sum.output += u.output || 0;
+  sum.cacheRead += u.cacheRead || 0;
+  sum.cacheWrite += u.cacheWrite || 0;
+  sum.cost += u.cost || 0;
+}
+
+/** 聚合 calls[]：token 四分量/cost/命中率/per-role。 */
+function summarizeCalls(calls) {
+  const sum = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  const byRole = {};
+  for (const c of calls || []) {
+    const u = c.usage;
+    addUsageSums(sum, u);
+    const key = c.role || "unknown";
+    byRole[key] = byRole[key] || { count: 0, input: 0, cacheRead: 0 };
+    byRole[key].count++;
+    byRole[key].input += usageOrZero(u, "input");
+    byRole[key].cacheRead += usageOrZero(u, "cacheRead");
+  }
+  const denom = sum.input + sum.cacheRead;
+  const cachePct = denom > 0 ? Math.round((sum.cacheRead / denom) * 100) : null;
+  return { sum, byRole, cachePct };
+}
+
+function roundCount(state) {
+  return (state.batches || []).reduce((a, b) => a + (b.rounds || []).length, 0);
+}
+
+/** phaseTimings 值合法性：[startMs, endMs] 数字对（半写入 run 容错）。 */
+function isTimingPair(pair) {
+  return Array.isArray(pair) && typeof pair[0] === "number" && typeof pair[1] === "number";
+}
+
+/** 收集 run 内全部合法 phase 时序对 [startMs, endMs]（非法值=半写入 run 容错跳过）。 */
+function validTimingPairs(state) {
+  const pairs = [];
+  for (const b of state.batches || []) {
+    for (const r of b.rounds || []) {
+      for (const pair of Object.values(r.phaseTimings || {})) {
+        if (isTimingPair(pair)) pairs.push(pair);
+      }
+    }
+  }
+  return pairs;
+}
+
+/** run 墙钟时间 = 全部合法时序对的 min(start) → max(end)；无任何合法对返回 null。 */
+function wallMs(state) {
+  const pairs = validTimingPairs(state);
+  if (pairs.length === 0) return null;
+  return Math.max(...pairs.map((p) => p[1])) - Math.min(...pairs.map((p) => p[0]));
+}
+
+function cmdList(repoSlug) {
+  const runs = listRuns(repoSlug);
+  if (runs.length === 0) {
+    console.log("no runs found" + (repoSlug ? " for repo " + repoSlug : "") + " (root: " + ROOT + ")");
+    return 0;
+  }
+  for (const r of runs) {
+    const started = (r.state.meta && r.state.meta.startedAt) || "?";
+    const term = (r.state.meta && r.state.meta.terminated) || "?";
+    console.log(
+      r.runId.padEnd(28) + "  " + String(started).padEnd(25) +
+      "  " + String(term).padEnd(18) +
+      "  rounds: " + roundCount(r.state) +
+      (r.state.calls ? "  calls: " + r.state.calls.length : ""),
+    );
+  }
+  return 0;
+}
+
+/** stats 概览段：terminated/轮数 + token 四分量 + per-role 明细。 */
+function printStatsSummary(s, { sum, cachePct, byRole }) {
+  console.log("  terminated: " + ((s.meta && s.meta.terminated) || "?") + "  rounds: " + roundCount(s) + "  started: " + (s.meta && s.meta.startedAt));
+  console.log(
+    "  tokens: input " + fmtTokens(sum.input) +
+    " (cacheRead " + (cachePct == null ? "-" : cachePct + "%") + ")" +
+    "  output " + fmtTokens(sum.output) +
+    "  cost " + fmtCost(sum.cost) +
+    "  wall " + fmtMs(wallMs(s)),
+  );
+  const roleParts = Object.entries(byRole).map(([role, v]) =>
+    role + " ×" + v.count + " " + fmtTokens(v.input + v.cacheRead));
+  console.log("  per-role: " + (roleParts.join(" │ ") || "(no calls)"));
+}
+
+/** stats issues 概览段（M1 origin/dormant 字段缺省容错）。 */
+function printStatsIssues(s) {
+  const issues = s.issues ? Object.values(s.issues) : [];
+  const fixed = issues.filter((i) => i.status === "fixed").length;
+  const regressed = issues.filter((i) => (i.history || []).some((h) => h.status === "regressed")).length;
+  const origins = {};
+  for (const i of issues) origins[i.origin || "-"] = (origins[i.origin || "-"] || 0) + 1;
+  // issues 与 dormant 都是批作用域（state.issues 每批重置，最终 state 只含末批
+  // 条目，非 run 累计）——表述显式限定作用域，防止被误读为整个 run 的总数
+  console.log("  issues (last batch): total " + issues.length + " → fixed " + fixed +
+    "  regressed-ever " + regressed +
+    "  origins " + (issues.length ? Object.entries(origins).map(([k, v]) => k + " " + v).join("/") : "-") +
+    "  dormant (last batch) " + ((s.dormant || []).length));
+}
+
+/** stats scores 表段（M2 字段缺省容错）。 */
+function printStatsScores(s) {
+  if (Array.isArray(s.scores) && s.scores.length > 0) {
+    for (const sc of s.scores) {
+      // regression=null = 该维度 unverifiable（workflow 无对账数据可回填），无分值
+      // 语义——显示 n/a 而非 JS 字面量 "null"（与 total 缺省 "(no total)" 惯例一致）
+      const dims = sc.dimensions ? Object.entries(sc.dimensions).map(([k, v]) => k + " " + (v == null ? "n/a" : v)).join(" ") : "";
+      // scores entry 的 round 是批局部编号（每批从 1 重新计数），多批 run 下批 1 与
+      // 批 2 的 "R1" 两行完全同形无法归批——行首补 B<batch> 标识（与下方时间线
+      // R<n> (batch N) 的批标注口径呼应）；旧数据无 batch 字段回退 B1
+      console.log("  score B" + (sc.batch ?? 1) + " R" + (sc.round ?? "?") + " " + (sc.targetKind || "?") + "/" + (sc.targetName || "?") +
+        ": " + (sc.total != null ? sc.total + "/10" : "(no total)") + "  [" + dims + "]");
+    }
+  } else {
+    console.log("  scores: (none)");
+  }
+}
+
+/** stats 轮次时间线段。 */
+function printStatsTimeline(s) {
+  for (const b of s.batches || []) {
+    for (const r of b.rounds || []) {
+      const pt = r.phaseTimings || {};
+      const seg = (k) => (Array.isArray(pt[k]) ? k + " " + fmtMs(pt[k][1] - pt[k][0]) : k + " -");
+      console.log("  R" + r.round + " (batch " + b.index + "): " + seg("review") + " │ " + seg("aggregate") + " │ " + seg("fix") +
+        "  mustFix " + (r.mustFix ?? "-"));
+    }
+  }
+}
+
+function cmdStats(runIdOrLatest, repoSlug) {
+  const runs = listRuns(repoSlug);
+  if (runs.length === 0) { console.log("no runs found (root: " + ROOT + ")"); return 1; }
+  const run = runIdOrLatest === "latest" ? runs[runs.length - 1] : runs.find((r) => r.runId === runIdOrLatest);
+  if (!run) { console.log("run not found: " + runIdOrLatest); return 1; }
+  const s = run.state;
+  const { sum, byRole, cachePct } = summarizeCalls(s.calls);
+  console.log("run " + run.runId + " (repo: " + run.repo + ")");
+  printStatsSummary(s, { sum, cachePct, byRole });
+  printStatsIssues(s);
+  printStatsScores(s);
+  printStatsTimeline(s);
+  return 0;
+}
+
+function cmdTrends(repoSlug) {
+  const runs = listRuns(repoSlug);
+  if (runs.length === 0) { console.log("no runs found (root: " + ROOT + ")"); return 0; }
+  // started 列宽 = ISO 8601 恒长 24（padEnd(20) 会让表头比数据行左移 4 字符错位）
+  // reg/att 列名刻意缩短：该列是末批作用域（见循环后 legend），长名 "regressed/
+  // attempted" 会被读成与 rounds/tokens/cache% 同级的 run 级指标
+  const header = "runId".padEnd(28) + "  " + "started".padEnd(24) + "  " + "rounds".padEnd(6) + "  " + "tokens".padEnd(8) + "  " + "cache%".padEnd(6) + "  " + "reg/att";
+  console.log(header);
+  for (const r of runs) {
+    const { sum, cachePct } = summarizeCalls(r.state.calls);
+    const issues = r.state.issues ? Object.values(r.state.issues) : [];
+    const regressed = issues.filter((i) => (i.history || []).some((h) => h.status === "regressed")).length;
+    // 分母 = 曾进入 fix-attempted 的 issue 数，与分子（含 regressed history 的 issue
+    // 数）同为 issue 计数口径（§6.7「fix 质量 = 1 − regressed/fix-attempted」的分母
+    // 应是被尝试修复过的 issue）。不能用 Σ fixAttempts：该字段权威语义是「修复失败
+    // 次数」（初始 0，每次转 regressed 才 +1），5 个 issue 修 4 成 1 败会算成 1/1
+    // （字面 100% 回归率），正确口径是 1/5；进入过修复的痕迹只有 history 的
+    // fix-attempted 条目。分母 0（从未尝试修复）率无意义，显示 "-"。
+    const attempted = issues.filter((i) => (i.history || []).some((h) => h.status === "fix-attempted")).length;
+    const regressedCol = attempted > 0 ? regressed + "/" + attempted : "-";
+    console.log(
+      r.runId.padEnd(28) + "  " + String((r.state.meta && r.state.meta.startedAt) || "?").padEnd(24) + "  " +
+      String(roundCount(r.state)).padEnd(6) + "  " +
+      fmtTokens(sum.input + sum.cacheRead + sum.output).padEnd(8) + "  " +
+      String(cachePct == null ? "-" : cachePct + "%").padEnd(6) + "  " + regressedCol,
+    );
+  }
+  // reg/att 与同行其他列口径不同：state.issues 每批重置，最终 state 只含末批条目
+  // （分子分母内部一致），而 rounds/tokens/cache% 是 run 级累计——跨 run 对比时
+  // 易把末批数据误读为 run 级，表后用 legend 显式标注作用域与分母口径（函数开头
+  // 已保证 runs 非空，走到这里表必然非空）
+  console.log("reg/att: last-batch scope (issues reset per batch); denominator = issues ever fix-attempted");
+  return 0;
+}
+
+function parseOlderThan(spec) {
+  const m = /^(\d+)([dh])$/.exec(String(spec || ""));
+  if (!m) return null;
+  return Date.now() - parseInt(m[1], 10) * (m[2] === "d" ? 86_400_000 : 3_600_000);
+}
+
+function cmdClean(spec, yes) {
+  const cutoff = parseOlderThan(spec);
+  if (cutoff == null) {
+    console.log("invalid --older-than (expect <N>d or <N>h, e.g. 30d)");
+    return 1;
+  }
+  const runs = listRuns();
+  const expired = runs.filter((r) => {
+    const t = r.stateFile ? statSync(r.stateFile).mtimeMs : 0;
+    const started = r.state.meta && r.state.meta.startedAt ? Date.parse(r.state.meta.startedAt) : NaN;
+    const basis = Number.isFinite(started) ? started : t;
+    return basis < cutoff;
+  });
+  if (expired.length === 0) { console.log("nothing older than " + spec); return 0; }
+  for (const r of expired) {
+    const dir = join(ROOT, r.repo, r.runId);
+    if (yes) {
+      rmSync(dir, { recursive: true, force: true });
+      console.log("deleted " + dir);
+    } else {
+      console.log("would delete " + dir + " (dry-run; add --yes to execute)");
+    }
+  }
+  return 0;
+}
+
+// ── main ──────────────────────────────────────────────────────
+const [cmd, ...rest] = process.argv.slice(2);
+try {
+  switch (cmd) {
+    case "list": process.exit(cmdList(rest[0])); break;
+    case "stats": {
+      if (!rest[0]) { console.log("usage: rfl stats <runId|latest> [repoSlug]"); process.exit(1); }
+      process.exit(cmdStats(rest[0], rest[1]));
+      break;
+    }
+    case "trends": process.exit(cmdTrends(rest[0])); break;
+    case "clean": {
+      const oi = rest.indexOf("--older-than");
+      const spec = oi >= 0 ? rest[oi + 1] : null;
+      if (!spec) { console.log("usage: rfl clean --older-than <N>d [--yes]"); process.exit(1); }
+      process.exit(cmdClean(spec, rest.includes("--yes")));
+      break;
+    }
+    default:
+      console.log("usage: rfl <list|stats|trends|clean> ...\n  list [repoSlug]\n  stats <runId|latest> [repoSlug]\n  trends [repoSlug]\n  clean --older-than 30d [--yes]");
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  console.error("rfl: " + (err && err.message ? err.message : String(err)));
+  process.exit(2);
+}

package/skills/workflow-script-format/SKILL.md

@@ -201,7 +201,7 @@ const results = await parallel(
 );
 ```
 
-> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 

package/src/execution/__tests__/channel-registry-handshake.test.ts

@@ -2,7 +2,7 @@
 //
 // 决策 D（修复 M4）：channel handshake 协议升级测试。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/channel-registry-access.ts
+// 测试对象：extensions/universal/subagent-workflow/src/execution/channel-registry-access.ts
 //
 // 协议契约（与 ask-user 侧严格对齐）：
 //   key 字面量：     "@zhushanwen/pi-subagents.channelHandshake"

package/src/execution/__tests__/dialog-queue.test.ts

@@ -2,7 +2,7 @@
 //
 // W2 红灯测试：dialog-queue.ts — L2 跨子进程全局 dialog 串行队列。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/dialog-queue.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/dialog-queue.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 3（L2 DialogGlobalQueue 设计）
 //
 // DialogGlobalQueue 设计要点：

package/src/execution/__tests__/finalize-record.test.ts

@@ -86,7 +86,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     return {
       manifestStore,
       worktreeManager: {} as never,
-      store: { archive: vi.fn() } as never,
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
       modelService: {} as never,
       pi: { appendEntry: vi.fn() },
       emitUnregister: vi.fn(),
@@ -206,7 +206,7 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     return {
       manifestStore,
       worktreeManager: { cleanup: vi.fn(), collectPatch: vi.fn() } as never,
-      store: { archive: vi.fn() } as never,
+      store: { archive: vi.fn(), reportRecordTransition: vi.fn() } as never,
       modelService: {} as never,
       pi: { appendEntry: vi.fn() } as never,
       emitUnregister: vi.fn(),
@@ -234,6 +234,17 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
   });
 
+  it("W16: 轮终上报 reportRecordTransition（record-store 类外恢复写点迁移落 entry）", async () => {
+    const deps = makeDeps();
+    const record = makeMinimalRecord({ id: "rec-report", chatMode: true, round: 2 });
+    record.status = "closed";
+    await doFinalizeRoundToIdle(deps, record, makeMinimalResult());
+    expect(deps.store.reportRecordTransition).toHaveBeenCalledTimes(1);
+    // 上报发生在 round 推进之后（entry 携带新轮计数，重建源不滞后）
+    expect(record.round).toBe(3);
+    expect(record.status).toBe("running");
+  });
+
   it("record.round 已为 N → round 变 N+1", async () => {
     const record = makeMinimalRecord({ id: "rec-round", round: 3 });
     record.status = "closed";
@@ -322,7 +333,7 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     expect(record.result).not.toContain("PREV-ROUND-TEXT");
   });
 
-  it("C1TC11: 非 chatMode 空文本沿用旧值——one-shot 空文本完成 record.result 保持 undefined（G2/G4）", async () => {
+  it("C1TC11 [R2-1]: one-shot 首轮空文本成功完成 → record.result 补占位「(empty)」（非 undefined）", async () => {
     const record = makeMinimalRecord({ id: "rec-oneshot-empty", chatMode: false });
     record.status = "closed";
     // one-shot 成功空文本完成路径（collectResult getFullText 返回 ""、success=true）：
@@ -333,10 +344,25 @@ describe("doFinalizeRoundToIdle — chatMode 轮次完成进 idle (M2-A)", () =>
     result.success = true;
     result.error = undefined;
     await doFinalizeRoundToIdle(makeDeps(), record, result);
-    // 非 chatMode 侧维持现状（第三分支 record.chatMode ? 占位 : record.result）
-    expect(record.result).toBeUndefined();
-    // notifier buildLlmContent 的 record.result ?? "(empty)" 确定性链保 G4：
-    // 通知文案逐字节产出 "completed. Result:\n(empty)"，不漂移为 "(no output this round)"
+    // [R2-1] 轮终信号优先：占位非 undefined 是 renderer hasRunning 排除轮终 running 的
+    // 判据——保持 undefined 会让完成注入后末位 turn 永久「工作中」
+    expect(record.result).toBe("(empty)");
+    // notifier buildLlmContent 的 record.result ?? "(empty)" 兜底同款措辞：
+    // 通知文案逐字节产出 "completed. Result:\n(empty)"（G4 保持）
     expect(record.result ?? "(empty)").toBe("(empty)");
   });
+
+  it("C1TC11b [R2-1]: one-shot 续轮空文本 → 沿用前值（one-shot 无增量语义，不覆盖为占位）", async () => {
+    const record = makeMinimalRecord({ id: "rec-oneshot-cont", chatMode: false });
+    record.status = "closed";
+    // 上一轮真实产出（续轮 record.result 前值）
+    record.result = "first round output";
+    const result = makeMinimalResult();
+    result.text = "";
+    result.success = true;
+    result.error = undefined;
+    await doFinalizeRoundToIdle(makeDeps(), record, result);
+    // one-shot record.result = 该 subagent 最终输出：空文本续轮沿用前值，不被 "(empty)" 覆盖
+    expect(record.result).toBe("first round output");
+  });
 });

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -63,6 +63,15 @@ import { PassThrough } from "node:stream";
 import { createRecord } from "../../execution-record.ts";
 import type { RunOptions, SessionRunnerContext } from "../../session-runner.ts";
 
+/** FakeChild 的假 pid（满足 ChildProcess.pid 形状，无真实进程语义）。 */
+const FAKE_PID = 12345;
+
+/** waitForSpawn 默认超时（ms），超时说明 spawn 未被调（runSpawn 前置 await 卡死）。 */
+const WAIT_SPAWN_TIMEOUT_MS = 1000;
+
+/** waitForSpawn 轮询间隔（ms），微任务级等待的粒度。 */
+const SPAWN_POLL_INTERVAL_MS = 5;
+
 /**
  * FakeChild：模拟 ChildProcess（EventEmitter + PassThrough streams）。
  *
@@ -74,7 +83,7 @@ import type { RunOptions, SessionRunnerContext } from "../../session-runner.ts";
  *   2. C13 e2e 测试可直接 `new FakeChild()` 手动构造 child 喂给 ui-request-queue（不经 spawn）。
  */
 export class FakeChild extends EventEmitter {
-  pid = 12345;
+  pid = FAKE_PID;
   stdout = new PassThrough();
   stderr = new PassThrough();
   stdin = new PassThrough();
@@ -136,14 +145,14 @@ export function lastSpawnedChild<
  */
 export async function waitForSpawn<
   T extends { mock: { results: unknown[] } },
->(mockSpawn: T, timeoutMs = 1000): Promise<void> {
+>(mockSpawn: T, timeoutMs: number = WAIT_SPAWN_TIMEOUT_MS): Promise<void> {
   const start = Date.now();
   const baseline = mockSpawn.mock.results.length;
   while (mockSpawn.mock.results.length <= baseline) {
     if (Date.now() - start > timeoutMs) {
       throw new Error(`spawn was not called within ${timeoutMs}ms`);
     }
-    await new Promise((r) => setTimeout(r, 5));
+    await new Promise((r) => setTimeout(r, SPAWN_POLL_INTERVAL_MS));
   }
 }
 

package/src/execution/__tests__/host-mode.test.ts

@@ -2,7 +2,7 @@
 //
 // W1 红灯测试：host-mode.ts 主进程运行模式分类工具。
 //
-// 测试对象：extensions/subagent-workflow/src/execution/host-mode.ts（新建）
+// 测试对象：extensions/universal/subagent-workflow/src/execution/host-mode.ts（新建）
 // 契约来源：.fix-plans/00-master-summary.md §一 冲突 4 + §2.5（W4 守卫消费点）
 //
 // 三个导出：