@nylorun/runtime 0.25.0-beta → 0.27.0-beta

package/dist/sandbox/manager.js

@@ -1,12 +1,35 @@
-import { SANDBOX_WORKSPACE, } from "@nylorun/core/define";
+/**
+ * Sandbox Manager: owns sandbox lifecycle for the Runtime. One workspace per sandbox resource
+ * (`sandbox: { id }`, keyed by the sandbox id), or per owning session for a sandbox chosen
+ * inline or by the Tenant default (keyed by the session id); created on the first sandbox tool
+ * call, stopped after its idle timeout, reattached on the next call. Each session's calls on a
+ * workspace run in the order it sends them, and different sessions' calls run at the same time
+ * (D66): the sessions of one Environment run their turns at once. Opening, stopping and removing
+ * a workspace run alone: a stop or removal waits for the calls running, and calls that come after
+ * it wait for it.
+ *
+ * The manager keeps no timers and reaches no store: it keeps its compute records through a
+ * `SandboxRecords` port (the Tenant's `sandboxes` table in core's process, a file in a harness's)
+ * and writes its events through `emit`. Its owner drives it: `stopIdle` stops sandboxes idle
+ * past their timeout and marks records of compute this process no longer holds as stopped
+ * (after a restart); `reconcile` removes workspaces whose owner is gone. `sweep` does both, the
+ * reconcile once per process, as the Tenant sweep does in core's process.
+ *
+ * A folder the harness asks for (`mountFolder`: our engine's skill folders, `/skills/<name>@<hash>/`,
+ * D66, protocol 15) is written read-only, once per open handle: the harness decides which folders
+ * and when, and gives their bytes; the manager only writes them (`skills.ts`).
+ */
+import { posix } from "node:path";
+import { SANDBOX_WORKSPACE } from "@nylorun/core/define";
 import { sandboxWorkspaceKey, sessionWorkspaceKey, workspacePrefix, } from "./records.js";
 import { DEFAULT_SANDBOX_CPUS, DEFAULT_SANDBOX_IMAGE, describeNetwork, idleMsOf, memoryMiBOf, resolveNetwork, } from "./policy.js";
 import { parseSandboxPreference, reportSelection, selectSandboxBackend, } from "./select.js";
-import { mountSkill, sandboxSkillsOf } from "./skills.js";
+import { mountFolderFiles } from "./skills.js";
+import { DEFAULT_SANDBOX_TOOL_LIMITS } from "@nylorun/harness";
 import { runDiskOp } from "./disk-fs.js";
-import { resolveSandboxPath, runSandboxTool, } from "./tools.js";
+import { helperCommandTimeoutMs, quote, resolveSandboxPath, runSandboxTool, } from "./tools.js";
 import { SandboxFileTooLargeError, } from "./types.js";
