@sema-agent/client-core 0.83.3 → 0.83.5

package/dist/hitl/armedGateRegistry.js

@@ -1,5 +1,5 @@
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
-import { armedKeyFromQuestionId, PLAN_REVIEW_QUESTION_ID_PREFIX, planReviewQuestionId, REOPEN_ID_TAIL } from './gateIdentity.js';
+import { armedKeyFromQuestionId, PLAN_REVIEW_QUESTION_ID_PREFIX, planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId, } from './gateIdentity.js';
 const armedGatesByKey = createSessionSlot();
 const armedListenersByKey = createSessionSlot();
 const planReviewGenByKey = createSessionSlot();
@@ -149,10 +149,8 @@ export function notePlanReviewAnsweredFor(sessionKey, questionId) {
     if (noted.has(questionId))
         return;
     noted.add(questionId);
-    const base = questionId.slice(PLAN_REVIEW_QUESTION_ID_PREFIX.length);
-    const cut = base.indexOf(REOPEN_ID_TAIL);
-    const taskId = cut >= 0 ? base.slice(0, cut) : base;
-    if (taskId.length === 0)
+    const taskId = taskIdFromPlanReviewQuestionId(questionId);
+    if (taskId === undefined)
         return;
     clearArmedGateFor(sessionKey, planReviewArmedKeyFor(sessionKey, taskId));
     const gens = genMapFor(sessionKey);

package/dist/hitl/gateIdentity.d.ts

@@ -4,4 +4,5 @@ export declare function approvalCallKey(gatedCallId: string | undefined, taskId:
 export declare function askGateQuestionId(callKey: string): string;
 export declare function planReviewQuestionId(taskId: string): string;
 export declare function liveFrameCallKey(approvalId: string): string;
+export declare function taskIdFromPlanReviewQuestionId(questionId: string): string | undefined;
 export declare function armedKeyFromQuestionId(questionId: string): string;

package/dist/hitl/gateIdentity.js

@@ -14,6 +14,14 @@ export function planReviewQuestionId(taskId) {
 export function liveFrameCallKey(approvalId) {
     return `${HITL_FRAME_CALL_KEY_PREFIX}${approvalId}`;
 }
+export function taskIdFromPlanReviewQuestionId(questionId) {
+    if (typeof questionId !== 'string' || !questionId.startsWith(PLAN_REVIEW_QUESTION_ID_PREFIX))
+        return undefined;
+    const base = questionId.slice(PLAN_REVIEW_QUESTION_ID_PREFIX.length);
+    const cut = base.indexOf(REOPEN_ID_TAIL);
+    const taskId = cut >= 0 ? base.slice(0, cut) : base;
+    return taskId.length > 0 ? taskId : undefined;
+}
 export function armedKeyFromQuestionId(questionId) {
     const base = questionId.startsWith(HITL_ASK_QUESTION_ID_PREFIX)
         ? questionId.slice(HITL_ASK_QUESTION_ID_PREFIX.length)

package/dist/hitl/planReviewWire.d.ts

@@ -25,8 +25,12 @@ export declare function isPlanReviewPark(result: unknown): result is {
     sessionId?: string;
 };
 export declare function _resetArmedPlanReviewsForTest(): void;
+export type PlanReviewReopenTrigger = 'user' | 'automatic';
+export type PlanReviewGateInstanceReader = (taskId: string) => Promise<ReadonlySet<string> | null>;
+export declare function clearPlanReviewUserDismissals(sessionKey?: string): void;
 export declare function armPlanReviewApproval(result: unknown, sessionKey?: string, opts?: {
     submittedInPlanMode?: boolean;
+    readGateInstanceKeys?: PlanReviewGateInstanceReader;
 }): boolean;
 export type PlanReviewDecisionEffect = 'took_effect' | 'advanced' | 'still_parked' | 'not_sent' | 'not_applied' | 'unconfirmed';
 export interface PlanReviewOutcomeMeta {
@@ -43,6 +47,9 @@ export interface ReopenPlanReviewOpts {
     deliverDecision?: (taskId: string, decision: 'approve' | 'reject') => void | Promise<void>;
     sessionKey?: string;
     presentationReceiptMs?: number;
+    trigger?: PlanReviewReopenTrigger;
+    readGateInstanceKeys?: PlanReviewGateInstanceReader;
+    decisionHandedOver?: (taskId: string) => boolean;
 }
 export declare function _resetActiveReopenRespondersForTest(): void;
 export declare function reopenPlanReviewCard(taskId: string, opts: ReopenPlanReviewOpts & {

package/dist/hitl/planReviewWire.js

@@ -1,5 +1,6 @@
 import { publishQuestionFrame, publishQuestionFrameFor, registerLocalQuestionResponder, unregisterLocalQuestionResponder, hasLocalQuestionResponder, hasQuestionOverlayFor, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
+import { abortableSleep } from '../abortableSleep.js';
 import { makeEngineWireClient } from '../engineWireSdk.js';
 import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
@@ -7,9 +8,9 @@ import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTria
 import { decideFailureNote } from '../decideFailureNote.js';
 import { isPlanReviewModeAfter } from './hitlBridge.js';
 import { engineCapString } from '../engineCapsCache.js';
-import { planReviewQuestionId, REOPEN_ID_TAIL } from './gateIdentity.js';
+import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, registerArmedGateFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
-import { DEFAULT_SESSION_KEY } from '../sessionSlot.js';
+import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { PLAN_REVIEW_GATE_KIND } from '../adapter/activeRunSelfHeal.js';
 import { readRunTerminal, runTerminalGateKind } from '../runTerminal.js';
 const PLAN_REVIEW_RESUME_TIMEOUT_MS = 6 * 60 * 60_000;
@@ -84,6 +85,13 @@ function notePlanReviewAnsweredIfDecisiveFor(sessionKey, questionId, answer) {
     if (planReviewDecisionFromAnswer(answer ?? { answers: [] }, ALL_KNOWN_LABELS) === 'dismissed')
         return;
     notePlanReviewAnsweredFor(sessionKey, questionId);
+    const taskId = typeof questionId === 'string' ? taskIdFromPlanReviewQuestionId(questionId) : undefined;
+    if (taskId === undefined)
+        return;
+    const current = dismissalEntryFor(sessionKey, taskId);
+    if (current?.kind === 'dismissed' && current.questionId === questionId)
+        return;
+    notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
 }
 export function isPlanReviewPark(result) {
     const read = readRunTerminal(result);
@@ -99,6 +107,93 @@ const offerModeAfterByTask = new Map();
 export function _resetArmedPlanReviewsForTest() {
     armedPlanReviewTaskIds.clear();
     offerModeAfterByTask.clear();
+    planReviewDismissalsByKey.clear();
+}
+const ON_SCREEN = Promise.resolve(true);
+const planReviewDismissalsByKey = createSessionSlot();
+const MAX_DISMISSAL_ENTRIES_PER_SESSION = 32;
+const GATE_INSTANCE_READ_WAIT_MS = 1_500;
+function dismissalEntryFor(sessionKey, taskId) {
+    return planReviewDismissalsByKey.get(sessionKey)?.get(taskId);
+}
+function putDismissalEntry(sessionKey, taskId, entry) {
+    let ledger = planReviewDismissalsByKey.get(sessionKey);
+    if (ledger === undefined) {
+        ledger = new Map();
+        planReviewDismissalsByKey.set(sessionKey, ledger);
+    }
+    ledger.delete(taskId);
+    ledger.set(taskId, entry);
+    while (ledger.size > MAX_DISMISSAL_ENTRIES_PER_SESSION) {
+        const oldest = ledger.keys().next();
+        if (oldest.done === true)
+            break;
+        ledger.delete(oldest.value);
+    }
+}
+function planReviewUserDismissalMarkFor(sessionKey, taskId) {
+    const entry = dismissalEntryFor(sessionKey, taskId);
+    return entry?.kind === 'dismissed' ? entry : undefined;
+}
+function startGateInstanceRead(reader, taskId) {
+    if (typeof reader !== 'function')
+        return null;
+    let raw;
+    try {
+        raw = reader(taskId);
+    }
+    catch {
+        return null;
+    }
+    return Promise.resolve(raw).then((v) => {
+        try {
+            return v instanceof Set ? new Set(v) : null;
+        }
+        catch {
+            return null;
+        }
+    }, () => null);
+}
+async function boundedGateInstanceRead(p) {
+    if (p === null)
+        return null;
+    const ac = new AbortController();
+    try {
+        return await Promise.race([
+            p.then((v) => v, () => null),
+            abortableSleep(GATE_INSTANCE_READ_WAIT_MS, ac.signal).then(() => null),
+        ]);
+    }
+    finally {
+        ac.abort();
+    }
+}
+function notePlanReviewUserDismissalFor(sessionKey, taskId, reader, questionId) {
+    try {
+        putDismissalEntry(sessionKey, taskId, { kind: 'dismissed', closedGates: startGateInstanceRead(reader, taskId), questionId });
+    }
+    catch (err) {
+        hostLog('debug', `planReviewWire: could not record that the user closed the plan card for task ${taskId}: ${String(err)}`);
+    }
+}
+function notePlanReviewDecisiveAnswerFor(sessionKey, taskId) {
+    if (dismissalEntryFor(sessionKey, taskId) === undefined)
+        return;
+    putDismissalEntry(sessionKey, taskId, { kind: 'decided', closedGates: null });
+}
+function revokePlanReviewUserDismissal(sessionKey, taskId, mark) {
+    if (mark === undefined || mark.kind !== 'dismissed')
+        return;
+    if (dismissalEntryFor(sessionKey, taskId) === mark)
+        putDismissalEntry(sessionKey, taskId, { kind: 'reopened', closedGates: null, onScreen: ON_SCREEN });
+}
+function dropDismissalEntry(sessionKey, taskId, entry) {
+    const ledger = planReviewDismissalsByKey.get(sessionKey);
+    if (ledger?.get(taskId) === entry)
+        ledger.delete(taskId);
+}
+export function clearPlanReviewUserDismissals(sessionKey = DEFAULT_SESSION_KEY) {
+    planReviewDismissalsByKey.set(sessionKey, undefined);
 }
 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?';
@@ -158,9 +253,11 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             const shown = planReviewCardOptions(offerModeAfterByTask.get(taskId) === true).map(o => o.label);
             const choice = planReviewChoiceFromAnswer(answer, shown);
             if (choice === 'dismissed') {
+                notePlanReviewUserDismissalFor(DEFAULT_SESSION_KEY, taskId, opts?.readGateInstanceKeys, questionId);
                 return { ok: true };
             }
             const decided = choice.decision;
+            notePlanReviewDecisiveAnswerFor(DEFAULT_SESSION_KEY, taskId);
             const modeAfter = choice.decision === 'approve' ? choice.permissionModeAfter : undefined;
             offerModeAfterByTask.delete(taskId);
             notePlanReviewAnswered(questionId);
@@ -375,10 +472,245 @@ function retireActiveReopen(sessionKey, canonicalId) {
 }
 export function _resetActiveReopenRespondersForTest() {
     activeReopenResponders.clear();
+    reopenFlights.clear();
+}
+const reopenFlights = new Map();
+function joinReopenFlight(flight, taskId, receiptMs) {
+    hostLog('debug', `planReviewWire: reopen for task ${taskId} joined the card already on its way (no second card, its answer path kept)`);
+    if (receiptMs === undefined)
+        return { reopened: true, firstSight: false };
+    const ac = new AbortController();
+    return Promise.race([
+        flight.presented.then((v) => v === true, () => false),
+        abortableSleep(Math.max(0, receiptMs), ac.signal).then(() => false),
+    ]).then((presented) => {
+        ac.abort();
+        return presented ? { reopened: true, firstSight: false } : { reopened: false };
+    }, () => {
+        ac.abort();
+        return { reopened: false };
+    });
+}
+function mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs) {
+    const flightKey = `${sessionKey}\u0000${taskId}`;
+    const inFlight = reopenFlights.get(flightKey);
+    if (inFlight !== undefined)
+        return joinReopenFlight(inFlight, taskId, receiptMs);
+    let land = () => { };
+    const flight = {
+        presented: new Promise((resolve) => {
+            land = resolve;
+        }),
+    };
+    reopenFlights.set(flightKey, flight);
+    const settle = (presented) => {
+        land(presented);
+        if (reopenFlights.get(flightKey) === flight)
+            reopenFlights.delete(flightKey);
+    };
+    let verdict;
+    try {
+        verdict = mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs);
+    }
+    catch (e) {
+        settle(false);
+        throw e;
+    }
+    if (verdict instanceof Promise) {
+        return verdict.then((v) => {
+            settle(v.reopened === true);
+            return v;
+        }, (e) => {
+            settle(false);
+            throw e;
+        });
+    }
+    settle(verdict.reopened === true);
+    return verdict;
+}
+function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
+    const markBefore = dismissalEntryFor(sessionKey, taskId);
+    const settleOnReceipt = (receipt, firstSight) => receipt.then((presented) => {
+        if (!presented)
+            return { reopened: false };
+        revokePlanReviewUserDismissal(sessionKey, taskId, markBefore);
+        return { reopened: true, firstSight };
+    }, () => ({ reopened: false }));
+    const canonicalId = planReviewQuestionId(taskId);
+    const armedKey = planReviewArmedKeyFor(sessionKey, taskId);
+    const firstSight = !wasGateArmedFor(sessionKey, armedKey);
+    const mintFresh = opts?.mintFreshQuestionId !== false;
+    if (!mintFresh && hasLocalQuestionResponder(canonicalId)) {
+        hostLog('debug', `planReviewWire: reopen for task ${taskId} reusing the canonical responder (path=reopen-canonical)`);
+        if (opts?.deliverDecision !== undefined) {
+            hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.deliverDecision (answers route through the existing arm responder — documented exception)`);
+        }
+        retireActiveReopen(sessionKey, canonicalId);
+        if (receiptMs !== undefined) {
+            const receipt = waitForGateArmedFor(sessionKey, [canonicalId], receiptMs);
+            publishQuestionFrameFor(sessionKey, {
+                type: 'question',
+                questionId: canonicalId,
+                questions: planReviewQuestions(ARM_QUESTION, offerModeAfterByTask.get(taskId) === true),
+            });
+            return settleOnReceipt(receipt, firstSight);
+        }
+        publishQuestionFrameFor(sessionKey, {
+            type: 'question',
+            questionId: canonicalId,
+            questions: planReviewQuestions(ARM_QUESTION, offerModeAfterByTask.get(taskId) === true),
+        });
+        registerArmedGateFor(sessionKey, armedKey);
+        revokePlanReviewUserDismissal(sessionKey, taskId, markBefore);
+        return { reopened: true, firstSight };
+    }
+    retireActiveReopen(sessionKey, canonicalId);
+    if (unregisterLocalQuestionResponder(canonicalId)) {
+        hostLog('debug', `planReviewWire: reopen retired the canonical responder for task ${taskId} (single-active discipline)`);
+    }
+    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)`);
+    const deliver = opts?.deliverDecision ??
+        ((tid, decision) => {
+            hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
+            void decidePlanReview(tid, decision);
+        });
+    const activeKey = `${sessionKey}\u0000${canonicalId}`;
+    const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
+        unregister();
+        if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
+            activeReopenResponders.delete(activeKey);
+        }
+        const decided = planReviewDecisionFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
+        if (decided === 'dismissed') {
+            notePlanReviewUserDismissalFor(sessionKey, taskId, opts?.readGateInstanceKeys, questionId);
+            return { ok: true };
+        }
+        notePlanReviewDecisiveAnswerFor(sessionKey, taskId);
+        notePlanReviewAnsweredFor(sessionKey, questionId);
+        try {
+            await deliver(taskId, decided);
+        }
+        catch (e) {
+            hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
+        }
+        return { ok: true };
+    });
+    activeReopenResponders.set(activeKey, { questionId, unregister });
+    if (receiptMs !== undefined) {
+        const receipt = waitForGateArmedFor(sessionKey, [questionId], receiptMs);
+        publishQuestionFrameFor(sessionKey, {
+            type: 'question',
+            questionId,
+            questions: planReviewQuestions(REOPEN_QUESTION),
+        });
+        return settleOnReceipt(receipt, firstSight);
+    }
+    registerArmedGateFor(sessionKey, armedKey);
+    publishQuestionFrameFor(sessionKey, {
+        type: 'question',
+        questionId,
+        questions: planReviewQuestions(REOPEN_QUESTION),
+    });
+    revokePlanReviewUserDismissal(sessionKey, taskId, markBefore);
+    return { reopened: true, firstSight };
+}
+async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark) {
+    const refusedByUser = { reopened: false, dismissedByUser: true };
+    try {
+        let fresh = false;
+        const closed = await boundedGateInstanceRead(mark.closedGates);
+        if (closed !== null && closed.size > 0) {
+            const now = await boundedGateInstanceRead(startGateInstanceRead(opts.readGateInstanceKeys, taskId));
+            if (now !== null) {
+                for (const k of now) {
+                    if (!closed.has(k)) {
+                        fresh = true;
+                        break;
+                    }
+                }
+            }
+        }
+        let handedOver = false;
+        if (!decideInFlight.has(taskId)) {
+            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 (decideInFlight.has(taskId) || handedOver) {
+            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 };
+        }
+        const current = dismissalEntryFor(sessionKey, taskId);
+        if (current !== mark) {
+            hostLog('debug', `planReviewWire: reopen for task ${taskId} not minted — the dismissal record changed while it was being checked (stale evaluation)`);
+            return await staleDismissalVerdict(current, sessionKey, taskId, receiptMs);
+        }
+        if (!fresh) {
+            hostLog('debug', `planReviewWire: automatic reopen for task ${taskId} refused — the user closed this gate's card (no newer gate instance proven)`);
+            return refusedByUser;
+        }
+        let settle = () => { };
+        const reopening = {
+            kind: 'reopened',
+            closedGates: null,
+            onScreen: new Promise((resolve) => {
+                settle = resolve;
+            }),
+        };
+        putDismissalEntry(sessionKey, taskId, reopening);
+        let verdict = { reopened: false };
+        try {
+            if (hasQuestionOverlayFor(sessionKey))
+                verdict = await mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);
+        }
+        finally {
+            const presented = verdict.reopened === true;
+            settle(presented);
+            if (!presented)
+                dropDismissalEntry(sessionKey, taskId, reopening);
+        }
+        return verdict;
+    }
+    catch {
+        return refusedByUser;
+    }
+}
+async function staleDismissalVerdict(current, sessionKey, taskId, receiptMs) {
+    const ac = new AbortController();
+    const windowEnd = abortableSleep(Math.max(0, receiptMs), ac.signal).then(() => false);
+    try {
+        let entry = current;
+        for (let round = 0; round < 8; round++) {
+            if (entry?.kind === 'decided')
+                return { reopened: false, _sema_decisionInFlight: true };
+            if (entry?.kind === 'dismissed')
+                return { reopened: false, dismissedByUser: true };
+            if (entry?.kind !== 'reopened' || entry.onScreen === undefined)
+                return { reopened: false };
+            const onScreen = await Promise.race([
+                entry.onScreen.then((v) => v === true, () => false),
+                windowEnd,
+            ]);
+            const now = dismissalEntryFor(sessionKey, taskId);
+            if (now === entry) {
+                return onScreen ? { reopened: true, firstSight: !wasGateArmedFor(sessionKey, planReviewArmedKeyFor(sessionKey, taskId)) } : { reopened: false };
+            }
+            entry = now;
+        }
+        return { reopened: false };
+    }
+    finally {
+        ac.abort();
+    }
 }
 export function reopenPlanReviewCard(taskId, opts) {
     const receiptMs = opts?.presentationReceiptMs;
-    const settleOnReceipt = (receipt, firstSight) => receipt.then((presented) => (presented ? { reopened: true, firstSight } : { reopened: false }), () => ({ reopened: false }));
     try {
         if (typeof taskId !== 'string' || taskId.length === 0) {
             return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });
@@ -399,81 +731,18 @@ export function reopenPlanReviewCard(taskId, opts) {
                 '此处拒绝而不是照发 —— 照发会把这条会话的决断发到另一个槽上。');
             return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });
         }
