@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/src/execution/alive-store.ts

@@ -1,34 +1,32 @@
-// src/runtime/execution/alive-store.ts
+// src/execution/alive-store.ts
 //
-// .alive sidecar 生产者 + pid 探活。
+// .alive sidecar：跨进程写权声明的生产者 + pid 探活。
 //
-// 子进程启动时写 .alive（pid+id+startedAt），心跳检测时读它 + isProcessAlive
-// 判活。finalize/cancel 收尾时 remove。与 .cancelled/.finalized 构成三件套。
-//
-// 设计对齐 tombstone-store：单文件 sidecar、best-effort I/O、无全局 index。
+// [U4a / D3 v7] 角色重定义（D3d 模块头权威表述）：
+//   - 宿主 resurrect/接管归口写：写权声明 acquire（markResurrected/acquireWriteLease）
+//     / release（markFinalized/markCancelled/markIdleArchived 内部删）；
+//   - 判活 = pid 单判据（findForeignLiveInstance：self-pid 排除 + isProcessAlive，
+//     软超时已退役——谱系 #12，跨轮保留 × startedAt 一次性不刷新的组合下超时会
+//     误判在持声明陈旧）。
+// 写/删动作均经 RecordStore 意图原语归口（G1：本模块不直接面向调用方，write/remove
+// 是 store 内部写面的实现件）。
 
 import * as fs from "node:fs";
 
-import type { AliveMarker } from "./types.ts";
+import { getLogger } from "../core/logger.ts";
 
-// ============================================================
-// 常量
-// ============================================================
+import type { AliveMarker } from "./types.ts";
 
