@sema-agent/core 2.11.0 → 2.13.0

package/dist/core/runner/prepare-task.js

@@ -49,7 +49,8 @@ import { capAggregateToolResults } from "../tool-result-budget.js";
 import { capAggregateMediaBytes, AGGREGATE_MEDIA_BUDGET_BYTES } from "../media-byte-cap.js";
 import { dropOrphanToolResults, guardBudget, insertTrimNotice, trimToBudget } from "../context-guard.js";
 import { StubExecutionEnv } from "../stub-env.js";
-import { hasDestroy, isIsolated, isRemoteExecutionEnv, isSuspendable } from "../remote-env.js";
+import { hasDestroy, isIsolated, isRemoteExecutionEnv, isRetryableRemoteErrorCode, isSuspendable, missingRestoreSurface, RETRYABLE_REMOTE_ERROR_CODES } from "../remote-env.js";
+import { withRetry } from "../with-retry.js";
 import { hasBackgroundShell, sweepBackgroundShells } from "../background-shell.js";
 import { createTaskOutputTool, createTaskStopTool, defaultTaskRegistry } from "../task-registry.js";
 import { createMonitorTool } from "../../tools/monitor.js";
@@ -173,6 +174,27 @@ export function rebaseWorkspacePath(p, fromRaw, toRaw) {
     const suffix = p.slice(fromPrefix.length).replace(/^\/+/, "");
     return to === "/" ? `${to}${suffix}` : `${to}/${suffix}`;
 }
+function remoteEnvFailureNote(op, error, attempts) {
+    return { op, code: error.code, retryable: isRetryableRemoteErrorCode(error.code), attempts, message: error.message };
+}
+const REMOTE_RESTORE_MAX_ATTEMPTS = 2;
+const REMOTE_RESTORE_BACKOFF_MS = 200;
+async function restoreWorkspaceWithRetry(env, snapshotId, options) {
+    let attempts = 0;
+    const outcome = await withRetry(async (attempt) => {
+        attempts = attempt;
+        return env.resumeVM(snapshotId, options);
+    }, { retryableCodes: RETRYABLE_REMOTE_ERROR_CODES, maxAttempts: REMOTE_RESTORE_MAX_ATTEMPTS, backoffMs: () => REMOTE_RESTORE_BACKOFF_MS }, { ...(options.abortSignal !== undefined ? { signal: options.abortSignal } : {}) });
+    return { outcome, attempts };
+}
+export function rebaseWorkspacePathAcross(p, froms, to) {
+    for (const from of froms) {
+        const out = rebaseWorkspacePath(p, from, to);
+        if (out !== p)
+            return out;
+    }
+    return p;
+}
 export async function prepareTask(spec, deps, sessions, resume, internals, runnerSelf) {
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
@@ -410,6 +432,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
     }
     const taskScope = internals?.registryScope ?? spec.principal ?? "default";
+    const offloadScope = spec.principal ?? "default";
     defaultTaskRegistry.maybeGc();
     const forgetOnThrow = () => forgetQuietly(sessions, sessionId);
     const extraBodyCollisions = reservedCollisions(model.extraBody, reservedFor(model.api));
@@ -434,7 +457,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const offloadEnabled = Number.isFinite(offloadThreshold) && offloadThreshold > 0;
     const rawOffloadStore = offloadEnabled ? (deps.toolResultStore ?? new InMemoryToolResultStore()) : undefined;
     const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
-        ? new ScopedToolResultStore(rawOffloadStore, taskScope)
+        ? new ScopedToolResultStore(rawOffloadStore, offloadScope)
         : rawOffloadStore;
     const offloadReachableToolsRef = {};
     const maybeOffload = (tool, perTool) => {
@@ -558,11 +581,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             }
         }
         let restoredRootRebase;
