@sema-agent/client-core 0.83.1 → 0.83.3

package/dist/engineAgentAbsence.js

@@ -0,0 +1,131 @@
+import { displayUntrusted } from './displayUntrusted.js';
+import { isEnginePanelTaskResident, isStaleEngineAgentPanelEnd, } from './engineAgentPanelStore.js';
+export const ENGINE_AGENT_ABSENT_ROW_TEXT = 'engine no longer reports this agent · it may still be running';
+export const ENGINE_AGENT_ABSENCE_TTL_MS = 30 * 60_000;
+function effectiveTtl(ttlMs) {
+    return typeof ttlMs === 'number' && Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : ENGINE_AGENT_ABSENCE_TTL_MS;
+}
+function markOf(row) {
+    if (typeof row !== 'object' || row === null)
+        return undefined;
+    const a = row.absence;
+    return typeof a === 'object' && a !== null ? a : undefined;
+}
+export function isEngineAgentAbsentRow(row) {
+    return markOf(row) !== undefined;
+}
+export function engineAgentAbsenceMarkOf(row, ev) {
+    if (row?.status !== 'running')
+        return null;
+    if (isEngineAgentAbsentRow(row))
+        return null;
+    if (typeof ev?.lastSeenAtMs !== 'number' || !Number.isFinite(ev.lastSeenAtMs))
+        return null;
+    return { lastSeenAtMs: ev.lastSeenAtMs, absentForMs: ev.absentForMs };
+}
+export function engineAgentPanelEventClearsAbsence(ev, current) {
+    if (typeof ev !== 'object' || ev === null)
+        return false;
+    switch (ev.kind) {
+        case 'tick':
+        case 'fleet-row':
+            return true;
+        case 'end':
+            return !isStaleEngineAgentPanelEnd(ev, current);
+        default:
+            return false;
+    }
+}
+export function engineAgentAbsenceClockStopMs(row) {
+    return markOf(row)?.lastSeenAtMs;
+}
+export function engineAgentRowCountsAsRunning(row) {
+    if (typeof row !== 'object' || row === null)
+        return false;
+    if (isEngineAgentAbsentRow(row))
+        return false;
+    return row.status === 'running' || row.status === 'pending';
+}
+export function tallyEngineAgentRows(rows) {
+    const list = Array.isArray(rows) ? rows : Object.values(rows ?? {});
+    let running = 0;
+    let absent = 0;
+    const byStatus = Object.create(null);
+    for (const row of list) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const r = row;
+        if (isEngineAgentAbsentRow(r)) {
+            absent++;
+            continue;
+        }
+        if (engineAgentRowCountsAsRunning(r)) {
+            running++;
+            continue;
+        }
+        const word = String(r.status);
+        byStatus[word] = (byStatus[word] ?? 0) + 1;
+    }
+    return { running, absent, byStatus };
+}
+export function engineAgentTurnSweepSettles(taskId, row) {
+    if (typeof row !== 'object' || row === null)
+        return false;
+    if (isEnginePanelTaskResident(taskId))
+        return false;
+    if (row.status !== 'running')
+        return false;
+    return !isEngineAgentAbsentRow(row);
+}
+export function engineAgentAbsenceTtlDueAtMs(row, ttlMs) {
+    const a = markOf(row);
+    if (a === undefined || typeof a.lastSeenAtMs !== 'number' || !Number.isFinite(a.lastSeenAtMs))
+        return undefined;
+    return a.lastSeenAtMs + effectiveTtl(ttlMs);
+}
+export const ENGINE_AGENT_REGISTRY_READINGS = Object.freeze(['running', 'ended', 'not_listed', 'unknown']);
+function registryConfirmsGone(reading) {
+    return reading === 'ended' || reading === 'not_listed';
+}
+export function reapEngineAgentAbsentRows(rows, opts) {
+    const reclaim = [];
+    const heldByViewer = [];
+    const now = opts?.nowMs;
+    if (typeof now !== 'number' || !Number.isFinite(now))
+        return { reclaim, heldByViewer };
+    const ttl = effectiveTtl(opts.ttlMs);
+    for (const [taskId, row] of Object.entries(rows ?? {})) {
+        if (opts.owned !== undefined && !opts.owned.has(taskId))
+            continue;
+        const a = markOf(row);
+        if (a === undefined || typeof a.lastSeenAtMs !== 'number' || !Number.isFinite(a.lastSeenAtMs))
+            continue;
+        const dueAtMs = a.lastSeenAtMs + ttl;
+        if (now < dueAtMs)
+            continue;
+        const registry = row?.registry;
+        if (!registryConfirmsGone(registry))
+            continue;
+        if (row?.viewing === true) {
+            heldByViewer.push(taskId);
+            continue;
+        }
+        reclaim.push({ taskId, lastSeenAtMs: a.lastSeenAtMs, absentForMs: a.absentForMs, dueAtMs, registry });
+    }
+    return { reclaim, heldByViewer };
+}
+const REMOVE_REASON_DISPLAY_MAX = 64;
+export function engineAgentAbsenceDroppedLine(label, ttlMs, removeReason) {
+    const minutes = Math.round(effectiveTtl(ttlMs) / 60_000);
+    const reason = typeof removeReason === 'string' && removeReason !== ''
+        ? displayUntrusted(removeReason, { max: REMOVE_REASON_DISPLAY_MAX })
+        : '';
+    const why = reason !== ''
+        ? ` · the engine removed it from the fleet list (${reason}); that is not an outcome — read the run to settle it`
+        : ' · outcome unknown';
+    return `${displayUntrusted(label)} was dropped from the task panel after ${minutes} min without an engine report${why}`;
+}
+export function engineAgentTerminalAfterDropLine(label, status, hasReport) {
+    const tail = hasReport ? ' · its final report arrived too late to keep in the panel' : '';
+    return `${displayUntrusted(label)} reported ${displayUntrusted(status)} after it was dropped from the task panel${tail}`;
+}

