@sema-agent/client-core 0.45.0 → 0.47.0

package/dist/hitl/parkResolver.js

@@ -1,4 +1,4 @@
-import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, findPendingForTask } from './hitlBridge.js';
+import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, findPendingForTask, readDecideCurrentPending, } from './hitlBridge.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -7,6 +7,38 @@ import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 /** 一 turn 内最多循环这么多次 park(防御:引擎/模型病态连环提问时不无限 attach)。 */
 const MAX_GATE_HOPS = 24;
+/**
+ * 「已解决 ⇒ reattach」臂的**同因连续命中上限**(#357,现网 P0;[5522] 定谳 / [5525] server 答复)。
+ * 同一判据源连续第 `N+1` 次命中即**不再** reattach。
+ *
+ * ── 病 ──────────────────────────────────────────────────────────────────────────────────────
+ * 用户批完两张卡,第三只门 16 分钟长等,最后吐 `gate hop limit (24) exceeded`,工具 abort,
+ * 而引擎侧 run 仍 parked。链:run 仍 parked 但取件当拍读不到本 run 的可决行 ⇒ 每一轮重放的 park
+ * 都命中「已解决」⇒ reattach ⇒ 引擎重放同一张 park ⇒ 循环到 hop 预算耗尽。24 轮里只有 debug 级
+ * 日志,用户零告知,拿到的还是一句与真因无关的预算话术。
+ *
+ * ── 两件修的分工(**别合并**)──────────────────────────────────────────────────────────────
+ *   · **主修 = 坐标重探**({@link resolvePark} 的 rescan 臂):server [5525] 定谳这不是「状态失配」
+ *     而是**坐标失配** —— decide 受理后 resume **消费**掉 checkpoint(token 一次性),下一 turn 再
+ *     撞门就是**新 park / 新 token / 新行**;拿旧坐标去查/去决恒得 409 `approval_stale`(体
+ *     terminal:"resolved")或 404 no-pending,逐字命中本文件的「已解决」判据集,而 run 真身是
+ *     parked、**新行真实存在待决**。⇒ 命中「已解决」时先**重读当前队列**(丢掉这张 park 自带的
+ *     陈旧身份,让取件腿按当前拍的坐标选行):有行 ⇒ 这一轮就把**新卡**真呈给用户;确无行 ⇒ 才是
+ *     #110 的重放窗,照旧 reattach。
+ *   · **兜底 = 本闸**:重探自己也失配/读不动时(网络类、或队列确实空而 run 就是不动),不许再
+ *     空转 24 轮 —— 同因连续第 2 次即诚实收场,终帧带真因。
+ *
+ * 值 = 1 的理由:「已解决」判据的**正当性只覆盖一次重放窗**(#110 成文:`lastEventId` 再准也只能
+ * 精确到帧,park 就在重放窗里,而那个窗**只有一次**)。第二次同因命中意味着重探也没能把新坐标
+ * 找出来 —— 那时继续 reattach 只是把同一个空转再跑一遍。
+ * 🔴 {@link MAX_GATE_HOPS} 总闸**保留**(最后防线):本闸只管「已解决」这一条臂,别的臂
+ * (重呈臂每轮真呈卡)仍由总闸兜底。
+ *
+ * 🔴 键**按语义分不按表征分**(异源复审 finding③):「已解决」在 wire 上有 `no_pending` 码 /
+ * 409 体 `resolved` / 404 `not found` 三种长相,它们是同一个真因 —— 按长相分键的话,表征一轮换
+ * 计数就重置回 1,闸永远不触发。判据见 {@link alreadyResolvedStreakKey}。
+ */
+const MAX_ALREADY_RESOLVED_REATTACHES = 1;
 /**
  * REF-CC-033:`GateOutcome` 的 `failed` 分支闭集判别码。来源两处:①本文件自己的
  * 「pending 行取不到」早退(`surfaceGateAndDecide` 里 `!pending` 那条);②`HitlBridge` 抛出的
@@ -51,13 +83,28 @@ function isGateFailureCode(v) {
  *  (desktop 实测——parked 刚批完、decide 未返回的竞态窗内 Stop 走 parked-deny 路),旧词表
  *  判不中 ⇒ 按真失败 log-only 放弃 ⇒ runs.cancel 永不发出=Stop 哑弹。按上方「宁可宽」方向收编。 */
 export function isAlreadyResolvedGateReason(reason) {
+    return alreadyResolvedReasonToken(reason) !== undefined;
+}
+/**
+ * 文案兜底臂的**词表**(判据本体;`isAlreadyResolvedGateReason` 是它的布尔投影)。
+ * 🔴 #357 把它从「四个 `||` 就地写死」抽成词表,**行为一个字节不变**:一处词表,两个消费点
+ * (布尔判定 + 诊断串里「是哪个词命中的」),此前后者只能靠人再读一遍那四个 `||`。
+ * 🔴 命中的词**不进限次闸的键** —— 键按语义分,理由见 {@link alreadyResolvedStreakKey}。
+ */
+const ALREADY_RESOLVED_REASON_TOKENS = ['no pending checkpoint', 'resolved', 'already', 'not found'];
+/** 命中的那个词(没命中 ⇒ `undefined`)。顺序即优先级,只进诊断串,不参与判定强弱。 */
+function alreadyResolvedReasonToken(reason) {
     if (typeof reason !== 'string')
-        return false;
+        return undefined;
     const r = reason.toLowerCase();
-    return r.includes('no pending checkpoint') || r.includes('resolved') || r.includes('already') || r.includes('not found');
+    return ALREADY_RESOLVED_REASON_TOKENS.find((t) => r.includes(t));
 }
