@sema-agent/client-core 0.89.0 → 0.91.0

package/dist/attachmentsWireCaps.js

@@ -1,11 +1,11 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
+import { retiredAttachmentsKeyOf } from './taskRequestWords.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
 export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
     'todoReminderMode',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -17,7 +17,6 @@ export const ATTACHMENTS_DEFAULT_ON_KEYS = ['agentListing', 'skillsListing', 'ba
 const OPT_IN_KEYS = [
     'todoReminder',
     'changedFiles',
-    'planModeReminder',
     'budgetUsd',
     'backgroundTasks',
     'toolsDelta',
@@ -28,25 +27,48 @@ const DEFAULT_PAIR = ['backgroundTasks', 'toolsDelta'];
 const _attachmentsKeyPins = [true, true, true, true, true, true];
 void _attachmentsKeyPins;
 const TODO_REMINDER_MODES = ['baseline', 'off'];
+export class AttachmentsSpecRefused extends TypeError {
+    token;
+    why;
+    allowed;
+    constructor(message, init) {
+        super(message);
+        this.name = 'AttachmentsSpecRefused';
+        this.token = init.token;
+        this.why = init.why;
+        this.allowed = Object.freeze([...init.allowed]);
+        if (init.key !== undefined)
+            this.key = init.key;
+    }
+}
+function legalAttachmentsTokens() {
+    return ['off', 'full', 'all', 'default', '<literalTrueKey>', '+<literalTrueKey>', ...DEFAULT_ON_ONLY_KEYS.map(k => `-${k}`), `todoReminderMode=${TODO_REMINDER_MODES.join('|')}`];
+}
 function refuse(token, why) {
-    throw new Error(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. ` +
-        `Legal tokens: off | full | all | default | <literalTrueKey> | +<literalTrueKey> | ` +
-        `-agentListing | -skillsListing | todoReminderMode=baseline|off`);
+    const allowed = legalAttachmentsTokens();
+    throw new AttachmentsSpecRefused(`${ATTACHMENTS_ENV}: refusing token "${token}" — ${why}. Legal tokens: ${allowed.join(' | ')}`, { token, why, allowed });
 }
-export function attachmentsForRequest(env = hostEnv()) {
-    const raw = (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+function deny(kind, token, why, index, key) {
+    return { ok: false, refusal: { kind, token, why, entry: index + 1, key } };
+}
+function judgeAttachmentsEnv(raw) {
     if (envFlagOff(raw))
-        return allDefaultOnOff();
+        return { ok: true, spec: allDefaultOnOff() };
     const tokens = raw.split(',').map(t => t.trim()).filter(t => t.length > 0);
+    for (const [i, token] of tokens.entries()) {
+        const named = retiredAttachmentsKeyOf(token);
+        if (named !== undefined)
+            return { ok: false, refusal: { kind: 'retired_key', token, why: named.why, entry: i + 1, key: named.key, retired: named } };
+    }
     if (tokens.length === 0)
-        return { backgroundTasks: true, toolsDelta: true };
+        return { ok: true, spec: { backgroundTasks: true, toolsDelta: true } };
     if (tokens.length === 1 && (tokens[0] === 'full' || tokens[0] === 'all'))
-        return allLiteralTrue();
+        return { ok: true, spec: allLiteralTrue() };
     if (tokens.length === 1 && !isKnownToken(tokens[0])) {
-        return { backgroundTasks: true, toolsDelta: true };
+        return { ok: true, spec: { backgroundTasks: true, toolsDelta: true } };
     }
     const spec = {};
-    for (const token of tokens) {
+    for (const [i, token] of tokens.entries()) {
         if (token === 'full' || token === 'all') {
             Object.assign(spec, allLiteralTrue());
             continue;
@@ -59,11 +81,11 @@ export function attachmentsForRequest(env = hostEnv()) {
         if (token.startsWith('-')) {
             const key = canonicalKey(token.slice(1));
             if (key === undefined)
-                refuse(token, 'unknown attachments key');
+                return deny('unknown_key', token, 'unknown attachments key', i, undefined);
             if (!isDefaultOnKey(key)) {
-                refuse(token, `"${key}" belongs to the literal-true family whose OFF is "delete the key", not "send false" ` +
+                return deny('minus_on_literal_true_key', token, `"${key}" belongs to the literal-true family whose OFF is "delete the key", not "send false" ` +
                     '(core wire contract, board [479] ask-2) — simply do not turn it on. ' +
-                    `Only the core DEFAULT-ON keys (${ATTACHMENTS_DEFAULT_ON_KEYS.join(' / ')}) accept an explicit false`);
+                    `Only the core DEFAULT-ON keys (${ATTACHMENTS_DEFAULT_ON_KEYS.join(' / ')}) accept an explicit false`, i, key);
             }
             spec[key] = false;
             continue;
@@ -71,25 +93,76 @@ export function attachmentsForRequest(env = hostEnv()) {
         const [lhs, rhs] = splitAssign(token);
         if (rhs !== undefined) {
             if (canonicalKey(lhs) !== 'todoReminderMode')
-                refuse(token, 'only `todoReminderMode` takes a `key=value` form');
+                return deny('value_form_on_other_key', token, 'only `todoReminderMode` takes a `key=value` form', i, canonicalKey(lhs));
             const mode = TODO_REMINDER_MODES.find(v => v === rhs);
             if (mode === undefined)
-                refuse(token, `todoReminderMode must be one of ${TODO_REMINDER_MODES.join('|')}`);
+                return deny('todo_mode_bad_value', token, `todoReminderMode must be one of ${TODO_REMINDER_MODES.join('|')}`, i, 'todoReminderMode');
             spec.todoReminderMode = mode;
             continue;
         }
         const key = canonicalKey(lhs.startsWith('+') ? lhs.slice(1) : lhs);
         if (key === undefined)
-            refuse(token, 'unknown attachments key');
+            return deny('unknown_key', token, 'unknown attachments key', i, undefined);
         if (isDefaultOnOnlyKey(key)) {
-            refuse(token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` +
-                `use "-${key}" to turn it OFF`);
+            return deny('plus_on_default_on_key', token, `"${key}" is core DEFAULT-ON — turning it "on" is a no-op that would send a redundant true; ` + `use "-${key}" to turn it OFF`, i, key);
         }
         if (key === 'todoReminderMode')
-            refuse(token, 'todoReminderMode needs a value: `todoReminderMode=baseline|off`');
+            return deny('todo_mode_needs_value', token, 'todoReminderMode needs a value: `todoReminderMode=baseline|off`', i, key);
         spec[key] = true;
     }
-    return spec;
+    return { ok: true, spec };
+}
+function envRawOf(env) {
+    return (env[ATTACHMENTS_ENV] ?? '').trim().toLowerCase();
+}
+export function attachmentsForRequest(env = hostEnv()) {
+    const judged = judgeAttachmentsEnv(envRawOf(env));
+    if (!judged.ok)
+        return refuse(judged.refusal.token, judged.refusal.why);
+    return judged.spec;
+}
+function attachmentsWayOut() {
+    const on = OPT_IN_KEYS.join(', ');
+    const off = ATTACHMENTS_DEFAULT_ON_KEYS.join(', ');
+    return (`Accepted writing is either the single word off on its own (every attachment off; it cannot be combined with other entries), or a comma-separated list of: ` +
+        `full or all (every opt-in attachment on), default, the name of an attachment to turn on (${on}), a leading minus to turn off one of ${off}, and todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}. ` +
+        `To drop the setting altogether, unset ${ATTACHMENTS_ENV}; the defaults then apply.`);
+}
+function attachmentsRefusalSentence(r) {
+    const head = `The attachments setting (${ATTACHMENTS_ENV}) cannot be used as it is set: entry ${r.entry} of the list`;
+    const key = r.key ?? '';
+    switch (r.kind) {
+        case 'retired_key':
+            return `${head} names "${key}", a key that no longer exists — ${r.retired?.because ?? 'it was retired'}, and a request carrying that key is refused by the server. Remove that entry${r.retired === undefined ? '' : `; ${r.retired.remedy}`}. ${attachmentsWayOut()}`;
+        case 'unknown_key':
+            return `${head} is not an attachment this version knows. ${attachmentsWayOut()}`;
+        case 'minus_on_literal_true_key':
+            return key === 'todoReminderMode'
+                ? `${head} puts a minus on todoReminderMode, which is a setting with a value rather than something to turn off — write todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}, or leave it out of the list. A minus only works on ${ATTACHMENTS_DEFAULT_ON_KEYS.join(', ')}, which are on by default. ${attachmentsWayOut()}`
+                : `${head} puts a minus on ${key}, and a minus cannot switch that attachment off — it is on only when it is named, or when full, all or default switches it on. A minus only works on ${ATTACHMENTS_DEFAULT_ON_KEYS.join(', ')}, which are on by default. To leave ${key} out, do not name it, and if full, all or default is what switches it on, list the attachments you want one by one instead. ${attachmentsWayOut()}`;
+        case 'plus_on_default_on_key':
+            return `${head} turns on ${key}, which is already on by default. To turn it off write -${key}; otherwise leave it out of the list. ${attachmentsWayOut()}`;
+        case 'value_form_on_other_key':
+            return `${head} uses a name=value form, and only todoReminderMode takes one. ${attachmentsWayOut()}`;
+        case 'todo_mode_bad_value':
+            return `${head} gives todoReminderMode a value it does not accept; the values are ${TODO_REMINDER_MODES.join(' and ')}. ${attachmentsWayOut()}`;
+        case 'todo_mode_needs_value':
+            return `${head} names todoReminderMode without a value; write todoReminderMode=${TODO_REMINDER_MODES.join(' or todoReminderMode=')}. ${attachmentsWayOut()}`;
+    }
+}
+function attachmentsUnreadableSentence() {
+    return `The attachments setting (${ATTACHMENTS_ENV}) could not be read as text, so it cannot be used as it is set. Set it to a plain comma-separated list, or unset it. ${attachmentsWayOut()}`;
+}
+export function attachmentsSubmitVerdict(env = hostEnv()) {
+    try {
+        const judged = judgeAttachmentsEnv(envRawOf(env));
+        if (judged.ok)
+            return { ok: true, attachments: judged.spec };
+        return { ok: false, sentence: attachmentsRefusalSentence(judged.refusal), refusedKey: judged.refusal.key };
+    }
+    catch {
+        return { ok: false, sentence: attachmentsUnreadableSentence(), refusedKey: undefined };
+    }
 }
 function allDefaultOnOff() {
     const out = {};

package/dist/compensations.js

@@ -7,8 +7,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts bindTaskCard()',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货且达标线 ≥ server 1.290(typed parentToolCallId 在每条 tick 上恒在)后,' +
-            'FIFO 回落臂可删 —— 但只在**确认不再支持老引擎**时删,见 bindTaskCard 的 old-engine fallback 注释',
+        retireOn: 'RL-31',
     },
     {
         id: 'T34',
@@ -26,7 +25,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts fireSubagentStart()(类型恒记 + 一生一次去重 + if-started 门)',
         chromeArm: 'subagent_lifecycle',
         hostHalf: '真执行用户 hook 进程(浏览器宿主根本不能执行 ⇒ 这一半必须留端)',
-        retireOn: 'G21 / P3a(引擎侧发正式的 subagent 生命周期事件)后,壳替 fire 整条退役',
+        retireOn: 'RL-32',
     },
     {
         id: 'T36',
@@ -35,7 +34,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts settlePanelTasks 的四个调用点(tool_end 关卡 / result / turn 末 / abort)',
         chromeArm: 'inline_task_stats',
         hostHalf: null,
-        retireOn: 'W6(引擎为每条子代发终态 tick)后,防御 sweep 降为纯兜底',
+        retireOn: 'RL-33',
     },
     {
         id: 'T44',
@@ -53,7 +52,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId / wa-id / workflow-card-parent 三级门',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货后判据②③(形状嗅探 + 实例台账)可删,只留判据①(帧带 workflowRunId)',
+        retireOn: 'RL-34',
     },
     {
         id: 'T48',
@@ -63,7 +62,7 @@ export const MIGRATED_COMPENSATIONS = [
         chromeArm: null,
         hostHalf: 'footer 行过滤 isFooterTaskRow/filterFooterTaskRows —— 含「丢弃所有无 parentId 顶层行」' +
             '这条**端专属决策**(主 run 头部行由端自己合成渲染),留 TUI',
-        retireOn: 'P1-2 到货后 fleet 行自带 parentToolCallId ⇒ 双生行不需要按尾段查',
+        retireOn: 'RL-35',
     },
     {
         id: 'T1',
@@ -83,8 +82,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'notifications.ts taskNotificationDedupKey + taskNotificationDedupKeyFromWire(裸 wire 入口)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货(帧带 completionId)⇒ 键改成**读** completionId,重算算法整条删;' +
-            '删之前要先有一批「同一完成在两条通道上 completionId 相同」的实测(否则换成了一把更差的键)',
+        retireOn: 'RL-36',
     },
     {
         id: 'T3',
@@ -95,8 +93,7 @@ export const MIGRATED_COMPENSATIONS = [
             'adapt.ts importLedgerFromTranscript(消费口)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ **回植仍要做**(crash 窗口客观存在),但不必再解 XML —— 转录里直接带 ' +
-            'completionId。所以退的是「XML 反解」这一段,不是整条回植',
+        retireOn: 'RL-37',
     },
     {
         id: 'T25',
@@ -106,7 +103,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'toolResult.ts 终态轮询卡臂的预 seed + notifications.markEngineWorkflowNotified',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ 两个方向带同一个 completionId,预 seed 这一手(按 runId 抢跑)可删',
+        retireOn: 'RL-38',
     },
     {
         id: 'T53',
@@ -115,8 +112,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts task_notification / workflow_complete 两臂的四道门(逐道说明见本行上方注释)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-3 到货 ⇒ 降到「①渲染去重(键换 completionId)+ ④队列撤单」两道;②③ 删。' +
-            '🔴 判据不是「四变一」而是逐道过一遍上面那四行 —— 把 ④ 当成去重删掉会让队列里的旧条目重新上屏',
+        retireOn: 'RL-39',
     },
     {
         id: 'T49',
@@ -125,7 +121,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts task_progress 臂 registerSubagentAlias(explicitParent, taskId)',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'P1-2 到货后 content 帧自带 taskId ⇒ alias 学习整条可删',
+        retireOn: 'RL-40',
     },
 ];
 export function compensationSplitViolations() {

package/dist/controlRouter.d.ts

@@ -21,7 +21,12 @@ export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full'
 export declare class ControlSafetyError extends Error {
     readonly code: ControlSafetyCode;
     readonly cause?: unknown | undefined;
-    constructor(message: string, code: ControlSafetyCode, cause?: unknown | undefined);
+    readonly advice?: string;
+    readonly status?: number;
+    constructor(message: string, code: ControlSafetyCode, cause?: unknown | undefined, detail?: {
+        readonly advice?: string;
+        readonly status?: number;
+    });
 }
 export type QueuePriority = 'now' | 'next' | 'later';
 export interface QueuedCommand {
@@ -72,8 +77,10 @@ export interface ErrCodes {
 }
 export declare function errCodes(e: unknown): ErrCodes;
 export declare function steeringStatusIs4xx(e: object): boolean;
-export interface SteeringRefusedBeforeEngine {
+export interface SteerRefusalAdvice {
     safety: ControlSafetyCode;
     advice: string;
 }
+export type SteeringRefusedBeforeEngine = SteerRefusalAdvice;
 export declare function steeringRefusedBeforeEngine(e: object): SteeringRefusedBeforeEngine | undefined;
+export declare function steerRefusalAdviceOf(e: object): SteerRefusalAdvice | undefined;

package/dist/controlRouter.js

@@ -3,11 +3,17 @@ import { uuid } from './adapter/types.js';
 export class ControlSafetyError extends Error {
     code;
     cause;
-    constructor(message, code, cause) {
+    constructor(message, code, cause, detail) {
         super(message);
         this.code = code;
         this.cause = cause;
         this.name = 'ControlSafetyError';
+        const advice = detail?.advice;
+        const status = detail?.status;
+        if (typeof advice === 'string' && advice.length > 0)
+            this.advice = advice;
+        if (typeof status === 'number')
+            this.status = status;
     }
 }
 const BAND_RANK = { now: 0, next: 1, later: 2 };
@@ -55,39 +61,38 @@ export class ControlRouter {
     }
     async steer(text, mode, opts) {
         if (this.taskId === null) {
-            throw new ControlSafetyError('no run in flight to steer — submit a turn first', 'not_running');
+            throw controlSafetyRefusal('not_running', 'no run in flight to steer', 'submit a turn first');
         }
         const body = mode !== undefined ? { text, mode } : { text };
         try {
             return await this.client.runs.steer(this.taskId, body, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
-            const verdict = steeringVerdict(e);
-            if (verdict !== undefined) {
-                const safety = steeringSafetyOf(e, verdict);
-                const wireCode = errCodes(e).code ?? errCodes(e).name ?? 'steering.<unknown>';
-                throw new ControlSafetyError(`${wireCode} — ${steeringAdviceOf(e, safety) ?? 'steering refused'}`, safety, e);
+            if (typeof e === 'object' && e !== null) {
+                const refusal = steerRefusalAdviceOf(e);
+                if (refusal !== undefined)
+                    throw controlSafetyRefusal(refusal.safety, steerRefusalWireLabel(e), refusal.advice, e);
             }
             throw e;
         }
     }
     async cancel(opts) {
         if (this.taskId === null) {
-            throw new ControlSafetyError('no run in flight to cancel', 'not_found');
+            throw controlSafetyRefusal('not_found', 'no run in flight to cancel');
         }
         try {
             return await this.client.runs.cancel(this.taskId, opts?.signal !== undefined ? { signal: opts.signal } : undefined);
         }
         catch (e) {
             if (cancelConflictFromError(e)?.kind === 'run_not_running') {
-                throw new ControlSafetyError(`runs.cancel 409 conflict.run_not_running — ${cancelConflictContent({ kind: 'run_not_running' })}`, 'cancel_run_not_running', e);
+                throw controlSafetyRefusal('cancel_run_not_running', 'runs.cancel 409 conflict.run_not_running', cancelConflictContent({ kind: 'run_not_running' }), e);
             }
             if (isCancelSuspendedConflict(e)) {
-                throw new ControlSafetyError('runs.cancel 409 — the pending gate was decided or expired concurrently (lost CAS race); ' +
-                    'check what that decision did to the run before retrying the cancel', 'cancel_lost_race', e);
+                throw controlSafetyRefusal('cancel_lost_race', 'runs.cancel 409', 'the pending gate was decided or expired concurrently (lost CAS race); ' +
+                    'check what that decision did to the run before retrying the cancel', e);
             }
             if (isNotFound(e)) {
-                throw new ControlSafetyError('runs.cancel 404 — non-owner / unknown run (no existence leak)', 'not_found', e);
+                throw controlSafetyRefusal('not_found', 'runs.cancel 404 — non-owner / unknown run (no existence leak)', undefined, e);
             }
             throw e;
         }
@@ -149,17 +154,17 @@ const STEERING_NAME_TO_SAFETY = new Map([
     ['SteeringLedgerUnavailableError', 'ledger_unavailable'],
     ['SteeringError', 'steering_other'],
 ]);
-const STEERING_ADVICE = new Map([
-    ['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_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_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;
@@ -172,9 +177,9 @@ export function steeringStatusIs4xx(e) {
     return status !== undefined && status >= 400 && status < 500;
 }
 function steeringAdviceOf(e, safety) {
-    if (safety === 'steering_other' && !(typeof e === 'object' && e !== null && steeringStatusIs4xx(e)))
+    if (safety === 'steering_other' && !steeringStatusIs4xx(e))
         return STEERING_OTHER_UNKNOWN_ADVICE;
-    return STEERING_ADVICE.get(safety);
+    return STEERING_ADVICE[safety];
 }
 const STEERING_REFUSED_BEFORE_ENGINE = new Map([['ledger_unavailable', 503]]);
 export function steeringRefusedBeforeEngine(e) {
@@ -185,8 +190,7 @@ export function steeringRefusedBeforeEngine(e) {
         const safety = steeringVerdict(e);
         if (safety === undefined || STEERING_REFUSED_BEFORE_ENGINE.get(safety) !== status)
             return undefined;
-        const advice = STEERING_ADVICE.get(safety);
-        return advice === undefined ? undefined : { safety, advice };
+        return { safety, advice: STEERING_ADVICE[safety] };
     }
     catch {
         return undefined;
@@ -195,7 +199,7 @@ export function steeringRefusedBeforeEngine(e) {
 function steeringSafetyOf(e, verdict) {
     if (!STEERING_REFUSED_BEFORE_ENGINE.has(verdict))
         return verdict;
-    const refused = typeof e === 'object' && e !== null ? steeringRefusedBeforeEngine(e) : undefined;
+    const refused = steeringRefusedBeforeEngine(e);
     return refused !== undefined && refused.safety === verdict ? verdict : 'steering_other';
 }
 function steeringVerdict(e) {
@@ -207,6 +211,40 @@ function steeringVerdict(e) {
         return STEERING_NAME_TO_SAFETY.get(name);
     return undefined;
 }
+export function steerRefusalAdviceOf(e) {
+    try {
+        const verdict = steeringVerdict(e);
+        if (verdict === undefined)
+            return undefined;
+        const safety = steeringSafetyOf(e, verdict);
+        return { safety, advice: steeringAdviceOf(e, safety) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function steerRefusalWireLabel(e) {
+    try {
+        const { code, name } = errCodes(e);
+        return code ?? name ?? 'steering.<unknown>';
+    }
+    catch {
+        return 'steering.<unknown>';
+    }
+}
+function statusOfThrown(e) {
+    try {
+        return errCodes(e).status;
+    }
+    catch {
+        return undefined;
+    }
+}
+function controlSafetyRefusal(code, head, advice, cause) {
+    const status = statusOfThrown(cause);
+    const detail = { ...(advice !== undefined ? { advice } : {}), ...(status !== undefined ? { status } : {}) };
+    return new ControlSafetyError(advice === undefined ? head : `${head} — ${advice}`, code, cause, detail);
+}
 function isCancelSuspendedConflict(e) {
     const { name, status } = errCodes(e);
     return name === 'ConflictError' || status === 409;

package/dist/coreValuePorts.d.ts

@@ -16,6 +16,7 @@ export interface AllowDenyPolicyOptionsView {
     deny?: string[];
     onInvalidName?: 'throw' | 'skip';
     onInvalidNameIssue?: (issue: AllowDenyInvalidNameIssueView) => void;
+    scope?: 'grant' | 'narrowing';
 }
 export interface AllowDenyInvalidNameIssueView {
     entry: string;

package/dist/decideFailureNote.js

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

package/dist/disableSkillsWire.d.ts

@@ -14,4 +14,5 @@ export type DisableSkillsDeclaration = {
     };
 };
 export declare function disableSkillsDeclaration(want: unknown, baseUrl: string | undefined): DisableSkillsDeclaration;
+export declare function disableSkillsDeclarationSettled(want: boolean | null | undefined, baseUrl: string | undefined, withinMs: number): Promise<DisableSkillsDeclaration>;
 export {};

package/dist/disableSkillsWire.js

@@ -1,4 +1,4 @@
-import { engineCapState } from './engineCapsCache.js';
+import { engineCapState, engineCapsSettled } from './engineCapsCache.js';
 const KEY = 'disableSkills';
 const shapeOf = (v) => {
     try {
@@ -50,3 +50,10 @@ export function disableSkillsDeclaration(want, baseUrl) {
     const cause = WITHHELD_CAUSE_OF[state];
     return Object.freeze({ field: Object.freeze({}), withheld: Object.freeze({ cause, text: WITHHELD_TEXT[cause] }) });
 }
+export async function disableSkillsDeclarationSettled(want, baseUrl, withinMs) {
+    refuseBadDisableSkills(want, 'disableSkillsDeclarationSettled');
+    if (want !== true)
+        return disableSkillsDeclaration(want, baseUrl);
+    await engineCapsSettled(baseUrl, { withinMs: typeof withinMs === 'number' ? withinMs : 0 });
+    return disableSkillsDeclaration(want, baseUrl);
+}