@migor/agentia 0.9.5 → 0.10.1

package/dist/transport/async.js

@@ -10,14 +10,19 @@ import { assertTimerDelay, TimeoutError } from '../core/timeout.js';
 import { zeroClauseOf } from '../core/limits.js';
 import { composeTraceEvents } from '../core/trace.js';
 import { SlotPool } from './slot-pool.js';
-import { approvalExpired, approvalsComplete, fillTimeoutDenials } from './approval-policy.js';
-import { summarizeSuspended, timerDue } from './wake-policy.js';
+import { ApprovalSupervisor } from './approval-supervisor.js';
+import { SignalSupervisor } from './signal-supervisor.js';
+import { ResumeScanner } from './resume-scanner.js';
+import { timerDue } from './wake-policy.js';
 import { DrainGate } from './drain-gate.js';
-import { resumeSkipReason } from './resume-policy.js';
 import { formatOwnerId } from './owner-id.js';
-import { ownerAlive } from './owner-liveness.js';
 import { TaskWaiters } from './task-waiters.js';
 import { TaskEventStreams } from './task-events.js';
+// 三个监督件（2026-09-29 抽出）的实现与类型现在各自在文件里 —— 审批（approval-supervisor.ts）、
+// 事件投递（signal-supervisor.ts）、恢复扫描（resume-scanner.ts）。下面 **re-export** 它们的
+// 对外符号 ⇒ 一切 `from './async.js'` 的既有 import 路径不变。
+export { TaskApproveError } from './approval-supervisor.js';
+export { TaskEventError } from './signal-supervisor.js';
 /**
  * `streamTask` 的失败：带 HTTP 语义的状态码（404 = 任务不存在），HTTP 宿主据此回对应响应。
  * 形状与 `TaskApproveError` 同款（module 级 export，不进公共导出面）。
@@ -44,19 +49,9 @@ function isTerminalTask(rec) {
     return isTerminalStatus(rec.status);
 }
 /**
- * `approve` 的失败：带 HTTP 语义的状态码（404 = 任务不存在，409 = 任务当前不在
- * `suspended` 状态），HTTP 宿主据此回对应响应。
- * module 级 export —— 不进公共导出面（纯宿主内部实现细节）。
+ * `TaskApproveError`（`approve` 的失败，带 HTTP 语义状态码）已随审批监督簇迁到
+ * `approval-supervisor.ts`，本文件顶部 re-export 保持导出面不变（定义与理由见那里）。
  */
-export class TaskApproveError extends Error {
-    /** 400 = 入参语义不合法（decisions 里有本任务待决之外的 id，2026-09-28 深评 P1-2） */
-    status;
-    constructor(status, message) {
-        super(message);
-        this.name = 'TaskApproveError';
-        this.status = status;
-    }
-}
 /**
  * `cancel` 的失败：带 HTTP 语义的状态码（404 = 任务不存在，409 = 已终态 / 在飞 run 不在本进程）。
  * 形状与 `TaskApproveError` 同款（module 级 export，不进公共导出面）。
@@ -69,19 +64,6 @@ export class TaskCancelError extends Error {
         this.status = status;
     }
 }
-/**
- * `signalTask` 的失败：带 HTTP 语义的状态码（404 = 任务不存在，409 = 任务当前不在
- * `suspended` 状态 / 同 eventId 已投递）。形状与 `TaskCancelError` 同款
- * （module 级 export，不进公共导出面）。
- */
-export class TaskEventError extends Error {
-    status;
-    constructor(status, message) {
-        super(message);
-        this.name = 'TaskEventError';
-        this.status = status;
-    }
-}
 /**
  * `submit` 在**排队段已满**时的失败（`AsyncRunnerOptions.maxQueued`，2026-09-28 外部深评 T5）。
  *
@@ -103,30 +85,6 @@ export class TaskQueueFullError extends Error {
         this.name = 'TaskQueueFullError';
     }
 }
-/**
- * `deliveredEventIds` 簿记的条数上限（FIFO 裁最旧）。它是**去重簿记**不是审计日志：
- * 256 条对「webhook 重试窗口」绰绰有余，而无界增长会让每条 TaskRecord 随事件量膨胀
- * （记录随 trace 一起落库，每次 save 全文重写）。「数量有界」不是用户旋钮，不进
- * `core/limits.ts` 的 0 语义表。
- */
-const MAX_DELIVERED_EVENT_IDS = 256;
-/**
- * `pendingEvents`（待注入事件缓冲）的**条数上限**（2026-09-28 复审第三轮，定案 **B**）。
- *
- * 为什么要有：`deliveredEventIds` 那侧是有界的（256），缓冲这侧原先没有 —— 而它不需要攻击者
- * 就能长：投方每次投一条、这条 run 每次都在恢复段**再次挂起**（再挂起出口刻意不注入事件，
- * 见 spec §10 ⑥ 第 4 条）⇒ 每条都留在记录上，而记录随 trace 一起落库、每次 save 全文重写。
- *
- * 为什么是「满了拒绝」而不是「丢最旧」（A 的反面）：缓冲**在下次跑通时就注入并清空**，所以
- * 上限只管「一个挂起窗口里能攒多少」。丢最旧必须**同时**把该 id 从 `deliveredEventIds` 摘掉，
- * 否则发件方重投会拿到「已投递」的 409 而事件其实已经没了 —— 那是最坏的一种谎。宁可不收下
- * 并说出来（调用方拿到 409 就能改主意：先让这条 run 真走起来）。
- *
- * 为什么是 64：一个挂起窗口里等到的输入，量级与 `deliveredEventIds` 的重试窗口（256）同类，
- * 取它的 1/4 —— 容得下真实的 webhook 突发（一次重试窗口里几十条），又不足以把挂起任务当队列灌。
- * **数量有界不是用户旋钮**（与 MAX_DELIVERED_EVENT_IDS 同档），不进 `core/limits.ts` 的 0 语义表。
- */
-const MAX_PENDING_EVENTS = 64;
 /**
  * 取消的**宽限**：取消请求发出后，留给那次 run 自己收尾的时间。
  *
@@ -197,6 +155,21 @@ export class AsyncRunner {
     }
     runTimeoutMs;
     approvalTimeoutMs;
+    /**
+     * 审批监督簇（挂起登记 + 在飞闸 + `approve` + 超时恢复）—— 实现见 approval-supervisor.ts。
+     * 依赖（store / ownerId / approvalTimeoutMs / dispatch 回调）在构造函数末尾注入。
+     */
+    #approvals;
+    /**
+     * 事件投递簇（`signalTask` + 串行闸 + 两个事件容量常量）—— 实现见 signal-supervisor.ts。
+     * 与 `#approvals` 同族（都是「挂起任务的外部唤醒入口」），故紧邻声明。
+     */
+    #signals;
+    /**
+     * 恢复扫描簇（`resumePending` 的四步扫描 + 到期唤醒）—— 实现见 resume-scanner.ts。
+     * 依赖 `#approvals`（读数重建 / 催超时）与 drain 读数（唤醒闸），构造时排在它之后。
+     */
+    #scanner;
     /** 并发槽位池（见 slot-pool.ts）：本类不再自管 running/waitQueue */
     #slots;
     /** 已受理但未达终态的任务数（queued + running）—— /healthz 与 drain 共用 */
