@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/engine/host-task-spec.ts

@@ -22,9 +22,9 @@ export function executeOptionsToEngineTaskSpec(opts: ExecuteOptions): AgentTaskS
   const persona: PersonaSpec | undefined =
     opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
       ? {
-          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
-          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
-        }
+        ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
+        ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+      }
       : undefined;
   return {
     task: opts.task,

package/src/execution/engine/port.ts

@@ -4,6 +4,13 @@
 // §3.3.5「EnginePort 完整签名」——本文件是可编码落地的契约层，后续 wave（公共降级层
 // P2 / zcode 引擎 P3 / 配置路由 P4）以本接口为实现契约，字段级变更须先改设计文档。
 //
+// 字段级扩展登记（接上文纪律——先改设计文档再扩接口）：
+//   - [R1 已实施 2026-08-30] EnginePort.dispose?()——引擎停机面。权威源：
+//     docs/design/zcode-engine-appserver-resident.md §3.3 D6 / §3.4 不变量 4。
+//   - [R4 已实施 2026-08-30] RunContext.onHandleReady——运行中句柄回填通道
+//     （同设计 §3.4 不变量 3：sessionRef 在 create 应答后经本回调送达编排层，
+//     与 onPoolResolved 分立两个时点）。
+//
 // 四个能力面（D1）：
 //   run        —— 主语义：一次性 fire-to-completion 任务执行；
 //   interact   —— 交互控制面（chatMode 的 message/close/cancel + idle，可选能力面，
@@ -22,6 +29,7 @@ import type {
   AgentTaskSpec,
   EngineCapabilities,
   EngineHandle,
+  EngineHandleData,
   InteractAction,
   InteractResult,
   ProbeReport,
@@ -49,7 +57,13 @@ export interface RunContext {
   signal?: AbortSignal;
   /** 事件流出口（host 消费后统一落 journal，D6 第②级）。 */
   onEvent?: (event: AgentEvent) => void;
-  /** model 解析第三层兼底（现有 D-008 语义不变）。 */
+  /**
+   * model 解析第三层兜底（现有 D-008 语义不变）——**pi 链路专属兜底**：经
+   * taskSpecToExecuteOptions → resolveModel 第三层消费（PiEngine 直通）。自带
+   * provider 体系与缺省模型的引擎（如 zcode：requested > 引擎缺省常量链）按自身
+   * 默认链解析，不消费本字段（zcode 侧在「ctx 有模型但被忽略」时出声留痕，
+   * zcode-engine.warnIgnoredCtxModel）。
+   */
   ctxModel?: ModelInfo;
   /**
    * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
@@ -81,12 +95,27 @@ export interface RunContext {
    * 未来流式引擎需在事件出口前调用）。
    */
   onPoolResolved?: (poolKey: string) => void;
+  /**
+   * [R4 §3.4 不变量 3] 运行中句柄回填通道：引擎在「session/create 应答到达后」
+   * 立即回调（早于 run resolve——stream 引擎的 run 生命周期远长于会话建立）。
+   * 与 onPoolResolved 分立两个时点：poolKey 在 prepare 期（onPoolResolved，连接
+   * 建立前即可知），sessionRef 在 create 应答后（本回调）。编排层收到后立即回填
+   * record.engineHandle 并落 entry——运行中的 GUI 经 entry 重建 record 即拿到
+   * ①②级读取钥匙，不再等 run resolve 后的终态回填。可选回调：不支持运行中回填
+   * 的引擎（spawn 单轮、终态即回填）不调用，宿主语义不受影响。
+   */
+  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
   /**
    * [U0 D10] 引擎 spawn 的子进程句柄注册钩子（宿主终止链记账）。引擎在 spawn 成功后
    * 同步回调（与 pi runSpawn 的 spawnedChildren.set 同构时机）；宿主据此把 child 注册进
    * session-runner 的 spawnedChildren Map（cancel SIGTERM / dispose 收割兜底 / killAll
    * 全量清理对非 pi 引擎 record 生效）。close/error 后由宿主按句守卫移除。可选：引擎
    * 内部不 spawn 进程（如未来常驻 driver host 实现）时不调用，宿主记账自然为空。
+   *
+   * 边界声明（R1 D6）：本钩子只用于 per-record 一次性 spawn（一任务一进程模态）。
+   * 引擎持有的常驻进程（跨任务共享，如 app-server 常驻连接）不经本钩子注册、不进
+   * spawnedChildren Map——其生命周期完全归引擎 dispose 管理（防 per-record 重复
+   * SIGTERM / 单任务 abort 误杀共享进程）。
    */
   onChildSpawned?: (child: ChildProcess) => void;
 }
@@ -150,4 +179,15 @@ export interface EnginePort {
    * 侧零改动。
    */
   listModels?(): Array<{ id: string; name?: string }> | null;
+
+  /**
+   * [R1 D6] 可选停机面：释放引擎持有的常驻资源（如 app-server 常驻进程 / 长连接）。
+   * 幂等契约（§3.4 不变量 4）：重复调用无副作用；dispose 后首个 run 自动重建（与
+   * 「进程死后重建」同一代码路径）。可选成员保持向后兼容——无常驻资源的引擎（pi
+   * 现状 spawn 单轮）不必实现。等待策略（D6①「触发不等待」）：宿主收割入口
+   * （registry disposeEngines → killAllSpawnedChildren）只同步调用拿 Promise 不
+   * await，引擎实现须自行保证同步面（立即 fire close 帧 + 同步 SIGTERM）在返回
+   * Promise 前完成；grace→SIGKILL 升级序列属异步面（promise 段）。
+   */
+  dispose?(): Promise<void>;
 }

package/src/execution/engine/registry.ts

@@ -10,9 +10,15 @@
 //
 // 依赖方向（设计 §3.3.1 贯穿纪律④）：registry 只依赖 port.ts 的类型，不 import 任何
 // 具体引擎——注册由组合根（index.ts）或引擎自己的 registration 模块完成，防循环依赖。
+// （core/logger 是 facade 基础设施非引擎，dispose best-effort 记日志需要它，不违反本纪律。）
+
+import { getLogger } from "../../core/logger.ts";
 
 import type { EnginePort } from "./port.ts";
 
+// core log facade（execution 层统一 "subagents" component，模块顶层缓存惯例）。
+const logger = getLogger("subagents");
+
 /** 引擎工厂：惰性创建引擎实例（getEngine 首次取用时执行）。 */
 export type EngineFactory = () => EnginePort;
 
@@ -87,17 +93,64 @@ function getRegistrySlot(): EngineRegistrySlot {
   return slot;
 }
 
+/**
+ * [R1 D6] 触发引擎 dispose：同步调用拿 Promise 不 await（「触发不等待」，D6①——
+ * dispose 的同步面〔fire close 帧 + 同步 SIGTERM〕由引擎实现保证在返回 Promise 前
+ * 完成，registry 不等待异步段）。同步 throw 与异步 reject 均记日志吞掉，绝不外溢
+ * 阻断调用方——重注册替换（D6②）与宿主收割（D6③）都是 best-effort 面，且 reject
+ * 无人接会成为 unhandledRejection 崩宿主。两条 dispose 路径共用本函数。
+ */
+function triggerEngineDispose(engine: EnginePort, source: string): void {
+  if (typeof engine.dispose !== "function") return;
+  try {
+    engine.dispose().then(undefined, (err: unknown) => {
+      logger.warn(
+        `[engine-registry] engine '${engine.id}' dispose rejected (${source}, best-effort continue): ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    });
+  } catch (err) {
+    logger.warn(
+      `[engine-registry] engine '${engine.id}' dispose threw synchronously (${source}, best-effort continue): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
 /**
  * 登记引擎工厂。重复注册同一 id = 覆盖（组合根可能多次执行，如每次 session_start 重跑
  * registerPiEngine——幂等覆盖保证不炸也不堆积），覆盖时丢弃缓存的旧单例，让下一次
  * getEngine 用新工厂重建。
+ *
+ * [R1 D6②] 覆盖前对已实例化的旧单例触发 dispose（防泄漏——旧实例可能持有常驻进程/
+ * 长连接）；触发不等待 + 失败不阻断（见 triggerEngineDispose），幂等覆盖语义不变。
  */
 export function registerEngine(id: string, factory: EngineFactory): void {
   const slot = getRegistrySlot();
+  const previous = slot.singletons.get(id);
+  if (previous) triggerEngineDispose(previous, `registerEngine('${id}') overwrite`);
   slot.factories.set(id, factory);
   slot.singletons.delete(id);
 }
 
+/**
+ * [R1 D6③] 对已实例化的引擎单例触发 dispose（触发不等待）。宿主唯一收割入口
+ * （session-runner killAllSpawnedChildren）在杀 per-record children 之前调用——
+ * 常驻进程的回收归引擎 dispose，本函数只负责按序触发。
+ *
+ * 只遍历 singletons：已实例化才可能持有常驻资源，绝不经 getEngine 实例化未用
+ * 引擎（停机路径反向创建资源违背停机语义）。dispose 后不删单例——幂等与
+ * 「dispose 后首个 run 自动重建」由引擎实现承诺（§3.4 不变量 4），registry
+ * 不越权管理引擎内部生命周期。
+ */
+export function disposeEngines(): void {
+  for (const engine of getRegistrySlot().singletons.values()) {
+    triggerEngineDispose(engine, "disposeEngines()");
+  }
+}
+
 /** 未注册 id 抛 EngineNotFoundError（含已注册清单与配置指引）。 */
 export function getEngine(id: string): EnginePort {
   const slot = getRegistrySlot();

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,10 +43,48 @@ 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 一并移除（无生产调用方，死机制）。
 }
 
+/**
+ * [T1/PS-9] 按 record 身份在 sessionDir 反查 session 文件（record.sessionFile 缺失时用）。
+ *
+ * 匹配依据：session JSONL 的 identity custom entry 携带 record id（子进程 session_start
+ * hook 写入），探测函数与 RecordStore 列表扫描同源（readIdentityHeader 头部 64KB →
+ * readIdentityTail 尾部 64KB；续聊场景 identity 靠尾）。readIdentityAnywhere 需全文读，
+ * 本反查是收尾路径的 best-effort，不做。
+ *
+ * @returns 匹配到的 session 文件绝对路径；目录不可读 / 无匹配返回 undefined（不抛）。
+ */
+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;
+}
+
 /**
  * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
  *
@@ -60,6 +99,21 @@ export async function doFinalizeRecord(
   status: "closed",
   closedReason?: ClosedReason,
 ): Promise<void> {
+  // [T1/PS-9] sessionFile 缺失时 sessionDir 反查（放在一切步骤前，让 archive 投影 /
+  // Step 3 marker / Step 4 manifest 统一受益）。RC-1（握手失败）+ LC-4（收尾反查未命中）
+  // 的残余形态下，磁盘上 session 文件仍可能真实存在（identity 携带 record.id）——
+  // 反查命中则 tombstone/finalized sidecar 与 removeAliveMarker 有了依据，终态原因
+  // 不再丢失、alive marker 不再残留；未命中则保持旧行为（best-effort 跳过）。
+  if (!record.sessionFile && deps.sessionDir) {
+    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 0: collectPatch（best-effort）──
   // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
   //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
@@ -179,7 +233,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 +249,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 +263,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/get-state-handshake.ts

@@ -30,6 +30,31 @@ export interface GetStateResult {
   sessionId?: string;
 }
 
+/**
+ * get_state response 监听器注册函数形态（stdout pump / 测试注入）。
+ *
+ * 返回值：注销函数（从监听表移除该 resolver），可省略——performGetStateHandshake
+ * 忽略返回值（既有语义：迟到 response 靠 resolved 标志自弃，条目由 close 统一清）；
+ * requestGetStateOnce 消费返回值做单次请求的自清理（不依赖 close 兜底）。
+ */
+export type AddGetStateResponseListener = (
+  id: string,
+  resolver: (data: unknown) => void,
+) => void | (() => void);
+
+/** 从 get_state response data 提取 sessionFile/sessionId（提取规则单一来源，握手与惰性重试共用）。 */
+function extractGetStateFields(data: unknown, into: GetStateResult): void {
+  if (data && typeof data === "object") {
+    const d = data as Record<string, unknown>;
+    if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
+      into.sessionFile = d.sessionFile;
+    }
+    if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
+      into.sessionId = d.sessionId;
+    }
+  }
+}
+
 /**
  * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
  *
@@ -43,7 +68,7 @@ export interface GetStateResult {
  */
 export function performGetStateHandshake(
   child: ChildProcess,
-  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
+  addResponseListener: AddGetStateResponseListener,
 ): Promise<GetStateResult> {
   return new Promise<GetStateResult>((resolve) => {
     const collected: GetStateResult = {};
@@ -81,15 +106,7 @@ export function performGetStateHandshake(
         // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
         clearTimeout(timer);
         if (pendingRetry) clearTimeout(pendingRetry);
-        if (data && typeof data === "object") {
-          const d = data as Record<string, unknown>;
-          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
-            collected.sessionFile = d.sessionFile;
-          }
-          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
-            collected.sessionId = d.sessionId;
-          }
-        }
+        extractGetStateFields(data, collected);
         // sessionFile 已获取——立即 resolve（无需更多重试）
         if (collected.sessionFile) {
           resolved = true;
@@ -102,3 +119,61 @@ export function performGetStateHandshake(
     tryOnce();
   });
 }
+
+/**
+ * [T1/RC-1] 单次 get_state 请求（agent_end 决策点惰性回补专用）。
+ *
+ * 与 performGetStateHandshake 的关系：复用同一消息构造（sendGetStateCommand）与同一
+ * 字段提取（extractGetStateFields），但**不做重试循环、不 share 握手语义**——调用方
+ * （session-runner agent_end 处置）在子进程 idle 时现场补一次查询（探针 P-T1 实证
+ * 应答 0.3-0.4ms），超时/失败即放弃，由调用方走既有保守分支（行为不劣化）。
+ *
+ * 结果契约与 performGetStateHandshake 一致：resolve GetStateResult（可能为空对象），
+ * 永不 reject——stdin 已断（EPIPE/ERR_STREAM_DESTROYED）的同步写失败按「回补失败」
+ * 处理 resolve 空对象，调用方无需 try/catch。
+ *
+ * 自清理：超时或 response 到达后从监听表移除本请求的 resolver（消费注册器的返回值），
+ * 不留迟到条目；注册器不返回注销函数时退化为 no-op（与握手同形态，靠 close 统一清）。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
+ * @param timeoutMs 单次超时（决策点预算 1s 量级；P-T1 实测 idle 应答亚毫秒）
+ */
+export function requestGetStateOnce(
+  child: ChildProcess,
+  addResponseListener: AddGetStateResponseListener,
+  timeoutMs: number,
+): Promise<GetStateResult> {
+  return new Promise<GetStateResult>((resolve) => {
+    let settled = false;
+    let removeListener: () => void = () => {};
+
+    const finish = (r: GetStateResult): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      removeListener();
+      resolve(r);
+    };
+
+    let reqId: string;
+    try {
+      reqId = sendGetStateCommand(child);
+    } catch {
+      // stdin 已断等同步写失败 = 回补失败，空结果走调用方保守分支（同超时语义）
+      resolve({});
+      return;
+    }
+    removeListener =
+      addResponseListener(reqId, (data: unknown) => {
+        const r: GetStateResult = {};
+        extractGetStateFields(data, r);
+        // response 已到达：无论是否含目标字段都不再等（单次语义，无重试）
+        finish(r);
+      }) ?? (() => {});
+    // [#15] 同款时序模式：timer 在 resolver 注册后创建，resolver/finish 闭包引用它——
+    // 两者都只在 timer 初始化之后才可能被调用（response 到达是异步事件）。
+    const timer: ReturnType<typeof setTimeout> = setTimeout(() => finish({}), timeoutMs);
+    timer.unref();
+  });
+}

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/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