@migor/agentia 0.10.1 → 0.10.3

package/dist/transport/async.js

@@ -3,7 +3,7 @@ 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 { InMemoryTaskStore, cloneTaskRecord, isThenable, nextTaskId } from '../store/store.js';
 import { combineSignals, releaseCombinedSignal } from '../core/abort.js';
 import { abortedError } from '../engine/turn.js';
 import { assertTimerDelay, TimeoutError } from '../core/timeout.js';
@@ -18,6 +18,8 @@ import { DrainGate } from './drain-gate.js';
 import { formatOwnerId } from './owner-id.js';
 import { TaskWaiters } from './task-waiters.js';
 import { TaskEventStreams } from './task-events.js';
+import { adoptSucceededOutcome, buildRunCallOptions } from './run-call-options.js';
+import { applySuspendedOutcome, applyTerminalOutcome, readClaimed } from './run-outcome.js';
 // 三个监督件（2026-09-29 抽出）的实现与类型现在各自在文件里 —— 审批（approval-supervisor.ts）、
 // 事件投递（signal-supervisor.ts）、恢复扫描（resume-scanner.ts）。下面 **re-export** 它们的
 // 对外符号 ⇒ 一切 `from './async.js'` 的既有 import 路径不变。
@@ -275,6 +277,7 @@ export class AsyncRunner {
             ownerId: this.ownerId,
             approvalTimeoutMs: this.approvalTimeoutMs,
             dispatch: (rec) => this.#dispatch(rec),
+            cancelInflight: (taskId) => this.#cancelInflight.get(taskId),
         });
         // 事件投递与恢复扫描同样在 ownerId 就位后构造。两处**回调注入**的理由与 `#approvals` 一致：
         // `#dispatch`（停机闸 + 唯一派发点 + 一次性告警）与 drain 读数都归本类，两个监督件只**消费**它们
@@ -284,6 +287,7 @@ export class AsyncRunner {
             ownerId: this.ownerId,
             approvals: this.#approvals,
             dispatch: (rec) => this.#dispatch(rec),
+            cancelInflight: (taskId) => this.#cancelInflight.get(taskId),
         });
         this.#scanner = new ResumeScanner({
             store: this.store,
