@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/finalize-record.ts

@@ -43,6 +43,16 @@ export interface FinalizeDeps {
   pi: { appendEntry?: (type: string, data: unknown) => void } | null;
   /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
   emitUnregister(id: string, status: string): void;
+  /**
+   * [F-5 修复] record 终态化的宿主侧收口钩子（recordId；best-effort，抛错由调用方
+   * 在闭包内自行兜底）。单一汇聚点：doFinalizeRecord 是全部 closed 终态的必经路径
+   * （finalizeRecord / closeChatIdle / closeAfterRoundSettled / finalizeFailed /
+   * finalizeAborted / consumeCloseAfterRound），chat 轮路由注销（chatRoundRoutes）
+   * 由 SubagentService 经此钩子统一执行——此前仅 cancelBackground 注销，chat record
+   * 经 finalize 链终态化后路由闭包（持 record/stream/守护引用）泄漏。finalizeRoundToIdle
+   * 不经本钩子（回 idle 非终态，续聊仍需路由）。
+   */
+  onFinalized?: (recordId: string) => void;
   /**
    * [T1/PS-9] subagent sessionDir（getSubagentSessionDir(agentDir, rootCwd)，调用方注入）。
    *
@@ -254,8 +264,23 @@ export async function doFinalizeRecord(
   removeAliveMarkerIfPresent(record);
 
   // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  // [W4 发射点枚举归属①] 注销合法发射点枚举（设计 D2）第 ① 处：subagent record
+  // 终态化（finalizeRecord 路径，含监督器放弃）。其余合法发射点：② chatMode 轮末
+  // idle（doFinalizeRoundToIdle，本文件下方）；③ workflow run 终态迁移
+  // （transition("done") 路径）；④ 监督器显式放弃（走本路径，终态化+注销同批）；
+  // ⑤ 注册对账 sweep 补发（round-supervisor/reconcile-sweep.ts）。进程退出本身
+  // 永远不是注销理由（subagent-service disposeAllRecords 的 emit 属①——其同批
+  // completeRecord+archive 终态化）。
   deps.emitUnregister(record.id, status);
 
+  // [F-5 修复] 宿主侧终态收口钩子（chat 轮路由注销的单一汇聚点，见 FinalizeDeps
+  // .onFinalized 注释）。fire-and-forget：钩子失败不阻断 manifest 收尾（闭包内自查）。
+  try {
+    deps.onFinalized?.(record.id);
+  } catch (err) {
+    bestEffort(err, "onFinalized hook (finalizeRecord)");
+  }
+
   // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
   await writeManifestBestEffort(deps, record);
 }

package/src/execution/idle-gc.ts

@@ -2,6 +2,22 @@
  * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
  * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
  * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
+ *
+ * [W4 idle-gc 扩展 · 设计 chat-domain-v1x-liveness-governance D4 连带面 2③]
+ * 注册翻 process 档后的兜底通道扩展（与翻档同批生效，先行期 = 无兜底挂账窗口）：
+ *  1. 锚扩展：无 idleSince 的 resumable record 以 startedAt（创建时确定，
+ *     types.ts ExecutionRecord.startedAt）为锚——兜底定位 30 天量级终态归档，
+ *     创建时锚的精度损失在该量级可接受（同设计对 record startedAt 的 rationale）。
+ *  2. **只归档不补注销**：被归档 record 的注册注销统一交 core 注册对账 sweep
+ *     （判据含「已归档 = 视同终态」）——归档跨 session record 时 appendEntry 只达
+ *     当前 session entries（写达域无效），且 archive 不走 finalizeRecord、无注销
+ *     发射枚举身份（发射点枚举 D2 的 5 处不含 GC）。
+ *  3. WorkflowRun store 同批纳入：running 且 meta.startedAt 超 IDLE_TTL_MS 的 run
+ *     终态化归档（transition("done","time_limited") + save 持久化终态）。时间锚选择
+ *     = WorkflowRunMeta.startedAt（run 创建时刻，ISO string）——run 状态无 idleSince
+ *     等价物，meta.completedAt 仅终态存在，startedAt 是唯一创建时确定的锚（与
+ *     record startedAt 同 rationale）。**只终态化不补注销**同上：run 的注销发射
+ *     身份在 transition("done") 路径（发射点③）与其宿主收口链，GC 不越权补发。
  */
 import { getLogger } from "../core/logger.ts";
 import { getEngineDataDir } from "./engine/common/data-dir.ts";
@@ -16,17 +32,32 @@ const logger = getLogger("subagents");
 /** GC 扫描间隔：1 小时。 */
 // eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
 const GC_INTERVAL_MS = 60 * 60 * 1000;
-/** idle record TTL：30 天（超龄归档）。 */
+/** idle record TTL：30 天（超龄归档）。record 锚窗与 workflow run 锚窗共用。 */
 // eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
 const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 /** 毫秒/天（GC 日志的 d 换算）。 */
 // eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+/**
+ * WorkflowRun GC 窄口（idle-gc 对 WorkflowRun store 的最小依赖面，结构类型——
+ * 调用方传 FileRunStore 实例即可，不 import orchestration 具体类，保持本模块
+ * 可独立编译 + 单测）。loadAll 失败（宿主未 configureCore / IO 错）由实现侧
+ * 或本模块 catch 吞掉，单轮跳过下轮重试。
+ */
+export interface WorkflowRunGcStore {
+  loadAll(): Promise<Array<{ runId: string; state: { status: string }; meta: { startedAt: string }; transition(target: "done", reason?: string): void }>>;
+  save(run: unknown): Promise<void>;
+}
+
 /**
  * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
- * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
- * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ * 每个扫描周期：
+ *  - record 面：对 store 内全部 active record 中 resumable 的，锚点（idleSince
+ *    优先，缺失回退 startedAt——[W4 锚扩展]）超过 IDLE_TTL_MS 的归档。archive
+ *    单条失败不阻断其余（bestEffort 留痕）。**只归档不补注销**（见文件头注）。
+ *  - workflow 面（注入 workflowRuns 时）：running 且 meta.startedAt 超
+ *    IDLE_TTL_MS 的 run 终态化归档（transition + save），单 run 失败不阻断。
  *
  * [D8 池引用计数接线] 归档时同步释放该 record 的引擎池引用（releasePoolRef：
  * journal 跟随 record 删除 + refs 移除 + 归零删池内原生状态）。锚点选在 30 天 TTL
@@ -37,28 +68,72 @@ const MS_PER_DAY = 24 * 60 * 60 * 1000;
  * 不能删——那是 record 主数据死亡（主 session 文件被 pi 侧删除，core 无触发点）才有
  * 的处置，由 cleanupExpiredPoolRefs 的 TTL 兜底覆盖。
  */
-export function startIdleGc(store: RecordStore): () => void {
+export function startIdleGc(store: RecordStore, workflowRuns?: WorkflowRunGcStore): () => void {
   const timer = setInterval(() => {
     const now = Date.now();
     for (const record of store.listAllActive()) {
-      if (isResumable(record) && record.idleSince) {
-        const age = now - record.idleSince;
-        if (age > IDLE_TTL_MS) {
-          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
-          try {
-            store.archive(record);
-          } catch (err) {
-            bestEffort(err, `GC archive record ${record.id}`);
-          }
-          releaseEnginePoolRef(record);
+      if (!isResumable(record)) continue;
+      // [W4 锚扩展] idleSince（轮终写点）优先；缺失（resumable 但无轮终信号的
+      // 存量/异常形态）回退 startedAt（创建时确定）——两锚同为「最晚活性证据」，
+      // 30 天量级下 created 锚的精度损失可接受。
+      const anchorMs = record.idleSince ?? record.startedAt;
+      const age = now - anchorMs;
+      if (age > IDLE_TTL_MS) {
+        logger.warn(
+          `[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`,
+        );
+        try {
+          store.archive(record);
+        } catch (err) {
+          bestEffort(err, `GC archive record ${record.id}`);
         }
+        releaseEnginePoolRef(record);
       }
     }
+    if (workflowRuns !== undefined) {
+      void gcWorkflowRuns(workflowRuns, now);
+    }
   }, GC_INTERVAL_MS);
   timer.unref?.();
   return () => clearInterval(timer);
 }
 
+/**
+ * [W4 WorkflowRun store 纳入] running 且 startedAt 超锚窗的 run 终态化归档。
+ * reason = "time_limited"（超龄归档语义的 DoneReason，对主 agent 的语义是
+ * 「run 因超时被收口」而非 completed）。失败吞错留痕（清理是旁路维护，不能
+ * 拖垮 GC interval；下轮重试）。
+ */
+async function gcWorkflowRuns(workflowRuns: WorkflowRunGcStore, now: number): Promise<void> {
+  let runs: Awaited<ReturnType<WorkflowRunGcStore["loadAll"]>>;
+  try {
+    runs = await workflowRuns.loadAll();
+  } catch (err) {
+    // 宿主未 configureCore（core_host_not_configured）/ IO 失败：本轮跳过，
+    // 下轮重试。debug 留痕——这是「workflow 域未启用」的正常形态，warn 会噪声。
+    logger.debug(`[subagents] GC: workflow run store loadAll failed (skipped this cycle): ${
+      err instanceof Error ? err.message : String(err)
+    }`);
+    return;
+  }
+  for (const run of runs) {
+    if (run.state.status !== "running") continue;
+    const startedMs = Date.parse(run.meta.startedAt);
+    if (!Number.isFinite(startedMs)) continue; // 畸形锚不过判（宁挂账不失明）
+    const age = now - startedMs;
+    if (age <= IDLE_TTL_MS) continue;
+    logger.warn(
+      `[subagents] GC: terminating stale running workflow run ${run.runId} (started ${Math.round(age / MS_PER_DAY)}d ago)`,
+    );
+    try {
+      run.transition("done", "time_limited");
+      await workflowRuns.save(run);
+    } catch (err) {
+      bestEffort(err, `GC terminate workflow run ${run.runId}`);
+    }
+  }
+}
+
 /**
  * 释放 record 的引擎池引用（best-effort）。无 engineHandle（存量 record / 非引擎
  * 路径）时 no-op；engine 缺省投影 'pi'（与读侧存量 entry 零迁移口径一致）。

package/src/execution/lifecycle-manager.ts

@@ -13,7 +13,10 @@
 //      【已接线：session-runner.ts agent_settled arm / subagent-service 新 turn disarm】
 //   2. 全局 ceiling —— 活进程上限，超限时按 LRU 挤出最久空闲（决策 4）【未接线，deferred】
 //   3. shutdown 收割 —— 父进程 shutdown 时显式 SIGTERM 全部 activation（决策 7 防线 i）
-//      【未接线：index.ts reapSpawnedChildrenOnShutdown + killAllSpawnedChildren 已等价覆盖】
+//      【未接线：[F-7 纠偏] 旧注「reapSpawnedChildrenOnShutdown 已等价覆盖」失实——
+//      该 hook 调 killAllSpawnedChildren，后者协议化后仅镜像置死 no-op（见
+//      engine/host/spawned-children.ts 与 src/index.ts 导出注释）；引擎进程实际回收 =
+//      stdin-EOF 自灭链，本职责仍无显式收割接线】
 //   4. 孤儿扫描 —— 父进程启动时按持久化 PID 扫收上次崩溃遗留的孤儿（决策 7 防线 ii）【deferred】
 //   5. activate 互斥 —— 同 recordId 的并发 activate 串行化（决策 7 防线 iii，防双写者）
 //      【已接线：subagent-service.ts 冷路径 resume 前 acquireActivateLock】
@@ -295,12 +298,12 @@ export function getActiveProcessCount(): number {
 // ============================================================
 // 职责 3：shutdown 收割（防线 i）
 //
-// [状态：未接线，已有等价实现] reapAllAliveProcesses 无生产调用方——shutdown 收割
-// 已由 index.ts 的 reapSpawnedChildrenOnShutdown（process hook → killAllSpawnedChildren
-// 发 SIGTERM，覆盖 SIGTERM/SIGINT/beforeExit 挂点）等价覆盖；后者直接遍历
-// spawnedChildren 句柄表，不依赖本模块 activeProcesses 记账的 register 时机，覆盖面
-// 更可靠。本函数保留作跨模块等价实现；若未来接入须先保证 register/unregister 记账
-// 完整，否则收割列表不全。
+// [状态：未接线，无等价实现（[F-7 纠偏]）] reapAllAliveProcesses 无生产调用方。旧注
+// 「shutdown 收割已由 reapSpawnedChildrenOnShutdown 等价覆盖」失实：该 hook 调
+// killAllSpawnedChildren，而后者协议化后（engines/pi inproc 删除、子进程活在引擎
+// 进程内）仅做 core 侧镜像置死，不发任何 SIGTERM（_signal 参数被忽略）——引擎进程
+// 实际回收走 stdin-EOF 自灭链，本职责的显式收割仍无接线。本函数保留作未来接入面；
+// 若未来接入须先保证 register/unregister 记账完整，否则收割列表不全。
 // ============================================================
 
 /**

package/src/execution/lifecycle-predicates.ts

@@ -4,8 +4,8 @@
 //
 // 旧三态（running/idle/cancelled）折为两态（running/closed）后，「对话模式等待续聊」
 //（旧 idle）和「正在执行」都是 status="running"，需派生谓词区分。谓词复用已有
-// lifecycle-manager.hasIdleTimer（idle timer 是否 armed）与 session-runner.getChildByRecord
-//（活进程句柄是否存在），不新增状态记账。
+// lifecycle-manager.hasIdleTimer（idle timer 是否 armed）与 core 侧 spawnedChildren
+// 状态镜像读点（engine/host/spawned-children.ts，活进程句柄是否存在），不新增状态记账。
 //
 // 两种 running 子态（v4 B-1）：
 //   - 等待续聊（旧 idle）：isIdle=true（timer armed）。又分两路：
@@ -20,19 +20,21 @@
 // 故 isIdle 在这两个检查点恒为 true——notify 守卫与 early-return 判据可靠。
 
 import { hasIdleTimer } from "./lifecycle-manager.ts";
-import { getChildByRecord } from "./engine/engines/pi/session-runner.ts";
+// [W6 拆依赖] 活进程句柄读点改经 core 侧 spawnedChildren 状态镜像公共面
+// （engine/host/spawned-children.ts），不再深路径 import inproc pi 引擎目录 内部——
+// 行为不变（镜像 ∪ inproc 权威 map 并读，见该文件头注释的过渡桥语义）。
+import { hasLiveProcessHandleCore } from "./engine/host/spawned-children.ts";
 import type { ExecutionRecord } from "./types.ts";
 
 /**
  * 活进程句柄是否存在（isResumable 子判据）。
  *
- * 复用 session-runner.spawnedChildren 的 getChildByRecord 查询。child 存在且未 kill
- * = 有活进程句柄（正在执行 / Path A 保活）。进程 close 后 spawnedChildren 已 delete，
- * 返回 undefined = 无活进程（Path B / 跨重启）。
+ * [W6] 改读 core 侧状态镜像（engine/host/spawned-children.ts 的 hasLiveProcessHandleCore：
+ * 镜像项存在且未 killed = 有活进程句柄；迁移期内建 pi 的 inproc 权威 map 并读兜底）。
+ * 进程 close / 被杀后镜像项置死或移除 = 无活进程（Path B / 跨重启）。
  */
 export function hasLiveProcessHandle(recordId: string): boolean {
-  const child = getChildByRecord(recordId);
-  return child !== undefined && !child.killed;
+  return hasLiveProcessHandleCore(recordId);
 }
 
 /**

package/src/execution/record-store.ts

@@ -744,7 +744,13 @@ export class RecordStore {
     // 的修补对 async/chat 成员同样生效——拉齐 light 重建丢 result/model 与 full 重建的
     // 既有形态不一致（v2 D3 影响面诚实口径），不触碰任何通知文案（golden 不锁 entry 字节）。
     const rec0 = lastEntry === undefined ? rec : RecordStore.mergeOrphanLastEntry(rec, lastEntry);
-    if (rec0.chatMode === true) {
+    // [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({ ...rec0, resumable: true });
       return;
@@ -769,12 +775,29 @@ 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({
       ...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)" }),
     });
   }
 
@@ -794,6 +817,10 @@ export class RecordStore {
       // `?? ""`），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,
     };
   }
 

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" };
+}