@sema-agent/core 5.62.0 → 5.64.0

package/dist/core/usage-window-store.d.ts

@@ -14,7 +14,8 @@
  */
 /**
  * One governed window. Its fields are allowances, not hints: `windowMs` is the window's WIDTH and
- * `maxTokens` / `maxCostUsd` the two CEILINGS it admits work under. `anchor` picks between the two window
+ * `maxTokens` / `maxCostUsd` the two CEILINGS it admits work under — each optional on its own, at least
+ * one required (a window with neither is refused at the door). `anchor` picks between the two window
  * shapes that actually exist in the wild:
  *  - `"first-use"` — the window OPENS at the key's first charge and lasts `windowMs`; when it lapses with
  *    no further use, the next charge opens a fresh one. This is the "5 hours from when you started"
@@ -26,19 +27,33 @@ export interface UsageWindow {
     /** Window width in ms. Must be finite and > 0 (a zero-width window admits nothing and expires
      *  instantly — refused at the door rather than silently governing every task to death). */
     windowMs: number;
-    /** Tokens the window admits before it is exhausted. Must be finite and >= 0; `0` is a real, always-full
-     *  window (an operator lock-out), not "unset". */
-    maxTokens: number;
     /**
-     * OPTIONAL second ceiling: the MONEY the window admits before it is exhausted, in absolute USD — the
+     * Tokens the window admits before it is exhausted. Must be finite and >= 0 WHEN PRESENT; `0` is a real,
+     * always-full window (an operator lock-out), not "unset" — absence is the only way to say "this window
+     * does not govern tokens".
+     *
+     * OPTIONAL since the $ ceiling below became a peer rather than an addition: a deployment governed by
+     * SPEND alone would otherwise have had to declare a token ceiling no run could reach, i.e. a number
+     * nobody chose sitting in the field this door exists to keep honest. Either ceiling alone is a complete
+     * declaration; a window that declares NEITHER is refused (`config.usage_window_invalid`) rather than
+     * admitting everything silently.
+     */
+    maxTokens?: number;
+    /**
+     * The OTHER ceiling: the MONEY the window admits before it is exhausted, in absolute USD — the
      * same quantity and unit `TaskLimits.maxCostUsd` names, one governance level up (a task's own allowance
-     * vs the allowance an operator grants a principal across tasks). Must be finite and >= 0; `0` is a real,
+     * vs the allowance an operator grants a principal across tasks). Must be finite, >= 0, and must still be
+     * finite once converted to the ledger's micro-USD unit (`× 1e6`, i.e. below ~1.79e302 USD — an Infinity
+     * threshold is not the declared ceiling in the unit the ledger counts, so such a window would read as
+     * governed while enforcing nothing it was given, and is refused at the door). `0` is a real,
      * always-full window, exactly as it is for `maxTokens`.
      *
-     * The two ceilings are INDEPENDENT and both bind: a window is exhausted when EITHER its tokens reach
-     * `maxTokens` or its cost reaches `maxCostUsd` — whichever fills first. Absent (the default, and every
-     * pre-existing deployment) means THIS window governs tokens only — its own reading never asks for or
-     * enforces a cost. Whether cost is tracked/recorded at all is a DEPLOYMENT-level fact, not a
+     * The two ceilings are INDEPENDENT and every DECLARED one binds: a window is exhausted when either its
+     * tokens reach `maxTokens` or its cost reaches `maxCostUsd` — whichever fills first — and a ceiling that
+     * is absent is not a ceiling at all (never a zero, never an infinity: it simply does not participate).
+     * Absent (the default, and every pre-existing deployment) means THIS window governs tokens only — its
+     * own reading never asks for or enforces a cost. Whether cost is tracked/recorded at all is a
+     * DEPLOYMENT-level fact, not a
      * per-window one (the `UsageSlot.costMicroUsd` / `UsageBucketRow` in-presence condition: "while the
      * deployment governs at least one `maxCostUsd` window"): in a MIXED declaration the shared ledger
      * rows carry cost under every window's bucket, and only a deployment with NO $ window anywhere keeps
@@ -111,8 +126,10 @@ export interface UsageWindowReading {
      *  whole window as exhausted until the unpriced charge ages out, would lock a key out for as long as
      *  `windowMs` over one degraded turn, which is a larger outage than the gap it answers. */
     costUnknown?: true;
