@sema-agent/core 5.64.0 → 5.65.0

package/dist/core/runner/runtask.js

@@ -36,13 +36,13 @@ import { cacheFamilyOf, usageCostMicroUsd } from "./usage-accounting.js";
 import { assembleResult, errorCodeOf } from "./assemble-result.js";
 import { ATTACHMENT_BYTE_CAP, CHANGED_FILES_MAX, AGENT_LISTING_REMOVED_HEADER, SKILLS_LISTING_DELTA_HEADER, SKILLS_LISTING_REMOVED_HEADER, advanceCadenceClock, agentListingDeltaHeader, attachmentEnvelopeTags, agentListingInitialHeader, replayAnnouncedListing, replayAnnouncedModels, clipToBytes, collectDateChange, collectDueAttachments, collectInstructionsChange, commitAgentListing, commitInstructionsChange, commitSkillsListing, createAttachmentState, rebaseCadenceWindows, reduceToolEnd, renderAgentListingDelta, renderMcpDroppedTools, renderMcpInstructionsDelta, renderOrphanedBackgroundTasks, selectMcpDroppedBatch, renderSkillsListingDelta, renderToolsDelta, stampWriteAnchor } from "./turn-attachments.js";
 import { buildWorkingFileAttachments, centerAdoptionOption, emitInputTruncated, forkContextOption } from "./compaction-call-options.js";
-import { effectiveDelegationFacts, gatedCallIdOf, prepareTask, resolveCheckpointStore } from "./prepare-task.js";
+import { effectiveDelegationFacts, gatedCallIdOf, placementValueOrAbsent, prepareTask, resolveCheckpointStore } from "./prepare-task.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 import { TOOL_SEARCH_NAME } from "./tool-disclosure.js";
 import { hasVerifiableStructureSignal } from "./grounding-signal.js";
 import { hasDestroy, isIsolated } from "../remote-env.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
-import { cloneObserverInput, formatHookFeedback, hookSeatExpiredError, mintHookInvocationIdentity, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
+import { cloneObserverInput, formatHookFeedback, hookSeatExpiredError, MAX_HOOK_TIMEOUT_MS, mintHookInvocationIdentity, resolveHookTimeoutMs, runHookSeat } from "../hooks.js";
 import { buildHumanInputEvent, frameMidTurnUserInput, projectHumanInput } from "../human-input-projection.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY, sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
 import { appendInterruptionMarker, reconcileInterruptedSession } from "../session-reconcile.js";
@@ -84,6 +84,7 @@ function sameAcceptedSteerInput(a, b) {
         a.actor?.issuer === b.actor?.issuer);
 }
 const MAX_CONSECUTIVE_COMPACTION_FAILURES = 3;
+const RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS = 10_000;
 const STOP_HOOK_BLOCK_CAP = 8;
 const COMPACTION_REGROWTH_FACTOR = 1.5;
 const COMPACTION_FREED_EPSILON = 256;
