@sema-agent/client-core 0.90.0 → 0.92.0

package/dist/hitl/askClassPair.js

@@ -0,0 +1,42 @@
+const ABSENT = Object.freeze({ state: 'absent' });
+const MALFORMED = Object.freeze({ state: 'malformed' });
+export function readAskClassPairState(v) {
+    if (typeof v !== 'object' || v === null)
+        return ABSENT;
+    const hasAskClass = Object.hasOwn(v, 'askClass');
+    const hasClasses = Object.hasOwn(v, 'classes');
+    if (!hasAskClass && !hasClasses)
+        return ABSENT;
+    if (!hasAskClass || !hasClasses)
+        return MALFORMED;
+    const askClass = v.askClass;
+    if (typeof askClass !== 'string' || askClass === '')
+        return MALFORMED;
+    const raw = v.classes;
+    if (!Array.isArray(raw))
+        return MALFORMED;
+    const length = raw.length;
+    if (typeof length !== 'number' || !Number.isSafeInteger(length) || length <= 0)
+        return MALFORMED;
+    const classes = [];
+    const seen = new Set();
+    for (let i = 0; i < length; i++) {
+        const d = Object.getOwnPropertyDescriptor(raw, i);
+        if (d === undefined || !('value' in d))
+            return MALFORMED;
+        const c = d.value;
+        if (typeof c !== 'string' || c === '' || seen.has(c))
+            return MALFORMED;
+        seen.add(c);
+        classes.push(c);
+    }
+    if (raw.length !== length)
+        return MALFORMED;
+    if (classes[0] !== askClass)
+        return MALFORMED;
+    return Object.freeze({ state: 'pair', askClass, classes: Object.freeze(classes) });
+}
+export function readAskClassPair(v) {
+    const r = readAskClassPairState(v);
+    return r.state === 'pair' ? { askClass: r.askClass, classes: r.classes } : undefined;
+}

package/dist/hitl/askGateWire.d.ts

@@ -8,7 +8,7 @@ export type { AskAnsweredOutput } from './gateLedger.js';
 export { SEMA_COLLATERAL_ABORT_KEY } from './gateLedger.js';
 export { SEMA_DENIAL_KIND_KEY } from './gateLedger.js';
 export type { GateDenyAttribution } from './gateLedger.js';
