@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/spaces/manager.js

@@ -0,0 +1,82 @@
+import { SpaceError } from './errors.js';
+import { createSpaceId, hashProjectDirectory, normalizeSpaceName } from './labels.js';
+
+// Memory limit of a new space. Swap adds nothing on top of it.
+const DEFAULT_SPACE_MEMORY_BYTES = 4 * 1024 * 1024 * 1024;
+
+/**
+ * Thin orchestration over places. It keeps no record of spaces: every answer
+ * comes from the place at the time of the call.
+ */
+export function createSpaceManager({ registry, now = () => new Date() }) {
+  const requirePlace = (placeId) => {
+    const place = registry.get(placeId);
+    if (!place) {
+      throw new SpaceError('place_not_found', `There is no place named '${placeId}'. Pick a configured place.`);
+    }
+    return place;
+  };
+
+  const removeSpace = async ({ placeId, spaceId }) => {
+    const result = await requirePlace(placeId).remove(spaceId);
+    if (result.failed.length > 0) {
+      throw new SpaceError(
+        'space_remove_incomplete',
+        `Could not remove: ${result.failed.map((item) => `${item.kind} ${item.name}`).join(', ')}`,
+        result,
+      );
+    }
+    return result;
+  };
+
+  const createSpace = async ({ placeId, projectDirectory, name }) => {
+    const place = requirePlace(placeId);
+    const spec = {
+      id: createSpaceId(),
+      name: normalizeSpaceName(name),
+      project: hashProjectDirectory(projectDirectory),
+      created: now().toISOString(),
+      memoryBytes: DEFAULT_SPACE_MEMORY_BYTES,
+    };
+    await place.create(spec);
+
+    // A space that cannot be verified is never handed out. It is removed instead.
+    const discard = async () => {
+      try {
+        return await place.remove(spec.id);
+      } catch (error) {
+        return { removed: [], failed: [{ kind: 'space', name: spec.id, message: error.message }] };
+      }
+    };
+
+    let violations;
+    try {
+      violations = await place.verify(spec.id);
+    } catch (error) {
+      const removal = await discard();
+      const wrapped = new SpaceError(error.code ?? 'space_verification_failed', `The space was removed because it could not be verified. ${error.message}`, { removal });
+      wrapped.cause = error;
+      throw wrapped;
+    }
+    if (violations.length > 0) {
+      const removal = await discard();
+      throw new SpaceError(
+        'space_verification_failed',
+        `The space was removed because it does not match the requested restrictions: ${violations.map((violation) => violation.message).join('; ')}`,
+        { violations, removal },
+      );
+    }
+    return { placeId: place.id, ...spec };
+  };
+
+  const listSpaces = async ({ placeId }) => {
+    const place = requirePlace(placeId);
+    return (await place.list()).map((space) => ({ placeId: place.id, ...space }));
+  };
+
+  const stopSpace = async ({ placeId, spaceId }) => requirePlace(placeId).stop(spaceId);
+
+  const startSpace = async ({ placeId, spaceId }) => requirePlace(placeId).start(spaceId);
+
+  return { createSpace, listSpaces, stopSpace, startSpace, removeSpace };
+}

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

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+
+import { SpaceError } from './errors.js';
+import { hashProjectDirectory } from './labels.js';
+import { createSpaceManager } from './manager.js';
+import { createMemoryPlace } from './places/memory-place.js';
+import { createPlaceRegistry } from './places/registry.js';
+
+const NOW = new Date('2026-09-19T10:00:00.000Z');
+const REQUEST = { placeId: 'memory', projectDirectory: '/home/me/project', name: '  Fix login  ' };
+
+const managerFor = (place) => createSpaceManager({ registry: createPlaceRegistry([place]), now: () => NOW });
+
+describe('createSpaceManager', () => {
+  it('creates a space with a fresh id, the project hash and the creation time', async () => {
+    const manager = managerFor(createMemoryPlace());
+
+    const space = await manager.createSpace(REQUEST);
+    expect(space).toEqual({
+      placeId: 'memory',
+      id: expect.stringMatching(/^[0-9a-f]{12}$/),
+      name: 'Fix login',
+      project: hashProjectDirectory('/home/me/project'),
+      created: '2026-09-19T10:00:00.000Z',
+      memoryBytes: 4 * 1024 * 1024 * 1024,
+    });
+    const { memoryBytes, ...listedFields } = space;
+    expect(memoryBytes).toBeGreaterThan(0);
+    expect(await manager.listSpaces({ placeId: 'memory' })).toEqual([{ ...listedFields, state: 'running', orphans: [], damaged: false, missing: [] }]);
+  });
+
+  it('names the place that does not exist', async () => {
+    const manager = managerFor(createMemoryPlace());
+
+    await expect(manager.createSpace({ ...REQUEST, placeId: 'cluster' })).rejects.toMatchObject({ code: 'place_not_found' });
+    await expect(manager.listSpaces({ placeId: 'cluster' })).rejects.toMatchObject({ code: 'place_not_found' });
+    await expect(manager.stopSpace({ placeId: 'cluster', spaceId: 'a1b2c3d4e5f6' })).rejects.toMatchObject({ code: 'place_not_found' });
+  });
+
+  it('rejects a bad name or directory before it asks the place', async () => {
+    const place = createMemoryPlace();
+    const manager = managerFor(place);
+
+    await expect(manager.createSpace({ ...REQUEST, name: '' })).rejects.toMatchObject({ code: 'invalid_space_name' });
+    await expect(manager.createSpace({ ...REQUEST, projectDirectory: '' })).rejects.toMatchObject({ code: 'invalid_project_directory' });
+    expect(await place.list()).toEqual([]);
+  });
+
+  it('removes and refuses a space whose verification reports violations', async () => {
+    const place = { ...createMemoryPlace(), verify: async () => [{ check: 'privileged', message: 'The container is privileged' }] };
+    const manager = managerFor(place);
+
+    const error = await manager.createSpace(REQUEST).catch((caught) => caught);
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error.code).toBe('space_verification_failed');
+    expect(error.message).toContain('The container is privileged');
+    expect(error.details.violations).toHaveLength(1);
+    expect(error.details.removal.failed).toEqual([]);
+    expect(await place.list()).toEqual([]);
+  });
+
+  it('removes a space that could not be verified at all', async () => {
+    const place = { ...createMemoryPlace(), verify: async () => { throw new SpaceError('command_timeout', 'docker inspect did not finish'); } };
+    const manager = managerFor(place);
+
+    await expect(manager.createSpace(REQUEST)).rejects.toMatchObject({ code: 'command_timeout' });
+    expect(await place.list()).toEqual([]);
+  });
+
+  it('reports a space it could neither verify nor remove', async () => {
+    const place = {
+      ...createMemoryPlace(),
+      verify: async () => [{ check: 'user', message: 'Runs as root' }],
+      remove: async () => { throw new SpaceError('docker_command_failed', 'daemon went away'); },
+    };
+
+    const error = await managerFor(place).createSpace(REQUEST).catch((caught) => caught);
+    expect(error.details.removal.failed).toEqual([{ kind: 'space', name: expect.any(String), message: 'daemon went away' }]);
+  });
+
+  it('lets a failed create through', async () => {
+    const place = { ...createMemoryPlace(), create: async () => { throw new SpaceError('image_pull_failed', 'no internet'); } };
+    await expect(managerFor(place).createSpace(REQUEST)).rejects.toMatchObject({ code: 'image_pull_failed' });
+  });
+
+  it('lets a list failure through instead of an empty list', async () => {
+    const place = { ...createMemoryPlace(), list: async () => { throw new SpaceError('docker_command_failed', 'daemon went away'); } };
+    await expect(managerFor(place).listSpaces({ placeId: 'memory' })).rejects.toMatchObject({ code: 'docker_command_failed' });
+  });
+
+  it('reads status from the place on every call', async () => {
+    const manager = managerFor(createMemoryPlace());
+    const { id: spaceId } = await manager.createSpace(REQUEST);
+    const state = async () => (await manager.listSpaces({ placeId: 'memory' }))[0].state;
+
+    await manager.stopSpace({ placeId: 'memory', spaceId });
+    expect(await state()).toBe('exited');
+    await manager.startSpace({ placeId: 'memory', spaceId });
+    expect(await state()).toBe('running');
+    await manager.removeSpace({ placeId: 'memory', spaceId });
+    expect(await manager.listSpaces({ placeId: 'memory' })).toEqual([]);
+  });
+
+  it('fails a removal that left something behind', async () => {
+    const failed = [{ kind: 'volume', name: 'openchamber-space-a1b2c3d4e5f6-volume-work', message: 'volume is in use' }];
+    const place = { ...createMemoryPlace(), remove: async () => ({ removed: [], failed }) };
+
+    await expect(managerFor(place).removeSpace({ placeId: 'memory', spaceId: 'a1b2c3d4e5f6' })).rejects.toMatchObject({
+      code: 'space_remove_incomplete',
+      message: 'Could not remove: volume openchamber-space-a1b2c3d4e5f6-volume-work',
+      details: { failed },
+    });
+  });
+});

