@sema-agent/client-core 0.91.0 → 0.93.0

package/dist/hitl/askParkRowRouting.js

@@ -15,9 +15,9 @@ export function classifyAskParkRows(rows, taskId, deps) {
             kind: 'unborn',
             reason: rows.length === 0
                 ?
-                    `no pending row at all for task ${taskId} — either an orphan park (a seat held with no decision outstanding) or the next gate's row is not minted yet`
+                    `no pending row at all for task ${taskId} — either an orphan park (a seat held with no decision outstanding) or the next gate's row is not minted yet; this client cannot tell which`
                 : soleUnowned
-                    ? `the only pending row (task ${String(sole?.taskId)} / session ${String(sole?.sessionId)}) could not be proven to belong to this client (not in its own-run ledger, session id absent or different) — refusing to surface an approval that may be another session's`
+                    ? `the only pending row (task ${String(sole?.taskId)} / session ${String(sole?.sessionId)}) could not be proven to belong to this client (not in its own-run ledger, session id absent or different; this client cannot tell which) — refusing to surface an approval that may be another session's`
                     : `${String(rows.length)} pending rows but none for task ${taskId} — ambiguous queue, refusing to surface an unrelated row`,
         };
     }

package/dist/hitl/askSurvivesPosture.d.ts

@@ -1,3 +1,4 @@
+import { type AutomaticAnswerRoad, type AutomaticAnswerUnknownWhy } from './automaticAnswerVerdict.js';
 export interface AskPostureFacts {
     readonly settingsAskRuleMatched?: boolean;
 }
