ompchamber 0.8.0 → 1.0.0

package/src/client/hooks/chat/timeline/queue.ts

@@ -4,84 +4,148 @@
  */
 
 /**
- * Follow-up + steering queue state for the chamber chat, backed by the SQLite
- * `queued_messages` table via /api/sessions/:id/queue (one row per item with a
- * model snapshot, so auto-delivery replays the settings the item was queued
- * with).
+ * Client view of the follow-up queue (SQLite `queued_messages`, owned by the
+ * server). The panel is a VIEW: mutations go through the per-item endpoints
+ * (`POST/PATCH/DELETE /api/sessions/:id/queue[/:itemId]`) and every response
+ * carries the canonical queue, which replaces local state wholesale. The old
+ * client-side replace-on-write mirror is gone — it was what let a reload
+ * hydrating over an empty state wipe the table, and a session switch PUT one
+ * session's list into another's rows.
  *
- * The client panel stays the source of truth while the session is open: every
- * mutation updates React state first, then PUTs the full remaining list to the
- * route (replace-on-write keeps ids stable for reorder/edit/delete). The queue
- * hydrates from the table on mount — a page reload mid-stream restores it.
- * Steering mirrors live in the session-state blob under a separate key.
- *
- * Kept out of useChatTimeline so that hook stays under the size ceiling.
+ * Steering still mirrors into the per-session session-state blob (client-only
+ * by design: an interrupt-and-reply is only meaningful while a client watches
+ * the run).
  */
 
-import type { SetStateAction } from 'preact/compat';
 import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 import type { QueuedMessage } from '@/shared/types';
 import { useSessionState } from '@/client/hooks/workspace/session-state';
 
 const STEERING_STATE_KEY = 'chat.steeringQueue';
 
