@nylorun/runtime 0.24.0-beta → 0.26.0-beta

package/dist/record/environment.js

@@ -1,7 +1,7 @@
 /**
  * A environment's lifecycle stream (blueprint D39, F7.1): `environment.created`, `environment.attached`,
  * `environment.detached` and `environment.deleted` (and the rest of `ENVIRONMENT_EVENT_TYPES`, egress-gate's
- * `environment.egress` between turns among them), on the `nylorun.environment-event/1` envelope, numbered
+ * `environment.egress` for every connection among them, D67), on the `nylorun.environment-event/1` envelope, numbered
  * from 0 per environment id in `nylorun_streams.environment_events`. The record module is its only
  * writer, as for session events; the store runs the two statements through
  * `EnvironmentRecordWriter` in the caller's transaction, under the environment row's lock (or, for a

package/dist/sandbox/join.js

@@ -159,6 +159,7 @@ export function hostAuthority(ctx) {
                     epoch,
                     setup: row ? await setupPlanOf(ctx, t, row) : undefined,
                     seeded: row?.diskSeed !== undefined,
+                    afterSeed: row?.diskSeed?.setup === true,
                 };
             });
             if ("lost" in joined) {
@@ -171,6 +172,9 @@ export function hostAuthority(ctx) {
             if (joined.seeded) {
                 // The engine connects next; the seed waits for it, then writes the version.
                 void runPendingSeed(ctx, sandboxId);
+                // A fork onto other setup (Q17): the engine runs it once the version is written.
+                if (joined.afterSeed)
+                    return { ...answer, seeded: true, afterSeed: true, ...(joined.setup ? { setup: joined.setup } : {}) };
                 return { ...answer, seeded: true };
             }
             return joined.setup ? { ...answer, setup: joined.setup } : answer;

package/dist/sandbox/manager.d.ts

@@ -2,8 +2,11 @@
  * 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. Commands against one
- * workspace run one at a time, whichever session sends them.
+ * 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)
@@ -12,18 +15,18 @@
  * (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 session's skills (track R2 M4) are mounted on its workspace, read-only under
- * `/skills/<name>/`, before the first call that opens it (`skills.ts`); their bytes come
- * through the `definitionFile` port.
+ * A session's skills (track R2 M4) are mounted on its workspace, read-only, one folder per
+ * version (`/skills/<name>@<hash>/`, D66), before the first call that needs them (`skills.ts`);
+ * their bytes come through the `definitionFile` port.
  */
 import type { EventPayload } from "@nylorun/core/contracts";