package/dist/engineNoticeCodes.js

@@ -65,6 +65,8 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     'task.halt_unconsumed',
     'task.late_approval',
     'task.interrupt_unconsumed',
+    'approval.read_root_granted',
+    'approval.read_root_grant_rejected',
     'memory.capture_opted_out',
     'memory.capture_optout_unpersisted',
     'skills.listing_truncated',
@@ -142,6 +144,8 @@ export const ENGINE_NOTICE_AUDIENCE = Object.freeze({
     'task.halt_unconsumed': 'user',
     'task.late_approval': 'user',
     'task.interrupt_unconsumed': 'user',
+    'approval.read_root_granted': 'user',
+    'approval.read_root_grant_rejected': 'user',
     'memory.capture_opted_out': 'user',
     'memory.capture_optout_unpersisted': 'user',
     'skills.listing_truncated': 'operator',

package/dist/gateVocabulary.d.ts

@@ -14,3 +14,7 @@ export type RuleStoreUnreadableKind = (typeof RULE_STORE_UNREADABLE_KINDS)[numbe
 export declare function isRuleStoreUnreadableKind(v: unknown): v is RuleStoreUnreadableKind;
 export declare function ruleStoreUnreadableDetail(kind: RuleStoreUnreadableKind): string;
 export declare function mandatedApprovalDetail(): string;
+export declare const APPROVAL_MANDATE_WORDS: readonly ["operator_always", "tool_marks", "probe_mandate", "probe_unanswered", "write_protection", "write_protection_unresolved"];
+export type ApprovalMandateWord = (typeof APPROVAL_MANDATE_WORDS)[number];
+export declare function isApprovalMandateWord(v: unknown): v is ApprovalMandateWord;
+export declare function approvalMandateDetail(word: ApprovalMandateWord): string;

package/dist/gateVocabulary.js

@@ -118,3 +118,31 @@ export function ruleStoreUnreadableDetail(kind) {
 export function mandatedApprovalDetail() {
     return 'no saved allow rule and no remembered answer can retire this question; each call is settled on its own — by you here, by a hook, or by an automatic check the deployment runs — and an answer covers only that call';
 }
+export const APPROVAL_MANDATE_WORDS = Object.freeze([
+    'operator_always',
+    'tool_marks',
+    'probe_mandate',
+    'probe_unanswered',
+    'write_protection',
+    'write_protection_unresolved',
+]);
+const _mandateWordsPin = true;
+void _mandateWordsPin;
+const APPROVAL_MANDATE_SET = new Set(APPROVAL_MANDATE_WORDS);
+export function isApprovalMandateWord(v) {
+    return APPROVAL_MANDATE_SET.has(v);
+}
+const APPROVAL_MANDATE_SENTENCES = Object.freeze({
+    operator_always: 'this deployment requires a separate confirmation for each shell command, and this call is one of them',
+    tool_marks: 'this tool declares that it reaches outside this machine or makes changes that cannot be undone',
+    probe_mandate: 'the check run on this call marked it as needing its own confirmation (the built-in shell check does so for a read outside the directories allowed for this session)',
+    probe_unanswered: 'the check run on this call did not answer (it timed out or failed), so whether the call stays inside the directories allowed for this session is unknown',
+    write_protection: "this change lands on a protected location (the agent's own configuration), which is confirmed one change at a time",
+    write_protection_unresolved: 'the protected-location check could not tell where this change lands, so whether it touches a protected location is unknown',
+});
+export function approvalMandateDetail(word) {
+    if (typeof word === 'string' && Object.hasOwn(APPROVAL_MANDATE_SENTENCES, word)) {
+        return APPROVAL_MANDATE_SENTENCES[word];
+    }
+    return 'the reason reported for this confirmation is not one this client recognises, so it shows no reason';
+}

package/dist/hitl/askSurvivesPosture.d.ts

@@ -0,0 +1,15 @@
+export interface AskPostureFacts {
+    readonly settingsAskRuleMatched?: boolean;
+}
+export type AskPostureSurvivalRoad = 'origin' | 'settings_ask_rule';
+export type AskPostureVerdict = {
+    readonly kind: 'must_ask';
+    readonly by: AskPostureSurvivalRoad;
+} | {
+    readonly kind: 'posture_may_answer';
+} | {
+    readonly kind: 'unknown';
+};
+export declare function askSurvivesPosture(req: {
+    readonly origin?: string;
+} | null | undefined, facts?: AskPostureFacts | null): AskPostureVerdict;

package/dist/hitl/askSurvivesPosture.js

@@ -0,0 +1,31 @@
+import { readOwnNonEmptyString } from '../ownKey.js';
+const ORIGIN_SURVIVES_POSTURE = Object.freeze({
+    content_question: true,
+    ancestor_marked: false,
+    org_unavailable: true,
+    org_rule: true,
+    rule_store_unavailable: true,
+    hook: true,
+    ask_rule: true,
+    denial_limit_fallback: true,
+    shell_gate_tighten: false,
+    safety_tighten: false,
+    policy: false,
+});
+const MUST_ASK_BY_ORIGIN = Object.freeze({ kind: 'must_ask', by: 'origin' });
+const MUST_ASK_BY_SETTINGS = Object.freeze({ kind: 'must_ask', by: 'settings_ask_rule' });
+const POSTURE_MAY_ANSWER = Object.freeze({ kind: 'posture_may_answer' });
+const UNKNOWN = Object.freeze({ kind: 'unknown' });
+export function askSurvivesPosture(req, facts) {
+    const origin = readOwnNonEmptyString(req, 'origin');
+    const rawMatched = typeof facts === 'object' && facts !== null ? facts.settingsAskRuleMatched : undefined;
+    const matched = typeof rawMatched === 'boolean' ? rawMatched : undefined;
+    const known = origin !== undefined && Object.hasOwn(ORIGIN_SURVIVES_POSTURE, origin);
+    if (known && ORIGIN_SURVIVES_POSTURE[origin] === true)
+        return MUST_ASK_BY_ORIGIN;
+    if (matched === true)
+        return MUST_ASK_BY_SETTINGS;
+    if (matched === false && (origin === undefined || known))
+        return POSTURE_MAY_ANSWER;
+    return UNKNOWN;
+}

package/dist/hitl/persistedRulesWire.d.ts

@@ -16,6 +16,7 @@ export interface RulesFacade {
         signal?: AbortSignal;
     }): Promise<CcImportRedeemResult>;
 }
+export type RulesListFacade = Pick<RulesFacade, 'list'>;
 export declare function persistedRulesLaneAvailable(baseUrl: string | undefined): boolean;
 export declare function persistedRulesGovernanceAvailable(baseUrl: string | undefined): boolean;
 export declare function persistedRulesWriteAvailable(baseUrl: string | undefined): boolean;
@@ -90,7 +91,7 @@ export type ListAllPersistedRulesOutcome = {
     ok: false;
     failure: RulesFailure;
 };
-export declare function listAllPersistedRules(facade: RulesFacade, params?: Omit<RuleListParams, 'cursor'>, opts?: {
+export declare function listAllPersistedRules(facade: RulesListFacade & Partial<Omit<RulesFacade, 'list'>>, params?: Omit<RuleListParams, 'cursor'>, opts?: {
     signal?: AbortSignal;
 }): Promise<ListAllPersistedRulesOutcome>;
 declare const DIRECT_WRITE_EXCLUDED_BEHAVIOR = "allow";

package/dist/hitl/toolApprovalWire.d.ts

@@ -1,5 +1,6 @@
 import { type GateCurrentPending, type HitlFailureStage, type HitlSafetyCode, type HitlClientLike, type DecideOperationObserver } from './hitlBridge.js';
 import { type RuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { type ApprovalMandateWord } from '../gateVocabulary.js';
 import { type DenyAttributionRefusalDetail } from '../wireRefusalCopy.js';
 import { type DecideReceiptView } from '../decideReceipt.js';
 import { RULE_OFFER_MATCHES, RULE_OFFER_BATCH_MEMBER_KINDS, RULE_OFFER_UNCOVERED_REASONS, RULE_OFFERS_ABSENCE_REASONS, DENIAL_LIMIT_KINDS } from '@sema-agent/sdk';
@@ -137,6 +138,7 @@ export interface ApprovalCardRequest {
     receivedAtMs?: number;
     ruleOffersAbsence?: string;
     mandated?: true;
+    mandate?: ApprovalMandateWord;
     denialLimitFallback?: DenialLimitFallback;
     origin?: string;
     ruleStoreUnreadable?: RuleStoreUnreadableKind;
@@ -176,6 +178,7 @@ export interface ToolApprovalFrame {
     ruleEvidence?: unknown;
     requiresRealApproval?: true;
     mandated?: true;
+    mandate?: string;
     origin?: string;
     inputHasBidi?: true;
     parked?: true;
@@ -194,11 +197,16 @@ export interface ToolApprovalDelegation {
     depth: number;
     agentName?: string;
 }
-export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "origin", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
-export declare function approvalIsMandated(v: {
-    mandated?: true;
-    ruleOffersAbsence?: string;
-} | undefined | null): boolean;
+export declare const TOOL_APPROVAL_FRAME_KEYS_MIRROR: readonly ["type", "approvalId", "toolCallId", "toolName", "sourceTaskId", "fromSubagent", "sourceAgentName", "message", "args", "argsOmitted", "governanceForced", "ruleSuggestions", "ruleOffers", "ruleOffersAbsence", "denialLimitFallback", "ruleStoreUnreadable", "readRootCandidate", "mandated", "mandate", "origin", "inputHasBidi", "parked", "persistedRuleShadowed", "probeCause", "ruleEvidence", "requiresRealApproval", "expiresInMs", "expiresAtMs", "serverNowMs", "delegation", "outcome"];
+export interface ApprovalMandatedFacts {
+    readonly mandated?: true;
+    readonly ruleOffersAbsence?: string;
+    readonly mandate?: string;
+}
+export declare function approvalIsMandated(v: ApprovalMandatedFacts | undefined | null): boolean;
+export declare function readApprovalMandate(v: {
+    readonly mandate?: string;
+} | undefined | null): ApprovalMandateWord | undefined;
 export declare function isFromSubagent(frame: ToolApprovalFrame): boolean;
 export type ToolApprovalRespondDecision = 'allow' | 'allow_session' | 'deny';
 export interface RespondToolApprovalOpts {

package/dist/hitl/toolApprovalWire.js

@@ -1,11 +1,13 @@
 import { DEFAULT_DENY_REASON, DecideTransportRetryExhaustedError, HitlBridge, HitlSafetyError, denyReasonForWire, findPendingForTask, readDecideCurrentPending, readWireErrorCode, } from './hitlBridge.js';
 import { askParkRowArm } from './askParkRowRouting.js';
 import { hostLog } from '../host.js';
+import { readOwnNonEmptyString } from '../ownKey.js';
 import { createSessionSlot, DEFAULT_SESSION_KEY } from '../sessionSlot.js';
 import { readEngineActiveBgTasks } from '../fleet/fleetLedger.js';
 import { observeCancelByDeny, surfaceRememberNotApplied, surfaceEditNotForwarded, surfaceEditRefusedOnBlindAsk, surfaceRuleArmNotSent, surfaceRuleArmRejected } from './hitlHostSurface.js';
 import { approvalCallKey, liveFrameCallKey } from './gateIdentity.js';
 import { isRuleStoreUnreadableKind } from '../gateVocabulary.js';
+import { isApprovalMandateWord } from '../gateVocabulary.js';
 import { denyAttributionRefusalFromError } from '../wireRefusalCopy.js';
 import { decideFailureNote } from '../decideFailureNote.js';
 import { readDecideReceipt } from '../decideReceipt.js';
@@ -205,6 +207,8 @@ export async function surfaceFsApprovalAndDecide(deps, taskId, argsByCall, signa
         ...(pending.governanceForced === true ? { governanceForced: true } : {}),
         ...(pending.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(pending.mandated === true ? { mandated: true } : {}),
+        ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(pending)),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(pending, 'origin')),
         ...(pending.gateKind === 'irreversible_ask' ? { irreversibleParkGate: true } : {}),
         ...(pending.hasBidiControls === true ? { hasBidiControls: true } : {}),
         ...(ruleOffersReadOnly !== undefined ? { ruleOffersReadOnly } : {}),
@@ -379,6 +383,7 @@ export const TOOL_APPROVAL_FRAME_KEYS_MIRROR = [
     'ruleStoreUnreadable',
     'readRootCandidate',
     'mandated',
+    'mandate',
     'origin',
     'inputHasBidi',
     'parked',
@@ -400,7 +405,15 @@ export function approvalIsMandated(v) {
         return false;
     if (v.mandated === true)
         return true;
-    return v.ruleOffersAbsence === MANDATED_ABSENCE_WORD;
+    if (v.ruleOffersAbsence === MANDATED_ABSENCE_WORD)
+        return true;
+    return readApprovalMandate(v) !== undefined;
+}
+export function readApprovalMandate(v) {
+    if (typeof v !== 'object' || v === null || !Object.hasOwn(v, 'mandate'))
+        return undefined;
+    const raw = v.mandate;
+    return isApprovalMandateWord(raw) ? raw : undefined;
 }
 function isToolApprovalDelegation(v) {
     if (v === null || typeof v !== 'object')
@@ -828,6 +841,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
         ...(isWireRecordCarrier(frame.ruleEvidence) ? { ruleEvidence: frame.ruleEvidence } : {}),
         ...(frame.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
         ...(frame.mandated === true ? { mandated: true } : {}),
+        ...((w) => (w !== undefined ? { mandate: w } : {}))(readApprovalMandate(frame)),
         ...(() => { const rc = readReadRootCandidate(frame.readRootCandidate); return rc !== undefined ? { readRootCandidate: rc } : {}; })(),
         ...(frame.inputHasBidi === true ? { inputHasBidi: true } : {}),
         ...(typeof frame.ruleOffersAbsence === 'string' && frame.ruleOffersAbsence !== ''
@@ -835,7 +849,7 @@ export async function surfaceToolApprovalFrameAndRespond(frame, respond, streamA
             : {}),
         ...(denialLimitFallback !== undefined ? { denialLimitFallback } : {}),
         ...((k) => (k !== undefined ? { ruleStoreUnreadable: k } : {}))(readRuleStoreUnreadable(frame.ruleStoreUnreadable)),
-        ...(typeof frame.origin === 'string' && frame.origin !== '' ? { origin: frame.origin } : {}),
+        ...((o) => (o !== undefined ? { origin: o } : {}))(readOwnNonEmptyString(frame, 'origin')),
     });
     if (argsNotRealInput && card.kind === 'allow' && card.updatedInput !== undefined) {
         hostLog('error', `liveToolApprovalWire: ${approvalId} card returned an edited approval on a card whose arguments are not the tool's real input (${lane?.argsUnavailable === true ? 'args-unavailable ask' : 'arguments omitted or absent on the frame'}) — nothing sent (the ask stays pending)`);

package/dist/hooksWireCaps.js

@@ -7,7 +7,7 @@ import { MAX_HOOK_NOTICE_TEXT_CHARS } from './notifications.js';
 import { goalStopHookMatcher, __resetGoalStopHookForTests } from './goalStopHook.js';
 export { GOAL_STOP_HOOK_WIRE_ENV, CC_STOP_SEMANTICS_MIN_SERVER, ccStopSemanticsFromVersion, engineCcStopSemantics, isGoalStopHookWireArmed, setWireSessionStopHook, getWireSessionStopHook, getWireSessionStopHookCcSemantics, buildGoalStopHookPrompt, } from './goalStopHook.js';
 const EDITABLE_HOOK_SOURCES = ['userSettings', 'projectSettings', 'localSettings'];
-const ALL_HOOK_SOURCES = ['policySettings', ...EDITABLE_HOOK_SOURCES];
+const ALL_HOOK_SOURCES = ['policySettings', ...EDITABLE_HOOK_SOURCES, 'flagSettings'];
 const _hookSourceListsPin = [true, true];
 void _hookSourceListsPin;
 function hooksLockedToPluginOnly(policyValue) {

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './sdkWireTransit.js';
 export { SEMA_SEGMENT_ID_KEY } from './adapt/textStream.js';
 export * from './subagentContentStore.js';
 export * from './engineAgentPanelStore.js';
+export * from './engineAgentAbsence.js';
 export * from './fleetAgentPanelProjection.js';
 export * from './liveQuestionStore.js';
 export * from './engineInlineTaskStats.js';
@@ -166,6 +167,7 @@ export * from './hitl/sessionPolicyWire.js';
 export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
+export * from './hitl/askSurvivesPosture.js';
 export * from './hitl/crashConverged.js';
 export * from './interactiveHalt.js';
 export * from './compensations.js';

package/dist/index.js

@@ -14,6 +14,7 @@ export * from './sdkWireTransit.js';
 export { SEMA_SEGMENT_ID_KEY } from './adapt/textStream.js';
 export * from './subagentContentStore.js';
 export * from './engineAgentPanelStore.js';
+export * from './engineAgentAbsence.js';
 export * from './fleetAgentPanelProjection.js';
 export * from './liveQuestionStore.js';
 export * from './engineInlineTaskStats.js';
@@ -163,6 +164,7 @@ export * from './hitl/sessionPolicyWire.js';
 export * from './hitl/sessionPolicyDeliverable.js';
 export * from './hitl/approvalsFeed.js';
 export * from './hitl/livePendingAsk.js';
+export * from './hitl/askSurvivesPosture.js';
 export * from './hitl/crashConverged.js';
 export * from './interactiveHalt.js';
 export * from './compensations.js';

package/dist/modelIdentityResolvability.d.ts

@@ -8,13 +8,14 @@ type ModelIdentityLaneTuple = readonly [
 export type ModelIdentityLane = ModelIdentityLaneTuple[number];
 export type ModelIdentityLaneReading = 'complete' | 'partial' | 'absent' | 'unreadable';
 export type ModelIdentityLanes = {
-    [L in ModelIdentityLane]: L extends 'modelCatalogFile' ? Exclude<ModelIdentityLaneReading, 'complete'> : ModelIdentityLaneReading;
+    [L in ModelIdentityLane]: ModelIdentityLaneReading;
 };
 export type EngineAnswerObservation = 'answered' | 'not_observed' | 'unreachable';
 export interface LocalEngineModelIdentityReading {
     engine: 'local';
     lanes: ModelIdentityLanes;
     engineAnswer?: EngineAnswerObservation;
+    engineAcceptsCatalogDefault?: boolean;
 }
 export interface RemoteEngineModelIdentityReading {
     engine: 'remote';

package/dist/modelIdentityResolvability.js

@@ -19,11 +19,12 @@ function laneState(lanes, lane) {
     if (hit === undefined)
         return 'not_reported';
     const v = hit.v;
-    const _catalogPin = true;
-    void _catalogPin;
-    if (v === 'complete')
-        return lane === 'modelCatalogFile' ? 'unusable' : v;
-    return v === 'partial' || v === 'absent' || v === 'unreadable' ? v : 'unusable';
+    return v === 'complete' || v === 'partial' || v === 'absent' || v === 'unreadable' ? v : 'unusable';
+}
+function catalogDefaultEvidence(catalog, accepts) {
+    const _evidencePin = true;
+    void _evidencePin;
+    return catalog === 'complete' && accepts === true ? { catalog, engineAccepts: accepts } : undefined;
 }
 function analyse(reading) {
     try {
@@ -40,16 +41,36 @@ function analyse(reading) {
             return malformed();
         const lanesHit = own(reading, 'lanes')?.v;
         const order = laneOrder();
-        if (!isPlainObject(lanesHit))
-            return { verdict: 'unknown', why: 'lanes', unreadable: [], unreported: [...order], unusable: [] };
+        if (!isPlainObject(lanesHit)) {
+            return { verdict: 'unknown', why: 'lanes', unreadable: [], unreported: [...order], unusable: [], catalogUnconfirmed: null, catalogRefused: false };
+        }
         const partial = [];
         const unreadable = [];
         const unreported = [];
         const unusable = [];
+        let catalogRefused = false;
+        let catalogUnconfirmed = null;
         for (const lane of order) {
             const s = laneState(lanesHit, lane);
-            if (s === 'complete')
+            if (lane === 'modelCatalogFile') {
+                if (s === 'complete') {
+                    const bit = own(reading, 'engineAcceptsCatalogDefault');
+                    const evidence = catalogDefaultEvidence(s, bit?.v);
+                    if (evidence !== undefined)
+                        return { verdict: 'resolvable', why: 'catalog_default', evidence };
+                    if (bit !== undefined && bit.v === false) {
+                        partial.push(lane);
+                        catalogRefused = true;
+                    }
+                    else {
+                        catalogUnconfirmed = bit === undefined || bit.v === undefined ? 'not_reported' : 'unusable';
+                    }
+                    continue;
+                }
+            }
+            else if (s === 'complete') {
                 return { verdict: 'resolvable', why: 'lane', lane };
+            }
             if (s === 'partial')
                 partial.push(lane);
             else if (s === 'unreadable')
@@ -59,10 +80,10 @@ function analyse(reading) {
             else if (s === 'unusable')
                 unusable.push(lane);
         }
-        if (unreadable.length > 0 || unreported.length > 0 || unusable.length > 0) {
-            return { verdict: 'unknown', why: 'lanes', unreadable, unreported, unusable };
+        if (unreadable.length > 0 || unreported.length > 0 || unusable.length > 0 || catalogUnconfirmed !== null) {
+            return { verdict: 'unknown', why: 'lanes', unreadable, unreported, unusable, catalogUnconfirmed, catalogRefused };
         }
-        return { verdict: 'not_resolvable', partial };
+        return { verdict: 'not_resolvable', partial, catalogRefused };
     }
     catch {
         return malformed();
@@ -97,13 +118,25 @@ export function modelIdentityDetail(reading) {
             if (a.why === 'engine_answered') {
                 return 'the engine is up and answering, and it does not start without a model name, so it has one — whether its gateway accepts that name is a separate check';
             }
+            if (a.why === 'catalog_default') {
+                return `${laneLabel('modelCatalogFile')} supplies a model name as its default, and the local engine accepts a catalog default in place of a startup model name, so it can start with it — whether its gateway accepts that name is a separate check`;
+            }
             return `${laneLabel(a.lane)} supplies a model name, so the local engine can start with it — whether its gateway accepts that name is a separate check`;
-        case 'not_resolvable':
-            if (a.partial.length > 0) {
-                const labels = joinPhrases(a.partial.map(laneLabel));
-                return `no model name is configured for the local engine — ${labels} ${a.partial.length > 1 ? 'carry' : 'carries'} part of a model configuration (such as a gateway address or a credential) but no model name, and the engine does not start without one`;
+        case 'not_resolvable': {
+            const others = a.catalogRefused ? a.partial.filter((l) => l !== 'modelCatalogFile') : a.partial;
+            const partialClause = others.length > 0
+                ? `${joinPhrases(others.map(laneLabel))} ${others.length > 1 ? 'carry' : 'carries'} part of a model configuration (such as a gateway address or a credential) but no model name`
+                : '';
+            if (a.catalogRefused) {
+                return (`no model name is configured for the local engine to start with — ${laneLabel('modelCatalogFile')} names a default model, but the local engine is reported not to accept a catalog default in place of a startup model name` +
+                    (partialClause !== '' ? `, and ${partialClause}` : '') +
+                    ', and the engine does not start without one');
+            }
+            if (others.length > 0) {
+                return `no model name is configured for the local engine — ${partialClause}, and the engine does not start without one`;
             }
             return 'no model name is configured for the local engine — none of the places this client reads supplies one, and the engine does not start without it';
+        }
         case 'unknown':
             if (a.why === 'remote') {
                 return a.answer === 'unreachable'
@@ -116,6 +149,15 @@ export function modelIdentityDetail(reading) {
                     ...a.unreported.map((l) => `${laneLabel(l)} was not reported`),
                     ...a.unusable.map((l) => `${laneLabel(l)} gave no usable reading`),
                 ];
+                if (a.catalogUnconfirmed === 'not_reported') {
+                    parts.push(`${laneLabel('modelCatalogFile')} names a default model, but whether the local engine accepts a catalog default in place of a startup model name was not reported`);
+                }
+                else if (a.catalogUnconfirmed === 'unusable') {
+                    parts.push(`${laneLabel('modelCatalogFile')} names a default model, but the report of whether the local engine accepts a catalog default in place of a startup model name gave no usable reading`);
+                }
+                else if (a.catalogRefused) {
+                    parts.push(`${laneLabel('modelCatalogFile')} names a default model, but the local engine is reported not to accept a catalog default in place of a startup model name`);
+                }
                 return `whether the local engine has a model name is unknown — ${joinPhrases(parts)}, and no other place this client reads provides one`;
             }
             return "this reading of the engine's model configuration could not be interpreted, so whether the engine has a model name is unknown";

package/dist/ownKey.d.ts

@@ -1 +1,2 @@
 export declare function putOwnKey<T>(table: Record<string, T>, key: string, value: T): void;
+export declare function readOwnNonEmptyString(v: object | null | undefined, key: string): string | undefined;

package/dist/ownKey.js

@@ -1,3 +1,9 @@
 export function putOwnKey(table, key, value) {
     Object.defineProperty(table, key, { value, enumerable: true, writable: true, configurable: true });
 }
+export function readOwnNonEmptyString(v, key) {
+    if (typeof v !== 'object' || v === null || !Object.hasOwn(v, key))
+        return undefined;
+    const raw = v[key];
+    return typeof raw === 'string' && raw !== '' ? raw : undefined;
+}

package/dist/pluginHooksWire.d.ts

@@ -10,7 +10,7 @@ export declare const PLUGIN_HOOK_EXCLUSION_REASONS: readonly ["workspace_untrust
 export type PluginHookExclusionReason = (typeof PLUGIN_HOOK_EXCLUSION_REASONS)[number];
 export declare const SETTINGS_HOOK_DROP_REASONS: readonly ["exec_form_unsupported", "mcp_tool_unsupported"];
 export type SettingsHookDropReason = (typeof SETTINGS_HOOK_DROP_REASONS)[number];
-export type HookSettingsSource = 'policySettings' | 'userSettings' | 'projectSettings' | 'localSettings';
+export type HookSettingsSource = 'policySettings' | 'userSettings' | 'projectSettings' | 'localSettings' | 'flagSettings';
 export interface PluginHookKey {
     readonly pluginId: string;
     readonly pluginName: string;

package/dist/pluginHooksWire.js

@@ -332,6 +332,7 @@ const SOURCE_TEXT = {
     userSettings: 'User settings',
     projectSettings: 'Project settings',
     localSettings: 'Local settings',
+    flagSettings: 'Flag settings',
 };
 export function pluginHookReasonText(reason) {
     return REASON_TEXT[reason];