@sema-agent/core 5.63.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();
@@ -3119,7 +3142,10 @@ export class Runner {
             }
             catch (err) {
                 if (turnSignal?.aborted === true && !prepared.abortController.signal.aborted) {
-                    queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "forced", reason: "guard-chain forced compaction cut short by a turn interrupt", ...ident() });
+                    const interruptReason = lane === "rejection"
+                        ? "prompt-too-long recovery pass cut short by a turn interrupt"
+                        : "guard-chain forced compaction cut short by a turn interrupt";
+                    queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "forced", reason: interruptReason, ...ident() });
                     return false;
                 }
                 compactionBreaker.failures += 1;
@@ -3135,9 +3161,11 @@ export class Runner {
             thinkingOnly: {},
             degenerateOutput: { detect: (m) => isDegenerateCutMessage(m) },
             promptTooLong: {
-                recover: async (attempt) => {
+                recover: async (attempt, turnSignal) => {
                     if (prepared.abortController.signal.aborted || prepared.suspendRef.token !== undefined)
                         return false;
+                    if (turnSignal?.aborted === true)
+                        return false;
                     if (prepared.microCompact.clearOnRejection && attempt === 1) {
                         const proj = prepared.microCompact.projectionRef.current;
                         const compactionAvailable = (spec.compaction?.enabled ?? true) && compactionBreaker.failures < MAX_CONSECUTIVE_COMPACTION_FAILURES;
@@ -3174,7 +3202,7 @@ export class Runner {
                             return true;
                         }
                     }
-                    return runForcedCompactionPass("rejection");
+                    return runForcedCompactionPass("rejection", turnSignal);
                 },
             },
         });
@@ -4308,7 +4336,9 @@ export class Runner {
         if (outcome === null || typeof outcome !== "object") {
             throw new CheckpointError("checkpoint.invalid_outcome", `resume outcome must be an object naming its gate (got ${outcome === null ? "null" : typeof outcome})`);
         }
-        const store = resolveCheckpointStore(taskConfig, this.deps);
+        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)");
         }
