@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.1

package/src/execution/__tests__/index-session-start.test.ts

@@ -0,0 +1,342 @@
+// src/execution/__tests__/index-session-start.test.ts
+//
+// C2 critical: index.ts session_start 的 UI handler 注入链路测试。
+//
+// 测试目标：验证 `subagentsWorkflowExtension(pi)` 的 session_start handler
+// 是否正确注入 uiRequestHandler，特别是 **SR-3**：
+//   无论 new 还是 existing SubagentService，session_start 都必须调
+//   setUiRequestHandler——/resume /fork 复用 existingService 时旧 handler 可能失效。
+//
+// 4 个 case：
+//   1. new 路径（existingService=null）：setUiRequestHandler 被调，参数是函数（tui mode）
+//   2. existing 路径（existingService=mockService）：setUiRequestHandler 仍被调（SR-3 关键）
+//   3. headless mode（json）：createUiRequestHandlerForMode 返回 undefined，
+//      setUiRequestHandler(undefined) 被调（不注入但仍有调用，SR-3 形式不破）
+//   4. rpc mode：setUiRequestHandler 被调，参数是函数
+//
+// 既有 crash-recovery.test.ts / session-start-reaper.test.ts mock 了 SubagentService
+// 但**没有断言 setUiRequestHandler 被调用**——本测试补这个断言，且覆盖 existing 路径
+// （既有测试 fixed getSubagentService() => null，只能走 new 分支）。
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules（在 import 前声明；路径相对 src/execution/__tests/） ──
+//
+// [D15] 为何此处内联 vi.mock 与 vitest.config.ts 的 alias（包根 mocks/pi-coding-agent.ts）并存：
+// 两套 mock 分工不同，不强制统一——
+//   1. **config alias（包根 mocks/pi-coding-agent.ts）**：完整 stub，导出 ExtensionAPI/
+//      ExtensionContext/ExtensionMode 等 *类型*（编译期擦除）+ getAgentDir 运行时值。服务于
+//      全仓库绝大多数测试的类型解析与轻量 mock（不 import 真实重模块的测试直接吃 alias）。
+//   2. **本文件内联 vi.mock（下方）**：vi.mock 在运行时覆盖 config alias，确保本文件 import
+//      真实 index.ts（它 `import { getAgentDir } from "@mariozechner/pi-coding-agent"` +
+//      一组 type-only import）时，运行时只暴露 getAgentDir，彻底隔离真实 SDK 的模块顶层
+//      副作用（避免 jiti 加载真实 pi 包触发未 mock 的依赖链）。
+//   3. 形状一致性：内联 mock 的运行时值形状（`{ getAgentDir }`）与 alias stub 的运行时值
+//      形状完全一致（alias stub 运行时也只导出 getAgentDir 函数，类型导出在运行期擦除）。
+//      差异仅在「覆盖时机」——vi.mock 比 alias 更早介入模块图解析，保证真实 index.ts 加载时
+//      拿到的是纯函数桩而非 alias 的完整对象。
+//   4. crash-recovery.test.ts / session-start-reaper.test.ts 同此模式（import 真实模块的
+//      测试统一用内联 vi.mock 覆盖），三者保持一致。
+// 结论：不抽共享 mocks 文件。alias 已承担类型解析，内联 vi.mock 承担运行时隔离，职责正交。
+
+vi.mock("@mariozechner/pi-coding-agent", () => ({
+  getAgentDir: () => "/home/user/.pi/agent",
+}));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  getAgentDir: () => "/home/user/.pi/agent",
+}));
+vi.mock("@mariozechner/pi-ai", () => ({
+  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
+}));
+vi.mock("@earendil-works/pi-ai", () => ({
+  StringEnum: (values: string[]) => ({ type: "string", enum: values }),
+}));
+vi.mock("@sinclair/typebox", () => ({
+  Type: {
+    Object: (props: Record<string, unknown>) => ({ type: "object", properties: props }),
+    Optional: (schema: unknown) => ({ ...(schema as object), optional: true }),
+    String: () => ({ type: "string" }),
+    Boolean: () => ({ type: "boolean" }),
+    Number: () => ({ type: "number" }),
+    Array: (items: unknown) => ({ type: "array", items }),
+    Record: (key: unknown, value: unknown) => ({ type: "object", additionalProperties: value, key }),
+    Unknown: () => ({ type: "unknown" }),
+    Union: (members: unknown[]) => ({ type: "union", members }),
+    Literal: (value: unknown) => ({ type: "literal", value }),
+  },
+}));
+
+// ── hoisted mock 实例：捕获 setUiRequestHandler 调用 + 可控行为 ──
+
+const {
+  mockSetUiRequestHandler,
+  mockInitSession,
+  mockLoadAll,
+  mockRecoverManifestTmpFiles,
+  /** existing service 引用——测试可改写以模拟 /resume /fork 复用。 */
+  existingServiceRef,
+} = vi.hoisted(() => ({
+  mockSetUiRequestHandler: vi.fn(),
+  mockInitSession: vi.fn(),
+  mockLoadAll: vi.fn(async () => []),
+  // ADR-035 启动恢复接线守护：session_start 必须调 service.recoverManifestTmpFiles
+  mockRecoverManifestTmpFiles: vi.fn(async () => ({ deleted: 0, recovered: 0 })),
+  existingServiceRef: { current: null as unknown },
+}));
+
+// SubagentService mock：每次构造都返回同一组 spy，setUiRequestHandler 可观察。
+// getSubagentService 返回 existingServiceRef.current（null=走 new；非 null=走 existing）。
+vi.mock("../subagent-service.ts", () => ({
+  SubagentService: class {
+    initSession = mockInitSession;
+    setUiRequestHandler = mockSetUiRequestHandler;
+    recoverManifestTmpFiles = mockRecoverManifestTmpFiles;
+    getStreamSink = () => null;
+    dispose = vi.fn();
+  },
+  getSubagentService: () => existingServiceRef.current,
+  setSubagentService: vi.fn(),
+}));
+
+vi.mock("../model-config-service.ts", () => ({
+  ModelConfigService: class {
+    initModel = vi.fn();
+    getAgentRegistry = () => ({ get: () => undefined, list: () => [] });
+    setCtxModel = vi.fn();
+  },
+  getModelConfigService: () => null,
+  setModelConfigService: vi.fn(),
+}));
+
+vi.mock("../worktree-manager.ts", () => ({
+  WorktreeManager: class {
+    constructor(_agentDir: string) {
+      /* mock */
+    }
+    scan = vi.fn();
+    cleanup = vi.fn();
+    create = vi.fn();
+    collectPatch = vi.fn();
+    registerPid = vi.fn();
+  },
+}));
+
+vi.mock("../session-file-gc.ts", () => ({
+  maybeCleanupExpiredSessionFiles: vi.fn(),
+}));
+
+// JsonlRunStore mock：loadAll 默认空数组（session_start 后段不抛即可）
+vi.mock("../../orchestration/jsonl-run-store.ts", () => ({
+  JsonlRunStore: class {
+    loadAll = mockLoadAll;
+    save = vi.fn(async () => {});
+  },
+}));
+
+// interface 层 mock：避免触发真实 pi.registerTool（pi 是 Proxy，真实模块访问 pi
+// 属性时可能抛错）。路径相对 src/execution/__tests/ → ../../interface/...
+vi.mock("../../interface/subagent-tool.ts", () => ({
+  registerSubagentTool: vi.fn(),
+}));
+vi.mock("../../interface/subagents.ts", () => ({
+  registerSubagentsCommand: vi.fn(),
+}));
+vi.mock("../../interface/bg-notify-render.ts", () => ({
+  renderBgNotifyMessage: vi.fn(),
+}));
+vi.mock("../../interface/tool-workflow.ts", () => ({
+  registerWorkflowTool: vi.fn(),
+}));
+vi.mock("../../interface/tool-workflow-script.ts", () => ({
+  registerWorkflowScriptTool: vi.fn(),
+}));
+vi.mock("../../interface/commands.ts", () => ({
+  registerWorkflowsCommand: vi.fn(),
+}));
+
+// ── import 被测工厂 ──
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import subagentsExtension from "../../index.ts";
+
+// ── helpers ──
+
+/** 创建可观察的 mock ExtensionAPI，捕获 session_start handler。
+ *  Proxy 兜底：未显式处理的 pi.xxx 返回 noop，避免抛错。 */
+function createMockPi(): {
+  pi: ExtensionAPI;
+  getSessionStartHandler: () => ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+} {
+  let sessionStartHandler: ((event: unknown, ctx: unknown) => Promise<void>) | undefined;
+  const events = { emit: vi.fn() };
+  const noop = (): void => {
+    /* mock */
+  };
+  const pi = new Proxy<ExtensionAPI>({} as ExtensionAPI, {
+    get(_target, prop: string | symbol): unknown {
+      if (prop === "on") {
+        return (event: string, handler: (...args: unknown[]) => unknown) => {
+          if (event === "session_start") {
+            sessionStartHandler = handler as (event: unknown, ctx: unknown) => Promise<void>;
+          }
+        };
+      }
+      if (prop === "events") return events;
+      if (prop === "appendEntry") return noop;
+      if (prop === "registerMessageRenderer") return noop;
+      return noop;
+    },
+  });
+  return { pi, getSessionStartHandler: () => sessionStartHandler };
+}
+
+/** 最小 ExtensionContext mock。mode 由参数控制（决定 handler 注入行为）。 */
+function createMockCtx(mode: "tui" | "rpc" | "json" | "print"): Record<string, unknown> {
+  const sessionManager = {
+    getSessionId: () => "session-inject-1",
+    getSessionFile: () => "/home/user/.pi/agent/sessions/session-inject-1.jsonl",
+    getSessionDir: () => "/home/user/.pi/agent/sessions",
+    getCwd: () => "/home/user/project",
+    getEntries: () => [],
+    getBranch: () => [],
+    getLeafId: () => null,
+    getLeafEntry: () => undefined,
+    getEntry: () => undefined,
+    getHeader: () => null,
+    getTree: () => [],
+    getSessionName: () => undefined,
+  };
+  const ui = mode === "rpc" ? { setWidget: vi.fn() } : undefined;
+  return {
+    cwd: "/home/user/project",
+    mode,
+    modelRegistry: {
+      getAvailable: () => [],
+      find: () => undefined,
+      hasConfiguredAuth: () => false,
+    },
+    model: undefined,
+    sessionManager,
+    ui,
+  };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockLoadAll.mockResolvedValue([]);
+  existingServiceRef.current = null;
+});
+
+// ── tests ──
+
+describe("session_start UI handler 注入链路（SR-3）", () => {
+  it("new 路径（existingService=null）：setUiRequestHandler 被调，参数是函数（tui mode）", async () => {
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // SR-3 核心：setUiRequestHandler 必须被调
+    expect(mockSetUiRequestHandler).toHaveBeenCalledTimes(1);
+    // 非 headless mode → 注入的是函数（UiRequestHandler），非 undefined
+    const injected = mockSetUiRequestHandler.mock.calls[0]?.[0];
+    expect(typeof injected).toBe("function");
+  });
+
+  it("existing 路径（existingService=mockService）：setUiRequestHandler 仍被调（SR-3 关键）", async () => {
+    // 模拟 /resume /fork：getSubagentService() 返回已存在的 service
+    //（同一 mock 类的实例——spy 仍是 mockSetUiRequestHandler，断言可观察到调用）
+    existingServiceRef.current = {
+      initSession: mockInitSession,
+      setUiRequestHandler: mockSetUiRequestHandler,
+      // ADR-035：与 SubagentService mock class 形状一致——session_start
+      // 会调 service.recoverManifestTmpFiles()，缺方法会抛 TypeError 被吞为 console.warn
+      recoverManifestTmpFiles: mockRecoverManifestTmpFiles,
+      getStreamSink: () => null,
+      dispose: vi.fn(),
+    };
+
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // SR-3 关键断言：existing 路径下 setUiRequestHandler 仍被调
+    //（旧 handler 可能已失效，session_start 必须重新注入）
+    expect(mockSetUiRequestHandler).toHaveBeenCalledTimes(1);
+    const injected = mockSetUiRequestHandler.mock.calls[0]?.[0];
+    expect(typeof injected).toBe("function");
+
+    // ADR-035 existing 路径守护：/resume /fork 复用 service 时 session_start
+    // 也必须调 recoverManifestTmpFiles。守护 case 走 new 路径抓不到 existing 误删，
+    // 此处对称断言（与 setUiRequestHandler 在本 case 的独立断言同模式）。
+    expect(mockRecoverManifestTmpFiles).toHaveBeenCalledTimes(1);
+  });
+
+  it("headless mode（json）：createUiRequestHandlerForMode 返回 undefined → setUiRequestHandler(undefined)", async () => {
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    await handler!({ type: "session_start" }, createMockCtx("json"));
+
+    // SR-3 形式不破：仍调 setUiRequestHandler（参数是 undefined，表示不注入）
+    expect(mockSetUiRequestHandler).toHaveBeenCalledTimes(1);
+    expect(mockSetUiRequestHandler.mock.calls[0]?.[0]).toBeUndefined();
+  });
+
+  it("rpc mode：setUiRequestHandler 被调，参数是函数", async () => {
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    await handler!({ type: "session_start" }, createMockCtx("rpc"));
+
+    expect(mockSetUiRequestHandler).toHaveBeenCalledTimes(1);
+    const injected = mockSetUiRequestHandler.mock.calls[0]?.[0];
+    expect(typeof injected).toBe("function");
+  });
+
+  it("initSession 不再收 uiRequestHandler（#24 单一注入入口：setUiRequestHandler 唯一通道）", async () => {
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // [#24] uiRequestHandler 单一注入入口：index.ts 只调 service.setUiRequestHandler(h)，
+    // 不再重复传 initSession.uiRequestHandler——避免同一 handler 双路径注入造成
+    // "哪一个是 source of truth" 歧义。此处断言该契约不被回退。
+    expect(mockInitSession).toHaveBeenCalledTimes(1);
+    const initArg = mockInitSession.mock.calls[0]?.[0] as {
+      uiRequestHandler?: unknown;
+      mode?: unknown;
+      dialogQueue?: unknown;
+    } | undefined;
+    expect(initArg).toBeDefined();
+    // uiRequestHandler 不再走 initSession（已被 #24 移除）
+    expect(initArg?.uiRequestHandler).toBeUndefined();
+    // mode 仍需 session 级注入（uiObservability.setMode 依赖它）
+    expect(initArg?.mode).toBe("tui");
+    // dialogQueue 仍注入（SR-4 清理路径接通）
+    expect(initArg).toHaveProperty("dialogQueue");
+    // handler 经 setUiRequestHandler 注入（单一入口）——前面 case 已断言，此处复断不再赘述。
+    expect(mockSetUiRequestHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it("session_start 调用 recoverManifestTmpFiles（接线守护，防 ADR-035 启动恢复再次断线）", async () => {
+    const { pi, getSessionStartHandler } = createMockPi();
+    subagentsExtension(pi);
+
+    const handler = getSessionStartHandler();
+    expect(handler).toBeDefined();
+    await handler!({ type: "session_start" }, createMockCtx("tui"));
+
+    // ADR-035 接线断言：session_start 必须调 service.recoverManifestTmpFiles（防死代码回退）
+    expect(mockRecoverManifestTmpFiles).toHaveBeenCalledTimes(1);
+  });
+});

package/src/execution/__tests__/list-component.test.ts

@@ -12,10 +12,10 @@
 
 import { afterEach,beforeEach, describe, expect, it, vi } from "vitest";
 
-import type { SubagentService } from "../subagent-service.ts";
 import type { ThemeLike } from "../../interface/format.ts";
 import { SubagentsListComponent } from "../../interface/list-component.ts";
 import type { KeyHandler, KeyResult, TuiLike, ViewState } from "../../interface/list-shared.ts";
+import type { SubagentService } from "../subagent-service.ts";
 import type { SubagentRecord } from "../types.ts";
 
 // ── KeyResult 常量（语义清晰，避到处写字面量对象） ──

package/src/execution/__tests__/notifier-flush.test.ts

@@ -0,0 +1,78 @@
+/**
+ * BgNotifier flushPendingNotifications — deliverAs 契约（FR-3/AC-3）。
+ *
+ * 修复：deliverAs 从 'followUp' 改为 'steer'，确保 subagent 完成通知在主 agent
+ * 处于 processing 状态（如轮询 loop）时也能立即抢占下一个 turn。
+ *
+ * 修复背景：commit d214d0d83 已验证 steer 能避免 'Agent is already processing'；
+ * workflow helpers.ts:151 已在同语义下用 steer。
+ *
+ * 测试方法：mock NotifierHost，捕获 sendMessage 调用参数，断言 deliverAs === 'steer'。
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { BgNotifier, type NotifierHost } from "../notifier.ts";
+
+/** mock host：捕获所有 sendMessage 调用 + 控制 hasRunningBackground。 */
+function makeMockHost(): NotifierHost & {
+	sendMessageCalls: { message: unknown; options: unknown }[];
+	hasRunningBackground: ReturnType<typeof vi.fn>;
+} {
+	const sendMessageCalls: { message: unknown; options: unknown }[] = [];
+	const hasRunningBackground = vi.fn(() => false);
+	return {
+		sendMessageCalls,
+		hasRunningBackground,
+		sendMessage(message, options) {
+			sendMessageCalls.push({ message, options });
+		},
+	};
+}
+
+describe("BgNotifier.flushPendingNotifications — deliverAs 契约", () => {
+	let host: ReturnType<typeof makeMockHost>;
+	let notifier: BgNotifier;
+
+	beforeEach(() => {
+		host = makeMockHost();
+		notifier = new BgNotifier(host);
+	});
+
+	afterEach(() => {
+		notifier.dispose();
+	});
+
+	it("flush 时调 sendMessage 的 options.deliverAs === 'steer'（FR-3/AC-3）", () => {
+		notifier.notify({
+			id: "bg-test-1",
+			status: "done",
+			agent: "explorer",
+			result: "done",
+			startedAt: Date.now() - 1000,
+			endedAt: Date.now(),
+		});
+
+		// hasRunningBackground=false → notify 立即 flush
+		expect(host.sendMessageCalls).toHaveLength(1);
+		const call = host.sendMessageCalls[0];
+		expect(call.options).toMatchObject({ deliverAs: "steer" });
+	});
+
+	it("flush 时 triggerTurn 也必须为 true（让父 agent 立即唤醒）", () => {
+		notifier.notify({
+			id: "bg-test-2",
+			status: "failed",
+			agent: "worker",
+			error: "boom",
+			startedAt: Date.now(),
+			endedAt: Date.now(),
+		});
+
+		expect(host.sendMessageCalls).toHaveLength(1);
+		expect(host.sendMessageCalls[0].options).toMatchObject({
+			triggerTurn: true,
+			deliverAs: "steer",
+		});
+	});
+});

package/src/execution/__tests__/path-encoding.test.ts

@@ -6,7 +6,7 @@ import * as path from "node:path";
 
 import { describe, expect, it } from "vitest";
 
-import { encodeCwd, getSubagentSessionDir } from "../path-encoding.ts";
+import { encodeCwd, getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
 
 describe("encodeCwd", () => {
   it("encodes a normal unix absolute path", () => {
@@ -73,3 +73,32 @@ describe("getSubagentSessionDir", () => {
     expect(a).not.toBe(b);
   });
 });
+
+describe("getSubagentRecordsDir", () => {
+  it("returns agentDir/subagents/<encodedCwd>/records", () => {
+    const result = getSubagentRecordsDir("/home/user/.pi/agent", "/Users/x/proj");
+    expect(result).toBe(
+      path.join("/home/user/.pi/agent", "subagents", "--Users-x-proj--", "records")
+    );
+  });
+
+  it("shares the same <enc> segment with getSubagentSessionDir for same cwd", () => {
+    // F1：records 与 sessions 在同一 <enc> 段下，仅尾段不同（records vs sessions）。
+    // worktree 场景三者恒等的前提就靠这个共享 enc。
+    const agentDir = "/home/user/.pi/agent";
+    const cwd = "/Users/x/proj";
+    const sessions = getSubagentSessionDir(agentDir, cwd);
+    const records = getSubagentRecordsDir(agentDir, cwd);
+    // 共享 enc：去掉尾段后剩同一路径前缀
+    expect(path.dirname(sessions)).toBe(path.dirname(records));
+    // 尾段不同
+    expect(path.basename(sessions)).toBe("sessions");
+    expect(path.basename(records)).toBe("records");
+  });
+
+  it("produces different path for different mainCwd", () => {
+    const a = getSubagentRecordsDir("/agent", "/cwd1");
+    const b = getSubagentRecordsDir("/agent", "/cwd2");
+    expect(a).not.toBe(b);
+  });
+});

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

@@ -15,11 +15,12 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { createRecord } from "../execution-record.ts";
 import { writeAliveMarker } from "../alive-store.ts";
+import { createRecord } from "../execution-record.ts";
 import { writeFinalized } from "../finalized-marker.ts";
+import type { ManifestRecord, ManifestStore } from "../manifest-store.ts";
 import type { StatusFilter } from "../record-store.ts";
 import { RecordStore } from "../record-store.ts";
 import { writeCancelledTombstone } from "../tombstone-store.ts";
@@ -542,4 +543,87 @@ describe("RecordStore", () => {
       expect(found?.endedAt).toBeUndefined();
     });
   });
+
+  // ============================================================
+  // [BL-M1] 修复：损坏 manifest 上报 pi.appendEntry（用户可见）
+  // collectRecords 跳过 mapManifestStatus 返回 null 的 manifest 时，除 console.warn
+  // 外还需调 pi.appendEntry("subagent:manifest-invalid-status", ...) 让用户能在 session
+  // 内复盘事故——避免磁盘陈旧/损坏 manifest 被静默吞掉。
+  // ============================================================
+  describe("manifest status 越界（损坏 manifest）", () => {
+    /** 构造一个 status 越界的 manifest mock。
+     *  ManifestRecord.status union 是 4 态，运行时却可能收到陈旧 "error" / 意外 "crashed"
+     * 等越界值——isValidManifest 当前挡掉了大部分，但 manifestStore.listAllSync 与
+     *  mapManifestStatus 之间仍有防御层（[BL-M1] 修复记录）。本测试用 unknown-cast 模拟
+     *  一个越过 ManifestRecord 静态类型的对象，验证 collectRecords 反应正确。 */
+    function brokenManifest(): ManifestRecord {
+      // eslint-disable-next-line taste/no-unsafe-cast -- intentional: cast status 越界值模拟磁盘损坏 manifest（测试目的本身）
+      return {
+        id: "broken-1",
+        rootSessionId: "sess-current",
+        agentName: "worker",
+        status: "crashed", // 越界值（union 不含 "crashed"）
+        createdAt: 1000,
+      } as unknown as ManifestRecord;
+    }
+
+    /** Mock ManifestStore 让测试不依赖 fs 路径 + isValidManifest 守卫。
+     *  source/target 类型不兼容是 intentional（ManifestStore 有多个方法，测试仅需 listAllSync），
+     *  `as unknown as ManifestStore` 是 vitest mock 标准 pattern。*/
+    function makeManifestStoreMock(manifests: ManifestRecord[]): ManifestStore {
+      // eslint-disable-next-line taste/no-unsafe-cast -- intentional: ManifestStore 有多个方法，测试仅需 listAllSync
+      return {
+        // 复制 manifests 防调用方意外 mutate 共享数组；vi.fn 每次调用返回独立数组
+        listAllSync: vi.fn(() => [...manifests]),
+      } as unknown as ManifestStore;
+    }
+
+    it("collectRecords 跳过越界 status 时调用 pi.appendEntry('subagent:manifest-invalid-status', ...)", () => {
+      const pi = { appendEntry: vi.fn() };
+      // Mock ManifestStore：listAllSync 返回损坏 manifest，绕开真实 fs 路径与 isValidManifest 守卫。
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      const store = new RecordStore(tmpDir, manifestStore, pi);
+
+      const result = store.collectRecords(100);
+
+      // 损坏 manifest 不出现在结果中（status 越界被跳过，不降级为 failed——避免误告警）
+      expect(result.find((r) => r.id === "broken-1")).toBeUndefined();
+      // appendEntry 被调用，customType + data 字段正确
+      expect(pi.appendEntry).toHaveBeenCalledTimes(1);
+      expect(pi.appendEntry).toHaveBeenCalledWith("subagent:manifest-invalid-status", {
+        id: "broken-1",
+        status: "crashed",
+        rootSessionId: "sess-current",
+        agentName: "worker",
+      });
+    });
+
+    it("pi 为 null/undefined 时不抛错（向后兼容：不注入 pi 的旧调用路径）", () => {
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      // 不传 pi（undefined）—— 模拟 SubagentService 构造期 session_start 未触发的场景。
+      const store = new RecordStore(tmpDir, manifestStore);
+      expect(() => store.collectRecords(100)).not.toThrow();
+      // 损坏 manifest 仍被跳过（不降级）
+      const result = store.collectRecords(100);
+      expect(result.find((r) => r.id === "broken-1")).toBeUndefined();
+    });
+
+    it("setPi() 后 appendEntry 切换到新 pi（覆盖初始 undefined）", () => {
+      const pi1 = { appendEntry: vi.fn() };
+      const pi2 = { appendEntry: vi.fn() };
+      const manifestStore = makeManifestStoreMock([brokenManifest()]);
+      const store = new RecordStore(tmpDir, manifestStore, pi1);
+      store.setPi(pi2);
+
+      store.collectRecords(100);
+
+      // 切换后只调 pi2（pi1 不再被调用）
+      expect(pi1.appendEntry).not.toHaveBeenCalled();
+      expect(pi2.appendEntry).toHaveBeenCalledTimes(1);
+      expect(pi2.appendEntry).toHaveBeenCalledWith(
+        "subagent:manifest-invalid-status",
+        expect.objectContaining({ id: "broken-1" }),
+      );
+    });
+  });
 });

package/src/execution/__tests__/records-cwd-isolation.test.ts

@@ -0,0 +1,91 @@
+// src/__tests__/records-cwd-isolation.test.ts
+//
+// T5（F1 端到端补充）：验证 records 目录改 cwd-scoped 后，不同 cwd 的 manifest 物理
+// 隔离——一个 cwd 的 ManifestStore 读不到另一个 cwd 的 manifest。
+//
+// F1 之前 recordsDir = path.join(agentDir, "records")（全局共享），所有 cwd 的 manifest
+// 混在一个目录，靠 rootSessionFilter 软隔离。F1 改为 getSubagentRecordsDir(agentDir, cwd)
+// 后，每个 cwd 物理独立目录，不再依赖软过滤。
+//
+// T1（path-encoding.test.ts）已覆盖路径层契约；本测试补一个真实 fs + ManifestStore 的
+// 端到端隔离烟雾测试，避免 SubagentService 构造成本（需 mock ModelConfigService/PiLike 等）。
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { ManifestRecord } from "../manifest-store.ts";
+import { ManifestStore } from "../manifest-store.ts";
+import { getSubagentRecordsDir } from "../path-encoding.ts";
+
+let tmpAgentDir: string;
+
+beforeEach(() => {
+  tmpAgentDir = fs.mkdtempSync(path.join(os.tmpdir(), "records-cwd-iso-"));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpAgentDir, { recursive: true, force: true });
+});
+
+/** 写一个最小合法的 manifest 到指定 records 目录。 */
+function writeManifest(recordsDir: string, id: string): string {
+  fs.mkdirSync(recordsDir, { recursive: true });
+  const rec: ManifestRecord = {
+    id,
+    rootSessionId: "sess-1",
+    agentName: "worker",
+    status: "completed",
+    createdAt: Date.now(),
+  };
+  const filePath = path.join(recordsDir, `${id}.json`);
+  fs.writeFileSync(filePath, JSON.stringify(rec), "utf-8");
+  return filePath;
+}
+
+describe("[F1/T5] records cwd physical isolation", () => {
+  it("ManifestStore bound to cwd1 cannot read cwd2's manifest (physical isolation)", () => {
+    const cwd1 = "/Users/x/proj-a";
+    const cwd2 = "/Users/x/proj-b";
+    const recordsDir1 = getSubagentRecordsDir(tmpAgentDir, cwd1);
+    const recordsDir2 = getSubagentRecordsDir(tmpAgentDir, cwd2);
+
+    // 两个 records 目录必须物理不同（已在 T1 路径层覆盖，这里再断言一次作为前提）
+    expect(recordsDir1).not.toBe(recordsDir2);
+
+    // 只在 cwd1 的 records 目录写一个 manifest
+    writeManifest(recordsDir1, "rec-cwd1");
+
+    const store1 = new ManifestStore(recordsDir1);
+    const store2 = new ManifestStore(recordsDir2);
+
+    const cwd1Ids = store1.listAllSync().map((m) => m.id);
+    const cwd2Ids = store2.listAllSync().map((m) => m.id);
+
+    // cwd1 能读到自己的 manifest
+    expect(cwd1Ids).toContain("rec-cwd1");
+    // cwd2 物理读不到 cwd1 的 manifest（不再依赖 rootSessionFilter 软过滤）
+    expect(cwd2Ids).not.toContain("rec-cwd1");
+    expect(cwd2Ids).toEqual([]);
+  });
+
+  it("two cwds with their own manifests are mutually invisible", () => {
+    const cwdA = "/home/user/project-a";
+    const cwdB = "/home/user/project-b";
+    const recordsDirA = getSubagentRecordsDir(tmpAgentDir, cwdA);
+    const recordsDirB = getSubagentRecordsDir(tmpAgentDir, cwdB);
+
+    writeManifest(recordsDirA, "rec-a");
+    writeManifest(recordsDirB, "rec-b");
+
+    const storeA = new ManifestStore(recordsDirA);
+    const storeB = new ManifestStore(recordsDirB);
+
+    const aIds = storeA.listAllSync().map((m) => m.id);
+    const bIds = storeB.listAllSync().map((m) => m.id);
+
+    expect(aIds).toEqual(["rec-a"]);
+    expect(bIds).toEqual(["rec-b"]);
+  });
+});