@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/sandbox/manager.js

@@ -2,10 +2,11 @@ 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, skillSignature } from "./skills.js";
+import { mountSkill, sandboxSkillsOf } 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";
+export { sandboxToolSpec } from "./runtime-tools.js";
 const READ_TOOLS = new Set(["read", "grep", "glob"]);
 export class SandboxManager {
     options;
@@ -43,23 +44,20 @@ export class SandboxManager {
         if (this.closing)
             return;
         const now = at ?? Date.now();
-        const idle = (live) => !!live.handle && live.active === 0 && now - live.lastUsedAt >= live.idleMs;
+        const idle = (live) => !!live.handle && live.running.size === 0 && now - live.lastUsedAt >= live.idleMs;
         const stops = [];
         for (const [key, live] of this.live) {
             if (!idle(live))
                 continue;
-            // Queued behind any call already waiting; checked again when its turn comes.
-            live.tail = live.tail
-                .then(() => (idle(live) ? this.stop(key, live) : undefined))
-                .catch(() => undefined);
-            stops.push(live.tail);
+            // After the calls running; checked again when its turn comes.
+            stops.push(this.alone(live, () => (idle(live) ? this.stop(key, live) : undefined)).catch(() => undefined));
         }
         await Promise.all(stops);
         for (const record of await this.options.records.list()) {
             if (record.state === "stopped")
                 continue;
             const live = this.live.get(record.key);
-            if (live && (live.handle || live.active > 0))
+            if (live && (live.handle || live.running.size > 0))
                 continue;
             await this.options.records.put({ ...record, state: "stopped" });
         }
@@ -89,34 +87,84 @@ 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 };
     }