-import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
+import { type AgentManifest, type SandboxManifest, 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";
+export { sandboxToolSpec } from "./runtime-tools.js";
 export type { SandboxRecord, SandboxRecords, SandboxState } from "./records.js";
 export interface SandboxSessionRef {
     /** The session whose log records the workspace's events: the owning session. */
@@ -35,6 +38,11 @@ export interface SandboxSessionRef {
      * so every session attached to it shares the files; absent, the workspace is the session's.
      */
     readonly environmentId?: string;
+    /**
+     * For a pod Environment: the host epoch it is at, so the call reaches a host that joined at
+     * that epoch or later, never one a restore or a lost volume retired.
+     */
+    readonly hostEpoch?: number;
     /** Variables every command of the call gets (R2c): secret names set to the sentinel, plain values. */
     readonly environment?: Readonly<Record<string, string>>;
     /**
@@ -111,13 +119,22 @@ export declare class SandboxManager {
     report(): Promise<SandboxSelectionReport & {
         readonly defaultImage: string;
     }>;
-    run(session: SandboxSessionRef, capability: CapabilityManifest, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    run(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    /**
+     * 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).
+     */
+    private inLane;
+    /** Runs `step` on `live` alone: after the calls running, before the calls that come after it. */
+    private alone;
+    /** The workspace's handle, opened once for the calls that need it at the same time. */
+    private handleOf;
     /**
      * 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.
      */
-    readBytes(session: SandboxSessionRef, capability: CapabilityManifest, path: string, maxBytes: number, signal: AbortSignal): Promise<{
+    readBytes(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, path: string, maxBytes: number, signal: AbortSignal): Promise<{
         kind: "read";
         path: string;
         bytes: Uint8Array;
@@ -132,7 +149,7 @@ export declare 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.
      */
-    listFiles(session: SandboxSessionRef, capability: CapabilityManifest, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
+    listFiles(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
         kind: "listed";
         path: string;
         listing: SandboxListing;
@@ -146,7 +163,7 @@ export declare class SandboxManager {
      * 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, {
+    disk(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, 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. */
@@ -156,9 +173,10 @@ export declare class SandboxManager {
     private execute;
     private executeOpen;
     /**
-     * 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.
      */
     private mountSkills;
     private open;

package/dist/sandbox/manager.js

@@ -2,11 +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;
@@ -44,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" });
         }
@@ -102,22 +99,72 @@ export class SandboxManager {
     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 {
@@ -147,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 {
@@ -172,8 +219,8 @@ export class SandboxManager {
      * 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) => {
+    async disk(session, sandbox, op, signal) {
+        return this.withHandle(session, sandbox, signal, async (handle, live) => {
             if (!handle.diskRoots)
                 return {
                     kind: "failed",
@@ -184,45 +231,35 @@ export class SandboxManager {
         });
     }
     /** 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)
@@ -234,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)
@@ -252,10 +289,11 @@ export class SandboxManager {
                 sessionId: session.id,
                 ...(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);
@@ -267,39 +305,31 @@ 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, "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}`,
-                };
-            }
+        let handle;
+        try {
+            handle = 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, live.handle, session, signal);
+        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, "environment.exec", {
@@ -313,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 {
@@ -325,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;
     }
@@ -421,8 +458,9 @@ export class SandboxManager {
     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;
@@ -455,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

@@ -19,7 +19,7 @@ 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";
+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. */

package/dist/sandbox/placement.js

@@ -21,7 +21,7 @@ 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";
+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";
@@ -53,7 +53,7 @@ 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 sandbox status\`.`, {
+        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" });

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

@@ -44,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;
@@ -52,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;

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

@@ -27,12 +27,20 @@
  *
  * - **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.
+ * - **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.
  *
  * An unused Environment is deleted by the Tenant sweep (`lifecycle.deleteAfter`), not here.
  */
 import type { EnvironmentEventPayload, EnvironmentEventType } from "@nylorun/core/contracts";
 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.
+ */
+export declare function imageDigestOf(imageID: string | undefined): 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. */

package/dist/sandbox/pods/lifecycle.js

@@ -1,3 +1,14 @@
+/**
+ * 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.
+ */
+export function imageDigestOf(imageID) {
+    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;
+}
 /** 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. */
@@ -137,6 +148,10 @@ export function decide(facts) {
                 patch.observed = "running";
                 patch.reason = null;
             }
+            // The image it runs, pinned by digest from now on (Q14).
+            const digest = pod.imageDigest === undefined ? imageDigestOf(status.imageID) : undefined;
+            if (digest !== undefined)
+                patch.imageDigest = digest;
             return done();
         }
         const startedAt = Date.parse(pod.startedAt ?? row.updatedAt);

package/dist/sandbox/pods/spec.js

@@ -36,7 +36,8 @@ export function storageGiBOf(spec) {
 export function podSpecOf(input) {
     const { spec, pod, config } = input;
     const lifecycle = podLifecycleConfig(config);
-    const image = spec.image;
+    // Pinned by digest once a pod ran it (Q14).
+    const image = pod.imageDigest ?? spec.image;
     const ours = (input.harness ?? DEFAULT_HARNESS) === DEFAULT_HARNESS;
     return {
         opId: opIdOf(pod),