-        const canonicalId = planReviewQuestionId(taskId);
-        const armedKey = planReviewArmedKeyFor(sessionKey, taskId);
-        const firstSight = !wasGateArmedFor(sessionKey, armedKey);
-        const mintFresh = opts?.mintFreshQuestionId !== false;
-        if (!mintFresh && hasLocalQuestionResponder(canonicalId)) {
-            hostLog('debug', `planReviewWire: reopen for task ${taskId} reusing the canonical responder (path=reopen-canonical)`);
-            if (opts?.deliverDecision !== undefined) {
-                hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.deliverDecision (answers route through the existing arm responder — documented exception)`);
-            }
-            retireActiveReopen(sessionKey, canonicalId);
-            if (receiptMs !== undefined) {
-                const receipt = waitForGateArmedFor(sessionKey, [canonicalId], receiptMs);
-                publishQuestionFrameFor(sessionKey, {
-                    type: 'question',
-                    questionId: canonicalId,
-                    questions: planReviewQuestions(ARM_QUESTION, offerModeAfterByTask.get(taskId) === true),
-                });
-                return settleOnReceipt(receipt, firstSight);
-            }
-            publishQuestionFrameFor(sessionKey, {
-                type: 'question',
-                questionId: canonicalId,
-                questions: planReviewQuestions(ARM_QUESTION, offerModeAfterByTask.get(taskId) === true),
-            });
-            registerArmedGateFor(sessionKey, armedKey);
-            return { reopened: true, firstSight };
-        }
-        retireActiveReopen(sessionKey, canonicalId);
-        if (unregisterLocalQuestionResponder(canonicalId)) {
-            hostLog('debug', `planReviewWire: reopen retired the canonical responder for task ${taskId} (single-active discipline)`);
-        }
-        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)`);
-        const deliver = opts?.deliverDecision ??
-            ((tid, decision) => {
-                hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
-                void decidePlanReview(tid, decision);
-            });
-        const activeKey = `${sessionKey}\u0000${canonicalId}`;
-        const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
-            unregister();
-            if (activeReopenResponders.get(activeKey)?.questionId === questionId) {
-                activeReopenResponders.delete(activeKey);
-            }
-            const decided = planReviewDecisionFromAnswer(answer, LEGACY_TWO_CHOICE_LABELS);
-            if (decided === 'dismissed') {
-                return { ok: true };
-            }
-            notePlanReviewAnsweredFor(sessionKey, questionId);
-            try {
-                await deliver(taskId, decided);
-            }
-            catch (e) {
-                hostLog('error', `planReviewWire: reopen decision delivery threw for task ${taskId}: ${String(e)}`);
+        const trigger = opts?.trigger === undefined ? undefined : opts.trigger === 'user' ? 'user' : 'automatic';
+        if (trigger === 'automatic') {
+            const mark = planReviewUserDismissalMarkFor(sessionKey, taskId);
+            if (mark !== undefined) {
+                if (receiptMs === undefined || opts === undefined) {
+                    hostLog('debug', `planReviewWire: automatic reopen for task ${taskId} refused — the user closed this gate's card`);
+                    return { reopened: false, dismissedByUser: true };
+                }
+                return reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark);
             }
-            return { ok: true };
-        });
-        activeReopenResponders.set(activeKey, { questionId, unregister });
-        if (receiptMs !== undefined) {
-            const receipt = waitForGateArmedFor(sessionKey, [questionId], receiptMs);
-            publishQuestionFrameFor(sessionKey, {
-                type: 'question',
-                questionId,
-                questions: planReviewQuestions(REOPEN_QUESTION),
-            });
-            return settleOnReceipt(receipt, firstSight);
         }
