@sema-agent/client-core 0.99.0 → 0.101.0

package/dist/headlessPermissionModeWire.js

@@ -1,7 +1,7 @@
 import { permissionModeField } from './permissionWireCaps.js';
 import { permissionModeAdmitted } from './permissionModesCapability.js';
 import { hostEnv } from './hostEnv.js';
-import { lastFlagValue } from './argvFlagValue.js';
+import { flagString, flagTrue } from './flagInput.js';
 import { PERMISSION_MODE_WORDS } from './taskRequestWords.js';
 import { readOwnDataValue } from './ownKey.js';
 export const HEADLESS_PERMISSION_MODE_ENV = 'SEMA_HEADLESS_PERMISSION_MODE';
@@ -12,33 +12,29 @@ export function normalizeShellPermissionModeForWire(mode) {
         return undefined;
     return SHELL_INTERNAL_MODE_TO_WIRE.get(mode) ?? mode;
 }
-export function permissionModeFromArgv(argv) {
-    const flag = lastFlagValue(argv, '--permission-mode', 'latch-previous');
-    if (flag.present && flag.raw !== undefined)
-        return flag.raw;
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--')
-            break;
-        if (a === '--dangerously-skip-permissions')
-            return 'bypassPermissions';
-    }
+function permissionModeOfFlags(flags) {
+    const flag = flagString(flags, 'flag');
+    if (flag !== undefined)
+        return flag;
+    if (flagTrue(flags, 'dangerouslySkipPermissions'))
+        return 'bypassPermissions';
     return undefined;
 }
 let warnedInvalidEnv = false;
