ompchamber 0.8.0 → 1.0.0

package/src/server/lib/fs/git-sync.ts

@@ -0,0 +1,191 @@
+import { runShell, shellOk } from '@/server/lib/fs/shell';
+
+/**
+ * Ahead/behind counts behind the git panel's Sync button.
+ *
+ * `git rev-list --left-right --count HEAD...@{upstream}` counts against the
+ * LOCAL remote-tracking ref, and that ref only moves on fetch/pull/push.
+ * Nothing in the chamber ever fetched, so `behind` reported the state of the
+ * last fetch rather than the remote: the badge sat at ↑0 ↓0 while origin had
+ * commits to pull, and the button — disabled by that very zero — could never
+ * correct itself.
+ *
+ * A read that asks for counts therefore refreshes the tracking ref first. The
+ * refresh is TTL'd so the git panel's 5s poll is not a 5s fetch loop, it is
+ * shared across the panels polling the same repo, and the loader starts it
+ * before its local git probes so the round trip overlaps instead of adding up.
+ */
+
+/** How long a fetch attempt — success or failure — is trusted. */
+const FETCH_TTL_MS = 60_000;
+/**
+ * How long a read waits for the fetch before answering from the tracking ref
+ * as it stands. A slow or offline remote must not stall the panel; the fetch
+ * keeps running under its own budget and a later read picks up the new ref.
+ */
+const FETCH_WAIT_MS = 3_000;
+/** Hard budget for one fetch; it is killed at the end of it. */
+const FETCH_TIMEOUT_MS = 15_000;
+
+export interface GitSyncCount {
+  ahead: number;
+  behind: number;
+}
+
+interface RemoteState {
+  /** When the last attempt settled; `0` means never attempted. */
+  at: number;
+  /** The running attempt, so concurrent polls share one fetch. */
+  inFlight: Promise<void> | null;
+}
+
+const remoteStates = new Map<string, RemoteState>();
+
+function stateFor(cwd: string): RemoteState {
+  let state = remoteStates.get(cwd);
+  if (!state) {
+    state = { at: 0, inFlight: null };
+    remoteStates.set(cwd, state);
+  }
+  return state;
+}
+
+/**
+ * Runs one `git fetch` with a hard deadline, returning whether it succeeded.
+ *
+ * Deliberately not `runShell`: that helper reads stdout and stderr to EOF, and
+ * a stalled fetch defeats it — git's own `git-remote-https` child survives the
+ * kill and keeps the inherited stderr pipe open, so the read never ends and the
+ * promise hangs forever. Verified on Bun 1.4.2: Bun's `timeout` closes stdout
+ * but not that inherited stderr, and the orphan lingers. Nothing here reads the
+ * fetch's output, so both streams are ignored (no pipe, nothing to hang on) and
+ * the process is killed by process group at the deadline — `detached` is what
+ * makes the group killable, and the group kill is what stops the helper from
+ * accumulating on every stalled attempt.
+ */
+async function runFetch(cwd: string, remote: string): Promise<boolean> {
+  const proc = Bun.spawn({
+    cmd: ['sh', '-c', `git fetch --quiet --no-tags '${remote.replace(/'/g, `'\\''`)}'`],
+    cwd,
+    stdin: 'ignore',
+    stdout: 'ignore',
+    stderr: 'ignore',
+    detached: true,
+    // Without this a remote that wants credentials blocks on stdin; the fetch
+    // then fails instead, and the counts fall back to the tracking ref.
+    env: { ...Bun.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<void>((resolve) => {
+    timer = setTimeout(resolve, FETCH_TIMEOUT_MS);
+  });
+  const exitCode = await Promise.race([
+    proc.exited,
+    deadline.then(() => {
+      try {
+        process.kill(-proc.pid, 'SIGKILL');
+      } catch {
+        // Already gone, or the group could not be signalled: `exited` below
+        // still settles, and the ref simply stays as it was.
+      }
+      return proc.exited;
+    }),
+  ]);
+  clearTimeout(timer);
+  return exitCode === 0;
+}
+
+/**
+ * The branch's upstream remote, or null when it has none. Cheap and local, so
+ * the no-upstream case is never cached: configuring an upstream in the terminal
+ * shows up on the next poll instead of up to a TTL later.
+ */
+async function readUpstreamRemote(cwd: string): Promise<string | null> {
+  try {
+    const result = await runShell('git rev-parse --abbrev-ref --symbolic-full-name @{upstream}', {
+      cwd,
+      timeout: 5_000,
+    });
+    if (!shellOk(result)) return null;
+    const upstream = result.stdout.trim();
+    const slash = upstream.indexOf('/');
+    return slash > 0 ? upstream.slice(0, slash) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Refresh `cwd`'s remote-tracking refs, awaiting at most `FETCH_WAIT_MS`.
+ * Resolves immediately when the last attempt is still inside its TTL, and
+ * shares the running attempt when one is already in flight.
+ */
+export async function refreshRemoteRefs(cwd: string): Promise<void> {
+  const state = stateFor(cwd);
+  if (state.inFlight) return state.inFlight;
+  if (state.at !== 0 && Date.now() - state.at < FETCH_TTL_MS) return;
+
+  const remote = await readUpstreamRemote(cwd);
+  if (!remote) return;
+  // Reading the upstream is itself an await: another poll may have started the
+  // fetch, or completed one, in the meantime.
+  if (state.inFlight) return state.inFlight;
+  if (state.at !== 0 && Date.now() - state.at < FETCH_TTL_MS) return;
+
+  // The attempt never rejects — a failed fetch is not a broken panel — and
+  // always clears `inFlight` so a later read can retry.
+  state.inFlight = (async () => {
+    try {
+      await runFetch(cwd, remote);
+    } finally {
+      state.at = Date.now();
+      state.inFlight = null;
+    }
+  })();
+
+  // Bounded wait. `AbortSignal.timeout` rather than `Bun.sleep`: it is unref'd,
+  // so an abandoned wait cannot hold a live timer open on every poll that
+  // refreshes.
+  const deadline = new Promise<void>((resolve) => {
+    AbortSignal.timeout(FETCH_WAIT_MS).addEventListener('abort', () => resolve(), { once: true });
+  });
+  await Promise.race([state.inFlight, deadline]);
+}
+
+/**
+ * Marks `cwd` as freshly fetched — a pull/push has already moved the tracking
+ * ref, so the next read must not fetch a state it just produced.
+ */
+export function markRemoteRefsFresh(cwd: string): void {
+  stateFor(cwd).at = Date.now();
+}
+
+/**
+ * Forces the next read to fetch. The counts are per-branch, so a checkout makes
+ * whatever the previous branch refreshed irrelevant.
+ */
+export function invalidateRemoteRefs(cwd: string): void {
+  stateFor(cwd).at = 0;
+}
+
+/**
+ * Ahead/behind against the branch's upstream, read from the local tracking ref
+ * (`refreshRemoteRefs` is what makes that ref current). Both zero when the
+ * branch has no upstream or git cannot answer.
+ */
+export async function gitSyncCount(cwd: string): Promise<GitSyncCount> {
+  try {
+    // `git rev-list --left-right --count HEAD...@{upstream}` prints "<ahead>\t<behind>".
+    const result = await runShell('git rev-list --left-right --count HEAD...@{upstream}', {
+      cwd,
+      timeout: 8_000,
+    });
+    if (!shellOk(result)) return { ahead: 0, behind: 0 };
+
+    const [ahead, behind] = result.stdout.trim().split(/\s+/).map(Number);
+    return { ahead: ahead || 0, behind: behind || 0 };
+  } catch {
+    return { ahead: 0, behind: 0 };
+  }
+}

package/src/server/lib/omp/rpc/manager.ts

@@ -20,8 +20,9 @@ import { PendingUiDialogs } from '@/server/lib/omp/rpc/pending-ui-dialogs';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { notifyRunningChange } from '@/server/lib/omp/rpc/session-registry';
 import { dispatchSessionCommand } from '@/server/lib/omp/rpc/session-commands';
+import { scheduleQueueDelivery } from '@/server/lib/queue/delivery.server';
 import { SubagentLiveness } from '@/server/lib/omp/rpc/subagent-liveness';
-import { markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
+import { loadStreamStatuses, markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
 import { GET_STATE_TIMEOUT_MS, IDLE_DESTROY_MS, NON_TERMINAL_CONTINUATION_GRACE_MS, READY_TIMEOUT_MS, SUBAGENT_STALE_MS, type AgentEvent, type EventListener, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
 
 export type {
@@ -172,6 +173,22 @@ export class AgentSessionWrapper {
     this.destroy();
   }
 
+  /** Write the terminal stream badge from the ending turn's own stopReason.
+   *  The `abort` command already wrote `abort` at dispatch time, but the
+   *  agent_end frame arrives later and previously flattened it to `finish`.
+   *  Re-check the current row and only upgrade `stream` rows, so a `finish`
+   *  written here can never clobber a newer run's live `stream`/`abort`. */
+  private async markEndStatus(messages: unknown): Promise<void> {
+    if (!this.sessionId) return;
+    const aborted = Array.isArray(messages) && messages.some((entry) => {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+      return (entry as Record<string, unknown>).stopReason === 'aborted';
+    });
+    const current = await loadStreamStatuses();
+    if (current[this.sessionId] !== 'stream') return;
+    await markStreamStatus(this.sessionId, aborted ? 'abort' : 'finish');
+  }
+
   private handleFrame(frame: RpcFrame): void {
     this.resetIdleTimer();
     const event = frame as AgentEvent;
@@ -188,6 +205,31 @@ export class AgentSessionWrapper {
         refreshSessionList = true;
         if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
         break;
+      case 'turn_start':
+        // Redundant with agent_start in the happy path, but the run-level
+        // counterpart can be missed (e.g. the state was cleared by a command
+        // between frames). The turn is proof enough the session is live.
+        if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
+        break;
+      case 'message_start':
+        // Same recovery as turn_start: a message frame is only emitted inside
+        // a live run, so its arrival re-arms the `stream` row no matter what
+        // stale status sits there (upsert overwrites any terminal badge).
+        if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
+        break;
+      case 'turn_end': {
+        // A multi-turn run emits turn_end for EVERY turn — intermediates end
+        // with `toolUse`/`stop` while the run keeps going (verified against
+        // omp 18.2.8: agent_start → turn_start → turn_end('toolUse') →
+        // turn_start → turn_end('stop') → agent_end, and the frame carries no
+        // isTerminal field). Only `aborted` is unambiguous here: the run is
+        // over, so the abort badge can be written before agent_end arrives.
+        // Everything else waits for agent_end, which knows isTerminal.
+        if (!this.sessionId) break;
+        const turn = event.message as Record<string, unknown> | undefined;
+        if (turn?.stopReason === 'aborted') void markStreamStatus(this.sessionId, 'abort');
+        break;
+      }
       case 'agent_end':
         if (event.isTerminal !== false) {
           this.streaming = false;
@@ -196,7 +238,21 @@ export class AgentSessionWrapper {
           this.awaitingAgentStartDeadline = 0;
           this.continuationGraceUntil = 0;
           clearSessionFileCaches();
-          if (this.sessionId) void markStreamStatus(this.sessionId, 'finish');
+          // The turn's own stopReason is the ground truth for how it ended:
+          // `aborted` = user stop, anything else (`stop`, `toolUse`, and the
+          // ambiguous `error` that tool failures also produce) completes as
+          // `finish`. This must not overwrite a fresh `abort` row from a NEWER
+          // run — guard against downgrades by checking the current row first.
+          const aborted = Array.isArray(event.messages) && event.messages.some((entry) => {
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
+            return (entry as Record<string, unknown>).stopReason === 'aborted';
+          });
+          if (this.sessionId) void this.markEndStatus(event.messages);
+          // The run truly ended — the server, not the browser, decides whether
+          // a queued follow-up goes out next. A user-aborted run holds the
+          // queue (stop-all semantics): the next run end or an explicit send
+          // picks it up.
+          if (!aborted) scheduleQueueDelivery(this);
         } else {
           this.continuationGraceUntil = Date.now() + NON_TERMINAL_CONTINUATION_GRACE_MS;
         }
@@ -232,7 +288,6 @@ export class AgentSessionWrapper {
           this.promptRunning = false;
           this.awaitingAgentStart = false;
           this.awaitingAgentStartDeadline = 0;
-          if (this.sessionId) void markStreamStatus(this.sessionId, 'error');
           this.emit({ type: 'prompt_error', errorMessage: (event.error as string) ?? 'Prompt failed' });
           notifyRunningChange();
           return;

package/src/server/lib/omp/rpc/session-commands.ts

@@ -13,6 +13,7 @@ import { RpcCommandTimeoutError, type RpcProcess } from '@/server/lib/omp/rpc/pr
 import { AWAITING_AGENT_START_TIMEOUT_MS, GET_STATE_TIMEOUT_MS, IMAGE_BEARING_COMMANDS, PASSTHROUGH_COMMANDS, PROMPT_ACK_TIMEOUT_MS, RESTARTING_MESSAGE, SESSION_BUSY_MESSAGE, WebRpcError, toImageContents, type AgentEvent, type RpcSessionState, validateAgentImages } from '@/server/lib/omp/rpc/constants';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { notifyRunningChange } from '@/server/lib/omp/rpc/session-registry';
+import { scheduleQueueDelivery } from '@/server/lib/queue/delivery.server';
 import { clearStreamStatus, markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
 import { buildWebState, type WebStateHost } from '@/server/lib/omp/rpc/web-state';
 
@@ -28,6 +29,8 @@ export interface SessionCommandHost extends WebStateHost {
   /** Real omp session id (empty before the first get_state). */
   sessionId: string;
   emit(event: AgentEvent): void;
+  /** One dispatch throat (same surface the wrapper's own send uses). */
+  send(command: Record<string, unknown>): Promise<unknown>;
   resetIdleTimer(force?: boolean): void;
   /** Forget a pending ask/approval dialog once its response is sent. */
   resolvePendingUiDialog(id: string): void;
@@ -100,6 +103,9 @@ export async function dispatchSessionCommand(host: SessionCommandHost, command:
           releaseStreamRow();
           host.emit({ type: 'prompt_result', agentInvoked: false });
           notifyRunningChange();
+          // Nothing ran (agent was idle and declined) — the queue may hold the
+          // next item; give it the same delivery window a run end would.
+          scheduleQueueDelivery(host);
         } else if (!streamingBehavior && ack?.agentInvoked !== false) {
           host.awaitingAgentStart = true;
           host.awaitingAgentStartDeadline = Date.now() + AWAITING_AGENT_START_TIMEOUT_MS;

package/src/server/lib/omp/session/sidebar-data.server.ts

@@ -110,11 +110,11 @@ export async function loadSidebarData(): Promise<SessionListPayload> {
   const sidebarSort = await serverSidebarSort();
 
   // Live stream status per session (spinner / one-shot done badge), written by
-  // the RPC manager on agent_start/agent_end/abort/error. `stream` rows whose
-  // session is no longer running are stale (restart mid-run) and heal to
+  // the RPC manager on agent_start/agent_end and by the abort command. `stream`
+  // rows whose session is no longer running are stale (restart mid-run) and heal to
   // `finish` right here — the authoritative status travels with the same
   // fetch that refreshes the sidebar list.
-  const streamStatuses: Record<string, 'stream' | 'finish' | 'abort' | 'error'> = {};
+  const streamStatuses: Record<string, 'stream' | 'finish' | 'abort'> = {};
   // Sessions blocked on a dialog nobody has answered yet. Read live from the
   // process registry (never persisted): the child that owns the question is the
   // same thing that owns the flag, so a restart cannot leave a stale badge.

package/src/server/lib/queue/delivery.server.ts

@@ -0,0 +1,114 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Server-side follow-up queue auto-delivery: the run's own `agent_end` — as
+ * observed by the session wrapper, the process that owns the omp child —
+ * triggers the next queued prompt. This replaces the client-driven
+ * auto-delivery whose state races (tab reload wiping the table, session
+ * switches sending a queue into the wrong session) made queued messages
+ * disappear or land in the wrong conversation.
+ *
+ * Semantics:
+ * - The head is CLAIMED (transactional DELETE) before dispatch, so a second
+ *   trigger — another tab's nudge, a racing run end — can never double-send.
+ * - A failed dispatch re-inserts the item at the head; nothing is lost.
+ * - A user Stop clears the pending-delivery timer instead of delivering (the
+ *   item stays claimed-but-returned... it is re-queued first), so stop-all
+ *   semantics live on the server now.
+ */
+
+import { claimHeadQueueItem, requeueHeadQueueItem } from '@/server/lib/queue/store.server';
+import type { QueuedMessage } from '@/shared/types/chat';
+
+/** Settling time between agent_end and the next prompt dispatch. Small on
+ *  purpose: omp's own turn-end bookkeeping (JSONL flush, title slot) runs on
+ *  the same child, and an instant dispatch races it. */
+const DELIVERY_DELAY_MS = 500;
+
+/** Per-session pending delivery timer, so a second agent_end while one is
+ *  already scheduled cannot double-book the head. */
+const pendingTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+function clearPendingTimer(sessionId: string): void {
+  const timer = pendingTimers.get(sessionId);
+  if (timer !== undefined) {
+    clearTimeout(timer);
+    pendingTimers.delete(sessionId);
+  }
+}
+
+/** Send one queued item to the session as a normal prompt. The model snapshot
+ *  rides first (set_model / set_thinking_level) exactly like the composer's
+ *  queued delivery did. Returns false when the dispatch failed. */
+async function dispatchQueuedItem(session: QueueDeliveryHost, item: QueuedMessage): Promise<boolean> {
+  try {
+    if (item.model) {
+      await session.send({ type: 'set_model', provider: item.model.provider, modelId: item.model.modelId });
+      if (item.model.thinkingLevel !== 'auto') {
+        await session.send({ type: 'set_thinking_level', level: item.model.thinkingLevel });
+      }
+    }
+    const images = item.attachments
+      .filter((a) => typeof a?.preview === 'string' && a.preview.startsWith('data:image/') && typeof a?.dataBase64 === 'string')
+      .map((a) => ({ type: 'image' as const, data: a.dataBase64 as string, mimeType: a.preview.slice(5).split(';')[0] || 'image/png' }));
+    await session.send({
+      type: 'prompt',
+      message: item.text,
+      ...(images.length ? { images } : {}),
+      ...(item.model ? { accessMode: item.model.accessMode } : {}),
+    });
+    return true;
+  } catch (error) {
+    console.error(`[queue] delivery failed for session ${session.sessionId}:`, error);
+    return false;
+  }
+}
+
+/** Minimal surface delivery needs from a live session wrapper. */
+export interface QueueDeliveryHost {
+  sessionId: string;
+  isAlive(): boolean;
+  isBusy(): boolean;
+  send(command: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * Schedule the next queued delivery for this session. Called on terminal
+ * agent_end and on a client's mount nudge. Idempotent: an in-flight timer is
+ * reused, a claimed head can only be won by one caller.
+ */
+export function scheduleQueueDelivery(session: QueueDeliveryHost): void {
+  const sessionId = session.sessionId;
+  if (!sessionId || pendingTimers.has(sessionId)) return;
+  const timer = setTimeout(() => {
+    pendingTimers.delete(sessionId);
+    void deliverNext(session);
+  }, DELIVERY_DELAY_MS);
+  pendingTimers.set(sessionId, timer);
+}
+
+async function deliverNext(session: QueueDeliveryHost): Promise<void> {
+  const sessionId = session.sessionId;
+  if (!session.isAlive() || session.isBusy()) return;
+  const item = claimHeadQueueItem(sessionId);
+  if (!item) return;
+  const ok = await dispatchQueuedItem(session, item);
+  if (!ok) await requeueHeadQueueItem(sessionId, item);
+}
+
+/**
+ * A user Stop: return anything already claimed for this session's pending
+ * delivery to the queue and cancel the timer. The item keeps its head
+ * position; nothing is sent until the next run end or explicit send.
+ */
+export function cancelQueuedDelivery(sessionId: string): void {
+  clearPendingTimer(sessionId);
+}
+
+/** Forget a session's timer state (process teardown, session destroy). */
+export function forgetQueuedDelivery(sessionId: string): void {
+  clearPendingTimer(sessionId);
+}

package/src/server/lib/queue/schema-migration.server.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Schema migration for `queued_messages`: installs older databases created the
+ * table with an FK to `sessions`, but omp session ids have no row there —
+ * every queue insert for a real session failed with FOREIGN KEY constraint
+ * failed. Rebuilds the table without the FK, once, marker-keyed in
+ * `app_settings` (same pattern as project-settings-migration).
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+
+const QUEUE_FK_MARKER = 'queue_fk_removed';
+
+const QUEUE_TABLE_SQL = `
+  CREATE TABLE queued_messages_new (
+    id TEXT PRIMARY KEY,
+    session_id TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    message TEXT NOT NULL DEFAULT '',
+    attachments TEXT NOT NULL DEFAULT '[]',
+    provider TEXT,
+    model_id TEXT,
+    thinking_level TEXT,
+    access_mode TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+  );
+  INSERT INTO queued_messages_new
+    (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode, created_at)
+  SELECT id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode, created_at
+    FROM queued_messages;
+  DROP TABLE queued_messages;
+  ALTER TABLE queued_messages_new RENAME TO queued_messages;
+`;
+
+/** Drop the invalid queue FK on pre-migration databases (idempotent). */
+export async function migrateQueueTableFk(db: DbClient): Promise<void> {
+  const marker = await db.get('SELECT value FROM app_settings WHERE key = ?', [QUEUE_FK_MARKER]);
+  if (marker?.value) return;
+
+  const table = await db.get(
+    "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'queued_messages'",
+  );
+  const hasLegacyFk = Boolean(table?.sql) && String(table.sql).includes('FOREIGN KEY');
+  if (hasLegacyFk) await db.exec(QUEUE_TABLE_SQL);
+  await db.run('INSERT OR REPLACE INTO app_settings (key, value) VALUES (?, ?)', [QUEUE_FK_MARKER, '1']);
+}

package/src/server/lib/queue/store.server.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * SQLite-backed follow-up queue store (`queued_messages` table).
+ *
+ * The server is the single source of truth: the client panel is a view that
+ * mutates through per-item operations, and every mutation returns the
+ * canonical queue so callers reconcile from the response instead of merging
+ * local state. Rows carry a model snapshot (provider, model_id,
+ * thinking_level, access_mode) so auto-delivery replays the settings the item
+ * was queued with.
+ *
+ * Delivery claims the head with a transactional DELETE (bun:sqlite is
+ * synchronous, so BEGIN…COMMIT cannot interleave with another request), which
+ * makes "exactly one consumer sends the head" hold across tabs, reloads and
+ * concurrent nudges. A failed send re-inserts the claimed row at the head.
+ */
+
+import { getDb, getDbSync } from '@/server/db.server';
+import { withTransaction } from '@/shared/lib/db/transaction.server';
+import { isApprovalMode } from '@/shared/lib/omp/config/access-mode';
+import type { QueuedMessage, QueuedMessageModel } from '@/shared/types/chat';
+
+interface QueueRow {
+  id: string;
+  session_id: string;
+  position: number;
+  message: string;
+  attachments: string;
+  provider: string | null;
+  model_id: string | null;
+  thinking_level: string | null;
+  access_mode: string | null;
+}
+
+export function rowToQueuedMessage(row: QueueRow): QueuedMessage {
+  let attachments: unknown = [];
+  try {
+    attachments = JSON.parse(row.attachments);
+  } catch {
+    attachments = [];
+  }
+  const model: QueuedMessageModel | null =
+    row.provider && row.model_id
+      ? {
+          provider: row.provider,
+          modelId: row.model_id,
+          thinkingLevel: row.thinking_level ?? 'auto',
+          accessMode: isApprovalMode(row.access_mode) ? row.access_mode : 'always-ask',
+        }
+      : null;
+  return {
+    id: row.id,
+    text: row.message,
+    attachments: Array.isArray(attachments) ? (attachments as QueuedMessage['attachments']) : [],
+    model,
+  };
+}
+
+export function normalizeModel(raw: unknown): QueuedMessageModel | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const m = raw as Record<string, unknown>;
+  if (typeof m.provider !== 'string' || typeof m.modelId !== 'string') return null;
+  return {
+    provider: m.provider,
+    modelId: m.modelId,
+    thinkingLevel: typeof m.thinkingLevel === 'string' ? m.thinkingLevel : 'auto',
+    accessMode: isApprovalMode(m.accessMode) ? m.accessMode : 'always-ask',
+  };
+}
+
+function serializeAttachments(attachments: unknown): string {
+  return JSON.stringify(Array.isArray(attachments) ? attachments : []);
+}
+
+interface QueueItemInput {
+  text: string;
+  attachments?: unknown;
+  model?: unknown;
+}
+
+/** The session's queued follow-ups in delivery order. */
+export async function listQueue(sessionId: string): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  const rows = (await db.all(
+    'SELECT * FROM queued_messages WHERE session_id = ? ORDER BY position ASC',
+    [sessionId],
+  )) as QueueRow[];
+  return rows.map(rowToQueuedMessage);
+}
+
+/** Append one item; returns the canonical queue. */
+export async function appendQueueItem(sessionId: string, input: QueueItemInput): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  const model = normalizeModel(input.model);
+  const id = crypto.randomUUID();
+  db.raw.run(
+    `INSERT INTO queued_messages (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode)
+     VALUES (?, ?, COALESCE((SELECT MAX(position) FROM queued_messages WHERE session_id = ?), -1) + 1, ?, ?, ?, ?, ?, ?)`,
+    [id, sessionId, sessionId, input.text, serializeAttachments(input.attachments),
+      model?.provider ?? null, model?.modelId ?? null, model?.thinkingLevel ?? null, model?.accessMode ?? null],
+  );
+  return listQueue(sessionId);
+}
+
+/** Patch one item's text/model; null when the id is unknown. */
+export async function patchQueueItem(
+  sessionId: string,
+  id: string,
+  patch: { text?: unknown; model?: unknown },
+): Promise<QueuedMessage[] | null> {
+  const db = await getDb();
+  const sets: string[] = [];
+  const values: unknown[] = [];
+  if (typeof patch.text === 'string') {
+    sets.push('message = ?');
+    values.push(patch.text);
+  }
+  if (patch.model !== undefined) {
+    const model = normalizeModel(patch.model);
+    sets.push('provider = ?', 'model_id = ?', 'thinking_level = ?', 'access_mode = ?');
+    values.push(model?.provider ?? null, model?.modelId ?? null, model?.thinkingLevel ?? null, model?.accessMode ?? null);
+  }
+  if (sets.length === 0) return listQueue(sessionId);
+  const result = await db.run(
+    `UPDATE queued_messages SET ${sets.join(', ')} WHERE session_id = ? AND id = ?`,
+    [...values, sessionId, id],
+  );
+  if (!result.changes) return null;
+  return listQueue(sessionId);
+}
+
+/** Remove one item by id; false when it was already claimed or absent. */
+export async function deleteQueueItem(sessionId: string, id: string): Promise<boolean> {
+  const db = await getDb();
+  const result = await db.run('DELETE FROM queued_messages WHERE session_id = ? AND id = ?', [sessionId, id]);
+  return result.changes > 0;
+}
+
+/** Reorder the queue to exactly `orderedIds` (unknown ids are ignored). */
+export async function reorderQueue(sessionId: string, orderedIds: string[]): Promise<QueuedMessage[]> {
+  const db = await getDb();
+  withTransaction(db, () => {
+    const update = db.raw.query('UPDATE queued_messages SET position = ? WHERE session_id = ? AND id = ?');
+    orderedIds.forEach((id, index) => update.run(index, sessionId, id));
+  });
+  return listQueue(sessionId);
+}
+
+/**
+ * Atomically claim the head for delivery: read + delete inside one
+ * transaction, so a concurrent claimant (second tab, reload nudge racing a
+ * run end) can never observe — and send — the same item twice. Null when the
+ * queue is empty. Synchronous by construction: `bun:sqlite` is sync, so the
+ * BEGIN…COMMIT block cannot interleave with another request.
+ */
+export function claimHeadQueueItem(sessionId: string): QueuedMessage | null {
+  const db = getDbSync();
+  return withTransaction(db, () => {
+    const row = db.raw
+      .query('SELECT * FROM queued_messages WHERE session_id = ? ORDER BY position ASC LIMIT 1')
+      .get(sessionId) as QueueRow | undefined;
+    if (!row) return null;
+    db.raw.run('DELETE FROM queued_messages WHERE id = ?', [row.id]);
+    return rowToQueuedMessage(row);
+  });
+}
+
+/**
+ * Put a failed delivery back at the head (position below the current minimum)
+ * so it is retried before anything else. The next run end or mount nudge
+ * picks it up again.
+ */
+export async function requeueHeadQueueItem(sessionId: string, item: QueuedMessage): Promise<void> {
+  const db = await getDb();
+  db.raw.run(
+    `INSERT INTO queued_messages (id, session_id, position, message, attachments, provider, model_id, thinking_level, access_mode)
+     VALUES (?, ?, COALESCE((SELECT MIN(position) FROM queued_messages WHERE session_id = ?), 0) - 1, ?, ?, ?, ?, ?, ?)`,
+    [item.id, sessionId, sessionId, item.text, serializeAttachments(item.attachments),
+      item.model?.provider ?? null, item.model?.modelId ?? null, item.model?.thinkingLevel ?? null, item.model?.accessMode ?? null],
+  );
+}