@sema-agent/core 5.7.0 → 5.8.0

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

@@ -19,8 +19,6 @@ import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import { combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets } from "../tool-policy.js";
 import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
-import { computeCallCap, createCallCapRef, softExecDeadlineMs, toolCutDeadlineMs, WALLTIME_STALL_CONNECT_MS, WALLTIME_STALL_FIRST_TOKEN_MS, WALLTIME_STALL_IDLE_MS } from "./call-cap.js";
-import { createCutKillRegistry } from "./cut-kill.js";
 import { CHANGED_FILES_MTIME_EPS_MS, fenceMcpServerInstructions, renderAgentListingDelta } from "./turn-attachments.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { emitTrace } from "../trace.js";
@@ -29,7 +27,7 @@ import { cloneObserverInput, formatHookFeedback, runToolGate } from "../hooks.js
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
 import { reservedCollisions, reservedFor } from "../../brain/request-params.js";
-import { resolveBrainCallGuardrailMs, withBrainCallGuardrail } from "../../brain/timeout.js";
+import { resolveBrainCallGuardrailMs, STALL_CONNECT_MS, STALL_FIRST_TOKEN_MS, STALL_IDLE_MS, withBrainCallGuardrail } from "../../brain/timeout.js";
 import { defineTool, isDefineToolProduct } from "../tools.js";
 import { RETIRED_TOOL_NAMES } from "../tool-name-aliases.js";
 import { protocolOf, PROTOCOL_TABLE } from "../protocol-table.js";
@@ -69,13 +67,96 @@ import { createRunWorkflowTool, RUN_WORKFLOW_TOOL_NAME } from "../../orchestrati
 import { resolveWorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { createLspTool, gitCheckIgnoreFilter, resolveLspPath } from "../lsp.js";
 import { resolveKey } from "../../tools/fs/safety.js";
-import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, RESOURCE_CHECKPOINT_VERSION, WALLTIME_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, remainingBudgetMicroUsd, } from "../checkpoint-store.js";
+import { BINDING_CHECKPOINT_VERSION, mintCheckpointToken, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, buildRiskDescriptor, debitLedger, remainingBudgetMicroUsd, } from "../checkpoint-store.js";
 import { boundInputHashOf } from "../canonical-json.js";
+import { GLOBAL_USAGE_KEY, resolveUsageWindows, usageRetryAfterMs } from "../usage-window-store.js";
 const RECONCILE_MAX_RETRIES = 3;
 const DEFAULT_MAX_SUSPENDS = 5;
-const DEFAULT_MAX_SLICES = 100;
+const TASK_LIMIT_KEYS = [
+    "maxTokens",
+    "maxCostUsd",
+    "maxTurns",
+    "maxWalltimeMs",
+    "maxOutputTokens",
+    "approachNotice",
+    "budgetStreamCancel",
+    "degrade",
+    "brainCallGuardrailMs",
+];
+const NUMERIC_TASK_LIMIT_KEYS = ["maxTokens", "maxCostUsd", "maxTurns", "maxWalltimeMs", "maxOutputTokens"];
+const RETIRED_TASK_LIMIT_KEYS = {
+    timeoutSec: "maxWalltimeMs (milliseconds, not seconds)",
+    deadlineNudge: "approachNotice",
+    callCapByDeadline: "(retired — no replacement)",
+    gracefulFinalize: "(retired — the approach notice is the only end-of-budget prompt)",
+};
+function limitConfigError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function resolveTaskLimits(limits) {
+    if (limits === undefined)
+        return undefined;
+    if (typeof limits !== "object" || Array.isArray(limits)) {
+        throw limitConfigError("config.limit_invalid", `TaskSpec.limits must be an object (got ${Array.isArray(limits) ? "an array" : typeof limits})`);
+    }
+    const raw = limits;
+    const legal = TASK_LIMIT_KEYS;
+    for (const key of Object.keys(raw)) {
+        if (legal.includes(key))
+            continue;
+        const replacement = RETIRED_TASK_LIMIT_KEYS[key];
+        throw limitConfigError("config.limit_unknown_key", `TaskSpec.limits.${key} is not a limit this engine reads` +
+            (replacement !== undefined ? ` — it was replaced by \`${replacement}\`` : "") +
+            `. Legal keys: ${TASK_LIMIT_KEYS.join(", ")}. Refused rather than ignored: a limit that is silently dropped reads to the caller as an armed ceiling.`);
+    }
+    for (const key of NUMERIC_TASK_LIMIT_KEYS) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.${key} must be a finite, non-negative number (got ${String(value)}) — an unevaluable ceiling is not a ceiling, and folding it to a default would run the task under a limit nobody chose.`);
+        }
+    }
+    const notice = raw.approachNotice;
+    if (notice !== undefined && notice !== false) {
+        if (typeof notice !== "object" || notice === null || Array.isArray(notice)) {
+            throw limitConfigError("config.limit_invalid", `TaskSpec.limits.approachNotice must be \`false\` or { at?: [first, second] } (got ${String(notice)})`);
+        }
+        const at = notice.at;
+        if (at !== undefined) {
+            const ok = Array.isArray(at) &&
+                at.length === 2 &&
+                at.every((n) => typeof n === "number" && Number.isFinite(n) && n > 0 && n <= 1) &&
+                at[0] <= at[1];
+            if (!ok) {
+                throw limitConfigError("config.limit_invalid", `TaskSpec.limits.approachNotice.at must be two fractions in (0, 1] with first <= second (got ${JSON.stringify(at)})`);
+            }
+        }
+    }
+    return limits;
+}
 const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
 const DEFAULT_RESOURCE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const ENV_LIFETIME_SUSPEND_MARGIN_MS = 60_000;