@@ -5,10 +6,14 @@ export type AskPostureSurvivalRoad = 'origin' | 'settings_ask_rule';
 export type AskPostureVerdict = {
     readonly kind: 'must_ask';
     readonly by: AskPostureSurvivalRoad;
+    readonly road?: AutomaticAnswerRoad;
+    readonly askClass?: string;
 } | {
     readonly kind: 'posture_may_answer';
+    readonly releaseReason?: string;
 } | {
     readonly kind: 'unknown';
+    readonly why?: AutomaticAnswerUnknownWhy;
 };
 export declare function askSurvivesPosture(req: {
     readonly origin?: string;

package/dist/hitl/askSurvivesPosture.js

@@ -1,4 +1,5 @@
 import { readOwnNonEmptyString } from '../ownKey.js';
+import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
 const ORIGIN_SURVIVES_POSTURE = Object.freeze({
     content_question: true,
     ancestor_marked: false,
@@ -17,6 +18,22 @@ const MUST_ASK_BY_SETTINGS = Object.freeze({ kind: 'must_ask', by: 'settings_ask
 const POSTURE_MAY_ANSWER = Object.freeze({ kind: 'posture_may_answer' });
 const UNKNOWN = Object.freeze({ kind: 'unknown' });
 export function askSurvivesPosture(req, facts) {
+    const old = legacyPostureVerdict(req, facts);
+    const neu = automaticAnswerVerdict(req, 'mode_posture', facts ?? undefined);
+    if (old.kind === 'must_ask' || neu.kind === 'must_ask') {
+        const by = old.kind === 'must_ask' ? old.by : neu.kind === 'must_ask' && neu.road === 'settings_ask_rule' ? 'settings_ask_rule' : 'origin';
+        const road = neu.kind === 'must_ask' ? neu.road : by === 'settings_ask_rule' ? 'settings_ask_rule' : 'origin';
+        const askClass = neu.kind === 'must_ask' ? neu.askClass : undefined;
+        return Object.freeze({ kind: 'must_ask', by, road, ...(askClass !== undefined ? { askClass } : {}) });
+    }
+    if (old.kind === 'unknown' || neu.kind === 'unknown') {
+        return neu.kind === 'unknown' ? Object.freeze({ kind: 'unknown', why: neu.why }) : UNKNOWN;
+    }
+    return neu.kind === 'may_answer' && neu.releaseReason !== undefined
+        ? Object.freeze({ kind: 'posture_may_answer', releaseReason: neu.releaseReason })
+        : POSTURE_MAY_ANSWER;
+}
+function legacyPostureVerdict(req, facts) {
     const origin = readOwnNonEmptyString(req, 'origin');
     const rawMatched = typeof facts === 'object' && facts !== null ? facts.settingsAskRuleMatched : undefined;
     const matched = typeof rawMatched === 'boolean' ? rawMatched : undefined;

package/dist/hitl/automaticAnswerVerdict.d.ts

@@ -0,0 +1,21 @@
+import { type CoreModeArbitrationRow } from '../generated/engineFactTables.js';
+export type AutomaticAnswerLane = 'mode_posture' | 'standing_rule';
+export interface AutomaticAnswerFacts {
+    readonly settingsAskRuleMatched?: boolean;
+}
+export type AutomaticAnswerRoad = 'origin' | 'requires_real_approval' | 'governance' | 'mandate_word' | 'mandated' | 'allow_rule_shadow' | 'ask_class' | 'settings_ask_rule';
+export type AutomaticAnswerUnknownWhy = 'card_unreadable' | 'lane_not_recognised' | 'classes_malformed' | 'classes_absent' | 'class_not_in_table' | 'host_not_reported';
+export type AutomaticAnswerVerdict = {
+    readonly kind: 'must_ask';
+    readonly road: AutomaticAnswerRoad;
+    readonly askClass?: string;
+    readonly origin?: string;
+} | {
+    readonly kind: 'may_answer';
+    readonly releaseReason?: string;
+} | {
+    readonly kind: 'unknown';
+    readonly why: AutomaticAnswerUnknownWhy;
+};
+export declare function foldModeArbitrationRow(classes: Iterable<string>): CoreModeArbitrationRow;
+export declare function automaticAnswerVerdict(card: object | null | undefined, lane: AutomaticAnswerLane, facts?: AutomaticAnswerFacts | null): AutomaticAnswerVerdict;

package/dist/hitl/automaticAnswerVerdict.js

@@ -0,0 +1,143 @@
+import { CORE_MODE_ARBITRATION, CORE_MODE_RELEASE_REASONS } from '../generated/engineFactTables.js';
+import { readOwnNonEmptyString } from '../ownKey.js';
+import { readAskClassPairState } from './askClassPair.js';
+import { approvalAllowRuleShadowed } from './allowRuleShadow.js';
+import { approvalIsMandated, readApprovalMandate } from './toolApprovalWire.js';
+const TABLE = CORE_MODE_ARBITRATION;
+const ORIGIN_IMPLIES_CLASS = Object.freeze({
+    content_question: 'content_question',
+    org_unavailable: 'governance_unavailable',
+    org_rule: 'org_rule',
+    hook: 'hook',
+    ask_rule: 'ask_rule',
+    denial_limit_fallback: 'denial_limit_fallback',
+});
+const MANDATE_WORD_IMPLIES_CLASS = Object.freeze({
+    operator_always: 'shell_floor',
+    write_protection_unresolved: 'write_protection_unresolved',
+});
+const ORDINARY_ROW = CORE_MODE_ARBITRATION.ordinary;
+export function foldModeArbitrationRow(classes) {
+    let any = false;
+    let bypassImmune = false;
+    let classifierEligible = true;
+    let sandboxAdmission = true;
+    let ruleMayClear = true;
+    let hookAskFloor = false;
+    for (const c of classes) {
+        if (!Object.hasOwn(TABLE, c))
+            continue;
+        const row = TABLE[c];
+        any = true;
+        bypassImmune ||= row.bypassImmune;
+        classifierEligible &&= row.classifierEligible;
+        sandboxAdmission &&= row.sandboxAdmission;
+        ruleMayClear &&= row.ruleMayClear;
+        hookAskFloor ||= row.hookAskFloor;
+    }
+    if (!any)
+        return ORDINARY_ROW;
+    return Object.freeze({ bypassImmune, classifierEligible, sandboxAdmission, ruleMayClear, hookAskFloor });
+}
+function laneBlocks(lane, row) {
+    return lane === 'mode_posture' ? row.bypassImmune : !row.ruleMayClear;
+}
+function mustAsk(road, extra) {
+    return Object.freeze({ kind: 'must_ask', road, ...(extra?.askClass !== undefined ? { askClass: extra.askClass } : {}), ...(extra?.origin !== undefined ? { origin: extra.origin } : {}) });
+}
+const UNKNOWN = Object.freeze({
+    card_unreadable: Object.freeze({ kind: 'unknown', why: 'card_unreadable' }),
+    lane_not_recognised: Object.freeze({ kind: 'unknown', why: 'lane_not_recognised' }),
+    classes_malformed: Object.freeze({ kind: 'unknown', why: 'classes_malformed' }),
+    classes_absent: Object.freeze({ kind: 'unknown', why: 'classes_absent' }),
+    class_not_in_table: Object.freeze({ kind: 'unknown', why: 'class_not_in_table' }),
+    host_not_reported: Object.freeze({ kind: 'unknown', why: 'host_not_reported' }),
+});
+const MAY_ANSWER = Object.freeze({ kind: 'may_answer' });
+function evidenceView(card, ...keys) {
+    const out = {};
+    for (const k of keys) {
+        const v = card[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function readHostAskRuleMatched(facts) {
+    if (typeof facts !== 'object' || facts === null)
+        return undefined;
+    try {
+        const d = Object.getOwnPropertyDescriptor(facts, 'settingsAskRuleMatched');
+        return d !== undefined && 'value' in d && typeof d.value === 'boolean' ? d.value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function automaticAnswerVerdict(card, lane, facts) {
+    if (lane !== 'mode_posture' && lane !== 'standing_rule')
+        return UNKNOWN.lane_not_recognised;
+    try {
+        if (typeof card !== 'object' || card === null)
+            return UNKNOWN.card_unreadable;
+        const origin = readOwnNonEmptyString(evidenceView(card, 'origin'), 'origin');
+        if (origin !== undefined && Object.hasOwn(ORIGIN_IMPLIES_CLASS, origin)) {
+            const cls = ORIGIN_IMPLIES_CLASS[origin];
+            if (laneBlocks(lane, TABLE[cls]))
+                return mustAsk('origin', { origin, askClass: cls });
+        }
+        if (lane === 'standing_rule' && evidenceView(card, 'requiresRealApproval').requiresRealApproval === true)
+            return mustAsk('requires_real_approval');
+        if (evidenceView(card, 'governanceForced').governanceForced === true)
+            return mustAsk('governance');
+        if (lane === 'mode_posture') {
+            const word = readApprovalMandate(evidenceView(card, 'mandate'));
+            if (word !== undefined && Object.hasOwn(MANDATE_WORD_IMPLIES_CLASS, word)) {
+                const cls = MANDATE_WORD_IMPLIES_CLASS[word];
+                if (laneBlocks(lane, TABLE[cls]))
+                    return mustAsk('mandate_word', { askClass: cls });
+            }
+        }
+        else {
+            const mandateView = evidenceView(card, 'mandated', 'ruleOffersAbsence', 'mandate');
+            if (approvalIsMandated(mandateView))
+                return mustAsk('mandated');
+            if (approvalAllowRuleShadowed(card) || readOwnNonEmptyString(mandateView, 'ruleOffersAbsence') === 'shadowed')
+                return mustAsk('allow_rule_shadow');
+        }
+        const pair = readAskClassPairState(card);
+        if (pair.state === 'malformed')
+            return UNKNOWN.classes_malformed;
+        if (pair.state === 'absent')
+            return UNKNOWN.classes_absent;
+        const folded = foldModeArbitrationRow(pair.classes);
+        let anyKnown = false;
+        let firstBlocking;
+        let anyUnknown = false;
+        for (const c of pair.classes) {
+            if (!Object.hasOwn(TABLE, c)) {
+                anyUnknown = true;
+                continue;
+            }
+            anyKnown = true;
+            if (firstBlocking === undefined && laneBlocks(lane, TABLE[c]))
+                firstBlocking = c;
+        }
+        if (anyKnown && laneBlocks(lane, folded))
+            return mustAsk('ask_class', firstBlocking !== undefined ? { askClass: firstBlocking } : undefined);
+        if (anyUnknown)
+            return UNKNOWN.class_not_in_table;
+        if (lane === 'standing_rule')
+            return MAY_ANSWER;
+        const matched = readHostAskRuleMatched(facts);
+        if (matched === true)
+            return mustAsk('settings_ask_rule');
+        if (matched !== false)
+            return UNKNOWN.host_not_reported;
+        const releaseReason = CORE_MODE_RELEASE_REASONS.find((r) => pair.classes.includes(r));
+        return releaseReason !== undefined ? Object.freeze({ kind: 'may_answer', releaseReason }) : MAY_ANSWER;
+    }
+    catch {
+        return UNKNOWN.card_unreadable;
+    }
+}

package/dist/hitl/crashConverged.d.ts

@@ -16,6 +16,7 @@ export interface CrashConvergedRow {
     readonly resumeSafe: boolean;
     readonly needsHumanReason?: 'approved_then_interrupted' | 'pending_unsafe' | 'unstable_row' | 'contradictory';
 }
+export declare const isCrashConvergedCause: (v: unknown) => v is CrashConvergedRow["cause"];
 export interface ApprovalsListEnvelope {
     pending: PendingCheckpoint[];
     livePending?: unknown[];

package/dist/hitl/crashConverged.js

@@ -2,7 +2,7 @@ const CRASH_CONVERGED_CAUSE_WORDS = Object.freeze({
     crashed_before_park: true,
     shutdown_before_park: true,
 });
-const isCrashConvergedCause = (v) => typeof v === 'string' && Object.hasOwn(CRASH_CONVERGED_CAUSE_WORDS, v);
+export const isCrashConvergedCause = (v) => typeof v === 'string' && Object.hasOwn(CRASH_CONVERGED_CAUSE_WORDS, v);
 const isString = (v) => typeof v === 'string';
 const isNumber = (v) => typeof v === 'number';
 const nonEmptyString = (v) => typeof v === 'string' && v.length > 0;

package/dist/hitl/frameRouter.d.ts

@@ -2,6 +2,7 @@ import type { AgentEvent } from '@sema-agent/sdk';
 import type { DecideOperationObserver, HitlClientLike } from './hitlBridge.js';
 import { type RespondToolApprovalFn, type ToolApprovalFrame, type ToolApprovalFrameLaneOpts, type ToolApprovalFrameOutcome } from './toolApprovalWire.js';
 import type { GateLedger } from './gateLedger.js';
+import { type ReplayedApprovalDisposition } from './replayedApproval.js';
 export declare const HITL_REJECT_MESSAGE = "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.";
 export declare const HITL_POLICY_DENY_MESSAGE: string;
 export declare const HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE = "[Request interrupted by user for tool use]";
@@ -23,6 +24,7 @@ export interface AskGateWireDeps {
     approvalLane?: ToolApprovalFrameLaneOpts;
     onToolApprovalOutcome?: (frame: ToolApprovalFrame, outcome: ToolApprovalFrameOutcome) => void | Promise<void>;
     onDecideOperation?: DecideOperationObserver;
+    onReplayedApproval?: (frame: ToolApprovalFrame, disposition: ReplayedApprovalDisposition) => void | Promise<void>;
 }
 type GateKind = 'ask' | 'fs';
 export interface GatePark {

package/dist/hitl/frameRouter.js

@@ -3,8 +3,10 @@ import { isToolApprovalGate, toolNameIsFsWrite, toolNameIsShellExec, isToolAppro
 import { classifierDenyFromToolEnd } from '../classifierVerdictWire.js';
 import { GATE_PARKED_ERROR_CODE } from '../engineErrorCodes.js';
 import { readRunTerminal, runTerminalCode, runTerminalGateKind, runTerminalGateToolName } from '../runTerminal.js';
-import { surfaceForCurrentSession } from './hitlHostSurface.js';
-import { SEMA_DENIAL_KIND_KEY } from './gateLedger.js';
+import { surfaceForCurrentSession, surfaceReplayedApprovalListUnreadable } from './hitlHostSurface.js';
+import { SEMA_DENIAL_KIND_KEY, hasLedgerPositionKey } from './gateLedger.js';
+import { replayedApprovalDisposition } from './replayedApproval.js';
+import { settleWithinDeadline } from '../abortableSleep.js';
 import { ccToolDenialKindForSettledBy } from '../gateVocabulary.js';
 import { REJECT_MESSAGE } from '../adapt/wireShapes.js';
 import { RUN_CANCELLED_CODE } from '../runCancelContext.js';
@@ -64,6 +66,11 @@ function isGatedToolName(name) {
 function isFsOrShellToolName(name) {
     return typeof name === 'string' && (toolNameIsFsWrite(name) || toolNameIsShellExec(name));
 }
+function parkFamilyEvidence(led, gateToolName, gatedCallId) {
+    if (!isFsOrShellToolName(gateToolName))
+        return false;
+    return gatedCallId === undefined || led.isFsOrShellGatedCall(gatedCallId);
+}
 const ENGINE_GATE_PARKED_ERROR_CODE = GATE_PARKED_ERROR_CODE;
 function isEngineAbortToolEnd(ev) {
     if (ev.errorCode === ENGINE_GATE_PARKED_ERROR_CODE)
@@ -233,22 +240,36 @@ async function routeToolApprovalFrame(ev, ctx) {
         hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} but no respond wire — engine self-settles (TTL deny)`);
         return { kind: 'skip' };
     }
-    if (isAskToolLoose(ev.toolName)) {
-        try {
-            await deps.respondToolApproval(ev.approvalId, 'allow', {
-                ...(ctx.signal && !ctx.signal.aborted ? { signal: ctx.signal } : {}),
-            });
-            hostLog('debug', `liveHitlAskWire: ask-tool approval frame ${ev.approvalId} → allow(问题门放行,候 park 弹卡)`);
-        }
-        catch (e) {
-            hostLog('debug', `liveHitlAskWire: ask-tool approval allow failed for ${ev.approvalId}: ${String(e)} — engine self-settles (TTL)`);
+    if (hasLedgerPositionKey(ev) && !led.preambleApprovals().has(ev.approvalId)) {
+        const disposition = await judgeLedgerApprovalFrame(ev, ctx);
+        if (disposition.kind !== 'live') {
+            hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} read back from the run event log is ${disposition.kind}` +
+                `${disposition.kind === 'unknown' ? ` (${disposition.why})` : disposition.cause !== undefined ? ` (${disposition.cause})` : ''}` +
+                ' — not raised as a question, no decision sent');
+            if (disposition.kind === 'unknown' && ctx.signal?.aborted !== true)
+                surfaceReplayedApprovalListUnreadable();
+            if (deps.onReplayedApproval !== undefined) {
+                try {
+                    const out = deps.onReplayedApproval(ev, disposition);
+                    if (out && typeof out.then === 'function') {
+                        void Promise.resolve(out).catch((e) => {
+                            hostLog('debug', `liveHitlAskWire: onReplayedApproval rejected: ${String(e).slice(0, 160)}`);
+                        });
+                    }
+                }
+                catch (e) {
+                    hostLog('debug', `liveHitlAskWire: onReplayedApproval threw: ${String(e).slice(0, 160)}`);
+                }
+            }
+            return { kind: 'skip' };
         }
-        return { kind: 'skip' };
     }
     const fromSubagent = isFromSubagent(ev);
     hostLog('debug', `liveHitlAskWire: tool_approval frame ${ev.approvalId} tool=${String(ev.toolName)}${fromSubagent ? ` from-subagent=${String(ev.sourceTaskId ?? ev.sourceAgentName ?? 'explicit')}` : ''}`);
-    const gatedCallId = !fromSubagent ? led.lastPendingFsCall() : undefined;
-    const outcome = await surfaceToolApprovalFrameAndRespond(ev, deps.respondToolApproval, argsOfGatedStart(led, gatedCallId), ctx.signal, deps.approvalLane);
+    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 { decision } = outcome;
     if (deps.onToolApprovalOutcome !== undefined) {
         try {
@@ -275,6 +296,30 @@ async function routeToolApprovalFrame(ev, ctx) {
     }
     return { kind: 'skip' };
 }
+const REPLAYED_APPROVAL_LIST_DEADLINE_MS = 3000;
+async function judgeLedgerApprovalFrame(ev, ctx) {
+    const outer = ctx.signal;
+    const got = await settleWithinDeadline(REPLAYED_APPROVAL_LIST_DEADLINE_MS, (deadline) => {
+        const ac = new AbortController();
+        const release = () => {
+            deadline.removeEventListener('abort', forward);
+            outer?.removeEventListener('abort', forward);
+        };
+        const forward = () => {
+            ac.abort();
+            release();
+        };
+        deadline.addEventListener('abort', forward, { once: true });
+        outer?.addEventListener('abort', forward, { once: true });
+        if (outer?.aborted === true)
+            forward();
+        return Promise.resolve()
+            .then(() => ctx.deps.client.approvals.list({ signal: ac.signal }))
+            .finally(release);
+    });
+    const approvals = got.kind === 'value' ? { read: 'ok', body: got.value } : { read: 'failed' };
+    return replayedApprovalDisposition(ev, { preamble: ctx.led.preambleApprovals(), approvals });
+}
 function routeToolStart(ev, callId, led) {
     led.noteStart(callId, ev);
     if (!led.markStarted(callId))
@@ -313,7 +358,7 @@ function routeSuspended(ev, ctx) {
     if (ev.gate &&
         isToolApprovalGate(ev.gate) &&
         ctx.taskId.current) {
-        ctx.led.noteParkGate({ fsOrShellFamily: isFsOrShellToolName(ev.gate.toolName) });
+        ctx.led.noteParkGate({ fsOrShellFamily: parkFamilyEvidence(ctx.led, ev.gate.toolName, gatedCallId) });
         return { kind: 'park', gate: 'fs', ...(gatedCallId !== undefined ? { gatedCallId } : {}) };
     }
     return { kind: 'yield', events: [ev] };
@@ -324,7 +369,7 @@ function routeDone(ev, ctx) {
     const park = parkGateOf(ev.result);
     if (park !== null) {
         ctx.taskId.current = ctx.taskId.current ?? park.taskId;
-        led.noteParkGate({ fsOrShellFamily: park.gate === 'fs' && isFsOrShellToolName(park.toolName) });
+        led.noteParkGate({ fsOrShellFamily: park.gate === 'fs' && parkFamilyEvidence(led, park.toolName, gatedCallId) });
         return { kind: 'park', gate: park.gate, pendingDone: ev, ...(gatedCallId !== undefined ? { gatedCallId } : {}) };
     }
     const events = [...flushHeldWithInterruptRewrite(led, { terminal: ev, signal: ctx.signal })];
@@ -355,5 +400,17 @@ export async function routeFrame(ev, ctx) {
     if (ev.type === 'failed') {
         return { kind: 'end', events: [...flushHeldWithInterruptRewrite(led, { terminal: ev, signal: ctx.signal }), ev] };
     }
+    if (ev.type === 'approval_request') {
+        try {
+            if (!hasLedgerPositionKey(ev)) {
+                const id = ev.approvalId;
+                if (typeof id === 'string' && id !== '')
+                    led.notePreambleApproval(id);
+            }
+        }
+        catch (e) {
+            hostLog('debug', `liveHitlAskWire: approval_request frame unreadable — not counted as preamble evidence: ${String(e).slice(0, 120)}`);
+        }
+    }
     return { kind: 'yield', events: [ev] };
 }

package/dist/hitl/gateLedger.d.ts

@@ -13,10 +13,16 @@ export interface AskAnsweredOutput {
         notes?: string;
     }>;
 }
+export declare function durableSeqOf(ev: object): string | undefined;
+export declare function hasLedgerPositionKey(ev: object): boolean;
+export declare const PREAMBLE_APPROVALS_MAX_ENTRIES = 4096;
 export interface GateLedger {
     noteSeq(ev: AgentEvent): void;
     lastSeq(): string | undefined;
     forgetRunScopedState(): void;
+    notePreambleApproval(approvalId: string): void;
+    preambleApprovals(): ReadonlySet<string>;
+    beginStreamSegment(): void;
     markStarted(callId: string): boolean;
     noteGatedStart(callId: string, ev: AgentEvent): void;
     gatedStartArgs(): ReadonlyMap<string, unknown>;
@@ -40,6 +46,7 @@ export interface GateLedger {
     lastPendingFsCall(): string | undefined;
     noteFsOrShellGate(callId: string): void;
     lastFsOrShellGatedCallId(): string | undefined;
+    isFsOrShellGatedCall(callId: string): boolean;
     noteParkGate(evidence: {
         fsOrShellFamily: boolean;
     }): void;

package/dist/hitl/gateLedger.js

@@ -1,5 +1,18 @@
 export const SEMA_COLLATERAL_ABORT_KEY = '_sema_collateral_abort';
 export const SEMA_DENIAL_KIND_KEY = '_sema_denial_kind';
+export function durableSeqOf(ev) {
+    const rawSeq = ev.id ?? ev.seq;
+    if (typeof rawSeq === 'string' && rawSeq.length > 0)
+        return rawSeq;
+    if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
+        return String(rawSeq);
+    return undefined;
+}
+export function hasLedgerPositionKey(ev) {
+    const { id, seq } = ev;
+    return (id !== undefined && id !== null) || (seq !== undefined && seq !== null);
+}
+export const PREAMBLE_APPROVALS_MAX_ENTRIES = 4096;
 export const START_ARGS_MAX_ENTRIES = 256;
 function normalizeDenyAttribution(a) {
     if (a === undefined)
@@ -74,13 +87,12 @@ export function createGateLedger() {
     let denyStampNextFsEnd = false;
     let denyStampAttribution;
     let seq;
+    const preambleApprovalIds = new Set();
     return {
         noteSeq(ev) {
-            const rawSeq = ev.id ?? ev.seq;
-            if (typeof rawSeq === 'string' && rawSeq.length > 0)
-                seq = rawSeq;
-            else if (typeof rawSeq === 'number' && Number.isFinite(rawSeq))
-                seq = String(rawSeq);
+            const s = durableSeqOf(ev);
+            if (s !== undefined)
+                seq = s;
         },
         lastSeq() {
             return seq;
@@ -91,6 +103,23 @@ export function createGateLedger() {
             gatedStartArgsByCall.clear();
             startArgsByCall.clear();
         },
+        notePreambleApproval(approvalId) {
+            if (typeof approvalId !== 'string' || approvalId === '')
+                return;
+            preambleApprovalIds.delete(approvalId);
+            preambleApprovalIds.add(approvalId);
+            if (preambleApprovalIds.size > PREAMBLE_APPROVALS_MAX_ENTRIES) {
+                const oldest = preambleApprovalIds.values().next().value;
+                if (oldest !== undefined)
+                    preambleApprovalIds.delete(oldest);
+            }
+        },
+        preambleApprovals() {
+            return preambleApprovalIds;
+        },
+        beginStreamSegment() {
+            preambleApprovalIds.clear();
+        },
         markStarted(callId) {
             if (startedCalls.has(callId))
                 return false;
@@ -206,6 +235,9 @@ export function createGateLedger() {
         lastFsOrShellGatedCallId() {
             return lastFsOrShellGatedCall;
         },
+        isFsOrShellGatedCall(callId) {
+            return fsOrShellGatedCalls.has(callId);
+        },
         noteParkGate(evidence) {
             if (batchParkCount > 0 && !heldSinceLastPark)
                 return;

package/dist/hitl/hitlBridge.d.ts

@@ -56,6 +56,7 @@ export interface HitlDecideDenyOutcome {
     decision: 'deny';
     reason?: string | undefined;
     settledBy?: 'policy' | undefined;
+    decidedBy?: 'policy' | undefined;
 }
 export declare class HitlSafetyError extends Error {
     readonly code: HitlSafetyCode;

package/dist/hitl/hitlBridge.js

@@ -2,6 +2,7 @@ import { askParkForeignGateKind } from '../adapter/activeRunSelfHeal.js';
 import { eventSeq } from '../adapter/types.js';
 import { hostLog } from '../host.js';
 import { abortableSleep } from '../abortableSleep.js';
+import { readOwnDataValue } from '../ownKey.js';
 import { suspendedReopenOf } from './suspendedReopen.js';
 export const DEFAULT_DENY_REASON = 'The user rejected this tool use';
 const MAX_DENY_REASON_CHARS = 4096;
@@ -291,7 +292,11 @@ export class HitlBridge {
                 decision: 'deny',
                 ...this.bindingOf(pending),
                 ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
-                ...(outcome.settledBy === 'policy' ? { settledBy: 'policy' } : {}),
+                ...(readOwnDataValue(outcome, 'decidedBy') === 'policy'
+                    ? { decidedBy: 'policy' }
+                    : readOwnDataValue(outcome, 'settledBy') === 'policy'
+                        ? { settledBy: 'policy' }
+                        : {}),
             };
         return this.decideRaw(pending.sessionId, decision, opts);
     }

package/dist/hitl/hitlHostSurface.d.ts

@@ -28,10 +28,13 @@ export declare const REMEMBER_NOT_APPLIED_WARN_TEXT = "this session-wide allow w
 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";
 export declare function surfaceRememberNotApplied(): void;
 export declare function surfaceEditNotForwarded(): 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;
 export declare function surfaceEditRefusedOnBlindAsk(): void;
 export declare const RULE_NOT_SENT_WARN_TEXT = "your \"don't ask again\" choice was NOT sent to this engine \u2014 support for that rule form could not be confirmed. The approval itself went through, but you will be asked again";
 export declare function surfaceRuleArmNotSent(): void;
-export declare const RULE_NOT_SENT_REJECTED_WARN_TEXT = "your \"don't ask again\" choice was NOT sent \u2014 it did not pass the client-side check (the card returned a rule the engine never offered, an index that is not a batch offer, or two conflicting choices at once). The approval itself went through, but you will be asked again";
-export declare function surfaceRuleArmRejected(): void;
+export type RuleArmRejectedWhy = 'both_arms' | 'index_not_a_batch_offer' | 'text_not_offered';
+export declare const RULE_NOT_SENT_REJECTED_WARN_TEXT: string;
+export declare function surfaceRuleArmRejected(why?: RuleArmRejectedWhy): void;
 export declare function observeCancelByDeny(settle: Promise<unknown>, taskId: string): void;

package/dist/hitl/hitlHostSurface.js

@@ -72,6 +72,13 @@ export function surfaceRememberNotApplied() {
 export function surfaceEditNotForwarded() {
     surfaceSelfClearingWarn(EDIT_NOT_FORWARDED_KEY, EDIT_NOT_FORWARDED_WARN_TEXT, EDIT_NOT_FORWARDED_TIMEOUT_MS);
 }
+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';
+const REPLAYED_APPROVAL_LIST_UNREADABLE_TIMEOUT_MS = 10_000;
+export function surfaceReplayedApprovalListUnreadable() {
+    surfaceSelfClearingWarn(REPLAYED_APPROVAL_LIST_UNREADABLE_KEY, REPLAYED_APPROVAL_LIST_UNREADABLE_WARN_TEXT, REPLAYED_APPROVAL_LIST_UNREADABLE_TIMEOUT_MS);
+}
 export const EDIT_REFUSED_ON_BLIND_ASK_WARN_TEXT = 'That approval was NOT sent: this request does not expose its tool arguments here, so an edited approval cannot be applied. ' +
     'The request is still waiting — approve or deny it as it is.';
 const EDIT_REFUSED_ON_BLIND_ASK_KEY = 'hitl-edit-refused-blind-ask';
@@ -84,11 +91,26 @@ const RULE_NOT_SENT_TIMEOUT_MS = 10_000;
 export function surfaceRuleArmNotSent() {
     surfaceSelfClearingWarn(RULE_NOT_SENT_KEY, RULE_NOT_SENT_WARN_TEXT, RULE_NOT_SENT_TIMEOUT_MS);
 }
-export const RULE_NOT_SENT_REJECTED_WARN_TEXT = 'your "don\'t ask again" choice was NOT sent — it did not pass the client-side check (the card returned a rule the engine never offered, an index that is not a batch offer, or two conflicting choices at once). The approval itself went through, but you will be asked again';
+function ruleNotSentRejectedReason(why) {
+    switch (why) {
+        case 'both_arms':
+            return 'the card returned two conflicting choices at once, a rule text and a batch index';
+        case 'index_not_a_batch_offer':
+            return 'the card returned an index that is not a batch offer';
+        case 'text_not_offered':
+            return 'the card returned a rule text that is not one of the single rules the engine offered';
+        default:
+            return 'the card returned a rule text that is not one of the single rules the engine offered, an index that is not a batch offer, or two conflicting choices at once; this client cannot tell which';
+    }
+}
+function ruleNotSentRejectedText(why) {
+    return `your "don't ask again" choice was NOT sent — it did not pass the client-side check (${ruleNotSentRejectedReason(why)}). The approval itself went through, but you will be asked again`;
+}
+export const RULE_NOT_SENT_REJECTED_WARN_TEXT = ruleNotSentRejectedText();
 const RULE_NOT_SENT_REJECTED_KEY = 'hitl-rule-arm-rejected';
 const RULE_NOT_SENT_REJECTED_TIMEOUT_MS = 10_000;
-export function surfaceRuleArmRejected() {
-    surfaceSelfClearingWarn(RULE_NOT_SENT_REJECTED_KEY, RULE_NOT_SENT_REJECTED_WARN_TEXT, RULE_NOT_SENT_REJECTED_TIMEOUT_MS);
+export function surfaceRuleArmRejected(why) {
+    surfaceSelfClearingWarn(RULE_NOT_SENT_REJECTED_KEY, ruleNotSentRejectedText(why), RULE_NOT_SENT_REJECTED_TIMEOUT_MS);
 }
 function isNoPendingError(e) {
     if (e instanceof HitlSafetyError)

package/dist/hitl/livePendingAsk.js

@@ -5,20 +5,39 @@ function nonEmptyString(v) {
 function nonNegativeFinite(v) {
     return typeof v === 'number' && Number.isFinite(v) && v >= 0;
 }
+function snapshotMembers(raw) {
+    const length = raw.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+        return undefined;
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const d = Object.getOwnPropertyDescriptor(raw, i);
+        if (d === undefined || !('value' in d))
+            return undefined;
+        out.push(d.value);
+    }
+    return raw.length === length ? out : undefined;
+}
 export function readLivePendingRows(body) {
     if (body === null || typeof body !== 'object' || Array.isArray(body))
         return { kind: 'malformed' };
-    if (!('livePending' in body))
-        return { kind: 'not_reported' };
-    const raw = body.livePending;
+    const field = Object.getOwnPropertyDescriptor(body, 'livePending');
+    if (field === undefined)
+        return 'livePending' in body ? { kind: 'malformed' } : { kind: 'not_reported' };
+    if (!('value' in field))
+        return { kind: 'malformed' };
+    const raw = field.value;
     if (raw === undefined)
         return { kind: 'not_reported' };
     if (!Array.isArray(raw))
         return { kind: 'malformed' };
+    const members = snapshotMembers(raw);
+    if (members === undefined)
+        return { kind: 'malformed' };
     const rows = [];
     const seen = new Set();
     let dropped = 0;
-    for (const item of raw) {
+    for (const item of members) {
         if (item === null || typeof item !== 'object' || Array.isArray(item)) {
             dropped++;
             continue;
@@ -46,7 +65,7 @@ export function readLivePendingRows(body) {
             ...(isToolApprovalFrame(o.frame) && o.frame.type === 'tool_approval' && o.frame.approvalId === o.approvalId ? { frame: o.frame } : {}),
         });
     }
-    if (raw.length > 0 && rows.length === 0)
+    if (members.length > 0 && rows.length === 0)
         return { kind: 'malformed' };
     return { kind: 'present', rows, dropped };
 }