-/** 已解决判据(REF-CC-033):code 在场就只信 code,不在场才落回文案兜底(fs 审批腿的
- *  `FsApprovalOutcome` 今天没有 code 字段——C-bridge 卡域,退役条件 = 那边也补上 code)。
+/** 已解决判据(REF-CC-033):code 在场就只信 code,不在场才落回文案兜底。
+ *  ✅ **记案已销**(#357,0.47.0):原注末句写的是「fs 审批腿的 `FsApprovalOutcome` 今天没有
+ *  code 字段——C-bridge 卡域,退役条件 = 那边也补上 code」。那个退役条件已兑现:取件腿的
+ *  `no_pending` 码现在由 `toolApprovalWire.surfaceFsApprovalAndDecide` 原样透传(见
+ *  `FsApprovalOutcome.code` 头注),两条腿从此同走 code 臂;文案兜底只剩 decide 失败那一类
+ *  (引擎的 409/404 语义答复文本)与旧引擎路径。
  *  🔴 入参**已经**是窄化到 `{kind:'failed'}` 的那半:一个「true ⇒ 是 failed」的判定不能反过来
  *  当「false ⇒ 不是 failed」的类型谓词用(TS 的 `outcome is Extract<…>` 负向窄化会把整个
  *  `'failed'` 分支从联合类型里排除,而这个函数对未解决的真失败照样返回 false——那不是「它不是
@@ -196,6 +243,8 @@ parkGatedCallId) {
         // 这里 instanceof 窄化后再过 isGateFailureCode 白名单——不认得的码(将来 hitlBridge 那边
         // 万一多加一种)一律降级成 undefined,退回文案兜底,不让开集腐蚀这个新判别位。
         const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
+        // #363:S-02 指路键原样透传 —— 与 `toolApprovalWire` 两条 decide 失败腿同形同源。
+        const currentPending = readDecideCurrentPending(e);
         return {
             kind: 'failed',
             gatedCallId,
@@ -203,6 +252,7 @@ parkGatedCallId) {
             ...(code !== undefined ? { code } : {}),
             // Inkglow-1085 P0a:ask 腿与 fs 腿同形 —— 瞬断耗尽给判别位,resolvePark 走重呈臂。
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+            ...(currentPending !== undefined ? { currentPending } : {}),
         };
     }
 }
@@ -210,22 +260,55 @@ parkGatedCallId) {
 function argsByCallOf(led) {
     return new Map(led.gatedStartArgs());
 }
-export async function resolvePark(park, ctx) {
-    const { deps, led, taskId, hops } = ctx;
-    let outcome;
-    // REF-CC-034:这次 park 的候选 callId(仅 fs 分支填,已决断身份匹配用)——ask 分支不填,
-    // 因为 `surfaceGateAndDecide` 的 `!pending` 早退已经自带 `code:'no_pending'`(REF-CC-033),
-    // 不需要这条第二判据。用 `lastFsOrShellGatedCallId()` 而非「未收口 fs call 栈」:durable
-    // re-attach 重放的 `suspended` park 没有配套的新 tool_start/tool_end,那个栈在这次重放之前
-    // 早被 tool_end 的 drop 清空了(见台账声明处注),取不到候选。
-    let candidateGatedCallId;
-    if (hops > MAX_GATE_HOPS) {
-        outcome = { kind: 'failed', reason: `gate hop limit (${MAX_GATE_HOPS}) exceeded` };
-    }
-    else if (park.gate === 'fs') {
-        candidateGatedCallId = led.lastFsOrShellGatedCallId();
+/**
+ * 限次闸的**判据源**(键)——「是哪一**条判据**把这一轮判成已解决的」。
+ *
+ * 🔴 键**按语义分,不按表征分**(异源复审 finding③ 的采纳):「队列里没有本 run 的可决行」这件事
+ * 在 wire 上有好几种长相 —— 取件读到空表落 `code:'no_pending'`,server 的 409 `approval_stale`
+ * (体 terminal:"resolved")/ 404 落文案臂的 `resolved` / `not found`。它们是**同一个真因的三种
+ * 说法**;按长相分键的话,一个卡死的 gate 只要在这几种表征之间轮换,连续计数就一路重置回 1,
+ * 闸永远不触发 —— 正是本闸要消灭的那个空转([anchor-on-the-deciding-quantity]:锚真正决定结果
+ * 的量,不锚它的表征)。命中的那个词只进诊断串,不进键。
+ *
+ * 只有身份腿(`decidedGates` 一次性匹配)另占一个键:它与「已解决」是两条独立判据,而且它一次性
+ * 消费、连续最多命中一次,天然不会把闸推到跳闸线。
+ */
+function alreadyResolvedStreakKey(byDecidedIdOnly) {
+    return byDecidedIdOnly ? 'decided-id-match' : 'already-resolved';
+}
+/**
+ * 这一轮的失败是不是「**取件那一步**就没找到本 run 的可决行」—— 即坐标重探唯一有资格跑的那一形。
+ *
+ * 🔴 判据锚在**结构**上,不锚文案:`code === 'no_pending'`(取件腿的结构化判别位,两条呈卡腿
+ * 今天都透传它)**且** `gatedCallId` 缺席。后半条是承重的 —— 两条呈卡腿里,`findPendingForTask`
+ * 失败那一条是**唯一**不带 `gatedCallId` 的 failed 出口(行都没选出来,哪来的 call 身份);它之后
+ * 的每一个失败出口(卡口缺席 / 无 payload / decide 4xx,包括 `HitlSafetyError.code==='no_pending'`)
+ * 都带着 `gatedCallId`。于是这条判据同时证明了一件承重的事:**这一轮没有向用户呈过卡**。
+ *
+ * 🔴 为什么必须证明「没呈过卡」(异源复审 finding② 的采纳):重探会把整条呈卡腿**再走一遍**。
+ * 若允许它在「卡已经呈过、用户答了、decide 回了一句带 resolved 字样的 409」之后跑,用户会在同一轮
+ * 里被同一张卡问第二遍(而且可能给出与第一次不同的答案)。把重探限定在取件步失败这一形,
+ * 「同一轮重复呈卡」在结构上就不成立。代价:decide 步的 stale 409 不再就地重探 —— 那一形照旧
+ * reattach 一次(durable 流本就会把 park 再送一遍),第二次同因命中由限次闸诚实收场。
+ */
+function isFetchStepNoPending(outcome) {
+    const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
+    return code === 'no_pending' && outcome.gatedCallId === undefined;
+}
+/**
+ * 「呈这张 park 的卡 → 等人决断 → decide」的**唯一**入口(两族各一条腿;fs 腿的 denied 记账随行)。
+ *
+ * 🔴 #357 抽成一处的理由不是去重:坐标重探臂要用**当前拍的坐标**再走一次同一条腿,两处各写一份
+ *    的话,「第一次走的路」与「重探走的路」会各自漂(记账少一笔 / 族判据不同 ⇒ 决断落到另一行)。
+ *
+ * @param gatedCallId 交给取件腿的**身份**(wire 给的 park 身份;缺席是常态)。首击与坐标重探
+ *   传的是**同一个值** —— 重探要的是读数新鲜,不是判据放宽,理由见调用点的红线注。
+ */
+async function surfaceParkGate(park, ctx, gatedCallId) {
+    const { deps, led, taskId } = ctx;
+    if (park.gate === 'fs') {
         // [816] 放宽腿:fs 写权限 gate → CC 三选卡(vendored PermissionRequest)→ decide。
-        outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, taskId, argsByCallOf(led), ctx.signal, park.gatedCallId);
+        const outcome = await surfaceFsApprovalAndDecide({ client: deps.client }, taskId, argsByCallOf(led), ctx.signal, gatedCallId);
         // #51: `outcome`'s declared type is the wider `GateOutcome |
         // FsApprovalOutcome`; both unions share a 'decided' kind with
         // different optional fields (`answered` vs `denied`), so a plain
@@ -236,9 +319,27 @@ export async function resolvePark(park, ctx) {
         if (outcome.kind === 'decided' && outcomeDenied === true && outcome.gatedCallId) {
             led.markDenied(outcome.gatedCallId); // 重放的报错帧渲 `User rejected …`(见 tool_end 有序臂 ③)
         }
+        return outcome;
+    }
+    return surfaceGateAndDecide(deps, taskId, argsByCallOf(led), ctx.signal, gatedCallId);
+}
+export async function resolvePark(park, ctx) {
+    // `deps` 不在本函数直读:呈卡/决断两族腿统一经 `surfaceParkGate`(#357 单源化,见其头注)。
+    const { led, taskId, hops } = ctx;
+    let outcome;
+    // REF-CC-034:这次 park 的候选 callId(仅 fs 分支填,已决断身份匹配用)——ask 分支不填,
+    // 因为 `surfaceGateAndDecide` 的 `!pending` 早退已经自带 `code:'no_pending'`(REF-CC-033),
+    // 不需要这条第二判据。用 `lastFsOrShellGatedCallId()` 而非「未收口 fs call 栈」:durable
+    // re-attach 重放的 `suspended` park 没有配套的新 tool_start/tool_end,那个栈在这次重放之前
+    // 早被 tool_end 的 drop 清空了(见台账声明处注),取不到候选。
+    let candidateGatedCallId;
+    if (hops > MAX_GATE_HOPS) {
+        outcome = { kind: 'failed', reason: `gate hop limit (${MAX_GATE_HOPS}) exceeded` };
     }
     else {
-        outcome = await surfaceGateAndDecide(deps, taskId, argsByCallOf(led), ctx.signal, park.gatedCallId);
+        if (park.gate === 'fs')
+            candidateGatedCallId = led.lastFsOrShellGatedCallId();
+        outcome = await surfaceParkGate(park, ctx, park.gatedCallId);
     }
     // #110 缺陷② b/c —— **重放的、早已决断过的 park 不是失败**。
     // durable re-attach 必然会把 park 帧再送一遍(`lastEventId` 再准也只能精确到帧,park 就在
@@ -250,10 +351,10 @@ export async function resolvePark(park, ctx) {
     // 同 session `--resume` 报 `No conversation found` ⇒ **整个会话废掉**。
     // 无限循环由 `hops > MAX_GATE_HOPS` 兜底(本 reattach 照常吃 hop 预算,不绕过它)。
     //
-    // REF-CC-034:`isAlreadyResolvedFailure` 是首选判据(code/文案双臂),但 fs 腿的
-    // `FsApprovalOutcome` 今天没有 `code`(toolApprovalWire.ts,C-bridge 域),失败原因若不是
-    // 那三个文案子串(例如 `approvals.list` 自身网络失败)就会漏判。已决断身份匹配是独立于
-    // 文案的第二判据 —— 两臂任一命中都按「已解决」处置,方向偏宽(见台账 `markDecided` 处注)。
+    // REF-CC-034:`isAlreadyResolvedFailure` 是首选判据(code/文案双臂;#357 起 fs 腿的取件码也
+    // 走 code 臂,见该函数头注的销案段)。失败原因若两臂都判不出(例如 `approvals.list` 自身网络
+    // 失败),已决断身份匹配是独立于文案的第二判据 —— 两臂任一命中都按「已解决」处置,方向偏宽
+    // (见台账 `markDecided` 处注)。
     //
     // [2393] hitl-F2(2026-08-02):这条身份判据**一次性消费**(`takeDecided` 而不是 `isDecided`)。
     // 它的正当性只覆盖「durable re-attach 把**那一次**已决断的 park 重放一遍」这一个窗口,而它的两个
@@ -261,15 +362,73 @@ export async function resolvePark(park, ctx) {
     // 不消费就等于:本 turn 只要成功决断过一次,之后**每一次** park 失败都被判「已解决」——
     // `approvals.list` 网络失败这类真失败会连吃 24 个 hop,最后吐一句与真因无关的 `gate hop limit`。
     // 消费点写在 `outcome.kind === 'failed'` 之内:决断成功的那一轮压根不该动这个记号。
+    //
+    // 🔴 #357(现网 P0,[5522]/[5525]):上面那条一次性只关掉了**身份腿**的空转;它的孪生腿
+    // (code/文案判据)当时没有任何限次 —— 「run 仍 parked 而取件读到空表」的**坐标失配**态下,
+    // 每一轮重放都命中 code 臂,照样烧满 24 个 hop、16 分钟长等、终帧还是那句与真因无关的预算话术
+    // ([same-shape-residue-constitution]:同一病形的第二处存量)。下面两件按 `MAX_ALREADY_RESOLVED_REATTACHES`
+    // 头注的分工落地:主修 = 坐标重探(拿当前拍的坐标真把新卡呈出去),兜底 = 同因连续限次。
     const alreadyDecidedById = outcome.kind === 'failed' &&
         candidateGatedCallId !== undefined &&
         led.takeDecided(candidateGatedCallId);
     if (outcome.kind === 'failed' && (isAlreadyResolvedFailure(outcome) || alreadyDecidedById)) {
-        const seq = led.lastSeq();
-        hostLog('debug', `liveHitlAskWire: gate already resolved (${outcome.reason}) — replayed park, re-attaching runs.events(${taskId})${seq ? ` from seq ${seq}` : ''} instead of failing the turn` +
-            (alreadyDecidedById ? ` [decidedGates id match: ${candidateGatedCallId}]` : '') +
-            (led.decidedCount() > 0 ? ` [decided so far: ${led.decidedCount()}]` : ''));
-        return { kind: 'reattach' };
+        const firstReason = outcome.reason;
+        // 键按语义分(见 `alreadyResolvedStreakKey` 头注);命中的那个文案词只进诊断串。
+        const streakKey = alreadyResolvedStreakKey(!isAlreadyResolvedFailure(outcome) && alreadyDecidedById);
+        const reasonToken = alreadyResolvedReasonToken(outcome.reason);
+        // ── 主修:坐标重探 ────────────────────────────────────────────────────────────────────
+        // 🔴 重探 = **按当前拍再读一次队列**(同一条呈卡腿、**同样的入参**)。有可决行 ⇒ 这一轮就把
+        //    新卡真呈给用户(死锁在这里破);无行 ⇒ 它照旧回同一个「已解决」,落下面的限次闸。
+        //    坐标轮换在这里是**自动**发生的:取件腿的身份腿在队列里找不到那张 park 的陈旧 callId 时
+        //    本就回落 taskId + 族谓词两腿,于是选中的正是当前拍的新行(server [5525] 的新 token 新行)。
+        // 🔴 **刻意不把身份入参抹成 `undefined`**(异源门 F10-j 当场证伪的写法):`parkGatedCallId` 在
+        //    `findPendingForTask` 里同时是「优先命中的身份」**和**「身份与本腿族属冲突时把候选池收紧」
+        //    的那把闸。抹掉它就等于把 F10-j 钉住的那条绕道兜底重新打开 —— 身份指着一行反族行、队列里
+        //    又没有别的行时,「任意行」兜底会把那行反族行捞回来呈卡 + decide(卡面全错、决断打在另一个
+        //    checkpoint 上)。重探要的是**读数新鲜**,不是**判据放宽**。
+        const rescan = isFetchStepNoPending(outcome) && hops <= MAX_GATE_HOPS
+            ? await surfaceParkGate(park, ctx, park.gatedCallId)
+            : undefined;
+        // 🔴 只有**真进展**才采信重探的结果:决断成功 / 用户 Esc / 瞬断耗尽(那一形有自己的重呈臂)。
+        //    重探自己失败(网络类、或队列确实没有可决行)⇒ **不采信**,走限次闸兜底 —— 采信的话,
+        //    一次瞬时读面故障就会把 #110 那条「重放的 park 不是失败」救回腿改判成 fail-soft(会话废掉
+        //    那条路径),代价严重不对称。
+        if (rescan !== undefined &&
+            (rescan.kind === 'decided' ||
+                rescan.kind === 'aborted' ||
+                (rescan.kind === 'failed' && rescan.retryExhausted === true))) {
+            led.resetAlreadyResolvedGate();
+            hostLog('debug', `liveHitlAskWire: gate reported already-resolved (${firstReason}) but a fresh approvals re-read for run ` +
+                `${taskId} surfaced a decidable row under the current coordinates — re-presented it (rescan: ${rescan.kind}) ` +
+                `instead of re-attaching on the stale park identity`);
+            outcome = rescan;
+        }
+        else {
+            const streak = led.noteAlreadyResolvedGate(streakKey);
+            if (streak <= MAX_ALREADY_RESOLVED_REATTACHES) {
+                const seq = led.lastSeq();
+                hostLog('debug', `liveHitlAskWire: gate already resolved (${firstReason}) — replayed park, re-attaching runs.events(${taskId})${seq ? ` from seq ${seq}` : ''} instead of failing the turn` +
+                    (alreadyDecidedById ? ` [decidedGates id match: ${candidateGatedCallId}]` : '') +
+                    (led.decidedCount() > 0 ? ` [decided so far: ${led.decidedCount()}]` : ''));
+                return { kind: 'reattach' };
+            }
+            // ── 兜底:同因连续第 2 次 ⇒ 不再空转,诚实收场 ──────────────────────────────────────
+            // 件B(可见告知):真因走**终帧的 errorMessage**(下面 fail-soft 汇流合成的那一条),不是只落
+            // debug —— 修前用户在 24 轮里什么都看不到,最后拿到的是一句关于 hop 预算的话。
+            // 🔴 如实记边界:`park.pendingDone` 在场(sync leg 的 `done{suspended}`)时,fail-soft 汇流
+            //    按既有语义原样吐那一帧、不合成 failed —— 那一格的告知面仍只有本行日志。durable 腿
+            //    (真实病形所在:`suspended` 事件无 pendingDone)恒走合成帧,真因必然上屏。
+            const stalled = `the gate reported already-resolved ${streak} times in a row while the run stayed parked, and a fresh ` +
+                `approvals re-read surfaced no decidable row for it — run/approvals coordinate mismatch ` +
+                `(last gate reason: ${firstReason})`;
+            hostLog('warn', `liveHitlAskWire: refusing to re-attach runs.events(${taskId}) again — ${stalled} ` +
+                `[criterion: ${streakKey}${reasonToken !== undefined ? ` via reason token "${reasonToken}"` : ''}]`);
+            outcome = {
+                kind: 'failed',
+                ...(outcome.gatedCallId !== undefined ? { gatedCallId: outcome.gatedCallId } : {}),
+                reason: stalled,
+            };
+        }
     }
     // Inkglow-1085 P0a —— **重呈臂**:decide 出站在瞬断类失败上重试一次仍未送达(两发都没拿到引擎的
     // 语义答复)。此刻 run 仍 parked、pending 行仍可决 —— 合成 `hitl_unanswered` 把 turn 判死是三条
@@ -325,6 +484,9 @@ export async function resolvePark(park, ctx) {
     //    `park.gatedCallId`(server ≥7.41.0 的 wire 身份)在场就点名摘,缺席则只在同族唯一时摘。
     //    这一行**刻意排在 `if (outcome.gatedCallId)` 之外**:身份在 wire 上时,摘不摘与 pending
     //    行给没给出 callId 无关(park 有主角,decide 也成功了)。
+    // #357:决断成功 = 判据链上的**真进展**,「已解决」的同因连续计数归零(否则一个 turn 里两只门
+    // 各带一次正当重放,第二只的重放会被第一只的计数顶成「第 2 次」而被闸掉)。
+    led.resetAlreadyResolvedGate();
     led.dropHeldForDecidedPark(outcome.gatedCallId, park.gatedCallId);
     if (outcome.gatedCallId) {
         // 🔴 #324:**刻意不把 pending 行的 callId 当成连坐判别的主角身份**。durable `checkpointGate`

package/dist/hitl/toolApprovalWire.d.ts

@@ -77,7 +77,7 @@
  *    静默截断);真落行与否看 ack 的 `noteRecorded`(缺席 ≠ false)。
  *    🔴 方向纪律:reason/note 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
  */
-import { type HitlClientLike } from './hitlBridge.js';
+import { type GateCurrentPending, type HitlClientLike } from './hitlBridge.js';
 import type { RuleSuggestion, ToolApprovalRespondAck } from '@sema-agent/sdk';
 /** fs 写权限 gate 判定:未来的一等 kind(tool_approval)或按 toolName(server 桥首批=fs 写三件,
  *  [820] 表)。AskUserQuestion 永不进这里(ask 桥先判)。 */
@@ -108,12 +108,26 @@ export type FsApprovalOutcome = {
 /** `retryExhausted`(Inkglow-1085 P0a,0.37.0):decide 出站在**瞬断类**失败上重试一次仍未送达
  *  (两发都没拿到引擎的语义答复)—— 在场即真。消费方(parkResolver)据此走**重呈臂**(re-attach
  *  重放 park ⇒ 同一张卡重新交给用户),不合成 `hitl_unanswered` 判死 turn。缺席 = 语义类失败
- *  (引擎答了且拒了)或卡面失败,既有 fail-soft 语义逐字节不变。 */
+ *  (引擎答了且拒了)或卡面失败,既有 fail-soft 语义逐字节不变。
+ *  `code`(#357,0.47.0):**取件当拍队列里没有本 run 的可决行** —— `findPendingForTask` 的
+ *  结构化判别位原样透传(此前本类型没有这个位,消费点只能拿 `reason` 的文案子串猜,而
+ *  `parkResolver.isAlreadyResolvedFailure` 的头注把「fs 腿没有 code」记成了已知缺口)。
+ *  🔴 只透传取件腿那一个码:decide 失败(409/404 语义答复)不落这个位 —— 那两件事对消费点
+ *  是不同处置(前者「这一拍没有行」可以重探,后者是引擎的语义答复)。 */
+/** `currentPending`(#363,0.47.0):**decide 失败**那一类才可能带 —— server S-02(≥7.52)在
+ *  409 `approval_stale` 拒体上铸的 additive **指路键**,说的是「你手上那条已经不是当前的了,
+ *  **当前**这条长这样」。壳据此**一跳重定位**再 decide,免整队重拉。
+ *  🔴 缺席是常态,而且缺席**什么都不证明**:老 server / 非工具门 / 行读失败 / 本次失败根本
+ *     不是 stale 臂,四种情形在 wire 上同形(server 自己的 F 类留痕账逐字如此)。
+ *  🔴 它**不参与任何裁决** —— 见 `GateCurrentPending` 顶注;消费方拿它当指路,不当放行凭据。
+ *  🔴 **取件腿的 `no_pending` 恒不带这一位**:那一腿连 decide 都没发,谈不上「你决的那条过期了」。 */
  | {
     kind: 'failed';
     gatedCallId?: string | undefined;
     reason: string;
+    code?: 'no_pending' | undefined;
     retryExhausted?: true;
+    currentPending?: GateCurrentPending | undefined;
 };
 /** 本桥消费的 wire 面(liveHitlAskWire 的 AskGateWireDeps 同形切片,mock 可注入)。 */
 export interface FsApprovalWireDeps {

package/dist/hitl/toolApprovalWire.js

@@ -77,7 +77,7 @@
  *    静默截断);真落行与否看 ack 的 `noteRecorded`(缺席 ≠ false)。
  *    🔴 方向纪律:reason/note 只做归因,绝不参与裁决;缺席 ⇒ 现状字节不变。
  */
-import { DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, denyReasonForWire, findPendingForTask, } from './hitlBridge.js';
+import { DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, denyReasonForWire, findPendingForTask, readDecideCurrentPending, } from './hitlBridge.js';
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
@@ -251,8 +251,10 @@ parkGatedCallId) {
     // toolName + fs/shell 名字腿),而上面那个 `matches` 只有名字腿那半 —— 拿它当身份闸会把合法的
     // kind-only 行判出局(五审 finding①)。gateKind = 行上的扁平投影,与 gate.kind 同一权威。
     (row) => isToolApprovalGate({ kind: row.gateKind, toolName: row.toolName }));
+    // #357:取件腿的结构化判别位原样透传(见 `FsApprovalOutcome.code` 头注)——「这一拍队列里没有
+    // 本 run 的可决行」与「approvals.list 自身炸了」自此对消费点结构可分,不再靠文案子串猜。
     if (!found.ok)
-        return { kind: 'failed', reason: found.reason };
+        return { kind: 'failed', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
     const { pending, gatedCallId } = found;
     const toolName = typeof pending.toolName === 'string' ? pending.toolName : '';
     // 工具入参:优先流上 tool_start.args(完整、零额外语义);缺则 pending.input(service 已 redact+限长
@@ -337,8 +339,20 @@ parkGatedCallId) {
                         // Inkglow-1085 P0a:瞬断耗尽同样**不许**回退纯 approve —— 引擎此刻根本够不着,再补一发
                         // 纯 approve 只是再烧一轮超时,还把「传输断了」错标成「老 server 不识别 remember」。
                         // 上抛给外层 catch ⇒ retryExhausted 判别位 ⇒ parkResolver 走重呈臂。
+                        // 🔴 **第三条再抛(#363,0.47.0;异源复审 [high] 采纳,真病)**:拒体带 `currentPending`
+                        // ⇒ 引擎**结构化地告诉我们**「你决的那一行已经不是当前的了,当前是这一条」——
+                        // 那和 `binding_mismatch` 是同一件事的另一种说法(人看见的那一行在他决断期间被换掉了),
+                        // 只是走的是 stale 那条码。修前它落进这条 catch-all,被当成「老 server 不识别 remember」
+                        // **并立刻用人对旧卡给的答案再发一次纯 approve** —— 正是本臂上方那条铁律禁的动作;
+                        // 而且顺带把这枚指路键吞掉(第二发若也失败,外层拍平拿到的是**第二个**错误,首发的
+                        // `currentPending` 从此不存在)。⇒ 上抛,由外层拍平臂原样带上指路键,人重新决断。
+                        // ⚠️ 边界如实说:本条只收「引擎给了指路键」这一格;「回退臂是不是应该收窄成**只**兜
+                        //    400 未知键」是**本批之前就在的**分类问题(见 §7b 登记),不在本批射程内 ——
+                        //    在一个 additive 批里悄悄改掉老引擎兼容腿的宽度,是另一种越界。
                         if (e instanceof HitlSafetyError || e instanceof DecideTransportRetryExhaustedError)
                             throw e;
+                        if (readDecideCurrentPending(e) !== undefined)
+                            throw e;
                         hostLog('debug', `liveToolApprovalWire: decide(approve+remember) failed (${String(e)}) — falling back to plain approve`);
                     }
                 }
@@ -346,12 +360,15 @@ parkGatedCallId) {
                 return { kind: 'decided', gatedCallId };
             }
             catch (e) {
+                // #363:S-02 指路键原样透传(读不出 ⇒ 键不铸,形状逐字节不变)。见 FsApprovalOutcome 同名位。
+                const currentPending = readDecideCurrentPending(e);
                 return {
                     kind: 'failed',
                     gatedCallId,
                     reason: `decide(approve) failed: ${String(e)}`,
                     // Inkglow-1085 P0a:瞬断耗尽的判别位(在场即真)—— 语义失败缺席,reason 字节不变。
                     ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+                    ...(currentPending !== undefined ? { currentPending } : {}),
                 };
             }
         case 'deny':
@@ -364,11 +381,14 @@ parkGatedCallId) {
                 return { kind: 'decided', gatedCallId, denied: true };
             }
             catch (e) {
+                // #363:与 allow 臂**同形同源**(同形存量清剿:两条 decide 失败腿一次改齐,不许只修当格)。
+                const currentPending = readDecideCurrentPending(e);
                 return {
                     kind: 'failed',
                     gatedCallId,
                     reason: `decide(deny) failed: ${String(e)}`,
                     ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+                    ...(currentPending !== undefined ? { currentPending } : {}),
                 };
             }
     }

package/dist/index.d.ts

@@ -237,6 +237,7 @@ export * from './hitl/resumeRunningCard.js';
 export * from './hitl/persistedRulesWire.js';
 export * from './hitl/localAllowRule.js';
 export * from './hitl/approvalsFeed.js';
+export * from './interactiveHalt.js';
 export * from './compensations.js';
 export * from './request/printNotification.js';
 export * from './seatContract.js';

package/dist/index.js

@@ -377,6 +377,13 @@ export * from './hitl/localAllowRule.js';
 // B7 ③(census G20,**行为改动**不是搬迁):pending-approvals 推送 feed(stream 优先 / 断流回落
 // 轮询 / 定期再试)。🔴 它**不替换** D-1 的取件 —— 那三处必须继续走权威 `list()`(见文件头)。
 export * from './hitl/approvalsFeed.js';
+// ── #363 件③(0.47.0):交互 Esc 的**停止判定**三端公共上收 ──────────────────────────────────
+// 「Esc ⇒ 先发 turn 级 halt;只有那一发连判决都拿不到、而屏上又确实挂着审批卡时,才升级成 run 级
+// cancel」——TUI/desktop/web 三端都会 Esc、都会撞同一个 parked 格,判定本该在库里。此前整条住在
+// cli 壳(`seamQuery.bestEffortInteractiveHalt` + `interruptWire.needsRunLevelStop`),那也是壳侧
+// 「裸 fetch 直拨 interrupt」那条网络面豁免**唯一**的退役条件。本模块只出**判据**(纯函数 + 引擎
+// 升级码闭集);发射/台账/留痕/UI 反馈仍归各端。🔴 零 IO、零 import、零 module 级状态。
+export * from './interactiveHalt.js';
 // ── B6 余项③(P5):补偿层登记表 —— 把「哪条补偿拆了、拆缝对面是谁、什么时候能退休」做成数据。
 // 🔴 它**不是** `ADAPTER_DIVERGENCES`(那张表说的是 adapt 与 cli 行为不同的地方;本表里的东西
 //    两侧行为相同)。自检口 `compensationSplitViolations()` 恒应为空。

package/dist/interactiveHalt.d.ts

@@ -0,0 +1,150 @@
+/**
+ * interactiveHalt — 交互 **Esc** 的停止判定层(#363 件③,0.47.0;三端公共判定上收)。
+ *
+ * ── 收的是哪一件事 ────────────────────────────────────────────────────────────────────────
+ * 「用户按 Esc ⇒ 先发 **turn 级 halt**;升级成 **run 级 cancel** 恰有**两格**:
+ *   ① 引擎自己回了升级闭集里的 **409**(它在说「这里没有在飞 turn 可切,run 级停止请用 cancel」);
+ *   ② 这一发**连判决都没拿到**(传输失败/超时/未武装)**且**屏上确实挂着审批卡(`parked`)。
+ * 其余一律不升级。」—— 这条判定 TUI / desktop / web **三端都要**(三端都会 Esc、都会撞
+ * 同一个 parked 格),此前整条住在 cli 壳里(`src/sema/seamQuery.ts` 的 `bestEffortInteractiveHalt`
+ * + `src/sema/interruptWire.ts` 的 `needsRunLevelStop`)。本模块把**判据**搬进来;
+ * **发射**(裸 fetch / SDK verb)、台账、留痕、UI 反馈仍归各端。
+ * ⚠️ 别把①漏掉(异源复审 [medium] 采纳的原文歧义):只写「拿不到判决且 parked 才升级」的话,
+ *    端会漏接**引擎明确指路**那一格 —— parked run 的会话锁不放,下一条消息照样撞「Session busy」。
+ *
+ * ── 两个动词各自唯一能做到的格(**cancel 绝不删**,本模块存在的前提)──────────────────────
+ *   · `interrupt`(turn 级,bare 形 = core `stream.halt()`「切 + 停」)—— 需要一条**活的、在飞的
+ *     turn**。这是 Esc 的正题:切掉这一轮,run 在边界上终局、同 session 下一 submit 照常续。
+ *   · `cancel`(run 级)—— 显式整 run 终局手势,而且它是**唯一**能把一条停在审批门上的
+ *     `suspended`/`needs_review` run 就地终态化、把会话锁放开的动词(server [868] 起的语义)。
+ * ⇒ 无条件把 cancel 换成 interrupt = 审批卡挂着按 Esc 的主场景当场回归成「Session busy」病;
+ *   无条件补 cancel = 同一条 run 上别的在飞工具(后台 bash 等)被连坐拆掉(#324 的病形)。
+ *   本判定就是这两条之间那道**不对称**的闸。
+ *
+ * ── 🔴 不对称是刻意的(方向安全,两条代价不等价)────────────────────────────────────────
+ * 判**不**升级的代价 = 用户退回既有的「Session busy」卡,自己再选一次(**可恢复**);
+ * 判**错**升级的代价 = 拆掉一条其实还活着的 run,连坐它身上所有在飞工具(**不可恢复**)。
+ * ⇒ 闸往严的一侧设,宁可少升一次;凡「证不出来」一律落**不升级**侧。
+ *
+ * ── 判据锚在哪 ────────────────────────────────────────────────────────────────────────────
+ *   · 升级的**第一判据 = 引擎自己的机器码**({@link RUN_LEVEL_STOP_ERROR_CODES} × 409),
+ *     不是壳对 UI 状态的猜测([anchor-on-the-deciding-quantity]);
+ *   · 只有当**引擎连判决都没给**(传输失败/超时/根本没武装)时,才轮到壳自己独立知道的那个
+ *     事实(`parked` = 这一拍屏上确实挂着审批卡 ⇒ 那条 run 停在 pending 决断上 ⇒ 本来就没有
+ *     在飞 turn 可切 ⇒ 补 cancel 不构成连坐)。
+ *
+ * 🔴 **纯判定**:零 IO、零 import、零 module 级状态,同一入参恒同一出参。
+ */
+/**
+ * server 在 interrupt 腿上表达「**这条 run 已经 parked、没有在飞 turn 可切**」的 409 机器码
+ * (engine 7.52.0 `dist/http/routes/runs.js` 真字节,`sendNoLiveTurn` 的 `isParkedRunStatus` 分支)。
+ *   · `interrupt.nothing_in_flight` —— run 停在 pending 决断上。**审批卡挂着按 Esc 的主场景就是
+ *     这一格**,server 的原话直接指路 steer/cancel。
+ *
+ * 🔴 **闭集只收这一员**,另外两个 409 都刻意在外:
+ *   · `interrupt.not_held` —— **不收**。语义是「**本副本**手上没有可切的 live turn face」,而 server
+ *     自己的两条原话把它拆得很清楚:一条是「run is live on **another replica**」,另一条是
+ *     verify/cascade 车道不暴露 live stream。**两条都不证明「全局没有在飞 turn」** —— 尤其第一条,
+ *     那条 run 正在别的副本上跑得好好的。对它升级 = 把 **turn 级** Esc 放大成**整 run 终止**。
+ *     server 提示「run-level stop 可用 cancel」是在告诉你**有这个动词**,不等于用户授权了 run 级停止。
+ *   · `steering.not_running` —— 不收。run 已终局,没有任何东西要停,补一发 cancel 是纯噪声。
+ * ⇒ 只有「引擎结构化地证明了 run 已 parked」这一格才允许升级。等上游给出 owner/parked 判别位
+ *   (或跨副本路由)之后,`not_held` 才谈得上有安全的处置。
+ *
+ * 🔴 **为什么是 `Object.freeze` 的数组而不是 `ReadonlySet`**(异源复审 [high] 采纳,真病):
+ * `ReadonlySet<string>` 只在**类型面**只读 —— 运行期它就是一只普通 `Set`,而判定查的是**同一个
+ * 实例**。任何 JS 消费者(或本包将来某处的一行手滑)`.add('interrupt.not_held')` 之后,同一份入参
+ * 就会从 `none` 变成 `escalate-cancel`,把一条**还活着**的 run 不可恢复地拆掉 —— 这正是本模块整段
+ * 头注在防的那个方向,却被自己的导出形留了后门;而「纯判定、零 module 级可变态」那句承诺也当场
+ * 变成假话。冻结数组在**运行期**真的改不动(ESM 恒 strict:`push`/下标赋值直接抛),于是「公开
+ * 面」与「判定源」可以安全地是同一个物,不必铸第二份(两份才会漂)。
+ * ⚠️ 判据形随之从 `.has()` 改成 `.includes()` —— 与同仓 `parkResolver.GATE_FAILURE_CODES` 的
+ *    `as const` 数组 + `includes` 逐字同姿势。闭集只有一员,查找成本不是这里的量。
+ */
+export declare const RUN_LEVEL_STOP_ERROR_CODES: readonly string[];
+/**
+ * 一发 bare interrupt 的归一结局(端把自己的发射结果折成这个形喂进来;**绝不是**异常)。
+ * 形与 cli `src/sema/interruptWire.ts` 的 `InterruptOutcome` 逐字同形 —— 壳换装时直接对接。
+ */
+export type InteractiveHaltInterruptOutcome = 
+/** 2xx:切 + 停受理。`turnCut` = 这一发有没有真切到一轮(重复调用第二次诚实 `false`;
+ *  读不出 ⇒ `undefined`,**不硬造 false**)。本判定不读它 —— 受理即受理。 */
+{
+    kind: 'halted';
+    turnCut?: boolean | undefined;
+}
+/** 非 2xx:引擎**给了判决**。带机器码与状态码,升级闸只认这一类。 */
+ | {
+    kind: 'refused';
+    errorCode?: string | undefined;
+    status: number;
+}
+/** 没武装(mock 车道 / live client 还没建)⇒ 一枪没打,**没有判决**。 */
+ | {
+    kind: 'unarmed';
+}
+/** 传输层失败(超时、连接断)⇒ 一样是**没拿到服务端判决**。 */
+ | {
+    kind: 'transport';
+    detail?: string | undefined;
+};
+/** 本判定的入参。 */
+export interface InteractiveHaltInput {
+    /**
+     * **这一拍屏上是否挂着审批卡**(壳自己独立知道的事实:cli = `focusedInputDialog === 'tool-permission'`)。
+     * 🔴 它只在「interrupt 连判决都没拿到」那一格起作用 —— 见 {@link planInteractiveHalt} 的分支表。
+     * 🔴 缺席 / 非 `true` 一律按**非 parked** 处理(fail-closed:证不出 parked 就不给升级资格)。
+     */
+    readonly parked?: boolean | undefined;
+    /**
+     * 首发 interrupt 的结局。**缺席 = 这一发还没打** ⇒ 本函数判 `interrupt`(首发恒行,无条件)。
+     * 在场 ⇒ 本函数回答的是「接着还要不要升级」。
+     */
+    readonly interruptOutcome?: InteractiveHaltInterruptOutcome | undefined;
+}
+/**
+ * 判决的**机读因由**(闭集;人话文案归端,别拿它当展示串 —— [machine-readable-signal-not-visual-anchor])。
+ */
+export type InteractiveHaltReason = 
+/** 还没发过 interrupt ⇒ 首发恒行(这一步不看 `parked`,不看任何东西)。 */
+'first-shot'
+/** 202 受理:这一轮已被切掉,run 在边界上终局 ⇒ 无事可做。 */
+ | 'halted'
+/** 引擎**自己**回了升级闭集里的 409 码 ⇒ 它在说「run 级停止请用 cancel」。 */
+ | 'engine-says-run-level'
+/** 连判决都没拿到(传输失败/超时/未武装),但壳自证屏上挂着审批卡 ⇒ 这一格本来就没有在飞 turn。 */
+ | 'no-verdict-on-parked-card'
+/** 连判决都没拿到且**非** parked ⇒ 那里真可能有在飞工具,凭一次超时拆整条 run 正是要消除的病。 */
+ | 'no-verdict-not-parked'
+/** 引擎给了判决,但不在升级闭集里(404 / 400 / 非 409 / `steering.not_running` / 码读不出)。 */
+ | 'refused-no-escalation'
+/** 入参不是本模块认得的任何一种结局形 ⇒ fail-closed 不升级(宿主传了新形/坏形)。 */
+ | 'unknown-outcome';
+/** 判决值:做什么 + 为什么(机读)。 */
+export interface InteractiveHaltPlan {
+    readonly action: 'interrupt' | 'escalate-cancel' | 'none';
+    readonly reason: InteractiveHaltReason;
+}
+/**
+ * Esc 停止弧的**唯一判定口**。
+ *
+ * ── 分支表(逐条 = 一条行为承诺)──────────────────────────────────────────────────────────
+ * | `interruptOutcome`                         | `parked` | 判决              | reason |
+ * |--------------------------------------------|----------|-------------------|--------|
+ * | 缺席(还没打)                              | 任意     | `interrupt`       | `first-shot` |
+ * | `halted`                                    | 任意     | `none`            | `halted` |
+ * | `refused` + 409 + 升级闭集码                 | 任意     | `escalate-cancel` | `engine-says-run-level` |
+ * | `refused`(其余:非 409 / 码不在闭集 / 码缺席)| 任意     | `none`            | `refused-no-escalation` |
+ * | `transport` / `unarmed`                     | `true`   | `escalate-cancel` | `no-verdict-on-parked-card` |
+ * | `transport` / `unarmed`                     | 其余     | `none`            | `no-verdict-not-parked` |
+ * | 认不得的形                                   | 任意     | `none`            | `unknown-outcome` |
+ *
+ * 🔴 **`parked` 只在「没有判决」那两格被读**:引擎给了判决时,判决说了算 —— 壳的 UI 状态不许覆盖
+ *    引擎的结构化答复(反过来也一样:引擎说 parked 时,`parked=false` 不阻止升级)。
+ * 🔴 **首发无条件**:`first-shot` 那一格刻意不看 `parked`。审批卡挂着时首发 interrupt 会吃一个
+ *    409,那正是升级闸要的**判决**;为了省一次往返而直接跳到 cancel,等于把判据从引擎搬回壳里猜。
+ * 🔴 **顺序契约(端必读,不是本函数能保证的那半)**:这一发必须排在「撕 SSE」**之前**。交互车道零
+ *    `x-detach-on-disconnect`,先撕流 = server 按断连语义当场收尾那条 run,随后落地的 interrupt
+ *    只会拿到 409 `steering.not_running`(cli L-11 真机实测:同步撕流形每一轮都是它)。
+ */
+export declare function planInteractiveHalt(input: InteractiveHaltInput): InteractiveHaltPlan;