@sema-agent/client-core 0.12.2 → 0.14.0

package/dist/hitl/gateLedger.js

@@ -0,0 +1,113 @@
+/** 造一份 turn 级 gate 台账(**不是单例**,见文件头注)。 */
+export function createGateLedger() {
+    const startedCalls = new Set();
+    const endedCalls = new Set();
+    const heldAskEnds = new Map();
+    const gatedStartArgsByCall = new Map();
+    const deniedCalls = new Set();
+    const pendingFsCalls = [];
+    const resolvedAnswers = new Map();
+    const decidedGates = new Set();
+    let lastFsOrShellGatedCall;
+    let denyStampNextFsEnd = false;
+    let seq;
+    return {
+        noteSeq(ev) {
+            const rawSeq = ev.id ?? ev.seq;
+            if (typeof rawSeq === 'string' && rawSeq.length > 0)
+                seq = rawSeq;
+            else if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
+                seq = String(rawSeq);
+        },
+        lastSeq() {
+            return seq;
+        },
+        markStarted(callId) {
+            if (startedCalls.has(callId))
+                return false;
+            startedCalls.add(callId);
+            return true;
+        },
+        noteGatedStart(callId, ev) {
+            gatedStartArgsByCall.set(callId, ev.args);
+        },
+        gatedStartArgs() {
+            return gatedStartArgsByCall;
+        },
+        isEnded(callId) {
+            return endedCalls.has(callId);
+        },
+        markEnded(callId) {
+            endedCalls.add(callId);
+        },
+        hold(callId, ev) {
+            heldAskEnds.set(callId, ev);
+        },
+        dropHeld(callId) {
+            heldAskEnds.delete(callId);
+        },
+        heldCount() {
+            return heldAskEnds.size;
+        },
+        *flushHeld() {
+            for (const [callId, held] of heldAskEnds) {
+                endedCalls.add(callId);
+                yield held;
+            }
+            heldAskEnds.clear();
+        },
+        markDenied(callId) {
+            deniedCalls.add(callId);
+        },
+        isDenied(callId) {
+            return deniedCalls.has(callId);
+        },
+        takeDenied(callId) {
+            return deniedCalls.delete(callId);
+        },
+        armDenyStamp() {
+            denyStampNextFsEnd = true;
+        },
+        takeDenyStamp() {
+            if (!denyStampNextFsEnd)
+                return false;
+            denyStampNextFsEnd = false;
+            return true;
+        },
+        pushFsCall(callId) {
+            pendingFsCalls.push(callId);
+        },
+        dropFsCall(callId) {
+            const at = pendingFsCalls.indexOf(callId);
+            if (at !== -1)
+                pendingFsCalls.splice(at, 1);
+        },
+        lastPendingFsCall() {
+            return pendingFsCalls.length > 0 ? pendingFsCalls[pendingFsCalls.length - 1] : undefined;
+        },
+        noteFsOrShellGate(callId) {
+            lastFsOrShellGatedCall = callId;
+        },
+        lastFsOrShellGatedCallId() {
+            return lastFsOrShellGatedCall;
+        },
+        rememberAnswer(callId, answered) {
+            resolvedAnswers.set(callId, answered);
+        },
+        answerFor(callId) {
+            return resolvedAnswers.get(callId);
+        },
+        dropAnswer(callId) {
+            resolvedAnswers.delete(callId);
+        },
+        markDecided(callId) {
+            decidedGates.add(callId);
+        },
+        takeDecided(callId) {
+            return decidedGates.delete(callId);
+        },
+        decidedCount() {
+            return decidedGates.size;
+        },
+    };
+}

package/dist/hitl/hitlBridge.d.ts

