@sema-agent/client-core 0.97.1 → 0.99.0

package/dist/hitl/approvalResolution.js

@@ -1,156 +1,120 @@
+import { DecideTransportRetryExhaustedError } from './hitlBridge.js';
+import { mintDecisionRefusalReading, refusalCarrierOf } from './decisionRefusal.js';
+import { thrownIsInstanceOf } from '../wireFailureShape.js';
+export const APPROVAL_RESOLUTION_LANES = Object.freeze(['respond', 'decide', 'ask']);
 export const APPROVAL_NOT_SENT_CAUSES = Object.freeze([
     'retracted',
     'edit_refused',
     'no_pending',
+    'wrong_gate',
     'fetch_failed',
     'no_input',
     'card_unavailable',
+    'safety_stop',
 ]);
 export const APPROVAL_UNSETTLED_CAUSES = Object.freeze([
     'engine_refused',
-    'decide_failed',
+    'engine_error',
+    'no_answer',
     'transport_exhausted',
-    'safety_stop',
-    'respond_failed',
     'parking_in_progress',
     'interrupted',
     'orchestration',
     'unreadable',
 ]);
-const FS_OUTCOME_KINDS = Object.freeze(['decided', 'aborted', 'retracted', 'failed']);
-function str(v) {
-    return typeof v === 'string' && v.length > 0 ? v : undefined;
+export function isApprovalDecided(r) {
+    return typeof r === 'object' && r !== null && r.kind === 'decided';
 }
-function num(v) {
-    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+export function approvalNotSentCause(r) {
+    if (typeof r !== 'object' || r === null || r.kind !== 'not_sent')
+        return undefined;
+    return r.cause;
 }
-function pick(o, key) {
+export function approvalUnsettledCause(r) {
+    if (typeof r !== 'object' || r === null || r.kind !== 'unsettled')
+        return undefined;
+    return r.cause;
+}
+export const APPROVAL_NOTE_RETRACTED_DETAIL = 'the card was retracted (this host no longer has a decision port for it)';
+export const APPROVAL_NOTE_EDIT_REFUSED_DETAIL = 'edits are not accepted on this card';
+const NOT_SENT_SENTENCES = Object.freeze({
+    retracted: APPROVAL_NOTE_RETRACTED_DETAIL,
+    edit_refused: APPROVAL_NOTE_EDIT_REFUSED_DETAIL,
+    no_pending: 'there was no pending approval to decide for this run (it may already have been decided or expired); nothing was sent',
+    wrong_gate: 'the pending approval is waiting at a different kind of gate than this card; nothing was sent',
+    fetch_failed: 'the pending approval could not be fetched; nothing was sent',
+    no_input: 'the approval has no tool input or question to show, so no card was shown; nothing was sent',
+    card_unavailable: 'no approval card could be shown on this host; nothing was sent',
+    safety_stop: 'the decision was stopped by a local safety check before it was sent; nothing was sent',
+});
+function nonEmpty(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function ownStr(o, key) {
     try {
-        return o?.[key];
+        if (typeof o !== 'object' || o === null)
+            return undefined;
+        const d = Object.getOwnPropertyDescriptor(o, key);
+        return d !== undefined && Object.hasOwn(d, 'value') ? nonEmpty(d.value) : undefined;
     }
     catch {
         return undefined;
     }
 }
-function opt(key, v) {
-    return v === undefined ? {} : { [key]: v };
-}
-export function approvalResolutionOf(outcome) {
-    if (typeof outcome !== 'object' || outcome === null || Array.isArray(outcome)) {
-        return { kind: 'unsettled', cause: 'unreadable' };
+export function approvalResolutionDetail(r) {
+    let kind;
+    try {
+        kind = typeof r === 'object' && r !== null ? r.kind : undefined;
     }
-    const kind = pick(outcome, 'kind');
-    if (typeof kind === 'string' && FS_OUTCOME_KINDS.includes(kind)) {
-        return fsLegResolution(outcome, kind);
+    catch {
+        return undefined;
     }
-    if (typeof pick(outcome, 'decision') === 'string') {
-        return frameLegResolution(outcome);
+    if (kind === 'not_sent') {
+        const cause = ownStr(r, 'cause');
+        if (cause === undefined || !Object.hasOwn(NOT_SENT_SENTENCES, cause))
+            return undefined;
+        const sentence = NOT_SENT_SENTENCES[cause];
+        const code = cause === 'safety_stop' ? ownStr(r, 'safetyCode') : undefined;
+        return code !== undefined ? `${sentence} (${code})` : sentence;
     }
-    return { kind: 'unsettled', cause: 'unreadable' };
-}
-function fsLegResolution(outcome, kind) {
-    const gatedCallId = str(pick(outcome, 'gatedCallId'));
-    const call = opt('gatedCallId', gatedCallId);
-    if (kind === 'decided') {
-        return {
-            kind: 'decided',
-            decision: pick(outcome, 'denied') === true ? 'deny' : 'allow',
-            ...call,
-            ...opt('receipt', pick(outcome, 'receipt')),
-        };
-    }
-    if (kind === 'retracted')
-        return { kind: 'not_sent', cause: 'retracted', ...call };
-    if (kind === 'aborted')
-        return { kind: 'unsettled', cause: 'interrupted', ...call };
-    const detail = opt('detail', str(pick(outcome, 'reason')));
-    const stage = pick(outcome, 'stage');
-    if (stage === 'fetch') {
-        const cause = pick(outcome, 'code') === 'no_pending' ? 'no_pending' : 'fetch_failed';
-        return { kind: 'not_sent', cause, ...call, ...detail };
+    if (kind !== 'unsettled')
+        return undefined;
+    let refusal;
+    try {
+        const d = Object.getOwnPropertyDescriptor(r, 'refusal');
+        refusal = d !== undefined && Object.hasOwn(d, 'value') ? d.value : undefined;
     }
-    if (stage === 'input')
-        return { kind: 'not_sent', cause: 'no_input', ...call, ...detail };
-    if (stage === 'card' && pick(outcome, 'editRefused') === true)
-        return { kind: 'not_sent', cause: 'edit_refused', ...call, ...detail };
-    if (stage === 'card')
-        return { kind: 'not_sent', cause: 'card_unavailable', ...call, ...detail };
-    if (stage === 'decide') {
-        const safetyCode = str(pick(outcome, 'safetyCode'));
-        const errorCode = str(pick(outcome, 'errorCode'));
-        const engineAnswered = errorCode !== undefined || pick(outcome, 'currentPending') !== undefined;
-        const cause = safetyCode !== undefined
-            ? 'safety_stop'
-            : pick(outcome, 'retryExhausted') === true
-                ? 'transport_exhausted'
-                : engineAnswered
-                    ? 'engine_refused'
-                    : 'decide_failed';
-        return {
-            kind: 'unsettled',
-            cause,
-            ...call,
-            ...opt('safetyCode', safetyCode),
-            ...opt('errorCode', errorCode),
-            ...detail,
-        };
+    catch {
+        refusal = undefined;
     }
-    if (stage === 'orchestration')
-        return { kind: 'unsettled', cause: 'orchestration', ...call, ...detail };
-    return { kind: 'unsettled', cause: 'unreadable', ...call, ...detail };
+    const parts = [ownStr(refusal, 'errorCode'), ownStr(r, 'detail') ?? ownStr(refusal, 'message')].filter((x) => x !== undefined);
+    return parts.length > 0 ? parts.join(' · ') : undefined;
 }
-function parkingViewOf(v) {
-    const approvalId = str(pick(v, 'approvalId'));
-    if (approvalId === undefined)
-        return undefined;
-    const hint = pick(v, 'retryAfterMs');
-    const retryAfterMs = typeof hint === 'number' && Number.isFinite(hint) && hint >= 0 ? hint : undefined;
-    const decidePath = str(pick(v, 'decidePath'));
-    const message = str(pick(v, 'message'));
-    return {
-        approvalId,
-        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
-        ...(decidePath !== undefined ? { decidePath } : {}),
-        ...(message !== undefined ? { message } : {}),
-    };
+export function unsettledCauseOfReading(reading) {
+    if (reading.standing === 'ambiguous')
+        return 'engine_error';
+    return reading.standing === undefined ? 'no_answer' : 'engine_refused';
 }
-function frameLegResolution(outcome) {
-    if (pick(outcome, 'retracted') === true)
-        return { kind: 'not_sent', cause: 'retracted' };
-    if (pick(outcome, 'editRefused') === true)
-        return { kind: 'not_sent', cause: 'edit_refused' };
-    if (pick(outcome, 'aborted') === true)
-        return { kind: 'unsettled', cause: 'interrupted' };
-    const parking = parkingViewOf(pick(outcome, 'parking'));
-    if (parking !== undefined)
-        return { kind: 'unsettled', cause: 'parking_in_progress', parking };
-    if (pick(outcome, 'decision') === 'unresolved') {
-        const refusal = pick(outcome, 'respondRefusal');
-        return {
-            kind: 'unsettled',
-            cause: 'respond_failed',
-            ...opt('status', num(pick(refusal, 'status'))),
-            ...opt('errorCode', str(pick(refusal, 'errorCode'))),
-            ...opt('detail', str(pick(refusal, 'message'))),
-        };
-    }
-    const ack = pick(outcome, 'ack');
-    return {
-        kind: 'decided',
-        decision: pick(outcome, 'decision'),
-        ...(typeof ack === 'object' && ack !== null ? { ack: ack } : {}),
+export function resolutionOfDecisionFailure(e, m) {
+    const base = {
+        lane: m.lane,
+        ...(m.gatedCallId !== undefined ? { gatedCallId: m.gatedCallId } : {}),
     };
+    const detail = m.detail !== undefined && m.detail.length > 0 ? { detail: m.detail } : {};
+    const { local } = refusalCarrierOf(e);
+    if (local !== undefined && local !== 'binding_mismatch') {
+        if (local === 'no_pending' || local === 'wrong_gate')
+            return { kind: 'not_sent', ...base, cause: local, ...detail };
+        return { kind: 'not_sent', ...base, cause: 'safety_stop', safetyCode: local, ...detail };
+    }
+    const refusal = mintDecisionRefusalReading(e, { route: m.route }, m.attributionCarried);
+    if (local === 'binding_mismatch')
+        return { kind: 'unsettled', ...base, cause: 'engine_refused', safetyCode: 'binding_mismatch', refusal, ...detail };
+    if (thrownIsInstanceOf(e, DecideTransportRetryExhaustedError))
+        return { kind: 'unsettled', ...base, cause: 'transport_exhausted', refusal, ...detail };
+    return { kind: 'unsettled', ...base, cause: unsettledCauseOfReading(refusal), refusal, ...detail };
 }
-export function isApprovalDecided(r) {
-    return typeof r === 'object' && r !== null && r.kind === 'decided';
-}
-export function approvalNotSentCause(r) {
-    if (typeof r !== 'object' || r === null || r.kind !== 'not_sent')
-        return undefined;
-    return r.cause;
-}
-export function approvalUnsettledCause(r) {
-    if (typeof r !== 'object' || r === null || r.kind !== 'unsettled')
-        return undefined;
-    return r.cause;
+export function joinedResolution(r, gatedCallId) {
+    const carry = r.gatedCallId === undefined && gatedCallId !== undefined && gatedCallId !== '' ? { gatedCallId } : {};
+    return { ...r, ...carry, joinedInFlight: true };
 }

package/dist/hitl/approvalsFeed.js

@@ -24,15 +24,6 @@ function readDurablePendingRows(raw) {
         return { kind: 'malformed' };
     return { kind: 'present', rows, dropped };
 }
-function baselineDurableDigestThrows(raw) {
-    try {
-        durableDigestOf(raw);
-        return false;
-    }
-    catch {
-        return true;
-    }
-}
 function durableDigestOf(rows) {
     return rows
         .map(r => [r.sessionId ?? '', r.taskId ?? '', r.toolCallId ?? '', r.boundCallId ?? '', r.boundInputHash ?? '', r.toolName ?? '']
@@ -214,17 +205,11 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             catch {
                 durableRead = { kind: 'malformed' };
             }
-            const badDurable = durableRead.kind === 'malformed' || durableRead.dropped > 0;
-            const escapes = badDurable && baselineDurableDigestThrows(rawPending);
-            if (durableRead.kind === 'malformed' || escapes) {
+            if (durableRead.kind === 'malformed') {
                 hostLog('debug', `approvalsFeed: list() body has an unreadable pending section (${via} leg) — snapshot not committed`);
-                if (!escapes)
-                    stats.listErrors++;
                 noteTakeMissed(via, seq);
                 publishUnknown('unreadable_payload', via, seq);
-                if (escapes)
-                    throw new TypeError('approvalsFeed: unreadable pending section (baseline digest would have thrown)');
-                return;
+                throw new TypeError('approvalsFeed: unreadable pending section');
             }
             rows = durableRead.rows;
             droppedDurable = durableRead.dropped;
@@ -246,7 +231,10 @@ export function startApprovalsFeed(client, onSnapshot, opts) {
             hostLog('debug', `approvalsFeed: dropping stale poll snapshot from leg ${leg} (current ${pollLeg}) — debt untouched`);
             return;
         }
-        noteTakeLooked(seq);
+        if (dropped > 0 || droppedDurable > 0)
+            noteTakeMissed(via, seq);
+        else
+            noteTakeLooked(seq);
         if (seq < lastObservedSeq) {
             hostLog('debug', `approvalsFeed: dropping out-of-order take #${seq} (newest observed #${lastObservedSeq})`);
             return;

package/dist/hitl/askClassPair.d.ts

@@ -1,3 +1,5 @@
+import { CORE_MODE_ARBITRATION } from '../generated/engineFactTables.js';
+export declare const DEPLOYMENT_LIST_ASK_CLASSES: readonly (keyof typeof CORE_MODE_ARBITRATION)[];
 export type AskClassPairReading = {
     readonly state: 'pair';
     readonly askClass: string;

package/dist/hitl/askClassPair.js

@@ -1,3 +1,5 @@
+import { CORE_MODE_ARBITRATION } from '../generated/engineFactTables.js';
+export const DEPLOYMENT_LIST_ASK_CLASSES = Object.freeze(['ask_rule']);
 const ABSENT = Object.freeze({ state: 'absent' });
 const MALFORMED = Object.freeze({ state: 'malformed' });
 export function readAskClassPairState(v) {
@@ -34,8 +36,23 @@ export function readAskClassPairState(v) {
         return MALFORMED;
     if (classes[0] !== askClass)
         return MALFORMED;
+    if (!inCanonicalOrder(classes))
+        return MALFORMED;
     return Object.freeze({ state: 'pair', askClass, classes: Object.freeze(classes) });
 }
+function inCanonicalOrder(classes) {
+    const order = Object.keys(CORE_MODE_ARBITRATION);
+    let last = -1;
+    for (const c of classes) {
+        const rank = order.indexOf(c);
+        if (rank < 0)
+            continue;
+        if (rank <= last)
+            return false;
+        last = rank;
+    }
+    return true;
+}
 export function readAskClassPair(v) {
     const r = readAskClassPairState(v);
     return r.state === 'pair' ? { askClass: r.askClass, classes: r.classes } : undefined;

package/dist/hitl/askGateWire.d.ts

@@ -8,11 +8,29 @@ export type { AskAnsweredOutput } from './gateLedger.js';
 export { SEMA_COLLATERAL_ABORT_KEY } from './gateLedger.js';
 export { SEMA_DENIAL_KIND_KEY } from './gateLedger.js';
 export type { GateDenyAttribution } from './gateLedger.js';
-export { toAnsweredOutput, isAlreadyResolvedFailure, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedFailure, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
 export type { HopBudget, HopRound } from './parkResolver.js';
-export type { GateOutcome, GateFailureCode } from './parkResolver.js';
+export type { GateFailureCode } from './parkResolver.js';
 export { GATE_FAILURE_CODES } from './hitlBridge.js';
 export declare function bridgeAskUserQuestionGates(source: AsyncGenerator<AgentEvent>, deps: AskGateWireDeps, opts?: {
     signal?: AbortSignal;
     taskId?: string;
 }): AsyncGenerator<AgentEvent>;
+export declare const LATE_DECIDE_OUTCOMES: readonly ["accepted-not-resolved", "resumed", "expired-reaped", "settled-elsewhere", "unknown"];
+export type LateDecideOutcome = (typeof LATE_DECIDE_OUTCOMES)[number];
+export interface LateDecideOutcomeReading {
+    readonly kind: LateDecideOutcome;
+    readonly taskId?: string;
+    readonly executed?: 'allowed' | 'denied';
+    readonly probeWorthy?: true;
+}
+export type LateDecideReply = {
+    readonly ok: true;
+    readonly body: object | null | undefined;
+} | {
+    readonly ok: false;
+    readonly error: object | null | undefined;
+};
+export declare function lateDecideOutcomeOf(reply: LateDecideReply, opts?: {
+    readonly lane?: 'decide' | 'respond';
+}): LateDecideOutcomeReading;

package/dist/hitl/askGateWire.js

@@ -4,12 +4,20 @@ import { resolvePark, nextHopBudget, stalledTerminal, MAX_GATE_HOPS } from './pa
 import { createStreamDrainingLegs } from '../streamDrainingLegs.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { hostLog } from '../host.js';
+import { decideAcceptedNotResolved, readDecideReceipt } from '../decideReceipt.js';
+import { APPROVAL_EXPIRED } from '../engineErrorCodes.js';
+import { isNotFoundFailure } from '../wireErrorTriage.js';
+import { readDecisionRefusalAsk } from './decisionRefusal.js';
+import { resumeReopenFromError } from './suspendedReopen.js';
+import { refusedParkFromError, resumeRefusalFromError } from '../resumeRefusalCopy.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
+import { readToolApprovalRespondParking } from './toolApprovalWire.js';
 export { HITL_REJECT_MESSAGE, ENGINE_ABORT_TOOL_RESULT } from './frameRouter.js';
 export { HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE } from './frameRouter.js';
 export { HITL_POLICY_DENY_MESSAGE } from './frameRouter.js';
 export { SEMA_COLLATERAL_ABORT_KEY } from './gateLedger.js';
 export { SEMA_DENIAL_KIND_KEY } from './gateLedger.js';
-export { toAnsweredOutput, isAlreadyResolvedFailure, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedFailure, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
 export { GATE_FAILURE_CODES } from './hitlBridge.js';
 export async function* bridgeAskUserQuestionGates(source, deps, opts) {
     const led = createGateLedger();
@@ -58,6 +66,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
             }
             park = {
                 gate: action.gate,
+                parkFrame: action.parkFrame,
                 ...(action.pendingDone !== undefined ? { pendingDone: action.pendingDone } : {}),
                 ...(action.gatedCallId !== undefined ? { gatedCallId: action.gatedCallId } : {}),
                 ...(action.toolName !== undefined ? { toolName: action.toolName } : {}),
@@ -152,3 +161,43 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
         });
     }
 }
+export const LATE_DECIDE_OUTCOMES = Object.freeze(['accepted-not-resolved', 'resumed', 'expired-reaped', 'settled-elsewhere', 'unknown']);
+const LATE_DECIDE_TASK_ID_MAX = 64;
+export function lateDecideOutcomeOf(reply, opts) {
+    try {
+        if (reply.ok === true) {
+            const body = reply.body;
+            if (guardedRead(() => readToolApprovalRespondParking(body)) !== undefined)
+                return LATE_UNKNOWN;
+            const receipt = guardedRead(() => readDecideReceipt(body));
+            const handoff = receipt?.handoffTaskId;
+            const rawTask = typeof handoff === 'string' && handoff !== '' ? handoff : guardedRead(() => readOwnDataValue(body, 'taskId'));
+            const taskId = typeof rawTask === 'string' && rawTask !== '' ? rawTask.slice(0, LATE_DECIDE_TASK_ID_MAX) : undefined;
+            const replayed = guardedRead(() => readOwnDataValue(body, 'idempotent')) === true;
+            if (opts?.lane === 'respond' && replayed)
+                return Object.freeze({ kind: 'settled-elsewhere' });
+            const kind = opts?.lane === 'respond' && !decideAcceptedNotResolved(receipt) ? 'resumed' : 'accepted-not-resolved';
+            const disposition = receipt?.executionOutcome?.disposition?.kind;
+            const executed = disposition === 'allowed' || disposition === 'denied' ? disposition : undefined;
+            return Object.freeze({ kind, ...(taskId !== undefined ? { taskId } : {}), ...(executed !== undefined ? { executed } : {}) });
+        }
+        const e = reply.error;
+        if (typeof e !== 'object' || e === null)
+            return LATE_UNKNOWN;
+        const code = guardedRead(() => readOwnDataValue(e, 'errorCode'));
+        const status = guardedRead(() => readOwnDataValue(e, 'status'));
+        if (code === APPROVAL_EXPIRED)
+            return Object.freeze({ kind: 'expired-reaped' });
+        if (resumeReopenFromError(e) !== null || resumeRefusalFromError(e)?.waitable === true || refusedParkFromError(e)?.stillPending === true)
+            return LATE_UNKNOWN;
+        const r = readDecisionRefusalAsk(e);
+        if (r.reading !== 'settled' && !(r.reading === 'not_settled' && r.gateMoved))
+            return LATE_UNKNOWN;
+        const probeWorthy = status === 404 || status === 410 || isNotFoundFailure(e) !== false;
+        return Object.freeze(probeWorthy ? { kind: 'settled-elsewhere', probeWorthy: true } : { kind: 'settled-elsewhere' });
+    }
+    catch {
+        return LATE_UNKNOWN;
+    }
+}
+const LATE_UNKNOWN = Object.freeze({ kind: 'unknown' });

package/dist/hitl/askParkRowRouting.d.ts

@@ -27,3 +27,8 @@ export interface RowArmSingleFlight<T> {
     clear: () => void;
 }
 export declare function createRowArmSingleFlight<T>(): RowArmSingleFlight<T>;
+export declare function pendingRowIsOwnedAndDecidable(row: PendingCheckpoint, deps?: ParkOwnershipDeps): boolean;
+export interface OwnedPendingListView {
+    readonly pending?: readonly PendingCheckpoint[] | null;
+}
+export declare function countOwnedPendingRows(listed: OwnedPendingListView | null | undefined, deps?: ParkOwnershipDeps): number;

package/dist/hitl/askParkRowRouting.js

@@ -1,4 +1,4 @@
-import { askParkForeignGateKind } from '../adapter/activeRunSelfHeal.js';
+import { askParkForeignGateKind, durableDecideLegOf } from '../adapter/activeRunSelfHeal.js';
 import { isAskTool } from './frameRouter.js';
 import { approvalCallKey } from './gateIdentity.js';
 import { askQuestionsFromPending, pendingRowIsOwnedByThisSession } from './parkOwnership.js';
@@ -108,3 +108,34 @@ export function createRowArmSingleFlight() {
         },
     };
 }
+export function pendingRowIsOwnedAndDecidable(row, deps) {
+    if (typeof row !== 'object' || row === null)
+        throw new TypeError('pending row is not an object — ownership cannot be judged');
+    if (!pendingRowIsOwnedByThisSession(row, deps))
+        return false;
+    void row.gateKind;
+    const leg = durableDecideLegOf(row);
+    if (leg === 'plan_review')
+        return true;
+    if (leg !== 'approval' && leg !== 'absent')
+        return false;
+    return askParkRowArm(row) === 'question' ? askQuestionsFromPending(row) !== null : true;
+}
+export function countOwnedPendingRows(listed, deps) {
+    if (typeof listed !== 'object' || listed === null || Array.isArray(listed)) {
+        throw new Error('approvals.list answered without a readable body — the owned pending count is unknown');
+    }
+    const pending = listed?.pending;
+    if (!Array.isArray(pending)) {
+        throw new Error('approvals.list answered without a readable `pending` array — the owned pending count is unknown');
+    }
+    let n = 0;
+    for (const row of pending) {
+        if (typeof row !== 'object' || row === null) {
+            throw new Error('approvals.list answered with a pending row that is not an object — the owned pending count is unknown');
+        }
+        if (pendingRowIsOwnedAndDecidable(row, deps))
+            n++;
+    }
+    return n;
+}

package/dist/hitl/askSettlementLine.d.ts

@@ -0,0 +1,28 @@
+import type { UiLanguage } from '../env/uiLanguage.js';
+export declare function askEndingCauseClause(cause: string | undefined, lang?: UiLanguage): string | undefined;
+export interface AskSettlementInput {
+    readonly cause?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly parked?: boolean | undefined;
+}
+export declare function askSettlementLine(settled: AskSettlementInput, lang?: UiLanguage): string | undefined;
+export type AskAcceptedFollow = 'following' | 'already-following' | 'not-following';
+export interface AskAcceptedInput {
+    readonly decision?: string | undefined;
+    readonly taskId?: string | undefined;
+    readonly late?: boolean | undefined;
+    readonly follow?: AskAcceptedFollow | undefined;
+    readonly executed?: string | undefined;
+}
+export declare function askAcceptedLine(accepted: AskAcceptedInput, lang?: UiLanguage): string;
+export type AskParkedCardForm = 'approval' | 'question' | 'queue_no_deadline';
+export declare function askParkedCardNote(form?: string | undefined, toolName?: string | undefined, lang?: UiLanguage): string;
+export interface AskHumanSettledInput {
+    readonly kind?: string | undefined;
+    readonly decision?: string | undefined;
+    readonly taskId?: string | undefined;
+    readonly late?: boolean | undefined;
+    readonly follow?: AskAcceptedFollow | undefined;
+    readonly executed?: string | undefined;
+}
+export declare function askHumanSettlementLine(settled: AskHumanSettledInput, lang?: UiLanguage): string | undefined;

package/dist/hitl/askSettlementLine.js

@@ -0,0 +1,99 @@
+import { displayUntrusted, quoteUntrustedForSentence } from '../displayUntrusted.js';
+import { msg, renderMessage } from '../i18n/translate.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
+const ENDING_CAUSE_KEYS = Object.freeze({
+    routing_failure_fail_closed: 'approval.settle.cause.routingFailureFailClosed',
+    run_cancelled: 'approval.settle.cause.runCancelled',
+    run_exited: 'approval.settle.cause.runExited',
+    batch_aborted: 'approval.settle.cause.batchAborted',
+    batch_sibling_withdrawn: 'approval.settle.cause.batchSiblingWithdrawn',
+    batch_bound_elsewhere: 'approval.settle.cause.batchBoundElsewhere',
+    adhoc_leg_no_durable_domain: 'approval.settle.cause.adhocLegNoDurableDomain',
+    orphan_ttl_exceeded: 'approval.settle.cause.orphanTtlExceeded',
+    crashed_before_park: 'approval.settle.cause.crashedBeforePark',
+    shutdown_before_park: 'approval.settle.cause.shutdownBeforePark',
+    ttl_expired: 'approval.settle.cause.ttlExpired',
+    broadcast_lost: 'approval.settle.cause.broadcastLost',
+    stream_disconnected: 'approval.settle.cause.streamDisconnected',
+    undeliverable: 'approval.settle.cause.undeliverable',
+});
+function endingCauseKeyOf(cause) {
+    return typeof cause === 'string' && Object.hasOwn(ENDING_CAUSE_KEYS, cause) ? ENDING_CAUSE_KEYS[cause] : undefined;
+}
+export function askEndingCauseClause(cause, lang) {
+    const key = endingCauseKeyOf(cause);
+    return key !== undefined ? renderMessage(msg(key), lang) : undefined;
+}
+function ownSlot(o, key) {
+    if (typeof o !== 'object' || o === null)
+        return undefined;
+    return guardedRead(() => readOwnDataValue(o, key));
+}
+function subjectOf(toolName, named, generic) {
+    const quoted = typeof toolName === 'string' ? guardedRead(() => quoteUntrustedForSentence(toolName, 80)) : undefined;
+    return quoted === undefined ? msg(generic) : msg(named, { tool: quoted });
+}
+export function askSettlementLine(settled, lang) {
+    if (ownSlot(settled, 'parked') === true)
+        return undefined;
+    const cause = ownSlot(settled, 'cause');
+    if (typeof cause !== 'string' || cause === '')
+        return undefined;
+    const subject = subjectOf(ownSlot(settled, 'toolName'), 'approval.settle.subject.named', 'approval.settle.subject.generic');
+    const clauseKey = endingCauseKeyOf(cause);
+    return renderMessage(clauseKey !== undefined ? msg('approval.settle.endedKnown', { subject, clause: msg(clauseKey) }) : msg('approval.settle.endedUnknown', { subject }), lang);
+}
+const TASK_ID_MAX = 64;
+const EXECUTED_TAIL_KEYS = Object.freeze({
+    allowed: 'approval.settle.executed.allowed',
+    denied: 'approval.settle.executed.denied',
+});
+const FOLLOW_CLAUSE_KEYS = Object.freeze({
+    following: 'approval.settle.follow.following',
+    'already-following': 'approval.settle.follow.alreadyFollowing',
+});
+export function askAcceptedLine(accepted, lang) {
+    const decision = ownSlot(accepted, 'decision');
+    const what = msg(decision === 'approve' ? 'approval.settle.what.approved' : decision === 'deny' ? 'approval.settle.what.denied' : 'approval.settle.what.answered');
+    const late = ownSlot(accepted, 'late') === false ? '' : msg('approval.settle.late');
+    const rawTask = ownSlot(accepted, 'taskId');
+    const shownTask = typeof rawTask === 'string' ? guardedRead(() => displayUntrusted(rawTask, { max: TASK_ID_MAX, blanks: true })) : undefined;
+    const where = shownTask === undefined || shownTask === '' ? '' : msg('approval.settle.where', { task: shownTask });
+    const follow = ownSlot(accepted, 'follow');
+    const executed = ownSlot(accepted, 'executed');
+    const tail = executed === 'allowed' || executed === 'denied' ? msg(EXECUTED_TAIL_KEYS[executed]) : '';
+    if (follow === 'following' || follow === 'already-following') {
+        return renderMessage(msg('approval.settle.acceptedFollowing', { what, late, where, follow: msg(FOLLOW_CLAUSE_KEYS[follow]), tail }), lang);
+    }
+    return renderMessage(msg('approval.settle.acceptedNotFollowing', { what, late, where, tail }), lang);
+}
+const PARKED_CARD_NOTE_KEYS = Object.freeze({
+    approval: 'approval.settle.parkedNote.approval',
+    question: 'approval.settle.parkedNote.question',
+    queue_no_deadline: 'approval.settle.parkedNote.queueNoDeadline',
+});
+export function askParkedCardNote(form, toolName, lang) {
+    const key = form === 'question' || form === 'queue_no_deadline' ? form : 'approval';
+    if (key !== 'queue_no_deadline')
+        return renderMessage(msg(PARKED_CARD_NOTE_KEYS[key]), lang);
+    return renderMessage(msg(PARKED_CARD_NOTE_KEYS[key], { subject: subjectOf(toolName, 'approval.settle.parkedSubject.named', 'approval.settle.parkedSubject.generic') }), lang);
+}
+export function askHumanSettlementLine(settled, lang) {
+    const kind = ownSlot(settled, 'kind');
+    if (kind === 'accepted-not-resolved')
+        return askAcceptedLine(settled, lang);
+    if (kind === 'expired-reaped')
+        return renderMessage(msg('approval.settleHuman.expiredReaped'), lang);
+    if (kind === 'settled-elsewhere')
+        return renderMessage(msg('approval.settleHuman.settledElsewhere'), lang);
+    if (kind !== 'resumed')
+        return undefined;
+    const decision = ownSlot(settled, 'decision');
+    const what = msg(decision === 'approve' ? 'approval.settle.what.approved' : decision === 'deny' ? 'approval.settle.what.denied' : 'approval.settle.what.answered');
+    const rawTask = ownSlot(settled, 'taskId');
+    const shownTask = typeof rawTask === 'string' ? guardedRead(() => displayUntrusted(rawTask, { max: TASK_ID_MAX, blanks: true })) : undefined;
+    const where = shownTask === undefined || shownTask === '' ? '' : msg('approval.settle.where', { task: shownTask });
+    const executed = ownSlot(settled, 'executed');
+    const tail = executed === 'allowed' || executed === 'denied' ? msg(EXECUTED_TAIL_KEYS[executed]) : '';
+    return renderMessage(msg(ownSlot(settled, 'late') === false ? 'approval.settleHuman.resumed' : 'approval.settleHuman.resumedLate', { what, where, tail }), lang);
+}

package/dist/hitl/automaticAnswerVerdict.d.ts

@@ -1,5 +1,6 @@
 import { type CoreModeArbitrationRow } from '../generated/engineFactTables.js';
 import { CORE_ASK_FACES } from '../generated/engineAskFaceTables.js';
+import type { UiLanguage } from '../env/uiLanguage.js';
 export type AutomaticAnswerLane = 'mode_posture' | 'standing_rule' | 'permission_request_hook';
 export type AutomaticAnswerAskFace = (typeof CORE_ASK_FACES)[number];
 export interface AutomaticAnswerFacts {
@@ -19,9 +20,9 @@ export type AutomaticAnswerVerdict = {
     readonly kind: 'unknown';
     readonly why: AutomaticAnswerUnknownWhy;
 };
-export declare const MODE_ARBITRATION: Readonly<Record<"hook" | "write_protection" | "mode" | "rule_unreadable" | "target_unresolved" | "content_question" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "org_rule" | "governance_unavailable" | "ask_rule" | "denial_limit_fallback" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", CoreModeArbitrationRow>>;
+export declare const MODE_ARBITRATION: Readonly<Record<"hook" | "write_protection" | "mode" | "target_unresolved" | "content_question" | "ancestor" | "dangerous_delete" | "unverifiable_delete" | "unverifiable_shell_text" | "transcript_write" | "org_rule" | "rule_unreadable" | "ask_rule" | "denial_limit_fallback" | "classifier_no_ruling" | "requires_user_interaction" | "operator_forced" | "shell_floor" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", CoreModeArbitrationRow>>;
 export declare function foldModeArbitrationRow(classes: Iterable<string>, askFace?: AutomaticAnswerAskFace): CoreModeArbitrationRow;
 export declare function automaticAnswerVerdict(card: object | null | undefined, lane: AutomaticAnswerLane, facts?: AutomaticAnswerFacts | null): AutomaticAnswerVerdict;
-export declare function mandatedApprovalDetailOf(card: object | null | undefined): string;
+export declare function mandatedApprovalDetailOf(card: object | null | undefined, lang?: UiLanguage): string;
 export type PermissionRequestHookScope = 'allow_or_deny' | 'deny_only' | 'skip';
 export declare function permissionRequestHookScope(verdict: AutomaticAnswerVerdict | null | undefined): PermissionRequestHookScope;