@kabmo-labs/kabmo 0.3.1 → 0.4.0

package/src/server/db.server.ts

@@ -41,6 +41,19 @@ interface DbSlot {
   promise: Promise<DbClient> | null;
   /** Resolved handle for `getDbSync`; hot paths must not await. */
   resolved: DbClient | null;
+  /**
+   * Set when a caller retired this slot while an open was still in flight.
+   *
+   * An open is asynchronous (`getDatabasePath` → `createDb` → `initSchema`), so
+   * a teardown that clears the slot mid-open does not stop it: the continuation
+   * used to keep running and assign `state.resolved` on the DROPPED slot object,
+   * leaving an open `bun:sqlite` handle nothing could ever close. On Windows
+   * that is a locked temp directory — measured on the Release gate, where
+   * `releaseDb` failed with `EBUSY … a handle outlived its test` and reported
+   * the two preceding cases as failed. The continuation now closes the handle
+   * it opened and rejects instead of caching it.
+   */
+  disposed: boolean;
 }
 
 declare global {
@@ -49,7 +62,30 @@ declare global {
 }
 
 function slot(): DbSlot {
-  return (globalThis.__kabmoDb ??= { promise: null, resolved: null });
+  return (globalThis.__kabmoDb ??= { promise: null, resolved: null, disposed: false });
+}
+
+/**
+ * Retire the current handle so the next `getDb()` opens the path configured
+ * NOW, closing whatever is open.
+ *
+ * The one caller is `test-support/isolated-db.ts`, but the rule it enforces is
+ * a lifecycle one: a handle must never outlive the configuration it was opened
+ * under. An in-flight open is marked `disposed` rather than awaited, and the
+ * continuation closes its own handle — see {@link DbSlot.disposed}.
+ */
+export function closeDb(): void {
+  const state = globalThis.__kabmoDb;
+  globalThis.__kabmoDb = undefined;
+  if (!state) return;
+  state.disposed = true;
+  try {
+    state.resolved?.raw.close();
+  } catch {
+    // Already closed by a failed open; the slot is gone either way.
+  }
+  state.resolved = null;
+  state.promise = null;
 }
 
 export async function getDatabasePath(): Promise<string> {
@@ -111,6 +147,18 @@ export async function getDb(): Promise<DbClient> {
 
     await migrateLegacyProjectSettings(db);
 
+    // The slot may have been retired while this open was in flight. Assigning
+    // `state.resolved` then would cache a handle on an object nothing reaches
+    // any more — an open connection whose temp directory can never be deleted.
+    if (state.disposed) {
+      try {
+        db.raw.close();
+      } catch {
+        // Nothing to do: the caller already moved on.
+      }
+      throw new Error('database open was retired before it finished');
+    }
+
     state.resolved = db;
     return db;
   })();

package/src/server/index.ts

@@ -25,6 +25,7 @@ import { isMockMode } from '@/server/mock.server';
 import { migrateLegacyDataDir } from '@/server/lib/lifecycle/paths';
 import { stopDiscoveryRootsWatch, syncDiscoveryRootsWatch } from '@/server/lib/omp/config/roots-watch.server';
 import { startScheduleRuntime, stopScheduleRuntime } from '@/server/lib/schedule/runtime.server';
+import { startWaitingRuntime, stopWaitingRuntime } from '@/server/lib/waiting/runtime.server';
 import { seedDefaultMarketplace } from '@/server/lib/panels/seed.server';
 import { syncBundledPlugins } from '@/server/lib/panels/sync.server';
 import { startPanelAutoUpdate } from '@/server/lib/panels/auto-update.server';
@@ -255,6 +256,13 @@ try {
  */
 startScheduleRuntime();
 
+/**
+ * The waiting-prompt clock: a prompt held until another session finishes. Same
+ * shape and the same placement — after the listener and the watchers, because
+ * the first sweep may spawn an omp child.
+ */
+startWaitingRuntime();
+
 /**
  * Bring installed BUNDLED plugins up to the copy this package ships.
  *
@@ -320,6 +328,7 @@ for (const signal of ['SIGTERM', 'SIGINT'] as const) {
   process.once(signal, () => {
     stopDiscoveryRootsWatch();
     stopScheduleRuntime();
+    stopWaitingRuntime();
     void app.stop();
     // Plugins own children and listeners nothing else releases, and a detached
     // child outlives its parent — so this is awaited BEFORE the exit. It is

package/src/server/lib/assets/compressed-cache.server.test.ts

@@ -0,0 +1,78 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { clearCompressedCache, compressedAsset, compressedCacheStats } from '@/server/lib/assets/compressed-cache.server';
+
+describe('compressedAsset', () => {
+  test('computes once for a key and serves the same bytes afterwards', async () => {
+    clearCompressedCache();
+    let produced = 0;
+    const produce = async () => {
+      produced += 1;
+      return new Uint8Array([1, 2, 3]);
+    };
+
+    const first = await compressedAsset('k', produce);
+    const second = await compressedAsset('k', produce);
+
+    expect(produced).toBe(1);
+    expect(second).toEqual(first);
+  });
+
+  // Two tabs opening a cold instance at the same moment would otherwise both
+  // compress a 10 MB bundle. The gate is a deferred promise, not a delay: the
+  // second caller must join the first while it is still unresolved.
+  test('shares one computation between concurrent callers', async () => {
+    clearCompressedCache();
+    const gate = Promise.withResolvers<void>();
+    let produced = 0;
+    const produce = async () => {
+      produced += 1;
+      await gate.promise;
+      return new Uint8Array([9]);
+    };
+
+    const first = compressedAsset('shared', produce);
+    const second = compressedAsset('shared', produce);
+    gate.resolve();
+    const [a, b] = await Promise.all([first, second]);
+
+    expect(produced).toBe(1);
+    expect(a).toEqual(b);
+  });
+
+  test('a different key is a different entry', async () => {
+    clearCompressedCache();
+    await compressedAsset('one', async () => new Uint8Array([1]));
+    await compressedAsset('two', async () => new Uint8Array([2]));
+
+    expect(compressedCacheStats().entries).toBe(2);
+  });
+
+  // An entry is keyed by the asset's ETag, so a rebuild is a new key and the
+  // old bytes are never asked for again. Retention is bounded by count.
+  test('retains a bounded number of entries', async () => {
+    clearCompressedCache();
+    for (let i = 0; i < 20; i += 1) {
+      await compressedAsset(`key-${i}`, async () => new Uint8Array(1024));
+    }
+
+    const stats = compressedCacheStats();
+    expect(stats.entries).toBeLessThanOrEqual(8);
+    expect(stats.bytes).toBeLessThanOrEqual(48 * 1024 * 1024);
+  });
+
+  // The caller needs the bytes it asked for even when they cannot be kept, or a
+  // single asset larger than the budget would fail to serve at all.
+  test('returns an asset larger than the whole budget', async () => {
+    clearCompressedCache();
+    const huge = new Uint8Array(50 * 1024 * 1024);
+    const bytes = await compressedAsset('huge', async () => huge);
+
+    expect(bytes.byteLength).toBe(huge.byteLength);
+  });
+});

package/src/server/lib/assets/compressed-cache.server.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Compressed bytes for a static asset, kept across requests.
+ *
+ * `plugins/compress.ts` compresses per response, which is right for a 4 KB JSON
+ * body and wrong for the client bundle: the production bundle is 10.4 MB, and
+ * re-compressing it on every cold request costs ~20 ms of blocked event loop
+ * for a result that cannot have changed. Measured on this repo's own bundle:
+ * zstd 10.4 MB -> 2.15 MB in 20 ms, gzip -> 2.32 MB in 66 ms.
+ *
+ * The key is the asset's own ETag plus the encoding, so an entry is valid
+ * exactly as long as the bytes it was made from — a rebuild changes the ETag
+ * (size and mtime both move) and the old entry simply stops being asked for.
+ * That also means no invalidation logic: the map is bounded, and a stale entry
+ * is evicted by age, never served.
+ *
+ * Two bounds, because a bundle-sized entry is not a small one: an entry count
+ * and a total byte budget. A single entry larger than the budget is still
+ * RETURNED — it just is not retained — since the caller needs the bytes it
+ * asked for either way.
+ */
+
+/** Encodings' worth of the biggest asset, plus room for the next build. */
+const MAX_ENTRIES = 8;
+const MAX_TOTAL_BYTES = 48 * 1024 * 1024;
+
+const entries = new Map<string, Uint8Array>();
+const inFlight = new Map<string, Promise<Uint8Array>>();
+let totalBytes = 0;
+
+/**
+ * The compressed bytes for `key`, computing them once.
+ *
+ * Concurrent requests for the same key share one computation: two tabs opening
+ * a cold instance at the same moment would otherwise both compress 10 MB.
+ */
+export async function compressedAsset(key: string, produce: () => Promise<Uint8Array>): Promise<Uint8Array> {
+  const hit = entries.get(key);
+  if (hit) {
+    // Re-insert so the map's own order stays least-recently-used first.
+    entries.delete(key);
+    entries.set(key, hit);
+    return hit;
+  }
+
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+
+  const work = produce().then((bytes) => {
+    retain(key, bytes);
+    return bytes;
+  }).finally(() => {
+    inFlight.delete(key);
+  });
+  inFlight.set(key, work);
+  return work;
+}
+
+function retain(key: string, bytes: Uint8Array): void {
+  // Too big to keep. The caller already holds the reference, so the response is
+  // built from it; retaining it would evict everything else and then itself.
+  if (bytes.byteLength > MAX_TOTAL_BYTES) return;
+  entries.set(key, bytes);
+  totalBytes += bytes.byteLength;
+  // Evict oldest first, and never the entry just stored.
+  for (const [candidate, value] of entries) {
+    if (entries.size <= MAX_ENTRIES && totalBytes <= MAX_TOTAL_BYTES) break;
+    if (candidate === key) continue;
+    entries.delete(candidate);
+    totalBytes -= value.byteLength;
+  }
+}
+
+/** The retained byte count and entry count — the observable half of the cache. */
+export function compressedCacheStats(): { entries: number; bytes: number } {
+  return { entries: entries.size, bytes: totalBytes };
+}
+
+/** Drop everything. Tests only; nothing at runtime has a reason to call this. */
+export function clearCompressedCache(): void {
+  entries.clear();
+  inFlight.clear();
+  totalBytes = 0;
+}

package/src/server/lib/db/schema.test.ts

@@ -194,6 +194,7 @@ describe('schema bootstrap', () => {
       'workspace_folders', 'sessions', 'app_settings', 'chat_sessions', 'deleted_workspaces',
       'archived_sessions', 'session_ui_state', 'queued_messages', 'session_stream_state',
       'files', 'btw_topics', 'btw_turns', 'scheduled_tasks', 'scheduled_task_runs',
+      'waiting_prompts',
     ]) {
       expect(first).toContain(expected);
     }

package/src/server/lib/db/schema.ts

@@ -15,6 +15,7 @@ import type { DbClient } from '@/server/lib/db/client';
 import { migrateQueueTableFk } from '@/server/lib/queue/schema-migration.server';
 import { ensureBtwSchema } from '@/server/lib/btw/schema.server';
 import { ensureScheduleSchema } from '@/server/lib/schedule/schema.server';
+import { ensureWaitingSchema } from '@/server/lib/waiting/schema.server';
 import { ensurePluginSchema } from '@/server/lib/plugins/schema.server';
 import { migrateWorkspaceFolderColumns } from '@/shared/lib/workspace/schema-migrations';
 import { migrateSessionStreamStateColumns } from '@/shared/lib/omp/session/schema-migrations';
@@ -104,6 +105,8 @@ export async function initSchema(db: DbClient): Promise<void> {
   await ensureBtwSchema(db);
   // Scheduled-task tables, same reasoning: their own module.
   await ensureScheduleSchema(db);
+  // Prompts held until another session finishes, same reasoning.
+  await ensureWaitingSchema(db);
   // The plugin platform's own tables (kv, records, settings).
   await ensurePluginSchema(db);
 

package/src/server/lib/fs/fs-path.test.ts

@@ -121,7 +121,7 @@ describe('resolveRoot / resolveReferencedPath / getDefaultFsRoot', () => {
     Bun.env.SYNC_WORKSPACE = 'false';
     Bun.env.KABMO_DB_PATH = dbPath;
     delete Bun.env.DB_PATH;
-    globalThis.__kabmoDb = { promise: null, resolved: null };
+    globalThis.__kabmoDb = { promise: null, resolved: null, disposed: false };
     const db = await getDb();
     await db.run('INSERT INTO workspace_folders (name, project_path) VALUES (?, ?)', ['proj', registeredDir]);
   });

package/src/server/lib/omp/rpc/terminal-settle.ts

@@ -32,6 +32,7 @@ import {
   type AutoTitleHost,
 } from '@/server/lib/omp/session/auto-title.server';
 import { scheduleQueueDelivery, type QueueDeliveryHost } from '@/server/lib/queue/delivery.server';
+import { requestWaitingSweep } from '@/server/lib/waiting/sweep-trigger';
 import { markStreamStatus, loadStreamStatuses } from '@/shared/lib/omp/session/stream-state.server';
 import { driveGoalAfterTurn } from '@/server/lib/omp/session/goal-driver.server';
 import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
@@ -81,6 +82,12 @@ export function settleTerminalRun(host: TerminalSettleHost, messages: unknown):
     void driveGoalAfterTurn({ host, messages });
     scheduleQueueDelivery(host);
   }
+  // A prompt held until this session finished is released HERE, and not only by
+  // the sweep tick: the run end is the event the wait was about. The delay is
+  // the settle grace — the stream row this frame just wrote needs to age past it
+  // before the dependency reads as finished, and a queued follow-up armed by the
+  // line above needs its window to go out first.
+  requestWaitingSweep();
   // A run's work may have touched files and certainly advanced usage; the
   // realtime layer republishes whichever workspace topics are actually watched
   // (see `republishWatchedWorkspaceTopics`).

package/src/server/lib/omp/session/delete.server.ts

@@ -34,6 +34,7 @@ import { findSessionFileById } from '@/server/lib/omp/session/locator';
 import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
 import { invalidateOmpSidebarData } from '@/server/lib/omp/session/reader';
 import { emitRealtimeSignal } from '@/server/lib/realtime/signals.server';
+import { failWaitingOn } from '@/server/lib/waiting/store.server';
 import { siblingDirForSession } from '@/server/lib/omp/subagent/history/paths';
 import { isSinglePathSegment } from '@/server/lib/fs/path-segment';
 
@@ -122,6 +123,13 @@ export async function purgeSessionData(sessionId: string): Promise<SessionPurgeR
   const db = await getDb();
   const rowChanges = await purgeKabmoRows(db, sessionId);
 
+  // A prompt waiting on this session will never be released: the dependency is
+  // gone. Fail it BY NAME rather than letting it wait for a session that no
+  // longer exists — and keep the row, because its error text is the only thing
+  // that tells the user what happened to the prompt they wrote.
+  const strandedPrompts = await failWaitingOn(sessionId, 'The session being waited for was deleted.');
+  if (strandedPrompts > 0) emitRealtimeSignal('waiting-changed');
+
   // Both caches outlive the mutation by their own keys: the file list/scan pair
   // is mtime-keyed (a delete bumps the parent directory, but the memo can still
   // answer first) and the sidebar dataset is TTL'd, so without this the deleted

package/src/server/lib/omp/session/ownership.server.test.ts

@@ -22,7 +22,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { testPosix } from '@/test-support/platform';
@@ -39,6 +39,7 @@ import { getRpcSession, startRpcSession } from '@/server/lib/omp/rpc/session-reg
 import { removeDir } from '@/test-support/remove-dir';
 
 let root: string;
+let holderLog = '';
 let savedXdg: string | undefined;
 let savedDbPath: string | undefined;
 let savedAgentDir: string | undefined;
@@ -89,7 +90,12 @@ async function holdLeaseInChild(sessionId: string): Promise<number> {
   // The background process must NOT inherit the wrapper's stdout pipe, or
   // reading `$!` would block until that process exits.
   const inner = `exec ${JSON.stringify(process.execPath)} -e ${shellQuote(script)} ${shellQuote(lease)}`;
-  const child = Bun.spawn(['sh', '-c', `{ ${inner} >/dev/null 2>&1 & } ; echo $!`], {
+  // The holder's stderr goes to a FILE, not to `ignore`: when the child fails
+  // to take the lock (a missing libc, a broken FFI bind, a Bun that could not
+  // start), the reason is the only useful evidence, and discarding it is what
+  // made the Linux CI failure a bare "expected promise that rejects".
+  holderLog = join(root, 'holder.log');
+  const child = Bun.spawn(['sh', '-c', `{ ${inner} >>${shellQuote(holderLog)} 2>&1 & } ; echo $!`], {
     stdout: 'pipe',
     stderr: 'ignore',
     env: { ...Bun.env, XDG_STATE_HOME: root, PI_CODING_AGENT_DIR: join(root, 'agent') },
@@ -104,10 +110,45 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-/** Wait until a process other than this one actually holds the lease. */
+/**
+ * How long a detached `sh -c` holder gets to take the lock.
+ *
+ * Polling real time is unavoidable here: the condition is an OS `flock` taken
+ * by ANOTHER process, which no fake timer can advance. The budget is generous
+ * on purpose — a cold CI runner spawns Bun and imports the FFI helper before it
+ * locks — and a miss is an ERROR, never a silent proceed.
+ */
+const FOREIGN_HOLDER_TIMEOUT_MS = 15_000;
+
+/**
+ * Wait until a process other than this one actually holds the lease.
+ *
+ * THROWS rather than returning on timeout. It used to give up silently after
+ * 3 s, which turned an infrastructure gap into a green-looking test that proved
+ * nothing: `startRpcSession` then found no foreign owner, spawned normally, and
+ * the assertion below failed with "Expected promise that rejects" — measured on
+ * the Linux CI leg, where the helper burned its whole budget (3075 ms) and the
+ * real reason (the detached holder never took the lock) was nowhere in the
+ * output. A slow cold runner is a reason to wait longer, never to proceed.
+ */
 async function waitForForeignHolder(leasePath: string): Promise<void> {
-  for (let attempt = 0; attempt < 300; attempt++) {
+  const deadline = Date.now() + FOREIGN_HOLDER_TIMEOUT_MS;
+  for (;;) {
     if (leaseHeldByAnother(leasePath) === true && fileHolderPid(leasePath) !== process.pid) return;
+    if (Date.now() >= deadline) {
+      const holder = fileHolderPid(leasePath);
+      let log = '';
+      try {
+        log = readFileSync(holderLog, 'utf8').trim();
+      } catch {
+        // The child never wrote anything: it did not start.
+      }
+      throw new Error(
+        `no foreign holder took ${leasePath} within ${FOREIGN_HOLDER_TIMEOUT_MS} ms ` +
+          `(held=${String(leaseHeldByAnother(leasePath))}, holderPid=${String(holder)}, ` +
+          `childPids=${JSON.stringify(children)})${log ? `\nholder log:\n${log}` : '\nholder log: (empty)'}`,
+      );
+    }
     await Bun.sleep(10);
   }
 }

package/src/server/lib/panels/registry.server.ts

@@ -46,7 +46,7 @@ import { toManifest, toMarketplaceCatalog } from '@/server/lib/panels/manifest';
 import { basenameOf, bundleUrl, cssUrl, iconUrl, readmeUrlFor } from '@/server/lib/panels/assets.server';
 import { readBundledCatalog } from '@/server/lib/panels/bundled-catalog.server';
 import { describeIncompatibility, runningVersions } from '@/server/lib/panels/compat.server';
-import { pluginPanelKey } from '@/shared/lib/workspace/panel-ids';
+import { pluginEnablementKey } from '@/shared/lib/workspace/panel-ids';
 
 /** The marketplace root: `<data>/marketplace`, overridable for tests. */
 export function getMarketplaceDir(): string {
@@ -205,7 +205,7 @@ async function runPanelScan(): Promise<PanelScan> {
     // panel id (`plugin:<id>`), so one stored list answers for both kinds. Testing
     // the bare manifest id here made a disabled plugin still report `enabled:
     // true` while its panel stayed hidden — two answers for one question.
-    const enabled = !disabled.has(pluginPanelKey(manifest.id));
+    const enabled = !disabled.has(pluginEnablementKey(manifest.id));
     const entries = [manifest.app, manifest.server].filter((entry): entry is string => Boolean(entry));
     let missingEntry: string | undefined;
     for (const entry of entries) {

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

@@ -21,7 +21,8 @@
  */
 
 import { claimHeadQueueItem, hasQueuedItem, requeueHeadQueueItem } from '@/server/lib/queue/store.server';
-import { composeMessageWithTextAttachments } from '@/shared/lib/chat/attachments';
+import { applyModelSnapshot, promptCommand } from '@/server/lib/queue/payload';
+import { requestWaitingSweep } from '@/server/lib/waiting/sweep-trigger';
 import type { QueuedMessage } from '@/shared/types/chat';
 
 /** Settling time between agent_end and the next prompt dispatch. Small on
@@ -94,45 +95,15 @@ function clearPendingTimer(sessionId: string): void {
 
 /** 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. */
+ *  queued delivery did. Returns false when the dispatch failed.
+ *
+ *  The command itself is built by `queue/payload.ts`, shared with the waiting
+ *  prompt's dispatcher: both send a prompt nobody typed in this tab, from the
+ *  same persisted shape. */
 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 });
-      }
-    }
-    // Attachments reach this point as the persisted display fields — the live
-    // `File` never survived the queue's JSON round trip. The base64 payload and
-    // the MIME type are therefore read from the fields that DID persist:
-    // `dataBase64` for the bytes, `type` for the media type. (Matching on a
-    // `data:` preview used to yield zero images, because the composer's preview
-    // is a `blob:` object URL that the server cannot read.)
-    const images = item.attachments
-      .filter((a) => typeof a?.dataBase64 === 'string' && a.dataBase64.length > 0)
-      .map((a) => ({
-        type: 'image' as const,
-        data: a.dataBase64 as string,
-        mimeType: typeof a.type === 'string' && a.type.startsWith('image/') ? a.type : 'image/png',
-      }));
-    // Text attachments are inlined into the prompt, exactly as the composer
-    // does at send time — the item's own `text` is the raw composer input, so
-    // without this a queued file would deliver as a bare filename mention.
-    const textFiles = item.attachments
-      .filter((a) => typeof a?.content === 'string' && a.content.length > 0)
-      .map((a) => ({
-        name: typeof a.name === 'string' && a.name ? a.name : 'attachment',
-        mimeType: typeof a.type === 'string' ? a.type : 'text/plain',
-        content: a.content as string,
-        size: typeof a.size === 'number' ? a.size : (a.content as string).length,
-      }));
-    await session.send({
-      type: 'prompt',
-      message: composeMessageWithTextAttachments(item.text, textFiles),
-      ...(images.length ? { images } : {}),
-      ...(item.model ? { accessMode: item.model.accessMode } : {}),
-    });
+    await applyModelSnapshot(session.send, item.model);
+    await session.send(promptCommand({ text: item.text, attachments: item.attachments, model: item.model }));
     return true;
   } catch (error) {
     console.error(`[queue] delivery failed for session ${session.sessionId}:`, error);
@@ -231,7 +202,13 @@ async function deliverNext(session: QueueDeliveryHost): Promise<boolean> {
     return false;
   }
   const item = await claimHeadQueueItem(sessionId);
-  if (!item) return false;
+  if (!item) {
+    // The queue just drained: a prompt held until this session finished may now
+    // be free to go. The sweep re-checks the queue itself, so requesting one
+    // here cannot release a prompt ahead of an item that is still waiting.
+    requestWaitingSweep();
+    return false;
+  }
   const ok = await dispatchQueuedItem(session, item);
   if (!ok) {
     await requeueHeadQueueItem(sessionId, item);
@@ -240,9 +217,24 @@ async function deliverNext(session: QueueDeliveryHost): Promise<boolean> {
     await armRetryIfQueued(session);
     return false;
   }
+  // This delivery may have been the last one: ask for a sweep so a dependent
+  // prompt does not sit until the next tick after the queue emptied.
+  requestWaitingSweep();
   return true;
 }
 
+/**
+ * Whether this process already holds a delivery slot for the session.
+ *
+ * Read by the waiting-prompt sweep: a run end arms a delivery 500 ms out, so a
+ * dependency that looks settled for a moment may still have its queued
+ * follow-up about to go out. Waiting for the slot to clear is what keeps a
+ * dependent prompt from starting a second turn in the gap.
+ */
+export function hasPendingDelivery(sessionId: string): boolean {
+  return getPendingTimers().has(sessionId);
+}
+
 /**
  * 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

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

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The one place a stored prompt becomes an omp command.
+ *
+ * Two dispatchers send prompts nobody typed in this tab: the follow-up queue
+ * (`queue/delivery.server.ts`) and a prompt held until another session finishes
+ * (`waiting/runtime.server.ts`). They carry the SAME persisted shape — a text,
+ * an attachment list whose live `File` did not survive the JSON round trip, and
+ * an optional model snapshot — so a second copy of this assembly is how the two
+ * drift (one inlining a text file, the other sending a bare filename).
+ *
+ * The attachment rules are read off the fields that DID persist:
+ *
+ *   - `dataBase64` holds an image's bytes; `type` its media type. Matching on a
+ *     `data:` preview yields zero images, because the composer's preview is a
+ *     `blob:` object URL the server cannot read.
+ *   - `content` is an inlined text file. Without it a queued attachment
+ *     delivers as a filename mention instead of the file.
+ */
+
+import type { Attachment, QueuedMessageModel } from '@/shared/types/chat';
+import { composeMessageWithTextAttachments } from '@/shared/lib/chat/attachments';
+
+export interface StoredPrompt {
+  text: string;
+  attachments: Attachment[];
+  model: QueuedMessageModel | null;
+}
+
+/** The `prompt` command (with any images) a stored prompt dispatches. */
+export function promptCommand(prompt: StoredPrompt): Record<string, unknown> {
+  const images = prompt.attachments
+    .filter((attachment) => typeof attachment?.dataBase64 === 'string' && attachment.dataBase64.length > 0)
+    .map((attachment) => ({
+      type: 'image' as const,
+      data: attachment.dataBase64 as string,
+      mimeType: typeof attachment.type === 'string' && attachment.type.startsWith('image/')
+        ? attachment.type
+        : 'image/png',
+    }));
+  const textFiles = prompt.attachments
+    .filter((attachment) => typeof attachment?.content === 'string' && attachment.content.length > 0)
+    .map((attachment) => ({
+      name: typeof attachment.name === 'string' && attachment.name ? attachment.name : 'attachment',
+      mimeType: typeof attachment.type === 'string' ? attachment.type : 'text/plain',
+      content: attachment.content as string,
+      size: typeof attachment.size === 'number' ? attachment.size : (attachment.content as string).length,
+    }));
+  return {
+    type: 'prompt',
+    message: composeMessageWithTextAttachments(prompt.text, textFiles),
+    ...(images.length ? { images } : {}),
+    ...(prompt.model ? { accessMode: prompt.model.accessMode } : {}),
+  };
+}
+
+/** Apply a stored model snapshot to a live child before its prompt. */
+export async function applyModelSnapshot(
+  send: (command: Record<string, unknown>) => Promise<unknown>,
+  model: QueuedMessageModel | null,
+): Promise<void> {
+  if (!model) return;
+  await send({ type: 'set_model', provider: model.provider, modelId: model.modelId });
+  // 'auto' thinking leaves omp's level alone: the snapshot records "no pick",
+  // not a level named auto.
+  if (model.thinkingLevel !== 'auto') {
+    await send({ type: 'set_thinking_level', level: model.thinkingLevel });
+  }
+}

package/src/server/lib/realtime/signals.server.ts

@@ -56,7 +56,16 @@ export type RealtimeSignal =
    * snapshot and then never moved — the panels rendered whatever existed when
    * they subscribed and only a reload showed the new state.
    */
-  | 'session-data-dirty';
+  | 'session-data-dirty'
+  /**
+   * A waiting prompt was created, cancelled, dispatched or failed.
+   *
+   * Both halves read it: the server republishes the `waiting` topic, and the
+   * client's dispatch watcher adopts the session a prompt became. Nothing else
+   * reports a dispatch — no user action causes it, and the spawned session's own
+   * transcript is seconds away.
+   */
+  | 'waiting-changed';
 
 export interface RealtimeSignalEvent {
   signal: RealtimeSignal;

package/src/server/lib/realtime/topics/catalog.server.ts

@@ -22,6 +22,7 @@ import {
   TOPIC_SIDEBAR,
   TOPIC_SIDEBAR_STATUS,
   TOPIC_USAGE,
+  TOPIC_WAITING,
   sessionPlanTopic,
   sessionQueueTopic,
   sessionTelemetryTopic,
@@ -67,6 +68,7 @@ export const EXACT_TOPICS = new Map<string, TopicDescriptor>([
   [TOPIC_USAGE, { resolve: () => globalDescriptor(TOPIC_USAGE).resolve(TOPIC_USAGE) }],
   [TOPIC_PANELS, { resolve: () => globalDescriptor(TOPIC_PANELS).resolve(TOPIC_PANELS) }],
   [TOPIC_MODELS, { resolve: () => globalDescriptor(TOPIC_MODELS).resolve(TOPIC_MODELS) }],
+  [TOPIC_WAITING, { resolve: () => globalDescriptor(TOPIC_WAITING).resolve(TOPIC_WAITING) }],
 ]);
 
 /** Suffixes a `session:<id>:<suffix>` topic may carry. */