@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/hitl/parkResolver.js

@@ -1,6 +1,7 @@
 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 { 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, isRefusedParkCode, refusalSaysStillPending } from '../engineErrorCodes.js';
+import { readDecisionRefusalAsk } from './decisionRefusal.js';
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
@@ -9,7 +10,7 @@ import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { wireFailureTextsOf } from '../wireFailureShape.js';
+import { thrownIsInstanceOf, wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -18,16 +19,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);
 }
@@ -41,32 +32,19 @@ 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);
+        const r = readDecisionRefusalAsk(failure);
+        return r.reading === 'settled' || (r.reading === 'not_settled' && (r.gateMoved || r.wordingHint));
     }
     catch {
         return false;
     }
 }
-function alreadyResolvedFailureVerdict(outcome) {
-    if (typeof outcome !== 'object' || outcome === null)
-        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))
-        return false;
-    if ('errorCode' in outcome && isDecideParkMovedCode(outcome.errorCode))
-        return true;
-    if ('errorCode' in outcome && outcome.errorCode === ASK_GONE)
-        return true;
-    return isAlreadyResolvedGateReason(outcome.reason);
-}
 export function isGateStandingErrorCode(code, retriable) {
     return (code === RESUME_POLICY_FOLD_CODE ||
         code === 'corrupt' ||
-        (code === CHECKPOINT_UNSUPPORTED_VERSION && retriable === true) ||
+        (isRefusedParkCode(code) && retriable === true) ||
         code === DECIDE_WORKFLOW_PARKS_UNREADABLE ||
         code === DECIDE_WORKFLOW_PARK_FORKED);
 }
@@ -167,9 +145,9 @@ 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 wireCodes = readWireCodes(e);
         const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
         const failureTexts = wireFailureTextsOf(e);
         hostLog('debug', `liveHitlAskWire: decide failed: ${failureTexts.log}`);
@@ -179,9 +157,9 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
             gatedCallId,
             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 } : {}),
+            ...wireCodes,
             ...(wireRetriable ? { retriable: true } : {}),
         };
     }

package/dist/hitl/parkRowBirthWait.d.ts

@@ -35,5 +35,6 @@ export interface ParkRowBirthWaitDeps<Row> {
     now?: () => number;
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     signal?: AbortSignal;
+    onFailure?: (log: string) => void;
 }
 export declare function waitForParkRowBirth<Row>(deps: ParkRowBirthWaitDeps<Row>): Promise<ParkRowWaitVerdict<Row>>;

package/dist/hitl/parkRowBirthWait.js

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

package/dist/hitl/persistedRulesWire.js

