@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.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,9 +132,9 @@ beforeEach(() => {
   registry = new WorktreeRegistry(agentDir);
 });
 
-afterEach(() => {
+afterEach(async () => {
   vi.useRealTimers();
-  cleanup();
+  await cleanup();
 });
 
 // ── 用例 ──
@@ -142,7 +143,7 @@ describe("worktree pid 注册链路（真实 spawn 集成）", () => {
   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 +171,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 +184,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 +194,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 +219,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/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 镜像会把
+ *   xyz-system-prompt-extension.js 带进每个 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/execution-record.ts

@@ -20,6 +20,7 @@ import type {
   AgentResult,
   AgentUsage,
   AgentUsageTotal,
+  ClosedReason,
   DisplayItem,
   ExecutionMode,
   ExecutionRecord,
@@ -156,6 +157,10 @@ export function createRecord(
     parentRecordId?: string;
     /** subagent 递归深度。顶层=0。 */
     depth?: number;
+    /** 对话模式标志（true = 可持续对话，轮次完成进 idle）。默认 undefined/false = 一次性。 */
+    chatMode?: boolean;
+    /** 空闲超时毫秒数（仅 chatMode 有意义）。覆盖默认 5min。 */
+    idleTimeoutMs?: number;
     controller?: AbortController;
   },
 ): ExecutionRecord {
@@ -171,6 +176,8 @@ export function createRecord(
     rootSessionId: identity.rootSessionId,
     parentRecordId: identity.parentRecordId,
     depth: identity.depth ?? 0,
+    chatMode: identity.chatMode,
+    idleTimeoutMs: identity.idleTimeoutMs,
 
     // 状态（实时更新）
     status: "running",
@@ -180,6 +187,8 @@ export function createRecord(
     turnCount: 0,
     totalTokens: 0,
     lastError: undefined,
+    // 对话轮次计数（首轮 = 0，每完成一轮 finalizeRoundToIdle +1）。非 chatMode 不自增。
+    round: 0,
 
     // 完成（completeRecord 唯一写点）
     endedAt: undefined,
@@ -233,6 +242,30 @@ function findRunningToolCall(
   return undefined;
 }
 
+/**
+ * [perf] running toolCall 倒序索引：tool_start push 位置入索引，tool_end 弹尾定位
+ *（尾部 = 最后 push 的同名项，与 findRunningToolCall 倒序全扫的语义等价），把每次
+ * tool_end 的 O(所有 turns × toolCalls) 扫描降为 O(1)。WeakMap 按 record 实例隔离
+ *（createRecord 新实例从空索引开始，不影响旧实例）。
+ * 索引 miss（重建 record 的历史 running toolCall / 外部注入工具无 tool_start）
+ * 回退 findRunningToolCall 全扫兜底——正确性不依赖索引完整性。
+ */
+const runningToolIndex = new WeakMap<ExecutionRecord, Map<string, Array<{ turn: Turn; idx: number }>>>();
+
+function indexToolStart(record: ExecutionRecord, turn: Turn, toolName: string): void {
+  let byName = runningToolIndex.get(record);
+  if (byName === undefined) {
+    byName = new Map();
+    runningToolIndex.set(record, byName);
+  }
+  const arr = byName.get(toolName);
+  if (arr === undefined) {
+    byName.set(toolName, [{ turn, idx: turn.toolCalls.length - 1 }]);
+  } else {
+    arr.push({ turn, idx: turn.toolCalls.length - 1 });
+  }
+}
+
 /**
  * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
  *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
@@ -271,13 +304,30 @@ export function updateFromEvent(record: ExecutionRecord, event: AgentEvent): voi
         _status: "running",
         startedTs: Date.now(),
       };
-      currentTurn(record).toolCalls.push(tc);
+      const turn = currentTurn(record);
+      turn.toolCalls.push(tc);
+      indexToolStart(record, turn, event.toolName);
       return;
     }
 
-    // ── tool_end：跨 turn 找 running 同名 toolCall，补全 result/isError/_status ──
+    // ── tool_end：索引弹尾 O(1) 定位 running 同名 toolCall，miss 回退全扫兜底 ──
     case "tool_end": {
-      const matched = findRunningToolCall(record, event.toolName);
+      let matched: readonly [Turn, number] | undefined;
+      const byName = runningToolIndex.get(record);
+      const arr = byName?.get(event.toolName);
+      if (arr !== undefined && arr.length > 0) {
+        const item = arr[arr.length - 1];
+        arr.pop();
+        const tc = item.turn.toolCalls[item.idx];
+        if (tc !== undefined && tc._status === "running") {
+          matched = [item.turn, item.idx] as const;
+        }
+      }
+      if (matched === undefined) {
+        // 兜底：重建 record 的历史 running toolCall（索引未覆盖）、索引项被外部路径
+        // 置非 running 等场景——保持与旧实现一致的跨 turn 倒序全扫。
+        matched = findRunningToolCall(record, event.toolName);
+      }
       if (matched !== undefined) {
         const [turn, i] = matched;
         const tc = turn.toolCalls[i]!;
@@ -488,6 +538,51 @@ export function getFullText(record: ExecutionRecord): string {
     .join("\n\n");
 }
 
+/**
+ * [增量通知] 从 fromTurnIndex 起聚合 turn 文本（getFullText 的增量视图）。
+ *
+ * 语义：record.turns.slice(Math.max(0, fromTurnIndex)) 的 text 数组
+ * filter(text => text.length > 0)（判据与 getFullText 逐字对齐——空白串 " " 按非空
+ * 处理，不发散）后 join("\n\n")。
+ *
+ * 不变式（单测锁死）：
+ *   - fromTurnIndex = 0 与 getFullText(record) 逐字节等价（one-shot/首轮回退零成本）
+ *   - fromTurnIndex >= turns.length 返回 ""（不抛错、不回绕）
+ *   - fromTurnIndex < 0 规范化为 0（防御，Math.max 不产生 slice 负偏移语义）
+ *
+ * 纯函数只读；getFullText 本体与既有调用方（collectResult 等）零改动。
+ * 唯一调用点 onRoundSettled 的增量派生（record.roundBaseTurnIndex ?? 0）。
+ */
+export function getFullTextFrom(record: ExecutionRecord, fromTurnIndex: number): string {
+  return record.turns
+    .slice(Math.max(0, fromTurnIndex))
+    .map((t) => t.text)
+    .filter((text) => text.length > 0)
+    .join("\n\n");
+}
+
+/**
+ * [增量通知] 轮次边界推进公式（D1）：返回下一轮增量的 turns[] 起始下标。
+ *
+ * record.turns.length - (末 turn 存在且 !closed 且 text.length === 0 ? 1 : 0)
+ *
+ * - 末 turn 已闭合（pi 现序常态：带 usage 的 message_end 恒先于 turn_end，settle 时
+ *   全闭合）→ 返回 length，下一轮从新 turn 起。
+ * - 末 turn 是滞后 message_end 开出的空 turn（防御分支，pi 现序不可达）→ 不计入边界
+ *   （-1），留在下一轮增量内：新轮首个 text_delta 经 currentTurn 复用该空 turn，复用
+ *   累积被 slice(from) 覆盖；若直用 turns.length 会把这段文本挤出 slice 范围静默丢失（D1）。
+ * - 末 turn 未闭合且 text 非空（防御形态，pi 现序不可达）→ 计入本轮返回 length（该形态
+ *   即 onRoundSettled 推进前观测哨 logger.warn 的触发条件）。
+ *
+ * 纯函数只读不写 record；唯一调用点 onRoundSettled 第 5 步（notify 之后推进）。
+ */
+export function nextRoundBaseTurnIndex(record: ExecutionRecord): number {
+  const last = record.turns[record.turns.length - 1];
+  const trailingOpenEmpty =
+    last !== undefined && !last.closed && last.text.length === 0 ? 1 : 0;
+  return record.turns.length - trailingOpenEmpty;
+}
+
 /**
  * 聚合所有 turn 的 toolCalls（扁平化），并 strip InternalToolCall 的内部字段。
  * 供 collectResult / schema enforcement 读，替代旧闭包 toolCalls 旁路。
@@ -499,6 +594,17 @@ export function getAllToolCalls(record: ExecutionRecord): ToolCall[] {
   return record.turns.flatMap((t) => t.toolCalls.map(stripInternal));
 }
 
+/**
+ * 聚合所有 turn 的 toolCalls 总数（免克隆计数）。
+ *
+ * getAllToolCalls 会 flatMap + strip 克隆出完整数组——只需计数的调用方（渲染签名
+ * 每 200ms tick 调用一次）用它是纯浪费；本函数 reduce 累加各 turn 的 length，零分配。
+ * 与 getAllToolCalls(...).length 恒等（同一 turns 源）。
+ */
+export function countAllToolCalls(record: ExecutionRecord): number {
+  return record.turns.reduce((sum, t) => sum + t.toolCalls.length, 0);
+}
+
 /** 把 InternalToolCall 映射回纯净的 ToolCall（丢弃 _status / startedTs）。 */
 function stripInternal(tc: InternalToolCall): ToolCall {
   return {
@@ -540,21 +646,26 @@ export function getTotalUsage(record: ExecutionRecord): AgentUsageTotal | undefi
 /**
  * status 状态机的 CAS 互斥锁。仅当 `record.status === "running"` 时改为 target
  * 并返回 true，否则返回 false。**status 状态机本身就是互斥锁**——终态
- * （done/failed/cancelled/crashed）不可逆，check-then-set 在 JS 单线程事件循环里天然原子。
+ * （closed/cancelled）不可逆，check-then-set 在 JS 单线程事件循环里天然原子。
  *
  * 用途：executor 的收尾竞争。cancelBackground 与 background detached 完成回调
  * 都调 tryTransition 抢锁：抢到负责完整收尾，没抢到闭嘴不做事。
  *
- * target 仅限正常执行流的三终态。crashed 不作 target——它由重建路径推断
- * （alive marker 存在但 session 文件无终态），不走 CAS；重建路径用 markReconstructedStatus
- * 直接赋值。收窄 target 类型可在编译期拒绍误用 tryTransition(record, "crashed")。
+ * target 仅限正常执行流的两终态（closed + cancelled）。
+ * closed 携带 closedReason（L2 原因子枚举），由重建路径或正常执行流写入。
+ * 重建路径也可用 markReconstructedStatus 直接赋值（跳过 CAS）。
+ *
+ * @param closedReason closed 终态的 L2 关闭原因。仅 target="closed" 时有意义；
+ *   target="cancelled" 时忽略。缺省 "gc"（通用完成/失败）。
  */
 export function tryTransition(
   record: ExecutionRecord,
-  target: "done" | "failed" | "cancelled",
+  target: "closed",
+  closedReason?: ClosedReason,
 ): boolean {
   if (record.status !== "running") return false;
   record.status = target;
+  record.closedReason = closedReason ?? "gc";
   return true;
 }
 
@@ -577,13 +688,18 @@ export function markReconstructedStatus(
  * 不修改 turns/totalTokens——已由 updateFromEvent 累积，completeRecord 只读不重置。
  *
  * ⚠ 前置条件：调用方必须先通过 tryTransition 抢到锁（status 已被 CAS 设为 target）。
+ *
+ * @param closedReason closed 终态的 L2 关闭原因。仅 status="closed" 时写入；
+ *   "cancelled" 时忽略。
  */
 export function completeRecord(
   record: ExecutionRecord,
   result: AgentResult,
-  status: "done" | "failed" | "cancelled",
+  status: "closed",
+  closedReason?: ClosedReason,
 ): void {
   record.status = status;
+  record.closedReason = closedReason ?? "gc";
   record.endedAt = Date.now();
   record.agentResult = result;
   record.result = result.text;
@@ -663,6 +779,7 @@ export function snapshot(record: ExecutionRecord): RecordSnapshot {
     task: record.task,
     slug: record.slug,
     status: record.status,
+    chatMode: record.chatMode,
     turns: record.turnCount,
     totalTokens: record.totalTokens,
     startedAt: record.startedAt,

package/src/execution/finalize-record.ts

@@ -27,7 +27,7 @@ import type { ModelConfigService } from "./model-config-service.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
 import type { RecordStore } from "./record-store.ts";
 import { writeCancelledTombstone } from "./tombstone-store.ts";
-import type { AgentResult, ExecutionRecord } from "./types.ts";
+import type { AgentResult, ClosedReason, ExecutionRecord } from "./types.ts";
 import type { WorktreeManager } from "./worktree-manager.ts";
 
 const logger = getLogger("subagents");
@@ -40,10 +40,10 @@ export interface FinalizeDeps {
   modelService: ModelConfigService;
   /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
   pi: { appendEntry?: (type: string, data: unknown) => void } | null;
-  /** 清节流状态（防 trailing timer 在 record 归档后误发陈旧 onUpdate）。 */
-  clearThrottle(id: string): void;
   /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
   emitUnregister(id: string, status: string): void;
+  // [review 修复] 已删除 redeliverPending 回调（MF-1 消费确认制补投）：pendingMessages
+  // 三段消费链随 deliverToRunning 一并移除（无生产调用方，死机制）。
 }
 
 /**
@@ -57,11 +57,9 @@ export async function doFinalizeRecord(
   deps: FinalizeDeps,
   record: ExecutionRecord,
   result: AgentResult,
-  status: "done" | "failed" | "cancelled",
+  status: "closed",
+  closedReason?: ClosedReason,
 ): Promise<void> {
-  // 终态清节流状态：防 trailing timer 在 record 归档后误发陈旧 onUpdate
-  deps.clearThrottle(record.id);
-
   // ── Step 0: collectPatch（best-effort）──
   // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
   //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
@@ -73,7 +71,7 @@ export async function doFinalizeRecord(
       );
       fs.mkdirSync(sessionsDir, { recursive: true });
       const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
-      const patch = deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
       if (patch.written) record.patchFile = patchFile;
     } catch (pe: unknown) {
       bestEffort(pe, "collectPatch (finalizeRecord Step0)");
@@ -82,7 +80,7 @@ export async function doFinalizeRecord(
 
   // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
   try {
-    completeRecord(record, result, status);
+    completeRecord(record, result, status, closedReason);
   } catch (err) {
     bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
   }
@@ -100,8 +98,8 @@ export async function doFinalizeRecord(
   //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
   if (record.sessionFile) {
     try {
-      // MF-1 fix: cancelled 状态写 tombstone 而非 finalized，防重建丢失 cancelled
-      if (status === "cancelled") {
+      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
+      if (closedReason === "cancelled") {
         writeCancelledTombstone(record.sessionFile, {
           id: record.id,
           status: "cancelled",
@@ -118,7 +116,7 @@ export async function doFinalizeRecord(
   }
   if (record.worktreeHandle) {
     try {
-      deps.worktreeManager.cleanup(record.worktreeHandle);
+      await deps.worktreeManager.cleanup(record.worktreeHandle);
     } catch (err) {
       bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
     }
@@ -146,7 +144,8 @@ export async function doFinalizeRecord(
       rootSessionId: record.rootSessionId ?? "",
       parentRecordId: record.parentRecordId,
       agentName: record.agent,
-      status: status === "done" ? "completed" : status,
+      // v4 B-1: manifest status 统一为 closed（cancelled 折入 closed，区分靠 tombstone sidecar）
+      status: "closed",
       createdAt: record.startedAt,
       completedAt: record.endedAt ?? Date.now(),
       sessionFile: record.sessionFile,
@@ -163,3 +162,81 @@ export async function doFinalizeRecord(
     });
   }
 }
+
+/**
+ * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
+ *
+ * 与 doFinalizeRecord 的关键区别（M2-A idle 语义）：
+ *   - 不调 completeRecord（record 不冻结，保留 turns[] 等运行时状态供续聊累积）
+ *   - 不调 store.archive（record 留内存，getMutable 可查、list 可见）
+ *   - 不 cleanup worktree（保留对话模式工作目录）
+ *   - 不写 manifest（idle 非终态，manifest 是终态诊断辅助）
+ *   - 删 .alive marker（进程已 SIGTERM 回收，不再是活进程）
+ *   - emitUnregister（进程已死，从 pending 活跃后代差集移除；record 留内存不 archive）
+ *
+ * MF-2：设 record.result = result.text（否则 notifier idle 回复正文恒为 "(empty)"，
+ *   G1/G2 多轮回复送达不成立）。失败轮次（result.success=false，MF-6 回退 idle 路径）
+ *   的 result.text 可能为空，用 result.error 兜底让 notify 可读。
+ *
+ * 状态：record.status = "idle"（覆盖 tryTransition 设的 done/failed），record.round += 1。
+ * 各步骤 best-effort 互不阻断（参照 doFinalizeRecord 的 bestEffort 用法）。
+ *
+ * @param deps 与 doFinalizeRecord 同源（从 SubagentService 注入）
+ * @param result 本轮 AgentResult（MF-2：result.text 写入 record.result 供 notifier idle 回复）
+ */
+export async function doFinalizeRoundToIdle(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+): Promise<void> {
+  // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
+  // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
+  // [增量 G2] 第三分支 chatMode 条件占位：本写点被 one-shot 成功路径共用（subagent-service
+  // runAndFinalize 的 `!record.chatMode && !aborted && result.success` 分支 → finalizeRoundToIdle），
+  // 非 chatMode 必须保持 `|| record.result` 现状——one-shot 空文本成功完成（collectResult
+  // getFullText 返回 ""、success=true、真实可达）时 result 前值 undefined → notifier
+  // buildLlmContent 的 `record.result ?? "(empty)"` 兜底确定性产出 "(empty)"，通知逐字节
+  // 不变（G4）；无条件替换会把文案漂移为占位。chatMode 空增量轮 → 固定占位
+  // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
+  // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
+  let nextResult: string | undefined;
+  if (result.text) {
+    nextResult = result.text;
+  } else if (result.error) {
+    nextResult = `round did not complete: ${result.error}`;
+  } else if (record.chatMode) {
+    nextResult = "(no output this round)";
+  } else {
+    nextResult = record.result;
+  }
+  record.result = nextResult;
+
+  // 删 .alive marker（进程已 SIGTERM 回收）。
+  // sessionFile 窗口期可能 undefined（极少——对话模式轮次完成意味着 session 已跑过），
+  // 缺失时跳过但仍设内存 idle（重启后磁盘重建会落到 crashed，边界可接受）。
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (doFinalizeRoundToIdle)");
+    }
+  }
+
+  // pending-notifications：进程已死，从活跃后代差集移除（record 留内存不 archive，
+  // v4 B-1：record 现为 running-resumable，但 pending 注册的是进程活跃性，进程死了需注销）。
+  deps.emitUnregister(record.id, "running");
+
+  // 状态机（v4 B-1）：record 保持 running（旧 idle 折入 running，覆盖 tryTransition 设的 closed，
+  // 可冷路径 resume），轮次计数 +1。idleSince 时间戳独立保留供 GC 判据。
+  // [S10] closedReason 同步清除：调用方（runAndFinalize catch / MF-6 分支）先 tryTransition
+  // 设了 closed+closedReason 再回退 running——不清则 "gc"/"cancelled" 残留在 running record 上，
+  // 泄漏进 list 投影与后续 notify 载荷（toNotifyRecord 透传 record.closedReason），让一个
+  // 活跃 record 看起来像已被某原因关闭过。
+  record.status = "running";
+  record.closedReason = undefined;
+  record.round = (record.round ?? 0) + 1;
+  record.idleSince = Date.now();
+
+  // [review 修复] 已删除残留 pendingMessages 的 redeliverPending 补投段（MF-1 消费
+  // 确认安全网）：三段消费链随 deliverToRunning 一并移除，本段不可达。
+}

package/src/execution/host-mode.ts

@@ -7,7 +7,7 @@
 // handler 工厂分流、stdio 选择等消费点统一调用。
 //
 // 判定依据见 AGENTS.md「运行时环境区分」章节 +
-// docs/pi-tui-development-guide.md 第四部分第 8 节。
+// docs/extensions/pi-tui-development-guide.md 第四部分第 8 节。
 // ExtensionMode 来自 Pi 源码 packages/coding-agent/src/core/extensions/types.ts:299
 // （dist 中 core/extensions/types.d.ts:207）。
 //