-    async run(session, capability, toolName, input, signal) {
-        const prepared = await this.prepare(session, capability);
+    async run(session, sandbox, toolName, input, signal) {
+        const prepared = await this.prepare(session, sandbox);
         if ("kind" in prepared)
             return prepared;
         const { live: entry, spec } = prepared;
-        const task = entry.tail.then(() => this.execute(entry, session, spec, toolName, input, signal));
-        entry.tail = task.catch(() => undefined);
+        return this.inLane(entry, session.id, () => this.execute(entry, session, spec, toolName, input, signal));
+    }
+    /**
+     * Runs `call` in session `sessionId`'s queue on `live`: after its earlier calls, and after any
+     * stop or removal pending, beside other sessions' calls (D66).
+     */
+    inLane(live, sessionId, call) {
+        const task = (live.lanes.get(sessionId) ?? Promise.resolve()).then(async () => {
+            // A stop queued while this waited goes first.
+            for (let gate = live.gate;; gate = live.gate) {
+                await gate;
+                if (gate === live.gate)
+                    break;
+            }
+            const running = call();
+            live.running.add(running);
+            try {
+                return await running;
+            }
+            finally {
+                live.running.delete(running);
+                live.lastUsedAt = Date.now();
+            }
+        });
+        const queued = task.catch(() => undefined);
+        live.lanes.set(sessionId, queued);
+        void queued.then(() => {
+            if (live.lanes.get(sessionId) === queued)
+                live.lanes.delete(sessionId);
+        });
+        return task;
+    }
+    /** Runs `step` on `live` alone: after the calls running, before the calls that come after it. */
+    alone(live, step) {
+        const task = live.gate.then(async () => {
+            while (live.running.size > 0)
+                await Promise.allSettled([...live.running]);
+            return step();
+        });
+        live.gate = task.catch(() => undefined);
         return task;
     }
+    /** The workspace's handle, opened once for the calls that need it at the same time. */
+    async handleOf(live, session, spec) {
+        if (live.handle)
+            return live.handle;
+        const opening = (live.opening ??= this.open(live, session, spec).finally(() => {
+            if (live.opening === opening)
+                live.opening = undefined;
+        }));
+        const handle = await opening;
+        live.handle ??= handle;
+        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
      * cannot open or the file is larger than `maxBytes`. Relative paths resolve in the workspace.
      */
-    async readBytes(session, capability, path, maxBytes, signal) {
-        return this.withHandle(session, capability, signal, async (handle, live) => {
+    async readBytes(session, sandbox, path, maxBytes, signal) {
+        return this.withHandle(session, sandbox, signal, async (handle, live) => {
             const resolved = resolveSandboxPath(path, handle.workspace ?? SANDBOX_WORKSPACE);
             if (!handle.readBytes)
                 return {
@@ -146,14 +194,14 @@ export class SandboxManager {
      * 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, capability, dir, maxEntries, signal) {
+    async listFiles(session, sandbox, dir, maxEntries, signal) {
         const key = this.keyFor(session);
         if (!this.live.get(key)?.handle) {
             const record = await this.options.records.get(key);
             if (!record)
                 return { kind: "missing", path: dir };
         }
-        return this.withHandle(session, capability, signal, async (handle, live) => {
+        return this.withHandle(session, sandbox, signal, async (handle, live) => {
             const resolved = resolveSandboxPath(dir, handle.workspace ?? SANDBOX_WORKSPACE);
             if (!handle.listFiles)
                 return {
@@ -167,46 +215,51 @@ 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, sandbox, op, signal) {
+        return this.withHandle(session, sandbox, 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);
+    async withHandle(session, sandbox, signal, use) {
+        const prepared = await this.prepare(session, sandbox);
         if ("kind" in prepared)
             return prepared;
         const { live, spec } = prepared;
-        const task = live.tail.then(async () => {
+        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");
-            live.active += 1;
+            let handle;
             try {
-                if (!live.handle) {
-                    try {
-                        live.handle = await this.open(live, session, spec);
-                    }
-                    catch (error) {
-                        return {
-                            kind: "failed",
-                            code: "sandbox.start_failed",
-                            message: `The sandbox could not start: ${error instanceof Error ? error.message : String(error)}`,
-                        };
-                    }
-                }
-                const unmounted = await this.mountSkills(live, live.handle, session, signal);
-                if (unmounted)
-                    return unmounted;
-                return await use(live.handle, live);
+                handle = await this.handleOf(live, session, spec);
             }
-            finally {
-                live.active -= 1;
-                live.lastUsedAt = Date.now();
+            catch (error) {
+                return {
+                    kind: "failed",
+                    code: "sandbox.start_failed",
+                    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);
         });
-        live.tail = task.catch(() => undefined);
-        return task;
     }
     /** The session's live sandbox entry and spec, or why it cannot run here. */
-    async prepare(session, capability) {
+    async prepare(session, sandbox) {
         const selection = await this.ready;
         const backend = selection.backend;
         if (!backend)
@@ -218,10 +271,10 @@ export class SandboxManager {
         const key = this.keyFor(session);
         const spec = {
             key,
-            image: capability.sandbox?.image ?? DEFAULT_SANDBOX_IMAGE,
-            cpus: capability.sandbox?.resources?.cpus ?? DEFAULT_SANDBOX_CPUS,
-            memoryMiB: memoryMiBOf(capability.sandbox),
-            network: resolveNetwork(capability.sandbox),
+            image: sandbox?.image ?? DEFAULT_SANDBOX_IMAGE,
+            cpus: sandbox?.resources?.cpus ?? DEFAULT_SANDBOX_CPUS,
+            memoryMiB: memoryMiBOf(sandbox),
+            network: resolveNetwork(sandbox),
         };
         const unmet = backend.unmet(spec);
         if (unmet)
@@ -234,12 +287,13 @@ 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,
+                idleMs: idleMsOf(sandbox),
+                running: new Set(),
                 lastUsedAt: Date.now(),
-                tail: Promise.resolve(),
+                lanes: new Map(),
+                gate: Promise.resolve(),
                 skills: new Map(),
             };
             this.live.set(key, live);
@@ -251,42 +305,34 @@ export class SandboxManager {
             throw new Error("Turn cancelled");
         if (this.closing)
             throw new Error("Runtime is shutting down");
-        live.active += 1;
-        try {
-            return await this.executeOpen(live, session, spec, toolName, input, signal);
-        }
-        finally {
-            live.active -= 1;
-            live.lastUsedAt = Date.now();
-        }
+        return this.executeOpen(live, session, spec, toolName, input, signal);
     }
     async executeOpen(live, session, spec, toolName, input, signal) {
-        if (!live.handle) {
-            try {
-                live.handle = await this.open(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, "sandbox.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}`,
-                };
-            }
+        let handle;
+        try {
+            handle = await this.handleOf(live, session, spec);
         }
-        const unmounted = await this.mountSkills(live, live.handle, session, signal);
+        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;
         const started = Date.now();
         let report = {};
         try {
-            const outcome = await runSandboxTool(live.handle, toolName, (input ?? {}), signal, (value) => {
+            const outcome = await runSandboxTool(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) } : {}),
@@ -297,8 +343,9 @@ export class SandboxManager {
             return outcome;
         }
         catch (error) {
-            // The backend itself failed; reopen on the next call.
-            live.handle = undefined;
+            // The backend itself failed; reopen on the next call, unless another call already did.
+            if (live.handle === handle)
+                live.handle = undefined;
             if (signal.aborted || !READ_TOOLS.has(toolName))
                 throw error;
             return {
@@ -309,32 +356,38 @@ export class SandboxManager {
         }
     }
     /**
-     * Mounts the session's skills the workspace does not hold as they are: on a handle just opened
-     * all of them, later only those another session brought or changed. A failed outcome when
-     * one cannot be mounted; nothing is marked mounted then, so the next call tries again.
+     * 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.
      */
     async mountSkills(live, handle, session, signal) {
         const read = this.options.definitionFile;
         if (!read)
             return undefined;
-        for (const [name, files] of sandboxSkillsOf(session.manifest)) {
-            const signature = skillSignature(files);
-            if (live.skills.get(name) === signature)
-                continue;
+        for (const [folder, files] of sandboxSkillsOf(session.manifest)) {
+            let mounting = live.skills.get(folder);
+            if (!mounting) {
+                const mount = mountSkill(handle, folder, files, (sha256) => read(sha256, session), signal);
+                live.skills.set(folder, mount);
+                void mount.catch(() => {
+                    if (live.skills.get(folder) === mount)
+                        live.skills.delete(folder);
+                });
+                mounting = mount;
+            }
             try {
-                await mountSkill(handle, name, files, (sha256) => read(sha256, session), signal);
+                await mounting;
             }
             catch (error) {
                 if (signal.aborted)
                     throw error;
-                live.skills.delete(name);
                 return {
                     kind: "failed",
                     code: "sandbox.skills_unavailable",
-                    message: `The files of skill '${name}' could not be put in the sandbox: ${error instanceof Error ? error.message : String(error)}`,
+                    message: `The files of skill folder ${folder} could not be put in the sandbox: ${error instanceof Error ? error.message : String(error)}`,
                 };
             }
-            live.skills.set(name, signature);
         }
         return undefined;
     }
@@ -347,12 +400,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 +424,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 +433,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,18 +448,19 @@ 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) {
         const live = this.live.get(key);
         if (live) {
-            await live.tail.catch(() => undefined);
-            live.handle = undefined;
+            await this.alone(live, () => {
+                live.handle = undefined;
+            }).catch(() => undefined);
             this.live.delete(key);
         }
         const { backend } = await this.ready;
@@ -425,9 +479,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;
             }
@@ -439,7 +493,8 @@ export class SandboxManager {
         if (!this.selection)
             return;
         const tasks = [...this.live.entries()].map(async ([key, live]) => {
-            await live.tail;
+            await Promise.allSettled([...live.lanes.values(), live.gate]);
+            await Promise.allSettled([...live.running]);
             if (this.options.ephemeral) {
                 live.handle = undefined;
                 await live.backend.remove(key);

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;
+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. */
 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) {
@@ -8,15 +21,19 @@ export function placementOf(config, harnessId = HARNESS_ID) {
     return placement?.[harnessId]?.hosts ?? placement?.["*"]?.hosts ?? DEFAULT_PLACEMENT;
 }
 /** 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) {
+export 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 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",
+        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" });
     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[];
@@ -39,6 +44,8 @@ export interface PodStatus {
     readonly expired: boolean;
     readonly podUID?: string;
     readonly podPhase?: string;
+    /** The workload container's image as the node pulled it (`repo@sha256:…`), once it runs. */
+    readonly imageID?: string;
     readonly volume: "present" | "missing";
     readonly opId?: string;
     readonly shutdownTime?: string;
@@ -47,7 +54,7 @@ export interface PodStatus {
     /** With `?wait=`: whether the state was reached before the timeout. */
     readonly met?: boolean;
 }
-/** `GET /v1/info`: the cluster `nylorun sandbox enable` recorded. */
+/** `GET /v1/info`: the cluster `nylorun local sandbox enable` recorded. */
 export interface ClusterInfo {
     readonly namespace: string;
     readonly context: string;