+function queueUrl(sessionId: string): string {
+  return `/api/sessions/${encodeURIComponent(sessionId)}/queue`;
+}
+
+async function readQueueResponse(res: Response): Promise<QueuedMessage[] | null> {
+  if (!res.ok) return null;
+  const data = (await res.json().catch(() => null)) as { queue?: unknown } | null;
+  return Array.isArray(data?.queue) ? (data.queue as QueuedMessage[]) : null;
+}
+
 export interface ChatTimelineQueueResult {
   messageQueue: QueuedMessage[];
-  setMessageQueue: (updater: SetStateAction<QueuedMessage[]>) => void;
+  /** Append one item; local state updates optimistically, then reconciles
+   *  from the canonical response. No-op without a session. */
+  enqueueMessage: (item: Omit<QueuedMessage, 'id'>) => void;
+  /** Edit one item's text (PATCH). */
+  editMessageText: (id: string, text: string) => void;
+  /** Remove one item by id (DELETE). */
+  removeMessage: (id: string) => void;
+  /** Reorder the queue to these ids (PUT, drag-and-drop). */
+  reorderMessages: (orderedIds: string[]) => void;
+  /** Replace the local list from a fetch (mount hydration, manual refresh). */
+  refresh: () => void;
+  /** Client-only steering mirror (session-state blob). */
   steeringQueue: QueuedMessage[];
-  setSteeringQueue: (updater: SetStateAction<QueuedMessage[]>) => void;
-  /** Drop an exactly-matching text from whichever mirror queue holds it. */
-  removeDeliveredFromQueue: (text: string) => void;
+  setSteeringQueue: (value: QueuedMessage[] | ((prev: QueuedMessage[]) => QueuedMessage[])) => void;
 }
 
 export function useChatTimelineQueue(sessionId: string | null): ChatTimelineQueueResult {
   const [messageQueue, setMessageQueueState] = useState<QueuedMessage[]>([]);
   const [steeringQueue, setSteeringQueue] = useSessionState<QueuedMessage[]>(STEERING_STATE_KEY, []);
 
-  // Hydrate from the table once per session. A generation-safe ref skips the
-  // stale-response race when the user switches sessions quickly.
+  // Hydrate from the table once per session, and re-read when the tab
+  // regains focus (a second tab may have claimed/delivered the head). A
+  // generation-safe ref skips the stale-response race on quick switches.
   const hydrateEpochRef = useRef(0);
-  useEffect(() => {
+  const cancelledRef = useRef(false);
+  const refresh = useCallback(() => {
     if (!sessionId) {
       setMessageQueueState([]);
       return;
     }
     const epoch = ++hydrateEpochRef.current;
-    let cancelled = false;
-    fetch(`/api/sessions/${encodeURIComponent(sessionId)}/queue`)
-      .then(res => (res.ok ? res.json() : { queue: [] }))
-      .then((data: { queue?: QueuedMessage[] }) => {
-        if (cancelled || hydrateEpochRef.current !== epoch) return;
-        setMessageQueueState(Array.isArray(data.queue) ? data.queue : []);
+    fetch(queueUrl(sessionId))
+      .then((res) => readQueueResponse(res))
+      .then((queue) => {
+        if (cancelledRef.current || hydrateEpochRef.current !== epoch) return;
+        setMessageQueueState(queue ?? []);
       })
       .catch(() => {});
-    return () => { cancelled = true; };
   }, [sessionId]);
+  useEffect(() => {
+    cancelledRef.current = false;
+    refresh();
+    const onFocus = () => refresh();
+    window.addEventListener('focus', onFocus);
+    return () => {
+      cancelledRef.current = true;
+      window.removeEventListener('focus', onFocus);
+    };
+  }, [refresh]);
 
-  // Replace-on-write mirror: every client mutation PUTs the full list so the
-  // table always matches the panel (order, edits, deletions included).
-  const mirrorQueue = useCallback((next: QueuedMessage[]) => {
+  // Mounted session with queued items: offer the server a delivery slot. The
+  // server-side claim makes this harmless when a run is active or another tab
+  // already took the head — this used to be the client auto-delivery effect,
+  // which fired into whatever session was open at the time.
+  useEffect(() => {
+    if (!sessionId || messageQueue.length === 0) return;
+    fetch(`${queueUrl(sessionId)}/deliver`, { method: 'POST' }).catch(() => {});
+  }, [sessionId, messageQueue.length > 0]);
+
+  const enqueueMessage = useCallback((item: Omit<QueuedMessage, 'id'>) => {
     if (!sessionId) return;
-    fetch(`/api/sessions/${encodeURIComponent(sessionId)}/queue`, {
-      method: 'PUT',
+    const optimistic: QueuedMessage = { ...item, id: `queue-${Date.now()}` };
+    setMessageQueueState((prev) => [...prev, optimistic]);
+    fetch(queueUrl(sessionId), {
+      method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ queue: next }),
-    }).catch(console.error);
+      body: JSON.stringify(item),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
   }, [sessionId]);
 
-  const setMessageQueue = useCallback((updater: SetStateAction<QueuedMessage[]>) => {
-    setMessageQueueState(prev => {
-      const next = typeof updater === 'function' ? updater(prev) : updater;
-      mirrorQueue(next);
-      return next;
-    });
-  }, [mirrorQueue]);
+  const editMessageText = useCallback((id: string, text: string) => {
+    if (!sessionId) return;
+    fetch(`${queueUrl(sessionId)}/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
+
+  const removeMessage = useCallback((id: string) => {
+    if (!sessionId) return;
+    // Optimistic removal, reconciled only on failure (404 = already claimed —
+    // the item is gone either way).
+    setMessageQueueState((prev) => prev.filter((i) => i.id !== id));
+    fetch(`${queueUrl(sessionId)}/${encodeURIComponent(id)}`, { method: 'DELETE' })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
 
-  const removeDeliveredFromQueue = useCallback((text: string) => {
-    const exact = (q: QueuedMessage[]) => q.some(i => i.text === text);
-    setSteeringQueue(q => (exact(q) ? q.filter(i => i.text !== text) : q));
-    setMessageQueue(q => (exact(q) ? q.filter(i => i.text !== text) : q));
-  }, [setSteeringQueue, setMessageQueue]);
+  const reorderMessages = useCallback((orderedIds: string[]) => {
+    if (!sessionId) return;
+    setMessageQueueState((prev) => {
+      const byId = new Map(prev.map((i) => [i.id, i]));
+      return orderedIds.map((id) => byId.get(id)).filter((i): i is QueuedMessage => Boolean(i));
+    });
+    fetch(queueUrl(sessionId), {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ orderedIds }),
+    })
+      .then((res) => readQueueResponse(res))
+      .then((queue) => { if (queue) setMessageQueueState(queue); })
+      .catch(() => {});
+  }, [sessionId]);
 
-  return { messageQueue, setMessageQueue, steeringQueue, setSteeringQueue, removeDeliveredFromQueue };
+  return { messageQueue, enqueueMessage, editMessageText, removeMessage, reorderMessages, refresh, steeringQueue, setSteeringQueue };
 }

package/src/client/hooks/workspace/terminal/index.ts

@@ -0,0 +1,217 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Live terminal session for the right panel: the socket, its status, and the
+ * attach/resize/input verbs the xterm view drives.
+ *
+ * The terminal id is per chamber session and persisted, which is what makes the
+ * shell survive a page reload: the panel reattaches to the id it already owns
+ * and the server replays its scrollback. `restart` mints a new id, so a shell
+ * that was exited (or wedged) is left behind rather than resurrected.
+ *
+ * The view owns the grid — it is the only thing that knows the container's
+ * size — so attach and resize flow view → hook, while output flows hook → view
+ * through the imperative handle the panel wires up.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import { useSessionStateContext } from '@/client/hooks/workspace/session-state/context';
+import { getSessionValue } from '@/shared/lib/workspace/session-state/store';
+import { connectTerminal, type TerminalSocket } from '@/client/hooks/workspace/terminal/socket';
+import { newTerminalId, type TerminalReadyFrame } from '@/shared/lib/workspace/terminal/protocol';
+
+export type TerminalStatus = 'connecting' | 'running' | 'exited' | 'error';
+
+export interface TerminalSystemInfo {
+  gitBranch: string;
+}
+
+export interface UseTerminalOptions {
+  root?: string;
+  repo?: string;
+  theme?: 'light' | 'dark';
+  onOutput?: (bytes: Uint8Array) => void;
+  onReplay?: (bytes: Uint8Array, frame: TerminalReadyFrame) => void;
+  /** Fired after the shell is replaced, so the view can drop its buffer. */
+  onRestart?: () => void;
+}
+
+export interface UseTerminalResult {
+  status: TerminalStatus;
+  /** Working directory the shell runs in, once known. */
+  cwd: string;
+  shell: string;
+  /** Exit code of a finished shell, or null while it runs. */
+  exitCode: number | null;
+  /** Set when the socket reported an error frame. */
+  error: string | null;
+  systemInfo: TerminalSystemInfo;
+  attach: (cols: number, rows: number) => void;
+  resize: (cols: number, rows: number) => void;
+  input: (data: Uint8Array) => void;
+  /** Replace the shell with a fresh one. */
+  restart: () => void;
+}
+
+export function useTerminal(options: UseTerminalOptions = {}): UseTerminalResult {
+  const { sessionId, ready } = useSessionStateContext();
+  const [terminalId, setTerminalId] = useSessionState<string>('terminal.id', '');
+  const [status, setStatus] = useState<TerminalStatus>('connecting');
+  const [cwd, setCwd] = useState('');
+  const [shell, setShell] = useState('');
+  const [exitCode, setExitCode] = useState<number | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [systemInfo, setSystemInfo] = useState<TerminalSystemInfo>({ gitBranch: 'main' });
+
+  const socketRef = useRef<TerminalSocket | null>(null);
+  // The grid the view reported, replayed on attach so a reconnect lands on the
+  // size the panel actually has instead of the default.
+  const sizeRef = useRef<{ cols: number; rows: number } | null>(null);
+  const outputRef = useRef(options.onOutput);
+  outputRef.current = options.onOutput;
+  const replayRef = useRef(options.onReplay);
+  replayRef.current = options.onReplay;
+  const restartRef = useRef(options.onRestart);
+  restartRef.current = options.onRestart;
+  const rootRef = useRef(options.root);
+  rootRef.current = options.root;
+  const repoRef = useRef(options.repo);
+  repoRef.current = options.repo;
+  const themeRef = useRef(options.theme);
+  themeRef.current = options.theme;
+  const setIdRef = useRef(setTerminalId);
+  setIdRef.current = setTerminalId;
+  /** Last `root\0repo` the shell was launched for; null until the first. */
+  const scopeRef = useRef<string | null>(null);
+
+  // One id per chamber session. The check reads the store, not the hook's local
+  // value: on the render where the blob first becomes ready, `useSessionState`
+  // still reports the fallback (its restore effect has not run yet), so
+  // deciding from the local value would mint a second id and overwrite the
+  // stored one — orphaning the live shell and its scrollback.
+  useEffect(() => {
+    if (!ready) return;
+    if (getSessionValue<string>(sessionId, 'terminal.id')) return;
+    setIdRef.current(newTerminalId());
+  }, [ready, sessionId]);
+
+  useEffect(() => {
+    if (!ready || !terminalId) return;
+
+    setStatus('connecting');
+    setError(null);
+    setExitCode(null);
+
+    const socket = connectTerminal(terminalId, {
+      onReady(frame) {
+        setStatus('running');
+        setCwd(frame.cwd);
+        setShell(frame.shell);
+        setExitCode(null);
+      },
+      onReplay(bytes, frame) {
+        replayRef.current?.(bytes, frame);
+      },
+      onOutput(bytes) {
+        outputRef.current?.(bytes);
+      },
+      onExit(code) {
+        setStatus('exited');
+        setExitCode(code);
+      },
+      onError(code, message) {
+        setStatus('error');
+        setError(`${code}: ${message}`);
+      },
+      onConnectionChange(connected) {
+        if (!connected) setStatus('connecting');
+      },
+    });
+    socketRef.current = socket;
+    // The socket re-dials the same id after a drop; the panel's size is the one
+    // to come back at. On a restart the view is already mounted and will not
+    // report its grid again, so the remembered size is what makes the new shell
+    // spawn at the right dimensions.
+    const size = sizeRef.current;
+    if (size) socket.attach(size.cols, size.rows, rootRef.current, repoRef.current, themeRef.current);
+
+    return () => {
+      socket.release();
+      socketRef.current = null;
+    };
+  }, [ready, terminalId]);
+
+  const restart = useCallback(() => {
+    // Kill the old shell before minting a new id: leaving it to the idle
+    // reaper would keep a dead terminal attached to this session for 30 min.
+    socketRef.current?.close();
+    restartRef.current?.();
+    setIdRef.current(newTerminalId());
+  }, []);
+
+  /**
+   * The repo picker in the header changes the shell's scope, and a PTY's cwd is
+   * fixed at spawn — so a scope change replaces the shell instead of trying to
+   * `cd` it (which would leave the user's own shell state — exports, jobs,
+   * history — describing the old tree).
+   *
+   * The first scope seen is adopted without restarting: `root` arrives
+   * asynchronously (the active project resolves with the sidebar data), and
+   * restarting on that first transition would kill the shell the view is still
+   * attaching.
+   */
+  useEffect(() => {
+    if (!ready) return;
+    const root = options.root;
+    if (!root) return;
+    const scope = `${root}\u0000${options.repo ?? '.'}`;
+    if (scopeRef.current === null) {
+      scopeRef.current = scope;
+      return;
+    }
+    if (scopeRef.current === scope) return;
+    scopeRef.current = scope;
+    restart();
+  }, [ready, options.root, options.repo, restart]);
+
+  // Launch context for the header (git branch), scoped like the shell itself.
+  useEffect(() => {
+    const root = options.root;
+    const repo = options.repo;
+    if (!root) return;
+    const params = new URLSearchParams({ root });
+    if (repo && repo !== '.') params.set('repo', repo);
+    let cancelled = false;
+    fetch(`/api/terminal/run?${params.toString()}`)
+      .then((response) => (response.ok ? response.json() : null))
+      .then((data: { gitBranch?: string } | null) => {
+        if (!cancelled && data?.gitBranch) setSystemInfo({ gitBranch: data.gitBranch });
+      })
+      .catch(() => {
+        // The header simply keeps its previous branch label.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [options.root, options.repo]);
+
+  const attach = useCallback((cols: number, rows: number) => {
+    sizeRef.current = { cols, rows };
+    socketRef.current?.attach(cols, rows, rootRef.current, repoRef.current, themeRef.current);
+  }, []);
+
+  const resize = useCallback((cols: number, rows: number) => {
+    sizeRef.current = { cols, rows };
+    socketRef.current?.resize(cols, rows);
+  }, []);
+
+  const input = useCallback((data: Uint8Array) => {
+    socketRef.current?.input(data);
+  }, []);
+
+  return { status, cwd, shell, exitCode, error, systemInfo, attach, resize, input, restart };
+}

package/src/client/hooks/workspace/terminal/socket.ts

@@ -0,0 +1,227 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Client transport for one terminal: dial, attach, and stay attached.
+ *
+ * One socket carries both directions — JSON control frames out, raw PTY bytes
+ * both ways. Three behaviours are deliberate:
+ *
+ * - **Binary in, binary out.** `binaryType = 'arraybuffer'` so output arrives as
+ *   bytes and is handed straight to `term.write(Uint8Array)`; the client never
+ *   decodes UTF-8 itself, which is what keeps a character split across two PTY
+ *   reads intact.
+ * - **`onBinary` carries the same bytes as `onData`.** xterm reports non-UTF-8
+ *   payloads (some mouse reports, paste of raw bytes) on `onBinary`; forwarding
+ *   only `onData` would silently drop them.
+ * - **Reconnect, not re-create.** A dropped socket re-dials the same terminal
+ *   id, so the shell and its scrollback survive a network blip or a page reload
+ *   instead of a second shell appearing.
+ */
+
+import {
+  decodeServerFrame,
+  encodeClientFrame,
+  terminalSocketUrl,
+  type TerminalAttachFrame,
+  type TerminalClientFrame,
+  type TerminalReadyFrame,
+  type TerminalServerFrame,
+} from '@/shared/lib/workspace/terminal/protocol';
+
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 8000;
+/** Consecutive re-dials that never opened before the stream is given up on. */
+const MAX_FAILED_DIALS = 4;
+
+export interface TerminalSocketHandlers {
+  /** The attach was accepted; `replayBytes` of scrollback follow. */
+  onReady: (frame: TerminalReadyFrame) => void;
+  /**
+   * The retained scrollback, once. The view must render this at the reported
+   * `replayCols`/`replayRows` before fitting its own viewport.
+   */
+  onReplay: (bytes: Uint8Array, frame: TerminalReadyFrame) => void;
+  /** Live PTY output, after the replay. */
+  onOutput: (bytes: Uint8Array) => void;
+  onExit: (exitCode: number | null, signal: string | null) => void;
+  onError: (code: string, message: string) => void;
+  /** Connection state for the panel's status badge. */
+  onConnectionChange: (connected: boolean) => void;
+}
+
+export interface TerminalSocket {
+  /** Send one attach frame; ignored once a terminal is attached. */
+  attach: (cols: number, rows: number, root?: string, repo?: string, theme?: 'light' | 'dark') => void;
+  resize: (cols: number, rows: number) => void;
+  /** Raw keystrokes or paste; never JSON-encoded. */
+  input: (data: Uint8Array) => void;
+  /** Kill the shell server-side. */
+  close: () => void;
+  /** Release the socket; the shell keeps running for the next attach. */
+  release: () => void;
+}
+
+export function connectTerminal(terminalId: string, handlers: TerminalSocketHandlers): TerminalSocket {
+  let socket: WebSocket | null = null;
+  let retryTimer: ReturnType<typeof setTimeout> | null = null;
+  let failures = 0;
+  let established = false;
+  let released = false;
+  let attached = false;
+  let lastAttach: TerminalAttachFrame | null = null;
+  /** Scrollback accumulated so far, plus how many bytes are still expected. */
+  let replayParts: Uint8Array[] = [];
+  let replayRemaining = 0;
+  let replayFrame: TerminalReadyFrame | null = null;
+
+  const dial = () => {
+    const ws = new WebSocket(terminalSocketUrl(terminalId));
+    ws.binaryType = 'arraybuffer';
+    socket = ws;
+
+    ws.onopen = () => {
+      if (released) return;
+      failures = 0;
+      established = true;
+      handlers.onConnectionChange(true);
+      // Re-attaching replays the retained scrollback, so a reconnected panel
+      // converges on the shell's real state instead of showing a gap.
+      if (lastAttach) ws.send(encodeClientFrame(lastAttach));
+    };
+
+    ws.onmessage = (event) => {
+      if (released) return;
+      if (event.data instanceof ArrayBuffer) {
+        handleOutput(new Uint8Array(event.data));
+        return;
+      }
+      const frame = decodeServerFrame(typeof event.data === 'string' ? event.data : '');
+      if (frame) applyFrame(frame);
+    };
+
+    ws.onclose = () => {
+      socket = null;
+      if (released) return;
+      handlers.onConnectionChange(false);
+      attached = false;
+      replayParts = [];
+      replayRemaining = 0;
+      replayFrame = null;
+      if (!established) return;
+      failures += 1;
+      if (failures > MAX_FAILED_DIALS) return;
+      const delay = Math.min(RECONNECT_BASE_MS * 2 ** (failures - 1), RECONNECT_MAX_MS);
+      retryTimer = setTimeout(() => {
+        retryTimer = null;
+        if (!released) dial();
+      }, delay);
+    };
+
+    ws.onerror = () => {
+      // `onclose` follows and owns the retry decision.
+    };
+  };
+
+  const applyFrame = (frame: TerminalServerFrame) => {
+    if (frame.t === 'ready') {
+      attached = true;
+      replayFrame = frame;
+      replayRemaining = frame.replayBytes;
+      replayParts = [];
+      handlers.onReady(frame);
+      // An empty scrollback never produces a binary frame, so complete it here.
+      if (replayRemaining === 0) finishReplay();
+      return;
+    }
+    if (frame.t === 'exit') {
+      handlers.onExit(frame.exitCode, frame.signal);
+      return;
+    }
+    handlers.onError(frame.code, frame.message);
+  };
+
+  const handleOutput = (bytes: Uint8Array) => {
+    if (replayRemaining <= 0) {
+      handlers.onOutput(bytes);
+      return;
+    }
+    // The server sends the scrollback as one frame, so this normally completes
+    // in a single step; the accounting is what keeps a fragmented delivery
+    // from being mistaken for live output.
+    replayParts.push(bytes);
+    replayRemaining -= bytes.length;
+    if (replayRemaining > 0) return;
+    finishReplay();
+  };
+
+  const finishReplay = () => {
+    const frame = replayFrame;
+    const parts = replayParts;
+    replayFrame = null;
+    replayParts = [];
+    replayRemaining = 0;
+    if (!frame) return;
+    handlers.onReplay(parts.length === 1 ? parts[0] : concat(parts), frame);
+  };
+
+  dial();
+
+  const send = (frame: TerminalClientFrame) => {
+    const ws = socket;
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    ws.send(encodeClientFrame(frame));
+  };
+
+  return {
+    attach(cols, rows, root, repo, theme) {
+      if (attached) return;
+      const frame: TerminalAttachFrame = { t: 'attach', cols, rows };
+      if (root) frame.root = root;
+      if (repo) frame.repo = repo;
+      if (theme) frame.theme = theme;
+      lastAttach = frame;
+      send(frame);
+    },
+    resize(cols, rows) {
+      send({ t: 'resize', cols, rows });
+    },
+    input(data) {
+      const ws = socket;
+      if (!ws || ws.readyState !== WebSocket.OPEN) return;
+      ws.send(data);
+    },
+    close() {
+      send({ t: 'close' });
+    },
+    release() {
+      released = true;
+      if (retryTimer !== null) {
+        clearTimeout(retryTimer);
+        retryTimer = null;
+      }
+      const ws = socket;
+      socket = null;
+      if (!ws) return;
+      ws.onopen = null;
+      ws.onmessage = null;
+      ws.onclose = null;
+      ws.onerror = null;
+      ws.close();
+    },
+  };
+}
+
+function concat(parts: Uint8Array[]): Uint8Array {
+  let size = 0;
+  for (const part of parts) size += part.length;
+  const out = new Uint8Array(size);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.length;
+  }
+  return out;
+}

package/src/server/db.server.ts

@@ -10,6 +10,9 @@ import { loadOmpSidebarData } from '@/server/lib/omp/session/reader';
 import { pathExists, projectPathKey } from '@/server/lib/omp/core/paths';
 
 let dbPromise: Promise<DbClient> | null = null;
+/** Resolved handle cached by getDb(); promise callbacks never run sync, so
+ *  hot paths unwrap through `getDbSync` instead of awaiting. */
+let dbResolved: DbClient | null = null;
 
 /** SYNC_WORKSPACE env flag (default true when unset). When enabled in real
  *  mode, workspace folders are auto-created from discovered omp projects. */
@@ -123,6 +126,10 @@ export async function getDb(): Promise<DbClient> {
 
     const { migrateWorkspaceFolderColumns } = await import('@/shared/lib/workspace/schema-migrations');
     await migrateWorkspaceFolderColumns(db);
+    // Installs older `queued_messages` schemas carry an invalid FK (see the
+    // migration module); rebuild once so real-session queue inserts work.
+    const { migrateQueueTableFk } = await import('@/server/lib/queue/schema-migration.server');
+    await migrateQueueTableFk(db);
 
     await db.exec(`
       CREATE TABLE IF NOT EXISTS files (
@@ -292,12 +299,24 @@ export async function getDb(): Promise<DbClient> {
     const { migrateLegacyProjectSettings } = await import('@/shared/lib/workspace/project-settings-migration');
     await migrateLegacyProjectSettings(db);
 
+    dbResolved = db;
     return db;
   })();
 
   return dbPromise;
 }
 
+/**
+ * Synchronous handle for hot paths needing raw sync transactions
+ * (`bun:sqlite` is sync, so BEGIN…COMMIT cannot interleave with another
+ * request). The server initializes the db at startup; anything earlier must
+ * use `getDb()`.
+ */
+export function getDbSync(): DbClient {
+  if (!dbResolved) throw new Error('Database not initialized — call getDb() first');
+  return dbResolved;
+}
+
 /**
  * Additive-only folder ↔ omp project sync: creates a workspace folder for
  * every project discovered from ~/.omp/agent (folder name = lowercase