@aiworker/web 1.22.0 → 1.23.0

package/server/lib/linear/status-runtime.test.js

@@ -50,11 +50,11 @@ describe('Linear session status runtime', () => {
   let previousPort;
 
   beforeEach(() => {
-    previousDataDir = process.env.OPENCHAMBER_DATA_DIR;
-    previousPort = process.env.OPENCHAMBER_PORT;
+    previousDataDir = process.env.AIWORKER_DATA_DIR;
+    previousPort = process.env.AIWORKER_PORT;
     dataDir = makeTempDir();
-    process.env.OPENCHAMBER_DATA_DIR = dataDir;
-    process.env.OPENCHAMBER_PORT = '3001';
+    process.env.AIWORKER_DATA_DIR = dataDir;
+    process.env.AIWORKER_PORT = '3001';
     setLinearAuth({
       accessToken: 'access-1',
       refreshToken: 'refresh-1',
@@ -69,14 +69,14 @@ describe('Linear session status runtime', () => {
     vi.unstubAllGlobals();
     clearLinearAuth();
     if (previousDataDir === undefined) {
-      delete process.env.OPENCHAMBER_DATA_DIR;
+      delete process.env.AIWORKER_DATA_DIR;
     } else {
-      process.env.OPENCHAMBER_DATA_DIR = previousDataDir;
+      process.env.AIWORKER_DATA_DIR = previousDataDir;
     }
     if (previousPort === undefined) {
-      delete process.env.OPENCHAMBER_PORT;
+      delete process.env.AIWORKER_PORT;
     } else {
-      process.env.OPENCHAMBER_PORT = previousPort;
+      process.env.AIWORKER_PORT = previousPort;
     }
     fs.rmSync(dataDir, { recursive: true, force: true });
   });
@@ -147,7 +147,7 @@ describe('Linear session status runtime', () => {
       });
       expect(commentCalls).toHaveLength(1);
       const body = JSON.parse(commentCalls[0][1].body).variables.input.body;
-      expect(body).toContain('OpenChamber session failed');
+      expect(body).toContain('AiWorker session failed');
     });
     runtime.stop();
   });

package/server/lib/linear/status.js

@@ -117,7 +117,7 @@ function statusWord(kind) {
 
 export function buildLinearSessionStatusComment({ kind, sessionUrl }) {
   const url = readTrimmedString(sessionUrl);
-  const label = `OpenChamber session ${statusWord(kind)}`;
+  const label = `AiWorker session ${statusWord(kind)}`;
   if (!url) return label;
   // The comment already lives on the issue, so it says only what happened and
   // links to the session. Issue titles routinely contain brackets ("[Bug] …"),

package/server/lib/linear/status.test.js

@@ -59,11 +59,11 @@ describe('Linear session status comments', () => {
   let previousPort;
 
   beforeEach(() => {
-    previousDataDir = process.env.OPENCHAMBER_DATA_DIR;
-    previousPort = process.env.OPENCHAMBER_PORT;
+    previousDataDir = process.env.AIWORKER_DATA_DIR;
+    previousPort = process.env.AIWORKER_PORT;
     dataDir = makeTempDir();
-    process.env.OPENCHAMBER_DATA_DIR = dataDir;
-    process.env.OPENCHAMBER_PORT = '3001';
+    process.env.AIWORKER_DATA_DIR = dataDir;
+    process.env.AIWORKER_PORT = '3001';
     setLinearAuth({
       accessToken: 'access-1',
       refreshToken: 'refresh-1',
@@ -78,14 +78,14 @@ describe('Linear session status comments', () => {
     vi.unstubAllGlobals();
     clearLinearAuth();
     if (previousDataDir === undefined) {
-      delete process.env.OPENCHAMBER_DATA_DIR;
+      delete process.env.AIWORKER_DATA_DIR;
     } else {
-      process.env.OPENCHAMBER_DATA_DIR = previousDataDir;
+      process.env.AIWORKER_DATA_DIR = previousDataDir;
     }
     if (previousPort === undefined) {
-      delete process.env.OPENCHAMBER_PORT;
+      delete process.env.AIWORKER_PORT;
     } else {
-      process.env.OPENCHAMBER_PORT = previousPort;
+      process.env.AIWORKER_PORT = previousPort;
     }
     fs.rmSync(dataDir, { recursive: true, force: true });
   });
@@ -95,7 +95,7 @@ describe('Linear session status comments', () => {
     expect(readSessionOrigin('http://127.0.0.1:3001/')).toBe('http://127.0.0.1:3001');
     expect(readSessionOrigin('javascript:alert(1)')).toBe('');
     expect(readSessionOrigin('https://app.example.com/secret')).toBe('');
-    expect(readSessionOrigin('openchamber:')).toBe('');
+    expect(readSessionOrigin('aiworker:')).toBe('');
     expect(buildLinearSessionOpenUrl('ses_1', 'https://app.example.com'))
       .toBe('https://app.example.com/?session=ses_1');
     expect(buildLinearSessionOpenUrl('ses_1', '')).toBe('');
@@ -117,7 +117,7 @@ describe('Linear session status comments', () => {
     expect(isPublicSessionOrigin('http://macbook.local:3001')).toBe(false);
     expect(isPublicSessionOrigin('http://macbook:3001')).toBe(false);
     expect(isPublicSessionOrigin('http://[fd00::1]:3001')).toBe(false);
-    expect(isPublicSessionOrigin('openchamber:')).toBe(false);
+    expect(isPublicSessionOrigin('aiworker:')).toBe(false);
     expect(isPublicSessionOrigin('')).toBe(false);
   });
 
@@ -164,15 +164,15 @@ describe('Linear session status comments', () => {
     expect(buildLinearSessionStatusComment({
       kind: 'started',
       sessionUrl: 'https://app.example.com/?session=ses_1',
-    })).toBe('[OpenChamber session started](https://app.example.com/?session=ses_1)');
+    })).toBe('[AiWorker session started](https://app.example.com/?session=ses_1)');
     expect(buildLinearSessionStatusComment({
       kind: 'completed',
       sessionUrl: 'https://app.example.com/?session=ses_1',
-    })).toBe('[OpenChamber session completed](https://app.example.com/?session=ses_1)');
+    })).toBe('[AiWorker session completed](https://app.example.com/?session=ses_1)');
     expect(buildLinearSessionStatusComment({
       kind: 'failure',
       sessionUrl: 'https://app.example.com/?session=ses_1',
-    })).toBe('[OpenChamber session failed](https://app.example.com/?session=ses_1)');
+    })).toBe('[AiWorker session failed](https://app.example.com/?session=ses_1)');
   });
 
   it('cannot be broken by brackets in the issue title', async () => {
@@ -231,7 +231,7 @@ describe('Linear session status comments', () => {
     });
     expect(commentCalls).toHaveLength(1);
     const body = JSON.parse(commentCalls[0][1].body).variables.input.body;
-    expect(body).toBe('[OpenChamber session started](https://app.example.com/?session=ses_1)');
+    expect(body).toBe('[AiWorker session started](https://app.example.com/?session=ses_1)');
     expect(JSON.stringify(first)).not.toContain('access-1');
   });
 
@@ -266,6 +266,6 @@ describe('Linear session status comments', () => {
     });
     expect(commentCalls).toHaveLength(1);
     const body = JSON.parse(commentCalls[0][1].body).variables.input.body;
-    expect(body).toBe('[OpenChamber session completed](https://app.example.com/?session=ses_1)');
+    expect(body).toBe('[AiWorker session completed](https://app.example.com/?session=ses_1)');
   });
 });

