@zhushanwen/subagent-core 0.2.0 → 0.4.0

package/src/execution/sessions-index.ts

@@ -21,12 +21,11 @@
 // 无状态纯函数模块：不依赖 RecordStore 任何内部状态。
 
 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 { writeAtomicFile } from "../shared/atomic-write.ts";
 
-import { bestEffort } from "./best-effort.ts";
 import type { ExecutionMode } from "./types.ts";
 
 const logger = getLogger("subagents");
@@ -44,13 +43,6 @@ export const INDEX_VERSION = 1;
 /** 两次成功落盘的最小墙钟间隔（节流：overlay 打开期间的高频扫描不放大磁盘写）。 */
 export const INDEX_WRITE_MIN_INTERVAL_MS = 60_000;
 
-/** tmp 文件单调计数：同一进程内并发的 saveIndex 各用独立 tmp。节流基准只在写成功后
- *  推进——W1 在途时新一轮过窗扫描可再 dispatch W2，共用同一 tmp 会交错（W2 truncate
- *  落在 W1 write 与 rename 之间 → 半成品被 rename / rename 后失败 → 假失败日志）。
- *  pid+seq 双后缀保证 tmp 唯一：交错 rename 的终态必为某次完整快照（last-writer-wins，
- *  与跨进程 pid 隔离同语义；陈旧快照胜出时下轮戳不匹配自愈）。 */
-let tmpSeq = 0;
-
 // ============================================================
 // 类型（DM1 磁盘顶层 + DM2 条目）
 // ============================================================
@@ -245,60 +237,23 @@ export function loadIndex(encDir: string): LoadedSessionsIndex {
 // ============================================================
 
 /**
- * 原子写索引（tmp(pid+seq) → fsync → rename → fsync 目录；逐环复刻
- * ManifestStore.writeManifest 的生产模式）。tmp 带 pid+单调序号双后缀：pid 防两进程
- * 共用同一 tmp，seq 防同进程内并发 saveIndex（节流基准在写成功后才推进，W1 在途时
- * 新一轮过窗扫描可 dispatch W2）共用同一 tmp；rename 原子性保证读侧看到旧版或完整
- * 新版，绝无半成品。
+ * 原子写索引（shared/atomic-write 统一原语，U6b 迁移：tmp → fsync → rename →
+ * fsync 目录）。原逐行实现（逐环复刻 ManifestStore.writeManifest 的生产模式）
+ * 与 writeAtomicFile 逐环等值；tmp 带 pid+单调序号双后缀防撞的语义由原语的
+ * atomicTmpPathFor 接管（pid 防两进程共用同一 tmp，seq+rand 防同进程并发
+ * saveIndex 共用同一 tmp）。rename 原子性保证读侧看到旧版或完整新版，绝无半成品。
+ * ensureDir:false——旧实现无 mkdir（目录由 sessionsDir 布局保证），缺目录维持
+ * fail-fast 上抛（调用方 .catch 兜底），不静默重建。
  *
  * 失败向上抛——RecordStore 的 flushIndexAfterScan 以 fire-and-forget .catch 消费
- * （写失败不影响任何扫描结果，恢复 dirty 待下轮过窗重试）。
+ *（写失败不影响任何扫描结果，恢复 dirty 待下轮过窗重试）。
  */
 export async function saveIndex(encDir: string, data: SessionsIndexData): Promise<void> {
   const filePath = path.join(encDir, INDEX_FILENAME);
-  const tmpPath = `${filePath}.tmp.${process.pid}.${++tmpSeq}`;
   const file: SessionsIndexFile = {
     version: INDEX_VERSION,
     pid: process.pid,
     entries: Object.fromEntries(data.entries),
   };
-  const content = JSON.stringify(file);
-
-  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(encDir, "r");
-      try {
-        await dirFh.sync();
-      } finally {
-        await dirFh.close();
-      }
-    } catch (dirSyncErr) {
-      bestEffort(dirSyncErr, "fsync dir (saveIndex)");
-    }
-  } catch (err) {
-    // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
-    if (!renamed) {
-      try {
-        await fsPromises.unlink(tmpPath);
-      } catch (cleanupErr) {
-        bestEffort(cleanupErr, "unlink tmp (saveIndex)");
-      }
-    }
-    throw err;
-  }
+  await writeAtomicFile(filePath, JSON.stringify(file), { ensureDir: false });
 }

package/src/execution/settled-watchdog.ts

