@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/sandbox/join.js

@@ -32,7 +32,9 @@
  * which check failed.
  */
 import { createHash, timingSafeEqual } from "node:crypto";
-import { isSandboxId } from "@nylorun/core/contracts";
+import { isEnvironmentId } from "@nylorun/core/contracts";
+import { recoverLostVolume, runPendingSeed } from "../artifacts/disk.js";
+import { recordSetup, setupFile, setupPlanOf, setupState, } from "./setup.js";
 import { mintHostTokens, staleHost, verifyHostToken, } from "../tenant/host-token.js";
 /** A refused join, renewal or host connection. */
 export class HostAuthError extends Error {
@@ -84,7 +86,7 @@ export function hostAuthority(ctx) {
     return {
         async join(request) {
             const { sandboxId, podUid, joinToken, volumeId } = request;
-            if (!isSandboxId(sandboxId) ||
+            if (!isEnvironmentId(sandboxId) ||
                 typeof podUid !== "string" ||
                 !POD_UID.test(podUid) ||
                 typeof joinToken !== "string" ||
@@ -107,11 +109,11 @@ export function hostAuthority(ctx) {
                 // A pod being stopped joins nothing: its sandbox runs again only when asked to.
                 if (pod.desired !== "running")
                     return refuse("the sandbox is stopped");
-                if (pod.observed === "lost" || pod.observed === "expired")
-                    return refuse(`the sandbox is ${pod.observed}`);
+                if (pod.observed === "lost")
+                    return refuse("the sandbox is lost");
                 return pod;
             };
-            const readRow = () => ctx.store.tx((t) => t.sandboxResource(sandboxId));
+            const readRow = () => ctx.store.tx((t) => t.environment(sandboxId));
             const before = usable(await readRow());
             let current;
             try {
@@ -123,7 +125,7 @@ export function hostAuthority(ctx) {
             if (current !== podUid)
                 refuse("the pod is not the sandbox's current pod");
             const joined = await ctx.store.tx(async (t) => {
-                const row = await t.sandboxResource(sandboxId, { lock: true });
+                const row = await t.environment(sandboxId, { lock: true });
                 const pod = usable(row);
                 if (pod.k8sName !== before.k8sName)
                     refuse("the sandbox was reset during the join");
@@ -132,11 +134,14 @@ export function hostAuthority(ctx) {
                 if (pod.volumeId !== undefined && volumeId !== pod.volumeId) {
                     // A new, empty volume under the same Sandbox: the sandbox's files are gone.
                     const reason = "The sandbox's volume was replaced: its files are gone";
-                    await t.updateSandboxPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
-                    await t.sandboxEvent(sandboxId, "sandbox.lost", { reason });
+                    await t.updateEnvironmentPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
+                    await t.environmentEvent(sandboxId, "environment.lost", { reason });
+                    // Its Sandbox is deleted; only a reset brings the sandbox back.
+                    await t.signal({ type: "host.revoked", sandboxId, epoch });
+                    await t.signalSandbox(sandboxId, { kind: "reconcile" });
                     return { lost: epoch };
                 }
-                await t.updateSandboxPod(sandboxId, {
+                await t.updateEnvironmentPod(sandboxId, {
                     hostEpoch: epoch,
                     podUid,
                     ...(pod.volumeId === undefined && volumeId !== undefined ? { volumeId } : {}),
@@ -144,27 +149,48 @@ export function hostAuthority(ctx) {
                 }, now);
                 if (pod.podUid !== podUid) {
                     if (pod.podUid !== undefined)
-                        await t.sandboxEvent(sandboxId, "sandbox.relaunched", { hostEpoch: epoch });
+                        await t.environmentEvent(sandboxId, "environment.relaunched", { hostEpoch: epoch });
                     else
-                        await t.sandboxEvent(sandboxId, "sandbox.running", { hostEpoch: epoch });
+                        await t.environmentEvent(sandboxId, "environment.running", { hostEpoch: epoch });
                 }
-                return epoch;
+                // The previous host's connection (an older epoch) serves nothing more, on any process.
+                await t.signal({ type: "host.revoked", sandboxId, epoch });
+                return {
+                    epoch,
+                    setup: row ? await setupPlanOf(ctx, t, row) : undefined,
+                    seeded: row?.diskSeed !== undefined,
+                };
             });
-            if (typeof joined === "object") {
-                ctx.harness.revokeHost(sandboxId, joined.lost);
-                // Its Sandbox is deleted; only a reset brings the sandbox back.
-                await ctx.sandboxSignal(sandboxId, { kind: "reconcile" });
+            if ("lost" in joined) {
+                // With a disk version, a new volume seeded from the latest one (R2d step 3).
+                void recoverLostVolume(ctx, sandboxId).catch(() => undefined);
                 return refuse("the volume was replaced: the sandbox is lost");
             }
-            // The previous host's connection (an older epoch) serves nothing more.
-            ctx.harness.revokeHost(sandboxId, joined);
-            ctx.config.logger.info("sandbox host joined", { sandboxId, epoch: joined });
-            return answerOf(await mintHostTokens(ctx, { sandboxId, epoch: joined, podUid }), await ctx.keys.egressCa());
+            ctx.config.logger.info("sandbox host joined", { sandboxId, epoch: joined.epoch });
+            const answer = answerOf(await mintHostTokens(ctx, { sandboxId, epoch: joined.epoch, podUid }), await ctx.keys.egressCa());
+            if (joined.seeded) {
+                // The engine connects next; the seed waits for it, then writes the version.
+                void runPendingSeed(ctx, sandboxId);
+                return { ...answer, seeded: true };
+            }
+            return joined.setup ? { ...answer, setup: joined.setup } : answer;
         },
         async renew(hostToken) {
             const claims = await verified(hostToken);
             return answerOf(await mintHostTokens(ctx, claims), await ctx.keys.egressCa());
         },
         verify: verified,
+        async setup(hostToken) {
+            const claims = await verified(hostToken);
+            return setupState(ctx, claims.sandboxId);
+        },
+        async reportSetup(hostToken, report) {
+            const claims = await verified(hostToken);
+            await recordSetup(ctx, claims.sandboxId, claims.epoch, report);
+        },
+        async setupFile(hostToken, index, path) {
+            const claims = await verified(hostToken);
+            return setupFile(ctx, claims.sandboxId, index, path);
+        },
     };
 }

package/dist/sandbox/manager.d.ts

@@ -20,6 +20,7 @@ import type { EventPayload } from "@nylorun/core/contracts";
 import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
 import { type SandboxRecord, type SandboxRecords } from "./records.js";
 import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
+import { type DiskAnswer, type DiskOp } from "./disk-fs.js";
 import { type SandboxToolOutcome } from "./tools.js";
 import { type SandboxBackend, type SandboxListing } from "./types.js";
 export { sandboxCapabilityOf } from "./capability.js";
@@ -33,7 +34,7 @@ export interface SandboxSessionRef {
      * The sandbox resource the owning session is attached to. Its workspace is keyed by this id,
      * so every session attached to it shares the files; absent, the workspace is the session's.
      */
-    readonly sandboxId?: string;
+    readonly environmentId?: string;
     /** Variables every command of the call gets (R2c): secret names set to the sentinel, plain values. */
     readonly environment?: Readonly<Record<string, string>>;
     /**
@@ -55,7 +56,7 @@ export interface SandboxSweepOptions {
     /** Whether a session still exists; sandboxes of deleted sessions are removed. */
     readonly sessionExists: (sessionId: string) => boolean | Promise<boolean>;
     /** Whether a sandbox resource still exists. Default: every one does. */
-    readonly sandboxExists?: (sandboxId: string) => boolean | Promise<boolean>;
+    readonly sandboxExists?: (environmentId: string) => boolean | Promise<boolean>;
 }
 export interface SandboxManagerOptions {
     /** Distinguishes this Runtime's sandboxes from other Runtimes on the same machine: the Tenant id. */
@@ -77,7 +78,7 @@ export interface SandboxManagerOptions {
     readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, meta: SandboxEventMeta) => void | Promise<void>;
 }
 /** The session events a sandbox writes. */
-export type SandboxEventType = "sandbox.state" | "sandbox.exec";
+export type SandboxEventType = "environment.state" | "environment.exec";
 export declare class SandboxManager {
     private readonly options;
     private selection?;
@@ -104,8 +105,8 @@ export declare class SandboxManager {
     /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
     hasRecords(): Promise<boolean>;
     keyOf(sessionId: string): string;
-    /** The workspace key of sandbox resource `sandboxId` (`sandboxWorkspaceKey`). */
-    sandboxKeyOf(sandboxId: string): string;
+    /** The workspace key of sandbox resource `environmentId` (`sandboxWorkspaceKey`). */
+    sandboxKeyOf(environmentId: string): string;
     private keyFor;
     report(): Promise<SandboxSelectionReport & {
         readonly defaultImage: string;
@@ -141,6 +142,13 @@ export declare class SandboxManager {
     } | Extract<SandboxToolOutcome, {
         kind: "failed";
     }>>;
+    /**
+     * One operation on the disk of the session's sandbox (R2d step 3, `sandbox/disk-fs.ts`), in the
+     * same queue as its tool calls, starting it first when it is stopped.
+     */
+    disk(session: SandboxSessionRef, capability: CapabilityManifest, op: DiskOp, signal: AbortSignal): Promise<DiskAnswer | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
     /** Runs `use` on the session's sandbox in its queue, starting it first when it is stopped. */
     private withHandle;
     /** The session's live sandbox entry and spec, or why it cannot run here. */
@@ -159,16 +167,16 @@ export declare class SandboxManager {
     /** The sandbox record for a session, if one was ever created. */
     status(sessionId: string): Promise<SandboxRecord | undefined>;
     /**
-     * Deletes sandbox resource `sandboxId`'s workspace, its files and its compute record, after
+     * Deletes sandbox resource `environmentId`'s workspace, its files and its compute record, after
      * any command queued on it. Called once the resource is deleted.
      */
-    removeSandbox(sandboxId: string): Promise<void>;
+    removeSandbox(environmentId: string): Promise<void>;
     /** Deletes the workspace `key`, its files and its record, after any command queued on it. */
     remove(key: string): Promise<void>;
     /**
      * Delete workspaces this Runtime owns whose owner is gone: a session's when `sessionExists`
      * says the session is gone, a sandbox resource's when `sandboxExists` says the resource is.
      */
-    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>, sandboxExists: (sandboxId: string) => boolean | Promise<boolean>): Promise<void>;
+    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>, sandboxExists: (environmentId: string) => boolean | Promise<boolean>): Promise<void>;
     close(): Promise<void>;
 }

package/dist/sandbox/manager.js

@@ -3,6 +3,7 @@ import { sandboxWorkspaceKey, sessionWorkspaceKey, workspacePrefix, } from "./re
 import { DEFAULT_SANDBOX_CPUS, DEFAULT_SANDBOX_IMAGE, describeNetwork, idleMsOf, memoryMiBOf, resolveNetwork, } from "./policy.js";
 import { parseSandboxPreference, reportSelection, selectSandboxBackend, } from "./select.js";
 import { mountSkill, sandboxSkillsOf, skillSignature } from "./skills.js";
+import { runDiskOp } from "./disk-fs.js";
 import { resolveSandboxPath, runSandboxTool, } from "./tools.js";
 import { SandboxFileTooLargeError, } from "./types.js";
 export { sandboxCapabilityOf } from "./capability.js";
@@ -89,14 +90,14 @@ export class SandboxManager {
     keyOf(sessionId) {
         return sessionWorkspaceKey(this.options.scope, sessionId);
     }
-    /** The workspace key of sandbox resource `sandboxId` (`sandboxWorkspaceKey`). */
-    sandboxKeyOf(sandboxId) {
-        return sandboxWorkspaceKey(this.options.scope, sandboxId);
+    /** The workspace key of sandbox resource `environmentId` (`sandboxWorkspaceKey`). */
+    sandboxKeyOf(environmentId) {
+        return sandboxWorkspaceKey(this.options.scope, environmentId);
     }
     keyFor(session) {
-        return session.sandboxId === undefined
+        return session.environmentId === undefined
             ? this.keyOf(session.id)
-            : this.sandboxKeyOf(session.sandboxId);
+            : this.sandboxKeyOf(session.environmentId);
     }
     async report() {
         return { ...reportSelection(await this.ready), defaultImage: DEFAULT_SANDBOX_IMAGE };
@@ -167,6 +168,21 @@ export class SandboxManager {
                 : { kind: "listed", path: resolved, listing };
         });
     }
+    /**
+     * One operation on the disk of the session's sandbox (R2d step 3, `sandbox/disk-fs.ts`), in the
+     * same queue as its tool calls, starting it first when it is stopped.
+     */
+    async disk(session, capability, op, signal) {
+        return this.withHandle(session, capability, signal, async (handle, live) => {
+            if (!handle.diskRoots)
+                return {
+                    kind: "failed",
+                    code: "sandbox.unsupported",
+                    message: `The ${live.backend.name} backend has no disk to version`,
+                };
+            return runDiskOp(handle.diskRoots, op);
+        });
+    }
     /** Runs `use` on the session's sandbox in its queue, starting it first when it is stopped. */
     async withHandle(session, capability, signal, use) {
         const prepared = await this.prepare(session, capability);
@@ -234,7 +250,7 @@ export class SandboxManager {
         if (!live) {
             live = {
                 sessionId: session.id,
-                ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
+                ...(session.environmentId === undefined ? {} : { environmentId: session.environmentId }),
                 backend,
                 idleMs: idleMsOf(capability.sandbox),
                 active: 0,
@@ -268,7 +284,7 @@ export class SandboxManager {
             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, "sandbox.state", { state: "stopped", backend: live.backend.name, error: message }, { record, ...claimOf(session) });
+                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",
@@ -286,7 +302,7 @@ export class SandboxManager {
             const outcome = await runSandboxTool(live.handle, toolName, (input ?? {}), signal, (value) => {
                 report = value;
             }, session.environment);
-            await this.options.emit(session.id, session.activeTurnId, "sandbox.exec", {
+            await this.options.emit(session.id, session.activeTurnId, "environment.exec", {
                 tool: toolName,
                 ...report,
                 ...(report.command ? { command: report.command.slice(0, 500) } : {}),
@@ -347,12 +363,12 @@ export class SandboxManager {
             network: describeNetwork(spec.network),
         };
         const creating = await this.record(spec.key, live, session.id, spec.image, "creating", existing);
-        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", { state: "creating", ...payload, ...(existing ? { reattach: true } : {}) }, { record: creating, ...claimOf(session) });
+        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();
         const running = await this.record(spec.key, live, session.id, spec.image, "running", existing);
-        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
+        await this.options.emit(session.id, session.activeTurnId, "environment.state", {
             state: "running",
             ...payload,
             ...(existing && handle.created
@@ -371,7 +387,7 @@ export class SandboxManager {
         }
         finally {
             const record = await this.record(key, live, live.sessionId, undefined, "stopped");
-            await this.options.emit(live.sessionId, null, "sandbox.state", { state: "stopped", backend: live.backend.name }, { record });
+            await this.options.emit(live.sessionId, null, "environment.state", { state: "stopped", backend: live.backend.name }, { record });
         }
     }
     async record(key, live, sessionId, image, state, known) {
@@ -380,7 +396,7 @@ export class SandboxManager {
         const record = {
             key,
             sessionId,
-            ...(live.sandboxId === undefined ? {} : { sandboxId: live.sandboxId }),
+            ...(live.environmentId === undefined ? {} : { environmentId: live.environmentId }),
             backend: live.backend.name,
             image: image ?? existing?.image ?? "",
             state,
@@ -395,11 +411,11 @@ export class SandboxManager {
         return this.options.records.get(this.keyOf(sessionId));
     }
     /**
-     * Deletes sandbox resource `sandboxId`'s workspace, its files and its compute record, after
+     * Deletes sandbox resource `environmentId`'s workspace, its files and its compute record, after
      * any command queued on it. Called once the resource is deleted.
      */
-    async removeSandbox(sandboxId) {
-        await this.remove(this.sandboxKeyOf(sandboxId));
+    async removeSandbox(environmentId) {
+        await this.remove(this.sandboxKeyOf(environmentId));
     }
     /** Deletes the workspace `key`, its files and its record, after any command queued on it. */
     async remove(key) {
@@ -425,9 +441,9 @@ export class SandboxManager {
         for (const key of await backend.list(this.prefix)) {
             const record = await this.options.records.get(key);
             if (record) {
-                const kept = record.sandboxId === undefined
+                const kept = record.environmentId === undefined
                     ? await sessionExists(record.sessionId)
-                    : await sandboxExists(record.sandboxId);
+                    : await sandboxExists(record.environmentId);
                 if (kept)
                     continue;
             }

package/dist/sandbox/placement.d.ts

@@ -1,27 +1,28 @@
 /**
  * Placement (F7.2, D38): where a session's harness runs, checked when the session opens and
  * never downgraded afterwards. The Tenant maps harness ids (`nylorun`, or `*` for the rest) to
- * the hosts they may run on (`sandbox.config` `placement`): `harness-container` (the Runtime's
- * harness: in process, or the harness container) and `sandbox` (the engine in a pod sandbox).
- * Default: both.
+ * the hosts they may run on (`environments.config` `placement`): `harness-container` (the
+ * Runtime's harness: in process, or the harness container) and `sandbox` (the engine in a pod).
+ * Default: both. `"*": { hosts: [] }` refuses every harness the map does not name (R4.1).
  *
- * A session attached to a pod sandbox runs on `sandbox`; every other session on
- * `harness-container`. A host the Tenant does not allow is `409 placement_refused`. A pod
- * sandbox needs sandbox pods: without a cluster (`nylorun sandbox enable`), or with the
- * sandboxes service not ready, it is `409 sandbox_unavailable`.
+ * A session on a pod Environment runs on `sandbox`; every other session (a virtual or `none`
+ * Environment, or none) on `harness-container` (D52). A host the Tenant does not allow is
+ * `409 placement_refused`. A pod Environment needs sandbox pods: without a cluster (`nylorun
+ * sandbox enable`), or with the sandboxes service not ready, it is `409 environment_unavailable`.
  */
-import type { SandboxPlacementHost, TenantSandboxConfig } from "@nylorun/core/contracts";
+import { type EnvironmentKind, type PlacementHost as SandboxPlacementHost } from "@nylorun/core/contracts";
+import type { TenantSandboxConfig } from "./tenant-config.js";
 import type { TenantPods } from "../tenant/context.js";
-/** The harness every session of this Runtime runs (blueprint D38). */
+/** Our harness's id (blueprint D38): what a session runs unless its Environment names another. */
 export declare const HARNESS_ID = "nylorun";
 export declare const DEFAULT_PLACEMENT: readonly SandboxPlacementHost[];
 /** The hosts harness `harnessId` may run on. */
 export declare function placementOf(config: TenantSandboxConfig, harnessId?: string): readonly SandboxPlacementHost[];
 /** How to enable sandbox pods, for the messages that need them. */
 export declare const ENABLE_PODS = "run `nylorun sandbox enable --context <name>` to give this Tenant a cluster";
-/** Refuses a session whose sandbox needs a host the Tenant does not allow. */
-export declare function checkPlacement(config: TenantSandboxConfig, kind: "virtual" | "pod" | undefined): void;
+/** 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. */
 export declare function podsReady(pods: TenantPods): Promise<boolean>;
-/** Refuses a pod sandbox without sandbox pods, or with the sandboxes service down. */
+/** 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

@@ -1,6 +1,19 @@
+/**
+ * Placement (F7.2, D38): where a session's harness runs, checked when the session opens and
+ * never downgraded afterwards. The Tenant maps harness ids (`nylorun`, or `*` for the rest) to
+ * the hosts they may run on (`environments.config` `placement`): `harness-container` (the
+ * Runtime's harness: in process, or the harness container) and `sandbox` (the engine in a pod).
+ * Default: both. `"*": { hosts: [] }` refuses every harness the map does not name (R4.1).
+ *
+ * A session on a pod Environment runs on `sandbox`; every other session (a virtual or `none`
+ * Environment, or none) on `harness-container` (D52). A host the Tenant does not allow is
+ * `409 placement_refused`. A pod Environment needs sandbox pods: without a cluster (`nylorun
+ * 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";
-/** The harness every session of this Runtime runs (blueprint D38). */
-export const HARNESS_ID = "nylorun";
+/** 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"];
 /** The hosts harness `harnessId` may run on. */
 export function placementOf(config, harnessId = HARNESS_ID) {
@@ -9,14 +22,18 @@ export function placementOf(config, harnessId = HARNESS_ID) {
 }
 /** How to enable sandbox pods, for the messages that need them. */
 export const ENABLE_PODS = "run `nylorun sandbox enable --context <name>` to give this Tenant a cluster";
-/** Refuses a session whose sandbox needs a host the Tenant does not allow. */
-export function checkPlacement(config, kind) {
+/** Refuses a session whose harness, on the host its Environment needs, the Tenant does not allow. */
+export function checkPlacement(config, kind, harness = HARNESS_ID) {
     const host = kind === "pod" ? "sandbox" : "harness-container";
-    const allowed = placementOf(config);
-    if (!allowed.includes(host))
-        fail(409, kind === "pod"
-            ? `This Tenant does not let the ${HARNESS_ID} harness run in a sandbox pod (placement allows ${allowed.join(", ")}).`
-            : `This Tenant runs the ${HARNESS_ID} harness only in sandbox pods (placement allows ${allowed.join(", ")}): attach a pod sandbox with sandbox: { id }.`, { code: "placement_refused", details: { harness: HARNESS_ID, host, allowed: [...allowed] } });
+    const allowed = placementOf(config, harness);
+    if (allowed.includes(host))
+        return;
+    const where = allowed.length === 0 ? "it may run nowhere" : `placement allows ${allowed.join(", ")}`;
+    fail(409, allowed.length === 0
+        ? `This Tenant does not run the ${harness} harness (${where}).`
+        : kind === "pod"
+            ? `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();
@@ -29,15 +46,15 @@ export async function podsReady(pods) {
     ready.set(pods, { at: Date.now(), ready: answer });
     return answer;
 }
-/** Refuses a pod sandbox without sandbox pods, or with the sandboxes service down. */
+/** Refuses a pod Environment without sandbox pods, or with the sandboxes service down. */
 export async function requirePods(pods, what) {
     if (!pods)
         return fail(409, `${what} needs sandbox pods, and this Runtime has no cluster: ${ENABLE_PODS}.`, {
-            code: "sandbox_unavailable",
+            code: "environment_unavailable",
         });
     if (!(await podsReady(pods)))
         fail(409, `${what} needs sandbox pods, and the sandboxes service is not ready. Check \`nylorun sandbox status\`.`, {
-            code: "sandbox_unavailable",
+            code: "environment_unavailable",
             details: { retryAfterSeconds: 5 },
         }, { "retry-after": "5" });
     return pods;

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

@@ -13,7 +13,12 @@ export interface PodSpec {
     readonly mode: "Running" | "Suspended";
     /** The workload image; the service defaults it to `python:3.13-slim`. */
     readonly image?: string;
-    /** The Runtime image the engine is copied from. */
+    /**
+     * What the workload runs: `engine` (default), our engine copied from `harnessImage`, or
+     * `image`, the image's own entrypoint, for a custom harness built into it (R4.4).
+     */
+    readonly entrypoint?: "engine" | "image";
+    /** The Runtime image the engine is copied from; not with `entrypoint: "image"`. */
     readonly harnessImage?: string;
     /** Replaces the engine command (diagnostics). */
     readonly command?: readonly string[];

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

@@ -1,5 +1,5 @@
 /**
- * A pod sandbox's lifecycle (blueprint D34, D36), as one pure decision: from the row, the
+ * A pod Environment's lifecycle (blueprint D34, D36), as one pure decision: from the row, the
  * Tenant's lifecycle settings, the Sandbox's status as the sandboxes service sees it and the
  * clock, what to ask of the service, what to write to the row, which events to record, and
  * when to look again. `reconcile.ts` gathers the facts, carries the decision out and runs it
@@ -12,42 +12,43 @@
  * - **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`
  *   is not the row's is applied again.
- * - **Idle** (`trigger: idle`): no turn on an attached session, and none ended within the
- *   Tenant's `limits.idle` → `Suspended` (`sandbox.suspended`, reason `idle`). The volume is
- *   kept; the next turn start asks for `Running` again.
- * - **TTL**: the Sandbox carries `shutdownTime = createdAt + lifecycle.ttl` and the Tenant's
- *   `onExpiry` as its `shutdownPolicy`. Once it passes, the sandbox is `expired`
- *   (`sandbox.expired`), its host epoch moves (its tokens stop working) and turns are refused
- *   (`sandbox_expired`); with `onExpiry: delete` it is deleted. A `PUT` with a longer TTL moves
- *   `expiresAt`, and the next apply revives it with the later `shutdownTime`.
+ * - **Idle** (`trigger: idle`): no turn on a session that names it, and none ended within its
+ *   `lifecycle.idle` (at most the Tenant's `limits.idle`) → `Suspended` (`environment.suspended`,
+ *   reason `idle`). The volume is kept; the next turn start asks for `Running` again.
  * - **Lost**: an incarnation that has run (a pod joined) whose Sandbox is gone or whose volume
- *   is missing is `lost` (`sandbox.lost`): its host epoch moves, its Sandbox is deleted, and
- *   only a reset brings the sandbox back. agent-sandbox recreates a deleted claim empty, so the
- *   engine's join also checks the id it keeps on the volume (`join.ts`): a new volume is lost
- *   too. A pod replaced on the same volume is not lost: the new pod's join bumps the epoch
- *   (`sandbox.relaunched`).
+ *   is missing is `lost` (`environment.lost`): its host epoch moves, its Sandbox is deleted, and
+ *   only a reset brings the Environment back. agent-sandbox recreates a deleted claim empty, so
+ *   the engine's join also checks the id it keeps on the volume (`join.ts`): a new volume is
+ *   lost too. A pod replaced on the same volume is not lost: the new pod's join bumps the epoch
+ *   (`environment.relaunched`).
  * - **Delete** (`desired: deleted`): the Sandbox is deleted, and the row once it is gone.
- * - **Reset** (`tenant/sandboxes.ts`) bumps the volume generation: a new name, so a new
+ * - **Reset** (`tenant/environments.ts`) bumps the volume generation: a new name, so a new
  *   Sandbox and volume; the old name is `retiring` and deleted here.
+ *
+ * - **Setup** (R2d step 2): a failed setup (`sandbox/setup.ts`) leaves the pod `failed` with a
+ *   reason that starts `setup:`, even while the pod is ready, until a turn start asks it to run.
+ *
+ * An unused Environment is deleted by the Tenant sweep (`lifecycle.deleteAfter`), not here.
  */
-import type { SandboxEventPayload, SandboxEventType } from "@nylorun/core/contracts";
-import type { SandboxPodPatch, SandboxPodState, SandboxResource } from "../../store/types.js";
+import type { EnvironmentEventPayload, EnvironmentEventType } from "@nylorun/core/contracts";
+import type { Environment, SandboxPodPatch, SandboxPodState } from "../../store/types.js";
 import type { PodStatus } from "./client.js";
+/** 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 Tenant's lifecycle settings (D36), read each time a decision is made. */
+/** The lifecycle settings (D36), read each time a decision is made. */
 export interface PodLifecycleConfig {
-    readonly onExpiry: "retain" | "delete";
     readonly idleMs: number;
 }
-/** Why the decision is made: a reconcile, or one of the sandbox's timers firing. */
-export type PodTrigger = "reconcile" | "idle" | "ttl";
-export type PodTimer = "idle" | "ttl";
-export type PodRow = SandboxResource & {
+/** Why the decision is made: a reconcile, or the idle timer firing. */
+export type PodTrigger = "reconcile" | "idle";
+export type PodTimer = "idle";
+export type PodRow = Environment & {
     readonly pod: SandboxPodState;
 };
 export interface PodFacts {
@@ -57,14 +58,14 @@ export interface PodFacts {
     readonly status: PodStatus | undefined;
     /** The retiring Sandbox's status, when the row names one. */
     readonly retiring?: PodStatus | undefined;
-    /** A session attached to the sandbox has a turn running. */
+    /** A session that names the Environment has a turn running. */
     readonly busy: boolean;
     readonly now: number;
     readonly trigger: PodTrigger;
 }
-export interface PodEvent<T extends SandboxEventType = SandboxEventType> {
+export interface PodEvent<T extends EnvironmentEventType = EnvironmentEventType> {
     readonly type: T;
-    readonly payload: SandboxEventPayload<T>;
+    readonly payload: EnvironmentEventPayload<T>;
 }
 export interface PodDecision {
     /** Apply the row's spec (after `patch`) in this mode; `rotateJoin` mints a new join token. */
@@ -76,7 +77,7 @@ export interface PodDecision {
     readonly delete: readonly string[];
     readonly patch: SandboxPodPatch;
     readonly events: readonly PodEvent[];
-    /** The Sandbox is gone and the sandbox deleted: remove the row. */
+    /** The Sandbox is gone and the Environment deleted: remove the row. */
     readonly removeRow?: true;
     /** Look again this soon. */
     readonly retryAfterMs?: number;