@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/execution/__tests__/worktree-pid-registration.integration.test.ts

@@ -15,13 +15,13 @@
 //   真实注册表文件，仅 mock ./pi-invocation.ts（把 pi 二进制替换为 node -e 脚本）。
 //
 // mock 最小化原则：
-//   - node:child_process 不 mock（真实 spawn / execFileSync git）
+//   - node:child_process 不 mock（真实 spawn / spawnSync git）
 //   - node:fs 不 mock（真实目录/文件：worktree checkout、注册表 JSON）
 //   - alive-store 不 mock（真实 process.kill(pid, 0) 探活）
 //   - 仅 vi.mock("./pi-invocation.ts")：getPiInvocation 返回 node -e 脚本
 //   - fake timers 仅 toFake: ["Date"]：推进注册表宽限判定用，不干扰真实 I/O 事件
 
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -67,7 +67,8 @@ let handle: WorktreeHandle | undefined;
 let spawnedPid: number | undefined;
 
 function git(args: string[], cwd: string): string {
-  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+  return (r.stdout ?? "").trim();
 }
 
 /** 初始化临时 git repo（至少一个 commit，worktreeManager.create 需要 clean tree + HEAD）。 */
@@ -97,7 +98,7 @@ async function waitForPid(branch: string, timeoutMs = 5000): Promise<number> {
 }
 
 /** 清理：kill 子进程 + worktree cleanup + 删除临时目录。 */