@@ -66,7 +66,11 @@ export function classifyRulesFailure(e, context) {
         catch {
             cursorSent = undefined;
         }
-        return cursorSent === false ? { kind: 'query-refused', message } : { kind: 'cursor-stale', message };
+        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 };

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<{
@@ -61,6 +62,7 @@ export interface PlanReviewDeliveryOptions {
 }
 export interface DecidePlanReviewOptions extends PlanReviewDeliveryOptions {
     reason?: string;
+    parkedResult?: unknown;
 }
 export interface PlanReviewDecisionHandle {
     settle(): void;
@@ -76,14 +78,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

@@ -13,7 +13,7 @@ import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, registerArmedGateFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { PLAN_REVIEW_GATE_KIND } from '../adapter/activeRunSelfHeal.js';
+import { PLAN_REVIEW_GATE_KIND, durableDecideLegOf } from '../adapter/activeRunSelfHeal.js';
 import { readRunTerminal, runTerminalGateKind } from '../runTerminal.js';
 const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
 export const PLAN_REVIEW_APPROVE_LABEL = 'Yes, approve and run the plan';
@@ -29,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' };
@@ -102,6 +130,18 @@ function pausedCheckpointIdOf(carrier) {
         return undefined;
     }
 }
+function pausedGateKindOf(carrier) {
+    try {
+        const read = readRunTerminal(carrier);
+        if (read === null || read.kind !== 'paused')
+            return undefined;
+        const kind = runTerminalGateKind(read);
+        return typeof kind === 'string' && kind.length > 0 ? kind : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const armedPlanReviewTaskIds = new Set();
 const offerModeAfterByTask = new Map();
 export function _resetArmedPlanReviewsForTest() {
@@ -270,10 +310,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);
@@ -440,7 +482,53 @@ export function __resetPlanReviewDecisionLatchForTests() {
     planReviewDecisionOps.length = 0;
 }
 export async function decidePlanReview(taskId, decision, permissionModeAfter, opts) {
-    return decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, undefined);
+    return decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, parkedGateIdentityOf(opts));
+}
+function parkedGateIdentityOf(opts) {
+    try {
+        return opts !== null && typeof opts === 'object' ? pausedCheckpointIdOf(opts.parkedResult) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function planReviewSettledVerdict(r) {
+    const status = r.postStatus ?? r.bodyStatus;
+    const gateMoved = r.gateBefore !== undefined && r.gateAfter !== undefined && r.gateAfter !== r.gateBefore;
+    if (r.reparked)
+        return status !== 'completed' && !gateMoved ? { effect: 'still_parked', proven: true } : { effect: 'unconfirmed', proven: false };
+    if (status === 'completed')
+        return { effect: 'took_effect', proven: false };
+    const newGateHasCard = () => {
+        const leg = durableDecideLegOf({ gateKind: r.gateKindAfter ?? null });
+        return leg === 'approval' || leg === 'plan_review';
+    };
+    if (status === 'suspended' && r.postStatus === 'suspended' && newGateHasCard())
+        return { effect: 'advanced', proven: false };
+    if (status === 'needs_review' && r.postStatus === 'needs_review' && r.gateBefore !== undefined && r.gateAfter !== undefined) {
+        if (r.gateAfter === r.gateBefore)
+            return { effect: 'still_parked', proven: true };
+        if (newGateHasCard())
+            return { effect: 'advanced', proven: false };
+    }
+    return { effect: 'unconfirmed', proven: false };
+}
+function bodyWordOf(body, key) {
+    try {
+        const v = body !== null && typeof body === 'object' ? body[key] : undefined;
+        return typeof v === 'string' && v.length > 0 ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function bodySaysReparked(body) {
+    try {
+        return body !== null && typeof body === 'object' && body.retriable === true;
+    }
+    catch {
+        return false;
+    }
 }
 async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, gateBefore) {
     if (typeof taskId === 'string' && planReviewDecisionOps.some((op) => op.taskId === taskId && op.phase === 'posting')) {
@@ -556,6 +644,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 hostLog('debug', `planReviewWire: ${decision} → ok (dispatch #${dispatchNo}) ${JSON.stringify(body).slice(0, 200)}`);
                 let postStatus;
                 let gateAfter;
+                let gateKindAfter;
                 try {
                     const probe = clients.repull();
                     if (probe) {
@@ -571,35 +660,54 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                         else {
                             post = (await probe.runs.get(taskId));
                         }
-                        postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                        postStatus = bodyWordOf(post, 'status');
                         gateAfter = pausedCheckpointIdOf(post?.result);
+                        gateKindAfter = pausedGateKindOf(post?.result);
                     }
                 }
                 catch (e) {
                     hostLog('debug', `planReviewWire: post-decide status re-pull failed (fail-soft): ${String(e)}`);
                 }
-                const effective = postStatus ?? (typeof body?.status === 'string' ? body.status : undefined);
+                const bodyStatus = bodyWordOf(body, 'status');
+                const effective = postStatus ?? bodyStatus;
                 statusSeen = effective;
-                const gateMoved = postStatus === 'needs_review' && gateBefore !== undefined && gateAfter !== undefined && gateAfter !== gateBefore;
-                if (effective === 'needs_review' && gateMoved) {
-                    effect = 'advanced';
-                    outcome = planReviewAdvancedOutcome(decision, 'needs_review');
-                }
-                else if (effective === 'needs_review') {
-                    effect = 'still_parked';
-                    stillParkedProven = postStatus === 'needs_review' && gateBefore !== undefined && gateAfter !== undefined && gateAfter === gateBefore;
+                const verdict = planReviewSettledVerdict({ postStatus, bodyStatus, reparked: bodySaysReparked(body), gateBefore, gateAfter, gateKindAfter });
+                effect = verdict.effect;
+                stillParkedProven = verdict.proven;
+                const code = bodyWordOf(body, 'errorCode');
+                if (effect === 'still_parked' && postStatus === 'needs_review' && !bodySaysReparked(body)) {
                     outcome =
                         `The plan_review ${decision} returned HTTP 200 but the session is STILL locked on the same review gate ` +
                             `(post-decide status: needs_review). The decision did NOT take effect (known engine issue, RB-471 family). ` +
                             `Tell the user plainly that the ${decision} did not go through; the reliable exits today are approving the plan or cancelling the task.`;
                 }
-                else if (effective === 'suspended') {
-                    effect = 'advanced';
-                    outcome = planReviewAdvancedOutcome(decision, 'suspended');
+                else if (effect === 'still_parked') {
+                    outcome =
+                        `The plan_review ${decision} was NOT applied: the engine could not continue the task and put the plan back to wait for a decision` +
+                            `${code !== undefined ? ` (engine code: ${code})` : ''}. Tell the user plainly that the ${decision} did not go through.`;
+                }
+                else if (effect === 'advanced') {
+                    outcome = planReviewAdvancedOutcome(decision, effective === 'needs_review' ? 'needs_review' : 'suspended');
+                }
+                else if (effect === 'took_effect') {
+                    outcome =
+                        `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} ` +
+                            `(${postStatus !== undefined ? 'post-decide re-checked: task left the review gate' : "from the decision's own reply; the post-decide re-check was unavailable"}).`;
+                }
+                else if (effective === 'needs_review' && (gateBefore === undefined || gateAfter === undefined || postStatus !== 'needs_review')) {
+                    outcome =
+                        `The plan_review ${decision} returned HTTP 200 and the task is waiting at a plan review gate again (post-decide status: needs_review), ` +
+                            `but it could not be told whether this is the same review (the ${decision} did not take effect) or a new plan written after it (it did).`;
+                }
+                else if (effective === 'suspended' || effective === 'needs_review') {
+                    outcome =
+                        `The plan_review ${decision} was accepted by the engine (HTTP 200) and the task is paused again (post-decide status: ${effective}), ` +
+                            `${gateKindAfter !== undefined ? `at a '${gateKindAfter}' pause that is not an approval card` : 'but the pause it stopped at was not reported'} — what the ${decision} led to could not be confirmed.`;
                 }
                 else if (effective !== undefined) {
-                    effect = 'took_effect';
-                    outcome = `The plan was ${decision === 'approve' ? 'approved and the parked task resumed to completion' : 'rejected (plan discarded)'} — final status: ${effective} (post-decide re-checked: task left the review gate).`;
+                    outcome =
+                        `The plan_review ${decision} was accepted by the engine (HTTP 200), but the task then reported status ${effective}` +
+                            `${code !== undefined ? ` (engine code: ${code})` : ''} — not a completion; what the ${decision} led to could not be confirmed.`;
                 }
                 else {
                     outcome = `The plan_review ${decision} was accepted by the engine (HTTP 200) but its effect is unconfirmed — final status: unknown (post-decide verification unavailable). Do not treat this as ${decision === 'approve' ? 'an approval that resumed the task' : 'a discarded plan'}.`;
@@ -648,10 +756,10 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     outcome = `This ${decision} was not applied. ${corruptStoredRowContent(where)}`;
                 }
                 else if (typeof status === 'number') {
-                    const msg = e instanceof Error ? e.message : String(e);
-                    hostLog('debug', `planReviewWire: ${decision} → ${status} ${msg.slice(0, 200)}`);
+                    const failureTexts = wireFailureTextsOf(e);
+                    hostLog('debug', `planReviewWire: ${decision} → ${status} ${failureTexts.log.slice(0, 200)}`);
                     effect = (status >= 400 && status < 500) || (typeof refusedCode === 'string' && isUnavailableFaceCode(refusedCode)) ? 'not_applied' : 'unconfirmed';
-                    outcome = `${`The plan_review decision failed: HTTP ${status} ${msg}`.trim()}${decideFailureNote(e)}`;
+                    outcome = `${`The plan_review decision failed: HTTP ${status} ${failureTexts.reason}`.trim()}${decideFailureNote(e)}`;
                 }
                 else if (noAnswer === 'time-limit' || noAnswer === 'deadline') {
                     hostLog('debug', `planReviewWire: ${decision} sent but no answer within the request time limit (task ${taskId})`);
@@ -821,9 +929,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) => {
@@ -831,15 +940,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)}`);
@@ -887,18 +1001,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,11 @@ 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 replayedApprovalClosesCardFrame(disposition: ReplayedApprovalDisposition | null | undefined): boolean;
+export declare function replayedApprovalSentence(disposition: ReplayedApprovalDisposition | undefined, opts?: {
+    readonly toolName?: string;
+}): string | undefined;