@sema-agent/client-core 0.95.0 → 0.97.0

package/dist/engineDirectory.js

@@ -0,0 +1,186 @@
+import { guardedRead, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
+const KIND_WORDS = ['managed'];
+const POSTURE_WORDS = ['single', 'multi'];
+const RULE_WORDS = ['only-one', 'none', 'ambiguous'];
+const UNREADABLE = Object.freeze({ kind: 'unreadable' });
+function isCenterRelativePath(path) {
+    if (path.length === 0 || path.charCodeAt(0) !== 0x2f)
+        return false;
+    const second = path.charCodeAt(1);
+    if (second === 0x2f || second === 0x5c)
+        return false;
+    if (/[\s\u0000-\u001f\u007f-\u009f\\?#]/u.test(path))
+        return false;
+    return path.split('/').every((segment) => {
+        const decoded = segment.replace(/%2e/gi, '.');
+        return decoded !== '.' && decoded !== '..';
+    });
+}
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function stringOf(holder, key) {
+    return guardedRead(() => readOwnDataNonEmptyString(holder, key));
+}
+function boolOf(holder, key) {
+    return guardedRead(() => {
+        const v = readOwnDataValue(holder, key);
+        return typeof v === 'boolean' ? v : undefined;
+    });
+}
+function wordOf(holder, key, listed) {
+    const word = stringOf(holder, key);
+    if (word === undefined)
+        return UNREADABLE;
+    const hit = listed.find((w) => w === word);
+    return hit !== undefined ? { kind: 'listed', word: hit } : { kind: 'unlisted', word };
+}
+function rowOf(raw) {
+    try {
+        if (!isObj(raw))
+            return undefined;
+        const name = stringOf(raw, 'name');
+        if (name === undefined)
+            return undefined;
+        const connect = guardedRead(() => readOwnDataValue(raw, 'connect'));
+        if (!isObj(connect))
+            return undefined;
+        const viaCenter = stringOf(connect, 'viaCenter');
+        if (viaCenter === undefined || !isCenterRelativePath(viaCenter))
+            return undefined;
+        return {
+            name,
+            kind: wordOf(raw, 'kind', KIND_WORDS),
+            scope: stringOf(raw, 'scope'),
+            online: boolOf(raw, 'online'),
+            posture: wordOf(raw, 'posture', POSTURE_WORDS),
+            viaCenter,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function rowSetOf(raw) {
+    try {
+        if (!Array.isArray(raw))
+            return undefined;
+        const length = readOwnDataValue(raw, 'length');
+        if (typeof length !== 'number' || !Number.isSafeInteger(length) || length < 0)
+            return undefined;
+        const rows = [];
+        const unreadableNames = [];
+        let unreadableRows = 0;
+        for (let i = 0; i < length; i += 1) {
+            const element = guardedRead(() => readOwnDataValue(raw, String(i)));
+            const row = rowOf(element);
+            if (row !== undefined) {
+                rows.push(row);
+                continue;
+            }
+            unreadableRows += 1;
+            const name = guardedRead(() => (isObj(element) ? stringOf(element, 'name') : undefined));
+            if (name !== undefined)
+                unreadableNames.push(name);
+        }
+        return { rows, unreadableRows, unreadableNames };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function projectEngineDirectory(body) {
+    try {
+        if (!isObj(body))
+            return undefined;
+        return rowSetOf(readOwnDataValue(body, 'engines'));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function projectMeEngine(body) {
+    try {
+        if (!isObj(body))
+            return undefined;
+        const rule = wordOf(body, 'rule', RULE_WORDS);
+        const rawTarget = guardedRead(() => readOwnDataValue(body, 'target'));
+        let target = UNREADABLE;
+        if (rawTarget === null) {
+            target = { kind: 'null' };
+        }
+        else {
+            const row = rowOf(rawTarget);
+            if (row !== undefined)
+                target = { kind: 'row', row };
+        }
+        const candidates = guardedRead(() => rowSetOf(readOwnDataValue(body, 'candidates')));
+        if (rule.kind === 'unreadable' && target.kind === 'unreadable' && candidates === undefined)
+            return undefined;
+        return { rule, target, candidates };
+    }
+    catch {
+        return undefined;
+    }
+}
+export function decideMeEngine(reading) {
+    try {
+        if (reading === undefined)
+            return { kind: 'unresolved', reason: 'body', rule: UNREADABLE, candidates: undefined };
+        const { rule, target, candidates } = reading;
+        const unresolved = (reason) => ({ kind: 'unresolved', reason, rule, candidates });
+        if (rule.kind === 'unreadable')
+            return unresolved('rule');
+        if (target.kind === 'unreadable')
+            return unresolved('target');
+        if (target.kind === 'row') {
+            if (rule.kind === 'listed' && (rule.word === 'none' || rule.word === 'ambiguous'))
+                return unresolved('conflict');
+            if (candidates === undefined)
+                return unresolved('candidates');
+            const picked = target.row;
+            if (!candidates.rows.some((row) => row.name === picked.name && row.viaCenter === picked.viaCenter))
+                return unresolved('conflict');
+            if (rule.kind === 'listed' && (candidates.rows.length !== 1 || candidates.unreadableRows !== 0))
+                return unresolved('conflict');
+            return { kind: 'connect', engine: picked, rule };
+        }
+        if (rule.kind === 'unlisted')
+            return unresolved('rule-unlisted');
+        if (rule.word === 'only-one')
+            return unresolved('conflict');
+        if (candidates === undefined)
+            return unresolved('candidates');
+        if (rule.word === 'none') {
+            if (candidates.rows.length === 0 && candidates.unreadableRows === 0)
+                return { kind: 'no-engine' };
+            return unresolved('conflict');
+        }
+        if (candidates.rows.length === 0)
+            return unresolved('candidates');
+        return candidates.rows.length + candidates.unreadableRows >= 2 ? { kind: 'choose', candidates } : unresolved('conflict');
+    }
+    catch {
+        return { kind: 'unresolved', reason: 'body', rule: UNREADABLE, candidates: undefined };
+    }
+}
+export function engineOverrideOf(set, requested) {
+    try {
+        if (typeof requested !== 'string' || requested === '')
+            return { kind: 'invalid' };
+        if (set === undefined)
+            return { kind: 'unreadable' };
+        const hits = set.rows.filter((row) => row.name === requested);
+        const hidden = set.unreadableNames.filter((name) => name === requested).length;
+        if (hits.length + hidden > 1)
+            return { kind: 'duplicate', name: requested };
+        if (hits.length === 1)
+            return { kind: 'select', engine: hits[0] };
+        if (hidden === 1)
+            return { kind: 'row-unreadable', name: requested };
+        return { kind: 'not-listed', candidates: set };
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+}

package/dist/engineErrorCodes.d.ts

@@ -18,7 +18,6 @@ export declare const CONFIG_IMAGE_INVALID = "config.image_invalid";
 export declare function imageInvalidFailureNoteOf(code: string | undefined): string | undefined;
 export declare const CONFIG_AGENT_UNKNOWN_TOOL = "config.agent.unknown_tool";
 export declare const CONFIG_OUTPUT_STYLE_INVALID = "config.output_style_invalid";
-export declare const CONFIG_REFUSAL_CODES: ReadonlySet<string>;
 export declare const RULES_LEGACY_TOOL_NAME = "rules.legacy_tool_name";
 export declare function isRulesRefusalCode(code: string | undefined): boolean;
 export declare const DELEGATION_CONCURRENCY_CAP = "delegation.concurrency_cap";
@@ -33,8 +32,21 @@ export declare const TOOL_END_INTERRUPTED_NEVER_STARTED = "interrupted_never_sta
 export declare const TOOL_END_INTERRUPTED_OUTCOME_UNKNOWN = "interrupted_outcome_unknown";
 export declare function isInterruptedToolEndCode(code: string | undefined): boolean;
 export declare const CAPABILITY_SELF_ORCHESTRATION_REQUIRED = "capability.self_orchestration_required";
+export declare const CAPABILITY_IMAGE_INDEX_REQUIRED = "capability.image_index_required";
 export declare const GATE_PARKED_ERROR_CODE = "gate.parked";
 export declare const ACTIVE_RUN_BUSY_ERROR_CODE = "conflict.session_active_run";
+export declare const CONFLICT_IDEMPOTENCY_PAYLOAD_MISMATCH = "conflict.idempotency_payload_mismatch";
+export declare function isIdempotencyPayloadMismatchCode(code: string | null | undefined): boolean;
+export declare function idempotencyPayloadMismatchContent(): string;
+export interface BusyClassification {
+    readonly busy: boolean;
+    readonly handle: string | null;
+}
+export declare function classifyActiveRunBusy(input: {
+    errorCode: string | undefined;
+    activeTaskId: unknown;
+}): BusyClassification;
+export declare function activeRunBusyCarrierOf(ev: unknown): Record<string, unknown> | null;
 export declare const CORRUPT_SESSION_ERROR_CODE = "corrupt_session";
 export declare function isCorruptSessionCode(code: string | null | undefined): boolean;
 export declare const STOP_PARK_ARBITER_UNREACHABLE = "stop.park_arbiter_unreachable";
@@ -58,6 +70,8 @@ export declare const REQUEST_AUTONOMY_LANE_REFUSED = "request.autonomy_lane_refu
 export declare const CHECKPOINT_UNSUPPORTED_VERSION = "checkpoint.unsupported_version";
 export declare const CHECKPOINT_WALLTIME_AXIS_RETIRED = "checkpoint.walltime_axis_retired";
 export declare const CHECKPOINT_CONFIG_REFUSED = "checkpoint.config_refused";
+export declare const CHECKPOINT_REFUSED_PARK_CODES: readonly string[];
+export declare function isRefusedParkCode(code: string | null | undefined): code is typeof CHECKPOINT_UNSUPPORTED_VERSION | typeof CHECKPOINT_WALLTIME_AXIS_RETIRED | typeof CHECKPOINT_CONFIG_REFUSED;
 export declare function refusalSaysStillPending(err: object): boolean;
 export declare function refusalRetriableReading(err: object): boolean | undefined;
 export type StatusDerivedCoarseCode = (typeof STATUS_DERIVED_COARSE_CODES)[number];
@@ -85,9 +99,11 @@ export declare const RESUME_OUTCOME_INVALID = "resume_outcome_invalid";
 export declare const CHECKPOINT_ALREADY_RESOLVED = "checkpoint.already_resolved";
 export declare const NOT_FOUND_APPROVAL = "not_found.approval";
 export declare const NOT_FOUND_CHECKPOINT = "not_found.checkpoint";
+export declare const NOT_FOUND_BLOB = "not_found.blob";
 export declare const DECIDE_ALREADY_RESOLVED_CODES: readonly string[];
 export declare function isDecideAlreadyResolvedCode(code: string | null | undefined): boolean;
 export declare const ASK_GONE = "gone.ask";
+export declare const ASK_GONE_PARKED = "gone.ask_parked";
 export declare const ASK_GONE_DENIED_WORD: "routing_failure_fail_closed";
 export declare const RUN_DEATH_VERDICT_CODES: readonly ["run.stalled", "run.orphaned", "approval.expired"];
 export type RunDeathVerdictCode = (typeof RUN_DEATH_VERDICT_CODES)[number];

package/dist/engineErrorCodes.js

@@ -1,5 +1,5 @@
 import { frozenSet } from './frozenSet.js';
-import { CORE_TOOL_DECLARATION_CODES } from './generated/engineFactTables.js';
+import { ownDataField } from './ownKey.js';
 import { SDK_DENY_REASON_ROUTING_FAILURE, SDK_RUN_DEATH_VERDICT_CODES, SDK_STATUS_DERIVED_COARSE_CODES } from './generated/sdkFactTables.js';
 export const LIMITS_MAX_TOKENS_EXCEEDED = 'limits.max_tokens_exceeded';
 export const LIMITS_MAX_COST_EXCEEDED = 'limits.max_cost_exceeded';
@@ -28,20 +28,6 @@ export function imageInvalidFailureNoteOf(code) {
 }
 export const CONFIG_AGENT_UNKNOWN_TOOL = 'config.agent.unknown_tool';
 export const CONFIG_OUTPUT_STYLE_INVALID = 'config.output_style_invalid';
-export const CONFIG_REFUSAL_CODES = frozenSet([
-    CONFIG_LIMIT_INVALID,
-    CONFIG_STRATEGY_FIND_LIMIT_INVALID,
-    CONFIG_STRATEGY_MAX_SIZE_INVALID,
-    CONFIG_LIMIT_UNKNOWN_KEY,
-    CONFIG_DELEGATION_ENTRY_CAPS,
-    CONFIG_MEMORY_PROJECT_KEY_SPELLING,
-    CONFIG_MEMORY_WRITE_SCOPE_MISMATCH,
-    CONFIG_LEGACY_TOOL_NAME,
-    CONFIG_IMAGE_INVALID,
-    CONFIG_AGENT_UNKNOWN_TOOL,
-    CONFIG_OUTPUT_STYLE_INVALID,
-    ...CORE_TOOL_DECLARATION_CODES,
-]);
 export const RULES_LEGACY_TOOL_NAME = 'rules.legacy_tool_name';
 const RULES_ERROR_CODE_PREFIX = 'rules.';
 export function isRulesRefusalCode(code) {
@@ -77,8 +63,42 @@ export function isInterruptedToolEndCode(code) {
     return typeof code === 'string' && TOOL_END_INTERRUPTED_CODES.has(code);
 }
 export const CAPABILITY_SELF_ORCHESTRATION_REQUIRED = 'capability.self_orchestration_required';
+export const CAPABILITY_IMAGE_INDEX_REQUIRED = 'capability.image_index_required';
 export const GATE_PARKED_ERROR_CODE = 'gate.parked';
 export const ACTIVE_RUN_BUSY_ERROR_CODE = 'conflict.session_active_run';
+export const CONFLICT_IDEMPOTENCY_PAYLOAD_MISMATCH = 'conflict.idempotency_payload_mismatch';
+export function isIdempotencyPayloadMismatchCode(code) {
+    return code === CONFLICT_IDEMPOTENCY_PAYLOAD_MISMATCH;
+}
+export function idempotencyPayloadMismatchContent() {
+    return 'This request reused an idempotency key that is already bound to a different request body, so the engine refused it and nothing ran · To retry, send exactly the same request again; to send a different request, use a new idempotency key';
+}
+export function classifyActiveRunBusy(input) {
+    const handle = typeof input.activeTaskId === 'string' && input.activeTaskId.length > 0 ? input.activeTaskId : null;
+    if (input.errorCode === ACTIVE_RUN_BUSY_ERROR_CODE)
+        return { busy: true, handle };
+    if (typeof input.activeTaskId === 'string')
+        return { busy: true, handle };
+    return { busy: false, handle };
+}
+export function activeRunBusyCarrierOf(ev) {
+    if (typeof ev !== 'object' || ev === null || !('type' in ev))
+        return null;
+    const type = ev.type;
+    if (type === 'failed')
+        return ev;
+    if (type !== 'done')
+        return null;
+    const result = ev.result;
+    if (typeof result !== 'object' || result === null)
+        return null;
+    const status = result.status;
+    if (status === 'failed')
+        return result;
+    if (status === undefined && !Array.isArray(result) && Object.hasOwn(result, 'terminal'))
+        return result;
+    return null;
+}
 export const CORRUPT_SESSION_ERROR_CODE = 'corrupt_session';
 export function isCorruptSessionCode(code) {
     return code === CORRUPT_SESSION_ERROR_CODE;
@@ -114,12 +134,20 @@ export const REQUEST_AUTONOMY_LANE_REFUSED = 'request.autonomy_lane_refused';
 export const CHECKPOINT_UNSUPPORTED_VERSION = 'checkpoint.unsupported_version';
 export const CHECKPOINT_WALLTIME_AXIS_RETIRED = 'checkpoint.walltime_axis_retired';
 export const CHECKPOINT_CONFIG_REFUSED = 'checkpoint.config_refused';
+export const CHECKPOINT_REFUSED_PARK_CODES = Object.freeze([
+    CHECKPOINT_UNSUPPORTED_VERSION,
+    CHECKPOINT_WALLTIME_AXIS_RETIRED,
+    CHECKPOINT_CONFIG_REFUSED,
+]);
+export function isRefusedParkCode(code) {
+    return typeof code === 'string' && CHECKPOINT_REFUSED_PARK_CODES.includes(code);
+}
 export function refusalSaysStillPending(err) {
     return refusalRetriableReading(err) === true;
 }
 export function refusalRetriableReading(err) {
     try {
-        return Object.hasOwn(err, 'retriable') && err.retriable === true;
+        return ownDataField(err, 'retriable') === true;
     }
     catch {
         return undefined;
@@ -167,6 +195,7 @@ export const RESUME_OUTCOME_INVALID = 'resume_outcome_invalid';
 export const CHECKPOINT_ALREADY_RESOLVED = 'checkpoint.already_resolved';
 export const NOT_FOUND_APPROVAL = 'not_found.approval';
 export const NOT_FOUND_CHECKPOINT = 'not_found.checkpoint';
+export const NOT_FOUND_BLOB = 'not_found.blob';
 export const DECIDE_ALREADY_RESOLVED_CODES = Object.freeze([
     APPROVAL_STALE,
     CHECKPOINT_ALREADY_RESOLVED,
@@ -177,6 +206,7 @@ export function isDecideAlreadyResolvedCode(code) {
     return typeof code === 'string' && DECIDE_ALREADY_RESOLVED_CODES.includes(code);
 }
 export const ASK_GONE = 'gone.ask';
+export const ASK_GONE_PARKED = 'gone.ask_parked';
 export const ASK_GONE_DENIED_WORD = SDK_DENY_REASON_ROUTING_FAILURE;
 export const RUN_DEATH_VERDICT_CODES = SDK_RUN_DEATH_VERDICT_CODES;
 const _runDeathVerdictCodePin = true;

package/dist/engineNoticeCodes.d.ts

@@ -171,6 +171,7 @@ export type ToolTurnIncompleteCause = (typeof CORE_TOOL_TURN_INCOMPLETE_CAUSES)[
 export interface ToolTurnIncompleteFactsView {
     cause: string;
     count: number;
+    outcome?: string;
     toolCallIds?: readonly string[];
     sessionId: string;
     runId: string;
@@ -201,6 +202,20 @@ export declare function readTurnInterrupted(notice: unknown): TurnInterruptedFac
 export declare function turnInterruptedNotice(facts: Pick<TurnInterruptedFactsView, 'lane'>): string | undefined;
 export type SteerCutVerdict = 'this_input' | 'other_input' | 'user_halt' | 'unattributed' | 'not_a_cut';
 export declare function steerCutVerdict(notice: unknown, messageId: string | undefined): SteerCutVerdict;
+export interface FinishReasonUnknownFactsView {
+    finishReason: string;
+    sessionId: string;
+    runId: string;
+}
+export declare function readFinishReasonUnknown(notice: unknown): FinishReasonUnknownFactsView | undefined;
+export interface StreamEndIgnoredFactsView {
+    statement: string;
+    word: string;
+    frames: number;
+    sessionId: string;
+    runId: string;
+}
+export declare function readStreamEndIgnored(notice: unknown): StreamEndIgnoredFactsView | undefined;
 export declare const ENGINE_NOTICE_FACT_READERS: Readonly<{
     readonly 'mcp.injection_dropped': typeof readMcpInjectionDrop;
     readonly 'delegation.ask_unresolvable': typeof readAskUnresolvable;
@@ -223,6 +238,8 @@ export declare const ENGINE_NOTICE_FACT_READERS: Readonly<{
     readonly 'task.user_steer_undrained': typeof readUserInputUndrained;
     readonly 'task.user_followup_undrained': typeof readUserInputUndrained;
     readonly 'task.turn_interrupted': typeof readTurnInterrupted;
+    readonly 'route.finish_reason_unknown': typeof readFinishReasonUnknown;
+    readonly 'route.stream_end_ignored': typeof readStreamEndIgnored;
 }>;
 type FactReaderTable = typeof ENGINE_NOTICE_FACT_READERS;
 export type EngineNoticeFactsCode = keyof FactReaderTable;

package/dist/engineNoticeCodes.js

@@ -602,12 +602,21 @@ function readToolTurnIncompleteOf(notice) {
     const o = d;
     const cause = nonEmpty(ownSeat(o, 'cause'));
     const count = positiveInt(ownSeat(o, 'count'));
+    const outcome = optionalNonEmpty(o, 'outcome');
     const toolCallIds = optionalNameList(o, 'toolCallIds');
     const sessionId = nonEmpty(ownSeat(o, 'sessionId'));
     const runId = nonEmpty(ownSeat(o, 'runId'));
     if (cause === undefined || count === undefined || sessionId === undefined || runId === undefined)
         return undefined;
-    return { cause, count, ...(toolCallIds !== undefined ? { toolCallIds } : {}), sessionId, runId };
+    return { cause, count, ...(outcome !== undefined ? { outcome } : {}), ...(toolCallIds !== undefined ? { toolCallIds } : {}), sessionId, runId };
+}
+function optionalNonEmpty(o, key) {
+    try {
+        return nonEmpty(ownSeat(o, key));
+    }
+    catch {
+        return undefined;
+    }
 }
 export function readUserInputUndrained(notice) {
     return guardedRead(notice, readUserInputUndrainedOf);
@@ -779,6 +788,48 @@ export function steerCutVerdict(notice, messageId) {
         return 'unattributed';
     return facts.inputId === messageId ? 'this_input' : 'other_input';
 }
+export function readFinishReasonUnknown(notice) {
+    return guardedRead(notice, readFinishReasonUnknownOf);
+}
+function readFinishReasonUnknownOf(notice) {
+    if (typeof notice !== 'object' || notice === null || Array.isArray(notice))
+        return undefined;
+    const n = notice;
+    if (ownSeat(n, 'code') !== 'route.finish_reason_unknown')
+        return undefined;
+    const d = ownSeat(n, 'detail');
+    if (typeof d !== 'object' || d === null || Array.isArray(d))
+        return undefined;
+    const o = d;
+    const finishReason = nonEmpty(ownSeat(o, 'finishReason'));
+    const sessionId = nonEmpty(ownSeat(o, 'sessionId'));
+    const runId = nonEmpty(ownSeat(o, 'runId'));
+    if (finishReason === undefined || sessionId === undefined || runId === undefined)
+        return undefined;
+    return { finishReason, sessionId, runId };
+}
+export function readStreamEndIgnored(notice) {
+    return guardedRead(notice, readStreamEndIgnoredOf);
+}
+function readStreamEndIgnoredOf(notice) {
+    if (typeof notice !== 'object' || notice === null || Array.isArray(notice))
+        return undefined;
+    const n = notice;
+    if (ownSeat(n, 'code') !== 'route.stream_end_ignored')
+        return undefined;
+    const d = ownSeat(n, 'detail');
+    if (typeof d !== 'object' || d === null || Array.isArray(d))
+        return undefined;
+    const o = d;
+    const statement = nonEmpty(ownSeat(o, 'statement'));
+    const word = nonEmpty(ownSeat(o, 'word'));
+    const frames = positiveInt(ownSeat(o, 'frames'));
+    const sessionId = nonEmpty(ownSeat(o, 'sessionId'));
+    const runId = nonEmpty(ownSeat(o, 'runId'));
+    if (statement === undefined || word === undefined || frames === undefined || sessionId === undefined || runId === undefined)
+        return undefined;
+    return { statement, word, frames, sessionId, runId };
+}
 export const ENGINE_NOTICE_FACT_READERS = Object.freeze({
     'mcp.injection_dropped': readMcpInjectionDrop,
     'delegation.ask_unresolvable': readAskUnresolvable,
@@ -801,6 +852,8 @@ export const ENGINE_NOTICE_FACT_READERS = Object.freeze({
     'task.user_steer_undrained': readUserInputUndrained,
     'task.user_followup_undrained': readUserInputUndrained,
     'task.turn_interrupted': readTurnInterrupted,
+    'route.finish_reason_unknown': readFinishReasonUnknown,
+    'route.stream_end_ignored': readStreamEndIgnored,
 });
 const _factReaderTablePin = true;
 void _factReaderTablePin;

package/dist/executionLaneCapability.d.ts

@@ -7,6 +7,8 @@ export interface ExecutionLaneCapabilityView {
 }
 export type ExecutionLaneReading = {
     kind: 'unobserved';
+} | {
+    kind: 'unreadable';
 } | {
     kind: 'not_reported';
 } | {

package/dist/executionLaneCapability.js

@@ -1,6 +1,6 @@
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
-import { createEngineCapReader } from './engineCapReader.js';
+import { createEngineCapReader, unreadableReadingDetail } from './engineCapReader.js';
 import { ownDataField } from './ownKey.js';
 export function projectExecutionLaneCapability(caps) {
     try {
@@ -55,7 +55,6 @@ export function projectExecutionLaneWiring(wiring) {
 const reader = createEngineCapReader({
     name: 'executionLane',
     project: projectExecutionLaneCapability,
-    makeUnobserved: () => ({ kind: 'unobserved' }),
 });
 export function noteEngineCapsForExecutionLane(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
@@ -98,6 +97,8 @@ export function noOsSandboxContent() {
 const LANE_DETAIL_MAX = 40;
 export function executionLaneDoctorDetail(reading) {
     switch (reading.kind) {
+        case 'unreadable':
+            return unreadableReadingDetail('execution lane');
         case 'unobserved':
             return ('execution lane not observed — the engine reports it on /v1/capabilities; ' +
                 'this process has no usable capabilities reading cached for it (none received, the last one was unreadable, or the last one was discarded when the engine connection was reset; this process cannot tell which)');

package/dist/fileHistoryCaptureCapability.d.ts

@@ -1,5 +1,7 @@
 export type FileHistoryCaptureReading = {
     kind: 'unobserved';
+} | {
+    kind: 'unreadable';
 } | {
     kind: 'not_reported';
 } | {
@@ -16,5 +18,19 @@ export declare function fileHistoryCaptureMode(reading: FileHistoryCaptureReadin
 export declare function fileHistoryDeclarationField(reading: FileHistoryCaptureReading, captureOff: boolean): {
     fileHistory: 'disabled';
 } | Record<string, never>;
+export declare const FILE_HISTORY_TIGHTEN_VERDICTS: readonly ["not_requested", "declare", "already_off", "unjudged"];
+export type FileHistoryTightenVerdict = (typeof FILE_HISTORY_TIGHTEN_VERDICTS)[number];
+export declare function fileHistoryTightenVerdict(reading: FileHistoryCaptureReading, captureOffByUser: boolean): FileHistoryTightenVerdict;
+export declare function fileHistoryUnjudgedRefusal(reading: FileHistoryCaptureReading, captureOffByUser: boolean): string | undefined;
+export interface FileHistoryTightenJudgement {
+    readonly verdict: FileHistoryTightenVerdict;
+    readonly reading: FileHistoryCaptureReading;
+    readonly refreshed: boolean;
+    readonly refusal: string | undefined;
+}
+export declare function judgeFileHistoryTighten(captureOffByUser: boolean, opts?: {
+    baseUrl?: string;
+    withinMs?: number;
+}): Promise<FileHistoryTightenJudgement>;
 export declare function fileHistoryCaptureDoctorDetail(reading: FileHistoryCaptureReading): string;
 export declare function __resetFileHistoryCaptureReadingsForTests(): void;

package/dist/fileHistoryCaptureCapability.js

@@ -1,6 +1,7 @@
 import { capForDisplay } from './fleetTaskDesc.js';
 import { engineWireTarget } from './engineWireTarget.js';
-import { createEngineCapReader } from './engineCapReader.js';
+import { createEngineCapReader, unreadableReadingDetail } from './engineCapReader.js';
+import { refreshEngineCapsOnce } from './engineCapsCache.js';
 import { ownDataField } from './ownKey.js';
 import { FILE_HISTORY_DISABLED } from './request/taskRequest.js';
 export function projectFileHistoryCaptureCapability(caps) {
@@ -21,7 +22,6 @@ export function projectFileHistoryCaptureCapability(caps) {
 const reader = createEngineCapReader({
     name: 'fileHistoryCapture',
     project: projectFileHistoryCaptureCapability,
-    makeUnobserved: () => ({ kind: 'unobserved' }),
 });
 export function noteEngineCapsForFileHistoryCapture(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
@@ -52,6 +52,100 @@ export function fileHistoryCaptureMode(reading) {
 export function fileHistoryDeclarationField(reading, captureOff) {
     return captureOff === true && fileHistoryCaptureMode(reading) === 'on-optional' ? { fileHistory: FILE_HISTORY_DISABLED } : {};
 }
+export const FILE_HISTORY_TIGHTEN_VERDICTS = Object.freeze(['not_requested', 'declare', 'already_off', 'unjudged']);
+export function fileHistoryTightenVerdict(reading, captureOffByUser) {
+    if (captureOffByUser !== true)
+        return 'not_requested';
+    const mode = fileHistoryCaptureMode(reading);
+    if (mode === 'on-optional')
+        return 'declare';
+    if (mode === 'off')
+        return 'already_off';
+    return 'unjudged';
+}
+const FILE_HISTORY_REFUSAL_NOT_YET = "Nothing was sent: file checkpointing is turned off in your settings, but this engine's capabilities have not been read " +
+    'yet, so whether it can stop recording file history for a session is unknown and sending now could record it anyway. ' +
+    'Try again in a moment; to send regardless and let file history be recorded this time, turn file checkpointing back on in your settings.';
+const FILE_HISTORY_REFUSAL_NOT_SAID = 'Nothing was sent: file checkpointing is turned off in your settings, but this engine did not report whether it can ' +
+    'stop recording file history for a session, so sending now could record it anyway. Trying again will not change that ' +
+    'while this engine reports the same; to send and let file history be recorded this time, turn file checkpointing back on in your settings.';
+const FILE_HISTORY_REFUSAL_UNREADABLE = "Nothing was sent: file checkpointing is turned off in your settings, but this engine's report on whether it can stop " +
+    'recording file history for a session could not be read by this client, so sending now could record it anyway. Trying ' +
+    'again will not change that while this engine reports the same; to send and let file history be recorded this time, ' +
+    'turn file checkpointing back on in your settings.';
+function unjudgedRefusalOf(reading) {
+    let kind;
+    let word;
+    try {
+        kind = typeof reading === 'object' && reading !== null ? reading.kind : undefined;
+        word = kind === 'present' ? reading.word : undefined;
+    }
+    catch {
+        return FILE_HISTORY_REFUSAL_NOT_YET;
+    }
+    if (kind === 'unreadable')
+        return FILE_HISTORY_REFUSAL_UNREADABLE;
+    if (kind === 'not_reported')
+        return FILE_HISTORY_REFUSAL_NOT_SAID;
+    if (kind === 'present' && typeof word === 'string' && word.length > 0)
+        return FILE_HISTORY_REFUSAL_NOT_SAID;
+    return FILE_HISTORY_REFUSAL_NOT_YET;
+}
+export function fileHistoryUnjudgedRefusal(reading, captureOffByUser) {
+    return fileHistoryTightenVerdict(reading, captureOffByUser) === 'unjudged' ? unjudgedRefusalOf(reading) : undefined;
+}
+const FILE_HISTORY_REFRESH_WITHIN_MS = 3000;
+export async function judgeFileHistoryTighten(captureOffByUser, opts) {
+    const closed = captureOffByUser === true;
+    const failClosed = () => {
+        const reading = { kind: 'unobserved' };
+        return closed
+            ? { verdict: 'unjudged', reading, refreshed: false, refusal: FILE_HISTORY_REFUSAL_NOT_YET }
+            : { verdict: 'not_requested', reading, refreshed: false, refusal: undefined };
+    };
+    try {
+        let explicitBase;
+        let withinMs = FILE_HISTORY_REFRESH_WITHIN_MS;
+        if (typeof opts === 'object' && opts !== null) {
+            try {
+                const b = opts.baseUrl;
+                if (b !== undefined) {
+                    if (typeof b !== 'string' || b === '')
+                        return failClosed();
+                    explicitBase = b;
+                }
+            }
+            catch {
+                return failClosed();
+            }
+            try {
+                const w = opts.withinMs;
+                if (w !== undefined)
+                    withinMs = typeof w === 'number' ? w : 0;
+            }
+            catch {
+                withinMs = 0;
+            }
+        }
+        const baseUrl = explicitBase ?? engineWireTarget()?.baseUrl;
+        const first = observedFileHistoryCapture(baseUrl);
+        const v1 = fileHistoryTightenVerdict(first, captureOffByUser);
+        if (v1 !== 'unjudged')
+            return { verdict: v1, reading: first, refreshed: false, refusal: undefined };
+        const outcome = await refreshEngineCapsOnce(baseUrl, { withinMs });
+        const second = observedFileHistoryCapture(baseUrl);
+        const v2 = fileHistoryTightenVerdict(second, captureOffByUser);
+        return {
+            verdict: v2,
+            reading: second,
+            refreshed: outcome !== 'no_probe',
+            refusal: v2 === 'unjudged' ? unjudgedRefusalOf(second) : undefined,
+        };
+    }
+    catch {
+        return failClosed();
+    }
+}
 const WORD_DETAIL_MAX = 40;
 export function fileHistoryCaptureDoctorDetail(reading) {
     const unobserved = 'file history capture not observed — the engine reports it on /v1/capabilities; this process has no usable capabilities reading cached for it, so whether this deployment captures file history is unknown';
@@ -67,6 +161,8 @@ export function fileHistoryCaptureDoctorDetail(reading) {
         return unobserved;
     }
     switch (kind) {
+        case 'unreadable':
+            return unreadableReadingDetail('file history capture');
         case 'not_reported':
             return 'file history capture not reported by this engine; this does not say whether file history is captured here';
         case 'present':

package/dist/fileHistoryLegNotice.js

@@ -89,6 +89,8 @@ function canonReading(r) {
         const kind = r.kind;
         if (kind === 'not_reported')
             return 'not_reported';
+        if (kind === 'unreadable')
+            return 'unreadable';
         if (kind === 'present') {
             const word = r.word;
             return typeof word === 'string' && word.length > 0 ? `present:${word}` : 'unobserved';
@@ -102,6 +104,8 @@ function canonReading(r) {
 function readingOfCanon(c) {
     if (c === 'not_reported')
         return { kind: 'not_reported' };
+    if (c === 'unreadable')
+        return { kind: 'unreadable' };
     if (c.startsWith('present:'))
         return { kind: 'present', word: c.slice('present:'.length) };
     return { kind: 'unobserved' };