@sema-agent/client-core 0.93.1 → 0.94.0

package/dist/hitl/frameRouter.js

@@ -4,6 +4,8 @@ import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 import { GATE_PARKED_ERROR_CODE } from '../engineErrorCodes.js';
 import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateToolName } from '../runTerminal.js';
 import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
+import { liveCardHoldOf, supersedeLiveCard } from './approvalHolds.js';
+import { liveFrameCallKey } from './gateIdentity.js';
 import { SEMA_DENIAL_KIND_KEY, hasLedgerPositionKey } from './gateLedger.js';
 import { replayedApprovalDisposition } from './replayedApproval.js';
 import { settleWithinDeadline } from '../abortableSleep.js';
@@ -14,6 +16,38 @@ export const HITL_REJECT_MESSAGE = REJECT_MESSAGE;
 export const HITL_POLICY_DENY_MESSAGE = 'Permission for this tool use was denied: it requires interactive approval, and permission prompts are ' +
     'not available in this session. The action was NOT performed. Do not claim it succeeded, and do not retry ' +
     'it in this session \u2014 report the limitation to the user, or suggest an alternative.';
+const SENTENCE_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_.:@-]{0,199}$/;
+export function policyDenyReason(facts) {
+    const one = typeof facts.toolName === 'string' && SENTENCE_TOOL_NAME.test(facts.toolName) ? `this one "${facts.toolName}" call` : 'this one call';
+    const flag = typeof facts.allowRuleFlag === 'string' && SENTENCE_TOOL_NAME.test(facts.allowRuleFlag.replace(/^--?/, '')) ? ` (or ${facts.allowRuleFlag})` : '';
+    const budgetKnob = typeof facts.budgetSetting === 'string' && SENTENCE_TOOL_NAME.test(facts.budgetSetting) ? facts.budgetSetting : undefined;
+    const cause = facts.cause === 'no_allow_rule' || facts.cause === 'ask_rule' || facts.cause === 'budget' ? facts.cause : 'other';
+    if (facts.lane === 'dont_ask') {
+        const mode = 'denied by the dontAsk permission mode';
+        switch (cause) {
+            case 'no_allow_rule':
+                return `${mode}: ${one} needed approval, no permission rule allowed it, and this mode refuses anything that would ask — calls that need no approval still run; an allow rule in settings${flag} can approve calls like this ahead of time`;
+            case 'ask_rule':
+                return `${mode}: an ask rule matched ${one}, and this mode refuses anything that would ask (an ask rule outranks allow rules) — narrow or remove that ask rule, or use another permission mode to answer it`;
+            case 'budget':
+                return `${mode}: ${one} needed approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls${budgetKnob !== undefined ? ` — raise ${budgetKnob} before launch to change the cap` : ''}`;
+            default:
+                return `${mode}: ${one} needed a person's approval that saved permission rules cannot approve here (the engine or your deployment requires a person for it, or it could not be checked against your rules), and this mode refuses anything that would ask — use another permission mode to answer it`;
+        }
+    }
+    const lane = 'no approval UI on this lane';
+    const tail = 'nobody can be asked here, so only this call was refused — calls that need no approval still run';
+    switch (cause) {
+        case 'no_allow_rule':
+            return `${lane}: ${one} needed a person's approval, no permission rule answered it, and ${tail}; a matching allow rule in settings${flag} can approve calls like this ahead of time`;
+        case 'ask_rule':
+            return `${lane}: an ask rule matched ${one}, so it needed a person's answer, and ${tail}; an ask rule outranks allow rules, so narrow or remove that ask rule, or run the task interactively to answer it`;
+        case 'budget':
+            return `${lane}: ${one} needed a person's approval, and this session's automatic-approval budget is used up, so saved rules no longer approve calls; ${tail}${budgetKnob !== undefined ? `; raise ${budgetKnob} before launch to change the cap` : ''}`;
+        default:
+            return `${lane}: ${one} needed a person's approval, and saved permission rules cannot approve it here (the engine or your deployment requires a person for it, or it could not be checked against your rules); ${tail}; run the task interactively to answer it`;
+    }
+}
 function denyOutputForRender(attribution) {
     if (attribution?.settledBy !== 'policy')
         return HITL_REJECT_MESSAGE;
@@ -232,10 +266,24 @@ const TOOL_END_ARMS = [
             '改顺序必须同批改 TOOL_END_ARM_ORDER 并说明为什么新顺序仍然对。');
     }
 }
