@sema-agent/core 2.11.0 → 2.12.0

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

@@ -242,6 +242,7 @@ export interface CheckpointSummary {
     contentKind?: "content_ask";
     createdAt?: number;
     toolInput?: string;
+    restoreMode?: "snapshot" | "park_only";
     preview?: unknown;
 }
 export declare function summarizeCheckpoint(cp: Checkpoint): CheckpointSummary;

package/dist/core/checkpoint-store.js

@@ -181,6 +181,9 @@ export function summarizeCheckpoint(cp) {
         ...(tool !== undefined ? { toolCallId: tool.toolCallId, toolName: tool.toolName } : {}),
         ...(tool?.toolName === ASK_USER_QUESTION_TOOL_NAME ? { contentKind: "content_ask" } : {}),
         ...(toolInput !== undefined ? { toolInput } : {}),
+        ...(cp.state.workspaceHandle !== undefined
+            ? { restoreMode: cp.state.workspaceHandle.restoreMode === "park_only" ? "park_only" : "snapshot" }
+            : {}),
         ...(tool?.preview !== undefined ? { preview: tool.preview } : {}),
     };
 }

package/dist/core/mcp.d.ts

@@ -57,6 +57,7 @@ export interface McpServerStatus {
     };
     toolNames?: string[];
     error?: string;
+    transportClosed?: boolean;
 }
 export declare const MCP_PREFIX = "mcp__";
 export declare function resolveMcpDeclaredResultSize(meta: Record<string, unknown> | undefined): number | undefined;
@@ -69,6 +70,7 @@ export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
+export declare function collapseMcpErrorPrefix(message: string): string;
 export declare function normalizeMcpName(name: string): string;
 export declare function clampNameSegment(seg: string, max?: number): string;
 export * from "./image-downsample.js";

