@sema-agent/client-core 0.84.0 → 0.85.0

package/dist/hitl/planReviewWire.js

@@ -1,12 +1,12 @@
 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 { abortableSleep, settleWithinDeadline } from '../abortableSleep.js';
+import { clientHasVerbs, engineWireFor, noAnswerKindOf, sendOnce } from '../engineWireFor.js';
 import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { isPlanReviewModeAfter } from './hitlBridge.js';
+import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { engineCapString } from '../engineCapsCache.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
 import { notePlanReviewAnswered, notePlanReviewAnsweredFor, planReviewArmedKeyFor, registerArmedGateFor, waitForGateArmedFor, wasGateArmedFor, } from './armedGateRegistry.js';
@@ -102,6 +102,18 @@ export function isPlanReviewPark(result) {
     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;
+    }
+}
 const armedPlanReviewTaskIds = new Set();
 const offerModeAfterByTask = new Map();
 export function _resetArmedPlanReviewsForTest() {
@@ -225,9 +237,21 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
                 '此处拒绝而不是回落默认槽 —— 回落会把这条会话的决断带着别的槽的 baseUrl/token/principal 发出去。');
             return false;
         }
-        if (!engineWireTarget())
+        const wire = opts?.wire;
+        if (wire !== undefined) {
+            if (!usablePlanReviewWireClient(wire.client)) {
+                hostLog('error', 'planReviewWire: plan_review card NOT armed — the engine client supplied by the host is not usable (needs assistant.planReview and runs.get)');
+                return false;
+            }
+        }
+        else if (!engineWireTarget()) {
             return false;
+        }
+        const delivery = wire !== undefined || opts?.onOutcome !== undefined
+            ? { ...(wire !== undefined ? { wire } : {}), ...(opts?.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
+            : undefined;
         const { taskId } = result;
+        const gateBefore = pausedCheckpointIdOf(result);
         retireActiveReopen(DEFAULT_SESSION_KEY, planReviewQuestionId(taskId));
         if (armedPlanReviewTaskIds.has(taskId)) {
             if (hasLocalQuestionResponder(planReviewQuestionId(taskId))) {
@@ -240,8 +264,9 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
         }
         armedPlanReviewTaskIds.add(taskId);
         armedTaskId = taskId;
+        const capsBaseUrl = wire !== undefined ? wire.capsBaseUrl : engineWireTarget()?.baseUrl;
         const offerModeAfter = opts?.submittedInPlanMode === true &&
-            versionSupportsPlanReviewModeAfter(engineCapString(engineWireTarget()?.baseUrl, 'version')) === 'supported';
+            versionSupportsPlanReviewModeAfter(engineCapString(capsBaseUrl, 'version')) === 'supported';
         if (offerModeAfter)
             offerModeAfterByTask.set(taskId, true);
         else
@@ -262,7 +287,7 @@ export function armPlanReviewApproval(result, sessionKey, opts) {
             offerModeAfterByTask.delete(taskId);
             notePlanReviewAnswered(questionId);
             hostLog('debug', `planReviewWire: arm responder delivering ${decided} for task ${taskId} (path=arm)`);
-            void decidePlanReview(taskId, decided, modeAfter);
+            void decidePlanReviewFor(taskId, decided, modeAfter, delivery, gateBefore);
             return { ok: true };
         });
         publishPlanReviewCard(taskId);
@@ -296,73 +321,211 @@ export function planReviewOutcomeTail(taskId, decision, effect) {
             return `Do not state the result as fact: tell the user the ${decision} was submitted but its effect could not be confirmed; TaskOutput("${taskId}") shows where the task stands.`;
     }
 }
-const decideInFlight = new Map();
+function planReviewDecisionTimedOutOutcome(decision) {
+    return (`The plan_review ${decision} was sent, but no answer came back from the engine within the time limit this host allows for it — ` +
+        `it may have taken effect (${decision === 'approve' ? 'an approval keeps the engine busy until the resumed work finishes' : 'the engine may still be applying it'}).`);
+}
+function planReviewDecisionConnectionLostOutcome(decision) {
+    return (`The plan_review ${decision} got no answer from the engine: the connection failed before an answer came back, and the request may already have reached the engine — ` +
+        `it may have taken effect (${decision === 'approve' ? 'an approval keeps the engine busy until the resumed work finishes' : 'the engine may still be applying it'}).`);
+}
+function planReviewAdvancedOutcome(decision, postStatus) {
+    return (`The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
+        `(post-decide status: ${postStatus}) — the next approval card will surface it; this is not a completion yet.`);
+}
+function usablePlanReviewWireClient(client) {
+    if (client === null || typeof client !== 'object')
+        return false;
+    return clientHasVerbs(client, [['assistant', 'planReview'], ['runs', 'get']]);
+}
+const PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS = 15_000;
+const planReviewDecisionOps = [];
+const MAX_PLAN_REVIEW_DECISION_OPS = 32;
+let planReviewLedgerClock = 0;
 let decideDispatchSeq = 0;
+function planReviewOpsOf(taskId) {
+    return planReviewDecisionOps.filter((op) => op.taskId === taskId);
+}
+function settlePlanReviewDecisionOp(op) {
+    if (op.settledAt === null)
+        op.settledAt = ++planReviewLedgerClock;
+}
+function pushPlanReviewDecisionOp(op) {
+    planReviewDecisionOps.push(op);
+    while (planReviewDecisionOps.length > MAX_PLAN_REVIEW_DECISION_OPS) {
+        let victim = planReviewDecisionOps.findIndex((o) => o.settledAt !== null && !o.ownCallOpen);
+        if (victim < 0)
+            victim = planReviewDecisionOps.findIndex((o) => o !== op && o.phase === 'handed');
+        if (victim < 0)
+            break;
+        planReviewDecisionOps.splice(victim, 1);
+    }
+}
+function dropPlanReviewDecisionOp(op) {
+    const i = planReviewDecisionOps.indexOf(op);
+    if (i >= 0)
+        planReviewDecisionOps.splice(i, 1);
+}
+export function notePlanReviewDecisionHandedOver(taskId) {
+    if (typeof taskId !== 'string' || taskId === '')
+        return null;
+    if (planReviewDecisionOps.some((op) => op.taskId === taskId && op.settledAt === null))
+        return null;
+    const op = { taskId, handedAt: ++planReviewLedgerClock, settledAt: null, phase: 'handed', notApplied: false, ownCallOpen: false };
+    pushPlanReviewDecisionOp(op);
+    return {
+        settle: () => {
+            if (op.phase !== 'handed')
+                return;
+            settlePlanReviewDecisionOp(op);
+        },
+        revoke: () => {
+            if (op.phase !== 'handed' || op.settledAt !== null)
+                return;
+            dropPlanReviewDecisionOp(op);
+        },
+    };
+}
+export function planReviewPendingReadMark() {
+    return ++planReviewLedgerClock;
+}
+export function planReviewDecisionInFlight(taskId, pendingReadStartedAt) {
+    if (typeof taskId !== 'string' || taskId === '')
+        return false;
+    const mark = typeof pendingReadStartedAt === 'number' && Number.isFinite(pendingReadStartedAt) ? pendingReadStartedAt : undefined;
+    return planReviewDecisionOps.some((op) => op.taskId === taskId && (op.settledAt === null || (mark !== undefined && op.settledAt > mark && !op.notApplied)));
+}
+export function notePlanReviewDecisionNotApplied(taskId) {
+    if (typeof taskId !== 'string' || taskId === '')
+        return;
+    const ops = planReviewOpsOf(taskId);
+    if (ops.some((op) => op.settledAt === null))
+        return;
+    let latest;
+    for (const op of ops)
+        if (latest === undefined || op.handedAt > latest.handedAt)
+            latest = op;
+    if (latest !== undefined)
+        latest.notApplied = true;
+}
+export function notePlanReviewGateLeft(taskId) {
+    if (typeof taskId !== 'string' || taskId === '')
+        return;
+    for (const op of planReviewOpsOf(taskId))
+        settlePlanReviewDecisionOp(op);
+}
+export function latestPlanReviewDecisionMark(taskId) {
+    if (typeof taskId !== 'string' || taskId === '')
+        return null;
+    let mark = null;
+    for (const op of planReviewOpsOf(taskId))
+        if (mark === null || op.handedAt > mark)
+            mark = op.handedAt;
+    return mark;
+}
 export function __resetPlanReviewDecisionLatchForTests() {
-    decideInFlight.clear();
+    planReviewDecisionOps.length = 0;
 }
-export async function decidePlanReview(taskId, decision, permissionModeAfter) {
-    if (decideInFlight.has(taskId)) {
+export async function decidePlanReview(taskId, decision, permissionModeAfter, opts) {
+    return decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, undefined);
+}
+async function decidePlanReviewFor(taskId, decision, permissionModeAfter, opts, gateBefore) {
+    if (typeof taskId === 'string' && planReviewDecisionOps.some((op) => op.taskId === taskId && 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;
     }
-    const token = {};
-    decideInFlight.set(taskId, token);
+    let op = planReviewDecisionOps.find((o) => o.taskId === taskId && o.phase === 'handed' && o.settledAt === null);
+    if (op === undefined) {
+        op = { taskId: typeof taskId === 'string' ? taskId : String(taskId), handedAt: ++planReviewLedgerClock, settledAt: null, phase: 'posting', notApplied: false, ownCallOpen: true };
+        pushPlanReviewDecisionOp(op);
+    }
+    else {
+        op.phase = 'posting';
+        op.ownCallOpen = true;
+    }
+    const mine = op;
     const releaseLatch = () => {
-        if (decideInFlight.get(taskId) === token)
-            decideInFlight.delete(taskId);
+        if (mine.phase === 'posting')
+            mine.phase = 'landed';
+    };
+    const settle = (notApplied) => {
+        if (notApplied)
+            mine.notApplied = true;
+        settlePlanReviewDecisionOp(mine);
     };
     const dispatchNo = ++decideDispatchSeq;
     hostLog('debug', `planReviewWire: decidePlanReview dispatch #${dispatchNo} task=${taskId} decision=${decision} mode=${permissionModeAfter ?? '-'}`);
     try {
-        await decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch);
+        await decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore);
     }
     finally {
         releaseLatch();
+        settlePlanReviewDecisionOp(mine);
+        mine.ownCallOpen = false;
     }
 }