@@ -292,6 +296,7 @@ export class AsyncRunner {
             approvals: this.#approvals,
             dispatch: (rec) => this.#dispatch(rec),
             isDraining: () => this.#drain.isDraining,
+            cancelInflight: (taskId) => this.#cancelInflight.get(taskId),
         });
     }
     /**
@@ -318,7 +323,7 @@ export class AsyncRunner {
             // 「同时提交两个同键任务」会两次都执行（见 #claims 的注释）。
             const inFlight = this.#claims.get(opts.idempotencyKey);
             if (inFlight)
-                return { ...inFlight };
+                return cloneTaskRecord(inFlight);
             const existing = this.store.byIdempotency(opts.idempotencyKey);
             if (isThenable(existing)) {
                 // 异步 store 返回 Promise —— 同步门面无法 await，去重交给 #execute。
@@ -380,8 +385,9 @@ export class AsyncRunner {
         // 仍然走它：**「派发一律走唯一入口」这条纪律不该有例外** —— 少一个例外，就少一处将来
         // 新增恢复路径时会漏的枚举。
         this.#dispatch(rec);
-        // 返回浅拷贝：记录会被后台状态机原地推进，调用方拿到的是提交时刻的快照
-        return { ...rec };
+        // 返回深拷贝（2026-10-13 ref-reject-static-methods 收口）：记录会被后台状态机原地推进，浅拷贝只隔顶层 ——
+        // `spec.messages` 等嵌套对象此前与 runner 的活记录共享（HITL 挂起会换 spec.messages）。
+        return cloneTaskRecord(rec);
     }
     /** 查任务当前记录（异步 store 下返回 Promise，调用方 await） */
     poll(taskId) {
@@ -456,6 +462,17 @@ export class AsyncRunner {
     list() {
         return this.store.list();
     }
+    /**
+     * cancel 的 per-task 在飞闸（2026-10-13 ref-run-root-close）—— cancel 与四条推进路径（approve /
+     * 事件投递 / 到期唤醒 / 审批超时恢复）之间的**互斥**靠它合上：
+     * - cancel 进入前：先等该任务的在飞推进收口、**重读**记录再判（凭进闸前的旧快照落
+     *   cancelled，会被对方随后的 running 落库覆盖回去 —— 任务取消后照常执行）；
+     * - 推进路径进入前：同步看一眼本闸（approve / signalTask 等它收口后重试；
+     *   到期唤醒 / 审批超时是**惰性**路径，跳过本轮、下一轮再判）。
+     * 两侧的「检查对方闸 + 登记自己闸」都在**同一个同步段**里 ⇒ 先登记者赢，没有缝隙。
+     * 同步 store 的 cancel 临界段（get → 落库）本身原子，不走本闸。
+     */
+    #cancelInflight = new Map();
     /**
      * 取消一个任务（durable 配套 5 的另一半；设计稿 `docs/plans/2026-09-28-cancel-api.md`）。
      *
@@ -485,13 +502,49 @@ export class AsyncRunner {
      * 它**不是**「不在本进程」—— 原文案一律那么说，对这一类是说反话。两种情形分开措辞
      * （见 `#cancel` 的判据），但**闸不放开**：放开会让等槽位那趟 `#execute` 的 finally
      * 双发 `onFinished`（spec §10 的变异 M23）。
+     *
+     * 与推进路径的互斥（2026-10-13 ref-run-root-close）：见 `#cancelInflight` 的注释。并发 cancel 同任务
+     * 串行：第二个等第一个收尾后重读再判（多半撞上「已终态 ⇒ 409」）。
      */
     cancel(taskId) {
+        // 并发 cancel 串行（2026-10-13 ref-run-root-close）：两个并发 cancel 各自读-改-写会双记账（webhook 双发）
+        const own = this.#cancelInflight.get(taskId);
+        if (own)
+            return own.then(() => this.cancel(taskId), () => this.cancel(taskId));
+        const advance = this.#advanceInflight(taskId);
         const found = this.store.get(taskId);
-        if (isThenable(found))
-            return found.then((rec) => this.#cancel(rec, taskId));
+        if (advance !== undefined || isThenable(found)) {
+            // 异步路径：先入闸（后续推进路径会看到它并等待/跳过），等在飞推进收口后**重读**再判
+            const run = (async () => {
+                if (advance !== undefined)
+                    await advance.catch(() => undefined);
+                // 意图先立（等闸窗口里就要可见）：等槽位那趟 #executeInner 可能正好放行 ——
+                // 意图在场它才不会起跑（见 #executeInner 的取消意图闸）
+                this.#cancels.add(taskId);
+                try {
+                    const rec = advance !== undefined ? await this.store.get(taskId) : await found;
+                    return await this.#cancel(rec, taskId);
+                }
+                catch (e) {
+                    this.#cancels.delete(taskId); // 没走到收尾（404/409）⇒ 意图撤回
+                    throw e;
+                }
+            })();
+            const tracked = run.finally(() => {
+                this.#cancelInflight.delete(taskId);
+            });
+            this.#cancelInflight.set(taskId, tracked);
+            return tracked;
+        }
+        // 同步快路径：同步 store 且无任何推进在飞 ⇒ 临界段（get → 落库）原子，无需入闸
         return this.#cancel(found, taskId);
     }
+    /** 三条推进路径（审批 / 事件投递 / 到期唤醒）在该任务上的在飞 Promise（无则 undefined） */
+    #advanceInflight(taskId) {
+        return (this.#approvals.inflightFor(taskId) ??
+            this.#signals.inflightFor(taskId) ??
+            this.#scanner.inflightWakeFor(taskId));
+    }
     #cancel(rec, taskId) {
         if (!rec)
             throw new TaskCancelError(404, `task 不存在: ${taskId}`);
@@ -512,7 +565,7 @@ export class AsyncRunner {
                 ? `task ${taskId} 已在本进程受理，但尚未起跑（正在等并发槽位 / 走恢复前置）—— ` +
                     `此刻取消无法与那条在等槽位的执行路径安全收口（会重复记账），暂不支持；` +
                     `请待它起跑后再取消，或先降低并发压力`
-                : `task ${taskId} 正在运行但不在本进程，本进程无法中断它（多进程部署见 spec §10 2026-09-28 ④）`);
+                : `task ${taskId} 正在运行但不在本进程，本进程无法中断它（多进程部署见 spec §10 2026-09-28 ref-cancel-api）`);
         }
         // 意图先记下：在飞那条路要靠它把 aborted 的收尾落成 cancelled（否则落成 failed）
         this.#cancels.add(taskId);
@@ -522,8 +575,10 @@ export class AsyncRunner {
         }
         // queued / suspended：没有在飞 run（或它还没起跑），直接落终态 —— 记账由本方法做完，
         // 等槽位那趟 #execute 的 finally 靠 `#cancelSettled` 跳过它那一份（否则 onFinished 两次）。
-        // ⚠️ `#cancelSettled` 只为 **queued** 而存（它有活着的、在等槽位的 #execute 来消费）；
-        // suspended 的那趟 #execute 早在挂起时就走完了，条目加进去永远没人摘（泄漏）。
+        // ⚠️ cancel 自己只为 **queued** 登记（它有活着的、在等槽位的 #execute 来消费）；
+        // suspended 的那趟 #execute 早在挂起时就走完了，cancel 直接登记会永远没人摘（泄漏）。
+        // 第二个生产者是 `#executeInner` 的取消意图闸（2026-10-13 ref-run-root-close）：被并发恢复路径派发出
+        // 来的那趟自己登记、自己的 finally 消费 —— 覆盖面带消费者一起补，仍不泄漏。
         // 既知边界（多进程）：他进程取消本进程**排队中**的任务时，本进程的 execute finally
         // 在自己的 `#cancelSettled` 里查不到 ⇒ onFinished 会双发（cancel 进程一次 + owner 一次）。
         const wasQueued = rec.status === 'queued';
@@ -537,11 +592,26 @@ export class AsyncRunner {
         rec.suspendedReason = undefined;
         rec.wakeAt = undefined;
         this.#approvals.unmarkSuspended(taskId);
-        const saved = this.#safeSave(rec, 'outcome');
-        this.#cancels.delete(taskId);
+        // ⚠️ 落库**当场发生**（2026-10-13 ref-run-root-close）：不走 `#safeSave` 的微任务延迟 —— cancel 的临界段
+        // 必须原子。落库推迟一个微任务，「重读再判」那几条路（readClaimed / 恢复路径的进闸重读）
+        // 就会在这个缝里读到取消前的旧状态、照常起跑/派发（「绝不起跑」承诺就是这样被破的）。
+        // 失败口径与 #safeSave 相同：不遮罩（记账继续），但必须可观测（onPersistError）。
+        let saved;
+        try {
+            saved = this.store.save(rec);
+        }
+        catch (error) {
+            this.#reportPersistError(rec, error, 'outcome');
+            saved = undefined;
+        }
         if (wasQueued)
             this.#cancelSettled.add(taskId);
         const finish = () => {
+            // 取消意图的终点（2026-10-13 ref-run-root-close）：还有活着的 #execute 时留给它消费 —— 它靠这个意图
+            // 判「绝不起跑」（等槽位那趟的 readClaimed 可能读到的是落库前的旧快照）；
+            // 没有活着的（suspended 取消 / 它已先走完全程）由这里摘掉，不得滞留。
+            if (!this.#executions.has(taskId))
+                this.#cancels.delete(taskId);
             this.#taskWaiters.notify(taskId);
             this.#streams.markDone(taskId);
             this.sessionInputs.delete(taskId);
@@ -549,10 +619,13 @@ export class AsyncRunner {
             if (key !== undefined && this.#claims.get(key)?.taskId === taskId)
                 this.#claims.delete(key);
             this.#notifyDrained();
+            // 深拷贝在此**不需要**（与 submit 的 cloneTaskRecord 不同档）：rec 是 cancel 自己的
+            // 入站快照（store 契约保证不是库内活引用），且任务已终态 —— 之后没有任何路径再推进它
             return { ...rec };
         };
         return isThenable(saved)
             ? Promise.resolve(saved)
+                .catch((error) => this.#reportPersistError(rec, error, 'outcome'))
                 .then(() => this.#notifySinks(rec))
                 .then(finish)
             : this.#notifySinks(rec).then(finish);
@@ -667,9 +740,13 @@ export class AsyncRunner {
         return rec;
     }
     /**
-     * 取消的**意图**（2026-09-28 ④）。落库状态按意图判、不从 signal 反推 ——
+     * 取消的**意图**（2026-09-28 ref-cancel-api）。落库状态按意图判、不从 signal 反推 ——
      * 同一条 signal 有三个来源（调用方传入 / `runTimeoutMs` / 取消），反推不出「谁按的」。
-     * 只在一次 run 的收尾判定里活着：登记在认领处，摘除在同一次 run 的 finally。
+     *
+     * 生命周期（2026-10-13 ref-run-root-close 收紧）：登记在 cancel 的临界段**入口**（异步路径在等闸之前
+     * 就立上 —— 它同时是 `#executeInner` 取消意图闸的判据），摘除在四处：run 收尾
+     * （`cancelIntent` 取值处）、`#executeInner` 的意图闸、cancel 自己的 `finish`
+     * （仅当没有活着的 `#execute` 会消费它时）、`#execute` 的 finally（兜底）。
      */
     #cancels = new Set();
     /** 在飞 run 的中止句柄（**每任务一个**，同时服务超时与取消 —— 机制相同、意图不同）。 */
@@ -678,6 +755,11 @@ export class AsyncRunner {
      * 已由 `cancel` **自己**收尾过的任务。那趟等槽位的 `#execute` 还活着，它的 finally 会再记一遍账
      * （onFinished 触发两次 / 流被关两次）—— 用这个集合把「谁负责记账」说定：cancel 收尾了，
      * finally 就只做它自己那份（在飞递减、通知等待者、排空通知）。
+     *
+     * 两个生产者（2026-10-13 ref-run-root-close 补齐）：① cancel 的 queued 分支（老的那条）；② `#executeInner`
+     * 的取消意图闸 —— 被并发恢复路径派发出来的 suspended 取消也有一条活着的 `#execute`，
+     * 它在意图闸拦下起跑、同样要把「记账归 cancel」说定。两个生产者都保证有消费者
+     * （那趟 `#execute` 自己的 finally），不会滞留。
      */
     #cancelSettled = new Set();
     /**
@@ -842,6 +924,10 @@ export class AsyncRunner {
                 // 「本进程已受理」的终点（与 #execute 同寿）。删在最后：此前若 cancel 挤进来，
                 // 它看到的仍是「本进程在推进这条」，文案不会突然改口。
                 this.#executions.delete(rec.taskId);
+                // 取消意图的兜底摘除（2026-10-13 ref-run-root-close）：正常路径里它已被各自的出口消费
+                // （run 收尾 / 意图闸 / cancel 自己的 finish），这里是「早退路径没走到任何出口」的
+                // 兜底 —— 意图滞留会让一条**后来**的同任务取消记录误导收尾判定（意图只认 taskId）。
+                this.#cancels.delete(rec.taskId);
             }
         }
     }
@@ -864,20 +950,12 @@ export class AsyncRunner {
         // 顶层容错：异步 store（网络客户端）任何一处 reject 都不得逃逸成
         // unhandled rejection（Node ≥15 默认终止进程）——任务标记失败尽力落库。
         try {
-            // 异步 store 的幂等去重在此补齐（submit 同步门面无法 await）：
-            // 同键已有 succeeded 记录 → 采纳其结果，不重复执行；queued/running 不采纳 ——
-            // 重复执行本就是 at-least-once 允许的行为。同步 store 下 submit 已完成去重，
-            // 这里查到的一般是 rec 自身（taskId 相同，直接放行）。
-            // 注意（load-bearing）：该去重依赖 store.save 先写记录、后写 idem 索引的顺序
-            // （见 redisStore 头注释）——索引指向自身时上面的 taskId 相等判断放行。
+            // 异步 store 的幂等去重在此补齐（submit 同步门面无法 await）。三条判据（存在既有记录 /
+            // 不是自己 / 状态是 succeeded）与那条 load-bearing 的顺序依赖（`store.save` 先写记录、
+            // 后写 idem 索引）都搬进了 `adoptSucceededOutcome` 的注释里 —— 一字未改。
             if (rec.idempotencyKey) {
                 const existing = await this.store.byIdempotency(rec.idempotencyKey);
-                if (existing && existing.taskId !== rec.taskId && existing.status === 'succeeded') {
-                    rec.status = 'succeeded';
-                    rec.runId = existing.runId;
-                    rec.result = existing.result;
-                    rec.error = existing.error;
-                    rec.finishedAt = Date.now();
+                if (adoptSucceededOutcome(rec, existing)) {
                     // 采纳既有结果：落库失败也不该把一次已知成功的任务翻成 failed
                     await this.#safeSave(rec, 'outcome');
                     return;
@@ -896,23 +974,12 @@ export class AsyncRunner {
             await this.#slots.acquire();
             this.#waiting.delete(rec.taskId); // 拿到槽位 = 离开排队段（此后归 concurrency 管）
             try {
-                // 认领前**重读一遍**再判（异步 store 交出的是副本：拿 submit 时那个对象判不出
-                // 「排队期间被取消了没有」）——与 `#wakeDueInner` 的「进闸后重读」同因。
-                // 不判的后果：cancel 只把状态改了，任务**照跑**（记录说 cancelled、副作用真发生 ——
-                // 最坏的一种谎）。
+                // 认领前**重读一遍**再判 —— 为什么要重读、以及「读失败不改变既有行为」那条边界，
+                // 都搬进了 `run-outcome.ts` 的 `readClaimed`（具名件才能被直接单测）。
                 // ⚠️ 判据**只挡终态**，别写成 `!== 'queued'`：恢复那几条路（approve / 到期唤醒 /
                 // 崩溃重投）都**先**把状态置成 `running` 再派发 —— 那样写会把它们全挡死，
                 // 症状是「恢复了但任务没跑」（本实现第一版就是这么错的，transport 套件当场挂住）。
-                // ⚠️ 读失败**不改变既有行为**：这道闸只负责「明知已终态就别跑」，不负责把
-                // store 读取故障升级成「任务起不来」（停机窗口里 store 已 close 是既有场景，
-                // 那条路径的行为由 scheduler 的用例钉着）。
-                let claimed;
-                try {
-                    claimed = (await this.store.get(rec.taskId)) ?? rec;
-                }
-                catch {
-                    claimed = undefined;
-                }
+                const claimed = await readClaimed(this.store, rec);
                 if (claimed && isTerminalTask(claimed)) {
                     // 与 store 对齐再返回：外层 finally 会拿 `rec` 落一次 outcome，
                     // 不同步的话会用**陈旧副本**把取消覆盖回 queued（任务从此既不起跑也不终态）。
@@ -921,6 +988,19 @@ export class AsyncRunner {
                     Object.assign(rec, claimed);
                     return;
                 }
+                // 取消意图闸（2026-10-13 ref-run-root-close）：cancel 已在收尾这条任务（意图先于落库可见、且
+                // 在还有活着的 #execute 时不会被摘除）⇒ **绝不起跑**。没有它时这条缝真实存在：
+                // 上面的 readClaimed 读到的是 cancel 落库前的快照，这里照常置 running 落库，
+                // 就把 cancelled 覆盖回去 —— 任务取消后照常执行、webhook 双发。
+                // 记账归 cancel：登记 #cancelSettled（覆盖面从 queued 补齐到这一支 —— 被并发
+                // 恢复路径派发出来的 suspended 取消也走这里），本趟 finally 只走低层清理。
+                if (this.#cancels.has(rec.taskId)) {
+                    this.#cancelSettled.add(rec.taskId);
+                    this.#cancels.delete(rec.taskId);
+                    rec.status = 'cancelled';
+                    rec.error = abortedError();
+                    return;
+                }
                 // 在飞句柄**先**登记（在任何 await 与状态写之前）：cancel 的中断窗口从这里闭合
                 this.#runAborts.set(rec.taskId, new AbortController());
                 rec.status = 'running';
@@ -955,116 +1035,51 @@ export class AsyncRunner {
                     // 与任务 spec 里可能自带的那个**叠加**而不是覆盖（composeTraceEvents 的同一份理由）：
                     // 两边都要收到 —— 覆盖会让其中一条静默失聪。
                     const bridgeTraceEvents = composeTraceEvents((e) => this.#streams.push(rec.taskId, e), rec.spec.options?.onTraceEvent);
-                    const callOpts = {
-                        ...(rec.spec.options ?? {}),
-                        // HITL 恢复段**不注入 session**（2026-09-20，spec §10 当日条）：恢复段的
-                        // rec.spec.messages 是挂起段落库的 suspendedMessages —— 已含 loadSession
-                        // 拼入的完整会话历史，再注入会让 run 层把 store 历史**再 prepend 一遍**
-                        // （历史翻倍、token 复利）；且成功后 appendSession 会把整段扩展历史
-                        // （含未决 tool_use 的 assistant）写进会话 —— 违反「只存对话轮次」不变量，
-                        // 留下孤立 tool_use + 连续两条 assistant，下一轮该会话直接撞 API 400。
-                        // 恢复段的会话回写由本类在成功后补写（见 #appendResumedSession）。
-                        ...(!isResume &&
-                            rec.spec.options?.sessionId !== undefined &&
-                            this.sessionStore !== undefined
-                            ? { session: { store: this.sessionStore, id: rec.spec.options.sessionId } }
-                            : {}),
-                        // 显式 undefined ≠ 不传（exactOptionalPropertyTypes）：无幂等键时不落这个键
-                        ...(rec.idempotencyKey !== undefined ? { idempotencyKey: rec.idempotencyKey } : {}),
-                        ...(rec.spec.options?.client !== undefined
-                            ? { client: rec.spec.options.client }
-                            : this.client !== undefined
-                                ? { client: this.client }
-                                : {}),
-                        // 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 的入站关联机制）——「挂起段 → 恢复段 → …」在观测后端连成一条链。
-                        // 判定依据：本段是续跑段（isResume）且已有上一段 runId；首次执行两者皆无。
-                        ...(isResume && rec.runId !== undefined
-                            ? { traceContext: { traceId: rec.runId } }
-                            : {}),
-                        rethrow: false, // 硬失败也以 failed 记录落库
+                    // 装配交给引擎的选项（三条口径：续跑段不注入 session / 无值不落键 /
+                    // 续跑段的 trace 挂到上一段 runId）—— 逐条理由在 `run-call-options.ts` 里
+                    const callOpts = buildRunCallOptions({
+                        rec,
+                        isResume,
+                        sessionStore: this.sessionStore,
+                        client: this.client,
                         signal: combined,
-                        // 记账事件 → 本任务的流（见上面 bridgeTraceEvents 的注释）
-                        ...(bridgeTraceEvents !== undefined ? { onTraceEvent: bridgeTraceEvents } : {}),
-                    };
+                        bridgeTraceEvents,
+                    });
                     try {
                         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 === 'suspended' && out.result.suspendedMessages) {
-                            // HITL 挂起：扩展后的消息历史（末尾是含未决 tool_use 的 assistant 消息）
-                            // 与待决清单、挂起时刻一起落库 —— approve / 惰性超时 / 重启后都靠它们。
+                            // HITL 挂起：记录怎么改、事件簿记按 `eventsDelivered` 分档、以及「用户输入快照
+                            // 必须在 `rec.spec` 被覆盖**之前**取」那条顺序事实 —— 全在 `run-outcome.ts`。
                             // 槽位照常释放（finally）、onFinished 不触发（#execute 的出口判断）、
                             // finishedAt 不置（下面 finally 里按状态跳过）：它不是终态。
-                            rec.status = 'suspended';
-                            // 「本轮用户输入」快照必须在 overwrite **之前**取 —— 此刻 rec.spec.messages
-                            // 还是原始输入；恢复段成功后由 #appendResumedSession 拿它 + finalText 补写会话。
-                            // 只在首个挂起段快照（!isResume）：恢复段再挂起时 spec.messages 已是
-                            // 扩展历史（含会话前缀），拿它当「用户输入」就错了 —— 原快照仍在，不能丢。
-                            if (!isResume &&
-                                rec.spec.options?.sessionId !== undefined &&
-                                this.sessionStore !== undefined) {
-                                this.sessionInputs.set(rec.taskId, rec.spec.messages);
-                            }
-                            rec.spec = { ...rec.spec, messages: out.result.suspendedMessages };
-                            rec.pendingApprovals = out.result.pendingApprovals;
-                            rec.suspendedSince = Date.now();
-                            // 挂起原因（2026-09-28 ①）：从结果形状里取，**不写死** ——
-                            // 写死成 'approval' 会让将来新增的挂起原因在落库这一步被悄悄改写成审批。
-                            rec.suspendedReason = out.result.suspendedReason;
-                            // 目标时刻（时间挂起才有）—— 同上，从结果形状里取，不按原因反推
-                            rec.wakeAt = out.result.wakeAt;
-                            // 挂起读数（纪律①）：与落库**同一个分支**登记，不另起一处判断
+                            const snapshot = applySuspendedOutcome(rec, out.result, out.result.suspendedMessages, {
+                                isResume,
+                                hasSessionStore: this.sessionStore !== undefined,
+                                now: Date.now(),
+                            });
+                            // 顺序承重：快照先落地，`markSuspended` 再登记（后者读 status / suspendedReason /
+                            // wakeAt —— 三样都刚被上一行写好；挂起读数纪律①：与落库同一个分支登记）
+                            if (snapshot !== undefined)
+                                this.sessionInputs.set(rec.taskId, snapshot);
                             this.#approvals.markSuspended(rec);
-                            // 事件簿记（2026-09-28 ⑥ 复审收口）：**注入过**就清 —— 事件已在挂起历史里
-                            // （suspendedMessages 含注入的 user 消息），簿记留着会让下次续跑**重复注入**
-                            // （真探针实证过：模型看到同一事件两次）。没注入（续跑入口的再挂起出口在
-                            // 注入点之前返回）则必须留住 —— 清掉就是丢事件。判据是结果上的
-                            // `eventsDelivered` 位，不是「是不是挂起」这个粗粒度。
-                            if (out.result.eventsDelivered)
-                                rec.pendingEvents = undefined;
                         }
                         else {
                             // 取消：机制与 `runTimeoutMs` 一字不差（同一条 abort signal），**意图**不同 ——
-                            // 状态按意图落（超时 = failed、人取消 = cancelled）。意图从 `#cancels` 取，
-                            // 不从 signal 反推：同一条 signal 有三个来源（调用方 / 超时 / 取消）。
+                            // 意图从 `#cancels` 取，不从 signal 反推：同一条 signal 有三个来源
+                            // （调用方 / 超时 / 取消）。记录的改法与「事件簿记在终态无条件清」那条（以及它
+                            // 与挂起分支刻意不同的理由）都在 `run-outcome.ts` 的 `applyTerminalOutcome` 里。
                             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.suspendedSince = undefined;
-                            rec.suspendedReason = undefined;
-                            rec.wakeAt = undefined;
-                            // 事件簿记（2026-09-28 ⑥）：**终态没有第二次机会** —— 这条记录不会再被续跑，
-                            // 事件留着也没有注入点，清掉。
-                            // ⚠️ 判据与挂起分支**刻意不同**（复审第二轮把这里的注释改成真话，原先写的是
-                            // 「跑通到非挂起出口 ⇒ 引擎已把它们注入消息流」—— 那句在注入点**之前**就被
-                            // 中止/失败的出口上不成立）：挂起分支按 `eventsDelivered` 判（注入过才清、
-                            // 没注入要留 —— 下次续跑补上），这里无条件清。
-                            // 于是「恢复段在注入之前就 abort（取消 / runTimeoutMs）或整段失败」的那些终态，
-                            // 其事件**不会**进历史 —— 既成事实，不假装「已注入」；发件方从记录的终态与
-                            // error 看得到这条 run 的下场（要重试就重新提交一次：事件不跨终态重放）。
-                            rec.pendingEvents = undefined;
+                            const settled = applyTerminalOutcome(rec, out, { cancelled, isResume });
                             // 离开挂起态（读数纪律②）：两处恢复路径负责「还没跑到终态」的那一半，
-                            // 这一支负责「跑到了终态」的那一半（兜底：恢复失败也会落到这里）
+                            // 这一支负责「跑到了终态」的那一半（兜底：恢复失败也会落到这里）。
+                            // ⚠️ 顺序承重：先改记录（上一行按 `run.status` 落状态），再除名。
                             this.#approvals.unmarkSuspended(rec.taskId);
-                            // HITL 恢复段 + 会话：本段没把 session 交给 run 层（见上面 callOpts 注释），
-                            // 会话回写由 runner 自己补 —— 口径与 run.ts 的 appendSession 一致。
-                            if (isResume && out.run.status === 'succeeded') {
+                            if (settled) {
+                                // HITL 恢复段 + 会话：本段没把 session 交给 run 层（见上面 callOpts 注释），
+                                // 会话回写由 runner 自己补 —— 口径与 run.ts 的 appendSession 一致。
                                 await this.#appendResumedSession(rec, out.result.finalText);
                             }
                         }
@@ -1128,17 +1143,23 @@ export class AsyncRunner {
             await Promise.resolve().then(() => this.store.save(rec));
         }
         catch (error) {
-            // 落库失败不遮罩主流程：任务结果仍在内存记录里可见。
-            // 但它**必须有人能收到** —— 宿主无法自己发现这件事（见 onPersistError 的注释）。
-            if (this.onPersistError) {
-                try {
-                    // 传快照（与 #notifySinks 同纪律）：回调拿到的是「此刻的记录」，之后记录
-                    // 再被推进不会串进回调持有的引用（引用语义 store 下，活引用 = 回调能改写库里的记录）
-                    this.onPersistError({ record: { ...rec }, error, phase });
-                }
-                catch {
-                    /* 观测是辅助动作：回调抛错不得影响 run（与 onUnpricedModel 同口径） */
-                }
+            this.#reportPersistError(rec, error, phase);
+        }
+    }
+    /**
+     * 落库失败的上报口（`#safeSave` 与 `cancel` 的临界段共用，2026-10-13 ref-run-root-close 抽出）。
+     * 落库失败不遮罩主流程：任务结果仍在内存记录里可见。
+     * 但它**必须有人能收到** —— 宿主无法自己发现这件事（见 onPersistError 的注释）。
+     */
+    #reportPersistError(rec, error, phase) {
+        if (this.onPersistError) {
+            try {
+                // 传快照（与 #notifySinks 同纪律）：回调拿到的是「此刻的记录」，之后记录
+                // 再被推进不会串进回调持有的引用
+                this.onPersistError({ record: { ...rec }, error, phase });
+            }
+            catch {
+                /* 观测是辅助动作：回调抛错不得影响 run（与 onUnpricedModel 同口径） */
             }
         }
     }
@@ -1159,7 +1180,7 @@ export class AsyncRunner {
                     timer = setTimeout(() => {
                         onTimeout?.();
                         // TimeoutError（code='timeout'）：classifyError 归 `timeout` 一类账 ——
-                        // 与引擎工具超时 / MCP 桥兜底同口径（spec §10 2026-09-17 ②「超时自成一类」）。
+                        // 与引擎工具超时 / MCP 桥兜底同口径（spec §10 2026-09-17 ref-timeout-error-type「超时自成一类」）。
                         // 此前这里是裸 Error → 落 unknown，同一件事在异步宿主这条路径上记成另一本账。
                         reject(new TimeoutError(`task ${taskId} 执行超时（${this.runTimeoutMs}ms）`));
                     }, this.runTimeoutMs);