@sema-agent/client-core 0.12.0 → 0.12.2

package/README.md

@@ -23,7 +23,7 @@ Renamed from **`@sema-agent/wire-cc-adapter`** (0.1.x, deprecated — see *Migra
 
 ## Scope
 
-**Version:** 0.11.23
+**Version:** 0.12.2
 
 - **Today** — the adapter seam, the whole `adapt()` pipeline (all 14 A-layer arms plus the
   B/D/E tool-card layers), the notification/caps/model families, the adapter kernel (stream driver
@@ -217,6 +217,8 @@ itself (FAILED names + skipped names + arithmetic reconciliation). All-SKIP repo
 | `scripts/run-background-view-test.mjs` | `createBackgroundView` lifecycle: polling/notify pairing, per-source degrade (`501 → not-configured` vs `unavailable`), the capabilities `scheduler` probe, and dispose really aborting the in-flight fleet snapshot (pure projection lives in the pure suite's W-A segment) |
 | `scripts/run-fleet-view-keys-test.mjs` | The fleet projection views, **both directions**: `FleetTaskView`/`FleetWorkflowView` ⇄ their key lists (compile-pinned) ⇄ what a maximal/minimal row really projects, plus a wire-key coverage ledger (every `FleetTaskRow` key is either projected or carries a written reason why not) and a drift ledger against the shell's render contract. A one-directional assignability check is blind to optional keys — which is how `startedAt` was silently dropped |
 | `scripts/run-usage-verbatim-channel-test.mjs` | The two complementary usage disciplines (core 3.0.0 metering semantics): the CC `ModelUsage` mirror stays pure (five pinned keys, `totalInputTokens` has no seat), while the sema-owned channel forwards the engine `turn_end.usage` object **verbatim** (six keys, incl. `totalInputTokens`) via `last_turn_usage.engineUsage` / `handle.latestEngineUsage` — honest absence on pre-3.0.0 engines, no fabricated zeros |
+| `scripts/run-plan-review-decide-verify-test.mjs` | `decidePlanReview`'s post-decide honesty ([2315]/[2316], engine RB-471 family): a 2xx from the decide endpoint is **not** a terminal — the wire re-pulls the task status and words the outcome by the real shape (still-locked / legal new gate / genuinely left park / unverified), never claiming success it hasn't earned. Driven against a real fake-engine HTTP server through the shipped dist |
+| `scripts/run-shell-gate-durable-allow-test.mjs` | #110: the durable approval leg for **shell** gates. The tool_end HOLD/REJECT predicate must cover Bash the same way park detection already does (otherwise the park poison frame `Operation aborted` hits the transcript, `endedCalls` swallows the real replayed result, and the user who pressed Yes watches a command that really ran be reported as aborted); a replayed, already-decided park must resume reading the stream instead of being reported as a failed turn; `lastEventId` must track numeric `seq` too. Mutation-proven: each of the three fixes reverted turns the gate red |
 | `scripts/run-public-surface-test.mjs` | The outward promises: the npm export surface baseline, the peer floor witness, and this README's claims |
 
 Each suite carries a floor that only moves up — a refactor that stops executing a group of

package/dist/hitl/askGateWire.js

@@ -2,7 +2,7 @@ import { HitlBridge } from './hitlBridge.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { isToolApprovalGate, toolNameIsFsWrite, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
+import { isToolApprovalGate, toolNameIsFsWrite, toolNameIsShellExec, surfaceFsApprovalAndDecide, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
 import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 // W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层(cli 装配不动)。
 const hostSurfaceByKey = createSessionSlot();
@@ -57,6 +57,42 @@ const MAX_GATE_HOPS = 24;
 /** core 对被 gate/连坐 abort 的 call 铸的 tool_end 载体(逐字;desktop session-host 真引擎实测
  *  同款)——HOLD 谓词锚它做**精确等值**,普通工具错的输出是各自错误文案,永不进 HOLD。 */
 export const ENGINE_ABORT_TOOL_RESULT = 'Operation aborted';
+/**
+ * 「这个工具名归 gate 管」的**统一**判据(#110 修,2026-08-02)。
+ *
+ * 🔴 它必须与 park 判定(`isAskTool` / `isToolApprovalGate`)覆盖**同一个集合** ——
+ * 两边不同集就是 [paired-mechanisms-must-share-premise] 那种「park 认得出、HOLD 认不出」的
+ * 半场病:[2150] S1 给 park 判定加了 `toolNameIsShellExec`(Bash/shell 类进 gate 了),但
+ * 本文件 tool_end 手柄的 HOLD/REJECT 谓词还停在 `isAskTool || toolNameIsFsWrite` ——
+ * 于是 Bash 的 durable gate 走到这里就两件事同时出错:
+ *   ① park 期的毒化帧(`tool_end{isError:true, output:"Operation aborted"}`)没被 HOLD,
+ *      **当场上屏**;用户按了 Yes、命令也真跑了,屏幕上却永远停在 `Error: Operation aborted`;
+ *   ② 更狠的是紧接着的 `endedCalls.add(toolCallId)` —— resume 后引擎重放的**真** tool_end
+ *      被手柄开头的 `if (endedCalls.has(...)) continue` 静默去重,真结果一帧都上不了屏。
+ * 附带第三件:deny 腿的 `User rejected …` 文案对 Bash 同样进不去,用户看到的是引擎原文。
+ * 证据链见 cli 仓 design/cli-164 T4-A(硬 oracle=磁盘状态:按 Yes 后 printf +504ms 真落盘)。
+ */
+/**
+ * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。
+ *
+ * 判据锚在**语义词**而不是整句:上游改文案是常事,而 `no pending checkpoint` / `resolved` /
+ * `already` 三者任一在场就足以把「重放的已决断 park」与真失败(网络断、决断超时、hop 超限)分开。
+ * 🔴 方向:这条判**错**的后果不对称 —— 误判成「已解决」最多让流多读一轮(hop 预算兜底),
+ * 误判成「真失败」会把一个已经 completed 的 run 谎报成失败并烧掉整条会话转录。所以宁可宽。
+ */
+function isAlreadyResolvedGateReason(reason) {
+    if (typeof reason !== 'string')
+        return false;
+    const r = reason.toLowerCase();
+    return r.includes('no pending checkpoint') || r.includes('resolved') || r.includes('already');
+}
+function isGatedToolName(name) {
+    if (isAskTool(name))
+        return true;
+    if (typeof name !== 'string')
+        return false;
+    return toolNameIsFsWrite(name) || toolNameIsShellExec(name);
+}
 function isAskTool(name) {
     return typeof name === 'string' && name.replace(/[\s_-]+/g, '').toLowerCase() === 'askuserquestion';
 }
@@ -300,6 +336,17 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
      *  不补就会渲成结果不可用;这里 stamp `structured` 让卡片渲真实选择。 */
     const resolvedAnswers = new Map();
     let lastSeq;
+    /**
+     * 已经决断过的 gate 身份(#110 缺陷② 的**承重**修,2026-08-02)。
+     *
+     * durable re-attach 会把「已经决断过的 park」重放一遍(边界上必然发生:`lastEventId` 再准也
+     * 只能精确到帧,park 帧本身就在续流的重放窗口里)。重放的 park 走到下面会去
+     * `surfaceFsApprovalAndDecide` 取 pending approval —— 那一行早已 resolved ⇒ 拿不到 ⇒
+     * `failed` ⇒ 合成 `hitl_unanswered` 终帧。而引擎侧 run 其实已经 `completed`:壳谎报失败,
+     * 连带 CC 转录 0 行写出、同 session `--resume` 报 `No conversation found` —— **会话废掉**。
+     * 与 `startedCalls`/`endedCalls` 同款的身份去重是这条的正解:决断过的 gate 不再决断第二次。
+     */
+    const decidedGates = new Set();
     let realTaskId = opts?.taskId;
     let stream = source;
     let hops = 0;
@@ -314,9 +361,14 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
         /** park 请求:遇 AskUserQuestion / fs 写权限 gate 时置位后 break 内环。 */
         let park = null;
         for await (const ev of stream) {
-            const seq = ev.id;
-            if (typeof seq === 'string' && seq.length > 0)
-                lastSeq = seq;
+            // #110 缺陷② a:`lastSeq` 要跟得上**已消费的最大 seq**。durable `runs.events` 流上并非每帧
+            // 都带 `id`(数字 `seq` 位的帧同样在场),旧式只吃 `ev.id` ⇒ 停在最后一个带 id 的帧上 ⇒
+            // re-attach 从一个陈旧位置重放,把已经决断的 park 又送一遍(实测:消费到 16 却 attach from 8)。
+            const rawSeq = ev.id ?? ev.seq;
+            if (typeof rawSeq === 'string' && rawSeq.length > 0)
+                lastSeq = rawSeq;
+            else if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
+                lastSeq = String(rawSeq);
             // ── [2084]① 扣留帧「模型推进即放行」(2026-07-30;同日 web 复审纠偏收窄触发集)──────────
             // HOLD 只护 park 窗口。放行触发集 = host-lane **模型推进**帧:text_delta/reasoning_delta/
             // tool_start —— park 路径上这三种在 done{suspended} 之前不会出现,真错路径上下一轮必来其一。
@@ -392,7 +444,8 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
                 if (startedCalls.has(ev.toolCallId))
                     continue; // durable 重放的已渲 call
                 startedCalls.add(ev.toolCallId);
-                if (isAskTool(ev.toolName) || (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName))) {
+                if (isGatedToolName(ev.toolName)) {
+                    // #110:Bash 也要记 args —— 卡片渲染要拿到 `command`,不记则 shell gate 的卡面空着。
                     askArgsByCall.set(ev.toolCallId, ev.args);
                     if (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName)) {
                         pendingFsCalls.push(ev.toolCallId);
@@ -425,8 +478,9 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
                     }
                 }
                 if (ev.isError === true &&
-                    typeof ev.toolName === 'string' &&
-                    toolNameIsFsWrite(ev.toolName) &&
+                    // #110:同步帧腿 deny 的 stamp 也要盖 shell —— 否则按 No 时用户看到的是引擎原文
+                    // `Operation aborted` 而不是 CC 的 `User rejected …`。
+                    isGatedToolName(ev.toolName) &&
                     denyStampNextFsEnd &&
                     !deniedCalls.has(ev.toolCallId)) {
                     // 同步帧腿 deny 且 callId 没关联上:下一张 fs 写报错帧即该 gate 的收口帧,stamp REJECT 文案。
@@ -436,8 +490,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
                     yield { ...ev, output: rejectMessageForRender(), structured: undefined };
                     continue;
                 }
-                if (ev.isError === true &&
-                    (isAskTool(ev.toolName) || (typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName)))) {
+                if (ev.isError === true && isGatedToolName(ev.toolName)) {
                     if (deniedCalls.has(ev.toolCallId)) {
                         // 三选卡 No:重放的报错帧 stamp REJECT 文案 → vendored 卡渲 `User rejected <op> to <path>`。
                         deniedCalls.delete(ev.toolCallId);
@@ -542,6 +595,24 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
         else {
             outcome = await surfaceGateAndDecide(deps, realTaskId, askArgsByCall, opts?.signal);
         }
+        // #110 缺陷② b/c —— **重放的、早已决断过的 park 不是失败**。
+        // durable re-attach 必然会把 park 帧再送一遍(`lastEventId` 再准也只能精确到帧,park 就在
+        // 重放窗口里)。这时 approval 行早已 resolved,`surfaceFsApprovalAndDecide` 取不到 pending,
+        // 返回 `failed: no pending checkpoint for this run (resolved/expired?)` —— 那句话的语义恰恰是
+        // **「这个 gate 已经被解决了」**,正确处置是**继续读流**(引擎那边 run 正常往下跑,实测
+        // `run.json status="completed"`),而不是宣布 turn 失败。旧行为的代价不是一句错文案:
+        // 终帧被投影成 `error_during_execution` ⇒ 壳走失败路径 ⇒ CC 转录**一行都不写** ⇒
+        // 同 session `--resume` 报 `No conversation found` ⇒ **整个会话废掉**。
+        // 无限循环由 `hops > MAX_GATE_HOPS` 兜底(本 continue 照常吃 hop 预算,不绕过它)。
+        if (outcome.kind === 'failed' && isAlreadyResolvedGateReason(outcome.reason)) {
+            hostLog('debug', `liveHitlAskWire: gate already resolved (${outcome.reason}) — replayed park, re-attaching runs.events(${realTaskId})${lastSeq ? ` from seq ${lastSeq}` : ''} instead of failing the turn` +
+                (decidedGates.size > 0 ? ` [decided so far: ${decidedGates.size}]` : ''));
+            stream = deps.runsEvents(realTaskId, {
+                ...(lastSeq !== undefined ? { lastEventId: lastSeq } : {}),
+                ...(opts?.signal ? { signal: opts.signal } : {}),
+            });
+            continue;
+        }
         if (outcome.kind !== 'decided') {
             hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}${'reason' in outcome ? `: ${outcome.reason}` : ''}) — fail-soft to suspended terminal`);
             yield* flushHeld(); // 回退:毒化帧照旧渲染(= 修复前的诚实红)
@@ -565,6 +636,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
         // 并记下真实答案供该解答帧 stamp `structured`(否则卡片渲成结果不可用)。
         if (outcome.gatedCallId) {
             heldAskEnds.delete(outcome.gatedCallId);
+            decidedGates.add(outcome.gatedCallId); // #110 缺陷② b:决断过的 gate 身份留痕(诊断面)
             if ('answered' in outcome && outcome.answered)
                 resolvedAnswers.set(outcome.gatedCallId, outcome.answered);
         }

package/dist/hitl/planReviewWire.js

@@ -119,7 +119,48 @@ export async function decidePlanReview(taskId, decision) {
     try {
         const body = await client.assistant.planReview(taskId, { decision });
         hostLog('debug', `planReviewWire: ${decision} → ok ${JSON.stringify(body).slice(0, 200)}`);
-        outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${body?.status ?? 'unknown'}.`;
+        // [2315]/[2316](#109,2026-08-02):decide 的 **2xx 不当终态** —— test 黑盒实测 reject 9/9
+        // 返回 200 而会话仍锁在同一 gate(core RB-471:重开兜底对 reject 腿恒真误触发)。这里回拉
+        // 一次任务状态,按真形分三路措辞;根因归 core/server,本腿是「对外动作回读验证」在产品面的
+        // 同款,上游修后仍有价值(approve 合法推进新 gate 的形也靠它说真话)。
+        // 回拉用**短超时**独立 client(15s):verify 腿挂住不该占用 decide 的 6h 宽预算。
+        let postStatus;
+        try {
+            const probe = makeEngineWireClient({
+                baseUrl: cfg.baseUrl,
+                ...(cfg.token ? { token: cfg.token } : {}),
+                principal: cfg.principal,
+                timeoutMs: 15_000,
+            });
+            const post = probe ? (await probe.runs.get(taskId)) : null;
+            postStatus = typeof post?.status === 'string' ? post.status : undefined;
+        }
+        catch (e) {
+            hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
+        }
+        // 回拉失败时回落 decide 200 体自带的 status(次级来源;两者都缺=unverified,措辞如实降级)。
+        const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+        if (effective === 'needs_review') {
+            // 决定没生效,仍锁原 gate。不渲「已处理」;真出路只有 approve 或 cancel(下一次提交撞 409
+            // 时 activeRunSelfHeal 会把审批卡重开——这里不自动重弹卡,避免「刚拒绝又弹卡」的突袭感,
+            // 决定权经卡的重开路径还给用户)。
+            outcome =
+                `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
+                    `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
+                    `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
+        }
+        else if (effective === 'suspended') {
+            // 合法推进到新 gate(test [2315] ②形):不是「完成」,如实说下一张审批卡会跟上。
+            outcome =
+                `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
+                    `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
+        }
+        else if (effective !== undefined) {
+            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
+        }
+        else {
+            outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: unknown (post-decide verification unavailable; treat as unconfirmed).`;
+        }
     }
     catch (e) {
         // APIError 判型走 status duck-check(sseIdleTriage 同款纪律:双包时 instanceof 会分叉)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",