package/server/lib/spaces/places/code-in.docker.live.test.js

@@ -0,0 +1,216 @@
+// Code in, into a real space on a real Docker daemon. Runs only with OPENCHAMBER_TEST_DOCKER=1.
+// The bait repository arrives over `git push` through `docker exec`, and a space whose receiving
+// side never answers is ended by the host's timeout with nothing left on the host. Every test runs
+// alone as well as in order: the shared code in happens in `beforeAll`, and the hanging tests make
+// spaces of their own.
+
+import zlib from 'node:zlib';
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { OBJECTS_ONLY_TEXT, SECRET, createTestHost, hostState, makeBait, removeTestHosts, shortStatus, unexpectedChanges } from '../code-in-bait.js';
+import { createSpaceId, hashProjectDirectory, spaceResourceName } from '../labels.js';
+import { runCommand } from '../run-command.js';
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+const WIN = process.platform === 'win32';
+// The timing of the hanging tests. After the host gives up, and before the limit inside ends the
+// receiver, the tests count what still runs inside and check the host's processes: that window is
+// the inner margin. Over `DOCKER_HOST=ssh://` every docker call opens its own SSH connection, so the
+// window is sized from a measured `docker exec` round trip, with today's local values as the floor:
+// a 6 s host timeout and a 5 s margin. The deadline is counted from before the call, while the push
+// starts a few docker calls later, so up to three round trips of skew are paid for as well.
+const hangTiming = (roundTripMs) => {
+  const hostTimeoutMs = Math.max(6000, 3 * roundTripMs + 3000);
+  const innerMarginSeconds = Math.max(5, Math.ceil((4 * roundTripMs + 4000) / 1000));
+  return { roundTripMs, hostTimeoutMs, innerMarginSeconds, innerLimitMs: hostTimeoutMs + innerMarginSeconds * 1000 };
+};
+
+// The docker calls each hanging test makes between `started` and the push, where the limit inside
+// begins to count. Every `exec` of the place inspects first, so it costs two. Code in: `execArgv`,
+// then the init script. The history: `execArgv`, the shallow check, then the side repository's init.
+const DOCKER_CALLS_BEFORE_CODE_IN_PUSH = 3;
+const DOCKER_CALLS_BEFORE_HISTORY_PUSH = 5;
+
+// What the agent could have done inside by the time the history travels: a global git config in
+// its HOME that points every git at hooks of its own, and a pre-receive hook that never ends.
+const PLANT_HANGING_HOOK = [
+  'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin;',
+  'mkdir -p "$HOME/planted-hooks" &&',
+  'printf "#!/bin/sh\\nexec /bin/sleep 1000\\n" > "$HOME/planted-hooks/pre-receive" &&',
+  'chmod 755 "$HOME/planted-hooks/pre-receive" &&',
+  'git config --global core.hooksPath "$HOME/planted-hooks"',
+].join(' ');
+const COUNT_SLEEPERS = 'PATH=/usr/bin:/bin; n=0; for p in /proc/[0-9]*; do tr "\\000" " " < "$p/cmdline" 2>/dev/null | grep -q "^/bin/sleep 1000" && n=$((n+1)); done; echo $n';
+
+const pause = (milliseconds) => new Promise((resolve) => { setTimeout(resolve, milliseconds); });
+
+/**
+ * Waits up to two seconds for the host processes that name the container to be gone, and says
+ * whether they went. It must finish before the limit inside the space: that limit ends a leftover
+ * `docker exec` on its own, and a check that waited for it would pass without the tree kill.
+ */
+async function hostProcessesGone(container, innerLimitAt) {
+  let count = await hostProcessesNaming(container);
+  for (let attempt = 0; attempt < 8 && count > 0; attempt += 1) {
+    await pause(250);
+    count = await hostProcessesNaming(container);
+  }
+  expect(Date.now(), 'the host check ran into the limit inside the space and proves nothing').toBeLessThan(innerLimitAt);
+  return count === 0;
+}
+
+/** How many host processes name this container on their command line. The docker CLI of an exec always does. */
+async function hostProcessesNaming(container) {
+  if (WIN) {
+    const script = `@(Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '*${container}*' -and $_.ProcessId -ne $PID }).Count`;
+    const result = await runCommand('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script]);
+    return Number(result.stdout.trim());
+  }
+  const result = await runCommand('ps', ['-A', '-o', 'command=']);
+  return result.stdout.split('\n').filter((command) => command.includes(container)).length;
+}
+
+describe.skipIf(!LIVE_DOCKER_ENABLED)('code in: docker (live)', () => {
+  const newSpec = (name) => ({
+    id: createSpaceId(),
+    name,
+    project: hashProjectDirectory('/code/in/project'),
+    created: new Date().toISOString(),
+    memoryBytes: 1024 * 1024 * 1024,
+  });
+  const spec = newSpec('Code in');
+  const spaceIds = [spec.id];
+  let place;
+  let dispose = async () => {};
+  let repo;
+  let g;
+  let codeIn;
+  let before;
+  let result;
+  let timing;
+
+  const inside = (spaceId, script, args = []) => place.exec(spaceId, ['/bin/sh', '-c', `PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; ${script}`, 'sh', ...args], { timeoutMs: 120_000 });
+  const insideRepo = async (args) => (await inside(spec.id, 'cd "$1" && shift && git "$@"', [result.spacePath, ...args])).stdout;
+  const unchanged = () => unexpectedChanges(before, hostState(repo), { spaceIds });
+
+  /**
+   * Whether nothing of the planted hook runs inside any more, asked until the limit inside has passed
+   * counted from the latest moment the push could have started: `started`, the docker calls before the
+   * push, two more round trips for the push's own `docker exec` to begin, and a few seconds. A receiver
+   * with no limit inside is still there at that bound.
+   */
+  const insideEmptiesByItsLimit = async (spaceId, started, callsBeforePush) => {
+    const bound = started + timing.innerLimitMs + (callsBeforePush + 2) * timing.roundTripMs + 3000;
+    for (;;) {
+      if ((await inside(spaceId, COUNT_SLEEPERS)).stdout === '0\n') return true;
+      if (Date.now() > bound) return false;
+      await pause(500);
+    }
+  };
+
+  /** A space of its own for a test that plants something in it. */
+  const freshSpace = async (name) => {
+    const own = newSpec(name);
+    spaceIds.push(own.id);
+    await place.create(own);
+    return own;
+  };
+
+  beforeAll(async () => {
+    ({ place, dispose } = createLiveDockerPlace());
+    const host = createTestHost({ ownHome: false });
+    ({ repo, g } = makeBait(host));
+    codeIn = host.codeIn(place);
+    await place.create(spec);
+    // The slowest of three round trips of `docker exec` into the space sizes the hanging tests.
+    let roundTripMs = 0;
+    for (let sample = 0; sample < 3; sample += 1) {
+      const sampleStarted = Date.now();
+      await place.exec(spec.id, ['/bin/true']);
+      roundTripMs = Math.max(roundTripMs, Date.now() - sampleStarted);
+    }
+    timing = hangTiming(roundTripMs);
+    before = hostState(repo);
+    result = await codeIn.bringCodeIn({ repository: repo, spaceId: spec.id });
+  }, CREATE_TIMEOUT_MS);
+
+  afterAll(async () => {
+    await dispose();
+    removeTestHosts();
+  }, CREATE_TIMEOUT_MS);
+
+  it('brings the bait in: the same status line for line, the exec bit, the identity, and nothing ignored', async () => {
+    expect(result.spacePath).toBe(`/spaces/${spec.id}/bait-repo-`);
+    expect(result.identityCopied).toEqual({ name: true, email: true });
+    expect(await insideRepo(['status', '--porcelain=v1', '--untracked-files=all'])).toBe(shortStatus(g));
+    expect(await insideRepo(['symbolic-ref', 'HEAD'])).toBe('refs/heads/main\n');
+    expect(await insideRepo(['rev-parse', 'HEAD'])).toBe(`${result.base}\n`);
+    expect(await insideRepo(['config', 'user.name'])).toBe('Bait Author\n');
+    expect(await insideRepo(['config', 'user.email'])).toBe('bait@example.invalid\n');
+    expect((await inside(spec.id, 'stat -c %a "$1/run.sh"', [result.spacePath])).stdout).toBe('755\n');
+    const present = await inside(spec.id, 'for f in .env node_modules secret-by-global-ignore.txt; do [ -e "$1/$f" ] && echo "$f"; done; true', [result.spacePath]);
+    expect(present.stdout).toBe('');
+    expect(unchanged()).toEqual([]);
+  });
+
+  it('sends the history afterwards, unshallows the repository, and removes the side repository', async () => {
+    expect(await codeIn.sendHistory({ repository: repo, spaceId: spec.id, spacePath: result.spacePath, base: result.base })).toEqual({ status: 'sent' });
+    expect(await insideRepo(['rev-list', '--count', 'HEAD'])).toBe(g(['rev-list', '--count', 'HEAD']));
+    expect(await insideRepo(['rev-parse', '--is-shallow-repository'])).toBe('false\n');
+    expect((await inside(spec.id, '[ -e "$1" ] && echo there; true', [`/spaces/${spec.id}/.openchamber-history.git`])).stdout).toBe('');
+    // Nothing the agent sees changed: the same status as before the history came.
+    expect(await insideRepo(['status', '--porcelain=v1', '--untracked-files=all'])).toBe(shortStatus(g));
+    expect(unchanged()).toEqual([]);
+  });
+
+  // The secret is searched for on the host, in what was collected from the space. Sending it into
+  // the space as a search pattern would put it there.
+  it('puts the ignored .env secret nowhere in the space, files or git objects', async () => {
+    // Gzipped on the way out, because the space's HOME holds OpenCode's data and exec output is capped.
+    const collect = async (script, args) => {
+      const collected = await place.exec(spec.id, ['/bin/sh', '-c', `PATH=/usr/bin:/bin; ${script} | gzip -c | base64 -w 0`, 'sh', ...args], { timeoutMs: 120_000 });
+      expect(collected.code).toBe(0);
+      return zlib.gunzipSync(Buffer.from(collected.stdout, 'base64'));
+    };
+    const files = await collect('tar -C / -cf - "${1#/}" home/space', [`/spaces/${spec.id}`]);
+    const objects = await collect('git -C "$1" cat-file --batch-all-objects --batch', [result.spacePath]);
+    // Controls: an untracked file's text is in the files, and the text of a tracked file the bait
+    // deleted is in the objects and not in the compressed files, so the object dump is uncompressed.
+    expect(files.includes('untracked travels')).toBe(true);
+    expect(objects.includes(OBJECTS_ONLY_TEXT)).toBe(true);
+    expect(files.includes(OBJECTS_ONLY_TEXT)).toBe(false);
+    expect(files.includes(SECRET)).toBe(false);
+    expect(objects.includes(SECRET)).toBe(false);
+  });
+
+  it('ends a history push that the space never answers at the host timeout, with no host process left and nothing inside after its limit', async () => {
+    const own = await freshSpace('Code in, hanging history');
+    const ownResult = await codeIn.bringCodeIn({ repository: repo, spaceId: own.id });
+    expect((await inside(own.id, PLANT_HANGING_HOOK)).code).toBe(0);
+    const started = Date.now();
+
+    const failure = await codeIn.sendHistory({ repository: repo, spaceId: own.id, spacePath: ownResult.spacePath, base: ownResult.base, timeoutMs: timing.hostTimeoutMs, innerMarginSeconds: timing.innerMarginSeconds }).catch((error) => error);
+    expect(failure).toMatchObject({ code: 'history_transfer_failed', details: { cause: 'command_timeout' } });
+    // The control: the receiving side really was held inside, and still is, because its limit is later.
+    expect(Number((await inside(own.id, COUNT_SLEEPERS)).stdout)).toBeGreaterThan(0);
+    expect(await hostProcessesGone(spaceResourceName(own.id, 'space'), started + timing.innerLimitMs)).toBe(true);
+    expect(await insideEmptiesByItsLimit(own.id, started, DOCKER_CALLS_BEFORE_HISTORY_PUSH), 'the receiver inside outlived the limit inside the space').toBe(true);
+    expect(unchanged()).toEqual([]);
+  }, CREATE_TIMEOUT_MS);
+
+  it('removes its host ref and leaves the host repository as it was when the space never answers the code-in push', async () => {
+    const own = await freshSpace('Code in, hanging');
+    expect((await inside(own.id, PLANT_HANGING_HOOK)).code).toBe(0);
+    const started = Date.now();
+
+    const failure = await codeIn.bringCodeIn({ repository: repo, spaceId: own.id, timeoutMs: timing.hostTimeoutMs, innerMarginSeconds: timing.innerMarginSeconds }).catch((error) => error);
+    expect(failure).toMatchObject({ code: 'code_transfer_failed', details: { step: 'the base commit', cause: 'command_timeout' } });
+    expect(g(['for-each-ref', `refs/openchamber/spaces/${own.id}/`])).toBe('');
+    expect(Number((await inside(own.id, COUNT_SLEEPERS)).stdout)).toBeGreaterThan(0);
+    expect(await hostProcessesGone(spaceResourceName(own.id, 'space'), started + timing.innerLimitMs)).toBe(true);
+    expect(await insideEmptiesByItsLimit(own.id, started, DOCKER_CALLS_BEFORE_CODE_IN_PUSH), 'the receiver inside outlived the limit inside the space').toBe(true);
+    expect(unchanged()).toEqual([]);
+  }, CREATE_TIMEOUT_MS);
+});

package/server/lib/spaces/places/contract-suite.js

@@ -0,0 +1,156 @@
+// The contract every place must pass. Stage 8 to 10 places run this same suite.
+// `setup` resolves `{ place, dispose }`. `dispose` cleans up and may assert that nothing is left.
+
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createSpaceId, hashProjectDirectory } from '../labels.js';
+import { runCommand } from '../run-command.js';
+import { REQUIRED_PLACE_METHODS } from './registry.js';
+
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+
+export function runPlaceContractSuite(title, { enabled = true, setup }) {
+  describe.skipIf(!enabled)(`place contract: ${title}`, () => {
+    const spec = {
+      id: createSpaceId(),
+      name: 'Contract suite, a=b',
+      project: hashProjectDirectory('/contract/suite/project'),
+      created: new Date().toISOString(),
+      memoryBytes: 512 * 1024 * 1024,
+    };
+    let place;
+    let dispose = async () => {};
+
+    const listed = async () => (await place.list()).find((space) => space.id === spec.id);
+
+    beforeAll(async () => {
+      ({ place, dispose } = await setup());
+    });
+
+    afterAll(async () => {
+      await dispose();
+    });
+
+    it('has an id and every operation', () => {
+      expect(place.id).toMatch(/\S/);
+      for (const method of REQUIRED_PLACE_METHODS) {
+        expect(place[method]).toBeInstanceOf(Function);
+      }
+    });
+
+    it('is available', async () => {
+      expect(await place.check()).toMatchObject({ available: true });
+    });
+
+    it('creates a space that verifies clean', async () => {
+      await place.create(spec);
+      expect(await place.verify(spec.id)).toEqual([]);
+    }, CREATE_TIMEOUT_MS);
+
+    it('lists the space as running, with what it was created with', async () => {
+      const { id, name, project, created } = spec;
+      expect(await listed()).toEqual({ id, name, project, created, state: 'running', orphans: [], damaged: false, missing: [] });
+    });
+
+    it('refuses to create the same space again, and leaves it alone', async () => {
+      await expect(place.create(spec)).rejects.toMatchObject({ code: 'space_name_taken' });
+      expect(await listed()).toMatchObject({ state: 'running' });
+    });
+
+    it('runs commands as uid 1000', async () => {
+      const result = await place.exec(spec.id, ['id', '-u']);
+      expect(result).toMatchObject({ code: 0, stdout: '1000\n' });
+    });
+
+    // Added in stage 2. From here on a place cannot host a space without a gatekeeper, so this
+    // is part of the contract every later place is held to. Nothing that was here changed.
+    it('runs a command in the gatekeeper, which is a container of its own', async () => {
+      // Two containers, not one target answering for both: a hostname is per container.
+      const space = await place.exec(spec.id, ['cat', '/etc/hostname']);
+      const gatekeeper = await place.exec(spec.id, ['cat', '/etc/hostname'], { target: 'gatekeeper' });
+      expect(space).toMatchObject({ code: 0 });
+      expect(gatekeeper).toMatchObject({ code: 0 });
+      expect(space.stdout.trim()).not.toBe('');
+      expect(gatekeeper.stdout.trim()).not.toBe('');
+      expect(gatekeeper.stdout.trim()).not.toBe(space.stdout.trim());
+
+      // And it is not the space: the space's work directory is not in it.
+      const work = `/spaces/${spec.id}`;
+      expect(await place.exec(spec.id, ['test', '-d', work])).toMatchObject({ code: 0 });
+      expect((await place.exec(spec.id, ['test', '-d', work], { target: 'gatekeeper' })).code).not.toBe(0);
+      expect(await place.exec(spec.id, ['id', '-u'], { target: 'gatekeeper' })).toMatchObject({ code: 0, stdout: '1000\n' });
+    });
+
+    // Added in stage 2. The place contract names two targets, and a place that quietly took a
+    // third would be running commands somewhere this suite never looks.
+    it('knows the two exec targets and no others', async () => {
+      for (const target of ['setup', 'host', '', 'space-old']) {
+        await expect(place.exec(spec.id, ['id', '-u'], { target })).rejects.toMatchObject({ code: 'invalid_exec_target' });
+      }
+    });
+
+    // Added in stage 3a. Code travels into a space by `git push` over `ext::`, and git starts that
+    // process itself, so a place hands out the argv that reaches the space. It must reach the very
+    // container `exec` reaches, and never the gatekeeper. It goes into a git URL, which cannot carry
+    // an empty argument or a control character. The user is not checked here: a Docker space already
+    // runs as uid 1000 by default, so no check through the argv could fail. Each place proves its
+    // own user flag with an exact-argv test, as docker.test.js does.
+    it('hands out an argv that runs a command in the space container', async () => {
+      const argv = await place.execArgv(spec.id);
+      expect(argv.length).toBeGreaterThan(0);
+      for (const argument of argv) {
+        expect(argument).toEqual(expect.any(String));
+        expect(argument).not.toBe('');
+        expect(argument).not.toMatch(/[\x00-\x1f\x7f]/);
+      }
+      const [file, ...args] = argv;
+      const run = (command) => runCommand(file, [...args, ...command], { timeoutMs: 60_000 });
+      const hostname = await run(['cat', '/etc/hostname']);
+      expect(hostname).toMatchObject({ code: 0 });
+      expect(hostname.stdout).toBe((await place.exec(spec.id, ['cat', '/etc/hostname'])).stdout);
+      expect(hostname.stdout).not.toBe((await place.exec(spec.id, ['cat', '/etc/hostname'], { target: 'gatekeeper' })).stdout);
+    });
+
+    it('stops the space and lists it as exited', async () => {
+      await place.stop(spec.id);
+      expect(await listed()).toMatchObject({ state: 'exited' });
+    });
+
+    // Added in stage 3a. git starts the argv itself, and a stopped container answers it only with
+    // the runtime's own words, so a place refuses a stopped space here with a code of its own.
+    it('hands out no argv for a stopped space', async () => {
+      await expect(place.execArgv(spec.id)).rejects.toMatchObject({ code: 'space_not_running' });
+    });
+
+    it('starts the space again', async () => {
+      await place.start(spec.id);
+      expect(await listed()).toMatchObject({ state: 'running' });
+      expect(await place.verify(spec.id)).toEqual([]);
+    });
+
+    it('removes the space and leaves no labelled resource behind', async () => {
+      const result = await place.remove(spec.id);
+      expect(result.failed).toEqual([]);
+      // `list` also reports orphaned networks and volumes, so an absent id means nothing is left.
+      expect(await listed()).toBeUndefined();
+    });
+
+    // Added in stage 2, for the same reason as the gatekeeper exec above. The test before this
+    // one ran a command in the gatekeeper, so this failure is the removal and nothing else.
+    // A place that removed the space and left its gatekeeper running would still answer here.
+    it('removes the gatekeeper with the space', async () => {
+      await expect(place.exec(spec.id, ['cat', '/etc/hostname'], { target: 'gatekeeper' })).rejects.toThrow();
+      await expect(place.exec(spec.id, ['cat', '/etc/hostname'])).rejects.toThrow();
+    });
+
+    // Added in stage 3a. The argv comes after the same ownership check as `exec`, so a space that
+    // is gone gets none. A place that built it from the id alone would still hand one out here.
+    it('hands out no argv for a space that is gone', async () => {
+      await expect(place.execArgv(spec.id)).rejects.toThrow();
+    });
+
+    it('treats removing a missing space as done', async () => {
+      expect(await place.remove(spec.id)).toEqual({ removed: [], failed: [] });
+    });
+  });
+}

package/server/lib/spaces/places/contract.docker.live.test.js

@@ -0,0 +1,7 @@
+import { runPlaceContractSuite } from './contract-suite.js';
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+
+runPlaceContractSuite('docker (live)', {
+  enabled: LIVE_DOCKER_ENABLED,
+  setup: async () => createLiveDockerPlace(),
+});

package/server/lib/spaces/places/contract.test.js

@@ -0,0 +1,6 @@
+import { runPlaceContractSuite } from './contract-suite.js';
+import { createMemoryPlace } from './memory-place.js';
+
+runPlaceContractSuite('memory', {
+  setup: async () => ({ place: createMemoryPlace(), dispose: async () => {} }),
+});