@sema-agent/client-core 0.90.0 → 0.91.0

package/dist/adapt/arms.js

@@ -11,6 +11,7 @@ import { readAsyncLaunchedAgentReceipt } from '../toolResult.js';
 import { isWorkflowAgentTaskId, recordWorkflowAgentTaskId } from '../workflow.js';
 import { isTerminalStatus } from '../runTerminal.js';
 import { readToolHistoryMismatchKey } from '../toolHistoryMismatch.js';
+import { readProviderRejectionResendKey } from '../providerRejection.js';
 import { resolveEnginePanelTaskId } from '../engineAgentPanelStore.js';
 import { fleetRowAgentType } from '../fleet/fleetRowAgentType.js';
 import { chrome, mainLane, transcript, messageIdentityOf } from './ids.js';
@@ -23,6 +24,13 @@ function toolHistoryKeyCarry(m) {
     const key = readToolHistoryMismatchKey(typeof raw === 'object' && raw !== null ? raw : undefined);
     return key === undefined ? {} : { _sema_tool_history_mismatch: key };
 }
+function providerResendKeyCarry(m) {
+    if (m._sema_api_error_message !== true)
+        return {};
+    const raw = m._sema_provider_rejection_resend;
+    const key = readProviderRejectionResendKey(typeof raw === 'object' && raw !== null ? raw : undefined);
+    return key === undefined ? {} : { _sema_provider_rejection_resend: key };
+}
 const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
     const message = m.message;
     const blocks = Array.isArray(message?.content)
@@ -129,6 +137,7 @@ const assistantArm = function* (m, { ctx, idOf, text, cards, inst }) {
             parent_tool_use_id: null,
             ...(m._sema_api_error_message === true ? { _sema_api_error_message: true } : {}),
             ...toolHistoryKeyCarry(m),
+            ...providerResendKeyCarry(m),
         }, ctx.now());
         text.markEmittedText(textBlock.text);
     }

package/dist/adapter/downstream/eventToSdkMessage.js

@@ -1,4 +1,4 @@
-import { readInstructionsSegment, wiringManifestViewOf } from './wiringManifestView.js';
+import { readFleetSegment, readInstructionsSegment, wiringManifestViewOf } from './wiringManifestView.js';
 import { stamp, snapshotSegmentIdentity, } from '../types.js';
 import { turnUsageToModelUsage } from './turnUsageToModelUsage.js';
 import { ccToolDenialKindForToolEnd, gateOutcomeOf } from '../../gateOutcome.js';
