@sema-agent/client-core 0.97.1 → 0.98.0

package/dist/hitl/askGateWire.js

@@ -4,12 +4,19 @@ 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 { 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 +65,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 +160,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 || (typeof code === 'string' && code.startsWith('not_found.'));
+        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,18 @@
+export declare function askEndingCauseClause(cause: string | undefined): string | undefined;
+export interface AskSettlementInput {
+    readonly cause?: string | undefined;
+    readonly toolName?: string | undefined;
+    readonly parked?: boolean | undefined;
+}
+export declare function askSettlementLine(settled: AskSettlementInput): 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): string;
+export type AskParkedCardForm = 'approval' | 'question' | 'queue_no_deadline';
+export declare function askParkedCardNote(form?: string | undefined, toolName?: string | undefined): string;

package/dist/hitl/askSettlementLine.js

@@ -0,0 +1,79 @@
+import { displayUntrusted, quoteUntrustedForSentence } from '../displayUntrusted.js';
+import { guardedRead, readOwnDataValue } from '../ownKey.js';
+const ENDING_CAUSE_CLAUSES = Object.freeze({
+    routing_failure_fail_closed: 'the engine could not route it to anywhere that can answer it, so it closed it',
+    run_cancelled: 'the run that asked for it was cancelled',
+    run_exited: 'the run that asked for it exited before anyone answered',
+    batch_aborted: 'the batch of tool calls it belonged to was aborted',
+    batch_sibling_withdrawn: 'another approval in the same batch was refused or withdrawn, which withdrew this one too',
+    batch_bound_elsewhere: 'the decision for its batch was bound to a different approval',
+    adhoc_leg_no_durable_domain: 'this kind of request cannot be kept waiting for an answer on this deployment',
+    orphan_ttl_exceeded: "it was left without an owner past the engine's time limit",
+    crashed_before_park: 'the engine process stopped before it could keep the request waiting',
+    shutdown_before_park: 'the engine shut down before it could keep the request waiting',
+    ttl_expired: 'nobody answered within the approval window',
+    broadcast_lost: 'it never reached any open connection',
+    stream_disconnected: 'the connection carrying this card dropped',
+    undeliverable: 'it could not be delivered to any approval surface',
+});
+export function askEndingCauseClause(cause) {
+    return typeof cause === 'string' && Object.hasOwn(ENDING_CAUSE_CLAUSES, cause) ? ENDING_CAUSE_CLAUSES[cause] : undefined;
+}
+function ownSlot(o, key) {
+    if (typeof o !== 'object' || o === null)
+        return undefined;
+    return guardedRead(() => readOwnDataValue(o, key));
+}
+function subjectOf(toolName, named, fallback) {
+    const quoted = typeof toolName === 'string' ? guardedRead(() => quoteUntrustedForSentence(toolName, 80)) : undefined;
+    return quoted === undefined ? fallback : named(quoted);
+}
+const SETTLEMENT_TAIL = ' Nothing was approved from this card; if the step is still needed, ask for it again.';
+export function askSettlementLine(settled) {
+    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'), (q) => `the approval request for ${q}`, 'this approval request');
+    const clause = askEndingCauseClause(cause);
+    const why = clause !== undefined ? `: ${clause}` : " (the engine's reason is one this build does not know yet)";
+    return `${subject} ended on the engine without an answer${why}.${SETTLEMENT_TAIL}`;
+}
+const TASK_ID_MAX = 64;
+const EXECUTED_TAILS = Object.freeze({
+    allowed: ' The engine also reports that the already-decided step was ALLOWED when it ran.',
+    denied: ' The engine also reports that the already-decided step was DENIED at execution time (a deployment review can overturn an approval after the fact).',
+});
+const FOLLOW_CLAUSES = Object.freeze({
+    following: 'sema is following that run here',
+    'already-following': 'this screen is already following that run',
+});
+export function askAcceptedLine(accepted) {
+    const decision = ownSlot(accepted, 'decision');
+    const what = decision === 'approve' ? 'approved' : decision === 'deny' ? 'denied' : 'answered';
+    const late = ownSlot(accepted, 'late') === false ? '' : ' 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 === '' ? '' : ` (task ${shownTask})`;
+    const follow = ownSlot(accepted, 'follow');
+    const executed = ownSlot(accepted, 'executed');
+    const tail = executed === 'allowed' || executed === 'denied' ? EXECUTED_TAILS[executed] : '';
+    if (follow === 'following' || follow === 'already-following') {
+        return `${what}${late} — the engine took this decision${where}; ${FOLLOW_CLAUSES[follow]}, so what it does next shows up below.${tail}`;
+    }
+    return (`${what}${late} — the engine took this decision${where}. Whether the parked call has resumed yet is not something this reply can say; ` +
+        `this screen is not following that run, so what it does next will not show up here by itself.${tail}`);
+}
+const PARKED_CARD_NOTES = Object.freeze({
+    approval: "This step was already parked in the engine's durable queue and waiting for a decision before this card went up. Yes approves it now and lets the step run late; No abandons the step — the model gets a refusal and can take another route.",
+    question: "This step was already parked in the engine's durable queue and waiting for a decision before this card went up. Answering now sends your decision late and lets the parked step continue with it; closing this card without answering abandons the step — the model gets a refusal and can take another route.",
+    queue_no_deadline: "{subject} is in the engine's durable queue (no deadline was reported for it). It waits for your decision — nothing has been decided on your behalf.",
+});
+export function askParkedCardNote(form, toolName) {
+    const key = form === 'question' || form === 'queue_no_deadline' ? form : 'approval';
+    const template = PARKED_CARD_NOTES[key];
+    if (key !== 'queue_no_deadline')
+        return template;
+    return template.split('{subject}').join(subjectOf(toolName, (q) => `the approval for ${q}`, 'this approval'));
+}

