@vantran-se/openchamber-web 2.0.3 → 2.0.5

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

@@ -0,0 +1,296 @@
+// The dispatcher in front of a real space on a real Docker daemon. Runs only with
+// OPENCHAMBER_TEST_DOCKER=1. Two parts: the dispatcher over the Docker place, mounted in an
+// Express app the way `server/index.js` mounts it; and the real server started headless, once
+// with the switch off and once with it on, in front of a stand-in Docker daemon that records
+// whether anything ever spoke to it.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import express from 'express';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+import { createSpacesHost } from '../host.js';
+import { createSpaceId, hashProjectDirectory } from '../labels.js';
+import { LIVE_DOCKER_ENABLED, createLiveDockerPlace } from './docker-live-support.js';
+
+const CREATE_TIMEOUT_MS = 25 * 60_000;
+const SERVER_ENTRY = fileURLToPath(new URL('../../../index.js', import.meta.url));
+
+const temporary = (prefix) => fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+
+const listen = (app) => new Promise((resolve) => {
+  const server = http.createServer(app);
+  server.listen(0, '127.0.0.1', () => resolve(server));
+});
+
+describe.skipIf(!LIVE_DOCKER_ENABLED)('dispatcher over a real space: docker (live)', () => {
+  const spec = {
+    id: createSpaceId(),
+    name: 'Dispatcher live',
+    project: hashProjectDirectory('/dispatcher/live/project'),
+    created: new Date().toISOString(),
+    memoryBytes: 2 * 1024 * 1024 * 1024,
+  };
+  const repo = `/spaces/${spec.id}/repo`;
+  let place;
+  let dispose = async () => {};
+  let dataDir;
+  let host;
+  let server;
+  let hostRouteRuns = 0;
+  const url = (suffix) => `http://127.0.0.1:${server.address().port}${suffix}`;
+  const shell = async (script) => {
+    const result = await place.exec(spec.id, ['sh', '-c', script]);
+    expect(result.code, `${script}: ${result.stderr}`).toBe(0);
+    return result.stdout;
+  };
+
+  beforeAll(async () => {
+    ({ place, dispose } = createLiveDockerPlace());
+    await place.create(spec);
+    await shell(`mkdir -p ${repo} && cd ${repo} && git init -q . && git -c user.email=space@example.invalid -c user.name=Space commit -q --allow-empty -m init`);
+    dataDir = temporary('openchamber-dispatcher-live-');
+    host = createSpacesHost({ dataDir, place, logger: { warn: () => {} } });
+    const app = express();
+    // The host's auth gate stands in front of the dispatcher in the real server; here the request
+    // is taken as authenticated, and one host route records whether it ever ran.
+    app.use(host.middleware);
+    app.all('/api/git/status', (req, res) => {
+      hostRouteRuns += 1;
+      res.json({ ranOnHost: true, directory: req.query.directory ?? null });
+    });
+    app.use((_req, res) => res.status(404).json({ error: 'not found on host' }));
+    server = await listen(app);
+  }, CREATE_TIMEOUT_MS);
+
+  afterAll(async () => {
+    host?.close();
+    await new Promise((resolve) => { if (server) server.close(() => resolve()); else resolve(); });
+    await dispose();
+    if (dataDir) fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it('forwards a prefixed request to the server inside and returns its answer', async () => {
+    const response = await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`));
+    expect(response.status).toBe(200);
+    expect(response.headers.get('x-content-type-options')).toBe('nosniff');
+    expect(response.headers.get('set-cookie')).toBeNull();
+    const list = await response.json();
+    expect(Array.isArray(list.data ?? list)).toBe(true);
+  });
+
+  it('creates a session inside through a streamed POST body, and lists it back', async () => {
+    const created = await fetch(url(`/api/spaces/${spec.id}/session`), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ location: { directory: repo } }),
+    });
+    expect(created.status, await created.clone().text()).toBe(200);
+    const session = (await created.json()).data;
+    expect(session.location.directory).toBe(repo);
+
+    const listed = await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`));
+    const ids = ((await listed.json()).data ?? []).map((entry) => entry.id);
+    expect(ids).toContain(session.id);
+  });
+
+  it('streams the event stream of the server inside', async () => {
+    const controller = new AbortController();
+    const response = await fetch(url(`/api/spaces/${spec.id}/event`), { signal: controller.signal, headers: { accept: 'text/event-stream' } });
+    expect(response.status).toBe(200);
+    expect(response.headers.get('content-type')).toContain('text/event-stream');
+    const reader = response.body.getReader();
+    const { value, done } = await reader.read();
+    expect(done).toBe(false);
+    expect(new TextDecoder().decode(value).length).toBeGreaterThan(0);
+    controller.abort();
+  }, 60_000);
+
+  it('refuses a prefixed request that names a directory outside the space, and a host-only route', async () => {
+    const outside = await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent('/home/me/project')}`));
+    expect(outside.status).toBe(400);
+    expect(await outside.json()).toMatchObject({ code: 'directory_outside_space' });
+    const hostOnly = await fetch(url(`/api/spaces/${spec.id}/config/settings`));
+    expect(hostOnly.status).toBe(403);
+    expect(await hostOnly.json()).toMatchObject({ code: 'host_only_route' });
+  });
+
+  // The escape check of TESTING.md: a request without the space prefix, but with a space
+  // directory, does not run on the host.
+  it('refuses an unprefixed request with the space\'s directory before any host route runs', async () => {
+    const response = await fetch(url(`/api/git/status?directory=${encodeURIComponent(repo)}`));
+    expect(response.status).toBe(400);
+    expect(await response.json()).toMatchObject({ code: 'space_directory_needs_prefix' });
+    expect(hostRouteRuns).toBe(0);
+    const ordinary = await fetch(url('/api/git/status?directory=/tmp'));
+    expect(ordinary.status).toBe(200);
+    expect(hostRouteRuns).toBe(1);
+  });
+
+  // Processes inside are read from /proc, because the image has no pgrep. The match is anchored
+  // to the bridge's own command line, so the shell that runs this count is not counted.
+  const bridgesInside = async () => Number((await shell('n=0; for p in /proc/[0-9]*; do if tr "\\0" " " < "$p/cmdline" 2>/dev/null | grep -q "^/usr/local/bin/node -e "; then n=$((n+1)); fi; done; echo $n')).trim());
+
+  it('ends the bridge inside when the host closes its connections', async () => {
+    expect((await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`))).status).toBe(200);
+    expect(await bridgesInside()).toBeGreaterThan(0);
+    host.close();
+    let left = await bridgesInside();
+    for (let attempt = 0; attempt < 40 && left > 0; attempt += 1) {
+      await new Promise((resolve) => { setTimeout(resolve, 250); });
+      left = await bridgesInside();
+    }
+    expect(left).toBe(0);
+    // The next request opens a new one.
+    expect((await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`))).status).toBe(200);
+  }, 60_000);
+
+  it('answers 503 with a stable code for a stopped space, and serves it again after a start', async () => {
+    await place.stop(spec.id);
+    const stopped = await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`));
+    expect(stopped.status).toBe(503);
+    expect(await stopped.json()).toMatchObject({ code: 'space_not_running' });
+
+    await place.start(spec.id);
+    const again = await fetch(url(`/api/spaces/${spec.id}/session?directory=${encodeURIComponent(repo)}`));
+    expect(again.status).toBe(200);
+  }, 5 * 60_000);
+});
+
+/**
+ * The real server, started headless, with a stand-in for the Docker daemon on `DOCKER_HOST`
+ * that records every connection. The docker CLI on this machine is the real one: whether the
+ * feature ever called it is exactly what the daemon's connection count says.
+ */
+const startFakeDaemon = async (folder) => {
+  const socketPath = path.join(folder, 'docker.sock');
+  let connections = 0;
+  const open = new Set();
+  const daemon = net.createServer((socket) => {
+    connections += 1;
+    open.add(socket);
+    socket.on('close', () => open.delete(socket));
+    socket.on('error', () => {});
+    socket.end('HTTP/1.1 500 Internal Server Error\r\ncontent-length: 0\r\n\r\n');
+  });
+  await new Promise((resolve) => daemon.listen(socketPath, resolve));
+  return {
+    host: `unix://${socketPath}`,
+    connections: () => connections,
+    // A docker CLI may hold a connection open; `close` alone would wait for it for ever.
+    stop: () => new Promise((resolve) => {
+      for (const socket of open) socket.destroy();
+      daemon.close(() => resolve());
+    }),
+  };
+};
+
+const freePort = () => new Promise((resolve) => {
+  const probe = net.createServer();
+  probe.listen(0, '127.0.0.1', () => {
+    const { port } = probe.address();
+    probe.close(() => resolve(port));
+  });
+});
+
+const startServer = async ({ dataDir, dockerHost, port }) => {
+  const child = spawn(process.execPath, [SERVER_ENTRY, '--port', String(port), '--api-only'], {
+    env: { ...process.env, OPENCHAMBER_DATA_DIR: dataDir, DOCKER_HOST: dockerHost, OPENCHAMBER_RELAY_HOST: 'off' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  let output = '';
+  child.stdout.on('data', (chunk) => { output += chunk; });
+  child.stderr.on('data', (chunk) => { output += chunk; });
+  const base = `http://127.0.0.1:${port}`;
+  const deadline = Date.now() + 60_000;
+  let healthy = false;
+  while (!healthy && Date.now() < deadline) {
+    if (child.exitCode !== null) throw new Error(`the server left early:\n${output.slice(-2000)}`);
+    try {
+      healthy = (await fetch(`${base}/health`, { signal: AbortSignal.timeout(5_000) })).status === 200;
+    } catch {
+      // Not up yet.
+    }
+    if (!healthy) await new Promise((resolve) => { setTimeout(resolve, 250); });
+  }
+  if (!healthy) throw new Error(`the server did not become healthy:\n${output.slice(-2000)}`);
+  return {
+    base,
+    /** One request with a bound, so a hang names itself and the server's output instead of a timeout. */
+    get: async (suffix) => {
+      try {
+        return await fetch(`${base}${suffix}`, { signal: AbortSignal.timeout(30_000) });
+      } catch (error) {
+        throw new Error(`${suffix}: ${error.message}\n${output.slice(-2000)}`);
+      }
+    },
+    output: () => output,
+    stop: () => new Promise((resolve) => {
+      child.once('exit', resolve);
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 10_000).unref();
+    }),
+  };
+};
+
+describe.skipIf(!LIVE_DOCKER_ENABLED)('the switch, on the real server (live)', () => {
+  const folders = [];
+  afterAll(() => {
+    for (const folder of folders) fs.rmSync(folder, { recursive: true, force: true });
+  });
+
+  const startWith = async (enabled) => {
+    const folder = temporary('openchamber-switch-live-');
+    folders.push(folder);
+    const dataDir = path.join(folder, 'data');
+    fs.mkdirSync(dataDir, { recursive: true });
+    // The server copies `projects`, `themes` and `speech-models` from the default data directory
+    // into a fresh one at start; the last of those can be gigabytes. Present and empty, they stay.
+    for (const entry of ['projects', 'themes', 'speech-models']) fs.mkdirSync(path.join(dataDir, entry));
+    fs.writeFileSync(path.join(dataDir, 'settings.json'), JSON.stringify({ isolatedSpacesEnabled: enabled }));
+    const daemon = await startFakeDaemon(folder);
+    const server = await startServer({ dataDir, dockerHost: daemon.host, port: await freePort() });
+    return { dataDir, daemon, server, stop: async () => { await server.stop(); await daemon.stop(); } };
+  };
+
+  it('registers no route of the feature and never speaks to Docker while the switch is off', async () => {
+    const run = await startWith(false);
+    try {
+      const prefixed = await run.server.get('/api/spaces/aaaaaaaaaaaa/session');
+      // Whatever the host answers, it is not the feature: no space code, and the request went on
+      // to the host's own routes.
+      const body = await prefixed.text();
+      expect(body).not.toMatch(/space_not_found|space_unreachable|host_only_route/);
+      const unguarded = await run.server.get('/api/git/status?directory=/spaces/aaaaaaaaaaaa/repo');
+      expect(unguarded.status).not.toBe(400);
+      expect(run.daemon.connections()).toBe(0);
+      expect(fs.existsSync(path.join(run.dataDir, 'spaces'))).toBe(false);
+    } finally {
+      await run.stop();
+    }
+  }, 120_000);
+
+  it('registers the routes and asks Docker for its spaces while the switch is on', async () => {
+    const run = await startWith(true);
+    try {
+      const prefixed = await run.server.get('/api/spaces/aaaaaaaaaaaa/session');
+      expect(prefixed.status).toBe(502);
+      expect(await prefixed.json()).toMatchObject({ code: 'space_unreachable' });
+      expect(run.daemon.connections()).toBeGreaterThan(0);
+      const guarded = await run.server.get('/api/git/status?directory=/spaces/aaaaaaaaaaaa/repo');
+      expect(guarded.status).toBe(400);
+      expect(await guarded.json()).toMatchObject({ code: 'space_directory_needs_prefix' });
+      const hostOnly = await run.server.get('/api/spaces/aaaaaaaaaaaa/config/settings');
+      expect(hostOnly.status).toBe(403);
+      expect(fs.existsSync(path.join(run.dataDir, 'spaces', 'owner'))).toBe(true);
+    } finally {
+      await run.stop();
+    }
+  }, 120_000);
+});

package/server/lib/spaces/places/docker-live-support.js

@@ -118,13 +118,21 @@ export function createLiveDockerPlace({ toolsSource = createRegistryToolsSource(
 const crypto = require('node:crypto');
 const hash = (value) => (value === undefined ? 'none' : 'sha256:' + crypto.createHash('sha256').update(String(value)).digest('hex'));
 require('node:http').createServer((request, response) => {
-  response.writeHead(200, { 'content-type': 'application/json' });
-  response.end(JSON.stringify({
+  const seen = {
+    method: request.method,
     path: request.url,
     authorization: hash(request.headers.authorization),
     apiKey: hash(request.headers['x-api-key']),
     headerNames: Object.keys(request.headers).sort(),
-  }));
+  };
+  // One line per request in the container's log, so the host can read what a client it does
+  // not control, OpenCode inside a space, sent here. Hashes only, as in the answer.
+  console.log('seen ' + JSON.stringify(seen));
+  request.resume();
+  request.on('end', () => {
+    response.writeHead(200, { 'content-type': 'application/json' });
+    response.end(JSON.stringify(seen));
+  });
 }).listen(9000, '0.0.0.0', () => console.log('upstream listening'));
 `;
       await docker([
@@ -136,9 +144,24 @@ require('node:http').createServer((request, response) => {
         await new Promise((resolve) => { setTimeout(resolve, 250); });
         if ((await docker(['logs', name])).stdout.includes('upstream listening')) break;
       }
-      return { url: 'http://upstream:9000/v1', stop: () => docker(['rm', '--force', name]) };
+      return {
+        url: 'http://upstream:9000/v1',
+        /** Every request this upstream has seen so far, oldest first, from its log. */
+        seen: async () => (await docker(['logs', name])).stdout.split('\n').filter((line) => line.startsWith('seen ')).map((line) => JSON.parse(line.slice(5))),
+        stop: () => docker(['rm', '--force', name]),
+      };
     },
 
+    /**
+     * Runs a Node script in a helper container on the space's outer network, where the stand-in
+     * upstream sits and where, on a Linux host, the host's own processes can reach. What such a
+     * neighbour can reach on the gatekeeper is what the gatekeeper's bind address decides.
+     */
+    probeFromOuterNetwork: (spaceId, script) => docker(
+      ['run', '--rm', ...helperLabels, '--network', spaceResourceName(spaceId, ROLE_OUTER_NETWORK), SPACE_BASE_IMAGE, 'node', '-e', script],
+      { timeoutMs: 120_000 },
+    ),
+
     /**
      * A name of our own in the space's outer network, answered by Docker's embedded resolver with
      * an address in that bridge's subnet — a private range, and therefore one the corridor must

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

@@ -1,3 +1,5 @@
+import net from 'node:net';
+
 import { SpaceError } from '../errors.js';
 import { createGatekeeperChannel } from '../gatekeeper-channel.js';
 import {
@@ -25,7 +27,8 @@ import {
   requireSpaceId,
   spaceResourceName,
 } from '../labels.js';
-import { SPACE_USER, TOOLS_MOUNT_PATH } from '../layout.js';
+import { SPACE_CONNECT_COMMAND, SPACE_USER, TOOLS_MOUNT_PATH } from '../layout.js';
+import { openCommandStream as openCommandStreamProcess } from '../run-command.js';
 import { createSpaceServerChannel, createSpaceToken } from '../space-server.js';
 import { CHANGE_TIMEOUT_MS, ROLLBACK_SETTLE_MS, createDockerEngine, entryLabels, entryName, isInterrupted, pause } from './docker-engine.js';
 import { createDockerTools } from './docker-tools.js';
@@ -57,7 +60,7 @@ function execRole(target) {
   throw new SpaceError('invalid_exec_target', `A command runs in the space or in its gatekeeper, not in '${target}'`);
 }
 
-export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource, wait = pause, now = () => new Date() }) {
+export function createDockerPlace({ runCommand, openCommandStream = openCommandStreamProcess, dockerPath, owner, toolsSource, wait = pause, now = () => new Date() }) {
   requireOwner(owner);
 
   const engine = createDockerEngine({ runCommand, dockerPath });
@@ -307,7 +310,7 @@ export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource,
       await docker(['network', 'connect', outerNetwork, gatekeeperName], CHANGE_TIMEOUT_MS);
       await requireGatekeeperVerified(id, await inspectOwnContainer(id, gatekeeperName) ?? {});
       await docker(['start', gatekeeperName], CHANGE_TIMEOUT_MS);
-      await gatekeeper.writeProgram(id);
+      await gatekeeper.writeProgram(id, { bindAddress: await innerAddressOf(id) });
       await gatekeeper.waitUntilReady(id);
       // Create, verify, then start: a container that fails the check never runs.
       await docker(buildSpaceCreateArgs({
@@ -388,6 +391,20 @@ export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource,
   // Starts that are under way in this process, by space id.
   const starting = new Map();
 
+  /**
+   * The gatekeeper's own address on the space's inner network, read from the runtime once the
+   * container runs: that is where its corridor and window listen, and nowhere else. An engine
+   * that reports none leaves the gatekeeper unstarted, which is the safe answer.
+   */
+  const innerAddressOf = async (spaceId) => {
+    const entry = await inspectOwnContainer(spaceId, spaceResourceName(spaceId, ROLE_GATEKEEPER));
+    const address = String(entry?.NetworkSettings?.Networks?.[spaceResourceName(spaceId, ROLE_NETWORK)]?.IPAddress ?? '');
+    if (net.isIP(address) === 0) {
+      throw new SpaceError('gatekeeper_address_unknown', `The runtime reports no address for the gatekeeper of space ${spaceId} on the space's network, so its listeners cannot be bound.`);
+    }
+    return address;
+  };
+
   /** The gatekeeper container of a space. It is never renamed, so there is no move to repair here. */
   const requireGatekeeperContainer = async (spaceId) => {
     const name = spaceResourceName(spaceId, ROLE_GATEKEEPER);
@@ -425,6 +442,17 @@ export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource,
     return [dockerPath, 'exec', '--interactive', '--user', SPACE_USER, spaceResourceName(spaceId, ROLE_SPACE)];
   };
 
+  /**
+   * A channel to the server inside the space: the bridge of `layout.js` over the argv of
+   * `execArgv`, so the same ownership and running checks come first, and the same process
+   * shape as a push carries the bytes. The space's network never sees it. The stream is a
+   * `CommandStream` of `run-command.js`, and the dispatcher's agent uses it as a socket.
+   */
+  const connect = async (spaceId) => {
+    const [file, ...args] = await execArgv(spaceId);
+    return openCommandStream(file, [...args, ...SPACE_CONNECT_COMMAND]);
+  };
+
   /**
    * The space stops first and its gatekeeper after it, so a space is never running while its
    * way out is not under the host's control. A stop of the gatekeeper that fails leaves the
@@ -456,7 +484,7 @@ export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource,
       await requireGatekeeperVerified(spaceId, container);
       await docker(['start', name], CHANGE_TIMEOUT_MS);
     }
-    await gatekeeper.writeProgram(spaceId);
+    await gatekeeper.writeProgram(spaceId, { bindAddress: await innerAddressOf(spaceId) });
     await gatekeeper.waitUntilReady(spaceId);
   };
 
@@ -583,5 +611,5 @@ export function createDockerPlace({ runCommand, dockerPath, owner, toolsSource,
     return starting.get(spaceId);
   };
 
-  return { id: DOCKER_PLACE_ID, check, create, list, exec, execArgv, stop, start, remove, verify };
+  return { id: DOCKER_PLACE_ID, check, create, list, exec, execArgv, connect, stop, start, remove, verify };
 }

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

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest';
 import { SpaceError } from '../errors.js';
 import { GATEKEEPER_PROGRAM } from '../gatekeeper-channel.js';
 import { buildSpaceLabels, buildToolsLabels, hashProjectDirectory } from '../labels.js';
-import { SPACE_ENVIRONMENT, SPACE_SERVER_COMMAND } from '../layout.js';
+import { SPACE_CONNECT_COMMAND, SPACE_ENVIRONMENT, SPACE_SERVER_COMMAND } from '../layout.js';
 import { createRegistryToolsSource, toolsContentKey } from '../tools.js';
 import { SPACE_BASE_IMAGE, createDockerPlace } from './docker.js';
 import { bridgeNetworkEntry, createFakeDocker, hardenedContainerEntry, internalNetworkEntry } from './fake-docker.js';
@@ -27,7 +27,7 @@ const NOW = new Date('2026-09-20T08:00:00.000Z');
 /** A place on a plain runner, for the tests that wrap or replace the fake. */
 const placeOn = (runCommand, options = {}) => createDockerPlace({ runCommand, dockerPath: 'docker', owner: OWNER, toolsSource: SOURCE, now: () => NOW, ...options });
 
-const makePlace = (fake, owner = OWNER, toolsSource = SOURCE) => placeOn(fake.runCommand, { dockerPath: '/usr/bin/docker', owner, toolsSource, wait: fake.wait, now: fake.now });
+const makePlace = (fake, owner = OWNER, toolsSource = SOURCE, options = {}) => placeOn(fake.runCommand, { dockerPath: '/usr/bin/docker', owner, toolsSource, wait: fake.wait, now: fake.now, ...options });
 
 const labelsFor = (role, { id = ID, owner = OWNER } = {}) => buildSpaceLabels({ ...SPEC, id, role, owner });
 
@@ -272,13 +272,21 @@ describe('docker place: create', () => {
       '--env', 'HOME=/tmp',
       SPACE_BASE_IMAGE,
       '/bin/sh', '-c',
-      'while [ ! -s /tmp/openchamber-gatekeeper/gatekeeper.cjs ]; do /bin/sleep 0.2; done; exec /usr/local/bin/node /tmp/openchamber-gatekeeper/gatekeeper.cjs 0.0.0.0 3128 8080 9099 300000 128 64 8',
+      // The bind host is the file the host writes after the start, holding the gatekeeper's own
+      // address on the space's network, never every interface: see "Known limits" of stage 2.
+      'while [ ! -s /tmp/openchamber-gatekeeper/gatekeeper.cjs ]; do /bin/sleep 0.2; done; exec /usr/local/bin/node /tmp/openchamber-gatekeeper/gatekeeper.cjs /tmp/openchamber-gatekeeper/bind 3128 8080 9099 300000 128 64 8',
     ]);
     expect(create).toContain('openchamber.space.role=gatekeeper');
     expect(create).not.toContain('--mount');
     // The program travels on stdin, so it is in no argument list, and no secret is in one either.
     const write = fake.calls.find((call) => isExec('gatekeeper.cjs.new')(call.args));
     expect(write.options.stdin).toBe(GATEKEEPER_PROGRAM);
+    // The address the fake engine gives the gatekeeper on the inner network, read after the start
+    // and written into the bind file before the program.
+    expect(write.args.slice(-2)).toEqual(['sh', '172.19.0.2']);
+    expect(write.args.join(' ')).toContain('> /tmp/openchamber-gatekeeper/bind.new && mv /tmp/openchamber-gatekeeper/bind.new /tmp/openchamber-gatekeeper/bind && cat > /tmp/openchamber-gatekeeper/gatekeeper.cjs.new');
+    const order = fake.calls.map((call) => describeCall(call.args));
+    expect(order.indexOf(`start ${GATEKEEPER}`)).toBeLessThan(order.indexOf('exec write program'));
     expect(write.args[4]).toBe(GATEKEEPER);
   });
 
@@ -833,6 +841,37 @@ describe('docker place: exec, stop, start, verify', () => {
     await expect(makePlace(createFakeDocker({ resources: aside })).execArgv(ID)).rejects.toMatchObject({ code: 'space_move_unfinished' });
   });
 
+  // Added in stage 4a. `connect` runs the bridge of layout.js over the argv of `execArgv`, through
+  // the injected stream opener, so the same checks come first and no process starts in a unit test.
+  it('connects through the bridge inside the space container, over the exec argv, and changes nothing', async () => {
+    const fake = createFakeDocker({ resources: spaceResources() });
+    const opened = [];
+    const stream = { destroyed: false };
+    const place = makePlace(fake, OWNER, SOURCE, { openCommandStream: (file, args) => { opened.push([file, ...args]); return stream; } });
+
+    expect(await place.connect(ID)).toBe(stream);
+    expect(opened).toEqual([['/usr/bin/docker', 'exec', '--interactive', '--user', '1000:1000', CONTAINER, ...SPACE_CONNECT_COMMAND]]);
+    expect(SPACE_CONNECT_COMMAND.slice(0, 2)).toEqual(['/usr/local/bin/node', '-e']);
+    expect(SPACE_CONNECT_COMMAND.slice(-2)).toEqual(['127.0.0.1', '27600']);
+    expect(SPACE_CONNECT_COMMAND.join(' ')).not.toMatch(/\n/);
+    expect(changes(fake)).toEqual([]);
+  });
+
+  it('connects to no stopped space, no stranger\'s container, no space of another installation, none that is missing or mid-move', async () => {
+    const opened = [];
+    const connectWith = (fake) => makePlace(fake, OWNER, SOURCE, { openCommandStream: (...args) => { opened.push(args); return {}; } }).connect(ID);
+    await expect(connectWith(createFakeDocker({ resources: spaceResources({ running: false }) }))).rejects.toMatchObject({ code: 'space_not_running' });
+    const stranger = hardenedContainerEntry({ name: CONTAINER, labels: {}, network: NETWORK, volumes: [] });
+    await expect(connectWith(createFakeDocker({ resources: [{ kind: 'container', name: CONTAINER, entry: stranger }] }))).rejects.toMatchObject({ code: 'space_not_ours' });
+    await expect(connectWith(createFakeDocker({ resources: spaceResources({ owner: 'install-b' }) }))).rejects.toMatchObject({ code: 'space_not_ours' });
+    await expect(connectWith(createFakeDocker())).rejects.toMatchObject({ code: 'space_not_found' });
+    const aside = spaceResources({ running: false }).map((resource) => (resource.name === CONTAINER
+      ? { ...resource, name: `${CONTAINER}-old`, entry: { ...resource.entry, Name: `/${CONTAINER}-old` } }
+      : resource));
+    await expect(connectWith(createFakeDocker({ resources: aside }))).rejects.toMatchObject({ code: 'space_move_unfinished' });
+    expect(opened).toEqual([]);
+  });
+
   it('stops the space, starts the same container again, and waits for its server', async () => {
     const fake = createFakeDocker({ resources: [toolsResource(), ...spaceResources()] });
     const place = makePlace(fake);