+function completeFrameParked(ev) {
+    try {
+        const d = Object.getOwnPropertyDescriptor(ev, 'parked');
+        return d !== undefined && 'value' in d && d.value === true;
+    }
+    catch {
+        return false;
+    }
+}
 async function routeToolApprovalFrame(ev, ctx) {
     const { led, deps } = ctx;
-    if (ev.type === 'tool_approval_complete')
+    if (ev.type === 'tool_approval_complete') {
+        const id = ev.approvalId;
+        if (typeof id === 'string' && id !== '' && supersedeLiveCard(liveFrameCallKey(id), completeFrameParked(ev))) {
+            hostLog('debug', `liveHitlAskWire: tool_approval_complete for ${id} arrived while its card was waiting — card withdrawn (nothing will be sent from it)`);
+        }
         return { kind: 'skip' };
+    }
     if (!deps.respondToolApproval) {
         hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} but no respond wire — engine self-settles (TTL deny)`);
         return { kind: 'skip' };
@@ -269,7 +317,16 @@ async function routeToolApprovalFrame(ev, ctx) {
     const frameCallId = !fromSubagent && typeof ev.toolCallId === 'string' && ev.toolCallId !== '' ? ev.toolCallId : undefined;
     const gatedCallId = fromSubagent ? undefined : frameCallId ?? led.lastPendingFsCall();
     const argsCallId = frameCallId === undefined ? gatedCallId : typeof ev.toolName === 'string' && toolNameIsFsWrite(ev.toolName) ? frameCallId : undefined;
-    const outcome = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane);
+    const launched = surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, argsCallId), ctx.signal, deps.approvalLane);
+    const hold = liveCardHoldOf(liveFrameCallKey(ev.approvalId));
+    const handled = launched.then((outcome) => settleLiveCardOutcome(ev, outcome, ctx, fromSubagent, gatedCallId), (e) => {
+        hostLog('debug', `liveHitlAskWire: tool_approval card for ${ev.approvalId} failed: ${String(e).slice(0, 160)}`);
+    });
+    led.trackLiveCard(() => hold?.phase ?? 'card', handled);
+    return { kind: 'skip' };
+}
+function settleLiveCardOutcome(ev, outcome, ctx, fromSubagent, gatedCallId) {
+    const { led, deps } = ctx;
     const { decision } = outcome;
     if (deps.onToolApprovalOutcome !== undefined) {
         try {
@@ -294,7 +351,6 @@ async function routeToolApprovalFrame(ev, ctx) {
         else
             led.armDenyStamp(attribution);
     }
-    return { kind: 'skip' };
 }
 const REPLAYED_APPROVAL_LIST_DEADLINE_MS = 3000;
 async function judgeLedgerApprovalFrame(ev, ctx) {

package/dist/hitl/gateLedger.d.ts

@@ -23,6 +23,9 @@ export interface GateLedger {
     notePreambleApproval(approvalId: string): void;
     preambleApprovals(): ReadonlySet<string>;
     beginStreamSegment(): void;
+    trackLiveCard(phaseOf: () => 'card' | 'respond', handled: Promise<void>): void;
+    answeringLiveCards(): Promise<void>[];
+    liveCardsSettled(): Promise<void>;
     markStarted(callId: string): boolean;
     noteGatedStart(callId: string, ev: AgentEvent): void;
     gatedStartArgs(): ReadonlyMap<string, unknown>;

package/dist/hitl/gateLedger.js

@@ -88,6 +88,7 @@ export function createGateLedger() {
     let denyStampAttribution;
     let seq;
     const preambleApprovalIds = new Set();
+    const liveCards = new Set();
     return {
         noteSeq(ev) {
             const s = durableSeqOf(ev);
@@ -120,6 +121,22 @@ export function createGateLedger() {
         beginStreamSegment() {
             preambleApprovalIds.clear();
         },
+        trackLiveCard(phaseOf, handled) {
+            const entry = { phaseOf, handled };
+            liveCards.add(entry);
+            void handled.then(() => { liveCards.delete(entry); }, () => { liveCards.delete(entry); });
+        },
+        answeringLiveCards() {
+            const out = [];
+            for (const e of liveCards)
+                if (e.phaseOf() === 'respond')
+                    out.push(e.handled);
+            return out;
+        },
+        async liveCardsSettled() {
+            while (liveCards.size > 0)
+                await Promise.allSettled([...liveCards].map((e) => e.handled));
+        },
         markStarted(callId) {
             if (startedCalls.has(callId))
                 return false;

package/dist/hitl/hitlBridge.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEvent, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
+import type { AgentEvent, ApprovalDecidedBy, ApprovalDecision, ApprovalStaleError, PendingCheckpoint, CheckpointGate, PlanReviewRequest, AssistantTaskStatus } from '@sema-agent/sdk';
 import type { PermissionResult } from '@sema-agent/agent-types';
 import type { ApprovalsListEnvelope } from './crashConverged.js';
 import { type SuspendedReopenReading } from './suspendedReopen.js';
@@ -56,7 +56,7 @@ export interface HitlDecideDenyOutcome {
     decision: 'deny';
     reason?: string | undefined;
     settledBy?: 'policy' | undefined;
-    decidedBy?: 'policy' | undefined;
+    decidedBy?: Extract<ApprovalDecidedBy, 'policy'> | undefined;
 }
 export declare class HitlSafetyError extends Error {
     readonly code: HitlSafetyCode;

package/dist/hitl/hitlBridge.js

@@ -3,6 +3,7 @@ import { eventSeq } from '../adapter/types.js';
 import { hostLog } from '../host.js';
 import { abortableSleep } from '../abortableSleep.js';
 import { readOwnDataValue } from '../ownKey.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
 const MAX_DENY_REASON_CHARS = 4096;
@@ -208,7 +209,9 @@ export async function findPendingForTask(client, taskId, matches, opts, callId,
         rows = (await client.approvals.list(opts)).pending;
     }
     catch (e) {
-        return { ok: false, reason: `approvals.list failed: ${String(e)}` };
+        const t = wireFailureTextsOf(e);
+        hostLog('debug', `hitlBridge: approvals.list failed: ${t.log}`);
+        return { ok: false, reason: `approvals.list failed: ${t.reason}` };
     }
     const decidable = rows.filter((r) => askParkForeignGateKind(r) === null);
     const identityRow = callId !== undefined
@@ -327,13 +330,8 @@ export class HitlBridge {
             throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry editedPlan`, 'bad_plan_edit');
         }
         const modeAfter = outcome.permissionModeAfter;