-        const rebaseRestoredPath = (p) => restoredRootRebase === undefined ? p : rebaseWorkspacePath(p, restoredRootRebase.from, restoredRootRebase.to);
+        const rebaseRestoredPath = (p) => restoredRootRebase === undefined ? p : rebaseWorkspacePathAcross(p, restoredRootRebase.from, restoredRootRebase.to);
         if (resume?.workspaceHandle !== undefined) {
-            const failResume = (message, cause) => {
+            const failResume = (message, cause, note) => {
                 const e = new Error(message, cause ? { cause } : undefined);
                 e.code = "resume.env_failed";
+                if (note !== undefined)
+                    e.remoteEnvFailure = note;
                 throw e;
             };
             const handle = resume.workspaceHandle;
@@ -570,7 +595,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 failResume("resume needs a RemoteExecutionEnv from executionEnvFactory to restore the workspace snapshot");
             }
             else if (handle.snapshotId === undefined) {
-                if (handle.restoreMode !== "park_only" && isSuspendable(ownedEnv)) {
+                if (handle.restoreMode !== "park_only" && ownedEnv.capabilities.suspendable) {
                     failResume("checkpoint workspaceHandle has no snapshotId and is not a park_only handle, but the resumed env is suspendable — refusing to resume on a possibly-unrestored workspace (corrupt checkpoint?)");
                 }
                 if (handle.mountPath && handle.mountPath !== taskRootPath) {
@@ -581,12 +606,37 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const restoreSignal = spec.signal
                     ? AbortSignal.any([abortController.signal, spec.signal])
                     : abortController.signal;
-                const restored = await ownedEnv.resumeVM(handle.snapshotId, { abortSignal: restoreSignal, priorHandle: handle });
+                const missingHere = missingRestoreSurface(ownedEnv);
+                if (missingHere.length > 0) {
+                    failResume(`the resumed execution env cannot restore a workspace snapshot: its adapter does not implement ${missingHere.join(" or ")}. The checkpoint holds snapshot "${handle.snapshotId}" — wire an adapter that implements the full RemoteExecutionEnv restore surface and re-resume.`);
+                }
+                const { outcome: restored, attempts: restoreAttempts } = await restoreWorkspaceWithRetry(ownedEnv, handle.snapshotId, {
+                    abortSignal: restoreSignal,
+                    priorHandle: handle,
+                });
                 if (!restored.ok) {
-                    failResume(`resumeVM failed (${restored.error.code}): ${restored.error.message}`, restored.error);
+                    failResume(`resumeVM failed after ${restoreAttempts} attempt(s) (${restored.error.code}): ${restored.error.message}`, restored.error, remoteEnvFailureNote("resumeVM", restored.error, restoreAttempts));
                 }
                 else {
+                    const restoredEnv = ownedEnv;
+                    const canonicalInEnv = async (p) => {
+                        try {
+                            const r = await restoredEnv.canonicalPath(p, restoreSignal);
+                            return r.ok ? r.value : undefined;
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    };
+                    let checkpointedCanonical;
+                    let sameRootUnderAlias = false;
                     if (restored.value.mountPath !== handle.mountPath) {
+                        checkpointedCanonical = await canonicalInEnv(handle.mountPath);
+                        const restoredCanonical = await canonicalInEnv(restored.value.mountPath);
+                        sameRootUnderAlias =
+                            checkpointedCanonical !== undefined && restoredCanonical !== undefined && checkpointedCanonical === restoredCanonical;
+                    }
+                    if (restored.value.mountPath !== handle.mountPath && !sameRootUnderAlias) {
                         if (resume.executesApprovedAction === true) {
                             failResume(`resumeVM workspace-root divergence with a pending approved action: checkpointed mountPath "${handle.mountPath}" but the restored handle reports "${restored.value.mountPath}" — the approved args are bound to the checkpointed root; refusing to execute them against a moved workspace (adapter should honor priorHandle)`);
                         }
@@ -599,13 +649,23 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (restored.value.mountPath && restored.value.mountPath !== taskRootPath) {
                         taskRootPath = restored.value.mountPath;
                     }
-                    if (restored.value.mountPath && restored.value.mountPath !== handle.mountPath) {
-                        restoredRootRebase = { from: handle.mountPath, to: restored.value.mountPath };
+                    if (restored.value.mountPath && restored.value.mountPath !== handle.mountPath && !sameRootUnderAlias) {
+                        const from = checkpointedCanonical !== undefined && checkpointedCanonical !== handle.mountPath
+                            ? [handle.mountPath, checkpointedCanonical]
+                            : [handle.mountPath];
+                        restoredRootRebase = { from, to: restored.value.mountPath };
+                        try {
+                            deps.onError?.(new Error(from.length > 1
+                                ? `resumeVM workspace-root rebase accepts both spellings of the checkpointed root (${from.map((f) => `"${f}"`).join(" and ")}) when migrating persisted paths to "${restored.value.mountPath}"`
+                                : `resumeVM workspace-root rebase is spelling-exact: it matches the checkpointed root "${handle.mountPath}" only, so persisted paths recorded under an equivalent alias of it are NOT migrated to "${restored.value.mountPath}" and stay as written`), { phase: "config", sessionId });
+                        }
+                        catch {
+                        }
                     }
                 }
                 const init = await ownedEnv.postResumeInit();
                 if (!init.ok) {
-                    failResume(`postResumeInit failed (${init.error.code}): ${init.error.message}`, init.error);
+                    failResume(`postResumeInit failed (${init.error.code}): ${init.error.message}`, init.error, remoteEnvFailureNote("postResumeInit", init.error, 1));
                 }
             }
         }
@@ -948,6 +1008,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         const suspendRef = {};
         const reviewRef = {};
+        const remoteEnvFailures = [];
         const suspendLoopRef = { hit: false };
         const compactionReuseRef = { consecutive: 0 };
         const trimPressureRef = { droppedMessages: false };
@@ -1324,6 +1385,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         owner: hostTaskId,
                         scope: taskScope,
                         ...(sessionId !== undefined ? { sessionId } : {}),
+                        enrichCtx: enrichSpecToolCtx,
                     })));
                 }
             }