@@ -551,7 +551,8 @@ function wiringManifestSupersetBody(ev) {
     const hands = projectHandsSection(ev);
     const fileHistory = projectFileHistorySection(ev);
     const instructions = readInstructionsSegment(ev, 'instructions');
-    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined && hands === undefined && fileHistory === undefined && instructions === undefined)
+    const fleet = readFleetSegment(ev, 'fleet');
+    if (modelGate === undefined && autoMode === undefined && mcp === undefined && tools === undefined && hooks === undefined && lsp === undefined && writeProtection === undefined && autoConsolidation === undefined && readDeny === undefined && hands === undefined && fileHistory === undefined && instructions === undefined && fleet === undefined)
         return undefined;
     return {
         ...(modelGate !== undefined ? { _sema_modelGate: modelGate } : {}),
@@ -566,6 +567,7 @@ function wiringManifestSupersetBody(ev) {
         ...(hands !== undefined ? { _sema_hands: hands } : {}),
         ...(fileHistory !== undefined ? { _sema_fileHistory: fileHistory } : {}),
         ...(instructions !== undefined ? { _sema_instructions: instructions } : {}),
+        ...(fleet !== undefined ? { _sema_fleet: fleet } : {}),
     };
 }
 function projectFileHistorySection(holder) {

package/dist/adapter/downstream/wiringManifestView.d.ts

@@ -15,8 +15,12 @@ export type WiringManifestSections = {
     _sema_instructions?: {
         readonly selected: readonly string[];
     };
+    _sema_fleet?: WiringManifestFleetView;
     eventId?: string;
 };
+export interface WiringManifestFleetView {
+    readonly subagentTranscripts: string;
+}
 export interface WiringManifestView {
     modelGate?: WiringManifestModelGate;
     autoMode?: WiringManifestAutoMode;
@@ -32,9 +36,11 @@ export interface WiringManifestView {
     instructions?: {
         readonly selected: readonly string[];
     };
+    fleet?: WiringManifestFleetView;
     eventId?: string;
 }
 export declare function readInstructionsSegment(holder: object, key: 'instructions' | '_sema_instructions'): {
     readonly selected: readonly string[];
 } | undefined;
+export declare function readFleetSegment(holder: object, key: 'fleet' | '_sema_fleet'): WiringManifestFleetView | undefined;
 export declare function wiringManifestViewOf(s: WiringManifestSections): WiringManifestView | undefined;

package/dist/adapter/downstream/wiringManifestView.js

@@ -27,9 +27,24 @@ export function readInstructionsSegment(holder, key) {
         return undefined;
     }
 }
+export function readFleetSegment(holder, key) {
+    try {
+        if (!Object.hasOwn(holder, key))
+            return undefined;
+        const raw = holder[key];
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw) || !Object.hasOwn(raw, 'subagentTranscripts'))
+            return undefined;
+        const tier = raw.subagentTranscripts;
+        return typeof tier === 'string' && tier.length > 0 ? Object.freeze({ subagentTranscripts: tier }) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 export function wiringManifestViewOf(s) {
     const instructions = readInstructionsSegment(s, '_sema_instructions');
+    const fleet = readFleetSegment(s, '_sema_fleet');
     const view = {
         ...(isObj(s._sema_modelGate) ? { modelGate: s._sema_modelGate } : {}),
         ...(isObj(s._sema_autoMode) ? { autoMode: s._sema_autoMode } : {}),
@@ -43,6 +58,7 @@ export function wiringManifestViewOf(s) {
         ...(isObj(s._sema_hands) && typeof s._sema_hands.mounted === 'boolean' ? { hands: s._sema_hands } : {}),
         ...(typeof s._sema_fileHistory === 'string' && s._sema_fileHistory.length > 0 ? { fileHistory: s._sema_fileHistory } : {}),
         ...(instructions !== undefined ? { instructions } : {}),
+        ...(fleet !== undefined ? { fleet } : {}),
     };
     if (Object.keys(view).length === 0)
         return undefined;

package/dist/adapter/runStream.js

@@ -7,6 +7,7 @@ import { ACTIVE_RUN_BUSY_ERROR_CODE, OUTPUT_INVALID, isCorruptSessionCode, isLim
 import { corruptSessionContent } from '../corruptSessionCopy.js';
 import { classifyToolHistoryMismatch, noteToolHistoryTerminal, openToolHistoryGeneration, TOOL_HISTORY_REWIND_SENTENCE, toolHistoryMismatchRowKey, toolHistoryRepeatSentence, toolHistoryRewindOffered, } from '../toolHistoryMismatch.js';
 import { isReviewPark, readRunTerminal, runTerminalCode } from '../runTerminal.js';
+import { providerRejectionResend } from '../providerRejection.js';
 import { washCredentials } from '../displayUntrusted.js';
 import { ccToolDenialKindForToolEnd, gateDeniedBy, gateOutcomeOf } from '../gateOutcome.js';
 import { resumeReopenContent, resumeReopenFromError, suspendedReopenOf } from '../hitl/suspendedReopen.js';
@@ -121,7 +122,7 @@ export function isModelOutputErrorRowText(text) {
     return text.trimStart().startsWith(`${MODEL_OUTPUT_ERROR_PREFIX}:`);
 }
 export const OUTCOME_UNKNOWN_ROW_PREFIX = 'Outcome unknown';
-function syntheticTerminalRow(ctx, text, historyKey) {
+function syntheticTerminalRow(ctx, text, historyKey, resend) {
     return stamp(ctx, {
         uuid: undefined,
         session_id: undefined,
@@ -130,6 +131,7 @@ function syntheticTerminalRow(ctx, text, historyKey) {
         parent_tool_use_id: null,
         _sema_api_error_message: true,
         ...(historyKey !== undefined ? { _sema_tool_history_mismatch: historyKey } : {}),
+        ...(resend !== undefined ? { _sema_provider_rejection_resend: { resend: resend.resend, text: resend.text } } : {}),
     });
 }
 function engineRunIdOf(result) {
@@ -264,41 +266,52 @@ export function toolHistoryErrorCarrierOf(terminalOrResult) {
         return empty();
     }
 }
+function terminalRowArmOf(facts) {
+    if (facts.errText === null)
+        return null;
+    return facts.busy.busy ? 'busy' : facts.governance ? 'governance' : isModelOutputErrorText(facts.errText) ? 'modelOutput' : 'apiError';
+}
 function toolHistoryCarrierFromFacts(x, facts) {
-    const empty = () => mintToolHistoryCarrier(undefined, undefined, undefined);
+    return apiErrorTerminalFromFacts(x, facts).carrier;
+}
+function apiErrorTerminalFromFacts(x, facts) {
+    const none = () => ({ carrier: mintToolHistoryCarrier(undefined, undefined, undefined), detail: undefined });
     try {
         const type = ownDataBit(x, 'type');
-        if (facts.errText === null || facts.busy.busy || facts.governance || isModelOutputErrorText(facts.errText))
-            return empty();
+        if (terminalRowArmOf(facts) !== 'apiError')
+            return none();
         if (type === 'failed')
-            return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(x, 'errorCode')), undefined, nonEmptyStr(ownDataBit(x, 'errorMessage')));
+            return { carrier: mintToolHistoryCarrier(nonEmptyStr(ownDataBit(x, 'errorCode')), undefined, nonEmptyStr(ownDataBit(x, 'errorMessage'))), detail: undefined };
         const result = type === 'done' ? plainObjectOf(ownDataBit(x, 'result')) : x;
         if (result === undefined)
-            return empty();
+            return none();
         const snap = ownTerminalSnapshot(result);
         if (snap === undefined)
-            return empty();
+            return none();
         const read = readRunTerminal(snap);
         if (read === null || read.kind !== 'failed')
-            return empty();
+            return none();
         const detail = plainObjectOf(ownDataBit(read, 'detail'));
         const detailStatus = detail !== undefined && ownDataBit(detail, 'kind') === PROVIDER_REJECTED_DETAIL ? ownDataBit(detail, 'status') : undefined;
         const apiFailure = plainObjectOf(ownDataBit(result, 'apiFailure'));
         const apiStatus = apiFailure === undefined ? undefined : ownDataBit(apiFailure, 'status');
         const status = typeof apiStatus === 'number' && Number.isFinite(apiStatus) ? apiStatus : typeof detailStatus === 'number' ? detailStatus : undefined;
-        return mintToolHistoryCarrier(nonEmptyStr(ownDataBit(read, 'code')), status, nonEmptyStr(ownDataBit(read, 'message')));
+        return {
+            carrier: mintToolHistoryCarrier(nonEmptyStr(ownDataBit(read, 'code')), status, nonEmptyStr(ownDataBit(read, 'message'))),
+            detail: detail,
+        };
     }
     catch {
-        return empty();
+        return none();
     }
 }
-function toolHistoryCarrierOfRowFrame(ev, facts) {
+function apiErrorTerminalOfRowFrame(ev, facts) {
     try {
         const x = plainObjectOf(ev);
-        return x === undefined ? mintToolHistoryCarrier(undefined, undefined, undefined) : toolHistoryCarrierFromFacts(x, facts);
+        return x === undefined ? { carrier: mintToolHistoryCarrier(undefined, undefined, undefined), detail: undefined } : apiErrorTerminalFromFacts(x, facts);
     }
     catch {
-        return mintToolHistoryCarrier(undefined, undefined, undefined);
+        return { carrier: mintToolHistoryCarrier(undefined, undefined, undefined), detail: undefined };
     }
 }
 const reportedDroppedTypes = new Set();
@@ -631,23 +644,24 @@ async function* runStreamInner(events, ctx, handle = {}) {
                 const maxTokHint = /max_tokens/i.test(errText)
                     ? '\nyour provider caps max_tokens lower — lower it in /model (press m, or M to type a value)'
                     : '';
-                const governance = rowFacts.governance;
                 const busyHandle = busy.handle;
-                const rowText = busy.busy
+                const arm = terminalRowArmOf(rowFacts);
+                const rowText = arm === 'busy'
                     ? `This session is locked by an earlier run${busyHandle ? ` (run ${busyHandle})` : ''} that ` +
                         `has not been released, so this message was NOT sent. Nothing releases it on its own — ` +
                         `cancel that run (POST /v1/runs/${busyHandle ?? '<id>'}/cancel), or start a new session.`
-                    : governance
+                    : arm === 'governance'
                         ?
                             `${isGovernanceStopRowText(errText) ? errText : `${RUN_STOPPED_MESSAGE_PREFIX}: ${errText}`}${maxTokHint}`
-                        : isModelOutputErrorText(errText)
+                        : arm === 'modelOutput'
                             ?
                                 `${MODEL_OUTPUT_ERROR_PREFIX}: ${errText}${maxTokHint}`
                             : `API Error: ${errText}${maxTokHint}`;
                 const sessionUnreadable = ev.type === 'failed'
                     ? isCorruptSessionCode(ev.errorCode)
                     : doneTerminal?.kind === 'failed' && isCorruptSessionCode(doneTerminal.code);
-                const historyMismatch = classifyToolHistoryMismatch(toolHistoryCarrierOfRowFrame(ev, rowFacts));
+                const historyTerminal = apiErrorTerminalOfRowFrame(ev, rowFacts);
+                const historyMismatch = classifyToolHistoryMismatch(historyTerminal.carrier);
                 const historyEchoedSid = ev.type === 'done' ? engineSessionIdOf(ev.result) : undefined;
                 const historyRepeat = noteToolHistoryTerminal({
                     sessionId: historyEchoedSid ?? ctx.sessionId,
@@ -657,10 +671,13 @@ async function* runStreamInner(events, ctx, handle = {}) {
                     replay: ev.type === 'done' && ev.replay === true,
                     mismatch: historyMismatch,
                 });
-                const rewindLine = historyMismatch !== null && ctx.lane !== 'print' && ctx.lane !== 'utility' && toolHistoryRewindOffered(ctx.offersRewind)
+                const rewindOffered = historyMismatch !== null && ctx.lane !== 'print' && ctx.lane !== 'utility' && toolHistoryRewindOffered(ctx.offersRewind);
+                const rewindLine = rewindOffered
                     ? `\n${TOOL_HISTORY_REWIND_SENTENCE}${historyRepeat !== undefined && historyRepeat >= 2 ? ` ${toolHistoryRepeatSentence(historyRepeat)}` : ''}`
                     : '';
-                yield syntheticTerminalRow(ctx, `${sessionUnreadable ? `${rowText}\n${corruptSessionContent()}` : rowText}${rewindLine}`, historyMismatch === null ? undefined : toolHistoryMismatchRowKey(historyMismatch, historyRepeat));
+                const resend = historyTerminal.detail !== undefined ? providerRejectionResend(historyTerminal.detail, historyTerminal.carrier) : undefined;
+                const resendLine = resend !== undefined ? `\n${resend.text}` : '';
+                yield syntheticTerminalRow(ctx, `${sessionUnreadable ? `${rowText}\n${corruptSessionContent()}` : rowText}${rewindLine}${resendLine}`, historyMismatch === null ? undefined : toolHistoryMismatchRowKey(historyMismatch, historyRepeat, rewindOffered), resend);
             }
             else {
                 const echoedSid = ev.type === 'done' ? engineSessionIdOf(ev.result) : undefined;

package/dist/askSurvivesStandingAnswer.d.ts

@@ -0,0 +1,10 @@
+export declare const MODE_ARBITRATION: Readonly<Record<"hook" | "write_protection" | "mode" | "rule_unreadable" | "content_question" | "ancestor" | "unverifiable_delete" | "transcript_write" | "org_rule" | "governance_unavailable" | "ask_rule" | "denial_limit_fallback" | "operator_forced" | "shell_floor" | "write_protection_unresolved" | "probe" | "tool_marks_mcp" | "tool_marks_a2a" | "policy_rra" | "artifact_shared_read" | "unstated" | "ordinary", import("./generated/engineFactTables.js").CoreModeArbitrationRow>>;
+export type StandingAnswerVerdict = {
+    readonly kind: 'must_ask';
+    readonly by: string;
+} | {
+    readonly kind: 'may_answer';
+} | {
+    readonly kind: 'unknown';
+};
+export declare function askSurvivesStandingAnswer(card: object | null | undefined): StandingAnswerVerdict;

package/dist/askSurvivesStandingAnswer.js

@@ -0,0 +1,40 @@
+import { CORE_MODE_ARBITRATION } from './generated/engineFactTables.js';
+export const MODE_ARBITRATION = CORE_MODE_ARBITRATION;
+const MUST_ASK_MANDATED = Object.freeze({ kind: 'must_ask', by: 'mandated' });
+const MAY_ANSWER = Object.freeze({ kind: 'may_answer' });
+const UNKNOWN = Object.freeze({ kind: 'unknown' });
+export function askSurvivesStandingAnswer(card) {
+    try {
+        if (card === null || card === undefined || typeof card !== 'object')
+            return UNKNOWN;
+        if (Object.hasOwn(card, 'mandated') && card.mandated === true)
+            return MUST_ASK_MANDATED;
+        const classes = Object.hasOwn(card, 'classes') ? card.classes : undefined;
+        if (!Array.isArray(classes))
+            return UNKNOWN;
+        const length = classes.length;
+        if (typeof length !== 'number' || !Number.isSafeInteger(length) || length <= 0)
+            return UNKNOWN;
+        const names = [];
+        for (let i = 0; i < length; i += 1) {
+            if (!Object.hasOwn(classes, i))
+                return UNKNOWN;
+            const c = classes[i];
+            if (typeof c !== 'string')
+                return UNKNOWN;
+            names.push(c);
+        }
+        if (classes.length !== length)
+            return UNKNOWN;
+        for (const name of names) {
+            if (!Object.hasOwn(MODE_ARBITRATION, name))
+                return UNKNOWN;
+            if (MODE_ARBITRATION[name]?.ruleMayClear !== true)
+                return Object.freeze({ kind: 'must_ask', by: name });
+        }
+        return MAY_ANSWER;
+    }
+    catch {
+        return UNKNOWN;
+    }
+}

package/dist/attachmentSeatCapability.d.ts

@@ -0,0 +1,11 @@
+export type AttachmentSeatReading = {
+    readonly kind: 'unobserved';
+} | {
+    readonly kind: 'not_reported';
+};
+export declare function noteEngineCapsForAttachmentSeat(baseUrl: string, caps: unknown, opts?: {
+    generation?: number;
+}): void;
+export declare function observedAttachmentSeat(baseUrl?: string | undefined): AttachmentSeatReading;
+export declare function forgetAttachmentSeatReading(baseUrl: string | undefined): void;
+export declare function __resetAttachmentSeatReadingsForTests(): void;

package/dist/attachmentSeatCapability.js

@@ -0,0 +1,27 @@
+import { engineWireTarget } from './engineWireTarget.js';
+import { createEngineCapReader } from './engineCapReader.js';
+function projectAttachmentSeat(caps) {
+    if (caps === null || typeof caps !== 'object' || Array.isArray(caps))
+        return undefined;
+    const p = Object.getPrototypeOf(caps);
+    if (p !== Object.prototype && p !== null)
+        return undefined;
+    return { kind: 'not_reported' };
+}
+const reader = createEngineCapReader({
+    name: 'attachmentSeat',
+    project: projectAttachmentSeat,
+    makeUnobserved: () => ({ kind: 'unobserved' }),
+});
+export function noteEngineCapsForAttachmentSeat(baseUrl, caps, opts) {
+    reader.note(baseUrl, caps, opts);
+}
+export function observedAttachmentSeat(baseUrl = engineWireTarget()?.baseUrl) {
+    return reader.observed(baseUrl);
+}
+export function forgetAttachmentSeatReading(baseUrl) {
+    reader.forget(baseUrl);
+}
+export function __resetAttachmentSeatReadingsForTests() {
+    reader.__resetForTests();
+}

package/dist/attachmentsWireCaps.d.ts

@@ -28,3 +28,12 @@ export declare class AttachmentsSpecRefused extends TypeError {
     });
 }
 export declare function attachmentsForRequest(env?: EnvLike): AttachmentsSpec | undefined;
+export type AttachmentsSubmitVerdict = {
+    readonly ok: true;
+    readonly attachments: AttachmentsSpec;
+} | {
+    readonly ok: false;
+    readonly sentence: string;
+    readonly refusedKey: string | undefined;
+};
+export declare function attachmentsSubmitVerdict(env?: EnvLike): AttachmentsSubmitVerdict;

package/dist/attachmentsWireCaps.js

@@ -1,6 +1,6 @@
 import { hostEnv } from './hostEnv.js';
 import { envFlagOff } from './envFlag.js';
-import { retiredAttachmentsKeyWhy } from './taskRequestWords.js';
+import { retiredAttachmentsKeyOf } from './taskRequestWords.js';
 export const ATTACHMENTS_ENV = 'SEMA_ATTACHMENTS';
 export const ATTACHMENTS_SPEC_KEYS = Object.freeze([
     'todoReminder',
@@ -48,25 +48,27 @@ function refuse(token, why) {
     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 token of tokens) {
-        const named = retiredAttachmentsKeyWhy(token);
+    for (const [i, token] of tokens.entries()) {
+        const named = retiredAttachmentsKeyOf(token);
         if (named !== undefined)
-            refuse(token, named);
+            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;
@@ -79,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;
@@ -91,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;