+export const USAGE_WINDOW_REAP_MARGIN_MS = 60 * 60 * 1000;
+export function resolveEnvLifetimeExpiry(env, observedAt) {
+    const lifetimeMs = env.lifetimeMs;
+    if (lifetimeMs === undefined)
+        return undefined;
+    if (typeof lifetimeMs !== "number" || !Number.isFinite(lifetimeMs) || lifetimeMs <= 0) {
+        throw limitConfigError("config.env_lifetime_invalid", `ExecutionEnv.lifetimeMs must be a finite number of milliseconds > 0 (got ${String(lifetimeMs)}) — an unevaluable lifetime is not a lifetime, and treating it as absent would run the task with no protection against the platform reclaiming its environment.`);
+    }
+    const declaredStart = env.lifetimeStartedAt;
+    if (declaredStart !== undefined && (typeof declaredStart !== "number" || !Number.isFinite(declaredStart))) {
+        throw limitConfigError("config.env_lifetime_invalid", `ExecutionEnv.lifetimeStartedAt must be a finite epoch-ms timestamp (got ${String(declaredStart)}).`);
+    }
+    const anchor = declaredStart ?? observedAt;
+    if (anchor === undefined)
+        return { unanchored: true };
+    return { expiresAt: anchor + lifetimeMs };
+}
 const DEFAULT_UNATTENDED_APPROVAL_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 function sanitizedTtlMs(ttlMs) {
     if (ttlMs === undefined)
@@ -237,6 +318,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         e.code = "config.empty_objective";
         throw e;
     }
+    resolveTaskLimits(spec.limits);
+    const usageWindows = resolveUsageWindows(deps.usageWindows);
     const brainCallGuardrailRef = {};
     const brainCallGuardrailMs = resolveBrainCallGuardrailMs(spec.limits?.brainCallGuardrailMs ?? deps.brainCallGuardrailMs);
     if (spec.agents !== undefined && spec.agents.length > 0) {
@@ -497,6 +580,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         throw e;
     }
     let ownedEnv;
+    let ownedEnvObservedAt;
     let mcp;
     let a2a;
     if (internals?.requestedCwd !== undefined && deps.executionEnvFactory === undefined) {
@@ -514,6 +598,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(internals?.parentCwd ? { parentCwd: internals.parentCwd } : {}),
             })
             : undefined;
