@vantran-se/openchamber-web 2.0.4 → 2.0.5

package/server/lib/spaces/run-command.test.js

@@ -1,10 +1,12 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
+import { getEventListeners } from 'node:events';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
 import { afterEach, describe, expect, it } from 'vitest';
 
+import { SpaceError } from './errors.js';
 import { killLiveTrees, killProcessTree, liveTreeCount, runCommand } from './run-command.js';
 
 const node = process.execPath;
@@ -96,6 +98,16 @@ describe('runCommand', () => {
     });
   });
 
+  // A failing `git apply --check` prints a line or two per path; its exit code is the answer.
+  it('keeps only the last bytes of each stream past the cap with keepTail, and still answers with the exit code', async () => {
+    const flood = 'for (let i = 0; i < 4000; i += 1) process.stderr.write(`line ${i}\\n`.padStart(100, "x")); process.stdout.write("out"); process.exitCode = 3;';
+    const done = await runCommand(node, ['-e', flood], { maxOutputBytes: 10_000, keepTail: true, timeoutMs: 20_000 });
+    expect(done.code).toBe(3);
+    expect(done.stdout).toBe('out');
+    expect(Buffer.byteLength(done.stderr)).toBe(10_000);
+    expect(done.stderr.endsWith(`${'line 3999\n'.padStart(100, 'x')}`)).toBe(true);
+  });
+
   it('rejects when the executable does not exist', async () => {
     await expect(runCommand('/nonexistent/openchamber-no-such-binary', ['version'])).rejects.toMatchObject({
       code: 'command_spawn_failed',
@@ -230,11 +242,11 @@ const [pidFile, mode] = process.argv.slice(2);
 if (mode === 'sigint') process.on('SIGINT', () => process.exit(130));
 // An exit listener registered before ours that throws, as the serve command registers one earlier.
 if (mode === 'throwing') process.on('exit', () => { throw new Error('an earlier exit listener'); });
-runCommand(process.execPath, ['-e', ${JSON.stringify(parentScript)}], { killTree: true, timeoutMs: 120000 }).catch(() => {});
+runCommand(process.execPath, ['-e', ${JSON.stringify(parentScript)}], { killTree: true, keepAtExit: mode === 'keep', timeoutMs: 120000 }).catch(() => {});
 const ready = setInterval(() => {
   if (!fs.existsSync(pidFile)) return;
   clearInterval(ready);
-  if (mode === 'exit' || mode === 'throwing') process.exit(0);
+  if (mode === 'exit' || mode === 'throwing' || mode === 'keep') process.exit(0);
   fs.writeFileSync(pidFile + '.ready', '');
   setInterval(() => {}, 1000);
 }, 50);
@@ -271,6 +283,77 @@ const ready = setInterval(() => {
     expect(await waitFor(() => !isAlive(child) && !isAlive(grandchild), 5000)).toBe(true);
   });
 
+  // `keepAtExit`, for `git apply`: killed in the middle it leaves a part written, so an exit leaves it.
+  // Windows has no such test: there libuv's job object ends the child with this process whatever we do.
+  it.skipIf(process.platform === 'win32')('leaves the tree of a keepAtExit child alive when the process leaves with process.exit', async () => {
+    const { child, grandchild } = await runWrapper('keep');
+    expect(isRealPid(child) && isRealPid(grandchild)).toBe(true);
+    expect(await waitFor(() => !isAlive(child) || !isAlive(grandchild), 1500)).toBe(false);
+  });
+
+  // The reviewer's probe: a `git apply` kept at exit whose smudge filter prints on stderr after the host
+  // left. Through a pipe to the dead host the print was SIGPIPE, and the apply stopped with files
+  // deleted; with the output in a file of its own it finishes, every file changed.
+  it.skipIf(process.platform === 'win32')('lets a keepAtExit git apply finish after the process left, while its filter prints', { timeout: 40_000 }, async () => {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-kept-apply-'));
+    try {
+      const repo = path.join(directory, 'repo');
+      const env = { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@example.invalid', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@example.invalid' };
+      const git = (args) => {
+        const done = spawnSync('git', ['-C', repo, ...args], { env, encoding: 'utf8' });
+        if (done.status !== 0) throw new Error(`git ${args.join(' ')}: ${done.stderr}`);
+        return done.stdout;
+      };
+      fs.mkdirSync(repo);
+      git(['init', '--quiet']);
+      const names = Array.from({ length: 20 }, (_, index) => `f${String(index).padStart(2, '0')}.txt`);
+      for (const name of names) fs.writeFileSync(path.join(repo, name), 'as it was\n');
+      git(['add', '.']);
+      git(['commit', '--quiet', '-m', 'files']);
+      for (const name of names) fs.writeFileSync(path.join(repo, name), 'changed\n');
+      const patch = path.join(directory, 'change.patch');
+      fs.writeFileSync(patch, git(['diff', '--binary']));
+      git(['checkout', '--quiet', '--', '.']);
+      const noisy = path.join(directory, 'noisy-smudge.sh');
+      fs.writeFileSync(noisy, '#!/bin/sh\nsleep 0.2\necho "a smudge filter that talks" >&2\ncat\n', { mode: 0o755 });
+      git(['config', 'filter.noisy.smudge', noisy]);
+      git(['config', 'filter.noisy.clean', 'cat']);
+      fs.writeFileSync(path.join(repo, '.git', 'info', 'attributes'), '*.txt filter=noisy\n');
+      const wrapper = path.join(directory, 'host.mjs');
+      fs.writeFileSync(wrapper, `
+import { runCommand } from ${JSON.stringify(new URL('./run-command.js', import.meta.url).href)};
+runCommand('git', ['-C', ${JSON.stringify(repo)}, 'apply', '--binary', ${JSON.stringify(patch)}], { env: ${JSON.stringify(env)}, killTree: true, keepAtExit: true, keepTail: true, maxOutputBytes: 65536, timeoutMs: 60000 }).catch(() => {});
+setTimeout(() => process.exit(0), 1000);
+`);
+      const host = spawn(node, [wrapper], { stdio: 'ignore' });
+      await new Promise((resolve) => { host.on('exit', resolve); });
+      const holds = (name) => fs.existsSync(path.join(repo, name)) && fs.readFileSync(path.join(repo, name), 'utf8') === 'changed\n';
+      // Four seconds of smudging in all, most of it after the host left.
+      expect(await waitFor(() => names.every(holds), 20_000)).toBe(true);
+      expect(git(['status', '--porcelain']).split('\n').filter(Boolean)).toEqual(names.map((name) => ` M ${name}`));
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  });
+
+  it('reads the stderr of a keepAtExit child back, its last maxOutputBytes with keepTail, and refuses more without it', async () => {
+    const script = 'process.stderr.write("x".repeat(5000) + "end"); process.stdout.write("gone"); process.exitCode = 2;';
+    expect(await runCommand(node, ['-e', script], { killTree: true, keepAtExit: true, keepTail: true, maxOutputBytes: 10 })).toEqual({ code: 2, stdout: '', stderr: 'xxxxxxxend' });
+    await expect(runCommand(node, ['-e', script], { killTree: true, keepAtExit: true, maxOutputBytes: 10 })).rejects.toMatchObject({ code: 'command_output_too_large' });
+    expect(await runCommand(node, ['-e', script], { killTree: true, keepAtExit: true })).toMatchObject({ code: 2, stderr: `${'x'.repeat(5000)}end` });
+    expect(fs.readdirSync(os.tmpdir()).filter((name) => name.startsWith('openchamber-stderr-'))).toEqual([]);
+  });
+
+  it('keeps a keepAtExit child out of the live set, and still kills its tree at the timeout', async () => {
+    const running = runCommand(node, ['-e', 'setInterval(() => {}, 1000)'], { killTree: true, keepAtExit: true, timeoutMs: 1500 }).catch((error) => error);
+    try {
+      expect(liveTreeCount()).toBe(0);
+    } finally {
+      // Out of the set, only its timeout ends it: waited for even when the assertion failed.
+      expect(await running).toMatchObject({ code: 'command_timeout' });
+    }
+  });
+
   it('still kills the tree when an exit listener registered before ours throws', async () => {
     const { child, grandchild } = await runWrapper('throwing');
     expect(isRealPid(child) && isRealPid(grandchild)).toBe(true);
@@ -394,3 +477,110 @@ setTimeout(() => process.exit(0), 200);
   }, 20_000);
 });
 
+
+// The caller stops a running child from outside, as code out does when the quarantine passes its
+// size cap. The rejection is the caller's own reason, whatever the child's exit looked like.
+describe('runCommand with an abort signal', () => {
+  const leftovers = [];
+  afterEach(() => {
+    for (const pid of leftovers.splice(0)) {
+      if (isRealPid(pid) && isAlive(pid)) process.kill(pid, 'SIGKILL');
+    }
+  });
+  const abortListeners = (signal) => getEventListeners(signal, 'abort').length;
+  const stopReason = () => new SpaceError('stopped_by_caller', 'the caller stopped it');
+
+  it('starts nothing when the signal is already aborted, and rejects with its reason', async () => {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-abort-before-'));
+    const marker = path.join(directory, 'started');
+    try {
+      const reason = stopReason();
+      const error = await runCommand(node, ['-e', `require('node:fs').writeFileSync(${JSON.stringify(marker)}, '')`], { killTree: true, signal: AbortSignal.abort(reason) }).catch((caught) => caught);
+      expect(error).toBe(reason);
+      // The control: the same command without the signal does start and leave its marker.
+      await new Promise((resolve) => { setTimeout(resolve, 300); });
+      expect(fs.existsSync(marker)).toBe(false);
+      expect(liveTreeCount()).toBe(0);
+      await runCommand(node, ['-e', `require('node:fs').writeFileSync(${JSON.stringify(marker)}, '')`]);
+      expect(fs.existsSync(marker)).toBe(true);
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  });
+
+  // On Windows this runs the real `taskkill /T`, whose child exits with code 1 and no signal.
+  it('kills the whole tree while it runs, rejects with the reason once the child is gone, and forgets the tree', async () => {
+    const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'openchamber-abort-during-'));
+    const pidFile = path.join(directory, 'pids.json');
+    try {
+      const controller = new AbortController();
+      const reason = stopReason();
+      const started = Date.now();
+      const running = runCommand(node, ['-e', parentOfSleeper(pidFile)], { killTree: true, timeoutMs: 60_000, signal: controller.signal }).catch((caught) => caught);
+      expect(await waitFor(() => fs.existsSync(pidFile) && fs.statSync(pidFile).size > 0)).toBe(true);
+      const pids = JSON.parse(fs.readFileSync(pidFile, 'utf8'));
+      leftovers.push(pids.grandchild, pids.child);
+      expect(isAlive(pids.child) && isAlive(pids.grandchild)).toBe(true);
+      expect(abortListeners(controller.signal)).toBe(1);
+      controller.abort(reason);
+      expect(await running).toBe(reason);
+      expect(isAlive(pids.child)).toBe(false);
+      expect(await waitFor(() => !isAlive(pids.grandchild))).toBe(true);
+      expect(Date.now() - started).toBeLessThan(30_000);
+      expect(liveTreeCount()).toBe(0);
+      expect(abortListeners(controller.signal)).toBe(0);
+    } finally {
+      fs.rmSync(directory, { recursive: true, force: true });
+    }
+  });
+
+  it('kills the child alone without killTree, and rejects with the reason', async () => {
+    const controller = new AbortController();
+    const reason = stopReason();
+    const running = runCommand(node, ['-e', 'process.stdout.write("up"); setInterval(() => {}, 1000)'], { timeoutMs: 60_000, signal: controller.signal }).catch((caught) => caught);
+    await new Promise((resolve) => { setTimeout(resolve, 300); });
+    controller.abort(reason);
+    expect(await running).toBe(reason);
+    expect(abortListeners(controller.signal)).toBe(0);
+  });
+
+  it('changes nothing about a run that already closed, and leaves no listener behind', async () => {
+    const controller = new AbortController();
+    expect(await runCommand(node, ['-e', 'process.stdout.write("ok")'], { killTree: true, signal: controller.signal })).toEqual({ code: 0, stdout: 'ok', stderr: '' });
+    expect(abortListeners(controller.signal)).toBe(0);
+    controller.abort(stopReason());
+    expect(liveTreeCount()).toBe(0);
+  });
+
+  // The timeout came first: its kill is the only one, and a late abort neither kills again nor
+  // replaces the error.
+  it('keeps the timeout as the error when the abort comes after it', async () => {
+    const controller = new AbortController();
+    const running = runCommand(node, ['-e', 'setInterval(() => {}, 1000)'], { killTree: true, timeoutMs: 500, signal: controller.signal }).catch((caught) => caught);
+    await new Promise((resolve) => { setTimeout(resolve, 700); });
+    expect(abortListeners(controller.signal)).toBe(0);
+    controller.abort(stopReason());
+    expect(await running).toMatchObject({ code: 'command_timeout' });
+    expect(liveTreeCount()).toBe(0);
+  });
+
+  // Whatever the caller aborts with, the rejection is a SpaceError: a string, null or nothing at all
+  // would otherwise reach a caller that catches SpaceErrors.
+  it.each([['a string', 'stopped'], ['null', null], ['nothing', undefined]])('rejects with a SpaceError when the reason is %s', async (_, reason) => {
+    const controller = new AbortController();
+    const running = runCommand(node, ['-e', 'setInterval(() => {}, 1000)'], { killTree: true, timeoutMs: 60_000, signal: controller.signal }).catch((caught) => caught);
+    await new Promise((resolve) => { setTimeout(resolve, 200); });
+    if (reason === undefined) controller.abort(); else controller.abort(reason);
+    const error = await running;
+    expect(error).toBeInstanceOf(SpaceError);
+    expect(error).toMatchObject({ code: 'command_aborted' });
+    expect(await runCommand(node, ['-e', ''], { signal: AbortSignal.abort(reason) }).catch((caught) => caught)).toMatchObject({ code: 'command_aborted' });
+  });
+
+  it('leaves no listener after a spawn failure', async () => {
+    const controller = new AbortController();
+    await expect(runCommand('/nonexistent/openchamber-no-such-binary', [], { killTree: true, signal: controller.signal })).rejects.toMatchObject({ code: 'command_spawn_failed' });
+    expect(abortListeners(controller.signal)).toBe(0);
+    expect(liveTreeCount()).toBe(0);
+  });
+});

package/server/lib/spaces/space-events.js

@@ -0,0 +1,153 @@
+// One event connection per space, with its own state and its own backoff, attached to the
+// host's event hub after the v2 translation layer: a space's events enter the hub as the
+// host's do, numbered, coalesced, replayed and fanned out, marked with the space's id. They
+// feed the same watcher, so live status, unread marks and notifications work for a space's
+// sessions, and the same browser streams, so a client keeps one cursor for everything.
+//
+// Every event is untrusted and passes the session index first: a directory outside the
+// space's root or a session id of the host's drops it. When a connection is made the host
+// asks the space for its live status and enters it the same way. A gap is reported to the
+// clients as `openchamber:space-stream`, so a client re-reads that one space.
+
+import { Readable } from 'node:stream';
+
+import { z } from 'zod';
+
+import { createUpstreamSseReader } from '../event-stream/upstream-reader.js';
+
+const EVENT_PATH = '/api/event';
+const STATUS_PATH = '/api/sessions/status';
+const STATUS_TIMEOUT_MS = 10_000;
+const MAX_STATUS_BYTES = 4 * 1024 * 1024;
+
+// Backoff between attempts: doubling from one second to a minute, reset by a connection.
+const RECONNECT_BASE_MS = 1_000;
+export const RECONNECT_CAP_MS = 60_000;
+export const reconnectDelayAfter = (failures) => Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** Math.max(0, failures - 1));
+
+// What the host reads of an answer from inside; the rest is carried, not read.
+const liveStatusSchema = z.object({ status: z.enum(['busy', 'idle']) });
+const statusSchema = z.object({ sessions: z.record(z.string(), z.unknown()).default({}) }).passthrough();
+const eventPayloadSchema = z.object({ location: z.object({ directory: z.string() }).passthrough().optional() }).passthrough();
+
+/** Reads a whole body up to a cap, as text. */
+const readBody = (response, cap) => new Promise((resolve, reject) => {
+  const chunks = [];
+  let size = 0;
+  response.on('data', (chunk) => {
+    size += chunk.length;
+    if (size > cap) {
+      response.destroy();
+      reject(new Error(`the answer exceeds ${cap} bytes`));
+      return;
+    }
+    chunks.push(chunk);
+  });
+  response.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+  response.on('error', reject);
+});
+
+/**
+ * `requestInside(spaceId, { path, headers, timeoutMs })` is the dispatcher's; `index` the
+ * session index; `hub` the global event hub. `stallTimeoutMs` and `now` are for the tests.
+ */
+export function createSpaceEventSources({ requestInside, index, hub, logger = console, stallTimeoutMs, now = Date.now }) {
+  const sources = new Map();
+
+  const inject = (spaceId, payload, directory) => hub.injectEvent({ payload, directory, spaceId });
+
+  const announce = (spaceId, status, wasReady) => {
+    inject(spaceId, { type: 'openchamber:space-stream', properties: { spaceId, status, wasReady, timestamp: now() } }, 'global');
+  };
+
+  /** The live status inside, entered as status events, so a busy session shows busy from the first moment. */
+  const seedStatus = async (spaceId) => {
+    const response = await requestInside(spaceId, { path: STATUS_PATH, headers: { accept: 'application/json' }, timeoutMs: STATUS_TIMEOUT_MS });
+    if (response.statusCode !== 200) {
+      response.resume();
+      throw new Error(`status ${response.statusCode}`);
+    }
+    const parsed = statusSchema.safeParse(JSON.parse(await readBody(response, MAX_STATUS_BYTES)));
+    if (!parsed.success) return;
+    for (const [sessionID, state] of Object.entries(parsed.data.sessions)) {
+      const live = liveStatusSchema.safeParse(state);
+      if (!live.success) continue;
+      const payload = { type: 'session.status', data: { sessionID, status: { type: live.data.status } } };
+      if (index.acceptSpaceEvent(spaceId, payload)) inject(spaceId, payload, '');
+    }
+  };
+
+  /** The event stream inside, over the dispatcher's channel, in the shape the reader expects. */
+  const fetchInside = (spaceId) => async (_url, { headers, signal }) => {
+    const response = await requestInside(spaceId, { path: EVENT_PATH, headers });
+    const stop = () => response.destroy();
+    if (signal?.aborted) { stop(); throw new Error('aborted'); }
+    signal?.addEventListener('abort', stop, { once: true });
+    const contentType = String(response.headers['content-type'] ?? '');
+    const ok = response.statusCode === 200 && contentType.includes('text/event-stream');
+    return { ok, status: response.statusCode, body: ok ? Readable.toWeb(response) : null };
+  };
+
+  const start = (spaceId) => {
+    if (sources.has(spaceId)) return;
+    const controller = new AbortController();
+    const source = { failures: 0, everConnected: false, reader: null, controller };
+    source.reader = createUpstreamSseReader({
+      signal: controller.signal,
+      fetchImpl: fetchInside(spaceId),
+      stallTimeoutMs,
+      reconnectDelayMs: () => reconnectDelayAfter(source.failures),
+      buildUrl: () => new URL(`http://space${EVENT_PATH}`),
+      onConnect() {
+        source.failures = 0;
+        const wasReady = source.everConnected;
+        source.everConnected = true;
+        announce(spaceId, 'connected', wasReady);
+        seedStatus(spaceId).catch((error) => logger.warn?.(`[spaces] could not read the status of space ${spaceId}: ${error?.code ?? error?.message ?? error}`));
+      },
+      onDisconnect({ reason }) {
+        source.failures += 1;
+        if (source.everConnected && reason !== 'stopped') announce(spaceId, 'disconnected', true);
+      },
+      onEvent({ payload }) {
+        const parsed = eventPayloadSchema.safeParse(payload);
+        if (!parsed.success || !index.acceptSpaceEvent(spaceId, payload)) return;
+        inject(spaceId, payload, parsed.data.location?.directory ?? '');
+      },
+      // Every failed attempt ends in `onDisconnect`, which is where it is counted.
+      onError(error) {
+        if (controller.signal.aborted) return;
+        logger.warn?.(`[spaces] event stream of space ${spaceId}: ${error?.type ?? 'error'} ${error?.status ?? error?.error?.code ?? ''}`.trim());
+      },
+    });
+    sources.set(spaceId, source);
+    void source.reader.start();
+  };
+
+  const stop = (spaceId) => {
+    const source = sources.get(spaceId);
+    if (!source) return;
+    sources.delete(spaceId);
+    source.controller.abort();
+    source.reader.stop();
+  };
+
+  return {
+    /** Follows the list of spaces: a connection for each new one, none for one that is gone. */
+    sync(spaceIds) {
+      const wanted = new Set(spaceIds);
+      for (const spaceId of Array.from(sources.keys())) {
+        if (!wanted.has(spaceId)) {
+          stop(spaceId);
+          index.forget(spaceId);
+        }
+      }
+      for (const spaceId of wanted) start(spaceId);
+    },
+    /** For the tests: whether a space has a connection right now. */
+    has: (spaceId) => sources.has(spaceId),
+    close() {
+      for (const spaceId of Array.from(sources.keys())) stop(spaceId);
+    },
+  };
+}

package/server/lib/spaces/space-events.test.js

@@ -0,0 +1,160 @@
+// The event connection of a space against a stand-in for the server inside, and the real hub.
+
+import { PassThrough } from 'node:stream';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createGlobalMessageStreamHub } from '../event-stream/global-hub.js';
+import { SpaceError } from './errors.js';
+import { RECONNECT_CAP_MS, createSpaceEventSources, reconnectDelayAfter } from './space-events.js';
+import { createSpaceSessionIndex } from './space-sessions.js';
+
+const ID = 'a1b2c3d4e5f6';
+const OTHER = '0f0f0f0f0f0f';
+const sleep = (ms) => new Promise((resolve) => { setTimeout(resolve, ms); });
+const until = async (check, timeoutMs = 3_000) => {
+  const deadline = Date.now() + timeoutMs;
+  while (!check() && Date.now() < deadline) await sleep(10);
+  return check();
+};
+
+/** A response of the server inside: an SSE stream that the test writes to, or a JSON answer. */
+const sseResponse = () => {
+  const stream = new PassThrough();
+  stream.statusCode = 200;
+  stream.headers = { 'content-type': 'text/event-stream' };
+  return stream;
+};
+const jsonResponse = (status, body) => {
+  const stream = new PassThrough();
+  stream.statusCode = status;
+  stream.headers = { 'content-type': 'application/json' };
+  stream.end(JSON.stringify(body));
+  return stream;
+};
+
+const makeHub = () => createGlobalMessageStreamHub({
+  buildOpenCodeUrl: (path) => `http://127.0.0.1:1${path}`,
+  getOpenCodeAuthHeaders: () => ({}),
+  deltaCoalesceWindowMs: 0,
+  fetchImpl: async () => { throw new Error('the host upstream is not part of this test'); },
+});
+
+describe('reconnectDelayAfter', () => {
+  it('doubles from one second and stops at a minute', () => {
+    expect([0, 1, 2, 3, 4].map(reconnectDelayAfter)).toEqual([1_000, 1_000, 2_000, 4_000, 8_000]);
+    expect(reconnectDelayAfter(20)).toBe(RECONNECT_CAP_MS);
+  });
+});
+
+describe('createSpaceEventSources', () => {
+  const streams = { [ID]: [], [OTHER]: [] };
+  const requests = [];
+  let status = { sessions: {} };
+  let refuse = null;
+  const requestInside = async (spaceId, request) => {
+    requests.push({ spaceId, path: request.path, headers: request.headers });
+    if (refuse) throw refuse;
+    if (request.path === '/api/sessions/status') return jsonResponse(200, status);
+    const stream = sseResponse();
+    streams[spaceId].push(stream);
+    return stream;
+  };
+  const logs = [];
+  const logger = { warn: (line) => logs.push(line) };
+  let hub;
+  let index;
+  let sources;
+  let received;
+
+  const start = () => {
+    hub = makeHub();
+    index = createSpaceSessionIndex({ logger });
+    received = [];
+    hub.subscribeEvent((event) => received.push(event), { spaces: true });
+    sources = createSpaceEventSources({ requestInside, index, hub, logger, stallTimeoutMs: 0 });
+  };
+
+  afterEach(() => {
+    sources?.close();
+    streams[ID].length = 0;
+    streams[OTHER].length = 0;
+    requests.length = 0;
+    logs.length = 0;
+    status = { sessions: {} };
+    refuse = null;
+  });
+
+  it('opens one connection per space, announces it, seeds the live status, and enters the events with the space id', async () => {
+    start();
+    status = { sessions: { busy1: { status: 'busy' }, idle1: { status: 'idle' }, odd: { status: 'retry' } } };
+    sources.sync([ID]);
+    expect(await until(() => streams[ID].length === 1)).toBe(true);
+    expect(requests[0]).toMatchObject({ spaceId: ID, path: '/api/event', headers: expect.objectContaining({ Accept: 'text/event-stream' }) });
+    expect(await until(() => received.length >= 3)).toBe(true);
+    expect(received[0].payload).toMatchObject({ type: 'openchamber:space-stream', properties: { spaceId: ID, status: 'connected', wasReady: false } });
+    expect(received.slice(1).map((event) => [event.payload.type, event.payload.data.sessionID, event.payload.data.status.type])).toEqual([
+      ['session.status', 'busy1', 'busy'],
+      ['session.status', 'idle1', 'idle'],
+    ]);
+
+    streams[ID][0].write(`data: ${JSON.stringify({ id: 'e1', type: 'session.execution.started', data: { sessionID: 's1' }, location: { directory: `/spaces/${ID}/repo` } })}\n\n`);
+    expect(await until(() => received.length === 4)).toBe(true);
+    expect(received[3]).toMatchObject({ spaceId: ID, directory: `/spaces/${ID}/repo`, payload: { id: 'e1' } });
+    expect(received[3].translated()).toEqual([expect.objectContaining({ type: 'session.status', properties: expect.objectContaining({ sessionID: 's1', directory: `/spaces/${ID}/repo` }) })]);
+    expect(sources.has(ID)).toBe(true);
+  });
+
+  it('drops an event that claims a directory outside the space or a session of the host', async () => {
+    start();
+    index.observeHostRecords([{ id: 'host-1' }]);
+    sources.sync([ID]);
+    expect(await until(() => streams[ID].length === 1)).toBe(true);
+    const stream = streams[ID][0];
+    const write = (payload) => stream.write(`data: ${JSON.stringify(payload)}\n\n`);
+    write({ id: 'bad1', type: 'session.execution.started', data: { sessionID: 's1' }, location: { directory: '/home/me/project' } });
+    write({ id: 'bad2', type: 'session.created', data: { sessionID: 's2', location: { directory: `/spaces/${OTHER}/repo` } }, location: { directory: `/spaces/${ID}/repo` } });
+    write({ id: 'bad3', type: 'session.execution.started', data: { sessionID: 'host-1' } });
+    write({ id: 'good', type: 'session.execution.started', data: { sessionID: 's1' } });
+    expect(await until(() => received.some((event) => event.payload.id === 'good'))).toBe(true);
+    expect(received.map((event) => event.payload.id).filter((id) => id?.startsWith('bad'))).toEqual([]);
+    expect(logs.filter((line) => line.includes('dropped an event'))).toHaveLength(3);
+    expect(logs.join('\n')).not.toContain('/home/me/project');
+  });
+
+  it('reconnects with backoff after the stream inside ends, announces the gap, and stops for a space that is gone', async () => {
+    start();
+    sources.sync([ID, OTHER]);
+    expect(await until(() => streams[ID].length === 1 && streams[OTHER].length === 1)).toBe(true);
+    expect(await until(() => received.filter((event) => event.payload.type === 'openchamber:space-stream').length === 2)).toBe(true);
+    streams[ID][0].end();
+    expect(await until(() => received.some((event) => event.payload.properties?.status === 'disconnected' && event.payload.properties?.spaceId === ID))).toBe(true);
+    // The first attempt after the gap waits a second, so it is not there at once.
+    await sleep(300);
+    expect(streams[ID]).toHaveLength(1);
+    expect(await until(() => streams[ID].length === 2, 3_000)).toBe(true);
+    expect(received.filter((event) => event.payload.properties?.spaceId === ID && event.payload.properties?.status === 'connected').at(-1).payload.properties.wasReady).toBe(true);
+    // A second drop in a row waits two seconds, not four: one failure is counted once.
+    const secondDropAt = Date.now();
+    streams[ID][1].end();
+    expect(await until(() => streams[ID].length === 3, 3_500)).toBe(true);
+    expect(Date.now() - secondDropAt).toBeLessThan(3_000);
+
+    index.acceptSpaceList(OTHER, [{ id: 'o1', location: { directory: `/spaces/${OTHER}/repo` } }], { complete: true });
+    sources.sync([ID]);
+    expect(sources.has(OTHER)).toBe(false);
+    expect(index.snapshot().map((entry) => entry.spaceId)).toEqual([]);
+    expect(streams[OTHER][0].destroyed).toBe(true);
+  }, 15_000);
+
+  it('keeps trying, quietly, while the space refuses the connection', async () => {
+    start();
+    refuse = new SpaceError('space_not_running', 'stopped');
+    sources.sync([ID]);
+    expect(await until(() => requests.length >= 1)).toBe(true);
+    await sleep(200);
+    expect(received).toEqual([]);
+    expect(requests.length).toBeLessThanOrEqual(2);
+    expect(logs.some((line) => line.includes(`event stream of space ${ID}`))).toBe(true);
+  });
+});