-    /** The window admits no further work: `tokens >= window.maxTokens`, OR (when the window declares one)
-     *  `costMicroUsd >= window.maxCostUsd` — the two ceilings are independent and either one binds. */
+    /** The window admits no further work: (when the window declares one) `tokens >= window.maxTokens`, OR
+     *  (when the window declares one) `costMicroUsd >= window.maxCostUsd` — the two ceilings are independent
+     *  and every DECLARED one binds. An undeclared axis never binds, however much the window holds on it:
+     *  `tokens` is still reported for a money-only window (what it holds), it is just not a ceiling there. */
     exhausted: boolean;
     /** Ms until this window next frees capacity: for `first-use`, when the open window lapses; for
      *  `rolling`, when its OLDEST in-window slot ages out (which frees that slot's tokens, not
@@ -146,6 +163,21 @@ export interface UsageWindowStore {
      * the pre-cost-arm signature drops the argument silently — which is why the arithmetic refuses an absent
      * cost outright (`usage_window.store_cost_unanswered`) instead of folding it to a 0 that would leave the
      * money ceiling open forever with nothing able to notice.
+     *
+     * IMPLEMENTER SELF-CHECK — three questions, in order. The in-presence condition above is a
+     * DEPLOYMENT-wide property of the `windows` argument, not a per-window one, and a store that reasons one
+     * window at a time is exactly where it gets missed:
+     *  1. Does this call's window set carry ANY window declaring `maxCostUsd`? Then this is a COST charge
+     *     for every row it writes — the rolling slot is ONE row every rolling window reads, and a first-use
+     *     bucket is ONE row per width shared by every window of that width — so there is no "cost only on
+     *     the $ windows" split to implement. A row written cost-less because a token-only window happened
+     *     to be the one in view is a row the $ window later reads as unpriced.
+     *  2. Was the spend real but unpriceable (no rate for the model, a provider that answered no usage)?
+     *     Then carry the `null` through AS `null`, never as `0`: `0` asserts "this charge cost nothing" and
+     *     silently raises the remaining allowance, while `null` is what lets the row say so and surfaces as
+     *     {@link UsageWindowReading.costUnknown}, keeping the reported total honest as a LOWER BOUND.
+     *  3. Cannot answer either — the argument never reached this layer? Then leave it `undefined` and let
+     *     the charge be refused loudly. A guessed 0 is the one outcome the money ceiling cannot survive.
      */
     charge(key: string, tokens: number, at: number, windows: readonly UsageWindow[], costMicroUsd?: number | null): Promise<void>;
     /** Read `key`'s state for each window as of `now`, in the order the windows were given. */

package/dist/core/usage-window-store.js

@@ -21,12 +21,19 @@ export function resolveUsageWindows(windows) {
         if (typeof w.windowMs !== "number" || !Number.isFinite(w.windowMs) || w.windowMs <= 0) {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].windowMs must be a finite number of milliseconds > 0 (got ${String(w.windowMs)})`);
         }
-        if (typeof w.maxTokens !== "number" || !Number.isFinite(w.maxTokens) || w.maxTokens < 0) {
-            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxTokens must be a finite, non-negative number (got ${String(w.maxTokens)})`);
+        if (w.maxTokens !== undefined && (typeof w.maxTokens !== "number" || !Number.isFinite(w.maxTokens) || w.maxTokens < 0)) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxTokens must be a finite, non-negative number when present (got ${String(w.maxTokens)})`);
         }
         if (w.maxCostUsd !== undefined && (typeof w.maxCostUsd !== "number" || !Number.isFinite(w.maxCostUsd) || w.maxCostUsd < 0)) {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxCostUsd must be a finite, non-negative number of USD when present (got ${String(w.maxCostUsd)})`);
         }
