@zhushanwen/pi-subagent-workflow 7.0.1 → 7.2.0

package/src/execution/__tests__/recursive-visibility-env.test.ts

@@ -0,0 +1,275 @@
+// src/__tests__/recursive-visibility-env.test.ts
+//
+// 递归 subagent 跨层可见性：env 身份贯穿验证（设计 docs/design/recursive-subagent-visibility.md 场景 1b）。
+//
+// 验证 runSpawn 构造的 childEnv 含 4 个 PI_SUBAGENT_* 身份 env，值 = ctx.sessionRootId /
+// record.id / String(record.depth) / ctx.rootCwd（[MF-3] 第 4 个：ROOT cwd，落盘目录编码键）。覆盖 opts.fork=true 与 opts.fork=false 两种（决策 2 无条件注入）。
+//
+// 这是场景 1（端到端三层嵌套全树可见）的「env 传递机制」确定性验证——不依赖 LLM 配合，
+// mock spawn 拦截 childEnv 直接断言。端到端可见性由场景 1（真实 pi CLI + recursive-worker agent）覆盖。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getSubagentSessionDir } from "../path-encoding.ts";
+
+// ── mock modules（同 session-runner-schema-env.test.ts 模式）──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFileSync: vi.fn(() => ""),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { createRecord } from "../execution-record.ts";
+import { type RunOptions, runSpawn, type SessionRunnerContext } from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExec = vi.mocked(execFileSync);
+const mockExistsSync = vi.mocked(fs.existsSync);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function getLastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+function getLastSpawnEnv(): Record<string, string | undefined> {
+  return (mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined>) ?? {};
+}
+
+/** 等待 runSpawn 内部调到 spawn（async，spawn 在 writePromptToTempFile await 之后才调）。 */
+async function waitForSpawn(timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length === 0) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn was not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+// ── fixture ──
+
+function makeRecord(overrides: { id?: string; depth?: number } = {}) {
+  return createRecord(overrides.id ?? "sa-test-record", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "should-be-overridden-by-sessionRootId-source",
+    parentRecordId: undefined,
+    depth: overrides.depth ?? 0,
+  });
+}
+
+function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-main-session",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+// ── runSpawn childEnv 身份 env 注入（场景 1b）──
+
+describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+    mockExec.mockReturnValue("");
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("非 fork（fork=false/undefined）：无条件注入 4 个身份 env（决策 2）", async () => {
+    const record = makeRecord({ id: "sa-aaa", depth: 0 });
+    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const opts = makeRunOpts({ fork: false });
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-aaa");
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("0");
+    // [MF-3] 第 4 个贯穿 env：ROOT cwd（子进程落盘目录编码键）
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe("/fake/cwd");
+    // fork=false 不注入 fork depth env（与既有行为一致，本测试不改变它）
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBeUndefined();
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("fork=true：4 个身份 env 与 fork depth env 共存（决策 2 无条件注入不依赖 fork）", async () => {
+    const record = makeRecord({ id: "sa-bbb", depth: 2 });
+    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const opts = makeRunOpts({ fork: true, parentForkDepth: 1 });
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+
+    // 身份 env 无条件存在（决策 2）
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-bbb");
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("2");
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe("/fake/cwd");
+    // fork depth env 同时存在（fork=true + parentForkDepth=1 → 2）
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("2");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("深层 record（depth=3）：DEPTH env = String(record.depth)，正确贯穿嵌套层级", async () => {
+    const record = makeRecord({ id: "sa-deep", depth: 3 });
+    const ctx = makeCtx({ sessionRootId: "root-topmost" });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("3");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-deep");
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-topmost");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("ROOT_SESSION_ID 恒等于 ctx.sessionRootId（贯穿真 ROOT，非 record.rootSessionId）", async () => {
+    // record.rootSessionId 是 createRecord 时写入的值（可能来自旧逻辑），但 env 注入用的是
+    // ctx.sessionRootId（经 buildSessionRunnerContext 从 this.sessionRootId 透传，贯穿真 ROOT）。
+    // 这保证深层 subagent 的子进程仍归顶层 ROOT（设计决策 1/3）。
+    const record = makeRecord({ id: "sa-ccc" }); // record.rootSessionId = fixture 默认值
+    const ctx = makeCtx({ sessionRootId: "real-root-session" });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+
+    // env 用 ctx.sessionRootId，不是 record.rootSessionId
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("real-root-session");
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).not.toBe(record.rootSessionId);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("[MF-3 回归] worktree 模式（mainCwd=checkout ≠ rootCwd）：sessionDir 用 ROOT cwd 编码，深层 record 落盘到 ROOT 可扫描段", async () => {
+    // 模拟 B（worktree 子进程）spawn C：ctx.cwd/mainCwd = checkout 路径，rootCwd = 真 ROOT cwd。
+    // 旧实现 sessionDir 用 ctx.mainCwd 编码 → enc(checkout) 段，ROOT 磁盘重建扫不到（MF-3）。
+    const rootCwd = "/root/project";
+    const checkoutPath = "/var/folders/worktree/pi-subagents/--root-project--/branch";
+    const agentDir = "/fake/agent";
+    const record = makeRecord({ id: "sa-deep", depth: 2 });
+    const ctx = makeCtx({ cwd: checkoutPath, mainCwd: checkoutPath, rootCwd, agentDir });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+    const spawnArgs = mockSpawn.mock.calls.at(-1)?.[1] as string[];
+
+    // 第 4 个 env 贯穿 ROOT cwd
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe(rootCwd);
+    // spawn --session-dir 指向 enc(ROOT cwd)（非 enc(checkout)）
+    expect(spawnArgs).toContain(getSubagentSessionDir(agentDir, rootCwd));
+    expect(spawnArgs).not.toContain(getSubagentSessionDir(agentDir, checkoutPath));
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

package/src/execution/__tests__/session-runner-schema-env.test.ts

@@ -104,7 +104,7 @@ interface FakeChild {
 function getLastSpawnedChild(): FakeChild {
   const result = mockSpawn.mock.results.at(-1);
   if (!result) throw new Error("spawn was not called yet");
-  return result.value as unknown as FakeChild;
+  return result.value as FakeChild;
 }
 
 function getLastSpawnEnv(): Record<string, string | undefined> {
@@ -155,12 +155,15 @@ function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
   };
 }
 
-function makeCtx(): SessionRunnerContext {
+function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
   return {
     cwd: "/fake/cwd",
     agentDir: "/fake/agent",
     skillDirs: [],
     mainCwd: "/fake/cwd",
+    sessionRootId: "root-session-test",
+    rootCwd: "/fake/cwd",
+    ...overrides,
   };
 }
 

package/src/execution/__tests__/subagent-service.test.ts

@@ -385,24 +385,22 @@ describe("SubagentService", () => {
   });
 
   // ============================================================
-  // execute() worktree fail-fast 校验 [MF#7]（commit 8e8e75966）
+  // execute() worktree 路径（worktree 与 fork 解耦后）
   // ============================================================
   //
-  // [MF#7] execute 入口校验 `worktree:true && !fork` → fail-fast 抛错。
-  // 否则下面三个 worktree 分支都不命中，worktreeHandle 恒 undefined → 子 agent
-  // 零文件隔离且零报错（静默 no-op）。此组验证该校验的三种 fork/worktree 组合：
-  //   1. worktree:true + fork:false → 抛 "requires fork"（fail-fast 命中）
-  //   2. worktree:true + fork:true  → 不命中校验（执行越过 guard，后续因副作用失败）
-  //   3. worktree:false + fork:false → 不命中校验（默认路径，执行越过 guard）
+  // worktree（文件隔离）与 fork（上下文继承）已解耦：worktree:true 可独立于 fork 工作
+  // （worktreeManager.create 只看 opts.worktree，不读 fork）。此组验证三种 fork/worktree
+  // 组合下 worktree 路径的行为（均不应抛 'requires fork'——该 guard 已移除）：
+  //   1. worktree:true + fork:false → 解耦后正常（创建 worktree 路径，不抛 requires fork）
+  //   2. worktree:true + fork:true  → 创建 worktree 路径（测试环境 git 失败，抛非 requires fork 错）
+  //   3. worktree:false + fork:false → 默认路径（不创建 worktree）
   //
-  // 被测点是 execute() 入口的 guard（subagent-service.ts L277-282），在任何副作用
-  // （record 创建 / worktree 创建 / spawn）之前。本文件不 mock spawn（保持与文件头
-  // 声明一致——execute 集成测试在 execute-nesting / run-spawn-integration），
-  // 因此 case 2/3 验证「guard 放行」而非「执行完成」：执行越过 guard 后在后续步骤
-  // （worktreeManager.create 调 git / runSpawn 调 spawn）抛与 fork/worktree 无关的错。
-  // 用 try/catch 断言抛出的不是 guard 错误，精确锁住 guard 的触发条件。
-
-  describe("execute() worktree fail-fast 校验 [MF#7]", () => {
+  // 本文件不 mock spawn（保持与文件头声明一致——execute 集成测试在 execute-nesting /
+  // run-spawn-integration），因此 case 验证「不抛 requires fork」而非「执行完成」：
+  // 执行越过 worktree 创建后在后续步骤（worktreeManager.create 调 git / runSpawn 调
+  // spawn）抛与 fork/worktree 无关的错。用 try/catch 断言抛出的不是 requires fork。
+
+  describe("execute() worktree 路径（worktree 与 fork 解耦）", () => {
     /** 构造已就绪的 service（initSession + initModel 注入 ctxModel，使 resolveIdentity 不因 model 拗错）。 */
     function makeReadyService(): SubagentService {
       const service = new SubagentService({ cwd: agentDir, modelService });
@@ -422,24 +420,25 @@ describe("SubagentService", () => {
       return service;
     }
 
-    it("worktree:true + fork:false → fail-fast 抛错含 'requires fork'（guard 命中）", async () => {
+    it("worktree:true + fork:false → 解耦后不抛 'requires fork'（worktree 独立于 fork）", async () => {
       const service = makeReadyService();
-      // guard 在所有副作用之前：无 record 创建、无 spawn
-      await expect(
-        service.execute({
-          task: "worktree without fork",
+      // 解耦后 worktree:true+fork:false 不再 throw requires fork（worktreeManager.create 只看 worktree）
+      try {
+        await service.execute({
+          task: "worktree without fork (decoupled)",
           worktree: true,
           fork: false,
           ctxModel: { id: "ctx-model", name: "Ctx", provider: "p", reasoning: false },
-        }),
-      ).rejects.toThrow(/requires fork/);
-      // 无副作用：record 未创建（guard 在 createRecordForMode 之前）
-      expect(service.collectRecords(10)).toHaveLength(0);
+        });
+      } catch (err) {
+        // 解耦后绝不抛 requires fork（执行继续到 worktreeManager.create/spawn 才可能抛其他错）
+        expect((err as Error).message).not.toMatch(/requires fork/);
+      }
     });
 
-    it("worktree:true + fork:true → 不命中 guard（执行越过 guard，不抛 'requires fork'）", async () => {
+    it("worktree:true + fork:true → 创建 worktree 路径（不抛 'requires fork'）", async () => {
       const service = makeReadyService();
-      // guard 放行 → 执行继续：先创建 record，然后 worktreeManager.create 调 git（测试环境无 repo → 抛与 fork 无关的错）
+      // 执行继续：先创建 record，然后 worktreeManager.create 调 git（测试环境无 repo → 抛与 fork 无关的错）
       try {
         await service.execute({
           task: "worktree with fork",
@@ -454,9 +453,9 @@ describe("SubagentService", () => {
       }
     });
 
-    it("worktree:false + fork:false → 不命中 guard（默认路径越过 guard，不抛 'requires fork'）", async () => {
+    it("worktree:false + fork:false → 默认路径（不创建 worktree，不抛 'requires fork'）", async () => {
       const service = makeReadyService();
-      // guard 放行 → 执行继续：runSpawn 调 child_process.spawn（测试环境无真实 pi → 抛与 fork 无关的错）
+      // 默认路径：runSpawn 调 child_process.spawn（测试环境无真实 pi → 抛与 fork 无关的错）
       try {
         await service.execute({
           task: "default path",

package/src/execution/__tests__/timeout-integration.test.ts

@@ -179,6 +179,8 @@ function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerCo
     skillDirs: [],
     mainCwd: "/tmp/test",
     mainSessionFile: undefined,
+    sessionRootId: "root-session-test",
+    rootCwd: "/tmp/test",
     ...overrides,
   };
 }

package/src/execution/__tests__/tool-action.test.ts

@@ -247,6 +247,32 @@ describe("cancelHandler", () => {
     await expect(cancelHandler(svc, { subagentId: "nope" })).rejects.toThrow(/No subagent record with id "nope"/);
   });
 
+  it("[S-19] id 属树内其他进程的 running record（磁盘可见、本进程内存无）→ throw 跨进程专属消息", async () => {
+    // MF-1 全树可见后：子进程 list 能看到父/兄弟进程的 running record，但 cancel 只作用于
+    // 本进程内存。旧消息「may have finished」误导（该 record 未 finished、正被列出）。
+    const foreign: SubagentRecord = {
+      id: "bg-foreign", agent: "w", status: "running", mode: "background", startedAt: 1,
+      endedAt: undefined, turns: 0, totalTokens: 0, model: "m", thinkingLevel: undefined, eventLog: [],
+    };
+    const svc = makeService({
+      findRecord: vi.fn(() => undefined),
+      collectRecords: vi.fn(() => [foreign] as SubagentRecord[]),
+    });
+    await expect(cancelHandler(svc, { subagentId: "bg-foreign" })).rejects.toThrow(/owned by another process in the tree/);
+  });
+
+  it("[S-19] id 在树内但已终态（磁盘可见 done）→ 仍用 may have finished 消息", async () => {
+    const done: SubagentRecord = {
+      id: "bg-done", agent: "w", status: "done", mode: "background", startedAt: 1,
+      endedAt: 2, turns: 0, totalTokens: 0, model: "m", thinkingLevel: undefined, eventLog: [],
+    };
+    const svc = makeService({
+      findRecord: vi.fn(() => undefined),
+      collectRecords: vi.fn(() => [done] as SubagentRecord[]),
+    });
+    await expect(cancelHandler(svc, { subagentId: "bg-done" })).rejects.toThrow(/may have finished/);
+  });
+
   it("已终态（cancel 返回 false）→ throw could not be cancelled", async () => {
     const svc = makeService({
       findRecord: vi.fn(() => makeSnapshot({ id: "bg-1", mode: "background", status: "done" })),

package/src/execution/notifier.ts

@@ -19,7 +19,7 @@ export interface BgNotifyRecord {
   error?: string;
   startedAt: number;
   endedAt: number | undefined;
-  /** [MF#1] fork+worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
+  /** [MF#1] worktree 模式下子 agent 改动的 patch 路径（worktree 外，cleanup 后留存）。
    *  done 时通知文本显式提示 `git apply`，否则 background 子 agent 在隔离 worktree 的改动
    *  会静默丢失——父 LLM 不知 patch 路径，无法应用。 */
   patchFile?: string;

package/src/execution/path-encoding.ts

@@ -21,9 +21,13 @@ export function encodeCwd(cwd: string): string {
  *
  * D-004: 用主 cwd 编码——保证同一主 cwd 下所有 subagent 的 session 文件
  * 存放在同一目录，便于 session-file-gc 统一清理。
+ * [MF-3] worktree 模式下调用方必须传树根 cwd（ROOT mainCwd，经 PI_SUBAGENT_ROOT_CWD
+ * 贯穿），不能传子进程自身的 checkout 路径——否则深层 record 落盘到 enc(worktree) 段，
+ * ROOT 磁盘重建扫不到（全树可见性断裂）。根进程传自身 cwd（行为不变）。
  *
  * @param agentDir agent 配置目录（如 ~/.pi/agent）
- * @param mainCwd 主 agent 的工作目录（非 subagent 的 effectiveCwd）
+ * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
+ *   是 ROOT 的 cwd，不是 checkout 路径）
  * @returns session 持久化目录绝对路径
  */
 export function getSubagentSessionDir(agentDir: string, mainCwd: string): string {
@@ -37,14 +41,18 @@ export function getSubagentSessionDir(agentDir: string, mainCwd: string): string
  * 获取 subagent records（manifest）持久化目录路径。
  *
  * 与 getSubagentSessionDir 同用 encodeCwd(mainCwd)，保证 records 与 sessions 在同一
- * <enc> 段下物理相邻——worktree 场景三者恒等（init.cwd /
- * buildSessionRunnerContext.mainCwd / record.worktreeHandle.mainCwd 指向同一主 cwd）。
+ * <enc> 段下物理相邻。
+ * [MF-3] 调用方必须与 getSubagentSessionDir 传同一编码键（进程内 init.cwd /
+ * buildSessionRunnerContext.mainCwd / record.worktreeHandle.mainCwd 恒等；worktree 模式
+ * 跨进程时统一用贯穿的 ROOT cwd）——sessions 与 records 两套目录同段，GC/重建才不会
+ * 互相找不到（enc 段不变量）。
  *
  * D-004 同源：用主 cwd 编码做物理隔离，使 session-file-gc 按 <enc>/records/ 子目录
  * 匹配 manifest .json 时天然限定在当前 cwd 范围内，不会越界清理其他 cwd 的 manifest。
  *
  * @param agentDir agent 配置目录（如 ~/.pi/agent）
- * @param mainCwd 主 agent 的工作目录（非 subagent 的 effectiveCwd）
+ * @param mainCwd 树根主 agent 的工作目录（非 subagent 的 effectiveCwd；worktree 模式下
+ *   是 ROOT 的 cwd，不是 checkout 路径）
  * @returns records 持久化目录绝对路径
  */
 export function getSubagentRecordsDir(agentDir: string, mainCwd: string): string {

package/src/execution/session-runner.ts

@@ -274,6 +274,13 @@ export interface SessionRunnerContext {
   dialogQueue?: DialogGlobalQueue;
   /** 主进程运行模式（W4 守卫：headless 不注入 ask_user RPC 提示词）。 */
   mode?: ExtensionMode;
+  /** 所属根 session ID（跨进程身份贯穿用）。子进程的 record.rootSessionId 全指向真 ROOT，
+   *  使主进程 /subagents 能看到完整递归树。runSpawn 无条件注入为子进程 env（设计 recursive-subagent-visibility.md）。 */
+  sessionRootId: string;
+  /** [MF-3] 所属根进程 cwd（跨进程落盘目录编码键）。根进程=自身 cwd；worktree 模式下子进程
+   *  mainCwd=checkout 路径，rootCwd 贯穿真 ROOT——session 文件落盘统一用 ROOT cwd 编码，
+   *  主进程磁盘重建才能看到全树（设计 recursive-subagent-visibility.md）。 */
+  rootCwd: string;
 }
 
 /** SessionRunner.run 的入参。 */
@@ -622,7 +629,11 @@ export async function runSpawn(
   };
 
   // d. session 目录（与 in-process 一致：list/恢复可发现同一目录）
-  const sessionDir = getSubagentSessionDir(ctx.agentDir, ctx.mainCwd);
+  // [MF-3] 用 ctx.rootCwd（贯穿真 ROOT）而非 ctx.mainCwd 编码：worktree 模式下 mainCwd 是
+  // 子进程的 checkout 路径，按它编码会让深层 record 落到 enc(worktree) 段，ROOT 磁盘重建
+  // 扫不到 → 全树可见性深度 ≥ 2 断裂。rootCwd 与 store 构造同源（subagent-service 同键），
+  // 保证 runSpawn 写入的 session 文件就在本进程/ROOT store 扫描的目录里。
+  const sessionDir = getSubagentSessionDir(ctx.agentDir, ctx.rootCwd);
   fs.mkdirSync(sessionDir, { recursive: true });
 
   // e. worktree 模式：checkout 路径作为 spawn cwd（隔离文件系统）
@@ -660,6 +671,20 @@ export async function runSpawn(
   if (opts.fork && opts.parentForkDepth !== undefined) {
     childEnv.PI_SUBAGENT_FORK_DEPTH = String(opts.parentForkDepth + 1);
   }
+  // [递归可见性] 跨进程身份贯穿（设计 docs/design/recursive-subagent-visibility.md）。
+  // 无条件注入每个 subagent（决策 2：身份贯穿是基础需求，不依赖 fork）。env 描述「子进程自己的身份」：
+  //   - ROOT_SESSION_ID：所属根 session（贯穿真 ROOT，子进程 sessionRootId 读它）
+  //   - SELF_RECORD_ID：子进程自己的 record id（子进程 execCtxAls 基线 = 孙的直接父）
+  //   - DEPTH：子进程的嵌套深度（子进程 execCtxAls 基线 depth）
+  //   - ROOT_CWD：真 ROOT 的 cwd（[MF-3] 落盘目录编码键，worktree 下与自身 spawn cwd 不同）
+  // 子进程 initSession 读这 4 个 env 建立基线 → createRecordForMode 读 execCtxAls 自动正确。
+  childEnv.PI_SUBAGENT_ROOT_SESSION_ID = ctx.sessionRootId;
+  childEnv.PI_SUBAGENT_SELF_RECORD_ID = record.id;
+  childEnv.PI_SUBAGENT_DEPTH = String(record.depth);
+  // [MF-3] 第 4 个贯穿 env：真 ROOT 的 cwd。worktree 模式下子进程 spawn cwd = checkout 路径，
+  // 子进程的 store/runSpawn 落盘目录须统一编码在 enc(ROOT cwd) 段（与身份贯穿同构），
+  // 否则 ROOT 磁盘重建扫不到深层 record（见 subagent-service ENV_ROOT_CWD 注释）。
+  childEnv.PI_SUBAGENT_ROOT_CWD = ctx.rootCwd;
   // D-A6 bridge: schema 激活 structured-output 扩展注册 tool（workflow 编排层需要）
   applySchemaEnvToChildEnv(childEnv, opts.schemaEnv);