@zhushanwen/pi-subagent-workflow 7.1.0 → 7.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/__tests__/execute-nesting.test.ts

@@ -91,7 +91,7 @@ vi.mock("node:fs", async () => {
 // （finalizeRecord 收尾删 .alive）。其余导出（readAliveMarker/isProcessAlive）保留真实实现
 // （worktree-manager/record-store 用，本组用例不涉及但保留以避免间接报错）。
 vi.mock("../alive-store.ts", async (importOriginal) => {
-  const actual = await importOriginal<typeof import("../runtime/execution/alive-store.ts")>();
+  const actual = await importOriginal<typeof import("../alive-store.ts")>();
   return {
     ...actual,
     writeAliveMarker: vi.fn(),

package/src/execution/__tests__/helpers/spawn-mock.ts

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

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

@@ -20,7 +20,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 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 { ManifestRecord } from "../manifest-store.ts";
+import { ManifestStore } from "../manifest-store.ts";
+import { getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
 import type { StatusFilter } from "../record-store.ts";
 import { RecordStore } from "../record-store.ts";
 import { writeCancelledTombstone } from "../tombstone-store.ts";
@@ -45,7 +47,7 @@ function makeRecord(over: Partial<ExecutionRecord> = {}): ExecutionRecord {
  */
 function writeSessionJsonl(
   filePath: string,
-  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; lastTs?: number },
+  identity: { id: string; agent: string; mode: "sync" | "background"; task: string; startedAt: number; rootSessionId?: string; parentRecordId?: string; depth?: number; lastTs?: number },
   assistantText = "result text",
 ): void {
   const lastTs = identity.lastTs ?? identity.startedAt + 1000;
@@ -60,6 +62,8 @@ function writeSessionJsonl(
     startedAt: identity.startedAt,
   };
   if (identity.rootSessionId !== undefined) identityData.rootSessionId = identity.rootSessionId;
+  if (identity.parentRecordId !== undefined) identityData.parentRecordId = identity.parentRecordId;
+  if (identity.depth !== undefined) identityData.depth = identity.depth;
   const identityEntry = JSON.stringify({
     type: "custom",
     id: "id-1",
@@ -189,6 +193,42 @@ describe("RecordStore", () => {
       const found = store.collectRecords(100).find((r) => r.id === "dup-1");
       expect(found?.status).toBe("running"); // 内存 running 覆盖磁盘 crashed
     });
+
+    it("[MF-3/S-20] 跨进程组合：子进程（worktree）写入 enc(ROOT) 的深层 record 被 ROOT store 重建，同 rootSessionId 全树可见、他树被排除", () => {
+      // MF-3 修复后：worktree 子进程把其子 record 的 session 文件写到统一 enc(ROOT cwd) 段，
+      // ROOT 进程的 store 扫同一目录重建（旧实现子进程写到 enc(checkout) 段，此处为空）。
+      const rootCwd = "/Users/x/root-proj";
+      const sessionsDir = getSubagentSessionDir(tmpDir, rootCwd);
+      const recordsDir = getSubagentRecordsDir(tmpDir, rootCwd);
+
+      // 父 record A（ROOT 自己 spawn，parentRecordId 缺省=顶层）+ 孙 record C（B 子进程写入，
+      // 同 rootSessionId、parentRecordId=A、depth=2）+ 他树 record X（rootSessionId 不同）
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-a.jsonl"), {
+        id: "sa-A", agent: "worker", mode: "background", task: "level1", startedAt: 1000, rootSessionId: "root-main",
+      });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-c.jsonl"), {
+        id: "sa-C", agent: "worker", mode: "background", task: "level3", startedAt: 3000,
+        rootSessionId: "root-main", parentRecordId: "sa-A", depth: 2,
+      });
+      writeSessionJsonl(path.join(sessionsDir, "2026-01-01-uuid-x.jsonl"), {
+        id: "sa-X", agent: "worker", mode: "background", task: "other root", startedAt: 4000, rootSessionId: "root-other",
+      });
+
+      // ROOT 进程的 store：sessionsDir/recordsDir 与子进程写盘目录同段（getSubagentSessionDir 同源）
+      const store = new RecordStore(sessionsDir, new ManifestStore(recordsDir), undefined);
+      const recs = store.collectRecords(10, "all", "root-main");
+      const ids = recs.map((r) => r.id);
+
+      // 全树可见：A（顶层）与 C（深度 2，跨进程写入）都在列表，身份字段正确
+      expect(ids).toContain("sa-A");
+      expect(ids).toContain("sa-C");
+      const c = recs.find((r) => r.id === "sa-C");
+      expect(c?.parentRecordId).toBe("sa-A");
+      expect(c?.depth).toBe(2);
+      // 他树 record 被 rootSessionFilter 排除（隔离不破坏）
+      expect(ids).not.toContain("sa-X");
+    });
   });
 
   // ============================================================

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

@@ -0,0 +1,340 @@
+// src/execution/__tests__/recursive-visibility-baseline.test.ts
+//
+// 递归 subagent 跨进程身份：进程级基线兜底验证（ALS 断裂修复）。
+//
+// 背景（2026-08-11 实测）：pi RPC mode 的 stdin JSONL 是事件回调式读取
+// （attachJsonlLineReader → stream.on("data")），每个 RPC 命令是独立异步链。
+// initSession 里 execCtxAls.enterWith 的 store 不会贯穿到后续 tool 调用事件——
+// 递归第二层 subagent 的 parentRecordId/depth 丢失（rootSessionId 是实例字段所以正确）。
+//
+// 修复：execCtxBaseline / forkDepthBaseline 实例字段（initSession 从 env 读取，
+// 与 sessionRootId 同机制），createRecordForMode / 嵌套护栏读 ALS store 失败时兜底。
+// 本文件验证：
+//   1. 有 env（子进程身份）→ execute 创建的 record parentRecordId/depth 来自基线
+//   2. 无 env（根进程）→ parentRecordId undefined / depth 0（顶层）
+//   3. execCtxAls.run 的 store 优先于基线（并发链语义不回归）
+//   4. forkDepth 基线：env PI_SUBAGENT_FORK_DEPTH → fork spawn env 递增
+//
+// mock 策略与 execute-nesting.test.ts 一致（spawn → FakeChild，fs 同步方法 mock，
+// temp-prompt / alive-store / finalized-marker / manifest-store mock）。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules（同 execute-nesting.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", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../alive-store.ts")>();
+  return {
+    ...actual,
+    writeAliveMarker: vi.fn(),
+    removeAliveMarker: vi.fn(),
+  };
+});
+
+vi.mock("../finalized-marker.ts", () => ({
+  writeFinalized: vi.fn(),
+  readFinalized: vi.fn(() => false),
+}));
+
+vi.mock("../manifest-store.ts", () => {
+  class FakeManifestStore {
+    writeManifest = vi.fn(async () => {});
+    readManifest = vi.fn(async () => null);
+    listAllSync = vi.fn(() => []);
+    recoverTmpFiles = vi.fn(async () => []);
+  }
+  // vi.fn 包裹：构造参数（recordsDir）可从 mock.calls 断言（[MF-3] 目录统一验证）。
+  // 注意用普通 function（箭头函数不能被 new 调用）。
+  return { ManifestStore: vi.fn(function (_recordsDir: string) { return new FakeManifestStore(); }) };
+});
+
+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 { spawn } from "node:child_process";
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import { ManifestStore } from "../manifest-store.ts";
+import { getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
+import type { RecordStore } from "../record-store.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+// ── 身份 env 名（与 subagent-service.ts 常量一致，避免魔法字符串）──
+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";
+const ENV_FORK_DEPTH = "PI_SUBAGENT_FORK_DEPTH";
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function lastSpawnedChild(): 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>) ?? {};
+}
+
+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, 2));
+  }
+}
+
+function sessionHeader(id = "baseline-session"): Record<string, unknown> {
+  return { type: "session", id, timestamp: "2026-08-11T00-00-00-000Z", cwd: "/tmp/test" };
+}
+
+function emitStdoutLine(child: FakeChild, obj: Record<string, unknown>): void {
+  child.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+
+/** 驱动 FakeChild 完成：header + 可选事件 + close(0)（runSpawn 自然 resolve）。 */
+async function driveChildToCompletion(child: FakeChild, events: Record<string, unknown>[] = []): Promise<void> {
+  emitStdoutLine(child, sessionHeader());
+  for (const e of events) emitStdoutLine(child, e);
+  child.stdout.end();
+  child.stderr.end();
+  child.emit("close", 0);
+}
+
+// ── 辅助：service 构造 ──
+
+function makeEmptyRegistry(): ModelRegistryLike {
+  return { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => true };
+}
+
+function makePi() {
+  return { sendMessage: vi.fn(), appendEntry: vi.fn(), events: { emit: vi.fn() } };
+}
+
+function setup(env: Record<string, string>): { service: SubagentService; store: RecordStore } {
+  const agentDir = "/tmp/baseline-it";
+  const modelService = new ModelConfigService({ agentDir });
+  modelService.initModel({
+    modelRegistry: makeEmptyRegistry(),
+    sessionId: "baseline-it",
+    ctxModel: { id: "m", name: "M", provider: "p", reasoning: false },
+  });
+  const service = new SubagentService({
+    cwd: agentDir,
+    modelService,
+    getMainSessionFile: () => "/mock/main-session.jsonl",
+  });
+  service.initSession({ pi: makePi(), sessionId: "baseline-it" });
+  const store = Reflect.get(service, "store") as RecordStore;
+  return { service, store };
+}
+
+const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
+
+/** execCtxAls.run 的 duck-type（绕过 import AsyncLocalStorage）。 */
+interface ExecCtxAls {
+  run: <T>(store: { recordId: string | undefined; depth: number }, cb: () => T) => T;
+}
+
+// ── 用例 ──
+
+describe("进程级基线兜底（ALS 断裂修复，pi 事件回调模型）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // 清理身份 env，防用例间泄漏
+    for (const k of [ENV_ROOT_SESSION_ID, ENV_SELF_RECORD_ID, ENV_DEPTH, ENV_FORK_DEPTH, ENV_ROOT_CWD]) {
+      delete process.env[k];
+    }
+  });
+
+  afterEach(() => {
+    for (const k of [ENV_ROOT_SESSION_ID, ENV_SELF_RECORD_ID, ENV_DEPTH, ENV_FORK_DEPTH, ENV_ROOT_CWD]) {
+      delete process.env[k];
+    }
+    vi.restoreAllMocks();
+  });
+
+  it("[核心回归] 有 env（子进程身份）：execute 创建 record 的 parentRecordId/depth 来自基线，不依赖 ALS store", async () => {
+    // 模拟第一层 subagent 进程：env 注入「自己的身份」（父 record id + depth=1）
+    process.env[ENV_ROOT_SESSION_ID] = "root-main";
+    process.env[ENV_SELF_RECORD_ID] = "sa-parent-record";
+    process.env[ENV_DEPTH] = "1";
+
+    const { service, store } = setup({});
+
+    // 不在 execCtxAls.run 内调用（模拟 ALS 断裂：事件回调上下文读不到 store）
+    const handle = await service.execute({ task: "child of parent", ctxModel });
+
+    const rec = store.collectRecords(10, "all", "root-main").find((r) => r.id === handle.subagentId);
+    expect(rec).toBeDefined();
+    expect(rec!.parentRecordId).toBe("sa-parent-record");
+    expect(rec!.depth).toBe(2); // 基线 depth 1 + 1
+    expect(rec!.rootSessionId).toBe("root-main");
+
+    // [MF-1 回归] 读侧 collectRecords 过滤必须与写侧盖章同源（sessionRootId）。
+    // 旧实现传 this.sessionId（子进程自己的 session id ≠ ROOT）→ 子进程内列表恒空。
+    // 子进程的本进程 sessionId 是 "baseline-it"（initSession 注入），而 record 归属
+    // root-main（env 贯穿的真 ROOT）——能查到即证明过滤用的是 sessionRootId。
+    const viaService = service.collectRecords(10);
+    expect(viaService.map((r) => r.id)).toContain(handle.subagentId);
+    expect(viaService[0]!.rootSessionId).toBe("root-main");
+  });
+
+  it("[顶层] 无 env（根进程）：parentRecordId undefined / depth 0", async () => {
+    const { service, store } = setup({});
+
+    const handle = await service.execute({ task: "top level", ctxModel });
+
+    const rec = store.collectRecords(10, "all", "baseline-it").find((r) => r.id === handle.subagentId);
+    expect(rec).toBeDefined();
+    expect(rec!.parentRecordId).toBeUndefined();
+    expect(rec!.depth).toBe(0);
+  });
+
+  it("[优先级] execCtxAls.run 的 store 优先于基线（并发链语义不回归）", async () => {
+    process.env[ENV_ROOT_SESSION_ID] = "root-main";
+    process.env[ENV_SELF_RECORD_ID] = "sa-baseline";
+    process.env[ENV_DEPTH] = "0";
+
+    const { service, store } = setup({});
+    const execCtxAls = Reflect.get(service, "execCtxAls") as ExecCtxAls;
+
+    const handle = await execCtxAls.run({ recordId: "sa-inline-parent", depth: 3 }, () =>
+      service.execute({ task: "inline nested", ctxModel }),
+    );
+
+    const rec = store.collectRecords(10, "all", "root-main").find((r) => r.id === handle.subagentId);
+    expect(rec).toBeDefined();
+    expect(rec!.parentRecordId).toBe("sa-inline-parent"); // run store 优先，非基线 sa-baseline
+    expect(rec!.depth).toBe(4);
+  });
+
+  it("[forkDepth 基线] env PI_SUBAGENT_FORK_DEPTH=1 + fork：spawn env 递增为 2（读点兜底基线生效）", async () => {
+    process.env[ENV_ROOT_SESSION_ID] = "root-main";
+    process.env[ENV_SELF_RECORD_ID] = "sa-fork-parent";
+    process.env[ENV_DEPTH] = "0";
+    process.env[ENV_FORK_DEPTH] = "1";
+
+    const { service } = setup({});
+
+    const execPromise = service.execute({ task: "fork child", ctxModel, fork: true });
+    await waitForSpawn();
+    const childEnv = getLastSpawnEnv();
+
+    // 742 行 parentDepth = forkDepthAls.getStore() ?? forkDepthBaseline —— ALS 断裂时基线=1，+1 → 2
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("2");
+
+    const child = lastSpawnedChild();
+    child.emit("close", 0);
+    await execPromise;
+  });
+
+  it("[嵌套护栏] 基线 depth 参与 execute 入口嵌套护栏（depth>MAX 拒绝）", async () => {
+    process.env[ENV_ROOT_SESSION_ID] = "root-main";
+    process.env[ENV_SELF_RECORD_ID] = "sa-deep-parent";
+    process.env[ENV_DEPTH] = "5";
+
+    const { service } = setup({});
+
+    // MAX_FORK_DEPTH 至少 > 5 才不会被误拒；这里验证基线参与计数的方式是
+    // 用直接深度断言——execute 不抛错说明 nestingDepth=6 未超限，护栏不误伤。
+    // （MAX_FORK_DEPTH 具体值由 session-context-resolver 定义，这里不硬编码。）
+    await expect(service.execute({ task: "deep but allowed", ctxModel })).resolves.toBeDefined();
+  });
+
+  it("[MF-3 回归] 有 ENV_ROOT_CWD（worktree 子进程）：sessions 与 records 两套目录统一编码在 ROOT cwd 段", () => {
+    // 模拟 B（worktree 子进程，自身 cwd=checkout 路径）经 env 拿到真 ROOT cwd。
+    // 旧实现按 init.cwd 编码 → enc(checkout) 段，ROOT 磁盘重建扫不到（MF-3）。
+    const rootCwd = "/root/project";
+    process.env[ENV_ROOT_CWD] = rootCwd;
+
+    const agentDir = "/tmp/baseline-it";
+    const checkoutPath = "/var/folders/worktree/pi-subagents/--root-project--/branch";
+    const modelService = new ModelConfigService({ agentDir });
+    modelService.initModel({
+      modelRegistry: makeEmptyRegistry(),
+      sessionId: "baseline-it",
+      ctxModel: { id: "m", name: "M", provider: "p", reasoning: false },
+    });
+    // service cwd = checkout 路径（worktree 子进程的 spawn cwd）
+    const service = new SubagentService({
+      cwd: checkoutPath,
+      modelService,
+      getMainSessionFile: () => "/mock/main-session.jsonl",
+    });
+
+    const store = Reflect.get(service, "store") as RecordStore;
+    const sessionsDir = Reflect.get(store, "sessionsDir") as string;
+    // ManifestStore 在本文件被 mock：recordsDir 从构造调用参数取（vi.fn 包裹）
+    const recordsDir = vi.mocked(ManifestStore).mock.calls.at(-1)?.[0] as string | undefined;
+
+    // 两套目录都编码在 enc(ROOT cwd) 段（不是 enc(checkout)）
+    expect(sessionsDir).toBe(getSubagentSessionDir(agentDir, rootCwd));
+    expect(recordsDir).toBe(getSubagentRecordsDir(agentDir, rootCwd));
+  });
+});

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/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,
     };
   }
 }

