@sema-agent/client-core 0.91.0 → 0.93.0

package/dist/compensations.js

@@ -2,12 +2,12 @@ import { CHROME_ARMS } from './seam.js';
 export const MIGRATED_COMPENSATIONS = [
     {
         id: 'T32',
-        what: 'bindTaskCard —— 把引擎子代行绑到它的委派工具卡上(显式父 / FIFO 猜父 / 含糊即 unbound)',
+        what: 'bindTaskCard —— 子代行按 typed 父键绑到委派工具卡上(点名的卡不合格 / 父键缺席即 unbound)',
         disposition: 'in-library',
         libraryHalf: 'adapt.ts bindTaskCard()',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'RL-31',
+        retireOn: null,
     },
     {
         id: 'T34',
@@ -25,7 +25,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts fireSubagentStart()(类型恒记 + 一生一次去重 + if-started 门)',
         chromeArm: 'subagent_lifecycle',
         hostHalf: '真执行用户 hook 进程(浏览器宿主根本不能执行 ⇒ 这一半必须留端)',
-        retireOn: 'RL-32',
+        retireOn: null,
     },
     {
         id: 'T36',
@@ -34,7 +34,7 @@ export const MIGRATED_COMPENSATIONS = [
         libraryHalf: 'adapt.ts settlePanelTasks 的四个调用点(tool_end 关卡 / result / turn 末 / abort)',
         chromeArm: 'inline_task_stats',
         hostHalf: null,
-        retireOn: 'RL-33',
+        retireOn: null,
     },
     {
         id: 'T44',
@@ -47,12 +47,12 @@ export const MIGRATED_COMPENSATIONS = [
     },
     {
         id: 'T47',
-        what: 'workflow lane 三级判据门 —— workflow 子代的 tick 绝不进前台 subagent lane',
+        what: 'workflow lane 判据门(帧带 workflowRunId)—— workflow 子代的 tick 绝不进前台 subagent lane',
         disposition: 'in-library',
-        libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId / wa-id / workflow-card-parent 三级门',
+        libraryHalf: 'adapt.ts task_progress 臂的 workflowRunId 门',
         chromeArm: null,
         hostHalf: null,
-        retireOn: 'RL-34',
+        retireOn: null,
     },
     {
         id: 'T48',

package/dist/controlRouter.d.ts

@@ -1,13 +1,11 @@
-import type { TaskRequest, RunReceipt, CancelAck, Scenario } from '@sema-agent/sdk';
+import type { TaskRequest, RunReceipt, CancelAck, Scenario, SteerPriority } from '@sema-agent/sdk';
+import { type SteerPriorityReading } from './steerPriorityCapability.js';
 export interface RunsResourceLike {
     create(req: TaskRequest, opts?: {
         idempotencyKey?: string | null;
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
-    steer(taskId: string, steer: {
-        text: string;
-        mode?: 'all' | 'one-at-a-time';
-    }, opts?: {
+    steer(taskId: string, steer: SteerBodyInput, opts?: {
         signal?: AbortSignal;
     }): Promise<unknown>;
     cancel(taskId: string, opts?: {
@@ -17,7 +15,7 @@ export interface RunsResourceLike {
 export interface ControlClientLike {
     runs: RunsResourceLike;
 }
-export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'ledger_unavailable' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found';
+export type ControlSafetyCode = 'not_running' | 'invalid_content' | 'queue_full' | 'duplicate_input_id' | 'ambiguous_target' | 'still_running' | 'blocked_by_hook' | 'ledger_unavailable' | 'steering_other' | 'cancel_lost_race' | 'cancel_run_not_running' | 'not_found' | 'priority_not_applied' | 'steer_input_invalid';
 export declare class ControlSafetyError extends Error {
     readonly code: ControlSafetyCode;
     readonly cause?: unknown | undefined;
@@ -28,11 +26,10 @@ export declare class ControlSafetyError extends Error {
         readonly status?: number;
     });
 }
-export type QueuePriority = 'now' | 'next' | 'later';
-export interface QueuedCommand {
-    id: string;
-    text: string;
-    priority: QueuePriority;
+export interface ControlRouterSteerOptions {
+    signal?: AbortSignal;
+    priority?: SteerPriority;
+    steerPriority?: SteerPriorityReading;
 }
 export interface ControlRouterOptions {
     sessionId?: string;
@@ -47,8 +44,6 @@ export declare class ControlRouter {
     private readonly jobId;
     private readonly scenario;
     private readonly systemPrompt;
-    private readonly queue;
-    private seq;
     constructor(client: ControlClientLike, opts?: ControlRouterOptions);
     activeTaskId(): string | null;
     activeSessionId(): string | undefined;
@@ -56,19 +51,10 @@ export declare class ControlRouter {
         signal?: AbortSignal;
     }): Promise<RunReceipt>;
     private buildTaskRequest;
-    steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: {
-        signal?: AbortSignal;
-    }): Promise<unknown>;
+    steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: ControlRouterSteerOptions): Promise<unknown>;
     cancel(opts?: {
         signal?: AbortSignal;
     }): Promise<CancelAck>;
-    enqueue(text: string, priority?: QueuePriority): QueuedCommand;
-    dequeue(id: string): boolean;
-    pending(): readonly QueuedCommand[];
-    drainNext(opts?: {
-        signal?: AbortSignal;
-    }): Promise<RunReceipt | null>;
-    private nextId;
 }
 export interface ErrCodes {
     code?: string | undefined;
@@ -80,7 +66,21 @@ export declare function steeringStatusIs4xx(e: object): boolean;
 export interface SteerRefusalAdvice {
     safety: ControlSafetyCode;
     advice: string;
+    happened: string;
+    nextStep: string;
 }
 export type SteeringRefusedBeforeEngine = SteerRefusalAdvice;
 export declare function steeringRefusedBeforeEngine(e: object): SteeringRefusedBeforeEngine | undefined;
 export declare function steerRefusalAdviceOf(e: object): SteerRefusalAdvice | undefined;
+export interface SteerBody {
+    readonly text: string;
+    readonly mode?: 'all' | 'one-at-a-time';
+    readonly priority?: 'now' | 'later';
+}
+export interface SteerBodyInput {
+    text: string;
+    mode?: 'all' | 'one-at-a-time';
+    priority?: SteerPriority;
+}
+export declare const UNOBSERVED_STEER_PRIORITY: SteerPriorityReading;
+export declare function steerBodyOf(input: SteerBodyInput, reading: SteerPriorityReading): SteerBody;

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;
@@ -17,6 +18,8 @@ export declare function decideAcceptedNotResolved(receipt: DecideReceiptView | u
 export interface DecideRefusalDetail {
     code: string;
     runId?: string;
+    runIds?: readonly string[];
+    readableHolderRunId?: string;
     detail: string;
     resendable: boolean;
 }
@@ -27,3 +30,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_PARK_FORKED, DECIDE_WORKFLOW_PARKS_UNREADABLE, DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED, isDecideParkMovedCode, } from './engineErrorCodes.js';
 import { effectiveWireErrorCode } from './wireErrorTriage.js';
-import { readErrorString } from './wireFailureShape.js';
+import { readErrorString, readErrorStrictStringList } 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;
@@ -56,25 +57,50 @@ export function decideAcceptedNotResolved(receipt) {
 const DECIDE_REFUSAL_SENTENCES = Object.freeze({
     [DECIDE_WORKFLOW_HOST_UNKNOWN]: 'no session is attached to this run to receive the decision, so re-sending the same decision cannot help; the approval is still pending and can be decided again once the run is reachable',
     [DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED]: 'this run cannot remember the decision for the session; re-send the same decision without the remember option — nothing was consumed by this refusal',
+    [DECIDE_WORKFLOW_PARKS_UNREADABLE]: "this approval cannot be matched to the run that is waiting on it, because that run's record was written by an earlier engine version or is damaged; nothing was delivered and the approval is still pending — try resuming that run, and if this approval is still refused afterwards, the record has to be repaired by whoever operates this deployment before it can be decided",
+    [DECIDE_WORKFLOW_PARK_FORKED]: 'the same run was resumed more than once and each resumed copy is waiting on this same approval, so there is no single run to hand the decision to; nothing was delivered and the approval is still pending — resume one of those runs, and if it reaches this approval again, decide here',
 });
 const DECIDE_RESENDABLE = Object.freeze({
     [DECIDE_WORKFLOW_HOST_UNKNOWN]: false,
     [DECIDE_WORKFLOW_REMEMBER_UNSUPPORTED]: true,
+    [DECIDE_WORKFLOW_PARKS_UNREADABLE]: false,
+    [DECIDE_WORKFLOW_PARK_FORKED]: false,
 });
+function readTopOwn(e, key) {
+    try {
+        return e !== null && e !== undefined ? e[key] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readForkedRunIds(e) {
+    const list = readErrorStrictStringList(e, 'runIds');
+    if (list === undefined || list.length === 0)
+        return undefined;
+    for (const id of list)
+        if (id.length === 0)
+            return undefined;
+    return Object.freeze(list.slice());
+}
 export function decideRefusalFromError(e) {
-    const code = typeof e?.errorCode === 'string'
-        ? (e.errorCode)
-        : undefined;
+    const rawCode = readTopOwn(e, 'errorCode');
+    const code = typeof rawCode === 'string' ? rawCode : undefined;
     if (code === undefined || !DECIDE_WORKFLOW_LANE_CODES.includes(code))
         return null;
-    const rawRunId = e.runId;
+    const rawRunId = code === DECIDE_WORKFLOW_PARK_FORKED ? undefined : readTopOwn(e, 'runId');
     const runId = typeof rawRunId === 'string' && rawRunId.length > 0 ? rawRunId : undefined;
+    const runIds = code === DECIDE_WORKFLOW_PARK_FORKED ? readForkedRunIds(e) : undefined;
+    const holderRaw = code === DECIDE_WORKFLOW_PARKS_UNREADABLE ? readErrorString(e, 'readableHolderRunId') : undefined;
+    const readableHolderRunId = holderRaw !== undefined && holderRaw.length > 0 ? holderRaw : undefined;
     const detail = Object.hasOwn(DECIDE_REFUSAL_SENTENCES, code)
         ? DECIDE_REFUSAL_SENTENCES[code]
         : undefined;
     return {
         code,
         ...(runId !== undefined ? { runId } : {}),
+        ...(runIds !== undefined ? { runIds } : {}),
+        ...(readableHolderRunId !== undefined ? { readableHolderRunId } : {}),
         detail: detail ?? 'the engine refused this decision; the approval is still pending and can be decided again',
         resendable: Object.hasOwn(DECIDE_RESENDABLE, code) ? DECIDE_RESENDABLE[code] === true : false,
     };
@@ -87,9 +113,9 @@ export function decideParkMovedFromError(e) {
     return { code, ...(taskId !== undefined && taskId.length > 0 ? { taskId } : {}) };
 }
 const DECIDE_PARK_MOVED_WHAT = Object.freeze({
-    [DECIDE_NOT_PARKED]: 'This approval was no longer waiting when the decision arrived (the agent was stopped, the approval was decided elsewhere, or the session it belongs to was deleted)',
-    [DECIDE_GATE_MOVED]: 'This approval moved while the decision was on its way (it was parked again, or settled elsewhere)',
-    [DECIDE_CLAIM_LOST]: 'Another decision on this approval got there first, or an earlier attempt is still holding it until the engine clears that hold on its own',
+    [DECIDE_NOT_PARKED]: 'This approval was no longer waiting when the decision arrived (the agent was stopped, the approval was decided elsewhere, or the session it belongs to was deleted; this client cannot tell which)',
+    [DECIDE_GATE_MOVED]: 'This approval moved while the decision was on its way (it was parked again, or settled elsewhere; this client cannot tell which)',
+    [DECIDE_CLAIM_LOST]: 'Another decision on this approval got there first, or an earlier attempt is still holding it until the engine clears that hold on its own; this client cannot tell which',
 });
 export function decideParkMovedContent(detail) {
     let code;
@@ -106,3 +132,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/detachWire.d.ts

@@ -2,27 +2,15 @@ import { type EnvLike } from './hostEnv.js';
 import { type WireAuthTokenSource } from './engineWireSdk.js';
 export declare const DETACH_HEADER = "x-detach-on-disconnect";
 export declare const HEADLESS_DETACH_ENV = "SEMA_HEADLESS_DETACH";
-export declare const DETACH_WIRE_MIN_ENGINE: readonly [number, number, number];
-export declare const versionSupportsDetach: (v: string | undefined) => boolean;
 export declare function headlessDetachDisabledByEnv(env?: EnvLike): boolean;
-export type EngineDetachSupport = 'supported' | 'unsupported' | 'unknown';
-export declare function probeEngineDetachSupport(baseUrl: string, opts?: {
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-}): Promise<EngineDetachSupport>;
-export declare function detachSupportDisclosure(support: EngineDetachSupport): string | undefined;
-export declare function engineSupportsDetach(baseUrl: string, opts?: {
-    fetchImpl?: typeof fetch;
-    timeoutMs?: number;
-}): Promise<boolean>;
 export type DetachResolution = {
     on: true;
     reason: 'default-on';
 } | {
     on: false;
-    reason: 'env-off' | 'old-engine';
+    reason: 'env-off';
 };
-export declare function resolveHeadlessDetach(baseUrl: string, env?: EnvLike, opts?: {
+export declare function resolveHeadlessDetach(_baseUrl: string, env?: EnvLike, _opts?: {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 }): Promise<DetachResolution>;