@sema-agent/core 7.43.0 → 7.44.0

package/dist/core/memory-engine/engine.js

@@ -18,7 +18,7 @@ import { landedUndecided, layerDigest, layerObservationLookup, readOnlyLayerCand
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
 import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, landingPathOf, storeTargetEscape, TARGET_OUTSIDE_STORE, adoptRootScopeLayout, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, indexLineIsStale, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, adoptRootScopeLayout, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
 import { createSessionIncarnationSeat, recalledForAnyIdentity, recalledForIdentity, rememberForIdentity } from "./session-incarnation.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 import { writableRootOf } from "./types.js";
@@ -1416,11 +1416,8 @@ export class MemoryEngine {
         ensureDirExists(this.memoryDir);
         const physicalRoot = landingPathOf(this.memoryDir);
         this.mountedRoot ??= physicalRoot;
-        if (physicalRoot !== this.mountedRoot) {
-            const e = new Error(`${TARGET_OUTSIDE_STORE}: the memory dir ${this.memoryDir} now resolves to ${physicalRoot}, not ${this.mountedRoot} where this engine first mounted it — refused; open a new engine on the directory you mean`);
-            e.code = TARGET_OUTSIDE_STORE;
-            throw e;
-        }
+        if (physicalRoot !== this.mountedRoot)
+            throw storeRootMovedRefusal("engine", this.memoryDir);
         ensureDirExists(this.controlDir);
         await this.adoptLayoutBeforeMount(writeScope);
         const restricted = opts?.adoptionRestricted === true;
@@ -2216,7 +2213,7 @@ export class MemoryEngine {
             if (content === undefined)
                 continue;
             try {
-                this.refuseOutsideStore(handle.memoryDir, m.path, "restoring");
+                this.refuseOutsideStore(handle.memoryDir, m.path, "restoring a memory file");
                 mkdirSync(dirname(m.path), { recursive: true });
                 writeFileNoFollow(m.path, content);
                 report.restored.push(m.relPath);
@@ -4947,15 +4944,11 @@ export class MemoryEngine {
         };
     }
     refuseOutsideStore(root, path, act) {
-        const escape = storeTargetEscape(root, path);
-        if (escape === undefined)
-            return;
-        const e = new Error(`${TARGET_OUTSIDE_STORE}: ${act} ${path} was refused — ${escape}; not performed`);
-        e.code = TARGET_OUTSIDE_STORE;
-        throw e;
+        if (landsOutsideStore(root, path))
+            throw storeActRefusal(act, path);
     }
     writeIfChanged(target, text, root) {
-        this.refuseOutsideStore(root, target, "the projection write of");
+        this.refuseOutsideStore(root, target, "the projection write");
         const current = readNoFollowSafe(target);
         if (current === text)
             return;

package/dist/core/memory-engine/file-backend.d.ts

@@ -682,9 +682,9 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  let a transient EIO run the unlocked recovery (and its staged sweep) over a live transaction. */
     private txnInFlight;
     /**
-     * The act gate for store paths ({@link storeTargetEscape}) over `ops`' writes and deletes — shadow
+     * The act gate for store paths ({@link landsOutsideStore}) over `ops`' writes and deletes — shadow
      * ops name control-plane files, not store paths. Refuses with `memory.target_outside_store` at the
-     * first op that would land outside the store, naming the op and where it resolves. Runs over a
+     * first op that would land outside the store, naming the op (its path on `detail.path`). Runs over a
      * whole batch before its commit marker (no journal is written; a caller that staged files removes
      * them) and per op at the act itself; past the marker a refusal keeps the journal, which replays
      * once the path resolves inside the store again.

package/dist/core/memory-engine/file-backend.js

@@ -8,7 +8,7 @@ import { ambiguousOriginRepresentation, committedDistilledOf, committedOriginOf,
 import { convertV1SidecarKeys } from "./delegation-settlement.js";
 import { layerObservationLookup, observedDivergenceNotice } from "./layer-observations.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./entry-scan.js";
-import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, landingPathOf, storeTargetEscape, TARGET_OUTSIDE_STORE, writeAllSync, } from "./layout.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, landingPathOf, landsOutsideStore, storeActRefusal, storeRootMovedRefusal, writeAllSync, } from "./layout.js";
 import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 import { thrownText } from "../thrown-value.js";
@@ -1404,7 +1404,7 @@ export class FileMemoryEngineBackend {
                 }
             }
             this.assertTxnLockOwnership(fenceToken);
-            const replayAt = `the journal replay (journal kept at ${jp})`;
+            const replayAt = "the journal replay (journal kept)";
             this.refuseEscapingTargets(journal.ops, replayAt);
             for (const op of journal.ops) {
                 this.refuseEscapingTargets([op], replayAt);
@@ -1470,10 +1470,8 @@ export class FileMemoryEngineBackend {
             if (op.kind !== "write" && op.kind !== "delete")
                 continue;
             for (const path of op.staged === undefined ? [op.target] : [op.target, op.staged]) {
-                const escape = storeTargetEscape(this.physicalRoot, path);
-                if (escape === undefined)
-                    continue;
-                throw erasureCodedError(`${TARGET_OUTSIDE_STORE}: ${at} refused a ${op.kind} of ${op.target}${path === op.target ? "" : ` (its staged file ${path})`} — ${escape}; not performed`, TARGET_OUTSIDE_STORE);
+                if (landsOutsideStore(this.physicalRoot, path))
+                    throw storeActRefusal(`${path === op.target ? "a" : "the staged file of a"} ${op.kind} at ${at}`, path);
             }
         }
     }
@@ -1481,7 +1479,7 @@ export class FileMemoryEngineBackend {
         const now = landingPathOf(this.directoryRoot);
         if (now === this.physicalRoot)
             return;
-        throw erasureCodedError(`${TARGET_OUTSIDE_STORE}: the store root ${this.directoryRoot} now resolves to ${now}, not ${this.physicalRoot} where this backend opened it — refused; open a new backend on the directory you mean`, TARGET_OUTSIDE_STORE);
+        throw storeRootMovedRefusal("backend", this.directoryRoot);
     }
     sweepStagedFiles() {
         const walk = (d, depth) => {

package/dist/core/memory-engine/layout.d.ts

@@ -259,8 +259,41 @@ export declare function adoptRootScopeLayout(rootPath: string, controlDir: strin
 export declare const canonicalize: typeof physicalPathOfExisting;
 /** True iff `child` (canonicalized) is `root` or inside it. */
 export declare function isContainedIn(root: string, child: string): boolean;
-/** The code an act on a store path is refused with when it would land outside the store ({@link storeTargetEscape}). */
+/** The code an act on a store path is refused with when it would land outside the store ({@link landsOutsideStore}). */
 export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+/** The code a scope home that is not a real directory is refused with ({@link assertHomePhysicalForm}). */
+export declare const SCOPE_HOME_NOT_DIRECTORY = "memory.scope_home_not_directory";
+/** What a scope home can be besides a real directory (an `lstat` verdict). */
+export declare const SCOPE_HOME_FORMS: readonly ["symlink", "file", "other"];
+export type ScopeHomeForm = (typeof SCOPE_HOME_FORMS)[number];
+/** How a refusal's sentence names each form. */
+declare const SCOPE_HOME_FORM_PHRASE: {
+    readonly symlink: "a symbolic link";
+    readonly file: "a regular file";
+    readonly other: "a special file";
+};
+export type HomeFormPhraseCoversEveryForm = AssertAllKeysHandled<Exclude<ScopeHomeForm, keyof typeof SCOPE_HOME_FORM_PHRASE>>;
+/** What a store-form refusal carries beside its sentence. The ONE host path lives here and never in the
+ *  sentence; `form` is present on {@link SCOPE_HOME_NOT_DIRECTORY} only. */
+export type StoreFormRefusalDetail = {
+    readonly path: string;
+    readonly form?: ScopeHomeForm;
+};
+/** A refusal the store's physical form earns: a plain `Error` (never the control-plane-damage class —
+ *  the engine's own account is intact, the layout it was handed is not the layout it needs) carrying a
+ *  `code` and a `detail`. */
+export type StoreFormRefusal = Error & {
+    code: typeof TARGET_OUTSIDE_STORE | typeof SCOPE_HOME_NOT_DIRECTORY;
+    detail: StoreFormRefusalDetail;
+};
+/** Seat 1 — an act the store's physical form refuses: `act` names what was refused (no path), `path` is the
+ *  target whose directory resolves outside the store ({@link landsOutsideStore}). */
+export declare function storeActRefusal(act: string, path: string): StoreFormRefusal;
+/** Seat 2 — the store root now resolves to another directory than the one the `holder` first opened; `path` is
+ *  the root's spelling. */
+export declare function storeRootMovedRefusal(holder: "backend" | "engine", path: string): StoreFormRefusal;
+/** Seat 3 — a scope home that is not a real directory. */
+export declare function scopeHomeRefusal(form: ScopeHomeForm, path: string): StoreFormRefusal;
 /** Where an act at `p` lands: the physical path of its normalized spelling (the spelling a child path
  *  joined under it carries), a MISSING tail rejoined under the deepest existing directory (what the act
  *  creates). Any other resolution fault (EACCES, ELOOP, ENOTDIR) is THROWN as itself: an act that
@@ -268,8 +301,8 @@ export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
  *  (a link whose own mode refuses `realpath` is still followed by `unlink` and `rename`). */
 export declare function landingPathOf(p: string): string;
 /**
- * Where a write, rename or delete at `target` would physically LAND, judged against the store's
- * `physicalRoot`: `undefined` = inside, otherwise the reason. The target's directory, resolved through
+ * Whether a write, rename or delete at `target` would physically LAND outside the store, judged against the
+ * store's `physicalRoot` (`true` = outside; the refusal is {@link storeActRefusal}). The target's directory, resolved through
  * every link on its existing prefix (a missing tail is what the act creates, under the deepest existing
  * directory), must be the root or inside it. `physicalRoot` is the root's physical form as the store
  * was opened and is not re-resolved here: a store mounted through a link is judged by what the link
@@ -280,7 +313,7 @@ export declare function landingPathOf(p: string): string;
  * keeps the spelling while the act follows the link out. A directory that cannot be resolved throws its
  * fault ({@link landingPathOf}).
  */
-export declare function storeTargetEscape(physicalRoot: string, target: string): string | undefined;
+export declare function landsOutsideStore(physicalRoot: string, target: string): boolean;
 /** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
 export declare function ensureDirExists(dir: string): void;
 /** The one remedy every surfaced permission refusal carries — `undefined` unless `err` is a write

package/dist/core/memory-engine/layout.js

@@ -472,11 +472,18 @@ function assertHomePhysicalForm(home) {
         return "absent";
     if (st.isDirectory())
         return "dir";
-    throw new ControlPlaneCorruptError(`scope home ${home} is ${st.isSymbolicLink() ? "a symbolic link" : "not a directory"} — a scope home must be a real directory (fail-closed)`);
+    throw scopeHomeRefusal(st.isSymbolicLink() ? "symlink" : st.isFile() ? "file" : "other", home);
 }
 function ensureScopeHome(home) {
-    if (assertHomePhysicalForm(home) === "absent")
-        mkdirSync(home, { recursive: true });
+    if (assertHomePhysicalForm(home) === "absent") {
+        try {
+            mkdirSync(home, { recursive: true });
+        }
+        catch (err) {
+            assertHomePhysicalForm(home);
+            throw err;
+        }
+    }
     assertHomePhysicalForm(home);
 }
 export function registerScope(memoryDir, controlDir, scope, opts) {
@@ -725,6 +732,28 @@ export function isContainedIn(root, child) {
     return c === r || c.startsWith(`${r}${sep}`);
 }
 export const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+export const SCOPE_HOME_NOT_DIRECTORY = "memory.scope_home_not_directory";
+export const SCOPE_HOME_FORMS = Object.freeze(["symlink", "file", "other"]);
+const SCOPE_HOME_FORM_PHRASE = {
+    symlink: "a symbolic link",
+    file: "a regular file",
+    other: "a special file",
+};
+function storeFormRefusal(code, sentence, detail) {
+    const e = new Error(`${code}: ${sentence}`);
+    e.code = code;
+    e.detail = detail;
+    return e;
+}
+export function storeActRefusal(act, path) {
+    return storeFormRefusal(TARGET_OUTSIDE_STORE, `${act} was refused — its directory resolves outside the store root; not performed`, { path });
+}
+export function storeRootMovedRefusal(holder, path) {
+    return storeFormRefusal(TARGET_OUTSIDE_STORE, `the ${holder === "backend" ? "store root" : "memory dir"} now resolves to a different directory than the one this ${holder} ${holder === "backend" ? "opened" : "first mounted"} — refused; open a new ${holder} on the directory you mean`, { path });
+}
+export function scopeHomeRefusal(form, path) {
+    return storeFormRefusal(SCOPE_HOME_NOT_DIRECTORY, `a scope home must be a real directory, but this one is ${SCOPE_HOME_FORM_PHRASE[form]} — refused (fail-closed); put the real directory back`, { path, form });
+}
 export function landingPathOf(p) {
     const normalized = resolve(p);
     try {
@@ -736,9 +765,9 @@ export function landingPathOf(p) {
         return canonicalize(normalized);
     }
 }
-export function storeTargetEscape(physicalRoot, target) {
+export function landsOutsideStore(physicalRoot, target) {
     const dir = landingPathOf(dirname(target));
-    return dir === physicalRoot || dir.startsWith(`${physicalRoot}${sep}`) ? undefined : `its directory resolves to ${dir}, outside the store root ${physicalRoot}`;
+    return dir !== physicalRoot && !dir.startsWith(`${physicalRoot}${sep}`);
 }
 export function ensureDirExists(dir) {
     if (!existsSync(dir))

package/dist/core/runner/contracts.d.ts

@@ -33,7 +33,7 @@ import type { AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { AutoModeDecider, AutoModeDenialTracker, DenialLimitFallbackFace } from "../auto-mode.js";
 import type { SettlementKind } from "../gate-outcome.js";
 import type { CacheBreakDetector, ToolFingerprintInput } from "../cache-break-detector.js";
-import type { ActorAssertion, Checkpoint, CheckpointState, CheckpointStore, CheckpointToken, PendingSteerEntry, PlatformLimitReason, ReopenReason, ResourceLedger, ResourceLimitReason, ResumeOutcome, SerializedCheckpointState } from "../checkpoint-store.js";
+import type { Checkpoint, CheckpointState, CheckpointStore, CheckpointToken, PendingSteerEntry, PlatformLimitReason, ReopenReason, ResourceLedger, ResourceLimitReason, ResumeOutcome, SerializedCheckpointState } from "../checkpoint-store.js";
 import type { ExecutionOutcomeRecordWord } from "../checkpoint-execution-record.js";
 import type { ClearedProjectionLedger, MicroCompactMachine, OccurrenceIndex } from "../context-edit.js";
 import type { HookInvocationIdentity, Hooks, OrgGateVerdict, PermissionDeniedPayload, PostToolBatchCall, PostToolBatchResult, ToolGateInput } from "../hooks.js";
@@ -2494,21 +2494,6 @@ export interface RunState {
         attachmentsInjected: number;
     };
 }
-/** One accepted live steer's REPLAY identity, the twin of the parked
- *  queue's `samePendingSteerPayload`. `payload` is the exact string handed to the harness, so the text,
- *  the speaker envelope and the trust framing all fold into it; `trusted` is kept SEPARATELY from those
- *  framed bytes so a text that spells its own `<system-reminder>` wrapper can never read as the trusted
- *  arm's byte-equal twin. `actor` carries the attribution the ledger frame reports. */
-export interface AcceptedSteerInput {
-    payload: string;
-    trusted: boolean;
-    /** The NORMALIZED priority the call delivered under (absent input ⇒ "next"),
-     *  the replay identity's sixth axis: same id + same text at a DIFFERENT tier is not a replay —
-     *  a `next` input re-sent as `now` answering "idempotent success" without the interrupt would be
-     *  a disposition lie, so it refuses `duplicate_input_id` like any other identity mismatch. */
-    priority: SystemInjectionPriority;
-    actor?: ActorAssertion;
-}
 /**
  * Config re-supplied to {@link Runner.resume}. A suspended task's tools / model / policy /
  * hooks cannot be reconstructed from a checkpoint token (the session stores neither tool implementations

package/dist/core/runner/runtask.js

@@ -40,6 +40,7 @@ import { resumeClaim } from "./resume-claim.js";
 import { streamSettleBackstop } from "./stream-settle-backstop.js";
 import { streamReap } from "./stream-reap.js";
 import { streamSteerVerb } from "./stream-steer-verb.js";
+import { steeringError } from "./steer-admission.js";
 import { streamLifecycleVerbs } from "./stream-lifecycle-verbs.js";
 import { streamHaltVerbs } from "./stream-halt-verbs.js";
 import { streamModeVerb } from "./stream-mode-verb.js";
@@ -411,11 +412,6 @@ export class Runner {
             locallyClaimedTokens: this.locallyClaimedTokens, parentConstraintRegistry: this.parentConstraintRegistry, suspendedEnvReaps: this.suspendedEnvReaps,
         }).onRunRejected);
         void settled.then(() => acceptedSteerInputs.clear(), () => acceptedSteerInputs.clear());
-        const steeringError = (msg, code = "steering.not_running") => {
-            const e = new Error(`cannot steer: ${msg}`);
-            e.code = code;
-            return e;
-        };
         const { reapSuspended } = streamReap({
             live, runner: this.depsSeat,
             locallyClaimedTokens: this.locallyClaimedTokens, parentConstraintRegistry: this.parentConstraintRegistry, suspendedEnvReaps: this.suspendedEnvReaps,

package/dist/core/runner/steer-admission.d.ts

@@ -1,14 +1,15 @@
 /**
- * Admission bookkeeping for HUMAN INPUTS accepted mid-run: the per-leg ordinal an
- * accepted input is stamped with, and the field-for-field "is this repeat the same instruction" test the
- * live steer verb applies under an already-used `inputId`. Two accepting arms share both — the stream's
- * `steer` verb and the run body — which is why the ordinal is keyed on the leg's harness in a module-level
- * WeakMap rather than held by either arm: one counter per leg, one ascending sequence across both.
+ * Admission bookkeeping for HUMAN INPUTS accepted mid-run: the per-leg ordinal an accepted input is stamped
+ * with, and the acceptance frame's once-only seat. Two accepting arms share the ordinal — the stream's `steer`
+ * verb and the run body — which is why it is keyed on the leg's harness in a module-level WeakMap rather than
+ * held by either arm: one counter per leg, one ascending sequence across both. Also the stream verbs' typed
+ * refusal. (Whether a repeat under a used `inputId` is the same instruction is steer-replay.ts's one judgement,
+ * shared with the parked queue.)
  *
  * Run-loop machinery (layer 1), not a driven lane: nothing here takes an Input or hands back a Result, and
  * nothing here reads host state. Named without the `run-` family prefix for that reason.
  */
-import type { AcceptedSteerInput } from "./contracts.js";
+import type { SteerReplayRefusalDetail } from "../steer-replay.js";
 export declare function nextHumanInputSeq(key: object): number;
 /** The identity keys a published `queued` frame carried beyond its own `eventId` (`parentToolCallId`, `sourceTaskId`): one fact, stated
  *  once by the frame's publisher and handed to whoever mints that input's other frames, so two frames of one input are never stamped
@@ -19,8 +20,6 @@ export type AcceptanceIdentity = {
 };
 export declare function armAcceptance(record: object, publish: () => AcceptanceIdentity): void;
 export declare function announceAcceptance(record: object): AcceptanceIdentity | undefined;
-/** Is a repeat under an already-accepted `inputId` the SAME
- *  instruction (an idempotent retry) or a different one wearing a used key? Compared field for field,
- *  exactly like the parked leg's replay check: the key alone is never evidence of a replay, and two
- *  callers colliding on one id must not silently lose the second instruction. */
-export declare function sameAcceptedSteerInput(a: AcceptedSteerInput, b: AcceptedSteerInput): boolean;
+/** The stream verbs' typed refusal: `cannot steer: <msg>`, `code` (`steering.not_running` by default), and the
+ *  refusal's `detail` when the code carries one (`steering.duplicate_input_id` always does). */
+export declare function steeringError(msg: string, code?: string, detail?: SteerReplayRefusalDetail): Error;

package/dist/core/runner/steer-admission.js

@@ -1,4 +1,3 @@
-import { steerPriorityOf } from "../task-notification.js";
 const humanInputOrdinals = new WeakMap();
 export function nextHumanInputSeq(key) {
     let box = humanInputOrdinals.get(key);
@@ -16,11 +15,10 @@ export function armAcceptance(record, publish) {
 export function announceAcceptance(record) {
     return acceptanceSeats.get(record)?.();
 }
-export function sameAcceptedSteerInput(a, b) {
-    return (a.payload === b.payload &&
-        a.trusted === b.trusted &&
-        steerPriorityOf(a) === steerPriorityOf(b) &&
-        a.actor?.id === b.actor?.id &&
-        a.actor?.hostAsserted === b.actor?.hostAsserted &&
-        a.actor?.issuer === b.actor?.issuer);
+export function steeringError(msg, code = "steering.not_running", detail) {
+    const e = new Error(`cannot steer: ${msg}`);
+    e.code = code;
+    if (detail !== undefined)
+        e.detail = detail;
+    return e;
 }

package/dist/core/runner/stream-steer-verb.d.ts

@@ -1,6 +1,7 @@
 import type { PushQueue } from "../push-queue.js";
 import { type TaskEvent, type TaskSpec, type TaskStream } from "../types.js";
-import type { AcceptedSteerInput, LiveHandle, RunInternals, RunnerDepsSeat, TaskStreamLiveSeat } from "./contracts.js";
+import type { LiveHandle, RunInternals, RunnerDepsSeat, TaskStreamLiveSeat } from "./contracts.js";
+import { type SteerReplayRecord, type SteerReplayRefusalDetail } from "../steer-replay.js";
 export interface StreamSteerVerbInput {
     /** borrowed-readonly — the task spec (the hooks seat, `principal`, `taskId`). */
     spec: TaskSpec;
@@ -9,7 +10,7 @@ export interface StreamSteerVerbInput {
     /** borrowed-mutable — the stream's event queue: the `human_input` receipt is pushed here on acceptance. */
     queue: PushQueue<TaskEvent>;
     /** borrowed-mutable — this stream's accepted-input dedup domain (the SAME Map the driver clears when the run settles). */
-    acceptedSteerInputs: Map<string, AcceptedSteerInput>;
+    acceptedSteerInputs: Map<string, SteerReplayRecord>;
     /** borrowed-readonly — the stream's live state: `resultValue` and `handle`, read at each liveness test. */
     live: TaskStreamLiveSeat;
     /** borrowed-readonly — the readiness promise (settles to the live handle, or `undefined` when the run ended first). */
@@ -18,8 +19,8 @@ export interface StreamSteerVerbInput {
     orTimeout: <T>(p: Promise<T>) => Promise<T | undefined>;
     /** borrowed-readonly — the readiness bound in ms; the birth-window poll's deadline reads it too. */
     readyTimeoutMs: number;
-    /** borrowed-readonly — the driver's typed steering refusal (`steering.not_running` by default). */
-    steeringError: (msg: string, code?: string) => Error;
+    /** borrowed-readonly — the driver's typed steering refusal (`steering.not_running` by default; `detail` rides the error). */
+    steeringError: (msg: string, code?: string, detail?: SteerReplayRefusalDetail) => Error;
     /** borrowed-readonly — the Runner's deployment deps, read LIVE (`hooks`, `onError`, `onNotice`, after awaits too). */
     runner: RunnerDepsSeat;
 }

package/dist/core/runner/stream-steer-verb.js

@@ -6,7 +6,8 @@ import { buildHumanInputEvent, frameMidTurnUserInput, projectHumanInput } from "
 import { isSystemInjectionPriority, steerPriorityOf, SYSTEM_INJECTION_PRIORITIES } from "../task-notification.js";
 import { deliverEngineNotice } from "../types.js";
 import { inlineUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
-import { announceAcceptance, armAcceptance, nextHumanInputSeq, sameAcceptedSteerInput } from "./steer-admission.js";
+import { announceAcceptance, armAcceptance, nextHumanInputSeq } from "./steer-admission.js";
+import { steerReplayRefusal } from "../steer-replay.js";
 import { asThrownError } from "../thrown-value.js";
 export function streamSteerVerb(input) {
     const { spec, internals, queue, acceptedSteerInputs, live, ready, orTimeout, readyTimeoutMs: READY_TIMEOUT_MS, steeringError, runner } = input;
@@ -43,7 +44,6 @@ export function streamSteerVerb(input) {
         };
         let payload;
         let mintsAFrame;
-        let replay;
         const publishQueued = (h) => {
             const identity = internals?.parentToolCallId !== undefined ? { parentToolCallId: internals.parentToolCallId, ...(spec.taskId !== undefined ? { sourceTaskId: spec.taskId } : {}) } : {};
             queue.push({
@@ -66,7 +66,7 @@ export function streamSteerVerb(input) {
             if (!mintsAFrame)
                 return;
             if (typeof inputId === "string")
-                acceptedSteerInputs.set(inputId, replay);
+                acceptedSteerInputs.set(inputId, parkRecord);
             announceAcceptance(parkRecord);
         };
         const deliver = async () => {
@@ -77,16 +77,14 @@ export function streamSteerVerb(input) {
                 throw steeringError("the task is not running");
             payload = trusted ? formatHookFeedback(projected, h.reminderMark) : frameMidTurnUserInput(projected);
             mintsAFrame = payload.trim().length !== 0;
-            replay = { payload, trusted, priority, ...(actor !== undefined ? { actor } : {}) };
             if (typeof inputId === "string") {
                 const prior = acceptedSteerInputs.get(inputId);
                 if (prior !== undefined) {
                     if (live.resultValue !== undefined || h.loop.ended)
                         throw steeringError("the task is no longer running");
-                    if (!sameAcceptedSteerInput(prior, replay)) {
-                        throw steeringError("a different steering instruction was already accepted under this inputId — re-issue this one with a fresh inputId " +
-                            "(an identical payload would have been an idempotent retry)", "steering.duplicate_input_id");
-                    }
+                    const refusal = steerReplayRefusal(prior, parkRecord, { seat: "accepted" });
+                    if (refusal !== undefined)
+                        throw steeringError(refusal.message, "steering.duplicate_input_id", refusal.detail);
                     return;
                 }
             }

package/dist/core/steer-replay.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Is a repeat under an already-used steer `inputId` the same instruction? ONE answer for both seats that hold a
+ * steer under its key — the parked queue (`appendPendingSteer`) and the live verb's accepted-input domain — and that
+ * one answer feeds the replay decision, the refusal's machine-readable `detail.differs` and its sentence.
+ *
+ * Both seats compare the record the CALLER sent (text, trusted, tier, actor) — never the delivered bytes: the live
+ * delivery folds `trusted` (the framing) and the actor (the speaker label) into its payload, so comparing payloads
+ * would report one changed facet as two.
+ */
+import type { ActorAssertion } from "../internal/llm.js";
+import { type SystemInjectionPriority } from "./task-notification.js";
+/** The facets a steer's replay identity is made of, in the order a refusal lists them. Closed. */
+export declare const STEER_REPLAY_FACETS: readonly ["text", "trusted", "priority", "actor"];
+export type SteerReplayFacet = (typeof STEER_REPLAY_FACETS)[number];
+/** What a seat remembers a steer by: the caller's own statement, as validated. The parked entry and the live park
+ *  record both are this shape. An absent `priority` reads as `"next"` ({@link steerPriorityOf}). */
+export interface SteerReplayRecord {
+    readonly text: string;
+    readonly trusted: boolean;
+    readonly priority?: SystemInjectionPriority;
+    readonly actor?: ActorAssertion;
+}
+/** The facets `repeat` differs from `held` in, in {@link STEER_REPLAY_FACETS} order. Empty = the idempotent replay. */
+export declare function steerReplayDiffers(held: SteerReplayRecord, repeat: SteerReplayRecord): SteerReplayFacet[];
+/** `steering.duplicate_input_id`'s machine-readable half: the facets, by name only (never the values). Always
+ *  present on that code, never empty. */
+export interface SteerReplayRefusalDetail {
+    readonly differs: readonly SteerReplayFacet[];
+}
+/** Which seat refuses: the parked queue names the key it holds; the live verb answers about the caller's own key. */
+export type SteerReplaySeat = {
+    readonly seat: "parked";
+    readonly inputId: string;
+} | {
+    readonly seat: "accepted";
+};
+/**
+ * The refusal for a repeat that is not a replay, or `undefined` for one that is. When `text` differs the repeat is
+ * another instruction and the caller is told to take a fresh key. When only the tier / trust / attribution differ it
+ * is the SAME instruction, already accepted, whose standing receipt those facets do not change — a fresh key would
+ * queue it a second time, so the sentence says so instead of advising one.
+ */
+export declare function steerReplayRefusal(held: SteerReplayRecord, repeat: SteerReplayRecord, where: SteerReplaySeat): {
+    message: string;
+    detail: SteerReplayRefusalDetail;
+} | undefined;

package/dist/core/steer-replay.js

@@ -0,0 +1,22 @@
+import { steerPriorityOf } from "./task-notification.js";
+export const STEER_REPLAY_FACETS = Object.freeze(["text", "trusted", "priority", "actor"]);
+const FACET_IS_SAME = {
+    text: (a, b) => a.text === b.text,
+    trusted: (a, b) => a.trusted === b.trusted,
+    priority: (a, b) => steerPriorityOf(a) === steerPriorityOf(b),
+    actor: (a, b) => a.actor?.id === b.actor?.id && a.actor?.hostAsserted === b.actor?.hostAsserted && a.actor?.issuer === b.actor?.issuer,
+};
+export function steerReplayDiffers(held, repeat) {
+    return STEER_REPLAY_FACETS.filter((facet) => !FACET_IS_SAME[facet](held, repeat));
+}
+export function steerReplayRefusal(held, repeat, where) {
+    const differs = steerReplayDiffers(held, repeat);
+    if (differs.length === 0)
+        return undefined;
+    const seat = where.seat === "parked" ? `parked under inputId "${where.inputId}"` : "accepted under this inputId";
+    const listed = differs.join(", ");
+    const message = differs.includes("text")
+        ? `a different steering instruction is already ${seat} (this repeat differs in: ${listed}) — re-issue this one with a fresh inputId (an identical payload would have been an idempotent retry)`
+        : `the same steering instruction is already ${seat}; this repeat differs only in: ${listed}, which cannot change after acceptance — sending it again under another inputId would queue it a second time; to confirm the standing receipt, replay it with its original values`;
+    return { message, detail: { differs } };
+}

package/dist/core/task-event.d.ts

@@ -94,8 +94,9 @@ export type BrainStatusPhase = "rate_limited" | "retrying" | "reconnecting" | "c
  * {@link BrainStatus.errorStatus}; this bucket is the reason a consumer RENDERS and the only carrier for the
  * transport classes, which have no status at all.) Values are about the SHAPE of the failure, never its
  * provider taxonomy:
- *  - `connect_refused` — the attempt got a definite negative about the target itself (nothing accepts
- *    at that address, or the name has no address). This is the class the SHORT retry lane serves.
+ *  - `connect_refused` — the attempt got a definite negative about the way to the target (nothing accepts
+ *    at that address, the name has no address, or the proxy on the way refused the tunnel). This is the class
+ *    the SHORT retry lane serves.
  *  - `transport`      — any other transport-level failure: a connect timeout, a reset, a mid-stream
  *    tear. No verdict about the target; the full ladder applies.
  *  - `stall`          — no failure was observed on the link at all: THIS process cancelled its own

package/dist/core/task-stream.d.ts

@@ -43,15 +43,20 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * that arrives while the task is LIVE was the only one that injected twice.
      *  - **Absent ⇒ nothing changes**: a uuidv7 is minted for the event, nothing is recorded for the call,
      *    and the delivered bytes are what they always were. Every pre-existing caller is on this arm.
-     *  - **Replay ⇒ idempotent no-op**: re-steering an id this stream already ACCEPTED, with an identical
-     *    payload (same text, same `trusted`, same `actor`), injects nothing and emits no second
+     *  - **Replay ⇒ idempotent no-op**: re-steering an id this stream already ACCEPTED, with the same
+     *    steer (same text, `trusted`, tier — absent reads `next` — and `actor`), injects nothing and emits no second
      *    `human_input` frame. What is remembered is exactly what QUEUED: a delivery that was refused
      *    (not running) can be retried under its own id, and a call whose DELIVERED payload is
      *    whitespace-only — which the harness discards without minting a frame; note a `trusted` steer is
      *    wrapped first, so it queues even for blank text — reserves nothing, leaving that id usable.
-     *  - **Same id, DIFFERENT instruction ⇒ typed throw** `steering.duplicate_input_id`: a key is not
+     *  - **Same id, not the same steer ⇒ typed throw** `steering.duplicate_input_id`: a key is not
      *    evidence of a replay, and two callers colliding on one id must not silently lose the second
-     *    (the parked leg's `appendPendingSteer` refuses it identically). Re-issue under a fresh id.
+     *    (the parked leg's `appendPendingSteer` judges and refuses it identically). The error carries
+     *    `detail.differs` — the facets that differ (closed `STEER_REPLAY_FACETS`: `text`, `trusted`,
+     *    `priority`, `actor`), compared on what the caller SENT, never on the framed bytes. With `text`
+     *    among them it is another instruction: re-issue it under a fresh id. Without, it is the accepted one
+     *    re-sent at another tier / trust / attribution, which acceptance does not change: a fresh id would
+     *    queue it twice, so replay it with its original values to confirm the receipt.
      *  - **Bad value ⇒ typed throw** `steering.invalid_content`, never a silent fallback to "no id": the
      *    value domain is the parked leg's (a non-empty string of at most `MAX_STEER_INPUT_ID_CHARS`
      *    characters), so one key is accepted or
@@ -107,8 +112,9 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      *    relaying steer must gate this option at its own face — relay IS authorization.
      *  An unknown value throws typed `steering.invalid_content` (bad-value loudness). The replay
      *  identity (`inputId` idempotency) includes the NORMALIZED tier: the same text replayed under
-     *  the same id at a different tier refuses `steering.duplicate_input_id` — an "idempotent
-     *  success" that silently skipped the interrupt would be a disposition lie.
+     *  the same id at a different tier refuses `steering.duplicate_input_id` (`detail.differs:
+     *  ["priority"]`) — an "idempotent success" that silently skipped the interrupt would be a
+     *  disposition lie.
      *
      * design/373 §4.3 (D2, ruling of 2026-08-24) — a deployment `userPromptSubmit` hook SCREENS this verb:
      * the steer face is a SERVICE entrance (third-party callers reach a running run through it), so

package/dist/core/tool-errors.d.ts

@@ -123,8 +123,8 @@ export type WorkerErrorClass = "budget" | "limit" | "output" | "suspend" | "revi
  * The `limits.` namespace splits into the `budget` and `limit` classes by exact code — see
  * {@link EXACT_CODE_CLASS}. Operation-level dotted codes that are surfaced to a *caller* and never become a
  * task outcome are deliberately OUT of scope: `steering.*` (`steering.not_running`/`steering.invalid_content`/
- * `steering.duplicate_input_id`/`steering.blocked_by_hook`, rejected to the `steer()` caller — the fourth also
- * rides the resume face as a `CheckpointError` code) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
+ * `steering.duplicate_input_id`/`steering.blocked_by_hook`, rejected to the `steer()` caller — the third also
+ * rides the parked queue's `setPendingSteer` face and the fourth the resume face, as `CheckpointError` codes) and `mcp.*` (`mcp.server_unavailable`, an `onWarn` warning code) — neither
  * reaches `TaskResult.errorCode`, so a caller will never pass them here. A genuinely unmapped code → `"unknown"` (which therefore means
  * "known-but-foreign or no code", e.g. a leaked fs/Node code, NOT "an OUR terminal class we forgot to add").
  */

package/dist/core/types.d.ts

@@ -29,6 +29,6 @@ export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js"
 export type { BackgroundChildEvent, DelegationLifecycleEvent } from "./delegation-frames.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
 export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
-export type { EngineNotice, OwedUserInputAccount, UserSteerUndrainedCause } from "./engine-notice.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_STEER_UNDRAINED_CAUSES } from "./engine-notice.js";
+export type { EngineNotice, OwedUserInputAccount, UserInputUndrainedCause } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES } from "./engine-notice.js";
 export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };

package/dist/core/types.js

@@ -1,4 +1,4 @@
 export { MODEL_ROLES } from "./model-seat.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_STEER_UNDRAINED_CAUSES } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, parentLegIds, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES } from "./engine-notice.js";

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { StdioLspTransport, type LspChildProcess } from "./engine/lsp/stdio-lsp-
 export { encodeFrame, createFrameDecoder } from "./engine/lsp/frame-decoder.js";
 export { resolveModel, resolveTaskModel, parseModelMention, expandTiers, DEFAULT_TIER_ORDER, CC_MODEL_TIER_ALIASES, ROLE_TIER_DEFAULTS, MODEL_ROLES, type ModelRole, type RoleSpec, type ModelRoles, type ResolvedRole, type ModelMention, } from "./core/roles.js";
 export { selectModel, selectModelOrThrow, type ModelCriteria, type ModelTier } from "./core/select-model.js";
-export { BrainError, classifyHttp, isProviderEchoShape, PROVIDER_ECHO_SHAPE, type BrainErrorCode } from "./brain/errors.js";
+export { BrainError, classifyHttp, isProviderEchoShape, PROVIDER_ECHO_SHAPE, PROXY_TUNNEL_REFUSED, type BrainErrorCode } from "./brain/errors.js";
 export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/repetition.js";
 export type { RepetitionEvent, RepetitionInspection } from "./brain/repetition.js";
 export { computeCostMicroUsd, isModelPriced, modelCostToPricing, type ModelPricing, type TokenCounts, } from "./core/pricing.js";
@@ -63,7 +63,8 @@ export { MCP_FAILURE_KINDS, MCP_DELIVERY_VERDICTS, MCP_LIVENESS_STATES, classify
 export { MCP_INJECTION_DROP_REASONS, MCP_INJECTION_DROP_TEXT, mcpInjectionDroppedNotice, type McpInjectionDropReason, type McpInjectionDropFacts } from "./core/mcp-injection-drop.js";
 export { askUnresolvableNotice, type AskUnresolvableFacts } from "./core/ask-unresolvable-notice.js";
 export { ASK_UNRESOLVABLE_CAUSES } from "./core/ask-unresolvable-notice.js";
-export { USER_STEER_UNDRAINED_CAUSES, type UserSteerUndrainedCause } from "./core/engine-notice.js";
+export { USER_INPUT_UNDRAINED_CAUSES, type UserInputUndrainedCause } from "./core/engine-notice.js";
+export { STEER_REPLAY_FACETS, type SteerReplayFacet } from "./core/steer-replay.js";
 export { TOOL_TURN_INCOMPLETE_CAUSES, type ToolTurnIncompleteCause } from "./internal/llm.js";
 export { DURABLE_MANDATE_SOURCES } from "./core/tool-policy.js";
 export { TERMINAL_CAUSE_IS_REPLAYABLE, type TerminalFailureDetail, type TerminalBlockedDetail, PROMPT_BLOCK_CAUSES, type PromptBlockCause, isPromptBlockCause } from "./core/terminal-cause.js";