package/dist/hitl/automaticAnswerVerdict.d.ts

@@ -19,7 +19,7 @@ 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;

package/dist/hitl/automaticAnswerVerdict.js

@@ -3,18 +3,20 @@ import { CORE_RELEASABLE_ASK_CLASSES_BY_FACE, CORE_SHELL_FACE_TOOL_NAMES } from
 import { mandatedApprovalDetail } from '../gateVocabulary.js';
 import { readAskOrigin, readOwnNonEmptyString } from '../ownKey.js';
 import { readAskClassPairState } from './askClassPair.js';
-import { approvalAllowRuleShadowed } from './allowRuleShadow.js';
+import { readRequiresRealApproval } from './approvalCardReading.js';
+import { approvalAllowRuleShadowed, retiredAllowRuleShadowKeyPresent } from './allowRuleShadow.js';
 import { approvalIsMandated, readApprovalMandate } from './toolApprovalWire.js';
 export const MODE_ARBITRATION = CORE_MODE_ARBITRATION;
 const TABLE = CORE_MODE_ARBITRATION;
 const ORIGIN_IMPLIES_CLASS = Object.freeze({
     content_question: 'content_question',
-    org_unavailable: 'governance_unavailable',
+    org_unavailable: 'rule_unreadable',
     org_rule: 'org_rule',
     hook: 'hook',
     ask_rule: 'ask_rule',
     denial_limit_fallback: 'denial_limit_fallback',
 });
