@vantran-se/openchamber-web 1.23.0 → 1.24.3

package/server/lib/guests/updates.test.js

@@ -0,0 +1,334 @@
+import { describe, expect, test } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { findInstalledGuest, listInstalledGuests } from './catalog.js';
+import { isGitRef, parseGitInstallUrl } from './clone.js';
+import { installGuestFromGitSource } from './install.js';
+import { readExtensionStore } from './persist.js';
+import {
+  UPDATE_CHECK_TTL_MS,
+  checkAllGuestUpdates,
+  checkGuestUpdate,
+  clearGuestUpdateCache,
+  compareSemver,
+  getCachedGuestUpdate,
+  updateGuest,
+} from './updates.js';
+
+const git = (cwd, args) => {
+  const result = spawnSync('git', args, {
+    cwd,
+    encoding: 'utf8',
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  }
+  return result.stdout;
+};
+
+const manifest = (id, version, extra = {}) => JSON.stringify({
+  name: `@openchamber/${id}`,
+  version,
+  openchamber: {
+    apiVersion: 1,
+    contributes: {
+      panel: { id, name: id, icon: 'window', entry: 'panel/index.html' },
+      ...extra,
+    },
+  },
+});
+
+const writeGuest = async (root, id, version, extra) => {
+  await fs.mkdir(path.join(root, 'panel'), { recursive: true });
+  await fs.writeFile(path.join(root, 'panel', 'index.html'), '<html></html>');
+  await fs.writeFile(path.join(root, 'package.json'), manifest(id, version, extra));
+};
+
+const commit = (cwd, message) => {
+  git(cwd, ['add', '.']);
+  git(cwd, ['-c', 'user.name=test', '-c', 'user.email=test@example.com', 'commit', '-q', '-m', message]);
+};
+
+/**
+ * A working repo plus a bare "remote" the install clones from, the way a
+ * hosted repository behaves: the bare repo has no working tree and gets new
+ * commits pushed to it.
+ */
+const setupRemote = async (dir, id, version = '1.0.0') => {
+  const work = path.join(dir, 'work');
+  const bare = path.join(dir, 'remote.git');
+  await writeGuest(work, id, version);
+  git(work, ['init', '-q', '--template=', '-b', 'main']);
+  commit(work, 'init');
+  // The bare repo's HEAD must name the branch that gets pushed; without -b
+  // it follows the machine's init.defaultBranch (master on CI), and a clone
+  // of a bare repo whose HEAD points at a missing branch checks out nothing.
+  git(dir, ['init', '-q', '--bare', '--template=', '-b', 'main', bare]);
+  git(work, ['remote', 'add', 'origin', bare]);
+  git(work, ['push', '-q', 'origin', 'main']);
+  return { work, bare };
+};
+
+const pushVersion = async (work, id, version, extra) => {
+  await fs.writeFile(path.join(work, 'package.json'), manifest(id, version, extra));
+  commit(work, `v${version}`);
+  git(work, ['push', '-q', 'origin', 'HEAD']);
+};
+
+const installFrom = async (bare, persistPath, ref) => {
+  const installed = await installGuestFromGitSource(bare, persistPath, { openchamberVersion: '1.30.0', ref });
+  if (!installed.ok) {
+    throw new Error(`install failed: ${installed.code}`);
+  }
+  return installed.guest;
+};
+
+const loadGuest = async (id, persistPath) => {
+  const guest = await findInstalledGuest(id, persistPath);
+  if (!guest) {
+    throw new Error(`guest ${id} missing`);
+  }
+  return guest;
+};
+
+describe('compareSemver', () => {
+  test('orders releases and puts prereleases below their release', () => {
+    expect(compareSemver('1.0.0', '1.0.0')).toBe(0);
+    expect(compareSemver('1.0.0', '1.0.1')).toBe(-1);
+    expect(compareSemver('1.10.0', '1.9.0')).toBe(1);
+    expect(compareSemver('2.0.0', '1.99.99')).toBe(1);
+    expect(compareSemver('1.1.0-beta.1', '1.1.0')).toBe(-1);
+    expect(compareSemver('1.1.0', '1.1.0-rc.1')).toBe(1);
+    expect(compareSemver('1.1.0-alpha', '1.1.0-beta')).toBe(-1);
+    expect(compareSemver('1.1.0-beta.2', '1.1.0-beta.10')).toBe(-1);
+    expect(compareSemver('1.1.0-beta', '1.1.0-beta.1')).toBe(-1);
+    expect(compareSemver('1.0.0+build.1', '1.0.0')).toBe(0);
+    expect(compareSemver('v1.0.0', '1.0.0')).toBeNull();
+    expect(compareSemver('1.0', '1.0.0')).toBeNull();
+  });
+});
+
+describe('parseGitInstallUrl', () => {
+  test('splits a #ref and refuses unusable refs', () => {
+    expect(parseGitInstallUrl('https://github.com/acme/panel.git')).toEqual({ url: 'https://github.com/acme/panel.git' });
+    expect(parseGitInstallUrl('https://github.com/acme/panel.git#v1.2.0')).toEqual({
+      url: 'https://github.com/acme/panel.git',
+      ref: 'v1.2.0',
+    });
+    expect(parseGitInstallUrl('https://github.com/acme/panel#release/2.x')).toEqual({
+      url: 'https://github.com/acme/panel',
+      ref: 'release/2.x',
+    });
+    expect(parseGitInstallUrl('https://github.com/acme/panel.git#')).toBeNull();
+    expect(parseGitInstallUrl('https://github.com/acme/panel.git#--upload-pack=evil')).toBeNull();
+    expect(parseGitInstallUrl('https://github.com/acme/panel.git#a..b')).toBeNull();
+    expect(parseGitInstallUrl('https://localhost/panel.git#main')).toBeNull();
+    expect(parseGitInstallUrl('http://github.com/acme/panel.git#main')).toBeNull();
+    expect(isGitRef('main')).toBe(true);
+    expect(isGitRef('-x')).toBe(false);
+    expect(isGitRef('feature/')).toBe(false);
+    expect(isGitRef('a//b')).toBe(false);
+  });
+});
+
+describe('checkGuestUpdate', () => {
+  test('reports a newer remote version and stays quiet on the same one', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-upd-'));
+    const persistPath = path.join(dir, 'data', 'extensions.json');
+    const { work, bare } = await setupRemote(dir, 'upd-hello');
+    await installFrom(bare, persistPath);
+    const guest = await loadGuest('upd-hello', persistPath);
+    expect(guest.gitOrigin).toEqual({ url: bare });
+    expect((await readExtensionStore(persistPath)).gitOrigins).toEqual({ [guest.packageRoot]: { url: bare } });
+
+    const same = await checkGuestUpdate({ guest, origin: guest.gitOrigin });
+    expect(same).toEqual({ available: false, version: '1.0.0' });
+
+    await pushVersion(work, 'upd-hello', '1.1.0', { capabilities: ['prompt'], filesystem: ['~/notes/**'] });
+    const newer = await checkGuestUpdate({ guest, origin: guest.gitOrigin });
+    expect(newer).toEqual({ available: true, version: '1.1.0', requested: ['prompt', 'filesystem'] });
+
+    await pushVersion(work, 'upd-hello', '1.0.1');
+    const older = await checkGuestUpdate({ guest: { ...guest, version: '1.2.0' }, origin: guest.gitOrigin });
+    expect(older).toEqual({ available: false, version: '1.0.1' });
+
+    await pushVersion(work, 'upd-hello', '2.0.0-beta.1');
+    const pre = await checkGuestUpdate({ guest, origin: guest.gitOrigin });
+    expect(pre).toEqual({ available: true, version: '2.0.0-beta.1', requested: [] });
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('follows a pinned tag and never throws on a broken remote', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-upd-'));
+    const persistPath = path.join(dir, 'data', 'extensions.json');
+    const { work, bare } = await setupRemote(dir, 'upd-tag');
+    git(work, ['tag', 'stable']);
+    git(work, ['push', '-q', 'origin', 'stable']);
+    await installFrom(bare, persistPath, 'stable');
+    const guest = await loadGuest('upd-tag', persistPath);
+    expect(guest.gitOrigin).toEqual({ url: bare, ref: 'stable' });
+
+    // main moves ahead; the tag does not.
+    await pushVersion(work, 'upd-tag', '1.5.0');
+    expect(await checkGuestUpdate({ guest, origin: guest.gitOrigin })).toEqual({ available: false, version: '1.0.0' });
+
+    git(work, ['tag', '-f', 'stable']);
+    git(work, ['push', '-q', '-f', 'origin', 'stable']);
+    expect(await checkGuestUpdate({ guest, origin: guest.gitOrigin })).toEqual({ available: true, version: '1.5.0', requested: [] });
+
+    await fs.rm(bare, { recursive: true, force: true });
+    expect(await checkGuestUpdate({ guest, origin: guest.gitOrigin })).toEqual({ available: false, error: 'fetch-failed' });
+    expect(await checkGuestUpdate({ guest, origin: undefined })).toEqual({ available: false, error: 'not-git' });
+    expect(await checkGuestUpdate({ guest, origin: { url: bare }, gitBinary: '/nonexistent/git' })).toEqual({ available: false, error: 'fetch-failed' });
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('checkAllGuestUpdates', () => {
+  test('caches per guest for an hour unless forced and feeds the catalog row', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-upd-'));
+    const persistPath = path.join(dir, 'data', 'extensions.json');
+    const { work, bare } = await setupRemote(dir, 'upd-cache');
+    await installFrom(bare, persistPath);
+    const start = Date.now();
+
+    expect(await checkAllGuestUpdates({ persistPath, now: start })).toEqual({});
+    await pushVersion(work, 'upd-cache', '1.1.0');
+    // Inside the hour: the stale answer stands.
+    expect(await checkAllGuestUpdates({ persistPath, now: start + UPDATE_CHECK_TTL_MS - 1 })).toEqual({});
+    expect(getCachedGuestUpdate(persistPath, 'upd-cache')).toBeNull();
+    // Forced: the network is asked again.
+    expect(await checkAllGuestUpdates({ persistPath, force: true, now: start + 1 })).toEqual({ 'upd-cache': { version: '1.1.0' } });
+    expect(getCachedGuestUpdate(persistPath, 'upd-cache')).toEqual({ version: '1.1.0' });
+    // After the hour: refreshed on its own.
+    await pushVersion(work, 'upd-cache', '1.2.0');
+    expect(await checkAllGuestUpdates({ persistPath, now: start + 1 + UPDATE_CHECK_TTL_MS })).toEqual({ 'upd-cache': { version: '1.2.0' } });
+
+    clearGuestUpdateCache(persistPath, 'upd-cache');
+    expect(getCachedGuestUpdate(persistPath, 'upd-cache')).toBeNull();
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});
+
+describe('updateGuest', () => {
+  test('swaps in the new clone and keeps grants, then reports a new version', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-upd-'));
+    const persistPath = path.join(dir, 'data', 'extensions.json');
+    const { work, bare } = await setupRemote(dir, 'upd-swap');
+    await installFrom(bare, persistPath);
+    const before = await loadGuest('upd-swap', persistPath);
+    const store = await readExtensionStore(persistPath);
+    await fs.writeFile(persistPath, `${JSON.stringify({
+      paths: store.paths,
+      sources: store.sources,
+      gitOrigins: store.gitOrigins,
+      capabilityGrants: { 'upd-swap': ['prompt'] },
+      disabledGuests: { 'upd-swap': true },
+    })}\n`);
+
+    await pushVersion(work, 'upd-swap', '1.1.0', { capabilities: ['prompt', 'sessions'] });
+    await checkAllGuestUpdates({ persistPath, force: true });
+    expect(getCachedGuestUpdate(persistPath, 'upd-swap')).toEqual({ version: '1.1.0' });
+
+    const updated = await updateGuest({ guest: before, origin: before.gitOrigin, persistPath, openchamberVersion: '1.30.0' });
+    expect(updated).toEqual({ ok: true, id: 'upd-swap' });
+
+    const after = await loadGuest('upd-swap', persistPath);
+    expect(after.version).toBe('1.1.0');
+    expect(after.packageRoot).toBe(before.packageRoot);
+    expect(after.gitOrigin).toEqual({ url: bare });
+    expect(after.capabilityGrants).toEqual(['prompt']);
+    expect(after.enabled).toBe(false);
+    expect(after.capabilities).toEqual(['prompt', 'sessions']);
+    expect(getCachedGuestUpdate(persistPath, 'upd-swap')).toBeNull();
+    const leftovers = (await fs.readdir(path.dirname(before.packageRoot))).filter((name) => name.startsWith('.'));
+    expect(leftovers).toEqual([]);
+    expect((await readExtensionStore(persistPath)).paths).toEqual([before.packageRoot]);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('a failure before the swap leaves the install untouched', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-upd-'));
+    const persistPath = path.join(dir, 'data', 'extensions.json');
+    const { work, bare } = await setupRemote(dir, 'upd-keep');
+    await installFrom(bare, persistPath);
+    const guest = await loadGuest('upd-keep', persistPath);
+    const copiesDir = path.dirname(guest.packageRoot);
+    const noLeftovers = async () => {
+      const names = (await fs.readdir(copiesDir)).filter((name) => name.startsWith('.'));
+      expect(names).toEqual([]);
+    };
+
+    // Remote now needs a host this build does not have.
+    await fs.writeFile(path.join(work, 'package.json'), JSON.stringify({
+      name: '@openchamber/upd-keep',
+      version: '1.1.0',
+      openchamber: {
+        apiVersion: 1,
+        engines: { openchamber: '>=9.9.9' },
+        contributes: { panel: { id: 'upd-keep', name: 'Keep', icon: 'window', entry: 'panel/index.html' } },
+      },
+    }));
+    commit(work, 'needs newer host');
+    git(work, ['push', '-q', 'origin', 'HEAD']);
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, openchamberVersion: '1.30.0' })).toEqual({
+      ok: false,
+      code: 'host-too-old',
+      required: '9.9.9',
+    });
+    await noLeftovers();
+    expect((await loadGuest('upd-keep', persistPath)).version).toBe('1.0.0');
+
+    // Remote now ships an unbuilt panel.
+    await fs.writeFile(path.join(work, 'package.json'), manifest('upd-keep', '1.2.0'));
+    await fs.writeFile(path.join(work, 'panel', 'index.html'), '<script src="./main.js"></script>');
+    commit(work, 'unbuilt');
+    git(work, ['push', '-q', 'origin', 'HEAD']);
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, openchamberVersion: '1.30.0' })).toEqual({
+      ok: false,
+      code: 'missing-build',
+    });
+    await noLeftovers();
+
+    // Remote renamed the panel: not an update of this extension.
+    await fs.writeFile(path.join(work, 'package.json'), manifest('other-id', '1.3.0'));
+    await fs.writeFile(path.join(work, 'panel', 'index.html'), '<html></html>');
+    commit(work, 'renamed');
+    git(work, ['push', '-q', 'origin', 'HEAD']);
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, openchamberVersion: '1.30.0' })).toEqual({
+      ok: false,
+      code: 'invalid-manifest',
+    });
+    await noLeftovers();
+
+    // Remote is gone.
+    await fs.rm(bare, { recursive: true, force: true });
+    expect(await updateGuest({ guest, origin: guest.gitOrigin, persistPath, openchamberVersion: '1.30.0' })).toEqual({
+      ok: false,
+      code: 'clone-failed',
+    });
+    await noLeftovers();
+
+    // Folder installs never update.
+    expect(await updateGuest({ guest: { ...guest, source: 'path' }, origin: guest.gitOrigin, persistPath })).toEqual({
+      ok: false,
+      code: 'not-git',
+    });
+
+    const still = await loadGuest('upd-keep', persistPath);
+    expect(still.version).toBe('1.0.0');
+    expect(still.packageRoot).toBe(guest.packageRoot);
+    expect(await fs.readFile(path.join(guest.packageRoot, 'panel', 'index.html'), 'utf8')).toBe('<html></html>');
+    expect((await listInstalledGuests({ persistPath })).map((entry) => entry.id)).toEqual(['upd-keep']);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});

