@vantran-se/openchamber-web 2.1.1 → 2.2.0

package/server/lib/spaces/host.js

@@ -347,6 +347,8 @@ export function createSpacesHost({
       unsubscribeHostEvents = globalEventHub.subscribeEvent((event) => { if (event.spaceId === null) index.observeHostEvent(event.payload); });
       followTimer = setTimer(() => { void follow(); }, FOLLOW_INTERVAL_MS);
       followTimer?.unref?.();
+      // A running space whose gatekeeper lost its grants, from a start cut short, gets them again.
+      void journey.restoreLostGrants();
       return follow();
     },
     /** For the proxy: the merged session list, or the host's own when no space exists. */

package/server/lib/spaces/journey.js

@@ -382,6 +382,45 @@ export function createSpaceJourney({
     return { restored, needsAccess };
   };
 
+  /**
+   * The grants of every running space that its gatekeeper does not hold, said again from the
+   * record, at the host's start: a start the previous host did not live to finish leaves them
+   * unsaid, and the user would otherwise be asked for a key the record already names. Only what
+   * the host can say on its own goes: an environment key read now, and an opened domain; a typed
+   * key stays with the user. A space with an action under way is left to that action, and a
+   * gatekeeper that cannot be asked is left alone and logged. Nothing here fails the start.
+   */
+  const restoreLostGrants = async () => {
+    let spaces;
+    try {
+      spaces = await manager.listSpaces({ placeId: place.id });
+    } catch (error) {
+      logger.warn?.(`[spaces] could not list the spaces to say their grants again: ${error?.code ?? error?.message ?? error}`);
+      return;
+    }
+    for (const space of spaces) {
+      if (space.state !== 'running' || busy.has(space.id)) continue;
+      const grants = (records.read(space.id).record?.grants ?? []).filter((grant) => grant.kind !== 'model' || grant.source.kind === 'env');
+      if (grants.length === 0) continue;
+      let held;
+      try {
+        held = new Set((await gatekeeper.readPolicy(space.id)).grants);
+      } catch (error) {
+        logger.warn?.(`[spaces] the gatekeeper of space ${space.id} did not say what it holds: ${error?.code ?? error?.message ?? error}`);
+        continue;
+      }
+      const lost = grants.filter((grant) => !held.has(grant.id));
+      if (lost.length === 0) continue;
+      try {
+        const { restored } = await exclusive(space.id, () => restoreGrants(space.id, lost));
+        if (restored.length > 0) logger.info?.(`[spaces] said the grants ${restored.join(', ')} of space ${space.id} again`);
+      } catch (error) {
+        logger.warn?.(`[spaces] the grants of space ${space.id} were not said again: ${error?.code ?? error?.message ?? error}`);
+      }
+    }
+    onSpacesChanged();
+  };
+
   /**
    * Which grants of the record a running gatekeeper holds now, read from the gatekeeper itself:
    * after a machine restart it holds none, and the space "needs access" (DESIGN.md, Gatekeeper).
@@ -466,6 +505,11 @@ export function createSpaceJourney({
       const { record } = records.read(space.id);
       const grants = record?.grants ?? [];
       const projectPath = record?.repository ?? projectDirectory;
+      // A record without a space path is a creation that a previous host did not live to finish:
+      // the containers run, the code never arrived, and the user would otherwise send the agent
+      // into an empty folder. It is listed as a failed creation, whose one way out is Remove; a
+      // creation under way in this process is replaced by its own entry below.
+      const codeNeverArrived = record !== null && record.spacePath === null;
       return {
         id: space.id,
         name: space.name,
@@ -474,10 +518,10 @@ export function createSpaceJourney({
         directory: projectDirectory === null ? null : spaceProjectPath(space.id, projectDirectory),
         projectFolder: { path: projectPath, found: projectPath === null ? null : await folderExists(projectPath) },
         created: space.created,
-        state: space.state,
+        state: codeNeverArrived ? 'failed' : space.state,
         stoppedIdle: space.stoppedIdle === true,
-        step: null,
-        failure: null,
+        step: codeNeverArrived ? 'failed' : null,
+        failure: codeNeverArrived ? { code: 'space_code_never_arrived', message: 'OpenChamber closed before the code arrived. Delete the space and create it again.', details: null } : null,
         network: record?.network ?? null,
         history: record?.history ?? 'unknown',
         setup: setup.describe(space.id, record),
@@ -741,7 +785,9 @@ export function createSpaceJourney({
       return { id: spaceId, ...(await removeEverything(spaceId, waiting.projectDirectory)), chats: null };
     }
     const space = await requireListed(spaceId);
-    const chats = await saveChatsOf(space, allowUnsaved);
+    // A creation that a previous host did not live to finish is a failed creation too: no chat
+    // could have run in it, so nothing is saved and the archive is not asked.
+    const chats = space.state === 'failed' ? null : await saveChatsOf(space, allowUnsaved);
     const { record } = records.read(spaceId);
     const outcome = await removeEverything(spaceId, record?.repository ?? space.projectDirectory);
     onSpacesChanged();
@@ -829,6 +875,9 @@ export function createSpaceJourney({
     if (Array.from(pending.values()).some((entry) => entry.state === 'preparing')) {
       throw new SpaceError('space_preparing', 'A space is being made. Clean up when it is ready.');
     }
+    if (place.imagePulling()) {
+      throw new SpaceError('image_pulling', 'The image is being downloaded. Clean up when it is done.');
+    }
     const { freedBytes, kept, machine } = await place.cleanUpDisk();
     for (const item of kept.filter((entry) => entry.reason === 'failed')) {
       logger.warn?.(`[spaces] clean-up could not remove ${item.kind} ${item.name}: ${item.message}`);
@@ -838,6 +887,18 @@ export function createSpaceJourney({
     return { freedBytes, kept: kept.map(({ kind, reason }) => ({ kind, reason })), disk: await place.readDisk() };
   };
 
+  /**
+   * Downloads the base image on a place ahead of the first space (journey step 0), so no create
+   * dialog waits for it. The place runs one download at a time and a creation under way shares it.
+   * Answers the disk at once, `imagePulling` set; the page reads the disk again until it is not,
+   * and `imageFailure` says why the image is still absent after a download that failed.
+   */
+  const pullImage = async (placeId) => {
+    requirePlace(placeId);
+    place.pullImage().catch((error) => { logger.warn?.(`[spaces] the image download failed: ${error.code ?? error.message}`); });
+    return place.readDisk();
+  };
+
   /** For a turn-off that did not go through after the spaces were stopped: creations are taken again. */
   const reopen = () => { closing = false; };
 
@@ -899,5 +960,5 @@ export function createSpaceJourney({
     return { brought, applied, removal, kept };
   });
 
-  return { createSpace, listSpaces, startSpace, stopSpace, restartSpace, restartOpenCode, removeSpace, stopAllSpaces, reopen, grantAccess, openDomain, readJournal, previewApply, applySpace, readIdleStopSetting, changeIdleStop, runSetup, readSetup, readDisk, cleanUpDisk };
+  return { createSpace, listSpaces, startSpace, stopSpace, restartSpace, restartOpenCode, removeSpace, stopAllSpaces, reopen, grantAccess, openDomain, restoreLostGrants, readJournal, previewApply, applySpace, readIdleStopSetting, changeIdleStop, runSetup, readSetup, readDisk, cleanUpDisk, pullImage };
 }

package/server/lib/spaces/journey.test.js

@@ -198,10 +198,26 @@ describe('the journey: create', () => {
 
 describe('the journey: disk and clean-up', () => {
   const DISK = { imageBytes: 1_632_000_000, toolsBytes: 438_000_000, spacesBytes: 0, freeBytes: 1_632_000_000, freesImage: true };
-  const placeWithDisk = (cleaned) => ({
+  const placeWithDisk = (cleaned, pull = { pulling: false, pulls: 0, fail: null }) => ({
     ...createMemoryPlace(),
-    readDisk: async () => DISK,
+    readDisk: async () => ({ ...DISK, imagePulling: pull.pulling }),
     cleanUpDisk: async () => { cleaned.count += 1; return cleaned.outcome; },
+    pullImage: async () => { pull.pulls += 1; if (pull.fail) throw pull.fail; },
+    imagePulling: () => pull.pulling,
+  });
+
+  it('starts the image download and answers the disk at once; a clean-up waits for the download; a failed download is logged, not thrown', async () => {
+    const warnings = [];
+    const cleaned = { count: 0, outcome: { freedBytes: 0, kept: [], machine: { state: 'skipped' } } };
+    const pull = { pulling: true, pulls: 0, fail: new SpaceError('image_pull_failed', 'Could not download the base image: no route to host.') };
+    const { journey } = journeyWith({ place: placeWithDisk(cleaned, pull), logger: { warn: (line) => warnings.push(line) } });
+    expect(await journey.pullImage('memory')).toEqual({ ...DISK, imagePulling: true });
+    expect(pull.pulls).toBe(1);
+    await expect(journey.pullImage('kubernetes')).rejects.toMatchObject({ code: 'place_not_found' });
+    await expect(journey.cleanUpDisk('memory')).rejects.toMatchObject({ code: 'image_pulling' });
+    expect(cleaned.count).toBe(0);
+    await new Promise((resolve) => { setTimeout(resolve, 0); });
+    expect(warnings).toEqual(['[spaces] the image download failed: image_pull_failed']);
   });
 
   it('answers what was freed and the disk after, keeps Docker\'s words out of the answer and logs them', async () => {
@@ -215,8 +231,8 @@ describe('the journey: disk and clean-up', () => {
       },
     };
     const { journey } = journeyWith({ place: placeWithDisk(cleaned), logger: { warn: (line) => warnings.push(line) } });
-    expect(await journey.readDisk('memory')).toEqual(DISK);
-    expect(await journey.cleanUpDisk('memory')).toEqual({ freedBytes: 440_000_000, kept: [{ kind: 'image', reason: 'in_use' }, { kind: 'tools', reason: 'failed' }], disk: DISK });
+    expect(await journey.readDisk('memory')).toEqual({ ...DISK, imagePulling: false });
+    expect(await journey.cleanUpDisk('memory')).toEqual({ freedBytes: 440_000_000, kept: [{ kind: 'image', reason: 'in_use' }, { kind: 'tools', reason: 'failed' }], disk: { ...DISK, imagePulling: false } });
     expect(warnings).toEqual([
       '[spaces] clean-up could not remove tools openchamber-tools-x: disk on fire',
       '[spaces] the Colima machine did not trim its disk: sudo: a password is required',
@@ -283,6 +299,17 @@ describe('the journey: start, stop, remove', () => {
     expect(calls.map(([name]) => name)).toEqual(['setNetwork']);
   });
 
+  it('lists a space whose code never arrived as a failed creation, which Remove takes away', async () => {
+    // A host that quit in the middle of bringing the code in leaves the containers running and
+    // the record without a space path. The next host must not list that as a healthy space.
+    const { journey, records, place, id } = await ready();
+    records.update(id, { spacePath: null, base: null });
+    expect((await journey.listSpaces())[0]).toMatchObject({ id, state: 'failed', step: 'failed', failure: { code: 'space_code_never_arrived', message: expect.stringContaining('closed before the code arrived'), details: null } });
+    expect(await journey.removeSpace(id)).toMatchObject({ id, removed: true, refsRemoved: true, failures: [] });
+    expect(await place.list()).toEqual([]);
+    expect(records.read(id)).toEqual({ status: 'missing', record: null });
+  });
+
   it('removes the space, the refs in the user\'s repository and the record', async () => {
     const { journey, place, records, calls, id } = await ready();
     expect(await journey.removeSpace(id)).toEqual({ id, removed: true, refsRemoved: true, failures: [], chats: null });
@@ -688,6 +715,62 @@ describe('the journey: grants', () => {
     expect((await refusing.journey.listSpaces({ access: true }))[0]).toMatchObject({ access: 'needs_access', needsAccess: ['openai'] });
   });
 
+  it('says the grants a running gatekeeper lost again when the host starts: an environment key and a domain, never a typed key', async () => {
+    const { journey, calls, gatekeeper, id, changes } = await ready({ hostEnvironment: { OPENAI_API_KEY: ENV_KEY } });
+    await journey.grantAccess(id, anthropic);
+    await journey.grantAccess(id, openai);
+    const opened = await journey.grantAccess(id, registry);
+    // The gatekeeper lost everything, as after a start the previous host did not live to finish; the space runs on.
+    gatekeeper.forget(id);
+    expect((await journey.listSpaces({ access: true }))[0]).toMatchObject({ access: 'needs_access', needsAccess: ['anthropic', 'openai', opened.grant.id] });
+    calls.splice(0);
+    const before = changes.count;
+
+    await journey.restoreLostGrants();
+    expect(calls.filter(([name]) => name === 'addGrant')).toEqual([
+      ['addGrant', id, { id: 'openai', upstream: 'https://api.openai.com/v1', header: 'authorization', secret: ENV_KEY }],
+      ['addGrant', id, { id: opened.grant.id, upstream: 'https://registry.example.com/npm/', header: null, secret: null }],
+    ]);
+    expect(JSON.stringify(calls)).not.toContain(KEY);
+    expect(changes.count).toBe(before + 1);
+    // Only the typed key still needs the user.
+    expect((await journey.listSpaces({ access: true }))[0]).toMatchObject({ access: 'needs_access', needsAccess: ['anthropic'] });
+
+    // A gatekeeper that holds its grants is asked and told nothing.
+    calls.splice(0);
+    await journey.restoreLostGrants();
+    expect(calls.map(([name]) => name)).toEqual(['readPolicy']);
+  });
+
+  it('leaves a stopped space, a space without grants and a gatekeeper that does not answer alone when the host starts', async () => {
+    const { journey, calls, gatekeeper, id, manager, place } = await ready({ hostEnvironment: { OPENAI_API_KEY: ENV_KEY } });
+    await journey.grantAccess(id, openai);
+    const empty = await manager.createSpace({ placeId: 'memory', projectDirectory: PROJECT, name: 'No grants' });
+    gatekeeper.forget(id);
+    gatekeeper.readPolicy = async () => { throw new SpaceError('gatekeeper_unreachable', 'the gatekeeper did not answer'); };
+    calls.splice(0);
+    await journey.restoreLostGrants();
+    expect(calls.filter(([name]) => name === 'addGrant')).toEqual([]);
+
+    await place.stop(id);
+    await place.stop(empty.id);
+    calls.splice(0);
+    await journey.restoreLostGrants();
+    expect(calls).toEqual([]);
+  });
+
+  it('leaves a space with an action under way to that action when the host starts', async () => {
+    const { journey, calls, gatekeeper, id, releaseCodeOut } = await ready({ hostEnvironment: { OPENAI_API_KEY: ENV_KEY }, holdCodeOut: true });
+    await journey.grantAccess(id, openai);
+    gatekeeper.forget(id);
+    const preview = journey.previewApply(id);
+    calls.splice(0);
+    await journey.restoreLostGrants();
+    expect(calls.filter(([name]) => name === 'readPolicy' || name === 'addGrant')).toEqual([]);
+    releaseCodeOut();
+    await preview;
+  });
+
   it('asks the gatekeeper only where there is something to ask, and never calls a failed read "granted"', async () => {
     const { journey, calls, id, manager, place } = await ready();
     const empty = await manager.createSpace({ placeId: 'memory', projectDirectory: PROJECT, name: 'No grants' });
@@ -1108,6 +1191,14 @@ describe('the journey: the chat archive of a deleted space', () => {
   };
   const notSaved = () => new SpaceError('chats_not_saved', 'The chats of "Fix login" could not be saved.', { name: 'Fix login', tooLarge: ['Big one'], failed: 0, listed: true });
 
+  it('does not ask the archive for a space whose code never arrived, and removes it', async () => {
+    const { journey, place, records, asked, id } = await ready();
+    records.update(id, { spacePath: null, base: null });
+    expect(await journey.removeSpace(id)).toMatchObject({ id, removed: true, refsRemoved: true, failures: [], chats: null });
+    expect(asked).toEqual([]);
+    expect(await place.list()).toEqual([]);
+  });
+
   it('saves the chats of a running space before it goes, and says how many', async () => {
     const { journey, place, asked, calls, id } = await ready();
     const outcome = await journey.removeSpace(id);

package/server/lib/spaces/layout.js

@@ -142,7 +142,7 @@ export const SPACE_ENVIRONMENT = Object.freeze({
   // NODE_USE_ENV_PROXY=1 proxies loopback too. Both spellings, because curl reads both.
   NO_PROXY: `${GATEKEEPER_ALIAS},localhost,127.0.0.1`,
   no_proxy: `${GATEKEEPER_ALIAS},localhost,127.0.0.1`,
-  // Node 22 ignores proxy variables without this. Measured: EAI_AGAIN for every fetch.
+  // Node ignores proxy variables without this. Measured on 22 and 24: EAI_AGAIN for every fetch.
   NODE_USE_ENV_PROXY: '1',
   // OpenCode's catalog and update downloads would only spend corridor attempts.
   OPENCODE_DISABLE_MODELS_FETCH: '1',

package/server/lib/spaces/places/docker-disk.js

@@ -1,6 +1,7 @@
 // The disk that spaces take on the Docker place, and the clean-up of what OpenChamber can make
 // again by itself (DESIGN.md, journey step 9 and decision 12): this owner's tools volumes but the
-// current one, this owner's leftover one-shot containers, and the space image.
+// current one, this owner's leftover one-shot containers, the space image, and the space images
+// of before.
 //
 // Nothing here decides whether a resource is still needed. Every removal goes without force, and
 // Docker refuses a volume a container mounts, an image a container was made from, and a running
@@ -35,10 +36,11 @@ const parseJson = (text) => {
 
 /**
  * `engine` is the place's docker CLI, `tools` its tools volume with `listOurs`, `image` the pinned
- * space image. `colimaPath` is the colima CLI, or null: after a clean-up that removed anything, a
- * Docker machine that calls itself Colima is asked to hand the freed blocks back to the Mac.
+ * space image and `retiredImages` the digests it replaced. `colimaPath` is the colima CLI, or null:
+ * after a clean-up that removed anything, a Docker machine that calls itself Colima is asked to
+ * hand the freed blocks back to the Mac.
  */
-export function createDockerDisk({ engine, runCommand, colimaPath, owner, image, tools }) {
+export function createDockerDisk({ engine, runCommand, colimaPath, owner, image, retiredImages = [], tools, imagePullState = () => ({ pulling: false, failure: null }) }) {
   /**
    * Docker's own account of the disk: every volume with its size and how many containers mount it,
    * by name, and what each image alone takes, by id. `docker image inspect` is no use for the
@@ -62,14 +64,24 @@ export function createDockerDisk({ engine, runCommand, colimaPath, owner, image,
     .map((entry) => String(entry.Name));
 
   /**
-   * The image with what it alone takes, or null when it is not there. In use when any container
+   * An image with what it alone takes, or null when it is not there. In use when any container
    * was made from it.
    */
-  const readImage = async (images) => {
-    const entry = await engine.inspect('image', image);
+  const readImage = async (name, images) => {
+    const entry = await engine.inspect('image', name);
     if (!entry) return null;
-    const users = await engine.docker(['ps', '--all', '--filter', `ancestor=${image}`, '--format', '{{.Names}}'], QUERY_TIMEOUT_MS);
-    return { bytes: images.get(String(entry.Id)) ?? 0, inUse: users.trim() !== '' };
+    const users = await engine.docker(['ps', '--all', '--filter', `ancestor=${name}`, '--format', '{{.Names}}'], QUERY_TIMEOUT_MS);
+    return { name, bytes: images.get(String(entry.Id)) ?? 0, inUse: users.trim() !== '', tags: entry.RepoTags ?? [] };
+  };
+
+  /**
+   * The retired images that are there and carry no tag but their own digest reference. A space
+   * pulls by digest, so another tag means someone pulled or tagged the same image for their own
+   * use, and a removal by digest would take their tag with it. Those stay.
+   */
+  const readRetiredImages = async (images) => {
+    const found = await Promise.all(retiredImages.map((name) => readImage(name, images)));
+    return found.filter((state) => state !== null && state.tags.every((tag) => tag === state.name));
   };
 
   const measure = async () => {
@@ -77,23 +89,30 @@ export function createDockerDisk({ engine, runCommand, colimaPath, owner, image,
     const { volumes } = usage;
     const sizeOf = (name) => volumes.get(name)?.bytes ?? 0;
     const oldTools = ours.volumes.filter((name) => name !== ours.current);
-    return { volumes, ours, oldTools, spaces, image: await readImage(usage.images), sizeOf };
+    const [imageState, retired] = await Promise.all([readImage(image, usage.images), readRetiredImages(usage.images)]);
+    return { volumes, ours, oldTools, spaces, image: imageState, retired, sizeOf };
   };
 
   /**
    * What the page shows: the image, the tools and the spaces' own volumes in bytes, and what a
-   * clean-up would free now. `freesImage` says whether the image is part of that.
+   * clean-up would free now. `freesImage` says whether the current image is part of that. A
+   * retired image is counted only in what a clean-up frees.
    */
   const read = async () => {
-    const { volumes, ours, oldTools, spaces, image: imageState, sizeOf } = await measure();
+    const { volumes, ours, oldTools, spaces, image: imageState, retired, sizeOf } = await measure();
     const freeTools = oldTools.filter((name) => (volumes.get(name)?.links ?? 0) === 0);
     const freesImage = imageState !== null && !imageState.inUse;
+    const freeRetired = retired.filter((state) => !state.inUse).reduce((total, state) => total + state.bytes, 0);
     const sum = (names) => names.reduce((total, name) => total + sizeOf(name), 0);
+    const pull = imagePullState();
     return {
       imageBytes: imageState?.bytes ?? null,
+      // A download under way on this host, and how the last one ended while the image is absent.
+      imagePulling: pull.pulling,
+      imageFailure: imageState === null && !pull.pulling ? pull.failure : null,
       toolsBytes: sum(ours.volumes),
       spacesBytes: sum(spaces),
-      freeBytes: sum(freeTools) + (freesImage ? imageState.bytes : 0),
+      freeBytes: sum(freeTools) + (freesImage ? imageState.bytes : 0) + freeRetired,
       freesImage,
     };
   };
@@ -121,7 +140,7 @@ export function createDockerDisk({ engine, runCommand, colimaPath, owner, image,
    * `freedBytes` counts the sizes measured just before, of what is gone afterwards.
    */
   const cleanUp = async () => {
-    const { oldTools, ours, image: imageState, sizeOf } = await measure();
+    const { oldTools, ours, image: imageState, retired, sizeOf } = await measure();
     let freedBytes = 0;
     const kept = [];
     const attempt = async (kind, name, bytes, removal) => {
@@ -144,6 +163,11 @@ export function createDockerDisk({ engine, runCommand, colimaPath, owner, image,
     if (imageState) {
       removedAny = (await attempt('image', image, imageState.bytes, engine.removeOne('image', image))) || removedAny;
     }
+    // A retired image stays while a container made from it exists: the gatekeeper of a space
+    // created before the bump keeps its image until the space is removed.
+    for (const state of retired) {
+      removedAny = (await attempt('image', state.name, state.bytes, engine.removeOne('image', state.name))) || removedAny;
+    }
     return { freedBytes, kept, machine: removedAny ? await trimMachine() : { state: 'skipped' } };
   };
 

package/server/lib/spaces/places/docker-disk.test.js

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { buildSpaceLabels, buildToolsLabels, hashProjectDirectory } from '../labels.js';
 import { createRegistryToolsSource, toolsContentKey } from '../tools.js';
 import { parseDockerSize } from './docker-disk.js';
-import { SPACE_BASE_IMAGE, createDockerPlace } from './docker.js';
+import { RETIRED_SPACE_BASE_IMAGES, SPACE_BASE_IMAGE, createDockerPlace } from './docker.js';
 import { createFakeDocker, hardenedContainerEntry } from './fake-docker.js';
 
 const OWNER = 'install-a';
@@ -74,6 +74,8 @@ describe('the disk of the Docker place', () => {
     });
     expect(await makePlace(fake).readDisk()).toEqual({
       imageBytes: 1_632_000_000,
+      imagePulling: false,
+      imageFailure: null,
       toolsBytes: 438_000_000 + 440_000_000 + 441_000_000,
       spacesBytes: 1_500_000_000,
       // The old tools nothing mounts; the image and the tools the stopped space holds are in use.
@@ -89,6 +91,34 @@ describe('the disk of the Docker place', () => {
     expect(await makePlace(without).readDisk()).toMatchObject({ imageBytes: null, freeBytes: 0, freesImage: false });
   });
 
+  it('downloads the image once for everyone who asks, says so on the disk, and remembers a failed download while the image is absent', async () => {
+    const fake = createFakeDocker({ imagePresent: false, resources: [toolsVolume(OWNER, KEY)] });
+    let release = null;
+    let pulls = 0;
+    const runCommand = (file, args, options) => {
+      if (args[0] !== 'pull') return fake.runCommand(file, args, options);
+      pulls += 1;
+      return new Promise((resolve) => { release = resolve; });
+    };
+    const place = makePlace(fake, { runCommand });
+    const first = place.pullImage();
+    const second = place.pullImage();
+    expect(second).toBe(first);
+    expect(place.imagePulling()).toBe(true);
+    expect(await place.readDisk()).toMatchObject({ imageBytes: null, imagePulling: true, imageFailure: null });
+    release({ code: 1, stdout: '', stderr: 'no route to host\n' });
+    await expect(first).rejects.toMatchObject({ code: 'image_pull_failed' });
+    expect(pulls).toBe(1);
+    expect(place.imagePulling()).toBe(false);
+    expect(await place.readDisk()).toMatchObject({ imagePulling: false, imageFailure: { code: 'image_pull_failed', message: expect.stringContaining('no route to host') } });
+    // The next download is a fresh one, and its success clears the failure.
+    const third = place.pullImage();
+    release({ code: 0, stdout: '', stderr: '' });
+    await third;
+    expect(pulls).toBe(2);
+    expect(await place.readDisk()).toMatchObject({ imagePulling: false, imageFailure: null });
+  });
+
   it('a failed read rejects rather than answering an empty disk', async () => {
     const fake = createFakeDocker({ failAt: (args) => args[0] === 'system' });
     await expect(makePlace(fake).readDisk()).rejects.toMatchObject({ code: 'docker_command_failed' });
@@ -142,6 +172,55 @@ describe('clean-up of the Docker place', () => {
     expect(fake.imagePresent()).toBe(true);
   });
 
+  describe('a retired space image', () => {
+    const RETIRED = RETIRED_SPACE_BASE_IMAGES[0];
+    const RETIRED_BYTES = 1_600_000_000;
+    // The gatekeeper of a space created before the bump, still on the image it was made from.
+    const oldGatekeeper = { kind: 'container', name: `openchamber-space-${ID}-gatekeeper`, entry: hardenedContainerEntry({ name: `openchamber-space-${ID}-gatekeeper`, labels: spaceLabels('gatekeeper'), network: `openchamber-space-${ID}-network`, mounts: [], running: false, image: RETIRED }) };
+
+    it('is counted in what a clean-up frees and nowhere else, and removed without force', async () => {
+      const fake = createFakeDocker({ imagePresent: false, retiredImages: [{ name: RETIRED, bytes: RETIRED_BYTES }], resources: [toolsVolume(OWNER, KEY)] });
+      const place = makePlace(fake);
+      expect(await place.readDisk()).toEqual({ imageBytes: null, imagePulling: false, imageFailure: null, toolsBytes: 0, spacesBytes: 0, freeBytes: RETIRED_BYTES, freesImage: false });
+      expect(await place.cleanUpDisk()).toEqual({ freedBytes: RETIRED_BYTES, kept: [], machine: { state: 'skipped' } });
+      expect(fake.retiredImagePresent(RETIRED)).toBe(false);
+      expect(removals(fake).some((args) => args.includes('--force'))).toBe(false);
+    });
+
+    it('stays while a container made from it exists, and goes once that container is gone', async () => {
+      const fake = createFakeDocker({ imagePresent: false, retiredImages: [{ name: RETIRED, bytes: RETIRED_BYTES }], resources: [toolsVolume(OWNER, KEY), oldGatekeeper] });
+      const place = makePlace(fake);
+      expect((await place.readDisk()).freeBytes).toBe(0);
+      const outcome = await place.cleanUpDisk();
+      expect(outcome.freedBytes).toBe(0);
+      expect(outcome.kept).toEqual([expect.objectContaining({ kind: 'image', name: RETIRED, reason: 'in_use' })]);
+      expect(fake.retiredImagePresent(RETIRED)).toBe(true);
+
+      // The old space is deleted, which takes its gatekeeper with it.
+      expect((await fake.runCommand('/usr/bin/docker', ['rm', oldGatekeeper.name], {})).code).toBe(0);
+      expect((await place.readDisk()).freeBytes).toBe(RETIRED_BYTES);
+      expect((await place.cleanUpDisk()).freedBytes).toBe(RETIRED_BYTES);
+      expect(fake.retiredImagePresent(RETIRED)).toBe(false);
+    });
+
+    it('is left alone, uncounted and never asked to go, when it carries a tag of its own', async () => {
+      const fake = createFakeDocker({ imagePresent: false, retiredImages: [{ name: RETIRED, bytes: RETIRED_BYTES, tags: [RETIRED, 'node:22-bookworm'] }], resources: [toolsVolume(OWNER, KEY)] });
+      const place = makePlace(fake);
+      expect((await place.readDisk()).freeBytes).toBe(0);
+      expect(await place.cleanUpDisk()).toEqual({ freedBytes: 0, kept: [], machine: { state: 'skipped' } });
+      expect(fake.retiredImagePresent(RETIRED)).toBe(true);
+      expect(removals(fake)).toEqual([]);
+    });
+
+    it('is counted as gone when it is not there', async () => {
+      const fake = createFakeDocker({ imagePresent: false, resources: [toolsVolume(OWNER, KEY)] });
+      const place = makePlace(fake);
+      expect((await place.readDisk()).freeBytes).toBe(0);
+      expect(await place.cleanUpDisk()).toEqual({ freedBytes: 0, kept: [], machine: { state: 'skipped' } });
+      expect(removals(fake)).toEqual([]);
+    });
+  });
+
   it('on Colima asks the machine to trim its disks after something went, and on any other engine does not', async () => {
     const colimaCalls = [];
     const fake = createFakeDocker({

package/server/lib/spaces/places/docker.js

@@ -36,8 +36,11 @@ import { createDockerTools } from './docker-tools.js';
 
 const DOCKER_PLACE_ID = 'docker';
 
-// node:22-bookworm as a multi-arch index digest. DOCUMENTATION.md says how it was verified.
-export const SPACE_BASE_IMAGE = 'node@sha256:dd5847a04b0deee391fa145f1f4c6d214196668b6bcc7988ebed67249f226844';
+// node:24-bookworm as a multi-arch index digest. DOCUMENTATION.md says how it was verified.
+export const SPACE_BASE_IMAGE = 'node@sha256:3d27e5c11e5786e309ec3e03f93ae536eb36e6e5eb3714d5eb3300a36157add0';
+// Base images spaces used before, which the clean-up removes like the current one. A bump adds
+// the digest it replaces here. node:22-bookworm, replaced on 2026-10-08.
+export const RETIRED_SPACE_BASE_IMAGES = ['node@sha256:dd5847a04b0deee391fa145f1f4c6d214196668b6bcc7988ebed67249f226844'];
 
 const CHECK_TIMEOUT_MS = 10_000;
 const PULL_TIMEOUT_MS = 20 * 60_000;
@@ -67,7 +70,12 @@ export function createDockerPlace({ runCommand, openCommandStream = openCommandS
   const engine = createDockerEngine({ runCommand, dockerPath });
   const { run, docker, inspect, removeOne, removeStoppedContainer } = engine;
   const tools = createDockerTools({ engine, owner, toolsSource, image: SPACE_BASE_IMAGE, now, wait });
-  const disk = createDockerDisk({ engine, runCommand, colimaPath, owner, image: SPACE_BASE_IMAGE, tools });
+  // The one download of the image under way, shared by a creation that needs it and the places
+  // page's button, and how the last one ended, so the page can say why the image is still absent.
+  let imagePull = null;
+  let imagePullFailure = null;
+  const imagePullState = () => ({ pulling: imagePull !== null, failure: imagePullFailure });
+  const disk = createDockerDisk({ engine, runCommand, colimaPath, owner, image: SPACE_BASE_IMAGE, retiredImages: RETIRED_SPACE_BASE_IMAGES, tools, imagePullState });
 
   /** Every resource that carries our marker and this owner, optionally for one space. Found by label only. */
   const findResources = async (spaceId) => {
@@ -159,18 +167,34 @@ export function createDockerPlace({ runCommand, openCommandStream = openCommandS
     };
   };
 
+  /** Downloads the image once; a second call while one runs waits on the same pull. */
+  const pullImage = () => {
+    if (imagePull === null) {
+      imagePull = run(['pull', SPACE_BASE_IMAGE], PULL_TIMEOUT_MS)
+        .then((result) => {
+          if (result.code !== 0) {
+            throw new SpaceError(
+              'image_pull_failed',
+              `Could not download the base image: ${result.stderr.trim() || `exit code ${result.code}`}. Common causes: no internet access on the Docker machine, or Docker's credential helper cannot run in this session.`,
+            );
+          }
+          imagePullFailure = null;
+        })
+        .catch((error) => {
+          imagePullFailure = { code: error.code ?? 'image_pull_failed', message: error.message };
+          throw error;
+        })
+        .finally(() => { imagePull = null; });
+    }
+    return imagePull;
+  };
+
   const ensureImage = async () => {
     const present = await inspect('image', SPACE_BASE_IMAGE);
     if (present) {
       return;
     }
-    const result = await run(['pull', SPACE_BASE_IMAGE], PULL_TIMEOUT_MS);
-    if (result.code !== 0) {
-      throw new SpaceError(
-        'image_pull_failed',
-        `Could not download the base image: ${result.stderr.trim() || `exit code ${result.code}`}. Common causes: no internet access on the Docker machine, or Docker's credential helper cannot run in this session.`,
-      );
-    }
+    await pullImage();
   };
 
   const verifyContainer = async (spaceId, container) => {
@@ -624,5 +648,5 @@ export function createDockerPlace({ runCommand, openCommandStream = openCommandS
     return starting.get(spaceId);
   };
 
-  return { id: DOCKER_PLACE_ID, check, create, list, exec, execArgv, connect, stop, start, remove, verify, readDisk: disk.read, cleanUpDisk: disk.cleanUp };
+  return { id: DOCKER_PLACE_ID, check, create, list, exec, execArgv, connect, stop, start, remove, verify, readDisk: disk.read, cleanUpDisk: disk.cleanUp, pullImage, imagePulling: () => imagePull !== null };
 }

package/server/lib/spaces/places/fake-docker.js

@@ -160,7 +160,9 @@ const readMounts = (args) => args
  * `start` is where the clock of `now()` begins. `wait(ms)` moves that clock, so nothing here sleeps.
  * `beforeFill()` runs before a tools fill ends, so a test can hold it open.
  * For the disk: `volumeSizes` maps a volume name to its size as `docker system df` prints it,
- * `imageBytes` is the size of the space image, `engineName` what `docker info` calls the machine,
+ * `imageBytes` is the size of the space image, `retiredImages` other images that are there as
+ * `{ name, bytes, tags }`, where `tags` defaults to the digest reference alone, as a pull by digest
+ * leaves it on the containerd image store, `engineName` what `docker info` calls the machine,
  * and `colima(args)` answers a call of the colima CLI, any file whose name ends in `colima`.
  */
 export function createFakeDocker({
@@ -170,6 +172,7 @@ export function createFakeDocker({
   resources = [],
   imagePresent = true,
   imageBytes = 1_632_000_000,
+  retiredImages = [],
   volumeSizes = {},
   engineName = 'docker-desktop',
   colima = () => ok(),
@@ -181,6 +184,7 @@ export function createFakeDocker({
 } = {}) {
   let clock = start.getTime();
   let image = imagePresent;
+  const retired = new Map(retiredImages.map((entry, index) => [entry.name, { id: `sha256:4567${index}`, bytes: entry.bytes, tags: entry.tags ?? [entry.name] }]));
   const calls = [];
   const late = [];
   const state = new Map(resources.map((resource) => [`${resource.kind}:${resource.name}`, resource]));
@@ -298,7 +302,18 @@ export function createFakeDocker({
     if (fails) return failed('Error response from daemon: simulated failure');
     if (first === 'inspect') return inspect('container', args.slice(3));
     // The size here is the compressed download, as the containerd image store reports it; the place must not use it.
-    if (first === 'image' && second === 'inspect') return image ? ok(JSON.stringify([{ Id: 'sha256:0123', Size: Math.round(imageBytes / 4) }])) : failed(NOT_FOUND_TEXT.image(args[2]), '[]');
+    if (first === 'image' && second === 'inspect') {
+      const old = retired.get(args[2]);
+      if (old) return ok(JSON.stringify([{ Id: old.id, Size: Math.round(old.bytes / 4), RepoTags: old.tags }]));
+      return image && args[2] === FAKE_BASE_IMAGE ? ok(JSON.stringify([{ Id: 'sha256:0123', Size: Math.round(imageBytes / 4), RepoTags: [FAKE_BASE_IMAGE] }])) : failed(NOT_FOUND_TEXT.image(args[2]), '[]');
+    }
+    if (first === 'image' && second === 'rm' && retired.has(args[args.length - 1])) {
+      const name = args[args.length - 1];
+      const user = ofKind('container').find((resource) => resource.entry.Config?.Image === name);
+      if (user && !args.includes('--force')) return failed(`Error response from daemon: conflict: unable to delete ${retired.get(name).id} (must be forced) - image is being used by stopped container ${user.entry.Id}`);
+      retired.delete(name);
+      return ok(`Deleted: ${name}`);
+    }
     if (first === 'image' && second === 'rm') {
       if (!image || args[args.length - 1] !== FAKE_BASE_IMAGE) return failed(NOT_FOUND_TEXT.image(args[args.length - 1]));
       // Like the real engine: without --force an image that any container was made from stays.
@@ -311,7 +326,10 @@ export function createFakeDocker({
       const mountedBy = (name) => ofKind('container').filter((resource) => resource.entry.Mounts.some((mount) => mount.Name === name)).length;
       return ok(JSON.stringify({
         // Like the containerd image store: the id is the digest, and the size is what the image alone takes unpacked.
-        Images: image ? [{ ID: 'sha256:0123', Size: `${imageBytes / 1e9}GB`, UniqueSize: `${imageBytes / 1e9}GB` }] : [],
+        Images: [
+          ...(image ? [{ ID: 'sha256:0123', Size: `${imageBytes / 1e9}GB`, UniqueSize: `${imageBytes / 1e9}GB` }] : []),
+          ...Array.from(retired.values(), (old) => ({ ID: old.id, Size: `${old.bytes / 1e9}GB`, UniqueSize: `${old.bytes / 1e9}GB` })),
+        ],
         Volumes: ofKind('volume').map((resource) => ({ Name: resource.name, Size: volumeSizes[resource.name] ?? '0B', Links: String(mountedBy(resource.name)) })),
       }));
     }
@@ -406,6 +424,7 @@ export function createFakeDocker({
     calls,
     names: () => Array.from(state.keys()),
     imagePresent: () => image,
+    retiredImagePresent: (name) => retired.has(name),
     token: (container) => tokens.get(homeOf(container)),
   };
 }

package/server/lib/spaces/places/memory-place.js

@@ -50,6 +50,9 @@ export function createMemoryPlace({ id = 'memory' } = {}) {
   return {
     id,
     check: async () => ({ available: true, version: 'memory', os: 'none', arch: 'none', hostIsolation: true }),
+    // Memory has no image to download: a pull ends at once and none is ever under way.
+    pullImage: async () => {},
+    imagePulling: () => false,
     create: async ({ id: spaceId, name, project, created }) => {
       if (spaces.has(requireSpaceId(spaceId))) {
         throw new SpaceError('space_name_taken', `Space ${spaceId} already exists`);