@sema-agent/client-core 0.96.0 → 0.97.0

package/dist/cloudConfigWireCaps.js

@@ -3,6 +3,7 @@ import { toCappedSpec } from './skillsWireCaps.js';
 import { TIER_ORDER } from './model/tierVocabulary.js';
 import { SETTINGS_NARROW_AT_MENTION } from './generated/settingsSchemaFns.js';
 import { modelsPolicyOf } from './model/modelsPolicy.js';
+import { guardedRead, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
 import { SETTINGS_BUDGET_NUMBER_KEYS, SETTINGS_BUDGET_PER_MODEL_NUMBER_KEYS, SETTINGS_BUDGET_STRING_KEYS, SETTINGS_TIER_GROUP_NAME_RE, } from './generated/settingsSchemaTables.js';
 const asRec = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined);
 const asArr = (v) => (Array.isArray(v) ? v : []);
@@ -96,6 +97,7 @@ export function cloudMcpToSpecs(servers, env) {
             ...(allowTools.length > 0 ? { allowTools } : {}),
             ...(s.elicitation === true ? { elicitation: true } : {}),
             ...(s.toolFaces !== undefined ? { toolFaces: s.toolFaces } : {}),
+            ...(s.toolAxes !== undefined ? { toolAxes: s.toolAxes } : {}),
         });
     }
     return { specs, missingEnv: [...new Set(missingEnv)], droppedServers };
@@ -140,6 +142,9 @@ const TIER_GROUP_NAME = SETTINGS_TIER_GROUP_NAME_RE;
 const setOwn = (o, k, v) => {
     Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
 };
