ompchamber 0.8.0 → 1.1.0

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

@@ -17,6 +17,7 @@ import type { ApprovalMode } from '@/shared/lib/omp/config/access-mode';
 import { streamChatResponse } from '@/client/hooks/chat/stream';
 import type { SessionSeed } from '@/client/hooks/chat/timeline/session-load';
 import { buildPromptText } from '@/client/hooks/chat/timeline/prompt-text';
+import { flushDeferredPick, type DeferredModelStore } from '@/client/hooks/chat/timeline/deferred-model';
 import { isTextAttachmentFile } from '@/shared/lib/chat/attachments';
 import { createMockStreamCallbacks } from '@/shared/lib/chat/timeline/stream-callbacks';
 import { PHASE_VERBS } from '@/shared/lib/chat/timeline/tool-phrases';
@@ -51,9 +52,9 @@ export interface ChatTimelineSendDeps {
   /** Global access-control mode (persisted user preference), read at send time
    *  so the spawn-capable requests carry the latest value. */
   accessModeRef: { current: ApprovalMode };
-  /** Live composer model/thinking mirror (written by ChatInput) so enqueue can
-   *  snapshot the selection onto queued items. */
-  composerModelRef: { current: { provider: string; modelId: string; thinkingLevel: string } | null };
+  /** Picks the composer made while a turn was streaming. Pushed onto the
+   *  session here, immediately before the prompt they were meant for. */
+  deferredComposerPickRef: DeferredModelStore;
   abortControllerRef: { current: AbortController | null };
   setInputValue: (v: string) => void;
   setSearchParams: (fn: (prev: URLSearchParams) => URLSearchParams, opts?: { replace?: boolean }) => void;
@@ -91,6 +92,7 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     seedSession,
     pendingComposerModelRef,
     pendingThinkingLevelRef,
+    deferredComposerPickRef,
     accessModeRef,
     abortControllerRef,
     setInputValue,
@@ -133,10 +135,13 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
 
   // Steer the running omp agent with a fresh prompt (interrupt-and-reply).
   const steerOmpAgent = useCallback(async (text: string, attachments: Attachment[]) => {
+    // A steer IS a new prompt: a pick made during the interrupted turn belongs
+    // to it, so it is pushed before the interrupt-and-reply starts the turn.
+    await flushDeferredPick(ompAgent, deferredComposerPickRef);
     const { promptText, images } = await prepareDeliverable(text, attachments);
     const ok = await ompAgent.sendInterruptAndReply(promptText, images);
     if (!ok) setInputValue(text);
-  }, [ompAgent, prepareDeliverable, setInputValue]);
+  }, [ompAgent, prepareDeliverable, setInputValue, deferredComposerPickRef]);
 
   const executeSend = useCallback(async (
     text: string,
@@ -209,6 +214,12 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
     if (isOmpSession) {
       aiPlaceholderIdRef.current = aiPlaceholderId;
       optimisticUserIdRef.current = userMsgId;
+      // A model/thinking pick made while the previous turn streamed was held
+      // back so it could not re-target that answer. A queued delivery does NOT
+      // own it: that item carries its own snapshot, so the pick stays pending
+      // for the composer's own next prompt instead of being spent — and then
+      // overwritten — by a delivery it was never meant for.
+      if (!modelOverride) await flushDeferredPick(ompAgent, deferredComposerPickRef);
       // Replay the queued snapshot first so the prompt runs on the exact
       // model/thinking the item was queued with.
       if (modelOverride) {
@@ -329,6 +340,6 @@ export function useChatTimelineSend(deps: ChatTimelineSendDeps): ChatTimelineSen
         scrollToBottom,
       })
     );
-  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, accessModeRef]);
+  }, [appSettings, folders, isOmpSession, ompAgent, selectedFolderId, sessionId, scrollToBottom, jumpToBottom, persistMessages, seedSession, pendingComposerModelRef, pendingThinkingLevelRef, deferredComposerPickRef, accessModeRef]);
   return { steerOmpAgent, executeSend };
 }

package/src/client/hooks/workspace/available-width.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+/**
+ * Measure an element's content width and keep it current.
+ *
+ * Panel widths are stored as a share of the group's available area, so the
+ * group has to report that area before any fraction can become pixels. Returns
+ * `null` until the first measurement — callers must treat that as "unknown",
+ * not as zero, or a panel would collapse on its first render.
+ *
+ * `ResizeObserver` is not optional here: the width changes on a window resize,
+ * on a devtools dock, and on a sibling panel being toggled, and none of those
+ * are `window` events.
+ */
+export function useAvailableWidth(ref: RefObject<HTMLElement | null>): number | null {
+  const [available, setAvailable] = useState<number | null>(null);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element || typeof ResizeObserver === 'undefined') return;
+
+    const observer = new ResizeObserver(() => {
+      setAvailable(element.clientWidth || null);
+    });
+    observer.observe(element);
+    setAvailable(element.clientWidth || null);
+
+    return () => observer.disconnect();
+  }, [ref]);
+
+  return available;
+}

