@zooique/memora 3.0.0 → 4.0.0

package/dist/agent/loop.js

@@ -10,18 +10,47 @@ import { logger } from '../logging/logger.js';
 import { ResultReplacementStrategy, ReplaceRoundsStrategy, DEFAULT_REPLACE_KEEP_RECENT_ROUNDS, } from '../agent/compaction.js';
 import { offloadLargeToolResult } from '../agent/toolResultOffload.js';
 import { deriveDialogueRounds } from '../agent/budget.js';
-import { parseAskCalls, wrapToolResult, isRetryableToolError, } from '../agent/managers/toolCallHelpers.js';
+import { parseAskCalls, wrapToolResult, unwrapToolResultBody, isRetryableToolError, 
+// B4 判据切换：护栏/替身/compress/remember 的 outcome 就地构造用
+blockedOutcome, okOutcome, failedOutcome, } from '../agent/managers/toolCallHelpers.js';
 import { LlmCaller } from '../agent/managers/llmCaller.js';
 import { LoopMetrics } from '../agent/managers/loopMetrics.js';
 import { DefaultDuplicateCallInterceptor } from '../agent/duplicateInterceptor.js';
 import { ToolResultCache, DEDUP_SUBJECT_EXTRACTORS, WRITE_PATH_EXTRACTORS, normalizePathKey, } from '../agent/toolResultCache.js';
 import { createDefaultGuards, GUARD_THRESHOLDS } from '../agent/guardRail.js';
-import { FileExposureLedger, parseReadFileCoverage, formatLedgerStub, shouldEchoLedgerStub, READ_DIGEST_CHARS, } from '../agent/toolLedger.js';
+import { FileExposureLedger, parseReadFileCoverage, formatLedgerStub, formatLedgerStubRange, shouldEchoLedgerStub, READ_DIGEST_CHARS, READ_FILE_NOTICE_PREFIX, } from '../agent/toolLedger.js';
 import { nowIso } from '../utils/time.js';
 import { DEFAULT_L2_STRATEGY } from '../role-pack/strategyResolver.js';
 import { DEFAULT_MAX_ITERATIONS } from '../role-pack/strategyKeys.js';
 import { ToolRunner } from '../agent/toolRunner.js';
 import { detectNeedsPlanning, PLAN_NUDGE_PROMPT } from '../agent/needsPlanning.js';
+import { formatBackgroundTaskNotice, } from '../agent/backgroundTasks.js';
+/** 合法 target 清单（工具描述与错误提示共用此真源，避免文案列举与判据漂移） */
+export const COMPRESS_TARGETS = [
+    'earliest_round',
+    'earliest_steps',
+    'largest_tool_result',
+];
+/**
+ * target → 中文标签（宿主 notice 文案的真源，**穷举映射不做 else 兜底**）
+ *
+ * 穷举而非三元/else：三元在枚举增补时把新值静默落到最后一个旧标签上（说谎），
+ * TS 侧因 `Record<CompressTarget, string>` 穷尽键而在增补时**编译期报错**——
+ * 让「加枚举忘了改文案」变成一道红闸，而不是运行时的一句假话。
+ */
+export const COMPRESS_TARGET_LABELS = {
+    earliest_round: '最早轮次摘要',
+    earliest_steps: '最早执行步骤摘要',
+    largest_tool_result: '最大工具结果摘要',
+};
+/**
+ * 解析压缩目标（非法/缺失降级 `earliest_round`——保持既有行为，不扩大缺省面）
+ *
+ * 单点收口：判据只此一处，工具描述与回传提示的列举均引 `COMPRESS_TARGETS`。
+ */
+function parseCompressTarget(raw) {
+    return COMPRESS_TARGETS.find((t) => t === raw) ?? 'earliest_round';
+}
 /*
  * 职责边界登记（暂不拆分）
  *
@@ -56,7 +85,7 @@ export class AgentLoop {
     opts;
     messages = [];
     maxIterations;
-    /** provider 上下文窗口（原始声明值，默认 120_000）。模型热切换经 setContextWindow 写入。 */
+    /** provider 上下文窗口（原始声明值；缺省 = `AGENT_CONSTANTS.DEFAULT_MAX_CONTEXT_TOKENS`，数字不落账）。模型热切换经 setContextWindow 写入。 */
     providerContextWindow;
     /** **有效上下文窗口** = min(providerContextWindow, strategy.contextLimit>0 ? contextLimit : ∞)。
      *  派生值（非独立真源）：由 #recomputeEffectiveWindow 在「provider 窗口变更」与「角色策略变更」
@@ -143,10 +172,36 @@ export class AgentLoop {
             this.interruptQueue.splice(idx, 1);
         }
     }
-    /** step 边界气口申请统一队列（pause/interject 统一入队，无独立 pauseRequested flag）。
-     *  用户申请的气口（pause/interject）统一入队，_handleInterrupt 在 step 边界消费：
-     *  先注入型（interject → appendUser），后挂起型（pause → yield paused）。 */
+    /** step 边界气口申请统一队列（pause/interject/command-result 统一入队，无独立 pauseRequested flag）。
+     *  消费在 _handleInterrupt：先注入型（interject → appendUser，command-result → appendSystem），
+     *  后挂起型（pause → yield paused）。 */
     interruptQueue = [];
+    /**
+     * 后台任务注册表（可选，装配层注入）
+     *
+     * loop 侧只做三件事，**不碰进程治理**（spawn / 杀树 / 内存护栏全在 skillScriptRunner）：
+     *   ① 注册完成监听 → 自然终态时把结果入队（`kind:'command-result'`），下个 step 边界注入 system 消息；
+     *   ② turn 终态脱管存活进程（不杀，见 detachAll 注释），回流跨 turn 留存；
+     *   ③ Agent 实例终态（close）真杀全部存活任务并注销 exit 兜底钩子（见 shutdownBackgroundTasks）——
+     *      跨 turn 但不跨宿主寿命，边界与 ② 不同；close 窗口赶不上时 exit 钩子同步兜底。
+     * 未注入时这些动作都是 no-op（无后台任务可管），不报错——纯 ToolExecutor 单测场景无注册表。
+     */
+    backgroundTasks;
+    /** 后台任务**自然终态**时通知装配层（由 Agent 在装配期接到事件面上，loop 只发不处理 UI）。
+     *  脱管后 turn 已结束，宿主挂在 turn 生命周期上的推送时机覆盖不到「任务自然跑完」⇒ 缺此
+     *  出口 UI 会显示假活跃。挂注册表 completion listener（notify）单点链，仅 settle 自然终态
+     *  到达；主动 kill 刻意不回调 listener（防同份结果双份消费），不经此事件。 */
+    emitBackgroundTaskSettled;
+    /**
+     * 装配层在装配期注入「后台任务自然终态」发射回调（**仅装配期一次**，非公开 API）。
+     *
+     * 走 Agent 事件面（`backgroundTaskSettled`）而非独立回调字段：与既有宿主事件
+     * （sessionError / contextTruncated / …）同型，宿主 `bindAgentNoticeEvents` 的
+     * 「先 off 再 on」幂等模式天然适用。
+     */
+    setBackgroundTaskSettledEmitter(fn) {
+        this.emitBackgroundTaskSettled = fn;
+    }
     /** 主动提问回调（LLM 调 ask_user 工具时调用，Agent 注入，loop 只回调不处理 UI） */
     onPendingQuestion;
     /** 有效窗口变更回调（Agent 注入）：把 loop 算出的**有效窗口**分发给 loop 之外仍持有窗口拷贝的
@@ -158,6 +213,15 @@ export class AgentLoop {
     strategy = { ...DEFAULT_L2_STRATEGY };
     /** 本 turn 是否已执行过自审查（单次终审：布尔状态，不再需要轮次计数） */
     selfReviewDone = false;
