@sema-agent/client-core 0.93.1 → 0.95.0

package/dist/hitl/decisionConflict.js

@@ -0,0 +1,43 @@
+import { APPROVAL_BINDING_MISMATCH, CHECKPOINT_UNSUPPORTED_VERSION, RESUME_OUTCOME_INVALID } from '../engineErrorCodes.js';
+import { readRefusalField } from '../wireFailureShape.js';
+const BINDING_SEAT_FIELDS = new Set(['boundCallId', 'boundInputHash']);
+const ANSWER_FIELD = 'answer';
+const BINDING_MISMATCH_ERROR_NAME = 'ApprovalBindingMismatchError';
+export function decisionConflictOf(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    let code;
+    let name;
+    try {
+        code = err.errorCode;
+    }
+    catch {
+        code = undefined;
+    }
+    try {
+        name = err.name;
+    }
+    catch {
+        name = undefined;
+    }
+    if (code === CHECKPOINT_UNSUPPORTED_VERSION)
+        return 'format_version';
+    const bindingFamily = code === APPROVAL_BINDING_MISMATCH || (code === undefined && name === BINDING_MISMATCH_ERROR_NAME);
+    if (!bindingFamily && code !== RESUME_OUTCOME_INVALID)
+        return undefined;
+    let field;
+    try {
+        field = readRefusalField(err);
+    }
+    catch {
+        field = undefined;
+    }
+    if (code === RESUME_OUTCOME_INVALID)
+        return field === ANSWER_FIELD ? 'answer_invalid' : undefined;
+    if (field === ANSWER_FIELD)
+        return 'answer_invalid';
+    if (field === undefined)
+        return 'row_integrity';
+    return BINDING_SEAT_FIELDS.has(field) ? 'binding_mismatch' : undefined;
+}
+export const DECISION_ANSWER_INVALID_CONTENT = 'The engine rejected the answer itself because it does not fit the question that was asked · Nothing was decided and the question is still waiting · Correct the answer and send it again';

package/dist/hitl/decisionRefusal.d.ts

@@ -0,0 +1,23 @@
+import { type DecisionRefusalConflict } from './decisionConflict.js';
+export type DecisionRefusalStanding = 'settled-elsewhere' | 'ambiguous' | 'refused-pending';
+export type { DecisionRefusalConflict } from './decisionConflict.js';
+export declare function decisionRefusalSaysAskGone(err: unknown): boolean;
+export interface DecisionRefusalClassified {
+    readonly standing: DecisionRefusalStanding;
+    readonly status: number;
+    readonly errorCode?: string;
+    readonly transient?: true;
+    readonly conflict?: DecisionRefusalConflict;
+}
+export declare function classifyDecisionRefusal(err: unknown): DecisionRefusalClassified | undefined;
+export type LiveAskPendingReading = 'pending' | 'not_pending' | 'unknown';
+export declare function liveAskPendingReading(envelope: unknown, approvalId: string): LiveAskPendingReading;
+export declare function decisionRefusalClosesOut(refusal: DecisionRefusalClassified | undefined, pending: LiveAskPendingReading): boolean;
+export type UndeliverableDecisionEnd = 'run-stopped' | 'run-unconfirmed' | 'turn-stopped';
+export interface UndeliverableDecisionFacts {
+    readonly status: number;
+    readonly errorCode?: string;
+    readonly end: UndeliverableDecisionEnd;
+    readonly runId?: string;
+}
+export declare function undeliverableDecisionContent(facts: UndeliverableDecisionFacts): string;

package/dist/hitl/decisionRefusal.js

