@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/notify-host.ts

@@ -8,7 +8,7 @@ import { displayAgentName } from "../shared/agent-ref.ts";
 import { snapshot } from "./execution-record.ts";
 import { hasIdleTimer } from "./lifecycle-manager.ts";
 import { hasLiveProcessHandle, isIdle, isResumable } from "./lifecycle-predicates.ts";
-import type { BgNotifier, NotifierHost } from "./notifier.ts";
+import type { BgNotifier, BatchBudgetParams, NotifierHost } from "./notifier.ts";
 import { createNotifier } from "./notifier.ts";
 import type { BgNotifyRecord } from "./notifier.ts";
 import type { ExecutionRecord, RecordSnapshot } from "./types.ts";
@@ -50,6 +50,14 @@ export interface NotifyHost {
   emitPendingRegister(id: string, name?: string): void;
   /** pending-notifications 注销（原模块函数 emitPendingUnregister）。 */
   emitPendingUnregister(id: string, reason: string): void;
+  /** [sync-collect U2 合并] record → BgNotifyRecord 映射——collectCoordinator 的
+   *  toNotifyRecord/notifyAsync 依赖注入消费（守卫放行逻辑单一权威在本文件）。 */
+  toNotifyRecord(record: ExecutionRecord): BgNotifyRecord | undefined;
+  /** [sync-collect 合并] 单条直发——collectCoordinator notifyAsync 与 E9 dispose
+   *  转换路径消费（已越过 toNotifyRecord 守卫的成品通知）。 */
+  notify(record: BgNotifyRecord): void;
+  /** [sync-collect 合并] sync 批投递——collectCoordinator flushBatch 与 E1 补发消费。 */
+  notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean;
   /** dispose 的逆操作（initSession 复活，原 notifier.revive 委托）。 */
   revive(): void;
   /** dispose 前冲刷待发通知（原 notifier.flushPendingNotifications 委托）。 */
@@ -197,6 +205,18 @@ export function createNotifyHost(deps: NotifyHostDeps): NotifyHost {
       emitPendingUnregister(deps.getPi(), id, reason);
     },
 
+    toNotifyRecord(record: ExecutionRecord): BgNotifyRecord | undefined {
+      return toNotifyRecord(record);
+    },
+
+    notify(record: BgNotifyRecord): void {
+      notifier.notify(record);
+    },
+
+    notifyBatch(records: readonly BgNotifyRecord[], budget?: BatchBudgetParams): boolean {
+      return notifier.notifyBatch(records, budget);
+    },
+
     revive(): void {
       notifier.revive();
     },

package/src/execution/record-entry.ts

@@ -97,6 +97,18 @@ export interface SubagentRecordEntryData {
    * 透传不枚举内部键（zcode = { sessionId, dbPath }）；缺省 = pi（存量 entry 零迁移）。
    */
   engineHandle?: { sessionRef: Record<string, string>; journalPath?: string; poolKey: string };
+  /**
+   * 同步收集模式标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。
+   * undefined = async（缺省语义，旧 entry 零迁移——undefined 经 JSON.stringify 自然缺省）。
+   * 消费方：U5 rebuildEntryRecord 投影扩展 + E1 重建扫描。
+   */
+  collectMode?: "sync";
+  /**
+   * 离开批终局标记（subagent-sync-collect 设计 §3.1.3，U1 foundation）。两出口统一
+   * 落标（批闭合 flush / E9 dispose 转换，均 appendEntry 持久化）。undefined =
+   * 未离开批 / 旧 entry 零迁移。消费方：U5 E1 重建扫描只收无标记成员（防双重通知）。
+   */
+  batchFinalized?: boolean;
 }
 
 /** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。
@@ -134,5 +146,9 @@ export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEnt
     engine: record.engine,
     engineFallback: record.engineFallback,
     engineHandle: record.engineHandle,
+    // 同步收集两字段（U1 foundation）：undefined 经 JSON.stringify 自然缺省，
+    // 旧记录/旧 entry 序列化产物字节不变（零迁移）。
+    collectMode: record.collectMode,
+    batchFinalized: record.batchFinalized,
   };
 }

package/src/execution/record-store.ts

@@ -259,40 +259,103 @@ function collectLastRecordEntries(content: string): Map<string, Record<string, u
   return lastById;
 }
 
+/** entry data 字段的安全 string 读取（非 string → undefined）。 */
+function entryStr(d: Record<string, unknown>, k: string): string | undefined {
+  return typeof d[k] === "string" ? (d[k] as string) : undefined;
+}
+
+/** entry data 字段的安全 number 读取（非 number → undefined）。 */
+function entryNum(d: Record<string, unknown>, k: string): number | undefined {
+  return typeof d[k] === "number" ? (d[k] as number) : undefined;
+}
+
+/** 终态域投影：status 只认 "closed" 字面量（其余含缺省 → "running"，旧调用方行为不变）；
+ *  closedReason 经枚举守卫（非法/缺省 → undefined）。 */
+function readEntryTerminalFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "status" | "closedReason"> {
+  const closedReason = entryStr(d, "closedReason");
+  return {
+    status: d.status === "closed" ? "closed" : "running",
+    closedReason: isValidClosedReason(closedReason) ? closedReason : undefined,
+  };
+}
+
+/** 批收集域投影（U5 E1）：仅显式字面量收敛，缺省 undefined（JSON 序列化自然缺省）。 */
+function readEntryBatchFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "collectMode" | "batchFinalized" | "resumable"> {
+  return {
+    collectMode: d.collectMode === "sync" ? "sync" : undefined,
+    batchFinalized: d.batchFinalized === true ? true : undefined,
+    resumable: d.resumable === true ? true : undefined,
+  };
+}
+
+/** engine 域投影：engineFallback/engineHandle 经运行时 guard（未知 JSON 不裸收）。 */
+function readEntryEngineFields(
+  d: Record<string, unknown>,
+): Pick<SubagentRecord, "engine" | "engineFallback" | "engineHandle"> {
+  return {
+    engine: entryStr(d, "engine"),
+    engineFallback: isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
+    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
+  };
+}
+
 /** entry data 即 SubagentRecord v1 快照——带运行时 guard 重建（taste/no-unsafe-cast）。
- *  损坏 entry（agent/task/startedAt 任一缺失）返回 null，由调用方跳过。 */
+ *  损坏 entry（agent/task/startedAt 任一缺失）返回 null，由调用方跳过。
+ *  [U5 E1] 投影白名单扩展（设计 §3.1.3「标记读取通路」）：collectMode/batchFinalized
+ *  + 终态五字段 status/endedAt/closedReason/result/error——原实现硬编码
+ *  status:"running" 且不投影终态，E1 重建成员恒被视为 running，「全员终态→补发」
+ *  判定永假、补发内容缺失，整条补发路径成死代码。status 守卫只认 "closed" 字面量
+ *  （其余含缺省 → "running"，旧调用方 recoverEntryOnlyOrphans 行为不变——其候选
+ *  守卫已滤非 running 末条）；closedReason 经 isValidClosedReason 枚举守卫。
+ *  [v2 D3] 再补 resumable/sessionFile 两投影：成功成员崩溃时末条恒为轮终
+ *  running+resumable entry（SP-5 有意语义），不投影 resumable 则 E1 无法与协调器
+ *  hasRunningSync 同构豁免（§2.3 断链 3）；sessionFile 原硬编码 undefined，导致
+ *  E1 落标路径重建快照丢失反查索引锚（断链 1 前置依赖）。recoverEntryOnlyOrphans
+ *  的候选判定（isEntryOrphanCandidate）只认 status==="running"，两新字段不参与
+ *  判定（P-rebuild 探针守卫面）。
+ *  [E1 恢复批语义修复] 再补 patchFile 投影：entry data 携带该字段
+ *  （toSubagentRecordEntry 落盘含 patchFile）但原投影丢弃 → E1 补发记录丢失
+ *  worktree patch 的 git-apply 回收指针（正常 flush 路径经 toNotifyRecord 特意
+ *  携带，notify-host.ts patchFile 透传）。undefined 经 JSON.stringify 自然缺省，
+ *  无 patchFile 的存量 entry 序列化字节不变（落标出口经 toSubagentRecordEntry
+ *  按名重投影，重建对象字段顺序不影响序列化字节形态）。
+ *  字段顺序 = 对象字面量原序（终态/批收集/engine 域以 spread 在原位置展开），
+ *  entry 序列化字节形态不变。 */
 function rebuildEntryRecord(id: string, d: Record<string, unknown>): SubagentRecord | null {
-  const str = (k: string): string | undefined => (typeof d[k] === "string" ? (d[k] as string) : undefined);
-  const num = (k: string): number | undefined => (typeof d[k] === "number" ? (d[k] as number) : undefined);
-  const agent = str("agent");
-  const task = str("task");
-  const startedAt = num("startedAt");
+  const agent = entryStr(d, "agent");
+  const task = entryStr(d, "task");
+  const startedAt = entryNum(d, "startedAt");
   if (agent === undefined || task === undefined || startedAt === undefined) return null; // 损坏 entry：跳过
   return {
     id,
     agent,
     task,
-    slug: str("slug") ?? "",
-    status: "running",
+    slug: entryStr(d, "slug") ?? "",
+    ...readEntryTerminalFields(d),
     mode: "background",
     startedAt,
-    rootSessionId: str("rootSessionId"),
-    parentRecordId: str("parentRecordId"),
-    depth: num("depth") ?? 0,
-    endedAt: undefined,
-    turns: num("turns") ?? 0,
-    totalTokens: num("totalTokens") ?? 0,
-    model: str("model") ?? "",
-    thinkingLevel: str("thinkingLevel"),
+    rootSessionId: entryStr(d, "rootSessionId"),
+    parentRecordId: entryStr(d, "parentRecordId"),
+    depth: entryNum(d, "depth") ?? 0,
+    endedAt: entryNum(d, "endedAt"),
+    turns: entryNum(d, "turns") ?? 0,
+    totalTokens: entryNum(d, "totalTokens") ?? 0,
+    model: entryStr(d, "model") ?? "",
+    thinkingLevel: entryStr(d, "thinkingLevel"),
     eventLog: [],
     displayItems: [],
-    sessionFile: undefined,
+    result: entryStr(d, "result"),
+    error: entryStr(d, "error"),
+    sessionFile: entryStr(d, "sessionFile"),
+    patchFile: entryStr(d, "patchFile"),
     chatMode: d.chatMode === true,
-    round: num("round"),
-    engine: str("engine"),
-    engineFallback:
-      isEngineFallbackShape(d.engineFallback) ? d.engineFallback : undefined,
-    engineHandle: isEngineHandleShape(d.engineHandle) ? d.engineHandle : undefined,
+    round: entryNum(d, "round"),
+    ...readEntryEngineFields(d),
+    ...readEntryBatchFields(d),
   };
 }
 
@@ -645,35 +708,59 @@ export class RecordStore {
    * - 文件不可读（IO 错误，可能暂时）→ 不判终态，落 resumable entry（防御性路径，
    *   IO 恢复后重开可重判）。
    *
+   * [v2 D3] mainSessionFile = 覆写 merge 数据源（主 session 每 id 末条 entry，与 E1
+   * 的 scanLastRecordEntries 同款通路）：崩溃前的批域标记（collectMode/batchFinalized）
+   * 与轮终 result/model 只活在主文件 entry——重建矩阵（buildRecord）的数据源
+   * （sidecar/子文件 identity）不含它们，覆写前不 merge 就会被抹掉（v2 §2.2 断链 2：
+   * E1 候选集恒空的真根因）。缺省（undefined）时 merge 无源，行为与旧版一致。
+   * 参数为追加式第二参（rootSessionFilter 保持首参）：既有调用面只传过滤参。
+   *
    * 防重：orphanJudged 实例级缓存（resumable 形态无 sidecar 锚，同进程重复调用跳过；
    * 终态形态双重防护 = sidecar + 缓存）。调用方：index.ts session_start 恢复段（一次）。
    */
-  recoverOrphanRecords(rootSessionFilter?: string): void {
+  recoverOrphanRecords(rootSessionFilter?: string, mainSessionFile?: string): void {
+    const lastById = new Map(this.scanLastRecordEntries(mainSessionFile).map((r) => [r.id, r]));
     for (const rec of this.reconstructAll(rootSessionFilter)) {
       // 分支 4 命中集 = running 且无活进程实例（分支 3 带 externalInstance，分支 1/2 已 closed）。
       if (rec.status !== "running" || rec.externalInstance !== undefined) continue;
       if (this.orphanJudged.has(rec.id)) continue;
       this.orphanJudged.add(rec.id);
-      this.finalizeOrphanRecord(rec);
+      this.finalizeOrphanRecord(rec, lastById.get(rec.id));
     }
   }
 
   /**
    * 单孤儿 record 的终态判定与落 entry（residual-fixes §5.2 三判据 + chat 分流）。
    * 防重锚（orphanJudged 标记）已由调用方完成。
+   *
+   * [v2 D3] 覆写前 merge（lastEntry = 主 session 同 id 末条 entry 重建，调用方构建）：
+   * 覆写是状态迁移不是信息重建，迁移不应丢末条既有信息。三个落 entry 分支（chatMode
+   * 分流 / IO 保守 / 终态覆写）统一基于 merge 后的 rec，同款口径。
    */
-  private finalizeOrphanRecord(rec: SubagentRecord): void {
-    if (rec.chatMode === true) {
+  private finalizeOrphanRecord(rec: SubagentRecord, lastEntry?: SubagentRecord): void {
+    // 仅补 undefined/空值字段、不覆盖已有值——覆写自带的 status/closedReason/endedAt/
+    // error 不在 merge 字段集，天然不受影响。批域字段（collectMode/batchFinalized）对
+    // 非 sync 成员恒 no-op（末条 entry collectMode undefined → 无值可补）；result/model
+    // 的修补对 async/chat 成员同样生效——拉齐 light 重建丢 result/model 与 full 重建的
+    // 既有形态不一致（v2 D3 影响面诚实口径），不触碰任何通知文案（golden 不锁 entry 字节）。
+    const rec0 = lastEntry === undefined ? rec : RecordStore.mergeOrphanLastEntry(rec, lastEntry);
+    // [W4 boot 分区 · 裁决表行 3] 重认领保留分支的判据 = resumable 且**无完成产出**：
+    // 非 chatMode 的 resumable=true 且 result 有值是 SP-5 one-shot 完成态（任务已完成，
+    // 直断 closed/gc 无损）；resumable=true 且 result 缺失是「监督器死亡纳管态」（W4：
+    // 引擎死亡接管后宿主重启）——保留 running 交 round-supervisor boot 重认领继续
+    // 管辖（注册存续 process 档），误判 closed 会制造「指向已终态 record 的残留注册」
+    // 并损失 resume 可能。
+    if (rec0.chatMode === true || (rec0.resumable === true && rec0.result === undefined)) {
       // chat 会话跨重启等续聊：保留 running（可续聊），仅落执行态信号。
-      this.reportSubagentRecord({ ...rec, resumable: true });
+      this.reportSubagentRecord({ ...rec0, resumable: true });
       return;
     }
-    const sessionFile = rec.sessionFile;
+    const sessionFile = rec0.sessionFile;
     if (sessionFile === undefined) return; // 无子文件锚（目录扫描源不可达，防御）
     const lastLine = readLastJsonlLine(sessionFile);
     if (!lastLine.ok) {
       // IO 错误可能暂时——判终态不可逆，保守落 resumable 等重开重判。
-      this.reportSubagentRecord({ ...rec, resumable: true });
+      this.reportSubagentRecord({ ...rec0, resumable: true });
       return;
     }
     let parseOk = false;
@@ -688,15 +775,55 @@ export class RecordStore {
     // 真实 reason 同层——否则无 reason sidecar 在磁盘重建时被兜底为 disconnected，
     // 把正常完成的记录误标成断联。
     writeFinalized(sessionFile, "gc");
+    // [F3 boot 直断语义，设计表 3 行 2] 走到本分支的 record 分两类：
+    //  - resumable=true（上方分流保证此时 result 有值）= SP-5 one-shot 完成态——任务
+    //    真实完成，直断 closed/gc 无 error，投影 completed 不变；
+    //  - 其余 = in-flight（重启前在途、无 resumable 信号）——宿主重启中断了在途任务，
+    //    投影不得是 completed（事故环 3：异常中断被谎报完成，违反 G3）。error 载体经
+    //    deriveOutcome("gc", error) = "failed"（execution-record.ts 唯一权威派生）
+    //    投影 failed，文案供 GUI/主 agent 明确「任务因宿主重启中断」；ClosedReason
+    //    枚举不扩展（sidecar/entry 面最小改动，"gc" 由 error 载体补足失败语义）。
+    const inFlightAbortedError =
+      rec0.resumable === true
+        ? undefined
+        : "orphan recovery: task aborted by host restart (in-flight at shutdown; session context lost" +
+          (parseOk ? "" : "; truncated last line") + ")";
     this.reportSubagentRecord({
-      ...rec,
+      ...rec0,
       status: "closed",
       closedReason: "gc",
       endedAt: Date.now(),
-      ...(parseOk ? {} : { error: "orphan recovery: subagent session ended abnormally (truncated last line)" }),
+      ...(inFlightAbortedError !== undefined
+        ? { error: inFlightAbortedError }
+        : parseOk
+          ? {}
+          : { error: "orphan recovery: subagent session ended abnormally (truncated last line)" }),
     });
   }
 
+  /** [v2 D3] 孤儿覆写 merge 字段集：末条 entry 的批域标记 + 轮终正文/模型，仅补 rec 侧
+   *  undefined/空值（model 的空值形态是 ""——light 重建无 model_change entry 时起步
+   *  空串），不覆盖已有值。merge 后写 entry 经 reportSubagentRecord →
+   *  toSubagentRecordEntry 序列化，undefined 字段自然缺省（不引入显式 null）。 */
+  private static mergeOrphanLastEntry(rec: SubagentRecord, last: SubagentRecord): SubagentRecord {
+    const pickStr = (cur: string | undefined, src: string | undefined): string | undefined =>
+      cur !== undefined && cur !== "" ? cur : src;
+    return {
+      ...rec,
+      collectMode: rec.collectMode ?? last.collectMode,
+      batchFinalized: rec.batchFinalized ?? last.batchFinalized,
+      result: pickStr(rec.result, last.result),
+      // 类型收尾：两侧实参恒 string（rec.model 类型非可选；last.model 重建投影自带
+      // `?? ""`），pickStr 签名宽返回 string|undefined —— `?? ""` 运行时不可达，
+      // 仅满足 model 非可选类型，空串回退语义不变（cur 空 → src，src 也空 → ""）。
+      model: pickStr(rec.model, last.model) ?? "",
+      // [W4 boot 分区] 轮终执行态信号（resumable）随末条 entry 保留：子文件侧重建
+      // （reconstructAll）不带该信号，boot 分区的「already-resumable-idle 重认领 vs
+      // in-flight 直断」分流（finalizeOrphanRecord）只能从主 session 末条 entry 取证。
+      resumable: rec.resumable ?? last.resumable,
+    };
+  }
+
   /**
    * [E2E 实测缺口] entry-born 孤儿恢复：register entry 已落主 session、但子 session 文件
    * 从未创建（父进程死在 spawn 窗口期——register 写点与子进程首笔写入之间的窗口；外部
@@ -762,6 +889,32 @@ export class RecordStore {
     });
   }
 
+  /**
+   * [E1/U5] sync 批崩溃恢复扫描：主 session 文件「每 id 末条 subagent-record entry」
+   * （collectLastRecordEntries + rebuildEntryRecord 组合通路，设计 §3.1.3「标记读取
+   * 通路」——batchFinalized 落标 entry 写主 session 文件，本扫描同文件域才可见；禁走
+   * collectRecords light 路径，它只读子文件 identity 头+sidecar，主 session 落标
+   * entry 不可见）。返回每 id 末条重建的完整 record（含 collectMode/batchFinalized /
+   * 终态五字段，损坏 entry 跳过）；调用方（service.recoverSyncCollectBatch 的 E1 过滤、
+   * recoverOrphanRecords 的覆写 merge）自行取舍。主文件不可读（含新 session 未 flush
+   * 的 ENOENT）→ 空数组静默。
+   */
+  scanLastRecordEntries(mainSessionFile: string | undefined): SubagentRecord[] {
+    if (mainSessionFile === undefined) return [];
+    let content: string;
+    try {
+      content = fs.readFileSync(mainSessionFile, "utf-8");
+    } catch {
+      return []; // 与 recoverEntryOnlyOrphans 同判：best-effort 恢复，不可读静默跳过
+    }
+    const out: SubagentRecord[] = [];
+    for (const [id, d] of collectLastRecordEntries(content)) {
+      const rec = rebuildEntryRecord(id, d);
+      if (rec !== null) out.push(rec);
+    }
+    return out;
+  }
+
   /** 订阅变更。返回取消订阅函数。 */
   onChange(listener: ChangeListener): () => void {
     this.listeners.add(listener);
@@ -1320,6 +1473,11 @@ export class RecordStore {
       engineFallback: r.engineFallback,
       // U2：engineHandle 经 entry 持久化（register/archive 双写点均经本投影），无则 undefined 自然省略
       engineHandle: r.engineHandle,
+      // [U5 修复 U2 披露的投影缺口] 同步收集两字段随本投影持久化（register entry /
+      // archive entry 双写点）——原缺失时闭合判定 flushBatch 重建、E1 重建扫描等消费方
+      // 读不到原始值。undefined 经 JSON.stringify 自然缺省，旧 entry 零迁移。
+      collectMode: r.collectMode,
+      batchFinalized: r.batchFinalized,
     };
   }
 }

package/src/execution/relay-env.ts

@@ -1,37 +1,20 @@
-/**
- * subagent relay 通道 env 名与协议常量 SSOT（docs/architecture/subagent-realtime-channel.md §5.1/§5.2/§3.1）。
- *
- * 为什么独立成模块：三方消费同一份常量——extension 侧（pi-invocation 激活判定 /
- * buildChildEnv 归属写入）、runtime 侧（env 注入与镜像校验）、代理脚本 relay.mjs
- * （零依赖脚本不能 import workspace 包，只能内嵌镜像，镜像一致性由 conformance
- * relay 变体断言锁定）。禁各处手写字符串。
- *
- * env 语义：SOCKET/NODE/SCRIPT 三者同时非空 = relay 激活（全有或全无，无中间态）；
- * SESSION_ID/RECORD_ID 是 tee 帧归属键（缺失由代理握手前自检拒绝，退出码 13）。
- */
+// src/execution/relay-env.ts
+//
+// relay 通道 env 名与协议常量的 re-export shim——单源在
+// @zhushanwen/subagent-engine-sdk（round1-reuse R9 跨进程契约副本收编；core → SDK
+// 边界正向合法）。本文件保持路径不变以保住 package.json exports 的 ./relay-env
+// 子入口（semver 面：runtime/extension 消费方 import specifier 不变）。
+// 代理脚本 relay.mjs 仍为内嵌镜像（零依赖脚本不能 import workspace 包），
+// 镜像一致性由 conformance relay 变体断言锁定。
 
-export const RELAY_ENV_SOCKET = 'XYZ_SUBAGENT_RELAY_SOCKET';
-export const RELAY_ENV_NODE = 'XYZ_SUBAGENT_RELAY_NODE';
-export const RELAY_ENV_SCRIPT = 'XYZ_SUBAGENT_RELAY_SCRIPT';
-export const RELAY_ENV_SESSION_ID = 'XYZ_SUBAGENT_RELAY_SESSION_ID';
-export const RELAY_ENV_RECORD_ID = 'XYZ_SUBAGENT_RELAY_RECORD_ID';
-
-/** relay 协议版本（握手帧 v 字段；runtime 与代理同包分发，不匹配=安装损坏）。 */
-export const RELAY_PROTOCOL_VERSION = 1;
-
-/** 代理专用退出码（extension 侧表现为「子进程非零退出」→ engine_run_failed 语义）。 */
-export const RELAY_EXIT_CODES = {
-  /** 握手被拒：协议版本不匹配（安装损坏，重装应用）。 */
-  VERSION_MISMATCH: 10,
-  /** relay socket 不可达（runtime 未运行或已重启）。 */
-  SOCKET_UNREACHABLE: 11,
-  /** socket 中途断开（runtime 崩溃等）——代理生命线断即退。 */
-  SOCKET_CLOSED: 12,
-  /** 归属 env（SESSION_ID/RECORD_ID）缺失——防无归属帧污染广播。 */
-  MISSING_IDENTITY: 13,
-} as const;
-
-/** 激活判定：三 env 同时非空才走 relay，任一缺失回落直连 spawn 真实 pi（TUI/独立 pi 零回归）。 */
-export function isRelayActive(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean {
-  return Boolean(env[RELAY_ENV_SOCKET] && env[RELAY_ENV_NODE] && env[RELAY_ENV_SCRIPT]);
-}
+export {
+  RELAY_ENV_SOCKET,
+  RELAY_ENV_NODE,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_RECORD_ID,
+  RELAY_PROTOCOL_VERSION,
+  RELAY_EXIT_CODES,
+  isRelayActive,
+  readRelayForwardEnv,
+} from "@zhushanwen/subagent-engine-sdk";

package/src/execution/round-supervisor/domain.ts

@@ -0,0 +1,89 @@
+// src/execution/round-supervisor/domain.ts
+//
+// [W4] 轮次活性监督器——域分类与 record 级判据谓词（单一权威源）。
+//
+// 设计权威源：docs/design/chat-domain-v1x-liveness-governance.md §3.2 D2 前置 1
+// （轮次域分类）+ 前置 2（record 去向单一裁决表）+ 三态判定表。
+//
+// 判定域 = run 域一次性任务（resumable 且无进程驱动）+ workflow 域 resumable run。
+// chat/conversation 形态（record.chatMode）**豁免**出 no-progress 判定域：轮终 idle
+// 现状（doFinalizeRoundToIdle + idle timer / idle-gc）+ settled-watchdog 两段守护
+// 管辖——豁免只意味着「监督器不重复管」，不意味着无界（D2 R2 精确化）。
+//
+// 判据状态源钉死为 record 级（R3 核正）：pi 引擎 poolKey 恒 'shared' 单进程、
+// ensureConnected 被动重建会重填「镜像整体置死」——镜像不能作持续判据；run 终态
+// failed 即「驱动死亡」的证据，不随引擎进程重建翻转。镜像置死仅作死亡事件的
+// 触发信号（supervisor 的死亡事件纳管入口），不作持续判据。
+//
+// 纳管模型（R3 显式化）：死亡事件纳管（run failed / 引擎 exited 事件把 record 纳入
+// 监督域），**重建不解管**（引擎进程重建不解除已纳管 record 的监督，监督器按
+// record 级状态持续判定直至终态或放弃）。本文件的谓词全部只读 record 级状态，
+// 不读引擎镜像——结构性保证「重建不解管」（模拟引擎重建后监督器仍按 record 级判）。
+
+import type { ExecutionRecord } from "../types.ts";
+
+/** 监督器域分类（判定域先收窄，再谈三态）。 */
+export type SupervisorDomain =
+  /** run 域一次性任务（非 chatMode record）——监督域主体。 */
+  | "run"
+  /** conversation/chat 形态（record.chatMode）——豁免，现状机制管辖。 */
+  | "conversation";
+
+/**
+ * 域分类（裁决表 conversation 行「任何触发不入监督域」的判定锚）。
+ * record.chatMode === true → conversation（豁免）；否则 → run 域。
+ * （workflow 域 resumable run 的活性收口 = kill-9 恢复链 + idle-gc startedAt 锚
+ * 归档 + sweep 对账——workflow run 不在 RecordStore，其注册对账按 type=workflow
+ * 保守跳过，见 reconcile-sweep.ts。）
+ */
+export function classifySupervisorDomain(record: Pick<ExecutionRecord, "chatMode">): SupervisorDomain {
+  return record.chatMode === true ? "conversation" : "run";
+}
+
+/**
+ * 三态判定「该唤醒」的 record 级判据（设计三态表逐字实现）：
+ * **resumable 未终态 且 无在途 run / 无进程驱动**。
+ *
+ * 入参解耦说明：谓词只消费 record 级状态与两个布尔（在途 run / 活进程句柄），
+ * 由调用方（supervisor）供给——「有在途 run」来自 supervisor 的在途记账
+ * （subagent-service 报告），「有进程驱动」来自生命周期镜像谓词。本函数不读
+ * 镜像/引擎状态，结构性满足「镜像置死只作触发信号不作持续判据」。
+ *
+ * 「已有完成产出」（SP-5 upgrade 等待态）不在本谓词域——由调用方以 hasResult
+ * 单独判定（视图投影面分离，supervisor.evaluate 消费）。
+ */
+export function isAwakeWarrantedShape(
+  record: { status: string; resumable: boolean; chatMode: boolean },
+  hasInFlightRun: boolean,
+  hasLiveProcess: boolean,
+): boolean {
+  if (record.chatMode === true) return false; // conversation 豁免
+  if (record.status !== "running") return false; // 终态 = 已收口
+  if (hasInFlightRun || hasLiveProcess) return false; // 该等（有驱动）→ 不干预
+  return record.resumable === true;
+}
+
+/**
+ * boot 分区「already-resumable-idle」重认领谓词（与裁决表同源——设计 D4 连带面 2
+ * ②「启动扫描 resumable 且无进程驱动且非 conversation 形态」的单一权威实现；
+ * cold-resurrect.ts 的 message 冷查链不承载启动扫描，本谓词即其「cold-resurrect
+ * 扩展」落点，record-store 孤儿恢复的保留分支与 supervisor.bootPartition 共同消费
+ * 同一判据形态）。
+ *
+ * 判据：非 conversation 形态 + status=running + resumable 信号（轮终写点 set true；
+ * 冷路径续轮清除——重启前已在途的 record resumable=undefined，走 boot 直断分支
+ * 而非重认领）+ **无完成产出**（resumable=true 且 result 有值是 SP-5 one-shot
+ * 完成态——任务已完成，直断 closed/gc 无损，不属重认领域；result 缺失才是 W4
+ * 死亡纳管态跨重启的形态）。
+ */
+export function isBootReadoptable(record: {
+  status: string;
+  resumable: boolean;
+  chatMode: boolean;
+  hasResult: boolean;
+}): boolean {
+  if (record.chatMode) return false;
+  if (record.status !== "running") return false;
+  if (!record.resumable) return false;
+  return !record.hasResult;
+}

package/src/execution/round-supervisor/index.ts

@@ -0,0 +1,33 @@
+// src/execution/round-supervisor/index.ts
+//
+// [W4] 轮次活性监督器公共出口（SubagentService 与测试的消费面）。
+
+export {
+  classifySupervisorDomain,
+  isAwakeWarrantedShape,
+  isBootReadoptable,
+  type SupervisorDomain,
+} from "./domain.ts";
+export {
+  classifyReplacement,
+  type ReplacementCandidate,
+  type ReplacementProbeSubject,
+  type ReplacementVerdict,
+} from "./notify-accounting.ts";
+export {
+  runReconcileSweep,
+  type ReconcileSweepDeps,
+  type ReconcileSweepResult,
+  type SupervisedRecordState,
+} from "./reconcile-sweep.ts";
+export {
+  ROUND_SUPERVISOR_WATCHDOG_DEFAULT_MS,
+  ROUND_SUPERVISOR_WATCHDOG_ENV,
+  RoundSupervisor,
+  getSupervisorWatchdogMs,
+  isSupervisorGiveUpDisabled,
+  type GiveUpKind,
+  type RoundSupervisorDeps,
+  type SupervisorCandidateRecord,
+  type SupervisorRecordView,
+} from "./supervisor.ts";

package/src/execution/round-supervisor/notify-accounting.ts

@@ -0,0 +1,87 @@
+// src/execution/round-supervisor/notify-accounting.ts
+//
+// [W4] 通知对账——送决策指引前查替代的两级启发式（纯函数）。
+//
+// 设计权威源：docs/design/chat-domain-v1x-liveness-governance.md §3.2 D2「通知对账」
+// （R3 增补、R4 钉死判定语义）。
+//
+// 背景：主 agent 是唯一决策者，重派不被禁止——即使合并单条通知，它仍可能在收到
+// 指引前合法地重派了新任务。record 数据模型不存在重派关联字段（parentRecordId 是
+// 层级语义、rootSessionId 是 session 隔离语义、task 是完整 prompt 非关联键），
+// 对账判定为显式定义的两级启发式：
+//  - 高置信替代：同 rootSessionId + 同 agent 名 + 同 slug（≤35 字符短标签，重派
+//    同任务大概率同 slug）+ 决策指引看门狗窗内新建 → 撤销指引，改送「原任务已被
+//    新任务替代」终止通知 + 对原 record 走该放弃路径（终态化 + 注销）；
+//  - 低置信（仅 agent 同名）：不撤销指引，但指引内容自带豁免声明（「若你已重新
+//    派发或不再需要此任务，忽略本指引；原任务将在看门狗到期后自动终止」）。
+//
+// 两失败方向登记（设计四要素）：
+//  - 漏判（重派改写 slug/task 致高置信不命中）→ 残余双执行；重审触发 = 实测双执行
+//    反馈 ≥1 例 → 升级「supersedes 显式引用」方案；
+//  - 误判（无关任务撞 slug）→ 原任务被错误终态化——危害轻（原任务本已无进程驱动，
+//    仅损失 resume 可能）。
+
+/** 对账候选（重派承接任务的 record 投影面）。 */
+export interface ReplacementCandidate {
+  id: string;
+  rootSessionId: string | undefined;
+  /** agent 类型名（record.agent）。 */
+  agentName: string;
+  /** 人类短标签（record.slug，≤35 字符）。 */
+  slug: string;
+  /** 创建时刻（record.startedAt，ms）。 */
+  startedAt: number;
+}
+
+/** 被接管 record 的对账基准面。 */
+export interface ReplacementProbeSubject {
+  id: string;
+  rootSessionId: string | undefined;
+  agentName: string;
+  slug: string;
+}
+
+/** 对账结论（两级 + 无命中）。 */
+export type ReplacementVerdict =
+  | { kind: "high-confidence"; replacementId: string }
+  | { kind: "low-confidence" }
+  | { kind: "none" };
+
+/**
+ * 高置信判定窗口：候选的 startedAt 必须落在「决策指引看门狗窗」内（接管时刻起
+ * 算——窗内新建才有「承接了同一任务」的置信；窗外的同名任务与本接管无时序关联）。
+ * 窗值由调用方传（= 监督器决策看门狗窗，同源常量）。
+ */
+export function classifyReplacement(
+  subject: ReplacementProbeSubject,
+  candidates: readonly ReplacementCandidate[],
+  windowMs: number,
+  now: number,
+): ReplacementVerdict {
+  let sameAgentOnly = false;
+  for (const candidate of candidates) {
+    if (candidate.id === subject.id) continue;
+    if (candidate.agentName !== subject.agentName) continue;
+    // 时序窗（高/低置信共同的门）：窗内新建才参与对账——窗外的同名任务与本接管
+    // 无时序关联（预先存在的同名任务不是替代者）。
+    if (now - candidate.startedAt > windowMs) continue;
+    // [契约锚] sameRoot 在生产装配下恒真——此检查是对供给侧不变量的防御性复认，
+    // 不是独立生效的第四要素。生产候选源 = supervisor.deps.listCandidateRecords
+    // （service-binding.ts supervisorCandidates 已按 getSessionRootId() 预过滤，
+    // 循环内候选恒同 root）。约束力悄悄依赖该供给不变量：若换候选源为未按 root
+    // 预过滤的全量集，sameRoot 从恒真退化为真实约束——跨 root 命中会从
+    // high-confidence 降为 low-confidence（替代收口弱化：原任务改由看门狗到期才
+    // 放弃），行为静默漂移。换候选源必须保「root 预过滤」或显式重审本判定语义。
+    const sameRoot =
+      candidate.rootSessionId !== undefined &&
+      candidate.rootSessionId === subject.rootSessionId;
+    const sameSlug =
+      subject.slug !== "" &&
+      candidate.slug === subject.slug;
+    if (sameRoot && sameSlug) {
+      return { kind: "high-confidence", replacementId: candidate.id };
+    }
+    sameAgentOnly = true;
+  }
+  return sameAgentOnly ? { kind: "low-confidence" } : { kind: "none" };
+}