-export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionModes) {
-    const flagMode = permissionModeFromArgv(argv);
+export function resolveHeadlessPermissionMode(flags, env = hostEnv(), permissionModes) {
+    const flagMode = permissionModeOfFlags(flags);
     if (flagMode !== undefined) {
         const snap = flagMode === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
         const normalized = normalizeShellPermissionModeForWire(flagMode);
         const projected = permissionModeField(normalized, { stampDefault: true, permissionModes: snap });
         return { fields: projected.permissionMode !== undefined ? projected : permissionModeField('default', { stampDefault: true }), source: 'flag' };
     }
-    const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
-    if (raw === undefined || raw === '') {
+    const knob = readHeadlessPermissionModeKnob(env);
+    if (knob.kind === 'absent') {
         return { fields: permissionModeField('default', { stampDefault: true }), source: 'default' };
     }
-    if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw)) {
+    if (knob.kind === 'word') {
+        const raw = knob.word;
         const snap = raw === 'dontAsk' ? dontAskSnapshot(permissionModes) : undefined;
         const resolution = {
             fields: permissionModeField(raw, { stampDefault: true, permissionModes: snap }),
@@ -46,7 +42,7 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionM
         };
         if (raw === 'dontAsk' && resolution.fields.permissionMode !== 'dontAsk' && !warnedInvalidEnv) {
             warnedInvalidEnv = true;
-            resolution.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="dontAsk" is only sent once this client knows the engine accepts that mode, and ${dontAskWithheldClause(permissionModes)} — this run uses "default"`;
+            resolution.warning = headlessDontAskDowngradeWarning(permissionModes);
         }
         return resolution;
     }
@@ -56,10 +52,25 @@ export function resolveHeadlessPermissionMode(argv, env = hostEnv(), permissionM
     };
     if (!warnedInvalidEnv) {
         warnedInvalidEnv = true;
-        resolution.warning = `sema: ${HEADLESS_PERMISSION_MODE_ENV}="${raw}" is not a recognized permission mode (expected one of: ${HEADLESS_PERMISSION_WIRE_MODES.join(', ')}) — ignoring it, this run keeps the default permission behavior`;
+        resolution.warning = knob.warning;
     }
     return resolution;
 }
+export function readHeadlessPermissionModeKnob(env = hostEnv()) {
+    const raw = env[HEADLESS_PERMISSION_MODE_ENV]?.trim();
+    if (raw === undefined || raw === '')
+        return Object.freeze({ kind: 'absent' });
+    if (HEADLESS_PERMISSION_WIRE_MODES.includes(raw))
+        return Object.freeze({ kind: 'word', word: raw });
+    return Object.freeze({
+        kind: 'invalid',
+        raw,
+        warning: `sema: ${HEADLESS_PERMISSION_MODE_ENV}="${raw}" is not a recognized permission mode (expected one of: ${HEADLESS_PERMISSION_WIRE_MODES.join(', ')}) — ignoring it, this run keeps the default permission behavior`,
+    });
+}
+export function headlessDontAskDowngradeWarning(permissionModes) {
+    return `sema: ${HEADLESS_PERMISSION_MODE_ENV}="dontAsk" is only sent once this client knows the engine accepts that mode, and ${dontAskWithheldClause(permissionModes)} — this run uses "default"`;
+}
 function dontAskSnapshot(reading) {
     return permissionModeAdmitted(reading, 'dontAsk') ? { kind: 'present', modes: Object.freeze(['dontAsk']) } : undefined;
 }

package/dist/hitl/allowRuleShadow.js

@@ -1,5 +1,7 @@
+import { appendOwnElement } from '../ownKey.js';
+import { slotPresenceOf } from '../wireFailureShape.js';
 import { CORE_ALLOW_RULE_MEMBERS } from '../generated/engineFactTables.js';
-import { quoteUntrustedForSentence } from '../displayUntrusted.js';
+import { displayUntrusted, quoteUntrustedForSentence } from '../displayUntrusted.js';
 import { msg, renderMessage } from '../i18n/translate.js';
 const KNOWN_MEMBERS = new Set(CORE_ALLOW_RULE_MEMBERS);
 function freezeMember(m) {
@@ -25,7 +27,7 @@ function readMemberRecord(r) {
             let ok = true;
             for (let i = 0; i < length; i++) {
                 const d = Object.getOwnPropertyDescriptor(rawEntries, i);
-                if (d === undefined || !('value' in d)) {
+                if (d === undefined || !Object.hasOwn(d, 'value')) {
                     ok = false;
                     break;
                 }
@@ -34,7 +36,7 @@ function readMemberRecord(r) {
                     ok = false;
                     break;
                 }
-                out.push(e);
+                appendOwnElement(out, e);
             }
             if (ok && rawEntries.length === length)
                 entries = Object.freeze(out);
@@ -92,7 +94,7 @@ export function retiredAllowRuleShadowKeyPresent(carrier, leg) {
         const host = leg === 'row' ? keyValue(carrier, 'riskDescriptor') : carrier;
         if (typeof host !== 'object' || host === null)
             return false;
-        return RETIRED_SHADOW_KEY[leg] in host;
+        return slotPresenceOf(host, RETIRED_SHADOW_KEY[leg]) !== 'absent';
     }
     catch {
         return true;
@@ -100,7 +102,7 @@ export function retiredAllowRuleShadowKeyPresent(carrier, leg) {
 }
 function readMemberAt(arr, i) {
     const d = Object.getOwnPropertyDescriptor(arr, i);
-    return d !== undefined && 'value' in d ? readMemberRecord(d.value) : freezeMember({ known: false, malformed: true });
+    return d !== undefined && Object.hasOwn(d, 'value') ? readMemberRecord(d.value) : freezeMember({ known: false, malformed: true });
 }
 export function readAllowRuleShadowFromWire(carrier, leg) {
     try {
@@ -133,7 +135,7 @@ function readStampedValue(raw) {
     for (let i = 0; i < length; i++) {
         const r = readMemberAt(members, i);
         const d = Object.getOwnPropertyDescriptor(members, i);
-        const was = d !== undefined && 'value' in d && typeof d.value === 'object' && d.value !== null && d.value.malformed === true;
+        const was = d !== undefined && Object.hasOwn(d, 'value') && typeof d.value === 'object' && d.value !== null && d.value.malformed === true;
         out.push(was && r.malformed !== true ? freezeMember({ ...r, malformed: true }) : r);
     }
     if (members.length !== length)
@@ -207,7 +209,7 @@ export function allowRuleShadowSentence(card, lang) {
         const single = singlePersistedEntry(shadow);
         if (single !== undefined)
             return renderMessage(msg('approval.card.shadow.single', { entry: single }), lang);
-        return renderMessage(msg('approval.card.shadow.several', { members: shadow.members.map((m) => memberPhrase(m, lang)).join(' · ') }), lang);
+        return renderMessage(msg('approval.card.shadow.several', { members: displayUntrusted(shadow.members.map((m) => memberPhrase(m, lang)).join(' · ')) }), lang);
     }
     catch {
         return renderMessage(msg('approval.card.shadow.unreadable'), lang);

package/dist/hitl/approvalCardReading.d.ts

@@ -1,3 +1,4 @@
+import { CORE_TOOL_APPROVAL_CARDS } from '../generated/engineFactTables.js';
 import type { ApprovalCardRequest } from './toolApprovalWire.js';
 export declare function readRequiresRealApproval(carrier: object | null | undefined): boolean;
 export interface ApprovalWindowKeys {
@@ -13,3 +14,5 @@ export interface ApprovalWindowReadOpts {
 }
 export declare function approvalWindowKeysOf(carrier: object | null | undefined, opts?: ApprovalWindowReadOpts | null): Readonly<ApprovalWindowKeys>;
 export declare function probeCauseRowsOf(card: Pick<ApprovalCardRequest, 'probeCause'> | null | undefined): readonly string[] | undefined;
+export type ApprovalCardWord = (typeof CORE_TOOL_APPROVAL_CARDS)[number];
+export declare function readApprovalCardWord(carrier: unknown): ApprovalCardWord | undefined;

package/dist/hitl/approvalCardReading.js

@@ -1,3 +1,4 @@
+import { CORE_TOOL_APPROVAL_CARDS } from '../generated/engineFactTables.js';
 import { displayUntrusted } from '../displayUntrusted.js';
 import { guardedRead, readOwnDataValue } from '../ownKey.js';
 export function readRequiresRealApproval(carrier) {
@@ -152,3 +153,19 @@ export function probeCauseRowsOf(card) {
         return undefined;
     }
 }
+const _approvalCardWordPins = [true, true];
+void _approvalCardWordPins;
+const APPROVAL_CARD_WORD_SET = new Set(CORE_TOOL_APPROVAL_CARDS);
+export function readApprovalCardWord(carrier) {
+    try {
+        if (typeof carrier !== 'object' || carrier === null)
+            return undefined;
+        const d = Object.getOwnPropertyDescriptor(carrier, 'approvalCard');
+        if (d === undefined || !Object.hasOwn(d, 'value'))
+            return undefined;
+        return APPROVAL_CARD_WORD_SET.has(d.value) ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/approvalCardReasons.js

@@ -104,8 +104,8 @@ export function approvalCardReasons(card, opts, lang) {
     for (const r of raw) {
         if (r.text === undefined)
             continue;
-        const text = displayUntrusted(r.text);
-        if (text === '' || seen.has(text))
+        const text = r.text;
+        if (text.trim() === '' || seen.has(text))
             continue;
         seen.add(text);
         lines.push(Object.freeze({ source: r.source, text }));

package/dist/hitl/approvalCompleteParked.js

@@ -1,6 +1,6 @@
 function ownData(o, key) {
     const d = Object.getOwnPropertyDescriptor(o, key);
-    return d !== undefined && 'value' in d ? d.value : undefined;
+    return d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
 }
 export function approvalCompleteParked(frame) {
     try {

package/dist/hitl/approvalDelivery.d.ts

@@ -0,0 +1,87 @@
+import { type AnswerCapture, type TopCauseReading, type TopLocalCodeReading, type UnansweredCapture } from '../engineWireFor.js';
+import { type AttributionLadderState, type AttributionLadderStep } from './attributionLadder.js';
+import { type RefusalCarrier, type SafetyStopHead } from './hitlBridge.js';
+export declare const PARKING_WAIT_CAP_MS = 5000;
+export interface DeliveryTiming {
+    readonly delays?: readonly number[];
+    readonly budgetMs?: number;
+    readonly parkingDelayMs?: number;
+}
+export declare function setDeliveryTimingForTests(t?: DeliveryTiming): void;
+export interface DeliveryTimingReading {
+    readonly delays: readonly number[];
+    readonly budgetMs: number;
+    readonly parkingDelayMs: number | undefined;
+}
+export declare function deliveryTiming(): DeliveryTimingReading;
+export type TransportClass = 'aborted' | 'transport' | 'server_5xx' | 'verdict' | 'local_error';
+export interface TransportReading {
+    readonly cls: TransportClass;
+    readonly answered?: AnswerCapture;
+    readonly unanswered?: UnansweredCapture;
+    readonly carrierReads?: readonly {
+        readonly thrown: object;
+        readonly read: RefusalCarrier;
+    }[];
+    readonly topLocalCode?: TopLocalCodeReading;
+    readonly bindingMismatchWrapper?: true;
+    readonly topCause?: TopCauseReading;
+    readonly safetyStop?: true;
+}
+export declare function transportReadingOf(e: {} | null | undefined, signal: AbortSignal | undefined): TransportReading;
+export declare function settledTransportReadingOf(e: {} | null | undefined, signal: AbortSignal | undefined, tally: SendTally): TransportReading;
+export declare function deliveryReadingOf(thrown: {} | null | undefined, tally: SendTally): TransportReading | undefined;
+export declare function transportClassOf(e: {} | null | undefined, signal: AbortSignal | undefined): TransportClass;
+export interface SendTally {
+    attempts: number;
+    retried: boolean;
+    readonly startedAt: number;
+    lastThrown: {
+        readonly thrown: {} | null | undefined;
+        readonly reading: TransportReading;
+    } | undefined;
+}
+export declare function newSendTally(): SendTally;
+export declare function budgetSpent(tally: SendTally, extraMs: number): boolean;
+export declare function isAborted(signal: AbortSignal | undefined): boolean;
+export declare function sleepFor(ms: number, signal: AbortSignal | undefined): Promise<void>;
+export declare function withTransportRetry<T>(send: (signal: AbortSignal | undefined) => Promise<T>, signal: AbortSignal | undefined, tally: SendTally, deadlineOnFirst?: boolean): Promise<T>;
+export interface SettledFailureReading {
+    readonly thrown: {} | null | undefined;
+    readonly reading: TransportReading;
+}
+export declare function directFailureReadingOf(e: {} | null | undefined, triaged: TransportReading, topHead: SafetyStopHead): SettledFailureReading;
+export interface ApprovalParkingFacts {
+    readonly approvalId: string;
+    readonly retryAfterMs?: number;
+}
+export declare function approvalParkingRetryWait(view: ApprovalParkingFacts, tally: SendTally, signal: AbortSignal | undefined): number | undefined;
+export type ApprovalDelivery = {
+    readonly kind: 'answered';
+    readonly raw: {} | null | undefined;
+    readonly parkingRetried?: true;
+} | {
+    readonly kind: 'thrown';
+    readonly error: {} | null | undefined;
+    readonly reading: TransportReading;
+    readonly transportExhausted: boolean;
+    readonly afterRetry: boolean;
+    readonly parkingRetried?: true;
+};
+export interface ApprovalDeliveryInput<B extends {
+    settledBy?: unknown;
+    decidedBy?: unknown;
+}> {
+    readonly approvalId: string;
+    readonly body: B;
+    readonly send: (body: B, signal: AbortSignal | undefined) => Promise<{} | null | undefined | void>;
+    readonly signal: AbortSignal | undefined;
+    readonly tally: SendTally;
+    readonly ladder: AttributionLadderState;
+    readonly onLadderStep?: (step: AttributionLadderStep) => void;
+    readonly parkingOf: (raw: {} | null | undefined) => ApprovalParkingFacts | undefined;
+}
+export declare function deliverApprovalDecision<B extends {
+    settledBy?: unknown;
+    decidedBy?: unknown;
+}>(input: ApprovalDeliveryInput<B>): Promise<ApprovalDelivery>;

package/dist/hitl/approvalDelivery.js

@@ -0,0 +1,193 @@
+import { abortableSleep } from '../abortableSleep.js';
+import { classifyTurnWireError } from '../wireErrorTriage.js';
+import { ownReadingSlot, triageReadingOf } from '../engineWireFor.js';
+import { isSlotCarrier, readThrownSlot, THROWN_SLOT_UNREADABLE } from '../wireFailureShape.js';
+import { deliverWithAttributionLadder, localCodeReadOf, topCauseReadOf } from './attributionLadder.js';
+import { GATE_FAILURE_CODES, refusalCarrierOf, safetyStopHeadOf } from './hitlBridge.js';
+const RETRY_DELAYS_MS = Object.freeze([500, 1_000, 2_000]);
+const RETRY_BUDGET_MS = 8_000;
+export const PARKING_WAIT_CAP_MS = 5_000;
+let timingOverride;
+export function setDeliveryTimingForTests(t) {
+    timingOverride = t;
+}
+export function deliveryTiming() {
+    return { delays: timingOverride?.delays ?? RETRY_DELAYS_MS, budgetMs: timingOverride?.budgetMs ?? RETRY_BUDGET_MS, parkingDelayMs: timingOverride?.parkingDelayMs };
+}
+function isAbortShaped(e) {
+    const name = readThrownSlot(e, 'name');
+    return name === 'TimeoutError' || name === 'AbortError';
+}
+export function transportReadingOf(e, signal) {
+    const reading = triageReadingOf(classifyTurnWireError(e));
+    const answered = ownReadingSlot(reading, 'answer');
+    const unanswered = ownReadingSlot(reading, 'unanswered');
+    const topLocalCode = ownReadingSlot(reading, 'topLocalCode');
+    const topCause = ownReadingSlot(reading, 'topCause');
+    const topFacts = { ...(topLocalCode !== undefined ? { topLocalCode } : {}), ...(topCause !== undefined ? { topCause } : {}) };
+    const layer = answered !== undefined && answered !== THROWN_SLOT_UNREADABLE ? { answered, ...topFacts } : unanswered !== undefined ? { unanswered, ...topFacts } : topFacts;
+    if (signal?.aborted === true)
+        return { cls: 'aborted', ...layer };
+    if (reading === undefined || answered === THROWN_SLOT_UNREADABLE)
+        return { cls: 'local_error', ...topFacts };
+    if (answered !== undefined)
+        return { cls: answered.status === 501 ? 'verdict' : answered.status >= 500 ? 'server_5xx' : 'verdict', ...layer };
+    return { cls: reading.transport || isAbortShaped(e) ? 'transport' : 'local_error', ...layer };
+}
+export function settledTransportReadingOf(e, signal, tally) {
+    const last = ownReadingSlot(tally, 'lastThrown');
+    if (last === undefined || last.thrown !== e)
+        return transportReadingOf(e, signal);
+    if (signal?.aborted === true)
+        return { ...last.reading, cls: 'aborted' };
+    return last.reading;
+}
+export function deliveryReadingOf(thrown, tally) {
+    const last = ownReadingSlot(tally, 'lastThrown');
+    return last !== undefined && last.thrown === thrown ? last.reading : undefined;
+}
+export function transportClassOf(e, signal) {
+    return transportReadingOf(e, signal).cls;
+}
+export function newSendTally() {
+    return { attempts: 0, retried: false, startedAt: Date.now(), lastThrown: undefined };
+}
+function attemptSignal(withDeadline, caller, startedAt, budgetMs) {
+    if (!withDeadline)
+        return caller;
+    const deadline = AbortSignal.timeout(Math.max(1, budgetMs - (Date.now() - startedAt)));
+    if (caller === undefined)
+        return deadline;
+    if (typeof AbortSignal.any === 'function')
+        return AbortSignal.any([caller, deadline]);
+    const ac = new AbortController();
+    const abort = (s) => ac.abort(s.reason);
+    if (caller.aborted)
+        abort(caller);
+    else
+        caller.addEventListener('abort', () => abort(caller), { once: true });
+    deadline.addEventListener('abort', () => abort(deadline), { once: true });
+    return ac.signal;
+}
+export function budgetSpent(tally, extraMs) {
+    return Date.now() - tally.startedAt + extraMs >= deliveryTiming().budgetMs;
+}
+export function isAborted(signal) {
+    return signal?.aborted === true;
+}
+export function sleepFor(ms, signal) {
+    return abortableSleep(ms, signal ?? new AbortController().signal);
+}
+export async function withTransportRetry(send, signal, tally, deadlineOnFirst = false) {
+    const { delays, budgetMs } = deliveryTiming();
+    const startedAt = tally.startedAt;
+    for (let attempt = 1;; attempt++) {
+        tally.attempts++;
+        try {
+            return await send(attemptSignal(attempt > 1 || deadlineOnFirst, signal, startedAt, budgetMs));
+        }
+        catch (e) {
+            const reading = transportReadingOf(e, signal);
+            const cls = reading.cls;
+            const delay = delays[attempt - 1] ?? 0;
+            const heads = localStopHeadsOf(e, reading);
+            const retriable = (cls === 'transport' || cls === 'server_5xx') && heads.safetyStop !== true;
+            const overBudget = Date.now() - startedAt + delay >= budgetMs;
+            if (!retriable || attempt > delays.length || overBudget)
+                throw answeredError(settledReadingOf(e, reading, heads), tally);
+            tally.retried = true;
+            await sleepFor(delay, signal);
+            if (signal?.aborted === true || Date.now() - startedAt >= budgetMs)
+                throw answeredError(settledReadingOf(e, reading, heads), tally);
+        }
+    }
+}
+function answeredError(settled, tally) {
+    tally.lastThrown = settled;
+    return settled.thrown;
+}
+function isLocalClosedCode(v) {
+    return typeof v === 'string' && GATE_FAILURE_CODES.includes(v);
+}
+function localStopHeadsOf(top, reading, known) {
+    const answered = ownReadingSlot(reading, 'answered')?.layer;
+    const deep = answered !== undefined && answered !== top ? answered : undefined;
+    const topCode = isSlotCarrier(top) ? localCodeReadOf(reading, top) : undefined;
+    const topHead = known ?? (!isSlotCarrier(top) ? undefined : topCode === undefined ? safetyStopHeadOf(top) : isLocalClosedCode(topCode.value) ? safetyStopHeadOf(top, topCode) : undefined);
+    const deepCode = deep !== undefined ? localCodeReadOf(reading, deep) : undefined;
+    const layerHead = deep !== undefined && deepCode !== undefined && isLocalClosedCode(deepCode.value) ? safetyStopHeadOf(deep, deepCode) : undefined;
+    const safetyStop = topHead?.local !== undefined || layerHead?.local !== undefined;
+    return Object.freeze({ ...(safetyStop ? { safetyStop: true } : {}), ...(topHead !== undefined ? { top: topHead } : {}), ...(layerHead !== undefined ? { layer: layerHead } : {}) });
+}
+function settledReadingOf(e, reading, heads) {
+    const top = e;
+    const layer = ownReadingSlot(reading, 'answered')?.layer;
+    const wrapper = isSlotCarrier(top) ? refusalCarrierOf(top, localCodeReadOf(reading, top), false, topCauseReadOf(reading, top), heads.top) : undefined;
+    const thrown = layer === undefined ? top : layer;
+    const reads = [];
+    if (wrapper !== undefined && isSlotCarrier(top))
+        reads.push(Object.freeze({ thrown: top, read: wrapper }));
+    if (layer !== undefined && layer !== top)
+        reads.push(Object.freeze({ thrown: layer, read: refusalCarrierOf(layer, localCodeReadOf(reading, layer), true, undefined, heads.layer) }));
+    const bindingMismatchWrapper = layer !== undefined && layer !== top && wrapper !== undefined && ownReadingSlot(wrapper, 'local') === 'binding_mismatch';
+    const safetyStop = heads.safetyStop === true;
+    const settled = reads.length > 0 || bindingMismatchWrapper || safetyStop
+        ? { ...reading, ...(reads.length > 0 ? { carrierReads: Object.freeze(reads) } : {}), ...(bindingMismatchWrapper ? { bindingMismatchWrapper: true } : {}), ...(safetyStop ? { safetyStop: true } : {}) }
+        : reading;
+    return { thrown, reading: settled };
+}
+export function directFailureReadingOf(e, triaged, topHead) {
+    return settledReadingOf(e, triaged, localStopHeadsOf(e, triaged, topHead));
+}
+export function approvalParkingRetryWait(view, tally, signal) {
+    const w = ownReadingSlot(view, 'retryAfterMs');
+    if (typeof w !== 'number' || !Number.isFinite(w) || w < 0)
+        return undefined;
+    if (w > PARKING_WAIT_CAP_MS)
+        return undefined;
+    if (isAborted(signal) || budgetSpent(tally, w))
+        return undefined;
+    return w;
+}
+function thrownFacts(e, signal, tally) {
+    const reading = settledTransportReadingOf(e, signal, tally);
+    return { reading, transportExhausted: reading.cls === 'transport' && tally.retried, afterRetry: tally.retried };
+}
+export async function deliverApprovalDecision(input) {
+    const { signal, tally } = input;
+    let last = input.body;
+    let raw;
+    try {
+        raw = (await deliverWithAttributionLadder(input.body, (b) => {
+            last = b;
+            return withTransportRetry((sig) => input.send(b, sig), signal, tally);
+        }, signal, input.ladder, input.onLadderStep, { kind: 'delivered', readingOf: (thrown) => deliveryReadingOf(thrown, tally) }));
+    }
+    catch (e) {
+        return { kind: 'thrown', error: e, ...thrownFacts(e, signal, tally) };
+    }
+    let parking;
+    try {
+        parking = input.parkingOf(raw);
+    }
+    catch {
+        parking = undefined;
+    }
+    if (parking === undefined || parking.approvalId !== input.approvalId)
+        return { kind: 'answered', raw };
+    const wait = approvalParkingRetryWait(parking, tally, signal);
+    if (wait === undefined)
+        return { kind: 'answered', raw };
+    await sleepFor(wait, signal);
+    if (isAborted(signal) || budgetSpent(tally, 0))
+        return { kind: 'answered', raw };
+    tally.retried = false;
+    const resent = last;
+    try {
+        const raw2 = (await withTransportRetry((sig) => input.send(resent, sig), signal, tally, true));
+        return { kind: 'answered', raw: raw2, parkingRetried: true };
+    }
+    catch (e) {
+        return { kind: 'thrown', error: e, ...thrownFacts(e, signal, tally), parkingRetried: true };
+    }
+}

package/dist/hitl/approvalHolds.d.ts

@@ -1,5 +1,6 @@
 import type { ApprovalHolderIdentity } from './toolApprovalWire.js';
 import type { ApprovalResolution, ApprovalResolutionLane } from './approvalResolution.js';
+import { type DecisionLedgerOp } from './decisionLedger.js';
 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;
@@ -29,6 +30,7 @@ export interface LiveCardHold {
     readonly cardSignal: AbortSignal;
     readonly interrupt: () => void;
     trailing?: Promise<boolean>;
+    ledgerOp?: DecisionLedgerOp;
 }
 export interface HostCardHold {
     readonly lane: 'host';
@@ -61,6 +63,17 @@ export interface HostApprovalCardHold {
     sending(): void;
     release(settled?: 'answered' | 'interrupted'): void;
 }
+export declare function hostHoldIsActive(handle: HostApprovalCardHold): boolean;
+export declare function takeHostHoldLedgerOp(handle: HostApprovalCardHold): DecisionLedgerOp | undefined;
+export type ApprovalHoldAttempt = {
+    readonly kind: 'settled';
+} | {
+    readonly kind: 'busy';
+} | {
+    readonly kind: 'held';
+    readonly hold: HostApprovalCardHold;
+};
+export declare function tryHoldApprovalNow(who: HoldIdentity, signal: AbortSignal | undefined): ApprovalHoldAttempt;
 export type ApprovalCardClaim = {
     readonly kind: 'held';
     readonly hold: HostApprovalCardHold;
@@ -93,4 +106,5 @@ export declare function settledLiveCardOutcome(approvalId: string): ApprovalReso
 export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
 export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ApprovalResolution>): Promise<ApprovalResolution>;
 export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ApprovalResolution>;
+export declare function enterLiveRespondPhase(hold: LiveCardHold): void;
 export declare function supersedeLiveCard(key: string, parked: boolean): boolean;

package/dist/hitl/approvalHolds.js

@@ -1,6 +1,7 @@
 import { hostLog } from '../host.js';
 import { liveFrameCallKey } from './gateIdentity.js';
 import { decideReceiptReopen, readDecideReceipt } from '../decideReceipt.js';
+import { closeDecisionOp, decisionLedgerKeysOf, openDecisionOp, settleDecisionOp } from './decisionLedger.js';
 export const APPROVAL_SETTLED_HOWS = Object.freeze(['answered', 'interrupted', 'closed_by_engine']);
 export const SETTLED_APPROVALS_MAX_ENTRIES = 4096;
 const nonEmpty = (v) => typeof v === 'string' && v !== '';
@@ -110,11 +111,16 @@ function holdHostCard(identity, signal) {
     h.inFlight.set(key, hold);
     let done = false;
     let stopFollowing = () => { };
+    let ledgerOp;
     const release = (settled) => {
         if (done)
             return;
         done = true;
         stopFollowing();
+        if (ledgerOp !== undefined) {
+            settleDecisionOp(ledgerOp, 'host');
+            ledgerOp.ownCallOpen = false;
+        }
         const how = settled === 'answered' || settled === 'interrupted' ? settled : undefined;
         if (how !== undefined && nonEmpty(frozen.approvalId))
             noteSettled(frozen.approvalId, how, false, how === 'interrupted' ? interruptedThere('decide') : nothingSentHere('decide'), true);
@@ -127,6 +133,8 @@ function holdHostCard(identity, signal) {
         sending: () => {
             if (done)
                 return;
+            if (hold.phase !== 'respond')
+                ledgerOp = openDecisionOp('tool_approval', ledgerKeysOfHold(frozen), 'handed', true);
             hold.phase = 'respond';
             stopFollowing();
         },
@@ -136,8 +144,31 @@ function holdHostCard(identity, signal) {
         if (!done && hold.phase === 'card')
             release();
     });
+    hostHoldControls.set(handle, {
+        active: () => !done && h.inFlight.get(key) === hold,
+        takeLedgerOp: () => {
+            const op = ledgerOp;
+            ledgerOp = undefined;
+            return op;
+        },
+    });
     return handle;
 }
+const hostHoldControls = new WeakMap();
+export function hostHoldIsActive(handle) {
+    return hostHoldControls.get(handle)?.active() === true;
+}
+export function takeHostHoldLedgerOp(handle) {
+    return hostHoldControls.get(handle)?.takeLedgerOp();
+}
+export function tryHoldApprovalNow(who, signal) {
+    const entry = settledApprovalOf(who.approvalId);
+    if (entry !== undefined && settledForDurableLane(entry))
+        return Object.freeze({ kind: 'settled' });
+    if (approvalHoldFor(who) !== undefined)
+        return Object.freeze({ kind: 'busy' });
+    return Object.freeze({ kind: 'held', hold: holdHostCard(who, signal) });
+}
 function callerSignalAborted(signal) {
     if (signal === undefined || signal === null)
         return false;
@@ -254,6 +285,8 @@ export function holdLiveCard(identity, callerSignal, present) {
     const hold = { lane: 'live', identity: Object.freeze({ ...identity }), outcome, phase: 'card', cardSignal: cut.signal, interrupt };
     h.inFlight.set(key, hold);
     const release = () => {
+        if (hold.ledgerOp !== undefined)
+            closeDecisionOp(hold.ledgerOp, 'package');
         if (h.inFlight.get(key) === hold)
             h.inFlight.delete(key);
     };
@@ -320,6 +353,14 @@ function followCallerSignal(signal, onAbort) {
         }
     };
 }
+function ledgerKeysOfHold(identity) {
+    return decisionLedgerKeysOf({ taskId: identity.taskId, approvalId: identity.approvalId, callId: identity.toolCallId });
+}
+export function enterLiveRespondPhase(hold) {
+    if (hold.ledgerOp === undefined)
+        hold.ledgerOp = openDecisionOp('tool_approval', ledgerKeysOfHold(hold.identity), 'posting', true);
+    hold.phase = 'respond';
+}
 export function supersedeLiveCard(key, parked) {
     const hold = liveCardHoldOf(key);
     if (hold === undefined || hold.phase !== 'card' || hold.superseded !== undefined)

package/dist/hitl/approvalResolution.d.ts

@@ -3,6 +3,7 @@ import { type HitlSafetyCode } from './hitlBridge.js';
 import type { AskAnsweredOutput } from './gateLedger.js';
 import type { ApprovalDenySettledBy, ToolApprovalRespondAckView, ToolApprovalRespondDecision, ToolApprovalRespondParkingView } from './toolApprovalWire.js';
 import { type DecisionRefusalReading, type RefusalRouteContext } from './decisionRefusal.js';
+import { type DeliveredReading, type LadderSafetyStop } from './attributionLadder.js';
 export declare const APPROVAL_RESOLUTION_LANES: readonly ["respond", "decide", "ask"];
 export type ApprovalResolutionLane = (typeof APPROVAL_RESOLUTION_LANES)[number];
 export declare const APPROVAL_NOT_SENT_CAUSES: readonly ["retracted", "edit_refused", "no_pending", "wrong_gate", "fetch_failed", "no_input", "card_unavailable", "safety_stop"];
@@ -55,7 +56,17 @@ export interface DecisionFailureMint {
     readonly gatedCallId?: string | undefined;
     readonly detail?: string | undefined;
     readonly attributionCarried?: boolean | undefined;
+    readonly transportExhausted?: boolean | undefined;
+    readonly afterRetry?: boolean | undefined;
+    readonly delivered?: DeliveredReading | undefined;
+    readonly directStop?: LadderSafetyStop | undefined;
 }
 export declare function resolutionOfDecisionFailure(e: {} | null | undefined, m: DecisionFailureMint): ApprovalResolution;
+export declare function directSafetyStopOf(e: {} | null | undefined): LadderSafetyStop | undefined;
+export interface DirectFailureVerdict {
+    readonly yields: boolean;
+    readonly directStop?: LadderSafetyStop;
+}
+export declare function directFailureVerdictOf(e: {} | null | undefined, stop: LadderSafetyStop | undefined): DirectFailureVerdict;
 export declare function joinedResolution(r: ApprovalResolution, gatedCallId?: string): ApprovalResolution;
 export {};