@sema-agent/client-core 0.110.0 → 0.112.0

package/dist/engineRepoint.d.ts

@@ -15,7 +15,12 @@ export declare function deviceHelloReadingOf(frame: {} | null | undefined): Devi
 export interface EngineRepointInput {
     readonly from: string;
     readonly to: string;
-    readonly expectDeviceId?: string;
+    readonly continuity?: EngineRepointContinuity;
+}
+export interface EngineRepointContinuity {
+    readonly deviceId: string;
+    readonly from: string;
+    readonly to: string;
 }
 export interface EngineRepointHandshakeTarget {
     readonly address: string;
@@ -26,8 +31,7 @@ export type EngineRepointHandshakePort = (target: EngineRepointHandshakeTarget,
 }) => Promise<{} | null | undefined> | {} | null | undefined;
 export interface EngineRepointRoster {
     readonly credential: 'operator' | 'non-operator';
-    readonly address: string;
-    readonly devices: DeviceListVerb | null | undefined;
+    readonly devices: (address: string) => DeviceListVerb | null | undefined;
 }
 export type EngineRepointRecordReading = {
     readonly kind: 'absent';
@@ -75,7 +79,7 @@ export type EngineRepointRosterProof = {
     readonly why: 'not-listed' | 'lane-absent';
 } | {
     readonly state: 'unreadable';
-    readonly why: 'operator-credential' | 'credential-unknown' | 'address-unbound' | 'list-incomplete' | 'refused' | 'transport' | 'unreadable' | 'unarmed';
+    readonly why: 'operator-credential' | 'credential-unknown' | 'list-incomplete' | 'refused' | 'transport' | 'unreadable' | 'unarmed';
 };
 export interface EngineRepointProofs {
     readonly handshake: EngineRepointHandshakeProof;
@@ -94,11 +98,12 @@ export interface EngineRepointSessionTally {
     readonly unreadable: number;
     readonly storeFailed: number;
 }
-export type EngineRepointRefusal = 'address-invalid' | 'same-address' | 'record-absent' | 'record-not-active' | 'record-unreadable' | 'target-occupied' | 'unarmed';
+export type EngineRepointRefusal = 'address-invalid' | 'same-address' | 'record-absent' | 'record-not-active' | 'record-unreadable' | 'target-occupied' | 'roster-unbound' | 'unarmed';
 export type EngineRepointResult = EngineRepointDone | EngineRepointPartial | EngineRepointUnverified | EngineRepointUndetermined | EngineRepointStoreFailed | EngineRepointRefused;
 export interface EngineRepointDone {
     readonly kind: 'repointed';
     readonly deviceId: string;
+    readonly continuity: EngineRepointContinuity;
     readonly record: 'moved' | 'already-there';
     readonly sessions: EngineRepointSessionTally;
     readonly proofs: EngineRepointProofs;
@@ -107,6 +112,7 @@ export interface EngineRepointPartial {
     readonly kind: 'partial';
     readonly stage: 'sessions' | 'sessions-list';
     readonly deviceId: string;
+    readonly continuity: EngineRepointContinuity;
     readonly record: 'moved' | 'already-there';
     readonly sessions: EngineRepointSessionTally;
     readonly proofs: EngineRepointProofs;
@@ -128,6 +134,7 @@ export interface EngineRepointStoreFailed {
     readonly kind: 'store-failed';
     readonly stage: 'record';
     readonly deviceId: string;
+    readonly continuity: EngineRepointContinuity;
 }
 export interface EngineRepointRefused {
     readonly kind: 'refused';

package/dist/engineRepoint.js

@@ -58,18 +58,27 @@ async function handshakeProofOf(port, target, signal) {
     return freeze({ state: 'unreadable', why: r.code });
 }
 const RO_PROVEN = freeze({ state: 'proven' });
-async function rosterProofOf(roster, target, deviceId, signal) {
+function rosterSliceOf(roster, target) {
     if (!isObject(roster))
-        return freeze({ state: 'unreadable', why: 'unarmed' });
+        return { kind: 'proof', proof: freeze({ state: 'unreadable', why: 'unarmed' }) };
     const credential = dataOf(roster, 'credential');
     if (credential === 'operator')
-        return freeze({ state: 'unreadable', why: 'operator-credential' });
+        return { kind: 'proof', proof: freeze({ state: 'unreadable', why: 'operator-credential' }) };
     if (credential !== 'non-operator')
-        return freeze({ state: 'unreadable', why: 'credential-unknown' });
-    const listed = addressOf(dataOf(roster, 'address'), false);
-    if (listed === undefined || engineNamespaceKeyFor(listed) !== engineNamespaceKeyFor(target))
-        return freeze({ state: 'unreadable', why: 'address-unbound' });
-    const devices = dataOf(roster, 'devices');
+        return { kind: 'proof', proof: freeze({ state: 'unreadable', why: 'credential-unknown' }) };
+    const factory = dataOf(roster, 'devices');
+    if (typeof factory !== 'function')
+        return { kind: 'unbound' };
+    let slice;
+    try {
+        slice = factory(target);
+    }
+    catch {
+        return { kind: 'proof', proof: freeze({ state: 'unreadable', why: 'unreadable' }) };
+    }
+    return slice === null || slice === undefined ? { kind: 'unbound' } : { kind: 'slice', devices: slice };
+}
+async function rosterProofOf(devices, deviceId, signal) {
     const out = await listDevices(devices, signal !== undefined ? { signal } : undefined);
     switch (out.kind) {
         case 'ok':
@@ -123,7 +132,17 @@ async function recordFactOf(read, port, address) {
     const deviceId = dataOf(raw, 'deviceId');
     return typeof deviceId === 'string' && deviceId !== '' ? freeze({ k: 'active', deviceId }) : UNREADABLE_RECORD;
 }
-function planOf(from, to, expectDeviceId) {
+function continuityReadingOf(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const deviceId = dataOf(raw, 'deviceId');
+    const f = addressOf(dataOf(raw, 'from'), false);
+    const t = addressOf(dataOf(raw, 'to'), true);
+    if (typeof deviceId !== 'string' || deviceId === '' || f === undefined || t === undefined)
+        return undefined;
+    return freeze({ deviceId, fromKey: engineNamespaceKeyFor(f), toKey: engineNamespaceKeyFor(t) });
+}
+function planOf(from, to, evidence, pair) {
     if (from.k === 'unreadable' || to.k === 'unreadable')
         return { kind: 'refused', reason: 'record-unreadable' };
     if (from.k === 'other')
@@ -135,8 +154,10 @@ function planOf(from, to, expectDeviceId) {
             return { kind: 'move', deviceId: from.deviceId };
         return { kind: 'refused', reason: 'target-occupied' };
     }
-    if (to.k === 'active')
-        return expectDeviceId !== undefined && to.deviceId === expectDeviceId ? { kind: 'finish', deviceId: to.deviceId } : { kind: 'refused', reason: 'record-absent' };
+    if (to.k === 'active') {
+        const bound = evidence !== undefined && to.deviceId === evidence.deviceId && evidence.fromKey === pair.fromKey && evidence.toKey === pair.toKey;
+        return bound ? { kind: 'finish', deviceId: to.deviceId } : { kind: 'refused', reason: 'record-absent' };
+    }
     if (to.k === 'other')
         return { kind: 'refused', reason: 'record-not-active', recordStatus: to.status };
     return { kind: 'refused', reason: 'record-absent' };
@@ -188,14 +209,17 @@ export async function repointEngine(input, ports) {
         const roster = dataOf(ports, 'roster');
         const signalRaw = dataOf(ports, 'signal');
         const signal = isObject(signalRaw) ? signalRaw : undefined;
-        const expectRaw = dataOf(input, 'expectDeviceId');
-        const expectDeviceId = typeof expectRaw === 'string' && expectRaw !== '' ? expectRaw : undefined;
+        const evidence = continuityReadingOf(dataOf(input, 'continuity'));
         const [fromFact, toFact] = await Promise.all([recordFactOf(read, recordPort, from), recordFactOf(read, recordPort, to)]);
-        const plan = planOf(fromFact, toFact, expectDeviceId);
+        const plan = planOf(fromFact, toFact, evidence, { fromKey: engineNamespaceKeyFor(from), toKey: engineNamespaceKeyFor(to) });
         if (plan.kind === 'refused')
             return refusedOf(plan.reason, plan.recordStatus);
         const deviceId = plan.deviceId;
-        const [hs, ro] = await Promise.all([handshakeProofOf(handshake, freeze({ address: to, deviceId }), signal), rosterProofOf(roster, to, deviceId, signal)]);
+        const continuity = freeze({ deviceId, from, to });
+        const slice = rosterSliceOf(roster, to);
+        if (slice.kind === 'unbound')
+            return refusedOf('roster-unbound');
+        const [hs, ro] = await Promise.all([handshakeProofOf(handshake, freeze({ address: to, deviceId }), signal), slice.kind === 'proof' ? slice.proof : rosterProofOf(slice.devices, deviceId, signal)]);
         const proofs = freeze({ handshake: hs, roster: ro });
         const verdict = engineRepointVerdictOf(proofs);
         if (verdict !== 'apply') {
@@ -217,7 +241,7 @@ export async function repointEngine(input, ports) {
                 moved = afterFrom.k === 'absent' && afterTo.k === 'active' && afterTo.deviceId === deviceId;
             }
             if (!moved)
-                return freeze({ kind: 'store-failed', stage: 'record', deviceId });
+                return freeze({ kind: 'store-failed', stage: 'record', deviceId, continuity });
         }
         const record = plan.kind === 'move' ? 'moved' : 'already-there';
         const counts = { moved: 0, unaffected: 0, conflict: 0, unreadable: 0, storeFailed: 0 };
@@ -229,7 +253,7 @@ export async function repointEngine(input, ports) {
             stores = undefined;
         }
         if (stores === undefined)
-            return freeze({ kind: 'partial', stage: 'sessions-list', deviceId, record, sessions: tallyOf(counts), proofs });
+            return freeze({ kind: 'partial', stage: 'sessions-list', deviceId, continuity, record, sessions: tallyOf(counts), proofs });
         for (const store of stores) {
             const r = repointSessionEngine(store, from, to);
             if (r === 'moved')
@@ -245,8 +269,8 @@ export async function repointEngine(input, ports) {
         }
         const sessions = tallyOf(counts);
         return counts.conflict + counts.unreadable + counts.storeFailed > 0
-            ? freeze({ kind: 'partial', stage: 'sessions', deviceId, record, sessions, proofs })
-            : freeze({ kind: 'repointed', deviceId, record, sessions, proofs });
+            ? freeze({ kind: 'partial', stage: 'sessions', deviceId, continuity, record, sessions, proofs })
+            : freeze({ kind: 'repointed', deviceId, continuity, record, sessions, proofs });
     }
     catch {
         return refusedOf('unarmed');
@@ -259,6 +283,7 @@ const REFUSAL_KEYS = {
     'record-not-active': 'session.devices.repoint.refused.recordNotActive',
     'record-unreadable': 'session.devices.repoint.refused.recordUnreadable',
     'target-occupied': 'session.devices.repoint.refused.targetOccupied',
+    'roster-unbound': 'session.devices.repoint.refused.rosterUnbound',
     unarmed: 'session.devices.repoint.refused.unarmed',
 };
 export function engineRepointMessageOf(result) {

package/dist/engineRowRef.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent } from '@sema-agent/sdk';
+import { type GateOutcomeView } from './gateOutcome.js';
 export interface EngineRowRef {
     readonly eventId?: string;
     readonly taskId?: string;
@@ -22,7 +23,9 @@ export declare function terminalRunIdOf(ev: Extract<AgentEvent, {
 } | {
     type: 'failed';
 }>): string | undefined;
+export declare const SEMA_REFUSAL_NOTED_KEY = "_sema_refusal_noted";
 export declare const TRANSCRIPT_ROW_SIDECAR_KEYS: readonly string[];
+export declare function refusalNotedOf(denialKind: string | undefined, gate: GateOutcomeView | undefined): boolean;
 export declare function parkHeldCallIdOf(carrier: {} | null | undefined): string | undefined;
 export declare function parkedToolEndRoleOf(frame: {} | null | undefined): 'held' | 'collateral' | undefined;
 export declare function isUnsettledHeldToolEnd(frame: {} | null | undefined): boolean;

package/dist/engineRowRef.js

@@ -1,6 +1,7 @@
 import { guardedRead, readFrameStringKey, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 import { GATE_PARKED_ERROR_CODE } from './engineErrorCodes.js';
-import { isCcToolDenialKind } from './gateVocabulary.js';
+import { ccToolDenialKindForSettledBy, isCcToolDenialKind } from './gateVocabulary.js';
+import { gateDeniedBy } from './gateOutcome.js';
 import { doneResultView } from './replayBody.js';
 import { TRANSCRIPT_ID_NAMESPACE, uuidV5 } from './uuidV5.js';
 const ENGINE_REF_KEY = '_sema_engine_ref';
@@ -77,6 +78,7 @@ export function terminalRunIdOf(ev) {
     const v = doneResultView(ev.result).body?.runId;
     return typeof v === 'string' && v.length > 0 ? v : undefined;
 }
+export const SEMA_REFUSAL_NOTED_KEY = '_sema_refusal_noted';
 export const TRANSCRIPT_ROW_SIDECAR_KEYS = Object.freeze([
     '_sema_segment_id',
     '_sema_engine_ref',
@@ -93,6 +95,7 @@ export const TRANSCRIPT_ROW_SIDECAR_KEYS = Object.freeze([
     '_sema_interrupted_never_started',
     '_sema_approval_window_expired',
     '_sema_denial_limit_window_expired',
+    SEMA_REFUSAL_NOTED_KEY,
     '_sema_api_error_status',
     '_sema_api_error_code',
     '_sema_provider_condition',
@@ -105,6 +108,13 @@ export const TRANSCRIPT_ROW_SIDECAR_KEYS = Object.freeze([
     '_sema_run_origin',
     '_sema_run_origin_unreadable',
 ]);
+export function refusalNotedOf(denialKind, gate) {
+    if (denialKind !== ccToolDenialKindForSettledBy('human'))
+        return false;
+    if (gateDeniedBy(gate) !== 'ask_resolution')
+        return false;
+    return gate?.settlement?.kind === 'human_refused' && gate.settlement.note !== undefined;
+}
 export function parkHeldCallIdOf(carrier) {
     return readFrameStringKey(carrier, 'toolCallId');
 }

package/dist/engineSwapCrossing.d.ts

@@ -0,0 +1,57 @@
+import type { ApprovalsFeedEmission } from './hitl/approvalsFeed.js';
+import type { LocalEngineUpgradePath, LocalEngineVerdict } from './localEngineJudge.js';
+import type { RequestLane } from './request/taskRequest.js';
+import type { UiLanguage } from './env/uiLanguage.js';
+export declare const ENGINE_DRAIN_CLASSES: readonly ["parked_tool_approvals"];
+export type EngineDrainClass = (typeof ENGINE_DRAIN_CLASSES)[number];
+export interface EngineDrainSession {
+    readonly sessionId: string;
+    readonly count: number;
+}
+export type EngineDrainReading = {
+    readonly class: EngineDrainClass;
+    readonly state: 'count';
+    readonly count: number;
+    readonly sessions: readonly EngineDrainSession[];
+} | {
+    readonly class: EngineDrainClass;
+    readonly state: 'failed';
+} | {
+    readonly class: EngineDrainClass;
+    readonly state: 'unsupported';
+};
+export type EngineSwapCrossing = 'newer' | 'same' | 'older' | 'none' | 'unknown';
+export interface EngineSwapCrossingFacts {
+    readonly engine: LocalEngineVerdict;
+    readonly drain?: readonly EngineDrainReading[];
+    readonly informed?: string;
+}
+export type EngineSwapCrossingVerdict = {
+    readonly kind: 'clear';
+    readonly crossing: 'none' | 'same' | 'older' | 'unknown';
+} | {
+    readonly kind: 'hold';
+    readonly reason: 'newer_engine';
+    readonly crossing: 'newer';
+    readonly running: string;
+    readonly own: string;
+    readonly source: 'running' | 'high-water';
+} | {
+    readonly kind: 'hold';
+    readonly reason: 'drain_unconfirmed';
+    readonly crossing: 'older';
+    readonly classes: readonly EngineDrainReading[];
+    readonly fingerprint: string;
+} | {
+    readonly kind: 'unknown';
+    readonly crossing: 'unknown';
+    readonly classes: readonly EngineDrainReading[];
+    readonly fingerprint: string;
+} | {
+    readonly kind: 'swap_and_tell';
+    readonly crossing: 'older' | 'unknown';
+    readonly classes: readonly EngineDrainReading[];
+};
+export declare function engineSwapCrossingVerdict(facts: EngineSwapCrossingFacts): EngineSwapCrossingVerdict;
+export declare function parkedToolApprovalsBySession(emission: ApprovalsFeedEmission | null | undefined): EngineDrainReading;
+export declare function engineSwapCrossingText(verdict: EngineSwapCrossingVerdict, lane: Exclude<RequestLane, 'utility'>, upgrade: LocalEngineUpgradePath | undefined, lang?: UiLanguage): string | undefined;

package/dist/engineSwapCrossing.js

@@ -0,0 +1,297 @@
+import { checkpointQueueRowSortOf } from './hitl/approvalQueueRow.js';
+import { durableDecideLegOf } from './adapter/activeRunSelfHeal.js';
+import { checkpointRowVerdictOf } from './checkpointRowVerdict.js';
+import { compareReleaseVersions } from './supportFloor.js';
+import { engineIdentityOf } from './engineIdentity.js';
+import { slotReadOf } from './wireFailureShape.js';
+import { msg, renderMessage } from './i18n/translate.js';
+export const ENGINE_DRAIN_CLASSES = Object.freeze(['parked_tool_approvals']);
+function own(o, key) {
+    if (typeof o !== 'object' || o === null)
+        return undefined;
+    const r = slotReadOf(o, key);
+    return r.presence === 'present' ? r.value : undefined;
+}
+function isArray(v) {
+    try {
+        return Array.isArray(v);
+    }
+    catch {
+        return false;
+    }
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !isArray(v);
+}
+function isCount(v) {
+    return typeof v === 'number' && Number.isSafeInteger(v) && v >= 0;
+}
+function nonEmpty(v) {
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function elementsOf(v) {
+    if (!isArray(v))
+        return undefined;
+    const len = own(v, 'length');
+    if (!isCount(len))
+        return undefined;
+    const out = [];
+    for (let i = 0; i < len; i++) {
+        const r = slotReadOf(v, String(i));
+        if (r.presence !== 'present')
+            return undefined;
+        out.push(r.value);
+    }
+    return out;
+}
+function failedOf(c) {
+    return Object.freeze({ class: c, state: 'failed' });
+}
+function crossingOf(v) {
+    const kind = own(v, 'kind');
+    if (kind === 'none')
+        return { crossing: 'none' };
+    if (kind === 'attach')
+        return isObject(own(v, 'engine')) ? { crossing: 'same' } : { crossing: 'unknown' };
+    if (kind === 'ahead' || kind === 'behind') {
+        const running = own(v, 'running');
+        const mine = own(v, 'own');
+        if (typeof running !== 'string' || typeof mine !== 'string')
+            return { crossing: 'unknown' };
+        const cmp = compareReleaseVersions(running, mine);
+        if (kind === 'ahead')
+            return cmp === -1 && isObject(own(v, 'engine')) ? { crossing: 'older' } : { crossing: 'unknown' };
+        const source = own(v, 'source');
+        if (cmp !== 1 || (source !== 'running' && source !== 'high-water'))
+            return { crossing: 'unknown' };
+        return { crossing: 'newer', running, own: mine, source };
+    }
+    return { crossing: 'unknown' };
+}
+function targetOf(v) {
+    const engine = own(v, 'engine');
+    const anchored = own(v, 'anchored');
+    const src = isObject(engine) ? own(engine, 'identity') : isObject(anchored) ? anchored : v;
+    const id = engineIdentityOf({ pid: own(src, 'pid'), instanceId: own(src, 'instanceId'), startedAt: own(src, 'startedAt') });
+    return { ...(id.pid !== undefined ? { pid: id.pid } : {}), ...(id.instanceId !== undefined ? { instanceId: id.instanceId } : {}), ...(id.startedAt !== undefined ? { startedAt: id.startedAt } : {}) };
+}
+function drainEntryOf(e) {
+    if (!isObject(e))
+        return undefined;
+    const c = own(e, 'class');
+    if (!ENGINE_DRAIN_CLASSES.includes(c))
+        return undefined;
+    const cls = c;
+    const state = own(e, 'state');
+    if (state === 'failed')
+        return failedOf(cls);
+    if (state === 'unsupported')
+        return Object.freeze({ class: cls, state: 'unsupported' });
+    if (state !== 'count')
+        return undefined;
+    const count = own(e, 'count');
+    const rows = elementsOf(own(e, 'sessions'));
+    if (!isCount(count) || rows === undefined)
+        return undefined;
+    const sessions = [];
+    const seen = new Set();
+    let sum = 0;
+    for (const s of rows) {
+        const sessionId = nonEmpty(own(s, 'sessionId'));
+        const n = own(s, 'count');
+        if (sessionId === undefined || !isCount(n) || n === 0 || seen.has(sessionId))
+            return undefined;
+        seen.add(sessionId);
+        sum += n;
+        sessions.push(Object.freeze({ sessionId, count: n }));
+    }
+    if (sum !== count)
+        return undefined;
+    sessions.sort((a, b) => (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
+    return Object.freeze({ class: cls, state: 'count', count, sessions: Object.freeze(sessions) });
+}
+function drainOf(raw) {
+    const entries = elementsOf(raw);
+    const byClass = new Map();
+    let bad = entries === undefined;
+    for (const e of entries ?? []) {
+        const r = drainEntryOf(e);
+        if (r === undefined || byClass.has(r.class)) {
+            bad = true;
+            break;
+        }
+        byClass.set(r.class, r);
+    }
+    return Object.freeze(ENGINE_DRAIN_CLASSES.map(c => (bad ? undefined : byClass.get(c)) ?? failedOf(c)));
+}
+function fingerprintOf(crossing, v, drain) {
+    const running = own(v, 'running');
+    const mine = own(v, 'own');
+    return JSON.stringify([
+        'engine-swap-crossing/1',
+        crossing,
+        targetOf(v),
+        typeof running === 'string' ? running : null,
+        typeof mine === 'string' ? mine : null,
+        drain.map(r => (r.state === 'count' ? [r.class, r.state, r.count, r.sessions.map(s => [s.sessionId, s.count])] : [r.class, r.state])),
+    ]);
+}
+function judge(facts) {
+    const engine = own(facts, 'engine');
+    const d = crossingOf(engine);
+    if (d.crossing === 'newer') {
+        return Object.freeze({ kind: 'hold', reason: 'newer_engine', crossing: 'newer', running: d.running, own: d.own, source: d.source });
+    }
+    if (d.crossing === 'none' || d.crossing === 'same')
+        return Object.freeze({ kind: 'clear', crossing: d.crossing });
+    const drain = drainOf(own(facts, 'drain'));
+    const classes = Object.freeze(drain.filter(r => !(r.state === 'count' && r.count === 0)));
+    const holding = drain.some(r => r.state === 'failed' || (r.state === 'count' && r.count > 0));
+    const fingerprint = fingerprintOf(d.crossing, engine, drain);
+    const informedRaw = own(facts, 'informed');
+    const informed = typeof informedRaw === 'string' && informedRaw === fingerprint;
+    if (d.crossing === 'older') {
+        if (!holding)
+            return Object.freeze({ kind: 'clear', crossing: 'older' });
+        if (informed)
+            return Object.freeze({ kind: 'swap_and_tell', crossing: 'older', classes });
+        return Object.freeze({ kind: 'hold', reason: 'drain_unconfirmed', crossing: 'older', classes, fingerprint });
+    }
+    if (informed) {
+        return holding
+            ? Object.freeze({ kind: 'swap_and_tell', crossing: 'unknown', classes })
+            : Object.freeze({ kind: 'clear', crossing: 'unknown' });
+    }
+    return Object.freeze({ kind: 'unknown', crossing: 'unknown', classes, fingerprint });
+}
+const UNKNOWN_ALL_FAILED = () => {
+    const drain = Object.freeze(ENGINE_DRAIN_CLASSES.map(failedOf));
+    return Object.freeze({ kind: 'unknown', crossing: 'unknown', classes: drain, fingerprint: fingerprintOf('unknown', undefined, drain) });
+};
+export function engineSwapCrossingVerdict(facts) {
+    try {
+        return judge(facts);
+    }
+    catch {
+        return UNKNOWN_ALL_FAILED();
+    }
+}
+const PARKED = 'parked_tool_approvals';
+function parkedOf(emission) {
+    if (!isObject(emission) || own(emission, 'kind') !== 'snapshot')
+        return failedOf(PARKED);
+    const droppedSlot = slotReadOf(emission, 'pendingDropped');
+    if (droppedSlot.presence === 'unreadable')
+        return failedOf(PARKED);
+    if (droppedSlot.presence === 'present' && droppedSlot.value !== undefined && !(isCount(droppedSlot.value) && droppedSlot.value === 0))
+        return failedOf(PARKED);
+    const rows = elementsOf(own(emission, 'pending'));
+    if (rows === undefined)
+        return failedOf(PARKED);
+    const tally = new Map();
+    for (const row of rows) {
+        if (!isObject(row))
+            return failedOf(PARKED);
+        const sort = checkpointQueueRowSortOf(row);
+        if (sort === 'excluded')
+            continue;
+        if (sort === 'unreadable')
+            return failedOf(PARKED);
+        const gate = slotReadOf(row, 'gateKind');
+        const leg = gate.presence === 'unreadable' ? 'unreadable' : durableDecideLegOf({ gateKind: typeof gate.value === 'string' ? gate.value : null });
+        if (leg === 'plan_review' || leg === 'other_gate')
+            continue;
+        const verdict = checkpointRowVerdictOf(row);
+        if (verdict !== undefined && verdict.kind !== 'ok')
+            continue;
+        if (leg !== 'approval')
+            return failedOf(PARKED);
+        const sessionId = nonEmpty(own(row, 'sessionId'));
+        if (sessionId === undefined)
+            return failedOf(PARKED);
+        tally.set(sessionId, (tally.get(sessionId) ?? 0) + 1);
+    }
+    const sessions = [...tally.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([sessionId, count]) => Object.freeze({ sessionId, count }));
+    const count = sessions.reduce((n, s) => n + s.count, 0);
+    return Object.freeze({ class: PARKED, state: 'count', count, sessions: Object.freeze(sessions) });
+}
+export function parkedToolApprovalsBySession(emission) {
+    try {
+        return parkedOf(emission);
+    }
+    catch {
+        return failedOf(PARKED);
+    }
+}
+function say(key, lang, params) {
+    return renderMessage(msg(key, params), lang);
+}
+function classLine(r, lang) {
+    const state = own(r, 'state');
+    if (state === 'failed')
+        return say('localEngine.swapGuard.parked.failed', lang);
+    if (state === 'unsupported')
+        return say('localEngine.swapGuard.parked.unsupported', lang);
+    const count = own(r, 'count');
+    if (state !== 'count' || !isCount(count) || count === 0)
+        return undefined;
+    if (count === 1)
+        return say('localEngine.swapGuard.parked.one', lang);
+    const sessions = elementsOf(own(r, 'sessions'));
+    if (sessions !== undefined && sessions.length > 1)
+        return say('localEngine.swapGuard.parked.manySessions', lang, { count, sessions: sessions.length });
+    return say('localEngine.swapGuard.parked.oneSession', lang, { count });
+}
+function toldLine(r, lang) {
+    const state = own(r, 'state');
+    if (state === 'failed' || state === 'unsupported')
+        return say('localEngine.swapGuard.told.unknown', lang);
+    const count = own(r, 'count');
+    if (state !== 'count' || !isCount(count) || count === 0)
+        return undefined;
+    return count === 1 ? say('localEngine.swapGuard.told.one', lang) : say('localEngine.swapGuard.told.other', lang, { count });
+}
+function classesOf(v) {
+    return elementsOf(own(v, 'classes')) ?? [];
+}
+function joined(parts, lang) {
+    const out = parts.filter((p) => typeof p === 'string' && p.length > 0);
+    return out.length > 0 ? out.join(lang === 'zh' ? '' : ' ') : undefined;
+}
+export function engineSwapCrossingText(verdict, lane, upgrade, lang) {
+    try {
+        const kind = own(verdict, 'kind');
+        const reason = own(verdict, 'reason');
+        if (kind === 'hold' && reason === 'newer_engine') {
+            const running = own(verdict, 'running');
+            const mine = own(verdict, 'own');
+            const source = own(verdict, 'source');
+            if (typeof running !== 'string' || typeof mine !== 'string' || compareReleaseVersions(running, mine) !== 1)
+                return undefined;
+            if (source !== 'running' && source !== 'high-water')
+                return undefined;
+            const head = say(source === 'high-water' ? 'localEngine.swapGuard.newer.highWater' : 'localEngine.swapGuard.newer', lang, { running, own: mine });
+            const way = upgrade === 'cli-update'
+                ? say('localEngine.swapGuard.newer.cliUpdate', lang)
+                : upgrade === 'app-update'
+                    ? say('localEngine.swapGuard.newer.appUpdate', lang)
+                    : undefined;
+            return joined([head, way], lang);
+        }
+        const wayOut = () => say(lane === 'interactive' ? 'localEngine.swapGuard.wayOut.interactive' : 'localEngine.swapGuard.wayOut.print', lang);
+        if (kind === 'hold' && reason === 'drain_unconfirmed') {
+            return joined([say('localEngine.swapGuard.hold', lang), ...classesOf(verdict).map(r => classLine(r, lang)), wayOut()], lang);
+        }
+        if (kind === 'unknown') {
+            return joined([say('localEngine.swapGuard.unknown', lang), ...classesOf(verdict).map(r => classLine(r, lang)), wayOut()], lang);
+        }
+        if (kind === 'swap_and_tell')
+            return joined(classesOf(verdict).map(r => toldLine(r, lang)), lang);
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/engineUnavailable.d.ts

@@ -0,0 +1,45 @@
+import type { RequestLane } from './request/taskRequest.js';
+import type { UiLanguage } from './env/uiLanguage.js';
+import { type HealthProbeVerdict } from './engineHealthProbeVerdict.js';
+export declare const ENGINE_UNAVAILABLE_REASONS: readonly ["not_running", "not_answering", "address_refused", "version_refused", "model_setup", "credential_conflict", "credential_refused", "data_root_refused", "previous_not_stopped"];
+export type EngineUnavailableReason = (typeof ENGINE_UNAVAILABLE_REASONS)[number];
+export type EngineBootRefusalReason = Extract<EngineUnavailableReason, 'model_setup' | 'credential_conflict' | 'credential_refused' | 'data_root_refused'>;
+export declare const ENGINE_INSTALL_SHAPES: readonly ["npm-global", "managed", "npm-local", "dev", "app", "unknown"];
+export type EngineInstallShape = (typeof ENGINE_INSTALL_SHAPES)[number];
+export type EngineBootRefusalForm = {
+    readonly kind: 'embedded';
+    readonly install: EngineInstallShape;
+    readonly dataDir?: string;
+} | {
+    readonly kind: 'deployment';
+};
+export type EngineDataRootVariant = 'newer_root' | 'unreadable' | 'unknown';
+export type EngineBootWayOut = 'newer_build' | 'separate_data_root' | 'restore_backup' | 'repair_access';
+export declare const ENGINE_BOOT_REFUSAL_CODES: Readonly<Record<string, EngineBootRefusalReason>>;
+export interface LocalEngineBootRefusal {
+    readonly code?: string;
+    readonly hint?: string;
+    readonly text: string;
+    readonly reason?: EngineBootRefusalReason;
+    readonly restartWouldHelp?: false;
+    readonly variant?: EngineDataRootVariant;
+    readonly findings?: readonly string[];
+    readonly highWater?: string;
+    readonly engineVersion?: string;
+    readonly markerPath?: string;
+    readonly waysOut?: readonly EngineBootWayOut[];
+}
+export declare function engineBootRefusalOf(lines: readonly string[], scrub: (s: string) => string): LocalEngineBootRefusal | undefined;
+export declare function engineBootRefusalSentence(refusal: LocalEngineBootRefusal, lang?: UiLanguage, form?: EngineBootRefusalForm): string | undefined;
+export interface EngineUnavailableFacts {
+    readonly reason?: EngineUnavailableReason;
+    readonly code?: string;
+    readonly detail?: string;
+    readonly refusal?: LocalEngineBootRefusal;
+    readonly engineExitCode?: number | null;
+    readonly engineSignal?: string | null;
+    readonly pid?: number;
+    readonly answer?: HealthProbeVerdict;
+    readonly form?: EngineBootRefusalForm;
+}
+export declare function engineUnavailableLine(facts: EngineUnavailableFacts, lane: RequestLane, lang?: UiLanguage): string | undefined;