+    /**
+     * 本 turn 是否已在 step 边界挂起（paused）——**turn 终态脱管的判据**（定案锚：ADR-036）。
+     *
+     * 置位点在 `_handleInterrupt` 的 pause 分支、**yield 之前**（宿主 break 会触发
+     * generator finally，时序敏感）；复位点在 `resetTurnState`（两个 turn 入口都调）。
+     * 语义：挂起 = 同 turn 续跑，后台进程继续跑；不挂起的收场（done / interrupted /
+     * error）才是终态，对存活后台进程脱管（不杀，跨轮存活）。
+     */
+    pauseBoundaryReached = false;
     /** 本 turn（processUserInput）内是否实际执行过工具步。
      *  自审查的唯一触发门槛：只有多轮 turn（发生过工具调用）才审查，
      *  一遍过的纯文本问答不触发。由 processUserInput 入口重置（续跑 continueAfterPause 保留）。
@@ -369,7 +433,8 @@ export class AgentLoop {
         }
         // 单工具执行器：注入 loop 稳定能力窄面，strategy 经闭包读最新（setStrategy 动态生效）
         this.toolRunner = new ToolRunner({
-            execute: (name, args) => this.opts.toolExecutor(name, args),
+            // 原生 outcome 回调逐跳透传：ToolRunner → opts.toolExecutor → toolExecutor.execute
+            execute: (name, args, emitOutcome) => this.opts.toolExecutor(name, args, emitOutcome),
             builtinTools: opts.builtinTools,
             preExecutionCheck: opts.preExecutionCheck,
             onToolExecuted: opts.onToolExecuted,
@@ -473,6 +538,23 @@ export class AgentLoop {
             throw err;
         }
         finally {
+            // turn 终态后台任务脱管（后台任务跨轮存活方案·脱管定案）：done / interrupted / error / 达到最大迭代
+            // 四条收场路径都经过本 finally ⇒ 调用点唯一。
+            // 判据 = pauseBoundaryReached：挂起是同 turn 续跑（后台继续跑、其回流照常注入），
+            // 不算终态、不脱管。脱管 = 不杀进程（error 路径也不杀）；进程寿命的终点在另一处：
+            // Agent 实例终态 close → shutdownBackgroundTasks 真杀 + exit 钩子同步兜底
+            // （观察点 ⑧ 真机定类后补，方案 §4.2）。
+            if (!this.pauseBoundaryReached) {
+                const bgReport = this.finalizeBackgroundTasksOnTurnEnd();
+                if (bgReport) {
+                    // 收尾报告双通道：chunk 上屏（finally 中 yield 合法——推迟 generator 完成，
+                    // 宿主照常 for-await 消费）+ system 消息进 LLM 历史（真源不因上屏形态漂移）。
+                    // generator.return() 硬关闭路径下 yield 被丢弃不上屏（用户已主动停止），
+                    // system 消息仍写入——报告不因上屏通道状态丢失。
+                    yield { type: 'background_report', content: bgReport };
+                    this.appendSystemMessage(bgReport, { executionTemp: true });
+                }
+            }
             const durationMs = Date.now() - taskStartAt;
             this.metrics.taskTotalDurationMs += durationMs;
             if (taskSucceeded) {
@@ -540,11 +622,149 @@ export class AgentLoop {
     clearPauseRequest() {
         this.cancelPauseEntry();
     }
-    /** 插话（申请入队）：把用户补充输入作为 InterruptRequest{kind:'interject'} 入 interruptQueue。
-     *  与 requestPause（queueInterrupt pause）同为「申请 → 气口生效」——不中断当前 LLM/工具执行，
-     *  只在 step 边界统一消费（先注入型 → appendUser，后挂起型 → yield paused）。 */
+    /**
+     * 插话（申请入队）：把用户补充输入作为 InterruptRequest{kind:'interject'} 入 interruptQueue。
+     * 与 requestPause（queueInterrupt pause）同为「申请 → 气口生效」——不中断当前 LLM/工具执行，
+     * 只在 step 边界统一消费（先注入型 → appendUser，后挂起型 → yield paused）。
+     *
+     * 上限裁决（内核资源不变量，值真源 = LOOP_CONSTANTS.MAX_PENDING_INTERJECTIONS）：待注入插话达上限时
+     * **整条拒收**返回 false（插话是原子思路，截半条 = 语义破坏）；宿主以此返回值做 UI
+     * 提示（webview 预检与其 shared 镜像常量由守卫测试与本常量锁同值）。pause 条目不受
+     * 本上限管辖（软暂停申请是内部控制语义，非用户输入洪流）。
+     *
+     * @returns true=已入队；false=待注入插话已满，本条未入队（调用方不应持久化/上屏）
+     */
     interject(content) {
+        if (this.getPendingInterjections().length >= LOOP_CONSTANTS.MAX_PENDING_INTERJECTIONS) {
+            return false;
+        }
         this.interruptQueue.push({ kind: 'interject', content });
+        return true;
+    }
+    /**
+     * 后台命令完成回流入队（**生产者入口**，由装配层从注册表完成监听器调用）
+     *
+     * 走既有 `interruptQueue`（判别联合队列）新增一个 kind，零新基建：
+     * 与插话同机制（iteration 间检查点消费、挂起/恢复全链路复用），但**异质**——
+     *   - 消费时进 `appendSystemMessage`（系统事件），不进 `appendUserMessage`（不伪装用户发言）；
+     *   - 不占插话满员计数（`interject()` 的容量裁决只数 kind==='interject'）；
+     *   - **跨 turn 留存**（脱管定案，后台任务跨轮存活方案）：turn 终态不丢弃，下个 turn 的 step 边界照常吸收——
+     *     与插话跨 turn 同标准，同性质数据不搞两套生命周期。
+     *
+     * @param content 已格式化的完成通知（含来源标记「后台命令完成」+ 命令 + 输出）
+     */
+    enqueueCommandResult(content) {
+        this.interruptQueue.push({ kind: 'command-result', content });
+    }
+    /**
+     * 装配后台任务注册表（assembler 调用，loop 创建之后）
+     *
+     * 两件职责一次接线，避免装配层散写两处：
+     *   ① 完成监听 → `enqueueCommandResult`（回流通道生产者）；
+     *   ② 持有引用供 turn 终态脱管报告。
+     */
+    setBackgroundTasks(registry) {
+        this.backgroundTasks = registry;
+        registry.setCompletionListener((task) => {
+            const notice = formatBackgroundTaskNotice(task);
+            this.enqueueCommandResult(notice);
+            // 后台自然终局失败结算（METRICS-BGTASK-1 显式闭合 · SCRIPT-2 批次 B3）：
+            // 本路径结构上不经工具结果通道——无 toolCallId、不产 tool_result，B4 判据切换
+            // 碰不到它，不在此显式施工则后台失败对 toolFailureCount 永久不可见。
+            // killed 不经本回调（注册表刻意不回调，防双份消费），只余 completed / timedOut：
+            // timedOut 或退出码非 0 = 执行事实失败，判定式与 run_command 同步路径同源
+            // （toolExecutor 的 commandFailed 同式，改一处必查另一处）。
+            // 即时结算、无 step 归属：metrics 是 loop 实例级累计（无 per-turn 重置），
+            // 脱管后终局照常落账；不产 ToolOutcome——无 toolCallId 可挂（工具结果通道
+            // 只覆盖经 runOne 的同步执行），后台失败经本点直接结算进 metrics。
+            // ⚠️ 口径变更：后台失败由不可见→计入 toolFailureCount，数字上升且历史不可比
+            // （论证：docs/方案-工具结果status字段化-20261006.md §三批次表 B3、§七）。
+            // task.result 类型可选，但自然终态必有（注册表 settle 先赋值后同步 notify），
+            // 判空即跳过、不计失败。
+            if (task.result && (task.result.timedOut || task.result.exitCode !== 0)) {
+                this.metrics.toolFailureCount++;
+            }
+            // 终态同时出宿主面（阶段二补漏 · 见方案文档 §5.2）：脱管后 turn 已结束，
+            // 宿主周期性推送（step_boundary / background_report / kill 后回推）覆盖不到
+            // 「turn 结束后任务自然跑完」⇒ UI 会一直显示「运行中」。经 Agent 事件面转发
+            // （走既有 TypedEventEmitter，与 bindAgentNoticeEvents 的 off/on 幂等模式对齐），
+            // **不新增注册表 listener**。主动 kill 不经此回调（注册表刻意不回调，防双份消费）。
+            this.emitBackgroundTaskSettled?.(task);
+        });
+    }
+    /**
+     * 后台任务只读快照（宿主 UI 出口 · 见 `docs/方案-后台任务可见性与kill入口-20261004.md` §2.1）
+     *
+     * 纯透传注册表 `list()`——投影已剥离 `killNow` / `peek` 进程句柄，宿主无从触碰进程。
+     * 注册表未装配（后台能力未启用 / 装配期之前）返回空数组，不抛。
+     */
+    getBackgroundTasks() {
+        return this.backgroundTasks?.list() ?? [];
+    }
+    /**
+     * 终止后台任务（宿主 UI 出口 · 同上 §2.1）
+     *
+     * 纯透传注册表 `kill()`：先取已捕获输出快照再走杀树原语，随后回读终态投影。
+     * 任务不存在 → `null`（`kill` 与 `get` 对未知 taskId 同为 null，无需二次判空）。
+     *
+     * ⚠️ 主动 kill 不触发回流——输出已直接返回调用方，再回流一次会让 LLM
+     * 收到同一份结果的第二份副本（重复消费）。
+     */
+    killBackgroundTask(taskId) {
+        if (!this.backgroundTasks)
+            return null;
+        // kill 对未知 taskId 返回 null 时 get 同样为 null，无需二次判空（防冗余分支）
+        this.backgroundTasks.kill(taskId);
+        return this.backgroundTasks.get(taskId);
+    }
+    /**
+     * Agent 实例终态收割（**唯一调用点 = `Agent.close`**）：真杀全部存活后台命令任务
+     * 并注销其 exit 兜底钩子。
+     *
+     * 纯透传注册表 `shutdown()`，判据不复制。与 turn 终态 `finalizeBackgroundTasksOnTurnEnd`
+     * 的边界见注册表 `detachAll / shutdown` 注释：跨 turn 存活是刻意语义，实例销毁后
+     * 任务不可寻址，留着只能是 OS 层孤儿（观察点 ⑧ 真机实锤）。
+     *
+     * 不产 `background_report`、不推 UI 快照——宿主正在退出，界面与回流都已无消费方。
+     * 注册表未装配返回 0，不抛。
+     *
+     * @returns 实际收割的 running 任务数
+     */
+    shutdownBackgroundTasks() {
+        return this.backgroundTasks?.shutdown() ?? 0;
+    }
+    /**
+     * turn 终态后台任务脱管（定案锚：ADR-036；论证见 `docs/方案-后台任务跨轮存活-20261004.md` §三）
+     *
+     * 判据 = 调用方传入的「本 turn 已收场」（挂起不算终态，见 `pauseBoundaryReached`）：
+     * done / interrupted / error / 达到最大迭代 四条收场路径统一经此，调用点唯一
+     * （`_runWithSlo` 的 finally）。
+     *
+     * 此处只做脱管（detach）——把存活任务移出跟踪，**不杀进程、不丢未消费的 command-result**。
+     *
+     * 为什么不杀：turn 是「一问一答」的**归档单元**，不是进程的容器。进程属于**会话**，
+     * 活过 turn 是应有语义（Claude Code 的后台任务同样活到进程退出）。真机实锤过一个反例：
+     * 用户起 `ping -n 90`，turn 仅 6.3 秒结束就把进程杀了，UI 底部条从「运行中」变「已终止」
+     * 而用户从未点过——「后台」名不副实，用户视角完全不可理解。
+     *
+     * 为什么不丢 command-result：回流与插话性质相同（外部产生的事实、显式一条消息、分别经
+     * appendSystem / appendUser），只封杀 `command-result` 而放行 `interject` ⇒ 同一现象
+     * 两套标准 = 违反 SSOT；且 turn 内跑的 command-result 走的就是同一条通路（`_handleInterrupt`
+     * → `appendSystem`），**机制在 turn 边界突然失效是一致性缺口，不是保护**。
+     *
+     * 跨 turn 留存的边界（如实写）：`interruptQueue` 挂在 Agent 级单例 `loop` 上
+     * （Agent 关闭即销毁）；`MAX_PENDING_COMMAND_RESULTS=3` 只限**每步注入条数**（防一次性
+     * 灌爆上下文），**不限队列总量**——队列条数与注册表终态条目目前都无 GC，是已登记的
+     * 设计缺口（真机出现症状再立项，不在本次提前加机制）。
+     *
+     * @returns 脱管报告文本（null = 无后台任务，纯问答 turn 的常态——不产 chunk 不写 system 消息）
+     */
+    finalizeBackgroundTasksOnTurnEnd() {
+        const detached = this.backgroundTasks?.detachAll() ?? [];
+        if (detached.length === 0)
+            return null;
+        const detail = detached.map((t) => `- ${t.taskId}（仍在运行）：${t.command}`).join('\n');
+        return `[本轮结束 · 后台任务继续运行] 本轮结束时有 ${detached.length} 个后台命令在运行，已转为后台常驻（本轮不终止；正常退出 VS Code 时随扩展终止，崩溃/被强杀除外）。结果不会自动进入上下文：你可以在后续任意一轮用 kill_command 传入该 taskId 取回截至当时的输出。\n${detail}`;
     }
     /** 删除待注入的插话（宿主 UI 层用户后悔）。与 interject 对称，在 step 边界消费前可安全删除。
      *  委托 interruptQueue 中 interject 条目的索引。
@@ -629,6 +849,8 @@ export class AgentLoop {
         // 但 processUserInput 在 resetTurnState 之后会重判设值（续跑入口不复用因此不重判）
         this.planNeedsNudge = false;
         this.planNudgeInjected = false;
+        // 挂起标记复位：续跑入口（continueAfterPause）也走本方法，复位后本段跑到底即终态
+        this.pauseBoundaryReached = false;
     }
     /** 重置 askLimit 计数（turn 入口）：仅 processUserInput 调用，continueAfterPause 不动，
      *  保证暂停-续跑同属一次用户输入、提问次数跨续跑累计（askLimit 语义：按输入打扰防刷）。 */
