@sema-agent/client-core 0.12.1 → 0.13.0

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;

package/dist/hitl/hitlHostSurface.js

@@ -0,0 +1,155 @@
+/**
+ * hitlHostSurface.ts — REF-CC-023(2026-08-02,P3 wave2 卡C-bridge):共享的 HITL 宿主通知面
+ * + cancel-by-deny 有界观察,从 `askGateWire.ts` 提出来给 `toolApprovalWire.ts` 也用。
+ *
+ * 🔴 为什么要提出来(不是顺手重排):`askGateWire.ts` 已经 `import` `toolApprovalWire.ts`(§ ask 桥
+ * 消费工具审批帧判定),反向 `toolApprovalWire.ts` → `askGateWire.ts` 会成环。`observeCancelByDeny`
+ * 曾经只活在 `askGateWire.ts` 里,而 `toolApprovalWire.ts:surfaceFsApprovalAndDecide` 的中断-deny
+ * 臂原样复刻了它要修的那个事故(件3,中断事故修复批 G,2026-07-15):裸 `.catch(()=>{})` 全吞 ⇒
+ * deny 丢失时 run 永卡 suspended、session 锁死,用户下一条消息撞 409「active run」还全无线索。
+ * 单源到一个两边都能 import 的模块,两条腿共用同一次修复,而不是「同一个仓、同一个事故、
+ * 一处修了另一处原样留着」。
+ *
+ * 这个模块也顺带带走了 `surfaceCancelDenyWarn` 唯一依赖的宿主通知面(`HitlHostSurface` /
+ * `installHitlHostSurface*` / `hitlHostSurfaceFor*`)—— 它不只是给 cancel-by-deny 用(分类器 deny
+ * 的端侧记账 `surfaceClassifierDeny` 也走它),`askGateWire.ts` 仍然是它的主要消费方,只是不再是
+ * 唯一持有方。
+ */
+import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+import { hostLog } from '../host.js';
+import { unrefTimer } from '../unrefTimer.js';
+import { HitlSafetyError } from './hitlBridge.js';
+// W1(design/161):sessionKey → 注册表;零参 API = DEFAULT_SESSION_KEY 兼容层(cli 装配不动)。
+const hostSurfaceByKey = createSessionSlot();
+const hostSurfaceMissesByKey = new Map();
+/** 装 HITL 宿主面(传 null 卸)。返回还原函数。 */
+export function installHitlHostSurface(surface) {
+    return installHitlHostSurfaceFor(DEFAULT_SESSION_KEY, surface);
+}
+/** W1 带 key 变体:装/卸某会话的 HITL 宿主面(多会话宿主每会话一键,互不顶盖)。 */
+export function installHitlHostSurfaceFor(sessionKey, surface) {
+    const prev = hostSurfaceByKey.get(sessionKey);
+    hostSurfaceByKey.set(sessionKey, surface);
+    return () => {
+        hostSurfaceByKey.set(sessionKey, prev);
+    };
+}
+/** 🔴 宿主自检:恒应为 0。非 0 = 有 HITL 副作用发生时口不在,那一行 warn / 那条记账丢了。 */
+export function hitlHostSurfaceMisses() {
+    return hitlHostSurfaceMissesFor(DEFAULT_SESSION_KEY);
+}
+/** W1 带 key 变体(miss 计数逐键)。 */
+export function hitlHostSurfaceMissesFor(sessionKey) {
+    return hostSurfaceMissesByKey.get(sessionKey) ?? 0;
+}
+/** W1 读端:某会话的 HITL 宿主面(未装 = null;**不计 miss** —— miss 只在副作用真发生时计)。 */
+export function hitlHostSurfaceFor(sessionKey) {
+    return hostSurfaceByKey.get(sessionKey) ?? null;
+}
+/** 测试钩:卸口 + 清计数。 */
+export function _resetHitlHostSurfaceForTest() {
+    hostSurfaceByKey.clear();
+    hostSurfaceMissesByKey.clear();
+}
+/** 内部读点(计 miss)。`askGateWire.ts` 的 `surfaceClassifierDeny` 路径与本文件的
+ *  `surfaceCancelDenyWarn` 共用它。 */
+export function surfaceForCurrentSession() {
+    const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
+    if (hostSurface === null) {
+        hostSurfaceMissesByKey.set(DEFAULT_SESSION_KEY, (hostSurfaceMissesByKey.get(DEFAULT_SESSION_KEY) ?? 0) + 1);
+    }
+    return hostSurface;
+}
+// ── 件3(中断事故修复批 G,2026-07-15)—— 中断 deny 的有界观察 ─────────────────────────────────
+/** cancel-by-deny 的后台 settle 预算。decide 是 SYNC 驱动的(引擎跑到下一 park/终态才返,实测
+ *  4-5s+),但 DENY-abort 语义上引擎收到即终结 run;2s 内连收都没收到 ⇒ 按丢失警示(晚到成功
+ *  只是多一行良性 warn,比锁死无线索诚实)。 */
+export const CANCEL_DENY_BUDGET_MS = 2000;
+/** warn 行文案(测试锁字面)。 */
+export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
+const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
+const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
+/** 失败 warn 上屏:借 footer notifications 通道。壳原文经 `appStateRef` 直写 store
+ *  (immediate 语义:立即顶到 current + 到点自清「仅当仍是本 warn 时」);本包把那两次
+ *  setState 拆成宿主口的两个动词,**时序纪律(2s 预算 / 10s 自清)留在库内**——
+ *  [paired-mechanisms-must-share-premise]:只给「显示」不给「清」,端各写各的清法必然漂。
+ *  无口(print/headless 没屏可上)⇒ 静默,与壳原文 `if (!store) return` 同语义。 */
+function surfaceCancelDenyWarn() {
+    try {
+        const s = surfaceForCurrentSession();
+        if (!s)
+            return;
+        s.showNotice({
+            key: CANCEL_DENY_WARN_KEY,
+            text: CANCEL_DENY_WARN_TEXT,
+            color: 'warning',
+            priority: 'immediate',
+            timeoutMs: CANCEL_DENY_WARN_TIMEOUT_MS,
+        });
+        const timer = setTimeout(() => {
+            try {
+                s.clearNoticeIfCurrent(CANCEL_DENY_WARN_KEY);
+            }
+            catch {
+                /* fail-soft */
+            }
+        }, CANCEL_DENY_WARN_TIMEOUT_MS);
+        unrefTimer(timer);
+    }
+    catch {
+        /* fail-soft:上屏失败绝不再伤害 abort 流 */
+    }
+}
+/**
+ * cancel-by-deny 的「良性 no_pending」判据。**结构化 `.code` 为主,`instanceof` 只作加强,绝不替代**:
+ *  - `.code` 是 client-core 自家 `HitlSafetyError` 的契约属性(hitlBridge.ts,REF-CC-036 起是闭集
+ *    联合 binding_mismatch|no_pending|wrong_gate|bad_plan_edit)—— 不是 SDK 错误的 `errorCode`;
+ *  - 只按 `instanceof` 判会在**跨 realm / 双实例**下假阴:打包后同一个包出现两份副本(本仓
+ *    `singleton-manifest.json` 把双实例当在册风险处理)、或宿主与包各持一份构造器时,同一个
+ *    语义错误 `instanceof` 为假 ⇒ 良性 no_pending 被当成「deny 丢失」弹一行吓人的 warn;
+ *  - 下游 `sema-cli` 的 `src/sema/hitlCancelDeny.test.ts` 用例 3 正是按 `code + name` 鸭子形造错,
+ *    那份契约就是「结构判据」本身。
+ * ⚠️ 判据不许松成「有 `.code` 就静默」—— 闭集里只有 `no_pending` 是良性,别的 code 照走 warn 臂。
+ */
+function isNoPendingError(e) {
+    if (e instanceof HitlSafetyError)
+        return e.code === 'no_pending';
+    if (typeof e !== 'object' || e === null || !('code' in e))
+        return false;
+    const code = e.code;
+    return typeof code === 'string' && code === 'no_pending';
+}
+/**
+ * 中断 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 function observeCancelByDeny(settle, taskId) {
+    let timer;
+    const budget = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`cancel-by-deny did not settle within ${CANCEL_DENY_BUDGET_MS}ms`)), CANCEL_DENY_BUDGET_MS);
+        unrefTimer(timer);
+    });
+    void Promise.race([settle, budget])
+        .then(() => {
+        hostLog('debug', `[hitl-cancel-deny] cancel-by-deny settled for run ${taskId} (session unlocked)`);
+    })
+        .catch((e) => {
+        if (isNoPendingError(e)) {
+            hostLog('debug', `[hitl-cancel-deny] cancel-by-deny no_pending for run ${taskId} (benign — already resolved)`);
+            return;
+        }
+        hostLog('error', `[hitl-cancel-deny] cancel-by-deny FAILED for run ${taskId}: ${String(e)}`);
+        surfaceCancelDenyWarn();
+    })
+        .finally(() => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    });
+    // 超时后原 promise 迟到 reject 不得变成 unhandledRejection。
+    void settle.catch(() => { });
+}

package/dist/hitl/parkResolver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * parkResolver — HITL gate 桥**外环**的 park 决断(REF-CC-032 / SPLIT-12 第三刀,2026-08-02)。
+ *
+ * 内环(`frameRouter.ts`)带出一个 `GatePark` 之后,这里回答唯一一个问题:**接着读流,还是
+ * fail-soft 收场**。三条出路:
+ *   · 决断成功 ⇒ `reattach`(驱动 attach `runs.events`,`lastEventId` 续传);
+ *   · 「这个 gate 早就被解决了」(durable re-attach 必然重放已决断的 park)⇒ 同样 `reattach`;
+ *   · 其余(overlay 缺席 / pending 蒸发 / decide 409/404 / turn 中断 / hop 预算耗尽)⇒ `failsoft`:
+ *     flush HOLD 的毒化帧 + 原样吐 suspended 终帧(durable 腿无终帧则合成一条可见的 failed)。
+ *
+ * 🔴 本文件不碰流、不 yield:events 以数组交回驱动。`resolvePark` 的**返回值**就是它的全部对外
+ *    效果(台账写入除外,且台账写入全经 `GateLedger` 的动词)—— 于是「禁掉某条真臂」这种变异
+ *    在驱动的消费点上必然显形,而不是被本文件自己吞掉。
+ */
+import type { AgentEvent } from '@sema-agent/sdk';
+import { type QuestionAnswer } from '../liveQuestionStore.js';
+import type { AskAnsweredOutput, GateLedger } from './gateLedger.js';
+import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
+/**
+ * REF-CC-033:`GateOutcome` 的 `failed` 分支闭集判别码。来源两处:①本文件自己的
+ * 「pending 行取不到」早退(`surfaceGateAndDecide` 里 `!pending` 那条);②`HitlBridge` 抛出的
+ * `HitlSafetyError.code`(hitlBridge.ts 契约:`binding_mismatch|no_pending|wrong_gate|bad_plan_edit`
+ * ——该属性今天仍是开集 `string`,TYPESHAPE-07/REF-CC-036 候后续车锁死;这里落地前用
+ * `isGateFailureCode` 按闭集白名单过滤,不认得的值一律降级成 `undefined`,退回文案兜底,不让
+ * 开集腐蚀这个新判别位)。消费点只认 `'no_pending'` 为「已解决」,其余码(binding_mismatch 等)
+ * 是真需要重新呈现给人的失败,不能走「继续读流」这条路。
+ */
+export type GateFailureCode = 'no_pending' | 'binding_mismatch' | 'wrong_gate' | 'bad_plan_edit';
+export type GateOutcome = {
+    kind: 'decided';
+    gatedCallId?: string | undefined;
+    answered?: AskAnsweredOutput | undefined;
+} | {
+    kind: 'aborted';
+    gatedCallId?: string | undefined;
+} | {
+    kind: 'failed';
+    gatedCallId?: string | undefined;
+    reason: string;
+    code?: GateFailureCode | undefined;
+};
+/**
+ * decide 的 `failed` 原因是不是「这个 gate 早就被解决了」(#110 缺陷② c 的判据)。
+ *
+ * REF-CC-033:此前判据**只**锚在文案词(`no pending checkpoint` / `resolved` / `already` 三者
+ * 任一在场)——server 原文改一个字,整条命中当场失效(FIX-13 / 域词表-01)。现在消费点(见下方
+ * `isAlreadyResolvedFailure`)优先判 `GateOutcome.code`(闭集判别位,见 `GateFailureCode`);
+ * 这个函数降级为**文案兜底臂**,只在 outcome 没带 code 的时候才被调用(典型:`FsApprovalOutcome`
+ * 来自 `toolApprovalWire.ts`,那份类型今天没有 code 字段——C-bridge 卡的文件域,本卡不改)。
+ * 🔴 方向没变:这条判**错**的后果不对称 —— 误判成「已解决」最多让流多读一轮(hop 预算兜底),
+ * 误判成「真失败」会把一个已经 completed 的 run 谎报成失败并烧掉整条会话转录。所以宁可宽。
+ */
+/** #114/[C68] 单源化提升:desktop 照抄件(durable 双实现审计 P0-1 修)到货换包导入删抄件。 */
+export declare function isAlreadyResolvedGateReason(reason: unknown): boolean;
+/** 把 wire 答案({answers:[{header,selected,note?}]})折回 CC 卡片的 Record<question,string> 形状
+ *  (multiSelect 与对话框同款 ", " lossy join;note → annotations.notes)。 */
+export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
+/** 外环决断的两种出路(见文件头注)。 */
+export type ParkResolution = {
+    kind: 'reattach';
+} | {
+    kind: 'failsoft';
+    events: readonly AgentEvent[];
+};
+export interface ParkResolveCtx {
+    deps: AskGateWireDeps;
+    led: GateLedger;
+    /** sync leg 捕获的真 run handle(内环 `TaskIdRef` 的当前值)。 */
+    taskId: string;
+    /** 本 turn 内这是第几次 park(hop 预算的唯一计量;由驱动累加,本函数只读)。 */
+    hops: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function resolvePark(park: GatePark, ctx: ParkResolveCtx): Promise<ParkResolution>;