@zhushanwen/pi-subagent-workflow 9.0.1 → 9.1.0

package/src/interface/tool/__tests__/subagent-tool-actions.test.ts

@@ -0,0 +1,238 @@
+/**
+ * subagent tool 非 start 通道 + renderCall 预解析测试（与 path-guard 的 start 守卫面
+ * 互补，覆盖 executeSubagent 的 action 路由全分支与 renderCall 的 model 预解析降级链）。
+ *
+ * 覆盖面：
+ *   - execute：service 缺席 → 带恢复动作的错误；未知 action → immediate throw；
+ *     list/cancel/message/close/fork-from 六通道 handler 接线 + adapter 包装
+ *     （content JSON 给 LLM / details 领域对象给 renderResult）
+ *   - renderCall：model override 三层解析（override 在场 → resolved 注入标题；
+ *     resolveModel 抛错 → 降级不崩；override 缺省 → resolved undefined）
+ *
+ * mock 策略：六 handler 深路径 stub（领域内核行为由 core 侧
+ * subagent-actions-core.test.ts 锁定，此处只测接线）；pi-ai/typebox 用共享桩
+ * （对齐 subagent-tool-path-guard.test.ts）；logger stub（debug 冷路径不落盘）。
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@earendil-works/pi-ai", async () => {
+  const { piAiStringEnumStub } = await import("../../../__tests__/mocks/runtime-stubs.ts");
+  return piAiStringEnumStub();
+});
+vi.mock("typebox", async () => {
+  const { typeboxStub } = await import("../../../__tests__/mocks/runtime-stubs.ts");
+  return typeboxStub;
+});
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => ({ debug: vi.fn(), info: vi.fn(), warn: vi.fn(), error: vi.fn() }),
+}));
+vi.mock("@zhushanwen/subagent-core/execution/assembly/subagent-actions-core.ts", () => ({
+  startHandler: vi.fn(),
+  listHandler: vi.fn(),
+  cancelHandler: vi.fn(),
+  messageHandler: vi.fn(),
+  closeHandler: vi.fn(),
+  forkFromHandler: vi.fn(),
+  endedMessageGuard: vi.fn(),
+  mapExternalState: vi.fn(),
+  recordToListItem: vi.fn(),
+}));
+
+import {
+  cancelHandler,
+  closeHandler,
+  forkFromHandler,
+  listHandler,
+  messageHandler,
+  startHandler,
+  setSubagentService,
+  GLOBAL_SLOT_KEYS,
+} from "@zhushanwen/subagent-core";
+
+import { registerSubagentTool } from "../subagent-tool.ts";
+import { mockExtensionApi } from "@zhushanwen/subagent-core/testing/execution/__tests__/helpers/mock-extension-api.ts";
+
+/** 注册捕获的 tool 窄 view（execute + renderCall）。 */
+interface SubagentToolView { // oe-exempt:20260930:test:test double shape for tool capture (test infra)
+  name: string;
+  execute: (
+    toolCallId: string,
+    params: Record<string, unknown>,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
+  renderCall: (args: unknown, theme: unknown, ctx: unknown) => { render(width: number): string[] };
+}
+
+function captureTool(): SubagentToolView {
+  let captured: SubagentToolView | undefined;
+  const pi = mockExtensionApi({
+    registerTool: (tool: unknown) => {
+      captured = tool as SubagentToolView;
+    },
+  });
+  registerSubagentTool(pi);
+  if (!captured) throw new Error("subagent tool not registered");
+  return captured;
+}
+
+function resetServiceSlot(): void {
+  const slot = Reflect.get(globalThis, Symbol.for(GLOBAL_SLOT_KEYS.service)) as
+    | { current: unknown }
+    | undefined;
+  if (slot) slot.current = null;
+}
+
+const markingTheme = {
+  fg: (tag: string, text: string) => `${tag}(${text})`,
+  bold: (text: string) => text,
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+afterEach(() => {
+  resetServiceSlot();
+});
+
+describe("subagent tool execute：守卫与缺席面", () => {
+  it("service 缺席 → immediate throw，错误带恢复动作指引", async () => {
+    const tool = captureTool(); // 槽未注入
+    await expect(
+      tool.execute("c1", { action: "list" }, undefined, undefined, undefined),
+    ).rejects.toThrow(/subagents runtime not initialized.*Recovery: reload this session/s);
+  });
+
+  it("未知 action → immediate throw（Unknown subagent action）", async () => {
+    setSubagentService({ execute: vi.fn() } as never);
+    const tool = captureTool();
+    await expect(
+      tool.execute("c2", { action: "pause" }, undefined, undefined, undefined),
+    ).rejects.toThrow("Unknown subagent action: pause");
+  });
+});
+
+describe("subagent tool execute：六 action 通道接线", () => {
+  /** 注入最小 fake service 并捕获 tool（六通道共用基座）。 */
+  function withService(): SubagentToolView {
+    setSubagentService({ execute: vi.fn() } as never);
+    return captureTool();
+  }
+
+  it("list：listParam 解包透传，adapter 包装 listResponse", async () => {
+    vi.mocked(listHandler).mockReturnValue({ response: { items: [], total: 0 } } as never);
+    const tool = withService();
+    const params = { action: "list", listParam: { includeFinished: true, limit: 5 } };
+    const result = await tool.execute("c3", params, undefined, undefined, undefined);
+    expect(vi.mocked(listHandler)).toHaveBeenCalledWith(expect.anything(), params.listParam);
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "list" });
+    expect(result.details).toMatchObject({ action: "list" });
+  });
+
+  it("cancel：cancelParam 解包透传 + subagentId 回显", async () => {
+    vi.mocked(cancelHandler).mockResolvedValue({ subagentId: "sa-9", response: { stopped: true } } as never);
+    const tool = withService();
+    const params = { action: "cancel", cancelParam: { subagentId: "sa-9" } };
+    const result = await tool.execute("c4", params, undefined, undefined, undefined);
+    expect(vi.mocked(cancelHandler)).toHaveBeenCalledWith(expect.anything(), { subagentId: "sa-9" });
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "cancel", subagentId: "sa-9" });
+  });
+
+  it("message：messageParam 解包透传", async () => {
+    vi.mocked(messageHandler).mockResolvedValue({ subagentId: "sa-7", response: { queued: true } } as never);
+    const tool = withService();
+    const params = { action: "message", messageParam: { subagentId: "sa-7", text: "continue" } };
+    const result = await tool.execute("c5", params, undefined, undefined, undefined);
+    expect(vi.mocked(messageHandler)).toHaveBeenCalledWith(expect.anything(), params.messageParam);
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "message", subagentId: "sa-7" });
+  });
+
+  it("close：closeParam 解包透传", async () => {
+    vi.mocked(closeHandler).mockResolvedValue({ subagentId: "sa-6", response: { archived: true } } as never);
+    const tool = withService();
+    const params = { action: "close", closeParam: { subagentId: "sa-6" } };
+    const result = await tool.execute("c6", params, undefined, undefined, undefined);
+    expect(vi.mocked(closeHandler)).toHaveBeenCalledWith(expect.anything(), { subagentId: "sa-6" });
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "close", subagentId: "sa-6" });
+  });
+
+  it("fork-from：forkFromParam 解包透传", async () => {
+    vi.mocked(forkFromHandler).mockResolvedValue({
+      subagentId: "sa-new",
+      response: { sourceSubagentId: "sa-old", newSubagentId: "sa-new" },
+    } as never);
+    const tool = withService();
+    const params = { action: "fork-from", forkFromParam: { sourceSubagentId: "sa-old", prompt: "continue" } };
+    const result = await tool.execute("c7", params, undefined, undefined, undefined);
+    expect(vi.mocked(forkFromHandler)).toHaveBeenCalledWith(expect.anything(), params.forkFromParam);
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "fork-from", subagentId: "sa-new" });
+  });
+
+  it("start：合法绝对路径放行，顶层 params 原样透传（含 signal/model override）", async () => {
+    vi.mocked(startHandler).mockResolvedValue({
+      subagentId: "sa-1",
+      slug: "demo",
+      model: "p/m",
+      response: { mode: "background" },
+    } as never);
+    setSubagentService({ execute: vi.fn() } as never);
+    const tool = captureTool();
+    const params = {
+      action: "start",
+      task: "t",
+      slug: "demo",
+      skillPath: "/abs/skills/x.md",
+      cwd: "/abs/cwd",
+      model: "p/m",
+    };
+    const result = await tool.execute("c8", params, undefined, undefined, { mode: "rpc", hasUI: true });
+    expect(vi.mocked(startHandler)).toHaveBeenCalledWith(expect.anything(), params, undefined, undefined);
+    expect(JSON.parse(result.content[0]!.text)).toMatchObject({ action: "start", subagentId: "sa-1", slug: "demo" });
+  });
+});
+
+describe("subagent tool renderCall：model 预解析", () => {
+  it("override 在场 + resolveModel 成功 → resolved 注入标题（provider/model · thinking）", () => {
+    setSubagentService({
+      resolveModel: () => ({ model: { provider: "p", id: "m1" }, thinkingLevel: "high" }),
+    } as never);
+    const tool = captureTool();
+    const comp = tool.renderCall({ agent: "coder", model: "p/m1", thinkingLevel: "high", slug: "demo" }, markingTheme, {});
+    const text = comp.render(200).join("");
+    expect(text).toContain("p/m1");
+    expect(text).toContain("· high");
+    expect(text).toContain("demo");
+  });
+
+  it("resolveModel 抛错 → 降级不崩（标题无 model 段）", () => {
+    setSubagentService({
+      resolveModel: () => {
+        throw new Error("registry cold");
+      },
+    } as never);
+    const tool = captureTool();
+    const comp = tool.renderCall({ agent: "coder", model: "p/m1" }, markingTheme, {});
+    const text = comp.render(80).join("");
+    expect(text).toContain("subagent");
+    expect(text).not.toContain("p/m1");
+  });
+
+  it("service 缺席 → resolved undefined 降级；无 agent 字段兜底默认名", () => {
+    const tool = captureTool(); // 槽空
+    const comp = tool.renderCall({ task: "t" }, markingTheme, {});
+    const text = comp.render(80).join("");
+    expect(text).toContain("subagent");
+    expect(text).not.toContain(" · high");
+  });
+
+  it("args 非 object（null）→ 不崩，标题仍渲染（isModelOverrideObj 假分支）", () => {
+    setSubagentService({
+      resolveModel: () => ({ model: { provider: "p", id: "m1" }, thinkingLevel: "high" }),
+    } as never);
+    const tool = captureTool();
+    const comp = tool.renderCall(null, markingTheme, {});
+    expect(comp.render(80).join("")).toContain("subagent");
+  });
+});