+        if (ownedEnv !== undefined)
+            ownedEnvObservedAt = Date.now();
     }
     catch (factoryErr) {
         await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (env-factory-throw leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
@@ -552,6 +638,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     if (spec.signal?.aborted)
         abortController.abort();
     try {
+        const envLifetime = resolveEnvLifetimeExpiry(executionEnv, ownedEnvObservedAt);
+        if (envLifetime !== undefined && "unanchored" in envLifetime) {
+            deps.onError?.(new Error("ExecutionEnv.lifetimeMs is declared but NOT enforceable: this env was not minted by the run's executionEnvFactory and reports no `lifetimeStartedAt`, so the engine cannot tell how old it is. The run will NOT suspend before the platform reclaims the environment — have the adapter report `lifetimeStartedAt`."), { phase: "config", sessionId });
+        }
+        const envLifetimeSuspendAt = envLifetime !== undefined && "expiresAt" in envLifetime ? envLifetime.expiresAt - ENV_LIFETIME_SUSPEND_MARGIN_MS : undefined;
         if (internals?.isolation === "worktree") {
             const failIsolation = (reason) => {
                 const e = new Error(`isolation "worktree" was requested but cannot be honored: ${reason}. The sub-agent was not started (fail-closed — no silent fallback to the shared working tree).`);
@@ -1034,12 +1125,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         };
         const priorSuspendCount = resume?.priorSuspendCount ?? 0;
         const maxSuspends = spec.maxSuspends ?? deps.maxSuspends ?? DEFAULT_MAX_SUSPENDS;
-        const maxSlices = spec.resourceSuspend?.maxSlices ?? DEFAULT_MAX_SLICES;
+        const maxSlices = spec.resourceSuspend?.maxSlices;
         const priorLedger = resume?.priorLedger;
         const resourceTotal = spec.resourceSuspend
             ? {
                 totalBudgetMicroUsd: spec.resourceSuspend.totalBudgetUsd !== undefined ? Math.round(spec.resourceSuspend.totalBudgetUsd * 1e6) : undefined,
-                totalWalltimeSec: spec.resourceSuspend.totalWalltimeSec,
+                totalTokens: spec.resourceSuspend.totalTokens,
             }
             : undefined;
         const budgetSnapshot = {
@@ -1058,6 +1149,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         let worktreeSessionRef;
         let backgroundTaskToolsActive = false;
         let suspendForResource;
+        let suspendForPlatformLimit;
         let suspendForReview;
         const outputRef = {};
         if (resume?.seed.outputRef) {
@@ -1212,29 +1304,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         }
         tools.push(...a2a.tools.map((t) => remoteToolOffload(t)));
         foldProtocolAxes(a2a.toolAxes, "A2A");
-        const callCapOn = spec.limits?.callCapByDeadline !== false;
-        const callCapRef = spec.limits?.timeoutSec &&
-            spec.limits.timeoutSec > 0 &&
-            (callCapOn || spec.limits.gracefulFinalize !== false)
-            ? createCallCapRef()
-            : undefined;
-        if (callCapRef) {
-            callCapRef.staticCapTokens =
-                spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
-                    ? spec.limits.maxOutputTokens
-                    : model.maxTokens;
-        }
-        const cutKills = callCapRef ? createCutKillRegistry() : undefined;
         const callIssuedAtRef = {};
-        const execClamp = callCapRef
-            ? {
-                deadlineMs: () => softExecDeadlineMs(callCapRef),
-                onClamp: () => {
-                    callCapRef.toolClamps = (callCapRef.toolClamps ?? 0) + 1;
-                },
-                ...(cutKills ? { registerKillHandle: cutKills.register } : {}),
-            }
-            : undefined;
         const memoryWriteGateRef = {};
         const additionalRootsCanonical = [];
         let attachmentRootCanonical;
@@ -1317,7 +1387,6 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ...(sessionId !== undefined ? { sessionId } : {}),
                 ...(internals?.onTaskNotification !== undefined ? { taskNotification: internals.onTaskNotification } : {}),
                 ...(internals?.detachHub !== undefined ? { detachHub: internals.detachHub } : {}),
-                ...(execClamp !== undefined ? { execClamp } : {}),
                 pdfModelCapabilities: pdfModelCapabilitiesOf(model),
                 ...(deps.hands?.bashReadonlyAllow !== undefined ? { bashReadonlyAllow: deps.hands.bashReadonlyAllow } : {}),
                 ...(deps.hands?.commitCoAuthor !== undefined ? { commitCoAuthor: deps.hands.commitCoAuthor } : {}),
@@ -1366,7 +1435,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         if (backgroundTaskToolsActive || workflowToolsActive) {
             toolEffects.set("TaskOutput", "read");
             toolEffects.set("TaskStop", "write");
-            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore, ...(callCapRef ? { deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()) } : {}) })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
+            tools.push(firstPartyOffload(createTaskOutputTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore, notificationWired: internals?.onTaskNotification !== undefined, oneShot: spec.oneShot, toolResultStore: offloadStore })), firstPartyOffload(createTaskStopTool({ registry: defaultTaskRegistry, owner: hostTaskId, scope: taskScope, sessionId, workflowStore: deps.workflowRunStore, agentStore: deps.backgroundAgentStore })));
             if (runnerSelf && !(spec.tools ?? []).some((t) => t.name === SEND_MESSAGE_TOOL_NAME)) {
                 const delegationForRevive = (spec.tools ?? []).find((t) => t.agentListing !== undefined);
                 const reviveSpawn = delegationForRevive !== undefined && deps.backgroundAgentStore !== undefined && deps.mailboxStore !== undefined
@@ -2137,46 +2206,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(spec.limits?.maxOutputTokens !== undefined && spec.limits.maxOutputTokens > 0
                 ? { maxOutputTokens: spec.limits.maxOutputTokens }
                 : {}),
-            ...(callCapRef !== undefined && callCapOn
-                ? {
-                    maxOutputTokensPerCall: () => {
-                        if (callCapRef.reasoningObserved === true)
-                            return undefined;
-                        const cap = computeCallCap(callCapRef, Date.now(), (thinking ?? "off") !== "off");
-                        if (cap !== undefined)
-                            callCapRef.shrinks = (callCapRef.shrinks ?? 0) + 1;
-                        return cap;
-                    },
-                }
-                : {}),
-            ...(callCapRef !== undefined
-                ? {
-                    callDeadlineMsPerCall: () => {
-                        callIssuedAtRef.current = Date.now();
-                        return softExecDeadlineMs(callCapRef);
-                    },
-                    stallTimeoutsPerCall: () => softExecDeadlineMs(callCapRef) !== undefined
-                        ? { connectMs: WALLTIME_STALL_CONNECT_MS, firstTokenMs: WALLTIME_STALL_FIRST_TOKEN_MS, idleMs: WALLTIME_STALL_IDLE_MS }
-                        : undefined,
-                }
-                : {}),
-            ...(callCapRef !== undefined
-                ? {
-                    toolDeadline: {
-                        deadlineMs: () => toolCutDeadlineMs(callCapRef, Date.now()),
-                        onCut: (info) => {
-                            callCapRef.toolCuts = (callCapRef.toolCuts ?? 0) + 1;
-                            if (callCapRef.finalizeMode === true && cutKills !== undefined) {
-                                cutKills.killFor(info.toolCallId);
-                            }
-                            callCapRef.pendingCutTools = (callCapRef.pendingCutTools ?? 0) + 1;
-                            void info.settled.then(() => {
-                                callCapRef.pendingCutTools = (callCapRef.pendingCutTools ?? 0) - 1;
-                            });
-                        },
-                    },
-                }
-                : {}),
+            stallTimeoutsPerCall: () => {
+                callIssuedAtRef.current = Date.now();
+                return { connectMs: STALL_CONNECT_MS, firstTokenMs: STALL_FIRST_TOKEN_MS, idleMs: STALL_IDLE_MS };
+            },
             ...(spec.resilience !== undefined ? { resilience: spec.resilience } : {}),
             loopTrace: (step) => {
                 if (step.kind !== "continue")
@@ -2642,11 +2675,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         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 &&
+        const durableSuspendInfraReady = (spec.checkpointStore ?? deps.checkpointStore) !== undefined &&
             !(offloadStore !== undefined && isVolatileOffloadStore(offloadStore)) &&
             (ownedEnv === undefined || isRemoteExecutionEnv(ownedEnv)) &&
             incompleteSuspendAdapter === undefined;
+        const resourceSuspendEligible = spec.resourceSuspend !== undefined && durableSuspendInfraReady;
         if (spec.resourceSuspend !== undefined && !resourceSuspendEligible) {
             const why = (spec.checkpointStore ?? deps.checkpointStore) === undefined
                 ? "no CheckpointStore is wired"
@@ -2660,7 +2693,33 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 sessionId,
             });
         }
-        if (effectivePolicy || hooks?.preToolUse || egressTools.size > 0 || irreversibleTools.size > 0 || resourceSuspendEligible || spec.enablePlanMode === true) {
+        const usageGovernance = (() => {
+            if (usageWindows === undefined || usageWindows.length === 0)
+                return undefined;
+            const store = deps.usageWindowStore;
+            if (store === undefined) {
+                deps.onError?.(new Error("RunnerDeps.usageWindows is set but INACTIVE: no `usageWindowStore` is wired, so cross-task usage cannot be counted and no window can be enforced. Wire InMemoryUsageWindowStore (process-local) or FileUsageWindowStore (restart-surviving)."), { phase: "config", sessionId });
+                return undefined;
+            }
+            const key = spec.principal || GLOBAL_USAGE_KEY;
+            const windows = usageWindows;
+            let charged = 0;
+            return {
+                key,
+                async check(now) {
+                    return usageRetryAfterMs(await store.read(key, windows, now));
+                },
+                async commit(cumulativeTokens, now) {
+                    const delta = cumulativeTokens - charged;
+                    if (delta <= 0)
+                        return;
+                    await store.charge(key, delta, now, windows);
+                    charged = cumulativeTokens;
+                },
+            };
+        })();
+        const platformSuspendArmed = durableSuspendInfraReady && (envLifetimeSuspendAt !== undefined || usageGovernance !== undefined);
+        if (effectivePolicy || hooks?.preToolUse || egressTools.size > 0 || irreversibleTools.size > 0 || resourceSuspendEligible || platformSuspendArmed || spec.enablePlanMode === true) {
             const adjudicate = effectivePolicy
                 ? (req) => raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot }, abortController.signal)), abortController.signal, () => ({
                     action: "deny",
@@ -2883,6 +2942,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 ref.scope = scope;
             };
             const suspendLoopCapHit = (count, cap, detail) => {
+                if (cap === undefined)
+                    return false;
                 if (count + 1 <= cap)
                     return false;
                 suspendLoopRef.hit = true;
@@ -2903,73 +2964,74 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 const { snapshotId: _lineage, ...identity } = env.workspaceHandle();
                 return { ...identity, restoreMode: "park_only" };
             };
-            suspendForResource = resourceSuspendEligible
-                ? async (reason, sliceSpend) => {
-                    const rs = spec.resourceSuspend;
-                    if (!checkpointStore || !rs)
-                        return false;
-                    if (abortController.signal.aborted)
-                        return false;
-                    if (suspendLoopCapHit(priorLedger?.sliceCount ?? 0, maxSlices, " (resource slice limit)"))
-                        return false;
-                    const leafId = await session.getLeafId();
-                    if (!leafId)
-                        return false;
-                    if (abortController.signal.aborted)
-                        return false;
-                    let remoteHandle;
-                    if (suspendableEnv !== undefined) {
-                        if (hasBackgroundShell(suspendableEnv))
-                            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;
-                        }
-                        remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
-                    }
-                    else if (parkOnlyRemoteEnv !== undefined) {
-                        if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
-                            await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
-                        remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
-                    }
-                    const token = mintCheckpointToken();
-                    const gate = { kind: "resource_limit", reason };
-                    const resourceLedgerOut = debitLedger(priorLedger, sliceSpend, resourceTotal);
-                    const mintedAt = Date.now();
-                    const cp = {
-                        token,
-                        version: resourceLedgerOut.totalWalltimeSec !== undefined ? WALLTIME_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
-                        scope: rs.scope,
-                        sessionId,
-                        leafId,
-                        gate,
-                        pendingAction: { kind: "resource_limit", reason },
-                        state: serializeCheckpointState(remoteHandle),
-                        status: "pending",
-                        createdAt: mintedAt,
-                        deadline: mintedAt + (sanitizedTtlMs(rs.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS),
-                        suspendCount: priorSuspendCount,
-                        humanReview: humanReviewRef.count > 0
-                            ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
-                            : undefined,
-                        resourceLedger: resourceLedgerOut,
-                        ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
-                    };
-                    if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+            const mintResourceSuspend = async (reason, sliceSpend, hint) => {
+                const rs = spec.resourceSuspend;
+                if (!checkpointStore)
+                    return false;
+                const scope = rs?.scope ?? checkpointScopeOf(spec);
+                if (abortController.signal.aborted)
+                    return false;
+                if (suspendLoopCapHit(priorLedger?.sliceCount ?? 0, maxSlices, " (resource slice limit)"))
+                    return false;
+                const leafId = await session.getLeafId();
+                if (!leafId)
+                    return false;
+                if (abortController.signal.aborted)
+                    return false;
+                let remoteHandle;
+                if (suspendableEnv !== undefined) {
+                    if (hasBackgroundShell(suspendableEnv))
+                        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;
-                    publishCommittedSuspend(token, gate, rs.scope, remoteHandle);
-                    try {
-                        await sessions.pin?.(sessionId);
                     }
-                    catch (pinErr) {
-                        deps.onError?.(pinErr, { phase: "config", sessionId });
-                    }
-                    harness.requestStopAfterTurn();
-                    return true;
+                    remoteHandle = { ...suspendableEnv.workspaceHandle(), snapshotId: snap.value };
+                }
+                else if (parkOnlyRemoteEnv !== undefined) {
+                    if (hasBackgroundShell(parkOnlyRemoteEnv) && spec.retainBackgroundProcesses !== true)
+                        await sweepBackgroundShells(parkOnlyRemoteEnv, defaultTaskRegistry);
+                    remoteHandle = parkOnlyHandle(parkOnlyRemoteEnv);
+                }
+                const token = mintCheckpointToken();
+                const gate = { kind: "resource_limit", reason, ...(hint !== undefined ? { resumeAfterMs: hint.resumeAfterMs } : {}) };
+                const resourceLedgerOut = debitLedger(priorLedger, sliceSpend, resourceTotal);
+                const mintedAt = Date.now();
+                const cp = {
+                    token,
+                    version: resourceLedgerOut.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : RESOURCE_CHECKPOINT_VERSION,
+                    scope,
+                    sessionId,
+                    leafId,
+                    gate,
+                    pendingAction: { kind: "resource_limit", reason },
+                    state: serializeCheckpointState(remoteHandle),
+                    status: "pending",
+                    createdAt: mintedAt,
+                    deadline: mintedAt + Math.max(sanitizedTtlMs(rs?.ttlMs) ?? DEFAULT_RESOURCE_TTL_MS, hint !== undefined ? hint.resumeAfterMs + USAGE_WINDOW_REAP_MARGIN_MS : 0),
+                    suspendCount: priorSuspendCount,
+                    humanReview: humanReviewRef.count > 0
+                        ? { count: humanReviewRef.count, totalWaitMs: humanReviewRef.totalWaitMs, gates: [...humanReviewRef.gates] }
+                        : undefined,
+                    resourceLedger: resourceLedgerOut,
+                    ...(spec.durableApproval !== undefined ? { durableApproval: { ...spec.durableApproval } } : {}),
+                };
+                if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)))
+                    return false;
+                publishCommittedSuspend(token, gate, scope, remoteHandle);
+                try {
+                    await sessions.pin?.(sessionId);
                 }
