@nylorun/runtime 0.26.0-beta → 0.28.0-beta

package/dist/sandbox/pods/lifecycle.js

@@ -1,22 +1,41 @@
+import { hostTuning } from "../../tuning.js";
+import { DEFAULT_SANDBOX_IMAGE } from "../policy.js";
 /**
- * The pullable reference of the image id a container status names (`repo@sha256:…`), or
- * undefined for one without a repository, such as an image loaded onto the node.
+ * The repository an image reference names, as a container runtime writes it: the tag and digest
+ * dropped, Docker Hub's host and `library/` filled in (`python:3.13-slim` is
+ * `docker.io/library/python`).
  */
-export function imageDigestOf(imageID) {
+export function repositoryOf(reference) {
+    let name = reference.replace(/^docker-pullable:\/\//, "");
+    const at = name.indexOf("@");
+    if (at >= 0)
+        name = name.slice(0, at);
+    const colon = name.lastIndexOf(":");
+    if (colon > name.lastIndexOf("/"))
+        name = name.slice(0, colon);
+    const parts = name.split("/");
+    const first = parts[0] ?? "";
+    const hasHost = parts.length > 1 && (first.includes(".") || first.includes(":") || first === "localhost");
+    if (hasHost)
+        return name;
+    return parts.length === 1 ? `docker.io/library/${name}` : `docker.io/${name}`;
+}
+/**
+ * The pullable reference of the image id a container status names (`repo@sha256:…`), when it is
+ * a digest of `requested`'s repository; undefined for an id without a repository, or with one
+ * the node made up for an image loaded onto it, which no registry serves.
+ */
+export function imageDigestOf(imageID, requested) {
     const id = imageID?.replace(/^docker-pullable:\/\//, "");
     if (!id)
         return undefined;
     const at = id.indexOf("@sha256:");
-    return at > 0 && /^[0-9a-f]{64}$/.test(id.slice(at + 8)) ? id : undefined;
+    if (at <= 0 || !/^[0-9a-f]{64}$/.test(id.slice(at + 8)))
+        return undefined;
+    return repositoryOf(id) === repositoryOf(requested) ? id : undefined;
 }
 /** A setup failure's `reason` starts with this (`sandbox/setup.ts`); it is sticky. */
 export const SETUP_FAILED = "setup:";
-/** A pod not ready this long after it was asked to run has failed. */
-export const READY_DEADLINE_MS = 5 * 60_000;
-/** How soon to look again while the pod changes. */
-export const POLL_MS = 2_000;
-/** How soon to look again when the sandboxes service does not answer. */
-export const UNREACHABLE_RETRY_MS = 5_000;
 /** The service's operation id of the row's current spec. */
 export function opIdOf(pod) {
     return `${pod.k8sName}.r${pod.rev}`;
@@ -28,6 +47,9 @@ function gone(status) {
 const event = (type, payload) => ({ type, payload });
 export function decide(facts) {
     const { row, status, now } = facts;
+    // A pod not ready `readyDeadlineMs` after it was asked to run has failed; look again after
+    // `pollMs` while it changes, or `unreachableRetryMs` when the sandboxes service does not answer.
+    const { readyDeadlineMs, pollMs, unreachableRetryMs } = hostTuning().pods;
     const pod = row.pod;
     const patch = {};
     const events = [];
@@ -49,17 +71,17 @@ export function decide(facts) {
     if (pod.retiring !== undefined) {
         const retiring = facts.retiring;
         if (retiring === undefined)
-            again(UNREACHABLE_RETRY_MS);
+            again(unreachableRetryMs);
         else if (gone(retiring))
             patch.retiring = null;
         else {
             if (retiring.exists && !retiring.deleting)
                 deletes.push(pod.retiring);
-            again(POLL_MS);
+            again(pollMs);
         }
     }
     if (status === undefined) {
-        again(UNREACHABLE_RETRY_MS);
+        again(unreachableRetryMs);
         return done();
     }
     if (pod.desired === "deleted") {
@@ -69,7 +91,7 @@ export function decide(facts) {
             deletes.push(pod.k8sName);
         if (pod.observed !== "deleting")
             patch.observed = "deleting";
-        again(POLL_MS);
+        again(pollMs);
         return done();
     }
     // Lost is terminal: only a reset (a new name) leaves it.
@@ -77,7 +99,7 @@ export function decide(facts) {
         if (status.exists && !status.deleting)
             deletes.push(pod.k8sName);
         if (status.exists)
-            again(POLL_MS);
+            again(pollMs);
         return done();
     }
     let desired = pod.desired;
@@ -91,7 +113,7 @@ export function decide(facts) {
             patch.desired = desired;
             patch.rev = rev;
             patch.hostEpoch = pod.hostEpoch + 1;
-            events.push(event("environment.suspended", { reason: "idle" }));
+            events.push(event("agent.suspended", { reason: "idle" }));
         }
         else
             arm.push({ timer: "idle", at: due });
@@ -99,23 +121,23 @@ export function decide(facts) {
     // An incarnation a pod has joined, whose Sandbox or volume is gone: lost.
     if (pod.podUid !== undefined && (!status.exists || status.deleting || status.volume === "missing")) {
         const reason = !status.exists
-            ? "The Environment's pod and volume were deleted outside the Runtime"
+            ? "The Agent's pod and volume were deleted outside the Runtime"
             : status.deleting
-                ? "The Environment's pod is being deleted outside the Runtime"
-                : "The Environment's volume is gone";
+                ? "The Agent's pod is being deleted outside the Runtime"
+                : "The Agent's volume is gone";
         patch.observed = "lost";
         patch.reason = reason;
         patch.hostEpoch = (patch.hostEpoch ?? pod.hostEpoch) + 1;
-        events.push(event("environment.lost", { reason }));
+        events.push(event("agent.lost", { reason }));
         if (status.exists && !status.deleting)
             deletes.push(pod.k8sName);
         if (status.exists)
-            again(POLL_MS);
+            again(pollMs);
         return done();
     }
     if (status.deleting) {
         // The previous incarnation of this name is still going (an Environment deleted and created again).
-        again(POLL_MS);
+        again(pollMs);
         return done();
     }
     const opId = opIdOf({ k8sName: pod.k8sName, rev });
@@ -133,7 +155,7 @@ export function decide(facts) {
         // A pod started by this apply (a create, a resume) is the Environment's first, not a relaunch.
         if (desired === "running" && pod.podUid !== undefined)
             patch.podUid = null;
-        again(POLL_MS);
+        again(pollMs);
         return done({
             apply: { mode: desired === "running" ? "Running" : "Suspended", rotateJoin: !status.exists },
         });
@@ -149,7 +171,7 @@ export function decide(facts) {
                 patch.reason = null;
             }
             // The image it runs, pinned by digest from now on (Q14).
-            const digest = pod.imageDigest === undefined ? imageDigestOf(status.imageID) : undefined;
+            const digest = pod.imageDigest === undefined ? imageDigestOf(status.imageID, facts.image) : undefined;
             if (digest !== undefined)
                 patch.imageDigest = digest;
             return done();
@@ -157,17 +179,17 @@ export function decide(facts) {
         const startedAt = Date.parse(pod.startedAt ?? row.updatedAt);
         if (pod.observed === "failed")
             return done();
-        if (now - startedAt >= READY_DEADLINE_MS) {
+        if (now - startedAt >= readyDeadlineMs) {
             const reason = [status.reason, status.message].filter(Boolean).join(": ") ||
-                `The pod was not ready within ${READY_DEADLINE_MS / 60_000} minutes`;
+                `The pod was not ready within ${Math.round(readyDeadlineMs / 1000)} s`;
             patch.observed = "failed";
             patch.reason = reason;
-            events.push(event("environment.failed", { reason }));
+            events.push(event("agent.failed", { reason }));
             return done();
         }
         if (pod.observed !== "creating")
             patch.observed = "creating";
-        again(POLL_MS);
+        again(pollMs);
         return done();
     }
     // Suspended, applied: suspended once its pod is gone.
@@ -176,6 +198,6 @@ export function decide(facts) {
             patch.observed = "suspended";
         return done();
     }
-    again(POLL_MS);
+    again(pollMs);
     return done();
 }

package/dist/sandbox/pods/network-gate.d.ts

@@ -2,20 +2,19 @@ export interface BlockedAddress {
     readonly host: string;
     readonly port: number;
 }
-/** Consecutive failed connections that prove an address blocked. */
-export declare const CONFIRMATIONS = 3;
 /** The addresses a pod's NetworkPolicy must block: the API server's service address. */
 export declare function blockedAddresses(env: Readonly<Record<string, string | undefined>>): BlockedAddress[];
 /** Whether a TCP connection to `address` opens within `timeoutMs`. */
 export declare function opens(address: BlockedAddress, timeoutMs: number): Promise<boolean>;
 export interface NetworkGateOptions {
     readonly addresses: readonly BlockedAddress[];
-    /** Give up after this long. Default 120 s. */
+    /** Give up after this long. Default `harness.networkPolicyTimeoutMs` (Host tuning, 120 s). */
     readonly timeoutMs?: number;
-    /** One connection attempt. Default 1 s. */
+    /** One connection attempt. Default `harness.networkProbeMs` (1 s). */
     readonly attemptMs?: number;
-    /** Between attempts after a connection opened. Default 250 ms. */
+    /** Between attempts after a connection opened. Default `harness.networkPauseMs` (250 ms). */
     readonly pauseMs?: number;
+    /** Consecutive failed connections that prove an address blocked. Default `harness.networkConfirmations` (3). */
     readonly confirmations?: number;
     readonly log?: (message: string, fields: Record<string, unknown>) => void;
 }

package/dist/sandbox/pods/network-gate.js

@@ -4,12 +4,11 @@
  * (`10.96.0.1:443`) for 0.5 to 5 s after it started (8a). So before the engine joins, or runs
  * anything, it connects to addresses the policy must block (the API server's service address,
  * `KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT`, which the kubelet always sets) until each
- * fails `CONFIRMATIONS` times in a row (refused, unreachable or timed out). A connection that
+ * fails `harness.networkConfirmations` times in a row (Host tuning) (refused, unreachable or timed out). A connection that
  * succeeds starts the count again. Past `timeoutMs` the engine exits, and the pod restarts it.
  */
 import { connect } from "node:net";
-/** Consecutive failed connections that prove an address blocked. */
-export const CONFIRMATIONS = 3;
+import { hostTuning } from "../../tuning.js";
 /** The addresses a pod's NetworkPolicy must block: the API server's service address. */
 export function blockedAddresses(env) {
     const override = env.NYLORUN_SANDBOX_BLOCKED_PROBE;
@@ -45,19 +44,20 @@ export function opens(address, timeoutMs) {
 }
 /** Resolves once every address is blocked; rejects past the timeout. */
 export async function awaitNetworkPolicy(options) {
+    const tuning = hostTuning().harness;
     const started = Date.now();
-    const deadline = started + (options.timeoutMs ?? 120_000);
-    const needed = options.confirmations ?? CONFIRMATIONS;
+    const deadline = started + (options.timeoutMs ?? tuning.networkPolicyTimeoutMs);
+    const needed = options.confirmations ?? tuning.networkConfirmations;
     for (const address of options.addresses) {
         let failures = 0;
         let opened = 0;
         while (failures < needed) {
             if (Date.now() > deadline)
                 throw new Error(`The pod's NetworkPolicy is not in force: ${address.host}:${address.port} still answered ${opened} time(s)`);
-            if (await opens(address, options.attemptMs ?? 1_000)) {
+            if (await opens(address, options.attemptMs ?? tuning.networkProbeMs)) {
                 failures = 0;
                 opened += 1;
-                await new Promise((resolve) => setTimeout(resolve, options.pauseMs ?? 250));
+                await new Promise((resolve) => setTimeout(resolve, options.pauseMs ?? tuning.networkPauseMs));
             }
             else
                 failures += 1;

package/dist/sandbox/pods/reconcile.js

@@ -15,12 +15,15 @@
  * infrastructure errors throw; Restate retries those.
  */
 import { randomBytes } from "node:crypto";
+import { DEFAULT_SANDBOX_IMAGE } from "../policy.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../tenant-config.js";
 import { podSandboxSpecOf } from "../resolve.js";
 import { sha256Hex } from "../join.js";
 import { recoverLostVolume } from "../../artifacts/disk.js";
 import { decide } from "./lifecycle.js";
 import { podLifecycleConfig, podSpecOf } from "./spec.js";
+import { hostTuning } from "../../tuning.js";
+import { idleMsOf, revertStart } from "../../tenant/agent-versions.js";
 export async function reconcileSandbox(ctx, sandboxId, trigger) {
     const pods = ctx.pods;
     if (!pods || ctx.closed)
@@ -49,9 +52,11 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
             return undefined;
         }
     };
-    const lifecycle = podLifecycleConfig(config, row.recipe);
+    // While a start would apply a new version (track T3), it idles at most `tenant.upgradeIdleMs`.
+    const lifecycle = { ...podLifecycleConfig(config, row.recipe), idleMs: idleMsOf(config, row) };
     const decision = decide({
         row,
+        image: row.applied.image ?? DEFAULT_SANDBOX_IMAGE,
         config: lifecycle,
         status: await status(row.pod.k8sName),
         ...(row.pod.retiring ? { retiring: await status(row.pod.retiring) } : {}),
@@ -116,7 +121,7 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
                 message: error instanceof Error ? error.message : String(error),
             });
             // Nothing of the decision is written: the next reconcile decides again.
-            return { retryAfterMs: decision.retryAfterMs ?? 5_000 };
+            return { retryAfterMs: decision.retryAfterMs ?? hostTuning().pods.reconcileRetryMs };
         }
     }
     const written = await ctx.store.tx(async (t) => {
@@ -137,9 +142,15 @@ export async function reconcileSandbox(ctx, sandboxId, trigger) {
         if (Object.keys(finalPatch).length > 0)
             await t.updateEnvironmentPod(sandboxId, finalPatch, new Date().toISOString());
         for (const item of decision.events)
-            await t.environmentEvent(sandboxId, item.type, item.payload);
+            await t.agentEvent(sandboxId, item.type, item.payload);
         if (epochMoved)
             await t.signal({ type: "host.revoked", sandboxId, epoch: finalPatch.hostEpoch });
+        // A pod that failed to start on a new version goes back to the version it ran (track T3).
+        if (finalPatch.observed === "failed" && current.startCheck) {
+            const failed = (await t.environment(sandboxId, { lock: true }));
+            await revertStart(t, failed, finalPatch.reason ?? "The pod failed", new Date().toISOString());
+            return { kind: "changed" };
+        }
         return { kind: "written" };
     });
     if (written.kind === "changed")

package/dist/sandbox/pods/spec.js

@@ -5,7 +5,8 @@
  */
 import { parseSandboxDuration, parseSandboxSize } from "@nylorun/core/define";
 import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
-import { memoryMiBOf } from "../policy.js";
+import { idleMsOf, memoryMiBOf } from "../policy.js";
+import { podTuningEnv } from "../../tuning.js";
 import { opIdOf } from "./lifecycle.js";
 /** The pod's grace period to stop when the Tenant sets none (D34). */
 export const DEFAULT_STOP_GRACE_SECONDS = 10;
@@ -19,13 +20,13 @@ export const POD_HARNESS_ROOT = "/harness";
  */
 export function podLifecycleConfig(config, recipe) {
     const stopGrace = config.lifecycle?.stopGrace;
-    const tenantIdle = parseSandboxDuration(config.limits?.idle ?? "15m") ?? 15 * 60_000;
+    const tenantIdle = idleMsOf({ ...(config.limits?.idle === undefined ? {} : { idle: config.limits.idle }) });
     const own = recipe?.lifecycle.idle === undefined ? undefined : parseSandboxDuration(recipe.lifecycle.idle);
+    const graceMs = stopGrace === undefined ? undefined : parseSandboxDuration(stopGrace);
     return {
         idleMs: own === undefined ? tenantIdle : Math.min(own, tenantIdle),
-        stopGraceSeconds: stopGrace === undefined
-            ? DEFAULT_STOP_GRACE_SECONDS
-            : Math.max(1, Math.min(30, Math.round((parseSandboxDuration(stopGrace) ?? 10_000) / 1000))),
+        // Kubernetes counts the grace in whole seconds, at least one.
+        stopGraceSeconds: graceMs === undefined ? DEFAULT_STOP_GRACE_SECONDS : Math.max(1, Math.round(graceMs / 1000)),
     };
 }
 /** The volume's size in GiB. */
@@ -53,6 +54,8 @@ export function podSpecOf(input) {
         env: {
             NYLORUN_SANDBOX_ID: input.environmentId,
             NYLORUN_HARNESS_ROOT: POD_HARNESS_ROOT,
+            // The `harness` and `engine` tuning the operator set: the pod's engine runs with them.
+            ...podTuningEnv(),
         },
         ...(input.joinToken ? { joinToken: input.joinToken } : {}),
     };

package/dist/sandbox/policy.d.ts

@@ -4,10 +4,16 @@ import type { ResolvedNetwork } from "./types.js";
 export declare const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
 export declare const DEFAULT_SANDBOX_CPUS = 2;
 export declare const DEFAULT_SANDBOX_MEMORY_MIB = 1024;
-export declare const DEFAULT_SANDBOX_IDLE_MS: number;
+/** The default of the Tenant's Environment setting `limits.idle` (`environments.config`, D36). */
+export declare const DEFAULT_SANDBOX_IDLE = "15m";
 /** Package registries and code hosts. Concrete names so every backend can express them. */
 export declare const DEV_PRESET_HOSTS: readonly string[];
 export declare function resolveNetwork(manifest: SandboxManifest | undefined): ResolvedNetwork;
+/**
+ * How long the sandbox may sit idle: its spec's `idle`, which `sandboxSpecOf` sets from the
+ * Environment's `lifecycle.idle` within the Tenant's `limits.idle`; else that setting's default
+ * (`DEFAULT_SANDBOX_IDLE`, D36).
+ */
 export declare function idleMsOf(manifest: SandboxManifest | undefined): number;
 export declare function memoryMiBOf(manifest: SandboxManifest | undefined): number;
 export declare function describeNetwork(network: ResolvedNetwork): string;

package/dist/sandbox/policy.js

@@ -1,9 +1,11 @@
 import { parseSandboxDuration, parseSandboxSize, } from "@nylorun/core/define";
+import { hostTuning } from "../tuning.js";
 /** Docker Official Image: Debian with bash, coreutils and Python 3; small first pull. */
 export const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
 export const DEFAULT_SANDBOX_CPUS = 2;
 export const DEFAULT_SANDBOX_MEMORY_MIB = 1024;
-export const DEFAULT_SANDBOX_IDLE_MS = 15 * 60_000;
+/** The default of the Tenant's Environment setting `limits.idle` (`environments.config`, D36). */
+export const DEFAULT_SANDBOX_IDLE = "15m";
 /** Package registries and code hosts. Concrete names so every backend can express them. */
 export const DEV_PRESET_HOSTS = Object.freeze([
     // npm and yarn
@@ -50,14 +52,19 @@ export function resolveNetwork(manifest) {
         suffixes: Object.freeze([...suffixes].sort()),
     });
 }
+/**
+ * How long the sandbox may sit idle: its spec's `idle`, which `sandboxSpecOf` sets from the
+ * Environment's `lifecycle.idle` within the Tenant's `limits.idle`; else that setting's default
+ * (`DEFAULT_SANDBOX_IDLE`, D36).
+ */
 export function idleMsOf(manifest) {
-    return (manifest?.idle && parseSandboxDuration(manifest.idle)) || DEFAULT_SANDBOX_IDLE_MS;
+    return parseSandboxDuration(manifest?.idle ?? DEFAULT_SANDBOX_IDLE) ?? parseSandboxDuration(DEFAULT_SANDBOX_IDLE);
 }
 export function memoryMiBOf(manifest) {
     const bytes = manifest?.resources?.memory
         ? parseSandboxSize(manifest.resources.memory)
         : undefined;
-    return bytes ? Math.max(128, Math.ceil(bytes / 1024 ** 2)) : DEFAULT_SANDBOX_MEMORY_MIB;
+    return bytes ? Math.max(hostTuning().pods.memoryFloorMiB, Math.ceil(bytes / 1024 ** 2)) : DEFAULT_SANDBOX_MEMORY_MIB;
 }
 export function describeNetwork(network) {
     const extra = network.preset === "dev"

package/dist/sandbox/resolve.d.ts

@@ -1,10 +1,10 @@
 /**
- * Resolves an Environment's recipe (`PUT /v1/environments/{id}`) against its Tenant's limits,
- * and the sandbox spec a recipe gives a session's pinned manifest (its `runtime` block) and the pod. Pure: the
+ * Resolves an Agent's recipe (`PUT /v1/agents/{id}`) against its Tenant's limits,
+ * and the sandbox spec a recipe gives a session (`Session.sandbox`) and the pod. Pure: the
  * caller supplies the configuration. Every problem is reported, not only the first, so one
  * response lists all of them.
  */
-import type { EnvironmentFile, EnvironmentKind, EnvironmentLifecycle, EnvironmentRecipe, EnvironmentSecretSlots, EnvironmentSetupCommand } from "@nylorun/core/contracts";
+import type { EnvironmentFile, EnvironmentKind, EnvironmentLifecycle, EnvironmentLimits, EnvironmentRecipe, EnvironmentSecretSlots, EnvironmentSetupCommand } from "@nylorun/core/contracts";
 import { type SandboxManifest } from "@nylorun/core/define";
 import type { PodSandboxSpec } from "./pods/spec.js";
 import { type EffectiveSandboxConfig } from "./tenant-config.js";
@@ -25,6 +25,11 @@ export interface RecipeRequest {
     readonly files?: readonly EnvironmentFile[];
     /** The secret slots (D64): passed through for every kind. */
     readonly secrets?: EnvironmentSecretSlots;
+    /**
+     * Artifact and skill limits: passed through for every kind, as set. The caller checks them
+     * against the Tenant's (`tenant/limits.ts`), which this module does not read.
+     */
+    readonly limits?: EnvironmentLimits;
 }
 export type RecipeResolution = {
     readonly kind: "recipe";
@@ -33,11 +38,11 @@ export type RecipeResolution = {
     readonly kind: "error";
     readonly errors: readonly string[];
 };
-/** The recipe `request` asks for an Environment of `kind`, or every reason it cannot have it. */
+/** The recipe `request` asks for an Agent of `kind`, or every reason it cannot have it. */
 export declare function resolveRecipe(kind: EnvironmentKind, request: RecipeRequest, config: EffectiveSandboxConfig): RecipeResolution;
 /**
- * The sandbox spec of a recipe: what a session's `runtime` block pins and the virtual
- * workspace runs. Idle is the Environment's `lifecycle.idle`, else the Tenant's.
+ * The sandbox spec of a recipe: what a session pins when it opens and the virtual
+ * workspace runs. Idle is the Agent's `lifecycle.idle`, else the Tenant's.
  */
 export declare function sandboxSpecOf(recipe: EnvironmentRecipe, tenantIdle: string): SandboxManifest;
 /** The pod's spec of a recipe: its sandbox spec and its volume's size. */

package/dist/sandbox/resolve.js

@@ -1,7 +1,7 @@
 import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { parseSandboxDuration } from "@nylorun/core/define";
 import { memoryMiB } from "./tenant-config.js";
-/** The recipe `request` asks for an Environment of `kind`, or every reason it cannot have it. */
+/** The recipe `request` asks for an Agent of `kind`, or every reason it cannot have it. */
 export function resolveRecipe(kind, request, config) {
     const { limits } = config;
     const errors = [];
@@ -9,7 +9,7 @@ export function resolveRecipe(kind, request, config) {
     // Any harness id (R4.1): placement decides where it may run, when a session opens.
     const harness = request.harness ?? DEFAULT_HARNESS;
     if (pod && harness !== DEFAULT_HARNESS && request.image === undefined)
-        errors.push(`harness ${harness} needs image: a pod Environment runs its image as the harness.`);
+        errors.push(`harness ${harness} needs image: a pod Agent runs its image as the harness.`);
     const lifecycle = request.lifecycle ?? {};
     const idle = lifecycle.idle === undefined ? undefined : parseSandboxDuration(lifecycle.idle);
     if (idle !== undefined && idle > (parseSandboxDuration(limits.idle) ?? Infinity))
@@ -17,15 +17,18 @@ export function resolveRecipe(kind, request, config) {
     if (kind === "none") {
         for (const field of ["image", "resources", "storage", "network", "setup", "files"])
             if (request[field] !== undefined)
-                errors.push(`${field} is for an Environment with a sandbox: kind none has none.`);
+                errors.push(`${field} is for an Agent with a sandbox: kind none has none.`);
         if (errors.length > 0)
             return { kind: "error", errors };
-        return { kind: "recipe", recipe: { harness, lifecycle: { ...lifecycle }, ...slotsOf(request) } };
+        return {
+            kind: "recipe",
+            recipe: { harness, lifecycle: { ...lifecycle }, ...limitsOf(request), ...slotsOf(request) },
+        };
     }
     if (request.image !== undefined && !pod)
-        errors.push("image is for kind pod: a virtual Environment runs no images.");
+        errors.push("image is for kind pod: a virtual Agent runs no images.");
     if (request.storage !== undefined && !pod)
-        errors.push("storage is for kind pod: a virtual Environment has no volume.");
+        errors.push("storage is for kind pod: a virtual Agent has no volume.");
     for (const field of ["setup", "files"])
         if (request[field] !== undefined && request[field].length > 0 && !pod)
             errors.push(`${field} is for kind pod: it runs when a pod's disk is made or reset.`);
@@ -34,7 +37,7 @@ export function resolveRecipe(kind, request, config) {
         if (!withinCeiling(host, limits.network))
             errors.push(`network.allowedHosts includes ${host}, which this Tenant does not allow.`);
         else if (host.startsWith("*.") && !pod)
-            errors.push(`network.allowedHosts includes ${host}; a virtual Environment allows exact host names only, such as ${host.slice(2)}.`);
+            errors.push(`network.allowedHosts includes ${host}; a virtual Agent allows exact host names only, such as ${host.slice(2)}.`);
     }
     const cpus = request.resources?.cpus ?? limits.defaultResources.cpus;
     const memory = request.resources?.memory === undefined
@@ -57,10 +60,17 @@ export function resolveRecipe(kind, request, config) {
             lifecycle: { ...lifecycle },
             ...(pod && request.setup?.length ? { setup: request.setup.map((command) => ({ ...command })) } : {}),
             ...(pod && request.files?.length ? { files: request.files.map((file) => ({ ...file })) } : {}),
+            ...limitsOf(request),
             ...slotsOf(request),
         },
     };
 }
+/** The request's limits, when it sets any. */
+function limitsOf(request) {
+    return request.limits !== undefined && Object.keys(request.limits).length > 0
+        ? { limits: structuredClone(request.limits) }
+        : {};
+}
 /** The request's secret slots, when it declares any. */
 function slotsOf(request) {
     return request.secrets !== undefined && Object.keys(request.secrets).length > 0
@@ -68,8 +78,8 @@ function slotsOf(request) {
         : {};
 }
 /**
- * The sandbox spec of a recipe: what a session's `runtime` block pins and the virtual
- * workspace runs. Idle is the Environment's `lifecycle.idle`, else the Tenant's.
+ * The sandbox spec of a recipe: what a session pins when it opens and the virtual
+ * workspace runs. Idle is the Agent's `lifecycle.idle`, else the Tenant's.
  */
 export function sandboxSpecOf(recipe, tenantIdle) {
     const allow = recipe.network?.allowedHosts ?? [];

package/dist/sandbox/setup.d.ts

@@ -6,6 +6,8 @@ export { SETUP_FAILED };
 export interface SetupPlan {
     /** The applied recipe's version: written into the volume's marker. */
     readonly recipeVersion: number;
+    /** The sha256 of the commands and files: a marker with another runs the setup again (T3). */
+    readonly setupHash: string;
     readonly commands: readonly {
         readonly command: string;
         readonly cwd: string;
@@ -33,8 +35,10 @@ export interface SetupReport {
 export declare function parseSetupReport(value: unknown): SetupReport | undefined;
 /**
  * Records a failed setup on Environment `id` held at host epoch `epoch` (the reporting engine's):
- * the pod is `failed` with a reason that starts `setup:`, and `environment.failed` says which
- * command failed and how. A report from an older host, or a success, changes nothing.
+ * the pod is `failed` with a reason that starts `setup:`, and `agent.failed` says which
+ * command failed and how, with the end of its output (the Tenant's `setupOutputChars`; the reason
+ * quotes `setupReasonChars` of it and `setupCommandExcerptChars` of the command). A report
+ * from an older host, or a success, changes nothing.
  */
 export declare function recordSetup(ctx: TenantContext, id: string, epoch: number, report: SetupReport): Promise<void>;
 /**