@migor/agentia 0.9.4 → 0.10.0

package/dist/transport/async.js

@@ -1,17 +1,28 @@
 import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
 import { classifyError } from '../engine/errors.js';
+import { isTerminalStatus } from '../core/run.js';
 import { normalizeMessages, TaskInputError } from '../engine/spec.js';
 import { InMemoryTaskStore, isThenable, nextTaskId } from '../store/store.js';
 import { combineSignals, releaseCombinedSignal } from '../core/abort.js';
-import { TimeoutError } from '../core/timeout.js';
+import { abortedError } from '../engine/turn.js';
+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 { 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 { 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，不进公共导出面）。
@@ -27,36 +38,138 @@ export class TaskStreamError extends Error {
 /**
  * 任务是否**已到终态**（流可以收口了）。
  *
- * ⚠️ 与 `resume-policy.ts` 那个「可续跑」的判定**刻意不同**：那里 `awaiting_approval`
+ * ⚠️ 与 `resume-policy.ts` 那个「可续跑」的判定**刻意不同**：那里 `suspended`
  * 算「不可续跑」（重启扫描不该去动它），这里是**非终态** —— 挂起在等人，人批了它会接着跑，
  * 流必须**继续开着**（关掉的话「等审批结果的前端」正好在最需要的时候断线）。
  */
 function isTerminalTask(rec) {
-    return rec.status !== 'queued' && rec.status !== 'running' && rec.status !== 'awaiting_approval';
+    // 判定外移到 core/run.ts 的 `isTerminalStatus`（单一真源，2026-09-28 外部深评 S1）：
+    // 这里原本是负向枚举（`status !== 'queued' && …`），而 Redis store 那边压根没判 ——
+    // 同一事实两份读数，写法还不一样。那两处现在都调同一个函数。
+    return isTerminalStatus(rec.status);
 }
 /**
- * `approve` 的失败：带 HTTP 语义的状态码（404 = 任务不存在，409 = 任务当前不在
- * `awaiting_approval` 状态），HTTP 宿主据此回对应响应。
- * module 级 export —— 不进公共导出面（纯宿主内部实现细节）。
+ * `TaskApproveError`（`approve` 的失败，带 HTTP 语义状态码）已随审批监督簇迁到
+ * `approval-supervisor.ts`，本文件顶部 re-export 保持导出面不变（定义与理由见那里）。
  */
-export class TaskApproveError extends Error {
+/**
+ * `cancel` 的失败：带 HTTP 语义的状态码（404 = 任务不存在，409 = 已终态 / 在飞 run 不在本进程）。
+ * 形状与 `TaskApproveError` 同款（module 级 export，不进公共导出面）。
+ */
+export class TaskCancelError extends Error {
     status;
     constructor(status, message) {
         super(message);
-        this.name = 'TaskApproveError';
+        this.name = 'TaskCancelError';
         this.status = status;
     }
 }
+/**
+ * `submit` 在**排队段已满**时的失败（`AsyncRunnerOptions.maxQueued`，2026-09-28 外部深评 T5）。
+ *
+ * 为什么单独一个类型、而不是复用 `TaskInputError`：两者在 HTTP 上的**含义不同** ——
+ * 入参不合法是 **400**（调用方改请求就能过），排队满**不是调用方的错**，是 **503
+ * + `Retry-After`**（同一次请求稍后重发就该过）。宿主若把它们混成一支，运维看到的就是
+ * 「你的请求有问题」，而实际是「服务该扩容 / 该退避」—— 与 `maxConcurrentRuns` 的 503
+ * 那支刻意分开的理由同款。
+ *
+ * `status` 是自陈字段（本仓 `TaskApproveError` 起的惯例）：宿主按它选状态码，不靠
+ * `instanceof` 猜；本类目前只有 503 一种。
+ *
+ * module 级 export —— 不进公共导出面（与 TaskApproveError / TaskCancelError / TaskEventError 同档）。
+ */
+export class TaskQueueFullError extends Error {
+    status = 503;
+    constructor(message) {
+        super(message);
+        this.name = 'TaskQueueFullError';
+    }
+}
+/**
+ * 取消的**宽限**：取消请求发出后，留给那次 run 自己收尾的时间。
+ *
+ * 尊重 signal 的 client 是毫秒级收尾（SDK 一收到 abort 就 reject，run 随即以 `stopReason:
+ * 'aborted'` 收尾 —— 那条路连 `result` 与 trace 都保得住，本常量对它只是余量：一次网络往返 +
+ * trace 落盘）。不认 signal 的宿主**永远**不会自己收尾 —— 等多久都是白等，所以到点就撤回意图、
+ * 如实抛 409（见 `#awaitCancelled`），不假装取消成功。
+ */
+const CANCEL_GRACE_MS = 2_000;
 export class AsyncRunner {
     app;
     store;
-    /** 本进程标识：写进认领的 TaskRecord.ownerId，供 resumePending 区分他我 */
+    /**
+     * 本进程标识：写进认领的 `TaskRecord.ownerId`，供 resumePending 区分他我。
+     *
+     * 形状 `p<pid>@<host>-<8位十六进制>`（真源见 `owner-id.ts`）。为什么带主机名与 pid：
+     * 光有时间判不出「主人还在不在」（`staleAfterMs` 是**新鲜度**不是**租约**），
+     * 而「同主机 + pid 还在」是能直接问操作系统的**直接证据**（见 `owner-liveness.ts`）。
+     */
     ownerId;
+    /**
+     * 本机主机名（构造期取一次）。**同一个值**既写进 `ownerId`、也用于「同主机吗」的判定 ——
+     * 两处各自取一次就可能不一致（hostname 在进程存活期间是可能被改的），判定会因此静默失效。
+     */
+    #host = hostname();
     client;
     sessionStore;
     concurrency;
+    maxQueued;
+    /**
+     * 当前**在等槽位**的任务 id 集合（已受理、尚未拿到槽位）—— `maxQueued` 的判据，
+     * 也是 `queued` 读数。
+     *
+     * 为什么是**集合**而不是计数器：入口只有一处（`#execute` 的**同步前段**、第一个 await
+     * 之前 `add`），出口有两处（`#executeInner` 里**拿到槽位**那一刻 `delete`，`#execute`
+     * 的外层 finally 再 `delete` 一次兜底 —— 覆盖「幂等去重早退 / 中途抛错」）。`add` /
+     * `delete` 的语义**天然幂等**，所以多重释放无害、漏放不可能（兜底那道闸在 finally 里）。
+     * 用整数计数器要做到同一件事，得自己再造一个「只减一次」的闸 —— 那正是最容易写漏的东西
+     * （第一版就是这么写的，而释放点根本不在同一个函数作用域里，闭包跨不过去）。
+     *
+     * ⚠️ 同一 taskId 的两次 `#execute` 并发不在设计内（在飞闸挡着）；万一发生，先退出那一趟
+     * 的 finally 会把仍在等槽位的那趟从集合里删掉 ⇒ 读数**偏小**（闸更宽松）。偏小是安全的
+     * 方向：它不会把服务永久锁在 503 上，而「多收一条」只是回到加本旋钮之前的行为。
+     *
+     * ⚠️ **它本身不是排队深度**：队列长度要减掉「马上就能拿到空槽位的那些」，见 `#queueDepth`
+     * —— 一个 `submit` 循环里同步灌进来的每一条都会先落进本集合，而此时池子还空着，
+     * 直接拿 `size` 当深度会把「立刻就能跑的」也算成排队的（`concurrency: 1` + `maxQueued: 1`
+     * 下连灌两条就会把第 2 条误拒 —— 第一版就是这么写的，被用例当场抓出来）。
+     */
+    #waiting = new Set();
+    /**
+     * **真正在排队的深度**（`maxQueued` 的判据，也是 `queued` 读数）。
+     *
+     * 公式：`max(0, 已受理未持槽的任务数 + adding − 当前空槽位数)`。
+     *
+     * 为什么不能只用等待队列长度、也不能只用 `#waiting.size`：
+     * - `#waiting` 里混了「刚 submit、还没走到 acquire」的任务 —— 池子空着时它们**不会排队**，
+     *   只是还没轮到执行那一刻。`adding` 就是给「正在提交的这一条」留的位置。
+     * - 空槽位数 = `concurrency − #slots.inUse`。于是「同步灌 N 条」时：先到的 N 条一边进
+     *   `#waiting`、一边还算着同样的空槽位，两个量相抵 ⇒ 判据正好落在
+     *   「最多 `concurrency + maxQueued` 条在推进」这条对外口径上（见 `AsyncRunnerOptions.maxQueued`）。
+     * - `concurrency` 为 `Infinity`（缺省）时空槽位数是 `Infinity` ⇒ 深度恒为 0 ⇒ 闸天然不起作用，
+     *   与「缺省行为与加本旋钮之前逐字一致」对齐。
+     */
+    #queueDepth(adding = 0) {
+        const freeSlots = Math.max(0, this.concurrency - this.#slots.inUse);
+        return Math.max(0, this.#waiting.size + adding - freeSlots);
+    }
     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 共用 */
@@ -65,6 +178,21 @@ export class AsyncRunner {
     #drain = new DrainGate();
     /** 任务终态等待表（见 task-waiters.ts）：仅覆盖本进程写终态，他进程写靠兜底轮询 */
     #taskWaiters = new TaskWaiters();
+    /**
+     * 本进程**已受理并正在推进**的任务（= `#execute` 的存活区间）。
+     *
+     * 只为 `cancel` 的文案存在：命中「`status === 'running'` 但在飞句柄表里没有」时，
+     * 区分「**本进程排队未起跑**」与「**真不在本进程**」——
+     * - 四条恢复路径（approve / 到期唤醒 / 事件投递 / 崩溃重投）都**先**把状态置 `running`
+     *   再 `#dispatch`，而 `#runAborts` 要到 `#slots.acquire()` 之后才登记 ⇒ 中间整个窗口
+     *   里 `status` 已是 running、句柄却还没有。原文案一律说「不在本进程」，
+     *   对同进程排队的那条是**说反话**（2026-09-28 外部复核抓到）。
+     * - 本集合与 `#runAborts` 的**差集**恰好就是「已受理、未起跑」（见 `#cancel`）。
+     *
+     * ⚠️ **纯诊断**：不参与任何正确性判定，也不影响 409 闸本身（那道闸不放开 ——
+     * 放开会让等槽位那趟 `#execute` 的 finally 双发 `onFinished`，正是 spec §10 的变异 M23）。
+     */
+    #executions = new Set();
     /**
      * 每任务的记账事件流（见 task-events.ts）：`GET /tasks/:id/stream` 的重放 + 实时推送。
      * 纯记账件，独立于 store / 槽位 —— 所以在 855 行的类里单独抽一个文件。
@@ -102,13 +230,25 @@ export class AsyncRunner {
         this.sessionStore = opts.sessionStore;
         this.taskSinks = opts.taskSinks ?? [];
         this.onPersistError = opts.onPersistError;
-        this.#streams = new TaskEventStreams(opts.streamBufferEvents === undefined ? {} : { maxEvents: opts.streamBufferEvents });
+        this.#streams = new TaskEventStreams({
+            ...(opts.streamBufferEvents === undefined ? {} : { maxEvents: opts.streamBufferEvents }),
+            ...(opts.streamNonTerminalBuffers === undefined
+                ? {}
+                : { nonTerminalBuffers: opts.streamNonTerminalBuffers }),
+        });
         this.concurrency = opts.concurrency ?? Number.POSITIVE_INFINITY;
         if (!(this.concurrency > 0)) {
-            throw new Error(`concurrency 必须为正数，收到 ${opts.concurrency}`);
+            throw new Error(`concurrency 必须为正数（${zeroClauseOf('AsyncRunner.concurrency')}），收到 ${opts.concurrency}`);
         }
         // 放在校验之后：字段初始化式在构造函数体之前求值，那时 concurrency 还是 undefined
         this.#slots = new SlotPool(this.concurrency);
+        this.maxQueued = opts.maxQueued ?? 0;
+        if (!Number.isInteger(this.maxQueued) || this.maxQueued < 0) {
+            // 与 concurrency 同族：`0` 本身**合法**（= 不限），坏的是「负数 / 小数 / NaN / Infinity」。
+            // 负数的读法无解（「最多排 -1 个」是什么），小数会让比较变成「有时收有时不收」——
+            // 都不是「配置宽一点」而是「配置说了另一件事」，所以构造期响亮失败。
+            throw new Error(`maxQueued 必须为 ≥ 0 的整数（${zeroClauseOf('AsyncRunner.maxQueued')}），收到 ${opts.maxQueued}`);
+        }
         this.runTimeoutMs = opts.runTimeoutMs ?? 0;
         if (!Number.isFinite(this.runTimeoutMs) || this.runTimeoutMs < 0) {
             // NaN/Infinity 都不能放给 setTimeout：两者都会被钳到 1ms，每个任务立即「超时」失败
@@ -116,12 +256,43 @@ export class AsyncRunner {
             // 文案里的「0 = 不限」取自 core/limits.ts 的表 —— 口径与实现同一处，不可能各说各话。
             throw new Error(`runTimeoutMs 必须为 ≥ 0 的有限数（${zeroClauseOf('AsyncRunner.runTimeoutMs')}），收到 ${opts.runTimeoutMs}`);
         }
+        // 上界（2026-09-28）：「≥0 且有限」还不够 —— 超过 2^31-1ms（约 24.86 天）的延迟
+        // Node **不会遵守**（stderr 一行 TimeoutOverflowWarning + 钳到 1ms），于是「配 30 天
+        // 超时」变成「每个任务立即超时失败」，静默且与配置相反。上限单源与五处站点共用：
+        // 这一句就是 scheduler.ts 注释里承诺过的「async.ts 同款防线」（此前那句话与实现不符）。
+        assertTimerDelay(this.runTimeoutMs, 'AsyncRunner 的 runTimeoutMs');
         this.approvalTimeoutMs = opts.approvalTimeoutMs ?? 0;
         if (!Number.isFinite(this.approvalTimeoutMs) || this.approvalTimeoutMs < 0) {
             // 同 runTimeoutMs：非有限数会让「已挂起多久」的比较静默失效或立即超时
             throw new Error(`approvalTimeoutMs 必须为 ≥ 0 的有限数（${zeroClauseOf('AsyncRunner.approvalTimeoutMs')}），收到 ${opts.approvalTimeoutMs}`);
         }
-        this.ownerId = `p${process.pid}-${randomUUID().slice(0, 8)}`;
+        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}。
@@ -156,10 +327,28 @@ export class AsyncRunner {
                 // 处理，拒绝即视为无记录，交 #execute 的去重兜底。
                 existing.catch(() => undefined);
             }
-            else if (existing && existing.status !== 'failed') {
-                return { ...existing }; // at-least-once 去重：不重复执行
+            else if (existing && existing.status !== 'failed' && existing.status !== 'cancelled') {
+                // at-least-once 去重：不重复执行。`failed` 被刻意排除（失败后同键重提要真跑）；
+                // `cancelled` 同理 —— 排队被取消的任务**一次都没跑过**，同键再提交若直接认回
+                // 那条 cancelled 记录，这次提交就被静默吞掉（且与 #executeInner 只采纳
+                // `succeeded` 的异步路径不一致：同一件事两种 store 两种结局）。
+                return { ...existing };
             }
         }
+        // 排队段闸（2026-09-28 外部深评 T5）：放在**去重之后** —— 幂等键命中既有记录时
+        // 本次提交既不产生新活也不排队，不该吃 503（否则「重试同一个键」会变成看运气）。
+        // 读 `#waiting` 是**同步准确**的：别的 submit 在它自己的 `#execute` 同步前段就入过集合
+        // （`#dispatch` 是 submit 的最后一行，`void this.#execute(rec)` 的 body 到第一个 await
+        // 之前全同步）⇒ 「一个循环里同步灌 N 条」不可能绕过这道闸，不靠人记得 await。
+        // 判据是**真正在排队的深度**（`#queueDepth`），不是「已受理未持槽」的集合大小：
+        // 后者把「池子还空着、马上就能跑」的那些也算成排队的，会把第 2 条合法提交误拒。
+        // `(1)` = 把正在提交的这一条算进去 —— 闸要拦的是「这条交了以后会溢出」。
+        const queueDepth = this.#queueDepth(1);
+        if (this.maxQueued > 0 && queueDepth > this.maxQueued) {
+            throw new TaskQueueFullError(`排队已满：这条提交会让 ${queueDepth} 条任务排在槽位后` +
+                `（上限 maxQueued=${this.maxQueued}，concurrency=${this.concurrency}）` +
+                '—— 请退避重试，或调大 concurrency / maxQueued');
+        }
         const rec = {
             taskId: nextTaskId(),
             status: 'queued',
@@ -182,17 +371,25 @@ export class AsyncRunner {
                 void this.#safeSave(rec, 'initial');
             });
         }
-        void this.#execute(rec);
+        // 派发走唯一入口（闸在 #dispatch 里）—— ⚠️ 这里是**结构一致性**，不是行为依赖：
+        // 本方法开头那道 `isDraining` 检查（拒绝语义：对调用方的承诺是抛错 / 503，不是静默排期）
+        // 与这一行之间**没有 await** —— `submit` 是**全同步**的（异步 store 的 `save` 也只是挂个
+        // `.catch`，不 await）⇒ JS 不可能在中间插入 drain 的置位 ⇒ `#dispatch` 那道闸在**本方法内
+        // 永远不触发**。（2026-09-28 PR #164 复核 §3：此前的注释与提交信息把它说成「挡进闸与派发
+        // 之间刚开始停机的窄窗口」，那是个不存在的窗口。）
+        // 仍然走它：**「派发一律走唯一入口」这条纪律不该有例外** —— 少一个例外，就少一处将来
+        // 新增恢复路径时会漏的枚举。
+        this.#dispatch(rec);
         // 返回浅拷贝：记录会被后台状态机原地推进，调用方拿到的是提交时刻的快照
         return { ...rec };
     }
     /** 查任务当前记录（异步 store 下返回 Promise，调用方 await） */
     poll(taskId) {
         const rec = this.store.get(taskId);
-        // 惰性审批超时（HITL）：读到 awaiting 记录时顺手判定 —— 到点就自动全拒并重派
+        // 惰性挂起闸（HITL 超时 + 到期唤醒）：读到挂起记录时顺手判定，到点就恢复并重派
         if (isThenable(rec))
-            return rec.then((r) => this.#lazyExpireApproval(r));
-        return this.#lazyExpireApproval(rec);
+            return rec.then((r) => this.#lazyGates(r));
+        return this.#lazyGates(rec);
     }
     /**
      * 订阅某任务的**记账事件流**（`GET /tasks/:id/stream` 的引擎侧）。
@@ -201,7 +398,7 @@ export class AsyncRunner {
      * 1. **先重放、后实时**：`opts.from`（= SSE 的 `Last-Event-ID` / `?from=`）之后的事件先补发，
      *    再挂实时订阅 —— 「连上时已经跑了一半」的客户端因此也能拿到完整前缀。
      * 2. **终态收口**：任务已终态 ⇒ 补发完缓冲 + 一帧 `end`，**不留**一条永远不会再产出事件的流。
-     *    挂起（`awaiting_approval`）**不是**终态：批了会接着跑，流必须开着（见 isTerminalTask）。
+     *    挂起（`suspended`）**不是**终态：批了（或睡到点了）会接着跑，流必须开着（见 isTerminalTask）。
      * 3. **跨进程不假装**：本进程没有这条流时（别的进程在跑 / 任务早于本进程），发一帧
      *    `unavailable` 后**立即收口**：终态补 `end`，非终态补 `closed`（流级收尾，不是
      *    伪造终态）—— 非终态只发 `unavailable` 就返回的话，这条 SSE 只剩心跳永远挂着。
@@ -260,78 +457,168 @@ export class AsyncRunner {
         return this.store.list();
     }
     /**
-     * 审批一个处于 `awaiting_approval` 的任务（HITL）。
-     *
-     * - **逐 tool_use_id 幂等**：已存在的决定不覆盖（第一次决定赢）—— 重复提交 /
-     *   并发点击不会推翻已有决定，也不会让恢复段重复执行；
-     * - **并发重入共享在飞那次**：同一任务的并发 approve（双击「批准」/两个审批人
-     *   同时批）返回同一个 Promise —— 否则两个调用都在对方落库前读到
-     *   `awaiting_approval`、各自判「决定齐了」、**各派发一次**（同一任务重复执行，
-     *   与 resumePending 的闸门同一 bug 类）。被共享的那次覆盖不到的决定不丢：
-     *   调用方从返回的记录看到任务仍在等待，重试即并入；
-     * - 决定齐了就恢复：`status` 回 `running`、**先落库再派发**（与 `#redispatch`
-     *   同一条纪律 —— 没落库就恢复，进程崩在窗口里会丢决定）；恢复段带着
-     *   `rec.approvals` 与扩展后的消息历史（`rec.spec.messages`，末尾是含未决
-     *   tool_use 的那条 assistant 消息）重进引擎循环；
-     * - 决定**没**齐：只把本批决定落库，任务继续等（可能多轮审批）；
-     * - 返回当前 TaskRecord（快照）。任务不存在抛 404 语义、状态不对抛 409 语义
-     *   的 `TaskApproveError`。
+     * 取消一个任务（durable 配套 5 的另一半；设计稿 `docs/plans/2026-09-28-cancel-api.md`）。
+     *
+     * 三种「在服」状态各自的语义 —— 都落在这一处，不分散：
+     * - **running**：中止在飞 signal ⇒ 引擎以 `stopReason: 'aborted'` 收尾（尊重 signal 的
+     *   client 是**真中断**，token 不再烧；不尊重者等价「放弃等待」—— 与 `runTimeoutMs`
+     *   同一份契约）。等它真落库再返回：不等的话调用方拿到的是 `status` 仍为 running 的快照，
+     *   「取消了但状态还在跑」比不返回更误导。
+     * - **queued**（还没起跑）：落终态；`#executeInner` 拿到槽位后会**重读**再判，
+     *   所以被取消的排队任务**绝不起跑**（这条是本次实现顺带补上的洞）。记账由本方法
+     *   自己做；那一趟还活着的 `#execute`（在等槽位）靠 `#cancelSettled` 在 finally 里
+     *   跳过它那一份（否则 onFinished 两次）。
+     * - **suspended**（两种原因都算）：落终态 —— 两条唤醒闸都 gate 在 `status === 'suspended'`
+     *   上，「不唤醒」因此是翻转状态的**推论**，不需要第二处标志。它没有活着的 `#execute`
+     *   （挂起时那趟就走完了），所以记账（sinks / 事件流 / 认领释放 / 等待者 / 会话清理）
+     *   由本方法自己做 —— 也因此它**不进** `#cancelSettled`（没有消费者，加了就是泄漏）。
+     *
+     * 状态按**意图**落，不按机制落：超时的收尾语义**不变**（仍是 `failed` + `error.type` 为
+     * `'timeout'`），取消带 `error = abortedError()`（取消不是失败，但原因要可查）。
+     *
+     * 不做静默 no-op：已终态 ⇒ `TaskCancelError(409)`（状态不对要说出来），不存在 ⇒ 404。
+     * 边界（如实写在这里）：`running` 的 run **不在本进程**（多进程部署 / 上一世留下的 running）
+     * 时抛 409 —— 本进程没有句柄可中断，改状态假装取消只会在那条 run 跑完时被覆盖回去。
+     *
+     * ⚠️ 同一个 409 判据下还有**第二种**情形（2026-09-28 外部复核）：任务已在本进程受理、
+     * 但还没走到 `#runAborts` 登记（在等并发槽位，或恢复路径刚写完 `running` 尚未派发完）。
+     * 它**不是**「不在本进程」—— 原文案一律那么说，对这一类是说反话。两种情形分开措辞
+     * （见 `#cancel` 的判据），但**闸不放开**：放开会让等槽位那趟 `#execute` 的 finally
+     * 双发 `onFinished`（spec §10 的变异 M23）。
      */
-    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;
+    cancel(taskId) {
+        const found = this.store.get(taskId);
+        if (isThenable(found))
+            return found.then((rec) => this.#cancel(rec, taskId));
+        return this.#cancel(found, taskId);
     }
-    /** 同一任务的在飞审批（approve 的重入闸，见上）。**与惰性超时恢复共用同一把闸** ——
-     *  approve 与 #expireAndResume 都会「填决定 + 落库 + 派发」，不互斥就是同一任务跑两遍。 */
-    inflightApprovals = new Map();
-    async #approveInner(taskId, decisions, opts) {
-        const rec = await this.store.get(taskId);
+    #cancel(rec, taskId) {
         if (!rec)
-            throw new TaskApproveError(404, `task 不存在: ${taskId}`);
-        if (rec.status !== 'awaiting_approval') {
-            throw new TaskApproveError(409, `task ${taskId} 当前状态为 ${rec.status}，只有 awaiting_approval 才能审批`);
+            throw new TaskCancelError(404, `task 不存在: ${taskId}`);
+        if (isTerminalTask(rec)) {
+            throw new TaskCancelError(409, `task ${taskId} 已终态（${rec.status}），不能取消`);
         }
-        const now = Date.now();
-        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.approvalPendingSince !== undefined
-                    ? { requestedAt: rec.approvalPendingSince }
-                    : {}),
-            };
+        const inflight = this.#runAborts.get(taskId);
+        if (rec.status === 'running' && !inflight) {
+            // 「假装取消」是这里最坏的选项：那条 run 还活着，跑完会把状态覆盖回去
+            // （调用方以为成功了，实际什么都没发生）。要说出来。
+            // ⚠️ 但这两类情形**必须分开说**（2026-09-28 外部复核）：`#executions` 是
+            // 「本进程已受理并正在推进」的集合，与 `#runAborts`（已登记在飞句柄）的差集
+            // 就是「**已受理、未起跑**」。四条恢复路径先置 `running` 再 `#dispatch`、
+            // 而句柄要到拿到槽位才登记 ⇒ 中间整个窗口都会落进这个差集 —— 对它说
+            // 「不在本进程」是反话。调用方据此区分「稍后重试」与「得去找那个进程」。
+            const acceptedHere = this.#executions.has(taskId);
+            throw new TaskCancelError(409, acceptedHere
+                ? `task ${taskId} 已在本进程受理，但尚未起跑（正在等并发槽位 / 走恢复前置）—— ` +
+                    `此刻取消无法与那条在等槽位的执行路径安全收口（会重复记账），暂不支持；` +
+                    `请待它起跑后再取消，或先降低并发压力`
+                : `task ${taskId} 正在运行但不在本进程，本进程无法中断它（多进程部署见 spec §10 2026-09-28 ④）`);
         }
-        // 惰性审批超时：人的决定先并入（先到先赢），仍空着的待决项由超时兜底成 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;
+        // 意图先记下：在飞那条路要靠它把 aborted 的收尾落成 cancelled（否则落成 failed）
+        this.#cancels.add(taskId);
+        if (inflight) {
+            inflight.abort();
+            return this.#awaitCancelled(taskId);
         }
-        // 先落库再派发 —— **真纪律，不是注释**：save 失败（同步抛 / 异步 reject）就
-        // 绝不恢复执行（落不了库的决定不算决定：进程崩在窗口里会丢决定，重启后把
-        // 同一件事再判一次、可能改判）。调用方拿到 reject，重试即可。
-        await this.store.save(rec);
-        if (complete)
-            void this.#execute(rec);
-        return { ...rec };
+        // queued / suspended：没有在飞 run（或它还没起跑），直接落终态 —— 记账由本方法做完，
+        // 等槽位那趟 #execute 的 finally 靠 `#cancelSettled` 跳过它那一份（否则 onFinished 两次）。
+        // ⚠️ `#cancelSettled` 只为 **queued** 而存（它有活着的、在等槽位的 #execute 来消费）；
+        // suspended 的那趟 #execute 早在挂起时就走完了，条目加进去永远没人摘（泄漏）。
+        // 既知边界（多进程）：他进程取消本进程**排队中**的任务时，本进程的 execute finally
+        // 在自己的 `#cancelSettled` 里查不到 ⇒ onFinished 会双发（cancel 进程一次 + owner 一次）。
+        const wasQueued = rec.status === 'queued';
+        rec.status = 'cancelled';
+        rec.error = abortedError();
+        rec.finishedAt = Date.now();
+        // 挂起痕迹清掉（`pendingApprovals` 与 `approvals` 的区别与既有终态口径一致：
+        // 未决清单清掉、**已做出的决定**保留 —— 那是审计的一部分，随任务走）
+        rec.pendingApprovals = undefined;
+        rec.suspendedSince = undefined;
+        rec.suspendedReason = undefined;
+        rec.wakeAt = undefined;
+        this.#approvals.unmarkSuspended(taskId);
+        const saved = this.#safeSave(rec, 'outcome');
+        this.#cancels.delete(taskId);
+        if (wasQueued)
+            this.#cancelSettled.add(taskId);
+        const finish = () => {
+            this.#taskWaiters.notify(taskId);
+            this.#streams.markDone(taskId);
+            this.sessionInputs.delete(taskId);
+            const key = rec.idempotencyKey;
+            if (key !== undefined && this.#claims.get(key)?.taskId === taskId)
+                this.#claims.delete(key);
+            this.#notifyDrained();
+            return { ...rec };
+        };
+        return isThenable(saved)
+            ? Promise.resolve(saved)
+                .then(() => this.#notifySinks(rec))
+                .then(finish)
+            : this.#notifySinks(rec).then(finish);
+    }
+    /**
+     * 等一条**已请求取消**的在飞任务真收尾（宽限见 `CANCEL_GRACE_MS`）。
+     *
+     * 终态判据用 `isTerminalTask`（单一真源）—— 手写两值会让 `cancelled` 在这里被漏掉，
+     * 等待就变成「等到超时」，症状是「取消没生效」。
+     *
+     * ⚠️ 宽限内没收尾 ⇒ **撤回意图 + 抛 409**，不假装：敢说「取消了」而那条 run 还活着的话，
+     * 它跑完会把状态覆盖回去（调用方以为成功、实际什么都没发生）。不认 `signal` 的宿主正是
+     * 这一类；`runTimeoutMs` 那条老路对同样情形是「放弃等待」（记录落 failed、槽位释放、
+     * 底层执行照样跑完）—— 两者**刻意不同**：超时是宿主自己定的预算，取消是人手按的动作，
+     * 骗人的代价不一样。
+     */
+    async #awaitCancelled(taskId) {
+        const deadline = Date.now() + CANCEL_GRACE_MS;
+        for (;;) {
+            const rec = await this.store.get(taskId);
+            if (rec && isTerminalTask(rec))
+                return rec;
+            const left = deadline - Date.now();
+            if (left <= 0) {
+                // 撤回意图（不删 `#runAborts`：那条 run 还在本进程里活着，句柄留给它自己的 finally 摘）
+                this.#cancels.delete(taskId);
+                throw new TaskCancelError(409, `task ${taskId} 的中断没有在 ${CANCEL_GRACE_MS}ms 内生效（宿主不认 signal？）—— 取消未发生`);
+            }
+            await this.#taskWaiters.wait(taskId, Math.min(250, left));
+        }
+    }
+    /**
+     * 审批一个处于 `suspended` 的任务（HITL）。
+     *
+     * 实现已外移到 `approval-supervisor.ts`（**逐字搬迁**，含四条语义与它们的理由：
+     * 逐 tool_use_id 幂等 / 并发重入共享在飞那次 / 决定齐了先落库再派发 / 状态不对抛
+     * `TaskApproveError`）。这里只留薄壳 —— `approve` 是 `AsyncRunner` 的公开 API，
+     * 签名与返回类型不变。
+     */
+    async approve(taskId, decisions, opts = {}) {
+        return this.#approvals.approve(taskId, decisions, opts);
+    }
+    /**
+     * 投递一个事件给**挂起**的任务（HITL 与 durable timer 两种挂起都适用）。
+     *
+     * 实现已外移到 `signal-supervisor.ts`（**逐字搬迁**，含完整语义清单与并发闸的理由：
+     * 只对 `suspended` 生效 / 按 `eventId` 幂等 / 缓冲满了拒收并说出来 / 投完即续跑且
+     * **先落库再派发** / 并发时**串行成链**而不是像 approve 那样共享在飞那次）。
+     * 这里只留薄壳 —— `signalTask` 是 `AsyncRunner` 的公开 API，签名与返回类型不变。
+     */
+    signalTask(taskId, event) {
+        return this.#signals.signalTask(taskId, event);
     }
     /** 已受理但未达终态的任务数（queued + running）—— 健康检查与 drain 共用同一口径 */
     get inFlight() {
         return this.active;
     }
+    /**
+     * **本进程可见的挂起读数**（`/healthz` 的 `suspended` 段，配套 6）。
+     *
+     * 口径与三条维护纪律（挂起时登记 / 离开时除名 / 每次扫描按 store 重建）已随审批监督簇
+     * 迁到 `approval-supervisor.ts` 的 `#suspended`（那张注释就写在那里）；这里只留对外 getter。
+     */
+    get suspendedSummary() {
+        return this.#approvals.summary;
+    }
     /** 是否已进入优雅停机（drain 之后为 true）—— HTTP 宿主据此对新单回 503 */
     get isDraining() {
         return this.#drain.isDraining;
@@ -343,84 +630,112 @@ export class AsyncRunner {
      * `resumePending` 续跑（所以 drain 不是「丢弃」，是「不再往前推」）。
      * - `timeoutMs` 缺省 0 = 一直等。
      * - 等待的是**所有已受理**的任务（queued 的也在内），不只是正在占槽位的那些。
+     *
+     * ⚠️ **这是一道单向闩：置位之后本进程不再推进任何任务，且没有复位路径**（`DrainGate` 只有
+     * 置位，没有复位）。所以 `false`（排空超时）的含义不只是「还有在飞的」——它同时给宿主
+     * 加了一条义务：**必须让进程退出**。理由（2026-09-28 PR #164 复核 §1，有探针实证）：
+     * 停机窗口里被 `#dispatch` 拒掉的记录**已经落库**（`running`/`queued` + **本进程的 ownerId**），
+     * 而本进程的 `resumePending` 会按 `own-process` 跳过它们（见 resume-policy.ts），`submit` 又
+     * 已整体关闭 ⇒ 本进程内**没有任何自愈路径**。宿主若在 `false` 之后继续服务，这些记录会永远
+     * 停在 `running`：`awaitTask` 不返回，`GET /tasks/:id/stream` 还会告诉客户端
+     * `not-in-this-process`（说不对话：记录里的 ownerId 正是本进程）。只有**下一次进程启动**
+     * 才会有人认领它们（ownerId 含 pid）。参考宿主（`examples/` 各示例的 `src/main.ts`）都是
+     * `await drain(...)` 之后 `process.exit(...)`，与本条契约一致。
      */
     async drain(opts = {}) {
         // 实现已外移到 drain-gate.ts（写前保留的契约注释仍在本方法上）
         return this.#drain.waitForIdle(() => this.active === 0, opts.timeoutMs ?? 0);
     }
     /**
-     * 审批超时的**判定**已外移到 approval-policy.ts（`approvalExpired` / `fillTimeoutDenials` /
-     * `approvalsComplete`）—— 下面是**编排**：进在飞闸、重读一遍、先落库再派发。
+     * poll 的读路径钩子：两条**惰性**的挂起闸各判一次（都不起定时器 —— 没人读的挂起不会自己动，
+     * 与审批超时同一条纪律；崩溃/重启也不依赖任何在飞回调）。
+     *
+     * 审批那一半已外移到 `#approvals.expireIfExpired`（判据与副作用逐字等价，见
+     * approval-supervisor.ts）；这里保留「命中审批就返回、不再判 timer」的形状 ——
+     * 两条闸的原因判据本来就互斥（`approval` / `timer`，`approvalExpired` 内部也卡原因），
+     * 排他在这里是**写出来的**而不是「两个函数各自恰好正确」—— C 之前正是「一个状态
+     * 兼职两件事」让审批那条闸去叫醒了等时刻的 run。
      */
+    #lazyGates(rec) {
+        if (!rec)
+            return rec;
+        const now = Date.now();
+        if (this.#approvals.expireIfExpired(rec, now))
+            return rec;
+        if (timerDue(rec, now))
+            this.#scanner.wakeDue(rec, now);
+        return rec;
+    }
     /**
-     * 惰性超时扫描（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 撞上在飞的超时恢复时共享其结果 —— 与人的决定竞速，先到先得。
+     * 取消的**意图**（2026-09-28 ④）。落库状态按意图判、不从 signal 反推 ——
+     * 同一条 signal 有三个来源（调用方传入 / `runTimeoutMs` / 取消），反推不出「谁按的」。
+     * 只在一次 run 的收尾判定里活着：登记在认领处，摘除在同一次 run 的 finally。
      */
-    #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 !== 'awaiting_approval' ||
-            !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;
+    #cancels = new Set();
+    /** 在飞 run 的中止句柄（**每任务一个**，同时服务超时与取消 —— 机制相同、意图不同）。 */
+    #runAborts = new Map();
+    /**
+     * 已由 `cancel` **自己**收尾过的任务。那趟等槽位的 `#execute` 还活着，它的 finally 会再记一遍账
+     * （onFinished 触发两次 / 流被关两次）—— 用这个集合把「谁负责记账」说定：cancel 收尾了，
+     * finally 就只做它自己那份（在飞递减、通知等待者、排空通知）。
+     */
+    #cancelSettled = new Set();
+    /**
+     * **唯一的派发口**（2026-09-28 外部深评 P1-1 / P2-1 的结构性修法）。
+     *
+     * 为什么要有它：所有「先把状态落库成 `running`/`queued`、再派发 `#execute`」的路径
+     * （`submit` / `approve` / `signalTask` / 到期唤醒 / 审批超时兜底 / `resumePending` 的认领）
+     * **形状相同**，而停机闸原先散在各支里 —— 于是「这道闸覆盖几条路径」变成一份**靠人记**的清单：
+     * 第二批修了三支、第四支（审批超时兜底，走 `poll()`）与第五支（认领循环）漏了，两处都在
+     * `drain()` 返回 `true`（「排空干净」）之后**又起了新 run**（实证：`drain-race.test.ts`）。
+     *
+     * 修法：闸**只在这里判一次**，各支只管「先落库」的顺序（那条纪律不变）。
+     * 源码级穷尽守卫在 `tests/transport/dispatch-guard.test.ts`：`this.#execute(` 与
+     * `this.#executeInner(` 都只许出现在自己的那一个家里 —— 第五次新增恢复路径时构建就红，
+     * 不靠记性。（钉两个而不是一个：`#executeInner` 是同一个旁路的另一半，绕过它还会连带
+     * 绕过 `active++` 与 `#streams.open`，见那份用例的注释。）
+     *
+     * 语义：停机窗口里**不派发**。记录已落库（`running`/`queued` + 本进程 ownerId），
+     * 留给下次启动的 `resumePending` 认领（ownerId 含 pid ⇒ 新进程必认领）—— at-least-once 兜底，
+     * 与「先落库再派发」的崩窗同形；决定 / 事件都在记录里，不丢。
+     * ⚠️ 「留给下次启动」成立的前提是**宿主真的退出**（见 `drain()` 的契约：单向闩 + 本进程内
+     * 无自愈路径）。所以这里的拒绝**不静默**：首次拒绝打一条 `console.warn` 说清「谁、什么状态、
+     * 谁来认领、宿主该做什么」—— 否则运维只看到一个停在 `running` 的任务，无从解释。
+     * ⚠️ 对调用方**不抛错**（`submit` 的「停机中不接单 ⇒ 503」在那之前的早返回里，不在这一层）。
+     */
+    #dispatch(rec) {
+        if (this.#drain.isDraining) {
+            // **不静默**（2026-09-28 PR #164 复核 §1）：这里的拒绝等于「本进程此后不再推进任何任务」，
+            // 而它此前是一条裸 `return` —— 运维只会看到一个停在 `running` 的任务，无从解释它为什么不跑
+            // （`drain()` 的契约见上：宿主此刻必须退出，记录留给下次启动认领）。
+            // 只报一次：停机窗口里每条被拒记录各报一条会把日志刷满，而它们的原因完全相同。
+            if (!this.#dispatchRefusedWarned) {
+                this.#dispatchRefusedWarned = true;
+                console.warn(`[agentia] 停机中：已拒绝派发 task ${rec.taskId}（记录已落库成 ${rec.status}）—— ` +
+                    '本进程此后不再推进任何任务，它留给下次启动的 resumePending 认领；' +
+                    '宿主必须在 drain() 之后退出，否则这条记录会一直停在 running（见 usage-guide §7）');
             }
+            return;
         }
-        void this.#execute(target);
-        return target;
+        void this.#execute(rec);
     }
-    /** poll 的读路径钩子：读到 awaiting 且已超时 ⇒ 惰性判掉（判定见 approval-policy.ts） */
-    #lazyExpireApproval(rec) {
-        if (!rec)
-            return rec;
-        const now = Date.now();
-        if (approvalExpired(rec, now, this.approvalTimeoutMs))
-            this.#expireAndResume(rec, now);
-        return rec;
+    /** 「停机窗口里拒绝派发」的告警是否已出过（每次停机只报一条，见 `#dispatch`） */
+    #dispatchRefusedWarned = false;
+    /**
+     * 当前**真正在排队**的任务数（`maxQueued` 的实时读数，诊断用）—— 与闸用的是**同一个**
+     * `#queueDepth`，所以「看到的数」就是「判据的数」，不会各说各话。
+     * 与 `inFlight` 的分工：`inFlight` 是「本进程已受理、未达终态」的全量（含在跑、含挂起），
+     * 本读数是其中「排不上、在等槽位」的那一段。
+     */
+    get queued() {
+        return this.#queueDepth();
     }
     /** 任务终态唤醒与等待：实现见 task-waiters.ts（`notify` / `wait`） */
     /** 排空通知：只在确无在飞任务时唤醒等待者（drain 的唯一出口）—— 判定在 drain-gate.ts */
     #notifyDrained() {
         this.#drain.signalIdle(() => this.active === 0);
     }
-    /** 等到任务终态；超时抛错。`awaiting_approval` 不是终态 —— 继续等（人在路上）。 */
+    /** 等到任务终态；超时抛错。`suspended` 不是终态 —— 继续等（人在路上 / 时刻未到）。 */
     async awaitTask(taskId, opts = {}) {
         const timeoutMs = opts.timeoutMs ?? 30_000;
         // intervalMs 现在只是**兜底轮询**间隔，不是主路径：本进程把任务写到终态会主动唤醒
@@ -434,7 +749,9 @@ export class AsyncRunner {
             const rec = await this.poll(taskId);
             if (!rec)
                 throw new Error(`task 不存在: ${taskId}`);
-            if (rec.status === 'succeeded' || rec.status === 'failed')
+            // ⚠️ 终态集合走 `isTerminalTask` 这个**单一真源**：手写枚举会让新加的终态（`cancelled`）
+            // 在这里被漏掉 —— 表现为「取消了但 awaitTask 一直等到超时」，看起来像取消没生效
+            if (isTerminalTask(rec))
                 return rec;
             const left = deadline - Date.now();
             if (left <= 0)
@@ -447,100 +764,16 @@ export class AsyncRunner {
      * （running 视为进程中断）。返回重派数量（异步 store 下返回 Promise<number>）。
      * 幂等键去重照常生效。
      *
-     * `awaiting_approval`（HITL）**不捡**：它在等人、不是孤儿（进程没死也可能挂着）。
-     * 但读到它会做**惰性超时判定**：配了 `approvalTimeoutMs` 且已超时的挂起任务
-     * 自动全拒（`denied, reason: '审批超时'`）并重派。
-     *
-     * **认领先落库、再派发**（见 `#redispatch`）；异步 store 的认领落库失败会让本方法
-     * reject —— 宁可让调用方看见「续跑没做」，也不要静默放出一批会被重复执行的任务。
+     * 实现在 `resume-scanner.ts`（**逐字搬迁**，含那四步扫描的**顺序**与各自理由、重入闸、
+     * 到期索引接线、多进程 `ownerId` 的判定分级）。这里只留薄壳 —— `resumePending` 是
+     * `AsyncRunner` 的公开 API，签名与返回类型不变。
      *
-     * 多进程共用一个 store 时靠 `ownerId` 区分他我：
-     * - 本进程的记录一律跳过（它还在本进程内存里跑，重派 = 跑两遍）；
-     * - `staleAfterMs > 0` 时，startedAt/createdAt 距今不足该值的他进程记录也跳过
-     *   （大概正被那个进程执行）。缺省 0 = 不判断、一律重派（单进程旧语义）。
+     * 一句话提要（细节见实现）：`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;
-        if (isThenable(listed)) {
-            const run = Promise.resolve(listed)
-                .then((recs) => this.#redispatch(recs, staleAfterMs))
-                .finally(() => {
-                this.inflightResume = null;
-            });
-            this.inflightResume = run;
-            return run;
-        }
-        const dispatched = this.#redispatch(listed, staleAfterMs);
-        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) {
-        const now = Date.now();
-        // 惰性审批超时扫描（HITL）：awaiting_approval **不捡走续跑**（它在等人，不是
-        // 孤儿 —— 崩溃续跑语义不适用于「等审批」），但读到它时顺手判超时：
-        // 到点自动全拒并重派（框架补的 deny 决定先进 store，再进引擎）。
-        let expired = 0;
-        for (const rec of recs) {
-            if (rec.status !== 'awaiting_approval' || !approvalExpired(rec, now, this.approvalTimeoutMs))
-                continue;
-            expired++;
-            this.#expireAndResume(rec, now);
-        }
-        // 认领判定外移到 resume-policy.ts：跳过原因具名化（terminal / own-process / too-fresh），
-        // 每条规则与边界都由那份纯函数的单测钉住
-        const pending = recs.filter((r) => resumeSkipReason(r, { ownerId: this.ownerId, staleAfterMs, now }) === 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(() => void this.#execute(rec)));
-            }
-            else {
-                void this.#execute(rec);
-            }
-        }
-        if (claims.length === 0)
-            return pending.length + expired;
-        return Promise.all(claims).then(() => pending.length + expired);
+        return this.#scanner.resumePending(opts);
     }
     /**
      * 在飞计数包裹层：#executeInner 是状态机主体，这里只负责 active 计数与排空通知。
@@ -549,47 +782,66 @@ export class AsyncRunner {
      */
     async #execute(rec) {
         // 同步认领（在任何 await 之前）：同键并发提交的第二个 submit 立刻能看见它。
-        // 挂起（awaiting_approval）**不释放** —— 那是「等人工」，不是终态；放了会让同键再起一个新任务。
+        // 挂起（suspended）**不释放** —— 那是「等人工」，不是终态；放了会让同键再起一个新任务。
         const key = rec.idempotencyKey;
         if (key !== undefined && !this.#claims.has(key))
             this.#claims.set(key, rec);
         // 同步开流（在任何 await 之前）：`GET /tasks/:id/stream` 从这一刻起可以订阅。
         // 复用语义见 task-events.ts —— HITL 恢复 / 崩溃重投是**同一个任务**，序号接着走。
         this.#streams.open(rec.taskId);
+        // 「本进程已受理」的起点（同步段，与 #streams.open 同处）：cancel 的 409 文案据此
+        // 区分「排队未起跑」与「真不在本进程」。终点是整个 #execute 退出的 finally。
+        this.#executions.add(rec.taskId);
         this.active++;
+        // **在等槽位**的入口（同步段，与 `active++` 同处）—— 只看 id，出集合在「拿到槽位」
+        // 那一刻（`#executeInner`）与本节 finally 两处，`add`/`delete` 幂等所以两处都安全。
+        // 同步段入集合是这道闸**挡得住同步突发**的前提：`#dispatch` 是 submit 的最后一行，
+        // `void this.#execute(rec)` 的 body 到第一个 await 之前全同步 ⇒ 一个循环里连续 submit
+        // 时，每次读到的都是已含前几条的**准确**读数。
+        this.#waiting.add(rec.taskId);
         try {
             await this.#executeInner(rec);
         }
         finally {
+            this.#waiting.delete(rec.taskId);
             // 通知在飞递减**之前**：drain() 返回时保证「任务已终态 + 回调已发完」。
             // 内层 finally 保证回调万一抛错（理论上被吞掉）也不泄漏在飞计数。
             try {
-                // HITL：挂起不是终态 —— onFinished 的承诺是「任务达终态」，对它不开火
-                if (rec.status !== 'awaiting_approval')
+                // HITL：挂起不是终态 —— onFinished 的承诺是「任务达终态」，对它不开火。
+                // 已由 `cancel` 自己收尾过的那一条也不开火（`#cancelSettled`）：两处都记会触发两次
+                if (rec.status !== 'suspended' && !this.#cancelSettled.has(rec.taskId)) {
                     await this.#notifySinks(rec);
+                }
             }
             finally {
                 this.active--;
-                // 终态即清理 HITL 会话回写快照（挂起则保留 —— 恢复段成功后还要用它）
-                if (rec.status !== 'awaiting_approval')
-                    this.sessionInputs.delete(rec.taskId);
+                // 记账的归属：cancel 收尾过的那一份已经做过（流收口 / 会话清理 / 认领释放），
+                // 这里只消费掉标记，不重复 —— 在飞递减、等待者、排空通知照旧必达
+                if (!this.#cancelSettled.delete(rec.taskId)) {
+                    // 终态即清理 HITL 会话回写快照（挂起则保留 —— 恢复段成功后还要用它）
+                    if (rec.status !== 'suspended')
+                        this.sessionInputs.delete(rec.taskId);
+                    // 任务流收口（挂起不算终态 —— 见 isTerminalTask 的注释：批了会接着跑，流得开着）。
+                    if (isTerminalTask(rec))
+                        this.#streams.markDone(rec.taskId);
+                    // 释放同键认领：**只有终态才释放**（挂起仍在等人，同键提交不该另起一个任务）。
+                    // 判据用 taskId 比对而非 `claimed`：HITL 的恢复段是**另一次** #execute 调用
+                    // （approve / 超时兜底 / 崩溃恢复都会重派，且异步 store 交出的常是新副本对象），
+                    // 那次 `claimed` 必为 false —— 只看 `claimed` 会让挂起过的键**永不释放**（认领表泄漏，
+                    // 同键从此永远命中那条老记录）。
+                    if (key !== undefined &&
+                        rec.status !== 'suspended' &&
+                        this.#claims.get(key)?.taskId === rec.taskId) {
+                        this.#claims.delete(key);
+                    }
+                }
                 // 任务已达终态并落库 → 唤醒 awaitTask 的等待者（放在递减之后，语义与 drain 一致）。
-                // 挂起也唤醒：等待者看一眼状态继续等（awaiting_approval 不是终态），无副作用。
+                // 挂起也唤醒：等待者看一眼状态继续等（suspended 不是终态），无副作用。
                 this.#taskWaiters.notify(rec.taskId);
-                // 任务流收口（挂起不算终态 —— 见 isTerminalTask 的注释：批了会接着跑，流得开着）。
-                if (isTerminalTask(rec))
-                    this.#streams.markDone(rec.taskId);
-                // 释放同键认领：**只有终态才释放**（挂起仍在等人，同键提交不该另起一个任务）。
-                // 判据用 taskId 比对而非 `claimed`：HITL 的恢复段是**另一次** #execute 调用
-                // （approve / 超时兜底 / 崩溃恢复都会重派，且异步 store 交出的常是新副本对象），
-                // 那次 `claimed` 必为 false —— 只看 `claimed` 会让挂起过的键**永不释放**（认领表泄漏，
-                // 同键从此永远命中那条老记录）。
-                if (key !== undefined &&
-                    rec.status !== 'awaiting_approval' &&
-                    this.#claims.get(key)?.taskId === rec.taskId) {
-                    this.#claims.delete(key);
-                }
                 this.#notifyDrained();
+                // 「本进程已受理」的终点（与 #execute 同寿）。删在最后：此前若 cancel 挤进来，
+                // 它看到的仍是「本进程在推进这条」，文案不会突然改口。
+                this.#executions.delete(rec.taskId);
             }
         }
     }
@@ -631,11 +883,53 @@ export class AsyncRunner {
                     return;
                 }
             }
+            // 「出排队段」必须与「占槽」落在**同一次同步执行**里：`await acquire()` 的连续体要等
+            // 一次微任务，而 `acquire` 内部的 `running++` 是同步的 —— 同一条任务在那一瞬被算两遍
+            // ⇒ 排队深度虚高一格（`concurrency: 1` + `maxQueued: 1` 下第 2 条合法提交被误拒）。
+            // 所以：**有空位就趁 await 之前出集合**（判据是快照 —— 判断与 acquire 之间没有 await，
+            // 池子状态不会变）；排队等到的那些，则在 acquire 兑现后出集合（同一个 delete，幂等）。
+            // ⚠️ 刻意**不**把 acquire 换成同步快路径：那会顺带少掉一次微任务，把「置 running」
+            // 相对引擎推进的时刻提前，踩到既有用例里「等到 running 就当工具已挂在飞」的隐含假设
+            // （`tests/transport/cancel.test.ts` 的前置断言当场红）。记账改原子，时序一个字不改。
+            if (this.#slots.inUse < this.concurrency)
+                this.#waiting.delete(rec.taskId);
             await this.#slots.acquire();
+            this.#waiting.delete(rec.taskId); // 拿到槽位 = 离开排队段（此后归 concurrency 管）
             try {
+                // 认领前**重读一遍**再判（异步 store 交出的是副本：拿 submit 时那个对象判不出
+                // 「排队期间被取消了没有」）——与 `#wakeDueInner` 的「进闸后重读」同因。
+                // 不判的后果：cancel 只把状态改了，任务**照跑**（记录说 cancelled、副作用真发生 ——
+                // 最坏的一种谎）。
+                // ⚠️ 判据**只挡终态**，别写成 `!== 'queued'`：恢复那几条路（approve / 到期唤醒 /
+                // 崩溃重投）都**先**把状态置成 `running` 再派发 —— 那样写会把它们全挡死，
+                // 症状是「恢复了但任务没跑」（本实现第一版就是这么错的，transport 套件当场挂住）。
+                // ⚠️ 读失败**不改变既有行为**：这道闸只负责「明知已终态就别跑」，不负责把
+                // store 读取故障升级成「任务起不来」（停机窗口里 store 已 close 是既有场景，
+                // 那条路径的行为由 scheduler 的用例钉着）。
+                let claimed;
+                try {
+                    claimed = (await this.store.get(rec.taskId)) ?? rec;
+                }
+                catch {
+                    claimed = undefined;
+                }
+                if (claimed && isTerminalTask(claimed)) {
+                    // 与 store 对齐再返回：外层 finally 会拿 `rec` 落一次 outcome，
+                    // 不同步的话会用**陈旧副本**把取消覆盖回 queued（任务从此既不起跑也不终态）。
+                    // 记账（sinks / 事件流 / 认领释放 / 等待者）交给**还活着**的那次 #execute 的 finally
+                    // ——它正是此刻在等槽位的这一条。
+                    Object.assign(rec, claimed);
+                    return;
+                }
+                // 在飞句柄**先**登记（在任何 await 与状态写之前）：cancel 的中断窗口从这里闭合
+                this.#runAborts.set(rec.taskId, new AbortController());
                 rec.status = 'running';
                 rec.startedAt = Date.now();
                 await this.store.save(rec);
+                // 取消意图在收尾判定里要用两次：正常出口（`#cancels.has`）与**异常出口**
+                // （拒绝式认 signal 的宿主 —— abort 后 reject，包 fetch 类客户端的常见写法）。
+                // ⚠️ 必须声明在 try **之外**：`let` 是块级作用域，写在 try 里 catch 看不到它。
+                let cancelIntent = false;
                 try {
                     // 会话注入（C4 的异步通道）：sessionId 是可序列化的引用，store 实例由
                     // runner 持有 —— 执行前在这里换成 RunAppOptions.session。resumed 记录
@@ -644,12 +938,19 @@ export class AsyncRunner {
                     if (rec.spec.options?.sessionId !== undefined && this.sessionStore === undefined) {
                         throw new Error(`任务 ${rec.taskId} 带了 options.sessionId，但本 runner 未配 sessionStore`);
                     }
-                    // HITL 恢复段（带审批决定重进引擎）的判定 —— 决定会话注入与回写的走向（见下）
-                    const isResume = rec.approvals !== undefined;
+                    // **续跑段**的判定（不只是 HITL：时间挂起醒来也是续跑）—— 决定会话注入、
+                    // 链路关联与会话回写三条口径的走向（见下）。判据**不能**只看 `approvals`：
+                    // timer 挂起醒来时没有任何决定（approvals 是空的），但 `rec.spec.messages` 同样是
+                    // 挂起段落库的**扩展历史**（末尾是含未决 tool_use 的 assistant）—— 那三条口径
+                    // 一字不差地适用（`suspendedSince` 是「这条记录挂起过」的痕迹：挂起时写、终态才清）。
+                    const isResume = rec.approvals !== undefined || rec.suspendedSince !== undefined;
                     // runTimeoutMs 到点即 abort（对尊重 signal 的客户端是真中止）；与调用方
                     // 可能传入的 signal 合成，任一触发都中止本次 run。
-                    const timeoutAc = new AbortController();
-                    const combined = combineSignals(rec.spec.options?.signal, timeoutAc.signal);
+                    // 每任务**一个** controller，同时服务超时与取消（机制是同一条 signal，差别在意图）：
+                    // 它在认领处就登记进了 #runAborts，所以 cancel 找得到它
+                    const runAc = this.#runAborts.get(rec.taskId) ?? new AbortController();
+                    this.#runAborts.set(rec.taskId, runAc);
+                    const combined = combineSignals(rec.spec.options?.signal, runAc.signal);
                     // 记账事件 → 本任务的流（`GET /tasks/:id/stream` 的数据源）。
                     // 与任务 spec 里可能自带的那个**叠加**而不是覆盖（composeTraceEvents 的同一份理由）：
                     // 两边都要收到 —— 覆盖会让其中一条静默失聪。
@@ -677,10 +978,16 @@ export class AsyncRunner {
                                 : {}),
                         // HITL 恢复段：审批决定随任务落库，重跑时原样进引擎（进程重启不丢）
                         ...(rec.approvals !== undefined ? { approvals: rec.approvals } : {}),
+                        // 事件投入口（2026-09-28 ⑥）：挂起期间投递的事件随记录进引擎，由它在
+                        // 未决 tool_use 解决之后注入消息流（为什么不能由宿主直接追加进
+                        // spec.messages 的末尾：见 signalTask 与 engine/loop.ts 的注入点纪律）
+                        ...(rec.pendingEvents !== undefined && rec.pendingEvents.length > 0
+                            ? { events: rec.pendingEvents }
+                            : {}),
                         // 恢复段的 trace 是一棵**新树**，经 traceContext link 挂到上一段 runId
                         // （spec §9.2 的入站关联机制）——「挂起段 → 恢复段 → …」在观测后端连成一条链。
-                        // 判定依据：有决定且已有上一段 runId = 本次是恢复执行；首次执行两者皆无。
-                        ...(rec.approvals !== undefined && rec.runId !== undefined
+                        // 判定依据：本段是续跑段（isResume）且已有上一段 runId；首次执行两者皆无。
+                        ...(isResume && rec.runId !== undefined
                             ? { traceContext: { traceId: rec.runId } }
                             : {}),
                         rethrow: false, // 硬失败也以 failed 记录落库
@@ -689,16 +996,16 @@ export class AsyncRunner {
                         ...(bridgeTraceEvents !== undefined ? { onTraceEvent: bridgeTraceEvents } : {}),
                     };
                     try {
-                        const out = await this.#raceTimeout(this.app.run(rec.spec.messages, callOpts), rec.taskId, () => timeoutAc.abort());
+                        const out = await this.#raceTimeout(this.app.run(rec.spec.messages, callOpts), rec.taskId, () => runAc.abort());
                         rec.runId = out.run.runId;
                         rec.result = out.result;
                         rec.error = out.result.error;
-                        if (out.result.stopReason === 'awaiting_approval' && out.result.suspendedMessages) {
+                        if (out.result.stopReason === 'suspended' && out.result.suspendedMessages) {
                             // HITL 挂起：扩展后的消息历史（末尾是含未决 tool_use 的 assistant 消息）
                             // 与待决清单、挂起时刻一起落库 —— approve / 惰性超时 / 重启后都靠它们。
                             // 槽位照常释放（finally）、onFinished 不触发（#execute 的出口判断）、
                             // finishedAt 不置（下面 finally 里按状态跳过）：它不是终态。
-                            rec.status = 'awaiting_approval';
+                            rec.status = 'suspended';
                             // 「本轮用户输入」快照必须在 overwrite **之前**取 —— 此刻 rec.spec.messages
                             // 还是原始输入；恢复段成功后由 #appendResumedSession 拿它 + finalText 补写会话。
                             // 只在首个挂起段快照（!isResume）：恢复段再挂起时 spec.messages 已是
@@ -710,13 +1017,51 @@ export class AsyncRunner {
                             }
                             rec.spec = { ...rec.spec, messages: out.result.suspendedMessages };
                             rec.pendingApprovals = out.result.pendingApprovals;
-                            rec.approvalPendingSince = Date.now();
+                            rec.suspendedSince = Date.now();
+                            // 挂起原因（2026-09-28 ①）：从结果形状里取，**不写死** ——
+                            // 写死成 'approval' 会让将来新增的挂起原因在落库这一步被悄悄改写成审批。
+                            rec.suspendedReason = out.result.suspendedReason;
+                            // 目标时刻（时间挂起才有）—— 同上，从结果形状里取，不按原因反推
+                            rec.wakeAt = out.result.wakeAt;
+                            // 挂起读数（纪律①）：与落库**同一个分支**登记，不另起一处判断
+                            this.#approvals.markSuspended(rec);
+                            // 事件簿记（2026-09-28 ⑥ 复审收口）：**注入过**就清 —— 事件已在挂起历史里
+                            // （suspendedMessages 含注入的 user 消息），簿记留着会让下次续跑**重复注入**
+                            // （真探针实证过：模型看到同一事件两次）。没注入（续跑入口的再挂起出口在
+                            // 注入点之前返回）则必须留住 —— 清掉就是丢事件。判据是结果上的
+                            // `eventsDelivered` 位，不是「是不是挂起」这个粗粒度。
+                            if (out.result.eventsDelivered)
+                                rec.pendingEvents = undefined;
                         }
                         else {
-                            rec.status = out.run.status;
+                            // 取消：机制与 `runTimeoutMs` 一字不差（同一条 abort signal），**意图**不同 ——
+                            // 状态按意图落（超时 = failed、人取消 = cancelled）。意图从 `#cancels` 取，
+                            // 不从 signal 反推：同一条 signal 有三个来源（调用方 / 超时 / 取消）。
+                            const cancelled = this.#cancels.has(rec.taskId);
+                            rec.status = cancelled ? 'cancelled' : out.run.status;
+                            // 取消必须带**结构化原因**（「取消不是失败，但原因要可查」）：宿主自定义的
+                            // AppCallable 若不认 signal，它照旧返回一个正常结果 ⇒ `result.error` 是空的，
+                            // 那时记录里也得说清「这条是被取消的」（与超时那条的账一类）。
+                            if (cancelled && rec.error === undefined)
+                                rec.error = abortedError();
                             // 终态后清掉挂起痕迹（决定保留：审批记录是审计的一部分，随任务走）
                             rec.pendingApprovals = undefined;
-                            rec.approvalPendingSince = undefined;
+                            rec.suspendedSince = undefined;
+                            rec.suspendedReason = undefined;
+                            rec.wakeAt = undefined;
+                            // 事件簿记（2026-09-28 ⑥）：**终态没有第二次机会** —— 这条记录不会再被续跑，
+                            // 事件留着也没有注入点，清掉。
+                            // ⚠️ 判据与挂起分支**刻意不同**（复审第二轮把这里的注释改成真话，原先写的是
+                            // 「跑通到非挂起出口 ⇒ 引擎已把它们注入消息流」—— 那句在注入点**之前**就被
+                            // 中止/失败的出口上不成立）：挂起分支按 `eventsDelivered` 判（注入过才清、
+                            // 没注入要留 —— 下次续跑补上），这里无条件清。
+                            // 于是「恢复段在注入之前就 abort（取消 / runTimeoutMs）或整段失败」的那些终态，
+                            // 其事件**不会**进历史 —— 既成事实，不假装「已注入」；发件方从记录的终态与
+                            // error 看得到这条 run 的下场（要重试就重新提交一次：事件不跨终态重放）。
+                            rec.pendingEvents = undefined;
+                            // 离开挂起态（读数纪律②）：两处恢复路径负责「还没跑到终态」的那一半，
+                            // 这一支负责「跑到了终态」的那一半（兜底：恢复失败也会落到这里）
+                            this.#approvals.unmarkSuspended(rec.taskId);
                             // HITL 恢复段 + 会话：本段没把 session 交给 run 层（见上面 callOpts 注释），
                             // 会话回写由 runner 自己补 —— 口径与 run.ts 的 appendSession 一致。
                             if (isResume && out.run.status === 'succeeded') {
@@ -728,16 +1073,29 @@ export class AsyncRunner {
                         // 正常收尾（没有源中止）时主动摘除挂在各源上的监听器 —— 宿主级共享
                         // signal 是长寿的，不摘会按任务数累积（MaxListenersExceededWarning）
                         releaseCombinedSignal(combined);
+                        // 在飞句柄与取消意图一起摘掉：意图只在**这次 run** 的收尾判定里有用（见下面那处）。
+                        // ⚠️ 意图的取值要留给 catch（`Set.delete` 返回布尔）：拒绝式认 signal 的宿主
+                        // 走的就是 catch —— 在这里丢掉意图，取消就会被记成 failed（正是要治的病）。
+                        this.#runAborts.delete(rec.taskId);
+                        cancelIntent = this.#cancels.delete(rec.taskId);
                     }
                 }
                 catch (e) {
-                    rec.error = classifyError(e);
-                    rec.status = 'failed';
+                    // 意图先到 ⇒ cancelled（与「结果说成功、取消先到」同一条「意图赢」规则）——
+                    // 覆盖「abort 后 reject」的宿主路径；无意图的异常照旧是 failed。
+                    if (cancelIntent) {
+                        rec.status = 'cancelled';
+                        rec.error = abortedError();
+                    }
+                    else {
+                        rec.error = classifyError(e);
+                        rec.status = 'failed';
+                    }
                 }
             }
             finally {
                 // HITL：挂起不是「完成」—— finishedAt 不置（等待中的任务没有结束时刻）
-                if (rec.status !== 'awaiting_approval')
+                if (rec.status !== 'suspended')
                     rec.finishedAt = Date.now();
                 // 落库失败不遮罩、槽位必须释放：释放放在内层 finally，即便落库实现抛错也必达
                 try {