@@ -4335,7 +4365,7 @@ export class Runner {
         let wakeMessage;
         let wakeHookContext;
         const outcomeGate = outcome.gate;
-        const resumeSignal = taskConfig.signal;
+        const resumeSignal = config.signal;
         let suppliedMessage;
         if (outcomeGate === "wake") {
             suppliedMessage = outcome.message;
@@ -4564,7 +4594,7 @@ export class Runner {
                     : "resume carried a content-ask `answer` on a `deny` — a denial injects a refusal, never an answer; refusing rather than dropping it silently", { field: "answer" });
             }
             if (contentAskCallId !== undefined && plainPolicyOutcome.decision === "allow" && suppliedAnswer === undefined) {
-                if (!isLiveQuestionFace(taskConfig.onQuestion ?? this.deps.onQuestion)) {
+                if (!isLiveQuestionFace(config.onQuestion ?? this.deps.onQuestion)) {
                     throw new CheckpointError("checkpoint.invalid_outcome", "resume approved a content-ask (the reserved question tool) without an `answer`, and this resume has no live answering face — " +
                         'executing the question against nothing would hand the model a fabricated "no human is available" default while consuming the approval; ' +
                         "re-resume with the operator's answer on the outcome (or deny it), the checkpoint stays pending", { field: "answer" });
@@ -4675,19 +4705,28 @@ export class Runner {
                 },
             }
             : internals;
-        if (this.deps.lockedConfig?.keys?.includes("toolPolicy") === true && taskConfig.basePolicyForResumeEdit !== undefined) {
+        if (this.deps.lockedConfig?.keys?.includes("toolPolicy") === true && config.basePolicyForResumeEdit !== undefined) {
             throw new CheckpointError("checkpoint.invalid_outcome", "TaskSpec.basePolicyForResumeEdit is administratively locked by this deployment (locked key \"toolPolicy\") — a task-supplied " +
                 "resume-edit policy is refused pre-CAS (the checkpoint stays pending); remove the field or change the deployment's lock configuration");
         }
         let recheckGovernanceWindow;
         {
             const rowPrincipal = cp.principal || undefined;
-            const suppliedPrincipal = taskConfig.principal || undefined;
+            const suppliedPrincipal = config.principal || undefined;
             if (rowPrincipal !== undefined && suppliedPrincipal !== undefined && suppliedPrincipal !== rowPrincipal) {
                 throw new CheckpointError("resume.principal_mismatch", `the resume config carries principal ${JSON.stringify(suppliedPrincipal)} but this checkpoint was suspended under principal ${JSON.stringify(rowPrincipal)} — ` +
                     "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;
@@ -4709,13 +4748,13 @@ export class Runner {
             }
         }
         if (outcomeGate === "wake" && wakeMessage !== undefined) {
-            const resumeScreenHooks = taskConfig.hooks ?? this.deps.hooks;
+            const resumeScreenHooks = config.hooks ?? this.deps.hooks;
             const screen = resumeScreenHooks?.userPromptSubmit;
             if (screen !== undefined && resumeSignal?.aborted !== true) {
                 const screenedMessage = wakeMessage;
                 const identity = mintHookInvocationIdentity({
                     sessionId: cp.sessionId,
-                    taskId: taskConfig.taskId ?? cp.sessionId,
+                    taskId: config.taskId ?? cp.sessionId,
                     legKind: "resume",
                     isDelegatedChild: effectiveDelegationFacts(internals, cp.state.isDelegatedChild).isDelegatedChild,
                     ...(internals?.insideFork === true ? { insideFork: true } : {}),
@@ -4784,7 +4823,7 @@ export class Runner {
                 budget: editBudget,
                 ...(cp.state.handsCwd !== undefined ? { cwd: cp.state.handsCwd } : {}),
             };
-            const editSignal = taskConfig.signal;
+            const editSignal = config.signal;
             const raceEditAbort = async (p) => {
                 if (editSignal === undefined)
                     return p;
@@ -4823,7 +4862,7 @@ export class Runner {
             const toolPolicyLocked = this.deps.lockedConfig?.keys?.includes("toolPolicy") === true;
             const editBasePolicy = toolPolicyLocked
                 ? (this.deps.basePolicyForResumeEdit ?? this.deps.toolPolicy)
-                : (taskConfig.basePolicyForResumeEdit ?? this.deps.basePolicyForResumeEdit ?? taskConfig.toolPolicy ?? this.deps.toolPolicy);
+                : (config.basePolicyForResumeEdit ?? this.deps.basePolicyForResumeEdit ?? config.toolPolicy ?? this.deps.toolPolicy);
             if (editBasePolicy !== undefined) {
                 let rechecked;
                 try {
@@ -4843,7 +4882,7 @@ export class Runner {
                         `refused pre-CAS (the checkpoint stays pending); re-submit the edited action so the rewrite is adjudicated and approved synchronously`);
                 }
             }
-            const resumeHooks = taskConfig.hooks ?? this.deps.hooks;
+            const resumeHooks = config.hooks ?? this.deps.hooks;
             if (resumeHooks?.preToolUse !== undefined && resumeHooks.preToolUseObservational === true) {
                 try {
                     await raceEditAbort(Promise.resolve(resumeHooks.preToolUse(cp.pendingAction.toolName, cloneObserverInput(editedArgs), {
@@ -4863,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") {
@@ -4878,15 +5031,15 @@ export class Runner {
             consumeFlipDone = true;
         }
         const answerFace = plainPolicyOutcome !== undefined && redeemedAnswer !== undefined
-            ? answerFaceForRedeemedCall(redeemedAnswer, plainPolicyOutcome.boundCallId, taskConfig.onQuestion ?? this.deps.onQuestion, boundInputHashOf(cp.pendingAction.args?.questions))
+            ? answerFaceForRedeemedCall(redeemedAnswer, plainPolicyOutcome.boundCallId, config.onQuestion ?? this.deps.onQuestion, boundInputHashOf(cp.pendingAction.args?.questions))
             : undefined;
         const spec = {
-            ...taskConfig,
-            ...((taskConfig.principal || undefined) === undefined && (cp.principal || undefined) !== undefined ? { principal: cp.principal } : {}),
+            ...config,
+            ...((config.principal || undefined) === undefined && (cp.principal || undefined) !== undefined ? { principal: cp.principal } : {}),
             objective: "",
             sessionId: cp.sessionId,
             requireExistingSession: true,
-            preemptSignal: taskConfig.preemptSignal?.aborted ? undefined : taskConfig.preemptSignal,
+            preemptSignal: config.preemptSignal?.aborted ? undefined : config.preemptSignal,
             ...(answerFace !== undefined ? { onQuestion: answerFace } : {}),
         };
         const reopenFn = store.reopen?.bind(store);

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

@@ -552,6 +552,13 @@ export interface ToolExecuteContext {
      *  fixed point `ctx.rootSessionId ?? ctx.sessionId` at every spawn). Absent for a top-level run
      *  (its OWN sessionId is the root). */
     rootSessionId?: string;
+    /** design/380 O1② (C12) — the spawning run's EXPLICIT placement fixed point
+     *  (`RunInternals.placementRoot`), present only when its internals carried one (cascade rungs /
+     *  verification legs after the first, or a caller-declared root). A delegation tool threads it
+     *  VERBATIM into child RunInternals so every descendant keeps the ladder/gate placement; absent ⇒
+     *  the `rootSessionId` chain above IS the placement root through prepare's mint middle segment
+     *  (`placementRoot ?? rootSessionId ?? sessionId`) and nothing extra is threaded. */
+    placementRoot?: string;
     /**
      * design/151 §7 S3c — TRUSTED tier-3 revival claim (same trusted-internals seat as
      * {@link parentTaskId}; never a model argument). Filled ONLY by the auto-mounted SendMessage's
@@ -5209,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
@@ -5219,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
@@ -5291,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 }` —
@@ -5369,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;
@@ -5632,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
@@ -5932,9 +6022,12 @@ export interface RunnerDeps {
      * `TaskSpec.limits`, which is the allowance ONE task asked for — an operator granting "N tokens per 5
      * hours" cannot express it as a task limit, because nothing stops the next task from asking again.
      *
-     * A window carries a TOKEN ceiling and, optionally, a MONEY ceiling (`UsageWindow.maxCostUsd`, absolute
-     * USD — the `TaskLimits.maxCostUsd` quantity one governance level up). The two are independent and
-     * either one binds. A $ ceiling requires a PRICED run: a task whose model has neither a {@link pricing}
+     * A window carries a TOKEN ceiling (`UsageWindow.maxTokens`), a MONEY ceiling (`UsageWindow.maxCostUsd`,
+     * absolute USD — the `TaskLimits.maxCostUsd` quantity one governance level up), or both: each is
+     * optional on its own and at least one is required, so a deployment governed by spend alone declares
+     * only `maxCostUsd` (a window with neither ceiling is refused, `config.usage_window_invalid`). The two
+     * are independent and every declared one binds. A $ ceiling requires a PRICED run: a task whose model
+     * has neither a {@link pricing}
      * entry nor a `Model.cost` declaration is refused at the door (`config.usage_window_unpriced`) rather
      * than charged the fabricated 0 an unpriced run would otherwise file into an operator's ceiling.
      *