package/src/interface/{__tests__ → tool/__tests__}/subagent-tool-path-guard.test.ts

@@ -21,22 +21,23 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-// 共享桩（./mocks/runtime-stubs.ts 相对本文件 = ../../__tests__/mocks/runtime-stubs.ts）：
+// 共享桩（./mocks/runtime-stubs.ts 相对本文件 = ../../../__tests__/mocks/runtime-stubs.ts）：
 // vi.mock 工厂提升到文件顶部，体内不能引用普通顶层变量，一律经 async 工厂 +
 // 动态 import 取桩。
 vi.mock("@earendil-works/pi-ai", async () => {
-  const { piAiStringEnumStub } = await import("../../__tests__/mocks/runtime-stubs.ts");
+  const { piAiStringEnumStub } = await import("../../../__tests__/mocks/runtime-stubs.ts");
   return piAiStringEnumStub();
 });
 vi.mock("typebox", async () => {
-  const { typeboxStub } = await import("../../__tests__/mocks/runtime-stubs.ts");
+  const { typeboxStub } = await import("../../../__tests__/mocks/runtime-stubs.ts");
   return typeboxStub;
 });
 
 import { setSubagentService } from "@zhushanwen/subagent-core";
 
-import { registerSubagentTool } from "../../interface/subagent-tool.ts";
+import { registerSubagentTool } from "../subagent-tool.ts";
 import { mockExtensionApi } from "@zhushanwen/subagent-core/testing/execution/__tests__/helpers/mock-extension-api.ts";