+        const maxCostMicroUsd = maxCostMicroUsdOf(w);
+        if (maxCostMicroUsd !== undefined && !Number.isFinite(maxCostMicroUsd)) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].maxCostUsd ${String(w.maxCostUsd)} overflows the ledger's micro-USD unit (${String(w.maxCostUsd)} × 1e6 = ${String(maxCostMicroUsd)}) — Infinity is not the declared ceiling in the unit this ledger counts, so the window would read as governed while enforcing nothing it was given. Declare a ceiling below 1.79e302 USD.`);
+        }
+        if (w.maxTokens === undefined && w.maxCostUsd === undefined) {
+            throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[] must declare at least one ceiling — maxTokens, maxCostUsd, or both (got neither, over windowMs ${String(w.windowMs)}, ${String(w.anchor)}). A window with no ceiling admits everything, which is not what declaring a window means.`);
+        }
         if (w.anchor !== "first-use" && w.anchor !== "rolling") {
             throw usageConfigError("config.usage_window_invalid", `RunnerDeps.usageWindows[].anchor must be "first-use" or "rolling" (got ${String(w.anchor)})`);
         }
@@ -132,7 +139,8 @@ export function readUsageRecord(record, windows, now) {
             }
         }
         const maxCostMicroUsd = maxCostMicroUsdOf(w);
-        const exhausted = tokens >= w.maxTokens || (maxCostMicroUsd !== undefined && costMicroUsd >= maxCostMicroUsd);
+        const exhausted = (w.maxTokens !== undefined && tokens >= w.maxTokens) ||
+            (maxCostMicroUsd !== undefined && costMicroUsd >= maxCostMicroUsd);
         const retryAfterMs = exhausted ? Math.max(1, freesAt === undefined ? w.windowMs : freesAt - now) : 0;
         readings.push({
             window: w,

package/dist/core/workflow-run-store-contract.js

@@ -101,6 +101,23 @@ export async function workflowRunStoreContract(make, runAssertion = defaultSeque
         assert.equal(namedSummary.description, "find flaky tests");
         assert.equal(namedSummary.currentPhase, "fix");
     });
+    run("the ADDITIVE terminal disclosures reach the LIST row: agentFailures + budgetOvershoot project, and a clean run keeps both keys ABSENT", async () => {
+        const store = make();
+        const over = createWorkflowRun({ id: "d-over", createdAt: 5_000, agentFailures: 2, budgetOvershoot: { budgetTokens: 150, spentTokens: 1_200 } });
+        const unsettled = createWorkflowRun({ id: "d-unsettled", createdAt: 6_000, budgetOvershoot: { budgetTokens: 100, spentTokens: 0, unsettledTokens: 500 } });
+        const clean = createWorkflowRun({ id: "d-clean", createdAt: 7_000 });
+        for (const r of [over, unsettled, clean])
+            await store.put(r.id, r);
+        const byId = new Map((await store.listByScope("tenant-a")).map((s) => [s.id, s]));
+        assert.equal(byId.get("d-over").agentFailures, 2);
+        assert.deepEqual(byId.get("d-over").budgetOvershoot, { budgetTokens: 150, spentTokens: 1_200 });
+        assert.deepEqual(byId.get("d-unsettled").budgetOvershoot, { budgetTokens: 100, spentTokens: 0, unsettledTokens: 500 });
+        assert.equal("agentFailures" in byId.get("d-clean"), false, "no failures ⇒ the key is OMITTED, not 0/null");
+        assert.equal("budgetOvershoot" in byId.get("d-clean"), false, "within (or without) a ceiling ⇒ the key is OMITTED, not null/zeroed");
+        assert.equal(byId.get("d-over").tokens, over.stats.tokens + over.stats.nested.tokens);
+        byId.get("d-over").budgetOvershoot.spentTokens = 7;
+        assert.equal((await store.get("d-over")).budgetOvershoot.spentTokens, 1_200);
+    });
     run("reap: only terminal runs, NEVER running; maxAgeMs + keep retention; no policy → no-op", async () => {
         const store = make();
         const running = createWorkflowRun({ id: "k-run", status: "running", createdAt: 100, endedAt: undefined });

package/dist/core/workflow-run-store.d.ts

@@ -49,6 +49,24 @@ export interface WorkflowRunSummary {
     /** Count of agent-runs that ended failed ({@link WorkflowRun.agentFailures}) — present only when > 0.
      *  Lets a list view flag a "completed, with failures" run without an N+1 `get` of the full run. */
     agentFailures?: number;
+    /** The run's TERMINAL token-budget overshoot ({@link WorkflowRun.budgetOvershoot}) — present ONLY when the
+     *  run actually spent MORE than its ceiling, absent on every run that stayed within one and on every run
+     *  that set no budget at all. The list-view twin of {@link agentFailures}: it lets a row be flagged
+     *  "completed, and over budget" without an N+1 `get` of the full run — the *other* way a `completed` row is
+     *  not the unqualified good news it looks like. It cannot be DERIVED from anything else on this projection:
+     *  {@link tokens} is a different axis (see its note), so without this seat an over-budget run reads on the
+     *  list face exactly like a clean one.
+     *
+     *  Projected as a de-aliased shallow COPY — every other member here is a primitive, so the projection must
+     *  not hand a caller a live reference into a stored run (the same anti-aliasing posture the stores' `get`
+     *  keeps with `structuredClone`). Read the members per {@link WorkflowRun.budgetOvershoot}: the overshoot is
+     *  `spentTokens + unsettledTokens - budgetTokens`, and a run resting entirely on `unsettledTokens` is a
+     *  best-effort disclosure rather than a measurement. */
+    budgetOvershoot?: {
+        budgetTokens: number;
+        spentTokens: number;
+        unsettledTokens?: number;
+    };
     /** Title of the latest phase recorded ({@link WorkflowRun.phases}`.at(-1).title`) — what the run is on RIGHT
      *  NOW for a `running` row (so the `/workflows` list shows the live phase without subscribing to the event
      *  stream). Absent when no phase has started yet. */
@@ -58,7 +76,10 @@ export interface WorkflowRunSummary {
     /** Number of agent-runs recorded so far ({@link WorkflowRun.agents}`.length`). */
     agentCount: number;
     /** Total tokens spent = own + nested (`stats.tokens + stats.nested.tokens`) — the figure a triage view
-     *  sorts/compares by. own/nested stay SEPARATE on the full run (R-5); the summary folds them for display. */
+     *  sorts/compares by. own/nested stay SEPARATE on the full run (R-5); the summary folds them for display.
+     *  ⚠️ NOT the budget axis's figure: run stats also count REPLAYED work, which the budget deliberately never
+     *  charges, so comparing this against a ceiling proves nothing in either direction — whether a run overran
+     *  its budget is read off {@link budgetOvershoot}, never inferred from here. */
     tokens: number;
     /** When the run started ({@link WorkflowRun.startedAt}, epoch ms). */
     startedAt: number;

package/dist/core/workflow-run-store.js

@@ -9,6 +9,7 @@ export function summarizeWorkflowRun(run) {
         ...(run.description !== undefined ? { description: run.description } : {}),
         status: run.status,
         ...(run.agentFailures !== undefined ? { agentFailures: run.agentFailures } : {}),
+        ...(run.budgetOvershoot !== undefined ? { budgetOvershoot: { ...run.budgetOvershoot } } : {}),
         ...(latestPhase !== undefined ? { currentPhase: latestPhase.title } : {}),
         phaseCount: run.phases.length,
         agentCount: run.agents.length,

package/dist/engine/harness/agent-harness.d.ts

@@ -70,7 +70,8 @@ export interface UserMessageProvenance {
  * (e.g. a forced compaction) — otherwise the next turn's `createTurnState()` rebuilds the context
  * from the session and the in-memory shrink evaporates. So the harness contract is: `recover`
  * persists the reduction to the session and returns whether anything shrank; the harness then
- * rebuilds the turn state FROM the session and hands the loop the rebuilt transcript.
+ * rebuilds the turn state FROM the session and hands the loop the rebuilt context — transcript AND
+ * system prompt (#474 ①), because the reduction pass may commit a prompt-epoch change of its own.
  */
 export interface HarnessLoopRecovery {
     truncatedOutput?: LoopTruncatedOutputRecovery;
@@ -86,8 +87,12 @@ export interface HarnessLoopRecovery {
         maxContinues?: number;
     };
     promptTooLong?: {
-        /** Persist a context reduction to the SESSION; return true if anything shrank. Must not throw. */
-        recover: (attempt: number) => Promise<boolean>;
+        /** Persist a context reduction to the SESSION; return true if anything shrank. Must not throw.
+         *  `turnSignal` is the TURN-scoped abort (#474 ②): a policy whose work is expensive (a forced
+         *  compaction's summary call) must ride it so a turn interrupt cuts the pass short instead of
+         *  being waited out — and a policy that declines under it leaves the loop settling the turn as
+         *  an interrupted one, never as the provider error's terminal. */
+        recover: (attempt: number, turnSignal?: AbortSignal) => Promise<boolean>;
         /** Override the loop's default prompt-too-long classifier. */
         detect?: (message: AssistantMessage) => boolean;
         /** Max recovery retries per turn (loop default: 2). */

package/dist/engine/harness/agent-harness.js

@@ -547,7 +547,7 @@ export class AgentHarness {
         userInputParkRecords.delete(message);
         engineNotePayloads.delete(message);
     }
-    createLoopConfig(getTurnState, setTurnState) {
+    createLoopConfig(getTurnState, setTurnState, runPromptOverride) {
         const turnState = getTurnState();
         const self = this;
         return {
@@ -564,9 +564,24 @@ export class AgentHarness {
                 : {}),
             convertToLlm: (messages) => stripEngineMetadata(convertToLlm(messages)),
             shouldStopAfterTurn: () => this._stopAfterTurn,
-            transformContext: async (messages) => {
-                const result = await this.emitHook({ type: "context", messages: [...messages] });
-                return result?.messages ?? messages;
+            transformContext: async (messages, signal) => {
+                const result = await this.emitHook({ type: "context", messages: [...messages], ...(signal !== undefined ? { signal } : {}) });
+                if (result?.adoptSessionRebuild !== true) {
+                    return result?.messages ?? messages;
+                }
+                await this.flushPendingSessionWrites();
+                const nextTurnState = await this.createTurnState();
+                setTurnState(nextTurnState);
+                const rebuiltContext = this.createContext(nextTurnState, runPromptOverride);
+                const recheck = await this.emitHook({ type: "context", messages: [...rebuiltContext.messages], ...(signal !== undefined ? { signal } : {}), recheck: true });
+                return {
+                    messages: recheck?.messages ?? rebuiltContext.messages,
+                    adoptedContext: {
+                        messages: rebuiltContext.messages,
+                        systemPrompt: rebuiltContext.systemPrompt,
+                        ...(rebuiltContext.systemBlocks !== undefined ? { systemBlocks: rebuiltContext.systemBlocks } : {}),
+                    },
+                };
             },
             beforeToolCall: async ({ toolCall, args }) => {
                 const result = await this.emitHook({
@@ -595,7 +610,7 @@ export class AgentHarness {
                 const nextTurnState = await this.createTurnState();
                 setTurnState(nextTurnState);
                 return {
-                    context: this.createContext(nextTurnState),
+                    context: this.createContext(nextTurnState, runPromptOverride),
                     model: nextTurnState.model,
                     thinkingLevel: nextTurnState.thinkingLevel,
                 };
@@ -633,10 +648,10 @@ export class AgentHarness {
                         detect: ptl.detect,
                         maxRetries: ptl.maxRetries,
                         withholdErrorEvents: ptl.withholdErrorEvents,
-                        recover: async (_messages, attempt) => {
+                        recover: async (_messages, attempt, turnSignal) => {
                             let shrank = false;
                             try {
-                                shrank = await ptl.recover(attempt);
+                                shrank = await ptl.recover(attempt, turnSignal);
                             }
                             catch {
                                 shrank = false;
@@ -645,7 +660,12 @@ export class AgentHarness {
                                 return undefined;
                             const nextTurnState = await self.createTurnState();
                             setTurnState(nextTurnState);
-                            return self.createContext(nextTurnState).messages;
+                            const rebuilt = self.createContext(nextTurnState, runPromptOverride);
+                            return {
+                                messages: rebuilt.messages,
+                                systemPrompt: rebuilt.systemPrompt,
+                                ...(rebuilt.systemBlocks !== undefined ? { systemBlocks: rebuilt.systemBlocks } : {}),
+                            };
                         },
                     };
                 },
@@ -780,7 +800,7 @@ export class AgentHarness {
         this.runAbortController = abortController;
         const runResultPromise = (async () => {
             try {
-                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace);
+                return await runAgentLoop(messages, this.createContext(turnState, beforeResult?.systemPrompt), this.createLoopConfig(getTurnState, setTurnState, beforeResult?.systemPrompt), (event) => this.handleAgentEvent(event, abortController.signal), abortController.signal, this.createStreamFn(getTurnState), undefined, this.loopTrace);
             }
             catch (error) {
                 try {

package/dist/engine/harness/types.d.ts

@@ -82,12 +82,38 @@ export interface AgentHarnessStreamOptionsPatch extends Omit<Partial<AgentHarnes
 }
 /** Kind of filesystem object as addressed by a {@link FileSystem}. Symlinks are not followed automatically. */
 export type FileKind = "file" | "directory" | "symlink";
+/** design/380 O13 — the precondition a {@link FileSystem.writeFileGuarded} call verifies IN the same
+ *  atomic backend step as the write (minted by the caller from its canonicalization/adjudication pass). */
+export interface WriteExpectation {
+    /** Refuse (nothing written) unless the FINAL open target canonicalizes to this path. */
+    canonicalPath: string;
+    /** Backend object identity (inode/file-id) when the precondition minter observed one; opaque string. */
+    fileId?: string;
+    /** Target must not exist (atomic exclusive create — the writeFileExclusive semantics folded in). */
+    exclusive?: boolean;
+    /** Open with no-follow semantics: a symlink at the leaf fails instead of being traversed. */
+    noFollow?: boolean;
+}
+/** design/380 O13 — the receipt a successful {@link FileSystem.writeFileGuarded} returns: facts about
+ *  the REAL on-disk object the atomic step produced (minter-stated, post-op). */
+export interface WriteReceipt {
+    /** The ACTUAL canonical path written (post-op fact, minter-stated). */
+    canonicalPath: string;
+    fileId?: string;
+    created: boolean;
+}
 /** Stable, backend-independent file error codes returned by {@link FileSystem} file operations. */
 export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported"
 /** Exclusive create refused because the path already exists ({@link FileSystem.writeFileExclusive},
  *  POSIX `O_EXCL` shape). Discriminable so a caller can distinguish "lost the create race" from a
  *  write failure and give honest guidance instead of overwriting. */
  | "already_exists"
+/** design/380 O13 — {@link FileSystem.writeFileGuarded}'s precondition did not hold at the atomic
+ *  write step (the final open target did not canonicalize to the expected path / the backend object
+ *  identity moved / an `exclusive` create found the target present). NOTHING was written —
+ *  discriminable so a caller can tell "the world moved between adjudication and write" from an
+ *  ordinary write failure and re-read instead of blindly retrying. */
+ | "precondition_failed"
 /** A remote fs RPC exceeded its liveness/idle bound (a hung provider call) — retryable by the caller per
  *  the op's idempotency. Mirrors `RemoteExecutionError` code `"timeout"` so a remote `FileSystem` op can
  *  surface a hang as a typed, retryable error instead of `"unknown"` (core src/core/remote-env.ts contract;
@@ -97,7 +123,15 @@ export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not
  *  retryable after reconnect. Mirrors `RemoteExecutionErrorCode` `"transport_lost"`, same precedent as
  *  `"timeout"` above (VENDOR.md mod #9 / service[63] SSH/ADB adapters), so a retry whitelist can see it
  *  instead of an opaque `"unknown"`. */
- | "transport_lost" | "unknown";
+ | "transport_lost"
+/** design/380 O12 — a WRITE-face op (writeFile/appendFile/remove…) was COMMITTED to a remote target and
+ *  its outcome is UNKNOWABLE (the target went unreachable / restarted / was revoked after
+ *  dispatch-commit). NEVER auto-retry and NEVER map onto `timeout`/`transport_lost` (both sit in retry
+ *  whitelists): the bytes may already be on the target. Message MUST carry the verify-first sentence
+ *  ("may have already executed on the target; verify its effect before re-running"). A device adapter's
+ *  WRITE face uses this instead of `transport_lost` (whose retryable-after-reconnect contract is safe
+ *  only for idempotent reads). */
+ | "outcome_unknown" | "unknown";
 /** Error returned by {@link FileSystem} file operations. */
 export declare class FileError extends Error {
     /** Backend-independent error code. */
@@ -131,7 +165,22 @@ export type ExecutionErrorCode = "aborted" | "timeout"
  *  command never started, and every retry will fail the same way (and may lock the account). Mirrors
  *  `RemoteExecutionErrorCode` `"auth_failed"`; deliberately NOT a mirror of `auth_transient`, which an
  *  adapter retries internally per its own bounded policy rather than surfacing as an exec outcome. */
- | "auth_failed" | "unknown";
+ | "auth_failed"
+/** design/380 O12 — the op was COMMITTED to a remote target and its outcome is UNKNOWABLE (the target
+ *  went unreachable / restarted / was revoked after dispatch-commit). NEVER auto-retry and NEVER map
+ *  onto `timeout`/`transport_lost` (both sit in retry whitelists): the command may have already
+ *  executed. Message MUST carry the verify-first sentence ("may have already executed on the target;
+ *  verify its effect before re-running"). Distinct from `transport_lost` (connection story known,
+ *  idempotency-gated retry) — this word is for the arm where the SERVER of the target protocol has
+ *  already ruled the outcome unknowable. */
+ | "outcome_unknown"
+/** design/380 O12 — the target refused the op BEFORE commit (device offline / busy / not bound): the
+ *  command NEVER STARTED, so a retry is safe once the target is back. The honest never-started word for
+ *  a device/remote adapter — `spawn_error` is contractually reserved for OS-level spawn failures (its
+ *  2026-07-13 contract above; the Bash dead-cwd diagnosis hangs off it) and `suspended` claims a paused
+ *  workspace this arm does not have. Spelling note: landed per design/380's arm (b); the device lane's
+ *  wire-word mapping may re-spell at the server's wire freeze. */
+ | "target_unavailable" | "unknown";
 /** Error returned by {@link ExecutionEnv.exec}. */
 export declare class ExecutionError extends Error {
     /** Backend-independent error code. */
@@ -288,6 +337,25 @@ export interface FileSystem {
      * emulation and own the residual race.
      */
     writeFileExclusive?(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
+    /**
+     * design/380 O13 — OPTIONAL guarded write: verify `expect` and write in ONE atomic backend step
+     * (openat/O_NOFOLLOW family on a local backend; a single wire instruction on a remote one), returning
+     * a receipt of the real on-disk object. Precondition mismatch ⇒ FileError `"precondition_failed"`
+     * (closed-set addition), nothing written. Degradation law VERBATIM from writeFileExclusive: a backend
+     * with no such primitive MUST leave this `undefined` rather than emulate in two steps — a two-step
+     * emulation re-opens the very TOCTOU window this method exists to close. Callers fall back to plain
+     * writeFile and OWN the residual race (which the write gate then discloses as "advisory
+     * adjudication" instead of claiming TOCTOU closure).
+     *
+     * SCOPE OF THE CLOSURE (stated so nothing overclaims): the window closed is the one between the
+     * CALLER's own precondition mint (its canonicalization at execute time) and the write. A policy
+     * adjudication that happened EARLIER — e.g. a write-gate verdict that waited on a human approval —
+     * is bound to that policy's own resolution, which is not carried into the caller's expectation
+     * today; a symlink swapped during the approval wait is therefore still re-resolved at execute time.
+     * Binding the GATE's adjudicated key across the approval wait needs a trusted receipt-carriage seat
+     * (policy verdict → approval record → tool execution) that is a separate design, not this method.
+     */
+    writeFileGuarded?(path: string, content: string | Uint8Array, expect: WriteExpectation, abortSignal?: AbortSignal): Promise<Result<WriteReceipt, FileError>>;
     /** Create or append to a file, creating parent directories when supported. */
     appendFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
     /** Return metadata for the addressed path without following symlinks. */
@@ -919,6 +987,25 @@ export interface BeforeAgentStartEvent<TSkill extends Skill = Skill, TPromptTemp
 export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
+    /**
+     * The TURN-scoped abort signal of the request build being transformed (present when the loop
+     * handed one — it always does in production; absent only for bare-harness callers). A handler
+     * that runs an EXPENSIVE reduction (the slice-3 arm-B in-turn compaction is the standing case)
+     * must honor it: a turn interrupt (design/373) fires this signal, and a reduction that only
+     * watches the RUN-level signal would make the interrupt wait out a long summary call and commit
+     * a session mutation the interrupted turn no longer needs (adversarial review r3).
+     */
+    signal?: AbortSignal;
+    /**
+     * design/374 slice 3 — set on the ONE bounded re-dispatch of the adopt seam
+     * ({@link ContextResult.adoptSessionRebuild}): `messages` are the just-adopted session rebuild,
+     * re-presented so the handler's request pipeline applies to what the provider will actually
+     * receive (the "recheck" step of build→reduce→adopt→recheck). A handler must not request a
+     * second adoption on this dispatch — the harness does not honor it (see the result member's
+     * doc) — so a reduction that is still over budget takes the handler's own next arm (the trim
+     * last resort) instead of looping. Absent on every ordinary dispatch.
+     */
+    recheck?: boolean;
 }
 export interface TurnBoundaryEvent {
     /** Fires between model-request boundaries, after session flush, before the context rebuild. */
@@ -991,12 +1078,49 @@ export type AgentHarnessEvent<TSkill extends Skill = Skill, TPromptTemplate exte
 export interface BeforeAgentStartResult {
     /** Replacement messages for the prompt run. */
     messages?: AgentMessage[];
-    /** Replacement system prompt for the prompt run. */
+    /**
+     * Replacement system prompt for the prompt run — RUN-scoped, not turn-scoped: it is in force from
+     * the first provider request until the run ends, across every turn boundary and every mid-request
+     * context rebuild (the turn-boundary rebuild, the arm-B session adopt, the prompt-too-long
+     * recovery retry). While it is in force it OUTRANKS the harness/session prompt, including a
+     * prompt-epoch change committed mid-run: the epoch restatement lands in the session and governs
+     * once no override is in force, it does not preempt the caller's replacement mid-run.
+     *
+     * The system prompt therefore has exactly three legal change points, and a deployment can rely on
+     * it being byte-stable between them (the prefix-cache-friendly property):
+     *   1. run start — this hook's return, or the harness/session prompt when it returns none;
+     *   2. a compaction boundary that adopts a new prompt epoch — live for the NEXT run without an
+     *      override, and for the current run's remaining turns only if no override is in force;
+     *   3. a session clear — the next run starts a fresh prompt.
+     *
+     * Returning a replacement also makes the run string-only on the prompt face: the block face
+     * (`systemBlocks`) attaches only when it provably corresponds to the string being shipped, so an
+     * override run ships no blocks on any of its turns.
+     */
     systemPrompt?: string;
 }
 /** Hook result for replacing the full context message list before provider conversion. */
 export interface ContextResult {
     messages: AgentMessage[];
+    /**
+     * design/374 slice 3 (arm B, the adopt seam) — the handler PERSISTED a session-level reduction
+     * during this dispatch (e.g. an in-turn forced compaction appended to the session) and asks the
+     * harness to adopt it MID-BUILD, the same three-step form as the two existing adoption flows
+     * (turn_boundary / prompt-too-long recovery): flush pending session writes, rebuild the turn
+     * context from the session (`createTurnState`), adopt it (`setTurnState` + the loop-context
+     * adoption via {@link import("../loop/types.js").TransformedContext}), then re-dispatch the
+     * context hook ONCE on the rebuilt view (`ContextEvent.recheck`) so the request pipeline applies
+     * to it. Result: the provider request, every subsequent hook dispatch, and the active turn state
+     * all see the SAME reduced transcript — the three-party co-view the seam exists for. `messages`
+     * on this arm are the handler's best unadopted view and are superseded by the rebuild.
+     *
+     * Honored AT MOST ONCE per request build: on the recheck dispatch this member is ignored (its
+     * `messages` are used verbatim) — the bound that keeps a reduction that cannot get under budget
+     * from re-entering forever. Typed on the hook RESULT deliberately (not a closure side channel):
+     * the adoption is part of the hook's answer, and the one prior closure-ref transport in this
+     * area (`requestLossyRef`) is a recorded bypass shape, not a precedent to grow.
+     */
+    adoptSessionRebuild?: boolean;
 }
 /** Hook result for patching provider request options before payload construction. */
 export interface BeforeProviderRequestResult {

package/dist/engine/loop/agent-loop.js

@@ -256,6 +256,7 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
         await executor.settle();
     }
     raiseFatalCancellation(executor);
+    let interruptedInRecovery = false;
     {
         if (ptl) {
             const detect = ptlDetect;
@@ -273,18 +274,29 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
                 }
                 let replaced;
                 try {
-                    replaced = await ptl.recover(state.context.messages, attempt);
+                    replaced = await ptl.recover(state.context.messages, attempt, turnController.signal);
                 }
                 catch {
                     replaced = undefined;
                 }
                 if (!replaced) {
                     state.context.messages.push(message);
+                    interruptedInRecovery = turnController.signal.aborted && !signal?.aborted;
                     break;
                 }
                 withhold?.discard();
                 withhold = withholdEnabled ? createPtlWithholdBuffer(emit, ptlDetect) : undefined;
-                state.context.messages = replaced;
+                if (Array.isArray(replaced)) {
+                    state.context.messages = replaced;
+                }
+                else {
+                    adoptRebuiltContext(state.context, replaced);
+                }
+                if (turnController.signal.aborted && !signal?.aborted) {
+                    state.context.messages.push(message);
+                    interruptedInRecovery = true;
+                    break;
+                }
                 trace?.({ kind: "continue", reason: "reactive_compact_retry" });
                 executor = new StreamToolExecutor(state.context, state.config, turnController.signal, emit);
                 try {
@@ -297,11 +309,21 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
             }
         }
     }
+    const unrecoveredPtlFailureUnderInterrupt = ptl !== undefined &&
+        message.stopReason === "error" &&
+        ptlDetect(message) &&
+        isBlankFailureContent(message) &&
+        executor.admittedCount === 0;
+    const interruptOwnsTurn = (message.stopReason === "aborted" || interruptedInRecovery || unrecoveredPtlFailureUnderInterrupt) &&
+        turnController.signal.aborted &&
+        !signal?.aborted;
+    if (interruptOwnsTurn && message.stopReason === "error")
+        withhold?.discard();
     await withhold?.flush();
     state.newMessages.push(message);
     if (message.staticReasoningCut === true)
         state.staticReasoningCutRecoveries++;
-    if (message.stopReason === "aborted" && turnController.signal.aborted && !signal?.aborted) {
+    if (interruptOwnsTurn) {
         retractSeat();
         return await settleInterruptedTurn(state, message, executor, [], signal, emit);
     }
@@ -425,6 +447,18 @@ async function runTurnPhases(state, signal, turnController, publishSeat, retract
     }
     return { kind: "ran" };
 }
+function adoptRebuiltContext(context, adopted) {
+    context.messages = adopted.messages;
+    if (adopted.systemPrompt === undefined)
+        return;
+    context.systemPrompt = adopted.systemPrompt;
+    if (adopted.systemBlocks !== undefined) {
+        context.systemBlocks = adopted.systemBlocks;
+    }
+    else {
+        delete context.systemBlocks;
+    }
+}
 function adoptNextTurnSnapshot(state, nextTurnSnapshot) {
     if (!nextTurnSnapshot)
         return;
@@ -524,7 +558,16 @@ async function settleInterruptedTurn(state, message, executor, committedResults,
 async function streamAssistantResponse(context, config, signal, emit, streamFn, runtime, executor, staticReasoningCutDowngrade) {
     let messages = context.messages;
     if (config.transformContext) {
-        messages = await config.transformContext(messages, signal);
+        const transformed = await config.transformContext(messages, signal);
+        if (Array.isArray(transformed)) {
+            messages = transformed;
+        }
+        else {
+            if (transformed.adoptedContext !== undefined) {
+                adoptRebuiltContext(context, transformed.adoptedContext);
+            }
+            messages = transformed.messages;
+        }
     }
     const llmMessages = await config.convertToLlm(messages);
     const llmContext = {