@sema-agent/core 5.63.0 → 5.65.0

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 5.65.0 — 2026-08-28
+
+### Added
+- design/380 batch 2 — the device-lane durable half:
+  - `CheckpointState.placementRootSessionId` (additive): stamped at every suspend mint, restored into the internals binding on resume, chain-stable across arbitrary park depth. A resume whose EXPLICIT `internals.placementRoot` contradicts the recorded root refuses pre-CAS with the NEW code `resume.placement_mismatch` (closed-set addition to `CheckpointError`), positioned in the identity block above the usage-window rung. A supplied `rootSessionId` is delegation identity, never a placement claim — the engine's own parked-agent revive lands at the recorded root. Legacy rows keep the historic fold byte-identical.
+  - `RunnerDeps.resumePreflight` + `resumePreflightTimeoutMs`, NEW public exports `ResumePreflightInfo` / `ResumePreflightVerdict`: a deployment callback screening every redeem attempt as the last pre-CAS rung, reading facts off the persisted row only. Non-answers (throw/timeout/unreadable verdict — including a terminal verdict without a readable message) fail closed as the NEW code `resume.preflight_rejected` on the retry-later arm; only an explicit terminal disposition settles the row, honoring the fence-winner duties (same-process paused env destroyed exactly once; cross-Runner losers retire their reap records). The deadline knob validates its full admissible range loudly and folds to its own 10s default.
+  - `ExecutionEnv.externalContentTarget` (adapter-declared) + `CheckpointState.externalContentTarget` (monotonic bit): the run's env-MOUNTED tool band (fs/bash, Monitor, worktree, LSP — the roster is minted at the mount sites) classifies as external for memory governance, ORs into the `execIsExternalContent` channel, persists across park/resume, and derives one neutral environment-facts prompt line. Orchestration tools never enter the roster. Undeclared deployments are byte-identical.
+- `WorkflowRun.timeoutInterruption` + `WorkflowRunSummary.timeoutInterruption` (#485 core half): a run abandoned by `totalTimeoutMs` carries `{timeoutMs, agentsCompleted, agentsFailed, agentsInFlight}` stamped once at the failure terminal (before the abandonment fold — the seat describes the world the deadline found); record face, list projection (cross-backend contract case), and the poll `note` read the same seat. The status enum is unchanged.
+- `HarvestReport.reportId` (#479): engine-minted uuidv7 per-occurrence identity on all five report-derived memory notices as flat `detail.reportId`; the dedup key is `(code, detail.reportId)`.
+- The workflow poll receipt disclosed a terminal budget overshoot (#478): one additive sentence off the summary seat; seatless runs byte-identical.
+
+### Changed
+- Workflow budget narration labels its unit honestly (#487, case A): four sema-authored faces now say "total tokens"; the CC-verbatim `WorkflowBudgetExceededError` message is deliberately frozen (anchor-inherited label, pinned byte-exact).
+- The read-boundary positive-control pins converted to a differential invariant (test-only).
+
+### Fixed
+- Merged-code rescan batch (A-081, 7 confirmed pre-ship): the placement rung no longer bricks parked durable agents revived under an explicit spawner placement root (P1); the O9a roster is minted at the mount sites instead of a static table, closing the Monitor/worktree/LSP under-marking hole AND the TaskOutput false-positive (P1); the terminal preflight expire honors the design/51 fence-winner duties (paused env reclaimed, P2); the preflight deadline knob's silent double-validation band closed (P2); empty-string placement anchors read uniformly as absence; a terminal verdict without a readable message never terminalizes a row; rung order fixed so a deterministic dead claim is never masked by a retryable code.
+
+### BREAKING/adaptation notes
+- `CheckpointError` closed set +2 (`resume.placement_mismatch`, `resume.preflight_rejected`); `detail.retryAfterMs` now rides two codes.
+- `SerializedCheckpointState` gains two REQUIRED keys (`placementRootSessionId`, `externalContentTarget`) — out-of-tree builders/`satisfies` sites gain compile errors (the mapped type's documented non-homomorphic contract).
+- Export surface +2 (`ResumePreflightInfo`, `ResumePreflightVerdict`).
+- A durable resume whose explicit placement anchor contradicts the recorded root now refuses loudly (named narrowing; re-pin old-behavior probes).
+
+## 5.64.0 — 2026-08-27
+
+### BREAKING
+- **design/380 batch 1 — device-lane placement identity**: `ExecutionEnvFactoryContext` grows a
+  REQUIRED `placementRootSessionId` (the run TREE's fixed point, minted once as
+  `placementRoot ?? rootSessionId ?? sessionId`; an empty resolved value is refused loudly as
+  `config.placement_root_invalid` before the factory is ever called). Deployment code that
+  CONSTRUCTS its own factory context gains a compile-time break — factory *implementors* are purely
+  additive. The fixed point threads through cascade rungs, verification legs and every spawn family
+  (subagent, workflow), so a descendant's fresh session id can no longer read as a new placement;
+  durable-resume carriage is the next batch's seat (`O1③`) and its current fallback is pinned in the
+  tree so landing it must flip the pin consciously.
+
+### Added
+- `WorkspaceHandle.deviceId` — explicit, minter-stated identity of the target a workspace lives on
+  (rides the checkpoint's all-string handle whitelist unchanged).
+- `outcome_unknown` joins `ExecutionErrorCode`, `FileErrorCode` and `RemoteExecutionErrorCode`, and
+  `target_unavailable` joins `ExecutionErrorCode`: an op COMMITTED to a remote target whose outcome
+  is unknowable must never be auto-retried (it is deliberately NOT in
+  `RETRYABLE_REMOTE_ERROR_CODES`), while a never-started commit refusal is retry-safe by contract.
+  `precondition_failed` joins `FileErrorCode` for the guarded write below. **Downstream exhaustive
+  switches over these unions will red — re-pin per the new members.**
+- `FileSystem.writeFileGuarded?` (+ `WriteExpectation` / `WriteReceipt`, both type-only exports):
+  optional atomic verify-and-write with a receipt of the real on-disk object, carrying
+  `writeFileExclusive`'s degradation law verbatim (a backend without the primitive leaves it
+  `undefined` rather than emulating it). New deployment knob `requireGuardedWrite` (default off,
+  byte-identical): armed, a covered write on an env lacking the capability is a typed refusal
+  instead of a silent fallback.
+- `UsageWindow.maxTokens` becomes optional (#480): a window may govern by `maxCostUsd` alone. A
+  window declaring NEITHER ceiling refuses loudly, the exhaustion arithmetic reads declared axes
+  only, and a `maxCostUsd` whose micro-USD conversion overflows is refused at the door instead of
+  being admitted and never binding (**named narrowing**: a dual window declaring such a ceiling
+  previously ran with its money arm silently dead).
+
+### Fixed
+- **#477 — the `before_agent_start` replacement prompt is run-scoped**: the between-turn rebuild
+  now carries it, so a run's prompt is byte-stable across its three legal change points (run start /
+  compaction-boundary epoch adoption / clear) instead of silently reverting to the base prompt from
+  turn 2 (which also broke prefix-cache stability). Deployments with no handler — or whose handler
+  returns no `systemPrompt` — are byte-identical.
+- **#482 / #486 — read-only command judgment, both directions**: the allowlist grows to CC's safe
+  command set (with per-verb availability guards), a classify-only superset admits `find`/`sed`/`cd`
+  behind CC's own guard grammars, and compound judgment now THREADS the base a `cd` actually moves —
+  every segment's containment *and* deny resolve against the base bash will have, and a poll-loop
+  body containing a `cd` is judged over its worst-case iterated shift. Two escapes are closed (an
+  iterated `cd ..` loop climbing out of the read roots; a `cd` eating the first segment of a
+  multi-segment deny pattern). **This is a judgment fix, not a narrowing**: legitimately-configured
+  full-read deployments keep zero-ask on the same commands, pinned by positive controls carrying the
+  same weight as the escape pins.
+- **#473** the resume verb snapshots its config once at the door (a mutated bag can no longer make
+  the identity gate and the resumed leg disagree); **#474** the prompt-too-long recovery lane adopts
+  the rebuilt prompt and honours the turn-scoped abort; **#470/#475** a workflow run that overran
+  its token ceiling discloses it on the list projection as well as the full record; **#468**
+  `SubagentSteerHandle.steer` gains the `inputId` pass-through its workflow twin already had.
+
+
 ## 5.63.0 — 2026-08-27
 
 ### BREAKING

package/dist/agents/cascade.d.ts

@@ -199,6 +199,10 @@ export declare function runCascade(runner: Runner, spec: TaskSpec, config: Casca
  * what teardown does to the workspace is the factory's business.
  *
  * Absent ⇒ every rung is dispatched exactly as before (the call site passes `undefined`, which is
- * what an omitted optional argument already was).
+ * what an omitted optional argument already was) — with ONE design/380 O1② placement delta either
+ * way: when neither `placementRoot` nor `rootSessionId` is present, rungs after the first are
+ * dispatched with a fresh shallow copy carrying `placementRoot` = the first rung's resolved
+ * sessionId (the ladder's placement fixed point); every other field still rides by the same
+ * reference, and an internals object that already carries a fixed point is forwarded verbatim.
  */
 internals?: RunInternals): Promise<CascadeRunResult>;

package/dist/agents/cascade.js

@@ -57,6 +57,7 @@ export async function runCascade(runner, spec, config, internals) {
     });
     let lastResult;
     let passedRung = -1;
+    let ladderPlacementRoot;
     const { sessionId: _drop, ...specBase } = spec;
     for (let i = 0; i < maxRungs; i++) {
         if (deadlineAt !== undefined && Date.now() >= deadlineAt)
@@ -81,14 +82,18 @@ export async function runCascade(runner, spec, config, internals) {
                 ? AbortSignal.any([specBase.signal, rungAbort.signal])
                 : rungAbort.signal;
         let result;
+        const rungInternals = ladderPlacementRoot === undefined || internals?.placementRoot !== undefined || internals?.rootSessionId !== undefined
+            ? internals
+            : { ...internals, placementRoot: ladderPlacementRoot };
         try {
-            result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(rungSignal ? { signal: rungSignal } : {}) }, internals);
+            result = await runner.runTask({ ...specBase, model: rung.model, ...(rung.overrides ?? {}), ...(rungSignal ? { signal: rungSignal } : {}) }, rungInternals);
         }
         finally {
             if (deadlineTimer !== undefined)
                 clearTimeout(deadlineTimer);
         }
         lastResult = result;
+        ladderPlacementRoot ??= internals?.placementRoot ?? internals?.rootSessionId ?? result.sessionId;
         const s = result.stats;
         const rungCostKnown = s.costMicroUsd !== undefined && (s.nested === undefined || s.nested.costMicroUsd !== undefined);
         const rungCost = rungCostKnown ? (s.costMicroUsd ?? 0) + (s.nested?.costMicroUsd ?? 0) : undefined;

package/dist/agents/subagent.js

@@ -1967,6 +1967,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(ctx.taskId !== undefined ? { parentTaskId: ctx.taskId } : {}),
                         ...(ctx.sessionId !== undefined ? { parentSessionId: ctx.sessionId } : {}),
                         ...((ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}),
+                        ...(ctx.placementRoot !== undefined ? { placementRoot: ctx.placementRoot } : {}),
                     }),
                 ...(ctx.centerArtifactDigest !== undefined ? { parentCenterArtifactDigest: ctx.centerArtifactDigest } : {}),
                 ...(ctx.centerSourceRevision !== undefined ? { parentCenterSourceRevision: ctx.centerSourceRevision } : {}),

package/dist/agents/verify.d.ts

@@ -287,7 +287,11 @@ export declare function verifyCompleted(runner: Runner, result: TaskResult, spec
  * refusal does and does not undo.
  *
  * Absent ⇒ every leg is dispatched exactly as before (each call site passes `undefined`, which is
- * what an omitted optional argument already was).
+ * what an omitted optional argument already was) — with ONE design/380 O1② placement delta either
+ * way: when neither `placementRoot` nor `rootSessionId` is present, the verifier and fix legs are
+ * dispatched with a fresh shallow copy carrying `placementRoot` = the entry implementation leg's
+ * sessionId (the gate's placement fixed point); every other field still rides by the same
+ * reference, and an internals object that already carries a fixed point is forwarded verbatim.
  */
 internals?: RunInternals): Promise<VerificationResult>;
 /**

package/dist/agents/verify.js

@@ -129,6 +129,9 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
     };
     const evidenceMode = config.evidence != null && config.evidence.trim() !== "";
     const verifierPrompt = config.verifierPrompt ?? (evidenceMode ? STATIC_VERIFICATION_PROMPT : VERIFICATION_PROMPT);
+    const legInternals = () => internals?.placementRoot !== undefined || internals?.rootSessionId !== undefined
+        ? internals
+        : { ...internals, placementRoot: result.sessionId };
     const runVerifier = async (impl, round) => {
         refuseUnhonorableInternals(internals, "before_leg");
         const roundEvidence = round === 1 ? config.evidence : undefined;
@@ -162,7 +165,7 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             ...(specBase.clientContext !== undefined ? { clientContext: { ...specBase.clientContext } } : {}),
             ...(specBase.promptProfile !== undefined ? { promptProfile: specBase.promptProfile } : {}),
             signal: specBase.signal,
-        }, internals);
+        }, legInternals());
         try {
             const cost = (v.stats.costMicroUsd ?? 0) + (v.stats.nested?.costMicroUsd ?? 0);
             return { verdict: v.structuredOutput, cost, ...(isDurablePause(v.status) ? { paused: v } : {}) };
@@ -242,7 +245,7 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
             objective: fixObjective(outcome.findings),
             ...(foldedRootsFace ? { readFace: "roots" } : {}),
             ...(foldedReadDeny.length > 0 ? { readDenyPatterns: [...foldedReadDeny] } : {}),
-        }, internals);
+        }, legInternals());
         spend += (current.stats.costMicroUsd ?? 0) + (current.stats.nested?.costMicroUsd ?? 0);
         implAccount.add(current.stats);
         if (isDurablePause(current.status)) {

package/dist/core/checkpoint-store.d.ts

@@ -349,7 +349,11 @@ export interface PendingSteerEntry {
     seq: number;
     /** Caller-supplied correlation/idempotency id (a service passes the message id it already minted);
      *  a uuidv7 is minted when absent. Re-appending the SAME `inputId` is a no-op, which is what keeps
-     *  `setPendingSteer` retry-safe now that it appends instead of overwriting. */
+     *  `setPendingSteer` retry-safe now that it appends instead of overwriting. Because the id lives on
+     *  the PERSISTED entry and every replayed drain of this row carries it verbatim, `(notice code,
+     *  sessionId, detail.inputId)` is the parked family's cross-replay OCCURRENCE key — consumers dedup
+     *  on it directly; no per-delivery key exists or is needed. (Write-path guarantee: a row written by
+     *  a non-conforming store may lack it, and read points do not re-validate.) */
     inputId: string;
     /** Carried VERBATIM for the serving layer; it does NOT reorder the drain (drain is `seq` order). */
     priority?: SystemInjectionPriority;
@@ -1156,6 +1160,43 @@ export interface CheckpointState {
      * delegated child (never `false` — presence-coded like the other monotonic bits here).
      */
     isDelegatedChild?: true;
+    /**
+     * design/380 O1③ — the run TREE's placement fixed point at suspend: the SAME three-segment fold the
+     * env-factory ctx mint uses (explicit `RunInternals.placementRoot` > the delegation lanes'
+     * `rootSessionId` > the leg's own resolved session), stamped from TRUSTED internals so a durable
+     * resume can restore it instead of falling back to the parked leg's own session (a target-bound
+     * factory keys its placement lookup on the fixed point — the self fallback read a resumed leg as a
+     * NEW placement). Restore is the `isDelegatedChild` posture replayed on the placement axis: an
+     * EXPLICIT live `internals.placementRoot` wins when re-supplied; otherwise THIS key restores into
+     * `internals.placementRoot` at prepare so descendants and the NEXT re-suspend mint inherit it too
+     * — outranking a supplied `rootSessionId`, which is DELEGATION IDENTITY (the peer/registry axis a
+     * revive leg re-supplies from its row), never a placement claim (rescan C1: reading it as one
+     * permanently stuck every parked agent spawned under an explicit placement root). The resume entry
+     * ALSO reads this key as an identity record: a resume whose supplied `internals.placementRoot`
+     * CONTRADICTS it is refused pre-CAS (`resume.placement_mismatch`); either side absent skips the
+     * check (an older row / a claim-less resume — the honest degradation arm), and `""` reads as
+     * absence (the identity fields' discipline). Schema ADDITION (additive, old readers ignore it — the Q5 posture;
+     * deliberately NOT version-gated: same rolling-deployment account as {@link Checkpoint.principal},
+     * whose doc records version-gating as a design candidate — any new stamp is a lattice-wide window
+     * rewrite, owned by that ticket, not ad-hoc here). Absent ⇒ minted before the field, or the fold
+     * resolved empty on a factory-less run (never persisted as garbage).
+     */
+    placementRootSessionId?: string;
+    /**
+     * design/380 O9a — MONOTONIC presence bit: this run's hand-tool content fold was EXTERNAL-TARGET
+     * armed (the env declared `ExecutionEnv.externalContentTarget`, or an earlier leg of this suspend
+     * chain did). Stamped at the suspend mint from the run's RESOLVED fold state — never from first
+     * tool use, so a park landing BEFORE the first hand call is covered too. Presence-coded like
+     * {@link isDelegatedChild} (absent = never armed; never `false`). The resume side folds
+     * **persisted OR live declaration** (a monotonic join, never a downgrade): a run minted under a
+     * declaring adapter keeps its memory fold and its prompt disclosure when resumed on an
+     * undeclared/older adapter — the downgrade is closed in the derivation itself, deliberately
+     * WITHOUT a new refusal arm (one fewer failure path, same safety). Feeds the memory face and the
+     * prompt disclosure only — no gate/policy/roster behavior reads it (the design/378 red line).
+     * Schema ADDITION (additive, Q5 posture; the version-gate residual is shared with
+     * {@link placementRootSessionId} above and owned by the same version-lattice ticket).
+     */
+    externalContentTarget?: true;
 }
 /**
  * {@link CheckpointState} with **every** field made required-PRESENT, while each value keeps its original
@@ -1865,6 +1906,30 @@ export declare class CheckpointError extends Error {
      *  refusal exists to close. Rejected PRE-CAS (the checkpoint stays `pending`); re-resume with the
      *  original principal, or omit the field to inherit the recorded one. */
      | "resume.principal_mismatch"
+    /** design/380 O1③ (placement identity continuity — the `resume.principal_mismatch` rung's twin
+     *  on the placement axis): the resume supplied trusted internals whose EXPLICIT
+     *  `placementRoot` differs from the {@link CheckpointState.placementRootSessionId} recorded at
+     *  the suspend mint. A target-bound env factory keys its placement lookup on that fixed point,
+     *  so silently resuming under a different one would re-place the leg — and every descendant
+     *  the child-internals chain hands it to — on another target than the parked workspace lives
+     *  on. A supplied `rootSessionId` deliberately does NOT take this refusal (rescan C1): it is
+     *  delegation identity, re-supplied by every revive leg, and legitimately differs from the
+     *  recorded root whenever the spawner carried an explicit placement — the recorded root simply
+     *  outranks it in prepare's restore fold. Rejected PRE-CAS (the checkpoint stays `pending`);
+     *  re-resume with the recorded root, or omit `internals.placementRoot` to inherit it. Either
+     *  side absent (an older row / a claim-less resume) skips the check, and `""` reads as absence
+     *  — the honest degradation arm. */
+     | "resume.placement_mismatch"
+    /** design/380 O2: the deployment's `RunnerDeps.resumePreflight` refused this resume — an
+     *  explicit refusal verdict, a throw, a timeout past its bounded deadline, or an unreadable
+     *  answer (all fail-closed). The LAST rung before the CAS, so nothing was consumed. Two arms,
+     *  discriminated by the message: the default `retry_later` arm leaves the checkpoint `pending`
+     *  and the SAME token redeemable once the obstacle clears (`detail.retryAfterMs` carries the
+     *  deployment's wait hint when it gave one — the #449 G1 carrier); the explicit `terminal` arm
+     *  has ALREADY settled the row out of `pending` via the single-shot `expire` CAS (reaper
+     *  parity) before this throw — the token is NOT redeemable, by the deployment's own permanent
+     *  verdict (a dead binding must not be redialed forever). */
+     | "resume.preflight_rejected"
     /** F-012 L3: the resume carried an approver EDIT (`updatedInput`) and a FROZEN inherited ancestor
      *  constraint (the persisted projection chain) — or the deployment's resume-edit policy — DENIES the
      *  edited args. Refused PRE-CAS with fresh-redecision semantics: the checkpoint stays `pending` and
@@ -1892,8 +1957,11 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     readonly detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
-        /** #449 G1 — on `resume.usage_window_exhausted` ONLY: how long until the binding window frees
-         *  (the same wait a suspended row carries as `gate.resumeAfterMs`). Absent on every other code. */
+        /** #449 G1 — on `resume.usage_window_exhausted`: how long until the binding window frees
+         *  (the same wait a suspended row carries as `gate.resumeAfterMs`). design/380 O2 — on a
+         *  retry-later `resume.preflight_rejected`: the deployment preflight's own wait hint, when it
+         *  gave one (same carrier, same semantics: retry the SAME token after the wait). Absent on
+         *  every other code. */
         retryAfterMs?: number;
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is
@@ -2020,6 +2088,30 @@ export declare class CheckpointError extends Error {
      *  refusal exists to close. Rejected PRE-CAS (the checkpoint stays `pending`); re-resume with the
      *  original principal, or omit the field to inherit the recorded one. */
      | "resume.principal_mismatch"
+    /** design/380 O1③ (placement identity continuity — the `resume.principal_mismatch` rung's twin
+     *  on the placement axis): the resume supplied trusted internals whose EXPLICIT
+     *  `placementRoot` differs from the {@link CheckpointState.placementRootSessionId} recorded at
+     *  the suspend mint. A target-bound env factory keys its placement lookup on that fixed point,
+     *  so silently resuming under a different one would re-place the leg — and every descendant
+     *  the child-internals chain hands it to — on another target than the parked workspace lives
+     *  on. A supplied `rootSessionId` deliberately does NOT take this refusal (rescan C1): it is
+     *  delegation identity, re-supplied by every revive leg, and legitimately differs from the
+     *  recorded root whenever the spawner carried an explicit placement — the recorded root simply
+     *  outranks it in prepare's restore fold. Rejected PRE-CAS (the checkpoint stays `pending`);
+     *  re-resume with the recorded root, or omit `internals.placementRoot` to inherit it. Either
+     *  side absent (an older row / a claim-less resume) skips the check, and `""` reads as absence
+     *  — the honest degradation arm. */
+     | "resume.placement_mismatch"
+    /** design/380 O2: the deployment's `RunnerDeps.resumePreflight` refused this resume — an
+     *  explicit refusal verdict, a throw, a timeout past its bounded deadline, or an unreadable
+     *  answer (all fail-closed). The LAST rung before the CAS, so nothing was consumed. Two arms,
+     *  discriminated by the message: the default `retry_later` arm leaves the checkpoint `pending`
+     *  and the SAME token redeemable once the obstacle clears (`detail.retryAfterMs` carries the
+     *  deployment's wait hint when it gave one — the #449 G1 carrier); the explicit `terminal` arm
+     *  has ALREADY settled the row out of `pending` via the single-shot `expire` CAS (reaper
+     *  parity) before this throw — the token is NOT redeemable, by the deployment's own permanent
+     *  verdict (a dead binding must not be redialed forever). */
+     | "resume.preflight_rejected"
     /** F-012 L3: the resume carried an approver EDIT (`updatedInput`) and a FROZEN inherited ancestor
      *  constraint (the persisted projection chain) — or the deployment's resume-edit policy — DENIES the
      *  edited args. Refused PRE-CAS with fresh-redecision semantics: the checkpoint stays `pending` and
@@ -2047,8 +2139,11 @@ export declare class CheckpointError extends Error {
      *  discriminant. */
     detail?: {
         field?: "boundCallId" | "boundInputHash" | "answer" | "settledBy" | "approver";
-        /** #449 G1 — on `resume.usage_window_exhausted` ONLY: how long until the binding window frees
-         *  (the same wait a suspended row carries as `gate.resumeAfterMs`). Absent on every other code. */
+        /** #449 G1 — on `resume.usage_window_exhausted`: how long until the binding window frees
+         *  (the same wait a suspended row carries as `gate.resumeAfterMs`). design/380 O2 — on a
+         *  retry-later `resume.preflight_rejected`: the deployment preflight's own wait hint, when it
+         *  gave one (same carrier, same semantics: retry the SAME token after the wait). Absent on
+         *  every other code. */
         retryAfterMs?: number;
         /** WHICH pre-CAS refusal arm fired, where one `code` covers several (requested 2026-08-10: a
          *  deployment retry policy needs to tell "a newer worker can redeem this row" from "this row is

package/dist/core/fs-write-gate-policy.d.ts

@@ -38,6 +38,27 @@ export interface FsWriteGatePolicyOptions {
      *    asks for an UNRESOLVABLE target fire before any canonical key exists, so they are never exempted.
      */
     isExempt?: (toolName: string, canonicalPath: string) => boolean | Promise<boolean>;
+    /**
+     * design/380 O13 — the deployment HARD-CLOSE knob for guarded writes. Armed (`true`), a covered
+     * write whose env does NOT provide `writeFileGuarded` is REFUSED (deny, typed message) — never the
+     * plain-writeFile fallback: for a deployment that exists to close the adjudicate→write TOCTOU
+     * window, a silent advisory downgrade would open the hole right beside its patch. The version-skew
+     * arm is the same refusal (an older adapter without the method IS an env without the capability).
+     * Default off = every verdict ACTION exactly as before (the capability's ABSENCE is still disclosed
+     * on the ask face either way — see the advisory sentence at the ask sites). The knob lives on the
+     * deployment's gate options, not in core-global state: core stays lane-agnostic (no device concept
+     * here); the deployment that runs guarded-capable envs arms it.
+     *
+     * WHAT ARMED DOES AND DOES NOT CLOSE (honesty boundary, codex r1-1): armed guarantees every covered
+     * write lands through an ATOMIC precondition-verified backend step — the tool's own
+     * canonicalize→write window is closed. It does NOT yet bind THIS GATE's adjudicated canonical key
+     * across an approval wait: the tool re-canonicalizes at execute time, so a symlink swapped between
+     * this gate's verdict and the tool's execution is re-resolved (and then atomically verified against
+     * the NEW resolution). Closing that remaining window needs the adjudicated key carried through a
+     * trusted approval receipt into tool execution — a separate seat, deliberately not smuggled into
+     * this knob.
+     */
+    requireGuardedWrite?: boolean;
 }
 /**
  * Build the file-write approval gate policy. Mount via `combinePolicies` alongside the deployment's

package/dist/core/fs-write-gate-policy.js

@@ -6,18 +6,29 @@ export function createFsWriteGatePolicy(opts) {
     const gated = PATH_CONFINABLE_WRITE_TOOLS;
     const acceptDirs = opts.acceptDirs && opts.acceptDirs.length > 0 ? opts.acceptDirs : undefined;
     const exemptDirs = opts.exemptDirs && opts.exemptDirs.length > 0 ? opts.exemptDirs : undefined;
+    const guardedCapable = env.writeFileGuarded !== undefined;
+    const advisory = guardedCapable
+        ? ""
+        : " (advisory adjudication: this environment provides no guarded write, so approval is judged before a separate, non-atomic write step)";
     return {
         async check(req, signal) {
             const canonical = req.toolName;
             if (!gated.has(canonical))
                 return { action: "allow" };
+            if (opts.requireGuardedWrite === true && !guardedCapable) {
+                return {
+                    action: "deny",
+                    message: `write tool "${req.toolName}" refused: this deployment requires guarded (atomic precondition-verified) writes (requireGuardedWrite), but the execution environment provides no writeFileGuarded capability — refusing rather than falling back to a non-atomic write`,
+                    decisionReason: "rule",
+                };
+            }
             const path = writeTargetPath(canonical, req.args);
             if (path === undefined) {
-                return ask(`write tool "${req.toolName}" requires approval: the call has no resolvable path target to confine`);
+                return ask(`write tool "${req.toolName}" requires approval: the call has no resolvable path target to confine${advisory}`);
             }
             const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
             if (!canon.ok) {
-                return ask(`write to "${path}" requires approval: its real target could not be resolved (${canon.message})`);
+                return ask(`write to "${path}" requires approval: its real target could not be resolved (${canon.message})${advisory}`);
             }
             for (const dirs of [exemptDirs, acceptDirs]) {
                 if (!dirs)
@@ -46,7 +57,7 @@ export function createFsWriteGatePolicy(opts) {
             }
             if (defaultWrite === "allow")
                 return { action: "allow" };
-            return ask(`approve write to "${path}"?`);
+            return ask(`approve write to "${path}"?${advisory}`);
         },
     };
 }

package/dist/core/hooks.d.ts

@@ -278,6 +278,10 @@ export interface Hooks {
  * answer in a second says so with `timeoutMs`.
  */
 export declare const DEFAULT_HOOK_TIMEOUT_MS = 600000;
+/** `setTimeout`'s own ceiling: above it the platform silently clamps to ~1ms, which would turn a
+ *  deployment's "very long bound" into an instant expiry it never asked for. Refused loudly instead
+ *  (same ceiling, same posture as the gate's `approvalTimeoutMs`). */
+export declare const MAX_HOOK_TIMEOUT_MS = 2147483647;
 /**
  * How long an observation seat still gets when the task is cancelled `elapsed` ms into its wait — the
  * grace, capped by what is LEFT of the declared deadline.
@@ -303,7 +307,11 @@ export declare function postAbortGraceMs(remainingMs: number): number;
  */
 export declare function resolveHookTimeoutMs(supplied: number | undefined, report?: (err: unknown) => void, owner?: object): number;
 /** The ten {@link Hooks} callback seats, named so a bound wait can say WHICH one did not answer. */
-export type HookSeatName = "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "stop" | "stopFailure" | "preCompact" | "postCompact" | "permissionDenied";
+export type HookSeatName = "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "stop" | "stopFailure" | "preCompact" | "postCompact" | "permissionDenied"
+/** design/380 O2 — not a {@link Hooks} record seat: the `RunnerDeps.resumePreflight` deployment
+ *  callback, run through the same bounded-wait home so the pre-CAS resume ladder cannot grow its
+ *  own dialect of "a deployment callback gets a deadline". */
+ | "resumePreflight";
 /** What one bounded seat invocation produced: the seat's own value, or the fact that the wait ended
  *  first. A seat that THREW is neither — the throw propagates out of {@link runHookSeat} unchanged, so
  *  each site's existing crash arm keeps owning it. */

package/dist/core/hooks.js

@@ -7,7 +7,7 @@ import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 export const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
-const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
+export const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
 const POST_ABORT_GRACE_MS = 1_000;
 export function postAbortGraceMs(remainingMs) {
     return Math.max(0, Math.min(POST_ABORT_GRACE_MS, remainingMs));

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

@@ -63,6 +63,9 @@ export function mergeHarvestReports(a, b) {
         restored: [...a.restored, ...b.restored],
         warnings: [...a.warnings, ...b.warnings],
     };
+    const reportId = a.reportId ?? b.reportId;
+    if (reportId !== undefined)
+        merged.reportId = reportId;
     const incident = a.incident ?? b.incident;
     if (incident !== undefined)
         merged.incident = incident;

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

@@ -443,6 +443,7 @@ export declare function memoryHarvestQuarantinedNotice(input: {
     sessionId?: string;
     provenance?: "off" | "carry";
     indexRolledBack?: boolean;
+    reportId?: string;
 }): EngineNotice;
 /**
  * design/336 §6.3 — the hold family's operator notices, derived from ONE harvest report's

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

@@ -111,12 +111,13 @@ export function pollutionContainmentCounts(report) {
 }
 export function memoryHarvestQuarantinedNotice(input) {
     const reason = input.reason !== undefined ? inlineUntrusted(input.reason, 200) : undefined;
+    const reportId = input.reportId !== undefined ? { reportId: input.reportId } : {};
     if (input.count === 0 && input.indexRolledBack === true) {
         return {
             code: "memory.harvest_quarantined",
             message: `Memory harvest rolled the derived index (MEMORY.md) back to its materialize-time baseline${reason !== undefined ? ` (${reason})` : ""}: ` +
                 `this session's index prose additions were captured to control-plane quarantine and not retained. No entry files were withheld.`,
-            detail: { count: 0, moved: 0, escalated: 0, indexRolledBack: true, ...(reason !== undefined ? { reason } : {}), ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}) },
+            detail: { count: 0, moved: 0, escalated: 0, indexRolledBack: true, ...reportId, ...(reason !== undefined ? { reason } : {}), ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}) },
         };
     }
     const lead = input.provenance === "carry"
@@ -135,6 +136,7 @@ export function memoryHarvestQuarantinedNotice(input) {
             count: input.count,
             moved: input.moved,
             escalated: input.escalated,
+            ...reportId,
             ...(reason !== undefined ? { reason } : {}),
             ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
         },
@@ -145,6 +147,7 @@ export function memoryHoldNotices(report, sessionId) {
     if (c === undefined)
         return [];
     const caps = (paths) => paths.slice(0, 20).map((p) => inlineUntrusted(p, 160));
+    const reportId = report.reportId !== undefined ? { reportId: report.reportId } : {};
     const notices = [];
     if (c.heldInstruction.length > 0) {
         notices.push({
@@ -152,14 +155,14 @@ export function memoryHoldNotices(report, sessionId) {
             message: `Memory harvest HELD ${c.heldInstruction.length} instruction-form entry file(s): this session's delegation outcome ` +
                 `is still pending, so instruction entries wait off the model-visible plane and commit automatically once every ` +
                 `delegation settles clean (a dirty or expired settlement disposes them to quarantine, announced; resolveHold is the host valve).`,
-            detail: { count: c.heldInstruction.length, paths: caps(c.heldInstruction), ...(sessionId !== undefined ? { sessionId } : {}) },
+            detail: { count: c.heldInstruction.length, paths: caps(c.heldInstruction), ...reportId, ...(sessionId !== undefined ? { sessionId } : {}) },
         });
     }
     if (c.releasedHolds.length > 0) {
         notices.push({
             code: "memory.hold_released",
             message: `Memory harvest RELEASED ${c.releasedHolds.length} held instruction entry file(s) — their writer sessions settled clean (or a host valve released them) and the entries re-walked the full gate set and committed.`,
-            detail: { count: c.releasedHolds.length, paths: caps(c.releasedHolds), ...(sessionId !== undefined ? { sessionId } : {}) },
+            detail: { count: c.releasedHolds.length, paths: caps(c.releasedHolds), ...reportId, ...(sessionId !== undefined ? { sessionId } : {}) },
         });
     }
     if (c.disposedHolds.length > 0) {
@@ -168,7 +171,7 @@ export function memoryHoldNotices(report, sessionId) {
             message: `Memory harvest DISPOSED ${c.disposedHolds.length} held instruction entry file(s) to control-plane quarantine ` +
                 `(terminals: ${[...new Set(c.disposedHolds.map((d) => d.terminal))].join(", ")}). An "expired" terminal is a TIMEOUT, not a ` +
                 `conviction — resolveHold(holdId, "release") commits such an entry with a "static"-cause marker after host review; the bytes are never silently dropped.`,
-            detail: { count: c.disposedHolds.length, disposed: c.disposedHolds.slice(0, 20).map((d) => ({ path: inlineUntrusted(d.relPath, 160), terminal: d.terminal })), ...(sessionId !== undefined ? { sessionId } : {}) },
+            detail: { count: c.disposedHolds.length, disposed: c.disposedHolds.slice(0, 20).map((d) => ({ path: inlineUntrusted(d.relPath, 160), terminal: d.terminal })), ...reportId, ...(sessionId !== undefined ? { sessionId } : {}) },
         });
     }
     return notices;
@@ -180,7 +183,7 @@ export function memoryConsolidationRecommendedNotice(report, sessionId) {
     return {
         code: "memory.consolidation_recommended",
         message: `Memory consolidation is recommended for scope ${inlineUntrusted(rec.scope, 80)}: ${rec.sessionsSince} distinct session(s) harvested since the last run and the time gate is open. The host decides — nothing runs automatically.`,
-        detail: { scope: inlineUntrusted(rec.scope, 80), sessionsSince: rec.sessionsSince, ...(sessionId !== undefined ? { sessionId } : {}) },
+        detail: { scope: inlineUntrusted(rec.scope, 80), sessionsSince: rec.sessionsSince, ...(report.reportId !== undefined ? { reportId: report.reportId } : {}), ...(sessionId !== undefined ? { sessionId } : {}) },
     };
 }
 export function memoryConsolidationCommittedNotice(input) {
@@ -1279,6 +1282,7 @@ export class MemoryEngine {
                 arr.push(rel);
         };
         const report = {
+            reportId: uuidv7(),
             ok: true,
             patches: { add: 0, update: 0, delete: 0 },
             conflicts: [],

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

@@ -497,6 +497,22 @@ export interface MemoryAnnouncement {
  * structure; the runner's boundary-announcement wiring (attachments member) lands in S2 (TODO(S2)).
  */
 export interface HarvestReport {
+    /** #479 — this report's own per-occurrence identity: a uuidv7 minted ONCE where the engine
+     *  creates the report (`harvestCore`'s single literal — every exit path, including the refused
+     *  and zero-admission arms, returns that one object), and read wherever a derived face needs to
+     *  name this harvest: the `memory.harvest_quarantined` + `memory.hold_*` notice family carries
+     *  it as `detail.reportId`. Occurrence semantics, both directions: two harvests whose counts and
+     *  paths happen to coincide are two facts and get two ids (the un-dedupable five-key repeat this
+     *  member exists to break), while every notice derived from ONE report shares the one id — a
+     *  consumer's dedup key is therefore `(code, reportId)`, never `reportId` alone. The report is
+     *  transient (delivered via `RunnerDeps.onMemoryHarvestReport` and the notice lane; the engine
+     *  persists no report row), so replay-stability comes from the id riding whatever record the
+     *  HOST persists: a durable replay re-reads the recorded value, a genuinely new harvest mints a
+     *  new one — per-delivery minting (the fail-open shape) is exactly what this seat avoids.
+     *  Optional in the TYPE only for hand-built reports (external constructors,
+     *  `mergeHarvestReports` inputs); every engine-minted report carries it, and the notice
+     *  factories OMIT the detail key rather than invent one when it is absent. */
+    reportId?: string;
     /** False ⇔ the whole harvest was refused (deletion fuse / missing dir / corrupt sidecar incident). */
     ok: boolean;
     /** Set when a fuse tripped (§2.4 删除防线 / B3 fail-closed): the harvest is refused wholesale, NO

package/dist/core/remote-env.d.ts

@@ -58,6 +58,13 @@ export interface WorkspaceHandle {
      *  `snapshotId` as corruption (fail-closed) unless the resumed env is itself non-suspendable
      *  (tolerance for park handles minted by 1.257.1 before this field existed). */
     restoreMode?: "park_only";
+    /**
+     * design/380 O1④ — explicit identity of the physical/target device this workspace lives on
+     * (device lane; an SSH/ADB adapter MAY also stamp it). MINTER-STATED: consumers read this field,
+     * never parse an identity out of `sandboxId`. Plain string → rides CheckpointState.workspaceHandle
+     * (all-string whitelist) with zero schema movement.
+     */
+    deviceId?: string;
 }
 /**
  * A reference to a secret injected at {@link RemoteExecutionEnv.connect}/{@link RemoteExecutionEnv.postResumeInit}
@@ -213,6 +220,16 @@ export type RemoteExecutionErrorCode =
  * else a retry whitelist misses them.
  */
  | "transport_lost"
+/**
+ * design/380 O12 — the op was COMMITTED to the remote target and its outcome is UNKNOWABLE (the target
+ * went unreachable / restarted / was revoked after dispatch-commit; an execStream cut where the target
+ * protocol's own server has ruled the outcome unknowable). NEVER auto-retried and deliberately NOT in
+ * {@link RETRYABLE_REMOTE_ERROR_CODES}: the command may have already executed — a retry whitelist that
+ * contained it would re-drive committed side effects. Distinct from `transport_lost` (connection story
+ * known, idempotency-gated retry after reconnect). Message MUST carry the verify-first sentence ("may
+ * have already executed on the target; verify its effect before re-running").
+ */
+ | "outcome_unknown"
 /** Unclassified provider/transport failure. */
  | "unknown";
 /**
@@ -220,8 +237,10 @@ export type RemoteExecutionErrorCode =
  * can succeed (`auth_transient`: retry-exactly-once after the device is authorized; `connect_failed`: the
  * workspace could not be reached/provisioned this attempt; `timeout`: a liveness bound tripped;
  * `transport_lost`: re-establish the connection). Every OTHER code is permanent for this attempt
- * (`auth_failed`/`unsupported`), caller-driven (`aborted`), or unclassifiable (`unknown`) — retrying them
- * burns budget or, worse, re-drives a rejected credential.
+ * (`auth_failed`/`unsupported`), caller-driven (`aborted`), unclassifiable (`unknown`), or
+ * outcome-unknowable (`outcome_unknown` — design/380 O12: the op may have ALREADY executed, so a retry
+ * re-drives committed side effects) — retrying them burns budget or, worse, re-drives a rejected
+ * credential or a committed op.
  *
  * ONE list, two consumers, so a caller's retry decision and its DISCLOSURE can never disagree: the engine
  * retries only IDEMPOTENT ops on these codes (see {@link withRetry}'s red line — a snapshot-taking
@@ -405,6 +424,19 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
 export interface ExecutionEnvFactoryContext {
     /** Resolved session id for the task — the stable identity of its per-task workspace. */
     sessionId: string;
+    /**
+     * design/380 O1① — the run TREE's placement root (fixed point), minted by prepare AFTER session
+     * resolution as `internals.placementRoot ?? internals.rootSessionId ?? sessionId` — a top-level
+     * run's own resolved sessionId, every descendant's inherited root, verbatim (delegation and
+     * workflow spawn chains re-thread an explicit `placementRoot` — C12; a bare DURABLE RESUME crosses
+     * too since design/380 O1③: the suspend mint stamps the fixed point on the checkpoint and the
+     * resume restores it into trusted internals — formerly the pinned residual). A target-bound
+     * factory (device lane) keys its placement lookup on THIS, never on `sessionId` (a child's fresh
+     * session id must not read as a new placement). Always present and non-empty — an empty value is
+     * an assembly error the engine refuses loudly at the mint (`config.placement_root_invalid`) and a
+     * factory MUST refuse loudly too (loud-bad-value posture), never default around.
+     */
+    placementRootSessionId: string;
     /** Caller-supplied task id, when set on the `TaskSpec`. */
     taskId?: string;
     /**