@sema-agent/core 5.63.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

@@ -610,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,
                 };
@@ -648,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;
@@ -660,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 } : {}),
+                            };
                         },
                     };
                 },

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. */
@@ -1010,7 +1078,25 @@ 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. */

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;
@@ -529,18 +563,8 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn,
             messages = transformed;
         }
         else {
-            const adopted = transformed.adoptedContext;
-            if (adopted !== undefined) {
-                context.messages = adopted.messages;
-                if (adopted.systemPrompt !== undefined) {
-                    context.systemPrompt = adopted.systemPrompt;
-                    if (adopted.systemBlocks !== undefined) {
-                        context.systemBlocks = adopted.systemBlocks;
-                    }
-                    else {
-                        delete context.systemBlocks;
-                    }
-                }
+            if (transformed.adoptedContext !== undefined) {
+                adoptRebuiltContext(context, transformed.adoptedContext);
             }
             messages = transformed.messages;
         }

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

@@ -159,8 +159,22 @@ export interface LoopPromptTooLongRecovery {
      * Produce a replacement transcript to retry the provider request with (attempt starts at 1).
      * Return undefined to give up — the loop then surfaces the original error unchanged.
      * Contract: must not throw or reject.
+     *
+     * The return may be a bare transcript (the historic form — messages only) or an
+     * {@link AdoptedLoopContext}, which additionally adopts the rebuilt SYSTEM PROMPT for the retry:
+     * the recovery pass can commit a prompt-epoch change (a compaction-boundary center-prompt
+     * adoption/rollback rides the very pass this lane runs), and a retry built from the rebuilt
+     * transcript under the PRE-epoch prompt ships one request under the policy the session just
+     * superseded. Same adoption rule as the transform seam's `adoptedContext` — one helper, both
+     * lanes.
+     *
+     * `turnSignal` is the TURN-scoped abort (design/373 S1): a turn interrupt fired while the policy
+     * runs, and a policy whose work is expensive (a forced compaction's summary call) must ride it so
+     * the interjection is served now instead of after the whole pass. A policy that DECLINES while
+     * this signal is aborted does not leave the run holding the provider error: the loop settles the
+     * turn as an interrupted one and continues.
      */
-    recover: (messages: AgentMessage[], attempt: number) => Promise<AgentMessage[] | undefined>;
+    recover: (messages: AgentMessage[], attempt: number, turnSignal?: AbortSignal) => Promise<AgentMessage[] | AdoptedLoopContext | undefined>;
     /** Override the prompt-too-long classifier. Default (design/374 slice 2): the TYPED cause first
      *  (`errorKind: "input_too_long"`, stamped by the brains from provenance-checked provider
      *  signals), then the conservative provider-message prose pattern as the fallback for brains
@@ -219,10 +233,10 @@ export interface LoopThinkingOnlyRecovery {
  *  this shape — `truncatedOutput`/`malformedToolUse`/`thinkingOnly` already reference the named types
  *  below by direct import (no drift risk); `degenerateOutput` (2 fields) is hand-copied there and is a
  *  candidate for a future `Pick`-style extraction; `promptTooLong` is
- *  INTENTIONALLY forked — the harness side is a session-level `recover(attempt)` reduction, this loop
- *  side is `recover(messages, attempt)` and also carries `withholdErrorEvents`, so the two can never share
- *  one type. (`agent-harness.ts` is outside this file's edit scope — its side of this mutual-reference
- *  note is pending.) */
+ *  INTENTIONALLY forked — the harness side is a session-level `recover(attempt, turnSignal)` reduction,
+ *  this loop side is `recover(messages, attempt, turnSignal)` and also carries `withholdErrorEvents`, so
+ *  the two can never share one type. (`agent-harness.ts` is outside this file's edit scope — its side of
+ *  this mutual-reference note is pending.) */
 /**
  * design/374 slice 3 — the transform's ADOPTING return shape (see
  * {@link AgentLoopConfig.transformContext}). Two arrays with different standings, on purpose:
@@ -239,23 +253,30 @@ export interface TransformedContext {
     /** The wire view for THIS request (what `convertToLlm` receives). */
     messages: AgentMessage[];
     /** Present ⇒ adopt this rebuilt context as the loop's live state before streaming. */
-    adoptedContext?: {
-        /** The rebuilt transcript the loop adopts as `state.context.messages`. */
-        messages: AgentMessage[];
-        /** When present, the rebuilt SYSTEM PROMPT is adopted too — and it applies to THIS very
-         *  request (the loop reads `context.systemPrompt` after the transform): an in-turn compaction
-         *  can commit a prompt-epoch change (center-prompt adoption/rollback rides the compaction
-         *  pass), and a request built from the rebuilt transcript under the PRE-epoch prompt would
-         *  disagree with the epoch the session just recorded (adversarial review r1). `systemBlocks`
-         *  must only ever accompany the prompt they byte-correspond to; when the prompt is adopted
-         *  WITHOUT blocks, stale blocks are dropped (the string face is the truth source — same
-         *  degrade-to-string posture as the harness's atomic-face guard). */
-        systemPrompt?: string;
-        systemBlocks?: Array<{
-            text: string;
-            cacheControlBoundary: boolean;
-        }>;
-    };
+    adoptedContext?: AdoptedLoopContext;
+}
+/**
+ * A session-rebuilt context the loop adopts as its LIVE state. Minted by the two adoption seams —
+ * the transform's {@link TransformedContext.adoptedContext} (design/374 slice 3, arm B) and the ④b
+ * prompt-too-long {@link LoopPromptTooLongRecovery.recover} return (#474 ①) — and applied by ONE
+ * rule inside the loop, so the two lanes can never drift on what "adopt" means.
+ */
+export interface AdoptedLoopContext {
+    /** The rebuilt transcript the loop adopts as `state.context.messages`. */
+    messages: AgentMessage[];
+    /** When present, the rebuilt SYSTEM PROMPT is adopted too — and it applies to THIS very
+     *  request (the loop reads `context.systemPrompt` after the transform / before the retry): an
+     *  in-turn compaction can commit a prompt-epoch change (center-prompt adoption/rollback rides the
+     *  compaction pass), and a request built from the rebuilt transcript under the PRE-epoch prompt
+     *  would disagree with the epoch the session just recorded (adversarial review r1). `systemBlocks`
+     *  must only ever accompany the prompt they byte-correspond to; when the prompt is adopted
+     *  WITHOUT blocks, stale blocks are dropped (the string face is the truth source — same
+     *  degrade-to-string posture as the harness's atomic-face guard). */
+    systemPrompt?: string;
+    systemBlocks?: Array<{
+        text: string;
+        cacheControlBoundary: boolean;
+    }>;
 }
 export interface LoopRecoveryOptions {
     promptTooLong?: LoopPromptTooLongRecovery;

package/dist/index.d.ts

@@ -75,7 +75,7 @@ export { getShellConfig, isWslBashLauncher } from "./engine/execution-env/node-e
 export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export type { SecretEnvFinding, SecretEnvFindingKind } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
-export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode } from "./internal/harness.js";
+export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode, WriteExpectation, WriteReceipt } from "./internal/harness.js";
 export type { ExecResult } from "./internal/harness.js";
 export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
 export { withRetry } from "./core/with-retry.js";

package/dist/internal/harness-types.d.ts

@@ -8,7 +8,7 @@ export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
 export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, } from "../engine/loop/types.js";
-export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
+export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";
 export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -186,6 +186,12 @@ export interface RunWorkflowToolDeps {
      *  root MUST ride deps; `ctx.rootSessionId` stays first for a deployment-composed mount that
      *  does get the enriched ctx. */
     rootSessionId?: string;
+    /** design/380 O1② (C12) — the host run's EXPLICIT placement fixed point
+     *  (`RunInternals.placementRoot`), riding deps for the same auto-mounted-ctx reason as
+     *  `rootSessionId` above; threaded into the workflow run so every workflow-spawned agent keeps
+     *  the ladder/gate placement. Absent ⇒ nothing extra travels (the rootSessionId chain is the
+     *  placement root through prepare's mint middle segment). */
+    placementRoot?: string;
     /** Process-local unified task registry. When present, RunWorkflow returns `task_id === runId` with a `w*` id. */
     taskRegistry?: TaskRegistry;
     /** design/115 P2 core slice: run-local task-notification sink for SDK event + live model XML injection.