@@ -0,0 +1,99 @@
+// src/execution/settled-watchdog.ts
+//
+// [T2-③ / LC-1] chatMode settled 等待固定硬上限（回收层「上界族」共享原语）。
+//
+// 设计：docs/design/subagent-core-unbounded-wait-audit.md §7.2 T2-③ / §4.1 LC-1。
+// chatMode 任意一轮等待 agent_settled 的窗口挂固定硬上限（默认 10 分钟）——settled
+// 永不到达（事件行丢失 / 子进程 wedged）时本 timer 是唯一独立回收通道：现状
+// 「settled 不 arm 则 idle timer 不挂、runSpawn 已在首轮返回、spawn watchdog 默认关」
+// 的三无窗口由此收敛（LC-1 同族变体）。
+//
+// 固定上界（非事件刷新语义）：该窗口的正常语义是 post-run 收尾（compact 检查等，
+// 秒级完成），窗口内的任何输出都不能证明 settled 终将到达——「刷新」会让「wedged
+// 但仍有周期性输出」的进程无限续命（LC-9 已证 stdout 可有调试行）。固定上界
+// by construction 覆盖静默与非静默两种 wedged 形态。多轮会话中每轮窗口独立计时
+//（重复 arm = 以新窗口覆盖旧计时，对齐 lifecycle-manager.armIdleTimer 的刷新语义）。
+//
+// 双挂载点共用同一原语——同一常量 + 同一挂载/清除 helper，仅两个调用点（设计
+// T2-③ 明示架构，两处各写一套恰是被否的「散布姿势」微缩复发）：
+//   - 首轮：session-runner.ts runSpawn（prompt 发出后挂；settled 到达 / close /
+//     resolveRun 任一发生即清）
+//   - 后续轮次热路径：subagent-service.ts deliverMessage（发出新一轮 prompt 后挂，
+//     u-t2b 接线）
+//
+// 与 lifecycle-manager 的 idle timer 互补：idle timer 管 settled 已到达后的空闲
+// 回收，本上界管 settled 永不到达的 wedged——两条正交通道不互相替代。
+//
+// 实现形态对齐 armIdleTimer（recordId → timer 的模块级记账）：重复 arm 先清旧
+// timer、到期回调先自删条目再执行——挂载/清除责任内聚在原语，调用方不管理句柄
+// 覆盖（防「忘清旧窗」散布错误）。
+
+import { getLogger } from "../core/logger.ts";
+import { assertSafeTimerDelay } from "../shared/timer-delay.ts";
+
+const logger = getLogger("subagents");
+
+/**
+ * settled 等待固定硬上限（10 分钟）。
+ *
+ * [P-T2c 定案] 真实 pi 会话 agent_end→agent_settled 间隔 6 轮全部 <2ms（两事件行
+ * 同 chunk 到达）；30 万 tokens 上下文显式 compaction 耗时 40.1s——10min 上限余量
+ * 4 个数量级以上（probe/p-t2c-report.md）。维持设计默认值，仅此一处定义。
+ */
+export const SETTLED_WATCHDOG_TIMEOUT_MS = 600_000;
+
+/** recordId → armed settled watchdog timer。仅在等待窗口内 armed（挂载/清除成对）。 */
+const armedTimers = new Map<string, NodeJS.Timeout>();
+
+/**
+ * 挂载（或按新窗口重挂）某 record 的 settled 等待硬上限。
+ *
+ * - 重复 arm（同 recordId）先 clearTimeout 旧 timer——每轮窗口独立计时，不叠加。
+ * - 到期回调先从 Map 移除自身再执行 onTimeout（onTimeout 内重新 arm 不会被误删）。
+ * - timer unref：不阻止主进程退出（回收兜底不阻塞 shutdown，对齐 idle timer /
+ *   spawn watchdog 的 unref 语义）。
+ * - 到期行为由调用方注入 onTimeout（kill 进程 + 该轮失败终态化）——本模块不持有
+ *   ChildProcess / record，与 lifecycle-manager 同构（副作用能力由调用方注入，
+ *   本模块只管 timer 生命周期，可独立编译 + 单测）。
+ */
+export function armSettledWatchdog(recordId: string, onTimeout: () => void): void {
+  // 常量恒在安全域内；入口统一校验防未来值改可配置时静默引入 1ms 溢出语义反转。
+  assertSafeTimerDelay(SETTLED_WATCHDOG_TIMEOUT_MS, "settled watchdog");
+  // 重挂 = 新窗口：先清旧 timer，防同一 record 叠加多个 armed timer。
+  disarmSettledWatchdog(recordId);
+  const timer = setTimeout(() => {
+    armedTimers.delete(recordId);
+    logger.debug(`[settled-watchdog] fired for ${recordId} after ${SETTLED_WATCHDOG_TIMEOUT_MS}ms without agent_settled`);
+    onTimeout();
+  }, SETTLED_WATCHDOG_TIMEOUT_MS);
+  timer.unref();
+  armedTimers.set(recordId, timer);
+}
+
+/**
+ * 清除某 record 的 settled 等待硬上限（settled 到达 / close / resolveRun 任一发生
+ * 即清）。不存在 armed timer 时 no-op。
+ */
+export function disarmSettledWatchdog(recordId: string): void {
+  const timer = armedTimers.get(recordId);
+  if (!timer) return;
+  clearTimeout(timer);
+  armedTimers.delete(recordId);
+}
+
+/**
+ * 查询某 record 是否有 armed settled watchdog（测试/接入期断言用）。
+ */
+export function hasSettledWatchdog(recordId: string): boolean {
+  return armedTimers.has(recordId);
+}
+
+/**
+ * 清空全部 armed timer（测试隔离用，beforeEach 调；命名对齐 _resetLifecycleState 先例）。
+ */
+export function _resetSettledWatchdogsForTest(): void {
+  for (const timer of armedTimers.values()) {
+    clearTimeout(timer);
+  }
+  armedTimers.clear();
+}