-        registerArmedGateFor(sessionKey, armedKey);
-        publishQuestionFrameFor(sessionKey, {
-            type: 'question',
-            questionId,
-            questions: planReviewQuestions(REOPEN_QUESTION),
-        });
-        return { reopened: true, firstSight };
+        return mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);
     }
     catch {
         return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,6 +1,7 @@
 import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode, type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
 import { type RuleStoreUnreadableKind } from '../gateVocabulary.js';
 import { type ApprovalMandateWord } from '../gateVocabulary.js';
+import type { ToolPermissionRequest } from '../seatContract.js';
 import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, DENIAL_LIMIT_KINDS } from '@sema-agent/sdk';
@@ -207,6 +208,7 @@ export declare function approvalIsMandated(v: ApprovalMandatedFacts | undefined
 export declare function readApprovalMandate(v: {
     readonly mandate?: string;
 } | undefined | null): ApprovalMandateWord | undefined;
+export declare function toolPermissionRequestAskBits(card: object | null | undefined): Pick<ToolPermissionRequest, 'mandated' | 'mandate' | 'origin' | 'ruleOffersAbsence'>;
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
 export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {

package/dist/hitl/toolApprovalWire.js

@@ -206,7 +206,7 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
             : {}),
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(pending.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
-        ...(pending.mandated === true ? { mandated: true } : {}),
+        ...(hasOwnStrictTrue(pending, 'mandated') ? { mandated: true } : {}),
         ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(pending)),
         ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(pending, 'origin')),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