@@ -1855,6 +1917,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
+            let activationChain = Promise.resolve();
+            const serializeActivation = (section) => {
+                const p = activationChain.then(section);
+                activationChain = p.then(() => undefined, () => undefined);
+                return p;
+            };
             const directCallFor = (name) => {
                 if (spec.deferSelfResolve === false)
                     return undefined;
@@ -1870,7 +1938,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         };
                     },
                     ...(executionMode !== undefined ? { executionMode } : {}),
-                    activate: async () => {
+                    activate: async () => serializeActivation(async () => {
                         if (activeTools.has(name))
                             return undefined;
                         activeTools.add(name);
@@ -1882,7 +1950,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             throw e;
                         }
                         return listingRideRef.current?.([name]);
-                    },
+                    }),
                 };
             };
             const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i, directCallFor(i.name))]));
@@ -1956,6 +2024,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 listingRide: (newly) => listingRideRef.current?.(newly),
                 mountedNames: callableToolNames,
                 directCallEnabled: spec.deferSelfResolve !== false,
+                serializeActivation,
             });
             harnessTools = buildToolList(activeTools);
         }
@@ -2541,16 +2610,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         const preToolContexts = new Map();
         const blockedToolCalls = new Set();
         const blockedTracked = Boolean(hooks?.postToolUse || hooks?.preToolUse || hooks?.postToolUseFailure || hooks?.postToolBatch);
+        const restoreSurfaceGap = ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) && ownedEnv.capabilities.suspendable ? missingRestoreSurface(ownedEnv) : [];
+        const incompleteSuspendAdapter = restoreSurfaceGap.length > 0 ? restoreSurfaceGap : undefined;
         const resourceSuspendEligible = spec.resourceSuspend !== undefined &&
             (spec.checkpointStore ?? deps.checkpointStore) !== undefined &&
             !(offloadStore !== undefined && isVolatileOffloadStore(offloadStore)) &&
