@sema-agent/client-core 0.93.1 → 0.95.0

package/dist/hitl/parkResolver.js

@@ -1,14 +1,17 @@
 import { putOwnKey, readOwnDataValue } from '../ownKey.js';
-import { DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, NO_QUESTION_OVERLAY_REASON, findPendingForTask, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
-import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
+import { ApprovalStaleError, NotFoundError, ParkedResumeStartupError } from '@sema-agent/sdk';
+import { DecideTransportRetryExhaustedError, GATE_FAILURE_CODES, HitlBridge, NO_QUESTION_OVERLAY_REASON, findPendingForTask, hitlSafetyCodeOf, isNoDecisionSurfaceReason, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
+import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, PARKED_RESUME_STARTUP_FAILED, RESUME_POLICY_FOLD_CODE, isDecideAlreadyResolvedCode, isDecideParkMovedCode, refusalSaysStillPending } from '../engineErrorCodes.js';
+import { isHitlSafetyErrorLike } from './parkOwnership.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
-import { observeCancelByDeny } from './hitlHostSurface.js';
+import { INTERRUPT_DENY_REASON, observeCancelByDeny } from './hitlHostSurface.js';
 import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -17,16 +20,6 @@ export function nextHopBudget(prev, round) {
 const MAX_TRANSPORT_REATTACHES = 2;
 export const MAX_TOTAL_PARKS = 64;
 const MAX_ALREADY_RESOLVED_REATTACHES = 1;
-export const GATE_FAILURE_CODES = [
-    'no_pending',
-    'binding_mismatch',
-    'wrong_gate',
-    'bad_plan_edit',
-    'bad_plan_mode',
-    'empty_answer',
-];
-const _gateFailureCodePins = [true, true];
-void _gateFailureCodePins;
 function isGateFailureCode(v) {
     return typeof v === 'string' && GATE_FAILURE_CODES.includes(v);
 }
@@ -40,27 +33,59 @@ function alreadyResolvedReasonToken(reason) {
     const r = reason.toLowerCase();
     return ALREADY_RESOLVED_REASON_TOKENS.find((t) => r.includes(t));
 }
-export function isAlreadyResolvedFailure(outcome) {
+export function isAlreadyResolvedFailure(failure) {
     try {
-        return alreadyResolvedFailureVerdict(outcome);
+        return alreadyResolvedFailureVerdict(failure);
     }
     catch {
         return false;
     }
 }
-function alreadyResolvedFailureVerdict(outcome) {
-    if (typeof outcome !== 'object' || outcome === null)
+const ALREADY_RESOLVED_TYPED_ERROR_NAMES = Object.freeze([ApprovalStaleError.name, NotFoundError.name]);
+const PARKED_RESUME_STARTUP_TYPED_ERROR_NAME = ParkedResumeStartupError.name;
+function decideFailureFactsOf(failure) {
+    if (typeof failure !== 'object' || failure === null)
+        return undefined;
+    const o = failure;
+    const ec = o.errorCode;
+    const errorCode = typeof ec === 'string' && ec.length > 0 ? ec : undefined;
+    const retriable = refusalSaysStillPending(failure);
+    if (Object.hasOwn(failure, 'kind') && o.kind === 'failed') {
+        const safety = isGateFailureCode(o.safetyCode) ? o.safetyCode : undefined;
+        const code = isGateFailureCode(o.code) ? o.code : safety;
+        return { code, safetySignal: safety !== undefined, errorCode, retriable, typedErrorName: undefined, reason: o.reason };
+    }
+    const name = o.name;
+    return {
+        code: isGateFailureCode(o.code) ? o.code : undefined,
+        safetySignal: isHitlSafetyErrorLike(failure),
+        errorCode,
+        retriable,
+        typedErrorName: typeof name === 'string' ? name : undefined,
+        reason: String(failure),
+    };
+}
+function alreadyResolvedFailureVerdict(failure) {
+    const f = decideFailureFactsOf(failure);
+    if (f === undefined)
         return false;
-    const code = 'code' in outcome && isGateFailureCode(outcome.code) ? outcome.code : undefined;
-    if (code !== undefined)
-        return code === 'no_pending';
-    if ('errorCode' in outcome && isCodeClassifiedGateFailure(outcome.errorCode, Object.hasOwn(outcome, 'retriable') && outcome.retriable === true))
+    if (f.code !== undefined)
+        return f.code === 'no_pending';
+    if (f.safetySignal)
+        return false;
+    if (isDecideAlreadyResolvedCode(f.errorCode))
+        return true;
+    if (f.typedErrorName !== undefined && ALREADY_RESOLVED_TYPED_ERROR_NAMES.includes(f.typedErrorName))
+        return true;
+    if (f.typedErrorName === PARKED_RESUME_STARTUP_TYPED_ERROR_NAME && !isDecideParkMovedCode(f.errorCode))
+        return false;
+    if (isCodeClassifiedGateFailure(f.errorCode, f.retriable))
         return false;
-    if ('errorCode' in outcome && isDecideParkMovedCode(outcome.errorCode))
+    if (isDecideParkMovedCode(f.errorCode))
         return true;
-    if ('errorCode' in outcome && outcome.errorCode === ASK_GONE)
+    if (f.errorCode === ASK_GONE)
         return true;
-    return isAlreadyResolvedGateReason(outcome.reason);
+    return isAlreadyResolvedGateReason(f.reason);
 }
 export function isGateStandingErrorCode(code, retriable) {
     return (code === RESUME_POLICY_FOLD_CODE ||
@@ -139,7 +164,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: 'Interrupted by user' }, gatedCallId, undefined, pending), taskId);
+        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: INTERRUPT_DENY_REASON }, gatedCallId, undefined, pending), taskId);
         return { kind: 'aborted', gatedCallId };
     }
     let declinedReceipt;