-async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch) {
+function planReviewClientsFor(resolved) {
+    if (resolved.kind === 'injected') {
+        const client = resolved.client;
+        return { decide: client, repull: () => client };
+    }
+    const decide = resolved.make({ timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS });
+    if (!decide)
+        return null;
+    return {
+        decide,
+        repull: () => resolved.make({ timeoutMs: 15_000 }),
+    };
+}
+async function decidePlanReviewInner(taskId, decision, permissionModeAfter, dispatchNo, releaseLatch, settle, opts, gateBefore) {
     let outcome;
     let effect = 'unconfirmed';
-    const cfg = engineWireTarget();
+    let stillParkedProven = false;
+    let statusSeen;
+    const wire = opts?.wire;
+    const resolved = engineWireFor(wire, DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
     const badMode = permissionModeAfter !== undefined && (decision !== 'approve' || !isPlanReviewModeAfter(permissionModeAfter));
     if (badMode) {
         hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter is only valid with approve and must be "default" or "acceptEdits"`);
         effect = 'not_sent';
         outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid for this decision (it only applies to an approval, and must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
     }
-    else if (!cfg) {
+    else if (resolved.kind === 'no-target') {
         hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
         effect = 'not_sent';
         outcome = `The plan_review ${decision} could NOT be sent: no engine connection is configured on this host. Tell the user plainly that the decision did not go through.`;
     }
+    else if (resolved.kind === 'injected-unusable') {
+        hostLog('error', `planReviewWire: ${decision} NOT sent — the engine client supplied by the host is not usable (needs assistant.planReview and runs.get)`);
+        effect = 'not_sent';
+        outcome = `The plan_review ${decision} could NOT be sent: the engine client supplied by the host cannot send it (it lacks the plan-review verb). Tell the user plainly that the decision did not go through.`;
+    }
     else {
-        const client = makeEngineWireClient({
-            baseUrl: cfg.baseUrl,
-            ...(cfg.token ? { token: cfg.token } : {}),
-            principal: cfg.principal,
-            timeoutMs: PLAN_REVIEW_RESUME_TIMEOUT_MS,
-        });
-        if (!client) {
+        const clients = planReviewClientsFor(resolved);
+        if (!clients) {
             hostLog('error', `planReviewWire: ${decision} NOT sent — makeEngineWireClient() returned null`);
-            effect = 'not_sent';
             outcome = `The plan_review ${decision} could NOT be sent: the engine client could not be constructed. Tell the user plainly that the decision did not go through.`;
+            effect = 'not_sent';
         }
         else {
+            const client = clients.decide;
             try {
                 const mode = isPlanReviewModeAfter(permissionModeAfter) ? permissionModeAfter : undefined;
+                const reason = denyReasonForWire(opts?.reason, `plan-review ${taskId}`);
                 const reqBody = { decision };
+                if (reason !== undefined)
+                    reqBody.reason = reason;
                 if (mode !== undefined)
                     reqBody.permissionModeAfter = mode;
                 let body;
                 try {
-                    body = await client.assistant.planReview(taskId, reqBody);
+                    body = await sendOnce(undefined, () => client.assistant.planReview(taskId, reqBody));
                 }
                 catch (e1) {
                     const conflict = e1;
                     if (mode === 'default' && conflict?.status === 400 && conflict?.errorCode === 'request.field_conflict') {
                         hostLog('debug', 'planReviewWire: permissionModeAfter "default" refused as not applicable — re-sending the approval without the key (same meaning)');
-                        body = await client.assistant.planReview(taskId, { decision });
+                        body = await sendOnce(undefined, () => client.assistant.planReview(taskId, reason !== undefined ? { decision, reason } : { decision }));
                     }
                     else {
                         throw e1;
@@ -373,22 +536,39 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 }
                 hostLog('debug', `planReviewWire: ${decision} → ok (dispatch #${dispatchNo}) ${JSON.stringify(body).slice(0, 200)}`);
                 let postStatus;
+                let gateAfter;
                 try {
-                    const probe = makeEngineWireClient({
-                        baseUrl: cfg.baseUrl,
-                        ...(cfg.token ? { token: cfg.token } : {}),
-                        principal: cfg.principal,
-                        timeoutMs: 15_000,
-                    });
-                    const post = probe ? (await probe.runs.get(taskId)) : null;
-                    postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                    const probe = clients.repull();
+                    if (probe) {
+                        let post;
+                        if (wire !== undefined) {
+                            const got = await settleWithinDeadline(PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS, (signal) => probe.runs.get(taskId, { signal }));
+                            if (got.kind === 'error')
+                                throw new Error(got.detail);
+                            if (got.kind === 'deadline')
+                                throw new Error(`post-decide status re-pull passed its ${PLAN_REVIEW_INJECTED_REPULL_TIMEOUT_MS} ms deadline`);
+                            post = got.value;
+                        }
+                        else {
+                            post = (await probe.runs.get(taskId));
+                        }
+                        postStatus = typeof post?.status === 'string' ? post.status : undefined;
+                        gateAfter = pausedCheckpointIdOf(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);
-                if (effective === 'needs_review') {
+                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;
                     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). ` +
@@ -396,9 +576,7 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 }
                 else if (effective === 'suspended') {
                     effect = 'advanced';
-                    outcome =
-                        `The plan was ${decision === 'approve' ? 'approved' : 'rejected'} and the task advanced to a NEW approval gate ` +
-                            `(post-decide status: suspended) — the next approval card will surface it; this is not a completion yet.`;
+                    outcome = planReviewAdvancedOutcome(decision, 'suspended');
                 }
                 else if (effective !== undefined) {
                     effect = 'took_effect';
@@ -411,9 +589,11 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
             catch (e) {
                 const status = e?.status;
                 const refusedCode = e?.errorCode;
+                const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
                 if (status === 400 && refusedCode === 'request.field_conflict' && permissionModeAfter === 'acceptEdits') {
                     hostLog('debug', 'planReviewWire: approve + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode');
                     effect = 'still_parked';
+                    stillParkedProven = true;
                     outcome =
                         'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
                             'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.';
@@ -437,21 +617,46 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     effect = status >= 400 && status < 500 ? 'not_applied' : 'unconfirmed';
                     outcome = `${`The plan_review decision failed: HTTP ${status} ${msg}`.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})`);
+                    outcome = planReviewDecisionTimedOutOutcome(decision);
+                }
+                else if (noAnswer === 'connection-lost') {
+                    hostLog('debug', `planReviewWire: ${decision} got no answer — the connection failed and it cannot be told whether the request reached the engine (task ${taskId})`);
+                    outcome = planReviewDecisionConnectionLostOutcome(decision);
+                }
                 else {
                     outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
                 }
             }
         }
     }
+    const tail = planReviewOutcomeTail(taskId, decision, effect);
+    const prompt = `<plan-review-outcome>\n${outcome}\n${tail}\n</plan-review-outcome>`;
+    const onOutcome = opts?.onOutcome;
+    settle(effect === 'not_sent' || (effect === 'still_parked' && stillParkedProven));
     try {
-        const delivered = enqueuePlanReviewOutcome(`<plan-review-outcome>\n${outcome}\n${planReviewOutcomeTail(taskId, decision, effect)}\n</plan-review-outcome>`, { taskId, dispatchNo, decision, effect });
+        const delivered = enqueuePlanReviewOutcome(prompt, { taskId, dispatchNo, decision, effect });
         if (!delivered) {
-            hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+            if (onOutcome !== undefined) {
+                hostLog('debug', `planReviewWire: outcome queue port not installed for task ${taskId} — outcome handed to the host's onOutcome callback only`);
+            }
+            else {
+                hostLog('error', `planReviewWire: outcome enqueue MISSED (queue port not installed or lacks enqueueMetaPrompt) for task ${taskId} — model will not learn the ${decision} result`);
+            }
         }
     }
     catch (e) {
         hostLog('debug', `planReviewWire: outcome enqueue threw: ${String(e)}`);
     }
+    if (onOutcome !== undefined) {
+        try {
+            onOutcome({ taskId, dispatchNo, decision, effect, detail: outcome, tail, prompt, ...(statusSeen !== undefined ? { status: statusSeen } : {}) });
+        }
+        catch (e) {
+            hostLog('debug', `planReviewWire: onOutcome callback threw for task ${taskId} (ignored): ${String(e)}`);
+        }
+    }
 }
 function reopenIdSuffix() {
     return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
@@ -545,6 +750,9 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
         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)`);
         }
+        if (opts?.wire !== undefined || opts?.onOutcome !== undefined) {
+            hostLog('debug', `planReviewWire: reopen canonical-reuse branch for task ${taskId} ignores opts.wire / opts.onOutcome (answers route through the existing arm responder and the wire it was armed with — documented exception)`);
+        }
         retireActiveReopen(sessionKey, canonicalId);
         if (receiptMs !== undefined) {
             const receipt = waitForGateArmedFor(sessionKey, [canonicalId], receiptMs);
@@ -571,10 +779,13 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     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 delivery = opts?.wire !== undefined || opts?.onOutcome !== undefined
+        ? { ...(opts.wire !== undefined ? { wire: opts.wire } : {}), ...(opts.onOutcome !== undefined ? { onOutcome: opts.onOutcome } : {}) }
+        : undefined;
     const deliver = opts?.deliverDecision ??
         ((tid, decision) => {
             hostLog('debug', `planReviewWire: reopen responder delivering ${decision} for task ${tid} (path=reopen-default)`);
-            void decidePlanReview(tid, decision);
+            void (delivery === undefined ? decidePlanReview(tid, decision) : decidePlanReview(tid, decision, undefined, delivery));
         });
     const activeKey = `${sessionKey}\u0000${canonicalId}`;
     const unregister = registerLocalQuestionResponder(questionId, async (_id, answer) => {
@@ -616,7 +827,7 @@ function mintPlanReviewReopenCard(taskId, opts, sessionKey, receiptMs) {
     revokePlanReviewUserDismissal(sessionKey, taskId, markBefore);
     return { reopened: true, firstSight };
 }
-async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark) {
+async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart) {
     const refusedByUser = { reopened: false, dismissedByUser: true };
     try {
         let fresh = false;
@@ -633,7 +844,8 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
             }
         }
         let handedOver = false;
-        if (!decideInFlight.has(taskId)) {
+        const ledgerSaysInFlight = planReviewDecisionInFlight(taskId, recheckReadStart);
+        if (!ledgerSaysInFlight) {
             try {
                 handedOver = opts.decisionHandedOver?.(taskId) === true;
             }
@@ -642,7 +854,7 @@ async function reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, ma
                 return { reopened: false };
             }
         }
-        if (decideInFlight.has(taskId) || handedOver) {
+        if (ledgerSaysInFlight || 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 };
         }
@@ -715,16 +927,19 @@ export function reopenPlanReviewCard(taskId, opts) {
         if (typeof taskId !== 'string' || taskId.length === 0) {
             return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });
         }
-        if (decideInFlight.has(taskId)) {
+        const readStart = typeof opts?.pendingReadStartedAt === 'number' && Number.isFinite(opts.pendingReadStartedAt) ? opts.pendingReadStartedAt : undefined;
+        if (planReviewDecisionInFlight(taskId, readStart)) {
             hostLog('debug', `planReviewWire: reopen for task ${taskId} refused — a decision for this task is in flight (its answer is still being delivered)`);
             const refused = { reopened: false, _sema_decisionInFlight: true };
             return receiptMs === undefined ? refused : Promise.resolve(refused);
         }
+        const guardStartedAt = planReviewPendingReadMark();
+        const recheckReadStart = readStart === undefined ? guardStartedAt : Math.min(readStart, guardStartedAt);
         const sessionKey = opts?.sessionKey ?? DEFAULT_SESSION_KEY;
         if (!hasQuestionOverlayFor(sessionKey)) {
             return receiptMs === undefined ? { reopened: false } : Promise.resolve({ reopened: false });
         }
-        if (sessionKey !== DEFAULT_SESSION_KEY && opts?.deliverDecision === undefined) {
+        if (sessionKey !== DEFAULT_SESSION_KEY && opts?.deliverDecision === undefined && opts?.wire === undefined) {
             hostLog('error', `planReviewWire: plan_review 卡未重开 —— sessionKey=${JSON.stringify(sessionKey)} 是非默认槽,` +
                 '而缺省决断投递口(decidePlanReview)今天固定打默认槽的 baseUrl/token/principal。' +
                 '整条链转 keyed 之前,非默认槽要重开请自带 deliverDecision(按本槽投递);' +
@@ -739,7 +954,7 @@ export function reopenPlanReviewCard(taskId, opts) {
                     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 reopenAfterDismissalCheck(taskId, opts, sessionKey, receiptMs, mark, recheckReadStart);
             }
         }
         return mintPlanReviewReopen(taskId, opts, sessionKey, receiptMs);

package/dist/hitl/rosterMountedNames.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRosterView } from '../toolRoster.js';
+export declare function rosterMountedNames(roster: ToolRosterView | null | undefined): ReadonlySet<string> | 'absent' | 'unreadable';

package/dist/hitl/rosterMountedNames.js

@@ -0,0 +1,38 @@
+export function rosterMountedNames(roster) {
+    if (roster === undefined || roster === null)
+        return 'absent';
+    try {
+        if (typeof roster !== 'object' || Array.isArray(roster))
+            return 'unreadable';
+        const entries = roster.entries;
+        if (!Array.isArray(entries))
+            return 'unreadable';
+        const names = new Set();
+        const n = entries.length;
+        for (let i = 0; i < n; i++) {
+            if (!Object.hasOwn(entries, i))
+                return 'unreadable';
+            const row = entries[i];
+            if (typeof row !== 'object' || row === null)
+                return 'unreadable';
+            const name = row.name;
+            if (typeof name !== 'string' || name.length === 0)
+                return 'unreadable';
+            names.add(name);
+            const aliases = row.aliases;
+            if (aliases === undefined)
+                continue;
+            if (!Array.isArray(aliases))
+                return 'unreadable';
+            for (const a of aliases) {
+                if (typeof a !== 'string')
+                    return 'unreadable';
+                names.add(a);
+            }
+        }
+        return names;
+    }
+    catch {
+        return 'unreadable';
+    }
+}

package/dist/hitl/sessionPolicyDeliverable.d.ts

@@ -1,5 +1,6 @@
 import type { SessionPermissionRules } from '@sema-agent/sdk';
-export type SessionPolicyWithheldWhy = 'ask_no_bucket' | 'qualified_deny' | 'peer_wide' | 'wildcard' | 'not_a_tool_name' | 'legacy_tool_name';
+import type { ToolRosterView } from '../toolRoster.js';
+export type SessionPolicyWithheldWhy = 'ask_no_bucket' | 'qualified_deny' | 'peer_wide' | 'wildcard' | 'not_a_tool_name' | 'legacy_tool_name' | 'not_in_roster';
 export declare const SESSION_POLICY_WITHHELD_WHY: readonly SessionPolicyWithheldWhy[];
 export interface SessionPolicyWithheldRule {
     readonly rule: string;
@@ -11,5 +12,10 @@ export interface SessionPolicyDeliverability {
     readonly withheld: readonly SessionPolicyWithheldRule[];
     readonly unreadable?: true;
 }
-export declare function sessionPolicyDeliverable(behavior: 'deny' | 'ask', rules: readonly string[]): SessionPolicyDeliverability;
+export interface SessionPolicyDeliverableOptions {
+    readonly roster?: ToolRosterView;
+}
+export declare function isEngineRefusedToolName(name: string): boolean;
+export declare function sessionPolicyDeliverable(behavior: 'deny' | 'ask', rules: readonly string[], opts?: SessionPolicyDeliverableOptions): SessionPolicyDeliverability;
 export declare function sessionPolicyWithheldNotice(why: SessionPolicyWithheldWhy): string;
+export declare function legacyToolNameFailureNoteOf(code: string | undefined): string | undefined;