-export { toAnsweredOutput, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, GATE_FAILURE_CODES, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedFailure, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, GATE_FAILURE_CODES, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
 export type { HopBudget, HopRound } from './parkResolver.js';
 export type { GateOutcome, GateFailureCode } from './parkResolver.js';
 export declare function bridgeAskUserQuestionGates(source: AsyncGenerator<AgentEvent>, deps: AskGateWireDeps, opts?: {

package/dist/hitl/askGateWire.js

@@ -6,7 +6,7 @@ export { HITL_INTERRUPT_MESSAGE_FOR_TOOL_USE } from './frameRouter.js';
 export { HITL_POLICY_DENY_MESSAGE } from './frameRouter.js';
 export { SEMA_COLLATERAL_ABORT_KEY } from './gateLedger.js';
 export { SEMA_DENIAL_KIND_KEY } from './gateLedger.js';
-export { toAnsweredOutput, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, GATE_FAILURE_CODES, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
+export { toAnsweredOutput, isAlreadyResolvedFailure, isAlreadyResolvedGateReason, isGateStandingErrorCode, isCodeClassifiedGateFailure, GATE_FAILURE_CODES, nextHopBudget, MAX_GATE_HOPS, MAX_TOTAL_PARKS } from './parkResolver.js';
 export async function* bridgeAskUserQuestionGates(source, deps, opts) {
     const led = createGateLedger();
     const taskId = { current: opts?.taskId };
@@ -116,6 +116,7 @@ export async function* bridgeAskUserQuestionGates(source, deps, opts) {
             led.forgetRunScopedState();
         }
         const seq = handoff !== undefined ? undefined : led.lastSeq();
+        led.beginStreamSegment();
         stream = deps.runsEvents(taskId.current, {
             ...(seq !== undefined ? { lastEventId: seq } : {}),
             ...(opts?.signal ? { signal: opts.signal } : {}),

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[];
@@ -28,3 +29,10 @@ export interface CrashConvergedProjection {
     readonly dropped: number;
 }
 export declare function projectCrashConverged(env: unknown): CrashConvergedProjection | undefined;
+export interface CrashConvergedNoticeFacts {
+    readonly total: number;
+    readonly dropped: number;
+    readonly needsHumanReasons: readonly (string | undefined)[];
+    readonly causes: readonly CrashConvergedRow['cause'][] | undefined;
+}
+export declare function readCrashConvergedNoticeFacts(projection: CrashConvergedProjection | undefined): CrashConvergedNoticeFacts | undefined;

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;
@@ -127,3 +127,60 @@ export function projectCrashConverged(env) {
     }
     return { total: resumeSafe.length + needsHuman.length, resumeSafe, needsHuman, dropped };
 }
+const isCount = (v) => typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+function bucketRowsOf(bucket) {
+    if (!Array.isArray(bucket))
+        return undefined;
+    const len = ownDataValue(bucket, 'length');
+    if (!isCount(len) || len > MAX_CRASH_CONVERGED_ROWS)
+        return undefined;
+    const rows = [];
+    for (let i = 0; i < len; i++)
+        rows.push(ownDataValue(bucket, String(i)));
+    return rows;
+}
+function reasonTextOf(row) {
+    try {
+        if (typeof row !== 'object' || row === null)
+            return undefined;
+        const v = ownDataValue(row, 'needsHumanReason');
+        return typeof v === 'string' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function causeWordsOf(rows) {
+    const seen = [];
+    try {
+        for (const row of rows) {
+            if (typeof row !== 'object' || row === null)
+                return undefined;
+            const c = ownDataValue(row, 'cause');
+            if (isCrashConvergedCause(c) && !seen.includes(c))
+                seen.push(c);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return seen;
+}
+export function readCrashConvergedNoticeFacts(projection) {
+    try {
+        if (typeof projection !== 'object' || projection === null)
+            return undefined;
+        const total = ownDataValue(projection, 'total');
+        const dropped = ownDataValue(projection, 'dropped');
+        if (!isCount(total) || !isCount(dropped) || total > MAX_CRASH_CONVERGED_ROWS)
+            return undefined;
+        const safe = bucketRowsOf(ownDataValue(projection, 'resumeSafe'));
+        const human = bucketRowsOf(ownDataValue(projection, 'needsHuman'));
+        if (safe === undefined || human === undefined || safe.length + human.length !== total)
+            return undefined;
+        return { total, dropped, needsHumanReasons: human.map(reasonTextOf), causes: causeWordsOf([...safe, ...human]) };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/hitl/crashConvergedNotice.d.ts

@@ -0,0 +1,4 @@
+import type { CrashConvergedProjection } from './crashConverged.js';
+export declare const NEEDS_HUMAN_REASON_ORDER: readonly ["approved_then_interrupted", "pending_unsafe", "contradictory", "unstable_row"];
+export declare function crashConvergedNeedsHumanSentence(reason: string | undefined, n: number, total: number): string | undefined;
+export declare function crashConvergedNotice(projection: CrashConvergedProjection | undefined): string | undefined;

package/dist/hitl/crashConvergedNotice.js

@@ -0,0 +1,57 @@
+import { readCrashConvergedNoticeFacts } from './crashConverged.js';
+export const NEEDS_HUMAN_REASON_ORDER = Object.freeze(['approved_then_interrupted', 'pending_unsafe', 'contradictory', 'unstable_row']);
+const _orderCoversReasons = true;
+const _orderInsideReasons = true;
+const _orderHasNoDuplicate = true;
+void _orderCoversReasons;
+void _orderInsideReasons;
+void _orderHasNoDuplicate;
+const RECORDED = 'based on what was recorded';
+const NO_AUTO_RERUN = 'sema has not re-run anything';
+const plural = (n, one, many) => (n === 1 ? one : many);
+const SENTENCE = Object.freeze({
+    approved_then_interrupted: (n, total) => `${n} of ${total} had already been approved and may have been running when the previous engine run ended, so a side effect may have partly landed`,
+    pending_unsafe: (n, total) => `${n} of ${total} had not started, ${RECORDED}, but the engine did not mark ${plural(n, 'it', 'them')} as safe to re-run`,
+    contradictory: (n, total) => `${n} of ${total} ${plural(n, 'has a contradictory record', 'have contradictory records')}`,
+    unstable_row: (n, total) => `${n} of ${total} ${plural(n, 'has a record that read differently each time it was read', 'have records that read differently each time they were read')}`,
+});
+const fallbackSentence = (n, total) => `${n} of ${total} had already been approved, or cannot be accounted for, so a side effect may have partly landed`;
+const isNeedsHumanReason = (v) => typeof v === 'string' && Object.hasOwn(SENTENCE, v);
+export function crashConvergedNeedsHumanSentence(reason, n, total) {
+    if (!isNeedsHumanReason(reason))
+        return undefined;
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 1)
+        return undefined;
+    if (typeof total !== 'number' || !Number.isSafeInteger(total) || total < n)
+        return undefined;
+    return SENTENCE[reason](n, total);
+}
+function needsHumanClauses(reasons, total) {
+    const clauses = [];
+    for (const reason of NEEDS_HUMAN_REASON_ORDER) {
+        const n = reasons.filter((r) => r === reason).length;
+        if (n > 0)
+            clauses.push(SENTENCE[reason](n, total));
+    }
+    const fallback = reasons.filter((r) => !isNeedsHumanReason(r)).length;
+    if (fallback > 0)
+        clauses.push(fallbackSentence(fallback, total));
+    return `${clauses.join('; ')} — check ${plural(reasons.length, 'it', 'them')} by hand before re-running`;
+}
+export function crashConvergedNotice(projection) {
+    const facts = readCrashConvergedNoticeFacts(projection);
+    if (facts === undefined)
+        return undefined;
+    const { total, dropped, needsHumanReasons, causes } = facts;
+    if (total === 0 && dropped === 0)
+        return undefined;
+    if (total === 0) {
+        return `the previous session left ${dropped} crash-converged approval ${plural(dropped, 'record', 'records')} that this version could not read. ${NO_AUTO_RERUN}.`;
+    }
+    const recordedAs = causes !== undefined && causes.length > 0 ? ` (recorded as ${causes.join(', ')})` : '';
+    const head = `the previous engine run ended with ${total} ${plural(total, 'approval', 'approvals')} still waiting${recordedAs}, ` +
+        `and the engine converged ${plural(total, 'it', 'them')} to denied`;
+    const body = needsHumanReasons.length > 0 ? needsHumanClauses(needsHumanReasons, total) : `${RECORDED}, ${plural(total, 'it', 'they')} can be re-run`;
+    const droppedClause = dropped > 0 ? ` (${dropped} further ${plural(dropped, 'record', 'records')} could not be read.)` : '';
+    return `${head}; ${body}. ${NO_AUTO_RERUN}.${droppedClause}`;
+}

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';
@@ -233,22 +235,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 +291,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))
@@ -355,5 +395,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>;

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;