@zhushanwen/pi-subagent-workflow 7.1.0 → 7.3.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__/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/finalize-record.ts

@@ -144,6 +144,7 @@ export async function doFinalizeRecord(
     await deps.manifestStore.writeManifest({
       id: record.id,
       rootSessionId: record.rootSessionId ?? "",
+      parentRecordId: record.parentRecordId,
       agentName: record.agent,
       status: status === "done" ? "completed" : status,
       createdAt: record.startedAt,

package/src/execution/manifest-store.ts

@@ -7,6 +7,8 @@ import { bestEffort } from "./best-effort.ts";
 export interface ManifestRecord {
   id: string;
   rootSessionId: string;
+  /** 直接父 subagent record ID（层级树构建用）。顶层 record 缺失（undefined）。M3a 补字段。 */
+  parentRecordId?: string;
   agentName: string;
   /**
    * 终态枚举：finalizeRecord 写 running/completed/failed/cancelled 四态；cancelled 不再
@@ -25,6 +27,9 @@ export interface ManifestRecord {
   model?: string;
 }
 
+/** JSON.stringify 缩进空格数（no-magic-numbers 合规）。 */
+const MANIFEST_INDENT_SPACES = 2;
+
 /** 合法 manifest status 集合（4 态；运行时守卫用，磁盘文件可能陈旧/损坏）。crashed 不在其中。 */
 const VALID_MANIFEST_STATUSES: ReadonlySet<string> = new Set([
   "running",
@@ -69,7 +74,7 @@ export class ManifestStore {
   async writeManifest(record: ManifestRecord): Promise<void> {
     const filePath = path.join(this.dir, `${record.id}.json`);
     const tmpPath = `${filePath}.tmp.${process.pid}`;
-    const content = JSON.stringify(record, null, 2);
+    const content = JSON.stringify(record, null, MANIFEST_INDENT_SPACES);
 
     let renamed = false;
     try {

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);
 

package/src/execution/subagent-service.ts

@@ -145,6 +145,19 @@ export interface SubagentServiceSessionInit {
 /** background 优先级（保留 priority 排序机制，单一值）。 */
 const PRIORITY_BACKGROUND = 1000;
 
+/** 跨进程身份贯穿的 env 名（父进程 spawn 子进程时注入，子进程 initSession 读取）。
+ *  仿照 PI_SUBAGENT_FORK_DEPTH 机制，让递归 subagent 的身份（rootSessionId / parentRecordId / depth）
+ *  跨进程传递，使主进程 /subagents 能看到完整递归树（设计见 docs/design/recursive-subagent-visibility.md）。
+ *  语义：env 描述「子进程自己的身份」，不是父的身份（决策 1）。
+ *  [MF-3] 第 4 个 env：真 ROOT 的 cwd（PI_SUBAGENT_ROOT_CWD）。worktree 模式下子进程 spawn cwd =
+ *  checkout 路径，若按各自 cwd 编码落盘目录，深层 record 写到 enc(worktree) 段、ROOT 磁盘重建
+ *  扫不到 → 全树可见性深度 ≥ 2 断裂。子进程经本 env 拿 ROOT cwd，sessions 与 records 两套目录
+ *  统一编码在 enc(ROOT cwd) 段（与身份贯穿同构，见 session-runner 注入点）。 */
+const ENV_ROOT_SESSION_ID = "PI_SUBAGENT_ROOT_SESSION_ID";
+const ENV_SELF_RECORD_ID = "PI_SUBAGENT_SELF_RECORD_ID";
+const ENV_DEPTH = "PI_SUBAGENT_DEPTH";
+const ENV_ROOT_CWD = "PI_SUBAGENT_ROOT_CWD";
+
 /** 触发 onUpdate 的事件类型（streaming delta 不触发，避免每 token 刷新）。 */
 const TRIGGERING_EVENT_TYPES = new Set<AgentEvent["type"]>([
   "tool_start",
@@ -196,8 +209,31 @@ export class SubagentService {
   /** UI 请求可观测性（sessionMode + handler 缺失告警去重，提取自本类降低行数）。 */
   private readonly uiObservability = new UiRequestObservability();
   private pi: PiLike | null = null;
-  /** 当前 Pi session ID（session 隔离过滤用）。initSession 时注入。 */
+  /** 当前 Pi session ID（本进程 pi session，事件路由等用；record 过滤不用它）。initSession 时注入。 */
   private sessionId: string | null = null;
+  /** 所属根 session ID（record 归属过滤用）。根进程 = sessionId（自己是 root）；
+   *  子进程 = env PI_SUBAGENT_ROOT_SESSION_ID 贯穿的真 ROOT（initSession 读取）。
+   *  与 sessionId 正交：sessionId 是本进程 pi session（事件路由等），sessionRootId 是所属根
+   *  （collectRecords filter 用，与 createRecordForMode 的 rootSessionId 盖章同源——子进程
+   *  因此看到整棵 ROOT 树）。设计见 recursive-subagent-visibility.md 决策 3。 */
+  private sessionRootId: string | null = null;
+  /** 进程级执行上下文基线（不依赖 ALS 贯穿——pi RPC mode 的 stdin JSONL 是事件回调式
+   *  （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，initSession 里
+   *  execCtxAls.enterWith 的 store 不会贯穿到后续 tool 调用事件（实测：递归第二层
+   *  parentRecordId/depth 丢失而 rootSessionId 正确——rootSessionId 是实例字段所以不受影响）。
+   *  基线 = 本进程自己的身份（initSession 从 env 读取，与 sessionRootId 同机制）：
+   *  读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」
+   *  这一跨进程树形关系成立。
+   *  initSession 设置：有 env PI_SUBAGENT_SELF_RECORD_ID → {recordId: env 值, depth: env DEPTH}；
+   *  无 env（根进程）→ null（顶层）。 */
+  private execCtxBaseline: { recordId: string | undefined; depth: number } | null = null;
+  /** fork 深度基线（同 ALS 断裂问题：forkDepthAls.getStore() 兜底用）。根进程=0。 */
+  private forkDepthBaseline = 0;
+  /** [MF-3] 所属根进程 cwd（sessions/records 落盘目录编码键）。
+   *  根进程=自身 cwd（构造时 init.cwd）；子进程=env PI_SUBAGENT_ROOT_CWD 贯穿的真 ROOT cwd。
+   *  worktree 模式下子进程 this.cwd 是 checkout 路径，若按它编码目录，深层 record 落到
+   *  enc(worktree) 段、ROOT 扫描不到 → 全树可见性深度 ≥ 2 断裂（与 sessionRootId 同构）。 */
+  private rootCwd: string;
   /** UI streaming sink（ctx.ui.setWidget）。workflow 域经 getStreamSink() 取用。 */
   private streamSink: StreamSink | null = null;
   /** [竞态修复] 主 agent isIdle 查询（ctx.isIdle）。notifier flush gate 用。
@@ -229,8 +265,15 @@ export class SubagentService {
     this.uiRequestHandler = init.uiRequestHandler;
     this.pool = new DefaultConcurrencyPool(this.modelService.getGlobalConfig().maxConcurrent);
     this.worktreeManager = new WorktreeManager(this.modelService.getAgentDir());
-    const sessionsDir = getSubagentSessionDir(this.modelService.getAgentDir(), init.cwd);
-    const recordsDir = getSubagentRecordsDir(this.modelService.getAgentDir(), init.cwd);
+    // [MF-3] worktree 隔离下全树落盘目录统一到 ROOT cwd：子进程（spawn cwd = worktree checkout 路径）
+    // 若按自身 cwd 编码目录，深层 record 写到 enc(worktree) 段，ROOT 磁盘重建扫不到。
+    // 读 env PI_SUBAGENT_ROOT_CWD（根进程无 env → init.cwd）。sessions 与 records 两套目录
+    // 必须同源（同一 rootCwd），否则 enc 段不变量断裂（只改其一会让同 record 的
+    // session 文件与 manifest 分落两段，GC/重建互相找不到）。
+    const envRootCwd = process.env[ENV_ROOT_CWD];
+    this.rootCwd = envRootCwd && envRootCwd !== "" ? envRootCwd : init.cwd;
+    const sessionsDir = getSubagentSessionDir(this.modelService.getAgentDir(), this.rootCwd);
+    const recordsDir = getSubagentRecordsDir(this.modelService.getAgentDir(), this.rootCwd);
     this.manifestStore = new ManifestStore(recordsDir);
     this.store = new RecordStore(sessionsDir, this.manifestStore, this.pi ?? undefined);
     this.notifier = new BgNotifier(this.piAdapter());
@@ -286,6 +329,32 @@ export class SubagentService {
       const base = Number.parseInt(envDepth, 10);
       if (!Number.isNaN(base) && base > 0) {
         this.forkDepthAls.enterWith(base);
+        this.forkDepthBaseline = base;
+      }
+    }
+    // [递归可见性] 跨进程身份贯穿（设计 recursive-subagent-visibility.md）。
+    // 父进程 spawn 时注入这 4 个 env 描述「子进程自己的身份」：
+    //   - rootSessionId：所属根 session（贯穿真 ROOT，子进程不覆盖）
+    //   - selfRecordId：子进程自己的 record id（孙 subagent 的直接父）
+    //   - depth：子进程的嵌套深度
+    //   - rootCwd：真 ROOT 的 cwd（[MF-3] 落盘目录编码键，worktree 下与自身 cwd 不同）
+    // 子进程读 env 建立基线后，createRecordForMode 读 execCtxAls 自动正确（孙挂到子名下）。
+    // 根进程无 env → sessionRootId = init.sessionId（自己是 root），execCtxAls 不 enterWith（顶层）。
+    // enterWith 贯穿整个 session 生命周期（与 forkDepthAls 同构，决策 4）。
+    const envRoot = process.env[ENV_ROOT_SESSION_ID];
+    this.sessionRootId = envRoot ?? init.sessionId;
+    const envSelfRecord = process.env[ENV_SELF_RECORD_ID];
+    if (envSelfRecord !== undefined && envSelfRecord !== "") {
+      const envNestingDepth = Number.parseInt(process.env[ENV_DEPTH] ?? "0", 10);
+      const nestingDepth = Number.isNaN(envNestingDepth) ? 0 : envNestingDepth;
+      // [ALS 断裂修复] 基线兜底：enterWith 在 pi 事件回调模型下不可靠（见 execCtxBaseline 注释），
+      // 基线是 createRecordForMode / 护栏读 ALS store 失败时的权威回退。
+      this.execCtxBaseline = { recordId: envSelfRecord, depth: nestingDepth };
+      this.execCtxAls.enterWith({ recordId: envSelfRecord, depth: nestingDepth });
+      if (process.env.PI_EXT_DEBUG) {
+        logger.debug(
+          `[subagents] execCtxAls initialized: recordId=${envSelfRecord} depth=${nestingDepth} rootSessionId=${envRoot ?? init.sessionId}`,
+        );
       }
     }
     // revive（dispose 的逆操作：/resume /fork /new 后复活）
@@ -413,7 +482,8 @@ export class SubagentService {
     // 但耗资源且 LLM 易陷入「委派→再委派」死循环。在所有副作用之前拦截，错误直达调用方。
     // 计数基准：顶层 nestingDepth=0，nestingDepth>MAX 被拒。与 fork 体积护栏（parentForkDepth 检查）
     // 互补：本护栏更严（计所有嵌套），混合链下先生效；两者共享 MAX_FORK_DEPTH 上限不漂移。
-    const parentNesting = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 在 pi 事件回调模型下可能读空（enterWith 不贯穿），基线兜底。
+    const parentNesting = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const nestingDepth = parentNesting ? parentNesting.depth + 1 : 0;
     if (nestingDepth > MAX_FORK_DEPTH) {
       throw new ForkDepthExceededError(
@@ -506,7 +576,8 @@ export class SubagentService {
     this.assertReady();
 
     // ── BC-12 嵌套护栏：复用 execute() 的 execCtxAls 深度检查 ──
-    const parentNesting = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 可能读空，基线兜底（与 execute 同）。
+    const parentNesting = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const nestingDepth = parentNesting ? parentNesting.depth + 1 : 0;
     if (nestingDepth > MAX_FORK_DEPTH) {
       throw new ForkDepthExceededError(
@@ -599,9 +670,10 @@ export class SubagentService {
   }
 
   /** 合并内存(running) + 磁盘(session.jsonl 重建) record（/subagents list + tool list 消费）。
-   *  按 rootSessionId 过滤，只返回当前 session 创建的 record（session 隔离）。 */
+   *  按 rootSessionId 过滤：根进程=本 session（sessionRootId===sessionId）；
+   *  子进程=env 贯穿的真 ROOT（sessionRootId≠sessionId）→ 看到整棵 ROOT 树（决策 3）。 */
   collectRecords(limit: number, statusFilter: StatusFilter = "all"): SubagentRecord[] {
-    return this.store.collectRecords(limit, statusFilter, this.sessionId ?? undefined);
+    return this.store.collectRecords(limit, statusFilter, this.sessionRootId ?? this.sessionId ?? undefined);
   }
 
   // ── 执行内部：身份解析 + record 创建 ──────────
@@ -638,7 +710,9 @@ export class SubagentService {
     // 从 async 调用链读父执行上下文：主 session 链上无 store → 顶层 record；
     // B run() 期间包了 execCtxAls，B 内创建 C 时读到 B → C.parentRecordId=B.id, C.depth=B.depth+1。
     // depth 语义：顶层（无父）=0；有父=父 depth+1。靠 recordId 是否存在区分，不用负数魔数。
-    const parentCtx = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 在 pi 事件回调模型下可能读空（enterWith 不贯穿），
+    // 基线兜底——本进程的身份在 initSession 已确定（env 注入），任何上下文下都能正确挂父链。
+    const parentCtx = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const parentRecordId = parentCtx?.recordId;
     const depth = parentCtx ? parentCtx.depth + 1 : 0;
 
@@ -650,7 +724,7 @@ export class SubagentService {
       task: opts.task,
       slug: opts.slug,
       startedAt: Date.now(),
-      rootSessionId: this.sessionId ?? undefined,
+      rootSessionId: this.sessionRootId ?? undefined,
       parentRecordId,
       depth,
       controller,
@@ -705,7 +779,7 @@ export class SubagentService {
       worktreeHandle = opts.worktree;
     }
     // [MF#4][MF#2] fork 深度护栏：ALS 传递深度（主 session 链无 store→0，fork 推进 +1）。
-    const parentDepth = this.forkDepthAls.getStore() ?? 0;
+    const parentDepth = this.forkDepthAls.getStore() ?? this.forkDepthBaseline;
     const effectiveDepth = opts.fork ? parentDepth + 1 : parentDepth;
 
     let result: AgentResult;
@@ -982,6 +1056,15 @@ export class SubagentService {
       dialogQueue: this.dialogQueue,
       // 主进程运行模式：session-runner W4 守卫据此决定是否注入 ask_user RPC 提示词。
       mode: this.uiObservability.getMode(),
+      // [递归可见性] 透传所属根 session（runSpawn 注入为子进程 env PI_SUBAGENT_ROOT_SESSION_ID）。
+      // sessionRootId 在 initSession 设定（根进程=sessionId，子进程=env 贯穿的真 ROOT）。
+      // execute/executeAndAwait 调本方法前必经 initSession，此时 sessionRootId 已非空；
+      // ?? 兑底防类型漂移（运行时不可达）。
+      sessionRootId: this.sessionRootId ?? this.sessionId ?? "",
+      // [MF-3] 透传 ROOT cwd（runSpawn 落盘目录编码键 + 注入子进程 env PI_SUBAGENT_ROOT_CWD）。
+      // worktree 模式下 mainCwd = 本进程 checkout 路径，rootCwd 才是真 ROOT——session 文件
+      // 落盘统一用 rootCwd 编码，ROOT 磁盘重建才扫得到深层 record（与 sessionRootId 同构）。
+      rootCwd: this.rootCwd,
     };
   }
 }