@@ -129,18 +129,55 @@ export interface PlanReviewOutcome {
  *  The caller MUST re-present to the human or surface the error — NEVER silently retry or auto-decide
  *  (contract/04 §9.1 fail-closed law). */
 export declare class HitlSafetyError extends Error {
-    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
-    readonly code: string;
+    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
+     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
+    readonly code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit';
     constructor(message: string, 
-    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
-    code: string);
+    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
+     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
+    code: 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit');
 }
 /** The active gate the downstream stream most recently suspended on (null when running). */
 export interface ActiveGate {
     gate: CheckpointGate;
     /** The durable seq of the `suspended` event, for rewind/dedup correlation (types.ts:48 eventSeq). */
-    seq?: string;
+    seq?: string | undefined;
 }
+/** Outcome of {@link findPendingForTask}. */
+export type FindPendingOutcome = {
+    ok: true;
+    pending: PendingCheckpoint;
+    gatedCallId: string | undefined;
+}
+/** `code`:结构化判别位(REF-CC-033)。'no_pending'=良性缺席(park 重放常见);缺席=真失败(list 抛)。 */
+ | {
+    ok: false;
+    reason: string;
+    code?: 'no_pending';
+};
+/**
+ * The single source for "which `PendingCheckpoint` row is the human about to decide on", used by the two
+ * decision wires (`toolApprovalWire.surfaceFsApprovalAndDecide` / `askGateWire.surfaceGateAndDecide`)
+ * BEFORE they know which specific call/question they're presenting — that is the FIRST fetch, the one
+ * that decides what gets rendered on the card/overlay.
+ *
+ * REF-CC-029(2026-08-02,消 hitl2-08/hitl2-01 双病根):this used to be three near-identical copies
+ * (this file's own `HitlBridge.findPending` plus one each in `toolApprovalWire.ts` / `askGateWire.ts`),
+ * and only `HitlBridge.findPending`'s copy had a `?? pending[0]` last-resort fallback (REF-CC-022) that
+ * could resolve a DIFFERENT session's or a background subagent lane's pending row once this taskId's own
+ * rows were gone — they all share the same `/v1/approvals` queue. Single-sourcing this lookup here means
+ * that divergence can't recur, and passing the resolved row straight into `decideTool`/`answerQuestion`'s
+ * `preResolvedPending` param closes the TOCTOU window between "the row the human saw" (this fetch) and
+ * "the row decide resolves" (previously a SECOND independent fetch inside the bridge).
+ *
+ * Match by `taskId` + a caller-supplied predicate over the row's `toolName` (the tool family this wire
+ * cares about, e.g. fs-write vs AskUserQuestion) first; fall back to ANY row for this `taskId` (a gate
+ * whose toolName the predicate doesn't recognize, but which still belongs to this run). Never `pending[0]`
+ * — a typed failure when nothing for this taskId is queued.
+ */
+export declare function findPendingForTask(client: HitlClientLike, taskId: string, matches: (toolName: string | undefined) => boolean, opts?: {
+    signal?: AbortSignal;
+}): Promise<FindPendingOutcome>;
 /**
  * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
  * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
@@ -161,13 +198,22 @@ export declare class HitlBridge {
      * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
      * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
      * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     *
+     * Used only as the fallback when a caller does NOT already have the pending row in hand (see
+     * `decideTool`/`answerQuestion`'s `preResolvedPending` param) — the wire modules that surface a card/
+     * overlay BEFORE calling decide/answer fetch the row themselves via `findPendingForTask` (below) and
+     * pass it straight through, closing the TOCTOU window between "the row the human saw" and "the row
+     * decide resolves" (REF-CC-029/hitl2-08).
      */
     private findPending;
     /**
      * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
-     * (contract/04 §2.2). Returns `{}` against a pre-D-1 worker (no binding fields) so the server can fall
-     * back to resolve-by-sessionId. `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
+     * (contract/04 §2.2). `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
      * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
+     *
+     * pre-D-1 的 `{}` 回落臂已删(2026-08-03,#117 提货 / [2356]#2):server 5.x 的 decide 三键必填、
+     * 缺键 400,「发一个注定 400 的请求」不如在本地响亮失败——pending 行缺绑定键只可能来自
+     * 不再支持的旧 worker 或坏数据,fail-loud 带坐标好过静默烧一轮 HTTP。
      */
     private bindingOf;
     /**
@@ -185,13 +231,20 @@ export declare class HitlBridge {
     decideTool(outcome: {
         decision: 'approve';
         updatedInput?: unknown;
-        remember?: 'session';
+        remember?: 'session' | undefined;
     } | {
         decision: 'deny';
-        reason?: string;
+        reason?: string | undefined;
     }, toolUseID?: string, opts?: {
         signal?: AbortSignal;
-    }): Promise<unknown>;
+    }, 
+    /** REF-CC-029(2026-08-02):the pending row the caller ALREADY fetched (via `findPendingForTask`,
+     *  below) to render the card/overlay the human just decided on. When supplied, this method skips
+     *  its own `approvals.list()` — closing the TOCTOU window between "the row the human saw" and "the
+     *  row decide resolves" (two independent fetches could otherwise land on different rows if the
+     *  first one got resolved/expired in between, hitl2-01/hitl2-08). Omit only when the caller has no
+     *  such row in hand (falls back to `findPending`). */
+    preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     /**
      * Answer an `AskUserQuestion` gate (contract/04 §4; 08 CS-16). Same suspended → decide loop as a
      * permission gate, but the answer rides `ApprovalDecision.answer` as the worker-validated
@@ -200,12 +253,16 @@ export declare class HitlBridge {
      */
     answerQuestion(answers: AskAnswer[], toolUseID?: string, opts?: {
         signal?: AbortSignal;
-    }): Promise<unknown>;
+    }, 
+    /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
+     *  fetched via `findPendingForTask`. */
+    preResolvedPending?: PendingCheckpoint): Promise<unknown>;
     /**
      * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
-     * `resume`. Guards the gate kind locally (a non-`plan_review` gate routed here would 409
-     * `gate_not_plan_review`) and the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
-     * otherwise → 400) so the bad call never leaves the shell.
+     * `resume`. Also guards the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
+     * otherwise → 400) so the bad call never leaves the shell — that check is unconditional (no
+     * `observe()` dependency). The gate-kind guard below is host-optional (see its own comment); the
+     * server's 409 `gate_not_plan_review` is the real backstop either way.
      */
     reviewPlan(outcome: PlanReviewOutcome, opts?: {
         signal?: AbortSignal;
@@ -213,7 +270,10 @@ export declare class HitlBridge {
     /**
      * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
      * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
-     * must NEVER bypass a human approval); the bridge guards locally first.
+     * must NEVER bypass a human approval). REF-CC-028(2026-08-02,评注现势):the local guard below is
+     * host-optional — it only fires when the host drives `observe(ev)` (neither production call site does
+     * today, see `reviewPlan`'s comment); the server's 409 is the fail-closed backstop that actually holds
+     * this invariant.
      */
     resumeResourceLimit(opts?: {
         signal?: AbortSignal;

package/dist/hitl/hitlBridge.js

@@ -6,13 +6,48 @@ import { eventSeq } from '../adapter/types.js';
 export class HitlSafetyError extends Error {
     code;
     constructor(message, 
-    /** A stable code the shell can branch on (`binding_mismatch` | `no_pending` | `wrong_gate` | `bad_plan_edit`). */
+    /** A stable code the shell can branch on (REF-CC-036,2026-08-02:闭集联合,不再是开集 string —
+     *  与同族兄弟 `controlRouter.ts` 的 `ControlSafetyError.code` 同形)。 */
     code) {
         super(message);
         this.code = code;
         this.name = 'HitlSafetyError';
     }
 }
+/**
+ * The single source for "which `PendingCheckpoint` row is the human about to decide on", used by the two
+ * decision wires (`toolApprovalWire.surfaceFsApprovalAndDecide` / `askGateWire.surfaceGateAndDecide`)
+ * BEFORE they know which specific call/question they're presenting — that is the FIRST fetch, the one
+ * that decides what gets rendered on the card/overlay.
+ *
+ * REF-CC-029(2026-08-02,消 hitl2-08/hitl2-01 双病根):this used to be three near-identical copies
+ * (this file's own `HitlBridge.findPending` plus one each in `toolApprovalWire.ts` / `askGateWire.ts`),
+ * and only `HitlBridge.findPending`'s copy had a `?? pending[0]` last-resort fallback (REF-CC-022) that
+ * could resolve a DIFFERENT session's or a background subagent lane's pending row once this taskId's own
+ * rows were gone — they all share the same `/v1/approvals` queue. Single-sourcing this lookup here means
+ * that divergence can't recur, and passing the resolved row straight into `decideTool`/`answerQuestion`'s
+ * `preResolvedPending` param closes the TOCTOU window between "the row the human saw" (this fetch) and
+ * "the row decide resolves" (previously a SECOND independent fetch inside the bridge).
+ *
+ * Match by `taskId` + a caller-supplied predicate over the row's `toolName` (the tool family this wire
+ * cares about, e.g. fs-write vs AskUserQuestion) first; fall back to ANY row for this `taskId` (a gate
+ * whose toolName the predicate doesn't recognize, but which still belongs to this run). Never `pending[0]`
+ * — a typed failure when nothing for this taskId is queued.
+ */
+export async function findPendingForTask(client, taskId, matches, opts) {
+    let rows;
+    try {
+        rows = (await client.approvals.list(opts)).pending;
+    }
+    catch (e) {
+        return { ok: false, reason: `approvals.list failed: ${String(e)}` };
+    }
+    const pending = rows.find((r) => r.taskId === taskId && matches(typeof r.toolName === 'string' ? r.toolName : undefined)) ??
+        rows.find((r) => r.taskId === taskId);
+    if (!pending)
+        return { ok: false, reason: 'no pending checkpoint for this run (resolved/expired?)', code: 'no_pending' };
+    return { ok: true, pending, gatedCallId: pending.toolCallId ?? pending.boundCallId ?? undefined };
+}
 /**
  * The bridge state. One per run/session. The shell feeds it `suspended` events (observe) and the human's
  * outcome (decide / answer / planReview); it owns the `approvals.list()` join + the verbatim binding echo.
@@ -59,6 +94,12 @@ export class HitlBridge {
      * Find the `PendingCheckpoint` the human is about to decide on. Joins by `toolCallId` when CC hands a
      * `toolUseID`; otherwise falls back to the single pending row for this run's `taskId`. Returns null when
      * the queue is empty (e.g. resolved/expired under the human → the caller must refetch + re-present).
+     *
+     * Used only as the fallback when a caller does NOT already have the pending row in hand (see
+     * `decideTool`/`answerQuestion`'s `preResolvedPending` param) — the wire modules that surface a card/
+     * overlay BEFORE calling decide/answer fetch the row themselves via `findPendingForTask` (below) and
+     * pass it straight through, closing the TOCTOU window between "the row the human saw" and "the row
+     * decide resolves" (REF-CC-029/hitl2-08).
      */
     async findPending(toolUseID, opts) {
         const { pending } = await this.client.approvals.list(opts);
@@ -70,22 +111,29 @@ export class HitlBridge {
                 return byCall;
         }
         // Fall back to this run's pending row (the suspended run holding the session claim).
-        const byTask = pending.find((p) => p.taskId === this.taskId);
-        return byTask ?? pending[0] ?? null;
+        // REF-CC-022(2026-08-02): NEVER `?? pending[0]` — once this taskId's own rows are exhausted, the
+        // first queue row can belong to a DIFFERENT session or a background subagent lane (they share the
+        // same `/v1/approvals` queue); deciding on it would resolve someone else's gate. A miss here is a
+        // real `no_pending` — the caller's existing typed-fail path (and exactly the signal #110's
+        // cancel-by-deny-recovery arm expects), not "decide on whatever happens to be first".
+        return pending.find((p) => p.taskId === this.taskId) ?? null;
     }
     /**
      * Build the D-1 binding off the pending row the human SAW. Echo VERBATIM — NEVER recompute the hash
-     * (contract/04 §2.2). Returns `{}` against a pre-D-1 worker (no binding fields) so the server can fall
-     * back to resolve-by-sessionId. `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
+     * (contract/04 §2.2). `checkpointToken` is DELIBERATELY never set (deprecated legacy path;
      * compliant clients send ONLY the two-tuple, approvals.ts:23-27).
+     *
+     * pre-D-1 的 `{}` 回落臂已删(2026-08-03,#117 提货 / [2356]#2):server 5.x 的 decide 三键必填、
+     * 缺键 400,「发一个注定 400 的请求」不如在本地响亮失败——pending 行缺绑定键只可能来自
+     * 不再支持的旧 worker 或坏数据,fail-loud 带坐标好过静默烧一轮 HTTP。
      */
     bindingOf(p) {
-        const binding = {};
-        if (p.boundCallId !== undefined)
-            binding.boundCallId = p.boundCallId;
-        if (p.boundInputHash !== undefined)
-            binding.boundInputHash = p.boundInputHash;
-        return binding;
+        if (p.boundCallId === undefined || p.boundInputHash === undefined) {
+            throw new HitlSafetyError(`pending checkpoint ${p.id ?? '<no-id>'} is missing D-1 binding fields ` +
+                `(boundCallId=${String(p.boundCallId)}, boundInputHash=${String(p.boundInputHash)}) — ` +
+                'pre-D-1 workers are no longer supported (server 5.x requires the verbatim two-tuple echo)', 'binding_mismatch');
+        }
+        return { boundCallId: p.boundCallId, boundInputHash: p.boundInputHash };
     }
     // ── §2. Permission gate: approve / deny a tool ──────────────────────────────
     /**
@@ -100,8 +148,15 @@ export class HitlBridge {
      * The resumed run continues its SAME durable stream. A binding mismatch (409) is re-raised as a
      * `HitlSafetyError('binding_mismatch')` — the caller re-presents, NEVER auto-retries.
      */
-    async decideTool(outcome, toolUseID, opts) {
-        const pending = await this.findPending(toolUseID, opts);
+    async decideTool(outcome, toolUseID, opts, 
+    /** REF-CC-029(2026-08-02):the pending row the caller ALREADY fetched (via `findPendingForTask`,
+     *  below) to render the card/overlay the human just decided on. When supplied, this method skips
+     *  its own `approvals.list()` — closing the TOCTOU window between "the row the human saw" and "the
+     *  row decide resolves" (two independent fetches could otherwise land on different rows if the
+     *  first one got resolved/expired in between, hitl2-01/hitl2-08). Omit only when the caller has no
+     *  such row in hand (falls back to `findPending`). */
+    preResolvedPending) {
+        const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending checkpoint to decide (resolved/expired under the human) — refetch + re-present', 'no_pending');
         }
@@ -131,8 +186,11 @@ export class HitlBridge {
      * `{ answers: [{ header, selected, note? }] }` shape. The D-1 binding STILL binds (it is still a
      * checkpoint). Each answer's `header` MUST match a question header (the worker 400s on mismatch).
      */
-    async answerQuestion(answers, toolUseID, opts) {
-        const pending = await this.findPending(toolUseID, opts);
+    async answerQuestion(answers, toolUseID, opts, 
+    /** REF-CC-029(2026-08-02):see `decideTool`'s same-named param — the pending row the caller already
+     *  fetched via `findPendingForTask`. */
+    preResolvedPending) {
+        const pending = preResolvedPending ?? (await this.findPending(toolUseID, opts));
         if (!pending) {
             throw new HitlSafetyError('no pending AskUserQuestion checkpoint to answer — refetch + re-present', 'no_pending');
         }
@@ -146,13 +204,20 @@ export class HitlBridge {
     // ── §4. plan_review: the distinct wire ──────────────────────────────────────
     /**
      * Resolve a plan-mode gate (contract/04 §3; 08 IH-6). Routed to `assistant.planReview`, NOT `decide`/
-     * `resume`. Guards the gate kind locally (a non-`plan_review` gate routed here would 409
-     * `gate_not_plan_review`) and the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
-     * otherwise → 400) so the bad call never leaves the shell.
+     * `resume`. Also guards the `editedPlan` invariant (REQUIRED iff `decision==="edit"`, FORBIDDEN
+     * otherwise → 400) so the bad call never leaves the shell — that check is unconditional (no
+     * `observe()` dependency). The gate-kind guard below is host-optional (see its own comment); the
+     * server's 409 `gate_not_plan_review` is the real backstop either way.
      */
     async reviewPlan(outcome, opts) {
         // Gate-kind guard (contract/04 §3.1): plan_review parks as needs_review / plan_review, distinct from the
-        // approval family. If the active gate is a tool/resource gate, refuse locally rather than 409 the server.
+        // approval family. REF-CC-028(2026-08-02,评注现势):this.active only latches when the host calls
+        // `observe(ev)` on the downstream stream — BOTH production construction points
+        // (askGateWire.ts / toolApprovalWire.ts) build a fresh `HitlBridge` per decide and never call
+        // `observe`, so `this.active` is null and this guard is a no-op there today. It is a host-optional
+        // auxiliary: a host that DOES drive `observe()` gets a local refuse instead of a round-trip; a host
+        // that doesn't (today's shell) relies entirely on the server's 409 `gate_not_plan_review` fail-closed
+        // path — the safety property holds either way, this guard just saves the round-trip when wired.
         const kind = this.active?.gate.kind;
         if (kind && kind !== 'plan_review' && kind !== 'needs_review') {
             throw new HitlSafetyError(`cannot plan-review a "${kind}" gate — a plan decision must never resolve a tool approval`, 'wrong_gate');
@@ -167,7 +232,10 @@ export class HitlBridge {
             throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
         }
         const req = { decision: outcome.decision };
-        if (outcome.decision === 'edit')
+        // eopt:上面的 invariant 检查已经保证 decision==='edit' ⇒ editedPlan 非空,但那道保证隔着一个
+        // 已经关闭的 if 块,TS 不跨块记账——这里重新直接判一次 undefined,narrowing 与赋值同一表达式内完成
+        // (PlanReviewRequest 是 SDK 外部 wire 型,不能改;诚实缺席 = 键不落,不传 `editedPlan: undefined`)。
+        if (outcome.decision === 'edit' && outcome.editedPlan !== undefined)
             req.editedPlan = outcome.editedPlan;
         if (outcome.reason !== undefined)
             req.reason = outcome.reason;
@@ -177,7 +245,10 @@ export class HitlBridge {
     /**
      * Continue a `resource_limit` slice pause (contract/04 §6.1; 08 IH-9). Bodyless `assistant.resume` — NOT
      * `decide`. A `human`/`irreversible_ask` gate routed here would 409 `gate_not_resumable` (a "continue"
-     * must NEVER bypass a human approval); the bridge guards locally first.
+     * must NEVER bypass a human approval). REF-CC-028(2026-08-02,评注现势):the local guard below is
+     * host-optional — it only fires when the host drives `observe(ev)` (neither production call site does
+     * today, see `reviewPlan`'s comment); the server's 409 is the fail-closed backstop that actually holds
+     * this invariant.
      */
     async resumeResourceLimit(opts) {
         const kind = this.active?.gate.kind;
@@ -233,7 +304,8 @@ export function makeHitlCanUseTool(bridge, prompt) {
     };
 }
 // ── helpers ───────────────────────────────────────────────────────────────────
-/** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`. */
+/** Marshal one answer into the worker-validated wire entry (contract/04 §4.1). Drops undefined `note`.
+ *  REF-CC-038(2026-08-02):return 类型是 `AskAnswer` 本身(唯一源),不再是一份重写的内联匿名形。 */
 function marshalAnswer(a) {
     const entry = {
         header: a.header,

package/dist/hitl/hitlHostSurface.d.ts

@@ -0,0 +1,49 @@
+import type { ClassifierDenyVerdict } from '../classifierVerdictWire.js';
+/** footer 通知(壳 `AppState.notifications.current` 的形)。 */
+export interface HitlNotice {
+    key: string;
+    text: string;
+    color: 'warning';
+    priority: 'immediate';
+    timeoutMs: number;
+}
+/** HITL 的宿主副作用面 —— 通知上屏 + 分类器 deny 的端侧记账。 */
+export interface HitlHostSurface {
+    /** 立即顶到 current(壳:`notifications.current = notice`,queue 不动)。 */
+    showNotice(notice: HitlNotice): void;
+    /** **仅当** current 仍是这个 key 时清掉(壳原文的 if-still-mine 语义 —— 否则会误清别人的通知)。 */
+    clearNoticeIfCurrent(key: string): void;
+    /** 分类器 deny 裁决的宿主副作用:footer 通知 + /permissions Recent Denials 记账(壳资产)。 */
+    surfaceClassifierDeny(toolName: string, verdict: ClassifierDenyVerdict): void;
+}
+/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
+export declare function installHitlHostSurface(surface: HitlHostSurface | null): () => void;
+/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
+export declare function installHitlHostSurfaceFor(sessionKey: string, surface: HitlHostSurface | null): () => void;
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
+export declare function hitlHostSurfaceMisses(): number;
+/** W1 带 key 变体(miss 计数逐键)。 */
+export declare function hitlHostSurfaceMissesFor(sessionKey: string): number;
+/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
+export declare function hitlHostSurfaceFor(sessionKey: string): HitlHostSurface | null;
+/** 测试钩:卸口 + 清计数。 */
+export declare function _resetHitlHostSurfaceForTest(): void;
+/** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
+ *  `surfaceCancelDenyWarn` 共用它。 */
+export declare function surfaceForCurrentSession(): HitlHostSurface | null;
+/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
+ *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
+ *  只是多一行良性 warn,比锁死无线索诚实)。 */
+export declare const CANCEL_DENY_BUDGET_MS = 2000;
+/** warn 行文案(测试锁字面)。 */
+export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
+/**
+ * 中断 deny 的有界观察(壳侧单测 `hitlCancelDeny.test.ts` 的被测面;REF-CC-023 起两条决断腿共用)。
+ * 铁律:不 await 进 abort 返回路径(用户立即拿回控制);这里只管后台 settle 的«观察»:
+ *   - 2s 内 settle 成功 ⇒ 零上屏(SEMA_DEBUG 记成功);
+ *   - 失败/超时 ⇒ 上屏一行 warn + SEMA_DEBUG 记原因(deny 丢失 = run 卡 suspended,下一条消息
+ *     撞 409;配合件2b 的专属文案,用户知道现场 + 出路);
+ *   - `code === 'no_pending'`(判据见上方 `isNoPendingError`)⇒ 良性静默(pending 已被别处消解/
+ *     过期 —— run 没锁;hitlBridge decideTool 的同款语义,那里的静默维持不动)。
+ */
+export declare function observeCancelByDeny(settle: Promise<unknown>, taskId: string): void;