@@ -403,9 +403,11 @@ const MANDATED_ABSENCE_WORD = 'mandated';
 export function approvalIsMandated(v) {
     if (v === null || v === undefined)
         return false;
-    if (v.mandated === true)
+    if (typeof v !== 'object')
+        return false;
+    if (hasOwnStrictTrue(v, 'mandated'))
         return true;
-    if (v.ruleOffersAbsence === MANDATED_ABSENCE_WORD)
+    if (readOwnNonEmptyString(v, 'ruleOffersAbsence') === MANDATED_ABSENCE_WORD)
         return true;
     return readApprovalMandate(v) !== undefined;
 }
@@ -415,6 +417,23 @@ export function readApprovalMandate(v) {
     const raw = v.mandate;
     return isApprovalMandateWord(raw) ? raw : undefined;
 }
+export function toolPermissionRequestAskBits(card) {
+    if (typeof card !== 'object' || card === null)
+        return {};
+    const mandated = hasOwnStrictTrue(card, 'mandated');
+    const mandate = readApprovalMandate(card);
+    const origin = readOwnNonEmptyString(card, 'origin');
+    const ruleOffersAbsence = readOwnNonEmptyString(card, 'ruleOffersAbsence');
+    return {
+        ...(mandated ? { mandated: true } : {}),
+        ...(mandate !== undefined ? { mandate } : {}),
+        ...(origin !== undefined ? { origin } : {}),
+        ...(ruleOffersAbsence !== undefined ? { ruleOffersAbsence } : {}),
+    };
+}
+function hasOwnStrictTrue(v, key) {
+    return Object.hasOwn(v, key) && v[key] === true;
+}
 function isToolApprovalDelegation(v) {
     if (v === null || typeof v !== 'object')
         return false;
@@ -840,7 +859,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(isWireRecordCarrier(frame.probeCause) ? { probeCause: frame.probeCause } : {}),
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
-        ...(frame.mandated === true ? { mandated: true } : {}),
+        ...(hasOwnStrictTrue(frame, 'mandated') ? { mandated: true } : {}),
         ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(frame)),
         ...(() => { const rc = readReadRootCandidate(frame.readRootCandidate); return rc !== undefined ? { readRootCandidate: rc } : {}; })(),
         ...(frame.inputHasBidi === true ? { inputHasBidi: true } : {}),