@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/execution/session-runner.ts

@@ -5,10 +5,12 @@
 // spawn 改造后：session 在独立子进程跑（进程隔离），事件经 stdout JSON 流回流。
 // runSpawn 是唯一执行入口（sync/background 共用）。mode 分叉在 Runtime.execute 顶部。
 
-import { type ChildProcess,execFileSync, spawn } from "node:child_process";
+import { type ChildProcess, type ChildProcessWithoutNullStreams, execFile, spawn } from "node:child_process";
 import * as fs from "node:fs";
 
 import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { bestEffort } from "./best-effort.ts";
+import { armIdleTimer } from "./lifecycle-manager.ts";
 import { readActivePendingFromSessionFile } from "./session-pending.ts";
 
 import type { ExtensionMode } from "./host-mode.ts";
@@ -23,9 +25,9 @@ import type { AgentConfig, ResolvedModel } from "./model-resolver.ts";
 import { collectResult } from "./output-collector.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
 import { getPiInvocation } from "./pi-invocation.ts";
+import { stringifySchemaCached } from "../shared/schema-jsonify.ts";
 import { MAX_FORK_DEPTH } from "./session-context-resolver.ts";
-import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "./session-reconstructor.ts";
-import { sendPromptCommand } from "./stdin-writer.ts";
+import { EPIPE_FAILURE_THRESHOLD, recordEpipeFailure, sendPromptCommand } from "./stdin-writer.ts";
 import {
   deriveSessionFilePath,
   findSessionFileByHeaderId,
@@ -74,6 +76,19 @@ function isAgentEndEvt(
   return x.type === "agent_end";
 }
 
+/**
+ * [V2 模块 3] agent_settled 事件守卫。对齐 isAgentEndEvt 模式（type 字段窄化，无需 cast）。
+ *
+ * agent_settled 是 V2 持续对话的「真空闲边界」：agent_end 之后、post-run（compact 检查等）
+ * 完成后才 emit（pi `agent-session.js` `_runAgentPrompt` finally 块，约 L744-755）。chatMode 在
+ * 此 arm idle timer + 通知本轮完成；非 chatMode 忽略（agent_end handler 已处理一次性 kill）。
+ */
+function isAgentSettledEvt(x: unknown): x is { type: "agent_settled" } {
+  if (typeof x !== "object" || x === null) return false;
+  if (!("type" in x)) return false;
+  return x.type === "agent_settled";
+}
+
 /**
  * 把 pi assistantMessageEvent 分流为 text_delta / thinking_delta AgentEvent，供 streaming 通道。
  *
@@ -96,19 +111,25 @@ export function mapAssistantMessageDelta(
 // 常量
 // ============================================================
 
+/** 时间单位换算常量（命名后供 watchdog 系列常量组合，消除裸乘法字面量）。 */
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+
 /** 默认 grace turns（soft limit 后宽限轮数，对齐旧实现 DEFAULT_GRACE_TURNS）。 */
 const DEFAULT_GRACE_TURNS = 2;
 
-/** watchdog 下限（ms）。兜底防止子进程卡死在单个 tool 内（hang 的 bash/网络读），
+/** watchdog 下限：30 分钟。兜底防止子进程卡死在单个 tool 内（hang 的 bash/网络读），
  *  导致 turn_end 永不触发、maxTurns limiter 失效、background 槽位/worktree/alive marker 泄漏。
  *  [M-1] 旧实现固定 30 分钟，与 maxTurns 无关——maxTurns=100 的长任务会被误杀。
  *  现改为基于 maxTurns 动态计算（见 computeWatchdogMs）。 */
-const SPAWN_WATCHDOG_FLOOR_MS = 30 * 60 * 1000;
+const WATCHDOG_FLOOR_MINUTES = 30;
+const SPAWN_WATCHDOG_FLOOR_MS = WATCHDOG_FLOOR_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
 
-/** [M-1] 单 turn 估算耗时（ms，含 LLM 响应 + tool 执行）。
+/** [M-1] 单 turn 估算耗时：5 分钟（含 LLM 响应 + tool 执行）。
  *  5 分钟是经验值——复杂 tool（大文件读写/长 bash）+ 长 LLM 响应约 3-4 分钟，
  *  留 1-2 分钟余量。下限与按 turn 计算取 max，避免 maxTurns 过小时 watchdog 紧到误杀。 */
-const WATCHDOG_MS_PER_TURN = 5 * 60 * 1000;
+const WATCHDOG_MINUTES_PER_TURN = 5;
+const WATCHDOG_MS_PER_TURN = WATCHDOG_MINUTES_PER_TURN * SECONDS_PER_MINUTE * MS_PER_SECOND;
 
 // [recursive-orchestration] agent_end keep-alive 的两类等待超时（不 kill 分支的兑底）。
 // 层主 subagent 空闲等待后代完成（steer 唤醒）期间不产生 turn，原 watchdog 已清；
@@ -143,13 +164,17 @@ export const WAKEUP_GRACE_MS = 15_000;
  *
  * @param maxTurns 调用方指定的 turn 上限；undefined/null/0 视为默认 10 turns
  */
+/** maxTurns 缺省（undefined/null/0）时的估算 turn 数（computeWatchdogMs 兜底）。 */
+const DEFAULT_MAX_TURNS_ESTIMATE = 10;
+
 export function computeWatchdogMs(maxTurns: number | undefined | null): number {
-  const effectiveTurns = maxTurns && maxTurns > 0 ? maxTurns : 10;
+  const effectiveTurns = maxTurns && maxTurns > 0 ? maxTurns : DEFAULT_MAX_TURNS_ESTIMATE;
   return Math.max(SPAWN_WATCHDOG_FLOOR_MS, effectiveTurns * WATCHDOG_MS_PER_TURN);
 }
 
-/** stderr 累积上限（字符）。防止失控子进程打满父进程内存。保留尾部便于诊断。 */
-const STDERR_MAX_CHARS = 64 * 1024;
+/** stderr 累积上限——按字符截断（.slice 语义），非字节；64K 规模沿自原实现。
+ *  防止失控子进程打满父进程内存。保留尾部便于诊断。 */
+const STDERR_MAX_CHARS = 65_536;
 
 /**
  * 跨包契约 env 名：workflow 子进程把权威 JSON Schema 通过此 env 传给 structured-output 扩展。
@@ -226,19 +251,21 @@ Your working directory (the "Working directory" in the environment block above)
 // 主进程异常退出（SIGKILL/崩溃/session_shutdown dispose）时，sync 子进程会成孤儿。
 //
 // 本 Set 是 dispose 的最后兜底——在 abortRunningControllers（background controller.abort 路径）
-// 之后，遍历所有仍存活的子进程（含 sync）发 SIGTERM。正常退出路径（子进程 close）会从 Set 移除，
+// 之后，遍历所有仍存活的子进程（含 sync）发 SIGTERM。正常退出路径（子进程 close）会从 Map 移除，
 // 不受影响。background 子进程可能被 controller.abort 路径先 kill 一次，再被本遍历 kill 一次
 // （对已退出的 child.kill 返回 false，无害）。
 //
+// [M2-B1] key = record.id（record→child 映射，busy 投递定位活进程用，见 getChildByRecord）。
 // [export] 测试可观测（断言 dispose 后 size===0）。业务代码误外部修改。
-export const spawnedChildren = new Set<ChildProcess>();
+export const spawnedChildren = new Map<string, ChildProcess>();
 
 /**
  * kill 所有未退出的 spawned 子进程（dispose 兜底用）。
  *
- * 遍历 spawnedChildren Set，对每个未 killed 的子进程发 `child.kill(signal)`。
- * 已退出的子进程在 close/error 事件时已从 Set 移除（`spawnedChildren.delete`），
- * 故 Set 中只剩「活着的」或「已被 kill 但 close 事件尚未回调的」。后者用 `child.killed`
+ * 遍历 spawnedChildren Map 的 values()，对每个未 killed 的子进程发 `child.kill(signal)`。
+ * 已退出的子进程在 close/error 事件时已从 Map 移除（按句守卫 removeChildRegistration——
+ * Map 当前值仍是该 child 才删，防误删 resume spawn 的新注册），故 Map 中只剩「活着的」
+ * 或「已被 kill 但 close 事件尚未回调的」。后者用 `child.killed`
  * 跳过——避免对一个已 kill 的子进程重复 kill。
  *
  * 用于 SubagentService.dispose（进程退出路径）：覆盖 sync 子进程（controller 为 undefined，
@@ -251,7 +278,7 @@ export const spawnedChildren = new Set<ChildProcess>();
  */
 export function killAllSpawnedChildren(signal: NodeJS.Signals = "SIGTERM"): number {
   let n = 0;
-  for (const child of spawnedChildren) {
+  for (const child of spawnedChildren.values()) {
     // 跳过已 kill 的（killed=true 表示已调过 child.kill；已退出的在 close/error 时已从 Set 移除）。
     // 不依赖 exitCode/signalCode：close 事件回调可能晚于 dispose，此时它们仍为 null，但子进程
     // 可能已被 controller.abort 路径 kill（killed=true）。
@@ -259,8 +286,14 @@ export function killAllSpawnedChildren(signal: NodeJS.Signals = "SIGTERM"): numb
     try {
       child.kill(signal);
       n++;
-    } catch {
-      // best-effort：单个 kill 失败不影响其他子进程
+    } catch (err) {
+      // best-effort：单个 kill 失败不影响其他子进程（常见于进程刚退出、句柄竞态），
+      // debug 级留诊断线索即可，不刷 info/warn
+      logger.debug(
+        `[session-runner] killAllSpawnedChildren: kill failed (best-effort continue): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
     }
   }
   // dispose 全量清理；正常路径的 close/error 事件 delete 保留作 per-child 精细清理，
@@ -271,6 +304,37 @@ export function killAllSpawnedChildren(signal: NodeJS.Signals = "SIGTERM"): numb
   return n;
 }
 
+/**
+ * 按 record id 查活子进程（busy 投递定位用，设计决策 6）。
+ *
+ * spawnedChildren 的 record→child 映射查询入口。busy 投递（follow_up/steer）需定位
+ * record 对应的活 ChildProcess 写 stdin；进程 close/error 后已从 Map 移除，返回 undefined。
+ *
+ * @param recordId ExecutionRecord.id
+ * @returns 活子进程；record 无活进程（未注册 / 已退出）时 undefined
+ */
+export function getChildByRecord(recordId: string): ChildProcess | undefined {
+  return spawnedChildren.get(recordId);
+}
+
+/**
+ * [M4 记账竞态守卫] 仅当 Map 当前值仍是本 child 句柄时才删除注册。
+ *
+ * 背景：spawnedChildren 是 Map<recordId, ChildProcess>，resume spawn 会 set 覆盖旧句柄。
+ * 旧 child 的 close/error 事件异步到达（kill 后 close 回调可能晚数 tick），若 close/error
+ * handler 无条件 delete(record.id)，会误删 resume spawn 刚注册的**新** child——
+ * 时序：idle timer 对旧 child SIGTERM（killed=true 但 close 未到）→ deliverMessage 判
+ * child.killed 走冷路径 resumeRound → spawn 新 child set 覆盖 → 旧 child close 此刻到达 →
+ * 误删新注册。后果：新活进程脱离记账（killAllSpawnedChildren 漏杀孤儿 + getChildByRecord
+ * undefined → busy 投递再走冷路径二次 resume → 两进程写同一 session 文件，v4 A-5 注释
+ * 自述的 P7 双写者事故模式）。按句相等守卫：set 覆盖后旧句柄 ≠ Map 当前值，天然跳过。
+ */
+function removeChildRegistration(recordId: string, child: ChildProcess): void {
+  if (spawnedChildren.get(recordId) === child) {
+    spawnedChildren.delete(recordId);
+  }
+}
+
 // ============================================================
 // 依赖注入容器 + 入参
 // ============================================================
@@ -291,8 +355,10 @@ export interface SessionRunnerContext {
    * worktree 子进程 pid 就绪回调（first header 时触发）。
    * Runtime 层接线为 WorktreeManager.registerPid，用于注册表补全 pid。
    * 解耦 Core 与 Runtime——session-runner 不直接依赖 WorktreeManager。
+   * [D5a] 返回 Promise（注册表 pid 补全走跨进程锁内 RMW）；实现方保证不 reject
+   * （WorktreeRegistry.mutate 内部降级兜底），本侧 fire-and-forget 安全。
    */
-  onWorktreePid?: (branch: string, pid: number) => void;
+  onWorktreePid?: (branch: string, pid: number, sessionFile?: string) => void | Promise<void>;
   /**
    * UI 请求处理回调。子进程发 extension_ui_request 时调用。
    *
@@ -322,6 +388,22 @@ export interface SessionRunnerContext {
    *  mainCwd=checkout 路径，rootCwd 贯穿真 ROOT——session 文件落盘统一用 ROOT cwd 编码，
    *  主进程磁盘重建才能看到全树（设计 recursive-subagent-visibility.md）。 */
   rootCwd: string;
+  /**
+   * [V2 模块 3] chatMode 本轮完成通知挂载点。
+   *
+   * V2 决策：chatMode 进程长驻（agent_end 不 kill），「本轮完成」的真空闲边界是
+   * `agent_settled`（agent_end 之后、post-run 完成后 emit，见 pi `agent-session.js`
+   * `_runAgentPrompt` finally 块），而非 agent_end（agent_end 时 post-run 可能仍在跑）。
+   * session-runner 在 agent_settled 时调本回调，调用方（subagent-service）注入
+   * notifyComplete 通知父 agent。
+   *
+   * **本步只定义挂载点，不接线**：subagent-service 未改，回调未注入 = no-op。
+   * notify 端到端 + runSpawn resolve 语义重构留 Step 4（与统一投递 + subagent-service
+   * 一起系统处理）。非 chatMode 路径不触发 agent_settled handler，本字段无影响。
+   *
+   * @param record 当前 ExecutionRecord（chatMode、已完成本轮）
+   */
+  onRoundSettled?: (record: ExecutionRecord) => void;
 }
 
 /** SessionRunner.run 的入参。 */
@@ -363,6 +445,29 @@ export interface RunOptions {
   parentForkDepth?: number;
 }
 
+/**
+ * resume spawn 选项——重开已结束的 session 文件继续对话（M1 基建）。
+ *
+ * resume 时 pi 子进程用 `--session <sessionFile> --mode rpc` 续写原文件（探针 P-1/P-8
+ * 实测：路径不变、entry 续写、上下文保留）。runSpawn 收到此参数后：
+ *   - buildSpawnArgs 追加 `--session <sessionFile>`
+ *   - record.sessionFile 提前设为 resume.sessionFile（handshake 只验证 spawn 成功，不覆盖）
+ *   - model/thinkingLevel 优先用此处的值（防多轮对话模型漂移，探针 P-10），否则回退 opts.resolved
+ *
+ * 注意：M1 只暴露能力，messageHandler（M2）才会真正调用。
+ */
+export interface SpawnResumeOpts {
+  /** resume 目标 session 文件绝对路径（pi `--session` 参数值）。 */
+  sessionFile: string;
+  /**
+   * resume 时覆盖的 model（`"provider/id"` 格式，防漂移，探针 P-10 证明必须传）；
+   * 不传则回退 opts.resolved。
+   */
+  model?: string;
+  /** resume 时覆盖的 thinkingLevel；不传则回退 opts.resolved。 */
+  thinkingLevel?: string;
+}
+
 // ============================================================
 // D-A6 schemaEnv bridge
 // ============================================================
@@ -387,12 +492,13 @@ export function applySchemaEnvToChildEnv(
 // Schema 指令
 // ============================================================
 
-/** formatSchemaInstruction 的 JSON pretty-print 缩进。 */
-const SCHEMA_JSON_INDENT = 2;
-
 /**
  * 构造 schema 指令模板（拼入 task 末尾 + steer reminder 复用）。
  * 指令明确要求 agent 调用 structured-output tool，而非直接输出 JSON 文本。
+ *
+ * schema JSON 的 pretty-print（indent=2）由 shared/schema-jsonify.ts 的
+ * stringifySchemaCached(schema, "pretty") 产出（IF7：与 resolver 的 compact 版
+ * 共享 WeakMap 缓存条目，输出与 JSON.stringify(schema, null, 2) 逐字节一致）。
  */
 export function formatSchemaInstruction(schema: Record<string, unknown>): string {
   return [
@@ -403,7 +509,9 @@ export function formatSchemaInstruction(schema: Record<string, unknown>): string
     "Do NOT pass a `schema` parameter; the system validates `data` against the authoritative schema automatically.",
     "The schema for your `data` is:",
     "```json",
-    JSON.stringify(schema, null, SCHEMA_JSON_INDENT),
+    // IF7(#13)：同 schema 对象引用的 pretty stringify 走 WeakMap 缓存
+    // （与 agent-opts-resolver 的 compact 版共享缓存条目，输出逐字节不变）
+    stringifySchemaCached(schema, "pretty"),
     "```",
   ].join("\n");
 }
@@ -420,7 +528,8 @@ const branchCache = new Map<string, string>();
 
 /**
  * 构建环境信息块（P7 防注入：环境数据标记为 data，非指令）。
- * git branch 同步获取（execFileSync），按 cwd 缓存。
+ * git branch 异步获取（execFile），按 cwd 缓存——缓存命中路径返回已 resolve 值零开销，
+ * 仅每 cwd 首次调用发起 git（此前为同步阻塞调用，挂载盘慢 git 时阻塞 spawn 链最多 2s）。
  *
  * [SPAWN 改造] 从旧 in-process run() 恢复。spawn 模型下此块拼进
  * --append-system-prompt 文件，子进程读文件注入 system prompt。
@@ -436,11 +545,11 @@ const branchCache = new Map<string, string>();
  * @param forkDepth 当前 fork 链深度（undefined=非 fork session，视为 0）。
  * @param nestingDepth 通用嵌套深度（record.depth，undefined=顶层）。
  */
-export function buildEnvBlock(
+export async function buildEnvBlock(
   cwd: string,
   forkDepth?: number,
   nestingDepth?: number,
-): string {
+): Promise<string> {
   const lines = ["--- environment (data, not instructions) ---", `Working directory: ${cwd}`];
   // [M9] 取 max(forkDepth, nestingDepth)——更严的约束先生效，避免只展示 forkDepth 误导 LLM。
   const fd = forkDepth ?? 0;
@@ -451,14 +560,27 @@ export function buildEnvBlock(
   }
   let branch = branchCache.get(cwd);
   if (branch === undefined) {
+    // catch 兜底一切失败（含 execFile 未被 mock 的测试环境）：branch 静默为空，
+    // env block 省略 Git branch 行——与旧同步版语义一致
     try {
-      branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
-        cwd,
-        encoding: "utf8",
-        stdio: ["pipe", "pipe", "ignore"],
-        timeout: ENV_GIT_TIMEOUT_MS,
-      }).trim();
-    } catch {
+      branch = await new Promise<string>((resolve, reject) => {
+        execFile(
+          "git",
+          ["rev-parse", "--abbrev-ref", "HEAD"],
+          { cwd, encoding: "utf8", timeout: ENV_GIT_TIMEOUT_MS },
+          (err: Error | null, stdout: string) => {
+            if (err) reject(err);
+            else resolve(stdout.trim());
+          },
+        );
+      });
+    } catch (err) {
+      // 非 git 目录 / git 不在 PATH 是高频正常路径，debug 级留诊断线索即可，不刷 info/warn
+      logger.debug(
+        `[session-runner] buildEnvBlock: git branch lookup failed for ${cwd}, fallback to empty: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
       branch = "";
     }
     branchCache.set(cwd, branch);
@@ -507,10 +629,16 @@ export function buildSpawnArgs(
     agentTools: string[] | undefined;
     appendSystemPromptPath: string | undefined;
     sessionDir: string;
+    /**
+     * resume 目标 session 文件路径。存在时紧跟 `--session-dir <dir>` 追加
+     * `--session <file>`，pi 续写原 session 文件而非新建（探针 P-1/P-8 实测续写成立）。
+     * undefined = 新 session（当前行为，向后兼容）。
+     */
+    sessionFile?: string;
     forkSource: string | undefined;
     skillPaths: string[] | undefined;
     /**
-     * 镜像自主进程 argv 的 flag（--no-extensions/--approve/--extension）。
+     * 镜像自主进程 argv 的 flag（--no-extensions/--approve/--extension/--no-context-files）。
      * undefined 或全空/全 false 时行为不变（向后兼容）。
      */
     mirrorFlags?: MirrorFlags;
@@ -520,6 +648,10 @@ export function buildSpawnArgs(
   // positional task arg / -p flag 在 rpc mode 下被 resolveAppMode 无视。
   // task 由 runSpawn 内 sendPromptCommand 写 child.stdin 驱动。
   const args: string[] = ["--mode", "rpc", "--session-dir", params.sessionDir];
+  // resume：紧跟 --session-dir 追加 --session <file>，pi 续写原 session 文件（P-8）。
+  if (params.sessionFile) {
+    args.push("--session", params.sessionFile);
+  }
   if (params.model) args.push("--model", params.model);
   if (params.thinkingLevel && params.model) {
     // thinking level 通过 model 后缀 :level 传递（pi CLI 约定）
@@ -543,12 +675,17 @@ export function buildSpawnArgs(
       args.push("--skill", sp);
     }
   }
-  // 镜像主进程的 extension/approve flag：让子进程 extension 加载行为与主进程一致。
-  // undefined/空值时不追加（向后兼容）。顺序紧跟 skill 之后，注入类 flag 集中。
+  // 镜像主进程的 extension/approve/context-files flag：让子进程 extension 加载与
+  // context files 行为与主进程一致。undefined/空值时不追加（向后兼容）。顺序紧跟
+  // skill 之后，注入类 flag 集中。
   const mf = params.mirrorFlags;
   if (mf) {
     if (mf.noExtensions) args.push("--no-extensions");
     if (mf.approve) args.push("--approve");
+    // 镜像 --no-context-files：@zhushanwen/pi-system-prompt（经 --extension 镜像进入
+    // 子进程）靠子进程 argv 检测此 flag 守卫全局 AGENTS.md 注入——不镜像则用户的
+    // context files opt-out 只对主进程生效，每个 subagent 仍被注入。
+    if (mf.noContextFiles) args.push("--no-context-files");
     for (const ep of mf.extensionPaths) {
       args.push("--extension", ep);
     }
@@ -557,18 +694,69 @@ export function buildSpawnArgs(
 }
 
 /**
- * spawn pi 子进程执行 session。
+ * [持久化 C] best-effort 写 alive marker（running 期间崩溃恢复用，子进程 pid + session id）。
  *
- * 契约与 run() 一致：正常路径不抛错（prompt 失败/turn-limit abort/子进程崩溃
- * 均合成 failed AgentResult 返回）。创建期异常（spawn 本身失败）会抛。
+ * 两处调用点（header 分支 / get_state 握手回填）原为两段相同的空 catch try/catch——
+ * 收敛为单函数后失败走 debug 日志（marker 是崩溃恢复的增强信号，缺失只降低可恢复性，
+ * 不影响执行主流程），消除 taste/no-silent-catch。
  */
-export async function runSpawn(
-  record: ExecutionRecord,
-  task: string,
-  opts: RunOptions,
-  ctx: SessionRunnerContext,
-): Promise<AgentResult> {
-  const startTime = Date.now();
+function writeAliveMarkerBestEffort(sessionFile: string, pid: number, id: string): void {
+  try {
+    writeAliveMarker(sessionFile, { pid, id, startedAt: Date.now() });
+  } catch (err) {
+    // best-effort：alive marker 失败不影响执行；debug 级留诊断线索即可，不刷 info/warn
+    logger.debug(
+      `[session-runner] alive marker write failed (best-effort continue): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
+// ============================================================
+// [SPAWN 改造] runSpawn 的阶段拆分（max-lines-per-function 383 > 300）
+// ============================================================
+//
+// runSpawn 原为单函数内联全部闭包（事件累积器 / 参数准备 / stdout pump / 退出等待），
+// 按执行阶段拆为下方模块级私有函数，闭包状态收拢进 SpawnRunState 经参数传递：
+//   - createSpawnEventHandlers：a/b. pendingTools 寄存器 + turnLimiter + handleSdkEvent
+//   - writeAppendSystemPromptFile：g. appendSystemPrompt 片段组装与落盘
+//   - buildChildEnv：h. 子进程环境变量组装
+//   - buildSpawnInvocation：i. pi CLI 参数组装与入口解析
+//   - attachStdoutPump：stdout 逐行解析 + get_state 握手状态机 + agent_end keep-alive
+//   - waitForChildExit：close/error → exitCode（含统一 cleanup）
+// 拆分只移动代码不改行为——runSpawn 导出签名与事件语义不变。
+
+/** runSpawn 各阶段共享的可变状态（原闭包变量收拢，经参数在阶段函数间传递）。 */
+interface SpawnRunState {
+  record: ExecutionRecord;
+  opts: RunOptions;
+  ctx: SessionRunnerContext;
+  /** 当前子进程句柄（limiter abort 经此 kill）。 */
+  proc: ChildProcess | undefined;
+  /** watchdog timer（stdout handler 的 agent_end keep-alive 分支重挂，收尾统一 clearTimeout）。 */
+  watchdog: NodeJS.Timeout | undefined;
+  /** stdout 首行 header（json mode 才有；RPC mode 恒 undefined）——收尾 sessionFile 兜底查找用。 */
+  sessionHeader: SpawnSessionHeader | undefined;
+  /** get_state 握手结果（RPC mode）——收尾 sessionFile 兜底查找用。 */
+  handshakeResult: GetStateResult | undefined;
+  /**
+   * [V2 决策 2] chatMode 首轮 resolveRun：agent_settled 时提前 resolve runSpawn 的
+   * exitCode promise（waitForChildExit 装配指向）。非 chatMode 不触发（agent_end
+   * handler 一次性 kill → close resolve）。chatMode 后续轮次到达时 resolve(code)
+   * 是 no-op（Promise 只 resolve 一次）。
+   */
+  resolveRun: ((code: number) => void) | undefined;
+}
+
+/**
+ * 事件累积器工厂（原 runSpawn 内联的 a/b 两段 + handleSdkEvent/agentEvent 闭包）。
+ *
+ * pendingTools 寄存器 / turnLimiter / accumulateMessageEnd 均闭包在工厂内部，
+ * 对外只暴露 handleSdkEvent（stdout 解析出的 SdkEvent 的唯一喂入口）。
+ */
+function createSpawnEventHandlers(state: SpawnRunState): (raw: SdkEvent) => void {
+  const { record, opts, ctx } = state;
 
   // a. transient 寄存器（同 run()：tool_end 缺 args 时回填）
   const pendingTools = new Map<string, { toolName: string; args?: unknown }>();
@@ -576,8 +764,7 @@ export async function runSpawn(
   // b. turnLimiter（spawn 版：abort = proc.kill；steer 是 no-op）
   // [M1] rpc mode 是长驻进程（agent_end 后不自动退出），maxTurns soft limit 依赖
   // graceTurns 后的 abort（proc.kill SIGTERM）兑现。agent 自然结束时由 stdout pump
-  // 的 agent_end 拦截 kill（见下方）。steer 通道当前未接通（见下方 steer no-op 注释）。
-  let proc: ChildProcess | undefined;
+  // 的 agent_end 拦截 kill（见 attachStdoutPump）。steer 通道当前未接通（见下方 steer no-op 注释）。
   const limiter = createTurnLimiter({
     maxTurns: opts.maxTurns ?? 0,
     graceTurns: opts.graceTurns ?? DEFAULT_GRACE_TURNS,
@@ -586,13 +773,20 @@ export async function runSpawn(
       // 但未实现写入逻辑）。补偿已在启动时注入 WRAP_UP_HINT 让 agent 主动收尾。
     },
     abort: () => {
-      proc?.kill("SIGTERM");
+      state.proc?.kill("SIGTERM");
     },
   });
 
-  // c. schema 指令拼到 task 末尾（替代 in-process 的 turn_end steer 循环）
-  const instruction = opts.schema ? formatSchemaInstruction(opts.schema) : ""
-  const fullTask = task + instruction;
+  // agentEvent 统一出口：updateFromEvent + onTurnEnd（limiter）+ opts.onEvent
+  const agentEvent = (event: AgentEvent): void => {
+    updateFromEvent(record, event);
+    if (event.type === "turn_end") limiter.onTurnEnd(record.turnCount);
+    // text_delta 分流到 stream 通道（在 onEvent 之前）。
+    // 双通道互斥设计：background 路径 stream 有值、onEvent=undefined；
+    // workflow 路径 onEvent 有值、stream=undefined。详见 W3 注释。
+    if (event.type === "text_delta") opts.stream?.onDelta(event.delta);
+    opts.onEvent?.(event);
+  };
 
   // ── SDK 事件累积器（闭包模式与 run() 完全相同）──
   const accumulateMessageEnd = (raw: SdkEvent): void => {
@@ -610,6 +804,31 @@ export async function runSpawn(
   };
 
   const handleSdkEvent = (raw: SdkEvent): void => {
+    // [V2 模块 3] agent_settled：真空闲边界（agent_end 之后、post-run 完成后才 emit）。
+    // chatMode：arm idle timer（超时 SIGTERM 回收）+ 通知本轮完成（onRoundSettled）。
+    // 非 chatMode：忽略（agent_end handler 的一次性 kill 已处理，进程不会活到 agent_settled）。
+    if (isAgentSettledEvt(raw)) {
+      if (record.chatMode) {
+        armIdleTimer(record.id, () => {
+          // onTimeout 复用现有 kill 路径：child.kill("SIGTERM") 触发 close → close handler
+          // 统一 cleanup（spawnedChildren.delete / get_stateListeners.clear / resolve）。
+          // 与 agent_end handler 现有 SIGTERM 分支一致，不新造 cleanup。
+          const child = getChildByRecord(record.id);
+          if (child && !child.killed) child.kill("SIGTERM");
+        }, record.idleTimeoutMs);
+        // [SP-9] chatMode 每轮 reset turn-limiter：新一轮开始（续聊）时，
+        // maxTurns/graceTurns 不跨轮累计（续聊本质是无限轮，累计上限违背 G1）。
+        // reset steered/aborted 标志 + turnCount 归零，下一轮独立计数。
+        limiter.reset();
+        record.turnCount = 0;
+        ctx.onRoundSettled?.(record);
+        // [V2 决策 2] chatMode 首轮：agent_settled = 本轮真空闲，提前 resolve runSpawn
+        //（exit code 0，进程仍保活 idle timer armed）。runAndFinalize 拿到 result 后走
+        // chatMode 首轮分支（不进 finalize 分流），onRoundSettled 已 notify 主 agent。
+        state.resolveRun?.(0);
+      }
+      return;
+    }
     switch (raw.type) {
       case "tool_execution_start": {
         const toolName = raw.toolName ?? "";
@@ -649,46 +868,35 @@ export async function runSpawn(
         agentEvent({ type: "compaction" });
         return;
       }
+      // [review 修复] 已删除 turn_start / message_start 两 case 的 pendingMessages
+      // 消费确认 shift（MF-5）：三段消费链（deliverToRunning push / message_start(user)
+      // shift / redeliverPending 补投）随 deliverToRunning 一并移除——SP-5 upgrade 后
+      // 无生产调用方，整条链路不可达。两 case 均为 no-op，落 default 即可。
       default:
         return;
     }
   };
 
-  // agentEvent 统一出口：updateFromEvent + onTurnEnd（limiter）+ opts.onEvent
-  const agentEvent = (event: AgentEvent): void => {
-    updateFromEvent(record, event);
-    if (event.type === "turn_end") limiter.onTurnEnd(record.turnCount);
-    // text_delta 分流到 stream 通道（在 onEvent 之前）。
-    // 双通道互斥设计：background 路径 stream 有值、onEvent=undefined；
-    // workflow 路径 onEvent 有值、stream=undefined。详见 W3 注释。
-    if (event.type === "text_delta") opts.stream?.onDelta(event.delta);
-    opts.onEvent?.(event);
-  };
-
-  // d. session 目录（与 in-process 一致：list/恢复可发现同一目录）
-  // [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（隔离文件系统）
-  // worktree checkout 已由 worktree-manager 在 execute 前创建，此处只取路径。
-  const spawnCwd = opts.worktree?.path ?? ctx.cwd;
-
-  // f. fork source：父 session 文件路径（--fork 参数）
-  const forkSource = opts.fork ? ctx.mainSessionFile : undefined;
+  return handleSdkEvent;
+}
 
-  // g. appendSystemPrompt 落盘（env block + agent body + 调用方片段拼成 --append-system-prompt 文件）
+/**
+ * g. appendSystemPrompt 落盘：env block + agent body + 调用方片段拼成
+ * --append-system-prompt 文件。返回临时文件句柄（无片段时 undefined，
+ * runSpawn finally 统一清理）。
+ */
+async function writeAppendSystemPromptFile(
+  record: ExecutionRecord,
+  opts: RunOptions,
+  ctx: SessionRunnerContext,
+): Promise<{ dir: string; filePath: string } | undefined> {
   // [M1 恢复] 环境块（cwd / fork depth / git branch）拼在最前面，与旧 in-process
   // buildAppendSystemPrompt 顺序一致——parts[0] 是环境块，其后 agent systemPrompt、再后调用方片段。
   const ownForkDepth = opts.fork ? (opts.parentForkDepth ?? 0) + 1 : undefined;
-  let tempPromptFile: { dir: string; filePath: string } | undefined;
   // [M9] buildEnvBlock 取 max(forkDepth, nestingDepth)：record.depth === nestingDepth（都从
   // execCtxAls 派生，见 createRecordForMode L425-427 与 execute L257-258），传它让 env block
   // 展示更严的约束（混合嵌套链下通用护栏可能先于 fork 护栏拒绝）。
-  const appendParts: string[] = [buildEnvBlock(ctx.cwd, ownForkDepth, record.depth)];
+  const appendParts: string[] = [await buildEnvBlock(ctx.cwd, ownForkDepth, record.depth)];
   if (opts.agentConfig?.systemPrompt) appendParts.push(opts.agentConfig.systemPrompt);
   if (opts.appendSystemPrompt) appendParts.push(...opts.appendSystemPrompt);
   // [M1 补偿] rpc mode 的 steer 通道当前未接通，改为启动时预置 wrap-up 提示——
@@ -705,10 +913,20 @@ export async function runSpawn(
     appendParts.push(WORKTREE_GUIDANCE_PROMPT);
   }
   if (appendParts.length > 0) {
-    tempPromptFile = await writePromptToTempFile(record.agent, appendParts.join("\n\n"));
+    return writePromptToTempFile(record.agent, appendParts.join("\n\n"));
   }
+  return undefined;
+}
 
-  // h. fork depth 经环境变量传给子进程（子进程 subagents 扩展 W3 读取）
+/**
+ * h. 子进程环境变量组装：继承 process.env + fork depth + 跨进程身份贯穿 4 元组 +
+ * identity 专属字段 + worktree 隔离标志 + schemaEnv bridge。
+ */
+function buildChildEnv(
+  record: ExecutionRecord,
+  opts: RunOptions,
+  ctx: SessionRunnerContext,
+): Record<string, string | undefined> {
   const childEnv: Record<string, string | undefined> = { ...process.env };
   if (opts.fork && opts.parentForkDepth !== undefined) {
     childEnv.PI_SUBAGENT_FORK_DEPTH = String(opts.parentForkDepth + 1);
@@ -727,33 +945,390 @@ export async function runSpawn(
   // 子进程的 store/runSpawn 落盘目录须统一编码在 enc(ROOT cwd) 段（与身份贯穿同构），
   // 否则 ROOT 磁盘重建扫不到深层 record（见 subagent-service ENV_ROOT_CWD 注释）。
   childEnv.PI_SUBAGENT_ROOT_CWD = ctx.rootCwd;
+  // [M4 identity 子进程写] 子进程 session_start hook 读这些 env → pi.appendEntry 写
+  // subagent-identity custom entry（V2 决策 5）。旧实现父进程 fs.appendFileSync 补写的
+  // custom entry 缺 id/parentId → 污染 pi _buildIndex leafId → message tree 断成两棵
+  // → 多轮对话丢上下文。改由子进程（session 文件所有者）用 appendEntry 写，pi 自动生成 id/parentId。
+  // id/rootSessionId/depth/forkDepth 复用上方身份贯穿 env（SELF_RECORD_ID/ROOT_SESSION_ID/DEPTH/FORK_DEPTH），
+  // 此处补 identity 专属字段：agent/mode/task/slug/startedAt/parentRecordId/chatMode。
+  childEnv.PI_SUBAGENT_AGENT = record.agent;
+  childEnv.PI_SUBAGENT_MODE = record.mode;
+  childEnv.PI_SUBAGENT_TASK = record.task;
+  childEnv.PI_SUBAGENT_SLUG = record.slug;
+  childEnv.PI_SUBAGENT_STARTED_AT = String(record.startedAt);
+  childEnv.PI_SUBAGENT_PARENT_RECORD_ID = record.parentRecordId;
+  childEnv.PI_SUBAGENT_CHAT_MODE =
+    record.chatMode !== undefined ? String(record.chatMode) : undefined;
+  // [review round2] worktree 隔离标志贯穿：resume 轮 opts.worktree 来自 record.worktreeHandle
+  //（同进程内保留），子进程 identity entry 据此记 worktree:true——跨重启重建时据此拒绝续聊
+  //（WorktreeHandle 不可序列化，reattach 不可行，静默回落主 repo 会破坏隔离）。
+  childEnv.PI_SUBAGENT_WORKTREE = opts.worktree !== undefined ? "true" : undefined;
   // D-A6 bridge: schema 激活 structured-output 扩展注册 tool（workflow 编排层需要）
   applySchemaEnvToChildEnv(childEnv, opts.schemaEnv);
+  return childEnv;
+}
 
-  // i. 组装 args + spawn
+/**
+ * i. 组装 spawn args 并解析 pi 可执行入口。
+ */
+function buildSpawnInvocation(
+  opts: RunOptions,
+  ctx: SessionRunnerContext,
+  resume: SpawnResumeOpts | undefined,
+  tempPromptFile: { dir: string; filePath: string } | undefined,
+  sessionDir: string,
+  forkSource: string | undefined,
+): ReturnType<typeof getPiInvocation> {
   // [M3 恢复] skillPaths: 主 session 的 skillDirs + 调用方传入的 skillPath。
   // ADR-031 后 skillDirs 固定为空，仅 opts.skillPath 生效（agent({skill}) 解析）。
   const skillPaths = [...ctx.skillDirs, opts.skillPath].filter(
     (p): p is string => typeof p === "string" && p.length > 0,
   );
   const modelId = opts.resolved.model.id;
+  // [M1 resume] resume 时 model/thinkingLevel 优先用 resume 值（防多轮对话模型漂移，P-10），
+  // 否则回退 opts.resolved。resume.model 已是 "provider/id" 格式，与 buildSpawnArgs 约定一致。
+  const effectiveModel = resume?.model ?? `${opts.resolved.model.provider}/${modelId}`;
+  const effectiveThinkingLevel = resume?.thinkingLevel ?? opts.resolved.thinkingLevel;
   const spawnArgs = buildSpawnArgs(
     {
-      model: `${opts.resolved.model.provider}/${modelId}`,
-      thinkingLevel: opts.resolved.thinkingLevel,
+      model: effectiveModel,
+      thinkingLevel: effectiveThinkingLevel,
       agentTools: opts.agentConfig?.tools,
       appendSystemPromptPath: tempPromptFile?.filePath,
       sessionDir,
+      sessionFile: resume?.sessionFile,
       forkSource,
       skillPaths: skillPaths.length > 0 ? skillPaths : undefined,
       // 镜像主进程 argv 的 extension/approve flag，让子进程加载行为对齐主进程
       mirrorFlags: mirrorMainProcessFlags(process.argv),
     },
   );
-  const invocation = getPiInvocation(spawnArgs);
+  return getPiInvocation(spawnArgs);
+}
+
+/** attachStdoutPump 返回的共享句柄（waitForChildExit / get_state 握手启动消费）。 */
+interface StdoutPumpHandles {
+  /** get_state RPC response 监听器注册（performGetStateHandshake 经此挂 resolver）。 */
+  registerGetStateListener(id: string, resolver: (data: unknown) => void): void;
+  /** 握手完成统一入口：记录结果 + 回填 sessionFile + 写 alive marker + settle。 */
+  finishHandshake(r: GetStateResult): void;
+  /** 立即放弃握手（close handler 用：子进程已退出，response 不会再来）。 */
+  abandonHandshake(): void;
+  /** 握手是否仍未 settle（header 加速路径 / get_state then 分支的覆盖守卫）。 */
+  isHandshakePending(): boolean;
+  /** 握手 settle promise（close handler await，保证回填结果对后续 identity 写入可见）。 */
+  readonly handshakeSettled: Promise<void>;
+  /** 处理 stdout 末尾残留行（无换行结尾的最后一段，close handler 用）。 */
+  processTrailingLine(): void;
+  /** 清空 get_state 监听器（子进程已退出，无更多 response）。 */
+  clearGetStateListeners(): void;
+}
+
+/**
+ * stdout pump + get_state 握手状态机（原 runSpawn 内联的 stdout data handler 整体迁入）。
+ *
+ * 逐行解析 stdout：header（json mode）/ SdkEvent / RPC response / UI 请求分发；
+ * agent_end（willRetry=false）的条件 kill（keep-alive 分支重挂 state.watchdog）也在此。
+ * 返回 StdoutPumpHandles 供 close handler 与握手启动方消费。
+ */
+function attachStdoutPump(
+  child: ChildProcessWithoutNullStreams,
+  state: SpawnRunState,
+  sessionDir: string,
+  handleSdkEvent: (raw: SdkEvent) => void,
+): StdoutPumpHandles {
+  const { record, opts, ctx } = state;
+
+  // stdout pump：逐行解析 → handleSdkEvent / enqueueUiRequest
+  const enqueueUiRequest = createUiRequestQueue(child, ctx);
+  // FR-4: get_state RPC response 监听器（id → resolver）。
+  // parseSpawnLine 返回 kind:"response" 时，按 command+id 匹配 resolver。
+  const get_stateListeners = new Map<string, (data: unknown) => void>();
+  let stdoutBuffer = "";
+
+  // [#18] 握手状态变量在 stdout handler 注册之前定义，消除"handler 闭包依赖同 tick
+  // 后续 const 初始化"的隐式顺序假设——handler 现在直接引用已初始化的变量，不靠
+  // "data 事件必然在下一 tick 才触发"的运行时不变式兜底。
+  let settleHandshake: (() => void) | undefined;
+  const handshakeSettled: Promise<void> = new Promise((resolveSettled) => {
+    settleHandshake = resolveSettled;
+  });
+
+  const settleHandshakeNow = (): void => {
+    settleHandshake?.();
+    settleHandshake = undefined;
+  };
+
+  /** 握手完成统一入口：记录结果 + 回填 sessionFile + 写 alive marker + settle。 */
+  const finishHandshake = (r: GetStateResult): void => {
+    state.handshakeResult = r;
+    // 仅当 header 未先行设置 record.sessionFile 时回填（RPC mode 路径）。
+    if (r.sessionFile && !record.sessionFile) {
+      record.sessionFile = r.sessionFile;
+      if (child.pid) {
+        writeAliveMarkerBestEffort(r.sessionFile, child.pid, r.sessionId ?? record.id);
+      }
+    }
+    settleHandshakeNow();
+  };
+
+  child.stdout.on("data", (data: string) => {
+    stdoutBuffer += data;
+    const lines = stdoutBuffer.split("\n");
+    stdoutBuffer = lines.pop() ?? ""; // 保留最后未完整行
+    for (const line of lines) {
+      const parsed = parseSpawnLine(line);
+      if (!parsed) continue;
+      if (parsed.kind === "header") {
+        state.sessionHeader = parsed.header;
+        // 回填 record.sessionFile（deriveSessionFilePath 推导路径）
+        record.sessionFile = deriveSessionFilePath(parsed.header, sessionDir);
+        // [持久化 C] alive marker：running 期间崩溃恢复用。子进程 pid + session id。
+        // 与 in-process 逻辑对齐（记 sessionFile + pid），改为子进程 pid。
+        if (record.sessionFile && child.pid) {
+          writeAliveMarkerBestEffort(record.sessionFile, child.pid, parsed.header.id);
+        }
+        // [全局注册表] worktree 模式：补全注册表条目的 pid。
+        // create 时 pid 未知写 0 占位，此处拿到 child.pid 后回调 WorktreeManager.registerPid。
+        // 取代旧的 .session mapping sidecar——注册表是 reaper 的唯一数据源。
+        // [D5a] fire-and-forget：回调内部走跨进程锁（毫秒级），且实现方保证不
+        // reject（锁降级兜底）；stdout data 回调是同步上下文，不 await。
+        if (opts.worktree && child.pid) {
+          // 透传 record.sessionFile：填入 registry entry（reaper 据 pid 死活判孤儿），
+          // first header 时 sessionFile 已回填（deriveSessionFilePath 在本分支上方）。
+          try {
+            void ctx.onWorktreePid?.(opts.worktree.branch, child.pid, record.sessionFile);
+          } catch (err) {
+            // 同步段异常（回调本身 throw）不阻断 stdout 解析；锁内错误由回调内部 warn。
+            bestEffort(err, "onWorktreePid callback (first header)");
+          }
+        }
+        // FR-4 加速路径：header 到达即 finishHandshake（header 已提供 sessionId，
+        // 足以推导 sessionFile + 兜底查找，无需等 get_state response）。
+        // [#25] buildSpawnArgs 固定 --mode rpc，RPC mode 不发 header——此分支当前不触发，
+        // 仅为未来 mode 回切（如 json mode 调试）保留：届时 header 先到可省去 get_state 握手等待。
+        if (settleHandshake) {
+          finishHandshake({
+            ...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
+            sessionId: parsed.header.id,
+          });
+        }
+      } else if (parsed.kind === "event") {
+        const evt = parsed.event;
+        // agent_end（willRetry=false）= agent 自然完成。rpc mode 子进程不自动退出
+        //（runRpcMode 末尾 return new Promise(() => {}) 长驻等命令），需主动 kill
+        // 触发 close → runSpawn resolve。willRetry=true 时 agent 会重试，不能 kill。
+        if (isAgentEndEvt(evt)) {
+          if (evt.willRetry) {
+            // agent 会重试，不能 kill。
+          } else {
+            // [V2 决策 1] chatMode：对话模式进程不因轮次死。agent_end 不 kill、不 MF-3/MF-4。
+            // 等待 agent_settled（真空闲信号）arm idle timer + notify（onRoundSettled）。
+            // 用 continue 而非 return：return 会跳出 stdout data handler 的 for(line) 循环，
+            // 丢弃同一 flush 内 agent_end 之后的事件（如紧随的 agent_settled）。continue 只
+            // 跳过当前行剩余（handleSdkEvent 对 agent_end 是 no-op），继续处理后续行。
+            if (record.chatMode) {
+              continue;
+            }
+            // [recursive-orchestration] 条件 kill：读子进程 session 文件算活跃后代
+            // （pending:register − unregister 差集）。有活跃后代（background subagent /
+            // workflow）→ 保持进程 idle，等后代完成时 notifier triggerTurn steer 唤醒；
+            // 无 → 正常完成，kill 触发 close → runSpawn resolve。
+            const pending = readActivePendingFromSessionFile(record.sessionFile);
+            if (pending.count > 0 || pending.error) {
+              if (pending.error) {
+                logger.warn(
+                  `[session-runner] agent_end: keep alive (sessionFile unreadable, conservative): ${pending.error}`,
+                );
+              } else {
+                logger.debug(
+                  `[session-runner] agent_end: keep alive, ${pending.count} active descendant(s) pending`,
+                );
+              }
+              // 空闲等待期间不消耗 turn：清原 watchdog，换等待后代超时（每次 agent_end 重新计时）。
+              // [MF-4] 动态超时 = computeWatchdogMs(maxTurns)：真实后代在跑，慢任务（wave 开发
+              // 数小时）不能被固定 2h 误杀——2h 到点 kill 会连坐 SubagentService.dispose 的
+              // killAllSpawnedChildren 杀全部子进程，L2 重派丢在途工作。maxTurns 大则超时长。
+              clearTimeout(state.watchdog);
+              state.watchdog = setTimeout(() => child.kill("SIGTERM"), computeWatchdogMs(opts.maxTurns));
+              state.watchdog.unref();
+            } else if (pending.recentUnregister) {
+              // 差集 0 但最近有 unregister：后代刚完成，notify 唤醒可能在路上（竞态窗口），
+              // 保持进程——父被唤醒后的下一次 agent_end 会正常判定。
+              // [MF-3] 秒级宽限：此分支在每层「最终 turn」必命中（closeout 的 agent_end 距
+              // 最后一次 unregister <60s），挂长超时 = 空等 2h 才 kill + 冒牌完成通知级联。
+              // 15s 内无新 agent_end（未被唤醒）即 kill；被唤醒后下一次 agent_end 重新评估。
+              logger.debug(
+                "[session-runner] agent_end: keep alive, recent descendant completion (wake-up in flight)",
+              );
+              clearTimeout(state.watchdog);
+              state.watchdog = setTimeout(() => child.kill("SIGTERM"), WAKEUP_GRACE_MS);
+              state.watchdog.unref();
+            } else {
+              child.kill("SIGTERM");
+            }
+          }
+        }
+        if (isSdkEvent(parsed.event)) handleSdkEvent(parsed.event);
+      } else if (parsed.kind === "response") {
+        // FR-4: RPC response handling — 匹配 get_state 响应
+        if (parsed.command === "get_state" && parsed.success && parsed.id) {
+          const resolver = get_stateListeners.get(parsed.id);
+          if (resolver) {
+            get_stateListeners.delete(parsed.id);
+            resolver(parsed.data);
+          }
+        }
+      } else if (parsed.kind === "extension_ui_request") {
+        // W3: 子进程发 UI 请求（ask_user）。入队 FIFO 串行处理，防止并发询问用户。
+        enqueueUiRequest(parsed.id, parsed.request);
+      }
+      // invalid 行忽略（stdout 可能有调试输出）
+    }
+  });
+
+  return {
+    registerGetStateListener: (id, resolver) => {
+      get_stateListeners.set(id, resolver);
+    },
+    finishHandshake,
+    abandonHandshake: settleHandshakeNow,
+    isHandshakePending: () => settleHandshake !== undefined,
+    handshakeSettled,
+    processTrailingLine: () => {
+      // 处理 stdout 末尾残留行
+      if (stdoutBuffer.trim()) {
+        const parsed = parseSpawnLine(stdoutBuffer);
+        if (parsed?.kind === "event" && isSdkEvent(parsed.event)) {
+          handleSdkEvent(parsed.event);
+        }
+      }
+    },
+    clearGetStateListeners: () => {
+      get_stateListeners.clear();
+    },
+  };
+}
+
+/**
+ * 等待子进程退出（close/error → exitCode，原 runSpawn 内联的 exit promise 迁入）。
+ *
+ * [V2 决策 2] resolveRun 指向本 promise 的 resolve：chatMode 首轮 agent_settled 时
+ * 由 handleSdkEvent 提前调 resolveRun(0)，close 最终到达时 resolve(code) 是 no-op。
+ * close handler 统一执行 cleanup（句柄移除 / 握手放弃 / 残留行处理）。
+ */
+function waitForChildExit(
+  child: ChildProcessWithoutNullStreams,
+  state: SpawnRunState,
+  spawnCwd: string,
+  pump: StdoutPumpHandles,
+): Promise<number> {
+  return new Promise<number>((resolve) => {
+    state.resolveRun = resolve;
+    child.on("close", async (code: number | null) => {
+      // [C1] 子进程已退出，从 orphan-tracking Map 移除（dispose 兜底无需再 kill 它）。
+      // [M4] 按值守卫：close 事件晚于 resume spawn 到达时不误删新 child 注册。
+      removeChildRegistration(state.record.id, child);
+      // FR-4: 清理 get_state 监听器（子进程已退出，无更多 response）
+      pump.clearGetStateListeners();
+      // FR-4: 子进程已退出，get_state response 不会再来。若握手仍未 settle，立即放弃
+      //（record.sessionFile 未回填则走 findSessionFileByHeaderId 兜底）。避免子进程快速
+      // 失败/退出场景下 close handler 阻塞等待握手内部 6s 超时。
+      pump.abandonHandshake();
+      // await 立即返回（上方已 settle）：保证 header 加速路径或 get_state response 已
+      // 完成的回填结果对后续 identity 写入可见。
+      await pump.handshakeSettled;
+      // 处理 stdout 末尾残留行
+      pump.processTrailingLine();
+      resolve(code ?? 0);
+    });
+    child.on("error", (err: Error) => {
+      // spawn 本身失败（command not found 等）
+      // [worktree-reaper-fix] 拼 spawnCwd 进错误消息：ENOENT 的 err.message 只含 command 名，
+      // 无 cwd 线索（worktree 被 reaper 误删后 cwd 指向虚空）会导致误诊——2026-08-11 事故
+      // AI 误判"node 被卸载"的直接原因。
+      // [M4] 按值守卫：error 事件晚于 resume spawn 到达时不误删新 child 注册。
+      removeChildRegistration(state.record.id, child);
+      // [S3] code 读取带运行时 guard：非 ErrnoException（普通 Error）时 code 为 undefined，
+      // 不加 cwd hint（行为与修复前一致）；仅 ENOENT 才拼 cwd。
+      const errno = err as NodeJS.ErrnoException;
+      const errCode = "code" in err ? errno.code : undefined;
+      const cwdHint = errCode === "ENOENT" ? ` (cwd: ${spawnCwd})` : "";
+      state.record.lastError = `${err.message}${cwdHint}`;
+      resolve(SIGNAL_EXIT_CODE_THRESHOLD); // 非零退出
+    });
+  });
+}
+
+/**
+ * spawn pi 子进程执行 session。
+ *
+ * 契约与 run() 一致：正常路径不抛错（prompt 失败/turn-limit abort/子进程崩溃
+ * 均合成 failed AgentResult 返回）。创建期异常（spawn 本身失败）会抛。
+ *
+ * [拆分] 各执行阶段（事件累积 / 参数准备 / stdout pump / 退出等待）拆到上方
+ * 模块级函数，闭包状态经 SpawnRunState 传递——只移动代码不改行为。
+ */
+export async function runSpawn(
+  record: ExecutionRecord,
+  task: string,
+  opts: RunOptions,
+  ctx: SessionRunnerContext,
+  /** resume 选项（M1 基建）：重开已结束的 session 继续对话。undefined = 新 session。 */
+  resume?: SpawnResumeOpts,
+): Promise<AgentResult> {
+  const startTime = Date.now();
+
+  // [M1 resume 基建] resume 时提前锁定 record.sessionFile：spawn 前已知目标文件，
+  // handshake 的 finishHandshake 内 `!record.sessionFile` 守卫天然跳过回填，
+  // sessionFile 用 resume.sessionFile 不被覆盖（RPC mode 无 header，header 分支也不触发）。
+  if (resume) {
+    record.sessionFile = resume.sessionFile;
+  }
+
+  // 各阶段共享状态（原闭包变量收拢：proc / watchdog / sessionHeader / handshakeResult / resolveRun）
+  const state: SpawnRunState = {
+    record,
+    opts,
+    ctx,
+    proc: undefined,
+    watchdog: undefined,
+    sessionHeader: undefined,
+    handshakeResult: undefined,
+    resolveRun: undefined,
+  };
+
+  // a/b. 事件累积器（pendingTools 寄存器 + turnLimiter + handleSdkEvent/agentEvent 闭包）
+  const handleSdkEvent = createSpawnEventHandlers(state);
+
+  // c. schema 指令拼到 task 末尾（替代 in-process 的 turn_end steer 循环）
+  const instruction = opts.schema ? formatSchemaInstruction(opts.schema) : "";
+  const fullTask = task + instruction;
+
+  // d. session 目录（与 in-process 一致：list/恢复可发现同一目录）
+  // [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（隔离文件系统）
+  // worktree checkout 已由 worktree-manager 在 execute 前创建，此处只取路径。
+  const spawnCwd = opts.worktree?.path ?? ctx.cwd;
+
+  // f. fork source：父 session 文件路径（--fork 参数）
+  const forkSource = opts.fork ? ctx.mainSessionFile : undefined;
+
+  // g. appendSystemPrompt 落盘（env block + agent body + 调用方片段）
+  const tempPromptFile = await writeAppendSystemPromptFile(record, opts, ctx);
+
+  // h. 子进程环境变量（fork depth / 身份贯穿 / identity / worktree 标志 / schemaEnv）
+  const childEnv = buildChildEnv(record, opts, ctx);
+
+  // i. 组装 args + 解析 pi 可执行入口
+  const invocation = buildSpawnInvocation(opts, ctx, resume, tempPromptFile, sessionDir, forkSource);
 
-  // 解析出的 session header（stdout 首行，含 session id）
-  let sessionHeader: SpawnSessionHeader | undefined;
   // 累积 stderr（错误诊断用）
   let stderrBuffer = "";
 
@@ -764,18 +1339,22 @@ export async function runSpawn(
       stdio: ["pipe", "pipe", "pipe"],
       env: childEnv,
     });
-    proc = child;
+    state.proc = child;
     // [worktree-reaper-fix] 同步补全注册表 pid：spawn 返回后 child.pid 立即可得（Node.js
     // 同步属性），无需等任何 stdout 事件。原补全点挂在 header 分支（下方 stdout handler 内），
     // 而 RPC mode（buildSpawnArgs 固定 --mode rpc）不输出 header 行——pid 恒为 0，超
     // SPAWN_GRACE_MS 后被 reaper 当孤儿误删活 worktree（2026-08-11 cw 递归编排整树失活事故）。
     // header 分支调用保留：json mode 回切时仍能补全，updatePid 同 branch 覆盖写幂等，无副作用。
     if (opts.worktree && child.pid) {
-      ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
+      // [D5a] void：回调可能返回 Promise（锁内 RMW），契约保证不 reject，fire-and-forget。
+      void ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
     }
     // [C1] track 子进程供 dispose 兜底 kill（sync + background 均注册——sync 无 controller，
-    // abortRunningControllers 跳过它，靠本 Set 兜底）。close/error 后移除（已退出无需再 kill）。
-    spawnedChildren.add(child);
+    // abortRunningControllers 跳过它，靠本 Map 兜底）。close/error 后按句守卫移除（已退出无需再 kill）。
+    spawnedChildren.set(record.id, child);
+    // [V2 决策 3] spawn 后 child.pid 同步立即可得，记录到 record 内存（lifecycle-manager
+    // 孤儿扫描用，Step 5 接入持久化）。resume spawn 时此处同样覆盖更新（pid 可能已变）。
+    if (child.pid !== undefined) record.pid = child.pid;
 
     // [worktree-reaper-fix] 同步补全注册表 pid：spawn 返回后 child.pid 立即可得（Node.js
     // 同步属性），无需等任何 stdout 事件。原补全点挂在 header 分支（下方 stdout handler 内），
@@ -787,7 +1366,8 @@ export async function runSpawn(
     // 注册表写失败最坏后果是条目停留 pid=0，由 reaper 宽限回收兜底）。
     if (opts.worktree && child.pid) {
       try {
-        ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
+        // [D5a] void：回调可能返回 Promise（锁内 RMW），契约保证不 reject，fire-and-forget。
+        void ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
       } catch (err) {
         logger.warn("[worktree] worktree pid registration failed (defensive)", {
           branch: opts.worktree.branch,
@@ -804,6 +1384,31 @@ export async function runSpawn(
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
 
+    // [v4 A-1] 异步 stdin 'error' listener。writeStdinLine 的 try/catch 只覆盖同步 write 抛错；
+    // 子进程退出后内核回写 EPIPE 会以异步 stream 'error' event 到达，若无 listener 会让 Node
+    // 抛 unhandled 'error' 崩主进程（P1）。必须在首次 stdin 写入（下方 sendPromptCommand）前注册。
+    // handler 行为：①移出 spawnedChildren 标记 dead（与 child.on('error') 同模式）；
+    // ②recordEpipeFailure 合并同步/异步计数；③logger.warn 记录一次。
+    // [v4 A-1 裁决] handler 内**不 throw**——stream 'error' listener 内 throw 会经 Node 内部
+    // emit() 传播为 uncaughtException 崩主进程，违背 A-1 防崩核心目标。达阈值的 throw 留给
+    // 同步路径（deliverMessage catch 合并计数达 EPIPE_FAILURE_THRESHOLD 时同步 throw，不崩）。
+    // async handler 只移句柄 + 计数 + warn；进程已 dead（移句柄），下次 deliverMessage 检测
+    // dead 走冷路径，冷路径 write EPIPE 同步计数达阈值同步 throw——防死循环且不崩。
+    child.stdin.on("error", (err: Error) => {
+      // [M4] 按值守卫：resume spawn 已覆盖注册时不误删新 child（见 removeChildRegistration）
+      removeChildRegistration(record.id, child);
+      const count = recordEpipeFailure(record.id);
+      logger.warn(`[subagents] async stdin error for ${record.id}`, {
+        detail: err.message,
+        epipeCount: count,
+        threshold: EPIPE_FAILURE_THRESHOLD,
+        hint:
+          count >= EPIPE_FAILURE_THRESHOLD
+            ? "sync path will throw on next write EPIPE"
+            : undefined,
+      });
+    });
+
     // 喂 prompt 命令驱动子进程开始处理 task。pi runRpcMode 只消费 stdin RpcCommand，
     // 不读 positional arg；必须在 spawn 后主动写，否则子进程阻塞、totalTokens 恒 0。
     // 时机安全：pipe 内核缓冲不丢；pi 在 rebindSession 后才挂 stdin reader。
@@ -826,156 +1431,16 @@ export async function runSpawn(
     // 主进程退出时（session_shutdown reason=quit）dispose 会 abort running controller
     // → 本监听器 kill 子进程。无此 unref，watchdog timer 会拖住 event loop 阻止退出。
     const watchdogMs = computeWatchdogMs(opts.maxTurns);
-    let watchdog = setTimeout(() => child.kill("SIGTERM"), watchdogMs);
-    watchdog.unref();
+    state.watchdog = setTimeout(() => child.kill("SIGTERM"), watchdogMs);
+    state.watchdog.unref();
 
     // [recursive-orchestration] agent_end 有活跃后代时的等待超时（不 kill 分支的兑底）。
     // 层主 subagent 空闲等待后代完成（steer 唤醒）期间不产生 turn，原 watchdog 已清；
     // 此后代卡死（永不完成）时此 timer 保证进程最终回收。超时 kill → finalize 视为正常
     // 完成 → 通知父（父查 cw status 发现未 closed 会走 L2/L3 重派，见 planning-agent 模板）。
 
-    // stdout pump：逐行解析 → handleSdkEvent / enqueueUiRequest
-    const enqueueUiRequest = createUiRequestQueue(child, ctx);
-    // FR-4: get_state RPC response 监听器（id → resolver）。
-    // parseSpawnLine 返回 kind:"response" 时，按 command+id 匹配 resolver。
-    const get_stateListeners = new Map<string, (data: unknown) => void>();
-    let stdoutBuffer = "";
-
-    // [#18] 握手状态变量在 stdout handler 注册之前定义，消除"handler 闭包依赖同 tick
-    // 后续 const 初始化"的隐式顺序假设——handler 现在直接引用已初始化的变量，不靠
-    // "data 事件必然在下一 tick 才触发”的运行时不变式兜底。
-    const handshakeResultRef: { current?: GetStateResult } = {};
-    let settleHandshake: (() => void) | undefined;
-    const handshakeSettled: Promise<void> = new Promise((resolveSettled) => {
-      settleHandshake = resolveSettled;
-    });
-    /** 握手完成统一入口：记录结果 + 回填 sessionFile + 写 alive marker + settle。 */
-    const finishHandshake = (r: GetStateResult): void => {
-      handshakeResultRef.current = r;
-      // 仅当 header 未先行设置 record.sessionFile 时回填（RPC mode 路径）。
-      if (r.sessionFile && !record.sessionFile) {
-        record.sessionFile = r.sessionFile;
-        if (child.pid) {
-          try {
-            writeAliveMarker(r.sessionFile, {
-              pid: child.pid,
-              id: r.sessionId ?? record.id,
-              startedAt: Date.now(),
-            });
-          } catch {
-            // best-effort：alive marker 失败不影响执行
-          }
-        }
-      }
-      settleHandshake?.();
-      settleHandshake = undefined;
-    };
-
-    child.stdout.on("data", (data: string) => {
-      stdoutBuffer += data;
-      const lines = stdoutBuffer.split("\n");
-      stdoutBuffer = lines.pop() ?? ""; // 保留最后未完整行
-      for (const line of lines) {
-        const parsed = parseSpawnLine(line);
-        if (!parsed) continue;
-        if (parsed.kind === "header") {
-          sessionHeader = parsed.header;
-          // 回填 record.sessionFile（deriveSessionFilePath 推导路径）
-          record.sessionFile = deriveSessionFilePath(parsed.header, sessionDir);
-          // [持久化 C] alive marker：running 期间崩溃恢复用。子进程 pid + session id。
-          // 与 in-process 逻辑对齐（记 sessionFile + pid），改为子进程 pid。
-          if (record.sessionFile && child.pid) {
-            try {
-              writeAliveMarker(record.sessionFile, {
-                pid: child.pid,
-                id: parsed.header.id,
-                startedAt: Date.now(),
-              });
-            } catch {
-              // best-effort：alive marker 失败不影响执行
-            }
-          }
-          // [全局注册表] worktree 模式：补全注册表条目的 pid。
-          // create 时 pid 未知写 0 占位，此处拿到 child.pid 后回调 WorktreeManager.registerPid。
-          // 取代旧的 .session mapping sidecar——注册表是 reaper 的唯一数据源。
-          if (opts.worktree && child.pid) {
-            ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
-          }
-          // FR-4 加速路径：header 到达即 finishHandshake（header 已提供 sessionId，
-          // 足以推导 sessionFile + 兜底查找，无需等 get_state response）。
-          // [#25] buildSpawnArgs 固定 --mode rpc，RPC mode 不发 header——此分支当前不触发，
-          // 仅为未来 mode 回切（如 json mode 调试）保留：届时 header 先到可省去 get_state 握手等待。
-          if (settleHandshake) {
-            finishHandshake({
-              ...(record.sessionFile ? { sessionFile: record.sessionFile } : {}),
-              sessionId: parsed.header.id,
-            });
-          }
-        } else if (parsed.kind === "event") {
-          const evt = parsed.event;
-          // agent_end（willRetry=false）= agent 自然完成。rpc mode 子进程不自动退出
-          //（runRpcMode 末尾 return new Promise(() => {}) 长驻等命令），需主动 kill
-          // 触发 close → runSpawn resolve。willRetry=true 时 agent 会重试，不能 kill。
-          if (isAgentEndEvt(evt)) {
-            if (evt.willRetry) {
-              // agent 会重试，不能 kill。
-            } else {
-              // [recursive-orchestration] 条件 kill：读子进程 session 文件算活跃后代
-              // （pending:register − unregister 差集）。有活跃后代（background subagent /
-              // workflow）→ 保持进程 idle，等后代完成时 notifier triggerTurn steer 唤醒；
-              // 无 → 正常完成，kill 触发 close → runSpawn resolve。
-              const pending = readActivePendingFromSessionFile(record.sessionFile);
-              if (pending.count > 0 || pending.error) {
-                if (pending.error) {
-                  logger.warn(
-                    `[session-runner] agent_end: keep alive (sessionFile unreadable, conservative): ${pending.error}`,
-                  );
-                } else {
-                  logger.debug(
-                    `[session-runner] agent_end: keep alive, ${pending.count} active descendant(s) pending`,
-                  );
-                }
-                // 空闲等待期间不消耗 turn：清原 watchdog，换等待后代超时（每次 agent_end 重新计时）。
-                // [MF-4] 动态超时 = computeWatchdogMs(maxTurns)：真实后代在跑，慢任务（wave 开发
-                // 数小时）不能被固定 2h 误杀——2h 到点 kill 会连坐 SubagentService.dispose 的
-                // killAllSpawnedChildren 杀全部子进程，L2 重派丢在途工作。maxTurns 大则超时长。
-                clearTimeout(watchdog);
-                watchdog = setTimeout(() => child.kill("SIGTERM"), computeWatchdogMs(opts.maxTurns));
-                watchdog.unref();
-              } else if (pending.recentUnregister) {
-                // 差集 0 但最近有 unregister：后代刚完成，notify 唤醒可能在路上（竞态窗口），
-                // 保持进程——父被唤醒后的下一次 agent_end 会正常判定。
-                // [MF-3] 秒级宽限：此分支在每层「最终 turn」必命中（closeout 的 agent_end 距
-                // 最后一次 unregister <60s），挂长超时 = 空等 2h 才 kill + 冒牌完成通知级联。
-                // 15s 内无新 agent_end（未被唤醒）即 kill；被唤醒后下一次 agent_end 重新评估。
-                logger.debug(
-                  "[session-runner] agent_end: keep alive, recent descendant completion (wake-up in flight)",
-                );
-                clearTimeout(watchdog);
-                watchdog = setTimeout(() => child.kill("SIGTERM"), WAKEUP_GRACE_MS);
-                watchdog.unref();
-              } else {
-                child.kill("SIGTERM");
-              }
-            }
-          }
-          if (isSdkEvent(parsed.event)) handleSdkEvent(parsed.event);
-        } else if (parsed.kind === "response") {
-          // FR-4: RPC response handling — 匹配 get_state 响应
-          if (parsed.command === "get_state" && parsed.success && parsed.id) {
-            const resolver = get_stateListeners.get(parsed.id);
-            if (resolver) {
-              get_stateListeners.delete(parsed.id);
-              resolver(parsed.data);
-            }
-          }
-        } else if (parsed.kind === "extension_ui_request") {
-          // W3: 子进程发 UI 请求（ask_user）。入队 FIFO 串行处理，防止并发询问用户。
-          enqueueUiRequest(parsed.id, parsed.request);
-        }
-        // invalid 行忽略（stdout 可能有调试输出）
-      }
-    });
+    // stdout pump：逐行解析 → handleSdkEvent / enqueueUiRequest + get_state 握手状态机
+    const pump = attachStdoutPump(child, state, sessionDir, handleSdkEvent);
 
     // FR-4: get_state RPC 握手——spawn 后无条件启动。
     // RPC mode（pi --mode rpc）不向 stdout 输出 header，record.sessionFile 无法靠 header
@@ -986,14 +1451,11 @@ export async function runSpawn(
     // 时序：握手在 stdout pump（get_stateListeners 已就绪）之后启动。get_state 命令写入
     // stdin，pi rebindSession 后读取并返回 response，经 stdout pump 匹配 resolver 触发 resolve。
     // close handler await handshakeSettled，保证无论 task 多快结束，close 时 sessionFile 已回填。
-    // [#18] 握手状态变量（handshakeResultRef/settleHandshake/handshakeSettled/finishHandshake）
-    // 已在上方 stdout handler 注册前定义，此处直接发起握手。
-    void performGetStateHandshake(child, (id, resolver) => {
-      get_stateListeners.set(id, resolver);
-    }).then((r) => {
+    // [#18] 握手状态变量已在 attachStdoutPump 内部（stdout handler 注册前）定义，此处直接发起握手。
+    void performGetStateHandshake(child, pump.registerGetStateListener).then((r) => {
       // header 加速路径下 settleHandshake 已 undefined，跳过（避免覆盖 header 结果）。
       // 超时兜底（r 为空对象）也经此分支 settle，但 record.sessionFile 不回填。
-      if (settleHandshake) finishHandshake(r);
+      if (pump.isHandshakePending()) pump.finishHandshake(r);
     });
 
     child.stderr.on("data", (data: string) => {
@@ -1002,91 +1464,26 @@ export async function runSpawn(
     });
 
     // 等待子进程退出
-    const exitCode = await new Promise<number>((resolve) => {
-      child.on("close", async (code: number | null) => {
-        // [C1] 子进程已退出，从 orphan-tracking Set 移除（dispose 兜底无需再 kill 它）
-        spawnedChildren.delete(child);
-        // FR-4: 清理 get_state 监听器（子进程已退出，无更多 response）
-        get_stateListeners.clear();
-        // FR-4: 子进程已退出，get_state response 不会再来。若握手仍未 settle，立即放弃
-        //（record.sessionFile 未回填则走 findSessionFileByHeaderId 兜底）。避免子进程快速
-        // 失败/退出场景下 close handler 阻塞等待握手内部 6s 超时。
-        settleHandshake?.();
-        settleHandshake = undefined;
-        // await 立即返回（上方已 settle）：保证 header 加速路径或 get_state response 已
-        // 完成的回填结果对后续 identity 写入可见。
-        await handshakeSettled;
-        // 处理 stdout 末尾残留行
-        if (stdoutBuffer.trim()) {
-          const parsed = parseSpawnLine(stdoutBuffer);
-          if (parsed?.kind === "event" && isSdkEvent(parsed.event)) {
-            handleSdkEvent(parsed.event);
-          }
-        }
-        resolve(code ?? 0);
-      });
-      child.on("error", (err: Error) => {
-        // spawn 本身失败（command not found 等）
-        // [worktree-reaper-fix] 拼 spawnCwd 进错误消息：ENOENT 的 err.message 只含 command 名，
-        // 无 cwd 线索（worktree 被 reaper 误删后 cwd 指向虚空）会导致误诊——2026-08-11 事故
-        // AI 误判"node 被卸载"的直接原因。
-        // [S3] code 读取带运行时 guard：非 ErrnoException（普通 Error）时 code 为 undefined，
-        // 不加 cwd hint（行为与修复前一致）；仅 ENOENT 才拼 cwd。
-        spawnedChildren.delete(child);
-        const errno = err as NodeJS.ErrnoException;
-        const errCode = "code" in err ? errno.code : undefined;
-        const cwdHint = errCode === "ENOENT" ? ` (cwd: ${spawnCwd})` : "";
-        record.lastError = `${err.message}${cwdHint}`;
-        resolve(SIGNAL_EXIT_CODE_THRESHOLD); // 非零退出
-      });
-    });
+    const exitCode = await waitForChildExit(child, state, spawnCwd, pump);
 
     opts.signal?.removeEventListener("abort", onAbort);
-    clearTimeout(watchdog);
+    clearTimeout(state.watchdog);
 
-    // [持久化 A] sessionFile 兜底校验 + identity entry。
-    // session.jsonl 由子进程写入，父进程在子进程退出后（写入完成）補写身份条目。
-    // reconstructFromFile 依赖 IDENTITY_CUSTOM_TYPE custom entry 重建 record 身份，
-    // 缺失则 /subagents list 磁盘源为空（终态 record 全丢失）。[回归修复]
+    // [持久化 A] sessionFile 兜底校验。
+    // identity custom entry 已改由子进程 session_start hook 写（M4 / V2 决策 5），
+    // 父进程不再 fs 补写——fs 补写的 entry 缺 id/parentId 污染 pi _buildIndex。
+    // 此处仅保留 sessionFile 路径兜底（deriveSessionFilePath/握手路径可能不准）。
     if (record.sessionFile) {
       // 兜底：deriveSessionFilePath 推导或握手返回的路径可能不存在（pi 命名规则变化），
       // 用 sessionId 后缀匹配实际文件。匹配到则修正 record.sessionFile。
       // sessionId 来源：header（json mode）优先，其次握手结果（RPC mode）。
       if (!fs.existsSync(record.sessionFile)) {
-        const lookupId = sessionHeader?.id ?? handshakeResultRef.current?.sessionId;
+        const lookupId = state.sessionHeader?.id ?? state.handshakeResult?.sessionId;
         if (lookupId) {
           const actual = findSessionFileByHeaderId(sessionDir, lookupId);
           if (actual) record.sessionFile = actual;
         }
       }
-      // 补写 identity custom entry（子进程已退出，append 安全）。
-      if (fs.existsSync(record.sessionFile)) {
-        const identity: SubagentIdentityData = {
-          id: record.id,
-          agent: record.agent,
-          mode: record.mode,
-          task: record.task,
-          slug: record.slug,
-          startedAt: record.startedAt,
-          rootSessionId: record.rootSessionId,
-          parentRecordId: record.parentRecordId,
-          depth: record.depth,
-          forkDepth: opts.fork ? (opts.parentForkDepth ?? 0) + 1 : undefined,
-        };
-        try {
-          fs.appendFileSync(
-            record.sessionFile,
-            `${JSON.stringify({ type: "custom", customType: IDENTITY_CUSTOM_TYPE, data: identity })}\n`,
-            "utf-8",
-          );
-        } catch (err) {
-          // best-effort：identity 写入失败不影响执行结果，但会影响 /subagents list 重建。
-          // 记录到 logger（非阻断）—— 终态 record 会从 list 消失，这是可观测的退化信号。
-          logger.error(`[subagents] identity append failed for ${record.sessionFile}`, {
-            detail: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
     }
 
     // 判定成功/失败（三来源：exitCode + record.lastError + abort 原因）
@@ -1115,7 +1512,7 @@ export async function runSpawn(
       startTime,
       success,
       error,
-      sessionId: sessionHeader?.id ?? record.id,
+      sessionId: state.sessionHeader?.id ?? record.id,
       sessionFile: record.sessionFile,
     });
   } finally {