berry-agent 0.1.0-alpha.1

package/dist/conversation/driver.js

@@ -0,0 +1,922 @@
+/**
+ * ConversationDriver 本体（02 §2.3 对话本体 / 04 §2-§4 运行时骨架）——
+ * loop 的驱动侧：组装回调注入 agent loop、durable 接线、turn 级 auto-retry
+ * （04 §3.3）与溢出兜底（04 §3.4）。
+ *
+ * 批 11c 纵切面：durable 接线 + runTurns 重试循环 + 溢出兜底 + 待发队列的
+ * 通道机制面（busy→steer 顶注 / idle→followUp 起跑 / 搁浅件种子续跑）。
+ * 批 11d 纵切面：三通道路由正式收口（inject 停摆落账不唤醒 / busy steer
+ * 合批 / 唤醒预算批消费位记账）+ 取消模型（dismantled 停摆旗标 + per-run
+ * 控制器——abort()）+ resume 冷启动续接（构造折叠 + 重播种 + header resume）。
+ * 批 11e 纵切面：open 域工具与审批三件装配（assembleOpenTools 消费）。
+ * 批 11f 纵切面：环境披露段注入（04 §11）+ onRunSettled 终态回调（ctx.agent
+ * 服务订阅面）+ 子代理审批挂起通知注入面（04 §10）；host 装配根接线归批 12。
+ * 批 v 纵切面（2026-09-11 运行时断言批）：「模型可见即已记录」请求关口总拍
+ * （05 §1.2 对拍断言）——onTransformContext 入口 timeline 活数组 vs 日志独立
+ * 重建恒开对拍，红 = 驱动 bug fail-loud（暗通道/翻译失真两类病灶）。
+ *
+ * 重试编舞（04 §3.3 六条）：
+ *  ① 遮蔽 + 落账一次 append——surfaceOp 随 llm/retry(phase=scheduled) 信封；
+ *     区间 = [错误 assistant seq, durable 高水位]（伴生组与垫底 turn/end 一并
+ *     盖住，防悬空 toolUse 进续入上下文）；
+ *  ② 重播种走私有路径（reseedTimeline）——不清 deliverMeta、不复位 header 落账
+ *     差分幂等位（header resume 形由 wiring 重建标记承载）；
+ *  ③ 重试循环在 runTurns 内部——run 未终结语义上 isRunning 恒真，零新事件型；
+ *  ④ 退避 = 指数 + 等比半幅抖动，sleep 挂 abort signal（打断即 aborted 落账）；
+ *  ⑤ attempt 计数生命周期 = 单次 runTurns 调用（进入即零、成功返回即弃）；
+ *  ⑥ 只 retry transient 桶（classifyError 注入缺席 = 一切 non-retryable 保守）。
+ * 溢出兜底（04 §3.4）：遮蔽（llm/retry reason=overflow 复用遮蔽信封）→
+ * compactForOverflow → compacted 则重播种续入；名额 1/1 独立分账；注入缺席 =
+ * 溢出直接终态（05 §2.3 门三道第三道的装配面兑现）。
+ */
+import { startRun } from '../agent/index.js';
+import { PendingMessageQueue } from '../agent/index.js';
+import { isStandardMessage, parseEventSource } from '../contracts/index.js';
+import { abortableSleep, retryDelay } from './backoff.js';
+import { DurableWiring } from './wiring.js';
+import { AGENT_PRE_STEP_EVENT, CONTEXT_TRANSFORM_EVENT, DEFAULT_RETRY_POLICY, MAX_CONSECUTIVE_WAKES, SESSION_LIFECYCLE_EVENT, } from './types.js';
+import { reseedTimeline } from './reseed.js';
+import { assertModelVisibleTimeline, degradationMask } from './model-visible.js';
+import { todoSnapshotMessage } from './todo.js';
+import { notifyRunSettled } from './agent-service.js';
+/**
+ * 对话驱动（per-session 实例）。timeline 活数组是投影的镜像缓存（05 §1.3
+ * 单一事实源——每次入口先重播种对齐，不另立第二真相）；durable 落账经
+ * DurableWiring 翻译，活体事件双腿转发（接线腿 + 外部汇腿）。
+ */
+export class ConversationDriver {
+    session;
+    options;
+    wiring;
+    context;
+    /** loop 回调基座（signal 每次入口另注——per-run AbortController 的协作面） */
+    baseConfig;
+    /** 当前入口的 active config（transformContext 取请求时点 model——换装后取新值） */
+    activeConfig;
+    /** 待发队列（三通道暂存——busy steer 顶注 / idle followUp 起跑同池，通道由消费点定） */
+    queue = new PendingMessageQueue();
+    /** 在飞 runTurns（busy 判据 + submit 搭车面） */
+    currentRun;
+    /**
+     * 当前 run 后台道声明位（04 §5——run 级后台性，2026-09-13 全面复盘修复批）：
+     * launch 随起跑 submit 置位、run 结算清位；请求组装期 budgetAdvisory 取值
+     * 器消费（前台 run 恒 false）。纯 run 级内存载体——不落 durable。
+     */
+    runLaneValue = false;
+    /** 当前 run 的协作中止控制器（abort() 触发——streamFn/工具执行/退避睡眠共挂） */
+    activeController;
+    /** 停摆旗标（02 §2.3 取消模型——会话级标记非 run 状态机成员；置位后一切投递转 inject） */
+    dismantledValue = false;
+    /**
+     * 排队 kick 计数（等位中的排队段在飞数——abort() 记忆位的射程判据）：
+     * 大于零 = 本会话仍有等位中的 run，此时无在飞 run 的 abort() 请求有明确
+     * 打断对象（排队段），值得记忆到取位结算后消费。
+     */
+    queuedKickCount = 0;
+    /**
+     * 排队期中止请求记忆位（无在飞 run 时 abort() 置、排队段取位后消费）：
+     * issue watchdog 等「排队期请求打断」的调用方意图不因排队窗丢失——修复前
+     * 排队期 abort() 为 no-op（activeController 尚未出生），run 起跑后预算帽
+     * 执法失效可超额跑完（2026-09-10 全面复盘真缺口修复）。
+     */
+    abortRequestedValue = false;
+    /** 连续后台唤醒计数（04 §4 唤醒预算——批消费位记账；前台 kick 复位） */
+    wakeStreak = 0;
+    /**
+     * a2a 链深内存位（03 §2.2 第十一面回合护栏——e-4 落码裁决：选计数位不选
+     * 血缘回溯，O(1) 受理面单点递推同效）。更新律：人面输入（treatedAsUser
+     * 源经 routeMessage）归 0、plugin: 源归 1、跨会话 send 经 deliverControl
+     * 专径携 depthHint 递推（送话方深度+1）；崩溃重启归零（环物理断链——
+     * 护栏目的已达，不承诺跨进程精确保留）。
+     */
+    a2aDepthValue = 0;
+    /** 全量工具面快照（工具面切换的还原基准——backgroundTools 的对照面） */
+    fullTools;
+    /** 警示面（缺省 stderr——护栏不静默） */
+    warnFace;
+    /**
+     * 重试进行态探针（04 §3.3 注记 seam——批 13a）：退避等待窗内非空、其余
+     * 时点 null；只读外推面 = retryState getter（SDK 心跳载荷唯一线面出口）。
+     */
+    retryProbeValue;
+    constructor(options) {
+        this.options = options;
+        this.session = options.session;
+        // context_transform 词汇自举注册（一词两册幂等——open-tools 同律）：独立
+        // stack（无 bootPlugins）的驱动也要能发射；bootPlugins 预注册 41 词在前，
+        // 已注册词跳过不撞名（EVENT_DUPLICATE 防御）
+        if (!options.dispatch.isRegistered(CONTEXT_TRANSFORM_EVENT)) {
+            options.dispatch.registerEventNames([CONTEXT_TRANSFORM_EVENT]);
+        }
+        // session/lifecycle 词汇自举注册（04 §6 e-2——同上幂等双源）：装配根
+        // boot 前预注册（插件装载期订阅可达）在前，此处兜底独立 stack 形
+        if (!options.dispatch.isRegistered(SESSION_LIFECYCLE_EVENT)) {
+            options.dispatch.registerEventNames([SESSION_LIFECYCLE_EVENT]);
+        }
+        // agent_pre_step 词汇自举注册（03 §2.4 message 层行——批 #99 发射腿）：
+        // 同上幂等双源——goal 件装载期 ctx.on('agent_pre_step') 可达在前，此处
+        // 兜底独立 stack 形（无 bootPlugins 的驱动也要能发射）
+        if (!options.dispatch.isRegistered(AGENT_PRE_STEP_EVENT)) {
+            options.dispatch.registerEventNames([AGENT_PRE_STEP_EVENT]);
+        }
+        // resolveToolOwner 透传（tool/call 载荷 owner 位取数 seam——T9 案一批 t-1）；
+        // 缺席 = 载荷不带 owner（wiring 侧可选带出形）
+        this.wiring = new DurableWiring(this.session, {
+            ...(options.resolveToolOwner !== undefined ? { resolveToolOwner: options.resolveToolOwner } : {}),
+        });
+        this.fullTools = options.tools !== undefined ? [...options.tools] : undefined;
+        this.warnFace = options.warn ?? ((message) => console.error(message));
+        this.context = {
+            ...(options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {}),
+            ...(this.fullTools !== undefined ? { tools: [...this.fullTools] } : {}),
+            messages: this.reseededTimeline(),
+        };
+        this.baseConfig = {
+            streamFn: options.streamFn,
+            model: options.model,
+            ...(options.thinkingLevel !== undefined ? { thinkingLevel: options.thinkingLevel } : {}),
+            convertToLlm: options.convertToLlm,
+            transformContext: this.onTransformContext,
+            preModelRequest: this.onPreModelRequest,
+            getSteeringMessages: this.consumeInRun,
+            getFollowUpMessages: this.consumeInRun,
+            onEvent: this.onLiveEvent,
+        };
+    }
+    /**
+     * 用户输入入口（04 §4——三通道路由细节单源在 routeMessage；本入口只
+     * 组装 user 消息：source 缺省 'user'、backgroundWake 随选项透传；
+     * dedupeKey 同随选项透传 data.dedupeKey——幂等 admit 落账位 05 §3.5）。
+     */
+    submit(content, options) {
+        // session: 前缀 fail-loud 拒（e-4 provenance 盖章单源——05 §3.1）：跨会话
+        // 操控注入的 source 只能由操控受理面铸（controlSourceOf——control.ts），
+        // 本入口不铸——前缀专属受理面铸，结构性杜绝绕受理面伪造送话身份
+        if (options?.source !== undefined && parseEventSource(options.source).kind === 'session') {
+            throw new Error(`submit 不受理 session: 前缀 source（跨会话操控注入走操控受理面——绕受理面伪造送话身份属调用方 bug）`);
+        }
+        const message = {
+            role: 'user',
+            content,
+            timestamp: Date.now(),
+            ...(options?.source !== undefined ? { source: options.source } : { source: 'user' }),
+            ...(options?.dedupeKey !== undefined ? { dedupeKey: options.dedupeKey } : {}),
+        };
+        // 后台道声明位随起跑透传（04 §5 run 级后台性——busy steer 搭在飞 run
+        // 时本位被忽略：车道随起跑 submit，不随搭车件）
+        return this.routeMessage(message, options?.backgroundWake, options?.backgroundLane === true);
+    }
+    /**
+     * 三通道路由单源（submit 与子代理审批挂起通知共用——04 §4）：
+     *  - dismantled 停摆 → **inject**：只落 durable user/message 不唤醒（随下次
+     *    启动 timeline 重播种带入——队列内存态崩即丢，durable 落账是唯一诚实承载）；
+     *  - busy → **steer**：入待发队列（唤醒位随条目透传）+ 搭在飞 run 结算；
+     *  - idle → **followUp**：搁浅件合批消费 + 新输入作种子起跑。
+     * 唤醒预算（04 §4 maxConsecutiveWakes=3 批消费位记账）：超帽唤醒件拒收
+     * （receipt + warn，不静默）；前台输入起跑即复位计数。
+     */
+    routeMessage(message, backgroundWake, backgroundLane) {
+        // a2a 链深更新律（03 §2.2 第十一面回合护栏——e-4）：人面输入归 0（用户
+        // 在场即重置链深）、plugin: 源归 1（插件直唤即第一跳）；session: 源到不了
+        // 这里（submit 已拒 + deliverControl 专径另走）——compaction 等其余非用户
+        // 源不触碰（不是链上事件）
+        const parsedSource = parseEventSource(message.source ?? 'user');
+        if (parsedSource.treatedAsUser)
+            this.a2aDepthValue = 0;
+        else if (parsedSource.kind === 'plugin')
+            this.a2aDepthValue = 1;
+        // inject 通道：停摆期只落账（durable 写点单归接线器——不绕过直写 session）
+        if (this.dismantledValue) {
+            return Promise.resolve({ status: 'injected', seq: this.wiring.appendInjectedUser(message) });
+        }
+        if (this.currentRun !== undefined) {
+            // busy：入列（steer 顶注——唤醒位随条目透传，消费位合批/预算执法）+ 搭车
+            this.queue.enqueue(message, 'steer', backgroundWake !== undefined ? { backgroundWake } : undefined);
+            return this.currentRun;
+        }
+        // idle：搁浅件消费（超帽唤醒件在 consumeBatch 内拒收过滤）+ 新输入
+        const consumed = this.consumeBatch();
+        const newWake = backgroundWake === true;
+        if (newWake && this.wakeStreak >= MAX_CONSECUTIVE_WAKES) {
+            // 新唤醒件拒收：无搁浅余件 → 拒收回执；有搁浅前台件 → 照常起前台 run
+            this.warnWakeRefused();
+            if (consumed.items.length === 0)
+                return Promise.resolve({ status: 'wake-refused', reason: 'wake-budget' });
+            return this.kick(consumed.items.map((item) => item.message), false, false);
+        }
+        const seeds = [...consumed.items.map((item) => item.message), message];
+        // 车道随起跑 submit 声明位（搁浅件批次级近似——04 §5 修复批定形注）
+        return this.kick(seeds, newWake || consumed.wakeTriggered, backgroundLane);
+    }
+    /**
+     * 跨会话操控投递入口（03 §2.2 第十一面 send——e-4 落码裁决：不复用
+     * submit，因 busy 腿 submit 搭车在飞 run 结算，而跨会话调用方要**即席
+     * 回执**不等目标 run 终态）。三通道与 routeMessage 同型判定：
+     *  - 停摆 → inject：durable 落账（回执携 seq）；
+     *  - busy → steer 入列：接 EnqueueReceipt 翻译（drop-oldest 被丢旧件呈报
+     *    droppedMessageId——被丢件有撤回关联键才填，普通件无名不虚构）；
+     *  - idle → followUp 起跑：搁浅件合批 + 新件作种子，fire-and-forget（run
+     *    异常走 warn 面不静默——跨会话调用方已拿到回执，无人 await 这个
+     *    promise）。**不置 backgroundWake**（e-4 落码裁决：a2a 委托是明确
+     *    意图的协作非自激励环——链深帽才是语义护栏；不置位保目标全量工具面）。
+     *
+     * @param depthHint a2a 链深递推值（受理面已算：送话方深度+1 / 插件道 1）——
+     * 本入口单点记账（受理序已过链深帽执法）。
+     */
+    deliverControl(message, messageId, depthHint) {
+        this.a2aDepthValue = depthHint;
+        // inject 通道：停摆期只落账（「随下次启动带入」的 durable 承载）
+        if (this.dismantledValue) {
+            return { status: 'delivered', messageId, seq: this.wiring.appendInjectedUser(message) };
+        }
+        if (this.currentRun !== undefined) {
+            // busy：steer 入列（撤回关联键随条目透传）+ 溢出回执翻译
+            const receipt = this.queue.enqueue(message, 'steer', { id: messageId });
+            if (!receipt.accepted)
+                return { status: 'dropped', reason: 'queue-full' };
+            return receipt.dropped?.id !== undefined
+                ? { status: 'queued', messageId, droppedMessageId: receipt.dropped.id }
+                : { status: 'queued', messageId };
+        }
+        // idle：搁浅件合批 + 新件作种子起跑（fire-and-forget）
+        const consumed = this.consumeBatch();
+        const seeds = [...consumed.items.map((item) => item.message), message];
+        // 跨会话操控不置后台道（e-4 落码裁决语义同 backgroundWake——明确意图的
+        // 协作非后台道编排，04 §5 修复批定形注）
+        void this.kick(seeds, consumed.wakeTriggered, false).catch((error) => {
+            this.warnFace(`操控投递起跑异常（会话 ${this.session.sessionId}）：${String(error)}`);
+        });
+        return { status: 'delivered', messageId };
+    }
+    /**
+     * 在队撤回读面（03 §2.2 第十一面 withdraw）：按撤回关联键移除在队件。
+     * @returns true = 撤到（'withdrawn'）；false = 已出队/从未在队（'delivered'
+     * 语义诚实呈报——停摆清队后同 false）。
+     */
+    withdrawQueued(messageId) {
+        return this.queue.withdraw(messageId) !== undefined;
+    }
+    /** a2a 链深读面（受理面送话方深度解析——03 §2.2 第十一面回合护栏） */
+    get a2aDepth() {
+        return this.a2aDepthValue;
+    }
+    /**
+     * 在队快照透传（e-5 操控收口——interrupt 回执 still_queued 数据源）：
+     * 打断只打断当前 run，在队 steer 件保留在队（下次 followUp 作种子续跑）
+     * ——受理面据此铸「打断后队列余量」呈报。只读零副作用。
+     */
+    queuedItems() {
+        return this.queue.snapshot();
+    }
+    /**
+     * 子代理审批挂起通知（04 §10 审批挂起通知——11f 注入面；子代理机器是
+     * 调用方，one-shot 形态不注入由调用方裁量）：background 子代理触发审批对
+     * 时向父会话注入一条 UserMessage（source='subagent-approval-pending'，
+     * 载荷 = job 名 + 工具名/理由）。三通道与 submit 同型：父 run 在飞走
+     * steer、不在飞走 followUp 起跑。
+     *
+     * 恰一条幂等（04 §10 边界②）：同一审批请求恰注入一次——dedupeKey =
+     * `subagent-approval:<approvalId>`，durable 日志已有同键通知即零动作
+     * （返回原落账 seq）；「被答或 Job 终态后不追加撤回」由调用方遵守
+     * （结算通知随后自愈）。纯信息位（边界①）：通知文案不携带任何应答面，
+     * 应答权钉死用户。
+     */
+    notifySubagentApprovalPending(input) {
+        const dedupeKey = `subagent-approval:${input.approvalId}`;
+        // 幂等扫描：durable 可见事件里已有同键通知 → 零动作（'injected' = 已在
+        // 日志，非新落——回执语义与 inject 通道同形）
+        for (const event of this.session.events()) {
+            if (event.type !== 'user/message')
+                continue;
+            if (event.data.dedupeKey === dedupeKey) {
+                return Promise.resolve({ status: 'injected', seq: event.seq });
+            }
+        }
+        const reason = input.reason !== undefined ? `——${input.reason}` : '';
+        const message = {
+            role: 'user',
+            content: `子代理「${input.jobName}」等待审批：${input.toolName}${reason}（通知仅信息位——审批应答权在用户，请勿代答/代批）`,
+            timestamp: Date.now(),
+            source: 'subagent-approval-pending',
+            dedupeKey,
+        };
+        // 审批挂起通知 = 信息位注入非后台道编排——前台车道（04 §5 修复批定形注）
+        return this.routeMessage(message, undefined, false);
+    }
+    /**
+     * 拆解收尾（02 §2.3 取消模型——停摆旗标置位）：打断在飞 run（per-run 控制器
+     * 协作面）+ 清待发队列（内存态不承诺跨进程——durable 真相只有已进 timeline
+     * 的消息）+ 置位停摆。此后一切投递转 inject（04 §4 第三通道）。
+     */
+    dismantle() {
+        this.dismantledValue = true;
+        this.abort();
+        this.queue.clear();
+    }
+    /** 停摆旗标读面（inject 路由判据——会话级标记非 run 状态机成员） */
+    get dismantled() {
+        return this.dismantledValue;
+    }
+    /**
+     * 协作中止：打断在飞 run（signal 透传流与工具）与退避睡眠（phase=aborted
+     * 落账）。无在飞 run 时若本会话仍有排队 kick（等位中）则记忆请求——排队段
+     * 取位后消费（零 LLM 收场），issue watchdog 等「排队期请求打断」的调用方
+     * 意图不因排队窗丢失；无排队时 no-op（idle 会话 abort 无对象——现状语义）。
+     */
+    abort() {
+        if (this.activeController !== undefined) {
+            this.activeController.abort();
+            return;
+        }
+        if (this.queuedKickCount > 0)
+            this.abortRequestedValue = true;
+    }
+    /** 是否有在飞 runTurns（busy 判据的读面） */
+    get running() {
+        return this.currentRun !== undefined;
+    }
+    /**
+     * 全量工具名快照（批 19c-1——子代理派生面的父面枚举读面：委派预检判据
+     * （全父面）+ 派生面交集的基准源。整形式 = 构造快照（含后续 shape 整形
+     * 后的面——子会话作祖父时以其实际面为基准）；纯对话形 undefined =
+     * 不可枚举（白名单透传——fail-closed 全列）。只读快照不暴露工具体。
+     */
+    get toolNames() {
+        return this.fullTools !== undefined ? this.fullTools.map((tool) => tool.name) : undefined;
+    }
+    /**
+     * 重试进行态只读小面（04 §3.3 注记 seam——批 13a）：退避等待窗内非空、
+     * 其余时点 null。SDK 线协议心跳载荷是该探针的唯一线面出口（03 §10.6 ②）
+     * ——非事件型、不进 durable；装配侧经结构共享消费（RetryProbe 归位
+     * contracts，零 import 边）。
+     */
+    get retryState() {
+        return this.retryProbeValue ?? null;
+    }
+    /** 活体事件双腿：durable 接线腿（同步序即落账序）+ 外部汇腿（channels 信封包装归批 12） */
+    onLiveEvent = (event) => {
+        this.wiring.onEvent(event);
+        if (this.options.onEvent !== undefined)
+            void this.options.onEvent(event);
+    };
+    /**
+     * 模型请求前瀑布分派（03 §2.4 agent_pre_step——批 #99 发射腿）：loop
+     * while 体顶调用（steering 消费与 turn_start 之前——刹停零 dangling turn）。
+     * 刹停 = warn 报备 + 'stop'（run 以 stopReason 'stop' 收 completed）；提醒
+     * 槽暂存 pendingReminders、于同请求的 transformContext 关口注入（瞬态不落
+     * durable）；管线失败沿链传播（fail-closed——context_transform 同律）。
+     */
+    pendingReminders = [];
+    onPreModelRequest = async () => {
+        const input = { sessionId: this.session.sessionId, reminders: [] };
+        const out = await this.options.dispatch.waterfall(AGENT_PRE_STEP_EVENT, input);
+        if (out.stop !== undefined) {
+            this.warnFace(`agent_pre_step 刹停（${out.stop.reason}）——本 turn 不起模型请求`);
+            return 'stop';
+        }
+        if (out.reminders.length > 0)
+            this.pendingReminders = out.reminders;
+    };
+    /**
+     * 请求组装最后关口：信封快照（边界制）在此落账——快照取原始 systemPrompt
+     * （04 §11 快照序钉死：先快照后注入，瞬态注入体不入快照不落日志）。
+     * 环境披露段（04 §11 迁层定形——2026-09-11 cache 经济批 RP1）：五件文本块
+     * 注入消息尾瞬态 UserMessage 族首位（原 systemPrompt 尾拼装废止——git 摘要/
+     * 插件计数/日期三 volatile 件随自主运行日 commit/装载/跨日 churn 杀全部
+     * 前缀缓存；瞬态层每请求重算、不落日志、随请求即弃；缺席/返回 null = 无披露）。
+     * todo 回看注入（05 §1.1 跨 turn 每轮当前全表）：UserMessage 追加于消息
+     * 尾——瞬态层（不进 timeline 活数组不落 durable，llmContext 每请求新建
+     * 零累积）；空表不注入；fold 单源 = durable 日志可见事件（遮蔽感知），
+     * 冷启动 resume 首请求同覆盖。
+     */
+    onTransformContext = async (context) => {
+        // 请求关口总拍（05 §1.2——「模型可见即已记录」收口对拍）：本入口是每次
+        // LLM 请求组装的唯一关口（stream.ts 组装序 convertToLlm → 此处），先对拍
+        // 持久层再注入瞬态层——下方各注入段（插件段/披露段/瀑布尾注）注入于对拍
+        // 之后，属规范既定豁免面不进 v1 射程
+        this.assertTimelineReconstructable();
+        const config = this.activeConfig;
+        if (config !== undefined) {
+            this.wiring.noteRequest({
+                config: {
+                    model: config.model,
+                    ...(config.thinkingLevel !== undefined ? { thinkingLevel: config.thinkingLevel } : {}),
+                },
+                systemPrompt: context.systemPrompt ?? '',
+                toolSchemas: context.tools ?? [],
+            });
+        }
+        // 插件提示词段注入位（批 19a 消费腿——03 §2.5 注册即生效面）：每请求
+        // 重取物化（段集动态；sessionId 透传 builder——每会话懒冻结类段消费，
+        // cache 经济批 ca-2）；披露段已迁瞬态层，本段区 = systemPrompt 会话内
+        // 恒定面的主体；空串/缺席 = 零段跳过
+        const sections = this.options.pluginSections !== undefined ? this.options.pluginSections(this.session.sessionId) : '';
+        let transformed = context;
+        if (sections !== '') {
+            transformed = {
+                ...transformed,
+                systemPrompt: context.systemPrompt !== undefined && context.systemPrompt !== ''
+                    ? `${context.systemPrompt}\n\n${sections}`
+                    : sections,
+            };
+        }
+        // context_transform 瀑布派发（03 §2.4——LLM 请求组装最后关口的插件管线）：
+        // 载荷消息批取拷贝（handler 就地改写不外溢变换前引用）；失败上抛携带
+        // 变换前原批（审计保输入——管线失败语义沿链传播，驱动不加吞）。todo 快照
+        // 注入位在瀑布之后恒最后（05 §1.1「todo 走瀑布最后」——注入序 diff →
+        // recall → todo）
+        const preTransformMessages = transformed.messages;
+        try {
+            const payload = {
+                sessionId: this.session.sessionId,
+                messages: [...preTransformMessages],
+            };
+            const out = await this.options.dispatch.waterfall(CONTEXT_TRANSFORM_EVENT, payload);
+            transformed = { ...transformed, messages: out.messages };
+        }
+        catch (err) {
+            throw Object.assign(err instanceof Error ? err : new Error(String(err)), {
+                originalMessages: [...preTransformMessages],
+            });
+        }
+        // 披露段 + agent_pre_step 提醒 + 预算预警 + goal 轮间沉淀（批 #99 + 批 H
+        // + cache 经济批 RP1）：同属请求组装瞬态层不落 durable；注入序定律（04
+        // §5 H 注单源）= 披露段 → reminders → 预算预警 → goal 沉淀 → todo 恒
+        // 最后（05 §1.1）。提醒槽取后即清（跨请求不残留——一次 pre_step 暂存
+        // 对应一次请求组装）
+        const reminders = this.pendingReminders;
+        this.pendingReminders = [];
+        const transientTail = [];
+        // 披露段注入位（04 §11 迁层定形）：消息尾瞬态族首位——瀑布之后注入
+        const disclosure = this.options.environmentDisclosure?.() ?? null;
+        if (disclosure !== null) {
+            transientTail.push({ role: 'user', content: disclosure, timestamp: Date.now() });
+        }
+        if (reminders.length > 0) {
+            transientTail.push({ role: 'user', content: reminders.join('\n'), timestamp: Date.now() });
+        }
+        // 预算预警注入（04 §5 三档软着陆——瞬态 UserMessage；分族判据 = origin
+        // 会话级两判 + 当前 run 后台道声明位〔修复批 run 级后台性〕，装配位闭包
+        // 铸造，本层只管注入位与序）
+        const advisory = this.options.budgetAdvisory?.(this.runLaneValue) ?? null;
+        if (advisory !== null) {
+            transientTail.push({ role: 'user', content: advisory, timestamp: Date.now() });
+        }
+        const deposit = this.options.goalDeposit?.() ?? null;
+        if (deposit !== null) {
+            transientTail.push({ role: 'user', content: deposit, timestamp: Date.now() });
+        }
+        if (transientTail.length > 0) {
+            transformed = { ...transformed, messages: [...transformed.messages, ...transientTail] };
+        }
+        // todo 快照注入位：null = 空表跳过（从未建表/用户已重置——不打扰上下文）
+        // goal 段升格（03 §10.5）：goalScopeFor 供锚 → fold 边界升格 goal 生命周期
+        // 段（user/message 不重置、跨续跑轮存活）；缺席 = run-scoped 现行为
+        const goalScope = this.options.goalScopeFor?.(this.session.sessionId) ?? undefined;
+        const snapshot = todoSnapshotMessage(this.session.events(), Date.now(), goalScope);
+        if (snapshot === null)
+            return transformed;
+        return { ...transformed, messages: [...transformed.messages, snapshot] };
+    };
+    /**
+     * run 存续期统一取件（loop 两取件点共用——steer 顶注 getSteeringMessages /
+     * 自然停候选 followUp getFollowUpMessages）：消费位合批与唤醒预算执法都在
+     * 此。唤醒批 → streak+1 + 收窄工具面；前台批保持现面（run 内纯前台批不
+     * 复位 streak——复位只认前台 idle 起跑，用户在场才复位预算）。
+     */
+    consumeInRun = () => {
+        const { items, wakeTriggered } = this.consumeBatch();
+        if (wakeTriggered) {
+            this.wakeStreak += 1;
+            this.applyToolFace(true);
+        }
+        return items.map((item) => item.message);
+    };
+    /**
+     * 入口统一 kickoff（04 §4——lane 帽两段形，channels 消息语义批 m-2）：
+     * ① **排队段（不计在飞）**——acquireRunSlot 在场先取位，帽满则挂起等位
+     *   （宿主级 FIFO，闸件在 host/conversation-stack）；submit 回执 promise
+     *   含排队等待（语义 = 起跑延迟，run 结算回执形不变）；排队期
+     *   currentRun 未置位——busy 判据 / interrupt 回执 / 后续消息路由皆读
+     *   已起跑形（冷读闸 M1 裁决「排队不计在飞」的执法位）。取位器缺席 =
+     *   无帽渐进增强（直通零破口）。
+     * ② **起跑段（launch）**——取位成功后进入：streak 记账 / 工具面定形 /
+     *   lifecycle 起拍广播 / currentRun 咬合；run 终态（launch promise 结算）
+     *   后 finally 释放位——「run 终态释放位」（04 §4）。
+     * steer/inject 腿不经本闸：busy 腿入列搭车（routeMessage 直入 queue）、
+     * 停摆腿 durable 落账（routeMessage 直落 inject）——两腿不产生新 run。
+     */
+    kick(seeds, wakeTriggered, backgroundLane) {
+        const gate = this.options.acquireRunSlot;
+        // 缺席直通：零包装零排队（既有「busy 回执 === 在飞 run promise」引用恒等
+        // 与「受理即已落账」同步段不破——渐进增强零破口含同步段）
+        if (gate === undefined)
+            return this.launch(seeds, wakeTriggered, backgroundLane);
+        // 在场同步试位：帽内有位直通（tryAcquire 零微任务边界——受理回执时种子
+        // 落账已完成，投影一致性同缺席形）；终态释放挂 settled 两路（run 回执
+        // promise 引用不变——busy 恒等同律保持）
+        const fast = gate.tryAcquire();
+        if (fast !== undefined) {
+            const settled = this.launch(seeds, wakeTriggered, backgroundLane);
+            void settled.then(fast, fast);
+            return settled;
+        }
+        // 排队段（不计在飞）：帽满挂起等位（宿主级 FIFO）；取位 promise 结算后
+        // 才进起跑段——排队期 currentRun 未置位（冷读闸 M1 裁决执法位）
+        return (async () => {
+            this.queuedKickCount += 1;
+            try {
+                const release = await gate.acquire();
+                // —— 取位后重验三查（2026-09-10 全面复盘真缺口修复）——
+                // 等位期间宿主状态可能已迁移；取位结算不能盲信起跑前快照，重验后再起跑。
+                // ① 停摆/中止重验：排队期 dismantle（finish/dispose/subagent 终态停摆
+                //   同置 dismantledValue）或 abort() 记忆（无在飞时记忆位）则零 LLM
+                //   收场：还位 + 种子转 inject 落账（durable 真相在——「随下次启动
+                //   timeline 重播种带入」与 routeMessage 停摆腿同语义；种子落账序在
+                //   起跑后的 message_end——不起跑则必须转 inject 承载）+ aborted 终态
+                //   回执（run 未起跑的诚实终态）。修复前：dismantle 后已排队 run 取位
+                //   照常起跑烧 LLM——issue 预算帽/日池对排队期 run 完全失效。
+                if (this.dismantledValue || this.abortRequestedValue) {
+                    this.abortRequestedValue = false;
+                    release();
+                    this.persistSeedsAsInjected(seeds);
+                    return { status: 'aborted' };
+                }
+                // ② 单 run 不变量重验（04 §4「帽下串行不合批」执法位）：另一排队 run
+                //   已先取位起跑（currentRun 已置——真闸件 FIFO 连续移交两位时后者必
+                //   见前者置位）则本批不起 run：种子转 steer 入列（消费位 = 在飞 run
+                //   取件点/尾声 drained 续跑）+ 搭车在飞 run 回执 + 立即还位（本单元
+                //   不占帽——在飞 run 持自己的位）。修复前：帽≥2 下同会话双 run 并发
+                //   起跑——currentRun 被覆写（abort 只达其一）+ durable turn 边界记账
+                //   腐坏。注：enqueue 与在飞 run 尾声 drained 判定间存在极窄微任务窗
+                //   ——若搭车件错过 drained，作搁浅件自愈（下次 idle 输入 consumeBatch
+                //   带入——与 steer 正常搁浅同形）。
+                if (this.currentRun !== undefined) {
+                    for (const seed of seeds) {
+                        this.queue.enqueue(seed, 'steer', wakeTriggered ? { backgroundWake: true } : undefined);
+                    }
+                    const ride = this.currentRun;
+                    release();
+                    return ride;
+                }
+                try {
+                    return await this.launch(seeds, wakeTriggered, backgroundLane);
+                }
+                finally {
+                    // run 终态释放位（幂等保护在闸件——release() 双调安全）
+                    release();
+                }
+            }
+            finally {
+                this.queuedKickCount -= 1;
+            }
+        })();
+    }
+    /**
+     * 排队收场种子的 durable 承载（排队段零 LLM 收场配套——2026-09-10 复盘真
+     * 缺口修复）：逐条转 inject 落账保住 durable 真相。种子调用源单源
+     * routeMessage/deliverControl（全 UserMessage）；非 user 形不可达——防御
+     * 丢弃并 warn 报备（不静默）。
+     */
+    persistSeedsAsInjected(seeds) {
+        for (const seed of seeds) {
+            if (isStandardMessage(seed) && seed.role === 'user') {
+                this.wiring.appendInjectedUser(seed);
+            }
+            else {
+                this.warnFace(`排队收场种子非用户消息（role=${String(seed.role)}）——durable 无承载位，丢弃报备`);
+            }
+        }
+    }
+    /**
+     * 起跑段（lane 取位后——原 kickoff 体）：streak 记账（04 §4 批消费位：
+     * 唤醒起跑 +1、前台起跑归零——用户在场即复位预算）；工具面随之定形——
+     * 唤醒 run 收窄、前台全量；登记在飞 promise、结算链第一拍清位（调用方
+     * await 的就是清理后的 promise——resolved 后 running 必已归 false，无
+     * 观察窗口）。
+     */
+    launch(seeds, wakeTriggered, backgroundLane) {
+        if (wakeTriggered)
+            this.wakeStreak += 1;
+        else
+            this.wakeStreak = 0;
+        // 后台道声明位随起跑置位（04 §5 run 级后台性——本 run 存续期请求组装的
+        // 预警分族判据；结算链清位防跨 run 残留）
+        this.runLaneValue = backgroundLane;
+        this.applyToolFace(wakeTriggered);
+        // 记账窗锚（04 §5——批 #99）：settle 时窗扫 [seqAtLaunch, settle) 的
+        // assistant/message 计数；捕获位在种子落账前（seeds 的 user/message 不入窗）
+        const eventsBefore = this.session.events();
+        const seqAtLaunch = eventsBefore.length > 0 ? eventsBefore[eventsBefore.length - 1].seq : 0;
+        // session/lifecycle 起拍广播（04 §6 e-2——fire-and-forget：活体投影不阻塞
+        // run 起跑；监听异常经 dispatch 隔离上报不回传）
+        void this.options.dispatch.emit(SESSION_LIFECYCLE_EVENT, {
+            sessionId: this.session.sessionId,
+            phase: 'run-started',
+            ...(wakeTriggered ? { wake: true } : {}),
+        });
+        const inner = this.runTurns(seeds);
+        const settled = inner.then((result) => {
+            if (this.currentRun === settled)
+                this.currentRun = undefined;
+            this.runLaneValue = false; // 车道随 run 结算清位（单 run 不变量下无跨 run 竞态）
+            this.noteRunSettled(seeds, seqAtLaunch, backgroundLane, result.status);
+            return result;
+        }, (error) => {
+            if (this.currentRun === settled)
+                this.currentRun = undefined;
+            this.runLaneValue = false;
+            this.noteRunSettled(seeds, seqAtLaunch, backgroundLane); // 崩溃路径——status 缺席不虚构
+            throw error;
+        });
+        this.currentRun = settled;
+        return settled;
+    }
+    /**
+     * run 结算记账腿（04 §5 双轨第一腿——批 #99 三入口统一：TUI/webui/issue/
+     * run CLI 全经 launch，一处嵌钩全入口覆盖）：窗扫 durable assistant/message
+     * 计数 + 种子归因单源（kind 判据——'user'/'channel:*' 真人入口 true、
+     * 'schedule' tick 源机器轮 false）。嵌于 settled 链内分支（回执 promise 引用
+     * 恒等律不破）；钩体自防炸（记账失败 warn 不改写 run 终态）。
+     */
+    noteRunSettled(seeds, seqAtLaunch, backgroundLane, status) {
+        if (this.options.onRunSettled === undefined)
+            return;
+        try {
+            let assistantMessages = 0;
+            for (const event of this.session.events()) {
+                if (event.seq > seqAtLaunch && event.type === 'assistant/message')
+                    assistantMessages += 1;
+            }
+            const userInitiated = seeds.some((message) => {
+                if (!isStandardMessage(message) || message.role !== 'user')
+                    return false;
+                // 「用户在场」判据 = 归因 kind（user / channel:* 真人入口）——schedule/
+                // budget-extended/subagent-* 机器注入位 treatedAsUser 虽 true（投影同视
+                // 用户话语——05 §3.1）但不算用户在场（04 §5 唤醒预算复位语义：机器
+                // 轮不复位）
+                const parsed = parseEventSource(message.source ?? 'user');
+                return parsed.kind === 'user' || parsed.kind === 'channel';
+            });
+            this.options.onRunSettled({
+                sessionId: this.session.sessionId,
+                assistantMessages,
+                seqFromLaunch: seqAtLaunch,
+                backgroundLane,
+                userInitiated,
+                ...(status !== undefined ? { status } : {}),
+            });
+        }
+        catch (err) {
+            this.warnFace(`run 结算记账失败（onRunSettled 自防炸——run 终态不受累）：${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * runTurns 本体（04 §3.3 重试循环宿主）：一次调用 = 「起跑 + 若干次重试续入 +
+     * 搁浅件续跑」的完整编舞。attempt 计数生命周期 = 本调用（进入即零）；
+     * transient 与 overflow 名额各自独立分账（04 §3.4 1/1）。
+     */
+    async runTurns(initialSeeds) {
+        const controller = new AbortController();
+        this.activeController = controller;
+        const retry = this.options.retry ?? DEFAULT_RETRY_POLICY;
+        let transientAttempt = 0;
+        let overflowAttempt = 0;
+        /** 终态结算值（finally 面的消费位——onRunSettled 订阅回调载荷） */
+        let settled;
+        try {
+            // 入口重播种：对齐投影（上次失败收场可能已遮蔽尾部——镜像先重建再起跑）
+            this.context.messages = this.reseededTimeline();
+            let result = await this.enterRun(initialSeeds, controller.signal);
+            while (true) {
+                if (result.status === 'failed') {
+                    const assistant = lastErrorAssistant(this.context.messages);
+                    if (assistant !== undefined) {
+                        const bucket = this.options.classifyError?.(assistant) ?? 'non-retryable';
+                        // —— transient 腿（04 §3.3）——
+                        if (bucket === 'transient' && retry.enabled && transientAttempt < retry.maxRetries) {
+                            transientAttempt += 1;
+                            const delayMs = retryDelay(retry, transientAttempt);
+                            this.occludeFailedTail('transient', transientAttempt, retry.maxRetries, delayMs);
+                            this.context.messages = this.reseededTimeline();
+                            // 重试探针窗开（04 §3.3 seam——退避等待期可见；心跳载荷唯一线面出口）
+                            this.retryProbeValue = {
+                                attempt: transientAttempt,
+                                maxAttempts: retry.maxRetries,
+                                nextAt: Date.now() + delayMs,
+                            };
+                            if (!(await abortableSleep(delayMs, controller.signal))) {
+                                // 退避中被取消：phase=aborted 落账；run 终态保持已结算的 failed
+                                this.session.append('llm/retry', {
+                                    attempt: transientAttempt,
+                                    maxAttempts: retry.maxRetries,
+                                    delayMs,
+                                    phase: 'aborted',
+                                });
+                                break;
+                            }
+                            // 窗关：续入即新流（活体层零新事件型——用户看到重跑，探针蒸发）
+                            this.retryProbeValue = undefined;
+                            result = await this.enterRun([], controller.signal);
+                            continue;
+                        }
+                        // —— overflow 腿（04 §3.4：1/1 独立分账；注入缺席 = 直接终态零事件）——
+                        if (bucket === 'overflow' && this.options.compactForOverflow !== undefined && overflowAttempt < 1) {
+                            overflowAttempt += 1;
+                            const delayMs = retryDelay(retry, overflowAttempt);
+                            this.occludeFailedTail('overflow', overflowAttempt, retry.maxRetries, delayMs);
+                            const outcome = await this.options.compactForOverflow(this.session);
+                            if (outcome === 'compacted') {
+                                this.context.messages = this.reseededTimeline();
+                                result = await this.enterRun([], controller.signal);
+                                continue;
+                            }
+                            // nothing（区间不足压无可压）/ failed（摘要通道失败）——续入必再溢出，诚实报败
+                            this.appendExhausted('overflow', overflowAttempt, retry.maxRetries, outcome);
+                            break;
+                        }
+                        // —— 达帽 / 不可重试：只在确有重试账面时落 exhausted（quota/auth 零重试零事件）——
+                        if (bucket === 'transient' && transientAttempt > 0) {
+                            this.appendExhausted('transient', transientAttempt, retry.maxRetries, 'exhausted', assistant.errorMessage);
+                        }
+                        else if (bucket === 'overflow' && overflowAttempt > 0) {
+                            this.appendExhausted('overflow', overflowAttempt, retry.maxRetries, 'exhausted', assistant.errorMessage);
+                        }
+                    }
+                    break;
+                }
+                // 非 failed 收场：completed 且队列有搁浅件（break 时未消费）→ 作种子续跑；
+                // aborted 不续（用户叫停语义——取消模型 11d 正式收口）。空消费防御：
+                // 搁浅件全被预算拒收时不续跑（startRun([]) 会触发无新消息的 LLM 调用）
+                if (result.status !== 'completed')
+                    break;
+                const drained = this.continueConsumption();
+                if (drained.length === 0)
+                    break;
+                result = await this.enterRun(drained, controller.signal);
+            }
+            settled = result;
+            return result;
+        }
+        finally {
+            if (this.activeController === controller)
+                this.activeController = undefined;
+            // 探针随 run 收口蒸发（防御位——aborted/exhausted 各 break 路不悬空）
+            this.retryProbeValue = undefined;
+            // run 终态 = 结算边界（04 §3）：审批对收口（04 §9 turn 界闭合——未决
+            // ask 统一 unavailable；run 打断的在身 ask 已由 signal 链先收 cancel）
+            this.options.settleApprovals?.();
+            // onRunSettled 终态回调（ctx.agent 服务订阅面——03 §2.2；非总线词汇，
+            // 与审批收口同界；异常/上抛路径无终态即零回调）
+            if (settled !== undefined) {
+                notifyRunSettled(this.options.scope, { result: settled, sessionId: this.session.sessionId });
+            }
+            // session/lifecycle 终态拍广播（04 §6 e-2——finally 面恒发：崩溃路径也
+            // 收口〔只报 phase 不虚构终值〕；与 onRunSettled 同界但语义分立——彼系
+            // ctx.agent 订阅面携 RunResult 本体、此系活体投影零结果引用）
+            void this.options.dispatch.emit(SESSION_LIFECYCLE_EVENT, {
+                sessionId: this.session.sessionId,
+                phase: 'run-settled',
+                ...(settled !== undefined ? { status: settled.status } : {}),
+            });
+        }
+    }
+    /** 单次入口 startRun（seeds 空数组 = 纯续入——04 §2 入口两式） */
+    async enterRun(seeds, signal) {
+        const config = { ...this.baseConfig, signal };
+        this.activeConfig = config;
+        try {
+            return await startRun(this.context, config, [...seeds]);
+        }
+        finally {
+            if (this.activeConfig === config)
+                this.activeConfig = undefined;
+        }
+    }
+    /**
+     * 消费位合批（04 §4 合批规则单源）：首件唤醒位 → 唤醒批取全量（合批窗口
+     * ——后续件不辨唤醒/前台全部并入）；首件前台位 → one-at-a-time 取一件。
+     * 预算执法：超帽唤醒件在此拒收过滤（warn 不静默）——kept 空时调用方各自
+     * 空消费防御（followUp 空即收 / 续跑段不起空 run）。
+     */
+    consumeBatch() {
+        if (!this.queue.hasItems())
+            return { items: [], wakeTriggered: false };
+        const items = this.queue.drain();
+        if (items[0].backgroundWake === true) {
+            // 唤醒头触发合批窗口：余件全量并入本批
+            while (this.queue.hasItems())
+                items.push(...this.queue.drain());
+        }
+        const kept = items.filter((item) => {
+            if (item.backgroundWake === true && this.wakeStreak >= MAX_CONSECUTIVE_WAKES) {
+                this.warnWakeRefused();
+                return false;
+            }
+            return true;
+        });
+        return { items: kept, wakeTriggered: kept.some((item) => item.backgroundWake === true) };
+    }
+    /**
+     * 搁浅件续跑消费（runTurns 续跑段专用）：面随本批触发者——唤醒批收窄并
+     * streak+1；前台批复原全量（不复位 streak——复位只认前台 idle 起跑）。
+     */
+    continueConsumption() {
+        const { items, wakeTriggered } = this.consumeBatch();
+        if (wakeTriggered)
+            this.wakeStreak += 1;
+        this.applyToolFace(wakeTriggered);
+        return items.map((item) => item.message);
+    }
+    /**
+     * 工具面切换（04 §4 合批收窄）：唤醒 run = backgroundTools 供应面产出
+     * （**缺席 = 零工具**——「防后台 run 自由动用全部工具」最保守兑现）；
+     * 前台 run = 全量 tools 快照（缺席 = 纯对话形态，摘除 tools 位）。
+     * 请求组装（stream）与工具批执行（tools-batch）都是请求时点读
+     * context.tools——换面即刻生效。
+     */
+    applyToolFace(wakeTriggered) {
+        if (wakeTriggered) {
+            this.context.tools = [...(this.options.backgroundTools?.() ?? [])];
+        }
+        else if (this.fullTools !== undefined) {
+            this.context.tools = [...this.fullTools];
+        }
+        else {
+            delete this.context.tools;
+        }
+    }
+    /** 唤醒预算拒收警示（护栏不静默——warn 面统一文案） */
+    warnWakeRefused() {
+        this.warnFace(`唤醒预算拒收：连续后台唤醒已达 ${MAX_CONSECUTIVE_WAKES} 帽（前台输入复位预算）`);
+    }
+    /**
+     * 遮蔽失败尾（04 §3.3 条 1：遮蔽 + 落账一次 append）：区间 = [错误 assistant
+     * 锚 seq, durable 高水位]，surfaceOp 随 llm/retry(phase=scheduled) 信封携带；
+     * sourceEventSeqs 全列区间 seq（溯源完整性校验）。校验红 = 驱动 bug，
+     * fail-loud 上抛（正门即执法位——05 §2.4 retry 区间合法规约）。
+     */
+    occludeFailedTail(reason, attempt, maxAttempts, delayMs) {
+        const start = this.wiring.lastAssistantSeq;
+        const events = this.session.events();
+        const end = events.length - 1;
+        if (start === undefined || end < start) {
+            // 防御位：错误 assistant 锚缺席（落账序漂移）——遮蔽不成不上重试，fail-loud
+            throw new Error(`retry 遮蔽锚缺席：lastAssistantSeq=${String(start)} 高水位=${end}（wiring 记账与落账序漂移——驱动 bug）`);
+        }
+        const sourceEventSeqs = [];
+        for (let seq = start; seq <= end; seq += 1)
+            sourceEventSeqs.push(seq);
+        this.session.appendWithSurfaceOp('llm/retry', {
+            attempt,
+            maxAttempts,
+            delayMs,
+            phase: 'scheduled',
+            ...(reason !== 'transient' ? { reason } : {}),
+        }, { op: 'replace', start, end }, sourceEventSeqs);
+        // 遮蔽即重建：下一请求 header 落 resume 形（timeline 重建的边界制判据）
+        this.wiring.markRebuildPending();
+    }
+    /** exhausted 落账（达帽放弃——errorMessage 随行；delayMs=0：无实退避发生） */
+    appendExhausted(reason, attempt, maxAttempts, outcome, errorMessage) {
+        this.session.append('llm/retry', {
+            attempt,
+            maxAttempts,
+            delayMs: 0,
+            phase: 'exhausted',
+            errorMessage: errorMessage ?? `retry 放弃：${outcome}`,
+            ...(reason !== 'transient' ? { reason } : {}),
+        });
+    }
+    /** 重播种（04 §3.3 条 2 私有路径）：投影 → timeline 活数组（确定性时间源） */
+    reseededTimeline() {
+        const events = this.session.events();
+        return reseedTimeline(this.session.projection(), (seq) => events[seq]?.time ?? 0);
+    }
+    /**
+     * 请求关口总拍（05 §1.2 对拍断言——恒开无开关）：timeline 活数组（loop
+     * 「入列↔emit」同步对偶维护的投影镜像缓存）vs 事件日志独立重建（投影 →
+     * reseedTimeline——与冷启动 resume / 重试重播种完全同路，两侧不共享中间
+     * 状态）。红 = 驱动 bug fail-loud：模型可见消息未经 durable 落账即入列
+     * （暗通道——含自定义角色零写点位）或落账翻译腿失真。比较 O(n) 与请求
+     * 序列化同阶（convertToLlm 全量转写已是每请求 O(n)）——恒开零边际成本；
+     * 降级掩码从投影原始形判（预算刀截断豁免位——重建形已丢标记，见件注）。
+     */
+    assertTimelineReconstructable() {
+        const events = this.session.events();
+        const projection = this.session.projection();
+        const expected = reseedTimeline(projection, (seq) => events[seq]?.time ?? 0);
+        assertModelVisibleTimeline(this.context.messages, expected, degradationMask(projection));
+    }
+}
+/** timeline 尾扫最后一条错误 assistant（runTurns 重试判定的起点消息） */
+function lastErrorAssistant(messages) {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const message = messages[i];
+        // 先收窄标准消息（CustomMessage.role 是宽 string，静态面可撞标准名）
+        if (!isStandardMessage(message) || message.role !== 'assistant')
+            continue;
+        return message.stopReason === 'error' ? message : undefined;
+    }
+    return undefined;
+}