@@ -294,6 +267,32 @@ export class AsyncRunner {
             throw new Error(`approvalTimeoutMs 必须为 ≥ 0 的有限数（${zeroClauseOf('AsyncRunner.approvalTimeoutMs')}），收到 ${opts.approvalTimeoutMs}`);
         }
         this.ownerId = formatOwnerId(process.pid, this.#host, randomUUID().slice(0, 8));
+        // 审批监督簇在 ownerId 就位后构造（它要用 store 与 ownerId）。`dispatch` 用**回调**
+        // 注入而不是 import：派发入口 `#dispatch` 仍归本类（停机闸 + 唯一派发点 + 一次性告警），
+        // 依赖保持单向（审批 → 派发），也避免两个模块互相 import。
+        this.#approvals = new ApprovalSupervisor({
+            store: this.store,
+            ownerId: this.ownerId,
+            approvalTimeoutMs: this.approvalTimeoutMs,
+            dispatch: (rec) => this.#dispatch(rec),
+        });
+        // 事件投递与恢复扫描同样在 ownerId 就位后构造。两处**回调注入**的理由与 `#approvals` 一致：
+        // `#dispatch`（停机闸 + 唯一派发点 + 一次性告警）与 drain 读数都归本类，两个监督件只**消费**它们
+        // ⇒ 依赖保持单向（监督件 → 派发），也避免三个模块互相 import。
+        this.#signals = new SignalSupervisor({
+            store: this.store,
+            ownerId: this.ownerId,
+            approvals: this.#approvals,
+            dispatch: (rec) => this.#dispatch(rec),
+        });
+        this.#scanner = new ResumeScanner({
+            store: this.store,
+            ownerId: this.ownerId,
+            host: this.#host,
+            approvals: this.#approvals,
+            dispatch: (rec) => this.#dispatch(rec),
+            isDraining: () => this.#drain.isDraining,
+        });
     }
     /**
      * 提交一次异步任务。入参可为 string / messages / {prompt|text|messages}。
@@ -537,7 +536,7 @@ export class AsyncRunner {
         rec.suspendedSince = undefined;
         rec.suspendedReason = undefined;
         rec.wakeAt = undefined;
-        this.#unmarkSuspended(taskId);
+        this.#approvals.unmarkSuspended(taskId);
         const saved = this.#safeSave(rec, 'outcome');
         this.#cancels.delete(taskId);
         if (wasQueued)
@@ -588,178 +587,24 @@ export class AsyncRunner {
     /**
      * 审批一个处于 `suspended` 的任务（HITL）。
      *
-     * - **逐 tool_use_id 幂等**：已存在的决定不覆盖（第一次决定赢）—— 重复提交 /
-     *   并发点击不会推翻已有决定，也不会让恢复段重复执行；
-     * - **并发重入共享在飞那次**：同一任务的并发 approve（双击「批准」/两个审批人
-     *   同时批）返回同一个 Promise —— 否则两个调用都在对方落库前读到
-     *   `suspended`、各自判「决定齐了」、**各派发一次**（同一任务重复执行，
-     *   与 resumePending 的闸门同一 bug 类）。被共享的那次覆盖不到的决定不丢：
-     *   调用方从返回的记录看到任务仍在等待，重试即并入；
-     * - 决定齐了就恢复：`status` 回 `running`、**先落库再派发**（与 `#redispatch`
-     *   同一条纪律 —— 没落库就恢复，进程崩在窗口里会丢决定）；恢复段带着
-     *   `rec.approvals` 与扩展后的消息历史（`rec.spec.messages`，末尾是含未决
-     *   tool_use 的那条 assistant 消息）重进引擎循环；
-     * - 决定**没**齐：只把本批决定落库，任务继续等（可能多轮审批）；
-     * - 返回当前 TaskRecord（快照）。任务不存在抛 404 语义、状态不对抛 409 语义
-     *   的 `TaskApproveError`。
+     * 实现已外移到 `approval-supervisor.ts`（**逐字搬迁**，含四条语义与它们的理由：
+     * 逐 tool_use_id 幂等 / 并发重入共享在飞那次 / 决定齐了先落库再派发 / 状态不对抛
+     * `TaskApproveError`）。这里只留薄壳 —— `approve` 是 `AsyncRunner` 的公开 API，
+     * 签名与返回类型不变。
      */
     async approve(taskId, decisions, opts = {}) {
-        const inflight = this.inflightApprovals.get(taskId);
-        if (inflight)
-            return inflight;
-        const run = this.#approveInner(taskId, decisions, opts).finally(() => {
-            this.inflightApprovals.delete(taskId);
-        });
-        this.inflightApprovals.set(taskId, run);
-        return run;
-    }
-    /** 同一任务的在飞审批（approve 的重入闸，见上）。**与惰性超时恢复共用同一把闸** ——
-     *  approve 与 #expireAndResume 都会「填决定 + 落库 + 派发」，不互斥就是同一任务跑两遍。 */
-    inflightApprovals = new Map();
-    async #approveInner(taskId, decisions, opts) {
-        const rec = await this.store.get(taskId);
-        if (!rec)
-            throw new TaskApproveError(404, `task 不存在: ${taskId}`);
-        if (rec.status !== 'suspended' || rec.suspendedReason !== 'approval') {
-            throw new TaskApproveError(409, rec.status === 'suspended'
-                ? `task ${taskId} 的挂起原因是 ${rec.suspendedReason ?? '未知'}，只有等人工审批的挂起能审批`
-                : `task ${taskId} 当前状态为 ${rec.status}，只有挂起在等审批的任务才能审批`);
-        }
-        const now = Date.now();
-        // 入参校验（2026-09-28 外部深评 P1-2）：本批只许批**本任务待决的** id。
-        // 不校验会怎样（实证：一次 approve 塞 5000 个无关键 ⇒ 记录从 246 字节撑到 419 KB）：
-        // 多出来的键照样写进 `rec.approvals`、随每次 save 全文重写落库、并随任务**永久保留**
-        // （终态也不清：审批记录是审计的一部分）⇒ 一个**认证调用方**单次请求就能把记录撑大，
-        // 反复调用可无限叠加。拒整批而不是挑着收：与 `parseApproveBody`（形状全有或全无）、
-        // `parseEventBody`（多一个字段即拒）同一条纪律 —— 调用方本来就该从记录的 `pendingApprovals`
-        // 里读要批哪些 id。
-        // ⚠️ 为什么**不需要**再给 `rec.approvals` 加常量上限：单次 approve 能新写的键 ⊆ 当前
-        // `pendingApprovals`（挂起那一刻固定）。跨多轮挂起它会累计**历次**待决的并集
-        // （决定是审计，终态也保留），但每一轮都对应真跑出来的模型回合与 tool_use ——
-        // 调用方的单次输入无法放大体积，增长只能随真实运行发生。再加常量上限是一段
-        // 永远触发不到的死代码（那不是护栏，是噪音）。
-        const pendingIds = new Set(rec.pendingApprovals ?? []);
-        const unknownIds = Object.keys(decisions).filter((id) => !pendingIds.has(id));
-        if (unknownIds.length > 0) {
-            throw new TaskApproveError(400, `decisions 里有 ${unknownIds.length} 个 id 不在本任务的待决列表里（如 ${unknownIds[0]}）—— 整批拒掉，记录不动`);
-        }
-        rec.approvals ??= {};
-        for (const [id, d] of Object.entries(decisions)) {
-            if (rec.approvals[id])
-                continue; // 逐 id 幂等：第一次决定赢
-            rec.approvals[id] = {
-                approved: d.approved,
-                ...(d.reason !== undefined ? { reason: d.reason } : {}),
-                ...(opts.decidedBy !== undefined ? { decidedBy: opts.decidedBy } : {}),
-                decidedAt: now,
-                ...(rec.suspendedSince !== undefined ? { requestedAt: rec.suspendedSince } : {}),
-            };
-        }
-        // 惰性审批超时：人的决定先并入（先到先赢），仍空着的待决项由超时兜底成 deny
-        if (approvalExpired(rec, now, this.approvalTimeoutMs))
-            fillTimeoutDenials(rec, now);
-        const complete = approvalsComplete(rec);
-        if (complete) {
-            rec.status = 'running'; // 由 #executeInner 接管（acquireSlot → 恢复执行）
-            rec.ownerId = this.ownerId;
-        }
-        // 先落库再派发 —— **真纪律，不是注释**：save 失败（同步抛 / 异步 reject）就
-        // 绝不恢复执行（落不了库的决定不算决定：进程崩在窗口里会丢决定，重启后把
-        // 同一件事再判一次、可能改判）。调用方拿到 reject，重试即可。
-        await this.store.save(rec);
-        if (complete) {
-            // 离开挂起态（读数纪律②）：决定齐了这就是「醒来」那一刻
-            this.#unmarkSuspended(taskId);
-            // 派发走**唯一入口**（闸在 #dispatch 里判一次 —— 2026-09-28 外部深评 P1-1 的结构性修法）：
-            // 决定已经在记录里，停机窗口里放行的是「重新排期」（下次启动认领），不是「吞掉」。
-            this.#dispatch(rec);
-        }
-        return { ...rec };
+        return this.#approvals.approve(taskId, decisions, opts);
     }
     /**
-     * 投递一个事件给**挂起**的任务（2026-09-28 ⑥，run 事件投入口；
-     * `POST /tasks/:id/events` 的宿主方法侧，与 approve/cancel 对称）。
-     *
-     * 语义（设计稿 §3 逐条的落点）：
-     * - **只对 `suspended` 生效**：不存在 ⇒ 404；其余状态（含已终态）⇒ 409
-     *   （「不唤醒已终态」是这条状态闸的推论，与 approve 同款「状态不对要说出来」）；
-     * - **幂等**：`eventId` 给定时按 `rec.deliveredEventIds` 去重，重复 ⇒ 409
-     *   （簿记随记录落库，重启不丢；有界 FIFO，见 MAX_DELIVERED_EVENT_IDS）。
-     *   不给 `eventId` 就**没有恰好一次**：重复投递 = 重复进历史（如实，不假装）；
-     * - **投完即续跑**（两种挂起原因都算 —— 对 timer 挂起这就是「提前醒」）：
-     *   事件进 `rec.pendingEvents`、状态回 `running`，**先落库再派发**
-     *   （与 approve / #wakeDueInner 同一条纪律：崩在窗口里不能丢事件）。
-     *   事件**不**直接追加进 `rec.spec.messages` —— 续跑判定只认历史末尾一条
-     *   （`tailToolUses`），追加 user 消息会把续跑判成新对话；注入由引擎在
-     *   未决 tool_use 解决之后做（见 engine/loop.ts 的 deliverTaskEvents）；
-     * - **不沿旧 wakeAt**：记录上的旧目标时刻不动（闸都 gate 在 suspended 上，
-     *   状态一翻它就失效）；醒来重跑那一批时工具若再次 `deferUntil`，
-     *   `wakeAt` 由新回合重新落定；
-     * - drain 期间**仍允许**（与 approve 同理由：挂起的任务只有外部输入能推进）。
+     * 投递一个事件给**挂起**的任务（HITL 与 durable timer 两种挂起都适用）。
      *
-     * 并发闸与 approve **不同款**：approve 共享在飞那次（决定是幂等合并），事件**串行成链**
-     * （两条并发事件是两条不同的输入，共享 = 静默丢一条）。与其它恢复路径
-     * （approve / 到期唤醒，各有自己的闸）的竞速：进闸后重读再判挡住绝大多数；
-     * 剩下的窄窗口与既有「approve × wakeDue 分闸」同类（那两条按挂起原因天然互斥，
-     * 事件两种原因都适用，是这个闸新盖的缝 —— 已记在 spec §10 2026-09-28 ⑥）。
+     * 实现已外移到 `signal-supervisor.ts`（**逐字搬迁**，含完整语义清单与并发闸的理由：
+     * 只对 `suspended` 生效 / 按 `eventId` 幂等 / 缓冲满了拒收并说出来 / 投完即续跑且
+     * **先落库再派发** / 并发时**串行成链**而不是像 approve 那样共享在飞那次）。
+     * 这里只留薄壳 —— `signalTask` 是 `AsyncRunner` 的公开 API，签名与返回类型不变。
      */
     signalTask(taskId, event) {
-        // 串行化（**不是** approve 那种「共享在飞那次」）：两个并发事件是**两条不同的输入**，
-        // 共享在飞那次 = 后一条被静默丢掉；各自读-改-写而不互斥 = 双派发（与 resumePending
-        // 的重入闸同一个 bug 类）。排成链：前一次落库完，这一次进闸后重读再判
-        // （那时若已派发则状态是 running ⇒ 409 如实说出来，调用方可重试）。
-        const prev = this.inflightSignals.get(taskId);
-        const run = Promise.resolve(prev)
-            .catch(() => undefined) // 前一次的 reject 已由它自己的调用方接走，这里只排队
-            .then(() => this.#signalInner(taskId, event))
-            .finally(() => {
-            // 只摘自己：链上可能已有更新的节点（无条件 delete 会摘掉别人的）
-            if (this.inflightSignals.get(taskId) === run)
-                this.inflightSignals.delete(taskId);
-        });
-        this.inflightSignals.set(taskId, run);
-        return run;
-    }
-    /** 同一任务的在飞事件投递（signalTask 的重入闸，见上） */
-    inflightSignals = new Map();
-    async #signalInner(taskId, event) {
-        const rec = await this.store.get(taskId);
-        if (!rec)
-            throw new TaskEventError(404, `task 不存在: ${taskId}`);
-        if (rec.status !== 'suspended') {
-            throw new TaskEventError(409, `task ${taskId} 当前状态为 ${rec.status}，只有挂起的任务能接收事件`);
-        }
-        // 幂等去重（先判再改）：重复 ⇒ 409，记录一个字节不动（与 cancel 的「已终态」同款）
-        if (event.eventId !== undefined && rec.deliveredEventIds?.includes(event.eventId)) {
-            throw new TaskEventError(409, `事件 ${event.eventId} 已投递给 task ${taskId}（重复投递）`);
-        }
-        // 缓冲上限（2026-09-28 复审第三轮，定案 B：满了**说出来**，不静默丢）。
-        // 判据次序 状态 ⇒ 幂等 ⇒ 容量：重复投递的那条本来就在缓冲里，报「重复投递」比报「满了」有用;
-        // 两种 409 的**区别必须让调用方看得见** —— 重复投递是「已经在里面了」，满了是「没收下」。
-        if ((rec.pendingEvents?.length ?? 0) >= MAX_PENDING_EVENTS) {
-            throw new TaskEventError(409, `task ${taskId} 的待注入事件已达上限（${MAX_PENDING_EVENTS} 条）—— ${rec.suspendedReason === 'approval'
-                ? '这条在等人工审批，而让它跑起来的唯一触发源是 approve（不在投递方手里）⇒ 要么等人批，要么 cancel 后重新提交'
-                : '这条在等定时到点（approve 对它不适用）—— 到点它会自己醒来，缓冲里的事件在醒来那段注入；等不了就 cancel 后重新提交'}；本次事件**没有**被记录。`);
-        }
-        rec.pendingEvents = [...(rec.pendingEvents ?? []), event];
-        if (event.eventId !== undefined) {
-            const ids = [...(rec.deliveredEventIds ?? []), event.eventId];
-            rec.deliveredEventIds =
-                ids.length > MAX_DELIVERED_EVENT_IDS
-                    ? ids.slice(ids.length - MAX_DELIVERED_EVENT_IDS)
-                    : ids;
-        }
-        rec.status = 'running'; // 由 #executeInner 接管（acquireSlot → 恢复执行）
-        rec.ownerId = this.ownerId;
-        // 先落库再派发 —— 与 #approveInner 同一条真纪律：save 失败就绝不恢复执行
-        // （落不了库的事件不算投递：崩在窗口里会丢事件）。调用方拿到 reject，重试即可。
-        await this.store.save(rec);
-        // 离开挂起态（读数纪律②）：事件到了这就是「醒来」那一刻 —— 与 approve 的决定齐了同形
-        this.#unmarkSuspended(taskId);
-        // 派发走唯一入口（闸在 #dispatch 里）：停机窗口里不派发，事件留在 pendingEvents 上，
-        // 下次启动的 resumePending 认领时注入。
-        this.#dispatch(rec);
-        return { ...rec };
+        return this.#signals.signalTask(taskId, event);
     }
     /** 已受理但未达终态的任务数（queued + running）—— 健康检查与 drain 共用同一口径 */
     get inFlight() {
@@ -768,33 +613,11 @@ export class AsyncRunner {
     /**
      * **本进程可见的挂起读数**（`/healthz` 的 `suspended` 段，配套 6）。
      *
-     * 口径与 `inFlight` 同一张表：只数**本进程**经手的挂起 —— 跨进程要合并看板请自己聚合，
-     * 不假装是全局面（别的进程挂起的记录这里看不见，重启后由首次扫描对齐，见下）。
-     *
-     * 三条维护纪律（这条读数的唯一风险是**漂移**，所以每条出口都要写清）：
-     * ① 进挂起时登记（`#executeInner` 的挂起分支，与落库同一个分支）；
-     * ② 离开挂起时除名（`approve` / 两条恢复路径 / 终态分支）；
-     * ③ **每次 `resumePending` 扫描按 store 重建** —— 扫描本来就 `list()` 了全表，
-     *    顺手对齐即可，把「漏了某个出口」从永久漂移降级成「下一次扫描前的偏差」。
-     *
-     * 为什么不留成 store 查询（每次 /healthz 扫全表）：`/healthz` 是探针端点（秒级频率），
-     * 而 `list()` 要把**每条记录的完整 trace**取出来（sqlite/redis 下是全部反序列化）——
-     * 拿它当健康检查的代价比它回答的问题大得多。
+     * 口径与三条维护纪律（挂起时登记 / 离开时除名 / 每次扫描按 store 重建）已随审批监督簇
+     * 迁到 `approval-supervisor.ts` 的 `#suspended`（那张注释就写在那里）；这里只留对外 getter。
      */
-    #suspended = new Map();
-    /** 挂起读数：按原因分组的条数 + 最早的目标时刻（无时间挂起时为 `null`） */
     get suspendedSummary() {
-        return summarizeSuspended(this.#suspended.values());
-    }
-    /** 登记一条挂起（纪律①）。原因缺失的记录不进表 —— 分不了组，宁可少数也不猜一个原因出来 */
-    #markSuspended(rec) {
-        if (rec.status !== 'suspended' || rec.suspendedReason === undefined)
-            return;
-        this.#suspended.set(rec.taskId, { reason: rec.suspendedReason, wakeAt: rec.wakeAt });
-    }
-    /** 除名（纪律②）：任务离开挂起态时调用（恢复、终态都算） */
-    #unmarkSuspended(taskId) {
-        this.#suspended.delete(taskId);
+        return this.#approvals.summary;
     }
     /** 是否已进入优雅停机（drain 之后为 true）—— HTTP 宿主据此对新单回 503 */
     get isDraining() {
@@ -823,89 +646,26 @@ export class AsyncRunner {
         // 实现已外移到 drain-gate.ts（写前保留的契约注释仍在本方法上）
         return this.#drain.waitForIdle(() => this.active === 0, opts.timeoutMs ?? 0);
     }
-    /**
-     * 审批超时的**判定**已外移到 approval-policy.ts（`approvalExpired` / `fillTimeoutDenials` /
-     * `approvalsComplete`）—— 下面是**编排**：进在飞闸、重读一遍、先落库再派发。
-     */
-    /**
-     * 惰性超时扫描（HITL）：读到一个已超时的 awaiting 任务 ⇒ 自动全拒 + 落库 + 重派。
-     * 与 #redispatch 同一条纪律：**先落库再派发**（没落库就恢复，进程崩在窗口里会
-     * 丢掉超时决定、把同一件事再判一次）。
-     *
-     * 重入闸（2026-09-20，见 spec §10 当日条）：与 `approve` **共用同一把** per-taskId
-     * 闸（inflightApprovals）。异步 store 的 `get` 返回**新副本**且有网络往返 —— 两个
-     * 并发 poll（或 poll 与 approve）各自看到 awaiting 快照 ⇒ 双双填超时拒绝 + 双双
-     * `#execute`（同一任务跑两遍）。在飞即跳过：另一路径自己会兜底（#approveInner
-     * 里也有 approvalExpired 判定，见 approval-policy.ts），决定逐 id 幂等（第一次决定赢）。
-     * 反之 approve 撞上在飞的超时恢复时共享其结果 —— 与人的决定竞速，先到先得。
-     */
-    #expireAndResume(rec, now) {
-        if (this.inflightApprovals.has(rec.taskId))
-            return;
-        const run = this.#expireAndResumeInner(rec, now).finally(() => {
-            this.inflightApprovals.delete(rec.taskId);
-        });
-        this.inflightApprovals.set(rec.taskId, run);
-        // poll / resumePending 路径没有调用方接 reject —— 订阅掉，不得逃逸成 unhandled rejection
-        run.catch(() => undefined);
-    }
-    async #expireAndResumeInner(rec, now) {
-        // 进闸后**重读一遍**再判：闸只互斥「进入」，挡不住「进闸前已取到的旧副本」——
-        // 本记录的快照可能是在另一次恢复落库**之前**取的（异步 store 的 get 有往返），
-        // 凭陈旧快照放行会把同一任务再派发一次。
-        const fresh = await this.store.get(rec.taskId);
-        const target = fresh ?? rec;
-        if (target.status !== 'suspended' || !approvalExpired(target, now, this.approvalTimeoutMs)) {
-            return target;
-        }
-        fillTimeoutDenials(target, now);
-        target.status = 'running';
-        target.ownerId = this.ownerId;
-        let saved;
-        try {
-            saved = this.store.save(target);
-        }
-        catch {
-            return target; // 同步落库失败则不派发（与下一条异步分支同纪律：先落库再派发）
-        }
-        if (isThenable(saved)) {
-            // 落库失败则不派发（认领没落地就派发 = 重新打开重复执行窗口）
-            try {
-                await saved;
-            }
-            catch {
-                return target;
-            }
-        }
-        // 离开挂起态（读数纪律②）—— 落在**落库成功之后**：落不了库就不算恢复（没派发，读数也不动）
-        this.#unmarkSuspended(target.taskId);
-        // 派发走唯一入口（闸在 #dispatch 里）。⚠️ **这一条正是外部深评抓到的第四条路径**：
-        // `#expireAndResume`（审批超时自动全拒并恢复）与 `approve` 不同触发源、同一形状，
-        // 由 `poll()` 的惰性闸驱动 —— 而「停机中照常可轮询」是 HTTP 宿主的明确承诺
-        // （LB / K8s preStop / 前端轮询）⇒ 停机后照样能起新 run。
-        this.#dispatch(target);
-        return target;
-    }
     /**
      * poll 的读路径钩子：两条**惰性**的挂起闸各判一次（都不起定时器 —— 没人读的挂起不会自己动，
      * 与审批超时同一条纪律；崩溃/重启也不依赖任何在飞回调）。
      *
-     * 写成 `else if` 而不是两个独立的 `if`：两条闸的原因判据本来就互斥（`approval` / `timer`），
-     * 排他在这里是**写出来的**而不是「两个函数各自恰好正确」—— C 之前正是「一个状态兼职两件事」
-     * 让审批那条闸去叫醒了等时刻的 run。
+     * 审批那一半已外移到 `#approvals.expireIfExpired`（判据与副作用逐字等价，见
+     * approval-supervisor.ts）；这里保留「命中审批就返回、不再判 timer」的形状 ——
+     * 两条闸的原因判据本来就互斥（`approval` / `timer`，`approvalExpired` 内部也卡原因），
+     * 排他在这里是**写出来的**而不是「两个函数各自恰好正确」—— C 之前正是「一个状态
+     * 兼职两件事」让审批那条闸去叫醒了等时刻的 run。
      */
     #lazyGates(rec) {
         if (!rec)
             return rec;
         const now = Date.now();
