@vantran-se/openchamber-web 1.22.1 → 1.22.2

package/server/lib/git/service.test.js

@@ -12,6 +12,7 @@ import {
   createWorktree,
   getWorktreeBootstrapStatus,
   getBranches,
+  getUnpushedBranchCounts,
   getRangeDiff,
   getStatus,
   getWorktrees,
@@ -54,6 +55,14 @@ const runGit = (cwd, args) =>
     stdio: ['ignore', 'pipe', 'pipe'],
   });
 
+const readBranchConfig = (cwd, branch, key) => {
+  try {
+    return runGit(cwd, ['config', '--get', `branch.${branch}.${key}`]).trim();
+  } catch {
+    return '';
+  }
+};
+
 /**
  * A repository on `next` whose only remote publishes `defaultBranch` and has it
  * recorded as that remote's HEAD — the shape of every repository whose default
@@ -508,6 +517,24 @@ describe('getWorktrees', () => {
     expect(Array.isArray(result)).toBe(true);
     expect(warnSpy).not.toHaveBeenCalled();
   });
+  it('flags a worktree whose directory was deleted outside git as prunable', async () => {
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    runGit(repo, ['commit', '--allow-empty', '-m', 'init']);
+    const worktreePath = path.join(createTempDir(), 'feature');
+    runGit(repo, ['worktree', 'add', worktreePath, '-b', 'feature']);
+
+    const before = await getWorktrees(repo);
+    expect(before.find((entry) => entry.branch === 'feature')).toMatchObject({ prunable: false });
+
+    fs.rmSync(worktreePath, { recursive: true, force: true });
+
+    const after = await getWorktrees(repo);
+    expect(after.find((entry) => entry.branch === 'feature')).toMatchObject({ path: expect.any(String), prunable: true });
+    expect(after.find((entry) => entry.branch === 'main')).toMatchObject({ prunable: false });
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -854,6 +881,135 @@ describe('createWorktree', () => {
       }
     }
   });
+
+  it('does not auto-track the remote start ref when creating a new branch from it', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const { repository } = createRepositoryWithRemote({ defaultBranch: 'main' });
+
+      const created = await createWorktree(repository, {
+        mode: 'new',
+        branchName: 'openchamber/feature',
+        worktreeName: 'feature-wt',
+        startRef: 'remotes/origin/main',
+        setUpstream: true,
+        upstreamRemote: 'origin',
+        upstreamBranch: 'openchamber/feature',
+      });
+
+      expect(created.branch).toBe('openchamber/feature');
+
+      await expect.poll(
+        () => getWorktreeBootstrapStatus(created.path).then((status) => status.status === 'ready' || status.status === 'failed'),
+        { timeout: 5_000 }
+      ).toBe(true);
+
+      expect(readBranchConfig(created.path, 'openchamber/feature', 'remote')).toBe('');
+      expect(readBranchConfig(created.path, 'openchamber/feature', 'merge')).toBe('');
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  }, 30_000);
+
+  it('falls back to the remote start ref for upstream tracking when no explicit keys are given', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const { repository } = createRepositoryWithRemote({ defaultBranch: 'main' });
+
+      const created = await createWorktree(repository, {
+        mode: 'new',
+        branchName: 'openchamber/fallback-wt',
+        worktreeName: 'fallback-wt',
+        startRef: 'remotes/origin/main',
+        setUpstream: true,
+      });
+
+      await expect.poll(
+        () => readBranchConfig(created.path, 'openchamber/fallback-wt', 'merge'),
+        { timeout: 5_000 }
+      ).toBe('refs/heads/main');
+      expect(readBranchConfig(created.path, 'openchamber/fallback-wt', 'remote')).toBe('origin');
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  }, 30_000);
+
+  it('falls back to the tracked local branch when the source fetch fails', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const { repository } = createRepositoryWithRemote({ defaultBranch: 'main' });
+      runGit(repository, ['branch', '--set-upstream-to=origin/main', 'next']);
+      runGit(repository, ['remote', 'set-url', 'origin', '/nonexistent/openchamber-unreachable.git']);
+
+      const created = await createWorktree(repository, {
+        mode: 'new',
+        branchName: 'openchamber/stale-ref-wt',
+        worktreeName: 'stale-ref-wt',
+        startRef: 'remotes/origin/main',
+      });
+
+      expect(created.branch).toBe('openchamber/stale-ref-wt');
+      expect(created.sourceFetchFailed).toBe(true);
+      const expectedHead = runGit(repository, ['rev-parse', 'next']).trim();
+      expect(runGit(created.path, ['rev-parse', 'HEAD']).trim()).toBe(expectedHead);
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  }, 30_000);
+
+  it('rejects creation from a remote start ref that was never fetched and cannot be fetched', async () => {
+    if (!canRunGit()) return;
+
+    const previousXdgDataHome = process.env.XDG_DATA_HOME;
+    const dataHome = createTempDir();
+    process.env.XDG_DATA_HOME = dataHome;
+
+    try {
+      const { repository } = createRepositoryWithRemote({ defaultBranch: 'main' });
+      runGit(repository, ['update-ref', '-d', 'refs/remotes/origin/main']);
+      runGit(repository, ['remote', 'set-url', 'origin', '/nonexistent/openchamber-unreachable.git']);
+
+      await expect(createWorktree(repository, {
+        mode: 'new',
+        branchName: 'openchamber/never-fetched-wt',
+        worktreeName: 'never-fetched-wt',
+        startRef: 'remotes/origin/main',
+      })).rejects.toThrow(/does not appear to be a git repository|Could not read from remote repository/i);
+    } finally {
+      if (previousXdgDataHome === undefined) {
+        delete process.env.XDG_DATA_HOME;
+      } else {
+        process.env.XDG_DATA_HOME = previousXdgDataHome;
+      }
+    }
+  }, 30_000);
 });
 
 // ---------------------------------------------------------------------------
@@ -1498,6 +1654,21 @@ describe.runIf(canRunGit())('getBranches', () => {
   });
 });
 
+describe.runIf(canRunGit())('getUnpushedBranchCounts', () => {
+  it('counts only commits ahead of a locally known upstream', async () => {
+    const { repository } = createRepositoryWithRemote();
+    runGit(repository, ['branch', '--set-upstream-to=origin/react', 'next']);
+    fs.writeFileSync(path.join(repository, 'ahead.txt'), 'ahead\n');
+    runGit(repository, ['add', 'ahead.txt']);
+    runGit(repository, ['commit', '-m', 'ahead']);
+    runGit(repository, ['checkout', '-b', 'no-upstream']);
+
+    await expect(getUnpushedBranchCounts(repository, ['next', 'no-upstream', 'remotes/origin/react'])).resolves.toEqual({
+      counts: { next: 1 },
+    });
+  });
+});
+
 describe.runIf(canRunGit())('getRangeDiff', () => {
   it('resolves a base that exists only on a remote other than origin', async () => {
     const { repository } = createRepositoryWithRemote({ remoteName: 'upstream', defaultBranch: 'react' });

package/server/lib/mcp-reconnect/DOCUMENTATION.md

@@ -0,0 +1,55 @@
+# Managed MCP Reconnect
+
+## Purpose
+
+OpenCode connects each configured MCP server once, when a project directory is
+first used. A server that does not come up then is marked `failed` and never
+retried; a server whose live connection later drops is marked `failed` too and
+stays that way until OpenCode restarts. This module injects a small plugin into
+the OpenCode process OpenChamber launches that reconnects those servers, so a
+server that was slow to start or crashed mid-session comes back on its own.
+
+## Runtime flow
+
+1. `prepareManagedOpenCodeEnv(configContent)` materializes the plugin under
+   `<openchamber-data-dir>/mcp-reconnect/` and appends its `file://` URL to
+   `OPENCODE_CONFIG_CONTENT` through the shared merge in
+   `packages/web/server/lib/opencode/managed-plugin-config.js`.
+2. It is always on for managed OpenCode. There is no setting, because it only
+   acts on servers OpenCode has already given up on.
+3. OpenCode loads the plugin once per project directory with an SDK client
+   scoped to that directory, so each directory reconnects its own servers.
+4. The plugin reads MCP status one second after load, calls connect for every
+   server in the `failed` state, then re-reads status after a per-server delay
+   that doubles from one second to a cap of thirty. A server seen in any other
+   state resets its counter. While nothing is failed it checks every thirty
+   seconds.
+5. A dropped connection publishes `mcp.tools.changed`, which the plugin uses to
+   check right away instead of waiting out the idle interval.
+6. OpenCode calls the plugin's `dispose` hook when it tears the directory down,
+   which stops the loop.
+
+## Invariants
+
+- Only `failed` is retried. `disabled` is the user's choice, and `needs_auth`
+  or `needs_client_registration` need the user to act; retrying those would
+  either re-enable a server the user turned off or loop on a login prompt.
+- The plugin logs nothing and swallows every error. OpenCode already logs each
+  failed attempt, and a status call failing during an OpenCode restart is not
+  news.
+- One check runs at a time; a wake-up arriving during a check is honored once
+  it finishes rather than starting a second loop.
+
+## What the UI sees
+
+OpenCode publishes no event when a reconnect succeeds. The chat picks the
+server up on the next prompt because tools are resolved from live state, but
+the MCP page reads status on bootstrap and refresh, so it can show `failed` for
+a while after the server is back.
+
+## Runtime parity
+
+- Web and Desktop managed OpenCode: injected automatically.
+- External OpenCode (`OPENCODE_HOST` or skip-start) and VS Code's separate
+  OpenCode lifecycle: not injected, because OpenChamber does not control that
+  process environment.

package/server/lib/mcp-reconnect/runtime.js

@@ -0,0 +1,122 @@
+import { pathToFileURL } from 'node:url';
+import { appendManagedPlugin } from '../opencode/managed-plugin-config.js';
+
+/**
+ * OpenCode marks an MCP server `failed` when it does not come up at startup or
+ * when a live connection drops, and never tries again. This plugin runs inside
+ * the managed OpenCode process and reconnects those servers with a per-server
+ * exponential backoff, so a server that was merely slow to start, or a local
+ * one that crashed, comes back without an OpenCode restart.
+ *
+ * Only `failed` is retried. `needs_auth`, `needs_client_registration`, and
+ * `disabled` are user decisions or need user action, and retrying them would
+ * either loop on a login prompt or re-enable a server the user turned off.
+ *
+ * The plugin talks to OpenCode through the SDK client OpenCode hands it, which
+ * is scoped to one project directory, so each open directory reconnects its
+ * own servers. Nothing is logged: OpenCode already reports each failed attempt.
+ */
+const createPluginSource = () => String.raw`
+const INITIAL_RETRY_MS = 1000
+const MAX_RETRY_MS = 30000
+const IDLE_CHECK_MS = 30000
+
+export const OpenChamberMcpReconnectPlugin = async ({ client }) => {
+  let disposed = false
+  let running = false
+  let wakeRequested = false
+  let timer
+  // Consecutive failed attempts per server, cleared once it is seen healthy.
+  const attempts = new Map()
+  const dueAt = new Map()
+
+  const schedule = (delayMs) => {
+    if (disposed) return
+    clearTimeout(timer)
+    timer = setTimeout(tick, delayMs)
+  }
+
+  const tick = async () => {
+    if (running) {
+      wakeRequested = true
+      return
+    }
+    running = true
+    let delay = IDLE_CHECK_MS
+    try {
+      const statuses = (await client.mcp.status())?.data ?? {}
+      const now = Date.now()
+      const due = []
+      for (const [name, entry] of Object.entries(statuses)) {
+        if (entry?.status !== "failed") {
+          attempts.delete(name)
+          dueAt.delete(name)
+          continue
+        }
+        const at = dueAt.get(name) ?? now
+        if (at > now) {
+          delay = Math.min(delay, at - now)
+          continue
+        }
+        due.push(name)
+      }
+      for (const name of attempts.keys()) {
+        if (!Object.hasOwn(statuses, name)) {
+          attempts.delete(name)
+          dueAt.delete(name)
+        }
+      }
+
+      await Promise.allSettled(due.map((name) => client.mcp.connect({ path: { name } })))
+
+      // The result is read on the next tick: a server that came back clears
+      // its counter there, one still failed waits out its backoff.
+      const after = Date.now()
+      for (const name of due) {
+        const count = (attempts.get(name) ?? 0) + 1
+        const wait = Math.min(INITIAL_RETRY_MS * 2 ** (count - 1), MAX_RETRY_MS)
+        attempts.set(name, count)
+        dueAt.set(name, after + wait)
+        delay = Math.min(delay, wait)
+      }
+    } catch {
+      // Status is unavailable while OpenCode is shutting down or restarting;
+      // the idle check picks up again when it is back.
+    } finally {
+      running = false
+      const wake = wakeRequested
+      wakeRequested = false
+      schedule(wake ? INITIAL_RETRY_MS : delay)
+    }
+  }
+
+  schedule(INITIAL_RETRY_MS)
+
+  return {
+    // A dropped connection publishes this event; checking right away beats
+    // waiting out the idle interval.
+    event: async ({ event }) => {
+      if (event?.type === "mcp.tools.changed") schedule(INITIAL_RETRY_MS)
+    },
+    dispose: async () => {
+      disposed = true
+      clearTimeout(timer)
+    },
+  }
+}
+`;
+
+export const createMcpReconnectRuntime = ({ fsPromises, path, dataDir }) => {
+  const pluginDirectory = path.join(dataDir, 'mcp-reconnect');
+  const pluginPath = path.join(pluginDirectory, 'openchamber-mcp-reconnect-plugin.js');
+
+  const prepareManagedOpenCodeEnv = async (rawConfig) => {
+    await fsPromises.mkdir(pluginDirectory, { recursive: true });
+    await fsPromises.writeFile(pluginPath, createPluginSource(), { mode: 0o600 });
+    return {
+      OPENCODE_CONFIG_CONTENT: appendManagedPlugin(rawConfig, pathToFileURL(pluginPath).href, 'MCP reconnect plugin'),
+    };
+  };
+
+  return { prepareManagedOpenCodeEnv };
+};