-function cleanup(): void {
+async function cleanup(): Promise<void> {
   if (spawnedPid) {
     try {
       process.kill(spawnedPid, "SIGKILL");
@@ -108,7 +109,7 @@ function cleanup(): void {
   }
   if (handle) {
     try {
-      wtm.cleanup(handle);
+      await wtm.cleanup(handle);
     } catch (err) {
       // best-effort：git worktree remove 失败不阻断测试清理
       // eslint-disable-next-line no-console
@@ -131,18 +132,21 @@ beforeEach(() => {
   registry = new WorktreeRegistry(agentDir);
 });
 
-afterEach(() => {
+afterEach(async () => {
   vi.useRealTimers();
-  cleanup();
+  await cleanup();
 });
 
 // ── 用例 ──
 
-describe("worktree pid 注册链路（真实 spawn 集成）", () => {
+// [HISTORICAL] 2026-08-20 PR #185：真实 spawn node 子进程 + 真实 git worktree + 注册表
+// 文件锁集成用例显式超时——整包满并行 + 系统余载下真实子进程链路超 vitest 默认 5s
+// testTimeout（对齐本包 worktree-registry D5a / process-shutdown-hook 口径）。
+describe("worktree pid 注册链路（真实 spawn 集成）", { timeout: 30_000 }, () => {
   it("正向：spawn 返回后注册表 pid 同步补全，活 worktree 超宽限不被 scan 误清", async () => {
     // 0. 长驻脚本（子进程 90s 内不退出，模拟长跑子 agent）
     scriptHolder.script = LONG_RUNNING_SCRIPT;    // 1. 真实创建 worktree（pid=0 占位）
-    handle = wtm.create(repoDir, "rec-1");
+    handle = await wtm.create(repoDir, "rec-1");
     expect(readEntry(handle.branch)).toMatchObject({ pid: 0 });
 
     // 2. runSpawn 挂后台（不 await——长驻子进程 close 不触发，await 会挂死），
@@ -170,7 +174,7 @@ describe("worktree pid 注册链路（真实 spawn 集成）", () => {
     vi.setSystemTime(Date.now() + SPAWN_GRACE_MS + 1000);
 
     // 5. scan()：活 worktree 必须不被清（修复前：pid=0 超宽限 → 误删 → 红）
-    wtm.scan();
+    await wtm.scan();
     expect(fs.existsSync(handle.path)).toBe(true);
 
     // 6. 收尾：真实时钟恢复 + kill 子进程让 runPromise settle
@@ -183,7 +187,7 @@ describe("worktree pid 注册链路（真实 spawn 集成）", () => {
     await runPromise;
 
     // 7. 反向：进程死后 scan 回收真孤儿
-    wtm.scan();
+    await wtm.scan();
     expect(fs.existsSync(handle.path)).toBe(false);
     const entryAfter = readEntry(handle.branch);
     expect(entryAfter).toBeUndefined();
@@ -193,7 +197,7 @@ describe("worktree pid 注册链路（真实 spawn 集成）", () => {
     // 0. 短命脚本（子进程立即退出，模拟快速完成的子 agent）
     scriptHolder.script = SHORT_LIVED_SCRIPT;
     // 1. 真实创建 worktree
-    handle = wtm.create(repoDir, "rec-2");
+    handle = await wtm.create(repoDir, "rec-2");
 
     // 2. 短命脚本子进程：spawn 后同步补 pid（修复前 pid=0，且未超宽限 → 不回收 → 红）
     const ctx = makeCtx({
@@ -218,7 +222,7 @@ describe("worktree pid 注册链路（真实 spawn 集成）", () => {
     spawnedPid = entry!.pid;
 
     // 4. scan：pid>0 且进程死 → 立即判孤儿回收（无需等宽限）
-    wtm.scan();
+    await wtm.scan();
     expect(fs.existsSync(handle.path)).toBe(false);
     expect(readEntry(handle.branch)).toBeUndefined();
   }, 15000);

package/src/execution/__tests__/worktree-reconcile.integration.test.ts

@@ -0,0 +1,181 @@
+// src/__tests__/worktree-reconcile.integration.test.ts
+//
+// D5b 对账双向 diff 集成测试：真实 git repo + 真实 tmpdir（不 mock fs/execFile）。
+//
+// 隔离手段：TMPDIR env 重定向到测试私有目录——WorktreeManager 的物理面扫描
+// 根 = os.tmpdir()/pi-subagents（跟随 TMPDIR），避免扫到本机其他进程的真实残留。
+//
+// 覆盖四个收敛方向（判据见 worktree-manager.ts reconcileWithPhysical）：
+//   1. 物理有 + 注册无 + 无活 pid + 超 grace → 清分支与目录
+//   2. 物理有 + 注册无 + 恰好 1 活 pid + 1 残留 → 补写回注册表（自愈）
+//   3. 注册有（pid 活）+ 物理无 → 移除幻影条目
+//   4. 多活 pid / 多残留（对应歧义）→ 跳过不动（宁延迟勿误删）
+
+import { execFileSync, spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { encodeCwd } from "../path-encoding.ts";
+import { WorktreeRegistry } from "../worktree-registry.ts";
+import { WorktreeManager } from "../worktree-manager.ts";
+
+/** 原始 TMPDIR（beforeEach 重定向、afterEach 还原）。 */
+const ORIG_TMPDIR = os.tmpdir();
+
+/** git 辅助：repo 内执行（输出 trim）。 */
+function git(repo: string, ...args: string[]): string {
+	return execFileSync("git", ["-C", repo, ...args], { encoding: "utf-8" }).trim();
+}
+
+// [HISTORICAL] 2026-08-20 PR #185：真实 git 子进程 + 注册表文件锁集成用例显式超时——
+// 每用例多次 git init/worktree add/branch -D 真实子进程调用，整包满并行 + 系统余载下
+// 超 vitest 默认 5s testTimeout（对齐本包 worktree-registry D5a / process-shutdown-hook 口径）。
+describe("WorktreeManager.scan 物理面对账（D5b）", { timeout: 30_000 }, () => {
+	let baseDir: string;
+	let agentDir: string;
+	let repo: string;
+	let enc: string;
+	let registry: WorktreeRegistry;
+	let mgr: WorktreeManager;
+	/** 真实系统 tmp 下的测试根（TMPDIR 重定向目标）。 */
+	let outerDir: string;
+
+	beforeEach(() => {
+		outerDir = fs.mkdtempSync(path.join(ORIG_TMPDIR, "wt-reconcile-it-"));
+		// 物理面扫描根重定向：os.tmpdir() 跟随 TMPDIR env（darwin/linux 均如此）
+		process.env.TMPDIR = outerDir;
+		baseDir = outerDir;
+
+		agentDir = path.join(baseDir, "agent");
+		repo = path.join(baseDir, "repo");
+		fs.mkdirSync(repo, { recursive: true });
+		git(repo, "init", "-q");
+		git(repo, "config", "user.email", "test@test.local");
+		git(repo, "config", "user.name", "test");
+		fs.writeFileSync(path.join(repo, "a.txt"), "init\n", "utf-8");
+		git(repo, "add", "-A");
+		git(repo, "commit", "-q", "-m", "init");
+
+		enc = encodeCwd(repo);
+		registry = new WorktreeRegistry(agentDir);
+		mgr = new WorktreeManager(agentDir);
+	});
+
+	afterEach(() => {
+		process.env.TMPDIR = ORIG_TMPDIR;
+		fs.rmSync(outerDir, { recursive: true, force: true });
+	});
+
+	/** 建一个物理 worktree（按 create() 的真实路径布局，绕过 WorktreeManager.create 的脏树校验）。 */
+	function makePhysicalWorktree(branch: string): string {
+		const checkout = path.join(baseDir, "pi-subagents", enc, branch);
+		git(repo, "worktree", "add", "-q", "-b", branch, checkout, "HEAD");
+		return checkout;
+	}
+
+	/** 在 <agentDir>/subagents/<enc>/sessions/ 下写一个 .alive marker。 */
+	function writeAliveMarker(sessionId: string, pid: number): void {
+		const sessions = path.join(agentDir, "subagents", enc, "sessions");
+		fs.mkdirSync(sessions, { recursive: true });
+		fs.writeFileSync(
+			path.join(sessions, `${sessionId}.jsonl.alive`),
+			JSON.stringify({ pid, id: sessionId, startedAt: Date.now() }),
+			"utf-8",
+		);
+	}
+
+	/** 把目录 mtime 设到 grace 之前（对账判据的 createdAt 近似）。 */
+function ageBeyondGrace(dir: string): void {
+		const past = new Date(Date.now() - 120_000);
+		fs.utimesSync(dir, past, past);
+	}
+
+	it("物理有 + 注册无 + 无活 pid + 超 grace → 清分支与目录", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t1");
+		ageBeyondGrace(checkout);
+
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(false);
+		expect(git(repo, "branch", "--list", "pi-sub-*")).toBe("");
+		expect(registry.load()).toEqual([]);
+	});
+
+	it("物理有 + 注册无 + 未超 grace（create 窗口）→ 跳过不删", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t2");
+		// mtime 保持「现在」——另一进程 worktree add 完成到 registry.add 落盘之间的窗口
+
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(true);
+		expect(git(repo, "branch", "--list", "pi-sub-t2")).not.toBe("");
+	});
+
+	it("物理有 + 注册无 + 恰好 1 活 pid + 1 残留 → 补写回注册表（自愈）", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-t3");
+		// 活 pid 用本测试进程（isProcessAlive 真实调用必活）
+		writeAliveMarker("s-t3", process.pid);
+
+		await mgr.scan();
+
+		const entries = registry.load();
+		expect(entries).toHaveLength(1);
+		expect(entries[0].branch).toBe("pi-sub-t3");
+		expect(entries[0].pid).toBe(process.pid);
+		expect(entries[0].checkout).toBe(checkout);
+		// 物理资源未被删（自愈而非只删）
+		expect(fs.existsSync(checkout)).toBe(true);
+	});
+
+	it("注册有（pid 活）+ 物理无 → 移除幻影条目", async () => {
+		// pid 活（本进程）使阶段一孤儿清理跳过，隔离方向一的独立语义
+		await registry.add({
+			repo,
+			branch: "pi-sub-ghost",
+			checkout: path.join(baseDir, "pi-subagents", enc, "pi-sub-ghost"),
+			pid: process.pid,
+			createdAt: Date.now(),
+		});
+
+		await mgr.scan();
+
+		expect(registry.load()).toEqual([]);
+	});
+
+	it("多残留 + 多活 pid（对应歧义）→ 跳过不动", async () => {
+		const c1 = makePhysicalWorktree("pi-sub-m1");
+		const c2 = makePhysicalWorktree("pi-sub-m2");
+		ageBeyondGrace(c1);
+		ageBeyondGrace(c2);
+		// 第二个「活 pid」用真实 sleep 子进程（与 process.pid 不同值）
+		const sleeper = spawn("sleep", ["60"]);
+		try {
+			expect(sleeper.pid).toBeTruthy();
+			writeAliveMarker("s-m1", process.pid);
+			writeAliveMarker("s-m2", sleeper.pid as number);
+
+			await mgr.scan();
+
+			// 歧义 → 本周期全部跳过（宁延迟勿误删），下周期活 pid 消失后收敛
+			expect(fs.existsSync(c1)).toBe(true);
+			expect(fs.existsSync(c2)).toBe(true);
+			expect(registry.load()).toEqual([]);
+		} finally {
+			sleeper.kill("SIGKILL");
+		}
+	});
+
+	it("幂等：连续两次 scan 结果一致（无重复动作）", async () => {
+		const checkout = makePhysicalWorktree("pi-sub-idem");
+		ageBeyondGrace(checkout);
+
+		await mgr.scan();
+		await mgr.scan();
+
+		expect(fs.existsSync(checkout)).toBe(false);
+		expect(git(repo, "branch", "--list", "pi-sub-*")).toBe("");
+	});
+});

package/src/execution/__tests__/worktree-registry.test.ts

@@ -45,29 +45,29 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("add + load", () => {
-    it("add 后 load 能读到", () => {
+    it("add 后 load 能读到", async () => {
       const entry = makeEntry();
-      registry.add(entry);
+      await registry.add(entry);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0]).toEqual(entry);
     });
 
-    it("多条目跨 repo 共存", () => {
+    it("多条目跨 repo 共存", async () => {
       const entryA = makeEntry({ repo: REPO_A, branch: "pi-sub-bg-1" });
       const entryB = makeEntry({ repo: REPO_B, branch: "pi-sub-bg-2" });
-      registry.add(entryA);
-      registry.add(entryB);
+      await registry.add(entryA);
+      await registry.add(entryB);
       const loaded = registry.load();
       expect(loaded).toHaveLength(2);
     });
 
-    it("同 branch add 覆盖（去重）", () => {
+    it("同 branch add 覆盖（去重）", async () => {
       const entry = makeEntry({ pid: 0 });
-      registry.add(entry);
+      await registry.add(entry);
       // 同 branch 再次 add（覆盖）
       const updated = makeEntry({ pid: 999 });
-      registry.add(updated);
+      await registry.add(updated);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].pid).toBe(999);
@@ -75,25 +75,25 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("updatePid", () => {
-    it("补全 pid（create 占位 → first header 补全）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1", pid: 0 }));
-      registry.updatePid("pi-sub-bg-1", 12345);
+    it("补全 pid（create 占位 → first header 补全）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1", pid: 0 }));
+      await registry.updatePid("pi-sub-bg-1", 12345);
       const loaded = registry.load();
       expect(loaded[0].pid).toBe(12345);
     });
 
-    it("branch 不存在时忽略（幂等）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.updatePid("pi-sub-nonexistent", 12345);
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.updatePid("pi-sub-nonexistent", 12345);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].pid).toBe(0); // 原条目未变
     });
 
-    it("update 不改变其他字段", () => {
+    it("update 不改变其他字段", async () => {
       const entry = makeEntry({ branch: "pi-sub-bg-1", repo: REPO_A, checkout: "/tmp/x" });
-      registry.add(entry);
-      registry.updatePid("pi-sub-bg-1", 999);
+      await registry.add(entry);
+      await registry.updatePid("pi-sub-bg-1", 999);
       const loaded = registry.load();
       expect(loaded[0].repo).toBe(REPO_A);
       expect(loaded[0].checkout).toBe("/tmp/x");
@@ -102,60 +102,98 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("remove", () => {
-    it("移除指定 branch", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.add(makeEntry({ branch: "pi-sub-bg-2" }));
-      registry.remove("pi-sub-bg-1");
+    it("移除指定 branch", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.add(makeEntry({ branch: "pi-sub-bg-2" }));
+      await registry.remove("pi-sub-bg-1");
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].branch).toBe("pi-sub-bg-2");
     });
 
-    it("branch 不存在时忽略（幂等）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.remove("pi-sub-nonexistent");
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.remove("pi-sub-nonexistent");
       expect(registry.load()).toHaveLength(1);
     });
 
-    it("空注册表 remove 不报错", () => {
-      expect(() => registry.remove("pi-sub-anything")).not.toThrow();
+    it("空注册表 remove 不报错", async () => {
+      await expect(registry.remove("pi-sub-anything")).resolves.not.toThrow();
     });
   });
 
   describe("降级与健壮性", () => {
-    it("文件不存在时 load 返回空数组", () => {
+    it("文件不存在时 load 返回空数组", async () => {
       expect(registry.load()).toEqual([]);
     });
 
-    it("损坏 JSON 时 load 返回空数组", () => {
+    it("损坏 JSON 时 load 返回空数组", async () => {
       fs.mkdirSync(path.dirname(registryFile), { recursive: true });
       fs.writeFileSync(registryFile, "{ not valid json }}}", "utf-8");
       expect(registry.load()).toEqual([]);
     });
 
-    it("entries 字段缺失时 load 返回空数组", () => {
+    it("entries 字段缺失时 load 返回空数组", async () => {
       fs.mkdirSync(path.dirname(registryFile), { recursive: true });
       fs.writeFileSync(registryFile, '{"other": 123}', "utf-8");
       expect(registry.load()).toEqual([]);
     });
 
-    it("save 创建不存在的父目录", () => {
+    it("save 创建不存在的父目录", async () => {
       // registryFile 在 tmpAgentDir/subagents/ 下，subagents 目录不存在
       expect(fs.existsSync(path.dirname(registryFile))).toBe(false);
-      registry.add(makeEntry());
+      await registry.add(makeEntry());
       expect(fs.existsSync(registryFile)).toBe(true);
     });
 
-    it("save 后无残留 .tmp 文件（原子写）", () => {
-      registry.add(makeEntry());
+    it("save 后无残留 .tmp 文件（原子写）", async () => {
+      await registry.add(makeEntry());
       const tmpFile = `${registryFile}.tmp`;
       expect(fs.existsSync(tmpFile)).toBe(false);
     });
   });
 
   describe("SPAWN_GRACE_MS 常量", () => {
-    it("值为 60s", () => {
+    it("值为 60s", async () => {
       expect(SPAWN_GRACE_MS).toBe(60_000);
     });
   });
+
+  describe("D5a 锁互斥（两写方并发不丢条目）", () => {
+    // [HISTORICAL] 2026-08-20 PR #185：真实 proper-lockfile 文件锁 RMW 用例显式超时——
+    // 单跑 >1s，整包满并行 + 系统余载下 100/31 次持锁 load→mutate→save 超过 vitest
+    // 默认 5s testTimeout（隔离跑通过，纯环境饿死），对齐本包 record-store-index 口径。
+    it("两个 registry 实例（模拟两 pi 进程写方）并发各 add 50 条，零丢失", { timeout: 30_000 }, async () => {
+      // 失败模式 G 的复现形态：无锁时两实例 load→mutate→save 交错，后写者覆盖
+      // 先写者 → 条目丢失。锁内 RMW 应保证 100 条全部落盘。
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 50; i++) {
+        tasks.push(r1.add(makeEntry({ branch: `pi-sub-w1-${i}` })));
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-w2-${i}` })));
+      }
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(100);
+      // 两写方的条目都在（非「后写者全量覆盖」形态）
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w1-"))).toHaveLength(50);
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w2-"))).toHaveLength(50);
+    });
+
+    it("并发 add + remove 交错：remove 只删自己的 branch", { timeout: 30_000 }, async () => {
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      await r1.add(makeEntry({ branch: "pi-sub-keep" }));
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 30; i++) {
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-n-${i}` })));
+      }
+      tasks.push(r1.remove("pi-sub-keep"));
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(30);
+      expect(loaded.find((e) => e.branch === "pi-sub-keep")).toBeUndefined();
+    });
+  });
 });

package/src/execution/agent-result-mapper.ts

@@ -8,6 +8,9 @@
 import type { AgentResult as WorkflowAgentResult, AgentUsage as WorkflowAgentUsage, ToolCallEntry } from "../orchestration/models/types.ts";
 import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "./types.ts";
 
+/** safeStringify 的 JSON 截断长度（字符），防大对象拼进 toolCalls 挤爆 trace。 */
+const TOOL_ARGS_JSON_MAX_CHARS = 500;
+
 /**
  * D-A10: subagents AgentResult → workflow AgentResult 映射。
  *
@@ -80,7 +83,7 @@ function mapToolCalls(calls: ToolCall[]): ToolCallEntry[] {
 function safeStringify(value: unknown): string {
   try {
     const s = JSON.stringify(value);
-    return s.length > 500 ? `${s.slice(0, 500)}...` : s;
+    return s.length > TOOL_ARGS_JSON_MAX_CHARS ? `${s.slice(0, TOOL_ARGS_JSON_MAX_CHARS)}...` : s;
   } catch {
     return String(value);
   }

package/src/execution/argv-mirror.ts

@@ -12,6 +12,7 @@ export interface MirrorFlags {
   noExtensions: boolean;
   approve: boolean;
   extensionPaths: string[];
+  noContextFiles: boolean;
 }
 
 /**
@@ -31,7 +32,7 @@ const VALUED_FLAGS = new Set<string>([
 const ARGV_FLAG_START = 2;
 
 /**
- * 从主进程 argv 解析可镜像的 flag（--no-extensions/--approve/--extension）。
+ * 从主进程 argv 解析可镜像的 flag（--no-extensions/--approve/--extension/--no-context-files）。
  *
  * 数据源是主 pi 进程的 process.argv：子进程 spawn 的父就是主进程，
  * 主进程 argv 完整保留启动时收到的全部 flag（已运行时验证）。这让子进程
@@ -39,14 +40,25 @@ const ARGV_FLAG_START = 2;
  *
  * 解析规则：
  * - --no-extensions / -ne、--approve / -a：布尔 flag
+ * - --no-context-files / -nc：布尔 flag（镜像理由：--extension 镜像会把
+ *   @zhushanwen/pi-system-prompt 带进每个 subagent，该扩展靠子进程自己的
+ *   argv 检测此 flag 决定是否注入全局 AGENTS.md——不镜像则用户 opt-out
+ *   在 subagent 路径失效）
  * - --extension / -e：支持 `--extension <path>`（空格）与 `--extension=<path>`（等号）
  * - 其他 flag（在 VALUED_FLAGS 中）的值不被误当 extension 路径
  * - positional 参数被忽略
  * - argv[0]/argv[1] 是 bun/pi binary 路径，从 argv[2:] 开始扫
  */
+// [perf] 进程内 process.argv 引用恒定（唯一调用点 session-runner 每次 spawn 传同一引用），
+// 解析结果按 argv 引用相等 memo——每次 spawn 免重复扫描/正则。测试传新数组引用不命中。
+let memoArgv: readonly string[] | undefined;
+let memoResult: MirrorFlags | undefined;
+
 export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
+  if (memoResult !== undefined && memoArgv === argv) return memoResult;
   let hasNoExtensions = false;
   let hasApprove = false;
+  let hasNoContextFiles = false;
   const extensionPaths: string[] = [];
 
   // argv[0]=runtime(bun), argv[1]=pi binary 路径；flag 从 argv[2] 起
@@ -62,6 +74,10 @@ export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
       hasApprove = true;
       continue;
     }
+    if (tok === "--no-context-files" || tok === "-nc") {
+      hasNoContextFiles = true;
+      continue;
+    }
     // 等号形式 --extension=path / -e=path
     const eqMatch = /^(--extension|-e)=(.*)$/.exec(tok);
     if (eqMatch) {
@@ -86,5 +102,8 @@ export function mirrorMainProcessFlags(argv: readonly string[]): MirrorFlags {
     // 其他情况（未知 flag、--flag=val 形式、positional）忽略
   }
 
-  return { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths };
+  const result = { noExtensions: hasNoExtensions, approve: hasApprove, extensionPaths, noContextFiles: hasNoContextFiles };
+  memoArgv = argv;
+  memoResult = result;
+  return result;
 }

package/src/execution/channel-registry-access.ts

@@ -76,7 +76,9 @@ function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
     );
     return undefined;
   }
-  const version = (slot as { version?: unknown }).version;
+  // 断言目标含必填 version 字段（object/null 已守卫；version 值本身在下一行校验），
+  // 对齐 format.ts extractAgentName 的必填字段断言先例，避免全可选断言零校验。
+  const version = (slot as { version: unknown }).version;
   if (version !== HANDSHAKE_VERSION) {
     logger.warn(
       `[pi-subagent-workflow] channel handshake version mismatch (got ${String(