-        if (modeAfter !== undefined) {
-            if (outcome.decision !== 'approve') {
-                throw new HitlSafetyError(`plan-review "${outcome.decision}" must NOT carry permissionModeAfter (it only applies to an approval)`, 'bad_plan_mode');
-            }
-            if (!isPlanReviewModeAfter(modeAfter)) {
-                throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
-            }
+        if (modeAfter !== undefined && !isPlanReviewModeAfter(modeAfter)) {
+            throw new HitlSafetyError('plan-review permissionModeAfter must be "default" or "acceptEdits"', 'bad_plan_mode');
         }
         const req = { decision: outcome.decision };
         if (modeAfter !== undefined && isPlanReviewModeAfter(modeAfter))
@@ -416,11 +414,11 @@ export class HitlBridge {
                     throw e;
                 if (isDecideAttemptTimeout(e)) {
                     if (attempts >= DECIDE_TIMEOUT_MIN_ATTEMPTS && Date.now() - startedAt >= decideTimeoutRetryBudgetMs()) {
-                        throw new DecideTransportRetryExhaustedError(attempts, String(e));
+                        throw new DecideTransportRetryExhaustedError(attempts, wireFailureTextsOf(e).reason);
                     }
                 }
                 else if (netRetriesUsed >= 1) {
-                    throw new DecideTransportRetryExhaustedError(attempts, String(e));
+                    throw new DecideTransportRetryExhaustedError(attempts, wireFailureTextsOf(e).reason);
                 }
                 else {
                     netRetriesUsed++;

package/dist/hitl/hitlHostSurface.d.ts

@@ -23,6 +23,7 @@ export declare function hitlHostSurfaceFor(sessionKey: string): HitlHostSurface
 export declare function _resetHitlHostSurfaceForTest(): void;
 export declare function surfaceForCurrentSession(): HitlHostSurface | null;
 export declare const CANCEL_DENY_BUDGET_MS = 2000;
+export declare const INTERRUPT_DENY_REASON = "Interrupted by user";
 export declare const CANCEL_DENY_WARN_TEXT = "could not cancel the pending question \u2014 the session may stay locked; the run may need engine-side recovery";
 export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow was not remembered by the worker \u2014 you will be asked again for this tool";
 export declare const EDIT_NOT_FORWARDED_WARN_TEXT = "your edited tool input was NOT forwarded \u2014 the tool is running with the ORIGINAL input you saw before editing";
@@ -31,6 +32,8 @@ export declare function surfaceEditNotForwarded(): void;
 export declare const APPROVAL_PARKING_WARN_TEXT = "This approval is being parked; answer it again on the parked card when it appears.";
 export declare function approvalParkingNoticeText(retryAfterMs?: number): string;
 export declare function surfaceApprovalParking(retryAfterMs?: number): void;
+export declare const COMPACT_NOT_RUNNING_WARN_TEXT = "engine run finished before compaction was applied; nothing was compacted";
+export declare function surfaceCompactNotRunning(sessionKey?: string): void;
 export declare const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT: string;
 export declare function surfaceReplayedApprovalListUnreadable(): void;
 export declare const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT: string;

package/dist/hitl/hitlHostSurface.js

@@ -29,22 +29,26 @@ export function _resetHitlHostSurfaceForTest() {
     hostSurfaceMissesByKey.clear();
 }
 export function surfaceForCurrentSession() {
-    const hostSurface = hitlHostSurfaceFor(DEFAULT_SESSION_KEY);
+    return surfaceForSession(DEFAULT_SESSION_KEY);
+}
+function surfaceForSession(sessionKey) {
+    const hostSurface = hitlHostSurfaceFor(sessionKey);
     if (hostSurface === null) {
-        hostSurfaceMissesByKey.set(DEFAULT_SESSION_KEY, (hostSurfaceMissesByKey.get(DEFAULT_SESSION_KEY) ?? 0) + 1);
+        hostSurfaceMissesByKey.set(sessionKey, (hostSurfaceMissesByKey.get(sessionKey) ?? 0) + 1);
     }
     return hostSurface;
 }
 export const CANCEL_DENY_BUDGET_MS = 2000;
+export const INTERRUPT_DENY_REASON = 'Interrupted by user';
 export const CANCEL_DENY_WARN_TEXT = 'could not cancel the pending question — the session may stay locked; the run may need engine-side recovery';
 const CANCEL_DENY_WARN_KEY = 'hitl-cancel-deny-warn';
 const CANCEL_DENY_WARN_TIMEOUT_MS = 10_000;
 function surfaceCancelDenyWarn(text = CANCEL_DENY_WARN_TEXT) {
     surfaceSelfClearingWarn(CANCEL_DENY_WARN_KEY, text, CANCEL_DENY_WARN_TIMEOUT_MS);
 }
-function surfaceSelfClearingWarn(key, text, timeoutMs) {
+function surfaceSelfClearingWarn(key, text, timeoutMs, sessionKey = DEFAULT_SESSION_KEY) {
     try {
-        const s = surfaceForCurrentSession();
+        const s = surfaceForSession(sessionKey);
         if (!s)
             return;
         s.showNotice({ key, text, color: 'warning', priority: 'immediate', timeoutMs });
@@ -83,6 +87,12 @@ export function approvalParkingNoticeText(retryAfterMs) {
 export function surfaceApprovalParking(retryAfterMs) {
     surfaceSelfClearingWarn(APPROVAL_PARKING_KEY, approvalParkingNoticeText(retryAfterMs), APPROVAL_PARKING_TIMEOUT_MS);
 }
+export const COMPACT_NOT_RUNNING_WARN_TEXT = 'engine run finished before compaction was applied; nothing was compacted';
+const COMPACT_NOT_RUNNING_KEY = 'engine-compact-not-running';
+const COMPACT_NOT_RUNNING_TIMEOUT_MS = 10_000;
+export function surfaceCompactNotRunning(sessionKey = DEFAULT_SESSION_KEY) {
+    surfaceSelfClearingWarn(COMPACT_NOT_RUNNING_KEY, COMPACT_NOT_RUNNING_WARN_TEXT, COMPACT_NOT_RUNNING_TIMEOUT_MS, sessionKey);
+}
 export const REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT = "Could not read the pending-approval list, so an approval request read back from this run's event log was not raised as a question, " +
     'and no decision was sent for it.';
 const REPLAYED_APPROVAL_LIST_UNREADABLE_KEY = 'hitl-replayed-approval-list-unreadable';

package/dist/hitl/localAllowRule.js

@@ -1,3 +1,4 @@
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 const BASH_TOOL_NAME_FOR_RULES = 'Bash';
 export function parseLocalAllowRule(rule, expectedToolName, deps) {
     if (typeof rule !== 'string' || rule === '') {
@@ -8,7 +9,7 @@ export function parseLocalAllowRule(rule, expectedToolName, deps) {
         value = deps.parseRule(rule);
     }
     catch (e) {
-        return { ok: false, error: `rule text did not parse (${String(e)})` };
+        return { ok: false, error: `rule text did not parse (${wireFailureTextsOf(e).reason})` };
     }
     if (typeof value.toolName !== 'string' || value.toolName === '') {
         return { ok: false, error: 'rule text carries no tool name' };

package/dist/hitl/noAllowCause.d.ts

@@ -0,0 +1,9 @@
+export type NoAllowCause = 'no_allow_rule' | 'ask_rule' | 'budget' | 'other';
+export interface RuleLadderNoAllowFacts {
+    readonly allowed?: boolean;
+    readonly denied?: boolean;
+    readonly askRuleMatched?: boolean;
+    readonly budgetExhausted?: boolean;
+    readonly noRuleMatched?: boolean;
+}
+export declare function noAllowCauseOf(card: object | null | undefined, ladder: RuleLadderNoAllowFacts | null | undefined): NoAllowCause | undefined;

package/dist/hitl/noAllowCause.js

@@ -0,0 +1,26 @@
+import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
+function ladderSays(ladder, key) {
+    if (typeof ladder !== 'object' || ladder === null)
+        return false;
+    try {
+        const d = Object.getOwnPropertyDescriptor(ladder, key);
+        return d !== undefined && 'value' in d && d.value === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function noAllowCauseOf(card, ladder) {
+    if (ladderSays(ladder, 'allowed') || ladderSays(ladder, 'denied'))
+        return undefined;
+    if (ladderSays(ladder, 'askRuleMatched'))
+        return 'ask_rule';
+    if (ladderSays(ladder, 'budgetExhausted'))
+        return 'budget';
+    const standing = automaticAnswerVerdict(card, 'standing_rule');
+    if (standing.kind === 'must_ask' && (standing.askClass === 'ask_rule' || standing.origin === 'ask_rule'))
+        return 'ask_rule';
+    if (ladderSays(ladder, 'noRuleMatched') && standing.kind === 'may_answer')
+        return 'no_allow_rule';
+    return 'other';
+}

package/dist/hitl/parkResolver.js

@@ -4,11 +4,12 @@ import { ASK_GONE, CHECKPOINT_UNSUPPORTED_VERSION, DECIDE_WORKFLOW_PARK_FORKED,
 import { publishQuestionFrame, registerLocalQuestionResponder, hasQuestionOverlay, } from '../liveQuestionStore.js';
 import { hostLog } from '../host.js';
 import { surfaceFsApprovalAndDecide } from './toolApprovalWire.js';
-import { observeCancelByDeny } from './hitlHostSurface.js';
+import { INTERRUPT_DENY_REASON, observeCancelByDeny } from './hitlHostSurface.js';
 import { flushHeldWithInterruptRewrite, isAskTool } from './frameRouter.js';
 import { approvalCallKey, askGateQuestionId } from './gateIdentity.js';
 import { readDecideReceipt } from '../decideReceipt.js';
 import { decideFailureNote } from '../decideFailureNote.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
 export const MAX_GATE_HOPS = 2;
 export function nextHopBudget(prev, round) {
     const total = (prev?.total ?? 0) + 1;
@@ -139,7 +140,7 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
     });
     const bridge = new HitlBridge(deps.client, taskId, deps.onDecideOperation ? { onDecideOperation: deps.onDecideOperation } : undefined);
     if (answer === null) {
-        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: 'Interrupted by user' }, gatedCallId, undefined, pending), taskId);
+        observeCancelByDeny(bridge.decideTool({ decision: 'deny', reason: INTERRUPT_DENY_REASON }, gatedCallId, undefined, pending), taskId);
         return { kind: 'aborted', gatedCallId };
     }
     let declinedReceipt;
@@ -170,11 +171,13 @@ async function surfaceGateAndDecide(deps, taskId, askArgsByCall, signal, parkGat
         const currentPending = readDecideCurrentPending(e);
         const wireCode = readWireErrorCode(e);
         const wireRetriable = typeof e === 'object' && e !== null && refusalSaysStillPending(e);
+        const failureTexts = wireFailureTextsOf(e);
+        hostLog('debug', `liveHitlAskWire: decide failed: ${failureTexts.log}`);
         return {
             kind: 'failed',
             stage: 'decide',
             gatedCallId,
-            reason: `decide failed: ${String(e)}${decideFailureNote(e, attemptedDecision)}`,
+            reason: `decide failed: ${failureTexts.reason}${decideFailureNote(e, attemptedDecision)}`,
             ...(code !== undefined ? { code } : {}),
             ...(e instanceof DecideTransportRetryExhaustedError ? { retryExhausted: true } : {}),
             ...(currentPending !== undefined ? { currentPending } : {}),

package/dist/hitl/parkRowBirthWait.js

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

package/dist/hitl/persistedRulesWire.d.ts

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

package/dist/hitl/persistedRulesWire.js

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

package/dist/hitl/planReviewWire.d.ts

@@ -48,7 +48,6 @@ export type PlanReviewWireClient = {
 };
 export interface PlanReviewWire {
     client: PlanReviewWireClient;
-    capsBaseUrl?: string;
 }
 export interface PlanReviewDecisionOutcome extends PlanReviewOutcomeMeta {
     detail: string;

package/dist/hitl/planReviewWire.js

@@ -6,7 +6,8 @@ import { engineWireTarget } from '../engineWireTarget.js';
 import { enqueuePlanReviewOutcome } from '../notifications.js';
 import { corruptStoredRowContent, corruptStoredRowWhere } from '../wireErrorTriage.js';
 import { decideFailureNote } from '../decideFailureNote.js';
-import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError } from '../resumeRefusalCopy.js';
+import { wireFailureTextsOf } from '../wireFailureShape.js';
+import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, resumeContextUnavailableContent, resumeContextUnavailableFromError } from '../resumeRefusalCopy.js';
 import { REQUEST_FIELD_CONFLICT, isUnavailableFaceCode } from '../engineErrorCodes.js';
 import { denyReasonForWire, isPlanReviewModeAfter } from './hitlBridge.js';
 import { planReviewQuestionId, REOPEN_ID_TAIL, taskIdFromPlanReviewQuestionId } from './gateIdentity.js';
@@ -309,6 +310,15 @@ export function planReviewOutcomeTail(taskId, decision, effect, cause) {
             return `Do not state the result as fact: tell the user the ${decision} was submitted but its effect could not be confirmed; TaskOutput("${taskId}") shows where the task stands.`;
     }
 }
+function clientOnlyView(wire) {
+    if (wire === undefined || wire === null || typeof wire !== 'object')
+        return wire;
+    return {
+        get client() {
+            return wire.client;
+        },
+    };
+}
 function planReviewDecisionTimedOutOutcome(decision) {
     return (`The plan_review ${decision} was sent, but no answer came back from the engine within the time limit this host allows for it — ` +
         `it may have taken effect (${decision === 'approve' ? 'an approval keeps the engine busy until the resumed work finishes' : 'the engine may still be applying it'}).`);
@@ -492,12 +502,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
     let stillParkedProven = false;
     let statusSeen;
     const wire = opts?.wire;
-    const resolved = engineWireFor(wire, DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
-    const badMode = permissionModeAfter !== undefined && (decision !== 'approve' || !isPlanReviewModeAfter(permissionModeAfter));
+    const resolved = engineWireFor(clientOnlyView(wire), DEFAULT_SESSION_KEY, usablePlanReviewWireClient);
+    const badMode = permissionModeAfter !== undefined && !isPlanReviewModeAfter(permissionModeAfter);
     if (badMode) {
-        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter is only valid with approve and must be "default" or "acceptEdits"`);
+        hostLog('error', `planReviewWire: ${decision} NOT sent — permissionModeAfter must be "default" or "acceptEdits"`);
         effect = 'not_sent';
-        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid for this decision (it only applies to an approval, and must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
+        outcome = `The plan_review ${decision} could NOT be sent: the post-approval permission mode given with it is not valid (it must be "default" or "acceptEdits"). Tell the user plainly that the decision did not go through; the plan is still waiting.`;
     }
     else if (resolved.kind === 'no-target') {
         hostLog('error', `planReviewWire: ${decision} NOT sent — engineWireTarget() unavailable`);
@@ -600,12 +610,15 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                 const refusedCode = e?.errorCode;
                 const noAnswer = typeof status === 'number' || typeof e !== 'object' ? null : noAnswerKindOf(e);
                 if (status === 400 && refusedCode === REQUEST_FIELD_CONFLICT && permissionModeAfter === 'acceptEdits') {
-                    hostLog('debug', 'planReviewWire: approve + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode');
+                    hostLog('debug', `planReviewWire: ${decision} + acceptEdits refused (request.field_conflict) — NOT re-sent with a different mode`);
                     effect = 'still_parked';
                     stillParkedProven = true;
                     outcome =
-                        'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
-                            'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.';
+                        decision === 'approve'
+                            ? 'The plan approval was NOT applied: the engine refused "auto-accept edits" for this task (it was not started read-only in plan mode, so that option does not apply). ' +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly, and that approving with "manually approve edits" will go through.'
+                            : `The plan ${decision} was NOT applied: the engine refused the post-approval permission mode that was sent with it (request.field_conflict). ` +
+                                'Nothing changed engine-side — the plan is still waiting for review. Tell the user plainly that the decision did not go through.';
                 }
                 else if (status === 404 && refusedCode === 'not_found.plan_review') {
                     hostLog('debug', `planReviewWire: ${decision} → 404 not_found.plan_review (no pending plan review any more — an earlier decision likely settled it)`);
@@ -622,6 +635,12 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     stillParkedCause = 'stored_form_unsupported';
                     outcome = `This ${decision} was not applied. ${checkpointUnsupportedVersionContent(cu, { parkKind: 'plan_review', runId: taskId })}`;
                 }
+                else if (resumeContextUnavailableFromError(e) !== null) {
+                    const ru = resumeContextUnavailableFromError(e);
+                    hostLog('debug', `planReviewWire: ${decision} → 409 conflict.resume_context_unavailable (the session context needed to continue this run is not available)`);
+                    effect = 'not_applied';
+                    outcome = `This ${decision} was not applied. ${resumeContextUnavailableContent(ru)}`;
+                }
                 else if (typeof status === 'number' && corruptStoredRowWhere(e) !== undefined) {
                     const where = corruptStoredRowWhere(e);
                     hostLog('debug', `planReviewWire: ${decision} → ${String(status)} corrupt (stored resume context unreadable)`);
@@ -643,7 +662,9 @@ async function decidePlanReviewInner(taskId, decision, permissionModeAfter, disp
                     outcome = planReviewDecisionConnectionLostOutcome(decision);
                 }
                 else {
-                    outcome = `The plan_review decision could not reach the engine: ${String(e)}`;
+                    const failureTexts = wireFailureTextsOf(e);
+                    hostLog('debug', `planReviewWire: ${decision} could not reach the engine: ${failureTexts.log}`);
+                    outcome = `The plan_review decision could not reach the engine: ${failureTexts.reason}`;
                 }
             }
         }

package/dist/hitl/sessionPolicyDeliverable.d.ts

@@ -15,7 +15,7 @@ export interface SessionPolicyDeliverability {
 export interface SessionPolicyDeliverableOptions {
     readonly roster?: ToolRosterView;
 }
-export declare function isEngineRefusedToolName(name: string): boolean;
+export { isEngineRefusedToolName } from '../engineRefusedToolName.js';
 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;

package/dist/hitl/sessionPolicyDeliverable.js

@@ -1,9 +1,10 @@
 import { CONFIG_LEGACY_TOOL_NAME, RULES_LEGACY_TOOL_NAME } from '../engineErrorCodes.js';
-import { rosterMountedNames } from './rosterMountedNames.js';
+import { rosterMountedNames } from '../rosterMountedNames.js';
 import { ruleCompileVerdict } from '../ruleCompileVerdict.js';
 import { protocolSegmentOf } from '../protocolSegment.js';
 import { PREFIXES_IN_PROSE, REFUSED_NAME_CLASSES, REFUSED_NAME_FIX, RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
 import { CORE_PROTOCOL_PREFIXES, CORE_RETIRED_TOOL_CURRENT_NAMES } from '../generated/toolNameTables.js';
+import { isEngineRefusedToolName } from '../engineRefusedToolName.js';
 const COVERING_NAMESPACE_PREFIXES = CORE_PROTOCOL_PREFIXES;
 const ENGINE_RETIRED_TOOL_NAMES = CORE_RETIRED_TOOL_CURRENT_NAMES;
 const WITHHELD_NOTICE = {
@@ -40,13 +41,7 @@ function withheldWhyOf(rule) {
         return 'legacy_tool_name';
     return undefined;
 }
-export function isEngineRefusedToolName(name) {
-    if (typeof name !== 'string')
-        return false;
-    if (ENGINE_RETIRED_TOOL_NAMES.has(name))
-        return true;
-    return name.includes('__') && !COVERING_NAMESPACE_PREFIXES.some((prefix) => name.startsWith(prefix));
-}
+export { isEngineRefusedToolName } from '../engineRefusedToolName.js';
 function suppliedRosterNames(opts) {
     if (opts === undefined || opts === null)
         return 'absent';

package/dist/hitl/sessionPolicyWire.js

@@ -3,7 +3,7 @@ import { hostLog } from '../host.js';
 import { isEngineRefusedToolName } from './sessionPolicyDeliverable.js';
 import { RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
 import { RULES_LEGACY_TOOL_NAME, isRulesRefusalCode } from '../engineErrorCodes.js';
-import { rosterMountedNames } from './rosterMountedNames.js';
+import { rosterMountedNames } from '../rosterMountedNames.js';
 import { CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
 function isLegacyToolNameVerdict(v) {
     return typeof v === 'string' && v !== 'current' && CORE_RULE_TOOL_NAME_VERDICTS.includes(v);