-            (ownedEnv === undefined || isRemoteExecutionEnv(ownedEnv));
+            (ownedEnv === undefined || isRemoteExecutionEnv(ownedEnv)) &&
+            incompleteSuspendAdapter === undefined;
         if (spec.resourceSuspend !== undefined && !resourceSuspendEligible) {
             const why = (spec.checkpointStore ?? deps.checkpointStore) === undefined
                 ? "no CheckpointStore is wired"
                 : offloadStore !== undefined && isVolatileOffloadStore(offloadStore)
                     ? "tool-result offload uses the in-memory store (a resume needs durable results)"
-                    : "the per-task execution env is not a RemoteExecutionEnv (it would be destroyed on suspend)";
+                    : incompleteSuspendAdapter !== undefined
+                        ? `the per-task execution env declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")} (a snapshot nothing can restore is worse than no snapshot)`
+                        : "the per-task execution env is not a RemoteExecutionEnv (it would be destroyed on suspend)";
             deps.onError?.(new Error(`resourceSuspend is set but INACTIVE: ${why}; resource limits will hard-fail, not suspend`), {
                 phase: "config",
                 sessionId,
@@ -2726,14 +2800,18 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 catch (putErr) {
                     deps.onError?.(putErr, { phase: "config", sessionId });
                     if (remoteEnv !== undefined && remoteHandle?.snapshotId !== undefined) {
-                        const back = await remoteEnv.resumeVM(remoteHandle.snapshotId, { abortSignal: abortController.signal });
+                        const { outcome: back, attempts: backAttempts } = await restoreWorkspaceWithRetry(remoteEnv, remoteHandle.snapshotId, {
+                            abortSignal: abortController.signal,
+                        });
                         if (back.ok) {
                             const init = await remoteEnv.postResumeInit();
                             if (init.ok)
                                 return false;
+                            remoteEnvFailures.push(remoteEnvFailureNote("postResumeInit", init.error, 1));
                             deps.onError?.(init.error, { phase: "config", sessionId });
                         }
                         else {
+                            remoteEnvFailures.push(remoteEnvFailureNote("resumeVM", back.error, backAttempts));
                             deps.onError?.(back.error, { phase: "config", sessionId });
                         }
                         abortController.abort();
@@ -2743,10 +2821,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     return false;
                 }
             };
-            const publishCommittedSuspend = (token, gate, scope) => {
+            const publishCommittedSuspend = (token, gate, scope, remoteHandle) => {
                 const ref = gate.kind === "needs_review" || gate.kind === "plan_review" ? reviewRef : suspendRef;
                 ref.token = token;
                 ref.gate = gate;
+                if (remoteHandle !== undefined)
+                    ref.restoreMode = remoteHandle.restoreMode === "park_only" ? "park_only" : "snapshot";
                 ref.scope = scope;
             };
             const suspendLoopCapHit = (count, cap, detail) => {
@@ -2763,7 +2843,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 return true;
             };
             const suspendableEnv = ownedEnv !== undefined && isSuspendable(ownedEnv) ? ownedEnv : undefined;
-            const parkOnlyRemoteEnv = suspendableEnv === undefined && ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) ? ownedEnv : undefined;
+            const parkOnlyRemoteEnv = suspendableEnv === undefined && ownedEnv !== undefined && isRemoteExecutionEnv(ownedEnv) && incompleteSuspendAdapter === undefined
+                ? ownedEnv
+                : undefined;
             const parkOnlyHandle = (env) => {
                 const { snapshotId: _lineage, ...identity } = env.workspaceHandle();
                 return { ...identity, restoreMode: "park_only" };
@@ -2788,6 +2870,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
                         const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
                         if (!snap.ok) {
+                            remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
                             deps.onError?.(new Error(`resource suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
                             return false;
                         }
@@ -2822,7 +2905,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     };
                     if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
                         return false;
-                    publishCommittedSuspend(token, gate, rs.scope);
+                    publishCommittedSuspend(token, gate, rs.scope, remoteHandle);
                     try {
                         await sessions.pin?.(sessionId);
                     }
@@ -2839,6 +2922,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         return false;
                     if (abortController.signal.aborted)
                         return false;
+                    if (incompleteSuspendAdapter !== undefined) {
+                        try {
+                            deps.onError?.(new Error(`plan_review park skipped: the per-task execution env declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so its workspace could not be restored on resume (the plan-review request was dropped; the run continues without pausing)`), { phase: "config", sessionId });
+                        }
+                        catch {
+                        }
+                        return false;
+                    }
                     if (suspendLoopCapHit(priorSuspendCount, maxSuspends, " for a plan_review (likely a resume/restart loop)."))
                         return false;
                     const leafId = await session.getLeafId();
@@ -2858,6 +2949,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             await sweepBackgroundShells(suspendableEnv, defaultTaskRegistry);
                         const snap = await suspendableEnv.suspendVM({ abortSignal: abortController.signal });
                         if (!snap.ok) {
+                            remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
                             deps.onError?.(new Error(`plan_review suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error }), { phase: "config", sessionId });
                             return false;
                         }
@@ -2896,7 +2988,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     };
                     if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
                         return false;
-                    publishCommittedSuspend(token, gate, scope);
+                    publishCommittedSuspend(token, gate, scope, remoteHandle);
                     try {
                         await sessions.pin?.(sessionId);
                     }
@@ -2930,10 +3022,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                 "RunnerDeps.toolResultStore or disable offload.");
                         }
                         if (ownedEnv !== undefined && remoteEnv === undefined && parkOnlyRemoteEnv === undefined) {
-                            throw new Error("durable suspend is not supported with a non-remote per-task executionEnvFactory env: the " +
-                                "minted env is destroyed on suspend, so a resumed file/shell tool would act on a fresh " +
-                                "(empty) env. Use a RemoteExecutionEnv factory (it is paused, not destroyed) or a static, " +
-                                "caller-owned RunnerDeps.executionEnv.");
+                            throw new Error(incompleteSuspendAdapter !== undefined
+                                ? `durable suspend is not supported with this per-task executionEnvFactory env: it declares capabilities.suspendable but its adapter does not implement ${incompleteSuspendAdapter.join(" or ")}, so a snapshot taken now could never be restored. Implement the full RemoteExecutionEnv restore surface, or declare capabilities.suspendable:false if the workspace is externally durable (the park-only lane).`
+                                : "durable suspend is not supported with a non-remote per-task executionEnvFactory env: the " +
+                                    "minted env is destroyed on suspend, so a resumed file/shell tool would act on a fresh " +
+                                    "(empty) env. Use a RemoteExecutionEnv factory (it is paused, not destroyed) or a static, " +
+                                    "caller-owned RunnerDeps.executionEnv.");
                         }
                         const leafId = await session.getLeafId();
                         if (!leafId) {
@@ -2951,6 +3045,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                 await sweepBackgroundShells(remoteEnv, defaultTaskRegistry);
                             const snap = await remoteEnv.suspendVM({ abortSignal: abortController.signal });
                             if (!snap.ok) {
+                                remoteEnvFailures.push(remoteEnvFailureNote("suspendVM", snap.error, 1));
                                 throw new Error(`suspendVM failed (${snap.error.code}): ${snap.error.message}`, { cause: snap.error });
                             }
                             remoteHandle = { ...remoteEnv.workspaceHandle(), snapshotId: snap.value };
@@ -3039,7 +3134,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (!(await commitSuspendSaga(token, cp, remoteEnv, remoteHandle))) {
                         return undefined;
                     }
-                    publishCommittedSuspend(token, gate, cp.scope);
+                    publishCommittedSuspend(token, gate, cp.scope, remoteHandle);
                     try {
                         await sessions.pin?.(sessionId);
                     }
@@ -3388,7 +3483,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, cacheBreakDetector, cacheFingerprint, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), ownedEnv, suspendRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(callCapRef ? { callCapRef } : {}), ...(cutKills ? { cutKills } : {}), ...(callCapRef ? { callIssuedAtRef } : {}), suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, promptOverheadTokens, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;