package/dist/core/mcp.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -145,8 +145,24 @@ const MCP_SPEC_ERROR_CODE_NAMES = new Map([
 export function describeMcpSpecErrorCode(code) {
     return typeof code === "number" ? MCP_SPEC_ERROR_CODE_NAMES.get(code) : undefined;
 }
+export function collapseMcpErrorPrefix(message) {
+    let out = message;
+    for (;;) {
+        const m = /^MCP error (-?\d+): (?=MCP error \1: )/.exec(out);
+        if (m === null)
+            return out;
+        out = out.slice(m[0].length);
+    }
+}
+function collapseMcpErrorStampInPlace(err) {
+    if (!(err instanceof McpError))
+        return;
+    const collapsed = collapseMcpErrorPrefix(err.message);
+    if (collapsed !== err.message)
+        err.message = collapsed;
+}
 function namedMcpFailureText(err) {
-    const detail = err instanceof Error ? err.message : String(err);
+    const detail = err instanceof Error ? collapseMcpErrorPrefix(err.message) : String(err);
     const condition = err instanceof McpError ? describeMcpSpecErrorCode(err.code) : undefined;
     return condition !== undefined ? `${condition}: ${detail}` : detail;
 }
@@ -155,6 +171,53 @@ function isTransportLost(err) {
         return true;
     return err instanceof Error && /not connected|connection closed/i.test(err.message);
 }
+const NETWORK_CODES_NEVER_DELIVERED = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+function networkErrorCode(err, depth = 0) {
+    if (depth > 5 || !(err instanceof Error))
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string" && /^(?:E[A-Z]+|UND_ERR_[A-Z_]+)$/.test(code))
+        return code;
+    if (err instanceof AggregateError) {
+        for (const inner of err.errors) {
+            const found = networkErrorCode(inner, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return networkErrorCode(err.cause, depth + 1);
+}
+function describeHttpTransportFailure(err) {
+    if (err instanceof McpError)
+        return undefined;
+    if (err instanceof StreamableHTTPError) {
+        const status = typeof err.code === "number" && err.code > 0 ? err.code : undefined;
+        return {
+            condition: status !== undefined
+                ? `its HTTP endpoint answered ${status} instead of an MCP response`
+                : "its HTTP endpoint answered something that is not an MCP response",
+            delivered: "unknown",
+            ...(status !== undefined ? { httpStatus: status } : {}),
+        };
+    }
+    const code = networkErrorCode(err);
+    if (code !== undefined) {
+        return NETWORK_CODES_NEVER_DELIVERED.has(code)
+            ? { condition: `its HTTP endpoint could not be reached (${code})`, delivered: "no" }
+            : { condition: `the connection to its HTTP endpoint failed (${code})`, delivered: "unknown" };
+    }
+    if (err instanceof TypeError && /fetch failed|terminated|network/i.test(err.message)) {
+        return { condition: "the HTTP request to its endpoint failed at the network layer", delivered: "unknown" };
+    }
+    return undefined;
+}
 function writeEffectWarning(writeEffect) {
     return writeEffect
         ? " This tool is write-capable: treat its side effects as POSSIBLY APPLIED and verify the actual state before retrying."
@@ -173,6 +236,7 @@ function rethrowHonestMcpError(err, ctx) {
     }
     if (ctx.signal?.aborted)
         throw err;
+    collapseMcpErrorStampInPlace(err);
     const serverLabel = inlineUntrusted(ctx.server);
     if (err instanceof McpError && err.code === ErrorCode.RequestTimeout) {
         const data = err.data;
@@ -193,6 +257,21 @@ function rethrowHonestMcpError(err, ctx) {
         e.details = { transportLost: true, server: ctx.server };
         throw e;
     }
+    const httpFailure = describeHttpTransportFailure(err);
+    if (httpFailure !== undefined) {
+        const detail = err instanceof Error ? err.message : String(err);
+        const fenced = `\nThe transport error follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} transport error`, truncateMcpErrorText(detail))}`;
+        const e = new Error(httpFailure.delivered === "no"
+            ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
+            : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err });
+        e.errorKind = httpFailure.delivered === "no" ? "server_disconnected" : "transport_lost";
+        e.details = {
+            server: ctx.server,
+            ...(httpFailure.delivered === "no" ? {} : { transportLost: true }),
+            ...(httpFailure.httpStatus !== undefined ? { httpStatus: httpFailure.httpStatus } : {}),
+        };
+        throw e;
+    }
     if (err instanceof McpError) {
         const condition = describeMcpSpecErrorCode(err.code);
         if (condition !== undefined) {
@@ -546,12 +625,16 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     serverInstructions.push({ server: spec.name, text: s.instructions });
                 }
                 const hasInstructions = s.instructions !== undefined;
-                s.announce.fn = () => {
-                    if (!disposing && hasInstructions)
+                const announceClose = () => {
+                    if (disposing)
+                        return;
+                    s.status.transportClosed = true;
+                    if (hasInstructions)
                         instructionsDelta.pendingRemovals.push(spec.name);
                 };
-                if (s.health.dead && hasInstructions)
-                    instructionsDelta.pendingRemovals.push(spec.name);
+                s.announce.fn = announceClose;
+                if (s.health.dead)
+                    announceClose();
                 if (s.resourceServer)
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)

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

@@ -44,6 +44,8 @@ export interface ExecStreamOptions {
     maxOutputBytes?: number;
 }
 export type RemoteExecutionErrorCode = "suspended" | "command_in_flight" | "connect_failed" | "post_resume_failed" | "aborted" | "timeout" | "unsupported" | "auth_transient" | "auth_failed" | "transport_lost" | "unknown";
+export declare const RETRYABLE_REMOTE_ERROR_CODES: readonly RemoteExecutionErrorCode[];
+export declare function isRetryableRemoteErrorCode(code: RemoteExecutionErrorCode): boolean;
 export declare class RemoteExecutionError extends Error {
     readonly code: RemoteExecutionErrorCode;
     constructor(code: RemoteExecutionErrorCode, message: string, cause?: Error);
@@ -101,5 +103,6 @@ export interface ExecutionEnvFactoryContext {
 export type ExecutionEnvFactory = (ctx: ExecutionEnvFactoryContext) => ExecutionEnv | Promise<ExecutionEnv>;
 export declare function hasDestroy(env: ExecutionEnv): env is ExecutionEnv & Pick<RemoteExecutionEnv, "destroy">;
 export declare function isRemoteExecutionEnv(env: ExecutionEnv): env is RemoteExecutionEnv;
+export declare function missingRestoreSurface(env: ExecutionEnv): readonly ("resumeVM" | "postResumeInit")[];
 export declare function isSuspendable(env: ExecutionEnv): env is RemoteExecutionEnv;
 export declare function isIsolated(env: ExecutionEnv): boolean;

package/dist/core/remote-env.js

@@ -1,3 +1,12 @@
+export const RETRYABLE_REMOTE_ERROR_CODES = [
+    "auth_transient",
+    "connect_failed",
+    "timeout",
+    "transport_lost",
+];
+export function isRetryableRemoteErrorCode(code) {
+    return RETRYABLE_REMOTE_ERROR_CODES.includes(code);
+}
 export class RemoteExecutionError extends Error {
     code;
     constructor(code, message, cause) {
@@ -18,8 +27,17 @@ export function isRemoteExecutionEnv(env) {
         typeof e.capabilities === "object" &&
         e.capabilities !== null);
 }
+export function missingRestoreSurface(env) {
+    const e = env;
+    const missing = [];
+    if (typeof e.resumeVM !== "function")
+        missing.push("resumeVM");
+    if (typeof e.postResumeInit !== "function")
+        missing.push("postResumeInit");
+    return missing;
+}
 export function isSuspendable(env) {
-    return isRemoteExecutionEnv(env) && env.capabilities.suspendable;
+    return isRemoteExecutionEnv(env) && env.capabilities.suspendable && missingRestoreSurface(env).length === 0;
 }
 export function isIsolated(env) {
     return isRemoteExecutionEnv(env) ? env.capabilities.isolation : false;

package/dist/core/runner/assemble-result.d.ts

@@ -70,6 +70,7 @@ export interface ResultFlags {
     model?: string;
     unpricedSpend?: boolean;
     rewindNotes?: TaskResult["rewindNotes"];
+    remoteEnvFailures?: TaskResult["remoteEnvFailures"];
     abortedForTimeout: boolean;
     abortedForTurns: boolean;
     abortedLive?: boolean;
@@ -81,10 +82,12 @@ export interface ResultFlags {
     suspendRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        restoreMode?: "snapshot" | "park_only";
     };
     reviewRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
         gate: import("../checkpoint-store.js").CheckpointGate;
+        restoreMode?: "snapshot" | "park_only";
     };
 }
 export declare function errorCodeOf(err: unknown): string | undefined;

package/dist/core/runner/assemble-result.js

@@ -54,6 +54,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     let salvagedOutput;
     let checkpointToken;
     let checkpointGate;
+    let workspaceRestoreMode;
     const isDegenerate = final?.stopReason === "error" && final.errorMessage === DEGENERATE_MESSAGE;
     const isWalltimeCutoff = final?.stopReason === "error" && final.errorMessage === WALLTIME_CUTOFF_MESSAGE;
     if (flags.outputInvalid) {
@@ -105,12 +106,14 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         status = "suspended";
         checkpointToken = flags.suspendRef.token;
         checkpointGate = flags.suspendRef.gate;
+        workspaceRestoreMode = flags.suspendRef.restoreMode;
     }
     else if (flags.reviewRef) {
         status = "needs_review";
         errorCode = "review.pending";
         checkpointToken = flags.reviewRef.token;
         checkpointGate = flags.reviewRef.gate;
+        workspaceRestoreMode = flags.reviewRef.restoreMode;
     }
     else if (flags.abortedLive || final?.stopReason === "aborted") {
         status = flags.abortedForTimeout ? "timeout" : "failed";
@@ -143,5 +146,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), stats: publicStats };
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, checkpointToken, checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), stats: publicStats };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -127,12 +127,15 @@ export interface Prepared {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
+        restoreMode?: "snapshot" | "park_only";
     };
     reviewRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;
         scope?: string;
+        restoreMode?: "snapshot" | "park_only";
     };
+    remoteEnvFailures: NonNullable<TaskResult["remoteEnvFailures"]>;
     suspendLoopRef: {
         hit: boolean;
     };
@@ -340,4 +343,5 @@ export declare function batchContextAt(messages: AgentMessage[], currentId: stri
     completedCallIds: string[];
 };
 export declare function rebaseWorkspacePath(p: string, fromRaw: string, toRaw: string): string;
+export declare function rebaseWorkspacePathAcross(p: string, froms: readonly string[], to: string): string;
 export declare function prepareTask(spec: TaskSpec, deps: RunnerDeps, sessions: SessionStore, resume?: PrepareResume, internals?: RunInternals, runnerSelf?: Runner): Promise<Prepared>;

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,
@@ -558,11 +580,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 +594,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 +605,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 +648,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 +1007,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 };
@@ -2541,16 +2601,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 +2791,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 +2812,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 +2834,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 +2861,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 +2896,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 +2913,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 +2940,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 +2979,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 +3013,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 +3036,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 +3125,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 +3474,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

@@ -1345,6 +1345,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 +1362,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, () => ({
@@ -2765,6 +2776,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 +2786,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 &&

package/dist/core/types.d.ts

@@ -370,6 +370,13 @@ export interface TaskSpec {
     signal?: AbortSignal;
 }
 export type TaskStatus = "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review";
+export interface RemoteEnvFailureNote {
+    op: "suspendVM" | "resumeVM" | "postResumeInit";
+    code: import("./remote-env.js").RemoteExecutionErrorCode;
+    retryable: boolean;
+    attempts: number;
+    message: string;
+}
 export interface TaskResult {
     taskId: string;
     sessionId: string;
@@ -380,6 +387,8 @@ export interface TaskResult {
     blockedReason?: string;
     checkpointToken?: import("./checkpoint-store.js").CheckpointToken;
     checkpointGate?: import("./checkpoint-store.js").CheckpointGate;
+    workspaceRestoreMode?: "snapshot" | "park_only";
+    remoteEnvFailures?: RemoteEnvFailureNote[];
     errorMessage?: string;
     errorCode?: string;
     degraded?: {

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

@@ -47,7 +47,7 @@ export declare class FileError extends Error {
     path?: string;
     constructor(code: FileErrorCode, message: string, path?: string, cause?: Error);
 }
-export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "transport_lost" | "unknown";
+export type ExecutionErrorCode = "aborted" | "timeout" | "shell_unavailable" | "spawn_error" | "callback_error" | "transport_lost" | "suspended" | "auth_failed" | "unknown";
 export declare class ExecutionError extends Error {
     code: ExecutionErrorCode;
     partialStdout?: string;

package/dist/index.d.ts

@@ -56,7 +56,7 @@ export { getShellConfig, isWslBashLauncher } from "./engine/execution-env/node-e
 export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
 export type { ExecutionEnv, FileInfo, Result, FileErrorCode, ExecutionErrorCode } from "./internal/harness.js";
-export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, } from "./core/remote-env.js";
+export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
 export { withRetry } from "./core/with-retry.js";
 export type { RetryPolicy, RetryResult } from "./core/with-retry.js";
 export type { RemoteExecutionEnv, WorkspaceHandle, SnapshotId, SessionToken, SandboxTier, OutputChunk, ExecStreamOptions, RemoteConnectConfig, VmLifecycleOptions, SecretRef, RemoteExecutionErrorCode, ExecutionEnvFactory, ExecutionEnvFactoryContext, } from "./core/remote-env.js";
@@ -189,7 +189,7 @@ export { retryBackoffMs, parseRetryAfter } from "./brain/retry.js";
 export { type BrainTimeoutConfig } from "./brain/timeout.js";
 export { createAssistantMessageEventStream } from "./internal/llm.js";
 export type { AssistantMessage, AssistantMessageEvent, 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, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskResult, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolEffect, WorkflowGovernanceBaseline, } from "./core/types.js";
+export type { AgentDefinition, BeforeWriteHook, BeforeWriteRequest, BeforeWriteResult, HandsBandOptions, Brain, BrainStatus, BrainStatusPhase, ImageInput, McpElicitRequest, McpElicitResponse, McpServerSpec, OnElicit, Model, ModelRef, ProjectMemoryLoad, RunnerDeps, RuntimeCaps, BackgroundChildEvent, SkillManifest, SkillSpec, TaskEvent, TaskEventIdentity, ToolActivity, TaskResult, RemoteEnvFailureNote, TaskSpec, TaskStatus, TaskStream, CompactOutcome, ThinkingLevel, ToolExecuteContext, ToolReturn, ToolSpec, ToolEffect, WorkflowGovernanceBaseline, } 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/index.js

@@ -51,7 +51,7 @@ export { killProcessTree, signalProcessTree } from "./engine/execution-env/kill-
 export { getShellConfig, isWslBashLauncher } from "./engine/execution-env/node-execution-env.js";
 export { isSecretEnvKey, scrubSecretEnv } from "./core/secret-env.js";
 export { MAX_EXEC_OUTPUT_BYTES, RollingTailBuffer, markTruncated } from "./core/exec-output-tail.js";
-export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, } from "./core/remote-env.js";
+export { RemoteExecutionError, hasDestroy, isRemoteExecutionEnv, isSuspendable, isIsolated, missingRestoreSurface, isRetryableRemoteErrorCode, RETRYABLE_REMOTE_ERROR_CODES, } from "./core/remote-env.js";
 export { withRetry } from "./core/with-retry.js";
 export { addWorktree, pruneWorktrees, WORKTREE_PARENT } from "./core/git-worktree-env.js";
 export { runExecGate } from "./core/exec-gate.js";

package/dist/tools/fs/fs-bash.js

@@ -229,6 +229,20 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
                 isError: true,
             };
         }
+        if (res.error.code === "suspended") {
+            return {
+                content: `Error (${toolName}): the execution environment is suspended (its workspace VM is paused), so the command did NOT run and no command can run in this leg. Do not retry it here — the task must be resumed first; report that the workspace is suspended. (${res.error.message})`,
+                details: { type: "bash", envSuspended: true },
+                isError: true,
+            };
+        }
+        if (res.error.code === "auth_failed") {
+            return {
+                content: `Error (${toolName}): authentication to the execution environment was rejected, so the command did NOT run. Do NOT retry — this is a permanent credential failure that an operator must fix; report it instead of trying other commands. (${res.error.message})`,
+                details: { type: "bash", authFailed: true },
+                isError: true,
+            };
+        }
         if (res.error.code === "timeout" || res.error.code === "aborted" || res.error.code === "callback_error") {
             const rawStdout = res.error.partialStdout ?? "";
             const rawStderr = res.error.partialStderr ?? "";

package/dist/tools/scheduler-tools.js

@@ -83,16 +83,13 @@ function expandCronField(field, { min, max }) {
     return out.size > 0 ? [...out].sort((a, b) => a - b) : null;
 }
 export function cronScheduleError(expr) {
-    const parts = expr.trim().split(/\s+/);
-    let std = parts;
-    if (parts.length === 6) {
-        if (!expandCronField(parts[0] ?? "", { min: 0, max: 59 })) {
-            return `invalid seconds field "${parts[0]}" — allowed 0-59 (syntax: N, N-M, */N, comma lists).`;
-        }
-        std = parts.slice(1);
+    const std = expr.trim().split(/\s+/);
+    if (std.length === 6) {
+        return (`its leading seconds field is not supported — the resident scheduler fires on 5-field cron, so one ` +
+            `minute is the finest granularity available. Pass "${std.slice(1).join(" ")}" if that cadence works.`);
     }
-    else if (parts.length !== 5) {
-        return `expected 5 fields (minute hour day-of-month month day-of-week) or 6 with leading seconds, got ${parts.length}.`;
+    if (std.length !== 5) {
+        return `expected 5 fields (minute hour day-of-month month day-of-week), got ${std.length}.`;
     }
     const expanded = [];
     for (let i = 0; i < 5; i++) {
@@ -117,9 +114,12 @@ export function cronScheduleError(expr) {
     return null;
 }
 const DAY_NAMES = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+function cronExprFromSummary(when) {
+    const trimmed = when.trim();
+    return trimmed.startsWith("cron ") ? trimmed.slice("cron ".length).trim() : trimmed;
+}
 export function cronToHuman(expr) {
-    const parts = expr.trim().split(/\s+/);
-    const std = parts.length === 6 ? parts.slice(1) : parts;
+    const std = cronExprFromSummary(expr).split(/\s+/);
     if (std.length !== 5)
         return expr;
     const [minute = "", hour = "", dom = "", month = "", dow = ""] = std;
@@ -191,7 +191,10 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
         parameters: Type.Object({
             prompt: Type.String({ description: "Self-contained instructions for the future task (it runs unattended)." }),
             schedule: Type.Optional(Type.Union([
-                Type.Object({ kind: Type.Literal("cron"), expr: Type.String({ description: "5- or 6-field cron expression." }) }),
+                Type.Object({
+                    kind: Type.Literal("cron"),
+                    expr: Type.String({ description: "5-field cron expression (minute hour day-of-month month day-of-week)." }),
+                }),
                 Type.Object({ kind: Type.Literal("at"), atMs: Type.Number({ description: "Absolute epoch ms to fire once." }) }),
                 Type.Object({ kind: Type.Literal("delay"), delaySec: Type.Number({ description: "Seconds from now to fire once." }) }),
             ], { description: 'When to fire. Pass exactly one of `schedule` or `cron`. Defaults to `durable: true`.' })),
@@ -246,22 +249,32 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
                 ...(!durable ? { lifetime: "session" } : {}),
                 ...(a.recurring !== undefined ? { recurring: a.recurring } : {}),
             };
+            const before = await sched.list(schedCtx);
+            const knownIds = before.ok ? new Set(before.value.map((s) => s.id)) : undefined;
             const r = await sched.schedule(intent, schedCtx);
             if (!r.ok)
                 return errorResult(`Error (CronCreate): ${r.error.message}`);
+            const replaced = knownIds?.has(r.value.id);
             const humanSchedule = when.kind === "cron"
                 ? cronToHuman(when.expr)
                 : when.kind === "delay"
                     ? `once in ${when.delaySec}s`
                     : `once at ${new Date(when.atMs).toISOString()}`;
+            const named = `${r.value.id}${a.label ? ` (${a.label})` : ""}`;
+            const content = replaced === true
+                ? `Updated scheduled task ${named} — it replaced an existing job with the same schedule and label, whose prompt is now gone.`
+                : replaced === false
+                    ? `Scheduled task ${named}.`
+                    : `Scheduled (or updated) task ${named} — the scheduler's listing was unavailable, so whether this replaced an existing job with the same schedule and label is unknown.`;
             return {
-                content: `Scheduled task ${r.value.id}${a.label ? ` (${a.label})` : ""}.`,
+                content,
                 details: {
                     type: "cron-create",
                     id: r.value.id,
                     humanSchedule,
                     recurring: when.kind === "cron" && a.recurring !== false,
                     durable,
+                    ...(replaced !== undefined ? { replaced } : {}),
                 },
             };
         },
@@ -298,17 +311,18 @@ Only use minute 0 or 30 when the user names that exact time and clearly means it
             }
             const content = r.value
                 .map((s) => {
+                const shown = cronExprFromSummary(s.when);
                 const human = cronToHuman(s.when);
                 const tier = s.lifetime === "session" ? " [session]" : "";
                 const once = s.recurring === false ? " [once]" : "";
-                return `- ${s.id}: ${s.when}${human !== s.when ? ` — ${human}` : ""}${s.label ? ` (${s.label})` : ""}${tier}${once}`;
+                return `- ${s.id}: ${shown}${human !== s.when ? ` — ${human}` : ""}${s.label ? ` (${s.label})` : ""}${tier}${once}`;
             })
                 .join("\n");
             const jobs = r.value.map((s) => {
                 const human = cronToHuman(s.when);
                 return {
                     id: s.id,
-                    cron: s.when,
+                    cron: cronExprFromSummary(s.when),
                     humanSchedule: human !== s.when ? human : s.when,
                     ...(s.label !== undefined ? { label: s.label } : {}),
                     ...(s.recurring !== undefined ? { recurring: s.recurring } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",