package/src/client/hooks/workspace/panel-widths.ts

@@ -1,59 +1,56 @@
-import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
-import type { RefObject } from 'preact/compat';
-import { mergePanelWidths, normalizePanelWidths, type PanelWidths } from '@/shared/lib/workspace/panel-widths';
+import { useCallback, useMemo } from 'preact/hooks';
+import {
+  mergePanelWidths,
+  normalizePanelWidths,
+  type PanelWidths,
+} from '@/shared/lib/workspace/panel-widths';
 import type { RightPanelType } from '@/shared/lib/workspace/right-panels';
-import { writeSetting } from '@/shared/lib/settings/client';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
 
-/** A drag commits once, after the pointer is released; this only coalesces. */
-const PERSIST_DEBOUNCE_MS = 500;
+/** Session-state key holding this session's own per-panel widths. */
+const PANEL_WIDTHS_KEY = 'layout.panelWidths';
 
 interface PanelWidthsResult {
   widths: PanelWidths;
-  /** Live widths, for imperative restores that cannot wait on a re-render. */
-  widthsRef: RefObject<PanelWidths>;
-  /** Fold measured panel widths in and persist the merged map. */
+  /** Fold measured panel widths into this session's map. */
   commitWidths: (patch: PanelWidths) => void;
 }
 
 /**
- * Owns the desktop layout's per-panel width map: restored from
- * `app_settings.desktopLayoutSizes`, kept in a ref for resize handlers, and
- * written back (debounced) whenever a panel is resized. One writer for both
- * resizable groups, so neither clobbers the other's widths.
+ * Owns the desktop layout's per-panel width map.
+ *
+ * Widths are **per session**: they live in `session_ui_state` under
+ * `layout.panelWidths`, next to the rest of a session's layout state
+ * (`layout.activeRightPanel`, `layout.showRightPanel`, `layout.openedFiles`), so
+ * switching sessions brings back the layout that session was left in.
+ *
+ * `app_settings.desktopLayoutSizes` is the **seed**: a session that has never
+ * been resized reads it, which is what keeps an existing user's layout across
+ * the upgrade instead of resetting everyone to the defaults. Once a panel is
+ * dragged, the session stores its own map and the seed is no longer consulted
+ * for that session.
+ *
+ * There is deliberately no px→fraction rewrite pass here. Converting a legacy
+ * pixel value is done when a width is *read* (`resolvePanelWidth`), because a
+ * write would have to run before this session's own blob has loaded and would
+ * therefore overwrite it with the seed.
  */
 export function usePanelWidths(
   appSettings: Record<string, any>,
   legacyView: RightPanelType,
 ): PanelWidthsResult {
-  const [widths, setWidths] = useState<PanelWidths>(() =>
-    normalizePanelWidths(appSettings.desktopLayoutSizes, legacyView),
+  const seed = useMemo(
+    () => normalizePanelWidths(appSettings.desktopLayoutSizes, legacyView),
+    [appSettings.desktopLayoutSizes, legacyView],
   );
-  const widthsRef = useRef<PanelWidths>(widths);
-  // Set while a debounced write is pending, which is also the flush condition.
-  const timerRef = useRef<number | undefined>(undefined);
-
-  const saveNow = useCallback(() => {
-    clearTimeout(timerRef.current);
-    timerRef.current = undefined;
-    writeSetting('desktopLayoutSizes', widthsRef.current);
-  }, []);
+  const [widths, setWidths] = useSessionState<PanelWidths>(PANEL_WIDTHS_KEY, seed);
 
   const commitWidths = useCallback(
     (patch: PanelWidths) => {
-      const next = mergePanelWidths(widthsRef.current, patch);
-      widthsRef.current = next;
-      setWidths(next);
-      clearTimeout(timerRef.current);
-      timerRef.current = window.setTimeout(saveNow, PERSIST_DEBOUNCE_MS);
+      setWidths((prev) => mergePanelWidths(prev, patch));
     },
-    [saveNow],
+    [setWidths],
   );
 
-  // The mobile layout unmounts this hook; flush instead of dropping the width
-  // the user just dragged.
-  useEffect(() => () => {
-    if (timerRef.current !== undefined) saveNow();
-  }, [saveNow]);
-
-  return { widths, widthsRef, commitWidths };
+  return { widths, commitWidths };
 }

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