@sema-agent/client-core 0.91.0 → 0.92.0

package/dist/controlRouter.js

@@ -1,5 +1,5 @@
 import { cancelConflictContent, cancelConflictFromError } from './wireRefusalCopy.js';
-import { uuid } from './adapter/types.js';
+import { steerPriorityMode } from './steerPriorityCapability.js';
 export class ControlSafetyError extends Error {
     code;
     cause;
@@ -16,7 +16,6 @@ export class ControlSafetyError extends Error {
             this.status = status;
     }
 }
-const BAND_RANK = { now: 0, next: 1, later: 2 };
 export class ControlRouter {
     client;
     taskId = null;
@@ -24,8 +23,6 @@ export class ControlRouter {
     jobId;
     scenario;
     systemPrompt;
-    queue = [];
-    seq = 0;
     constructor(client, opts = {}) {
         this.client = client;
         this.sessionId = opts.sessionId;
@@ -63,7 +60,16 @@ export class ControlRouter {
         if (this.taskId === null) {
             throw controlSafetyRefusal('not_running', 'no run in flight to steer', 'submit a turn first');
         }
-        const body = mode !== undefined ? { text, mode } : { text };
+        let priority;
+        let reading;
+        try {
+            priority = opts?.priority;
+            reading = opts?.steerPriority;
+        }
+        catch (e) {
+            throw steerLocalRefusal('steer_input_invalid', 'unknown', e);
+        }
+        const body = steerBodyOf({ text, ...(mode !== undefined ? { mode } : {}), ...(priority !== undefined ? { priority: priority } : {}) }, (reading ?? UNOBSERVED_STEER_PRIORITY));
         try {
             return await this.client.runs.steer(this.taskId, body, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
@@ -92,38 +98,11 @@ export class ControlRouter {
                     'check what that decision did to the run before retrying the cancel', e);
             }
             if (isNotFound(e)) {
-                throw controlSafetyRefusal('not_found', 'runs.cancel 404 — non-owner / unknown run (no existence leak)', undefined, e);
+                throw controlSafetyRefusal('not_found', 'runs.cancel 404', `${CANCEL_NOT_FOUND_COPY.happened} — ${CANCEL_NOT_FOUND_COPY.nextStep}`, e);
             }
             throw e;
         }
     }
-    enqueue(text, priority = 'next') {
-        const cmd = { id: this.nextId(), text, priority };
-        this.queue.push(cmd);
-        return cmd;
-    }
-    dequeue(id) {
-        const i = this.queue.findIndex((c) => c.id === id);
-        if (i < 0)
-            return false;
-        this.queue.splice(i, 1);
-        return true;
-    }
-    pending() {
-        return [...this.queue].sort((a, b) => BAND_RANK[a.priority] - BAND_RANK[b.priority]);
-    }
-    async drainNext(opts) {
-        const ordered = this.pending();
-        const head = ordered[0];
-        if (!head)
-            return null;
-        this.dequeue(head.id);
-        return this.submit(head.text, opts);
-    }
-    nextId() {
-        this.seq += 1;
-        return `q-${this.seq}-${uuid()}`;
-    }
 }
 export function errCodes(e) {
     if (!e || typeof e !== 'object')
@@ -152,20 +131,72 @@ const STEERING_NAME_TO_SAFETY = new Map([
     ['SteeringAmbiguousTargetError', 'ambiguous_target'],
     ['SteeringStillRunningError', 'still_running'],
     ['SteeringLedgerUnavailableError', 'ledger_unavailable'],
+    ['SteeringQueueFullError', 'queue_full'],
+    ['SteeringDuplicateInputIdError', 'duplicate_input_id'],
     ['SteeringError', 'steering_other'],
 ]);
-const STEERING_ADVICE = {
-    not_running: 'the run is suspended/terminal/on another replica — resolve its gate via decide, do not steer',
-    invalid_content: 'the steer text carried a control-plane escape; surface it, do not strip-and-retry',
-    queue_full: 'the parked steering queue on this checkpoint is full (core fails loud rather than evicting an accepted instruction) — wait for it to drain, do not resend',
-    duplicate_input_id: 'this Idempotency-Key is already parked with DIFFERENT steering content — reissue with a fresh key, resending verbatim will never succeed',
-    ambiguous_target: 'more than one live target matches — address it uniquely (sub-agent: parentToolCallId; workflow: a more specific label); retrying verbatim yields the same result',
-    still_running: 'the target is STILL RUNNING — steer it instead of resuming, or wait for it to settle (this is the exact opposite of not_running: never collapse the two)',
-    blocked_by_hook: "this deployment's userPromptSubmit gate refused the input (block, timeout and crash all report this one code, fail-closed) — the input was NOT accepted: no human_input frame, the inputId is not on the ledger, so editing the text and sending again is a normal retry, not a duplicate",
-    ledger_unavailable: 'the server could not record this steer in its user-input ledger and refused it before anything reached the engine — the input was NOT delivered; resend the same text later (the same Idempotency-Key is fine)',
-    steering_other: 'an unrecognized steering.* refusal (open set) — the steer did NOT land; log the errorCode verbatim, do not guess its meaning',
+const STEERING_COPY = {
+    not_running: {
+        happened: 'that run is not accepting messages right now — it has just finished, is running on another server, or is not the active run of its session',
+        nextStep: 'check its current state and send the message to the run that is active',
+    },
+    invalid_content: {
+        happened: 'the message was refused because its text contains control markers the engine does not accept, so nothing was delivered',
+        nextStep: 'rewrite the message and send it again',
+    },
+    queue_full: {
+        happened: 'that run is paused and already holds as many waiting messages as it can, so this one was not accepted',
+        nextStep: 'send it again once the waiting messages have been delivered (when the run resumes or the session is woken)',
+    },
+    duplicate_input_id: {
+        happened: 'a different instruction was already accepted under this idempotency key, and that earlier instruction stands',
+        nextStep: 'if you changed the text, send the new text under a new key; otherwise do not resend it — a new key would deliver the same instruction twice',
+    },
+    ambiguous_target: {
+        happened: 'more than one running agent matches that target, so the message was not delivered',
+        nextStep: 'address a sub-agent by its tool-call id; a workflow agent cannot be singled out while another running agent shares its label, so send it again once only one does',
+    },
+    still_running: {
+        happened: 'that agent is still running, so it cannot be resumed',
+        nextStep: 'send it a message instead, or wait for it to finish',
+    },
+    blocked_by_hook: {
+        happened: "the message was not accepted: a prompt check on this deployment blocked it, so nothing was delivered",
+        nextStep: 'edit the message and send it again — that is not a duplicate submission',
+    },
+    ledger_unavailable: {
+        happened: 'the server could not record the message and refused it before anything reached the engine, so nothing was delivered',
+        nextStep: 'send the same text again later',
+    },
+    steering_other: {
+        happened: 'the message was refused for a reason this version does not recognise, so it did not land',
+        nextStep: 'report its error code if this keeps happening; do not guess what it means',
+    },
+};
+const adviceOfCopy = (c) => `${c.happened} — ${c.nextStep}`;
+const STEERING_ADVICE = Object.freeze(Object.fromEntries(Object.entries(STEERING_COPY).map(([k, c]) => [k, adviceOfCopy(c)])));
+const STEERING_OTHER_UNKNOWN_COPY = {
+    happened: 'the message was refused for a reason this version does not recognise, and whether it was delivered is not known',
+    nextStep: 'do not resend it as if it had certainly been dropped — check the run first, and report its error code if this keeps happening',
+};
+const CANCEL_NOT_FOUND_COPY = {
+    happened: 'this server has no run with that id for you — it does not exist, or it belongs to someone else',
+    nextStep: 'nothing was cancelled; refresh the run list',
+};
+const PRIORITY_NOT_APPLIED_COPY = {
+    advisory: {
+        happened: "this server accepts a steer priority but does not apply it — a 'now' message would not interrupt the running turn and a 'later' message would not wait",
+        nextStep: 'nothing was sent; to interrupt the turn now, send the text as an interrupt, or send it without a priority to have it delivered at the next turn boundary',
+    },
+    unknown: {
+        happened: 'whether this server applies a steer priority is not known — there is no usable capability reading for it',
+        nextStep: 'nothing was sent; wait for the capability reading and try again, or send it without a priority to have it delivered at the next turn boundary',
+    },
+};
+const STEER_INPUT_INVALID_COPY = {
+    happened: "the steer request could not be built — its priority must be 'now', 'next' or 'later', and its fields must be readable",
+    nextStep: 'nothing was sent; fix the request and send it again',
 };
-const STEERING_OTHER_UNKNOWN_ADVICE = 'an unrecognized steering.* refusal (open set) — treat delivery as unknown (do not resend as if it had certainly been dropped); log the errorCode verbatim, do not guess its meaning';
 export function steeringStatusIs4xx(e) {
     let status;
     try {
@@ -176,10 +207,10 @@ export function steeringStatusIs4xx(e) {
     }
     return status !== undefined && status >= 400 && status < 500;
 }
-function steeringAdviceOf(e, safety) {
+function steeringCopyOf(e, safety) {
     if (safety === 'steering_other' && !steeringStatusIs4xx(e))
-        return STEERING_OTHER_UNKNOWN_ADVICE;
-    return STEERING_ADVICE[safety];
+        return STEERING_OTHER_UNKNOWN_COPY;
+    return STEERING_COPY[safety];
 }
 const STEERING_REFUSED_BEFORE_ENGINE = new Map([['ledger_unavailable', 503]]);
 export function steeringRefusedBeforeEngine(e) {
@@ -190,7 +221,8 @@ export function steeringRefusedBeforeEngine(e) {
         const safety = steeringVerdict(e);
         if (safety === undefined || STEERING_REFUSED_BEFORE_ENGINE.get(safety) !== status)
             return undefined;
-        return { safety, advice: STEERING_ADVICE[safety] };
+        const copy = STEERING_COPY[safety];
+        return { safety, advice: STEERING_ADVICE[safety], happened: copy.happened, nextStep: copy.nextStep };
     }
     catch {
         return undefined;
@@ -217,7 +249,8 @@ export function steerRefusalAdviceOf(e) {
         if (verdict === undefined)
             return undefined;
         const safety = steeringSafetyOf(e, verdict);
-        return { safety, advice: steeringAdviceOf(e, safety) };
+        const copy = steeringCopyOf(e, safety);
+        return { safety, advice: adviceOfCopy(copy), happened: copy.happened, nextStep: copy.nextStep };
     }
     catch {
         return undefined;
@@ -245,6 +278,38 @@ function controlSafetyRefusal(code, head, advice, cause) {
     const detail = { ...(advice !== undefined ? { advice } : {}), ...(status !== undefined ? { status } : {}) };
     return new ControlSafetyError(advice === undefined ? head : `${head} — ${advice}`, code, cause, detail);
 }
+export const UNOBSERVED_STEER_PRIORITY = Object.freeze({ kind: 'unobserved' });
+function steerLocalRefusal(code, mode, cause) {
+    const copy = code === 'steer_input_invalid' ? STEER_INPUT_INVALID_COPY : PRIORITY_NOT_APPLIED_COPY[mode === 'advisory' ? 'advisory' : 'unknown'];
+    return controlSafetyRefusal(code, 'steer not sent', adviceOfCopy(copy), cause);
+}
+function ownInputField(input, key) {
+    return Object.hasOwn(input, key) ? input[key] : undefined;
+}
+export function steerBodyOf(input, reading) {
+    let text;
+    let mode;
+    let priority;
+    try {
+        if (input === null || typeof input !== 'object' || Array.isArray(input))
+            throw new TypeError('steer input is not an object');
+        text = ownInputField(input, 'text');
+        mode = ownInputField(input, 'mode');
+        priority = ownInputField(input, 'priority');
+    }
+    catch (e) {
+        throw steerLocalRefusal('steer_input_invalid', 'unknown', e);
+    }
+    const base = mode !== undefined ? { text, mode } : { text };
+    if (priority === undefined || priority === 'next')
+        return Object.freeze(base);
+    const tierMode = steerPriorityMode(reading);
+    if (priority !== 'now' && priority !== 'later')
+        throw steerLocalRefusal('steer_input_invalid', tierMode);
+    if (tierMode !== 'engine')
+        throw steerLocalRefusal('priority_not_applied', tierMode);
+    return Object.freeze({ ...base, priority });
+}
 function isCancelSuspendedConflict(e) {
     const { name, status } = errCodes(e);
     return name === 'ConflictError' || status === 409;

package/dist/coreValuePorts.d.ts

@@ -32,7 +32,7 @@ export interface CoreProtocolNamespaceView {
 }
 export interface PermissionRuleView {
     rule: string;
-    behavior: 'deny' | 'ask' | 'allow';
+    behavior: 'deny' | 'ask';
     source?: string;
 }
 export interface PermissionRuleIssueView {
@@ -59,8 +59,9 @@ export interface CoreValuePorts {
     ruleToolGrammarOf: (toolName: string) => 'command' | 'path' | undefined;
     validatePermissionRules: (rules: PermissionRuleView[], opts?: ValidatePermissionRulesOptionsView) => PermissionRuleIssueView[];
     DISCUSSION_WORKFLOW_NAME: string;
+    mintNamespacePrefix(ns: CoreProtocolNamespaceView, peer: string): string;
 }
-export declare const CORE_VALUE_PORT_NAMES: readonly ["resolveAutonomousLoopPrompt", "loosenReasons", "combinePolicies", "createAllowDenyPolicy", "MCP_NAMESPACE", "RETIRED_TOOL_NAMES", "protocolOf", "ruleToolGrammarOf", "validatePermissionRules", "DISCUSSION_WORKFLOW_NAME"];
+export declare const CORE_VALUE_PORT_NAMES: readonly ["resolveAutonomousLoopPrompt", "loosenReasons", "combinePolicies", "createAllowDenyPolicy", "MCP_NAMESPACE", "RETIRED_TOOL_NAMES", "protocolOf", "ruleToolGrammarOf", "validatePermissionRules", "DISCUSSION_WORKFLOW_NAME", "mintNamespacePrefix"];
 export type CoreValuePortName = (typeof CORE_VALUE_PORT_NAMES)[number];
 export declare function installCoreValuePorts(ports: Partial<CoreValuePorts> | null): () => void;
 export declare function hasCoreValuePorts(): boolean;
@@ -76,3 +77,4 @@ export declare function protocolOf(name: string): CoreProtocolNamespaceView | un
 export declare function ruleToolGrammarOf(toolName: string): 'command' | 'path' | undefined;
 export declare function validatePermissionRules(rules: PermissionRuleView[], opts?: ValidatePermissionRulesOptionsView): PermissionRuleIssueView[] | undefined;
 export declare function discussionWorkflowName(): string | undefined;
+export declare function mintNamespacePrefix(ns: CoreProtocolNamespaceView, peer: string): string | undefined;

package/dist/coreValuePorts.js

@@ -9,6 +9,7 @@ export const CORE_VALUE_PORT_NAMES = Object.freeze([
     'ruleToolGrammarOf',
     'validatePermissionRules',
     'DISCUSSION_WORKFLOW_NAME',
+    'mintNamespacePrefix',
 ]);
 let installed = null;
 export function installCoreValuePorts(ports) {
@@ -67,3 +68,7 @@ export function validatePermissionRules(rules, opts) {
 export function discussionWorkflowName() {
     return port('DISCUSSION_WORKFLOW_NAME');
 }
+export function mintNamespacePrefix(ns, peer) {
+    const fn = port('mintNamespacePrefix');
+    return fn === undefined ? undefined : fn(ns, peer);
+}

package/dist/decideFailureNote.js

@@ -1,6 +1,6 @@
 import { corruptStoredRowContent, corruptStoredRowWhere } from './wireErrorTriage.js';
 import { checkpointUnsupportedVersionContent, checkpointUnsupportedVersionFromError, parkedResumeStartupContent, parkedResumeStartupFromError, resumePolicyBlockContent, resumePolicyBlockFromError, } from './resumeRefusalCopy.js';
-import { decideParkMovedContent, decideParkMovedFromError } from './decideReceipt.js';
+import { askGoneContent, askGoneFromError, decideParkMovedContent, decideParkMovedFromError } from './decideReceipt.js';
 import { settingsPermissionBucketRefusalContent, settingsPermissionBucketRefusalFromError } from './wireRefusalCopy.js';
 export function decideFailureNote(err, decision) {
     const where = corruptStoredRowWhere(err);
@@ -9,10 +9,12 @@ export function decideFailureNote(err, decision) {
     const moved = decideParkMovedFromError(err);
     const bucket = settingsPermissionBucketRefusalFromError(err);
     const unsupported = checkpointUnsupportedVersionFromError(err);
+    const gone = askGoneFromError(err);
     return ((where === undefined ? '' : ` — ${corruptStoredRowContent(where)}`) +
         (fold === null ? '' : ` — ${resumePolicyBlockContent(fold)}`) +
         (bucket === null ? '' : ` — ${settingsPermissionBucketRefusalContent(bucket)}`) +
         (startup === null ? '' : ` — ${parkedResumeStartupContent(startup)}`) +
         (moved === null ? '' : ` — ${decideParkMovedContent(moved)}`) +
-        (unsupported === null ? '' : ` — ${checkpointUnsupportedVersionContent(unsupported)}`));
+        (unsupported === null ? '' : ` — ${checkpointUnsupportedVersionContent(unsupported)}`) +
+        (gone === null ? '' : ` — ${askGoneContent(gone)}`));
 }

package/dist/decideReceipt.d.ts

@@ -1,5 +1,6 @@
 import { type GateOutcomeView } from './gateOutcome.js';
 import { type ResumeReopenDetail } from './hitl/suspendedReopen.js';
+import { type CrashConvergedRow } from './hitl/crashConverged.js';
 export interface DecideReceiptView {
     status?: string;
     taskId?: string;
@@ -27,3 +28,11 @@ export interface DecideParkMovedDetail {
 }
 export declare function decideParkMovedFromError(e: unknown): DecideParkMovedDetail | null;
 export declare function decideParkMovedContent(detail: Pick<DecideParkMovedDetail, 'code'>): string;
+export interface AskGoneDetail {
+    code: 'gone.ask';
+    state?: 'VOID' | 'DENIED';
+    deniedReason?: string;
+    holderGone?: CrashConvergedRow['cause'];
+}
+export declare function askGoneFromError(e: unknown): AskGoneDetail | null;
+export declare function askGoneContent(detail: AskGoneDetail): string;

package/dist/decideReceipt.js

@@ -1,8 +1,9 @@
 import { gateOutcomeOf } from './gateOutcome.js';
 import { resumeReopenFromError } from './hitl/suspendedReopen.js';
-import { DECIDE_CLAIM_LOST, DECIDE_GATE_MOVED, DECIDE_NOT_PARKED, DECIDE_WORKFLOW_HOST_UNKNOWN, DECIDE_WORKFLOW_LANE_CODES, DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED, isDecideParkMovedCode, } from './engineErrorCodes.js';
+import { ASK_GONE, ASK_GONE_DENIED_WORD, DECIDE_CLAIM_LOST, DECIDE_GATE_MOVED, DECIDE_NOT_PARKED, DECIDE_WORKFLOW_HOST_UNKNOWN, DECIDE_WORKFLOW_LANE_CODES, DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED, isDecideParkMovedCode, } from './engineErrorCodes.js';
 import { effectiveWireErrorCode } from './wireErrorTriage.js';
 import { readErrorString } from './wireFailureShape.js';
+import { isCrashConvergedCause } from './hitl/crashConverged.js';
 const STATUS_RESUMING = 'resuming';
 function str(v) {
     return typeof v === 'string' && v.length > 0 ? v : undefined;
@@ -106,3 +107,63 @@ export function decideParkMovedContent(detail) {
     const extra = code === DECIDE_CLAIM_LOST ? '; if this approval is still listed, wait a little before deciding it again' : '';
     return `${what} · This decision was not applied — fetch the pending approvals again and decide from what is pending now${extra}`;
 }
+export function askGoneFromError(e) {
+    if (typeof e !== 'object' || e === null)
+        return null;
+    if (effectiveWireErrorCode(e) !== ASK_GONE)
+        return null;
+    const rawState = readErrorString(e, 'state');
+    const state = rawState === 'VOID' || rawState === 'DENIED' ? rawState : undefined;
+    const rawReason = readErrorString(e, 'deniedReason');
+    const deniedReason = rawReason === undefined || rawReason.length === 0
+        ? undefined
+        : state === 'DENIED'
+            ? rawReason === ASK_GONE_DENIED_WORD ? rawReason : undefined
+            : state === 'VOID' ? rawReason : undefined;
+    const holderGone = state === 'VOID' && isCrashConvergedCause(deniedReason) ? deniedReason : undefined;
+    return {
+        code: ASK_GONE,
+        ...(state !== undefined ? { state } : {}),
+        ...(deniedReason !== undefined ? { deniedReason } : {}),
+        ...(holderGone !== undefined ? { holderGone } : {}),
+    };
+}
+export function askGoneContent(detail) {
+    let state;
+    let deniedReason;
+    let holderGone;
+    try {
+        state = detail.state;
+        deniedReason = detail.deniedReason;
+        holderGone = detail.holderGone;
+    }
+    catch {
+        state = undefined;
+        deniedReason = undefined;
+        holderGone = undefined;
+    }
+    const st = state === 'VOID' || state === 'DENIED' ? state : undefined;
+    const safety = 'Your answer was not applied and nothing was run on it';
+    if (st === 'VOID' && (isCrashConvergedCause(holderGone) || isCrashConvergedCause(deniedReason))) {
+        return [
+            'The engine run that was waiting for this answer ended before the answer arrived',
+            safety,
+            'That run will not continue: submit the work again as a new task, and it will ask again',
+        ].join(' · ');
+    }
+    if (st === 'DENIED') {
+        return ['This approval was closed without a human decision and the request was denied', safety, 'The denial stands; this approval cannot be reopened'].join(' · ');
+    }
+    if (st === 'VOID') {
+        return [
+            'This approval was withdrawn without a human decision',
+            safety,
+            'Nothing is waiting for this answer any more; if the work still needs this step, wait for it to be asked again or submit the work again',
+        ].join(' · ');
+    }
+    return [
+        'This approval was closed without a human decision',
+        safety,
+        'It can no longer be decided; fetch the pending approvals again and decide from what is pending now',
+    ].join(' · ');
+}

package/dist/displayUntrusted.js

@@ -1,3 +1,4 @@
+import { SETTINGS_SECRET_LITERAL_RE } from './generated/settingsSchemaTables.js';
 export const REDACTION_MARKER_PREFIX = '\u00abredacted';
 const MARKER_RE = /^\u00abredacted(?::[a-z-]{1,16}){0,2}\u00bb$/;
 const REDACTED_USERINFO = '\u00abredacted:userinfo\u00bb';
@@ -26,7 +27,7 @@ function pushEdit(edits, src, start, end, text) {
 const UNIT_NONE = 0;
 const UNIT_SEQUENCE = 1;
 const UNIT_SINGLE = 2;
-const SECRET_LITERAL_RE = /^(sk-|gh[opus]_|github_pat_|xox[baprse]-|xapp-|bearer\s|basic\s|eyJ[A-Za-z0-9_-]{10,}\.|AKIA[0-9A-Z]{12,}|AIza[0-9A-Za-z_-]{20,}|-----BEGIN[A-Z0-9 ]*PRIVATE KEY)/i;
+const SECRET_LITERAL_RE = SETTINGS_SECRET_LITERAL_RE;
 const SCHEME_TOKEN_RE = /(?:^|[^A-Za-z0-9_-])(?:bearer|basic)[ \t]+\S{8,4096}/i;
 const JWT_RE = /(?:^|[^A-Za-z0-9_-])eyJ[A-Za-z0-9_-]{8,2048}\.[A-Za-z0-9_-]{8,2048}\.[A-Za-z0-9_-]{4,2048}/i;
 function scanForSecretLiteral(s) {

package/dist/effectiveFacts.d.ts

@@ -7,15 +7,25 @@ export interface EffectiveReasoningView {
     endpoint: string;
     dropped?: true;
 }
+export type EffectiveMemoryProjectKey = {
+    readonly scope: string;
+    readonly absent?: never;
+} | {
+    readonly absent: string;
+    readonly scope?: never;
+};
+export interface EffectiveMemoryScopeRow {
+    scope: string;
+    origin: 'deployment' | 'request';
+    shadowed?: number;
+}
 export interface EffectiveMemoryScopesView {
     state: 'mounted' | 'memoryless' | 'none';
     reason?: string;
     contract?: 'v2' | 'legacy';
-    scopes: readonly {
-        scope: string;
-        origin: 'deployment' | 'request';
-    }[];
+    scopes: readonly EffectiveMemoryScopeRow[];
     writeScope: string | null;
+    projectKey?: EffectiveMemoryProjectKey;
     materializedResidue?: readonly string[];
 }
 export declare function readEffectiveReasoning(v: unknown): EffectiveReasoningView | undefined;

package/dist/effectiveFacts.js

@@ -1,4 +1,37 @@
 const nonEmpty = (v) => typeof v === 'string' && v.length > 0;
+const nonBlank = (v) => typeof v === 'string' && v.trim().length > 0;
+const UNREADABLE = Symbol('unreadable');
+const protectedRead = (o, key) => {
+    try {
+        return o[key];
+    }
+    catch {
+        return UNREADABLE;
+    }
+};
+function readProjectKey(v) {
+    try {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+            return undefined;
+        const o = v;
+        const scope = protectedRead(o, 'scope');
+        const absent = protectedRead(o, 'absent');
+        if (scope === UNREADABLE || absent === UNREADABLE)
+            return undefined;
+        if ((scope === undefined) === (absent === undefined))
+            return undefined;
+        if (scope !== undefined)
+            return nonBlank(scope) ? { scope } : undefined;
+        return nonBlank(absent) ? { absent } : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readShadowed(r, isWriteHome) {
+    const n = protectedRead(r, 'shadowed');
+    return !isWriteHome && typeof n === 'number' && Number.isSafeInteger(n) && n > 0 ? n : undefined;
+}
 export function readEffectiveReasoning(v) {
     if (typeof v !== 'object' || v === null)
         return undefined;
@@ -27,7 +60,8 @@ export function readEffectiveMemoryScopes(v) {
         return undefined;
     if (!Array.isArray(o.scopes))
         return undefined;
-    if (o.writeScope !== null && typeof o.writeScope !== 'string')
+    const writeScope = o.writeScope;
+    if (writeScope !== null && typeof writeScope !== 'string')
         return undefined;
     const contract = o.contract === 'v2' || o.contract === 'legacy' ? o.contract : undefined;
     const reason = nonEmpty(o.reason) ? o.reason : undefined;
@@ -39,13 +73,19 @@ export function readEffectiveMemoryScopes(v) {
             if (typeof row !== 'object' || row === null)
                 continue;
             const r = row;
-            if (!nonEmpty(r.scope) || typeof r.origin !== 'string' || !ORIGINS.has(r.origin))
+            const scope = r.scope;
+            if (!nonEmpty(scope))
+                continue;
+            const origin = r.origin;
+            if (typeof origin !== 'string' || !ORIGINS.has(origin))
                 continue;
-            scopes.push({ scope: r.scope, origin: r.origin });
+            const shadowed = readShadowed(r, scope === writeScope);
+            scopes.push({ scope, origin: origin, ...(shadowed !== undefined ? { shadowed } : {}) });
         }
-        return { state: 'mounted', contract, scopes, writeScope: o.writeScope };
+        const projectKey = readProjectKey(protectedRead(o, 'projectKey'));
+        return { state: 'mounted', contract, scopes, writeScope, ...(projectKey !== undefined ? { projectKey } : {}) };
     }
-    if (o.scopes.length !== 0 || o.writeScope !== null)
+    if (o.scopes.length !== 0 || writeScope !== null)
         return undefined;
     if (o.state === 'memoryless') {
         if (reason !== 'mount-failed' && reason !== 'no-backend')

package/dist/engineAgentAbsence.js

@@ -2,6 +2,7 @@ import { registryClockNowMs, registryListingProvenanceOf } from './agentSession/
 import { displayUntrusted } from './displayUntrusted.js';
 import { ABSENT_SETTLE_MS } from './fleetAgentPanelProjection.js';
 import { isEnginePanelTaskResident, isStaleEngineAgentPanelEnd, } from './engineAgentPanelStore.js';
+import { CORE_DURABLE_AGENT_HANDLE_RE } from './generated/engineFactTables.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) {
@@ -132,7 +133,7 @@ export function engineAgentTerminalAfterDropLine(label, status, hasReport) {
     return `${displayUntrusted(label)} reported ${displayUntrusted(status)} after it was dropped from the task panel${tail}`;
 }
 const REGISTRY_LIST_LIMIT = 500;
-const REGISTRY_AGENT_HANDLE_RE = /^a[0-9a-f]{6,32}$/;
+const REGISTRY_AGENT_HANDLE_RE = CORE_DURABLE_AGENT_HANDLE_RE;
 const REGISTRY_AGENT_TYPE = 'background_agent';
 function registryStatusReading(status) {
     const s = status;

package/dist/engineCapReader.js

@@ -1,4 +1,5 @@
 import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
+import { capsGenerationMarkOf, retainCapsGenerationMark } from './engineCapsCache.js';
 function freezeReading(reading, seen = new Set()) {
     if (reading === null || typeof reading !== 'object' || seen.has(reading))
         return reading;
@@ -11,7 +12,7 @@ function freezeReading(reading, seen = new Set()) {
     return reading;
 }
 export function createEngineCapReader(spec) {
-    const readingByBase = new Map();
+    const cellByBase = new Map();
     return {
         note(baseUrl, caps, opts) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
@@ -21,6 +22,7 @@ export function createEngineCapReader(spec) {
                 return;
             if (!capsGenerationStillCurrent(baseUrl, gen))
                 return;
+            const mark = retainCapsGenerationMark(baseUrl);
             let reading;
             try {
                 reading = spec.project(caps);
@@ -28,29 +30,33 @@ export function createEngineCapReader(spec) {
             catch {
                 reading = undefined;
             }
-            if (!capsGenerationStillCurrent(baseUrl, gen))
+            if (capsGenerationMarkOf(baseUrl) !== mark)
                 return;
             if (reading === undefined) {
-                readingByBase.delete(baseUrl);
+                cellByBase.delete(baseUrl);
                 return;
             }
-            readingByBase.set(baseUrl, freezeReading(reading));
+            cellByBase.set(baseUrl, { reading: freezeReading(reading), mark });
         },
         observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
                 return spec.makeUnobserved();
-            const hit = readingByBase.get(baseUrl);
-            if (hit !== undefined)
-                return hit;
-            return spec.makeUnobserved();
+            const cell = cellByBase.get(baseUrl);
+            if (cell === undefined)
+                return spec.makeUnobserved();
+            if (cell.mark !== capsGenerationMarkOf(baseUrl)) {
+                cellByBase.delete(baseUrl);
+                return spec.makeUnobserved();
+            }
+            return cell.reading;
         },
         forget(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
                 return;
-            readingByBase.delete(baseUrl);
+            cellByBase.delete(baseUrl);
         },
         __resetForTests() {
-            readingByBase.clear();
+            cellByBase.clear();
         },
     };
 }

package/dist/engineCapsCache.d.ts

@@ -1,4 +1,6 @@
 export declare function engineCapsGeneration(baseUrl: string): number;
+export declare function capsGenerationMarkOf(baseUrl: string): object | undefined;
+export declare function retainCapsGenerationMark(baseUrl: string): object;
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
 export declare function engineCapsSettled(baseUrl: string | undefined, opts?: {
     withinMs?: number;

package/dist/engineCapsCache.js

@@ -3,11 +3,22 @@ const inFlight = new Set();
 const settleByBase = new Map();
 const genByBase = new Map();
 function capsGeneration(baseUrl) {
-    return genByBase.get(baseUrl) ?? 0;
+    return genByBase.get(baseUrl)?.n ?? 0;
 }
 export function engineCapsGeneration(baseUrl) {
     return capsGeneration(baseUrl);
 }
+export function capsGenerationMarkOf(baseUrl) {
+    return genByBase.get(baseUrl);
+}
+export function retainCapsGenerationMark(baseUrl) {
+    let mark = genByBase.get(baseUrl);
+    if (mark === undefined) {
+        mark = Object.freeze({ n: 0 });
+        genByBase.set(baseUrl, mark);
+    }
+    return mark;
+}
 export function kickEngineCapsProbe(baseUrl, probe) {
     if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
         return;
@@ -165,7 +176,7 @@ export function invalidateEngineCaps(baseUrl, probe) {
         settleByBase.has(baseUrl) ||
         genByBase.has(baseUrl);
     if (hadState) {
-        genByBase.set(baseUrl, capsGeneration(baseUrl) + 1);
+        genByBase.set(baseUrl, Object.freeze({ n: capsGeneration(baseUrl) + 1 }));
         capsByBase.delete(baseUrl);
         inFlight.delete(baseUrl);
         settleByBase.get(baseUrl)?.wake();