@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/__tests__/subprocess-agent-runner.test.ts

@@ -29,6 +29,13 @@ import type { AgentCallOpts, AgentResult } from "../../orchestration/models/type
 import { ModelConfigService, setModelConfigService } from "../model-config-service.ts";
 import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
 import { replayJournal } from "../engine/common/event-journal.ts";
+import { clearEngines, registerEngine } from "../engine/registry.ts";
+import type { EnginePort, RunContext } from "../engine/port.ts";
+import type {
+  AgentOutcome,
+  EngineCapabilities,
+  ProbeReport,
+} from "../engine/types.ts";
 import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
 import type { SubagentService } from "../subagent-service.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
@@ -48,9 +55,41 @@ function makeMockResult(overrides: Partial<AgentResult> = {}): AgentResult {
   };
 }
 
+/** 协议替身的引擎内「任务声明 → 执行选项」映射（原 core PiEngine
+ *  agentCallToExecuteOptions 的最小同构还原——[W3] 该映射本体已随 inproc pi 引擎目录 迁入
+ *  pi-subagent-cli 引擎包，此处仅为保留 executeAndAwait 委托断言面）。 */
+function fakeAgentCallToExecuteOptions(task: AgentCallOpts, ctxModel?: ModelInfo): Record<string, unknown> {
+  const rawSlug = task.description ?? task.agent ?? "workflow-agent";
+  return {
+    task: task.prompt,
+    slug: rawSlug.length > 35 ? rawSlug.slice(0, 35) : rawSlug,
+    agent: task.agent,
+    model: task.model,
+    thinkingLevel: task.thinkingLevel,
+    skillPath: task.skillPath,
+    appendSystemPrompt: task.appendSystemPrompt,
+    schema: task.schema,
+    schemaEnv: task.schemaEnv,
+    maxTurns: task.maxTurns,
+    graceTurns: task.graceTurns,
+    ctxModel,
+    fork: task.fork,
+    worktree: task.worktree,
+    cwd: task.cwd,
+    conversation: task.conversation,
+    idleTimeoutMs: task.idleTimeoutMs,
+  };
+}
+
+/** 引擎 run 捕获面（T3.19 直传保真断言用：SAR → engine.run 的 task 原样性）。 */
+const engineRunSpy = vi.fn();
+
 /** 创建 mock SubagentService（只实现 executeAndAwait）。
- *  [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取 PiEngineService——fake 的
- *  face 即自身，getter 直接返回 self。 */
+ *  [D4 聚合连带] SAR 构造器经 asEngineService 显式视图取引擎服务面——fake 的 face
+ *  即自身，getter 直接返回 self。
+ *  [W3 改写] 同步注册「委托式」替身 pi 引擎：run() 还原引擎内 task→ExecuteOptions
+ *  映射后委托 mock 的 executeAndAwait（原 inproc PiEngine 的 workflow 分支形态）——
+ *  resolveHostPiEnginePort 对已注册 port 原样返回，SAR 路由命中替身。 */
 function createMockService(impl?: typeof vi.fn): SubagentService {
   const executeAndAwait = impl ?? vi.fn().mockResolvedValue(makeMockResult());
   // partial mock（仅 executeAndAwait + asEngineService self-引用）——SAR 测试路径
@@ -58,6 +97,50 @@ function createMockService(impl?: typeof vi.fn): SubagentService {
   const partial: { executeAndAwait: typeof executeAndAwait; asEngineService?: unknown } = { executeAndAwait };
   const service = partial as unknown as SubagentService;
   partial.asEngineService = service;
+
+  const fakePort: EnginePort = {
+    id: "pi",
+    capabilities: (): EngineCapabilities => ({
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "native",
+      personaInjection: "flag",
+      eventGranularity: "stream",
+      sandbox: "emulated",
+      sessionRead: "full",
+      resume: "native",
+      interrupt: "kill-only",
+      permissionMode: "native",
+      maxTurns: true,
+    }),
+    probe: async (): Promise<ProbeReport> => ({ ok: true, engineVersion: "fake", checks: [] }),
+    run: async (task: AgentCallOpts, ctx: RunContext) => {
+      engineRunSpy(task, ctx);
+      const wfResult = await executeAndAwait(
+        fakeAgentCallToExecuteOptions(task, ctx.ctxModel),
+        ctx.signal,
+        ctx.onEvent,
+        ctx.stream,
+      ) as { content: string; parsedOutput?: unknown; durationMs?: number; error?: string };
+      const outcome: AgentOutcome = {
+        content: wfResult.content,
+        parsedOutput: wfResult.parsedOutput,
+        durationMs: wfResult.durationMs,
+        error: wfResult.error,
+        engineId: "pi",
+      };
+      return {
+        handle: {
+          data: { v: 1, engineId: "pi", sessionRef: {}, poolKey: "shared", adapterVersion: "fake-sar" },
+        },
+        outcome,
+      };
+    },
+    interact: async () => ({ ok: false, code: "engine_interact_failed", message: "not supported in this test" }),
+    read: async () => ({ engineId: "pi", turns: [], source: "outcome-only" }),
+  };
+  clearEngines();
+  registerEngine("pi", () => fakePort);
   return service;
 }
 
@@ -83,6 +166,9 @@ function makeBaseOpts(): AgentCallOpts {
 describe("SubprocessAgentRunner (wave-4 delegate)", () => {
   beforeEach(() => {
     configureCore({ dataRoot: () => "/fake-sar-data-root", log: () => {} });
+    // [U-2 一致性修复] pi 未注册时 resolveHostPiEnginePort 返回 engine_not_found stub
+    // ——替身 pi 引擎在 createMockService 内按测试服务注册（[W3] 委托式协议替身）。
+    engineRunSpy.mockClear();
   });
 
   afterEach(() => {
@@ -441,7 +527,7 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
         const workflowOnEvent = vi.fn();
         await sar.run(makeBaseOpts(), new AbortController().signal, workflowOnEvent);
 
-        // journal 落在 <dataDir>/engines/pi/shared/journal-<taskId>.jsonl
+        // journal 落在 <dataDir>/inproc pi 引擎目录/shared/journal-<taskId>.jsonl
         const journalFile = join(dataDir, "engines", "pi", "shared");
         const files = readdirSync(journalFile).filter((f) => f.startsWith("journal-") && f.endsWith(".jsonl"));
         expect(files.length).toBe(1);
@@ -491,17 +577,14 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
   });
 
   // ────────────────────────────────────────────────
-  // T3.19: AgentCallOpts → ExecuteOptions 映射保真
+  // T3.19: SAR → engine.run 任务声明直传保真
+  //   [W3 改写] 「AgentCallOpts → ExecuteOptions 映射点在 PiEngine 边界」随 inproc pi 引擎目录
+  //   删除迁入 pi-subagent-cli（引擎包 spawn-args 测试守护）；core 侧存留契约 =
+  //   SAR 对 AgentCallOpts 直传零映射（engine.run 的 task 原样性）。
   // ────────────────────────────────────────────────
-  describe("T3.19 直出保真（D6：映射点在 PiEngine.agentCallToExecuteOptions，SAR 直传零映射）", () => {
-    it("prompt → task, agent → agent, schemaEnv 透传（经 pi 边界直出）", async () => {
-      let capturedOpts: Record<string, unknown> | undefined;
-      const mockService = createMockService(
-        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
-          capturedOpts = opts;
-          return Promise.resolve(makeMockResult());
-        }),
-      );
+  describe("T3.19 直传保真（D6：SAR 直传零映射，任务声明原样到达 engine.run）", () => {
+    it("prompt/agent/skillPath/schemaEnv 原样到达 engine.run", async () => {
+      const mockService = createMockService();
       const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
       const sar = new SubprocessAgentRunner(deps);
 
@@ -514,35 +597,24 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       };
       await sar.run(opts, new AbortController().signal);
 
-      expect(capturedOpts).toBeDefined();
-      expect(capturedOpts!.task).toBe("do the thing");
-      expect(capturedOpts!.agent).toBe("code-reviewer");
-      expect(capturedOpts!.skillPath).toBe("/skills/code-review.md");
-      // schemaEnv 应通过 ExecuteOptions 透传
-      expect((capturedOpts as Record<string, unknown>).schemaEnv).toBe('{"type":"object"}');
+      expect(engineRunSpy).toHaveBeenCalledTimes(1);
+      const [task] = engineRunSpy.mock.calls[0] as [AgentCallOpts, unknown];
+      expect(task.prompt).toBe("do the thing");
+      expect(task.agent).toBe("code-reviewer");
+      expect(task.skillPath).toBe("/skills/code-review.md");
+      expect(task.schemaEnv).toBe('{"type":"object"}');
     });
 
-    it("schema 透传为原始对象", async () => {
-      let capturedOpts: Record<string, unknown> | undefined;
-      const mockService = createMockService(
-        vi.fn().mockImplementation((opts: Record<string, unknown>) => {
-          capturedOpts = opts;
-          return Promise.resolve(makeMockResult());
-        }),
-      );
+    it("schema 原样透传为原始对象", async () => {
+      const mockService = createMockService();
       const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
       const sar = new SubprocessAgentRunner(deps);
 
-      const opts = {
-        ...makeBaseOpts(),
-        schema: { type: "object", properties: { name: { type: "string" } } },
-      };
-      await sar.run(opts, new AbortController().signal);
+      const schema = { type: "object", properties: { name: { type: "string" } } };
+      await sar.run({ ...makeBaseOpts(), schema }, new AbortController().signal);
 
-      expect(capturedOpts!.schema).toEqual({
-        type: "object",
-        properties: { name: { type: "string" } },
-      });
+      const [task] = engineRunSpy.mock.calls[0] as [AgentCallOpts, unknown];
+      expect(task.schema).toEqual(schema);
     });
   });
 

package/src/execution/__tests__/sync-collect-recovery.test.ts

@@ -62,35 +62,18 @@ import * as path from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 
-const { loggerMock, runSpawnMock } = vi.hoisted(() => ({
+const { loggerMock } = vi.hoisted(() => ({
   loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn(), info: vi.fn() },
-  runSpawnMock: vi.fn(async () => ({
-    text: "ok",
-    turns: 1,
-    durationMs: 10,
-    success: true,
-    sessionId: "spawned",
-    toolCalls: [],
-  })),
 }));
 // mock logger：路径从 __tests__ 出发是 ../../core/（src/core/logger.ts——subagent-service
 // 经 ../core/logger.ts 引用的同一模块）。曾写 ../core/logger.ts 指向不存在的
 // src/execution/core/，vi.mock 静默失效（D4 上限用例首次断言日志时暴露）。
 vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
 
-// mock session-runner：execute 链经 kickOffBackground → runAndFinalize → runSpawn。
-// 路径必须命中生产 import 的真实模块——merge 后 session-runner 落位
-// src/execution/engine/engines/pi/session-runner.ts（subagent-service.ts 的 import 源），
-// 旧路径 "../session-runner.ts" 模块已不存在，拦截静默失效（U2 教训的变体：
-// 相对路径「层级」与「落位」都可能漂移，见 collect-coordinator-service.test.ts）。
-vi.mock("../engine/engines/pi/session-runner.ts", () => ({
-  runSpawn: runSpawnMock,
-  killAllSpawnedChildren: vi.fn(),
-  killRecordChildWithEscalation: vi.fn(),
-  getChildByRecord: vi.fn(() => undefined),
-  registerSpawnedChildForRecord: vi.fn(),
-  spawnedChildren: new Map(),
-}));
+// [W3 改写] mock session-runner（execute 链 runSpawn 替身）随 inproc pi 引擎目录 删除消亡——
+// execute 链改为协议 seam（registerFakePiEngine 替身 + 显式 settle 应答）。
+import { registerFakePiEngine, type FakePiEnginePort } from "./helpers/fake-engine-port.ts";
+import { clearEngines } from "../engine/registry.ts";
 
 import { SUBAGENT_RECORD_CUSTOM_TYPE } from "../record-entry.ts";
 import { ManifestStore } from "../manifest-store.ts";
@@ -275,6 +258,12 @@ describe("sync collect recovery (U5 E1/E9) — 真实文件通路", () => {
 
   /** 恢复侧 service：断言 pi（覆写不落盘，断言内存面）/ 写文件 pi（覆写真实落盘，
    *  E1 读覆写后末条——kill -9 真实链路同构）两用。 */
+  /** [W3] 协议替身注册（per-test 调用；afterEach clearEngines 统一清理）。 */
+  function makeRecoveryFake(): FakePiEnginePort {
+    clearEngines();
+    return registerFakePiEngine();
+  }
+
   function makeRecoveryService(pi: AssertPi | WritingPi): SubagentService {
     const modelService = new ModelConfigService({ agentDir, cwd: agentDir });
     const modelRegistry: ModelRegistryLike = {
@@ -564,15 +553,13 @@ describe("sync collect recovery (U5 E1/E9) — 真实文件通路", () => {
 
   it("E9 dispose：缓冲终态成员逐条转 async notify + 落标；在跑成员走现有退出路径（不通知）", async () => {
     // 复用 execute 真链：成员 1 受控终态（入缓冲后批因成员 2 在跑不闭合），成员 2 悬置 running
-    let resolve1!: (v: { text: string; turns: number; durationMs: number; success: boolean; sessionId: string; toolCalls: [] }) => void;
-    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolve1 = res; }));
-    runSpawnMock.mockImplementationOnce(() => new Promise(() => { /* 悬置到 dispose */ }));
+    const fake = makeRecoveryFake();
     const pi = makeAssertPi();
     const service = makeRecoveryService(pi);
     const spy = spyNotifier(service);
     const h1 = await service.execute({ task: "terminal one", slug: "one", collect: "sync" });
     await service.execute({ task: "running two", slug: "two", collect: "sync" });
-    await until(() => runSpawnMock.mock.calls.length >= 2);
+    await until(() => fake.runs.length >= 2);
 
     // 成员 1 子文件就位（E9 落标 getFullRecord 冷路径数据源）
     const sessionsDir = getSubagentSessionDir(agentDir, agentDir);
@@ -599,9 +586,10 @@ describe("sync collect recovery (U5 E1/E9) — 真实文件通路", () => {
     );
 
     // 成员 1 终态：入缓冲，成员 2 在跑 → 批不闭合（零批投递）
-    resolve1({ text: "ok-terminal", turns: 1, durationMs: 10, success: true, sessionId: "spawned", toolCalls: [] });
-    await until(() => spy.notify.mock.calls.length + spy.notifyBatch.mock.calls.length > 0 || runSpawnMock.mock.calls.length >= 2);
-    await new Promise((resolve) => setTimeout(resolve, 50)); // microtask 链排空
+    fake.runs[0]!.settle({ content: "ok-terminal" });
+    // 等 settle 收尾链排空（finalize→route 入缓冲；成员 2 悬置 → 零投递）
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(spy.notify.mock.calls.length + spy.notifyBatch.mock.calls.length).toBe(0);
     expect(spy.notifyBatch).not.toHaveBeenCalled();
 
     // dispose（E9）：成员 1 逐条转 async 写账 + 落标；成员 2 不通知（现有退出路径）
@@ -1071,23 +1059,20 @@ describe("sync collect recovery (U5 E1/E9) — 真实文件通路", () => {
     // 成员 1：失败终态（archive 出内存）且不写子文件 → getFullRecord 双 miss
     //（内存已出 + 子文件缺失——子文件被 GC/删除的窗口形态）；
     // 成员 2：SP-5 成功回退（留内存）→ getFullRecord 内存命中（正常落标对照）。
-    let resolve1!: (v: { text: string; turns: number; durationMs: number; success: boolean; sessionId: string; toolCalls: [] }) => void;
-    let resolve2!: (v: { text: string; turns: number; durationMs: number; success: boolean; sessionId: string; toolCalls: [] }) => void;
-    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolve1 = res; }));
-    runSpawnMock.mockImplementationOnce(() => new Promise((res) => { resolve2 = res; }));
+    const fake = makeRecoveryFake();
     // 写文件 pi：标记 entry 真实落盘主文件，E1 扫描通路（rebuildEntryRecord）可重解析
     const pi = makeWritingPi(mainFile);
     const service = makeRecoveryService(pi);
     const spy = spyNotifier(service);
     const h1 = await service.execute({ task: "miss one", slug: "one", collect: "sync" });
     const h2 = await service.execute({ task: "full two", slug: "two", collect: "sync" });
-    await until(() => runSpawnMock.mock.calls.length >= 2);
+    await until(() => fake.runs.length >= 2);
 
     // 成员 1 子文件故意缺失（getFullRecord miss 前提）；成员 2 内存命中不依赖子文件。
     // 注：两成员的 settle 链竞态可能拆两批（[U8] 合批窗口形态）——S11 断言与批切分
     // 无关，只锁「批成员并集覆盖」与「miss 成员兜底落标」。
-    resolve1({ text: "boom-miss", turns: 1, durationMs: 10, success: false, sessionId: "spawned", toolCalls: [] });
-    resolve2({ text: "ok-full", turns: 1, durationMs: 10, success: true, sessionId: "spawned", toolCalls: [] });
+    fake.runs[0]!.settle({ content: "boom-miss", error: "boom-miss" });
+    fake.runs[1]!.settle({ content: "ok-full" });
     await until(() => spy.notifyBatch.mock.calls.length > 0);
     await new Promise((resolve) => setTimeout(resolve, 50)); // flushBatch 落标同步链排空
 

package/src/execution/__tests__/workflow-state-root.test.ts

@@ -0,0 +1,232 @@
+// src/execution/__tests__/workflow-state-root.test.ts
+//
+// [F-1 修复] pi 宿主 WorkflowRun state 读侧装配同源布局测试。
+//
+// 背景（装配错位事故面）：round-supervisor sweep 与 idle-gc 曾用 FileRunStore 缺省根
+// `<dataRoot>/workflow-state`（zcode 宿主布局）读 workflow run state，而 pi 宿主真实
+// 落盘 = JsonlRunStore 的 `<sessionDir>/workflow-state/<runId>.jsonl`——两目录生产不
+// 相交 → findStateByIdSync 恒 missing → sweep 按终态补注销**活跃 run**；WorkflowRun
+// GC 恒空转。修复后装配点传 resolvePiWorkflowStateDir()（execution/workflow-state-root.ts，
+// 与 extensions/universal/subagent-workflow/src/session-lifecycle.ts resolveSessionDir
+// 同规则重写）。
+//
+// 本套件用 mkdtemp 真实目录布局（非 mock fs）证明四件事：
+//   ① resolvePiWorkflowStateDir 探测语义两分支（sessionScopedDir 存在/不存在）；
+//   ② FileRunStore({stateDir}) findStateByIdSync 在真实布局命中 running/终态/missing；
+//   ③ sweep 装配链（runPendingReconcileSweepForService，env 指向 tmp agentDir）端到端：
+//      running run 不补注销（修复前被误注销的事故方向）、终态 run 补注销；
+//   ④ idle-gc 同布局：30 天 running run 文件被终态化写回（findStateByIdSync 变 done）。
+//
+// 写删目标全部 mkdtempSync 自建自删（禁触真实数据目录纪律）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { FileRunStore } from "../../orchestration/file-run-store.ts";
+import { Budget } from "../../orchestration/models/budget.ts";
+import { Trace } from "../../orchestration/models/trace.ts";
+import { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
+import { startIdleGc } from "../idle-gc.ts";
+import { RecordStore } from "../record-store.ts";
+import { runPendingReconcileSweepForService } from "../round-supervisor/service-binding.ts";
+import type { RoundSupervisorBinding } from "../round-supervisor/service-binding.ts";
+import { resolvePiWorkflowStateDir } from "../workflow-state-root.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+
+let tmpDir: string;
+let stopGc: (() => void) | undefined;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-state-root-"));
+});
+
+afterEach(() => {
+  stopGc?.();
+  stopGc = undefined;
+  vi.unstubAllEnvs();
+  vi.useRealTimers();
+  fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+});
+
+/** 与 session-lifecycle.resolveSessionDir 同规则的 cwd-slug（测试构造期望布局用）。 */
+function slugOf(cwd: string): string {
+  return `--${cwd.replace(/^\//, "").replace(/\//g, "-")}--`;
+}
+
+/** 构造可持久化的 WorkflowRun（对齐 file-run-store.test.ts makeRun 模式）。 */
+function makeRun(
+  runId: string,
+  opts: { status?: "running" | "done"; startedAt?: string } = {},
+): WorkflowRun {
+  const status = opts.status ?? "running";
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "export function execute() { return 'ok'; }",
+      args: { topic: "demo" },
+      scriptName: "test-script",
+      scriptPath: "/fake/test.js",
+      parameters: { type: "object" },
+      budgetTokens: 1000,
+    },
+    {
+      status,
+      ...(status === "done" ? { reason: "completed" as const } : {}),
+      budget: new Budget({ maxTokens: 1000, usedTokens: 1, usedCost: 0, totalCallCount: 1 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+      scriptResult: undefined,
+    },
+    { startedAt: opts.startedAt ?? "2026-08-30T00:00:00.000Z" },
+  );
+}
+
+describe("resolvePiWorkflowStateDir 探测语义（session-lifecycle resolveSessionDir 同规则）", () => {
+  it("sessionScopedDir 存在 → 用 <agentDir>/sessions/<slug>/workflow-state（实例隔离布局）", () => {
+    const cwd = path.join(tmpDir, "proj"); // 形式 cwd（不要求真实存在）
+    const agentDir = path.join(tmpDir, "agent");
+    const sessionScopedDir = path.join(agentDir, "sessions", slugOf(cwd));
+    fs.mkdirSync(sessionScopedDir, { recursive: true });
+    expect(resolvePiWorkflowStateDir({ agentDir, cwd })).toBe(path.join(sessionScopedDir, "workflow-state"));
+  });
+
+  it("sessionScopedDir 不存在 → 回退 <agentDir>/workflow-state（JsonlRunStore 首写 mkdir 的根布局）", () => {
+    const agentDir = path.join(tmpDir, "agent");
+    fs.mkdirSync(agentDir, { recursive: true });
+    expect(resolvePiWorkflowStateDir({ agentDir, cwd: path.join(tmpDir, "fresh-proj") })).toBe(
+      path.join(agentDir, "workflow-state"),
+    );
+  });
+});
+
+describe("FileRunStore({stateDir}) × 真实 JsonlRunStore 布局（findStateByIdSync 读侧判据）", () => {
+  it("真实布局命中：running → {kind:running}；done → {kind:terminal, reason}；无文件 → {kind:missing}", async () => {
+    const stateDir = path.join(tmpDir, "sessions", slugOf("/x/y"), "workflow-state");
+    const store = new FileRunStore({ stateDir });
+    await store.save(makeRun("wf-live")); // running（首写不节流）
+    await store.save(makeRun("wf-done", { status: "done" }));
+
+    expect(store.findStateByIdSync("wf-live")).toEqual({ kind: "running" });
+    expect(store.findStateByIdSync("wf-done")).toEqual({ kind: "terminal", reason: "completed" });
+    expect(store.findStateByIdSync("wf-never")).toEqual({ kind: "missing" });
+    // 落盘路径形状与 pi 壳 JsonlRunStore 同构：<sessionDir>/workflow-state/<runId>.jsonl
+    expect(fs.existsSync(path.join(stateDir, "wf-live.jsonl"))).toBe(true);
+  });
+});
+
+describe("sweep 装配链端到端（runPendingReconcileSweepForService × 真实布局）", () => {
+  /**
+   * 装配 harness：env 指向 tmp agentDir（生产装配 resolvePiWorkflowStateDir() 无参走
+   * env + process.cwd()），run state 由 FileRunStore({stateDir}) 写入解析出的目录——
+   * 证明「生产装配点读的目录 = run state 真实落盘目录」（同源布局闭环）。
+   */
+  function setupSweep(): { agentDir: string; store: FileRunStore } {
+    const agentDir = path.join(tmpDir, "agent");
+    vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+    const store = new FileRunStore({ stateDir: resolvePiWorkflowStateDir() }); // 与生产装配同参
+    return { agentDir, store };
+  }
+
+  function makeBinding(sessionFile: string, appended: Array<{ customType: string; data: unknown }>): RoundSupervisorBinding {
+    return {
+      getStore: () => new RecordStore(path.join(tmpDir, "records")),
+      getPi: () =>
+        ({
+          appendEntry: (type: string, data: unknown) => appended.push({ customType: type, data }),
+          events: { emit: vi.fn() },
+          sendMessage: vi.fn(),
+        }) as unknown as NonNullable<ReturnType<RoundSupervisorBinding["getPi"]>>,
+      getSessionRootId: () => "root",
+      getMainSessionFile: () => sessionFile,
+      finalizeClosed: vi.fn(),
+    };
+  }
+
+  function writeRegister(sessionFile: string, id: string): void {
+    fs.writeFileSync(
+      sessionFile,
+      JSON.stringify({ customType: "pending:register", data: { id, type: "workflow", name: id } }) + "\n",
+      "utf-8",
+    );
+  }
+
+  it("活跃 workflow run（running state 文件在盘）→ sweep 不补注销（修复前被误注销）", async () => {
+    const { agentDir, store } = setupSweep();
+    await store.save(makeRun("wf-live"));
+
+    const sessionFile = path.join(agentDir, "main-session.jsonl");
+    writeRegister(sessionFile, "wf-live");
+    const appended: Array<{ customType: string; data: unknown }> = [];
+    runPendingReconcileSweepForService(makeBinding(sessionFile, appended), false);
+    expect(appended).toHaveLength(0); // 活跃 run 不注销——事故方向的回归钉
+  });
+
+  it("终态 workflow run（done state 文件在盘）→ sweep 补注销（reason 取 run reason）", async () => {
+    const { agentDir, store } = setupSweep();
+    await store.save(makeRun("wf-done", { status: "done" }));
+
+    const sessionFile = path.join(agentDir, "main-session.jsonl");
+    writeRegister(sessionFile, "wf-done");
+    const appended: Array<{ customType: string; data: unknown }> = [];
+    runPendingReconcileSweepForService(makeBinding(sessionFile, appended), false);
+    expect(appended).toEqual([
+      { customType: "pending:unregister", data: { id: "wf-done", reason: "completed", status: "completed" } },
+    ]);
+  });
+});
+
+describe("idle-gc 同布局（WorkflowRun GC 读对根）", () => {
+  /**
+   * GC interval 用 fake timers 推进；但 gcWorkflowRuns 的 loadAll/save 是**真实 fs IO**
+   * （libuv 线程池回调不属被 fake 的 timer API）——推进后经 setImmediate（toFake 排除，
+   * 保持真实调度）反复让出事件循环排空在途 IO。
+   */
+  async function flushRealIo(): Promise<void> {
+    for (let i = 0; i < 50; i++) {
+      await new Promise<void>((resolve) => setImmediate(() => resolve()));
+    }
+  }
+
+  it("真实布局 30 天 running run → GC 终态化写回（findStateByIdSync 变 terminal/time_limited）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval"] });
+    const agentDir = path.join(tmpDir, "agent");
+    const cwd = path.join(tmpDir, "proj");
+    const sessionScopedDir = path.join(agentDir, "sessions", slugOf(cwd));
+    fs.mkdirSync(sessionScopedDir, { recursive: true });
+    const stateDir = resolvePiWorkflowStateDir({ agentDir, cwd });
+    const runStore = new FileRunStore({ stateDir });
+    await runStore.save(
+      makeRun("wf-stale", { startedAt: new Date(Date.now() - 31 * DAY_MS).toISOString() }),
+    );
+    expect(runStore.findStateByIdSync("wf-stale")).toEqual({ kind: "running" });
+
+    stopGc = startIdleGc(new RecordStore(path.join(tmpDir, "records")), runStore);
+    await vi.advanceTimersByTimeAsync(GC_INTERVAL_MS + 1);
+    await flushRealIo();
+
+    // 终态已落盘（同目录 append 终态快照行）——GC 读侧与落盘侧同根闭环
+    expect(runStore.findStateByIdSync("wf-stale")).toEqual({ kind: "terminal", reason: "time_limited" });
+  });
+
+  it("窗内 running run 不动（GC 判据在正确根上按 startedAt 生效）", async () => {
+    vi.useFakeTimers({ toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval"] });
+    const agentDir = path.join(tmpDir, "agent");
+    const stateDir = resolvePiWorkflowStateDir({ agentDir, cwd: tmpDir });
+    const runStore = new FileRunStore({ stateDir });
+    await runStore.save(
+      makeRun("wf-fresh", { startedAt: new Date(Date.now() - 1 * DAY_MS).toISOString() }),
+    );
+
+    stopGc = startIdleGc(new RecordStore(path.join(tmpDir, "records")), runStore);
+    await vi.advanceTimersByTimeAsync(GC_INTERVAL_MS + 1);
+    await flushRealIo();
+
+    expect(runStore.findStateByIdSync("wf-fresh")).toEqual({ kind: "running" });
+  });
+});

package/src/execution/agent-registry.ts

@@ -20,7 +20,10 @@ import { parseResourceMeta } from "../shared/meta-parser.ts";
 import { lintAgentMeta } from "../orchestration/script-lint.ts";
 import type { AgentMeta, RoutingExample } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
-import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
+import { EngineNotFoundError, listEngines } from "./engine/registry.ts";
+// [W8] 存在性校验经补扫通道（快照未命中触发一次三级补扫，W4 ensureEngineDiscovered
+// 语义——宿主未接线补扫参数时与裸 hasEngine 等价）。
+import { hasEngineWithRescan } from "./engine/routing.ts";
 
 const logger = getLogger("subagents");
 
@@ -134,7 +137,8 @@ function resolveAgentEngine(
   filePath: string,
 ): string | undefined {
   const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
-  if (engine !== undefined && !hasEngine(engine)) {
+  // [W8] 补扫通道：快照未命中先一次三级补扫再判（装了引擎包 → 下次解析即可用）。
+  if (engine !== undefined && !hasEngineWithRescan(engine)) {
     throw new EngineNotFoundError(engine, listEngines(), filePath);
   }
   return engine;

package/src/execution/dialog-queue.ts

@@ -84,79 +84,12 @@ function dialogTimeoutLogMessage(req: UiRequest, waitedMs: number): string {
   );
 }
 
-// ── 类型定义（本模块是 UiRequest/UiResponse/UiRequestHandler 的规范来源） ──
-// session-runner.ts 和 ui-channels.ts 复用这些类型（session-runner 再导出供测试 import）。
-
-/** Pi extension_ui_request 的方法枚举（dialog + fire-and-forget 两类）。
- *  dialog 类：select/confirm/input/editor（占输入焦点，等响应）。
- *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
- *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
-export type UiMethod =
-  | "select"
-  | "confirm"
-  | "input"
-  | "editor"
-  | "notify"
-  | "setStatus"
-  | "setWidget"
-  | "setTitle"
-  | "set_editor_text"
-  | (string & {});
-
-/** UI 请求（session-runner 构造后传给 handler）。
- *
- *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
- *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
- *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
- *
- *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
-export interface UiRequest {
-  /** Pi rpc-types.ts 的 method（select/confirm/input/editor 为 dialog 类）。 */
-  method: UiMethod;
-  /** 请求 id（从 extension_ui_request envelope 顶层提取，用于 response 关联）。 */
-  id: string;
-  // method 特定字段（按 method 可选，与 ExtensionUiRequest 1:1）
-  title?: string;
-  options?: string[];
-  message?: string;
-  placeholder?: string;
-  prefill?: string;
-  notifyType?: string;
-  statusKey?: string;
-  statusText?: string | undefined;
-  widgetKey?: string;
-  widgetLines?: string[] | undefined;
-  widgetPlacement?: "aboveEditor" | "belowEditor";
-  text?: string;
-  timeout?: number;
-  /** channel 名（从 method 对应字段的 NUL 前缀解析）。
-   *  select → 从 title 解析；setWidget → 从 widgetLines[0] 解析；其他 → undefined。
-   *  已知值："ask_user"（select）、"gui_widget"（setWidget）。handler 按 channel 分发。 */
-  channel?: string;
-  /** channel 解析后的结构化 payload（已 JSON.parse）。
-   *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
-  channelPayload?: unknown;
-  /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
-   *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
-   *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
-  _childPid?: number;
-}
-
-/** UI 响应（handler 返回，session-runner 按 shape 回写 stdin）。
- *  - {value}: select/input/editor 的答案
- *  - {confirmed}: confirm 的答案
- *  - {cancelled}: 取消（child close / handler 抛错 / 用户取消）
- *  - {ack}: fire-and-forget（当前不透传到 TUI，留作协议完整） */
-export type UiResponse =
-  | { value: string }
-  | { confirmed: boolean }
-  | { cancelled: true }
-  | { ack: true };
-
-/** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
- *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
- *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
-export type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
+// ── 类型再导出（W7 / R3 S-A + R4-S③：SSOT 迁 @zhushanwen/subagent-engine-sdk
+// src/ui-types.ts，结构等价；队列实现本体留 core——壳侧 host/askUser 消费端与
+// inproc 过渡链路同样消费该类型面。双向可赋值断言挂本包 typecheck 断言族
+// （contract-closure），漂移编译期可抓。 ──
+export type { UiMethod, UiRequest, UiRequestHandler, UiResponse } from "@zhushanwen/subagent-engine-sdk";
+import type { UiRequest, UiRequestHandler, UiResponse } from "@zhushanwen/subagent-engine-sdk";
 
 // ── DialogGlobalQueue 实现 ──