-/**
- * .alive marker 的软超时（1h，自 record-store.ts 迁移为共享常量）：超过此时长的
- * alive 视为陈旧——pid 复用窗口有限（[防] 缩短窗口降误判），且长时间 marker 多半
- * 是异常退出后的残留。v8.5 D 透明重生的异进程探针复用同一判据（findForeignLiveInstance）。
- */
-export const ALIVE_SOFT_TIMEOUT_MS = 3_600_000;
+const logger = getLogger("subagents");
 
 // ============================================================
 // 公开函数
 // ============================================================
 
 /**
- * 在 sessionFile 旁写 .alive sidecar（单行 JSON）。
+ * 在 sessionFile 旁写 .alive sidecar（单行 JSON，跨进程写权声明 acquire）。
  * 覆盖写——同一 sessionFile 只有最后一个 alive marker 有意义。
+ * 失败原样上抛（IO 错不吞——acquire 失败 = 双写风险敞口，调用方响亮处理，D3c）。
  */
 export function writeAliveMarker(sessionFile: string, marker: AliveMarker): void {
   const alivePath = `${sessionFile}.alive`;
@@ -62,14 +60,20 @@ export function readAliveMarker(sessionFile: string): AliveMarker | undefined {
 }
 
 /**
- * 删除 sessionFile 旁的 .alive sidecar。
- * best-effort：不存在不抛（finalize/cancel 收尾调，sidecar 可能已被清理）。
+ * 删除 sessionFile 旁的 .alive sidecar（写权声明 release）。
+ * best-effort：不存在不抛（finalize/cancel 收尾调，sidecar 可能已被清理）；
+ * 存在但删除失败（权限/磁盘错）warn 留痕——release 失败 = 残留声明可能误拦异宿主，
+ * 排障需要线索（D3a：泄漏窗 = 至宿主退出，已接受但必须可见）。
  */
 export function removeAliveMarker(sessionFile: string): void {
   try {
     fs.unlinkSync(`${sessionFile}.alive`);
-  } catch {
-    void 0; // best-effort
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return; // 不存在 = 已释放（幂等终态，正常）
+    logger.warn("[subagents] alive marker release failed (stale lease may block foreign hosts)", {
+      detail: { sessionFile, error: err instanceof Error ? err.message : String(err) },
+    });
   }
 }
 
@@ -95,18 +99,23 @@ export function isProcessAlive(pid: number): boolean {
 }
 
 /**
- * [v8.5 D] 异进程活实例探针：sessionFile 是否仍有「另一进程」的活跃实例。
+ * [v8.5 D → D3c/D3b v7] 异进程活实例探针：sessionFile 是否仍有「另一进程」持有的
+ * 写权声明。调用方在 resurrect / fork-from 前必须经此确认无他方持有，防双写同一
+ * session jsonl。
  *
- * 三判据与 record-store buildRecord 分支 3 同源（readAliveMarker + isProcessAlive +
- * 软超时）：marker 存在 && pid 存活 && 未超软超时才返回 marker；其余返回 undefined
- * （视为确死/陈旧，允许透明重生）。调用方在 resurrect 前必须经此确认源进程确死，
- * 防双写同一 session jsonl。
+ * 判据 = **pid 单判据 + self-pid 排除**（D3 v7，谱系 #12：软超时退役——跨轮保留 ×
+ * startedAt 一次性不刷新的组合下，>1h idle 的在持声明会被误判陈旧，探针超时放行
+ * 开双写窗）：
+ *   - marker.pid === process.pid → undefined（self-pid 排除：本进程的自有声明视同
+ *     无 foreign——消除本进程被自己 marker 拦死的重试死锁，D3c）；
+ *   - marker.pid 活（isProcessAlive）→ marker（他方在持，拦截）；
+ *   - pid 死 / marker 缺失/损坏 → undefined（确死/无声明，放行）。
  */
-export function findForeignLiveInstance(sessionFile: string, now: number = Date.now()): AliveMarker | undefined {
+export function findForeignLiveInstance(sessionFile: string): AliveMarker | undefined {
   const marker = readAliveMarker(sessionFile);
   if (!marker) return undefined;
+  if (marker.pid === process.pid) return undefined;
   if (!isProcessAlive(marker.pid)) return undefined;
-  if (now - marker.startedAt >= ALIVE_SOFT_TIMEOUT_MS) return undefined;
   return marker;
 }
 

package/src/execution/{cold-resurrect.ts → cold-lookup.ts}

@@ -1,14 +1,16 @@
-// [D4-③ 冷路径复活职责轴] message action 冷查/复活链（原 SubagentService 私有的
-// findColdLookupCandidate / assertReconnectAllowed / resurrectColdRecord /
-// coldLookupForAction + isReconnectableClosed 判定）整体搬移至 record-store 邻接处
-// （行为逐字节等价：搬移 + 依赖注入，不重写逻辑）。变化轴：改跨重启重建 /
-// 透明重生回边 / 可重连守卫语义，只改本文件；Service 的 getRecordForAction 保留
-// 归属校验编排（内存未命中分支委托 coldLookupForAction）。
+// [D4-③ 冷路径查询职责轴 / H1 U6 改名] message action 冷查链（原 SubagentService
+// 私有的 findColdLookupCandidate / assertReconnectAllowed / resurrectColdRecord /
+// coldLookupForAction + isReconnectableClosed 判定，W3 后寄居 cold-resurrect.ts）。
+// [H1 U6] cold-resurrect.ts 随 chat 域退役改名落位本文件：其中「跨重启磁盘重建无条件
+// 置 chatMode=true」的升级语义已迁 Continuation D4 revive 格 + D5 gate
+//（conversation-continuation.ts reviveOrThrow / subagent-actions-core messageHandler
+// 双写点），本文件只保留冷查定位 / 可重连守卫 / 磁盘重建注册链——UF-1 跨重启续聊
+// 绑定链（getRecordForAction → coldLookupForAction → 绑定重建 → Continuation）的
+// 宿主侧解析承载。变化轴：改跨重启重建 / 透明重生回边 / 可重连守卫语义，只改本文件；
+// Service 的 getRecordForAction 保留归属校验编排（内存未命中分支委托 coldLookupForAction）。
 
-import * as fs from "node:fs";
-
-import { findForeignLiveInstance, writeAliveMarker } from "./alive-store.ts";
-import { createRecord, resurrectClosed } from "./execution-record.ts";
+import { findForeignLiveInstance } from "./alive-store.ts";
+import { createRecord } from "./execution-record.ts";
 import type { StatusFilter } from "./record-store.ts";
 import type { ExecutionRecord, SubagentRecord } from "./types.ts";
 import { isReconnectableFinalReason, ResurrectDeniedError } from "./types.ts";
@@ -19,16 +21,22 @@ import { isReconnectableFinalReason, ResurrectDeniedError } from "./types.ts";
 export const COLD_LOOKUP_SCAN_LIMIT = 1000;
 
 /** 冷查/复活的依赖注入（Service 侧供给，store 查询 + 归属上下文）。 */
-export interface ColdResurrectDeps {
+export interface ColdLookupDeps {
   /** store 的 idToFile 索引直查（light 快照）。 */
   findLightById: (id: string) => SubagentRecord | undefined;
   /** store 的磁盘全扫（内存未命中 / 索引未热时兜底）。rootFilter 恒 undefined
    *  （冷查不做 root 过滤——归属校验在候选定位之后，见 coldLookupForAction）。 */
   collectRecords: (limit: number, statusFilter: StatusFilter, rootFilter: undefined) => SubagentRecord[];
-  /** 重建 record 注册进内存 store。 */
+  /** 重建 record 注册进内存 store。（[U2a/B4] register 已收编进 markResurrected
+   *  ——生产链不调用（resurrect 回边经 markResurrected 幂等再注册）；保留供编排层
+   *  显式性与测试断言。） */
   register: (record: ExecutionRecord) => void;
-  /** 重建后的 transition entry 上报（live ≡ reload 等价性）。 */
+  /** 重建后的 transition entry 上报（live ≡ reload 等价性——纯投递副作用，留编排层）。 */
   reportRecordTransition: (record: ExecutionRecord) => void;
+  /** [U2a/B4] 透明重生回边原语（store.markResurrected，D3c 规格）：acquire-first
+   *  三件套（写 .alive 写权声明 → 删 .state → 删 .finalized legacy）+ resurrectClosed
+   *  内存翻回 + register，单 try 域原子收敛；任一步失败响亮抛错中止主流程。 */
+  markResurrected: (record: ExecutionRecord, wasClosed: boolean) => void;
   /** 当前所属根 session id（归属校验用，运行时可变——initSession 建立）。 */
   getSessionRootId: () => string | null;
   /** 本进程嵌套基线 recordId（直接父校验用；根进程 undefined）。 */
@@ -43,12 +51,13 @@ export interface ColdResurrectDeps {
  *  异进程实例（父进程重启后旧子进程尚存的窗口），resume 会 spawn 第二个 pi 子进程
  *  写同一 session JSONL（本代码最忌惮的双写者形态，v4 A-5/P7 事故模式）。closed 候选
  *  的同款守卫已在 assertReconnectAllowed（v8.5 D）；本守卫闭合 running 候选的防御
- *  不对称。marker 的 pid 是子进程 pi 的 pid（非父进程），本进程持有的 running record
- *  恒在内存（archive 才移出），可达本冷查分支的 running 候选必然来自磁盘重建——
- *  探针命中即拒绝（ResurrectDeniedError，与 closed 候选守卫同异常类型，错误含 pid
- *  与恢复指引）。 */
+ *  不对称。marker 的 pid 是**宿主进程** pid（D3d 失实注释修正：写者 = 宿主的写权声明
+ *  acquire——resurrect 回边 / running 接管 / spawn 锚点确立，非子进程 pi 自写），本
+ *  进程持有的 running record 恒在内存（archive 才移出），可达本冷查分支的 running
+ *  候选必然来自磁盘重建——探针命中即拒绝（ResurrectDeniedError，与 closed 候选守卫
+ *  同异常类型，错误含 pid 与恢复指引）。 */
 function findColdLookupCandidate(
-  deps: ColdResurrectDeps,
+  deps: ColdLookupDeps,
   id: string,
   allowReconnect: boolean,
 ): SubagentRecord | undefined {
@@ -106,7 +115,7 @@ function assertReconnectAllowed(found: SubagentRecord, id: string): void {
 
 /** 磁盘候选重建为可变 record 并 register + 上报（coldLookupForAction 步骤 4）。 */
 function resurrectColdRecord(
-  deps: ColdResurrectDeps,
+  deps: ColdLookupDeps,
   found: SubagentRecord,
   id: string,
 ): ExecutionRecord {
@@ -121,10 +130,11 @@ function resurrectColdRecord(
     rootSessionId: found.rootSessionId,
     parentRecordId: found.parentRecordId,
     depth: found.depth,
-    // [v4 A-3] 跨重启恢复入口——message 路径磁盘重建无条件置 chatMode=true（现状机制，
-    // V3 方案 A 方向兑现）。改动此处必须带 S3 回归场景（跨重启 message 续聊验证）。
-    // V3 SP-5 探针定案：机制已存在，本注释即定案，不再悬置。
-    chatMode: true,
+    // [v4 A-3 → H1 U6 / D4-D5] 水合保留持久化 chatMode（UF-1 绑定 sidecar 的身份域
+    // 投影，record-store buildRecord 已承载）：磁盘上是什么就是什么。原「无条件置
+    // chatMode=true」的升级语义迁 Continuation D4 revive 格 + D5 gate 双写点
+    //（one-shot 跨重启重建 chatMode=false 后收到 message → gate 放行 → 升级置位再续聊）。
+    chatMode: found.chatMode === true,
     controller: new AbortController(),
   });
   record.sessionFile = found.sessionFile;
@@ -135,29 +145,22 @@ function resurrectColdRecord(
   // 隔离——正是 worktree 要防的并发写冲突场景）。close 不受影响（closeChatIdle 走
   // doFinalizeRecord，泄漏的 worktree 由 reaper 兜底回收）。
   record.hadWorktree = found.worktree === true;
-  // [v8.5 D] 透明重生回边：独立函数不走 tryTransition 单向语义（closed 单向性对正常
-  // 执行流完整保留）；准入唯一依据 = A 档 sidecar 真实死因 ∈ 可重连集。死亡语义位由
-  // resurrectClosed 清除；register 后立刻上报 transition entry，live/reload 视图同步
-  // 翻回 running（等价性由 applyEntry reducer 保证，对齐 SP-2 重建即报告先例）。
+  // [U2a/B4 → D3c] 透明重生回边整体收编 store.markResurrected：acquire-first 顺序
+  // （写 .alive 写权声明 → 删 .state → 删 .finalized legacy）+ resurrectClosed 内存
+  // 翻回 + register，单 try 域原子收敛。准入唯一依据 = A 档 sidecar 真实死因 ∈ 可重连
+  // 集（守卫已在上方跑完）；reportTransition（entry 上报）留本编排层（纯投递副作用，
+  // 失败不破坏状态一致性）。
+  // 两种接管形态统一 acquire（D3c）：closed 候选（wasClosed=true）三件套全量；running
+  // 候选接管（跨重启磁盘重建，wasClosed=false）跳过删终态位（无 .state 可删）**仍
+  // acquire marker**——「接管即声明」，现状此路径不写 marker 的 B/C 双写窗随归口消灭。
+  // 失败语义 = 响亮抛错中止主流程（§3.4）：acquire 失败 = 双写风险敞口，禁止
+  // best-effort 吞错续跑（旧「单 try 吞错后继续 resurrectClosed + register」形态随
+  // 归口消灭）；acquire-first 顺序保证失败时终态位未删、磁盘保持旧形态（可重试）。
   const wasClosed = found.status !== "running";
+  deps.markResurrected(record, wasClosed);
   if (wasClosed) {
-    // [review MF-8] 磁盘终态位同步翻转：record-store buildRecord 分支 2（.finalized
-    // 存在 → closed）优先级高于 .alive 活态分支 3，重生若不删 sidecar，任何磁盘扫描
-    // （异进程 / reload / session-reader）都会把本进程内存里 running 的 record 报成
-    // closed/disconnected——破坏 live ≡ reload，且为跨进程二次 resurrect 开门。
-    // best-effort 对齐 BC-4 语义；.alive 刷新为当前进程（后续 resume spawn 会覆盖写）。
-    if (record.sessionFile) {
-      try {
-        fs.rmSync(`${record.sessionFile}.finalized`, { force: true });
-        writeAliveMarker(record.sessionFile, { pid: process.pid, id, startedAt: Date.now() });
-      } catch (_e) {
-        void _e; // best-effort：sidecar 翻转失败不阻断重生主流程
-      }
-    }
-    resurrectClosed(record);
-  }
-  deps.register(record);
-  if (wasClosed) {
+    // 重生后立刻上报 transition entry（live/reload 视图同步翻回 running，等价性由
+    // applyEntry reducer 保证，对齐 SP-2 重建即报告先例）。
     deps.reportRecordTransition(record);
   }
   return record;
@@ -169,7 +172,7 @@ function resurrectColdRecord(
  *  @throws ResurrectDeniedError 可重连候选被 worktree/异进程活实例守卫拦截
  *  @throws Error parentRecordId 跨层不匹配（direct parent 错误，与外层校验同文案） */
 export function coldLookupForAction(
-  deps: ColdResurrectDeps,
+  deps: ColdLookupDeps,
   id: string,
   allowReconnect: boolean,
 ): ExecutionRecord | undefined {

package/src/execution/config.ts

@@ -1,4 +1,4 @@
-// src/runtime/config/config.ts
+// src/execution/config.ts
 //
 // 全局配置（~/.pi/agent/subagents/config.json）。
 // 仅保留 maxConcurrent（pool 大小）。模型解析已退化为「主 agent model 优先」，