@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/finalize-record.ts

@@ -26,6 +26,7 @@ import type { ManifestStore } from "./manifest-store.ts";
 import type { ModelConfigService } from "./model-config-service.ts";
 import { getSubagentSessionDir } from "./path-encoding.ts";
 import type { RecordStore } from "./record-store.ts";
+import { readIdentityHeader, readIdentityTail } from "./session-reconstructor.ts";
 import { writeCancelledTombstone } from "./tombstone-store.ts";
 import type { AgentResult, ClosedReason, ExecutionRecord } from "./types.ts";
 import type { WorktreeManager } from "./worktree-manager.ts";
@@ -42,105 +43,147 @@ export interface FinalizeDeps {
   pi: { appendEntry?: (type: string, data: unknown) => void } | null;
   /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
   emitUnregister(id: string, status: string): void;
+  /**
+   * [T1/PS-9] subagent sessionDir（getSubagentSessionDir(agentDir, rootCwd)，调用方注入）。
+   *
+   * record.sessionFile 缺失（RC-1 握手失败 + LC-4 反查也未命中的残余形态）时用于磁盘
+   * 反查：按 identity（record.id）扫目录找真实 session 文件，作为 tombstone/finalized
+   * sidecar 与 removeAliveMarker 的依据——消除「sessionFile 缺失 → 终态原因丢失 +
+   * alive marker 残留」。undefined = 调用方无法提供（反查跳过，行为退回修复前）。
+   */
+  sessionDir?: string;
   // [review 修复] 已删除 redeliverPending 回调（MF-1 消费确认制补投）：pendingMessages
   // 三段消费链随 deliverToRunning 一并移除（无生产调用方，死机制）。
 }
 
 /**
- * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ * [T1/PS-9] 按 record 身份在 sessionDir 反查 session 文件（record.sessionFile 缺失时用）。
  *
- * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
- * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
- * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ * 匹配依据：session JSONL 的 identity custom entry 携带 record id（子进程 session_start
+ * hook 写入），探测函数与 RecordStore 列表扫描同源（readIdentityHeader 头部 64KB →
+ * readIdentityTail 尾部 64KB；续聊场景 identity 靠尾）。readIdentityAnywhere 需全文读，
+ * 本反查是收尾路径的 best-effort，不做。
+ *
+ * @returns 匹配到的 session 文件绝对路径；目录不可读 / 无匹配返回 undefined（不抛）。
  */
