@sema-agent/client-core 0.97.0 → 0.98.0

package/dist/hitl/approvalCardReading.js

@@ -0,0 +1,154 @@
+import { displayUntrusted } from '../displayUntrusted.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
+export function readRequiresRealApproval(carrier) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return false;
+    let failed = false;
+    let failure;
+    try {
+        if (carrier.requiresRealApproval === true)
+            return true;
+    }
+    catch (e) {
+        failed = true;
+        failure = e;
+    }
+    try {
+        const risk = carrier.risk;
+        if (typeof risk === 'object' && risk !== null && risk.requiresRealApproval === true)
+            return true;
+    }
+    catch (e) {
+        if (!failed)
+            failure = e;
+        failed = true;
+    }
+    if (failed)
+        throw failure;
+    return false;
+}
+const EMPTY = Object.freeze({});
+const UNKNOWN_SHAPE_COHERENCE_TOLERANCE_MS = 1_000;
+function nonNegativeFinite(v) {
+    return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined;
+}
+export function approvalWindowKeysOf(carrier, opts) {
+    if (typeof carrier !== 'object' || carrier === null)
+        return EMPTY;
+    if (typeof opts !== 'object' || opts === null)
+        return EMPTY;
+    let current;
+    let anchor;
+    let unknownShape;
+    try {
+        current = opts.windowIsCurrent;
+        anchor = opts.receivedAtMs;
+        unknownShape = opts.unknownShape;
+    }
+    catch {
+        return EMPTY;
+    }
+    if (current !== true)
+        return EMPTY;
+    const read = (key) => {
+        try {
+            return nonNegativeFinite(carrier[key]);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const inMs = read('expiresInMs');
+    const atMs = read('expiresAtMs');
+    const nowMs = read('serverNowMs');
+    if (unknownShape === true) {
+        if (inMs === undefined || atMs === undefined || nowMs === undefined)
+            return EMPTY;
+        if (atMs <= 0 || nowMs <= 0)
+            return EMPTY;
+        if (Math.abs(inMs - Math.max(0, atMs - nowMs)) > UNKNOWN_SHAPE_COHERENCE_TOLERANCE_MS)
+            return EMPTY;
+    }
+    const receivedAtMs = nonNegativeFinite(anchor);
+    const out = {};
+    if (inMs !== undefined)
+        out.expiresInMs = inMs;
+    if (atMs !== undefined)
+        out.expiresAtMs = atMs;
+    if (nowMs !== undefined)
+        out.serverNowMs = nowMs;
+    if ((inMs !== undefined || atMs !== undefined) && receivedAtMs !== undefined)
+        out.receivedAtMs = receivedAtMs;
+    return Object.freeze(out);
+}
+const PROBE_CAUSE_SHOWN_MAX = 8;
+const PROBE_CAUSE_ENTRY_MAX = 200;
+function own(v, key) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    return guardedRead(() => readOwnDataValue(v, key));
+}
+function readOperands(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const shown = own(v, 'shown');
+    const isList = guardedRead(() => Array.isArray(shown));
+    if (isList !== true)
+        return undefined;
+    const length = own(shown, 'length');
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        return undefined;
+    const items = [];
+    for (let i = 0; i < length; i++) {
+        const item = own(shown, String(i));
+        if (typeof item !== 'string')
+            return undefined;
+        items.push(item);
+    }
+    const total = own(v, 'total');
+    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < 0 || total < items.length)
+        return undefined;
+    return { shown: items, total };
+}
+function operandsText(label, o) {
+    const shown = o.shown.slice(0, PROBE_CAUSE_SHOWN_MAX).map((p) => displayUntrusted(p, { max: PROBE_CAUSE_ENTRY_MAX }));
+    if (shown.length === 0)
+        return `${label}: ${String(o.total)} total`;
+    const more = o.total - shown.length;
+    return more > 0 ? `${label}: ${shown.join(', ')} (+${String(more)} more)` : `${label}: ${shown.join(', ')}`;
+}
+export function probeCauseRowsOf(card) {
+    try {
+        if (typeof card !== 'object' || card === null)
+            return undefined;
+        const cause = own(card, 'probeCause');
+        if (typeof cause !== 'object' || cause === null)
+            return undefined;
+        if (guardedRead(() => Array.isArray(cause)) !== false)
+            return undefined;
+        const code = own(cause, 'code');
+        if (typeof code !== 'string' || code === '')
+            return undefined;
+        const roots = readOperands(own(cause, 'roots'));
+        if (roots === undefined)
+            return undefined;
+        let fd;
+        try {
+            fd = Object.getOwnPropertyDescriptor(cause, 'further');
+        }
+        catch {
+            return undefined;
+        }
+        if (fd === undefined || (Object.hasOwn(fd, 'value') && fd.value === undefined))
+            return Object.freeze([operandsText('roots', roots)]);
+        if (!Object.hasOwn(fd, 'value'))
+            return undefined;
+        const further = readOperands(fd.value);
+        if (further === undefined)
+            return undefined;
+        return Object.freeze([operandsText('roots', roots), operandsText('further', further)]);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/approvalCardReasons.d.ts

@@ -0,0 +1,13 @@
+import { type DenialLimitFallback } from './toolApprovalWire.js';
+export declare const APPROVAL_CARD_REASON_SOURCES: readonly ["payload_unreadable", "prior_cards", "message", "mandated", "mandate", "origin", "denial_limit", "probe", "allow_rule_shadow", "classifier_no_ruling", "bound_grants", "more"];
+export type ApprovalCardReasonSource = (typeof APPROVAL_CARD_REASON_SOURCES)[number];
+export interface ApprovalCardReasonLine {
+    readonly source: ApprovalCardReasonSource;
+    readonly text: string;
+}
+export interface ApprovalCardReasonsOptions {
+    readonly maxLines?: number;
+}
+export declare const APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES = 4;
+export declare function denialLimitFallbackDetail(v: DenialLimitFallback | null | undefined): string | undefined;
+export declare function approvalCardReasons(card: object | null | undefined, opts?: ApprovalCardReasonsOptions | null): readonly ApprovalCardReasonLine[];

package/dist/hitl/approvalCardReasons.js

@@ -0,0 +1,120 @@
+import { displayUntrusted } from '../displayUntrusted.js';
+import { approvalMandateDetail, askOriginNoteOf } from '../gateVocabulary.js';
+import { readAskOrigin, readOwnDataValue, guardedRead } from '../ownKey.js';
+import { allowRuleShadowSentence } from './allowRuleShadow.js';
+import { mandatedApprovalDetailOf } from './automaticAnswerVerdict.js';
+import { approvalBoundGrantsDetail, approvalIsMandated, approvalPriorCardsDetail, askProbeReasonDetail, classifierNoRulingDetail, readApprovalBoundGrants, readApprovalClassifierNoRuling, readApprovalMandate, readDenialLimitFallback, } from './toolApprovalWire.js';
+export const APPROVAL_CARD_REASON_SOURCES = Object.freeze([
+    'payload_unreadable',
+    'prior_cards',
+    'message',
+    'mandated',
+    'mandate',
+    'origin',
+    'denial_limit',
+    'probe',
+    'allow_rule_shadow',
+    'classifier_no_ruling',
+    'bound_grants',
+    'more',
+]);
+export const APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES = 4;
+const MESSAGE_DISPLAY_MAX = 300;
+const PAYLOAD_UNREADABLE_DETAIL = 'This client cannot read the format of this approval card, so only its basic facts are shown — decide from those, or deny it if you are not sure what it will do.';
+function moreDetail(n) {
+    return n === 1 ? '1 more reason for this card is not shown.' : `${String(n)} more reasons for this card are not shown.`;
+}
+export function denialLimitFallbackDetail(v) {
+    const d = readDenialLimitFallback(v);
+    if (d === undefined)
+        return undefined;
+    const parts = [
+        'auto-deny limit reached — auto mode denied enough calls on its own that the engine now wants a real human decision',
+        `${String(d.consecutive)} consecutive / ${String(d.total)} total automatic denials so far`,
+        `the limit that tripped: ${displayUntrusted(d.limit, { max: 24 })}`,
+    ];
+    if (d.autoDenyAfterMs > 0)
+        parts.push(`the engine auto-denies it in ${String(Math.round(d.autoDenyAfterMs / 1000))}s if nobody answers`);
+    return parts.join('; ');
+}
+function ownData(card, key) {
+    return guardedRead(() => readOwnDataValue(card, key));
+}
+function readMaxLines(opts) {
+    const raw = typeof opts === 'object' && opts !== null ? guardedRead(() => readOwnDataValue(opts, 'maxLines')) : undefined;
+    return typeof raw === 'number' && Number.isSafeInteger(raw) && raw >= 1 ? raw : APPROVAL_CARD_REASONS_DEFAULT_MAX_LINES;
+}
+export function approvalCardReasons(card, opts) {
+    if (typeof card !== 'object' || card === null)
+        return Object.freeze([]);
+    const raw = [];
+    const add = (source, read) => {
+        let text;
+        try {
+            text = read();
+        }
+        catch {
+            text = undefined;
+        }
+        raw.push({ source, text });
+    };
+    let denialLimitReadable = false;
+    try {
+        denialLimitReadable = readDenialLimitFallback(ownData(card, 'denialLimitFallback')) !== undefined;
+    }
+    catch {
+        denialLimitReadable = false;
+    }
+    add('payload_unreadable', () => (ownData(card, 'cardPayloadUnreadable') === true ? PAYLOAD_UNREADABLE_DETAIL : undefined));
+    add('prior_cards', () => approvalPriorCardsDetail(card));
+    add('message', () => {
+        const msg = ownData(card, 'message');
+        if (typeof msg !== 'string' || msg.trim() === '')
+            return undefined;
+        const tool = ownData(card, 'toolName');
+        if (typeof tool === 'string' && msg.trim() === `approval required for "${tool}"`)
+            return undefined;
+        return displayUntrusted(msg, { max: MESSAGE_DISPLAY_MAX });
+    });
+    add('mandated', () => (approvalIsMandated(card) ? mandatedApprovalDetailOf(card) : undefined));
+    add('mandate', () => {
+        const word = readApprovalMandate(card);
+        return word !== undefined ? approvalMandateDetail(word) : undefined;
+    });
+    add('origin', () => {
+        const origin = readAskOrigin(card);
+        if (origin === undefined)
+            return undefined;
+        if (origin === 'denial_limit_fallback' && denialLimitReadable)
+            return undefined;
+        return askOriginNoteOf(origin);
+    });
+    add('denial_limit', () => denialLimitFallbackDetail(ownData(card, 'denialLimitFallback')));
+    add('probe', () => askProbeReasonDetail(card));
+    add('allow_rule_shadow', () => allowRuleShadowSentence(card));
+    add('classifier_no_ruling', () => {
+        const word = readApprovalClassifierNoRuling(card);
+        return word !== undefined ? classifierNoRulingDetail(word) : undefined;
+    });
+    add('bound_grants', () => {
+        const grants = readApprovalBoundGrants(card);
+        return grants !== undefined ? approvalBoundGrantsDetail(grants) : undefined;
+    });
+    const seen = new Set();
+    const lines = [];
+    for (const r of raw) {
+        if (r.text === undefined)
+            continue;
+        const text = displayUntrusted(r.text);
+        if (text === '' || seen.has(text))
+            continue;
+        seen.add(text);
+        lines.push(Object.freeze({ source: r.source, text }));
+    }
+    const max = readMaxLines(opts);
+    if (lines.length <= max)
+        return Object.freeze(lines);
+    const kept = lines.slice(0, max - 1);
+    kept.push(Object.freeze({ source: 'more', text: moreDetail(lines.length - kept.length) }));
+    return Object.freeze(kept);
+}

package/dist/hitl/approvalHolds.d.ts

@@ -1,15 +1,18 @@
-import type { ApprovalHolderIdentity, FsApprovalOutcome, ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+import type { ApprovalHolderIdentity } from './toolApprovalWire.js';
+import type { ApprovalResolution, ApprovalResolutionLane } from './approvalResolution.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;
 export interface SettledApprovalEntry {
     readonly how: ApprovalSettledHow;
     readonly parked: boolean;
-    readonly outcome: ToolApprovalFrameOutcome;
+    readonly outcome: ApprovalResolution;
 }
 export interface DurableDecisionHold {
     readonly lane: 'durable';
-    readonly outcome: Promise<FsApprovalOutcome>;
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly outcome: Promise<ApprovalResolution>;
     presented: boolean;
     readonly interrupt: () => void;
     readonly cardSignal: AbortSignal;
@@ -18,7 +21,7 @@ export interface DurableDecisionHold {
 export interface LiveCardHold {
     readonly lane: 'live';
     readonly identity: LiveCardIdentity;
-    readonly outcome: Promise<ToolApprovalFrameOutcome>;
+    readonly outcome: Promise<ApprovalResolution>;
     phase: 'card' | 'respond';
     superseded?: {
         readonly parked: boolean;
@@ -27,17 +30,45 @@ export interface LiveCardHold {
     readonly interrupt: () => void;
     trailing?: Promise<boolean>;
 }
-export type ApprovalHold = DurableDecisionHold | LiveCardHold;
-export interface LiveCardIdentity {
+export interface HostCardHold {
+    readonly lane: 'host';
+    readonly identity: HoldIdentity;
+    phase: 'card' | 'respond';
+    readonly released: Promise<'answered' | 'interrupted' | undefined>;
+}
+export type ApprovalHold = DurableDecisionHold | LiveCardHold | HostCardHold;
+export interface LiveCardIdentity extends HoldIdentity {
     readonly approvalId: string;
-    readonly toolCallId?: string;
-    readonly taskId?: string;
-    readonly sessionId?: string;
 }
-export declare function liveCardHoldFor(who: ApprovalHolderIdentity): LiveCardHold | undefined;
+export interface HoldIdentity extends ApprovalHolderIdentity {
+    readonly askSig?: string;
+}
+export declare function approvalHoldFor(who: HoldIdentity, except?: (h: ApprovalHold) => boolean): ApprovalHold | undefined;
 export declare function settledForDurableLane(entry: SettledApprovalEntry | undefined): boolean;
-export declare function liveCardAnsweredHow(o: ToolApprovalFrameOutcome): 'answered' | 'interrupted' | undefined;
-export declare function awaitLiveCardHolder(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome | undefined>;
+export declare function liveCardAnsweredHow(r: ApprovalResolution): 'answered' | 'interrupted' | undefined;
+export type ApprovalHolderWait = {
+    readonly kind: 'settled';
+    readonly how: 'answered' | 'interrupted';
+    readonly outcome: ApprovalResolution;
+} | {
+    readonly kind: 'free';
+} | {
+    readonly kind: 'left';
+};
+export declare function awaitApprovalHolder(hold: ApprovalHold, signal: AbortSignal | undefined, asker: ApprovalResolutionLane): Promise<ApprovalHolderWait>;
+export interface HostApprovalCardHold {
+    readonly identity: ApprovalHolderIdentity;
+    sending(): void;
+    release(settled?: 'answered' | 'interrupted'): void;
+}
+export type ApprovalCardClaim = {
+    readonly kind: 'held';
+    readonly hold: HostApprovalCardHold;
+} | {
+    readonly kind: 'joined';
+    readonly outcome: ApprovalResolution;
+};
+export declare function claimApprovalCardFor(who: HoldIdentity, signal: AbortSignal | undefined): Promise<ApprovalCardClaim>;
 export interface ApprovalDecisionHoldTable {
     readonly inFlight: Map<string, ApprovalHold>;
     readonly settled: Map<string, DurableSettledHold>;
@@ -54,8 +85,9 @@ export declare function settledApprovalOf(approvalId: string | undefined): Settl
 export declare function clearSettledApprovals(): void;
 export declare function anyApprovalSettled(): boolean;
 export declare function noteEngineClosedApproval(approvalId: string, parked: boolean): void;
-export declare function settledLiveCardOutcome(approvalId: string): ToolApprovalFrameOutcome | undefined;
+export declare function noteHolderSettledApproval(approvalId: string, how: 'answered' | 'interrupted', outcome: ApprovalResolution): void;
+export declare function settledLiveCardOutcome(approvalId: string): ApprovalResolution | undefined;
 export declare function liveCardHoldOf(key: string): LiveCardHold | undefined;
-export declare function holdLiveCard(identity: LiveCardIdentity, callerSignal: AbortSignal | undefined, present: (hold: LiveCardHold) => Promise<ToolApprovalFrameOutcome>): Promise<ToolApprovalFrameOutcome>;
-export declare function joinLiveCard(hold: LiveCardHold, signal: AbortSignal | undefined): Promise<ToolApprovalFrameOutcome>;
+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 supersedeLiveCard(key: string, parked: boolean): boolean;

package/dist/hitl/approvalHolds.js

@@ -1,51 +1,149 @@
 import { hostLog } from '../host.js';
 import { liveFrameCallKey } from './gateIdentity.js';
-import { approvalResolutionOf } from './approvalResolution.js';
+import { decideReceiptReopen } from '../decideReceipt.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 !== '';
-export function liveCardHoldFor(who) {
-    if (nonEmpty(who.approvalId))
-        return liveCardHoldOf(liveFrameCallKey(who.approvalId));
-    if (!nonEmpty(who.taskId) || !nonEmpty(who.toolCallId))
-        return undefined;
+function sameApproval(who, h) {
+    const id = h.identity;
+    if (nonEmpty(who.approvalId) && nonEmpty(id.approvalId))
+        return who.approvalId === id.approvalId;
+    if (h.phase !== 'card')
+        return false;
+    if (!nonEmpty(who.taskId) || !nonEmpty(who.toolCallId) || id.taskId !== who.taskId || id.toolCallId !== who.toolCallId)
+        return false;
+    if (nonEmpty(who.sessionId) && nonEmpty(id.sessionId) && id.sessionId !== who.sessionId)
+        return false;
+    return !(nonEmpty(who.askSig) && nonEmpty(id.askSig) && id.askSig !== who.askSig);
+}
+export function approvalHoldFor(who, except) {
     for (const h of approvalDecisionHolds.inFlight.values()) {
-        if (h.lane !== 'live' || h.phase !== 'card')
+        if (except?.(h) === true)
             continue;
-        const id = h.identity;
-        if (id.taskId !== who.taskId || id.toolCallId !== who.toolCallId)
-            continue;
-        if (nonEmpty(who.sessionId) && nonEmpty(id.sessionId) && id.sessionId !== who.sessionId)
-            continue;
-        return h;
+        if (sameApproval(who, h))
+            return h;
     }
     return undefined;
 }
 export function settledForDurableLane(entry) {
     return entry !== undefined && !entry.parked;
 }
-export function liveCardAnsweredHow(o) {
-    return answeredHowOf(approvalResolutionOf(o));
-}
-function answeredHowOf(r) {
+export function liveCardAnsweredHow(r) {
     if (r.kind === 'decided')
         return 'answered';
     return r.kind === 'unsettled' && r.cause === 'interrupted' ? 'interrupted' : undefined;
 }
-export async function awaitLiveCardHolder(hold, signal) {
+const HOLDER_FREE = Object.freeze({ kind: 'free' });
+function nothingSentHere(asker) {
+    return Object.freeze({ kind: 'not_sent', lane: asker, cause: 'retracted' });
+}
+function interruptedThere(asker) {
+    return Object.freeze({ kind: 'unsettled', lane: asker, cause: 'interrupted' });
+}
+export async function awaitApprovalHolder(hold, signal, asker) {
+    if (hold.lane === 'host')
+        return awaitHostHolder(hold, signal, asker);
     const unsubscribe = followCallerSignal(signal, hold.interrupt);
-    let o;
     try {
-        o = await hold.outcome;
+        if (hold.lane === 'live') {
+            let o;
+            try {
+                o = await hold.outcome;
+            }
+            catch {
+                return HOLDER_FREE;
+            }
+            const stillHeld = approvalDecisionHolds.inFlight.get(liveFrameCallKey(hold.identity.approvalId)) === hold;
+            const entry = settledApprovalOf(hold.identity.approvalId);
+            if (!stillHeld && !settledForDurableLane(entry))
+                return HOLDER_FREE;
+            return Object.freeze({ kind: 'settled', how: entry?.how === 'answered' ? 'answered' : 'interrupted', outcome: o });
+        }
+        let r;
+        try {
+            r = await hold.outcome;
+        }
+        catch {
+            return HOLDER_FREE;
+        }
+        if (r.kind === 'decided') {
+            if (decideReceiptReopen(r.receipt) !== null)
+                return HOLDER_FREE;
+            return Object.freeze({ kind: 'settled', how: 'answered', outcome: r });
+        }
+        if (r.kind !== 'unsettled' || r.cause !== 'interrupted' || hold.trailing === undefined)
+            return HOLDER_FREE;
+        const landed = await hold.trailing.then(() => true, () => false);
+        return landed ? Object.freeze({ kind: 'settled', how: 'interrupted', outcome: r }) : HOLDER_FREE;
     }
-    catch {
-        return undefined;
+    finally {
+        unsubscribe();
+    }
+}
+async function awaitHostHolder(hold, signal, asker) {
+    let leave = () => { };
+    const left = new Promise((resolve) => {
+        leave = () => resolve('left');
+    });
+    const unsubscribe = followCallerSignal(signal, leave);
+    try {
+        const r = await Promise.race([hold.released, left]);
+        if (r === 'left')
+            return Object.freeze({ kind: 'left' });
+        if (r === undefined)
+            return HOLDER_FREE;
+        return Object.freeze({ kind: 'settled', how: r, outcome: r === 'interrupted' ? interruptedThere(asker) : nothingSentHere(asker) });
     }
     finally {
         unsubscribe();
     }
-    const stillHeld = approvalDecisionHolds.inFlight.get(liveFrameCallKey(hold.identity.approvalId)) === hold;
-    return stillHeld || settledForDurableLane(settledApprovalOf(hold.identity.approvalId)) ? { ...o, joinedInFlight: true } : undefined;
+}
+function holdHostCard(identity) {
+    const h = approvalDecisionHolds;
+    const key = `hitl-host:${++h.clock}`;
+    let resolveReleased = () => { };
+    const released = new Promise((resolve) => {
+        resolveReleased = resolve;
+    });
+    const frozen = Object.freeze({ ...identity });
+    const hold = { lane: 'host', identity: frozen, phase: 'card', released };
+    h.inFlight.set(key, hold);
+    let done = false;
+    return Object.freeze({
+        identity: frozen,
+        sending: () => {
+            if (!done)
+                hold.phase = 'respond';
+        },
+        release: (settled) => {
+            if (done)
+                return;
+            done = true;
+            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);
+            if (h.inFlight.get(key) === hold)
+                h.inFlight.delete(key);
+            resolveReleased(how);
+        },
+    });
+}
+const CLAIM_MAX_ROUNDS = 8;
+export async function claimApprovalCardFor(who, signal) {
+    for (let round = 0; round < CLAIM_MAX_ROUNDS; round++) {
+        const entry = settledApprovalOf(who.approvalId);
+        if (settledForDurableLane(entry) && entry !== undefined)
+            return Object.freeze({ kind: 'joined', outcome: { ...entry.outcome, joinedInFlight: true } });
+        const holder = approvalHoldFor(who);
+        if (holder === undefined)
+            return Object.freeze({ kind: 'held', hold: holdHostCard(who) });
+        const wait = await awaitApprovalHolder(holder, signal, 'decide');
+        if (wait.kind === 'settled')
+            return Object.freeze({ kind: 'joined', outcome: { ...wait.outcome, joinedInFlight: true } });
+        if (wait.kind === 'left')
+            return Object.freeze({ kind: 'joined', outcome: { ...nothingSentHere('decide'), joinedInFlight: true } });
+    }
+    return Object.freeze({ kind: 'held', hold: holdHostCard(who) });
 }
 export const approvalDecisionHolds = { inFlight: new Map(), settled: new Map(), openReads: new Set(), outcomes: new Map(), clock: 0 };
 export function settledApprovalOf(approvalId) {
@@ -57,14 +155,17 @@ export function clearSettledApprovals() {
 export function anyApprovalSettled() {
     return approvalDecisionHolds.outcomes.size > 0;
 }
-function noteSettled(approvalId, how, parked, outcome) {
+function noteSettled(approvalId, how, parked, outcome, upgradesParked = false) {
     if (typeof approvalId !== 'string' || approvalId === '')
         return;
     if (!APPROVAL_SETTLED_HOWS.includes(how))
         return;
     const t = approvalDecisionHolds.outcomes;
-    if (t.has(approvalId))
+    const prev = t.get(approvalId);
+    if (prev !== undefined && !(upgradesParked && prev.parked && how !== 'closed_by_engine'))
         return;
+    if (prev !== undefined)
+        t.delete(approvalId);
     t.set(approvalId, Object.freeze({ how, parked, outcome: Object.freeze({ ...outcome }) }));
     while (t.size > SETTLED_APPROVALS_MAX_ENTRIES) {
         const oldest = t.keys().next();
@@ -73,9 +174,14 @@ function noteSettled(approvalId, how, parked, outcome) {
         t.delete(oldest.value);
     }
 }
-const ENGINE_CLOSED_OUTCOME = Object.freeze({ decision: 'unresolved', retracted: true });
+function engineClosedOutcome() {
+    return Object.freeze({ kind: 'not_sent', lane: 'respond', cause: 'retracted' });
+}
 export function noteEngineClosedApproval(approvalId, parked) {
-    noteSettled(approvalId, 'closed_by_engine', parked, ENGINE_CLOSED_OUTCOME);
+    noteSettled(approvalId, 'closed_by_engine', parked, engineClosedOutcome());
+}
+export function noteHolderSettledApproval(approvalId, how, outcome) {
+    noteSettled(approvalId, how, false, outcome, true);
 }
 export function settledLiveCardOutcome(approvalId) {
     const e = settledApprovalOf(approvalId);