@sema-agent/client-core 0.104.1 → 0.105.0

package/dist/hitl/planReviewWire.js

@@ -15,10 +15,14 @@ import { refusalDeliveryOf } from './decisionRefusal.js';
 import { directFailureVerdictOf, directSafetyStopOf } from './approvalResolution.js';
 import { __resetDecisionLedgerForTests, decisionInFlightOf, decisionKeyInFlight, decisionLedgerKeysOf, decisionOpsWithKey, decisionReadMark, dropDecisionOp, latestDecisionHandedMark, markLatestDecisionNotApplied, openDecisionOp, planDecisionKey, readMarkOf, settleDecisionOp, settleDecisionOpsOnGateLeft, } from './decisionLedger.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
-import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
+import { freshPlanReviewQuestionId, planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
+import { isPlanReviewPark, mintPlanReviewCardFacts, notePlanReviewCardIssued, pausedCheckpointIdOf, planReviewCardFactsFrom, planReviewFactsCurrent, registeredPlanReviewCardFacts, samePlanReviewCardFacts, unknownBody, _resetPlanReviewRunsForTest, } from '../planReviewCardFacts.js';
+import { planReviewAskAgainKey, planReviewCardNoteRef, planReviewUnreadableNoteRef, takePlanReviewFacts, _resetPlanReviewFactsFlightsForTest, } from './planReviewCard.js';
+import { EN_MESSAGES } from '../i18n/messages.en.js';
+import { msg, renderMessage, DATA_FACE_LANGUAGE } from '../i18n/translate.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { PLAN_REVIEW_GATE_KIND, durableDecideLegOf } from '../adapter/activeRunSelfHeal.js';
+import { 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';
@@ -27,17 +31,33 @@ export const PLAN_REVIEW_APPROVE_AUTO_LABEL = 'Yes, and auto-accept edits';
 export const PLAN_REVIEW_APPROVE_MANUAL_LABEL = 'Yes, and manually approve edits';
 const APPROVE_LABEL = PLAN_REVIEW_APPROVE_LABEL;
 const REJECT_LABEL = PLAN_REVIEW_REJECT_LABEL;
-const LEGACY_TWO_CHOICE_LABELS = Object.freeze([PLAN_REVIEW_APPROVE_LABEL, PLAN_REVIEW_REJECT_LABEL]);
-const THREE_CHOICE_LABELS = Object.freeze([PLAN_REVIEW_APPROVE_AUTO_LABEL, PLAN_REVIEW_APPROVE_MANUAL_LABEL, PLAN_REVIEW_REJECT_LABEL]);
-const ANY_CARD_SHAPE_LABELS = Object.freeze([PLAN_REVIEW_APPROVE_AUTO_LABEL, PLAN_REVIEW_APPROVE_MANUAL_LABEL, PLAN_REVIEW_APPROVE_LABEL, PLAN_REVIEW_REJECT_LABEL]);
+const ASK_AGAIN_LABEL = EN_MESSAGES['approval.planReview.option.askAgain.label'];
+const REJECT_OPTION = Object.freeze({ label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it', choice: 'reject' });
+const OPTIONS_BY_SHAPE = Object.freeze({
+    two_choice: Object.freeze([
+        Object.freeze({ label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)', choice: 'approve' }),
+        REJECT_OPTION,
+    ]),
+    three_choice: Object.freeze([
+        Object.freeze({ label: PLAN_REVIEW_APPROVE_AUTO_LABEL, description: 'Resume and execute the plan; edits inside the working directory are not asked about one by one', choice: 'approve_accept_edits' }),
+        Object.freeze({ label: PLAN_REVIEW_APPROVE_MANUAL_LABEL, description: 'Resume and execute the plan; every edit still asks for approval', choice: 'approve_manual' }),
+        REJECT_OPTION,
+    ]),
+    withheld: Object.freeze([REJECT_OPTION, Object.freeze({ label: ASK_AGAIN_LABEL, description: EN_MESSAGES['approval.planReview.option.askAgain.description'], choice: 'ask_again' })]),
+});
+const LEGACY_TWO_CHOICE_LABELS = Object.freeze(OPTIONS_BY_SHAPE.two_choice.map((o) => o.label));
+const THREE_CHOICE_LABELS = Object.freeze(OPTIONS_BY_SHAPE.three_choice.map((o) => o.label));
+const WITHHELD_LABELS = Object.freeze(OPTIONS_BY_SHAPE.withheld.map((o) => o.label));
+const LABELS_BY_SHAPE = Object.freeze({ three_choice: THREE_CHOICE_LABELS, two_choice: LEGACY_TWO_CHOICE_LABELS, withheld: WITHHELD_LABELS });
+const ANY_CARD_SHAPE_LABELS = Object.freeze([...new Set([...THREE_CHOICE_LABELS, ...LEGACY_TWO_CHOICE_LABELS, ...WITHHELD_LABELS])]);
 export function planReviewDecisionFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
     const { choice } = readPlanReviewAnswer(answer, shownLabels);
-    if (choice === 'dismissed')
-        return 'dismissed';
+    if (typeof choice === 'string')
+        return choice;
     return choice.decision;
 }
-function readDismissed() {
-    return { choice: 'dismissed', noteIgnoredOnApprove: false };
+function readNonDecision(choice) {
+    return { choice, noteIgnoredOnApprove: false };
 }
 function freeTextNoteOf(entry) {
     try {
@@ -50,23 +70,25 @@ function freeTextNoteOf(entry) {
 }
 function readPlanReviewAnswer(answer, shownLabels) {
     const answers = answer?.answers;
-    if (!Array.isArray(answers) || answers.length !== 1)
-        return readDismissed();
+    if (!Array.isArray(answers) || answers.length === 0)
+        return readNonDecision('dismissed');
+    if (answers.length !== 1)
+        return readNonDecision('inadmissible');
     const entry = answers[0];
     const picked = entry?.selected;
     if (!Array.isArray(picked))
-        return readDismissed();
+        return readNonDecision('dismissed');
     const note = freeTextNoteOf(entry);
     if (picked.length === 0) {
         if (note === undefined || !shownLabels.includes(REJECT_LABEL))
-            return readDismissed();
+            return readNonDecision('dismissed');
         return { choice: { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
     }
     if (picked.length !== 1)
-        return readDismissed();
+        return readNonDecision('inadmissible');
     const selected = picked[0];
     if (typeof selected !== 'string' || !shownLabels.includes(selected))
-        return readDismissed();
+        return readNonDecision('inadmissible');
     const ignored = note !== undefined;
     if (selected === PLAN_REVIEW_APPROVE_AUTO_LABEL)
         return { choice: { decision: 'approve', permissionModeAfter: 'acceptEdits' }, noteIgnoredOnApprove: ignored };
@@ -76,7 +98,9 @@ function readPlanReviewAnswer(answer, shownLabels) {
         return { choice: { decision: 'approve' }, noteIgnoredOnApprove: ignored };
     if (selected === REJECT_LABEL)
         return { choice: note === undefined ? { decision: 'reject' } : { decision: 'reject', reason: note }, noteIgnoredOnApprove: false };
-    return readDismissed();
+    if (selected === ASK_AGAIN_LABEL)
+        return { choice: note === undefined ? { decision: 'ask_again' } : { decision: 'ask_again', reason: note }, noteIgnoredOnApprove: false };
+    return readNonDecision('inadmissible');
 }
 export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOICE_LABELS) {
     const { choice, noteIgnoredOnApprove } = readPlanReviewAnswer(answer, shownLabels);
@@ -85,21 +109,53 @@ export function planReviewChoiceFromAnswer(answer, shownLabels = LEGACY_TWO_CHOI
     return choice;
 }
 export function planReviewCardOptions(offerModeAfter) {
-    const reject = { label: REJECT_LABEL, description: 'Discard this plan and stay in plan mode to refine it' };
-    if (!offerModeAfter) {
-        return [{ label: APPROVE_LABEL, description: 'Resume the task now and execute the plan (runs to completion engine-side)' }, reject];
+    return OPTIONS_BY_SHAPE[offerModeAfter ? 'three_choice' : 'two_choice'].map(({ label, description }) => ({ label, description }));
+}
+export function planReviewOptionsOf(facts, opts) {
+    return OPTIONS_BY_SHAPE[cardShapeOf(facts, submittedInPlanModeOf(opts))];
+}
+function submittedInPlanModeOf(opts) {
+    try {
+        return readOwnDataValue(opts, 'submittedInPlanMode') === true;
+    }
+    catch {
+        return false;
+    }
+}
+function cardShapeOf(facts, submittedInPlanMode) {
+    try {
+        if (planReviewCardFactsFrom(facts)?.body.kind !== 'shown')
+            return 'withheld';
+    }
+    catch {
+        return 'withheld';
+    }
+    return submittedInPlanMode ? 'three_choice' : 'two_choice';
+}
+export function planReviewCardViewOf(frame, lang) {
+    try {
+        const questionId = readOwnDataNonEmptyString(frame ?? undefined, 'questionId');
+        const taskId = questionId === undefined ? undefined : taskIdFromPlanReviewQuestionId(questionId);
+        if (taskId === undefined)
+            return undefined;
+        const facts = planReviewCardFactsFrom(readOwnDataValue(frame ?? undefined, '_sema_planReview'));
+        if (facts === undefined || facts.taskId !== taskId) {
+            return Object.freeze({ options: OPTIONS_BY_SHAPE.withheld, note: renderMessage(planReviewUnreadableNoteRef(), lang) });
+        }
+        const shape = cardShapeOf(facts, frame !== null && frame !== undefined && offeredModeFromLabels(frame) === 'three_choice');
+        const noteRef = planReviewCardNoteRef(facts);
+        return Object.freeze({ facts, options: OPTIONS_BY_SHAPE[shape], ...(noteRef !== undefined ? { note: renderMessage(noteRef, lang) } : {}) });
+    }
+    catch {
+        return Object.freeze({ options: OPTIONS_BY_SHAPE.withheld, note: renderMessage(planReviewUnreadableNoteRef(), lang) });
     }
-    return [
-        { label: PLAN_REVIEW_APPROVE_AUTO_LABEL, description: 'Resume and execute the plan; edits inside the working directory are not asked about one by one' },
-        { label: PLAN_REVIEW_APPROVE_MANUAL_LABEL, description: 'Resume and execute the plan; every edit still asks for approval' },
-        reject,
-    ];
 }
 export function notePlanReviewAnsweredIfDecisive(questionId, answer) {
     notePlanReviewAnsweredIfDecisiveFor(DEFAULT_SESSION_KEY, questionId, answer);
 }
 function notePlanReviewAnsweredIfDecisiveFor(sessionKey, questionId, answer) {
-    if (planReviewDecisionFromAnswer(answer ?? { answers: [] }, planReviewShownLabelsOf(questionId) ?? ANY_CARD_SHAPE_LABELS) === 'dismissed')
+    const decided = planReviewDecisionFromAnswer(answer ?? { answers: [] }, planReviewShownLabelsOf(questionId) ?? ANY_CARD_SHAPE_LABELS);
+    if (decided === 'dismissed' || decided === 'inadmissible')
         return;
     notePlanReviewAnsweredFor(sessionKey, questionId);
     const taskId = typeof questionId === 'string' ? taskIdFromPlanReviewQuestionId(questionId) : undefined;
@@ -110,27 +166,7 @@ function notePlanReviewAnsweredIfDecisiveFor(sessionKey, questionId, answer) {
         return;
     notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
 }
-export function isPlanReviewPark(result) {
-    const read = readRunTerminal(result);
-    if (read === null || read.kind !== 'paused')
-        return false;
-    if (runTerminalGateKind(read) !== PLAN_REVIEW_GATE_KIND)
-        return false;
-    const taskId = result?.taskId;
-    return typeof taskId === 'string' && taskId.length > 0;
-}
-function pausedCheckpointIdOf(carrier) {
-    try {
-        const read = readRunTerminal(carrier);
-        if (read === null || read.kind !== 'paused')
-            return undefined;
-        const id = read.checkpointId;
-        return typeof id === 'string' && id.length > 0 ? id : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
+export { isPlanReviewPark };
 function pausedGateKindOf(carrier) {
     try {
         const read = readRunTerminal(carrier);
@@ -143,15 +179,15 @@ function pausedGateKindOf(carrier) {
         return undefined;
     }
 }
-const armedPlanReviewTaskIds = new Set();
-const offerModeAfterByTask = new Map();
+const armedPlanReviews = new Map();
 const offeredModeByQuestionId = new Map();
 const OFFERED_MODE_LEDGER_MAX = 64;
 export function _resetArmedPlanReviewsForTest() {
-    armedPlanReviewTaskIds.clear();
-    offerModeAfterByTask.clear();
+    armedPlanReviews.clear();
     offeredModeByQuestionId.clear();
     planReviewDismissalsByKey.clear();
+    _resetPlanReviewRunsForTest();
+    _resetPlanReviewFactsFlightsForTest();
 }
 const ON_SCREEN = Promise.resolve(true);
 const planReviewDismissalsByKey = createSessionSlot();
@@ -241,31 +277,40 @@ export function clearPlanReviewUserDismissals(sessionKey = DEFAULT_SESSION_KEY)
 }
 const ARM_QUESTION = 'The plan is ready for review. Approve it and start the implementation?';
 const REOPEN_QUESTION = 'This plan is still waiting for your review — it is what is holding this session. Approve it and start the implementation?';
-function planReviewQuestions(question, offerModeAfter = false) {
+function planReviewQuestions(question, shape) {
     return [
         {
             header: 'Plan review',
             question,
-            options: planReviewCardOptions(offerModeAfter),
+            options: OPTIONS_BY_SHAPE[shape].map(({ label, description }) => ({ label, description })),
             multiSelect: false,
         },
     ];
 }
-function planReviewQuestionFrame(questionId, question, offerModeAfter, reopened = false) {
-    if (!reopened) {
-        offeredModeByQuestionId.delete(questionId);
-        offeredModeByQuestionId.set(questionId, offerModeAfter);
-        while (offeredModeByQuestionId.size > OFFERED_MODE_LEDGER_MAX) {
-            const oldest = offeredModeByQuestionId.keys().next();
-            if (oldest.done === true)
-                break;
-            offeredModeByQuestionId.delete(oldest.value);
-        }
+function planReviewQuestionFrame(questionId, question, shape, facts) {
+    offeredModeByQuestionId.delete(questionId);
+    offeredModeByQuestionId.set(questionId, shape);
+    while (offeredModeByQuestionId.size > OFFERED_MODE_LEDGER_MAX) {
+        const oldest = offeredModeByQuestionId.keys().next();
+        if (oldest.done === true)
+            break;
+        offeredModeByQuestionId.delete(oldest.value);
     }
-    return { type: 'question', questionId, questions: planReviewQuestions(question, offerModeAfter) };
+    return {
+        type: 'question',
+        questionId,
+        questions: planReviewQuestions(question, shape),
+        ...(facts !== undefined ? { _sema_planReview: facts } : {}),
+    };
 }
-function publishPlanReviewCard(taskId) {
-    publishQuestionFrame(planReviewQuestionFrame(planReviewQuestionId(taskId), ARM_QUESTION, offerModeAfterByTask.get(taskId) === true));
+function publishArmedPlanReviewCard(inst) {
+    publishQuestionFrame(planReviewQuestionFrame(inst.questionId, ARM_QUESTION, inst.shape, inst.facts));
+}
+function retireArmedPlanReview(taskId, inst) {
+    if (armedPlanReviews.get(taskId) === inst)
+        armedPlanReviews.delete(taskId);
+    unregisterLocalQuestionResponder(inst.questionId);
+    publishQuestionFrame({ type: 'question_complete', questionId: inst.questionId });
 }
 const OFFERED_MODE_SCAN_MAX = 32;
 function ownElementsOf(v, max) {
@@ -280,6 +325,7 @@ function ownElementsOf(v, max) {
 function offeredModeFromLabels(card) {
     let modeAfter = false;
     let plain = false;
+    let askAgain = false;
     for (const q of ownElementsOf(readOwnDataValue(card, 'questions'), OFFERED_MODE_SCAN_MAX)) {
         if (typeof q !== 'object' || q === null)
             continue;
@@ -291,8 +337,12 @@ function offeredModeFromLabels(card) {
                 modeAfter = true;
             else if (label === APPROVE_LABEL)
                 plain = true;
+            else if (label === ASK_AGAIN_LABEL)
+                askAgain = true;
         }
     }
+    if (askAgain)
+        return modeAfter || plain ? undefined : 'withheld';
     if (modeAfter && !plain)
         return 'three_choice';
     if (plain && !modeAfter)
@@ -310,10 +360,7 @@ export function planReviewTaskIdFromQuestionId(questionId) {
 function offeredModeFromQuestionId(questionId) {
     if (taskIdFromPlanReviewQuestionId(questionId) === undefined)
         return 'unknown';
-    const recorded = offeredModeByQuestionId.get(questionId);
-    if (recorded !== undefined)
-        return recorded ? 'three_choice' : 'two_choice';
-    return questionId.includes(REOPEN_ID_TAIL) ? 'two_choice' : 'unknown';
+    return offeredModeByQuestionId.get(questionId) ?? 'unknown';
 }
 export function planReviewOfferedModeOf(card) {
     try {
@@ -337,14 +384,16 @@ export function planReviewShownLabelsOf(questionId) {
             return undefined;
         const recorded = offeredModeByQuestionId.get(questionId);
         if (recorded !== undefined)
-            return recorded ? THREE_CHOICE_LABELS : LEGACY_TWO_CHOICE_LABELS;
-        for (const t of armedPlanReviewTaskIds) {
-            if (planReviewQuestionId(t) === questionId)
-                return offerModeAfterByTask.get(t) === true ? THREE_CHOICE_LABELS : LEGACY_TWO_CHOICE_LABELS;
+            return LABELS_BY_SHAPE[recorded];
+        for (const inst of armedPlanReviews.values()) {
+            if (inst.questionId === questionId)
+                return LABELS_BY_SHAPE[inst.shape];
         }
-        if (taskIdFromPlanReviewQuestionId(questionId) === undefined)
-            return undefined;
-        return questionId.includes(REOPEN_ID_TAIL) ? LEGACY_TWO_CHOICE_LABELS : undefined;
+        for (const r of activeReopenResponders.values()) {
+            if (r.questionId === questionId)
+                return LABELS_BY_SHAPE[r.shape];
+        }
+        return undefined;
     }
     catch {
         return undefined;
@@ -384,28 +433,81 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             : undefined;
         const { taskId } = result;
         const gateBefore = pausedCheckpointIdOf(result);
+        if (gateBefore === undefined) {
+            presentArmedPlanReview(mintPlanReviewCardFacts(taskId, undefined, unknownBody('gate_unidentified')), delivery);
+            return true;
+        }
+        const taking = takePlanReviewFacts(DEFAULT_SESSION_KEY, taskId, gateBefore, () => planReviewLedgerSourceFor(wire, DEFAULT_SESSION_KEY));
+        if (taking.kind === 'now') {
+            presentArmedPlanReview(taking.taken.facts, delivery);
+            return true;
+        }
+        hostLog('debug', `planReviewWire: arm-await-ledger task=${taskId}`);
+        void taking.pending.then((taken) => {
+            try {
+                if (taken !== undefined && planReviewFactsCurrent(taken)) {
+                    presentArmedPlanReview(taken.facts, delivery);
+                    return;
+                }
+                const current = registeredPlanReviewCardFacts(DEFAULT_SESSION_KEY, taskId, gateBefore);
+                if (current !== undefined) {
+                    presentArmedPlanReview(current, delivery);
+                    return;
+                }
+                hostLog('debug', `planReviewWire: arm-superseded task=${taskId}`);
+            }
+            catch (e) {
+                if (armedTaskId !== undefined)
+                    armedPlanReviews.delete(armedTaskId);
+                hostLog('debug', `planReviewWire: arm-publish-failed task=${taskId} err=${String(e)}`);
+            }
+        });
+        return true;
+    }
+    catch (e) {
+        if (armedTaskId !== undefined)
+            armedPlanReviews.delete(armedTaskId);
+        hostLog('debug', `planReviewWire: arm failed (fail-soft): ${String(e)}`);
+        return false;
+    }
+    function presentArmedPlanReview(facts, delivery) {
+        if (!isPlanReviewPark(result))
+            return;
+        const { taskId } = result;
+        const gateBefore = pausedCheckpointIdOf(result);
+        const shape = cardShapeOf(facts, submittedInPlanModeOf(opts));
         retireActiveReopen(DEFAULT_SESSION_KEY, planReviewQuestionId(taskId));
-        if (armedPlanReviewTaskIds.has(taskId)) {
-            if (hasLocalQuestionResponder(planReviewQuestionId(taskId))) {
+        const prev = armedPlanReviews.get(taskId);
+        const hadArmedInstance = prev !== undefined;
+        if (prev !== undefined) {
+            if (hasLocalQuestionResponder(prev.questionId) &&
+                prev.checkpointId !== undefined &&
+                prev.checkpointId === gateBefore &&
+                samePlanReviewCardFacts(prev.facts, facts)) {
                 hostLog('debug', `planReviewWire: arm replayed — re-presenting the still-armed card for task ${taskId}`);
-                publishPlanReviewCard(taskId);
-                return true;
+                publishArmedPlanReviewCard(prev);
+                return;
             }
-            hostLog('debug', `planReviewWire: stale armed state for task ${taskId} (no local responder) — re-arming from scratch`);
-            armedPlanReviewTaskIds.delete(taskId);
+            hostLog('debug', `planReviewWire: arm-retire task=${taskId} card=${prev.questionId}`);
+            retireArmedPlanReview(taskId, prev);
         }
-        armedPlanReviewTaskIds.add(taskId);
+        const issuedBefore = notePlanReviewCardIssued(DEFAULT_SESSION_KEY, taskId);
+        const questionId = issuedBefore || hadArmedInstance ? freshPlanReviewQuestionId(taskId, reopenIdSuffix()) : planReviewQuestionId(taskId);
+        const instance = Object.freeze({ questionId, ...(gateBefore !== undefined ? { checkpointId: gateBefore } : {}), facts, shape });
+        armedPlanReviews.set(taskId, instance);
         armedTaskId = taskId;
-        const offerModeAfter = opts?.submittedInPlanMode === true;
-        if (offerModeAfter)
-            offerModeAfterByTask.set(taskId, true);
-        else
-            offerModeAfterByTask.delete(taskId);
-        const questionId = planReviewQuestionId(taskId);
-        const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+        let unregister = () => { };
+        const responder = async (_id, answer) => {
             const choice = planReviewAnswerChoiceOf(questionId, answer);
+            if (choice === 'inadmissible') {
+                if (armedPlanReviews.get(taskId) === instance && !hasLocalQuestionResponder(questionId))
+                    unregister = registerLocalQuestionResponder(questionId, responder);
+                hostLog('debug', `planReviewWire: answer-inadmissible card=${questionId}`);
+                return { ok: false, inadmissible: true };
+            }
             unregister();
-            armedPlanReviewTaskIds.delete(taskId);
+            if (armedPlanReviews.get(taskId) === instance)
+                armedPlanReviews.delete(taskId);
             if (choice === 'dismissed') {
                 notePlanReviewUserDismissalFor(DEFAULT_SESSION_KEY, taskId, opts?.readGateInstanceKeys, questionId);
                 return { ok: true };
@@ -413,25 +515,16 @@ 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 cardReason = choice.decision === 'approve' ? undefined : choice.reason;
             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, cardDelivery, gateBefore);
+            void decidePlanReviewFor(taskId, decided, modeAfter, cardDelivery, gateBefore, facts);
             return { ok: true };
-        });
-        publishPlanReviewCard(taskId);
+        };
+        unregister = registerLocalQuestionResponder(questionId, responder);
+        publishArmedPlanReviewCard(instance);
         hostLog('debug', `planReviewWire: approval card armed for parked plan (task ${taskId})`);
-        return true;
-    }
-    catch (e) {
-        if (armedTaskId !== undefined) {
-            armedPlanReviewTaskIds.delete(armedTaskId);
-            offerModeAfterByTask.delete(armedTaskId);
-        }
-        hostLog('debug', `planReviewWire: arm failed (fail-soft): ${String(e)}`);
-        return false;
     }
 }
 export function planReviewOutcomeTail(taskId, decision, effect, cause) {
@@ -588,7 +681,17 @@ function bodySaysReparked(body) {
         return false;
     }
 }
-async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, gateBefore) {
+function askAgainReasonOf(card, opts) {
+    try {
+        const sentence = renderMessage(msg(planReviewAskAgainKey(card === undefined ? undefined : planReviewCardFactsFrom(card))), DATA_FACE_LANGUAGE);
+        const note = opts !== null && typeof opts === 'object' ? opts.reason : undefined;
+        return typeof note === 'string' && note.trim() !== '' ? renderMessage(msg('approval.planReview.askAgain.withNote', { sentence, note }), DATA_FACE_LANGUAGE) : sentence;
+    }
+    catch {
+        return renderMessage(msg('approval.planReview.askAgain.unknown'), DATA_FACE_LANGUAGE);
+    }
+}
+async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, gateBefore, card) {
     if (typeof taskId === 'string' && planReviewOpsOf(taskId).some((op) => op.phase === 'posting')) {
         hostLog('error', `planReviewWire: decidePlanReview(${decision}) for task ${taskId} REFUSED — a decision for this task is already in flight (duplicate delivery latched)`);
         return;
@@ -619,7 +722,9 @@ async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts,
     const dispatchNo = ++decideDispatchSeq;
     hostLog('debug', `planReviewWire: decidePlanReview dispatch #${dispatchNo} task=${taskId} decision=${decision} mode=${permissionModeAfter ?? '-'}`);
     try {
-        await decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore);
+        const wireDecision = decision === 'ask_again' ? 'reject' : decision;
+        const wireOpts = decision === 'ask_again' ? { ...opts, reason: askAgainReasonOf(card, opts) } : opts;
+        await decidePlanReviewInner(taskId, wireDecision, permissionModeAfter, dispatchNo, releaseLatch, settle, wireOpts, gateBefore, decision);
     }
     finally {
         releaseLatch();
@@ -640,7 +745,7 @@ function planReviewClientsFor(resolved) {
         repull: () => resolved.make({ timeoutMs: 15_000 }),
     };
 }
-async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore) {
+async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore, semanticDecision) {
     let outcome;
     let effect = 'unconfirmed';
     let stillParkedCause;
@@ -839,7 +944,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     const onOutcome = opts?.onOutcome;
     settle(effect === 'not_sent' || effect === 'still_parked');
     try {
-        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}) });
+        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision: semanticDecision, effect, ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}) });
         if (!delivered) {
             if (onOutcome !== undefined) {
                 hostLog('debug', `planReviewWire: outcome queue port not installed for task ${taskId} — outcome handed to the host's onOutcome callback only`);
@@ -857,7 +962,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             onOutcome({
                 taskId,
                 dispatchNo,
-                decision,
+                decision: semanticDecision,
                 effect,
                 ...(effect === 'still_parked' && stillParkedCause !== undefined ? { cause: stillParkedCause } : {}),
                 detail: outcome,
@@ -907,8 +1012,8 @@ function joinReopenFlight(flight, taskId, receiptMs) {
         return refusedReopen('not_presented');
     });
 }
-function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs) {
-    const flightKey = `${sessionKey}\u0000${taskId}`;
+function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs, taken) {
+    const flightKey = `${sessionKey}\u0000${taskId}\u0000${taken.facts.checkpointId ?? ''}`;
     const inFlight = reopenFlights.get(flightKey);
     if (inFlight !== undefined)
         return joinReopenFlight(inFlight, taskId, receiptMs);
@@ -926,7 +1031,7 @@ function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs) {
     };
     let verdict;
     try {
-        verdict = mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs);
+        verdict = mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs, taken);
     }
     catch (e) {
         settle(false);
@@ -940,7 +1045,12 @@ function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs) {
         throw e;
     });
 }
-function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
+function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs, taken) {
+    if (!planReviewFactsCurrent(taken)) {
+        hostLog('debug', `planReviewWire: reopen-superseded task=${taskId}`);
+        return Promise.resolve(refusedReopen('not_presented'));
+    }
+    const facts = taken.facts;
     const markBefore = dismissalEntryFor(sessionKey, taskId);
     const settleOnReceipt = (receipt, firstSight) => receipt.then((presented) => {
         if (!presented)
@@ -952,20 +1062,27 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     const armedKey = planReviewArmedKeyFor(sessionKey, taskId);
     const firstSight = !wasGateArmedFor(sessionKey, armedKey);
     const mintFresh = opts?.mintFreshQuestionId !== false;
-    if (!mintFresh && hasLocalQuestionResponder(canonicalId)) {
+    const armed = armedPlanReviews.get(taskId);
+    if (!mintFresh &&
+        armed !== undefined &&
+        hasLocalQuestionResponder(armed.questionId) &&
+        armed.checkpointId !== undefined &&
+        armed.checkpointId === facts.checkpointId &&
+        samePlanReviewCardFacts(armed.facts, facts)) {
         hostLog('debug', `planReviewWire: reopen for task ${taskId} reusing the canonical responder (path=reopen-canonical)`);
         retireActiveReopen(sessionKey, canonicalId);
-        const receipt = waitForGateArmedFor(sessionKey, [canonicalId], receiptMs);
-        publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(canonicalId, ARM_QUESTION, offerModeAfterByTask.get(taskId) === true));
+        const receipt = waitForGateArmedFor(sessionKey, [armed.questionId], receiptMs);
+        publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(armed.questionId, ARM_QUESTION, armed.shape, armed.facts));
         return settleOnReceipt(receipt, firstSight);
     }
     retireActiveReopen(sessionKey, canonicalId);
-    if (unregisterLocalQuestionResponder(canonicalId)) {
-        hostLog('debug', `planReviewWire: reopen retired the canonical responder for task ${taskId} (single-active discipline)`);
+    const armedId = armed?.questionId ?? canonicalId;
+    if (unregisterLocalQuestionResponder(armedId)) {
+        hostLog('debug', `planReviewWire: reopen-retire-armed task=${taskId} card=${armedId}`);
     }
-    publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId: canonicalId });
-    const questionId = `${canonicalId}${REOPEN_ID_TAIL}${reopenIdSuffix()}`;
-    hostLog('debug', `planReviewWire: reopen for task ${taskId} minting a fresh card ${questionId} (path=reopen-fresh)`);
+    publishQuestionFrameFor(sessionKey, { type: 'question_complete', questionId: armedId });
+    const questionId = freshPlanReviewQuestionId(taskId, reopenIdSuffix());
+    hostLog('debug', `planReviewWire: path=reopen-fresh task=${taskId} card=${questionId}`);
     const delivery = opts?.wire !== undefined || opts?.onOutcome !== undefined
         ? { ...(opts.wire !== undefined ? { wire: opts.wire } : {}), ...(opts.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
         : undefined;
@@ -973,21 +1090,29 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         ((tid, decision, reason) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
             const withReason = reason === undefined ? delivery : { ...delivery, reason };
-            void (withReason === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, withReason));
+            void decidePlanReviewFor(tid, decision, undefined, withReason, parkedGateIdentityOf(withReason), facts);
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
-    const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+    let unregister = () => { };
+    const responder = async (_id, answer) => {
+        const choice = planReviewAnswerChoiceOf(questionId, answer);
+        if (choice === 'inadmissible') {
+            if (activeReopenResponders.get(activeKey)?.questionId === questionId && !hasLocalQuestionResponder(questionId)) {
+                unregister = registerLocalQuestionResponder(questionId, responder);
+            }
+            hostLog('debug', `planReviewWire: answer-inadmissible card=${questionId}`);
+            return { ok: false, inadmissible: true };
+        }
         unregister();
         if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
             activeReopenResponders.delete(activeKey);
         }
-        const choice = planReviewAnswerChoiceOf(questionId, answer);
         if (choice === 'dismissed') {
             notePlanReviewUserDismissalFor(sessionKey, taskId, opts?.readGateInstanceKeys, questionId);
             return { ok: true };
         }
         const decided = choice.decision;
-        const cardReason = choice.decision === 'reject' ? choice.reason : undefined;
+        const cardReason = choice.decision === 'approve' ? undefined : choice.reason;
         notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
         notePlanReviewAnsweredFor(sessionKey, questionId);
         try {
@@ -1000,10 +1125,12 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
             hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
         }
         return { ok: true };
-    });
-    activeReopenResponders.set(activeKey, { questionId, unregister });
+    };
+    const shape = cardShapeOf(facts, false);
+    unregister = registerLocalQuestionResponder(questionId, responder);
+    activeReopenResponders.set(activeKey, { questionId, unregister: () => unregister(), shape });
     const receipt = waitForGateArmedFor(sessionKey, [questionId], receiptMs);
-    publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(questionId, REOPEN_QUESTION, false, true));
+    publishQuestionFrameFor(sessionKey, planReviewQuestionFrame(questionId, REOPEN_QUESTION, shape, facts));
     return settleOnReceipt(receipt, firstSight);
 }
 function refusedReopen(cause) {
@@ -1015,7 +1142,7 @@ function noPresentationSurfaceVerdict(taskId, sessionKey) {
         `${JSON.stringify(sessionKey)} (onQuestionFrameFor), so the card has nowhere to render`);
     return verdict;
 }
-async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart) {
+async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart, taken) {
     const refusedByUser = { reopened: false, dismissedByUser: true };
     try {
         let fresh = false;
@@ -1061,7 +1188,7 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
         putDismissalEntry(sessionKey, taskId, reopening);
         let verdict = { reopened: false };
         try {
-            verdict = await mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);
+            verdict = await mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs, taken);
         }
         finally {
             const presented = verdict.reopened === true;
@@ -1140,15 +1267,110 @@ export function reopenPlanReviewCard(taskId, opts) {
                 '此处拒绝而不是照发 —— 照发会把这条会话的决断发到另一个槽上。');
             return Promise.resolve(refusedReopen('no_delivery_path'));
         }
+        const taking = takeReopenPlanReviewFacts(taskId, opts, sessionKey);
+        if (taking.kind === 'now')
+            return reopenWithPlanReviewFacts(taskId, opts, sessionKey, receiptMs, recheckReadStart, taking.taken);
+        return taking.pending.then((taken) => {
+            if (taken === undefined) {
+                hostLog('debug', `planReviewWire: reopen-superseded task=${taskId}`);
+                return refusedReopen('not_presented');
+            }
+            if (decisionInFlightOf({ gate: 'plan_review', taskId }, recheckReadStart)) {
+                hostLog('debug', `planReviewWire: reopen-refused-in-flight-after-read task=${taskId}`);
+                return { reopened: false, _sema_decisionInFlight: true };
+            }
+            return reopenWithPlanReviewFacts(taskId, opts, sessionKey, receiptMs, recheckReadStart, taken);
+        }, () => refusedReopen('internal_error'));
+    }
+    catch {
+        return Promise.resolve(refusedReopen('internal_error'));
+    }
+}
+function takeReopenPlanReviewFacts(taskId, opts, sessionKey) {
+    const raw = opts.checkpointId;
+    const checkpointId = typeof raw === 'string' && raw.length > 0 ? raw : undefined;
+    const wire = opts.mintFreshQuestionId === false ? undefined : opts.wire;
+    return takePlanReviewFacts(sessionKey, taskId, checkpointId, () => planReviewLedgerSourceFor(wire, sessionKey));
+}
+function reopenWithPlanReviewFacts(taskId, opts, sessionKey, receiptMs, recheckReadStart, taken) {
+    try {
         const trigger = opts.trigger === undefined ? undefined : opts.trigger === 'user' ? 'user' : 'automatic';
         if (trigger === 'automatic') {
             const mark = planReviewUserDismissalMarkFor(sessionKey, taskId);
             if (mark !== undefined)
-                return reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart);
+                return reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart, taken);
         }
-        return mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);
+        return mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs, taken);
     }
     catch {
         return Promise.resolve(refusedReopen('internal_error'));
     }
 }
+const PLAN_REVIEW_LEDGER_CLIENT_TIMEOUT_MS = 15_000;
+function usableLedgerClient(client) {
+    return clientHasVerbs(client, [['runs', 'get'], ['runs', 'events']]);
+}
+function planReviewLedgerSourceFor(wire, sessionKey) {
+    try {
+        const resolved = engineWireFor(wire, sessionKey, usableLedgerClient);
+        let client;
+        if (resolved.kind === 'injected')
+            client = resolved.client;
+        else if (resolved.kind === 'target')
+            client = resolved.make({ timeoutMs: PLAN_REVIEW_LEDGER_CLIENT_TIMEOUT_MS });
+        else
+            client = null;
+        if (client === null)
+            return undefined;
+        const c = client;
+        return {
+            runRow: (taskId, signal) => c.runs.get(taskId, { signal }),
+            frames: (taskId, signal) => c.runs.events(taskId, { signal }),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function abortSignalOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const s = v;
+    return typeof s.aborted === 'boolean' && typeof s.addEventListener === 'function' && typeof s.removeEventListener === 'function' ? v : undefined;
+}
+export async function readPlanReviewCardFacts(taskId, opts) {
+    if (typeof taskId !== 'string' || taskId.length === 0)
+        return mintPlanReviewCardFacts('', undefined, unknownBody('gate_unidentified'));
+    let checkpointId;
+    try {
+        checkpointId = readOwnDataNonEmptyString(opts, 'checkpointId');
+        const wire = readOwnDataValue(opts, 'wire');
+        const signal = abortSignalOf(readOwnDataValue(opts, 'signal'));
+        if (signal?.aborted === true)
+            return mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('unreadable'));
+        const taking = takePlanReviewFacts(DEFAULT_SESSION_KEY, taskId, checkpointId, () => planReviewLedgerSourceFor(wire, DEFAULT_SESSION_KEY), signal);
+        if (taking.kind === 'now')
+            return taking.taken.facts;
+        let taken;
+        if (signal === undefined)
+            taken = await taking.pending;
+        else {
+            let onAbort;
+            const aborted = new Promise((resolve) => {
+                onAbort = () => resolve(undefined);
+                signal.addEventListener('abort', onAbort, { once: true });
+            });
+            try {
+                taken = await Promise.race([taking.pending, aborted]);
+            }
+            finally {
+                if (onAbort !== undefined)
+                    signal.removeEventListener('abort', onAbort);
+            }
+        }
+        return taken?.facts ?? mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('unreadable'));
+    }
+    catch {
+        return mintPlanReviewCardFacts(taskId, checkpointId, unknownBody('unreadable'));
+    }
+}