+function modelsDocPositionOf(m, key) {
+    return guardedRead(() => (Object.hasOwn(m, key) ? { value: m[key] } : 'absent')) ?? 'unreadable';
+}
 function modelsDocOf(models, opts) {
     const m = asRec(models);
     if (!m || !Array.isArray(m.models))
@@ -169,6 +174,7 @@ function modelsDocOf(models, opts) {
     };
     const refOf = (v) => (typeof v === 'string' && v !== '' ? { target: v } : {});
     const reasonOf = (v) => typeof v === 'string' && v !== '' ? (rawNames.has(v) ? 'rejected' : 'dangling') : 'unreadable';
+    const modelRefVerdict = (v) => names.has(v) ? (accept === undefined ? 'unvouched' : 'accepted') : reasonOf(v);
     let written = stripped;
     let catalogKept = false;
     if (acceptedFlags && stripped.length > 0) {
@@ -191,41 +197,57 @@ function modelsDocOf(models, opts) {
         drop({ key: 'roles', at: 'default', reason: 'unreadable' });
     const dm = policy.defaultModel;
     let defaultRole;
-    if (accept && dm !== undefined && dm.from === 'default') {
-        if (names.has(dm.name))
+    let defaultWinner;
+    if (dm !== undefined && dm.from === 'default') {
+        const verdict = modelRefVerdict(dm.name);
+        if (verdict === 'accepted')
             defaultRole = { model: dm.name };
         else
-            drop({ key: 'roles', at: 'default', target: dm.name, reason: reasonOf(dm.name) });
+            drop({ key: 'roles', at: 'default', target: dm.name, reason: verdict });
+        if (verdict === 'accepted' || verdict === 'unvouched')
+            defaultWinner = dm.name;
     }
     const roles = asRec(m.roles);
     const keptRoles = {};
+    let sameModelDefaultRole;
     for (const [role, t] of Object.entries(roles ?? {})) {
-        if (role === 'default' && defaultRole !== undefined) {
-            let same = false;
+        if (role === 'default' && defaultWinner !== undefined) {
+            const tr = asRec(t);
+            let model;
+            let snapshot;
             try {
-                same = JSON.stringify(t) === JSON.stringify(defaultRole);
+                model = tr && Object.hasOwn(tr, 'model') ? tr.model : undefined;
+                if (tr !== undefined && typeof model === 'string' && model === defaultWinner) {
+                    snapshot = {};
+                    for (const [k, v] of Object.entries(tr))
+                        setOwn(snapshot, k, v);
+                    setOwn(snapshot, 'model', model);
+                }
             }
             catch {
-                same = false;
+                model = undefined;
+                snapshot = undefined;
             }
-            if (!same) {
-                const tr = asRec(t);
-                const model = tr && Object.hasOwn(tr, 'model') ? tr.model : undefined;
+            if (snapshot !== undefined)
+                sameModelDefaultRole = snapshot;
+            else
                 drop({ key: 'roles', at: 'default', ...refOf(model), reason: 'shadowed' });
-            }
             continue;
         }
         const tr = asRec(t);
         const model = tr && Object.hasOwn(tr, 'model') ? tr.model : undefined;
-        if (typeof model === 'string' && !names.has(model)) {
-            drop({ key: 'roles', at: role, ...refOf(model), reason: reasonOf(model) });
-            continue;
+        if (typeof model === 'string') {
+            const verdict = modelRefVerdict(model);
+            if (verdict !== 'accepted') {
+                drop({ key: 'roles', at: role, ...refOf(model), reason: verdict });
+                continue;
+            }
         }
         setOwn(keptRoles, role, t);
     }
     const rolesOut = {};
     if (defaultRole !== undefined)
-        setOwn(rolesOut, 'default', defaultRole);
+        setOwn(rolesOut, 'default', sameModelDefaultRole ?? defaultRole);
     else if (Object.hasOwn(keptRoles, 'default'))
         setOwn(rolesOut, 'default', keptRoles.default);
     for (const [k, v] of Object.entries(keptRoles))
@@ -260,53 +282,64 @@ function modelsDocOf(models, opts) {
         }
     }
     let groupNames;
-    const rawGroupNames = new Set((Array.isArray(m.tierGroups) ? m.tierGroups : []).map((g) => asStr(asRec(g)?.name)).filter((n) => !!n));
-    if (accept && Object.hasOwn(m, 'tierGroups')) {
-        if (!Array.isArray(m.tierGroups)) {
-            drop({ key: 'tierGroups', reason: 'unreadable' });
+    if (accept) {
+        const tg = modelsDocPositionOf(m, 'tierGroups');
+        const atg = modelsDocPositionOf(m, 'activeTierGroup');
+        const tgValue = typeof tg === 'object' ? tg.value : undefined;
+        const rawGroupNames = new Set((Array.isArray(tgValue) ? tgValue : []).map((g) => asStr(asRec(g)?.name)).filter((n) => !!n));
+        if (tg === 'unreadable') {
+            drop({ key: 'tierGroups', at: 'models', reason: 'unreadable' });
         }
-        else {
-            const groups = [];
-            groupNames = new Set();
-            for (const raw of m.tierGroups) {
-                const g = asRec(raw);
-                const name = g ? asStr(g.name) : undefined;
-                if (!g || !name || !TIER_GROUP_NAME.test(name)) {
-                    drop({ key: 'tierGroups', ...(name ? { at: name } : {}), reason: 'unreadable' });
-                    continue;
-                }
-                if (groupNames.has(name)) {
-                    drop({ key: 'tierGroups', at: name, reason: 'duplicate' });
-                    continue;
-                }
-                groupNames.add(name);
-                const tiers = {};
-                if (Object.hasOwn(g, 'tiers')) {
-                    const t = asRec(g.tiers);
-                    if (!t)
-                        drop({ key: 'tierGroups', at: `${name}.tiers`, reason: 'unreadable' });
-                    else {
-                        for (const [tier, model] of Object.entries(t)) {
-                            if (!TIER_WORDS.includes(tier))
-                                drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: 'unsupported' });
-                            else if (typeof model === 'string' && names.has(model))
-                                setOwn(tiers, tier, model);
-                            else
-                                drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: reasonOf(model) });
+        else if (tg !== 'absent') {
+            if (!Array.isArray(tgValue)) {
+                drop({ key: 'tierGroups', reason: 'unreadable' });
+            }
+            else {
+                const groups = [];
+                groupNames = new Set();
+                for (const raw of tgValue) {
+                    const g = asRec(raw);
+                    const name = g ? asStr(g.name) : undefined;
+                    if (!g || !name || !TIER_GROUP_NAME.test(name)) {
+                        drop({ key: 'tierGroups', ...(name ? { at: name } : {}), reason: 'unreadable' });
+                        continue;
+                    }
+                    if (groupNames.has(name)) {
+                        drop({ key: 'tierGroups', at: name, reason: 'duplicate' });
+                        continue;
+                    }
+                    groupNames.add(name);
+                    const tiers = {};
+                    if (Object.hasOwn(g, 'tiers')) {
+                        const t = asRec(g.tiers);
+                        if (!t)
+                            drop({ key: 'tierGroups', at: `${name}.tiers`, reason: 'unreadable' });
+                        else {
+                            for (const [tier, model] of Object.entries(t)) {
+                                if (!TIER_WORDS.includes(tier))
+                                    drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: 'unsupported' });
+                                else if (typeof model === 'string' && names.has(model))
+                                    setOwn(tiers, tier, model);
+                                else
+                                    drop({ key: 'tierGroups', at: `${name}.${tier}`, ...refOf(model), reason: reasonOf(model) });
+                            }
                         }
                     }
+                    groups.push({ name, tiers, ...(typeof g.notes === 'string' ? { notes: g.notes } : {}) });
                 }
-                groups.push({ name, tiers, ...(typeof g.notes === 'string' ? { notes: g.notes } : {}) });
+                doc.tierGroups = groups;
             }
-            doc.tierGroups = groups;
         }
-    }
-    if (accept && Object.hasOwn(m, 'activeTierGroup')) {
-        const a = m.activeTierGroup;
-        if (typeof a === 'string' && groupNames?.has(a))
-            doc.activeTierGroup = a;
-        else
-            drop({ key: 'activeTierGroup', ...refOf(a), reason: typeof a === 'string' && a !== '' ? (rawGroupNames.has(a) ? 'rejected' : 'dangling') : 'unreadable' });
+        if (atg === 'unreadable') {
+            drop({ key: 'activeTierGroup', at: 'models', reason: 'unreadable' });
+        }
+        else if (atg !== 'absent') {
+            const a = atg.value;
+            if (typeof a === 'string' && groupNames?.has(a))
+                doc.activeTierGroup = a;
+            else
+                drop({ key: 'activeTierGroup', ...refOf(a), reason: typeof a === 'string' && a !== '' ? (rawGroupNames.has(a) ? 'rejected' : 'dangling') : 'unreadable' });
+        }
     }
     return { doc, issues };
 }
@@ -566,6 +599,8 @@ function droppedRefNotice(d) {
         case 'roles':
             if (d.at === 'default' && d.reason === 'unreadable')
                 return { level: 'warn', text: 'cloud config: the default model setting could not be read, so it was left out — the local engine picks its default from roles and tiers instead' };
+            if (d.reason === 'unvouched')
+                return { level: 'warn', text: `cloud config: role "${d.at ?? ''}" points at model "${t ?? ''}", but this client was given no way to check that the local engine can use that model — the role was left out and falls back along the engine's role chain` };
             if (d.reason === 'shadowed')
                 return { level: 'warn', text: `cloud config: the "${d.at ?? ''}" role${t === undefined ? '' : ` ("${t}")`} is overridden by the default model setting served to you — only one default model can be set, so that role entry was left out` };
             return { level: 'warn', text: `cloud config: role "${d.at ?? ''}" ${t === undefined ? 'names no readable model' : `points at model "${t}", which ${notServed}`} — the role was left out and falls back along the engine's role chain` };
@@ -582,11 +617,111 @@ function droppedRefNotice(d) {
                 return { level: 'warn', text: `cloud config: tier "${d.at ?? ''}" is bound to model "${t ?? ''}", which ${notServed} — that tier was left unbound` };
             if (d.reason === 'unsupported')
                 return { level: 'warn', text: `cloud config: tier "${d.at ?? ''}" is not a tier the local engine reads (${TIER_WORDS.join(', ')}) — that binding was left out` };
+            if (d.at === 'models')
+                return { level: 'warn', text: 'cloud config: the tier group settings served to you could not be read by this client — they were left out, so no tier groups are set on the local engine' };
             return { level: 'warn', text: `cloud config: a tier group setting${d.at === undefined ? '' : ` ("${d.at}")`} could not be read and was left out` };
         case 'activeTierGroup':
             return { level: 'warn', text: `cloud config: ${t === undefined ? 'the active tier group setting could not be read' : `the active tier group "${t}" is not among the readable tier groups`} — no tier table is active on the local engine` };
     }
 }
+const MCP_DROP_SENTENCES = {
+    'missing-field': {
+        level: 'warn',
+        text: (who) => `cloud config: MCP server entries left out because a required setting is missing or unreadable (a name, a transport, or its command or address): ${who}`,
+    },
+    'unknown-transport': {
+        level: 'warn',
+        text: (who) => `cloud config: MCP server entries left out because their transport is not one this client supports: ${who}`,
+    },
+    'principal-and-assertion-header': {
+        level: 'warn',
+        text: (who) => `cloud config: MCP server entries left out because they set both principalHeader and assertionHeader, which name the same identity header — keep only one of the two: ${who}`,
+    },
+    capped: {
+        level: 'warn',
+        text: (who) => `cloud config: MCP server entries left out because more than ${MCP_CAPS.items} were served to you and this client passes at most ${MCP_CAPS.items} to the engine: ${who}`,
+    },
+    disabled: {
+        level: 'info',
+        text: (who) => `cloud config: MCP server entries switched off in the served settings, so they are not started here: ${who}`,
+    },
+};
+const MCP_DROP_UNRECOGNISED = (who) => `cloud config: MCP server entries left out for a reason this client does not recognise: ${who}`;
+const MCP_DROP_LIST_UNREADABLE = 'cloud config: the list of MCP server entries left out could not be read by this client — servers missing from the local tool list may have been left out without notice';
+const MCP_DROP_NAMES_SHOWN = 5;
+function mcpDropWho(names, unnamed) {
+    const distinct = [...new Set(names)];
+    const parts = distinct.slice(0, MCP_DROP_NAMES_SHOWN).map((n) => `"${n}"`);
+    if (distinct.length > MCP_DROP_NAMES_SHOWN)
+        parts.push(`+${distinct.length - MCP_DROP_NAMES_SHOWN} more`);
+    if (unnamed > 0)
+        parts.push(`${unnamed} without a readable name`);
+    return parts.join(', ');
+}
+function guarded(read) {
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+}
+function droppedMcpNotices(carrier) {
+    const listUnreadable = [{ level: 'warn', text: MCP_DROP_LIST_UNREADABLE }];
+    let desc;
+    try {
+        desc = Object.getOwnPropertyDescriptor(carrier, 'droppedMcpServers');
+    }
+    catch {
+        return listUnreadable;
+    }
+    if (desc === undefined)
+        return [];
+    if (!Object.hasOwn(desc, 'value'))
+        return listUnreadable;
+    const rows = desc.value;
+    let count = 0;
+    try {
+        if (!Array.isArray(rows))
+            return listUnreadable;
+        count = rows.length;
+    }
+    catch {
+        return listUnreadable;
+    }
+    const known = new Map();
+    const unrecognised = { names: [], unnamed: 0 };
+    for (let i = 0; i < count; i++) {
+        const row = guarded(() => readOwnDataValue(rows, String(i)));
+        const rowObj = typeof row === 'object' && row !== null ? row : undefined;
+        const reason = guarded(() => {
+            const raw = readOwnDataValue(rowObj, 'reason');
+            return typeof raw === 'string' && Object.hasOwn(MCP_DROP_SENTENCES, raw) ? raw : undefined;
+        });
+        const name = guarded(() => readOwnDataNonEmptyString(rowObj, 'name'));
+        let bucket = unrecognised;
+        if (reason !== undefined) {
+            let b = known.get(reason);
+            if (b === undefined)
+                known.set(reason, (b = { names: [], unnamed: 0 }));
+            bucket = b;
+        }
+        if (name === undefined)
+            bucket.unnamed++;
+        else
+            bucket.names.push(name);
+    }
+    const out = [];
+    for (const reason of Object.keys(MCP_DROP_SENTENCES)) {
+        const b = known.get(reason);
+        if (b !== undefined)
+            out.push({ level: MCP_DROP_SENTENCES[reason].level, text: MCP_DROP_SENTENCES[reason].text(mcpDropWho(b.names, b.unnamed)) });
+    }
+    if (unrecognised.names.length + unrecognised.unnamed > 0) {
+        out.push({ level: 'warn', text: MCP_DROP_UNRECOGNISED(mcpDropWho(unrecognised.names, unrecognised.unnamed)) });
+    }
+    return out;
+}
 function budgetNotice(r) {
     switch (r.kind) {
         case 'configured': {
@@ -654,6 +789,7 @@ export function cloudEffectiveNotices(p) {
                 'the catalog is kept as sent, and a locally started engine rejects the cloud model settings: at startup it uses its own environment catalog instead, and on a later refresh it keeps the previous configuration',
         });
     }
+    out.push(...droppedMcpNotices(p));
     out.push(budgetNotice(p.budget));
     out.push(runtimeCapsNotice(p.runtimeCaps));
     return out;

package/dist/declared/supportFloorDeclared.js

@@ -1,5 +1,5 @@
 export const DECLARED_SUPPORT_FLOOR = Object.freeze({
-    server: "7.125.0",
-    core: "7.48.0",
-    sdk: "20.0.0",
+    server: "7.126.0",
+    core: "7.49.5",
+    sdk: "21.1.0",
 });

package/dist/deviceExecutorManagementCapability.d.ts

@@ -1,5 +1,7 @@
 export type DeviceExecutorManagementReading = {
     kind: 'unobserved';
+} | {
+    kind: 'unreadable';
 } | {
     kind: 'not_reported';
     why: 'capability_absent';

package/dist/deviceExecutorManagementCapability.js

@@ -1,5 +1,5 @@
 import { engineWireTarget } from './engineWireTarget.js';
-import { createEngineCapReader } from './engineCapReader.js';
+import { createEngineCapReader, unreadableReadingDetail } from './engineCapReader.js';
 import { ownDataField } from './ownKey.js';
 import { capForDisplay } from './fleetTaskDesc.js';
 export function projectDeviceExecutorManagementCapability(caps) {
@@ -43,7 +43,6 @@ export function projectDeviceExecutorManagementCapability(caps) {
 const reader = createEngineCapReader({
     name: 'deviceExecutor.management',
     project: projectDeviceExecutorManagementCapability,
-    makeUnobserved: () => ({ kind: 'unobserved' }),
 });
 export function noteEngineCapsForDeviceExecutorManagement(baseUrl, caps, opts) {
     reader.note(baseUrl, caps, opts);
@@ -83,6 +82,8 @@ function laneFactsSuffix(r) {
 }
 export function deviceExecutorManagementDoctorDetail(reading) {
     switch (reading.kind) {
+        case 'unreadable':
+            return unreadableReadingDetail('device management face');
         case 'unobserved':
             return 'device management face not observed — the engine reports it on /v1/capabilities (deviceExecutor.management); 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)';
         case 'not_reported':

package/dist/displayUntrusted.d.ts

@@ -33,6 +33,9 @@ export interface DisplayUntrustedMarked {
 export declare const ESCAPE_FACE: DisplayFace;
 export declare const LABEL_FACE: DisplayFace;
 export declare const PEER_NAME_FACE: DisplayFace;
+export declare const REDACTION_MARKER_MAX_LENGTH: number;
+export declare const DISPLAY_CAP_BACKOFF_MAX: number;
+export declare function markerSafeCut(text: string, cut: number): number;
 export declare function capDisplay(text: string, max: number | undefined, mark: DisplayMark): string;
 export declare function paintAndCap(text: string, face: DisplayFace, max?: number): string;
 export declare function credentialWashPasses(text: string, opts?: DisplayUntrustedOptions | null): {

package/dist/displayUntrusted.js

@@ -4326,6 +4326,7 @@ function capPaired(t, max) {
     if (id >= 0)
         while (cut > 0 && t.ids[cut - 1] === id)
             cut--;
+    cut = markerSafeCut(t.text, cut);
     if (cut > 0) {
         const code = t.text.charCodeAt(cut - 1);
         if (code >= 0xd800 && code <= 0xdbff)
@@ -4370,6 +4371,19 @@ export const ESCAPE_FACE = Object.freeze({ ...publicFace({ foldLines: false }) }
 export const LABEL_FACE = Object.freeze({ ...publicFace({}) });
 export const PEER_NAME_FACE = Object.freeze({ ...publicFace({ mark: 'space' }) });
 const ESCAPE_TOKEN_AT = /^\\u(?:[0-9A-F]{4}|\{[0-9A-F]{1,6}\})/;
+export const REDACTION_MARKER_MAX_LENGTH = REDACTION_MARKER_PREFIX.length + 2 * (1 + 16) + 1;
+export const DISPLAY_CAP_BACKOFF_MAX = REDACTION_MARKER_MAX_LENGTH;
+export function markerSafeCut(text, cut) {
+    if (cut <= 0 || cut >= text.length)
+        return cut;
+    const open = text.lastIndexOf('\u00ab', cut - 1);
+    if (open < 0 || cut - open >= REDACTION_MARKER_MAX_LENGTH)
+        return cut;
+    const close = text.indexOf('\u00bb', open);
+    if (close < cut || close - open + 1 > REDACTION_MARKER_MAX_LENGTH)
+        return cut;
+    return MARKER_RE.test(text.slice(open, close + 1)) ? open : cut;
+}
 export function capDisplay(text, max, mark) {
     if (typeof max !== 'number' || !Number.isFinite(max))
         return text;
@@ -4387,6 +4401,7 @@ export function capDisplay(text, max, mark) {
             break;
         }
     }
+    cut = markerSafeCut(text, cut);
     if (cut > 0) {
         const code = text.charCodeAt(cut - 1);
         if (code >= 0xd800 && code <= 0xdbff)

package/dist/engineCapReader.d.ts

@@ -1,16 +1,22 @@
 interface EngineCapReaderSpec<R> {
     name: string;
     project: (caps: unknown) => R | undefined;
-    makeUnobserved: () => R;
 }
+type ReaderUnobserved = {
+    kind: 'unobserved';
+};
+type ReaderUnreadable = {
+    kind: 'unreadable';
+};
 interface EngineCapReader<R> {
     note(baseUrl: string, caps: unknown, opts?: {
         generation?: number;
     }): void;
-    observed(baseUrl: string | undefined): R;
+    observed(baseUrl: string | undefined): R | ReaderUnobserved | ReaderUnreadable;
     __resetForTests(): void;
 }
 export declare function createEngineCapReader<R>(spec: EngineCapReaderSpec<R>): EngineCapReader<R>;
+export declare function unreadableReadingDetail(subject?: string): string;
 export type StoreSeat = {
     kind: 'object';
     store: object;

package/dist/engineCapReader.js

@@ -1,5 +1,7 @@
 import { engineCapsLandingOf } from './engineCapsCache.js';
 import { ownDataField } from './ownKey.js';
+const unobserved = () => ({ kind: 'unobserved' });
+const unreadable = () => ({ kind: 'unreadable' });
 function freezeReading(reading, seen = new Set()) {
     if (reading === null || typeof reading !== 'object' || seen.has(reading))
         return reading;
@@ -18,15 +20,17 @@ export function createEngineCapReader(spec) {
         note(_baseUrl, _caps, _opts) { },
         observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
-                return spec.makeUnobserved();
+                return unobserved();
             const landing = engineCapsLandingOf(baseUrl);
-            if (landing === undefined)
-                return spec.makeUnobserved();
+            if (landing.kind === 'not_landed')
+                return unobserved();
+            if (landing.kind === 'unreadable')
+                return unreadable();
             const hit = memo.get(landing);
             if (hit === PROJECTING)
-                return spec.makeUnobserved();
+                return unobserved();
             if (hit !== undefined)
-                return hit.reading === undefined ? spec.makeUnobserved() : hit.reading;
+                return hit.reading === undefined ? unreadable() : hit.reading;
             const mine = memo;
             mine.set(landing, PROJECTING);
             let reading;
@@ -38,17 +42,21 @@ export function createEngineCapReader(spec) {
             }
             if (engineCapsLandingOf(baseUrl) !== landing) {
                 mine.delete(landing);
-                return spec.makeUnobserved();
+                return unobserved();
             }
             const done = { reading: reading === undefined ? undefined : freezeReading(reading) };
             mine.set(landing, done);
-            return done.reading === undefined ? spec.makeUnobserved() : done.reading;
+            return done.reading === undefined ? unreadable() : done.reading;
         },
         __resetForTests() {
             memo = new WeakMap();
         },
     };
 }
+export function unreadableReadingDetail(subject) {
+    const head = typeof subject === 'string' && subject.length > 0 ? `${subject} could not be read` : 'could not be read';
+    return `${head} — the engine's /v1/capabilities report arrived, but this entry is not in a form this client reads, so it is shown as unknown, not as absent; probing the same engine again will not change it while the engine reports it this way`;
+}
 export function storeSeatOf(caps) {
     try {
         const store = ownDataField(caps, 'store');

package/dist/engineCapsCache.d.ts

@@ -1,7 +1,13 @@
+export type EngineCapsLanding = {
+    readonly kind: 'landed';
+    readonly caps: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'not_landed';
+} | {
+    readonly kind: 'unreadable';
+};
 export declare function engineCapsGeneration(baseUrl: string): number;
-export declare function engineCapsLandingOf(baseUrl: string): {
-    readonly caps: object;
-} | undefined;
+export declare function engineCapsLandingOf(baseUrl: string | undefined): EngineCapsLanding;
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
 export declare function engineCapsSettled(baseUrl: string | undefined, opts?: {
     withinMs?: number;
@@ -30,6 +36,8 @@ export type EngineCapValueState = {
 export declare function engineCapValue(baseUrl: string | undefined, key: string): EngineCapValueState;
 export declare function engineCapString(baseUrl: string | undefined, key: string): string | undefined;
 export declare function invalidateEngineCaps(baseUrl: string | undefined, probe?: () => Promise<unknown>): void;
+export type EngineCapsProbeRotation = 'started' | 'registered' | 'ignored';
+export declare function rotateEngineCapsProbe(baseUrl: string | undefined, probe: () => Promise<unknown>): EngineCapsProbeRotation;
 export declare function refreshEngineCapsOnce(baseUrl: string | undefined, opts?: {
     withinMs?: number;
 }): Promise<'settled' | 'timed_out' | 'no_probe'>;