-        if (approvalExpired(rec, now, this.approvalTimeoutMs))
-            this.#expireAndResume(rec, now);
-        else if (timerDue(rec, now))
-            this.#wakeDue(rec, now);
+        if (this.#approvals.expireIfExpired(rec, now))
+            return rec;
+        if (timerDue(rec, now))
+            this.#scanner.wakeDue(rec, now);
         return rec;
     }
-    /** 在飞的到期唤醒（同一任务的重入闸，理由与 inflightApprovals 同款：两条路径都「落库 + 派发」）。 */
-    inflightWakes = new Map();
     /**
      * 取消的**意图**（2026-09-28 ④）。落库状态按意图判、不从 signal 反推 ——
      * 同一条 signal 有三个来源（调用方传入 / `runTimeoutMs` / 取消），反推不出「谁按的」。
@@ -920,65 +680,6 @@ export class AsyncRunner {
      * finally 就只做它自己那份（在飞递减、通知等待者、排空通知）。
      */
     #cancelSettled = new Set();
-    /**
-     * 到期唤醒（durable timer）：读到一条**在睡且到点**的挂起 ⇒ 认领 + 重派，醒来后重跑那一批。
-     *
-     * 与 `#expireAndResume` 逐条同形（进在飞闸、重读一遍、先落库再派发），理由一字不差；
-     * 三处不同，都写在下面：drain 之后不唤（配套 5）、不填任何决定（时间挂起没有待决项）、
-     * 以及**返回值**（见下）。
-     *
-     * @returns 是否真的接管了这次唤醒 —— decline 时 `false`。`resumePending` 的返回值是
-     * 「我推进了几条」，把没推进的算进去就是谎报（drain 之后每次扫描都报「唤醒了 N 条」，
-     * 而它们一条都没动）。⚠️ 审批那条（`#expireAndResume`）的计数口径略宽（在飞也计入），
-     * 那是既有行为、本批不动它。
-     */
-    #wakeDue(rec, now) {
-        // 配套 5（drain 后不唤醒）：停机是「不再往前推」，与 submit 在 drain 后回 503 同一条纪律。
-        // 不设这道闸，一条天级的 sleeping run 会在停机窗口里被叫起来接着跑 —— 部署卡在它身上。
-        // （重启后由新进程的首次 resumePending 唤醒：那时停机窗口早过去了。）
-        if (this.#drain.isDraining)
-            return false;
-        if (this.inflightWakes.has(rec.taskId))
-            return false;
-        const run = this.#wakeDueInner(rec, now).finally(() => {
-            this.inflightWakes.delete(rec.taskId);
-        });
-        this.inflightWakes.set(rec.taskId, run);
-        // poll / resumePending 路径没有调用方接 reject —— 订阅掉，不得逃逸成 unhandled rejection
-        run.catch(() => undefined);
-        return true;
-    }
-    async #wakeDueInner(rec, now) {
-        // 进闸后**重读一遍**再判（与 #expireAndResumeInner 同因）：闸只互斥「进入」，
-        // 挡不住「进闸前已取到的旧副本」——异步 store 的 get 有往返，凭陈旧快照放行会重复派发。
-        const fresh = await this.store.get(rec.taskId);
-        const target = fresh ?? rec;
-        if (!timerDue(target, now))
-            return target;
-        target.status = 'running';
-        target.ownerId = this.ownerId;
-        let saved;
-        try {
-            saved = this.store.save(target);
-        }
-        catch {
-            return target; // 同步落库失败则不派发（先落库再派发，见 #expireAndResumeInner）
-        }
-        if (isThenable(saved)) {
-            try {
-                await saved;
-            }
-            catch {
-                return target;
-            }
-        }
-        // 离开挂起态（读数纪律②）—— 落库成功之后才算醒来
-        this.#unmarkSuspended(target.taskId);
-        // 派发走唯一入口（闸在 #dispatch 里判一次 —— 它同时盖住「进入时」与「窗口里刚进入停机」
-        // 两个时点，这里不必再判一遍）。
-        this.#dispatch(target);
-        return target;
-    }
     /**
      * **唯一的派发口**（2026-09-28 外部深评 P1-1 / P2-1 的结构性修法）。
      *
@@ -1063,145 +764,16 @@ export class AsyncRunner {
      * （running 视为进程中断）。返回重派数量（异步 store 下返回 Promise<number>）。
      * 幂等键去重照常生效。
      *
-     * `suspended`（HITL）**不捡**：它在等人、不是孤儿（进程没死也可能挂着）。
-     * 但读到它会做**惰性判定**，两条闸各管各的原因：
-     * - `approval`：配了 `approvalTimeoutMs` 且已超时的挂起任务自动全拒
-     *   （`denied, reason: '审批超时'`）并重派；
-     * - `timer`：`wakeAt` 已到的睡着的任务**唤醒并重派**（醒来重跑那一批）。
-     *   ⚠️ `drain()` 之后不唤醒（配套 5）：停机窗口里天级的 run 被叫起来接着跑 = 部署卡死。
+     * 实现在 `resume-scanner.ts`（**逐字搬迁**，含那四步扫描的**顺序**与各自理由、重入闸、
+     * 到期索引接线、多进程 `ownerId` 的判定分级）。这里只留薄壳 —— `resumePending` 是
+     * `AsyncRunner` 的公开 API，签名与返回类型不变。
      *
-     * **认领先落库、再派发**（见 `#redispatch`）；异步 store 的认领落库失败会让本方法
-     * reject —— 宁可让调用方看见「续跑没做」，也不要静默放出一批会被重复执行的任务。
-     *
-     * 多进程共用一个 store 时靠 `ownerId` 区分他我：
-     * - 本进程的记录一律跳过（它还在本进程内存里跑，重派 = 跑两遍）；
-     * - `staleAfterMs > 0` 时启动他进程判定：**同主机就问 pid 还在不在**（在的不抢、
-     *   不在的立刻抢），问不到（异主机 / 旧格式 ownerId）才退回保鲜期启发式。
-     *   缺省 0 = 不判断、一律重派（单进程旧语义）。判定分级与边界见 `resume-policy.ts`。
+     * 一句话提要（细节见实现）：`suspended` **不捡**（它在等人、不是孤儿），但读到它会做
+     * 惰性判定 —— 审批超时自动全拒并重派、`wakeAt` 已到的唤醒并重派（`drain()` 之后不唤，
+     * 配套 5）；认领**先落库再派发**；多进程靠 `ownerId` 区分他我（`staleAfterMs > 0` 时问 pid）。
      */
     resumePending(opts = {}) {
-        // 重入闸：**并发**调用共享同一次扫描的结果，而不是各自再扫一遍。
-        //
-        // 为什么必须（2026-09-18 补）：「先落库再派发」只堵住了**串行**重扫 —— 认领是异步的
-        // （异步 store 的 `list()` 返回反序列化的**新对象**），两个并发调用都在任一 `save`
-        // 落地前 `list()` 到旧快照，`ownerId === this.ownerId` 的过滤对两份旧快照**双双失效**
-        // ⇒ 同一个任务被派发两次（`app.run` 重复执行，副作用与花费翻倍）。
-        //
-        // 语义：闸门期间返回**在飞那次的 Promise**（同一个数），而不是 0 —— 0 会谎称
-        // 「没派发任何东西」，而实际上派发了。调用方拿到的始终是本次扫描的真实结果。
-        if (this.inflightResume)
-            return this.inflightResume;
-        const listed = this.store.list();
-        const staleAfterMs = opts.staleAfterMs ?? 0;
-        // 到期索引（2026-09-28 ⑤ 落地）：store 实现了 `listDue` 时，「到期唤醒」那一半的
-        // 输入走索引（只回到期的记录），否则回退全表过滤 —— 语义不变，只是扫描规模不同。
-        // ⚠️ 它**只**替代那一半的输入：挂起读数重建 / 审批超时 / 孤儿认领的职责
-        // 仍是全表 `list()`（它们要的不只是「到期的」），别把整个扫描的输入源换掉。
-        const dueListed = this.store.listDue === undefined ? undefined : this.store.listDue(Date.now());
-        if (isThenable(listed) || (dueListed !== undefined && isThenable(dueListed))) {
-            const run = Promise.all([listed, dueListed])
-                .then(([recs, due]) => this.#redispatch(recs, staleAfterMs, due))
-                .finally(() => {
-                this.inflightResume = null;
-            });
-            this.inflightResume = run;
-            return run;
-        }
-        const dispatched = this.#redispatch(listed, staleAfterMs, dueListed);
-        if (isThenable(dispatched)) {
-            const run = Promise.resolve(dispatched).finally(() => {
-                this.inflightResume = null;
-            });
-            this.inflightResume = run;
-            return run;
-        }
-        return dispatched;
-    }
-    /**
-     * 在飞的 `resumePending`（重入闸，见上）。不用 boolean 而用 Promise：
-     * 重入方要拿到**同一次扫描**的结果，而不是一个「你等着」的空数。
-     */
-    inflightResume = null;
-    /**
-     * 重新派发前**必须**先把 `ownerId` 认领落库 —— 否则「认领」只是内存里的一个记号。
-     *
-     * 病灶：此前这里只改内存里的 `status`/`ownerId` 就 `void #execute(rec)`，真正的 save
-     * 要等到 `#executeInner`（还在 `#acquireSlot` 之后）。对 sqlite/redis 这类 `list()`
-     * 返回**反序列化新对象**的 store，这段窗口里再调一次 `resumePending()` 读到的仍是旧
-     * ownerId，`:305` 的过滤失效 → 同一个任务被再派发一次 → `app.run` 重复执行，副作用
-     * 与花费翻倍。`InMemoryTaskStore` 存的是对象引用，恰好掩盖了这个问题。
-     *
-     * 返回类型刻意保持 `number | Promise<number>`：同步 store 的 save 是同步的，认领当场
-     * 落地，返回数字（`submit`/`list` 那套「同步 store 保持同步门面」的约定不变）；只有
-     * 真出现 thenable 才升级成 Promise，等所有认领落库后再统一派发。
-     */
-    #redispatch(recs, staleAfterMs, due) {
-        const now = Date.now();
-        // 挂起读数的对齐（读数纪律③）：扫描本来就拿到了全表，顺手把 `/healthz` 的读数
-        // 按 store 重建一遍 —— 于是「漏了某个除名出口」只是下一次扫描前的偏差，不会永久漂移。
-        // 顺带把**他进程**（或本进程上一世）留下的挂起也算进本进程可见的那些（口径见
-        // suspendedSummary 的注释：本进程看得见的记录，不假装是全局面）。
-        this.#suspended.clear();
-        for (const rec of recs) {
-            if (rec.status !== 'suspended' || rec.suspendedReason === undefined)
-                continue;
-            this.#suspended.set(rec.taskId, { reason: rec.suspendedReason, wakeAt: rec.wakeAt });
-        }
-        // 惰性审批超时扫描（HITL）：suspended **不捡走续跑**（它在等人，不是
-        // 孤儿 —— 崩溃续跑语义不适用于「等审批」），但读到它时顺手判超时：
-        // 到点自动全拒并重派（框架补的 deny 决定先进 store，再进引擎）。
-        let expired = 0;
-        for (const rec of recs) {
-            if (rec.status !== 'suspended' || !approvalExpired(rec, now, this.approvalTimeoutMs))
-                continue;
-            expired++;
-            this.#expireAndResume(rec, now);
-        }
-        // 到期唤醒（durable timer）：在睡且到点的 timer 挂起 ⇒ 认领 + 重派（醒来重跑那一批）。
-        // 与上面那条循环并列而不是合并：两条闸的**原因判据互斥**，各读各的一眼可见；
-        // 合并成一个循环会让「谁的责任」藏进条件里。drain 之后不唤（#wakeDue 里那道闸）。
-        // 输入（2026-09-28 ⑤）：store 提供到期索引时 `due` 是「只回到期的」那一半 ——
-        // 仍过 `timerDue` 复核（索引口径是 status+wakeAt，原因那一半由这里兜，且
-        // #wakeDueInner 进闸后还会重读再判一次）。
-        let woken = 0;
-        for (const rec of due ?? recs) {
-            if (!timerDue(rec, now))
-                continue;
-            // 只算**真接管**的那些（drain / 已在飞 ⇒ 不算）—— 返回值是「推进了几条」的承诺
-            if (this.#wakeDue(rec, now))
-                woken++;
-        }
-        // 认领判定外移到 resume-policy.ts：跳过原因具名化（terminal / suspended / own-process /
-        // owner-alive / too-fresh），每条规则与边界都由那份纯函数的单测钉住
-        const alive = (id) => this.#ownerLiveness(id);
-        const pending = recs.filter((r) => resumeSkipReason(r, { ownerId: this.ownerId, staleAfterMs, now, ownerAlive: alive }) ===
-            undefined);
-        const claims = [];
-        for (const rec of pending) {
-            rec.status = 'queued'; // 重新入队，由 #execute 统一推进
-            rec.ownerId = this.ownerId; // 认领：此后本进程的记录不再被（自己）重派
-            const saved = this.store.save(rec);
-            if (isThenable(saved)) {
-                // 落库失败则**不派发**：认领没落地，派发等于把上面那个重复执行的窗口重新打开
-                claims.push(Promise.resolve(saved).then(() => this.#dispatch(rec)));
-            }
-            else {
-                // 派发走唯一入口（闸在 #dispatch 里）—— 外部深评 P2-1：认领循环以前绕过了那道闸。
-                this.#dispatch(rec);
-            }
-        }
-        if (claims.length === 0)
-            return pending.length + expired + woken;
-        return Promise.all(claims).then(() => pending.length + expired + woken);
-    }
-    /**
-     * 「这条记录的主人还活着吗」—— 绑上本机主机名后的 pid 存活判定（见 `owner-liveness.ts`）。
-     *
-     * 只被 `#redispatch` 用，且只在 `staleAfterMs > 0` 时真正被问到（那道闸在 resume-policy
-     * 里，单源；缺省 0 = 不看他进程，与升级前逐字一致）。判定不写库、不改状态 —— 纯读数。
-     */
-    #ownerLiveness(ownerId) {
-        return ownerAlive(ownerId, this.#host);
+        return this.#scanner.resumePending(opts);
     }
     /**
      * 在飞计数包裹层：#executeInner 是状态机主体，这里只负责 active 计数与排空通知。
@@ -1452,7 +1024,7 @@ export class AsyncRunner {
                             // 目标时刻（时间挂起才有）—— 同上，从结果形状里取，不按原因反推
                             rec.wakeAt = out.result.wakeAt;
                             // 挂起读数（纪律①）：与落库**同一个分支**登记，不另起一处判断
-                            this.#markSuspended(rec);
+                            this.#approvals.markSuspended(rec);
                             // 事件簿记（2026-09-28 ⑥ 复审收口）：**注入过**就清 —— 事件已在挂起历史里
                             // （suspendedMessages 含注入的 user 消息），簿记留着会让下次续跑**重复注入**
                             // （真探针实证过：模型看到同一事件两次）。没注入（续跑入口的再挂起出口在
@@ -1489,7 +1061,7 @@ export class AsyncRunner {
                             rec.pendingEvents = undefined;
                             // 离开挂起态（读数纪律②）：两处恢复路径负责「还没跑到终态」的那一半，
                             // 这一支负责「跑到了终态」的那一半（兜底：恢复失败也会落到这里）
-                            this.#unmarkSuspended(rec.taskId);
+                            this.#approvals.unmarkSuspended(rec.taskId);
                             // HITL 恢复段 + 会话：本段没把 session 交给 run 层（见上面 callOpts 注释），
                             // 会话回写由 runner 自己补 —— 口径与 run.ts 的 appendSession 一致。
                             if (isResume && out.run.status === 'succeeded') {