package/dist/core/runner/runtask.js

@@ -222,6 +222,7 @@ function resumeContinuation(resume) {
 }
 function makeTurnBoundary(prepared, stats, rs, deps) {
     const { spec, queue, manualCompactRef, todoToolMounted, taskToolsMounted, turnToolSpan, walltimeDeadlineMs, walltimeMonotonicDeadline, nudgeSchedule, buildFinalizeText, timeout, ident, postToolBatchHook, batchArgs, compactionBrain, withinTaskCompaction, compactionBreaker, windowSafetyOptions, rapidRefill, drainManualCompact, runnerHooks } = deps;
+    let finalVerifySeenAtLastBoundary = 0;
     const onTurnBoundary = async (event) => {
         if (prepared.callCapRef && turnToolSpan.startMin !== undefined && turnToolSpan.endMax !== undefined) {
             recordToolCycleSample(prepared.callCapRef.state, turnToolSpan.endMax - turnToolSpan.startMin);
@@ -499,11 +500,13 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             }
         }
         let batchContextBlock;
+        const finalVerifyInjectedThisTurn = rs.counters.finalVerifyInjections !== finalVerifySeenAtLastBoundary;
+        finalVerifySeenAtLastBoundary = rs.counters.finalVerifyInjections;
         if (postToolBatchHook !== undefined && rs.turn.toolBatch.length > 0) {
             const batch = rs.turn.toolBatch;
             rs.turn.toolBatch = [];
             batchArgs?.clear();
-            if (!boundarySteered && !rs.counters.finalizeInjected && rs.counters.finalVerifyInjections === 0 && !prepared.abortController.signal.aborted) {
+            if (!boundarySteered && !rs.counters.finalizeInjected && !finalVerifyInjectedThisTurn && !prepared.abortController.signal.aborted) {
                 try {
                     const r = await postToolBatchHook(batch);
                     if (r?.additionalContext) {
@@ -1345,6 +1348,16 @@ export class Runner {
                 queue.close();
                 return;
             }
+            const remoteEnvFailure = (() => {
+                let cur = err;
+                for (let depth = 0; cur && typeof cur === "object" && depth < 8; depth++) {
+                    const note = cur.remoteEnvFailure;
+                    if (note !== undefined)
+                        return [note];
+                    cur = cur.cause;
+                }
+                return undefined;
+            })();
             resultValue = {
                 taskId: taskIdRef.current ?? "unknown",
                 sessionId: taskIdRef.sessionId ?? "unknown",
@@ -1352,6 +1365,7 @@ export class Runner {
                 result: "",
                 errorMessage: err instanceof Error ? err.message : String(err),
                 errorCode: code,
+                ...(remoteEnvFailure !== undefined ? { remoteEnvFailures: remoteEnvFailure } : {}),
                 stats: { turns: 0, tokens: 0, toolCalls: 0, cachedTokens: 0, costMicroUsd: 0 },
             };
             emitTrace(spec.tracer ?? this.deps.tracer, () => ({
@@ -1651,6 +1665,9 @@ export class Runner {
             const gateToolName = "toolName" in resume.cp.gate ? resume.cp.gate.toolName : undefined;
             prepared.humanReviewRef.gates.push({ kind: resume.cp.gate.kind, waitMs, ...(decision !== undefined ? { decision } : {}), ...(gateToolName !== undefined ? { toolName: gateToolName } : {}) });
         }
+        if (resume !== undefined && resume.outcome.gate === "plan_review" && resume.outcome.decision === "reject") {
+            prepared.planModeRef.active = true;
+        }
         const rs = createRunState();
         rs.telemetry.cacheFamily = cacheFamilyOf(prepared.model);
         rs.telemetry.pricing = this.deps.pricing?.[prepared.model.id] ?? modelCostToPricing(prepared.model.cost);
@@ -2520,13 +2537,26 @@ export class Runner {
                 let promptBlocked = false;
                 const userPromptSubmit = (spec.hooks ?? this.deps.hooks)?.userPromptSubmit;
                 if (userPromptSubmit) {
-                    const decision = await userPromptSubmit(spec.objective);
-                    if (decision?.block) {
-                        prepared.blockedRef.reason = formatHookFeedback(decision.block);
-                        promptBlocked = true;
+                    try {
+                        const decision = await userPromptSubmit(spec.objective);
+                        if (decision?.block) {
+                            prepared.blockedRef.reason = formatHookFeedback(decision.block);
+                            promptBlocked = true;
+                        }
+                        else if (decision?.additionalContext) {
+                            effectiveObjective = `${formatHookFeedback(decision.additionalContext)}\n\n${spec.objective}`;
+                        }
                     }
-                    else if (decision?.additionalContext) {
-                        effectiveObjective = `${formatHookFeedback(decision.additionalContext)}\n\n${spec.objective}`;
+                    catch (hookErr) {
+                        const err = hookErr instanceof Error ? hookErr : new Error(String(hookErr));
+                        try {
+                            this.deps.onError?.(err, { phase: "hook", sessionId: prepared.sessionId });
+                        }
+                        catch {
+                        }
+                        prepared.blockedRef.reason = formatHookFeedback(`the deployment's userPromptSubmit hook crashed while screening this prompt (${err.message}); ` +
+                            `the prompt was NOT submitted (fail-closed)`);
+                        promptBlocked = true;
                     }
                 }
                 const firstFrames = [];
@@ -2765,6 +2795,7 @@ export class Runner {
                 model: prepared.model.id,
                 unpricedSpend: rs.telemetry.unpricedSpend,
                 rewindNotes: prepared.rewindNotes,
+                remoteEnvFailures: prepared.remoteEnvFailures,
                 abortedForTimeout: timeout.fired,
                 abortedForTurns: rs.limits.turnsExceeded,
                 abortedLive,
@@ -2774,10 +2805,18 @@ export class Runner {
                 outputInvalid: rs.degrade.outputInvalid,
                 suspendLoop: prepared.suspendLoopRef.hit,
                 suspendRef: prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined
-                    ? { token: prepared.suspendRef.token, gate: prepared.suspendRef.gate }
+                    ? {
+                        token: prepared.suspendRef.token,
+                        gate: prepared.suspendRef.gate,
+                        ...(prepared.suspendRef.restoreMode !== undefined ? { restoreMode: prepared.suspendRef.restoreMode } : {}),
+                    }
                     : undefined,
                 reviewRef: prepared.reviewRef.token !== undefined && prepared.reviewRef.gate !== undefined
-                    ? { token: prepared.reviewRef.token, gate: prepared.reviewRef.gate }
+                    ? {
+                        token: prepared.reviewRef.token,
+                        gate: prepared.reviewRef.gate,
+                        ...(prepared.reviewRef.restoreMode !== undefined ? { restoreMode: prepared.reviewRef.restoreMode } : {}),
+                    }
                     : undefined,
             });
             if (resume !== undefined &&
@@ -3082,7 +3121,7 @@ export class Runner {
             if (!r.ok) {
                 const tooLarge = r.error.code === "too_large";
                 const refusedAt = Date.now();
-                if (tooLarge)
+                if (tooLarge && !this.snapshotTooLargeRoots.has(root))
                     this.snapshotTooLargeRoots.set(root, { refusedAt, skipAnnounced: false });
                 try {
                     this.deps.onError?.(new Error(`rewind-files snapshot failed (${r.error.code}): ${r.error.message}` +

package/dist/core/runner/tool-disclosure.d.ts

@@ -57,4 +57,5 @@ export declare function createToolSearchTool(opts: {
     listingRide?: (newlyActivated: readonly string[]) => string | undefined;
     mountedNames?: () => ReadonlySet<string>;
     directCallEnabled?: boolean;
+    serializeActivation?: <T>(section: () => Promise<T>) => Promise<T>;
 }): AgentTool;

package/dist/core/runner/tool-disclosure.js

@@ -172,11 +172,22 @@ export function resolveToolSearch(args, registry) {
 export function extractDiscoveredToolNames(messages, registry) {
     const names = new Set();
     const pendingDirect = new Map();
+    const pendingSearch = new Map();
     for (const m of messages) {
         if (m.role === "toolResult") {
             const name = pendingDirect.get(m.toolCallId);
-            if (name !== undefined && m.isError !== true)
-                names.add(name);
+            if (name !== undefined) {
+                pendingDirect.delete(m.toolCallId);
+                if (m.isError !== true)
+                    names.add(name);
+            }
+            const searched = pendingSearch.get(m.toolCallId);
+            if (searched !== undefined) {
+                pendingSearch.delete(m.toolCallId);
+                if (m.isError !== true)
+                    for (const n of searched)
+                        names.add(n);
+            }
             continue;
         }
         if (m.role !== "assistant")
@@ -185,15 +196,18 @@ export function extractDiscoveredToolNames(messages, registry) {
             if (part.type !== "toolCall")
                 continue;
             if (part.name === TOOL_SEARCH_NAME) {
-                for (const n of resolveToolSearch(part.arguments, registry)) {
-                    names.add(n);
-                }
+                const prior = pendingSearch.get(part.id);
+                const resolved = resolveToolSearch(part.arguments, registry);
+                pendingSearch.set(part.id, prior === undefined ? resolved : [...prior, ...resolved]);
             }
             else if (registry.has(part.name)) {
                 pendingDirect.set(part.id, part.name);
             }
         }
     }
+    for (const list of pendingSearch.values())
+        for (const n of list)
+            names.add(n);
     return [...names];
 }
 export function createToolSearchTool(opts) {
@@ -209,6 +223,12 @@ export function createToolSearchTool(opts) {
             "first. When any instruction, reminder, or another tool's description names a deferred tool, activate it " +
             'with query "select:<name>" before calling it. ';
     let activationChain = Promise.resolve();
+    const serializeActivation = opts.serializeActivation ??
+        ((section) => {
+            const p = activationChain.then(section);
+            activationChain = p.then(() => undefined, () => undefined);
+            return p;
+        });
     return defineTool({
         name: TOOL_SEARCH_NAME,
         contract: { contractId: "core.tool_search@1", implementationRevision: "1" },
@@ -259,7 +279,7 @@ export function createToolSearchTool(opts) {
                     },
                 };
             }
-            const section = activationChain.then(async () => {
+            const section = serializeActivation(async () => {
                 const newly = matched.filter((n) => !active.has(n));
                 if (newly.length > 0) {
                     for (const n of newly)
@@ -275,7 +295,6 @@ export function createToolSearchTool(opts) {
                 }
                 return { newly, ride: newly.length > 0 ? listingRide?.(newly) : undefined };
             });
-            activationChain = section.then(() => undefined, () => undefined);
             const { newly, ride } = await section;
             const lines = matched.map((n) => {
                 const info = registry.get(n);

package/dist/core/session-store.js

@@ -114,6 +114,11 @@ export class TtlSessionStore {
         }
         const forked = await this.repo.fork(await source.getMetadata(), forkParams);
         const meta = await forked.getMetadata();
+        const inherited = this.owners.has(sourceId) ? this.owners.get(sourceId) : undefined;
+        const forkOwner = owner ?? inherited;
+        if (forkOwner !== undefined && !this.owners.has(meta.id)) {
+            this.owners.set(meta.id, forkOwner);
+        }
         this.entries.set(meta.id, {
             session: forked,
             lastActiveAt: Date.now(),
@@ -149,8 +154,13 @@ export class TtlSessionStore {
         return this.owners.has(sessionId) ? this.owners.get(sessionId) : undefined;
     }
     async register(sessionId, owner) {
-        if (!this.owners.has(sessionId))
-            this.owners.set(sessionId, owner);
+        if (this.owners.has(sessionId)) {
+            return;
+        }
+        if (owner !== null && typeof owner !== "string") {
+            throw new TypeError(`SessionStore.register: owner must be a string (owned) or null (anonymous), got ${owner === undefined ? "undefined" : typeof owner}`);
+        }
+        this.owners.set(sessionId, owner);
     }
     sweep(now = Date.now()) {
         for (const [id, e] of this.entries) {
@@ -160,8 +170,9 @@ export class TtlSessionStore {
             if (now - e.lastActiveAt > this.defaultTtlMs) {
                 this.entries.delete(id);
                 if (this.evictPolicy === "delete") {
-                    void this.repo.delete({ id, createdAt: "" });
-                    this.owners.delete(id);
+                    void this.repo.delete({ id, createdAt: "" }).then(() => {
+                        this.owners.delete(id);
+                    }, () => { });
                 }
             }
         }

package/dist/core/skill-tool-specifier.d.ts

@@ -0,0 +1,8 @@
+export interface SkillToolEntry {
+    readonly raw: string;
+    readonly name: string;
+    readonly specifier?: string;
+}
+export declare function parseSkillToolEntry(entry: string): SkillToolEntry;
+export declare function isSkillSpecifierEnforced(canonicalName: string): boolean;
+export declare function skillSpecifierRejection(entry: SkillToolEntry, args: unknown): string | undefined;