+import { GLOBAL_SLOT_KEYS } from "@zhushanwen/subagent-core";
 
 // ── 访问器槽注入 helpers ─────────────────────────────────────
 
@@ -48,7 +49,7 @@ const { mockServiceExecute } = vi.hoisted(() => ({
 /** 重置进程级 SubagentService 单例槽（setSubagentService 不接受 null，测试清理用
  *  Symbol 直写；key 与生产 getServiceSlot 的 SERVICE_SLOT_KEY 一致）。 */
 function resetServiceSlot(): void {
-  const slot = Reflect.get(globalThis, Symbol.for("@zhushanwen/pi-subagents.service")) as
+  const slot = Reflect.get(globalThis, Symbol.for(GLOBAL_SLOT_KEYS.service)) as
     | { current: unknown }
     | undefined;
   if (slot) slot.current = null;

package/src/interface/{__tests__ → tool/__tests__}/tool-subagents.test.ts

@@ -142,7 +142,7 @@ interface SharedConstantsModule {
 
 /** 动态 import 真 constants 模块（文本断言会漏「值被改」的漂移，故取真值）。 */
 async function loadSharedConstants(): Promise<SharedConstantsModule> {
-  const url = pathToFileURL(join(__dirname, "../../../../../../packages/shared/src/constants.ts")).href;
+  const url = pathToFileURL(join(__dirname, "../../../../../../../packages/shared/src/constants.ts")).href;
   const mod: Record<string, unknown> = await import(/* @vite-ignore */ url);
   const workflows = mod.WORKFLOW_TOOL_NAMES;
   const subagents = mod.SUBAGENT_TOOL_NAMES;
@@ -213,8 +213,8 @@ describe("schema 契约：一跳扁平 + tasks 必填（D2）", () => {
     expect(TOOL_SRC).toContain("SLUG_MAX_LENGTH");
   });
 
-  it("文件头与 interface/subagents.ts（/subagents 命令壳）互指防混淆", () => {
-    expect(TOOL_SRC).toContain("interface/subagents.ts");
+  it("文件头与 interface/command/subagents.ts（/subagents 命令壳）互指防混淆", () => {
+    expect(TOOL_SRC).toContain("interface/command/subagents.ts");
     // 指认对面是 slash 命令（同名不同命名空间）
     expect(TOOL_SRC.toLowerCase()).toContain("slash");
   });
@@ -239,7 +239,7 @@ describe("schema 契约：一跳扁平 + tasks 必填（D2）", () => {
 });
 
 // ══════════════════════════════════════════════════════════════
-describe("handler 转译：runWorkflow('fan-out') 确定性映射（D3）", () => {
+describe("handler 组装：runWorkflow('fan-out') 确定性映射（D3）", () => {
   it("全参数调用 → spec 逐字段映射（scriptSource/budget/slug/model/thinkingLevel/args）", async () => {
     const registry = makeRegistry();
     const result = await runSubagentsBatch(

package/src/interface/tool/__tests__/tool-workflow-resume.test.ts

@@ -0,0 +1,161 @@
+/**
+ * workflow tool resume action 契约（workflow-run-resume-revision U3 / D14）。
+ *
+ * 覆盖面（[§2.5] D14 判定已下沉 core，本文件只测壳的转发与接线面）：
+ * - 转发契约：args 与 journalDir 原样下传 core（判定与拒绝文案的权威测试在 core
+ *   `orchestration/__tests__/resume-args-guard.test.ts`；真链路拒绝见
+ *   scenario-24-args-mismatch-rejection.test.ts）。
+ * - resumeRun 接线：budgetTimeMs（time 形参透传）/ budgetTokens（tokens 形参透传）/
+ *   host / runId；成功文案与 details。
+ * - runId 缺失与 time/tokens 负值的入口护栏（assertEntryTimeBudget / assertEntryTokenBudget 同源）。
+ *
+ * mock 策略：resume-run 深路径 stub（resumeRun 为 vi.fn——不起锁/IO，只测入口
+ * 面与校验层）；record 流用 mkdtemp 真文件（D14 读取面读真实路径）。范式对齐
+ * tool-workflow.test.ts（lifecycle 深路径 mock + captureTool 注册层黑盒）。
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 被 mock 的模块——import 路径与被测源文件的等值实例（vi.mock hoist 后 barrel
+// re-export 与深路径指向同一 mock 实例，对齐 tool-workflow.test.ts 先例）
+import { resumeRun } from "@zhushanwen/subagent-core/orchestration/resume-run.ts";
+
+import { actionResume } from "../tool-workflow.ts";
+
+/** 桩化 resume-run——resumeRun 为 vi.fn（不起锁/record IO，只测入口校验与接线面）。 */
+vi.mock("@zhushanwen/subagent-core/orchestration/resume-run.ts", () => ({
+  resumeRun: vi.fn(),
+}));
+
+// ── fixture ──────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(() => {
+  vi.mocked(resumeRun).mockReset();
+  vi.mocked(resumeRun).mockResolvedValue("wf-test");
+  tmpDir = mkdtempSync(join(tmpdir(), "u3-resume-"));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  vi.restoreAllMocks();
+});
+
+/** 写 record 流（每行一个 JSON 对象）并返回路径——D14 读取面的真实文件。 */
+function writeRecordStream(lines: unknown[]): string {
+  const path = join(tmpDir, "wf-test.record.jsonl");
+  writeFileSync(path, lines.map((l) => JSON.stringify(l)).join("\n") + "\n", "utf8");
+  return path;
+}
+
+/** run-created 帧（args 含 _runId——对齐 lifecycle runWorkflow 注入后落账形态）。 */
+function runCreatedFrame(argsSummary: string) {
+  return {
+    type: "run-created",
+    seq: 1,
+    ts: 1_700_000_000_000,
+    runId: "wf-test",
+    workflowName: "demo",
+    argsSummary,
+    scriptSource: "// demo",
+  };
+}
+
+/** 最小 deps stub（actionResume 只触 store.stateFilePath 与 resumeRun(deps)）。 */
+function makeDeps(stateFilePath: string): unknown {
+  return {
+    runs: new Map(),
+    store: { stateFilePath: () => stateFilePath },
+    registry: { get: vi.fn(), getPath: vi.fn(), loadAll: vi.fn() },
+  };
+}
+
+// ── actionResume：入口校验与接线 ─────────────────────────────
+
+describe("actionResume", () => {
+  it("runId 缺失 → throw 用法指引（不触 resumeRun）", async () => {
+    await expect(
+      actionResume({ action: "resume" } as never, makeDeps("/nonexistent") as never),
+    ).rejects.toThrow(/resume requires 'runId'/);
+    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
+  });
+
+  it("[§2.5 转发契约] args + journalDir 原样下传（判定在 core；journalDir = store 路径同目录，防双锚）", async () => {
+    const recordPath = join(tmpDir, "wf-test.record.jsonl");
+    const result = (await actionResume(
+      { action: "resume", runId: "wf-test", args: { a: 1 } } as never,
+      makeDeps(recordPath) as never,
+    )) as { content: Array<{ text: string }>; details: Record<string, unknown> };
+    expect(vi.mocked(resumeRun)).toHaveBeenCalledTimes(1);
+    const [calledRunId, , options] = vi.mocked(resumeRun).mock.calls[0]!;
+    expect(calledRunId).toBe("wf-test");
+    expect((options as { args?: unknown }).args).toEqual({ a: 1 });
+    // core 缺省走模块锚；壳必须传 store 同源目录，否则多 session 场景读成「无记录」
+    expect((options as { journalDir?: string }).journalDir).toBe(tmpDir);
+    expect(result.content[0]!.text).toContain("Resuming workflow run wf-test");
+    expect(result.details).toMatchObject({ action: "resume", runId: "wf-test", status: "running" });
+  });
+
+  it("[§2.5 转发契约] args 缺省 → options 不带 args 键（core 侧跳过比对）", async () => {
+    await actionResume(
+      { action: "resume", runId: "wf-test" } as never,
+      makeDeps(join(tmpDir, "missing.record.jsonl")) as never,
+    );
+    expect(vi.mocked(resumeRun)).toHaveBeenCalledTimes(1);
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as Record<string, unknown>;
+    expect("args" in options).toBe(false);
+  });
+
+  it("time 形参透传 budgetTimeMs（u2 偏差②：预算经 D14 同款通道传入）", async () => {
+    const recordPath = writeRecordStream([runCreatedFrame('{"a":1}')]);
+    await actionResume(
+      { action: "resume", runId: "wf-test", args: { a: 1 }, time: 120_000 } as never,
+      makeDeps(recordPath) as never,
+    );
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as { budgetTimeMs?: number };
+    expect(options.budgetTimeMs).toBe(120_000);
+  });
+
+  it("tokens 形参透传 budgetTokens（与 time 同款通道，三档回落与落盘归 core）", async () => {
+    const recordPath = writeRecordStream([runCreatedFrame('{"a":1}')]);
+    await actionResume(
+      { action: "resume", runId: "wf-test", args: { a: 1 }, tokens: 50_000 } as never,
+      makeDeps(recordPath) as never,
+    );
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as { budgetTokens?: number };
+    expect(options.budgetTokens).toBe(50_000);
+  });
+
+  it("tokens 缺省 → options 不带 budgetTokens 键（core 侧跳过覆盖、走三档回落）", async () => {
+    await actionResume(
+      { action: "resume", runId: "wf-test" } as never,
+      makeDeps(join(tmpDir, "missing.record.jsonl")) as never,
+    );
+    const options = vi.mocked(resumeRun).mock.calls[0]![2] as Record<string, unknown>;
+    expect("budgetTokens" in options).toBe(false);
+  });
+
+  it("tokens 负值 → 入口护栏拒绝（与 run action 同源 assertEntryTokenBudget）", async () => {
+    await expect(
+      actionResume(
+        { action: "resume", runId: "wf-test", tokens: -1 } as never,
+        makeDeps("/nonexistent") as never,
+      ),
+    ).rejects.toThrow(/tokens/);
+    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
+  });
+
+  it("time 负值 → 入口护栏拒绝（与 run action 同源 assertEntryTimeBudget）", async () => {
+    await expect(
+      actionResume(
+        { action: "resume", runId: "wf-test", time: -1 } as never,
+        makeDeps("/nonexistent") as never,
+      ),
+    ).rejects.toThrow(/time/);
+    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
+  });
+});

package/src/interface/{__tests__ → tool/__tests__}/tool-workflow.test.ts

@@ -38,6 +38,8 @@ import {
   Trace,
   WorkflowRun,
   WorkflowScriptRegistryImpl,
+  doneReasonToRunOutcome,
+  noteRebuiltSettlement,
   parseResourceMeta,
   setModelConfigService,
 } from "@zhushanwen/subagent-core";
@@ -49,6 +51,9 @@ import {
 // 被 mock 的模块——import 路径与被测源文件的等值实例（vi.mock hoist 后 barrel
 // re-export 与深路径指向同一 mock 实例）
 import { runWorkflow, abortRun } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
+// [D6(a) 第 1 步] 终局记录注册表清零面（换源后 done 判定唯一源 = 注册表，且注册表
+// 按 runId 全局分区——用例间不清零会让复用 runId 的 fixture 跨用例污染）。
+import { setRunEventJournalDirForTest } from "@zhushanwen/subagent-core/orchestration/terminal-actions.ts";
 
 import { actionRun, registerWorkflowTool, TOOL_TOP_LEVEL } from "../tool-workflow.ts";
 import { REENTRY_BUSY_MESSAGE, type ReentryGuardRef } from "../reentry-guard.ts";
@@ -65,6 +70,8 @@ vi.mock("@zhushanwen/subagent-core/orchestration/lifecycle.ts", () => ({
 beforeEach(() => {
   vi.mocked(runWorkflow).mockReset();
   vi.mocked(runWorkflow).mockResolvedValue("run-id-1");
+  // 终局记录注册表清零（setRunEventJournalDirForTest 同实现内清注册表 + 活体态）
+  setRunEventJournalDirForTest(undefined);
 });
 
 afterEach(() => {
@@ -162,7 +169,7 @@ function makeRun(opts: {
   startedAt: string;
   completedAt?: string;
 }): WorkflowRun {
-  return WorkflowRun.reconstruct(
+  const run = WorkflowRun.reconstruct(
     opts.runId,
     {
       scriptSource: "// stub source",
@@ -181,6 +188,16 @@ function makeRun(opts: {
     },
     { startedAt: opts.startedAt, completedAt: opts.completedAt },
   );
+  // [D6(a) 第 1 步] 终局判定源 = 终局记录注册表：done 形态 fixture 建模「重水合
+  // done run」时必须携带注册表条目（生产 = 壳重建点 noteRebuiltSettlement 注入
+  // run-settled 帧事实；settledAt = 快照 completedAt = 帧时序）。
+  if (opts.status === "done") {
+    noteRebuiltSettlement(opts.runId, {
+      outcome: doneReasonToRunOutcome(opts.reason ?? "completed"),
+      settledAt: opts.completedAt !== undefined ? Date.parse(opts.completedAt) : 0,
+    });
+  }
+  return run;
 }
 
 describe("actionStatus 输出形态（LLM 可见文本锁）", () => {
@@ -790,14 +807,18 @@ describe("abort 转移文案全文锚定（LLM 可见文本锁）", () => {
     ) => Promise<AbortResult>;
   };
 
-  /** mock abortRun 落位终态（模拟 lifecycle transition 语义：status=done + 可选 reason）。 */
-  function stubAbortTransition(opts: { reason?: string }): void {
+  /** mock abortRun 落位终态（模拟 lifecycle transition 语义：status=done + 可选 reason）。
+   *  `settle: false` = abort 未产生终局记录（换源后 run 保持 running 投影）。 */
+  function stubAbortTransition(opts: { reason?: string; settle?: boolean }): void {
     vi.mocked(abortRun).mockReset();
     vi.mocked(abortRun).mockImplementation(async (runId, deps) => {
       const run = deps.runs.get(runId);
-      if (run) {
+      if (run && (opts.settle ?? true)) {
         run.state.status = "done";
         run.state.reason = opts.reason;
+        // [D6(a) 第 1 步] 终局判定源 = 终局记录注册表：stub 直改状态须同步注入终局
+        // 事实（生产 abortRun 经 dispatch 链 note）——否则 runSummary 投影回退 running。
+        noteRebuiltSettlement(runId, { outcome: "cancelled", settledAt: Date.now() });
       }
     });
   }
@@ -817,8 +838,11 @@ describe("abort 转移文案全文锚定（LLM 可见文本锁）", () => {
     expect(r.details).toMatchObject({ action: "abort", runId: run.runId, status: "done", reason: "aborted" });
   });
 
-  it("无 reason → 转移段无后缀（reasonSuffix 条件拼接）", async () => {
-    stubAbortTransition({ reason: undefined });
+  it("无终局记录 → 转移段无后缀（reasonSuffix 条件拼接；[D6(a) 第 1 步] 换源后「未终局」不再投影 done/reason）", async () => {
+    // 换源前本用例靠「聚合 done 而注册表 miss」造出 done+无 reason 形态——该形态随
+    // R6 判据换源消失（done ⟺ 注册表有条目 ⟺ reason 由 (outcome,errorCode) 恒派生）。
+    // 现锁同一条拼接分支的可达形态：无终局记录 = 未终局，status 与 reason 都不投影。
+    stubAbortTransition({ settle: false });
     const run = makeRun({
       runId: "wf-1719600000000-z9y8x7",
       scriptName: "cleanup-wf",
@@ -828,8 +852,8 @@ describe("abort 转移文案全文锚定（LLM 可见文本锁）", () => {
     const tool = captureRegisteredTool<AbortToolView>(new Map([[run.runId, run]]));
 
     const r = await tool.execute("id", { action: "abort", runId: run.runId }, undefined, undefined, {});
-    expect(r.content[0]?.text).toBe("Workflow 'cleanup-wf' (wf-1719600000000-z9y8x7): running → done");
-    expect(r.details).toMatchObject({ action: "abort", runId: run.runId, status: "done" });
+    expect(r.content[0]?.text).toBe("Workflow 'cleanup-wf' (wf-1719600000000-z9y8x7): running → running");
+    expect(r.details).toMatchObject({ action: "abort", runId: run.runId, status: "running" });
   });
 });
 
@@ -847,7 +871,7 @@ function rflParams(): object {
   const src = readFileSync(
     join(
       __dirname,
-      "../../../node_modules/@zhushanwen/subagent-core/workflows/review-fix-loop.js",
+      "../../../../node_modules/@zhushanwen/subagent-core/workflows/review-fix-loop.js",
     ),
     "utf-8",
   );

package/src/interface/{subagent-tool-schema.ts → tool/subagent-tool-schema.ts}

@@ -1,4 +1,4 @@
-// src/interface/subagent-tool-schema.ts
+// src/interface/tool/subagent-tool-schema.ts
 //
 // `subagent` 工具的参数 schema 纯常量叶子（零运行时依赖）。
 //

package/src/interface/{subagent-tool.ts → tool/subagent-tool.ts}

@@ -1,4 +1,4 @@
-// src/interface/subagent-tool.ts
+// src/interface/tool/subagent-tool.ts
 //
 // `subagent` LLM 工具。薄壳——参数解析 + 调 runtime.execute。
 // 不创建 state、不节流 onUpdate、不持久化（全部在 runtime 层统一）。
@@ -27,9 +27,9 @@ import {
   messageHandler,
   startHandler,
 } from "@zhushanwen/subagent-core";
-import { extractAgentName } from "./format.ts";
-import { toGuiCtx } from "./gui-mappers.ts";
-import { adapter } from "./subagent-actions.ts";
+import { extractAgentName } from "../format/format.ts";
+import { toGuiCtx } from "../gui/gui-mappers.ts";
+import { adapter } from "../gui/subagent-actions.ts";
 import { SubagentParams } from "./subagent-tool-schema.ts";
 import { type RenderContext,renderSubagentCall, renderSubagentResult } from "./tool-render.ts";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";

package/src/interface/{tool-render.ts → tool/tool-render.ts}

@@ -1,4 +1,4 @@
-// src/interface/tool-render.ts
+// src/interface/tool/tool-render.ts
 //
 // 对话流 tool block 渲染。renderCall（标题行）+ renderResult（背景色 block）。
 //
@@ -32,8 +32,8 @@ import {
   formatElapsedSeconds,
   statusGlyph,
   type ThemeLike,
-} from "./format.ts";
-import { truncLine } from "./tui-kit.ts";
+} from "../format/format.ts";
+import { truncLine } from "../tui/tui-kit.ts";
 
 // ============================================================
 // 常量

package/src/interface/{tool-shared.ts → tool/tool-shared.ts}

@@ -29,7 +29,7 @@ import type { GuiComponent, GuiContext, GuiRenderResult } from "@zhushanwen/exte
 import { guiResult, isGuiCapable } from "@zhushanwen/extension-protocol";
 import type { RunSpec, WorkflowScript } from "@zhushanwen/subagent-core";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
-import { renderTextFallback } from "./format.ts";
+import { renderTextFallback } from "../format/format.ts";
 
 /** renderResult 回调的宽入参形态（content 可缺省，由 renderTextFallback 兜底）。 */
 export interface RenderableToolResult {