package/server/lib/spaces/space-opencode.js

@@ -0,0 +1,52 @@
+// The one place that writes OpenCode's own files inside a space, so an OpenCode format change is
+// a one-file edit (DESIGN.md, "Parts"). Today: the provider configuration that sends a provider's
+// model calls through the gatekeeper's window. The login record for the short OpenAI token and
+// the move of a chat to the host's archive belong here too, in their stages.
+//
+// What is written here cooperates and enforces nothing. The agent can change or delete the file;
+// the gatekeeper is what keeps the key out of the space and the space away from the internet.
+
+import { SpaceError } from './errors.js';
+import { tail } from './exec-http.js';
+import { IMAGE_ONLY_PATH, IMAGE_SH, SPACE_OPENCODE_CONFIG_DIRECTORY, SPACE_OPENCODE_CONFIG_PATH, spaceWindowUrl } from './layout.js';
+
+// OpenCode takes a key from this option and its auth plugins stay out of the way; the window
+// throws it away and puts the real one in its place. It is not a secret and never was one.
+export const WINDOW_PLACEHOLDER_KEY = 'space-window';
+
+// Through a temporary name, so OpenCode never reads half a file. The configuration is JSON on
+// stdin: nothing of it is an argument.
+const WRITE_CONFIG_SCRIPT = [
+  IMAGE_ONLY_PATH,
+  `mkdir -p ${SPACE_OPENCODE_CONFIG_DIRECTORY}`,
+  `&& cat > ${SPACE_OPENCODE_CONFIG_PATH}.new && mv ${SPACE_OPENCODE_CONFIG_PATH}.new ${SPACE_OPENCODE_CONFIG_PATH}`,
+].join(' ');
+
+/**
+ * OpenCode's global configuration for a space with these model grants: each provider, under the
+ * id the host's catalog gives it, with its base URL at the window and a placeholder key. The
+ * composer offers the host's catalog, and the same provider id inside is what makes that choice
+ * work in the space unchanged. Decided with the maintainer on 2026-09-26.
+ */
+export function buildProviderConfig(grants) {
+  const provider = {};
+  for (const grant of grants) {
+    if (grant.kind !== 'model') continue;
+    provider[grant.provider] = { options: { baseURL: spaceWindowUrl(grant.id), apiKey: WINDOW_PLACEHOLDER_KEY } };
+  }
+  return { $schema: 'https://opencode.ai/config.json', provider };
+}
+
+/** `exec` is the place operation, always for the space container. */
+export function createSpaceOpenCode({ exec }) {
+  /** Writes the whole global configuration from the model grants the record holds. */
+  const writeProviderConfig = async (spaceId, grants) => {
+    const text = `${JSON.stringify(buildProviderConfig(grants), null, 2)}\n`;
+    const result = await exec(spaceId, [IMAGE_SH, '-c', WRITE_CONFIG_SCRIPT], { stdin: text });
+    if (result.code !== 0) {
+      throw new SpaceError('space_setup_failed', `Could not write the provider configuration inside the space: ${tail(result.stderr) || `exit code ${result.code}`}`);
+    }
+  };
+
+  return { writeProviderConfig };
+}