@@ -166,17 +191,19 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         return { kind: 'decided', gatedCallId, ...(declinedReceipt !== undefined ? { receipt: declinedReceipt } : {}) };
     }
     catch (e) {
-        const code = e instanceof HitlSafetyError && isGateFailureCode(e.code) ? e.code : undefined;
+        const code = hitlSafetyCodeOf(e);
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(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: ${String(e)}${decideFailureNote(e, attemptedDecision)}`,
+            reason: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}`,
             ...(code !== undefined ? { code } : {}),
-            ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
+            ...(thrownIsInstanceOf(e, DecideTransportRetryExhaustedError) ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),
             ...(wireCode !== undefined ? { errorCode: wireCode } : {}),
             ...(wireRetriable ? { retriable: true } : {}),

package/dist/hitl/parkRowBirthWait.js

@@ -1,4 +1,5 @@
 import { abortableSleep } from '../abortableSleep.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 function parkRowPollDelay(ms, signal) {
     return abortableSleep(ms, signal ?? new AbortController().signal);
 }
@@ -16,7 +17,7 @@ export async function waitForParkRowBirth(deps) {
             return await deps.probe(attempt, signal);
         }
         catch (e) {
-            return { kind: 'unborn', reason: `probe threw: ${String(e)}` };
+            return { kind: 'unborn', reason: `probe threw: ${wireFailureTextsOf(e).reason}` };
         }
     };
     const probeWithinRemaining = async (attempt, remainingMs) => {

package/dist/hitl/persistedRulesWire.d.ts

@@ -44,6 +44,9 @@ export type RulesFailure = {
 } | {
     kind: 'cursor-stale';
     message: string;
+} | {
+    kind: 'query-refused';
+    message: string;
 } | {
     kind: 'too-many-candidates';
     message: string;
@@ -78,7 +81,9 @@ export type RulesFailure = {
     kind: 'error';
     message: string;
 };
-export declare function classifyRulesFailure(e: unknown): RulesFailure;
+export declare function classifyRulesFailure(e: unknown, context?: {
+    readonly cursorSent?: boolean;
+}): RulesFailure;
 export declare const PERSISTED_RULE_BEHAVIORS: readonly RuleBehavior[];
 export declare function persistedRuleBehaviorOf(rule: unknown): RuleBehavior | undefined;
 export declare const PERSISTED_RULE_BEHAVIOR_UNKNOWN = "(unknown)";

package/dist/hitl/persistedRulesWire.js

@@ -36,7 +36,7 @@ export function readCcImportRedeemCounts(result) {
     }
     return null;
 }
-export function classifyRulesFailure(e) {
+export function classifyRulesFailure(e, context) {
     const { status, errorCode, message, retryAfterSec, committed } = wireFailureShapeOf(e);
     if (errorCode === 'capability.rule_store_required') {
         return { kind: 'lane-unavailable', message };
@@ -58,8 +58,20 @@ export function classifyRulesFailure(e) {
     if (errorCode === 'state.rule_write_failed') {
         return committed === 'no' ? { kind: 'write-not-committed', message } : { kind: 'write-indeterminate', message };
     }
-    if (status === 400 && errorCode === 'request.query_invalid')
-        return { kind: 'cursor-stale', message };
+    if (status === 400 && errorCode === 'request.query_invalid') {
+        let cursorSent;
+        try {
+            cursorSent = context?.cursorSent;
+        }
+        catch {
+            cursorSent = undefined;
+        }
+        if (cursorSent === true)
+            return { kind: 'cursor-stale', message };
+        if (cursorSent === false)
+            return { kind: 'query-refused', message };
+        return { kind: 'error', message };
+    }
     if (status === 400 && errorCode === 'request.field_invalid')
         return { kind: 'field-refused', message };
     if (status === 400 && errorCode === 'request.body_shape')
@@ -144,7 +156,7 @@ export async function listAllPersistedRules(facade, params = {}, opts) {
                 res = await facade.list({ limit: PAGE_LIMIT, ...cleanParams, ...(cursor !== undefined ? { cursor } : {}) }, opts);
             }
             catch (e) {
-                const failure = classifyRulesFailure(e);
+                const failure = classifyRulesFailure(e, { cursorSent: cursor !== undefined });
                 if (failure.kind === 'cursor-stale' && cursor !== undefined && attempt === 0) {
                     hostLog('debug', 'persistedRulesWire: rule list cursor was minted on another rev/principal/scope — dropping it and re-listing from the top (never resuming a stale keyset)');
                     restart = true;

package/dist/hitl/planReviewWire.d.ts

@@ -12,6 +12,7 @@ export type PlanReviewChoice = {
     permissionModeAfter?: PlanReviewModeAfter;
 } | {
     decision: 'reject';
+    reason?: string;
 };
 export declare function planReviewChoiceFromAnswer(answer: QuestionAnswer | null | undefined, shownLabels?: readonly string[]): PlanReviewChoice | 'dismissed';
 export declare function planReviewCardOptions(offerModeAfter: boolean): Array<{
@@ -48,7 +49,6 @@ export type PlanReviewWireClient = {
 };
 export interface PlanReviewWire {
     client: PlanReviewWireClient;
-    capsBaseUrl?: string;
 }
 export interface PlanReviewDecisionOutcome extends PlanReviewOutcomeMeta {
     detail: string;
@@ -77,14 +77,13 @@ export declare function __resetPlanReviewDecisionLatchForTests(): void;
 export declare function decidePlanReview(taskId: string, decision: 'approve' | 'reject', permissionModeAfter?: string, opts?: DecidePlanReviewOptions): Promise<void>;
 export interface ReopenPlanReviewOpts {
     mintFreshQuestionId?: boolean;
-    deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
+    deliverDecision?: (taskId: string, decision: 'approve' | 'reject', reason?: string) => void | Promise<void>;
     sessionKey?: string;
     wire?: PlanReviewWire;
     onOutcome?: PlanReviewDeliveryOptions['onOutcome'];
     presentationReceiptMs?: number;
     trigger?: PlanReviewReopenTrigger;
     readGateInstanceKeys?: PlanReviewGateInstanceReader;
-    decisionHandedOver?: (taskId: string) => boolean;
     pendingReadStartedAt?: number;
 }
 export declare function _resetActiveReopenRespondersForTest(): void;

package/dist/hitl/planReviewWire.js

@@ -6,7 +6,8 @@ import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError } from '../resumeRefusalCopy.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
+import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, resumeContextUnavailableContent, resumeContextUnavailableFromError } from '../resumeRefusalCopy.js';
 import { REQUEST_FIELD_CONFLICT, isUnavailableFaceCode } from '../engineErrorCodes.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
@@ -28,31 +29,59 @@ const ALL_KNOWN_LABELS = Object.freeze([
     PLAN_REVIEW_APPROVE_LABEL,
     PLAN_REVIEW_REJECT_LABEL,
 ]);
-export function planReviewDecisionFromAnswer(answer, shownLabels) {
-    const choice = planReviewChoiceFromAnswer(answer, shownLabels);
+export function planReviewDecisionFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+    const { choice } = readPlanReviewAnswer(answer, shownLabels);
     if (choice === 'dismissed')
         return 'dismissed';
     return choice.decision;
 }
-export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+function readDismissed() {
+    return { choice: 'dismissed', noteIgnoredOnApprove: false };
+}
+function freeTextNoteOf(entry) {
+    try {
+        const note = entry?.note;
+        return typeof note === 'string' && note.trim() !== '' ? note : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPlanReviewAnswer(answer, shownLabels) {
     const answers = answer?.answers;
     if (!Array.isArray(answers) || answers.length !== 1)
-        return 'dismissed';
-    const picked = answers[0]?.selected;
-    if (!Array.isArray(picked) || picked.length !== 1)
-        return 'dismissed';
+        return readDismissed();
+    const entry = answers[0];
+    const picked = entry?.selected;
+    if (!Array.isArray(picked))
+        return readDismissed();
+    const note = freeTextNoteOf(entry);
+    if (picked.length === 0) {
+        if (note === undefined || !shownLabels.includes(REJECT_LABEL))
+            return readDismissed();
+        return { choice: { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
+    }
+    if (picked.length !== 1)
+        return readDismissed();
     const selected = picked[0];
     if (typeof selected !== 'string' || !shownLabels.includes(selected))
-        return 'dismissed';
+        return readDismissed();
+    const ignored = note !== undefined;
     if (selected === PLAN_REVIEW_APPROVE_AUTO_LABEL)
-        return { decision: 'approve', permissionModeAfter: 'acceptEdits' };
+        return { choice: { decision: 'approve', permissionModeAfter: 'acceptEdits' }, noteIgnoredOnApprove: ignored };
     if (selected === PLAN_REVIEW_APPROVE_MANUAL_LABEL)
-        return { decision: 'approve', permissionModeAfter: 'default' };
+        return { choice: { decision: 'approve', permissionModeAfter: 'default' }, noteIgnoredOnApprove: ignored };
     if (selected === APPROVE_LABEL)
-        return { decision: 'approve' };
+        return { choice: { decision: 'approve' }, noteIgnoredOnApprove: ignored };
     if (selected === REJECT_LABEL)
-        return { decision: 'reject' };
-    return 'dismissed';
+        return { choice: note === undefined ? { decision: 'reject' } : { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
+    return readDismissed();
+}
+export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
+    const { choice, noteIgnoredOnApprove } = readPlanReviewAnswer(answer, shownLabels);
+    if (noteIgnoredOnApprove)
+        hostLog('debug', 'planReviewWire: note ignored on approve — an approval carries no feedback text; the note was not sent');
+    return choice;
 }
 export function planReviewCardOptions(offerModeAfter) {
     const reject = { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' };
@@ -269,10 +298,12 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             const decided = choice.decision;
             notePlanReviewDecisiveAnswerFor(DEFAULT_SESSION_KEY, taskId);
             const modeAfter = choice.decision === 'approve' ? choice.permissionModeAfter : undefined;
+            const cardReason = choice.decision === 'reject' ? choice.reason : undefined;
+            const cardDelivery = cardReason !== undefined ? { ...delivery, reason: cardReason } : delivery;
             offerModeAfterByTask.delete(taskId);
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReviewFor(taskId, decided, modeAfter, delivery, gateBefore);
+            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, gateBefore);
             return { ok: true };
         });
         publishPlanReviewCard(taskId);
@@ -309,6 +340,15 @@ export function planReviewOutcomeTail(taskId, decision, effect, cause) {
             return `Do not state the result as fact: tell the user the ${decision} was submitted but its effect could not be confirmed; TaskOutput("${taskId}") shows where the task stands.`;
     }
 }
+function clientOnlyView(wire) {
+    if (wire === undefined || wire === null || typeof wire !== 'object')
+        return wire;
+    return {
+        get client() {
+            return wire.client;
+        },
+    };
+}
 function planReviewDecisionTimedOutOutcome(decision) {
     return (`The plan_review ${decision} was sent, but no answer came back from the engine within the time limit this host allows for it — ` +
         `it may have taken effect (${decision === 'approve' ? 'an approval keeps the engine busy until the resumed work finishes' : 'the engine may still be applying it'}).`);
@@ -492,12 +532,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     let stillParkedProven = false;
     let statusSeen;
     const wire = opts?.wire;
-    const resolved = engineWireFor(wire, DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
-    const badMode = permissionModeAfter !== undefined && (decision !== 'approve' || !isPlanReviewModeAfter(permissionModeAfter));
+    const resolved = engineWireFor(clientOnlyView(wire), DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
+    const badMode = permissionModeAfter !== undefined && !isPlanReviewModeAfter(permissionModeAfter);
     if (badMode) {
-        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter is only valid with approve and must be "default" or "acceptEdits"`);
+        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter must be "default" or "acceptEdits"`);
         effect = 'not_sent';
-        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid for this decision (it only applies to an approval, and must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
+        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid (it must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
     }
     else if (resolved.kind === 'no-target') {
         hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
@@ -600,12 +640,15 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 const refusedCode = e?.errorCode;
                 const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
                 if (status === 400 && refusedCode === REQUEST_FIELD_CONFLICT && permissionModeAfter === 'acceptEdits') {
-                    hostLog('debug', 'planReviewWire: approve + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode');
+                    hostLog('debug', `planReviewWire: ${decision} + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode`);
                     effect = 'still_parked';
                     stillParkedProven = true;
                     outcome =
-                        'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
-                            'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.';
+                        decision === 'approve'
+                            ? 'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.'
+                            : `The plan ${decision} was NOT applied: the engine refused the post-approval permission mode that was sent with it (request.field_conflict). ` +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly that the decision did not go through.';
                 }
                 else if (status === 404 && refusedCode === 'not_found.plan_review') {
                     hostLog('debug', `planReviewWire: ${decision} → 404 not_found.plan_review (no pending plan review any more — an earlier decision likely settled it)`);
@@ -622,6 +665,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     stillParkedCause = 'stored_form_unsupported';
                     outcome = `This ${decision} was not applied. ${checkpointUnsupportedVersionContent(cu, { parkKind: 'plan_review', runId: taskId })}`;
                 }
+                else if (resumeContextUnavailableFromError(e) !== null) {
+                    const ru = resumeContextUnavailableFromError(e);
+                    hostLog('debug', `planReviewWire: ${decision} → 409 conflict.resume_context_unavailable (the session context needed to continue this run is not available)`);
+                    effect = 'not_applied';
+                    outcome = `This ${decision} was not applied. ${resumeContextUnavailableContent(ru)}`;
+                }
                 else if (typeof status === 'number' && corruptStoredRowWhere(e) !== undefined) {
                     const where = corruptStoredRowWhere(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${String(status)} corrupt (stored resume context unreadable)`);
@@ -643,7 +692,9 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     outcome = planReviewDecisionConnectionLostOutcome(decision);
                 }
                 else {
-                    outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+                    const failureTexts = wireFailureTextsOf(e);
+                    hostLog('debug', `planReviewWire: ${decision} could not reach the engine: ${failureTexts.log}`);
+                    outcome = `The plan_review decision could not reach the engine: ${failureTexts.reason}`;
                 }
             }
         }
@@ -800,9 +851,10 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         ? { ...(opts.wire !== undefined ? { wire: opts.wire } : {}), ...(opts.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
         : undefined;
     const deliver = opts?.deliverDecision ??
-        ((tid, decision) => {
+        ((tid, decision, reason) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
-            void (delivery === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, delivery));
+            const withReason = reason === undefined ? delivery : { ...delivery, reason };
+            void (withReason === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, withReason));
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
@@ -810,15 +862,20 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
             activeReopenResponders.delete(activeKey);
         }
-        const decided = planReviewDecisionFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
-        if (decided === 'dismissed') {
+        const choice = planReviewChoiceFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
+        if (choice === 'dismissed') {
             notePlanReviewUserDismissalFor(sessionKey, taskId, opts?.readGateInstanceKeys, questionId);
             return { ok: true };
         }
+        const decided = choice.decision;
+        const cardReason = choice.decision === 'reject' ? choice.reason : undefined;
         notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
         notePlanReviewAnsweredFor(sessionKey, questionId);
         try {
-            await deliver(taskId, decided);
+            if (cardReason === undefined)
+                await deliver(taskId, decided);
+            else
+                await deliver(taskId, decided, cardReason);
         }
         catch (e) {
             hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
@@ -866,18 +923,8 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
                 }
             }
         }
-        let handedOver = false;
         const ledgerSaysInFlight = planReviewDecisionInFlight(taskId, recheckReadStart);
-        if (!ledgerSaysInFlight) {
-            try {
-                handedOver = opts.decisionHandedOver?.(taskId) === true;
-            }
-            catch (err) {
-                hostLog('debug', `planReviewWire: reopen for task ${taskId} refused — the host's decision hand-over check threw: ${String(err)}`);
-                return { reopened: false };
-            }
-        }
-        if (ledgerSaysInFlight || handedOver) {
+        if (ledgerSaysInFlight) {
             hostLog('debug', `planReviewWire: reopen for task ${taskId} refused after the dismissal check — a decision for this task went out while the check was reading`);
             return { reopened: false, _sema_decisionInFlight: true };
         }

package/dist/hitl/replayedApproval.d.ts

@@ -1,3 +1,4 @@
+import { type ApprovalSettledHow } from './gateLedger.js';
 import { type ApprovalsListEnvelope, type CrashConvergedRow } from './crashConverged.js';
 export type ReplayedApprovalDisposition = {
     readonly kind: 'live';
@@ -5,6 +6,8 @@ export type ReplayedApprovalDisposition = {
 } | {
     readonly kind: 'decided';
     readonly cause?: CrashConvergedRow['cause'];
+    readonly needsHumanReason?: NonNullable<CrashConvergedRow['needsHumanReason']>;
+    readonly settled?: ApprovalSettledHow;
 } | {
     readonly kind: 'unknown';
     readonly why: 'unreadable_frame' | 'no_approval_id' | 'not_read' | 'list_unreadable' | 'list_not_reported' | 'list_incomplete';
@@ -17,5 +20,10 @@ export interface ReplayPendingBasis {
     } | {
         readonly read: 'failed';
     };
+    readonly settled?: ReadonlyMap<string, ApprovalSettledHow>;
 }
+export declare function settledApprovalDisposition(frame: object, settled: ReplayPendingBasis['settled']): ReplayedApprovalDisposition | undefined;
 export declare function replayedApprovalDisposition(frame: object, basis: ReplayPendingBasis): ReplayedApprovalDisposition;
+export declare function replayedApprovalSentence(disposition: ReplayedApprovalDisposition | undefined, opts?: {
+    readonly toolName?: string;
+}): string | undefined;