@@ -694,9 +916,19 @@ export class AgentLoop {
         // LLM 返回 done（纯文本完成）期间用户 interject() 入队的补充输入，若直接 return false 会被静默丢弃；
         // 消费并继续迭代，下一轮 LLM 必看到插话内容。委托 _consumeInterjects（SSOT）。
         // 主要消费发生在 _handleInterrupt（迭代开始前），此处覆盖「LLM 在收尾轮执行期间插话」的窗口。
+        //
+        // ⚠️ 后台回流（command-result）**同样**在此消费，理由与插话同源但多一层：
+        // 收尾轮期间完成的后台命令若随 turn 结束被丢弃，agent 就永远拿不到自己起的任务的输出
+        // ——LLM 会带着「任务大概在跑」的**错误信念交付答案**（进程虽已脱管继续跑，但结果永远不回流）。
+        // 故有后台结果就再跑一轮，让它看到。
         const consumedCount = this._consumeInterjects(this.interruptQueue);
+        const consumedResults = this._consumeCommandResults(this.interruptQueue);
+        // ⚠️ 只清 interject：**不清 command-result** —— 限量注入（MAX_PENDING_COMMAND_RESULTS）
+        // 意味着本轮可能只投了前 N 条，剩下的必须**留队**等下个 step 边界续投；这里一并清掉
+        // 就等于「限量」退化成「截半丢弃」。turn 终态**也不再清**（脱管定案，见
+        // `finalizeBackgroundTasksOnTurnEnd`）——跨 turn 留存是刻意语义，不是遗漏。
         this.interruptQueue = this.interruptQueue.filter((r) => r.kind !== 'interject');
-        return consumedCount > 0;
+        return consumedCount > 0 || consumedResults > 0;
     }
     /**
      * 自审查注入判定（emit selfReview 通知与注入 SELF_REVIEW 提示共用单一真理源）。
@@ -760,11 +992,46 @@ export class AgentLoop {
         }
         return count;
     }
-    /** 中断检查：step 边界统一消费 interruptQueue（pause + interject）+ 硬中止检查。
+    /**
+     * 消费注入型**系统事件**条目（command-result → appendSystemMessage）
+     *
+     * 与 `_consumeInterjects` 严格分开而非合并成「消费所有注入型」：
+     * 两者的注入通道（user / system）、role 语义、容量裁决（插话占满员名额 / 回流不占）不同；
+     * **生命周期 = 跨 turn 留存**（turn 终态不丢弃，下个 turn 的 step 边界照常吸收，见 finalize 注释）。
+     * 即便如此仍须分开：通道与容量判据各异，合并成一个泛化遍历等于把判据摊平到 if 分支里
+     * ——将来任一判据变化都要在同一段代码里翻找，正是「同一语义两套判定」的开始。
+     * 故：两个方法，各守一条通道。
+     *
+     * **限量注入**（`MAX_PENDING_COMMAND_RESULTS`）：回流是已发生的事实、不可拒收，
+     * 只能限量。每步只注入 N 条，其余留队列等下个 step 边界——避免 N 个后台任务同时完成时
+     * 一次性灌爆上下文。
+     *
+     * `executionTemp: true` —— 回流是**本轮执行期事件**（进程已结束、结果已交付），
+     * 下一轮闭环入口由 `cleanExecutionTemporary` 清掉，不进历史上下文。
+     *
+     * @param reqs 待消费的申请列表（只读遍历，不修改）
+     * @returns 消费的条目数
+     */
+    _consumeCommandResults(reqs) {
+        const cap = LOOP_CONSTANTS.MAX_PENDING_COMMAND_RESULTS;
+        let count = 0;
+        for (const req of reqs) {
+            if (req.kind !== 'command-result')
+                continue;
+            if (count >= cap)
+                break; // 超量留队，下个 step 边界续投
+            this.appendSystemMessage(req.content, { executionTemp: true });
+            count++;
+        }
+        return count;
+    }
+    /** 中断检查：step 边界统一消费 interruptQueue（pause + interject + command-result）+ 硬中止检查。
      *
      *  单一气口出口——气口申请统一收在 interruptQueue（无独立 pause flag / 插话数组写位），
-     *  此处统一 queue.splice(0) 取出全部申请，按 kind 分两类处理：
-     *    - 注入型（interject）：先 appendUserMessage，不暂停 loop，让补充输入立刻进入下一轮 step
+     *  此处统一 queue.splice(0) 取出全部申请，按 kind 分三类处理：
+     *    - 注入型·用户意图（interject）：appendUserMessage，不暂停 loop，让补充输入立刻进入下一轮 step
+     *    - 注入型·系统事件（command-result）：appendSystemMessage（executionTemp），
+     *      不暂停 loop；与 interject 的差别只在注入通道与 role 语义（系统事件 ≠ 用户发言）
      *    - 挂起型（pause）：yield {type:'paused'} + return 'paused'，generator 在 step 边界挂起
      *
      *  顺序：先消费注入型 → 再检查挂起型 → 最后硬中止。注入型优先是为了让补充输入在 pause 生效前
@@ -774,8 +1041,10 @@ export class AgentLoop {
     async *_handleInterrupt(signal) {
         // 统一取出全部气口申请（queue.splice(0) 原子消费，消费后队列为空）
         const reqs = this.interruptQueue.splice(0);
-        // ① 先处理注入型气口（interject → appendUserMessage）——不暂停 loop，让补充输入立刻生效
+        // ① 先处理注入型气口（interject → appendUserMessage；command-result → appendSystemMessage）
+        //    ——不暂停 loop，让补充输入 / 后台结果立刻进入下一轮 step
         this._consumeInterjects(reqs);
+        this._consumeCommandResults(reqs);
         // ② 后处理挂起型气口（pause → yield paused）——如果队列里有 pause 申请，在 step 边界挂起
         // ⛔ 生命周期契约：yield paused 后本 generator 立即 return 结束，
         // **不再产出任何后续 chunk**（挂起即本流结束，续跑靠宿主另起 resumeExecution 新流）。
@@ -784,6 +1053,11 @@ export class AgentLoop {
         // 导致"暂停态输入补充"被误路由进 interject 排队而无人消费（卡死坑）。
         if (reqs.some((r) => r.kind === 'pause')) {
             // pause 消费后 clearPauseRequest 已由 splice(0) 自动完成——无需额外清 flag
+            // 挂起**不是** turn 终态（后台任务跨轮存活方案）：同 turn 续跑，后台进程应继续跑、其回流照常注入。
+            // 标记必须在 yield 之前置位——宿主在 paused chunk 处 break 会让 generator 停在
+            // 这个 yield 上并触发 finally（runIterationLoop 的收割判据），置位晚了就会
+            // 把「续跑」误判成「终态」而错杀后台进程。
+            this.pauseBoundaryReached = true;
             yield { type: 'paused' };
             return 'paused';
         }
@@ -895,10 +1169,10 @@ export class AgentLoop {
      *  比较 active 任务项是否已推进，推进才产 plan_item_boundary（宿主按任务项分组后续事件）。
      *  无任务表（null）或 planItemId 未变则不产（lastBoundaryPlanItemId 去噪，避免每迭代发一条空边界）。
      *
-     *  **检出时机 = 迭代开始、LLM 调用之前（硬，2026-09-26 定案）**：边界的语义是「**以下内容**
+     *  **检出时机 = 迭代开始、LLM 调用之前（定案锚 ADR-034）**：边界的语义是「**以下内容**
      *  属于该任务项」，故必须产在它所罩住的思考与工具之前——放在工具落定之后，宿主
      *  「向前找最近边界」的判据对该迭代必然落空 → 每个任务项的首个迭代（思考 + 首批工具）恒掉出
-     *  折叠块，且流式插入后不搬家（「任务项边界产出时机前移」定案）。
+     *  折叠块，且流式插入后不搬家。
      *
      *  语义后果（可接受，非缺陷）：任务表若由本轮某迭代的工具**新建**，该迭代仍留在组外——
      *  那个时刻任务表还不存在。本产出点修的是「任务表在本轮开始前已存在」（续会/预置/上一 turn
@@ -1149,13 +1423,20 @@ export class AgentLoop {
             };
             return 'aborted';
         }
-        // Reflection：本轮工具结果含 retryable 错误时，追加反思提示帮 LLM 聚焦修正而非放弃
-        // slice 按实际执行的 effectiveToolCalls.length 取窗口——若按 LLM 原始请求条数
-        // llmResult.toolCalls.length 切，toolStepLimit 截断时 slice 多看会把上一轮残留的
-        // tool 错误吸进判定窗口，误注入反思提示（坑）
-        const hasRetryableError = this.messages
-            .slice(-effectiveToolCalls.length) // 只看本轮工具结果
-            .some((m) => m.role === 'tool' && isRetryableToolError(m.content));
+        // Reflection：本轮工具结果含 retryable 错误时，追加反思提示帮 LLM 聚焦修正而非放弃。
+        // 判据改读 executeToolCalls **回流的 outcome**（本轮专属，天然不含上一轮残留）——
+        // 原实现按 effectiveToolCalls.length 反切 messages 取窗口，toolStepLimit 截断时切错
+        // 会把上一轮残留的 tool 错误吸进判定窗口，误注入反思提示（坑，随回流一并消除）。
+        //
+        // 重试轴 vs 计数轴分离（两条**正交**轴，判据面都是结构化字段）：
+        //   · 计数轴 —— `_processToolResults` 只读 `outcome.status` 三值（成/败/拦，不编码类别），零文本判据；
+        //   · 重试轴 —— 判「败因是否可重试」，读 `outcome.errorCode`；`isRetryableToolError` 传入
+        //     outcome 时**直接读该字段**，无码才回退解析文本前缀（兼容不入错误码体系的 `ABORTED`
+        //     与造裸文本 outcome 的测试桩）。
+        // `errorCode` 与文本前缀在 `failedOutcomeWithCode` **同源产出一次**，前缀是其渲染面
+        // ⇒ 读字段与读文本同解、不存在漂移。禁再散落手抄前缀：改一处漏一处会让 Reflection
+        // 静默失效（该重试的不再重试，无报错）。
+        const hasRetryableError = execResult.outcomes.some((o) => isRetryableToolError(o));
         if (hasRetryableError) {
             // 反思次数用显式计数器限制，避免 messages 裁剪导致计数失真
             if (this.reflectionCountThisTurn < this.maxReflectionRetries) {
@@ -1343,16 +1624,18 @@ export class AgentLoop {
             for (const tc of toolCalls) {
                 this.appendToolMessage(wrapToolResult(tc.function.name, '[TOOL_ABORTED] 该调用因本轮被中止而未执行。如需其结果，请重新发起。'), tc.id);
             }
-            return { aborted: true };
+            // 一条工具都没跑 ⇒ 无 outcome（重试分类自然为空集，TOOL_ABORTED 本就不可重试）
+            return { aborted: true, outcomes: [] };
         }
         // 实际执行工具步：标记"本 turn 发生过工具调用"，作为自审查触发门槛（多轮 turn 才审查）
         this.toolExecutedThisTurn = true;
         // 标记进入自主工具步（供内核向宿主暴露"可续跑"信号）
         this.inAutonomousStep = true;
         // yield tool_start 并并发发起所有工具执行（不 await，由 Promise.all 统一等待）
-        // blocked 与执行 promise 耦合为同一结构体，每个工具恰好一条。
-        // 每个工具一次 push 一个 { blocked, promise }，结果按工具顺序对齐取出，
-        // 保证护栏拦截标记永不与执行结果错位（避免平行数组各自 push 导致索引漂移）。
+        // 每个工具一次 push 一个 { promise }，结果按工具顺序对齐取出，
+        // 保证拦截事实与执行结果永不错位（避免平行数组各自 push 导致索引漂移）。
+        // B4 判据切换：promise 直接产出 ToolOutcome——护栏/替身在推送点构造 blockedOutcome，
+        // 经 ToolRunner 的由 runOne 返回，loop 内自执行（compress/remember）返回结构化结果。
         const toolExecs = [];
         // 同路径写串行闸：键 = 写工具的规范化目标路径（`WRITE_PATH_EXTRACTORS`），值 = 该路径的写链尾。
         // 为何需要——`write_file` 是「读盘 → 改 → 写盘」，同 step 内并行发起时两次都基于同一份旧快照，
@@ -1420,7 +1703,10 @@ export class AgentLoop {
                     this.appendSystemMessage(`[SEARCH_LIMIT] 联网搜索已达 ${LOOP_CONSTANTS.MAX_WEB_SEARCH_CALLS} 次上限，视为未检索到更多相关内容。` +
                         `请停止调用 web_search，直接基于已有信息继续下一步或作答。`, { executionTemp: true });
                 }
-                toolExecs.push({ blocked: true, promise: Promise.resolve(guardHit.message) });
+                toolExecs.push({
+                    // search_limit 护栏拦截 = 主动挡下 ⇒ blockedOutcome（原因 GuardHit 已带）
+                    promise: Promise.resolve(blockedOutcome(guardHit.reason, guardHit.message)),
+                });
                 continue;
             }
             // 其余护栏命中 → 硬拦回填拒绝文案（blocked 与拒绝 promise 一体推出）；未命中 → 下方正常执行。
@@ -1440,16 +1726,29 @@ export class AgentLoop {
                 }
                 // 拦截归属回喂：read_dedup 的撞墙升级计数只认自己拦的（onExec 分不清拦截归属）
                 this.guardier.notifyBlocked(guardHit.guardId, tc.function.name, tc.function.arguments);
-                toolExecs.push({ blocked: true, promise: Promise.resolve(guardHit.message) });
+                toolExecs.push({
+                    // 其余护栏（ask_limit/write_loop/read_failed/read_dedup）= 主动挡下 ⇒ blockedOutcome；
+                    // read_failed 是唯一「挡下背后藏真失败」的护栏（hasRealFailure 事实随 outcome 带出）
+                    promise: Promise.resolve(blockedOutcome(guardHit.reason, guardHit.message, guardHit.reason === 'read_failed')),
+                });
                 continue;
             }
-            // 台账替身回显分支（摘要顶替，不收口进 guardRail）：原文已压缩/分段脚注时用摘要或引导 offset 续读替代重读。
-            // 保守放行分支：无摘要 / 区间超出覆盖 → 放行（宁可多读一次，不可死锁）。
+            // 台账替身回显分支（不收口进 guardRail）：**原文仍在上下文**时，同参/变体重读用**请求区间
+            // 原文**（切不出则退化顶头摘要）替代；原文已被压缩链清出 → 放行真读（替身是死路，见 stillInContext 注）。
+            // 其余保守放行分支：无摘要 / 区间超出覆盖 → 放行（宁可多读一次，不可死锁）。
             // 文件被 write/delete 修改 → 结果处理循环 invalidate 台账，放行合法重读。
             const ledgerSubject = DEDUP_SUBJECT_EXTRACTORS[tc.function.name]?.(tc.function.arguments);
             if (ledgerSubject?.path) {
                 const cov = this.fileExposure.get(ledgerSubject.path);
-                if (cov && shouldEchoLedgerStub(ledgerSubject, cov)) {
+                // 前置：原文仍在上下文才拦。摘要替身只服务「手边有原文可回顾」的语境；原文已被压缩链
+                // 清出时回显替身 = 死路（模型要的中段 token 永远不在顶头摘要里，同参重读被反复拦），
+                // 必须放行真读。判据与 read_dedup 分支①共用 isMessageStillUnmodified（同源）。
+                // 顺带取回原文：拦下后按请求区间回显（见下方 formatLedgerStubRange），一次 find 两处消费。
+                const covContent = cov !== undefined
+                    ? this.stillUnmodifiedContent(cov.lastToolCallId, cov.fingerprint)
+                    : undefined;
+                const stillInContext = covContent !== undefined;
+                if (cov && shouldEchoLedgerStub(ledgerSubject, cov, stillInContext)) {
                     // 观测「补缝过度拦截」候选：台账替身回显命中累加。
                     this.metrics.ledgerStubEchoCount++;
                     // 裁决证据落盘（悬案取证）：计数判不了意图，「模型规避完整读取」vs「防重误拦合法
@@ -1471,8 +1770,16 @@ export class AgentLoop {
                     logger.debug({
                         path: ledgerSubject.path,
                         cov: `${cov.coverStart}-${cov.coverEnd}/${cov.totalLines}`,
-                    }, 'read_file 台账替身回显：已用摘要顶替整读');
-                    toolExecs.push({ blocked: true, promise: Promise.resolve(formatLedgerStub(cov)) });
+                    }, 
+                    // 文案只陈述两形态皆真的事实（未重新读取文件）——不再写「摘要顶替整读」：
+                    // 命中区间时回显的是请求的区间原文，写「摘要顶替」即与行为不符（改一处漏一处的老伤）。
+                    'read_file 台账替身回显：未重新读取文件');
+                    toolExecs.push({
+                        // 台账替身 = 主动挡下 ⇒ blockedOutcome（替身非护栏、不经 GuardHit：原因固定 ledger_stub）
+                        // 回显取材：优先按**请求区间**切原文（原文仍在上下文时零成本可取）；切不出 → 退化顶头替身。
+                        // 旧版恒给顶头 400 字符，与模型请求的区间零重叠 → 模型绕道（生产轮 round-1791449684099）。
+                        promise: Promise.resolve(blockedOutcome('ledger_stub', formatLedgerStubRange(cov, ledgerSubject, covContent === undefined ? undefined : unwrapToolResultBody(covContent)))),
+                    });
                     continue;
                 }
             }
@@ -1483,7 +1790,7 @@ export class AgentLoop {
             const writeKey = pathExtractor?.(tc.function.arguments);
             const useWriteBarrier = OPAQUE_WRITE_TOOL_NAMES.includes(tc.function.name) ||
                 (pathExtractor !== undefined && writeKey === undefined);
-            // 第二级压缩工具由 loop 拦截执行（现场压临时摘要替换，loop 收尾即弃），不落 ToolExecutor
+            // 第二级压缩/情报区工具由 loop 拦截执行（决策四：直接返回 ToolOutcome，不经 ToolExecutor）
             let promise;
             if (tc.function.name === COMPRESS_CONTEXT_TOOL.name) {
                 promise = this.compressContext(tc.function.arguments, signal);
@@ -1495,53 +1802,61 @@ export class AgentLoop {
                 // 屏障：排在全部在途写链尾之后（同/异路径写与既有屏障都要等），执行后成为新屏障尾
                 const prior = [...writeChains.values(), ...(opaqueWriteTail ? [opaqueWriteTail] : [])];
                 promise = Promise.all(prior).then(() => this.toolRunner.runOne(tc, signal));
-                // 链尾吞掉失败：一次写失败不得毒化后续写（本次真实结果仍由 promise 原样上抛）
-                opaqueWriteTail = promise.catch(() => '');
+                // 链尾吞掉失败：一次写失败不得毒化后续写（本次真实结果仍由 promise 原样上抛；
+                // 链尾值从不被消费，仅作串行占位 ⇒ okOutcome('') 即可）
+                opaqueWriteTail = promise.catch(() => okOutcome(''));
             }
             else if (writeKey) {
                 // 等同路径上一次写落地后再执行——这样本次「读盘」拿到的是上一次写后的最新内容，
                 // 不再基于旧快照、也就不会把上一次的改动覆盖掉；屏障在途时同样等它（目标可能就是本文件）。
                 const prior = [
-                    writeChains.get(writeKey) ?? Promise.resolve(''),
+                    writeChains.get(writeKey) ?? Promise.resolve(okOutcome('')),
                     ...(opaqueWriteTail ? [opaqueWriteTail] : []),
                 ];
                 promise = Promise.all(prior).then(() => this.toolRunner.runOne(tc, signal));
                 // 链尾吞掉失败：一次写失败不得毒化同路径的后续写（本次真实结果仍由 promise 原样上抛）
-                writeChains.set(writeKey, promise.catch(() => ''));
+                writeChains.set(writeKey, promise.catch(() => okOutcome('')));
             }
             else {
                 promise = this.toolRunner.runOne(tc, signal);
             }
-            toolExecs.push({ blocked: false, promise });
+            toolExecs.push({ promise });
         }
         const results = await Promise.all(toolExecs.map((e) => e.promise));
+        // 结果随 outcome 一并下传：status 是成败/拦截判据的唯一真源
+        //（B4 判据切换：编排层与计数层读同一份 status，禁另立文本判据）
         this._processToolResults(toolCalls, results);
         // 按原始顺序 yield tool_result
         for (let i = 0; i < toolCalls.length; i++) {
             const tc = toolCalls[i];
-            const result = results[i];
-            // 第三态：策略拦截 blocked=true 非成功亦非失败——ok=false 且不计成功搜索数；
-            // 失败（[ERR 前缀）与拦截区分开，UI 显示「已拦截」，metrics 失败数不把拦截算作失败
-            const blocked = toolExecs[i].blocked;
-            const ok = !blocked && !result.startsWith('[ERR');
+            const outcome = results[i];
+            // 渲染面文本（给 LLM / 防重指纹 / 台账用）；成败与拦截一律读 outcome.status，不再扫文本
+            const result = outcome.text;
+            // 第三态：主动挡下（loop 护栏 / 执行层闸门 / 旁路拒绝 / 台账替身）非成功亦非失败——
+            // ok=false 且不计成功搜索数；失败与拦截区分开，UI 显示「已拦截」，
+            // metrics 失败数不把拦截算作失败（B4 口径：执行层闸门也归 blocked，见方案 §六决策二）
+            const blocked = outcome.status === 'blocked';
+            const ok = outcome.status === 'ok';
             // 搜索收敛护栏：累计本闭环成功 web_search 次数（LLM 反复搜索不收敛时据此注入收敛提示）
             if (tc.function.name === 'web_search' && ok) {
                 this.successfulWebSearchCount++;
             }
             // 工具结果防重缓存：仅成功且是 info-fetch 类型的工具才写入（失败/拦截不缓存——
             // 失败可能是临时问题，拦截是我们主动挡的）。
-            // 一并记录 toolCallId + 内容指纹：拦截前据此判定「该结果是否仍在当前上下文中」。
-            // 指纹按进入上下文的包裹口径计算（复用 wrapToolResult 同一函数 → 同源，不会因模板改动失配）。
             const resultExtractor = DEDUP_SUBJECT_EXTRACTORS[tc.function.name];
             if (ok && resultExtractor) {
                 const subject = resultExtractor(tc.function.arguments);
                 if (subject) {
+                    // 指纹按进入上下文的包裹口径计算（复用 wrapToolResult 同一函数 → 同源，不会因模板改动失配）。
+                    // 一次计算两处消费（缓存 + 台账）：分支①分支②的「原文是否仍在上下文」比对同一份指纹。
+                    const fingerprint = sha256Fingerprint(wrapToolResult(tc.function.name, result));
                     this.toolResultCache.set(tc.function.name, subject, this.currentIteration, {
                         toolCallId: tc.id,
-                        fingerprint: sha256Fingerprint(wrapToolResult(tc.function.name, result)),
+                        fingerprint,
                     });
                     // 文件覆盖度台账写侧：read_file 返回分段脚注（= 文件确实大/被截断，按需读取信号）
-                    // 时记录覆盖区间 + 轻量替身摘要——供替身回显分支在原文被压缩后回显（防重读永动机 / 空拦死锁）。
+                    // 时记录覆盖区间 + 轻量替身摘要——原文**仍在上下文**时替身回显分支据此拦截变体重读
+                    // （防重读永动机）；原文被压缩后条目随指纹失配自动失效为放行（台账不清、判据把关）。
                     if (tc.function.name === 'read_file' && subject.path) {
                         const cov = parseReadFileCoverage(result);
                         if (cov) {
@@ -1558,22 +1873,42 @@ export class AgentLoop {
                                 // 替身 = 已读正文前 READ_DIGEST_CHARS 字符（轻量启发式，零 LLM 成本）
                                 digest: cov.content.slice(0, READ_DIGEST_CHARS),
                                 cachedAtIteration: this.currentIteration,
+                                // 在上下文判定三件套：定位锚 + 指纹与缓存同源（见上方 fingerprint 注）
+                                lastToolCallId: tc.id,
+                                fingerprint,
                             });
                         }
-                        else {
-                            // 整读无脚注（= 已读到文件末尾 / 文件未超单段预算，读到末尾零噪音）：
-                            // 同样记「全文件覆盖」——否则小文件整读后无台账 → 替身回显永不触发 → 压缩后重读狂飙
-                            // （真机 182 次 read_file 复发根因正是小文件不记——「补缝过度拦截」的反例）。
-                            const totalLines = result.split('\n').length;
-                            logger.debug({ path: subject.path, totalLines, src: 'whole-read', peek: result.slice(0, 80) }, 'read_file 台账写入（整读无脚注）');
+                        else if (!result.startsWith(READ_FILE_NOTICE_PREFIX)) {
+                            // 整读无脚注 = handler 不变量（sliceFileByLineBudget）：请求区间读到文件末尾且
+                            // 预算足，返回**从请求 offset 到末尾**的完整尾段（正文首行 = 文件第 offset 行）。
+                            // 故覆盖区间按请求起点记：coverStart=offset、totalLines=offset+正文行数-1——
+                            // 错记成「1 起的整读」会把早段未覆盖误当已覆盖（真机 round-1791507775404：
+                            // offset=54 读到末尾被记 1–95/共95，随后 offset=1 早段读被假拦 + 回显行号错位）。
+                            // offset≤1 时与旧记账数值完全等价（起点即 1，总行数=正文行数）。
+                            const start = subject.offset ?? 1;
+                            const totalLines = start + result.split('\n').length - 1;
+                            logger.debug({
+                                path: subject.path,
+                                start,
+                                totalLines,
+                                src: 'whole-read',
+                                peek: result.slice(0, 80),
+                            }, 'read_file 台账写入（整读无脚注，按请求起点记账）');
                             this.fileExposure.record(subject.path, {
                                 totalLines,
-                                coverStart: 1,
+                                coverStart: start,
                                 coverEnd: totalLines,
                                 digest: result.slice(0, READ_DIGEST_CHARS),
                                 cachedAtIteration: this.currentIteration,
+                                lastToolCallId: tc.id,
+                                fingerprint,
                             });
                         }
+                        else {
+                            // 提示性返回（越界等，READ_FILE_NOTICE_PREFIX 开头）：非文件正文，不进台账——
+                            // 记了会把「不存在的覆盖」当真，随后再次越界读命中归一判据被假拦（宁少记放行）
+                            logger.debug({ path: subject.path, peek: result.slice(0, 80) }, 'read_file 提示性返回，不进覆盖度台账');
+                        }
                     }
                 }
             }
@@ -1583,7 +1918,9 @@ export class AgentLoop {
                 toolName: tc.function.name,
                 argsJson: tc.function.arguments,
                 toolCallId: tc.id,
-                outcome: blocked ? 'blocked' : ok ? 'ok' : 'failed',
+                // B4 判据切换：执行层拒绝（宿主审批）从 'failed' 变 'blocked'——write_loop
+                // 自持状态因此不再把「用户拒绝」当失败升级文案，语义对齐「主动挡下」
+                outcome: outcome.status,
             });
             // 副作用型工具成功 → 主动失效关联的 read_file 缓存（放行后续合法重读）
             // 覆盖面派生自 `diskWrite:'path'` 声明（与串行闸同一真源），目标提取复用同一提取器——
@@ -1608,10 +1945,12 @@ export class AgentLoop {
         // 循环结束后再查 abort：最后一个工具执行期间被 abort 时返回 aborted:true，
         // 否则 processUserInput 会进入下一轮 LLM 调用（浪费资源）
         if (signal?.aborted) {
-            return { aborted: true };
+            // 工具已跑完、本轮被中止：outcome 照常回流（重试分类仍基于真实结果，不因中止而失忆）
+            return { aborted: true, outcomes: results };
         }
         this.inAutonomousStep = false;
-        return { aborted: false };
+        // 回流本轮 outcome：重试分类据此读结构化 errorCode，不再回头解析 message 文本
+        return { aborted: false, outcomes: results };
     }
     /**
      * 第二级压缩（LLM 主动触发兜底）：把最早的 turn 或超大工具结果现场压成临时摘要替换。
@@ -1621,28 +1960,31 @@ export class AgentLoop {
      *
      * @param args 工具参数 JSON（{ target: 'earliest_round' | 'largest_tool_result' }）
      * @param signal 中止信号
-     * @returns 回传给 LLM 的确认串（失败/无目标时返回提示，不抛错阻断工具链）
+     * @returns 结构化 outcome（B4 判据切换）：无目标 → blocked(no_compress_target)；
+     *   真跑了但失败（摘要生成失败 / 压缩异常）→ **failed**（重归类：文本判据期这两串
+     *   无失败前缀、曾被静默算成功，口径变更见方案 §七）；成功 → ok。
+     *   text 仍是回传给 LLM 的提示串（失败/无目标不抛错阻断工具链）。
      */
     async compressContext(args, signal) {
         try {
             // 解析目标（非法/缺失降级 earliest_round）
             let target;
             try {
-                const parsed = JSON.parse(args).target;
-                target = parsed === 'largest_tool_result' ? 'largest_tool_result' : 'earliest_round';
+                target = parseCompressTarget(JSON.parse(args).target);
             }
             catch {
                 target = 'earliest_round';
             }
-            // 定位目标消息
-            const targetMsgs = target === 'largest_tool_result' ? this.findLargestToolResult() : this.findEarliestRound();
+            // 定位目标消息（各定位器只返回「可安全整段替换」的区间——配对完整性由定位器自身保证）
+            const targetMsgs = this.findCompressTarget(target);
             if (!targetMsgs || targetMsgs.length === 0) {
-                return '[compress_context] 无可压缩目标（上下文为空或目标不存在）';
+                return blockedOutcome('no_compress_target', `[compress_context] 无可压缩目标（上下文为空或目标不存在；可用 target=${COMPRESS_TARGETS.join(' | ')}）`);
             }
             // LLM 现场压成临时摘要
             const summary = await this.summarizeForCompression(targetMsgs, signal);
             if (!summary) {
-                return '[compress_context] 摘要生成失败，已跳过（不破坏上下文）';
+                // B4 重归类：真跑了压缩但摘要生成为空 ⇒ failed（原无失败前缀，曾被算成功）
+                return failedOutcome('[compress_context] 摘要生成失败，已跳过（不破坏上下文）');
             }
             // 替换为目标内容为临时摘要 system 消息（executionTemp：loop 收尾即弃）
             const tempSummaryMsg = {
@@ -1654,23 +1996,30 @@ export class AgentLoop {
             const startIdx = this.messages.indexOf(first);
             const endIdx = last === first ? startIdx : this.messages.indexOf(last);
             if (startIdx === -1 || endIdx === -1) {
-                return '[compress_context] 目标已不在当前上下文，已跳过';
+                return blockedOutcome('no_compress_target', '[compress_context] 目标已不在当前上下文，已跳过');
             }
             this.messages.splice(startIdx, endIdx - startIdx + 1, tempSummaryMsg);
             this.executionTempSystem.add(tempSummaryMsg);
             logger.info({ target, replacedCount: targetMsgs.length }, 'compress_context 已压缩为临时摘要（loop 收尾即弃）');
             // 回调宿主：LLM 主动压缩完成（第二级压缩，与 contextTruncated 的内核自动截断区分）
             this.onContextCompressed?.(target, targetMsgs.length, summary.length);
-            return `[compress_context] 已把目标压缩为临时摘要（${summary.length} 字，loop 收尾即弃）：${summary.slice(0, 80)}`;
+            return okOutcome(`[compress_context] 已把目标压缩为临时摘要（${summary.length} 字，loop 收尾即弃）：${summary.slice(0, 80)}`);
         }
         catch (err) {
             logger.warn({ err: toError(err).message }, 'compress_context 压缩失败，已跳过');
-            return '[compress_context] 压缩失败，已跳过（不阻断工具链）';
+            // B4 重归类：压缩异常 = 真跑了但失败 ⇒ failed（原无失败前缀，曾被算成功）
+            return failedOutcome('[compress_context] 压缩失败，已跳过（不阻断工具链）');
         }
     }
     /**
      * 定位当前触发输入（顶级锚点）之前最早的 turn；无旧轮次（新对话第一轮）返回 null
      * （当前输入永不压缩——交软上限收尾而非压掉触发输入继续硬跑）。
+     *
+     * ⚠️ **单轮 turn 内本定位器恒返回 null**（CTX-WIN-2 实锤）：锚点是
+     * 「第一个 user vs 最后一个 user」，而单轮 turn 内**只有一个 user**（当前触发输入）
+     * ⇒ `firstUserIdx >= lastUserIdx` 恒成立 ⇒ 无旧 turn 可压。
+     * 这不是「长单轮不需要压缩」，而是**锚点粒度选错了**——单轮内的历史是 step 序列，
+     * 由 `findEarliestSteps` 承接。两定位器互补，单轮长任务才有目标。
      */
     findEarliestRound() {
         // 最后一个 user = 当前触发输入（顶级锚点，永不压缩）
@@ -1698,7 +2047,16 @@ export class AgentLoop {
         }
         return out;
     }
-    /** 定位最大的 tool 结果（超大 tool_result 的压缩目标） */
+    /**
+     * 定位最大的 tool 结果所在**整段 step**（超大 tool_result 的压缩目标）。
+     *
+     * 🔴 **配对完整性（CTX-WIN-2 实锤，原实现带伤）**：本定位器曾只返回
+     * **单条 tool 消息**，而它所属的 `assistant.toolCalls` 留在上下文里
+     * ⇒ 下一次请求命中发送边界守卫 `unpairedAssistantCall` **fail-fast 抛错，整个 turn 崩掉**
+     * （实证：单轮 turn 内 `target=largest_tool_result` 必崩，非边缘情形）。
+     * 故返回**整段**：该 tool 消息 + 所属 assistant 消息（toolCalls 全部摘除）
+     * + 中间夹在两者之间的其他消息——保证替换后剩余上下文仍处处配对。
+     */
     findLargestToolResult() {
         let largest = null;
         for (const m of this.messages) {
@@ -1708,7 +2066,97 @@ export class AgentLoop {
                 largest = m;
             }
         }
-        return largest ? [largest] : null;
+        if (!largest)
+            return null;
+        const toolIdx = this.messages.indexOf(largest);
+        // 向前找所属 assistant（最近的、带 toolCalls 且含该 toolCallId 者）
+        let assistantIdx = -1;
+        for (let i = toolIdx - 1; i >= 0; i--) {
+            const m = this.messages[i];
+            if (m.role === 'assistant' && m.toolCalls?.some((tc) => tc.id === largest.toolCallId)) {
+                assistantIdx = i;
+                break;
+            }
+            // 撞上 user/system 边界 ⇒ 该 tool 无所属 assistant（异常态），只取自身
+            if (m.role === 'user')
+                break;
+        }
+        const start = assistantIdx === -1 ? toolIdx : assistantIdx;
+        return this.messages.slice(start, toolIdx + 1);
+    }
+    /**
+     * 定位**最早的若干个已完成 step**（单轮 turn 内的压缩目标，CTX-WIN-2 新增）。
+     *
+     * 为什么需要它（第一性原理）：单轮长任务（一个 user 输入跑几十个 step）的上下文增长
+     * 全部来自 **step 序列**（assistant 思考 + tool 结果），而 `earliest_round` 的锚点是
+     * 「user 消息」⇒ 单轮内只有一个 user ⇒ 恒无目标。上一轮三样本 38.5万 / 105.3万 / 72.0万
+     * token 的长单轮就是这样把窗口顶满、却没有任何可压目标。
+     *
+     * **step 边界判据**（内核既有结构，零新概念）：一个 step = 一条 `assistant` 消息
+     * （思考/工具调用意图）到**下一条 assistant 消息之前**的全部消息（含其 tool 结果与
+     * 夹在中间的 system 注入）。故本定位器 = 「跳过当前触发输入，取第一个 assistant 起的
+     * 一个完整 step」。
+     *
+     * 边界纪律（与既有两定位器同源）：
+     * ① **当前触发输入（最后一个 user）永不压缩**——顶级锚点；
+     * ② **只取「已完成」的 step**：末条 assistant 之后若还有 tool 结果，说明该 step 尚未走完
+     *   （结果可能是 `[ASK_SUSPENDED]` 等），留待下轮；
+     * ③ **整段替换**——step 内 assistant.toolCalls 与其 tool 结果同进同出，配对恒成立。
+     */
+    findEarliestSteps() {
+        // 顶级锚点：当前触发输入位置（其后的消息才可压）
+        let lastUserIdx = -1;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            if (this.messages[i].role === 'user') {
+                lastUserIdx = i;
+                break;
+            }
+        }
+        if (lastUserIdx === -1)
+            return null;
+        // 第一个 assistant = 最早 step 的起点（必须晚于顶级锚点：user 之前的 assistant 属上一轮，
+        // 由 findEarliestRound 负责，不在此越界）
+        let firstAssistantIdx = -1;
+        for (let i = lastUserIdx + 1; i < this.messages.length; i++) {
+            if (this.messages[i].role === 'assistant') {
+                firstAssistantIdx = i;
+                break;
+            }
+        }
+        if (firstAssistantIdx === -1)
+            return null;
+        // 下一条 assistant 之前 = 本 step 的右边界
+        let endIdx = this.messages.length;
+        for (let i = firstAssistantIdx + 1; i < this.messages.length; i++) {
+            if (this.messages[i].role === 'assistant') {
+                endIdx = i;
+                break;
+            }
+        }
+        const step = this.messages.slice(firstAssistantIdx, endIdx);
+        if (step.length === 0)
+            return null;
+        // 「已完成」判据 = 本 step 内每个 assistant.toolCalls 的 id 都有配对的 tool 消息回齐。
+        // 逐 id 核验（而非「区间内有无 tool」）：后者被**后续** step 的 tool 结果误判为未完成
+        // —— 那是拿「别的 step 的状态」当「本 step 的状态」，判据层级选错。
+        const toolIdsInStep = new Set(step.filter((m) => m.role === 'tool' && m.toolCallId).map((m) => m.toolCallId));
+        const allAnswered = step
+            .flatMap((m) => (m.toolCalls ?? []).map((tc) => tc.id))
+            .every((id) => toolIdsInStep.has(id));
+        if (!allAnswered)
+            return null;
+        return step;
+    }
+    /** 压缩目标分派（三个定位器互补，各守一条通道，不合并成泛化遍历） */
+    findCompressTarget(target) {
+        switch (target) {
+            case 'largest_tool_result':
+                return this.findLargestToolResult();
+            case 'earliest_steps':
+                return this.findEarliestSteps();
+            case 'earliest_round':
+                return this.findEarliestRound();
+        }
     }
     /** 用 provider 把目标内容压成临时摘要（走 summary 路由，轻量模型优先；失败降级空串） */
     async summarizeForCompression(targetMsgs, signal) {
@@ -1940,10 +2388,10 @@ export class AgentLoop {
         if (this.opts.chatOptions) {
             Object.assign(baseOptions, this.opts.chatOptions);
         }
-        // 输出上限**取交集**（对齐上下文窗口 `min(provider 窗口, 角色包 contextLimit)` 的语义）：
-        // per-LLM 配置与角色包策略都是「上限」性质，任何一侧声明「不能超过 X」都必须被满足 ⇒ 取更小值。
-        // 直接覆盖（Object.assign 压过）与「上限」语义相反——它会让角色包把用户配的小值顶大
-        //（包 128K 顶掉面板 64K），用户无从得知谁赢了。
+        // 输出上限**取交集**（定案锚 ADR-035）：per-LLM 配置与角色包策略都是「上限」性质，
+        // 任何一侧声明「不能超过 X」都必须被满足 ⇒ 取更小值（对齐上下文窗口
+        // `min(provider 窗口, 角色包 contextLimit)` 的同构语义）。直接覆盖（Object.assign 压过）
+        // 与「上限」语义相反——它会让角色包把用户配的小值顶大，用户无从得知谁赢了。
         const perLlmLimit = this.opts.defaultMaxTokens;
         const strategyLimit = baseOptions.maxTokens;
         if (perLlmLimit !== undefined && strategyLimit !== undefined) {
@@ -2128,6 +2576,9 @@ export class AgentLoop {
                 unparsedToolIntentCount: this.metrics.unparsedToolIntentCount,
                 ledgerStubEchoCount: this.metrics.ledgerStubEchoCount,
                 readDedupBlockCount: this.metrics.readDedupBlockCount,
+                // SCRIPT-2 B4 口径：执行层闸门归 blocked（不再计入 failureCount），见字段 JSDoc
+                toolBlockedCount: this.metrics.toolBlockedCount,
+                toolBlockedWithFailureCount: this.metrics.toolBlockedWithFailureCount,
             },
             context: {
                 truncationCount: this.contextManager.truncationCount,
@@ -2382,7 +2833,11 @@ export class AgentLoop {
      */
     appendToolMessage(content, toolCallId) {
         const finalContent = this.offloadDir
-            ? offloadLargeToolResult(content, { offloadDir: this.offloadDir }).content
+            ? offloadLargeToolResult(content, {
+                offloadDir: this.offloadDir,
+                // 尾部预览：长输出的关键信息常在尾部（缺口 D）；份额在既有预览预算内划分
+                tailPreviewChars: LOOP_CONSTANTS.TOOL_RESULT_OFFLOAD_TAIL_PREVIEW_CHARS,
+            }).content
             : content;
         this.messages.push({
             role: 'tool',
@@ -2398,7 +2853,8 @@ export class AgentLoop {
      * ack **不回填 note 原文**（工具结果只回「已记录」），note 原文只进情报区 system 消息 → 不在用户流。
      *
      * @param args remember_intel 的 JSON arguments
-     * @returns 简短 ack（作为该工具调用的 tool 结果）
+     * @returns 结构化 outcome（B4 判据切换）：note 为空 → blocked(invalid_intel_note)
+     *   （主动挡下：没写就谈不上失败）；已记录 → ok。text 仍为简短 ack（工具结果不回填 note 原文）。
      */
     handleRememberIntel(args) {
         let note;
@@ -2411,7 +2867,7 @@ export class AgentLoop {
             note = undefined;
         }
         if (!note) {
-            return '[情报区] 未写入：note 为空或缺少该参数。';
+            return blockedOutcome('invalid_intel_note', '[情报区] 未写入：note 为空或缺少该参数。');
         }
         const prev = this.intelNote;
         this.intelNote = prev ? `${prev}\n${note}` : note;
@@ -2419,7 +2875,7 @@ export class AgentLoop {
         if (this.intelNote.length > LOOP_CONSTANTS.MAX_INTEL_PREFIX_LEN) {
             this.intelNote = this.intelNote.slice(-LOOP_CONSTANTS.MAX_INTEL_PREFIX_LEN);
         }
-        return '[情报区] 已记录（对你私有，不会展示给用户）。';
+        return okOutcome('[情报区] 已记录（对你私有，不会展示给用户）。');
     }
     /**
      * 每轮装配把情报区注入为**单条尾部私有 system 消息**。
@@ -2449,13 +2905,41 @@ export class AgentLoop {
         }
     }
     /**
-     * 缓存条目对应的工具结果是否**仍在当前上下文中** —— 防重拦截的前提（调用点见 handleToolCalls）。
+     * 指定 toolCallId 的 tool 消息是否仍在上下文中且内容未被改动 —— 「结果仍在上下文」的共用判据。
      *
-     * 三道判据全过才算「在」：① 条目带 toolCallId 与指纹；② `this.messages` 中仍有该 toolCallId 的
-     * tool 消息；③ 其内容指纹与记录一致（内容未被压缩链替换成 `[Previous: used x]` 占位符）。
+     * 两个消费语境（SSOT）：① read_dedup 分支①（经 isCachedResultStillInContext）；
+     * ② 台账替身回显分支②（按 FileCoverage.lastToolCallId + fingerprint 直调）。
+     * 二者比对口径必须一致（wrapped 后消息内容指纹），否则两路对「同一结果在不在」的理解分叉。
      *
-     * **保守方向：宁可放行，不可误拦。** 找不到消息 / 指纹不符 / 条目缺元信息 → 一律 false（放行）。
+     * 三道判据全过才算「在」：消息数组中仍有该 toolCallId 的 tool 消息，且内容指纹与记录一致
+     * （内容未被压缩链替换成 `[Previous: used x]` 占位符）。
+     *
+     * **保守方向：宁可放行，不可误拦。** 找不到消息 / 指纹不符 → false（放行）。
      * 误放行的代价是「多读一次」；误拦的代价是「内容已不在手上却读不回来 = 死锁」——两者不对称。
+     */
+    isMessageStillUnmodified(toolCallId, fingerprint) {
+        return this.stillUnmodifiedContent(toolCallId, fingerprint) !== undefined;
+    }
+    /**
+     * 指定 toolCallId 的 tool 消息**内容**（判「在不在」与取内容同源，避免两处各自 find 各算一次）。
+     *
+     * 判据与 `isMessageStillUnmodified` 完全一致（布尔版委托本方法），差别只在返回原文：
+     * 分支②拦截后要按请求区间回显原文，而「在不在」的判据本身已经把消息翻出来了——
+     * 再翻一次既浪费，又容易让两处对「同一结果在不在」的理解分叉（SSOT：翻找+指纹比对只此一处）。
+     *
+     * @returns 仍在上下文且未被压缩链改动的原始消息内容；否则 undefined
+     */
+    stillUnmodifiedContent(toolCallId, fingerprint) {
+        const msg = this.messages.find((m) => m.role === 'tool' && m.toolCallId === toolCallId);
+        if (!msg)
+            return undefined;
+        return sha256Fingerprint(msg.content) === fingerprint ? msg.content : undefined;
+    }
+    /**
+     * 缓存条目对应的工具结果是否**仍在当前上下文中** —— read_dedup 分支①拦截的前提（调用点见 handleToolCalls）。
+     *
+     * 实际判定委托 `isMessageStillUnmodified`（与台账分支②共用判据）；本方法只补条目元信息缺失的
+     * 保守放行（条目没带 toolCallId/指纹 → 无从核验 → 视为「不在」放行）。
      *
      * 注：超阈结果经入口关落盘后，上下文里留的是「路径 + 预览」，与记录指纹（包裹后的原文）不符
      * → 判为「不在」，重读放行。这是正确语义：原文确实已不在上下文中。
@@ -2463,26 +2947,42 @@ export class AgentLoop {
     isCachedResultStillInContext(entry) {
         if (entry.toolCallId === undefined || entry.fingerprint === undefined)
             return false;
-        const msg = this.messages.find((m) => m.role === 'tool' && m.toolCallId === entry.toolCallId);
-        if (!msg)
-            return false;
-        return sha256Fingerprint(msg.content) === entry.fingerprint;
+        return this.isMessageStillUnmodified(entry.toolCallId, entry.fingerprint);
     }
     /** 整体替换执行上下文（截断落盘 / 恢复历史 / 装配重排：传入的数组已是完整上下文） */
     replaceContext(next) {
         this.messages = next;
     }
     // ─── Reflection 辅助方法 ────────────────────────────────
-    /** 处理工具执行结果：push tool 消息 + 统计失败数 */
+    /**
+     * 处理工具执行结果：push tool 消息 + 按结构化 `status` 结算计数。
+     *
+     * B4 判据切换：成败/拦截判据唯一真源 = `ToolOutcome.status`（三值契约），不再解析文本前缀。
+     * 三路互斥穷尽：
+     *   · `blocked` → `toolBlockedCount`（主动挡下总数：loop 护栏 + 旁路拒绝 + 台账替身 + 执行层闸门）
+     *     其中 `hasRealFailure=true`（当前唯一 = read_failed 护栏）→ 另计 `toolBlockedWithFailureCount`
+     *   · `failed` → `toolFailureCount`；`ok` → 无计数
+     * **口径变更（Breaking，CHANGELOG 已登记）**：执行层闸门（宿主审批拒绝 / 只读拒绝 /
+     * 幂等跳过）从 `toolFailureCount` 剔除、归入 `toolBlockedCount` ⇒ 失败数下降、挡下数上升，
+     * 历史不可比（方案 §六决策二）。
+     */
     _processToolResults(toolCalls, results) {
         for (let i = 0; i < toolCalls.length; i++) {
             const tc = toolCalls[i];
-            const result = results[i];
+            const outcome = results[i];
             // 工具结果隔离：用 <tool_result> 包裹 + 指令前缀，防外部工具返回承载间接注入；
-            // ERR 前缀保留在包裹内，供 isRetryableToolError 识别（该正则不锚定行首）
-            const wrapped = wrapToolResult(tc.function.name, result);
+            // 重试分类主判据是 outcome.errorCode（结构化契约，toolCallHelpers），
+            // ERR 前缀仅兜底 errorCode 缺失的旧形态文本（该正则不锚定行首，包裹内仍可识别）
+            const wrapped = wrapToolResult(tc.function.name, outcome.text);
             this.appendToolMessage(wrapped, tc.id);
-            if (result.startsWith('[ERR')) {
+            // 计数读 status（禁另立文本判据——判据面与渲染面分离是 SCRIPT-2 的核心契约）
+            if (outcome.status === 'blocked') {
+                this.metrics.toolBlockedCount++;
+                // blocked 背后藏真失败的子集计数（独立于失败总数，防「主动停手」与「真失败」混数）
+                if (outcome.hasRealFailure === true)
+                    this.metrics.toolBlockedWithFailureCount++;
+            }
+            else if (outcome.status === 'failed') {
                 this.metrics.toolFailureCount++;
             }
         }