-export async function doFinalizeRecord(
-  deps: FinalizeDeps,
-  record: ExecutionRecord,
-  result: AgentResult,
-  status: "closed",
-  closedReason?: ClosedReason,
-): Promise<void> {
-  // ── Step 0: collectPatch（best-effort）──
-  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
-  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
-  if (record.worktreeHandle) {
-    try {
-      const sessionsDir = getSubagentSessionDir(
-        deps.modelService.getAgentDir(),
-        record.worktreeHandle.mainCwd,
-      );
-      fs.mkdirSync(sessionsDir, { recursive: true });
-      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
-      const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
-      if (patch.written) record.patchFile = patchFile;
-    } catch (pe: unknown) {
-      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
-    }
+function findSessionFileByRecordIdentity(
+  sessionDir: string,
+  recordId: string,
+): string | undefined {
+  let names: string[];
+  try {
+    names = fs.readdirSync(sessionDir);
+  } catch {
+    return undefined; // 目录缺失/不可读 → 反查跳过，行为退回无反查
+  }
+  for (const name of names) {
+    if (!name.endsWith(".jsonl")) continue;
+    const full = path.join(sessionDir, name);
+    const recon = readIdentityHeader(full) ?? readIdentityTail(full);
+    if (recon?.id === recordId) return full;
   }
+  return undefined;
+}
 
-  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
-  try {
-    completeRecord(record, result, status, closedReason);
-  } catch (err) {
-    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+/**
+ * [T1/PS-9] Step 序言：sessionFile 缺失时按 record 身份在 sessionDir 反查回填。
+ *
+ * 放在一切步骤前，让 archive 投影 / Step 3 marker / Step 4 manifest 统一受益。
+ * RC-1（握手失败）+ LC-4（收尾反查未命中）的残余形态下，磁盘上 session 文件仍可能
+ * 真实存在（identity 携带 record.id）——反查命中则 tombstone/finalized sidecar 与
+ * removeAliveMarker 有了依据，终态原因不再丢失、alive marker 不再残留；未命中则
+ * 保持旧行为（best-effort 跳过）。
+ */
+function resolveMissingSessionFile(deps: FinalizeDeps, record: ExecutionRecord): void {
+  if (record.sessionFile || !deps.sessionDir) return;
+  const resolved = findSessionFileByRecordIdentity(deps.sessionDir, record.id);
+  if (resolved) {
+    record.sessionFile = resolved;
+    logger.warn(
+      `[subagent] finalizeRecord: sessionFile was missing, resolved via sessionDir identity lookup: ${resolved}`,
+    );
   }
+}
 
-  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+/**
+ * Step 0: collectPatch（best-effort，仅 worktree 绑定时执行）。
+ * [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
+ * 路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
+ */
+async function collectPatchIfWorktree(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
+  if (!record.worktreeHandle) return;
   try {
-    deps.store.archive(record);
-  } catch (err) {
-    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+    const sessionsDir = getSubagentSessionDir(
+      deps.modelService.getAgentDir(),
+      record.worktreeHandle.mainCwd,
+    );
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
+    const patch = await deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+    if (patch.written) record.patchFile = patchFile;
+  } catch (pe: unknown) {
+    bestEffort(pe, "collectPatch (finalizeRecord Step0)");
   }
+}
 
-  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
-  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
-  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
-  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
-  if (record.sessionFile) {
-    try {
-      // MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，防重建丢失 cancelled
-      if (closedReason === "cancelled") {
-        writeCancelledTombstone(record.sessionFile, {
-          id: record.id,
-          status: "cancelled",
-          agent: record.agent,
-          startedAt: record.startedAt,
-          endedAt: record.endedAt ?? Date.now(),
-        });
-      } else {
-        // [v8.5 A2] 真实 reason 写入 sidecar 内容（旧格式是空文件）：磁盘重建时用它
-        // 还原 closedReason，不再一律硬编码 gc。cancelled 之外的全部原因（gc /
-        // user-close / parent-*）都经此路径持久化。
-        writeFinalized(record.sessionFile, closedReason);
-      }
-    } catch (err) {
-      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
-    }
-  }
-  if (record.worktreeHandle) {
-    try {
-      await deps.worktreeManager.cleanup(record.worktreeHandle);
-    } catch (err) {
-      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
+/**
+ * Step 3a: finalized/tombstone sidecar（best-effort 幂等，仅 sessionFile 存在时执行）。
+ * MF-1 fix / v4 B-1: cancelled（closedReason='cancelled'）写 tombstone 而非 finalized，
+ * 防重建丢失 cancelled；其余 reason 写 finalized sidecar（真实 reason 进 sidecar 内容，
+ * 磁盘重建用它还原 closedReason，不再一律硬编码 gc）。
+ */
+function writeFinalizedOrTombstone(record: ExecutionRecord, closedReason: ClosedReason | undefined): void {
+  if (!record.sessionFile) return;
+  try {
+    if (closedReason === "cancelled") {
+      writeCancelledTombstone(record.sessionFile, {
+        id: record.id,
+        status: "cancelled",
+        agent: record.agent,
+        startedAt: record.startedAt,
+        endedAt: record.endedAt ?? Date.now(),
+      });
+    } else {
+      writeFinalized(record.sessionFile, closedReason);
     }
+  } catch (err) {
+    bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
   }
-  if (record.sessionFile) {
-    try {
-      removeAliveMarker(record.sessionFile);
-    } catch (err) {
-      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
-    }
+}
+
+/**
+ * Step 3b: worktree cleanup（best-effort 幂等，仅 worktree 绑定时执行）。
+ * [Critical] 绝不能因 manifest 写失败而跳过（否则 worktree 泄漏）。
+ */
+async function cleanupWorktreeIfBound(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
+  if (!record.worktreeHandle) return;
+  try {
+    await deps.worktreeManager.cleanup(record.worktreeHandle);
+  } catch (err) {
+    bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
   }
+}
 
-  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
-  deps.emitUnregister(record.id, status);
+/** Step 3c: 删 .alive marker（best-effort 幂等，仅 sessionFile 存在时执行）。 */
+function removeAliveMarkerIfPresent(record: ExecutionRecord): void {
+  if (!record.sessionFile) return;
+  try {
+    removeAliveMarker(record.sessionFile);
+  } catch (err) {
+    bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
+  }
+}
 
-  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
-  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
-  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
-  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
-  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
-  //   manifestToSubagent 投影时用真实值而非硬编码空串。
+/**
+ * Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）。
+ *
+ * [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
+ * 仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过 Step 3 cleanup
+ * 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
+ * task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
+ * manifestToSubagent 投影时用真实值而非硬编码空串。
+ */
+async function writeManifestBestEffort(deps: FinalizeDeps, record: ExecutionRecord): Promise<void> {
   try {
     await deps.manifestStore.writeManifest({
       id: record.id,
@@ -166,6 +209,55 @@ export async function doFinalizeRecord(
   }
 }
 
+/**
+ * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ *
+ * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
+ * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
+ * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ */
+export async function doFinalizeRecord(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+  status: "closed",
+  closedReason?: ClosedReason,
+): Promise<void> {
+  // [T1/PS-9] sessionFile 缺失时 sessionDir 反查（序言，先于一切步骤）。
+  resolveMissingSessionFile(deps, record);
+
+  // ── Step 0: collectPatch（best-effort）──
+  await collectPatchIfWorktree(deps, record);
+
+  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+  try {
+    completeRecord(record, result, status, closedReason);
+  } catch (err) {
+    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+  try {
+    deps.store.archive(record);
+  } catch (err) {
+    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 3: finalized + cleanup + aliveMarker（全部先执行，幂等）──
+  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
+  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
+  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
+  writeFinalizedOrTombstone(record, closedReason);
+  await cleanupWorktreeIfBound(deps, record);
+  removeAliveMarkerIfPresent(record);
+
+  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  deps.emitUnregister(record.id, status);
+
+  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
+  await writeManifestBestEffort(deps, record);
+}
+
 /**
  * 对话模式轮次完成收尾：record 进 idle 态（非终态化，等待续聊）。
  *
@@ -179,7 +271,9 @@ export async function doFinalizeRecord(
  *
  * MF-2：设 record.result = result.text（否则 notifier idle 回复正文恒为 "(empty)"，
  *   G1/G2 多轮回复送达不成立）。失败轮次（result.success=false，MF-6 回退 idle 路径）
- *   的 result.text 可能为空，用 result.error 兜底让 notify 可读。
+ *   error 优先于 text：collectResult 恒带 getFullText 全量正文，text 优先会把失败的
+ *   恢复指引覆盖成轮内旧正文（Gate B S-B-1 实测：settled watchdog kill 后宿主收到
+ *   成功形态通知，无从得知挂死与恢复方式）。
  *
  * 状态：record.status = "idle"（覆盖 tryTransition 设的 done/failed），record.round += 1。
  * 各步骤 best-effort 互不阻断（参照 doFinalizeRecord 的 bestEffort 用法）。
@@ -193,7 +287,9 @@ export async function doFinalizeRoundToIdle(
   result: AgentResult,
 ): Promise<void> {
   // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
-  // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
+  // [T2-③ / LC-1] 失败轮 error 优先：collectResult 恒带 getFullText 全量正文（即使
+  // success=false），text 优先会把 watchdog 等失败的恢复指引覆盖成轮内正文（半成品 /
+  // 回补值），宿主无从得知失败与恢复方式（S-B-1 首轮 settled watchdog 实测）。
   // [R2-1] 轮终写点恒写非空：one-shot 空文本成功完成（collectResult getFullText 返回 ""、
   // success=true、真实可达，本写点被 subagent-service runAndFinalize 的成功分支共用）首轮
   // result 前值 undefined，兜底补 "(empty)" 占位——措辞与 notifier buildLlmContent 的
@@ -205,10 +301,10 @@ export async function doFinalizeRoundToIdle(
   // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
   // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
   let nextResult: string | undefined;
-  if (result.text) {
-    nextResult = result.text;
-  } else if (result.error) {
+  if (result.error && (!result.success || !result.text)) {
     nextResult = `round did not complete: ${result.error}`;
+  } else if (result.text) {
+    nextResult = result.text;
   } else if (record.chatMode) {
     nextResult = "(no output this round)";
   } else {

package/src/execution/idle-gc.ts

@@ -4,9 +4,12 @@
  * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
  */
 import { getLogger } from "../core/logger.ts";
+import { getEngineDataDir } from "./engine/common/data-dir.ts";
+import { releasePoolRef } from "./engine/common/pool-manager.ts";
 import { bestEffort } from "./best-effort.ts";
 import { isResumable } from "./lifecycle-predicates.ts";
 import type { RecordStore } from "./record-store.ts";
+import type { ExecutionRecord } from "./types.ts";
 
 const logger = getLogger("subagents");
 
@@ -24,6 +27,15 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
  * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
  * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ *
+ * [D8 池引用计数接线] 归档时同步释放该 record 的引擎池引用（releasePoolRef：
+ * journal 跟随 record 删除 + refs 移除 + 归零删池内原生状态）。锚点选在 30 天 TTL
+ * 而非 dispose/archive 类时机，依据：idle record 30 天后引擎侧不会再有活动（archive
+ * 后 message 续聊走 fork-from/新 start，不触原引擎），且与 pi 域 session 文件 30 天
+ * TTL（session-file-gc 同期删①级读源）形成两引擎对称衰减；disposeAllRecords/close
+ * 类时机 record 数据仍保留（可 resurrect / GUI 历史重建可见），journal（②级数据源）
+ * 不能删——那是 record 主数据死亡（主 session 文件被 pi 侧删除，core 无触发点）才有
+ * 的处置，由 cleanupExpiredPoolRefs 的 TTL 兜底覆盖。
  */
 export function startIdleGc(store: RecordStore): () => void {
   const timer = setInterval(() => {
@@ -38,6 +50,7 @@ export function startIdleGc(store: RecordStore): () => void {
           } catch (err) {
             bestEffort(err, `GC archive record ${record.id}`);
           }
+          releaseEnginePoolRef(record);
         }
       }
     }
@@ -45,3 +58,18 @@ export function startIdleGc(store: RecordStore): () => void {
   timer.unref?.();
   return () => clearInterval(timer);
 }
+
+/**
+ * 释放 record 的引擎池引用（best-effort）。无 engineHandle（存量 record / 非引擎
+ * 路径）时 no-op；engine 缺省投影 'pi'（与读侧存量 entry 零迁移口径一致）。
+ */
+function releaseEnginePoolRef(record: ExecutionRecord): void {
+  const poolKey = record.engineHandle?.poolKey;
+  if (poolKey === undefined) return;
+  const engineId = record.engine ?? "pi";
+  try {
+    releasePoolRef(getEngineDataDir(), engineId, poolKey, record.id);
+  } catch (err) {
+    bestEffort(err, `GC release pool ref for record ${record.id}`);
+  }
+}

package/src/execution/lifecycle-manager.ts

@@ -24,8 +24,13 @@
 // 设计参考：session-runner 的 MF-3/MF-4 setTimeout→SIGTERM 骨架（复用 timer 形态，
 // 触发条件重构）；spawnedChildren Map 的模块级单例模式。
 
+import { getLogger } from "../core/logger.ts";
 import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
 
+// core/logger 无本地状态依赖（不 import execution/orchestration 层），与本模块
+// 「可独立编译 + 单测」约束兼容；不 import session-runner / subagent-service（循环依赖）。
+const logger = getLogger("subagents");
+
 // ============================================================
 // 默认常量
 // ============================================================
@@ -48,6 +53,10 @@ export const DEFAULT_IDLE_TIMEOUT_MS = IDLE_TIMEOUT_MINUTES * SECONDS_PER_MINUTE
  * 从环境变量 XYZ_SUBAGENT_IDLE_TIMEOUT_MS 读取全局默认超时。
  * 返回 undefined 表示 env 未设置或非法（调用方回落 DEFAULT_IDLE_TIMEOUT_MS）。
  *
+ * [LC-7/T7①] env 已设但非法（非数字/<=0）回落默认值时必须 warn 留痕——「以为设了
+ * 极长保活、实际回落 5min」的静默语义漂移不可见（设计 §4.3 LC-7），生效行为必须
+ * 可见。禁用语义不认 env（禁用只能显式传参 <=0，见 armIdleTimer 注释）。
+ *
  * [review 修复] 原 PI_ 前缀（PI_SUBAGENT_IDLE_TIMEOUT_MS）不在 ENV_WHITELIST_PREFIXES
  * 白名单（packages/shared/src/constants.ts 只有 XYZ_ 等，无 PI_），xyz-agent 桌面
  * spawn 链（safe-env 过滤）会丢弃该 env，配置口在桌面场景静默失效——已改名 XYZ_
@@ -59,7 +68,12 @@ function getEnvIdleTimeoutMs(): number | undefined {
   const raw = process.env.XYZ_SUBAGENT_IDLE_TIMEOUT_MS;
   if (!raw) return undefined;
   const parsed = Number(raw);
-  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    logger.warn(
+      `[lifecycle-manager] XYZ_SUBAGENT_IDLE_TIMEOUT_MS="${raw}" is invalid (expected a positive millisecond number) — falling back to DEFAULT_IDLE_TIMEOUT_MS (${DEFAULT_IDLE_TIMEOUT_MS}ms); set a plain ms value (e.g. 1800000) to override`,
+    );
+    return undefined;
+  }
   return parsed;
 }
 
@@ -134,8 +148,18 @@ export function armIdleTimer(
   // 刷新：先清旧 timer，避免同一 record 叠加多个 armed timer。
   disarmIdleTimer(recordId);
 
-  const timer = setTimeout(() => {
-    idleTimers.delete(recordId);
+  // [LC-5/T6①] 超时回调按值守卫（对齐同包 session-runner.ts removeChildRegistration
+  // 的按句守卫先例）：clearTimeout 对「已到期、回调已入 macrotask 队列」的 timer 无效
+  //（Node 语义：fire 后不可撤销），若此刻同 recordId 发生 disarm + re-arm（agent_settled
+  // 刷新与旧 timer 到点同轮交错），旧回调无条件 delete(recordId) 会误删**新** timer 条目
+  // ——新 timer 脱管，后续 disarm 失效 → turn 中途被 idle GC 误杀。回调捕获自己的 timer
+  // 引用，仅当 Map 当前条目仍是自己（未被 re-arm 覆盖）才删除。设计 §11-2：fake-timer
+  // 模型内无法复现「旧回调迟到于 re-arm」的精确交错（sinon clock 同步 tick 消除了该
+  // 中间态），身份比对按防御性守卫保留（成本一行）。
+  const timer: NodeJS.Timeout = setTimeout(() => {
+    if (idleTimers.get(recordId)?.timer === timer) {
+      idleTimers.delete(recordId);
+    }
     onTimeout();
   }, resolved);
   // node 默认 setTimeout 返回的 timer 会被事件循环 keep-alive；unref 让它不阻塞

package/src/execution/lifecycle-predicates.ts

@@ -20,7 +20,7 @@
 // 故 isIdle 在这两个检查点恒为 true——notify 守卫与 early-return 判据可靠。
 
 import { hasIdleTimer } from "./lifecycle-manager.ts";
-import { getChildByRecord } from "./session-runner.ts";
+import { getChildByRecord } from "./engine/engines/pi/session-runner.ts";
 import type { ExecutionRecord } from "./types.ts";
 
 /**

package/src/execution/manifest-store.ts

@@ -2,7 +2,12 @@ import * as fs from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 
+import { getLogger } from "../core/logger.ts";
+
 import { bestEffort } from "./best-effort.ts";
+import { writeAtomicFile } from "../shared/atomic-write.ts";
+
+const logger = getLogger("subagents");
 
 export interface ManifestRecord {
   id: string;
@@ -89,54 +94,19 @@ export class ManifestStore {
   }
 
   /**
-   * 原子写：tmp → fsync → rename → fsync dir。真异步（fs.promises，不阻塞 event loop）。
+   * 原子写：tmp → fsync → rename → fsync dir（shared/atomic-write 统一原语，
+   * U6b 迁移——原逐行实现与 writeAtomicFile 逐环等值）。真异步（fs.promises，
+   * 不阻塞 event loop）。
    *
-   * rename 失败时 best-effort 清理残留 tmp（用 renamed 标志在 catch 中决定是否 unlink），
-   * 不掩盖原错误。失败向上抛——调用方（finalizeRecord）决定降级策略。
+   * 失败时原语尽力清理残留 tmp（debug 记录，不掩盖原错误）并原样上抛——
+   * 调用方（finalizeRecord）决定降级策略。
    */
   async writeManifest(record: ManifestRecord): Promise<void> {
     const filePath = path.join(this.dir, `${record.id}.json`);
-    const tmpPath = `${filePath}.tmp.${process.pid}`;
     const content = JSON.stringify(record, null, MANIFEST_INDENT_SPACES);
-
-    let renamed = false;
-    try {
-      // 1. 写 tmp → fsync 文件
-      const fh = await fsPromises.open(tmpPath, "w");
-      try {
-        await fh.writeFile(content, "utf-8");
-        await fh.sync();
-      } finally {
-        await fh.close();
-      }
-
-      // 2. rename tmp → final（放入 try：失败时 catch 清理 tmp）
-      await fsPromises.rename(tmpPath, filePath);
-      renamed = true;
-
-      // 3. fsync 目录（best-effort：POSIX 不要求，失败不否定已成功的 rename）
-      try {
-        const dirFh = await fsPromises.open(this.dir, "r");
-        try {
-          await dirFh.sync();
-        } finally {
-          await dirFh.close();
-        }
-      } catch (dirSyncErr) {
-        bestEffort(dirSyncErr, "fsync dir (writeManifest)");
-      }
-    } catch (err) {
-      // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
-      if (!renamed) {
-        try {
-          await fsPromises.unlink(tmpPath);
-        } catch (cleanupErr) {
-          // best-effort：tmp 可能已被 rename 消费或从未创建。不影响主错误（下面 re-throw err）
-          bestEffort(cleanupErr, "unlink tmp (writeManifest)");
-        }
-      }
-      throw err;
-    }
+    // ensureDir:false：目录由构造函数负责创建（缺目录 = 外部删除的异常态，
+    // 维持旧实现的 fail-fast 上抛语义，不静默重建）
+    await writeAtomicFile(filePath, content, { ensureDir: false });
   }
 
   /**
@@ -212,10 +182,16 @@ export class ManifestStore {
    * 1. manifest 已存在 → 删 tmp（陈旧）
    * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
    * 3. tmp 非法 + manifest 缺失 → 删 tmp
+   *
+   * [T5④ / PS-13] per-file 容错：单个 tmp 文件操作失败（ENOENT——并发回收/外部清理
+   * 抢先、EACCES 等）只 warn + 跳过该文件，不再中断整轮——旧实现单文件 ENOENT 即抛，
+   * 剩余 tmp 本轮不再处理，自愈但不可见（残留顺延下次启动）。跳过数经 warn 汇总留痕，
+   * 调用方返回值形态不变（跳过者不计数）。
    */
   async recoverTmpFiles(): Promise<{ deleted: number; recovered: number }> {
     let deleted = 0;
     let recovered = 0;
+    let failed = 0;
 
     const files = fs.readdirSync(this.dir);
     const tmpFiles = files.filter((f) => f.includes(".json.tmp."));
@@ -225,32 +201,47 @@ export class ManifestStore {
       const manifestId = tmpFile.split(".json.tmp.")[0];
       const manifestPath = path.join(this.dir, `${manifestId}.json`);
 
-      if (fs.existsSync(manifestPath)) {
-        // 分支 1: manifest 已存在，删 tmp
-        fs.unlinkSync(tmpPath);
-        deleted++;
-      } else {
-        // 试解析 tmp
-        try {
-          const content = fs.readFileSync(tmpPath, "utf-8");
-          const parsed: unknown = JSON.parse(content);
-          if (isValidManifest(parsed)) {
-            // 分支 2: tmp 是合法 manifest，rename 为正式文件
-            fs.renameSync(tmpPath, manifestPath);
-            recovered++;
-          } else {
-            // 分支 3b: 合法 JSON 但非合法 manifest（缺必填字段），删
+      try {
+        if (fs.existsSync(manifestPath)) {
+          // 分支 1: manifest 已存在，删 tmp
+          fs.unlinkSync(tmpPath);
+          deleted++;
+        } else {
+          // 试解析 tmp
+          try {
+            const content = fs.readFileSync(tmpPath, "utf-8");
+            const parsed: unknown = JSON.parse(content);
+            if (isValidManifest(parsed)) {
+              // 分支 2: tmp 是合法 manifest，rename 为正式文件
+              fs.renameSync(tmpPath, manifestPath);
+              recovered++;
+            } else {
+              // 分支 3b: 合法 JSON 但非合法 manifest（缺必填字段），删
+              fs.unlinkSync(tmpPath);
+              deleted++;
+            }
+          } catch {
+            // 分支 3a: JSON.parse 失败，删
             fs.unlinkSync(tmpPath);
             deleted++;
           }
-        } catch {
-          // 分支 3a: JSON.parse 失败，删
-          fs.unlinkSync(tmpPath);
-          deleted++;
         }
+      } catch (fileErr) {
+        // [T5④/PS-13] 单文件失败不中断整轮：warn 留痕（含文件名与原因）后继续处理
+        // 剩余 tmp。常见于 tmp 已被并发回收/外部清理删除（ENOENT）——自愈场景不再放大。
+        failed++;
+        logger.warn(`[subagents] recoverTmpFiles: failed to recover ${tmpFile}, skipping (leftovers retry on next startup)`, {
+          detail: fileErr instanceof Error ? fileErr.message : String(fileErr),
+        });
       }
     }
 
+    if (failed > 0) {
+      logger.warn(
+        `[subagents] recoverTmpFiles: ${failed} of ${tmpFiles.length} tmp file(s) could not be recovered`,
+      );
+    }
+
     return { deleted, recovered };
   }
 }

package/src/execution/notifier.ts

@@ -95,9 +95,9 @@ export interface NotifierHost {
   isIdle?: () => boolean;
   /**
    * 原生 settled 事件订阅能力（D8）：注册 handler 监听主 agent settled 边沿。
-   * 无退订语义（pi 0.84.1 的 `pi.on(...)` 全部重载返回 void、无 off——实装锚点：
+   * 无退订语义（pi 0.84.4 的 `pi.on(...)` 全部重载返回 void、无 off——实装锚点：
    * node_modules `@earendil-works/pi-coding-agent` dist/core/extensions/types.d.ts
-   * `on()` 系列重载，0.84.1 实测）——退订由本模块的 disposed
+   * `on()` 系列重载，0.84.4 实测）——退订由本模块的 disposed
    * 标志包装兑现（见下方 port 装配）。可选：未注入时内核退化退避轮询（busy 消息
    * 靠退避达上限强发，不走 settled 边沿驱动）。
    */
@@ -226,14 +226,14 @@ export function createNotifier(host: NotifierHost): BgNotifier {
       host.onAgentSettled === undefined
         ? undefined
         : (cb) => {
-            let disposed = false;
-            host.onAgentSettled?.(() => {
-              if (!disposed) cb();
-            });
-            return () => {
-              disposed = true;
-            };
-          },
+          let disposed = false;
+          host.onAgentSettled?.(() => {
+            if (!disposed) cb();
+          });
+          return () => {
+            disposed = true;
+          };
+        },
     send: (msg, _intent) => {
       // D5 单通道：投递意图唯一化——steer/followUp/nextTurn 多通道全部删除，
       // 唯一发送形态 = sendCustomMessage({triggerTurn:true})。busy 场景由 ledger