package/server/lib/linear/teams.test.js

@@ -17,9 +17,9 @@ describe('Linear teams list', () => {
   let previousDataDir;
 
   beforeEach(() => {
-    previousDataDir = process.env.OPENCHAMBER_DATA_DIR;
+    previousDataDir = process.env.AIWORKER_DATA_DIR;
     dataDir = makeTempDir();
-    process.env.OPENCHAMBER_DATA_DIR = dataDir;
+    process.env.AIWORKER_DATA_DIR = dataDir;
     setLinearAuth({
       accessToken: 'access-1',
       refreshToken: 'refresh-1',
@@ -33,9 +33,9 @@ describe('Linear teams list', () => {
     vi.unstubAllGlobals();
     clearLinearAuth();
     if (previousDataDir === undefined) {
-      delete process.env.OPENCHAMBER_DATA_DIR;
+      delete process.env.AIWORKER_DATA_DIR;
     } else {
-      process.env.OPENCHAMBER_DATA_DIR = previousDataDir;
+      process.env.AIWORKER_DATA_DIR = previousDataDir;
     }
     fs.rmSync(dataDir, { recursive: true, force: true });
   });

package/server/lib/magic-prompts/routes.js

@@ -4,13 +4,13 @@ export const registerMagicPromptRoutes = (app, dependencies) => {
   const {
     fsPromises,
     path,
-    openchamberDataDir,
+    aiworkerDataDir,
   } = dependencies;
 
   const runtime = createMagicPromptRuntime({
     fsPromises,
     path,
-    filePath: path.join(openchamberDataDir, 'magic-prompts.json'),
+    filePath: path.join(aiworkerDataDir, 'magic-prompts.json'),
   });
 
   app.get('/api/magic-prompts', async (_req, res) => {

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 AiWorker 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 AiWorker 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 AiWorkerMcpReconnectPlugin = 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.AiWorkerMcpReconnectPlugin };
+};
+
+/**
+ * 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,161 @@
+# 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` (`AIWORKER_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 AiWorker 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 `aiworker:message-queue.updated` with
+`{ revision, session }` to all connected clients (SSE and WS), so several
+devices on one server see one queue. SSE uses the shared control stream at
+`/api/openchamber/events`; `/api/global/event` carries no AiWorker events.
+The UI subscribes independently of its OpenCode transport and re-reads the
+snapshot whenever either stream reconnects. 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 AiWorker webviews closed, queued
+messages there are not delivered.