package/server/lib/guests/upload.js

@@ -0,0 +1,50 @@
+/**
+ * Body handling for `POST /api/guests/upload`: a raw zip sent as
+ * `application/octet-stream`. The archive is collected into memory (the
+ * install path works on a buffer) under a configurable cap, so a remote or
+ * web user can add an extension without a path on the server. Nothing from
+ * the archive is ever logged.
+ */
+
+const DEFAULT_UPLOAD_MAX_BYTES = 50 * 1024 * 1024;
+
+export const guestUploadMaxBytes = () => {
+  const raw = Number(process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES);
+  if (Number.isFinite(raw) && raw > 0) return Math.floor(raw);
+  return DEFAULT_UPLOAD_MAX_BYTES;
+};
+
+const isOctetStream = (contentType) => (
+  String(contentType || '').toLowerCase().startsWith('application/octet-stream')
+);
+
+/**
+ * Reads the upload body. `req` is the Express request (headers plus an
+ * async-iterable body). Answers `{ ok: true, buffer }`, or `{ ok: false,
+ * status, error }` with 415 for a wrong content type and 413 when either the
+ * declared `Content-Length` or the bytes actually received pass `maxBytes`.
+ * The declared-size refusal drains the request so the socket stays reusable.
+ */
+export const readGuestUploadBody = async (req, maxBytes) => {
+  if (!isOctetStream(req.headers?.['content-type'])) {
+    req.resume?.();
+    return { ok: false, status: 415, error: 'unsupported-media-type' };
+  }
+  const declaredSize = Number(req.headers?.['content-length']);
+  if (Number.isFinite(declaredSize) && declaredSize > maxBytes) {
+    req.resume?.();
+    return { ok: false, status: 413, error: 'too-large' };
+  }
+  const chunks = [];
+  let received = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    received += buffer.length;
+    if (received > maxBytes) {
+      req.resume?.();
+      return { ok: false, status: 413, error: 'too-large' };
+    }
+    chunks.push(buffer);
+  }
+  return { ok: true, buffer: Buffer.concat(chunks, received) };
+};