package/src/interface/subagent-actions.ts

@@ -226,7 +226,21 @@ export async function cancelHandler(
 
   // step 1: id 不存在（findRecord 只查内存 running record，不从 session.jsonl 重建）
   const rec = service.findRecord(id);
-  if (!rec) throw new Error(`No subagent record with id "${id}". It may have finished — use action:'list' with includeFinished:true to verify.`);
+  if (!rec) {
+    // [S-19] MF-1 全树可见后，list/completion 可能列出其他进程（父/兄弟）的 running record
+    //（collectRecords 扫共享 sessionsDir 按 rootSessionId 过滤，跨进程互相可见），而 cancel
+    // 只作用于本进程内存 record。区分两种失败，避免「may have finished」误导（该 record 正
+    // 被列出且未 finished，只是不属于本进程内存）。仅文案区分，不改 cancel 作用域。
+    const treeRec = service.collectRecords(DEFAULT_LIST_LIMIT, "all").find((r) => r.id === id);
+    if (treeRec && treeRec.status === "running") {
+      throw new Error(
+        `Subagent record "${id}" is running but owned by another process in the tree ` +
+          `(it was spawned by a different subagent process) — this process cannot cancel it; ` +
+          `cancel only works for subagents spawned by the current process.`,
+      );
+    }
+    throw new Error(`No subagent record with id "${id}". It may have finished — use action:'list' with includeFinished:true to verify.`);
+  }
   // step 2: controller 检查（controller 为 undefined 表示 record 已终态或未启动）
   if (rec.mode !== "background") {
     throw new Error(`Cannot cancel subagent ${id} (unsupported mode: ${rec.mode})`);

package/src/interface/subagents.ts

@@ -32,7 +32,7 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
         try {
           const service = getSubagentService();
           if (!service) return null;
-          // collectRecords 合并内存(running) + 磁盘重建 record，按 session 过滤。
+          // collectRecords 合并内存(running) + 磁盘重建 record，按 rootSessionId 过滤。
           // cancel 只对 running 有效，但全部列出便于用户辨认（终态 record 会被 service 拒绝）。
           const records = service.collectRecords(LIST_LIMIT);
           if (records.length === 0) return null;

package/src/orchestration/__tests__/jsonl-run-store-session-file.test.ts

@@ -175,3 +175,55 @@ describe("W2: RunStore.stateFilePath 暴露 run 状态文件路径", () => {
     expect(result).toBe(path.join(tmpDir, "workflow-state", "run-xyz.jsonl"));
   });
 });
+
+// W3: save 兜底容错——run 工作目录被并发清理时 mkdir 抛 ENOENT，save 静默返回。
+//
+// 防的 bug（PR #166 CI 回归）：review-fix-loop-e2e 等 runAndWait 测试中，
+// handleReturn 的 run.transition("done") 同步改 status 后，runAndWait 轮询发现 done
+// 并 resolve，测试 afterEach 随即 rmSync 删除 sessionDir；此时 handleReturn 内 in-flight
+// 的 await save 尚未完成，mkdir 遇到目录链被并发删除 → ENOENT。原实现 await save 让错误
+// 冒泡为 unhandled promise rejection（worker-host onMessage 无 catch），CI exit 1。
+// 修复：save 仅容错 ENOENT（run 已终态，状态不再变化，持久化无意义也无法完成）→ silent return；
+// 非 ENOENT 错误（EACCES/ENOSPC 等真实磁盘问题）仍重新抛出，不掩盖。
+//
+// 注：真正的 ENOENT 只在 rmSync 与 mkdir 并发时出现（串行 rmSync 后 mkdir {recursive:true}
+// 会重建目录而非抛 ENOENT），故用 mock 直接锁定 save 的容错判定逻辑，不依赖竞态时序复现。
+describe("W3: JsonlRunStore.save 兜底容错（run 工作目录被并发清理时的竞态）", () => {
+  let tmpDir: string;
+  let store: JsonlRunStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-store-enoent-"));
+    store = new JsonlRunStore({ sessionDir: tmpDir });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("mkdir 抛 ENOENT（sessionDir 被并发清理）→ save 静默返回，不抛 unhandled rejection", async () => {
+    const run = makeRunWithDoneCall();
+    const spy = vi
+      .spyOn(fs.promises, "mkdir")
+      .mockRejectedValueOnce(
+        Object.assign(new Error("ENOENT: no such file or directory, mkdir"), {
+          code: "ENOENT",
+        }),
+      );
+    // run 已终态 + 工作目录消失 → save 放弃持久化，resolve undefined（不抛）
+    await expect(store.save(run)).resolves.toBeUndefined();
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it("mkdir 抛非 ENOENT 错误（EACCES）→ save 重新抛出，不掩盖真实磁盘问题", async () => {
+    const run = makeRunWithDoneCall();
+    const spy = vi
+      .spyOn(fs.promises, "mkdir")
+      .mockRejectedValueOnce(
+        Object.assign(new Error("permission denied"), { code: "EACCES" }),
+      );
+    await expect(store.save(run)).rejects.toThrow("permission denied");
+    expect(spy).toHaveBeenCalled();
+  });
+});

package/src/orchestration/jsonl-run-store.ts

@@ -241,7 +241,26 @@ export class JsonlRunStore {
  */
   async save(run: WorkflowRun): Promise<void> {
     const filePath = this.filePathFor(run.runId);
-    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    // 兜底容错：run 工作目录（sessionDir）已被清理时，mkdir 抛 ENOENT，save 放弃。
+    // 竞态场景（review-fix-loop-e2e 等 runAndWait 测试）：handleReturn 内
+    // run.transition("done") 同步改 status 后，runAndWait 轮询发现 done 并 resolve，
+    // 测试 afterEach 随即 rmSync 删除 sessionDir；此时本方法 in-flight 的 mkdir
+    // 遇到目录链已删除 → ENOENT（{recursive:true} 在并发 rmSync 下仍可抛 ENOENT）。
+    // run 既已终态（状态不再变化），持久化无意义也无法完成 → silent return。
+    // 仅容错 ENOENT，重新抛出其他错误（EACCES/ENOSPC 等真实磁盘问题不掩盖）。
+    try {
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    } catch (err) {
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        (err as { code: unknown }).code === "ENOENT"
+      ) {
+        return;
+      }
+      throw err;
+    }
     const snapshot = serializeRun(run);
     await fs.promises.writeFile(filePath, JSON.stringify(snapshot) + "\n", "utf8");
     if (this.pi) {