@sema-agent/client-core 0.97.1 → 0.98.0

package/dist/hitl/hitlBridge.js

@@ -4,8 +4,8 @@ import { hostLog } from '../host.js';
 import { invokeHostCallbackIsolated } from '../hostCallbackGuard.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { ownDataField, readOwnDataValue } from '../ownKey.js';
-import { THROWN_SLOT_UNREADABLE, readBlockedBy, readThrownSlot, thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
-import { RESUME_POLICY_FOLD_CODE } from '../engineErrorCodes.js';
+import { PROTOCOL_ERROR_NAME, THROWN_SLOT_UNREADABLE, protocolErrorNameReading, readBlockedBy, readThrownSlot, thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
+import { APPROVAL_BINDING_MISMATCH, CHECKPOINT_INVALID_OUTCOME, RESUME_POLICY_FOLD_CODE } from '../engineErrorCodes.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
 const MAX_DENY_REASON_CHARS = 4096;
@@ -46,8 +46,8 @@ export function isNoDecisionSurfaceReason(reason) {
 }
 export class HitlSafetyError extends Error {
     code;
-    constructor(message, code) {
-        super(message);
+    constructor(message, code, options) {
+        super(message, options);
         this.code = code;
         this.name = 'HitlSafetyError';
     }
@@ -455,7 +455,7 @@ export class HitlBridge {
             catch (e) {
                 const binding = bindingMismatchReading(e);
                 if (binding === 'mismatch') {
-                    throw new HitlSafetyError('approval_binding_mismatch — the pending action changed under the human; refetch + re-present', 'binding_mismatch');
+                    throw new HitlSafetyError('approval_binding_mismatch — the pending action changed under the human; refetch + re-present', 'binding_mismatch', { cause: e });
                 }
                 if (binding === 'unreadable')
                     throw e;
@@ -532,10 +532,13 @@ function bindingMismatchReading(e) {
     if (!e || typeof e !== 'object')
         return 'not';
     const code = readWireErrorCodeReading(e);
-    const name = readThrownSlot(e, 'name');
-    const family = (code.state === 'code' && code.code === 'approval_binding_mismatch') || name === 'ApprovalBindingMismatchError';
+    const nameReading = protocolErrorNameReading(e);
+    const family = (code.state === 'code' && (code.code === APPROVAL_BINDING_MISMATCH || code.code === CHECKPOINT_INVALID_OUTCOME)) ||
+        (nameReading.state === 'named' && nameReading.name === PROTOCOL_ERROR_NAME.ApprovalBindingMismatchError);
     if (family)
         return 'mismatch';
+    if (nameReading.state === 'sdk-instance' && code.state !== 'code')
+        return 'unreadable';
     if (code.state === 'unreadable')
         return 'unreadable';
     return 'not';

package/dist/hitl/livePendingAsk.d.ts

@@ -1,5 +1,6 @@
+import type { ApprovalResolution } from './approvalResolution.js';
 import type { ApprovalsFeedEmission } from './approvalsFeed.js';
-import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
+import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts } from './toolApprovalWire.js';
 export interface LivePendingAskView {
     approvalId: string;
     toolName: string;
@@ -43,11 +44,10 @@ export interface ApprovalsAwaitingDecisionCount {
 }
 export declare function countApprovalsAwaitingDecision(snapshot: ApprovalsFeedEmission | null | undefined, filter: SuspendedAskFilter): ApprovalsAwaitingDecisionCount;
 export declare function livePendingRowToApprovalFrame(row: LivePendingAskView): ToolApprovalFrame;
-export declare function surfaceSuspendedAskAndRespond(row: LivePendingAskView, respond: RespondToolApprovalFn, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ToolApprovalFrameOutcome>;
+export declare function surfaceSuspendedAskAndRespond(row: LivePendingAskView, respond: RespondToolApprovalFn, signal?: AbortSignal, lane?: ToolApprovalFrameLaneOpts): Promise<ApprovalResolution>;
 export interface SuspendedAskDelta {
     appeared: LivePendingAskView[];
     gone: string[];
-    upgraded: LivePendingAskView[];
 }
 export interface SuspendedAskTracker {
     ingest(snapshot: ApprovalsFeedEmission | null | undefined): SuspendedAskDelta;

package/dist/hitl/livePendingAsk.js

@@ -1,3 +1,4 @@
+import { readRequiresRealApproval } from './approvalCardReading.js';
 import { THROWN_SLOT_UNREADABLE, readThrownSlot } from '../wireFailureShape.js';
 import { isToolApprovalFrame, surfaceToolApprovalFrameAndRespond, } from './toolApprovalWire.js';
 function nonEmptyString(v) {
@@ -59,7 +60,7 @@ export function readLivePendingRows(body) {
             ts: o.ts,
             expiresAtMs: o.expiresAtMs,
             ...(nonEmptyString(o.sessionId) ? { sessionId: o.sessionId } : {}),
-            ...(o.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(readRequiresRealApproval(o) ? { requiresRealApproval: true } : {}),
             ...(o.governanceForced === true ? { governanceForced: true } : {}),
             ...(o.fromSubagent === true ? { fromSubagent: true } : {}),
             ...(nonEmptyString(o.originTaskId) ? { originTaskId: o.originTaskId } : {}),
@@ -128,7 +129,7 @@ export function livePendingRowToApprovalFrame(row) {
         ...(row.fromSubagent === true ? { fromSubagent: true } : {}),
         ...(row.originTaskId !== undefined ? { sourceTaskId: row.originTaskId } : {}),
         ...(row.governanceForced === true ? { governanceForced: true } : {}),
-        ...(row.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        ...(readRequiresRealApproval(row) ? { requiresRealApproval: true } : {}),
     };
 }
 export function surfaceSuspendedAskAndRespond(row, respond, signal, lane) {
@@ -144,7 +145,6 @@ const TRACKER_UNSEEN_CLAIMS_MAX = 512;
 export function createSuspendedAskTracker(filter) {
     const scope = suspendedAskScopeOf(filter);
     const shown = new Set();
-    const shownWithFrame = new Set();
     const claimed = new Map();
     const claim = (id) => {
         if (claimed.has(id))
@@ -166,28 +166,20 @@ export function createSuspendedAskTracker(filter) {
     return {
         ingest(snapshot) {
             if (snapshot?.kind === 'unknown')
-                return { appeared: [], gone: [], upgraded: [] };
+                return { appeared: [], gone: [] };
             if (scope.kind === 'identity_pending')
-                return { appeared: [], gone: [], upgraded: [] };
+                return { appeared: [], gone: [] };
             const rows = subagentAsksIn(snapshot, scope);
             const present = new Set(rows.map(r => r.approvalId));
             const appeared = [];
-            const upgraded = [];
             for (const r of rows) {
                 if (claimed.has(r.approvalId)) {
                     claimed.set(r.approvalId, true);
                     continue;
                 }
-                if (shown.has(r.approvalId)) {
-                    if (r.frame !== undefined && !shownWithFrame.has(r.approvalId)) {
-                        shownWithFrame.add(r.approvalId);
-                        upgraded.push(r);
-                    }
+                if (shown.has(r.approvalId))
                     continue;
-                }
                 shown.add(r.approvalId);
-                if (r.frame !== undefined)
-                    shownWithFrame.add(r.approvalId);
                 appeared.push(r);
             }
             const incomplete = snapshot !== null && snapshot !== undefined && (snapshot.livePendingDropped ?? 0) > 0;
@@ -197,14 +189,13 @@ export function createSuspendedAskTracker(filter) {
                     if (present.has(id))
                         continue;
                     shown.delete(id);
-                    shownWithFrame.delete(id);
                     gone.push(id);
                 }
                 for (const [id, seen] of [...claimed])
                     if (seen && !present.has(id))
                         claimed.delete(id);
             }
-            return { appeared, gone, upgraded };
+            return { appeared, gone };
         },
         noteSurfacedByStream(approvalId) {
             if (typeof approvalId !== 'string' || approvalId === '')
@@ -217,7 +208,6 @@ export function createSuspendedAskTracker(filter) {
         noteDecided(approvalId) {
             if (typeof approvalId !== 'string' || approvalId === '')
                 return;
-            shownWithFrame.delete(approvalId);
             const wasShown = shown.delete(approvalId);
             if (wasShown)
                 claimed.set(approvalId, true);
@@ -228,7 +218,6 @@ export function createSuspendedAskTracker(filter) {
             if (typeof approvalId !== 'string' || approvalId === '')
                 return;
             shown.delete(approvalId);
-            shownWithFrame.delete(approvalId);
             claimed.delete(approvalId);
         },
     };

package/dist/hitl/parkResolver.d.ts

@@ -1,9 +1,8 @@
 import type { AgentEvent } from '@sema-agent/sdk';
-import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode } from './hitlBridge.js';
+import { type HitlSafetyCode } from './hitlBridge.js';
 import { type QuestionAnswer } from '../liveQuestionStore.js';
 import type { AskAnsweredOutput, GateLedger } from './gateLedger.js';
 import { type AskGateWireDeps, type GatePark } from './frameRouter.js';
-import { type DecideReceiptView } from '../decideReceipt.js';
 export declare const MAX_GATE_HOPS = 2;
 export type HopRound = 'progress' | 'stalled';
 export interface HopBudget {
@@ -13,30 +12,9 @@ export interface HopBudget {
 export declare function nextHopBudget(prev: HopBudget | undefined, round: HopRound): HopBudget;
 export declare const MAX_TOTAL_PARKS = 64;
 export type GateFailureCode = HitlSafetyCode;
-export type GateOutcome = {
-    kind: 'decided';
-    gatedCallId?: string | undefined;
-    answered?: AskAnsweredOutput | undefined;
-    receipt?: DecideReceiptView | undefined;
-} | {
-    kind: 'aborted';
-    gatedCallId?: string | undefined;
-} | {
-    kind: 'failed';
-    stage: HitlFailureStage;
-    gatedCallId?: string | undefined;
-    reason: string;
-    code?: GateFailureCode | undefined;
-    errorCode?: string | undefined;
-    blockedBy?: string | undefined;
-    retriable?: true;
-    retryExhausted?: true;
-    currentPending?: GateCurrentPending | undefined;
-};
 export declare function isAlreadyResolvedGateReason(reason: unknown): boolean;
 export declare function isAlreadyResolvedFailure(failure: unknown): boolean;
-export declare function isGateStandingErrorCode(code: string | null | undefined, retriable?: boolean): boolean;
-export declare function isCodeClassifiedGateFailure(code: string | null | undefined, retriable?: boolean): boolean;
+export { isGateStandingErrorCode, isCodeClassifiedGateFailure } from '../gateFailureCodes.js';
 export declare function toAnsweredOutput(questions: unknown[], answer: QuestionAnswer): AskAnsweredOutput;
 export type ParkResolution = {
     kind: 'reattach';

package/dist/hitl/parkResolver.js

@@ -1,17 +1,17 @@
 import { putOwnKey, readOwnDataValue } from '../ownKey.js';
-import { DecideTransportRetryExhaustedError, GATE_FAILURE_CODES, HitlBridge, NO_QUESTION_OVERLAY_REASON, findPendingForTask, hitlSafetyCodeOf, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireCodes, } from './hitlBridge.js';
-import { DECIDE_WORKFLOW_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, RESUME_REOPEN_CODES, RESUME_RETRY_LATER_CODES, isRefusedParkCode, refusalSaysStillPending } from '../engineErrorCodes.js';
-import { RESUME_REFUSAL_CODES } from '../resumeRefusalCopy.js';
+import { HitlBridge, NO_QUESTION_OVERLAY_REASON, findPendingForTask, isNoDecisionSurfaceReason, } from './hitlBridge.js';
+import { approvalResolutionDetail, resolutionOfDecisionFailure } from './approvalResolution.js';
 import { readDecisionRefusalAsk } from './decisionRefusal.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
 import { INTERRUPT_DENY_REASON, observeCancelByDeny } from './hitlHostSurface.js';
 import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
+import { inheritFrameBinding } from '../frameBinding.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -20,9 +20,6 @@ export function nextHopBudget(prev, round) {
 const MAX_TRANSPORT_REATTACHES = 2;
 export const MAX_TOTAL_PARKS = 64;
 const MAX_ALREADY_RESOLVED_REATTACHES = 1;
-function isGateFailureCode(v) {
-    return typeof v === 'string' && GATE_FAILURE_CODES.includes(v);
-}
 export function isAlreadyResolvedGateReason(reason) {
     return alreadyResolvedReasonToken(reason) !== undefined;
 }
@@ -42,19 +39,7 @@ export function isAlreadyResolvedFailure(failure) {
         return false;
     }
 }
-export function isGateStandingErrorCode(code, retriable) {
-    return (code === RESUME_POLICY_FOLD_CODE ||
-        code === 'corrupt' ||
-        (isRefusedParkCode(code) && retriable === true) ||
-        (typeof code === 'string' && RESUME_REOPEN_CODES.includes(code) && retriable === true) ||
-        code === DECIDE_WORKFLOW_PARKS_UNREADABLE ||
-        code === DECIDE_WORKFLOW_PARK_FORKED);
-}
-export function isCodeClassifiedGateFailure(code, retriable) {
-    return (isGateStandingErrorCode(code, retriable) ||
-        code === PARKED_RESUME_STARTUP_FAILED ||
-        (typeof code === 'string' && (RESUME_RETRY_LATER_CODES.includes(code) || RESUME_REFUSAL_CODES.includes(code))));
-}
+export { isGateStandingErrorCode, isCodeClassifiedGateFailure } from '../gateFailureCodes.js';
 export function toAnsweredOutput(questions, answer) {
     const answers = {};
     const annotations = {};
@@ -74,12 +59,13 @@ export function toAnsweredOutput(questions, answer) {
 }
 async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGatedCallId, onPresented) {
     if (!hasQuestionOverlay()) {
-        return { kind: 'failed', stage: 'card', reason: NO_QUESTION_OVERLAY_REASON };
+        return { kind: 'not_sent', lane: 'ask', cause: 'card_unavailable', detail: NO_QUESTION_OVERLAY_REASON };
     }
     const found = await findPendingForTask(deps.client, taskId, isAskTool, signal ? { signal } : undefined, parkGatedCallId, (row) => isAskTool(typeof row.toolName === 'string' ? row.toolName : undefined));
     if (!found.ok)
-        return { kind: 'failed', stage: 'fetch', reason: found.reason, ...(found.code !== undefined ? { code: found.code } : {}) };
+        return { kind: 'not_sent', lane: 'ask', cause: found.code ?? 'fetch_failed', ...(found.reason !== '' ? { detail: found.reason } : {}) };
     const { pending, gatedCallId } = found;
+    const at = { lane: 'ask', ...(gatedCallId !== undefined ? { gatedCallId } : {}) };
     const fromArgs = gatedCallId
         ? askArgsByCall.get(gatedCallId)?.questions
         : undefined;
@@ -88,10 +74,10 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
     if (!Array.isArray(questions) || questions.length === 0) {
         const truncated = pending.input?.truncated === true;
         return {
-            kind: 'failed',
-            stage: 'input',
-            gatedCallId,
-            reason: truncated
+            kind: 'not_sent',
+            ...at,
+            cause: 'no_input',
+            detail: truncated
                 ? 'question payload exceeded the engine input cap (input={truncated:true}) — dialog cannot be re-rendered; run stays suspended for out-of-band decide'
                 : 'gate has no question payload (pre-CHANNEL[56] engine?)',
         };
@@ -123,7 +109,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
     const bridge = new HitlBridge(deps.client, taskId, deps.onDecideOperation ? { onDecideOperation: deps.onDecideOperation } : undefined);
     if (answer === null) {
         observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: INTERRUPT_DENY_REASON }, gatedCallId, undefined, pending), taskId);
-        return { kind: 'aborted', gatedCallId };
+        return { kind: 'unsettled', ...at, cause: 'interrupted' };
     }
     let declinedReceipt;
     let attemptedDecision;
@@ -136,7 +122,8 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             const receipt = readDecideReceipt(raw);
             return {
                 kind: 'decided',
-                gatedCallId,
+                ...at,
+                decision: 'allow',
                 answered: toAnsweredOutput(questions, answer),
                 ...(receipt !== undefined ? { receipt } : {}),
             };
@@ -146,26 +133,12 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             const raw = await bridge.decideTool({ decision: 'deny', reason: 'User declined to answer' }, gatedCallId, signal ? { signal } : undefined, pending);
             declinedReceipt = readDecideReceipt(raw);
         }
-        return { kind: 'decided', gatedCallId, ...(declinedReceipt !== undefined ? { receipt: declinedReceipt } : {}) };
+        return { kind: 'decided', ...at, decision: 'deny', ...(declinedReceipt !== undefined ? { receipt: declinedReceipt } : {}) };
     }
     catch (e) {
-        const code = hitlSafetyCodeOf(e);
-        const currentPending = readDecideCurrentPending(e);
-        const wireCodes = readWireCodes(e);
-        const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
         const failureTexts = wireFailureTextsOf(e);
         hostLog('debug', `liveHitlAskWire: decide failed: ${failureTexts.log}`);
-        return {
-            kind: 'failed',
-            stage: 'decide',
-            gatedCallId,
-            reason: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}`,
-            ...(code !== undefined ? { code } : {}),
-            ...(thrownIsInstanceOf(e, DecideTransportRetryExhaustedError) ? { retryExhausted: true } : {}),
-            ...(currentPending !== undefined ? { currentPending } : {}),
-            ...wireCodes,
-            ...(wireRetriable ? { retriable: true } : {}),
-        };
+        return resolutionOfDecisionFailure(e, { lane: 'ask', route: 'ask_decide', gatedCallId, detail: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}` });
     }
 }
 function argsByCallOf(led) {
@@ -175,8 +148,18 @@ function alreadyResolvedStreakKey(byDecidedIdOnly) {
     return byDecidedIdOnly ? 'decided-id-match' : 'already-resolved';
 }
 function isFetchStepNoPending(outcome) {
-    const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
-    return code === 'no_pending' && outcome.gatedCallId === undefined;
+    return outcome.kind === 'not_sent' && outcome.cause === 'no_pending' && outcome.gatedCallId === undefined;
+}
+function isHumanDisposition(r) {
+    return r.kind === 'decided' || (r.kind === 'unsettled' && r.cause === 'interrupted') || (r.kind === 'not_sent' && r.cause === 'retracted');
+}
+function failureReasonOf(r) {
+    if (r.kind === 'decided')
+        return '';
+    return r.detail ?? approvalResolutionDetail(r) ?? r.cause;
+}
+function orchestrationEnd(park, gatedCallId, detail) {
+    return { kind: 'unsettled', lane: park.gate === 'fs' ? 'decide' : 'ask', cause: 'orchestration', ...(gatedCallId !== undefined ? { gatedCallId } : {}), detail };
 }
 async function surfaceParkGate(park, ctx, gatedCallId, onPresented) {
     const { deps, led, taskId } = ctx;
@@ -194,13 +177,10 @@ async function surfaceParkGate(park, ctx, gatedCallId, onPresented) {
             ...(deps.onDecideOperation ? { onDecideOperation: deps.onDecideOperation } : {}),
             ...(decidedByReading !== undefined ? { approvalDecidedBy: decidedByReading } : {}),
         }, taskId, argsByCallOf(led), ctx.signal, gatedCallId, park.toolName);
-        const outcomeDenied = 'denied' in outcome ? outcome.denied : undefined;
-        if (outcome.kind === 'decided' && outcomeDenied === true && outcome.gatedCallId) {
-            const denySettledBy = 'denySettledBy' in outcome ? outcome.denySettledBy : undefined;
-            const denyReason = 'denyReason' in outcome ? outcome.denyReason : undefined;
+        if (outcome.kind === 'decided' && outcome.decision === 'deny' && outcome.gatedCallId) {
             led.markDenied(outcome.gatedCallId, {
-                ...(denySettledBy !== undefined ? { settledBy: denySettledBy } : {}),
-                ...(denyReason !== undefined ? { reason: denyReason } : {}),
+                ...(outcome.deny?.settledBy !== undefined ? { settledBy: outcome.deny.settledBy } : {}),
+                ...(outcome.deny?.reason !== undefined ? { reason: outcome.deny.reason } : {}),
             });
         }
         return outcome;
@@ -225,25 +205,18 @@ export async function resolvePark(park, ctx) {
     };
     if ((ctx.unverifiableParks ?? 0) > MAX_TOTAL_PARKS) {
         closingCardTried = true;
-        outcome = {
-            kind: 'failed',
-            stage: 'orchestration',
-            reason: `${ctx.unverifiableParks ?? 0} parks in this single turn resolved to no identifiable approval (hard cap ${MAX_TOTAL_PARKS}; last: ${ctx.lastStallReason ?? 'the engine kept parking'})`,
-        };
+        outcome = orchestrationEnd(park, undefined, `${ctx.unverifiableParks ?? 0} parks in this single turn resolved to no identifiable approval (hard cap ${MAX_TOTAL_PARKS}; last: ${ctx.lastStallReason ?? 'the engine kept parking'})`);
     }
     else if (stalledRounds > MAX_GATE_HOPS) {
         closingCardTried = true;
         const stalledReason = `the run stayed parked across ${stalledRounds} consecutive re-attach rounds without any host progress ` +
             `(last: ${ctx.lastStallReason ?? 'unknown'})`;
         if (ctx.lastRoundPresentedCard === true) {
-            outcome = { kind: 'failed', stage: 'orchestration', reason: stalledReason };
+            outcome = orchestrationEnd(park, undefined, stalledReason);
         }
         else {
             const closing = await surfaceParkGate(park, ctx, park.gatedCallId, witness);
-            outcome =
-                closing.kind === 'decided' || closing.kind === 'aborted' || closing.kind === 'retracted'
-                    ? closing
-                    : { kind: 'failed', stage: 'orchestration', reason: `${stalledReason}; closing re-read: ${closing.reason}` };
+            outcome = isHumanDisposition(closing) ? closing : orchestrationEnd(park, undefined, `${stalledReason}; closing re-read: ${failureReasonOf(closing)}`);
         }
     }
     else {
@@ -251,21 +224,20 @@ export async function resolvePark(park, ctx) {
             candidateGatedCallId = decidedIdentityCandidate(led, park);
         outcome = await surfaceParkGate(park, ctx, park.gatedCallId, witness);
     }
-    const alreadyDecidedById = outcome.kind === 'failed' &&
+    const failed = !isHumanDisposition(outcome);
+    const alreadyDecidedById = failed &&
         candidateGatedCallId !== undefined &&
         led.takeDecided(candidateGatedCallId);
-    if (!closingCardTried && outcome.kind === 'failed' && (isAlreadyResolvedFailure(outcome) || alreadyDecidedById)) {
-        const firstReason = outcome.reason;
+    if (!closingCardTried && failed && (isAlreadyResolvedFailure(outcome) || alreadyDecidedById)) {
+        const firstReason = failureReasonOf(outcome);
         const streakKey = alreadyResolvedStreakKey(!isAlreadyResolvedFailure(outcome) && alreadyDecidedById);
-        const reasonToken = alreadyResolvedReasonToken(outcome.reason);
+        const reasonToken = alreadyResolvedReasonToken(firstReason);
         const rescan = isFetchStepNoPending(outcome) && stalledRounds <= MAX_GATE_HOPS
             ? await surfaceParkGate(park, ctx, park.gatedCallId, witness)
             : undefined;
         if (rescan !== undefined &&
-            (rescan.kind === 'decided' ||
-                rescan.kind === 'aborted' ||
-                rescan.kind === 'retracted' ||
-                (rescan.kind === 'failed' && rescan.retryExhausted === true))) {
+            (isHumanDisposition(rescan) ||
+                (rescan.kind === 'unsettled' && rescan.cause === 'transport_exhausted'))) {
             hostLog('debug', `liveHitlAskWire: gate reported already-resolved (${firstReason}) but a fresh approvals re-read for run ` +
                 `${taskId} surfaced a decidable row under the current coordinates — re-presented it (rescan: ${rescan.kind}) ` +
                 `instead of re-attaching on the stale park identity`);
@@ -286,48 +258,40 @@ export async function resolvePark(park, ctx) {
                 `(last gate reason: ${firstReason})`;
             hostLog('warn', `liveHitlAskWire: refusing to re-attach runs.events(${taskId}) again — ${stalled} ` +
                 `[criterion: ${streakKey}${reasonToken !== undefined ? ` via reason token "${reasonToken}"` : ''}]`);
-            outcome = {
-                kind: 'failed',
-                stage: 'orchestration',
-                ...(outcome.gatedCallId !== undefined ? { gatedCallId: outcome.gatedCallId } : {}),
-                reason: stalled,
-            };
+            outcome = orchestrationEnd(park, outcome.gatedCallId, stalled);
         }
     }
-    if (outcome.kind === 'failed' && outcome.retryExhausted === true && !closingCardTried) {
-        const token = transportReasonToken(outcome.reason);
+    if (outcome.kind === 'unsettled' && outcome.cause === 'transport_exhausted' && !closingCardTried) {
+        const transportReason = failureReasonOf(outcome);
+        const token = transportReasonToken(transportReason);
         const streak = led.noteAlreadyResolvedGate(`transport:${token}`);
         if (streak <= MAX_TRANSPORT_REATTACHES) {
             const seq = led.lastSeq();
             notifyParkReattach(ctx, streak, MAX_TRANSPORT_REATTACHES, `decide transport failed: ${token}`);
-            hostLog('debug', `liveHitlAskWire: decide transport retries exhausted (${outcome.reason}) — re-presenting the gate via ` +
+            hostLog('debug', `liveHitlAskWire: decide transport retries exhausted (${transportReason}) — re-presenting the gate via ` +
                 `re-attach runs.events(${taskId})${seq ? ` from seq ${seq}` : ''} instead of failing the turn (the run is still parked and the pending row is still decidable) [${streak}/${MAX_TRANSPORT_REATTACHES}]`);
             return { kind: 'reattach', progress: false, reason: `decide transport failed: ${token}`, presented: presentedThisRound, gatedCallId: outcome.gatedCallId };
         }
-        outcome = {
-            kind: 'failed',
-            stage: 'orchestration',
-            ...(outcome.gatedCallId !== undefined ? { gatedCallId: outcome.gatedCallId } : {}),
-            reason: `the decide call failed on transport ${streak} times in a row while the run stayed parked (${outcome.reason})`,
-        };
+        outcome = orchestrationEnd(park, outcome.gatedCallId, `the decide call failed on transport ${streak} times in a row while the run stayed parked (${transportReason})`);
     }
     if (outcome.kind !== 'decided') {
-        hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}${'reason' in outcome ? `: ${outcome.reason}` : ''}) — fail-soft to suspended terminal`);
-        const failedReason = outcome.kind === 'failed'
-            ? outcome.reason
-            : outcome.kind === 'retracted'
+        hostLog('debug', `liveHitlAskWire: gate not decided (${outcome.kind}/${outcome.cause}: ${failureReasonOf(outcome)}) — fail-soft to suspended terminal`);
+        const interrupted = outcome.kind === 'unsettled' && outcome.cause === 'interrupted';
+        const failedReason = interrupted
+            ? undefined
+            : outcome.kind === 'not_sent' && outcome.cause === 'retracted'
                 ? 'the approval card was retracted by the host without a decision (nothing was sent; the run stays parked and remains decidable elsewhere)'
-                : undefined;
-        const noDecisionSurface = outcome.kind === 'failed' && outcome.stage === 'card' && isNoDecisionSurfaceReason(outcome.reason);
-        return { kind: 'failsoft', events: failsoftEvents(park, ctx, outcome.kind === 'aborted', failedReason, undefined, noDecisionSurface) };
+                : failureReasonOf(outcome);
+        const noDecisionSurface = outcome.kind === 'not_sent' && outcome.cause === 'card_unavailable' && outcome.detail !== undefined && isNoDecisionSurfaceReason(outcome.detail);
+        return { kind: 'failsoft', events: failsoftEvents(park, ctx, interrupted, failedReason, undefined, noDecisionSurface) };
     }
     led.dropHeldForDecidedPark(outcome.gatedCallId, park.gatedCallId);
     if (outcome.gatedCallId) {
         led.markDecided(outcome.gatedCallId);
-        if ('answered' in outcome && outcome.answered)
+        if (outcome.answered)
             led.rememberAnswer(outcome.gatedCallId, outcome.answered);
     }
-    const handoffTaskId = 'receipt' in outcome && outcome.receipt?.handoffTaskId !== undefined && outcome.receipt.handoffTaskId !== taskId
+    const handoffTaskId = outcome.receipt?.handoffTaskId !== undefined && outcome.receipt.handoffTaskId !== taskId
         ? outcome.receipt.handoffTaskId
         : undefined;
     const seq = led.lastSeq();
@@ -360,13 +324,13 @@ function failsoftEvents(park, ctx, gateAbortedByUser, failedReason, terminal, no
     ];
     const reason = failsoftReasonSentence(park, failedReason, terminal);
     if (park.pendingDone) {
-        events.push(reason === undefined || noDecisionSurface ? park.pendingDone : { ...park.pendingDone, _sema_park_failed_reason: reason });
+        events.push(reason === undefined || noDecisionSurface ? park.pendingDone : inheritFrameBinding(park.pendingDone, { ...park.pendingDone, _sema_park_failed_reason: reason }));
     }
     else if (terminal !== undefined) {
-        events.push({ type: 'failed', ...terminal });
+        events.push(inheritFrameBinding(park.parkFrame, { type: 'failed', ...terminal }));
     }
     else if (reason !== undefined) {
-        events.push({ type: 'failed', errorCode: 'hitl_unanswered', errorMessage: reason });
+        events.push(inheritFrameBinding(park.parkFrame, { type: 'failed', errorCode: 'hitl_unanswered', errorMessage: reason }));
     }
     return events;
 }

package/dist/hitl/persistedRulesWire.d.ts

@@ -88,6 +88,30 @@ export declare const PERSISTED_RULE_BEHAVIORS: readonly RuleBehavior[];
 export declare function persistedRuleBehaviorOf(rule: unknown): RuleBehavior | undefined;
 export declare const PERSISTED_RULE_BEHAVIOR_UNKNOWN = "(unknown)";
 export declare function persistedRuleBehaviorLabel(rule: unknown): string;
+export interface PersistedRuleOriginsRow {
+    readonly adds?: readonly {
+        readonly origin?: string | undefined;
+    }[] | undefined;
+}
+export declare function persistedRuleAddOriginLabel(origin: string | undefined): string;
+export declare function persistedRuleOriginsLabel(rule: PersistedRuleOriginsRow): string;
+export declare function persistedRuleScopeLabel(scope: string | undefined): string;
+export type PersistedRuleRevokeOutcomeWord = 'removed' | 'nothing-written' | 'unknown-status';
+export interface PersistedRuleRevokeResultBody {
+    readonly status?: string | undefined;
+    readonly stillLive?: string | undefined;
+}
+export interface PersistedRuleRevokeOutcome {
+    readonly outcome: PersistedRuleRevokeOutcomeWord;
+    readonly liveness: PersistedRuleLiveness;
+    readonly notice: string;
+    readonly change: string;
+}
+export declare function persistedRuleRevokeOutcome(ruleText: string | undefined, result: PersistedRuleRevokeResultBody | undefined): PersistedRuleRevokeOutcome;
+export interface PersistedRuleMatchRow {
+    readonly match?: string | undefined;
+}
+export declare function persistedRuleMatchLabel(ruleOrMatch: string | PersistedRuleMatchRow | undefined): string;
 export declare function revokeTargetFromPersistedRule(rule: unknown, opts?: {
     principal?: string;
 }): RuleRevokeRequest | undefined;