@@ -1455,6 +1456,8 @@ export class Runner {
     snapshotTooLargeRoots = new Map();
     pendingSessionNotifications = new PendingSessionNotifications();
     parentConstraintRegistry = new Map();
+    suspendedEnvReaps = new Map();
+    locallyClaimedTokens = new Set();
     static PARENT_CONSTRAINT_REGISTRY_CAP = 1024;
     constructor(deps) {
         this.deps = deps;
@@ -1663,8 +1666,11 @@ export class Runner {
                 await this.runLocked(spec, queue, (r) => {
                     resultValue = r;
                     const pcs = internals?.inheritedGate?.parentConstraints;
+                    if (resume !== undefined)
+                        this.locallyClaimedTokens.delete(resume.cp.token);
                     if (resume !== undefined && r.checkpointToken !== resume.cp.token) {
                         this.parentConstraintRegistry.delete(resume.cp.token);
+                        this.suspendedEnvReaps.delete(resume.cp.token);
                     }
                     if (r.status === "suspended" && r.checkpointToken !== undefined && pcs !== undefined && pcs.length > 0) {
                         if (this.parentConstraintRegistry.size >= Runner.PARENT_CONSTRAINT_REGISTRY_CAP) {
@@ -1681,6 +1687,7 @@ export class Runner {
                     publishReady(h);
                 }, (s) => {
                     reapHandle = s;
+                    this.suspendedEnvReaps.set(s.token, s);
                 }, manualCompactRef, taskIdRef, resume, { ...(internals ?? {}), detachHub }, notifyRef, entryActor);
             }
             finally {
@@ -1698,6 +1705,7 @@ export class Runner {
             const reopenReason = code === "resume.tool_unavailable" ? "tool_unavailable" : "env_failed";
             const reopenable = resume !== undefined && resume.pendingActionStarted !== true && reopenReason !== undefined && !(resumeDecisionWasNegative(resume) && resume.decisionDelivered === true);
             let reopenCommitted = false;
+            let reopenStateUnknown = false;
             if (reopenable && resume?.onEnvRestoreFailed) {
                 try {
                     await resume.onEnvRestoreFailed(reopenReason);
@@ -1708,15 +1716,26 @@ export class Runner {
                     const original = err instanceof Error ? err : new Error(String(err));
                     const reopenMsg = reopenErr instanceof Error ? reopenErr.message : String(reopenErr);
                     const definitive = errorCodeOf(reopenErr) === "checkpoint.reopen_failed";
+                    reopenStateUnknown = !definitive;
                     err = Object.assign(new Error(definitive
                         ? `${reopenMsg} (original resume failure: ${original.message})`
                         : `checkpoint reopen threw mid-flight — state UNKNOWN, confirm via the checkpoint store before retrying: ${reopenMsg} (original resume failure: ${original.message})`, { cause: original }), { code: "checkpoint.reopen_failed" });
                     code = "checkpoint.reopen_failed";
                 }
             }
+            if (resume)
+                this.locallyClaimedTokens.delete(resume.cp.token);
             if (resume && !reopenCommitted) {
                 this.parentConstraintRegistry.delete(resume.cp.token);
                 await settleTeardownLeg(() => this.sessions.unpin?.(resume.cp.sessionId), "sessions.unpin (resume-failure leg)", (e) => this.deps.onError?.(e, { phase: "config", sessionId: resume.cp.sessionId }));
+                if (!reopenStateUnknown) {
+                    const failedReap = this.suspendedEnvReaps.get(resume.cp.token);
+                    this.suspendedEnvReaps.delete(resume.cp.token);
+                    if (failedReap?.env !== undefined && hasDestroy(failedReap.env)) {
+                        const failedEnv = failedReap.env;
+                        await settleTeardownLeg(() => failedEnv.destroy(), "terminal resume-failure env destroy", (e) => this.deps.onError?.(e, { phase: "config", sessionId: resume.cp.sessionId }));
+                    }
+                }
             }
             if (resultValue !== undefined) {
                 try {
@@ -1802,9 +1821,13 @@ export class Runner {
                 reportErr(err);
                 return;
             }
-            if (!won)
+            if (!won) {
+                if (!this.locallyClaimedTokens.has(rh.token))
+                    this.suspendedEnvReaps.delete(rh.token);
                 return;
+            }
             this.parentConstraintRegistry.delete(rh.token);
+            this.suspendedEnvReaps.delete(rh.token);
             if (rh.env && hasDestroy(rh.env)) {
                 try {
                     await rh.env.destroy();
@@ -4314,6 +4337,7 @@ export class Runner {
             throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome must be an object naming its gate (got ${outcome === null ? "null" : typeof outcome})`);
         }
         const config = typeof taskConfig === "object" && taskConfig !== null ? { ...taskConfig } : taskConfig;
+        internals = internals !== undefined ? { ...internals } : undefined;
         const store = resolveCheckpointStore(config, this.deps);
         if (!store) {
             throw new CheckpointError("checkpoint.not_found", "no CheckpointStore wired — cannot resume (set RunnerDeps.checkpointStore or taskConfig.checkpointStore)");
@@ -4694,6 +4718,15 @@ export class Runner {
                     "running the resumed leg under a different identity would move its usage-ledger bucket, scope derivation and attribution; " +
                     "refused pre-CAS (the checkpoint stays pending): re-resume with the original principal, or omit the field to inherit the recorded one");
             }
+            {
+                const recordedPlacementRoot = placementValueOrAbsent(cp.state.placementRootSessionId);
+                const suppliedPlacementRoot = placementValueOrAbsent(internals?.placementRoot);
+                if (recordedPlacementRoot !== undefined && suppliedPlacementRoot !== undefined && suppliedPlacementRoot !== recordedPlacementRoot) {
+                    throw new CheckpointError("resume.placement_mismatch", `the resume supplied explicit placement root ${JSON.stringify(suppliedPlacementRoot)} but this checkpoint recorded placement root ${JSON.stringify(recordedPlacementRoot)} at suspend — ` +
+                        "resuming under a different placement fixed point would re-place the leg (and its descendants) on another target; " +
+                        "refused pre-CAS (the checkpoint stays pending): re-resume with the recorded root, or omit internals.placementRoot to inherit it");
+                }
+            }
             const owesDelivery = outcomeGate !== "resource_limit" ||
                 readPendingSteerQueue(cp.state).length > 0 ||
                 (cp.state.runningBackgroundTasks?.length ?? 0) > 0;
@@ -4869,7 +4902,121 @@ export class Runner {
         if (outcomeForStore === undefined) {
             throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome (gate "${describeSuppliedValue(outcomeGate)}") matched the checkpoint gate but no lane captured it — refusing pre-CAS rather than passing the caller's live object to the store and the resumed run`);
         }
+        if (this.deps.resumePreflight !== undefined) {
+            const preflight = this.deps.resumePreflight;
+            const rawDeadline = this.deps.resumePreflightTimeoutMs;
+            let preflightTimeoutMs = RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS;
+            if (rawDeadline !== undefined) {
+                if (typeof rawDeadline === "number" && Number.isFinite(rawDeadline) && rawDeadline > 0 && rawDeadline <= MAX_HOOK_TIMEOUT_MS) {
+                    preflightTimeoutMs = rawDeadline;
+                }
+                else {
+                    try {
+                        this.deps.onError?.(new Error(`RunnerDeps.resumePreflightTimeoutMs is not a positive finite number within the seat ceiling of ${MAX_HOOK_TIMEOUT_MS}ms (got ${describeSuppliedValue(rawDeadline)}) — the resume preflight falls back to its own ${RESUME_PREFLIGHT_DEFAULT_TIMEOUT_MS}ms default`), { phase: "config", sessionId: cp.sessionId });
+                    }
+                    catch {
+                    }
+                }
+            }
+            const info = {
+                token,
+                sessionId: cp.sessionId,
+                ...(cp.state.placementRootSessionId !== undefined ? { placementRootSessionId: cp.state.placementRootSessionId } : {}),
+                ...(cp.principal ? { principal: cp.principal } : {}),
+                ...(cp.state.workspaceHandle !== undefined ? { workspaceHandle: structuredClone(cp.state.workspaceHandle) } : {}),
+                gateKind: cp.gate.kind,
+            };
+            const refusalTail = "; the checkpoint stays pending and the same token is redeemable once the obstacle clears";
+            let verdict;
+            try {
+                const seat = await runHookSeat("resumePreflight", {
+                    timeoutMs: preflightTimeoutMs,
+                    ...(resumeSignal !== undefined ? { signal: resumeSignal } : {}),
+                    abortEnds: true,
+                    onBadTimeout: (badErr) => {
+                        try {
+                            this.deps.onError?.(badErr instanceof Error ? badErr : new Error(String(badErr)), { phase: "hook", sessionId: cp.sessionId });
+                        }
+                        catch {
+                        }
+                    },
+                    owner: this.deps,
+                }, (sig) => preflight(info, sig));
+                if (seat.expired) {
+                    throw new CheckpointError("resume.preflight_rejected", seat.cause === "timeout"
+                        ? `the deployment's resumePreflight did not answer within its ${preflightTimeoutMs}ms deadline while screening this resume — refused fail-closed (retry-later arm)${refusalTail}`
+                        : `the resume was cancelled while the deployment's resumePreflight was still screening it — refused (retry-later arm)${refusalTail}`);
+                }
+                verdict = seat.value;
+            }
+            catch (preflightErr) {
+                if (preflightErr instanceof CheckpointError)
+                    throw preflightErr;
+                const err = preflightErr instanceof Error ? preflightErr : new Error(String(preflightErr));
+                try {
+                    this.deps.onError?.(err, { phase: "hook", sessionId: cp.sessionId });
+                }
+                catch {
+                }
+                throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight crashed while screening this resume (${inlineUntrusted(err.message)}) — refused fail-closed (retry-later arm)${refusalTail}`);
+            }
+            const verdictOk = verdict !== null && typeof verdict === "object" ? verdict.ok : undefined;
+            if (verdictOk !== true) {
+                const bag = verdict !== null && typeof verdict === "object" ? verdict : undefined;
+                const disposition = bag?.disposition;
+                const suppliedMessage = bag?.message;
+                const retryAfterMs = bag?.retryAfterMs;
+                const readableMessage = typeof suppliedMessage === "string" && suppliedMessage !== "" ? suppliedMessage : undefined;
+                const said = readableMessage !== undefined ? `: ${inlineUntrusted(readableMessage)}` : " (no readable verdict — fail-closed)";
+                if (disposition === "terminal" && readableMessage !== undefined) {
+                    this.locallyClaimedTokens.add(token);
+                    let settled;
+                    try {
+                        settled = await store.expire(token, cp.scope);
+                    }
+                    catch (expireErr) {
+                        this.locallyClaimedTokens.delete(token);
+                        throw expireErr;
+                    }
+                    if (!settled) {
+                        this.locallyClaimedTokens.delete(token);
+                        const live = await store.get(token);
+                        if (live?.status === "pending") {
+                            throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said}, but the row moved under this refusal (a concurrent resolve/reopen cycle) — nothing was settled here; the row is pending again, re-resume against the current state (the preflight screens every attempt)`);
+                        }
+                        throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said} — a concurrent actor had already settled the row (${describeSuppliedValue(live?.status ?? "consumed")}); nothing was settled by this refusal`);
+                    }
+                    this.parentConstraintRegistry.delete(token);
+                    const terminalReap = this.suspendedEnvReaps.get(token);
+                    this.suspendedEnvReaps.delete(token);
+                    this.locallyClaimedTokens.delete(token);
+                    if (terminalReap?.env !== undefined && hasDestroy(terminalReap.env)) {
+                        const terminalEnv = terminalReap.env;
+                        await settleTeardownLeg(() => terminalEnv.destroy(), "terminal-preflight env destroy", (envErr) => {
+                            try {
+                                this.deps.onError?.(envErr, { phase: "config", sessionId: terminalReap.sessionId });
+                            }
+                            catch {
+                            }
+                        });
+                    }
+                    try {
+                        this.deps.onError?.(new Error(`resumePreflight ruled this row PERMANENTLY blocked${said} — the row was settled terminally (expired) by this refusal's single-shot CAS (token no longer redeemable)`), { phase: "hook", sessionId: cp.sessionId });
+                    }
+                    catch {
+                    }
+                    throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight ruled this resume PERMANENTLY blocked${said} — the row was settled terminally (expired by this refusal's single-shot CAS); the token is not redeemable`);
+                }
+                const waitHint = typeof retryAfterMs === "number" && Number.isFinite(retryAfterMs) && retryAfterMs >= 0 ? retryAfterMs : undefined;
+                throw new CheckpointError("resume.preflight_rejected", `the deployment's resumePreflight refused this resume${said}${refusalTail}${waitHint !== undefined ? ` (deployment wait hint: ${String(waitHint)}ms)` : ""}`, waitHint !== undefined ? { retryAfterMs: waitHint } : undefined);
+            }
+            if (recheckGovernanceWindow !== undefined)
+                await recheckGovernanceWindow();
+        }
+        this.locallyClaimedTokens.add(token);
         const won = await store.resolve(token, cp.scope, outcomeForStore, { rev: cp.rev ?? 0 });
+        if (!won)
+            this.locallyClaimedTokens.delete(token);
         if (!won) {
             const live = await store.get(token);
             if (live?.status === "pending") {

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

@@ -8,6 +8,10 @@ import { type ExecResult, type ExecutionEnv, ExecutionError, FileError, type Fil
  */
 export declare class StubExecutionEnv implements ExecutionEnv {
     cwd: string;
+    /** design/380 O9a — declared on the class so the prepare fold can read the optional interface
+     *  member off a `ExecutionEnv | StubExecutionEnv` union; the no-I/O stub produces no target
+     *  content, so it never declares (always `undefined` — the trusted-side default). */
+    readonly externalContentTarget?: boolean;
     constructor(cwd?: string);
     private fsErr;
     absolutePath(path: string): Promise<Result<string, FileError>>;

package/dist/core/stub-env.js

@@ -1,6 +1,7 @@
 import { ExecutionError, FileError, err, } from "../internal/harness.js";
 export class StubExecutionEnv {
     cwd;
+    externalContentTarget;
     constructor(cwd = "/") {
         this.cwd = cwd;
     }

package/dist/core/task-registry-shared.js

@@ -166,6 +166,22 @@ function workflowAgentRow(a, ordinal) {
         ...(a.replayed === true ? { replayed: true } : {}),
     };
 }
+function budgetOvershootNote(overshoot) {
+    if (overshoot === undefined)
+        return "";
+    const unsettled = overshoot.unsettledTokens ?? 0;
+    const total = overshoot.spentTokens + unsettled;
+    return (` token budget OVERSHOT: this run spent ${total.toLocaleString()} total tokens against a ${overshoot.budgetTokens.toLocaleString()} ceiling ` +
+        `(over by ${(total - overshoot.budgetTokens).toLocaleString()}` +
+        `${unsettled > 0 ? `, of which ${unsettled.toLocaleString()} was observed on agents still in flight at the terminal and never settled` : ""}).`);
+}
+function timeoutInterruptionNote(interruption) {
+    if (interruption === undefined)
+        return "";
+    return (` INTERRUPTED by the workflow's total timeout (${interruption.timeoutMs.toLocaleString()}ms): when the deadline fired ` +
+        `${interruption.agentsCompleted} agent(s) had completed, ${interruption.agentsFailed} had failed, and ` +
+        `${interruption.agentsInFlight} were still in flight — the failed run status is the deadline's, not a verdict on those agents.`);
+}
 export function formatWorkflowRun(run) {
     const summary = summarizeWorkflowRun(run);
     const done = run.agents.filter((a) => a.status === "completed" || a.status === "failed").length;
@@ -223,7 +239,7 @@ export function formatWorkflowRun(run) {
                         : {}),
                 }
                 : {}),
-            note: run.status === "running"
+            note: (run.status === "running"
                 ? "still running — poll again shortly."
                 : run.status === "completed"
                     ? run.result !== undefined
@@ -231,7 +247,9 @@ export function formatWorkflowRun(run) {
                         : "completed — this run predates result persistence; its result was delivered on the completion notification."
                     : finishedAgents.length > 0
                         ? `failed — see error. ${finishedAgents.length} agent(s) had already completed before the run ended; their outputs are inlined under \`partial_results\`.`
-                        : "failed — see error.",
+                        : "failed — see error.") +
+                timeoutInterruptionNote(summary.timeoutInterruption) +
+                budgetOvershootNote(summary.budgetOvershoot),
         }),
         details: {
             task_id: run.id,

package/dist/core/types.d.ts

@@ -5216,8 +5216,13 @@ export interface EngineNotice {
      *    two numbers are read off the report's rows, never subtracted from each other). One notice PER
      *    HARVEST that withheld at least one entry file (a checkpoint harvest and the terminal harvest
      *    are distinct facts), never minted for a clean session; `detail: { count, moved, escalated,
-     *    reason?, sessionId? }` (`reason` absent ⇔ the pollution marker could not be re-read at report
-     *    time — the withheld count stays true either way). The formerly registered index-only gap is
+     *    reportId?, reason?, sessionId? }` (`reason` absent ⇔ the pollution marker could not be re-read
+     *    at report time — the withheld count stays true either way). `reportId` (#479) is the minting
+     *    harvest's own occurrence identity ({@link import("./memory-engine/types.js").HarvestReport}
+     *    `.reportId`, uuidv7): two harvests whose counts and paths coincide carry DISTINCT ids, a
+     *    durable replay of the same notice carries the SAME id, and the hold family below shares this
+     *    harvest's id — dedup on `(code, detail.reportId)`, never on `reportId` alone (absent only for
+     *    a hand-built report; every engine-minted report carries it). The formerly registered index-only gap is
      *    CLOSED under `memoryProvenance: "carry"` (design/336 §6.3, #331): the mint condition reads
      *    `HarvestReport.containment`, so a containment whose only act was the derived-index rollback
      *    announces with `count: 0` and `detail.indexRolledBack: true`; under `"off"` the pre-336
@@ -5226,15 +5231,18 @@ export interface EngineNotice {
      *    §4/§6.3) — the instruction-hold lifecycle, derived from the same structured
      *    `HarvestReport.containment` signal (hold seats are only ever filled under
      *    `memoryProvenance: "carry"`): a PENDING session's instruction-form entry files were captured
-     *    off the model-visible plane (`hold_opened`, `detail: { count, paths, sessionId? }` — paths
-     *    neutralized/length-bounded); previously held entries re-walked the full gate set and
+     *    off the model-visible plane (`hold_opened`, `detail: { count, paths, reportId?, sessionId? }`
+     *    — paths neutralized/length-bounded); previously held entries re-walked the full gate set and
      *    committed after their writer session settled clean or a host valve released them
-     *    (`hold_released`); held entries moved to control-plane quarantine (`hold_disposed`,
-     *    `detail.disposed: [{ path, terminal }]` with the closed terminal set
+     *    (`hold_released`, same detail shape); held entries moved to control-plane quarantine
+     *    (`hold_disposed`, `detail.disposed: [{ path, terminal }]` with the closed terminal set
      *    dirty/expired/conflict/capture_lost/discarded — an `expired` terminal is explicitly a
      *    TIMEOUT, not a conviction, and the message names `resolveHold` as the recovery valve). At
      *    most one notice per family per harvest report; wording is factual, never threat-flavored
-     *    (the design/336 §13-2 model-psyche guardrail).
+     *    (the design/336 §13-2 model-psyche guardrail). `detail.reportId` (#479) is shared by all
+     *    three families AND `"memory.harvest_quarantined"` when they derive from the same harvest
+     *    report — that sharing is the contract (one report, several distinct facts): dedup on
+     *    `(code, detail.reportId)`; a repeat with the same pair is a replay, a new pair is a new fact.
      *  - `"memory.delegation_static_mark_waived"` (design/324, #324 ruling ①) — the deployment set
      *    {@link RunnerDeps.memoryDelegationEvidence} to `"attested-only"` and a delegation call whose
      *    STATIC tool-face verdict would have marked this session's memory polluted (attestation
@@ -5298,7 +5306,9 @@ export interface EngineNotice {
      *    session count crossed the consolidation thresholds (time gate open ∧ enough distinct
      *    sessions); minted at most once per crossing (a completed run re-arms the edge), NEVER when
      *    the deployment leaves consolidation off. ADVISORY: the host owns the verbs, nothing runs
-     *    automatically; `detail: { scope, sessionsSince, sessionId? }`.
+     *    automatically; `detail: { scope, sessionsSince, reportId?, sessionId? }` — `reportId` (#479)
+     *    is the minting harvest report's occurrence identity, shared with the harvest/hold family's
+     *    notices of the same report (dedup on `(code, detail.reportId)`).
      *  - `"memory.consolidation_committed"` (design/339 §6.2) — a consolidation plan reached
      *    `completed`: products landed, superseded targets left the default read face (retained as
      *    evidence), intents settled; `detail: { planId, scope, products, superseded, intents }` —
@@ -5376,6 +5386,56 @@ export declare function undrainedUserInputNotices(counts: {
     steer: number;
     followUp: number;
 }, taskId?: string, sessionId?: string): EngineNotice[];
+/**
+ * design/380 O2 — the facts handed to a deployment's {@link RunnerDeps.resumePreflight}: the row's
+ * own recorded identity + placement record, read off the persisted checkpoint (never off the resume
+ * caller's bag), so the hook judges the SAME row the CAS is about to consume.
+ */
+export interface ResumePreflightInfo {
+    token: import("./checkpoint-store.js").CheckpointToken;
+    sessionId: string;
+    /** design/380 O1③ — the row's recorded placement root, when stamped. */
+    placementRootSessionId?: string;
+    /** The row's recorded identity ({@link import("./checkpoint-store.js").Checkpoint.principal}), when stamped —
+     *  the resume entry's identity-continuity rung already refused a contradicting supplied principal
+     *  before this hook runs, so a present value IS the resumed leg's identity. */
+    principal?: string;
+    /** provider / deviceId / mountPath — the placement facts. */
+    workspaceHandle?: import("./remote-env.js").WorkspaceHandle;
+    gateKind: import("./checkpoint-store.js").CheckpointGate["kind"];
+}
+/** design/380 O2 — a {@link RunnerDeps.resumePreflight} answer. */
+export type ResumePreflightVerdict = {
+    ok: true;
+}
+/** Transient obstacle (device offline, dependency briefly down): the checkpoint stays `pending`,
+ *  the SAME token is redeemable later; retryAfterMs threads the wait hint (the #449 G1 carrier). */
+ | {
+    ok: false;
+    disposition?: "retry_later";
+    message: string;
+    retryAfterMs?: number;
+}
+/** PERMANENT obstacle (binding revoked, placement identity gone): the row is settled TERMINALLY —
+ *  core CASes it out of `pending` before answering, so a dead binding cannot
+ *  be redialed forever (prose-terminal + mechanically-retriable = unbounded redeem). The `expire`
+ *  CAS is a pure STATUS flip — the row records no reason (the store seam has no seat for one);
+ *  the REASON travels on the typed `resume.preflight_rejected` refusal (the hook's `message`
+ *  inlined), the `onError` disclosure sink, and the deployment hook's own audit plane — it
+ *  authored the verdict and owns the durable record of why. The exact
+ *  terminal CAS form is the single-shot `expire` CAS (reaper parity — exactly one settler wins; a
+ *  LOST race is re-read and reported as concurrent movement, never claimed as this refusal's
+ *  settle); the CONTRACT is: terminal verdict ⇒ atomic single-shot settle, never a silent
+ *  pending-forever. PHYSICAL reclamation of a suspended workspace stays with the DEPLOYMENT that
+ *  ruled the binding dead — core holds no env pre-restore and a factory cannot reconnect to a
+ *  revoked target; the session pin follows the store contract's documented reap posture. Trust
+ *  grant is acceptable: the hook lives on RunnerDeps, the same deployment plane that owns the
+ *  checkpoint store itself. */
+ | {
+    ok: false;
+    disposition: "terminal";
+    message: string;
+};
 /** Runtime dependencies shared across tasks. */
 export interface RunnerDeps {
     brain: Brain;
@@ -5639,6 +5699,29 @@ export interface RunnerDeps {
      * `checkpointStore` overrides this. Omitted → no durable suspension (policy `ask` stays synchronous).
      */
     checkpointStore?: import("./checkpoint-store.js").CheckpointStore;
+    /**
+     * design/380 O2 — deployment-supplied resume preflight, called INSIDE the pre-CAS ladder (after the
+     * row-integrity rungs, immediately before the CAS) with a bounded deadline
+     * ({@link resumePreflightTimeoutMs}). Refusal / throw / timeout ⇒ typed `resume.preflight_rejected`
+     * (CheckpointError closed-set addition); the DEFAULT/absent disposition is `retry_later` (the safe
+     * arm — fail-closed hooks that just throw can never accidentally terminalize a row) — the
+     * entrance-screen posture of the wake-message hook (design/373 D2), generalized from "screen the
+     * wake message" to "screen the resume". A deployment binding runs to targets (a device lane) checks
+     * its placement/binding tables here: a transient obstacle answers `retry_later` (+`retryAfterMs`,
+     * the #449 G1 wait-hint carrier — the row stays `pending`, the SAME token redeems later); a
+     * PERMANENT one answers `terminal` (the row is settled by the single-shot `expire` CAS — never a
+     * silent pending-forever; bounded waiting for a target to come back also belongs HERE, inside the
+     * deadline, never in the env factory). Absent ⇒ no preflight, byte-identical resume behavior.
+     */
+    resumePreflight?: (info: ResumePreflightInfo, signal: AbortSignal) => Promise<ResumePreflightVerdict>;
+    /**
+     * design/380 O2 — the {@link resumePreflight} deadline in ms. Default 10s (its own bound,
+     * deliberately NOT the hooks-record default: a resume preflight sits on every redeem attempt of a
+     * parked row and must answer promptly or get out of the way). Bad values (non-finite, ≤ 0,
+     * non-number) are DISCLOSED loudly through `onError` and fall back to the default (the bad-value
+     * loudness default: announce, never silently absorb).
+     */
+    resumePreflightTimeoutMs?: number;
     /**
      * design/101 §E19 — working-tree snapshot backend for {@link TaskSpec.rewindFiles}. A task with
      * `rewindFiles` captures a snapshot per completed turn (keyed by the leaf `SessionTreeEntry.id`) and, when it

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

@@ -118,6 +118,19 @@ export async function workflowRunStoreContract(make, runAssertion = defaultSeque
         byId.get("d-over").budgetOvershoot.spentTokens = 7;
         assert.equal((await store.get("d-over")).budgetOvershoot.spentTokens, 1_200);
     });
+    run("the TOTAL-TIMEOUT disclosure reaches the LIST row: timeoutInterruption projects (de-aliased), and a run without it keeps the key ABSENT", async () => {
+        const store = make();
+        const seat = { timeoutMs: 600_000, agentsCompleted: 3, agentsFailed: 1, agentsInFlight: 2 };
+        const cut = createWorkflowRun({ id: "d-timeout", createdAt: 8_000, status: "failed", error: "workflow total timeout", timeoutInterruption: seat });
+        const threw = createWorkflowRun({ id: "d-threw", createdAt: 8_100, status: "failed", error: "script blew up" });
+        for (const r of [cut, threw])
+            await store.put(r.id, r);
+        const byId = new Map((await store.listByScope("tenant-a")).map((s) => [s.id, s]));
+        assert.deepEqual(byId.get("d-timeout").timeoutInterruption, seat);
+        assert.equal("timeoutInterruption" in byId.get("d-threw"), false, "a run its own error ended ⇒ the key is OMITTED, not null/zeroed");
+        byId.get("d-timeout").timeoutInterruption.agentsCompleted = 7;
+        assert.equal((await store.get("d-timeout")).timeoutInterruption.agentsCompleted, 3);
+    });
     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

@@ -67,6 +67,23 @@ export interface WorkflowRunSummary {
         spentTokens: number;
         unsettledTokens?: number;
     };
+    /** The run's TERMINAL total-timeout interruption ({@link WorkflowRun.timeoutInterruption}) — present ONLY
+     *  when the `totalTimeoutMs` deadline had fired by the time the run reached its terminal. The third member
+     *  of the same family as {@link agentFailures} and {@link budgetOvershoot}: it lets a list row separate
+     *  "this run was CUT SHORT, and here is what it had achieved" from "this run failed", without an N+1 `get`
+     *  of the full run. Nothing else on this projection can answer that — {@link status} is `failed` either
+     *  way, and {@link agentCount} counts records regardless of how they ended.
+     *
+     *  Projected as a de-aliased shallow COPY (same anti-aliasing posture as {@link budgetOvershoot}: a list
+     *  row must not be a mutable window into the stored run). Read the members per
+     *  {@link WorkflowRun.timeoutInterruption} — in particular `agentsFailed` is a PRE-abandonment count and is
+     *  NOT {@link agentFailures}. */
+    timeoutInterruption?: {
+        timeoutMs: number;
+        agentsCompleted: number;
+        agentsFailed: number;
+        agentsInFlight: 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. */

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

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

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

@@ -455,6 +455,24 @@ export interface ExecutionEnv extends FileSystem, Shell {
      * harmless explicit spelling of the local default.
      */
     readonly hostLocalPaths?: boolean;
+    /**
+     * design/380 O9 — declared by the ADAPTER: content produced by THIS env (every FileSystem/Shell
+     * result — stdout, file bytes, listings, names) originates from a target OUTSIDE the deployment's
+     * trust boundary (a personal device, an unmanaged host). Omitted ⇒ historic behavior (trusted-side
+     * results). `true` feeds three EXISTING channels, no new vocabulary:
+     *  - memory: the run's hand-tool results are treated as external-class content — the session mark
+     *    (`memory.session_polluted`) + the design/336 origin carriage at harvest, via the same fold
+     *    `execIsExternalContent` upgrades through (this flag ORs into that fold for the run);
+     *  - env facts / prompt renderer: one declarative line disclosing the execution locus + trust posture;
+     *  - audit: TaskResult/checkpoint carry it implicitly through WorkspaceHandle{provider, deviceId}.
+     * Suspend/resume: the run-level fold is PRESENCE-persisted on the checkpoint
+     * (`CheckpointState.externalContentTarget`, monotonic) and resume joins persisted OR live
+     * declaration — a run minted under a declaring adapter never silently downgrades on an
+     * undeclared/older one. A trust-posture declaration ONLY: no gate/policy/roster behavior reads it
+     * (the design/378 content-origin red line), and it is ORTHOGONAL to `capabilities.isolation` — an
+     * SSH env to an organization-managed build host can be non-isolated yet omit this flag.
+     */
+    readonly externalContentTarget?: boolean;
 }
 /** Base fields shared by append-only session tree entries. */
 export interface SessionTreeEntryBase {

package/dist/index.d.ts

@@ -263,7 +263,7 @@ export { ROUTE_ADJUDICATION_CONFORMANCE_CORPUS, type RouteAdjudicationVector } f
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, CompleteSimpleFn, Context, DocumentContent, ImageContent, Message, StopReason, StreamFn, TextContent, ThinkingContent, ToolCall, ToolResultMessage, Usage, UserMessage, } from "./internal/llm.js";
-export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, BrainRetryErrClass, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, A2aServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, ResumePreflightInfo, ResumePreflightVerdict, EngineNotice, RuntimeCaps, BackgroundChildEvent, DelegationLifecycleEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskLimits, StaleToolResultOffloadOptions, TaskResult, EffectiveMemoryScopes, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ReversibilityVerdict, ToolEffect, ToolContentOrigin, WorkflowGovernanceBaseline, DelegationTaskType, } from "./core/types.js";
 export { Type } from "typebox";
 export type { TSchema, Static } from "typebox";
 export { explainPromptAssembly, describeDefaultPack, type DefaultPackDescription, type ExplainInput } from "./prompt-assembly/explain.js";

package/dist/orchestration/workflow-types.d.ts

@@ -192,6 +192,41 @@ export interface WorkflowRun {
         spentTokens: number;
         unsettledTokens?: number;
     };
+    /** The run's TERMINAL total-timeout interruption — present ONLY when the `totalTimeoutMs` deadline had
+     *  FIRED by the time this run reached its (failed) terminal, absent on every other run: one that finished
+     *  inside its deadline, one that failed for its own reason before the deadline, and one that armed no
+     *  deadline at all. Same ADDITIVE-observation contract as {@link agentFailures} and
+     *  {@link budgetOvershoot} (never a gate input, never re-read by the engine, status enums untouched).
+     *
+     *  WHY IT EXISTS: the deadline abandons the script body, so the run finalizes `failed` carrying the
+     *  deadline's own message — and that is ALL any downstream face had to go on. A run whose agents had in
+     *  fact answered (their outputs already on the record, inlined as `partial_results` on a poll) read as a
+     *  total loss. This seat is the missing distinction: it states that the deadline is what ended the run,
+     *  and what the run had ACHIEVED at that moment. Extending {@link WorkflowRunStatus} with a separate
+     *  terminal word would say the same thing at the cost of a wire contract every consumer switches on, so
+     *  the fact rides an optional member instead.
+     *
+     *  `timeoutMs` is the deadline that fired (the run's configured `totalTimeoutMs`), so a reader can raise
+     *  it deliberately rather than guess it.
+     *
+     *  ⚠️ THE COUNTS ARE A POINT-IN-TIME SNAPSHOT, taken BEFORE the terminal fold that closes abandoned
+     *  agents. That is the whole point (it reports what the deadline INTERRUPTED), and it is also why
+     *  `agentsFailed` here is NOT {@link agentFailures}: the terminal fold marks every still-running agent
+     *  `failed`, so the record's tally counts them and this member does not. The two are different questions
+     *  about the same run — "how many had failed on their own when the clock ran out" versus "how many agent
+     *  records ended failed" — and a consumer that swaps one for the other reports abandoned work as failed
+     *  work. `agentsInFlight` counts records still `running` at that moment, which includes calls still
+     *  QUEUED for a concurrency slot (they had not been refused, they had not finished).
+     *
+     *  The seat is an OBJECT rather than a flat pair of members so a later disclosure about the same terminal
+     *  (how much of the deadline was spent waiting on something outside the run, say) joins it additively with
+     *  no shape change on any of the three faces. Nothing beyond the four members below is declared today. */
+    timeoutInterruption?: {
+        timeoutMs: number;
+        agentsCompleted: number;
+        agentsFailed: number;
+        agentsInFlight: number;
+    };
     phases: WorkflowPhase[];
     agents: WorkflowAgentRun[];
     /** design/97 CORE-3: nested `ctx.workflow` sub-groups (the persisted group tree). Empty when the script

package/dist/orchestration/workflow-types.js

@@ -67,11 +67,11 @@ export class WorkflowMaxAgentsError extends Error {
                 `Add a hard iteration cap to the loop, or pass a token budget.`
             : spentTokens !== undefined && spentTokens > budgetTotal
                 ? `Workflow agent() call cap reached (${max}), and the token budget is ALREADY EXCEEDED ` +
-                    `(${spentTokens.toLocaleString()} spent / ${budgetTotal.toLocaleString()} output tokens): agents already in flight when ` +
+                    `(${spentTokens.toLocaleString()} spent / ${budgetTotal.toLocaleString()} total tokens): agents already in flight when ` +
                     `the ceiling was reached are not bound by the per-call gate, so their spend landed on top of it. BOTH bounds are ` +
                     `binding — raising maxAgents alone would only buy more overshoot. Fan out over fewer items, or lower concurrency ` +
                     `(it bounds the overshoot) and raise the token budget deliberately.`
-                : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} output tokens), ` +
+                : `Workflow agent() call cap reached (${max}). A token budget IS set (${budgetTotal.toLocaleString()} total tokens), ` +
                     `so this is the CALL-COUNT cap, not the token ceiling: the script asked for more than ${max} agent() calls. ` +
                     `Fan out over fewer items, or raise maxAgents.`);
         this.max = max;