@@ -0,0 +1,88 @@
+import { refusalSaysStillPending } from '../engineErrorCodes.js';
+import { notPendingCauseSaysEnded } from './approvalEndingCause.js';
+import { decisionConflictOf } from './decisionConflict.js';
+import { readLivePendingRows } from './livePendingAsk.js';
+import { readToolApprovalRespondRefusal } from './toolApprovalWire.js';
+const ASK_DECIDED_CODE = 'conflict.ask_decided';
+const TRANSIENT_STATUSES = new Set([408, 425, 429, 502, 503, 504]);
+const DISPLAYABLE_CODE = /^[A-Za-z0-9._:-]{1,64}$/;
+export function decisionRefusalSaysAskGone(err) {
+    try {
+        if (typeof err === 'object' && err !== null && 'code' in err) {
+            const code = err.code;
+            if (code === 'no_pending')
+                return true;
+        }
+        const c = classifyDecisionRefusal(err);
+        if (c?.standing !== 'settled-elsewhere')
+            return false;
+        return c.status !== 404 || (typeof err === 'object' && err !== null && notPendingCauseSaysEnded(err));
+    }
+    catch {
+        return false;
+    }
+}
+export function classifyDecisionRefusal(err) {
+    const r = readToolApprovalRespondRefusal(err);
+    const status = r?.status;
+    if (status === undefined || !Number.isInteger(status) || status < 400 || status > 599)
+        return undefined;
+    const code = r?.errorCode;
+    const errorCode = code !== undefined && DISPLAYABLE_CODE.test(code) ? code : undefined;
+    const standing = status === 404 || status === 410 || (status === 409 && code === ASK_DECIDED_CODE)
+        ? 'settled-elsewhere'
+        : status >= 500 && status !== 501
+            ? 'ambiguous'
+            : 'refused-pending';
+    const transient = TRANSIENT_STATUSES.has(status) || (typeof err === 'object' && err !== null && refusalSaysStillPending(err));
+    const conflict = status === 409 ? decisionConflictOf(err) : undefined;
+    return Object.freeze({
+        standing,
+        status,
+        ...(errorCode !== undefined ? { errorCode } : {}),
+        ...(transient ? { transient: true } : {}),
+        ...(conflict !== undefined ? { conflict } : {}),
+    });
+}
+export function liveAskPendingReading(envelope, approvalId) {
+    if (typeof approvalId !== 'string' || approvalId === '')
+        return 'unknown';
+    try {
+        const reading = readLivePendingRows(envelope);
+        if (reading.kind !== 'present')
+            return 'unknown';
+        if (reading.rows.some((row) => row.approvalId === approvalId))
+            return 'pending';
+        return reading.dropped === 0 ? 'not_pending' : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function decisionRefusalClosesOut(refusal, pending) {
+    if (pending !== 'pending' || typeof refusal !== 'object' || refusal === null)
+        return false;
+    try {
+        const standing = refusal.standing;
+        if (refusal.transient === true)
+            return false;
+        return standing === 'ambiguous' || standing === 'refused-pending';
+    }
+    catch {
+        return false;
+    }
+}
+export function undeliverableDecisionContent(facts) {
+    const code = typeof facts.errorCode === 'string' && DISPLAYABLE_CODE.test(facts.errorCode) ? ` ${facts.errorCode}` : '';
+    const head = `The engine refused the approval decision this client sent (HTTP ${String(facts.status)}${code}), so the call it asked about could not be answered from here and did not run`;
+    const runId = typeof facts.runId === 'string' && DISPLAYABLE_CODE.test(facts.runId) ? ` ${facts.runId}` : '';
+    switch (facts.end) {
+        case 'run-stopped':
+            return `${head}; the run was stopped instead of being left waiting for the approval window to close. Update the client, or run the task in an interactive session and answer the approval there.`;
+        case 'run-unconfirmed':
+            return `${head}; this client stopped waiting, but the engine did not confirm that it stopped the run${runId}, so that approval may stay open until its window closes. Update the client, or run the task in an interactive session and answer the approval there.`;
+        case 'turn-stopped':
+        default:
+            return `${head}; this turn was stopped instead of being left waiting. Update the client, or switch to a permission mode that shows you the approval and try again.`;
+    }
+}

package/dist/hitl/frameRouter.d.ts

@@ -2,9 +2,19 @@ import type { AgentEvent } from '@sema-agent/sdk';
 import type { DecideOperationObserver, HitlClientLike } from './hitlBridge.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
+import type { NoAllowCause } from './noAllowCause.js';
 import { type ReplayedApprovalDisposition } from './replayedApproval.js';
 export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
 export declare const HITL_POLICY_DENY_MESSAGE: string;
+export type PolicyDenyLane = 'no_approval_ui' | 'dont_ask';
+export interface PolicyDenyReasonFacts {
+    readonly lane: PolicyDenyLane;
+    readonly toolName: string;
+    readonly cause?: NoAllowCause;
+    readonly allowRuleFlag?: string;
+    readonly budgetSetting?: string;
+}
+export declare function policyDenyReason(facts: PolicyDenyReasonFacts): string;
 export declare const HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
 export declare const ENGINE_ABORT_TOOL_RESULT = "Operation aborted";
 export declare function toolEndOutputText(output: unknown): string | undefined;

package/dist/hitl/frameRouter.js

@@ -1,11 +1,15 @@
 import { hostLog } from '../host.js';
+import { invokeHostCallbackIsolated } from '../hostCallbackGuard.js';
 import { isToolApprovalGate, toolNameIsFsWrite, toolNameIsShellExec, isToolApprovalFrame, isFromSubagent, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
 import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 import { GATE_PARKED_ERROR_CODE } from '../engineErrorCodes.js';
 import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateToolName } from '../runTerminal.js';
 import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
+import { liveCardAnsweredHow, liveCardHoldOf, supersedeLiveCard } from './approvalHolds.js';
+import { approvalCompleteParked } from './approvalCompleteParked.js';
+import { liveFrameCallKey } from './gateIdentity.js';
 import { SEMA_DENIAL_KIND_KEY, hasLedgerPositionKey } from './gateLedger.js';
-import { replayedApprovalDisposition } from './replayedApproval.js';
+import { replayedApprovalDisposition, settledApprovalDisposition } from './replayedApproval.js';
 import { settleWithinDeadline } from '../abortableSleep.js';
 import { ccToolDenialKindForSettledBy } from '../gateVocabulary.js';
 import { REJECT_MESSAGE } from '../adapt/wireShapes.js';
@@ -14,6 +18,38 @@ export const HITL_REJECT_MESSAGE = REJECT_MESSAGE;
 export const HITL_POLICY_DENY_MESSAGE = 'Permission for this tool use was denied: it requires interactive approval, and permission prompts are ' +
     'not available in this session. The action was NOT performed. Do not claim it succeeded, and do not retry ' +
     'it in this session \u2014 report the limitation to the user, or suggest an alternative.';
+const SENTENCE_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.:@-]{0,199}$/;
+export function policyDenyReason(facts) {
+    const one = typeof facts.toolName === 'string' && SENTENCE_TOOL_NAME.test(facts.toolName) ? `this one "${facts.toolName}" call` : 'this one call';
+    const flag = typeof facts.allowRuleFlag === 'string' && SENTENCE_TOOL_NAME.test(facts.allowRuleFlag.replace(/^--?/, '')) ? ` (or ${facts.allowRuleFlag})` : '';
+    const budgetKnob = typeof facts.budgetSetting === 'string' && SENTENCE_TOOL_NAME.test(facts.budgetSetting) ? facts.budgetSetting : undefined;
+    const cause = facts.cause === 'no_allow_rule' || facts.cause === 'ask_rule' || facts.cause === 'budget' ? facts.cause : 'other';
+    if (facts.lane === 'dont_ask') {
+        const mode = 'denied by the dontAsk permission mode';
+        switch (cause) {
+            case 'no_allow_rule':
+                return `${mode}: ${one} needed approval, no permission rule allowed it, and this mode refuses anything that would ask — calls that need no approval still run; an allow rule in settings${flag} can approve calls like this ahead of time`;
+            case 'ask_rule':
+                return `${mode}: an ask rule matched ${one}, and this mode refuses anything that would ask (an ask rule outranks allow rules) — narrow or remove that ask rule, or use another permission mode to answer it`;
+            case 'budget':
+                return `${mode}: ${one} needed approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls${budgetKnob !== undefined ? ` — raise ${budgetKnob} before launch to change the cap` : ''}`;
+            default:
+                return `${mode}: ${one} needed a person's approval that saved permission rules cannot approve here (the engine or your deployment requires a person for it, or it could not be checked against your rules), and this mode refuses anything that would ask — use another permission mode to answer it`;
+        }
+    }
+    const lane = 'no approval UI on this lane';
+    const tail = 'nobody can be asked here, so only this call was refused — calls that need no approval still run';
+    switch (cause) {
+        case 'no_allow_rule':
+            return `${lane}: ${one} needed a person's approval, no permission rule answered it, and ${tail}; a matching allow rule in settings${flag} can approve calls like this ahead of time`;
+        case 'ask_rule':
+            return `${lane}: an ask rule matched ${one}, so it needed a person's answer, and ${tail}; an ask rule outranks allow rules, so narrow or remove that ask rule, or run the task interactively to answer it`;
+        case 'budget':
+            return `${lane}: ${one} needed a person's approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls; ${tail}${budgetKnob !== undefined ? `; raise ${budgetKnob} before launch to change the cap` : ''}`;
+        default:
+            return `${lane}: ${one} needed a person's approval, and saved permission rules cannot approve it here (the engine or your deployment requires a person for it, or it could not be checked against your rules); ${tail}; run the task interactively to answer it`;
+    }
+}
 function denyOutputForRender(attribution) {
     if (attribution?.settledBy !== 'policy')
         return HITL_REJECT_MESSAGE;
@@ -234,32 +270,32 @@ const TOOL_END_ARMS = [
 }
 async function routeToolApprovalFrame(ev, ctx) {
     const { led, deps } = ctx;
-    if (ev.type === 'tool_approval_complete')
+    if (ev.type === 'tool_approval_complete') {
+        const id = ev.approvalId;
+        if (typeof id === 'string' && id !== '' && supersedeLiveCard(liveFrameCallKey(id), approvalCompleteParked(ev))) {
+            hostLog('debug', `liveHitlAskWire: tool_approval_complete for ${id} arrived while its card was waiting — card withdrawn (nothing will be sent from it)`);
+        }
+        if (typeof id === 'string' && id !== '')
+            led.noteApprovalSettled(id, 'closed_by_engine');
         return { kind: 'skip' };
+    }
     if (!deps.respondToolApproval) {
         hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} but no respond wire — engine self-settles (TTL deny)`);
         return { kind: 'skip' };
     }
-    if (hasLedgerPositionKey(ev) && !led.preambleApprovals().has(ev.approvalId)) {
-        const disposition = await judgeLedgerApprovalFrame(ev, ctx);
+    const settledHere = settledApprovalDisposition(ev, led.settledApprovals());
+    if (settledHere !== undefined || (hasLedgerPositionKey(ev) && !led.preambleApprovals().has(ev.approvalId))) {
+        const disposition = settledHere ?? (await judgeLedgerApprovalFrame(ev, ctx));
         if (disposition.kind !== 'live') {
-            hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} read back from the run event log is ${disposition.kind}` +
-                `${disposition.kind === 'unknown' ? ` (${disposition.why})` : disposition.cause !== undefined ? ` (${disposition.cause})` : ''}` +
-                ' — not raised as a question, no decision sent');
+            hostLog('debug', disposition.kind === 'decided' && disposition.settled !== undefined
+                ? `liveHitlAskWire: tool_approval frame ${ev.approvalId} repeats a question already settled on this bridge (${disposition.settled}) — not raised again, no decision sent`
+                : `liveHitlAskWire: tool_approval frame ${ev.approvalId} read back from the run event log is ${disposition.kind}` +
+                    `${disposition.kind === 'unknown' ? ` (${disposition.why})` : disposition.cause !== undefined ? ` (${disposition.cause})` : ''}` +
+                    ' — not raised as a question, no decision sent');
             if (disposition.kind === 'unknown' && ctx.signal?.aborted !== true)
                 surfaceReplayedApprovalListUnreadable();
             if (deps.onReplayedApproval !== undefined) {
-                try {
-                    const out = deps.onReplayedApproval(ev, disposition);
-                    if (out && typeof out.then === 'function') {
-                        void Promise.resolve(out).catch((e) => {
-                            hostLog('debug', `liveHitlAskWire: onReplayedApproval rejected: ${String(e).slice(0, 160)}`);
-                        });
-                    }
-                }
-                catch (e) {
-                    hostLog('debug', `liveHitlAskWire: onReplayedApproval threw: ${String(e).slice(0, 160)}`);
-                }
+                invokeHostCallbackIsolated('liveHitlAskWire: onReplayedApproval', () => deps.onReplayedApproval?.(ev, disposition));
             }
             return { kind: 'skip' };
         }
@@ -269,20 +305,24 @@ async function routeToolApprovalFrame(ev, ctx) {
     const frameCallId = !fromSubagent && typeof ev.toolCallId === 'string' && ev.toolCallId !== '' ? ev.toolCallId : undefined;
     const gatedCallId = fromSubagent ? undefined : frameCallId ?? led.lastPendingFsCall();
     const argsCallId = frameCallId === undefined ? gatedCallId : typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName) ? frameCallId : undefined;
-    const outcome = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane);
+    const runTaskId = ctx.taskId.current;
+    const approvalIdAtLaunch = ev.approvalId;
+    const launched = surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane, typeof runTaskId === 'string' && runTaskId !== '' ? { taskId: runTaskId } : undefined);
+    const hold = liveCardHoldOf(liveFrameCallKey(ev.approvalId));
+    const handled = launched.then((outcome) => settleLiveCardOutcome(ev, approvalIdAtLaunch, outcome, ctx, fromSubagent, gatedCallId), (e) => {
+        hostLog('debug', `liveHitlAskWire: tool_approval card for ${ev.approvalId} failed: ${String(e).slice(0, 160)}`);
+    });
+    led.trackLiveCard(() => hold?.phase ?? 'card', handled);
+    return { kind: 'skip' };
+}
+function settleLiveCardOutcome(ev, approvalId, outcome, ctx, fromSubagent, gatedCallId) {
+    const { led, deps } = ctx;
     const { decision } = outcome;
+    const settledHow = liveCardAnsweredHow(outcome);
+    if (settledHow !== undefined)
+        led.noteApprovalSettled(approvalId, settledHow);
     if (deps.onToolApprovalOutcome !== undefined) {
-        try {
-            const out = deps.onToolApprovalOutcome(ev, outcome);
-            if (out && typeof out.then === 'function') {
-                void Promise.resolve(out).catch((e) => {
-                    hostLog('debug', `liveHitlAskWire: onToolApprovalOutcome rejected: ${String(e).slice(0, 160)}`);
-                });
-            }
-        }
-        catch (e) {
-            hostLog('debug', `liveHitlAskWire: onToolApprovalOutcome threw: ${String(e).slice(0, 160)}`);
-        }
+        invokeHostCallbackIsolated('liveHitlAskWire: onToolApprovalOutcome', () => deps.onToolApprovalOutcome?.(ev, outcome));
     }
     if (decision === 'deny' && !fromSubagent) {
         const attribution = {
@@ -294,7 +334,6 @@ async function routeToolApprovalFrame(ev, ctx) {
         else
             led.armDenyStamp(attribution);
     }
-    return { kind: 'skip' };
 }
 const REPLAYED_APPROVAL_LIST_DEADLINE_MS = 3000;
 async function judgeLedgerApprovalFrame(ev, ctx) {
@@ -318,7 +357,7 @@ async function judgeLedgerApprovalFrame(ev, ctx) {
             .finally(release);
     });
     const approvals = got.kind === 'value' ? { read: 'ok', body: got.value } : { read: 'failed' };
-    return replayedApprovalDisposition(ev, { preamble: ctx.led.preambleApprovals(), approvals });
+    return replayedApprovalDisposition(ev, { preamble: ctx.led.preambleApprovals(), approvals, settled: ctx.led.settledApprovals() });
 }
 function routeToolStart(ev, callId, led) {
     led.noteStart(callId, ev);

package/dist/hitl/gateLedger.d.ts

@@ -16,6 +16,9 @@ export interface AskAnsweredOutput {
 export declare function durableSeqOf(ev: object): string | undefined;
 export declare function hasLedgerPositionKey(ev: object): boolean;
 export declare const PREAMBLE_APPROVALS_MAX_ENTRIES = 4096;
+export declare const APPROVAL_SETTLED_HOWS: readonly ["answered", "interrupted", "closed_by_engine"];
+export type ApprovalSettledHow = (typeof APPROVAL_SETTLED_HOWS)[number];
+export declare const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 export interface GateLedger {
     noteSeq(ev: AgentEvent): void;
     lastSeq(): string | undefined;
@@ -23,6 +26,11 @@ export interface GateLedger {
     notePreambleApproval(approvalId: string): void;
     preambleApprovals(): ReadonlySet<string>;
     beginStreamSegment(): void;
+    noteApprovalSettled(approvalId: string, how: ApprovalSettledHow): void;
+    settledApprovals(): ReadonlyMap<string, ApprovalSettledHow>;
+    trackLiveCard(phaseOf: () => 'card' | 'respond', handled: Promise<void>): void;
+    answeringLiveCards(): Promise<void>[];
+    liveCardsSettled(): Promise<void>;
     markStarted(callId: string): boolean;
     noteGatedStart(callId: string, ev: AgentEvent): void;
     gatedStartArgs(): ReadonlyMap<string, unknown>;

package/dist/hitl/gateLedger.js

@@ -13,6 +13,8 @@ export function hasLedgerPositionKey(ev) {
     return (id !== undefined && id !== null) || (seq !== undefined && seq !== null);
 }
 export const PREAMBLE_APPROVALS_MAX_ENTRIES = 4096;
+export const APPROVAL_SETTLED_HOWS = Object.freeze(['answered', 'interrupted', 'closed_by_engine']);
+export const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 export const START_ARGS_MAX_ENTRIES = 256;
 function normalizeDenyAttribution(a) {
     if (a === undefined)
@@ -88,6 +90,8 @@ export function createGateLedger() {
     let denyStampAttribution;
     let seq;
     const preambleApprovalIds = new Set();
+    const settledApprovalHows = new Map();
+    const liveCards = new Set();
     return {
         noteSeq(ev) {
             const s = durableSeqOf(ev);
@@ -120,6 +124,40 @@ export function createGateLedger() {
         beginStreamSegment() {
             preambleApprovalIds.clear();
         },
+        noteApprovalSettled(approvalId, how) {
+            if (typeof approvalId !== 'string' || approvalId === '')
+                return;
+            if (!APPROVAL_SETTLED_HOWS.includes(how))
+                return;
+            if (settledApprovalHows.has(approvalId))
+                return;
+            settledApprovalHows.set(approvalId, how);
+            while (settledApprovalHows.size > SETTLED_APPROVALS_MAX_ENTRIES) {
+                const oldest = settledApprovalHows.keys().next();
+                if (oldest.done === true)
+                    break;
+                settledApprovalHows.delete(oldest.value);
+            }
+        },
+        settledApprovals() {
+            return settledApprovalHows;
+        },
+        trackLiveCard(phaseOf, handled) {
+            const entry = { phaseOf, handled };
+            liveCards.add(entry);
+            void handled.then(() => { liveCards.delete(entry); }, () => { liveCards.delete(entry); });
+        },
+        answeringLiveCards() {
+            const out = [];
+            for (const e of liveCards)
+                if (e.phaseOf() === 'respond')
+                    out.push(e.handled);
+            return out;
+        },
+        async liveCardsSettled() {
+            while (liveCards.size > 0)
+                await Promise.allSettled([...liveCards].map((e) => e.handled));
+        },
         markStarted(callId) {
             if (startedCalls.has(callId))
                 return false;

package/dist/hitl/hitlBridge.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+import type { AgentEvent, ApprovalDecidedBy, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
 import type { PermissionResult } from '@sema-agent/agent-types';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
@@ -46,7 +46,8 @@ export interface PlanReviewOutcome {
 export declare const PLAN_REVIEW_MODE_AFTER_WORDS: readonly ["default", "acceptEdits"];
 export type PlanReviewModeAfter = (typeof PLAN_REVIEW_MODE_AFTER_WORDS)[number];
 export declare function isPlanReviewModeAfter(v: string | undefined): v is PlanReviewModeAfter;
-export type HitlSafetyCode = 'binding_mismatch' | 'no_pending' | 'wrong_gate' | 'bad_plan_edit' | 'bad_plan_mode' | 'empty_answer';
+export declare const GATE_FAILURE_CODES: readonly ["no_pending", "binding_mismatch", "wrong_gate", "bad_plan_edit", "bad_plan_mode", "empty_answer"];
+export type HitlSafetyCode = (typeof GATE_FAILURE_CODES)[number];
 export type HitlFailureStage = 'fetch' | 'input' | 'card' | 'decide' | 'orchestration';
 export declare const NO_APPROVAL_CARD_PORT_REASON = "no approval card port installed (print/non-REPL mode, or host forgot installApprovalCardPort)";
 export declare const APPROVAL_CARD_PORT_KEY_MISMATCH_REASON = "no approval card port installed for the default session key, but a non-default sessionKey has one \u2014 likely a keyed-install/default-read mismatch (installApprovalCardPortFor vs the zero-arg default-key read), not a missing install";
@@ -56,15 +57,25 @@ export interface HitlDecideDenyOutcome {
     decision: 'deny';
     reason?: string | undefined;
     settledBy?: 'policy' | undefined;
-    decidedBy?: 'policy' | undefined;
+    decidedBy?: Extract<ApprovalDecidedBy, 'policy'> | undefined;
 }
 export declare class HitlSafetyError extends Error {
     readonly code: HitlSafetyCode;
     constructor(message: string, code: HitlSafetyCode);
 }
+export declare function hitlSafetyCodeOf(e: unknown): HitlSafetyCode | undefined;
 export type GateCurrentPending = Readonly<NonNullable<ApprovalStaleError['currentPending']>>;
 export declare function readDecideCurrentPending(e: unknown): GateCurrentPending | undefined;
 export declare function readWireErrorCode(e: unknown): string | undefined;
+export type WireErrorCodeReading = {
+    readonly state: 'code';
+    readonly code: string;
+} | {
+    readonly state: 'absent';
+} | {
+    readonly state: 'unreadable';
+};
+export declare function readWireErrorCodeReading(e: unknown): WireErrorCodeReading;
 export declare function __setDecideTimeoutRetryBudgetForTests(ms?: number): void;
 export declare class DecideTransportRetryExhaustedError extends Error {
     readonly attempts: number;