-export { sandboxToolSpec } from "./runtime-tools.js";
+import { hostTuning } from "../tuning.js";
 const READ_TOOLS = new Set(["read", "grep", "glob"]);
 export class SandboxManager {
     options;
@@ -99,12 +122,16 @@ export class SandboxManager {
     async report() {
         return { ...reportSelection(await this.ready), defaultImage: DEFAULT_SANDBOX_IMAGE };
     }
-    async run(session, sandbox, toolName, input, signal) {
+    /**
+     * Runs sandbox operation `toolName` in the session's sandbox, held to `limits`: the harness's
+     * sandbox tool limits (`DEFAULT_SANDBOX_TOOL_LIMITS` when it names none).
+     */
+    async run(session, sandbox, toolName, input, signal, limits = DEFAULT_SANDBOX_TOOL_LIMITS) {
         const prepared = await this.prepare(session, sandbox);
         if ("kind" in prepared)
             return prepared;
         const { live: entry, spec } = prepared;
-        return this.inLane(entry, session.id, () => this.execute(entry, session, spec, toolName, input, signal));
+        return this.inLane(entry, session.id, () => this.execute(entry, session, spec, toolName, input, signal, limits));
     }
     /**
      * Runs `call` in session `sessionId`'s queue on `live`: after its earlier calls, and after any
@@ -159,8 +186,8 @@ export class SandboxManager {
         return handle;
     }
     /**
-     * The bytes of one file in the session's sandbox, for `save_artifact` (F8.1), in the same queue
-     * as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
+     * The bytes of one file in the session's sandbox, for our engine's `save_artifact` and its
+     * outputs folder (`files.read`), in the same queue as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
      * cannot open or the file is larger than `maxBytes`. Relative paths resolve in the workspace.
      */
     async readBytes(session, sandbox, path, maxBytes, signal) {
@@ -190,8 +217,37 @@ export class SandboxManager {
         });
     }
     /**
-     * The files under directory `dir` of the session's sandbox, for the turn-end export (F8.2), in
-     * the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
+     * Writes `body` to one file of the session's sandbox, as it comes, for our engine's
+     * `read_artifact` with `path` (protocol 15), in the same queue as its tool calls: its folders
+     * are made first, and a file there is replaced. Relative paths resolve in the workspace.
+     */
+    async writeBytes(session, sandbox, path, body, signal) {
+        return this.withHandle(session, sandbox, signal, async (handle) => {
+            const resolved = resolveSandboxPath(path, handle.workspace ?? SANDBOX_WORKSPACE);
+            const parent = posix.dirname(resolved);
+            const made = await handle.exec({ command: `mkdir -p ${quote(parent)}`, cwd: "/", timeoutMs: helperCommandTimeoutMs() }, signal);
+            if (made.exitCode !== 0)
+                return {
+                    kind: "failed",
+                    code: "sandbox.write_failed",
+                    message: made.stderr.trim() || `Could not create ${parent}`,
+                };
+            let size = 0;
+            const counted = body instanceof Uint8Array
+                ? ((size = body.byteLength), body)
+                : (async function* () {
+                    for await (const chunk of body) {
+                        size += chunk.byteLength;
+                        yield chunk;
+                    }
+                })();
+            await handle.writeFile(resolved, counted);
+            return { kind: "written", path: resolved, size };
+        });
+    }
+    /**
+     * The files under directory `dir` of the session's sandbox, for our engine's outputs folder
+     * (`files.list`, protocol 15), in the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
      * started to look) or `dir` is not a directory. Relative paths resolve in the workspace.
      */
     async listFiles(session, sandbox, dir, maxEntries, signal) {
@@ -252,9 +308,6 @@ export class SandboxManager {
                     message: `The sandbox could not start: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
-            const unmounted = await this.mountSkills(live, handle, session, signal);
-            if (unmounted)
-                return unmounted;
             return await use(handle, live);
         });
     }
@@ -294,48 +347,52 @@ export class SandboxManager {
                 lastUsedAt: Date.now(),
                 lanes: new Map(),
                 gate: Promise.resolve(),
-                skills: new Map(),
+                mounts: new Map(),
             };
             this.live.set(key, live);
         }
         return { live, spec };
     }
-    async execute(live, session, spec, toolName, input, signal) {
+    async execute(live, session, spec, toolName, input, signal, limits) {
         if (signal.aborted)
             throw new Error("Turn cancelled");
         if (this.closing)
             throw new Error("Runtime is shutting down");
-        return this.executeOpen(live, session, spec, toolName, input, signal);
+        return this.executeOpen(live, session, spec, toolName, input, signal, limits);
     }
-    async executeOpen(live, session, spec, toolName, input, signal) {
-        let handle;
+    /**
+     * The workspace's handle, opened when there is none. A start that fails is recorded as stopped
+     * and answered as a failed outcome: nothing ran yet, so it is definite, not uncertain.
+     */
+    async started(live, session, spec) {
         try {
-            handle = await this.handleOf(live, session, spec);
+            return await this.handleOf(live, session, spec);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             const record = await this.record(spec.key, live, session.id, spec.image, "stopped");
             await this.options.emit(session.id, session.activeTurnId, "environment.state", { state: "stopped", backend: live.backend.name, error: message }, { record, ...claimOf(session) });
-            // Nothing ran yet, so a failed start is a definite outcome, not an uncertain one.
             return {
                 kind: "failed",
                 code: "sandbox.start_failed",
                 message: `The sandbox could not start on ${live.backend.name} (image ${spec.image ?? "the backend's default"}): ${message}`,
             };
         }
-        const unmounted = await this.mountSkills(live, handle, session, signal);
-        if (unmounted)
-            return unmounted;
+    }
+    async executeOpen(live, session, spec, toolName, input, signal, limits) {
+        const handle = await this.started(live, session, spec);
+        if ("kind" in handle)
+            return handle;
         const started = Date.now();
         let report = {};
         try {
             const outcome = await runSandboxTool(handle, toolName, (input ?? {}), signal, (value) => {
                 report = value;
-            }, session.environment);
+            }, limits, session.environment);
             await this.options.emit(session.id, session.activeTurnId, "environment.exec", {
                 tool: toolName,
                 ...report,
-                ...(report.command ? { command: report.command.slice(0, 500) } : {}),
+                ...(report.command ? { command: report.command.slice(0, hostTuning().harness.execCommandChars) } : {}),
                 outcome: outcome.kind,
                 ...(outcome.kind === "failed" ? { code: outcome.code } : {}),
                 durationMs: Date.now() - started,
@@ -356,23 +413,34 @@ export class SandboxManager {
         }
     }
     /**
-     * Mounts the skill folders the session needs that the workspace does not hold (D66): on a
-     * handle just opened all of them, later only versions another session has not mounted. Calls
-     * that need one folder at once share its mount. A failed outcome when one cannot be mounted;
-     * the folder is not marked mounted then, so the next call tries again.
+     * Writes `files` (path in `folder` to `sha256:<hex>`) to `folder` of the session's sandbox,
+     * read-only, each one's bytes from `read`, in the session's queue (protocol 15: the harness
+     * decides which folders, and when). A folder the open handle already holds is `present` without
+     * an exec; calls that need one folder at once share its mount. A failed outcome when the sandbox
+     * cannot start or the folder cannot be written; it is not marked mounted then, so the next call
+     * tries again. A reopened handle holds none.
      */
-    async mountSkills(live, handle, session, signal) {
-        const read = this.options.definitionFile;
-        if (!read)
-            return undefined;
-        for (const [folder, files] of sandboxSkillsOf(session.manifest)) {
-            let mounting = live.skills.get(folder);
+    async mountFolder(session, sandbox, folder, files, read, signal) {
+        const prepared = await this.prepare(session, sandbox);
+        if ("kind" in prepared)
+            return prepared;
+        const { live, spec } = prepared;
+        return this.inLane(live, session.id, async () => {
+            if (signal.aborted)
+                throw new Error("Turn cancelled");
+            if (this.closing)
+                throw new Error("Runtime is shutting down");
+            const handle = await this.started(live, session, spec);
+            if ("kind" in handle)
+                return handle;
+            let mounting = live.mounts.get(folder);
+            const present = mounting !== undefined;
             if (!mounting) {
-                const mount = mountSkill(handle, folder, files, (sha256) => read(sha256, session), signal);
-                live.skills.set(folder, mount);
+                const mount = mountFolderFiles(handle, folder, files, async (sha256) => read(sha256), signal);
+                live.mounts.set(folder, mount);
                 void mount.catch(() => {
-                    if (live.skills.get(folder) === mount)
-                        live.skills.delete(folder);
+                    if (live.mounts.get(folder) === mount)
+                        live.mounts.delete(folder);
                 });
                 mounting = mount;
             }
@@ -385,11 +453,11 @@ export class SandboxManager {
                 return {
                     kind: "failed",
                     code: "sandbox.skills_unavailable",
-                    message: `The files of skill folder ${folder} could not be put in the sandbox: ${error instanceof Error ? error.message : String(error)}`,
+                    message: `The files of folder ${folder} could not be put in the sandbox: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
-        }
-        return undefined;
+            return { kind: present ? "present" : "mounted" };
+        });
     }
     async open(live, session, spec) {
         const existing = await this.options.records.get(spec.key);
@@ -402,8 +470,8 @@ export class SandboxManager {
         const creating = await this.record(spec.key, live, session.id, spec.image, "creating", existing);
         await this.options.emit(session.id, session.activeTurnId, "environment.state", { state: "creating", ...payload, ...(existing ? { reattach: true } : {}) }, { record: creating, ...claimOf(session) });
         const handle = await live.backend.open(spec);
-        // A handle opened afresh holds no skills this manager knows of.
-        live.skills.clear();
+        // A handle opened afresh holds no folder this manager knows of.
+        live.mounts.clear();
         const running = await this.record(spec.key, live, session.id, spec.image, "running", existing);
         await this.options.emit(session.id, session.activeTurnId, "environment.state", {
             state: "running",

package/dist/sandbox/placement.d.ts

@@ -22,7 +22,7 @@ export declare function placementOf(config: TenantSandboxConfig, harnessId?: str
 export declare const ENABLE_PODS = "run `nylorun local sandbox enable --context <name>` to give this Tenant a cluster";
 /** Refuses a session whose harness, on the host its Environment needs, the Tenant does not allow. */
 export declare function checkPlacement(config: TenantSandboxConfig, kind: EnvironmentKind | undefined, harness?: string): void;
-/** Whether the sandboxes service is up, cached for a few seconds. */
+/** Whether the sandboxes service is up, the answer reused for `pods.readyCacheMs` (Host tuning). */
 export declare function podsReady(pods: TenantPods): Promise<boolean>;
 /** Refuses a pod Environment without sandbox pods, or with the sandboxes service down. */
 export declare function requirePods(pods: TenantPods | undefined, what: string): Promise<TenantPods>;

package/dist/sandbox/placement.js

@@ -11,7 +11,8 @@
  * sandbox enable`), or with the sandboxes service not ready, it is `409 environment_unavailable`.
  */
 import { DEFAULT_HARNESS, } from "@nylorun/core/contracts";
-import { fail } from "../tenant/http.js";
+import { fail, failRetryLater } from "../tenant/http.js";
+import { hostTuning } from "../tuning.js";
 /** Our harness's id (blueprint D38): what a session runs unless its Environment names another. */
 export const HARNESS_ID = DEFAULT_HARNESS;
 export const DEFAULT_PLACEMENT = ["harness-container", "sandbox"];
@@ -35,12 +36,11 @@ export function checkPlacement(config, kind, harness = HARNESS_ID) {
             ? `This Tenant does not let the ${harness} harness run in a sandbox pod (${where}).`
             : `This Tenant runs the ${harness} harness only in sandbox pods (${where}): open the session on a pod Environment.`, { code: "placement_refused", details: { harness, host, allowed: [...allowed] } });
 }
-const READY_CACHE_MS = 5_000;
 const ready = new WeakMap();
-/** Whether the sandboxes service is up, cached for a few seconds. */
+/** Whether the sandboxes service is up, the answer reused for `pods.readyCacheMs` (Host tuning). */
 export async function podsReady(pods) {
     const cached = ready.get(pods);
-    if (cached && Date.now() - cached.at < READY_CACHE_MS)
+    if (cached && Date.now() - cached.at < hostTuning().pods.readyCacheMs)
         return cached.ready;
     const answer = await pods.client.ready();
     ready.set(pods, { at: Date.now(), ready: answer });
@@ -53,9 +53,6 @@ export async function requirePods(pods, what) {
             code: "environment_unavailable",
         });
     if (!(await podsReady(pods)))
-        fail(409, `${what} needs sandbox pods, and the sandboxes service is not ready. Check \`nylorun local sandbox status\`.`, {
-            code: "environment_unavailable",
-            details: { retryAfterSeconds: 5 },
-        }, { "retry-after": "5" });
+        failRetryLater(`${what} needs sandbox pods, and the sandboxes service is not ready. Check \`nylorun local sandbox status\`.`, "environment_unavailable");
     return pods;
 }

package/dist/sandbox/pods/client.d.ts

@@ -1,12 +1,3 @@
-/**
- * The sandboxes service's client (F7.2, D32): the Go service (`sandboxes/`) that alone holds
- * the cluster credentials and drives agent-sandbox Sandboxes in the Tenant's namespace. Core
- * reaches it at `NYLORUN_SANDBOXES_URL` with `NYLORUN_SANDBOXES_TOKEN`; nothing else does.
- *
- * Pull, not push: the service never calls core. Core reads a Sandbox's status when it
- * reconciles (`GET /v1/pods/{name}`, optionally blocking with `?wait=`), and every change it
- * asks for carries an operation id, so a retried `PUT` is a no-op.
- */
 /** `PUT /v1/pods/{name}`: the Sandbox the service applies (`driver.Spec` in Go). */
 export interface PodSpec {
     readonly opId: string;
@@ -92,6 +83,6 @@ export declare function httpSandboxesClient(options: {
     readonly url: string;
     readonly token: string;
     readonly fetch?: typeof fetch;
-    /** Per request, unless the request waits longer. Default 20 s. */
+    /** Per request, unless the request waits longer. Default `pods.requestTimeoutMs` (Host tuning, 20 s). */
     readonly timeoutMs?: number;
 }): SandboxesClient;

package/dist/sandbox/pods/client.js

@@ -7,6 +7,7 @@
  * reconciles (`GET /v1/pods/{name}`, optionally blocking with `?wait=`), and every change it
  * asks for carries an operation id, so a retried `PUT` is a no-op.
  */
+import { hostTuning, SANDBOXES_MAX_WAIT_MS } from "../../tuning.js";
 /** The service refused a request, or did not answer. */
 export class SandboxesError extends Error {
     status;
@@ -23,7 +24,7 @@ export function httpSandboxesClient(options) {
     const base = options.url.replace(/\/+$/, "");
     const call = options.fetch ?? fetch;
     const request = async (method, path, init = {}) => {
-        const timeout = AbortSignal.timeout(init.timeoutMs ?? options.timeoutMs ?? 20_000);
+        const timeout = AbortSignal.timeout(init.timeoutMs ?? options.timeoutMs ?? hostTuning().pods.requestTimeoutMs);
         const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
         let response;
         try {
@@ -58,7 +59,7 @@ export function httpSandboxesClient(options) {
     return {
         async ready(signal) {
             try {
-                await request("GET", "/ready", { auth: false, timeoutMs: 3_000, ...(signal ? { signal } : {}) });
+                await request("GET", "/ready", { auth: false, timeoutMs: hostTuning().pods.readyProbeTimeoutMs, ...(signal ? { signal } : {}) });
                 return true;
             }
             catch {
@@ -68,10 +69,13 @@ export function httpSandboxesClient(options) {
         info: (signal) => request("GET", "/v1/info", signal ? { signal } : {}),
         put: (name, spec, signal) => request("PUT", pod(name), { body: spec, ...(signal ? { signal } : {}) }),
         status(name, { wait, timeoutMs, signal } = {}) {
-            const query = wait ? `?wait=${wait}&timeoutMs=${Math.min(timeoutMs ?? 30_000, 30_000)}` : "";
+            const tuning = hostTuning().pods;
+            // The service waits at most `SANDBOXES_MAX_WAIT_MS`; the answer has `waitSlackMs` to arrive.
+            const waitMs = Math.min(timeoutMs ?? tuning.waitMs, SANDBOXES_MAX_WAIT_MS);
+            const query = wait ? `?wait=${wait}&timeoutMs=${waitMs}` : "";
             return request("GET", `${pod(name)}${query}`, {
                 ...(signal ? { signal } : {}),
-                ...(wait ? { timeoutMs: Math.min(timeoutMs ?? 30_000, 30_000) + 10_000 } : {}),
+                ...(wait ? { timeoutMs: waitMs + tuning.waitSlackMs } : {}),
             });
         },
         delete: (name, opId, signal) => request("DELETE", `${pod(name)}?opId=${encodeURIComponent(opId)}`, signal ? { signal } : {}),

package/dist/sandbox/pods/lifecycle.d.ts

@@ -7,7 +7,7 @@
  * per sandbox and keeps its timers.
  *
  * - **Create** is eager: a `PUT` of a new pod sandbox asks for `Running` at once. One that is
- *   not ready within `READY_DEADLINE_MS` is `failed`, with the pod's reason; the next turn
+ *   not ready within `pods.readyDeadlineMs` (Host tuning) is `failed`, with the pod's reason; the next turn
  *   start tries again.
  * - **Every change** the Runtime asks for bumps `rev`; the `PUT` carries `opId =
  *   <name>.r<rev>`, so a repeated apply is a no-op at the service, and a Sandbox whose `opId`
@@ -29,7 +29,9 @@
  *   reason that starts `setup:`, even while the pod is ready, until a turn start asks it to run.
  * - **Image** (Q14): the first ready pod's workload image is recorded by digest (`imageDigest`),
  *   and every later apply runs that digest, so a stop, relaunch or reset never pulls another
- *   image under the same tag. An image id with no repository (a locally loaded image) pins nothing.
+ *   image under the same tag. Only a digest of the repository the Environment asked for is
+ *   pinned: an image id with no repository, or one a node gave a name of its own (kind names an
+ *   image it loads `import-<date>`), pins nothing, since no registry serves it under that name.
  *
  * An unused Environment is deleted by the Tenant sweep (`lifecycle.deleteAfter`), not here.
  */
@@ -37,18 +39,19 @@ import type { EnvironmentEventPayload, EnvironmentEventType } from "@nylorun/cor
 import type { Environment, SandboxPodPatch, SandboxPodState } from "../../store/types.js";
 import type { PodStatus } from "./client.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 declare function imageDigestOf(imageID: string | undefined): string | undefined;
+export declare function repositoryOf(reference: string): string;
+/**
+ * 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 declare function imageDigestOf(imageID: string | undefined, requested: string): string | undefined;
 /** A setup failure's `reason` starts with this (`sandbox/setup.ts`); it is sticky. */
 export declare const SETUP_FAILED = "setup:";
-/** A pod not ready this long after it was asked to run has failed. */
-export declare const READY_DEADLINE_MS: number;
-/** How soon to look again while the pod changes. */
-export declare const POLL_MS = 2000;
-/** How soon to look again when the sandboxes service does not answer. */
-export declare const UNREACHABLE_RETRY_MS = 5000;
 /** The lifecycle settings (D36), read each time a decision is made. */
 export interface PodLifecycleConfig {
     readonly idleMs: number;
@@ -61,6 +64,11 @@ export type PodRow = Environment & {
 };
 export interface PodFacts {
     readonly row: PodRow;
+    /**
+     * The workload image the pod is asked to run: its applied recipe's, else the sandboxes
+     * service's default (`DEFAULT_SANDBOX_IMAGE`). Only a digest of its repository is pinned.
+     */
+    readonly image: string;
     readonly config: PodLifecycleConfig;
     /** The Sandbox's status; undefined when the sandboxes service did not answer. */
     readonly status: PodStatus | undefined;

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;
@@ -110,12 +132,12 @@ export function decide(facts) {
         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,9 +179,9 @@ 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 }));
@@ -167,7 +189,7 @@ export function decide(facts) {
         }
         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;
 }