+const RULE_LANE_COULD_CLEAR = 'lane_cannot_speak';
 function mandateWordClass(raw) {
     if (raw === 'operator_always')
         return 'shell_floor';
@@ -102,6 +104,17 @@ export function automaticAnswerVerdict(card, lane, facts) {
     try {
         if (typeof card !== 'object' || card === null)
             return UNKNOWN.card_unreadable;
+        if (card.cardPayloadUnreadable === true)
+            return UNKNOWN.card_unreadable;
+        const unreadable = card.unreadableEvidence;
+        if (unreadable !== undefined) {
+            if (!Array.isArray(unreadable) || unreadable.some((k) => typeof k !== 'string'))
+                return UNKNOWN.card_unreadable;
+            if (unreadable.some((k) => k !== 'rememberRefused' && k !== 'ruleOffers'))
+                return UNKNOWN.card_unreadable;
+        }
+        if (!approvalAllowRuleShadowed(card) && retiredAllowRuleShadowKeyPresent(card, 'frame'))
+            return UNKNOWN.card_unreadable;
         const face = lane === 'mode_posture' ? askFaceOfCard(card) : undefined;
         const origin = readAskOrigin(evidenceView(card, 'origin'));
         if (origin !== undefined && Object.hasOwn(ORIGIN_IMPLIES_CLASS, origin)) {
@@ -109,7 +122,7 @@ export function automaticAnswerVerdict(card, lane, facts) {
             if (classBlocks(lane, cls, face))
                 return mustAsk('origin', { origin, askClass: cls });
         }
-        if (lane !== 'mode_posture' && evidenceView(card, 'requiresRealApproval').requiresRealApproval === true)
+        if (lane !== 'mode_posture' && readRequiresRealApproval(card))
             return mustAsk('requires_real_approval');
         if (evidenceView(card, 'governanceForced').governanceForced === true)
             return mustAsk('governance');
@@ -123,8 +136,11 @@ export function automaticAnswerVerdict(card, lane, facts) {
             const mandateView = evidenceView(card, 'mandated', 'ruleOffersAbsence', 'mandate');
             if (approvalIsMandated(mandateView))
                 return mustAsk('mandated');
-            if (lane === 'standing_rule' && (approvalAllowRuleShadowed(card) || readOwnNonEmptyString(mandateView, 'ruleOffersAbsence') === 'shadowed'))
-                return mustAsk('allow_rule_shadow');
+            if (lane === 'standing_rule') {
+                const absence = readOwnNonEmptyString(mandateView, 'ruleOffersAbsence');
+                if (approvalAllowRuleShadowed(card) || (absence !== undefined && absence !== RULE_LANE_COULD_CLEAR))
+                    return mustAsk('allow_rule_shadow');
+            }
         }
         const pair = readAskClassPairState(card);
         if (pair.state === 'malformed')

package/dist/hitl/crashConverged.d.ts

@@ -1,31 +1,18 @@
-import type { PendingCheckpoint } from '@sema-agent/sdk';
+import type { CrashConvergedRow, PendingCheckpoint } from '@sema-agent/sdk';
 export type CrashConvergedOrphanState = 'pending' | 'decided';
-export interface CrashConvergedRow {
-    readonly approvalId: string;
-    readonly toolName: string;
-    readonly taskId: string;
-    readonly sessionId?: string;
-    readonly ts: number;
-    readonly expiresAtMs: number;
-    readonly decision: 'denied';
-    readonly cause: 'crashed_before_park' | 'shutdown_before_park';
-    readonly orphanState: CrashConvergedOrphanState;
-    readonly originalDecision?: 'approve';
-    readonly decidedAtMs?: number;
-    readonly convergedAtMs: number;
-    readonly resumeSafe: boolean;
+export interface CrashConvergedRowReading extends Readonly<CrashConvergedRow> {
     readonly needsHumanReason?: 'approved_then_interrupted' | 'pending_unsafe' | 'unstable_row' | 'contradictory';
 }
-export declare const isCrashConvergedCause: (v: unknown) => v is CrashConvergedRow["cause"];
+export declare const isCrashConvergedCause: (v: unknown) => v is CrashConvergedRowReading["cause"];
 export interface ApprovalsListEnvelope {
     pending: PendingCheckpoint[];
     livePending?: unknown[];
-    crashConverged?: CrashConvergedRow[];
+    crashConverged?: CrashConvergedRowReading[];
 }
 export interface CrashConvergedProjection {
     readonly total: number;
-    readonly resumeSafe: readonly CrashConvergedRow[];
-    readonly needsHuman: readonly CrashConvergedRow[];
+    readonly resumeSafe: readonly CrashConvergedRowReading[];
+    readonly needsHuman: readonly CrashConvergedRowReading[];
     readonly dropped: number;
 }
 export declare function projectCrashConverged(env: unknown): CrashConvergedProjection | undefined;
@@ -33,6 +20,10 @@ export interface CrashConvergedNoticeFacts {
     readonly total: number;
     readonly dropped: number;
     readonly needsHumanReasons: readonly (string | undefined)[];
-    readonly causes: readonly CrashConvergedRow['cause'][] | undefined;
+    readonly causes: readonly CrashConvergedRowReading['cause'][] | undefined;
 }
+export declare function crashConvergedRowInProjection(projection: CrashConvergedProjection | undefined, row: Pick<CrashConvergedRowReading, 'approvalId'>): {
+    readonly bucket: 'resumeSafe' | 'needsHuman';
+    readonly row: CrashConvergedRowReading;
+} | undefined;
 export declare function readCrashConvergedNoticeFacts(projection: CrashConvergedProjection | undefined): CrashConvergedNoticeFacts | undefined;

package/dist/hitl/crashConverged.js

@@ -168,6 +168,62 @@ function causeWordsOf(rows) {
     }
     return seen;
 }
+function rowRecordsAgreeUnexecuted(row) {
+    try {
+        if (typeof row !== 'object' || row === null)
+            return false;
+        const own = (k) => Object.getOwnPropertyDescriptor(row, k);
+        const valueIs = (k, want) => {
+            const d = own(k);
+            return d !== undefined && Object.hasOwn(d, 'value') && d.value === want;
+        };
+        const noValue = (k) => {
+            const d = own(k);
+            return d === undefined || (Object.hasOwn(d, 'value') && d.value === undefined);
+        };
+        return valueIs('orphanState', 'pending') && valueIs('resumeSafe', true) && noValue('originalDecision') && noValue('decidedAtMs');
+    }
+    catch {
+        return false;
+    }
+}
+export function crashConvergedRowInProjection(projection, row) {
+    try {
+        if (typeof row !== 'object' || row === null)
+            return undefined;
+        const id = ownDataValue(row, 'approvalId');
+        if (typeof id !== 'string' || id === '')
+            return undefined;
+        if (typeof projection !== 'object' || projection === null)
+            return undefined;
+        const total = ownDataValue(projection, 'total');
+        if (!isCount(total) || total > MAX_CRASH_CONVERGED_ROWS)
+            return undefined;
+        const safe = bucketRowsOf(ownDataValue(projection, 'resumeSafe'));
+        const human = bucketRowsOf(ownDataValue(projection, 'needsHuman'));
+        if (safe === undefined || human === undefined || safe.length + human.length !== total)
+            return undefined;
+        const find = (rows) => {
+            for (const r of rows) {
+                if (typeof r === 'object' && r !== null && ownDataValue(r, 'approvalId') === id)
+                    return r;
+            }
+            return undefined;
+        };
+        const inSafe = find(safe);
+        const inHuman = find(human);
+        if (inSafe !== undefined && inHuman !== undefined)
+            return undefined;
+        if (inSafe !== undefined)
+            return rowRecordsAgreeUnexecuted(inSafe) ? { bucket: 'resumeSafe', row: inSafe } : undefined;
+        if (inHuman !== undefined)
+            return { bucket: 'needsHuman', row: inHuman };
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function readCrashConvergedNoticeFacts(projection) {
     try {
         if (typeof projection !== 'object' || projection === null)

package/dist/hitl/crashConvergedNotice.d.ts

@@ -1,4 +1,6 @@
-import type { CrashConvergedProjection } from './crashConverged.js';
+import type { CrashConvergedProjection, CrashConvergedRowReading } from './crashConverged.js';
 export declare const NEEDS_HUMAN_REASON_ORDER: readonly ["approved_then_interrupted", "pending_unsafe", "contradictory", "unstable_row"];
 export declare function crashConvergedNeedsHumanSentence(reason: string | undefined, n: number, total: number): string | undefined;
 export declare function crashConvergedNotice(projection: CrashConvergedProjection | undefined): string | undefined;
+export declare function crashConvergedRowSentence(projection: CrashConvergedProjection | undefined, row: Pick<CrashConvergedRowReading, 'approvalId'>): string | undefined;
+export declare function crashConvergedCauseSentence(cause: string | undefined): string | undefined;

package/dist/hitl/crashConvergedNotice.js

@@ -1,4 +1,5 @@
-import { readCrashConvergedNoticeFacts } from './crashConverged.js';
+import { askEndingCauseClause } from './askSettlementLine.js';
+import { crashConvergedRowInProjection, isCrashConvergedCause, readCrashConvergedNoticeFacts } from './crashConverged.js';
 export const NEEDS_HUMAN_REASON_ORDER = Object.freeze(['approved_then_interrupted', 'pending_unsafe', 'contradictory', 'unstable_row']);
 const _orderCoversReasons = true;
 const _orderInsideReasons = true;
@@ -9,14 +10,28 @@ void _orderHasNoDuplicate;
 const RECORDED = 'based on what was recorded';
 const NO_AUTO_RERUN = 'sema has not re-run anything';
 const plural = (n, one, many) => (n === 1 ? one : many);
-const SENTENCE = Object.freeze({
-    approved_then_interrupted: (n, total) => `${n} of ${total} had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed`,
-    pending_unsafe: (n, total) => `${n} of ${total} had not started, ${RECORDED}, but the engine did not mark ${plural(n, 'it', 'them')} as safe to re-run`,
-    contradictory: (n, total) => `${n} of ${total} ${plural(n, 'has a contradictory record', 'have contradictory records')}`,
-    unstable_row: (n, total) => `${n} of ${total} ${plural(n, 'has a record that read differently each time it was read', 'have records that read differently each time they were read')}`,
+const NEEDS_HUMAN_CLAUSES = Object.freeze({
+    approved_then_interrupted: {
+        one: 'had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed',
+        many: 'had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed',
+    },
+    pending_unsafe: {
+        one: `had not started, ${RECORDED}, but the engine did not mark it as safe to re-run`,
+        many: `had not started, ${RECORDED}, but the engine did not mark them as safe to re-run`,
+    },
+    contradictory: { one: 'has a contradictory record', many: 'have contradictory records' },
+    unstable_row: {
+        one: 'has a record that read differently each time it was read',
+        many: 'have records that read differently each time they were read',
+    },
 });
-const fallbackSentence = (n, total) => `${n} of ${total} had already been approved, or cannot be accounted for, so a side effect may have partly landed`;
-const isNeedsHumanReason = (v) => typeof v === 'string' && Object.hasOwn(SENTENCE, v);
+const FALLBACK_CLAUSE = Object.freeze({
+    one: 'had already been approved, or cannot be accounted for, so a side effect may have partly landed',
+    many: 'had already been approved, or cannot be accounted for, so a side effect may have partly landed',
+});
+const RESUME_SAFE_CLAUSE = `had not started, ${RECORDED}, and can be re-run`;
+const countedClause = (clause, n, total) => `${n} of ${total} ${n === 1 ? clause.one : clause.many}`;
+const isNeedsHumanReason = (v) => typeof v === 'string' && Object.hasOwn(NEEDS_HUMAN_CLAUSES, v);
 export function crashConvergedNeedsHumanSentence(reason, n, total) {
     if (!isNeedsHumanReason(reason))
         return undefined;
@@ -24,18 +39,18 @@ export function crashConvergedNeedsHumanSentence(reason, n, total) {
         return undefined;
     if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < n)
         return undefined;
-    return SENTENCE[reason](n, total);
+    return countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total);
 }
 function needsHumanClauses(reasons, total) {
     const clauses = [];
     for (const reason of NEEDS_HUMAN_REASON_ORDER) {
         const n = reasons.filter((r) => r === reason).length;
         if (n > 0)
-            clauses.push(SENTENCE[reason](n, total));
+            clauses.push(countedClause(NEEDS_HUMAN_CLAUSES[reason], n, total));
     }
     const fallback = reasons.filter((r) => !isNeedsHumanReason(r)).length;
     if (fallback > 0)
-        clauses.push(fallbackSentence(fallback, total));
+        clauses.push(countedClause(FALLBACK_CLAUSE, fallback, total));
     return `${clauses.join('; ')} — check ${plural(reasons.length, 'it', 'them')} by hand before re-running`;
 }
 export function crashConvergedNotice(projection) {
@@ -55,3 +70,25 @@ export function crashConvergedNotice(projection) {
     const droppedClause = dropped > 0 ? ` (${dropped} further ${plural(dropped, 'record', 'records')} could not be read.)` : '';
     return `${head}; ${body}. ${NO_AUTO_RERUN}.${droppedClause}`;
 }
+export function crashConvergedRowSentence(projection, row) {
+    const hit = crashConvergedRowInProjection(projection, row);
+    if (hit === undefined)
+        return undefined;
+    let descriptor;
+    try {
+        descriptor = Object.getOwnPropertyDescriptor(hit.row, 'needsHumanReason');
+    }
+    catch {
+        return undefined;
+    }
+    if (hit.bucket === 'resumeSafe')
+        return descriptor === undefined ? RESUME_SAFE_CLAUSE : undefined;
+    const reason = descriptor !== undefined && Object.hasOwn(descriptor, 'value') ? descriptor.value : undefined;
+    return (isNeedsHumanReason(reason) ? NEEDS_HUMAN_CLAUSES[reason] : FALLBACK_CLAUSE).one;
+}
+export function crashConvergedCauseSentence(cause) {
+    if (typeof cause !== 'string' || cause === '')
+        return undefined;
+    const clause = isCrashConvergedCause(cause) ? askEndingCauseClause(cause) : undefined;
+    return clause === undefined ? 'the decision converged automatically' : `${clause}, and the decision converged automatically`;
+}

package/dist/hitl/decisionConflict.js

@@ -1,29 +1,22 @@
 import { APPROVAL_BINDING_MISMATCH, CHECKPOINT_UNSUPPORTED_VERSION, RESUME_OUTCOME_INVALID } from '../engineErrorCodes.js';
 import { ownDataField } from '../ownKey.js';
-import { readRefusalField } from '../wireFailureShape.js';
+import { PROTOCOL_ERROR_NAME, protocolErrorNameOf, readRefusalField } from '../wireFailureShape.js';
 const BINDING_SEAT_FIELDS = new Set(['boundCallId', 'boundInputHash']);
 const ANSWER_FIELD = 'answer';
-const BINDING_MISMATCH_ERROR_NAME = 'ApprovalBindingMismatchError';
 export function decisionConflictOf(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
     let code;
-    let name;
     try {
         code = ownDataField(err, 'errorCode');
     }
     catch {
         return undefined;
     }
-    try {
-        name = ownDataField(err, 'name');
-    }
-    catch {
-        name = undefined;
-    }
+    const protocolName = protocolErrorNameOf(err);
     if (code === CHECKPOINT_UNSUPPORTED_VERSION)
         return 'format_version';
-    const bindingFamily = code === APPROVAL_BINDING_MISMATCH || (code === undefined && name === BINDING_MISMATCH_ERROR_NAME);
+    const bindingFamily = code === APPROVAL_BINDING_MISMATCH || (code === undefined && protocolName === PROTOCOL_ERROR_NAME.ApprovalBindingMismatchError);
     if (!bindingFamily && code !== RESUME_OUTCOME_INVALID)
         return undefined;
     let field;

package/dist/hitl/decisionRefusal.d.ts

@@ -1,6 +1,23 @@
+import { type GateCurrentPending, type HitlSafetyCode } from './hitlBridge.js';
 import { type DecisionRefusalConflict } from './decisionConflict.js';
+import { type ProtocolErrorName } from '../wireFailureShape.js';
+import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 export type DecisionRefusalStanding = 'settled-elsewhere' | 'ambiguous' | 'refused-pending';
 export type { DecisionRefusalConflict } from './decisionConflict.js';
+export interface RefusalCarrier {
+    readonly local?: HitlSafetyCode;
+    readonly carrier: {} | null | undefined;
+}
+export declare function refusalCarrierOf(err: {} | null | undefined): RefusalCarrier;
+export interface RefusalRouteContext {
+    readonly route?: 'approval_decide' | 'live_respond' | 'ask_decide' | 'plan_review' | 'compact';
+}
+export interface RefusalDelivery {
+    readonly delivery: 'refused' | 'ambiguous' | 'no_answer';
+    readonly status?: number;
+    readonly errorCode?: string;
+}
+export declare function refusalDeliveryOf(err: {} | null | undefined, context?: RefusalRouteContext): RefusalDelivery;
 export declare function decisionRefusalSaysAskGone(err: unknown): boolean;
 export type DecisionRefusalAskReading = 'settled' | 'not_settled' | 'unreadable';
 interface DecisionRefusalAskFacts {
@@ -10,6 +27,28 @@ interface DecisionRefusalAskFacts {
 }
 export declare function readDecisionRefusalAsk(failure: unknown): DecisionRefusalAskFacts;
 export declare function decisionRefusalAskReading(failure: unknown): DecisionRefusalAskReading;
+export interface DecisionRefusalReading {
+    readonly status?: number;
+    readonly errorCode?: string;
+    readonly message?: string;
+    readonly retriable?: true;
+    readonly protocolName?: ProtocolErrorName;
+    readonly extra?: {
+        readonly cause?: string;
+        readonly field?: string;
+    };
+    readonly blockedBy?: string;
+    readonly currentPending?: GateCurrentPending;
+    readonly denyAttributionRefusal?: DenyAttributionRefusalDetail;
+    readonly ask: DecisionRefusalAskReading;
+    readonly gateMoved?: true;
+    readonly wordingHint?: true;
+    readonly standing?: DecisionRefusalStanding;
+    readonly transient?: true;
+    readonly conflict?: DecisionRefusalConflict;
+}
+export declare function mintDecisionRefusalReading(err: {} | null | undefined, context?: RefusalRouteContext, attributionCarried?: boolean): DecisionRefusalReading;
+export declare function readDecisionRefusalReading(err: {} | null | undefined, context?: RefusalRouteContext): DecisionRefusalReading;
 export interface DecisionRefusalClassified {
     readonly standing: DecisionRefusalStanding;
     readonly status: number;
@@ -17,7 +56,7 @@ export interface DecisionRefusalClassified {
     readonly transient?: true;
     readonly conflict?: DecisionRefusalConflict;
 }
-export declare function classifyDecisionRefusal(err: unknown): DecisionRefusalClassified | undefined;
+export declare function classifyDecisionRefusal(err: unknown, context?: RefusalRouteContext): DecisionRefusalClassified | undefined;
 export type LiveAskPendingReading = 'pending' | 'not_pending' | 'unknown';
 export declare function liveAskPendingReading(envelope: unknown, approvalId: string): LiveAskPendingReading;
 export declare function decisionRefusalClosesOut(refusal: DecisionRefusalClassified | undefined, pending: LiveAskPendingReading): boolean;