package/server/lib/mcp-reconnect/runtime.test.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createMcpReconnectRuntime } from './runtime.js';
+
+const temporaryDirectories = [];
+const disposers = [];
+
+afterEach(async () => {
+  await Promise.all(disposers.splice(0).map((dispose) => dispose()));
+  vi.useRealTimers();
+  await Promise.all(temporaryDirectories.splice(0).map((directory) => fs.rm(directory, { recursive: true, force: true })));
+});
+
+const materialize = async (rawConfig = '{}') => {
+  const dataDir = await fs.mkdtemp(path.join(os.tmpdir(), 'openchamber-mcp-reconnect-'));
+  temporaryDirectories.push(dataDir);
+  const runtime = createMcpReconnectRuntime({ fsPromises: fs, path, dataDir });
+  const prepared = await runtime.prepareManagedOpenCodeEnv(rawConfig);
+  const pluginPath = path.join(dataDir, 'mcp-reconnect', 'openchamber-mcp-reconnect-plugin.js');
+  const pluginModule = await import(`${pathToFileURL(pluginPath).href}?test=${Date.now()}-${Math.random()}`);
+  return { prepared, pluginPath, plugin: pluginModule.OpenChamberMcpReconnectPlugin };
+};
+
+/**
+ * A stand-in for the SDK client OpenCode hands to plugins. `statuses` is live
+ * state the test mutates; `connect` records when each attempt happened.
+ */
+const createClient = (statuses, { onConnect } = {}) => {
+  const attempts = [];
+  return {
+    attempts,
+    statuses,
+    mcp: {
+      status: vi.fn(async () => ({ data: { ...statuses } })),
+      connect: vi.fn(async ({ path: { name } }) => {
+        attempts.push({ name, at: Date.now() });
+        onConnect?.(name);
+        return { data: true };
+      }),
+    },
+  };
+};
+
+const start = async (plugin, client) => {
+  const hooks = await plugin({ client });
+  disposers.push(hooks.dispose);
+  return hooks;
+};
+
+describe('managed MCP reconnect runtime', () => {
+  it('materializes the plugin and preserves existing plugin entries', async () => {
+    const { prepared, pluginPath } = await materialize('{ "plugin": ["file:///existing.js"], "model": "test/model" }');
+    const config = JSON.parse(prepared.OPENCODE_CONFIG_CONTENT);
+    expect(config.model).toBe('test/model');
+    expect(config.plugin).toEqual(['file:///existing.js', pathToFileURL(pluginPath).href]);
+  });
+
+  it('reconnects only servers in the failed state', async () => {
+    vi.useFakeTimers();
+    const { plugin } = await materialize();
+    const client = createClient({
+      broken: { status: 'failed', error: 'spawn ENOENT' },
+      healthy: { status: 'connected' },
+      off: { status: 'disabled' },
+      login: { status: 'needs_auth' },
+      registration: { status: 'needs_client_registration', error: 'no client id' },
+    });
+    await start(plugin, client);
+
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(client.attempts.map((attempt) => attempt.name)).toEqual(['broken']);
+  });
+
+  it('backs off per server up to a cap while it keeps failing', async () => {
+    vi.useFakeTimers();
+    const { plugin } = await materialize();
+    const client = createClient({ broken: { status: 'failed', error: 'refused' } });
+    const started = Date.now();
+    await start(plugin, client);
+
+    await vi.advanceTimersByTimeAsync(92_000);
+
+    expect(client.attempts.map((attempt) => attempt.at - started)).toEqual([
+      1000, 2000, 4000, 8000, 16_000, 32_000, 62_000, 92_000,
+    ]);
+  });
+
+  it('stops retrying once a server is back and starts fresh when it drops again', async () => {
+    vi.useFakeTimers();
+    const { plugin } = await materialize();
+    const statuses = { flaky: { status: 'failed', error: 'refused' } };
+    const client = createClient(statuses, {
+      onConnect: () => { statuses.flaky = { status: 'connected' }; },
+    });
+    const hooks = await start(plugin, client);
+
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(client.attempts).toHaveLength(1);
+
+    statuses.flaky = { status: 'failed', error: 'Connection closed' };
+    await hooks.event({ event: { type: 'mcp.tools.changed', properties: { server: 'flaky' } } });
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(client.attempts).toHaveLength(2);
+    expect(client.attempts[1].at - client.attempts[0].at).toBeGreaterThan(30_000);
+  });
+
+  it('keeps going when status is temporarily unavailable', async () => {
+    vi.useFakeTimers();
+    const { plugin } = await materialize();
+    const client = createClient({ broken: { status: 'failed', error: 'refused' } });
+    client.mcp.status.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+    await start(plugin, client);
+
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(client.attempts).toHaveLength(0);
+
+    await vi.advanceTimersByTimeAsync(30_000);
+    expect(client.attempts).toHaveLength(1);
+  });
+
+  it('does nothing after dispose', async () => {
+    vi.useFakeTimers();
+    const { plugin } = await materialize();
+    const client = createClient({ broken: { status: 'failed', error: 'refused' } });
+    const hooks = await plugin({ client });
+
+    await hooks.dispose();
+    await hooks.event({ event: { type: 'mcp.tools.changed', properties: { server: 'broken' } } });
+    await vi.advanceTimersByTimeAsync(120_000);
+
+    expect(client.mcp.status).not.toHaveBeenCalled();
+    expect(client.attempts).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,158 @@
+# Message Queue
+
+## Purpose
+
+Owns the messages a user queued while a session was busy, and sends them the
+moment the session goes idle. The queue lives in the web server so a closed
+tab, a locked phone, or a dropped connection no longer strands it. Structural
+template: `permission-auto-accept` — the server is authoritative, the shared UI
+renders a projection, and VS Code (which has no server of its own) keeps its
+UI-side queue and foreground auto-send hook.
+
+## Files
+
+- `runtime.js` — `createMessageQueueRuntime(...)` (state, persistence,
+  dispatch loop, event handling) and `registerMessageQueueRoutes(app, runtime)`.
+- `runtime.test.js` — delivery, idleness gates, retries, holds, persistence,
+  concurrency with in-flight sends, slash commands, and project knowledge.
+
+Wiring: created in `server/index.js` after the global event hub and the
+session-knowledge runtime; routes registered in
+`opencode/feature-routes-runtime.js` (before the generic OpenCode proxy) with
+JSON bodies enabled in `opencode/core-routes.js`; stopped by
+`opencode/shutdown-runtime.js`.
+
+## Item
+
+An item is what the UI would have sent itself, captured at queue time so the
+send never re-resolves mutable UI state:
+
+```
+{
+  id, createdAt,
+  content,        // raw text for display and editing
+  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 }],
+  context: [      // what the composer had attached, in send order
+    { kind: 'context', text, metadata, instructions? },  // a draft chip or linked issue/PR; metadata is the UI's structured payload
+    { kind: 'instruction', text },                       // derived from the text (skill instruction)
+    { kind: 'synthetic', text },                         // handed to the composer by another surface
+  ],
+  sendConfig: { providerID, modelID, agent?, variant? }   // required
+}
+```
+
+The server is a courier for `context`: it validates the shape (a kind it
+knows, a `metadata` object on `context` entries) and delivers each entry as a
+synthetic text part, an entry's `instructions` going out as its own part just
+before it and its `metadata` riding the part verbatim so the timeline renders
+the context block back. The payload inside `metadata` is the UI's contract
+(`lib/messages/contextParts.ts`), parsed by the UI on the way back.
+
+`parseQueuedItemInput` rejects anything the server could not deliver later
+(no text, attachments, or context; missing model; malformed attachment or
+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`.
+
+## Persistence
+
+`<data-dir>/message-queue.json` (`OPENCHAMBER_DATA_DIR` or
+`~/.config/openchamber`): `{ version, revision, sessions: { [sessionId]:
+{ directory, items } } }`, written atomically (temp file + rename) through a
+serialized write chain. A missing file is an empty queue. A malformed file is
+a failure, not an empty queue: it is moved aside as
+`message-queue.json.corrupt-<timestamp>` before the runtime starts empty, so
+the next write cannot overwrite the user's data. A failed read leaves writes
+disabled until a later load succeeds. `revision` is a global monotonic counter
+bumped on every mutation; clients use it to reject stale snapshots.
+
+In-memory only, deliberately: the in-flight item (`sendingId`), retry
+backoff, abort timestamps, and holds. A restart has no in-flight sends; a
+persisted "sending" flag would strand a message forever.
+
+## Delivery loop
+
+1. `start()` subscribes to the global upstream hub and loads the file; on
+   load and on every hub `connect` it arms every session that has items.
+2. `session.status` for a queued session: `idle` arms a short quiet timer
+   (500 ms, coalescing the burst around a turn boundary), `busy`/`retry`
+   clears it. A `message.updated` for a completed assistant reply arms as
+   well, so a missed idle event cannot strand the queue. `session.deleted`
+   drops the session's queue. An assistant `MessageAbortedError` records an
+   abort.
+3. `tick(sessionId)` bails when the queue is empty, an item is in flight, or
+   the session is held. It re-arms after a 2 s post-abort hold (the UI's
+   old behavior: a stop is not immediately followed by the next prompt) or
+   while the head item is in retry backoff.
+4. Idleness is re-verified against OpenCode before sending, because
+   `prompt_async` into a running turn steers into it instead of starting the
+   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:
+   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`
+     list (skills included) and carries no captured context goes to
+     `POST /session/:id/command` with the captured model, agent, variant, and
+     file parts. That route accepts file parts only, so a command queued
+     **with** context takes the prompt route instead, the same rule the
+     composer applies: the command's template is expanded with its arguments
+     (`$ARGUMENTS`, `$1..$N`, or appended), a skill keeps its `/name args` text
+     and gets an explicit "the user invoked this skill" synthetic part after
+     the context;
+   - otherwise `POST /session/:id/prompt_async` with the parts in the same
+     order a UI send uses: text, files, the captured context, the skill
+     invocation when there is one, pending project knowledge
+     (`sessionKnowledgeRuntime.resolvePendingForSession`, synthetic, recorded
+     as delivered only after the prompt is accepted), then the agent mention.
+   Success removes the item, persists, broadcasts, and marks the user
+   message sent for notifications. Failure keeps the item, backs off
+   2 s → 60 s (doubling per consecutive failure of that item), and re-arms.
+6. The next item goes out after the next busy → idle cycle.
+
+## Holds
+
+Auto-review is driven from the UI and bounces the original session through
+idle between iterations; the UI tells the server to hold that session's queue
+(`PUT .../hold { held: true, ttlMs? }`) while a run is going and releases it
+when the run ends. A hold expires on its own (default 5 min, cap 10 min)
+because the UI that asserted it may be gone; the UI re-asserts it every two
+minutes while the run continues. Releasing arms a dispatch.
+
+## Routes (`/api/message-queue`)
+
+Normal authenticated OpenChamber runtime routes; never on browser URL-token
+allowlists.
+
+| Route | Purpose |
+|---|---|
+| `GET /api/message-queue` | Full snapshot `{ revision, sessions[] }` |
+| `POST .../sessions/:id/items` | Append `{ directory, item }`; returns `{ revision, session, itemId }` and arms a dispatch (the session may already be idle) |
+| `DELETE .../sessions/:id/items/:itemId` | Remove; `409` while that item is in flight |
+| `POST .../sessions/:id/items/:itemId/take` | Remove and return the full item (payloads included); `404`/`409` |
+| `POST .../sessions/:id/take` | Remove and return every item not in flight, in order |
+| `PUT .../sessions/:id/order` | `{ itemIds }` must be a complete permutation |
+| `DELETE .../sessions/:id` | Clear; the in-flight item stays |
+| `PUT .../sessions/:id/hold` | `{ held, ttlMs? }` |
+
+Every mutation broadcasts `openchamber:message-queue.updated` with
+`{ revision, session }` to all connected clients (SSE and WS), so several
+devices on one server see one queue. The session in that payload always names
+its `directory`, including the broadcast that removes the last item: the UI
+keys its projection by directory, and a broadcast without one left the
+delivered message on screen (a session's directory is remembered until the
+session is deleted or evicted).
+
+Limits: 20 items per session, 50 sessions (oldest evicted, never one with an
+item in flight), 200k characters of content; attachment payloads are bounded
+by the route family's 50 MB JSON limit.
+
+## UI ownership
+
+`packages/ui/src/stores/messageQueueStore.ts` is the projection: see its
+section in `packages/ui/src/stores/DOCUMENTATION.md`. VS Code intentionally
+does not use this module; with all OpenChamber webviews closed, queued
+messages there are not delivered.