package/server/lib/guests/upload.test.js

@@ -0,0 +1,131 @@
+import { describe, expect, test } from 'bun:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { listInstalledGuests } from './catalog.js';
+import { buildStoreZip } from './extract-zip.test.js';
+import { installGuestFromZipBuffer } from './install.js';
+import { guestCopiesDir } from './persist.js';
+import { guestUploadMaxBytes, readGuestUploadBody } from './upload.js';
+
+const fakeRequest = ({ headers = {}, chunks = [] } = {}) => {
+  let resumed = false;
+  return {
+    headers: { 'content-type': 'application/octet-stream', ...headers },
+    resume: () => {
+      resumed = true;
+    },
+    wasResumed: () => resumed,
+    async *[Symbol.asyncIterator]() {
+      for (const chunk of chunks) {
+        yield chunk;
+      }
+    },
+  };
+};
+
+const guestZip = (id) => buildStoreZip([
+  { name: 'package.json', data: JSON.stringify({
+    name: `@openchamber/${id}`,
+    version: '1.0.0',
+    openchamber: {
+      apiVersion: 1,
+      contributes: {
+        panel: { id, name: 'Uploaded', icon: 'window', entry: 'panel/index.html' },
+      },
+    },
+  }) },
+  { name: 'panel/index.html', data: '<html></html>' },
+]);
+
+describe('readGuestUploadBody', () => {
+  test('collects an octet-stream body under the cap', async () => {
+    const req = fakeRequest({ chunks: [Buffer.from('ab'), Buffer.from('cd')] });
+    const body = await readGuestUploadBody(req, 10);
+    expect(body).toEqual({ ok: true, buffer: Buffer.from('abcd') });
+  });
+
+  test('refuses a wrong content type without reading the body', async () => {
+    const req = fakeRequest({ headers: { 'content-type': 'multipart/form-data' }, chunks: [Buffer.from('abcd')] });
+    const body = await readGuestUploadBody(req, 10);
+    expect(body).toEqual({ ok: false, status: 415, error: 'unsupported-media-type' });
+    expect(req.wasResumed()).toBe(true);
+  });
+
+  test('refuses a declared size over the cap before reading', async () => {
+    const req = fakeRequest({ headers: { 'content-length': '11' }, chunks: [Buffer.from('abcd')] });
+    const body = await readGuestUploadBody(req, 10);
+    expect(body).toEqual({ ok: false, status: 413, error: 'too-large' });
+    expect(req.wasResumed()).toBe(true);
+  });
+
+  test('stops a body that grows past the cap without a declared size', async () => {
+    const req = fakeRequest({ chunks: [Buffer.from('12345'), Buffer.from('678901')] });
+    const body = await readGuestUploadBody(req, 10);
+    expect(body).toEqual({ ok: false, status: 413, error: 'too-large' });
+  });
+
+  test('reads the cap from the environment', () => {
+    const previous = process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES;
+    try {
+      delete process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES;
+      expect(guestUploadMaxBytes()).toBe(50 * 1024 * 1024);
+      process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES = '1234';
+      expect(guestUploadMaxBytes()).toBe(1234);
+      process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES = 'nope';
+      expect(guestUploadMaxBytes()).toBe(50 * 1024 * 1024);
+    } finally {
+      if (previous === undefined) delete process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES;
+      else process.env.OPENCHAMBER_GUEST_UPLOAD_MAX_BYTES = previous;
+    }
+  });
+});
+
+describe('installGuestFromZipBuffer', () => {
+  test('installs from bytes, lists with source zip, and reinstalls only with replace', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-ext-upload-'));
+    const persistPath = path.join(dir, 'extensions.json');
+    const buffer = guestZip('upload-hello');
+
+    const installed = await installGuestFromZipBuffer(buffer, persistPath);
+    expect(installed.ok).toBe(true);
+    if (!installed.ok) {
+      throw new Error('expected upload install');
+    }
+    expect(installed.guest.id).toBe('upload-hello');
+    expect(installed.guest.source).toBe('zip');
+    expect(installed.replaced).toBe(false);
+    const copy = path.join(guestCopiesDir(persistPath), 'upload-hello');
+    expect(await fs.stat(path.join(copy, 'package.json')).then((stat) => stat.isFile())).toBe(true);
+
+    const listed = await listInstalledGuests({ persistPath });
+    expect(listed.map((guest) => [guest.id, guest.source])).toEqual([['upload-hello', 'zip']]);
+
+    const again = await installGuestFromZipBuffer(buffer, persistPath);
+    expect(again).toEqual({ ok: false, code: 'already-installed', id: 'upload-hello' });
+
+    const replaced = await installGuestFromZipBuffer(buffer, persistPath, { replace: true });
+    expect(replaced.ok).toBe(true);
+    if (!replaced.ok) {
+      throw new Error('expected replace');
+    }
+    expect(replaced.replaced).toBe(true);
+    expect((await listInstalledGuests({ persistPath })).length).toBe(1);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  test('answers extract-failed for bytes that are not a zip and leaves nothing behind', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-ext-upload-'));
+    const persistPath = path.join(dir, 'extensions.json');
+
+    const result = await installGuestFromZipBuffer(Buffer.from('this is a text file, not a zip'), persistPath);
+    expect(result).toEqual({ ok: false, code: 'extract-failed' });
+    expect(await listInstalledGuests({ persistPath })).toEqual([]);
+    const leftovers = await fs.readdir(guestCopiesDir(persistPath)).catch(() => []);
+    expect(leftovers).toEqual([]);
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+});

package/server/lib/linear/DOCUMENTATION.md

@@ -28,7 +28,7 @@ VS Code omits Linear (`RuntimeAPIs.linear` is optional). Hide Linear UI when the
 - `POST /api/linear/auth/activate`: body `{ organizationId }`. Makes that stored workspace current. 400 if the id is missing, 404 if it is not stored.
 - `DELETE /api/linear/auth`: revokes the current workspace refresh token when present, then drops that workspace only. Other stored workspaces stay. Mapping is kept.
 - `GET /api/linear/issues/list?query=&cursor=&status=&assignee=&teamId=&priority=`: issues from the current workspace. Omitted `status` is incomplete states (same as the chat picker). The panel sends `all`, `backlog`, `todo` (Linear `unstarted`), `started` (In Progress, excluding the In Review name), `inReview` (state name In Review), `completed` (Done), `canceled` (excluding the Duplicate name), or `duplicate` (state type or name Duplicate). `assignee` is `any` (default) or `me`. `teamId` limits the list to that Linear team. `priority` is `all` (default), `none`, `urgent`, `high`, `medium`, or `low`. An identifier or Linear URL returns that issue even if it is completed and ignores the other filters. Each issue includes `state.id` when Linear sends it, plus `priority` (0 none through 4 low) and `labels`. Never returns tokens.
-- `GET /api/linear/issues/get?id=`: one issue by UUID or identifier, including description, comments, team, `state.id`, priority, and labels.
+- `GET /api/linear/issues/get?id=`: one issue by UUID or identifier, including description, comments, team, `state.id`, priority, and labels. The host Linear guest panel uses this route for the issue card so comment images keep public file URLs. Guest request does not add Linear headers.
 - `GET /api/linear/issues/states?teamId=`: workflow states for that Linear team (`id`, `name`, `type`, `position`), ordered like Linear's workflow: type (backlog, unstarted, started, completed, canceled) then position. Missing `teamId` is 400. Linear not-found or validation errors are 400 with Linear's presentable message. Disconnected is `{ connected: false }` with HTTP 200.
 - `POST /api/linear/issues/update`: body `{ id, stateId }`. `id` may be a UUID, identifier, or Linear URL; identifiers are resolved before `issueUpdate` because Linear's mutation requires a UUID. Returns the updated issue. Closing an issue is this same call with the team's first `type: completed` state. Missing `id` or `stateId` is 400. Linear validation (for example a non-UUID `stateId`) is 400 with Linear's presentable message. A GraphQL 401 clears that workspace only. Disconnected is `{ connected: false }` with HTTP 200.
 - `GET /api/linear/mapping`: stored default project plus live Linear teams with their mapped paths. Missing file is empty mapping. Malformed file is 500, not empty success. Disconnected is `{ connected: false }` with HTTP 200.

package/server/lib/message-queue/DOCUMENTATION.md

@@ -22,6 +22,12 @@ session-knowledge runtime; routes registered in
 JSON bodies enabled in `opencode/core-routes.js`; stopped by
 `opencode/shutdown-runtime.js`.
 
+## Auto routing
+
+`resolvePromptBody` (the routing runtime) runs on the assembled body right
+before the prompt or command send, turning a queued `openchamber/auto` model
+into a real one. The queue captures the sentinel like any other send config.
+
 ## Item
 
 An item is what the UI would have sent itself, captured at queue time so the
@@ -31,6 +37,7 @@ send never re-resolves mutable UI state:
 {
   id, createdAt,
   content,        // raw text for display and editing
+  contextPreview?, // bounded display-only summary captured by the UI
   text,           // text to deliver (agent mention stripped, file mentions resolved); defaults to content
   agentMention?,  // delivered as an `agent` part
   attachments: [{ id, filename, mimeType, size, source, serverPath?, dataUrl }],
@@ -56,6 +63,12 @@ context entry). Public snapshots and broadcasts strip the payloads —
 attachment `dataUrl` (megabytes of base64) and `context` (a PR diff, say) —
 so they do not ride every update; the only way to get them back is a `take`.
 
+Snapshots retain `contextPreview`, capped at 100 characters plus an ellipsis.
+It carries the attached comment or context label when `content` is empty and
+never replaces editable text or delivered parts. Older items without a summary
+derive one from the attached comment metadata or the first non-instruction
+context text. This optional field needs no queue-file migration.
+
 ## Persistence
 
 `<data-dir>/message-queue.json` (`OPENCHAMBER_DATA_DIR` or
@@ -91,7 +104,10 @@ persisted "sending" flag would strand a message forever.
    next one: `GET /session/status` must not list the session as busy/retry,
    and the trailing message must not be an unfinished assistant reply (the
    status map only lists busy sessions, so a missed busy event leaves no
-   entry while a turn still streams). A failed fetch is unknown, never idle:
+   entry while a turn still streams). An unfinished reply created before this
+   runtime started does not block: its run died with the previous server and
+   will never complete, so a restored queue would wait on it forever. A reply
+   with no `created` time still blocks. A failed fetch is unknown, never idle:
    the tick re-arms with backoff.
 5. The head is marked in flight (broadcast), then sent:
    - text starting with `/` that names a command in OpenCode's `/command`

package/server/lib/message-queue/runtime.js

@@ -133,6 +133,8 @@ export const parseQueuedItemInput = (value) => {
   if (agentMention) item.agentMention = agentMention;
   item.attachments = attachments;
   item.context = context;
+  const contextPreview = asNonEmptyString(raw.contextPreview).slice(0, 103);
+  if (contextPreview) item.contextPreview = contextPreview;
   item.sendConfig = sendConfig;
   return item;
 };
@@ -157,6 +159,17 @@ const toPublicItem = (item) => {
   const publicItem = { id: item.id, createdAt: item.createdAt, content: item.content, text: item.text };
   if (item.agentMention) publicItem.agentMention = item.agentMention;
   publicItem.attachments = item.attachments.map(toPublicAttachment);
+  // Older persisted items have no UI summary. Prefer their attached comment
+  // before falling back to the model-facing context text.
+  const contextPreview = item.contextPreview || item.context
+    .filter((part) => part.kind !== 'instruction')
+    .map((part) => asNonEmptyString(asRecord(part.metadata?.openchamberContext)?.text) || part.text.trim())
+    .find(Boolean);
+  if (contextPreview) {
+    const firstLine = contextPreview.split('\n', 1)[0];
+    publicItem.contextPreview = firstLine.slice(0, 100)
+      + (contextPreview.length > firstLine.length || firstLine.length > 100 ? '...' : '');
+  }
   publicItem.sendConfig = { ...item.sendConfig };
   return publicItem;
 };
@@ -198,6 +211,9 @@ export function createMessageQueueRuntime({
   sessionKnowledgeRuntime = null,
   broadcastGlobalUiEvent,
   onPromptSent,
+  // Turns the `openchamber/auto` model into a real one right before the send;
+  // absent means the queue never sees the sentinel.
+  resolvePromptBody = null,
   dataDir,
   fetchImpl = fetch,
   now = Date.now,
@@ -214,6 +230,13 @@ export function createMessageQueueRuntime({
   let writePromise = Promise.resolve();
   let stopped = false;
 
+  // An unfinished assistant message older than this marker is a run that died
+  // with the previous server, not a streaming turn: no completion event will
+  // ever arrive for it, so treating it as live strands restored queue items
+  // forever. A run that outlived the restart (external OpenCode) is still
+  // caught by the live status check, which runs first.
+  const runtimeStartedAt = now();
+
   /** In-memory only — a restart has no in-flight sends. */
   const sending = new Map(); // sessionId → itemId
   const timers = new Map(); // sessionId → timeout
@@ -380,7 +403,15 @@ export function createMessageQueueRuntime({
     }).catch(() => null));
     if (!messages) return null;
     const last = asRecord(asRecord(messages[messages.length - 1])?.info);
-    if (last?.role === 'assistant' && asCount(asRecord(last.time)?.completed) === null) return false;
+    const lastTime = asRecord(last?.time);
+    if (last?.role === 'assistant' && asCount(lastTime?.completed) === null) {
+      const created = asCount(lastTime?.created);
+      if (created === null || created >= runtimeStartedAt) return false;
+      // Unfinished tail from before this runtime started: its run died with
+      // the previous server, so it must not block delivery. (A missing
+      // created timestamp stays conservative and blocks, as before.)
+      console.log(`[message-queue] ignoring pre-boot unfinished tail for ${sessionId}`);
+    }
     return true;
   };
 
@@ -456,6 +487,7 @@ export function createMessageQueueRuntime({
       if (agent) body.agent = agent;
       if (variant) body.variant = variant;
       if (fileParts.length > 0) body.parts = fileParts;
+      await resolvePromptBody?.(body, { sessionId, directory });
       await openCodeFetch(`/session/${encodeURIComponent(sessionId)}/command`, { directory, method: 'POST', body });
       return;
     }
@@ -490,6 +522,7 @@ export function createMessageQueueRuntime({
     if (agent) body.agent = agent;
     if (variant) body.variant = variant;
     body.parts = parts;
+    await resolvePromptBody?.(body, { sessionId, directory });
     await openCodeFetch(`/session/${encodeURIComponent(sessionId)}/prompt_async`, { directory, method: 'POST', body });
     if (knowledge.text && sessionKnowledgeRuntime) {
       // After the prompt is accepted, so a rejected dispatch carries it again.