-                : undefined;
+                catch (pinErr) {
+                    deps.onError?.(pinErr, { phase: "config", sessionId });
+                }
+                harness.requestStopAfterTurn();
+                return true;
+            };
+            suspendForResource = resourceSuspendEligible ? mintResourceSuspend : undefined;
+            suspendForPlatformLimit = durableSuspendInfraReady ? mintResourceSuspend : undefined;
             suspendForReview = checkpointStore
                 ? async (reason) => {
                     if (!checkpointStore)
@@ -3021,7 +3083,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     const mintedAt = Date.now();
                     const cp = {
                         token,
-                        version: reviewLedger.totalWalltimeSec !== undefined ? WALLTIME_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                        version: reviewLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                         scope,
                         sessionId,
                         leafId,
@@ -3146,7 +3208,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const mintedAt = Date.now();
                         cp = {
                             token,
-                            version: approvalLedger.totalWalltimeSec !== undefined ? WALLTIME_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
+                            version: approvalLedger.totalTokens !== undefined ? TOKEN_CHECKPOINT_VERSION : BINDING_CHECKPOINT_VERSION,
                             scope,
                             sessionId,
                             leafId,
@@ -3537,7 +3599,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, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), 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 } : {}), brainCallGuardrailRef, 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 } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(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, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), 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, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, 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 } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(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.d.ts

@@ -5,8 +5,6 @@ import { type TaskOutcome } from "../task-outcome.js";
 import { type SideQuerySpec, type SideQueryResult } from "../side-query.js";
 import type { SessionStore } from "../session.js";
 import type { AgentDefinition, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
-import { DEFAULT_MAX_TURNS } from "../../config/defaults.js";
-export { DEFAULT_MAX_TURNS };
 export type ResumeTaskConfig = Omit<TaskSpec, "objective" | "sessionId">;
 interface ResumeRun {
     cp: Checkpoint;