package/server/lib/spaces/space-opencode.test.js

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import { WINDOW_PLACEHOLDER_KEY, buildProviderConfig, createSpaceOpenCode } from './space-opencode.js';
+
+const ID = 'a1b2c3d4e5f6';
+const GRANTS = [
+  { kind: 'model', id: 'anthropic', provider: 'anthropic', upstream: 'https://api.anthropic.com/v1', header: 'x-api-key', source: { kind: 'typed' } },
+  { kind: 'domain', id: 'open-0a1b2c3d4e5f', upstream: 'https://registry.example.com/npm/' },
+  { kind: 'model', id: 'openai', provider: 'openai', upstream: 'https://api.openai.com/v1', header: 'authorization', source: { kind: 'env', name: 'OPENAI_API_KEY' } },
+];
+
+describe('the provider configuration inside a space', () => {
+  it('names each granted provider as the host does, at the window, with a placeholder key, and leaves domains out', () => {
+    expect(buildProviderConfig(GRANTS)).toEqual({
+      $schema: 'https://opencode.ai/config.json',
+      provider: {
+        anthropic: { options: { baseURL: 'http://gatekeeper:8080/model/anthropic', apiKey: WINDOW_PLACEHOLDER_KEY } },
+        openai: { options: { baseURL: 'http://gatekeeper:8080/model/openai', apiKey: WINDOW_PLACEHOLDER_KEY } },
+      },
+    });
+    expect(buildProviderConfig([])).toEqual({ $schema: 'https://opencode.ai/config.json', provider: {} });
+    // The upstream is the gatekeeper's business; nothing of it is written where the agent reads.
+    expect(JSON.stringify(buildProviderConfig(GRANTS))).not.toContain('api.anthropic.com');
+  });
+
+  it('writes the whole file over exec, as JSON on stdin, through a temporary name', async () => {
+    const calls = [];
+    const opencode = createSpaceOpenCode({ exec: async (spaceId, argv, options) => { calls.push({ spaceId, argv, options }); return { code: 0, stdout: '', stderr: '' }; } });
+    await opencode.writeProviderConfig(ID, GRANTS);
+    expect(calls).toEqual([{
+      spaceId: ID,
+      argv: ['/bin/sh', '-c', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin; mkdir -p /home/space/.config/opencode && cat > /home/space/.config/opencode/opencode.json.new && mv /home/space/.config/opencode/opencode.json.new /home/space/.config/opencode/opencode.json'],
+      options: { stdin: `${JSON.stringify(buildProviderConfig(GRANTS), null, 2)}\n` },
+    }]);
+  });
+
+  it('says what failed inside', async () => {
+    const opencode = createSpaceOpenCode({ exec: async () => ({ code: 1, stdout: '', stderr: 'sh: cannot create: Read-only file system\n' }) });
+    await expect(opencode.writeProviderConfig(ID, GRANTS)).rejects.toMatchObject({ code: 'space_setup_failed', message: expect.stringContaining('Read-only file system') });
+  });
+});