ompchamber 0.6.0 → 0.8.0

package/src/client/hooks/chat/timeline/session-load.ts

@@ -18,10 +18,11 @@
  */
 
 import type { Dispatch, RefObject, SetStateAction } from 'preact/compat';
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
 
 import type { ChatMessageData } from '@/shared/types';
 import { SESSION_META_RETRY_SCHEDULE_MS } from '@/shared/lib/workspace/refresh-cadence';
+import { useSessionPagination } from '@/client/hooks/chat/timeline/session-pagination';
 
 export interface SessionDataShape {
   id?: string;
@@ -31,6 +32,12 @@ export interface SessionDataShape {
   messages?: any[];
 }
 
+/** Session identity a spawn established before omp's JSONL is readable. */
+export interface SessionSeed {
+  model?: { provider: string; modelId: string } | null;
+  thinkingLevel?: string | null;
+}
+
 export interface UseSessionLoadDeps {
   sessionId: string | null;
   setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
@@ -59,24 +66,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
   const { sessionId, setLocalMessages, setGenerating, isGeneratingRef, aiPlaceholderIdRef, localMessagesRef, optimisticUserIdRef, cancelStreamingCoalescer, metaRefreshedRef, scrollRef } = deps;
 
   const [sessionData, setSessionData] = useState<SessionDataShape | null>(null);
-  // History pagination state: the first fetch receives the newest window only;
-  // scrolling to the top pages further back via ?before=oldestIndex.
-  const [hasMore, setHasMore] = useState(false);
-  const [oldestIndex, setOldestIndex] = useState(0);
-  const [loadingOlder, setLoadingOlder] = useState(false);
-  // Sticky failure flag for the "Load earlier messages" affordance: a failed
-  // page fetch must keep the button visible (retryable) instead of silently
-  // dropping hasMore, which made the button vanish with no feedback.
-  const [loadOlderError, setLoadOlderError] = useState(false);
-  // Bumped on every successful older-window prepend; the scroll-anchor layout
-  // effect keys on it (its other deps have stable identities, so it needs an
-  // explicit change signal per commit).
-  const [prependTick, setPrependTick] = useState(0);
-  const loadingOlderRef = useRef(false);
   const [sessionLoading, setSessionLoading] = useState(false);
-  // Set while prepending older rows; the layout effect below re-anchors the
-  // viewport to the content the user was reading instead of jumping.
-  const pendingScrollAnchorRef = useRef<{ prevHeight: number; prevTop: number } | null>(null);
   const prevSessionIdRef = useRef<string | null>(null);
   // Real session id adopted by a fresh spawn ("new-…" → UUID). onAgentStart
   // may fire before React re-renders with the new URL, so it reads the id
@@ -84,16 +74,33 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
   const adoptedSessionIdRef = useRef<string | null>(null);
   // Model seeded from the spawn response; kept until the JSONL writes model_change.
   const seededModelRef = useRef<{ provider: string; modelId: string } | null>(null);
+  // Thinking level seeded from the spawn response. The spawn's
+  // `set_thinking_level` IS the level this session runs, and `/api/chat/:id`
+  // cannot report it until omp's JSONL is locatable — until then the loader
+  // answers from the chamber DB copy, which carries no thinkingLevel at all.
+  // Without this seed the composer that takes over the pending view falls back
+  // to a catalog default and claims a level the run never used.
+  const seededThinkingLevelRef = useRef<string | null>(null);
 
   const applySessionData = useCallback((incoming: SessionDataShape) => {
     if (incoming.model && typeof incoming.model === 'object') seededModelRef.current = incoming.model;
     const model = incoming.model ?? (isGeneratingRef.current ? seededModelRef.current ?? undefined : undefined);
-    setSessionData({ ...incoming, model });
+    const thinkingLevel = incoming.thinkingLevel ?? seededThinkingLevelRef.current ?? undefined;
+    setSessionData({ ...incoming, model, thinkingLevel });
   }, []);
 
   const sessionIdRef = useRef(sessionId);
   sessionIdRef.current = sessionId;
 
+  // Older-window pagination (cursor, retry flag, scroll anchoring) lives in its
+  // own hook so this one stays under the repo's per-file size ceiling.
+  const { hasMore, loadingOlder, loadOlderError, loadOlder, resetPages, applyWindow } = useSessionPagination({
+    sessionId,
+    sessionIdRef,
+    setLocalMessages,
+    scrollRef,
+  });
+
   /** Re-fetch the session's title/metadata after the omp JSONL has been
    *  written (spawn or agent end) so the navbar and context panel show the
    *  real session title instead of the default. Retries on a front-loaded
@@ -127,9 +134,17 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
     tryFetch();
   }, [applySessionData]);
 
-  const setSessionModelWithSeed = useCallback((model: { provider: string; modelId: string } | null) => {
-    seededModelRef.current = model;
-    setSessionData(prev => ({ ...(prev ?? {}), model: model ?? undefined }));
+  /** Adopt a spawn's session identity: the model and the thinking level the
+   *  first prompt is running with. Only the fields a caller supplies are
+   *  written, so a null model/level leaves the previous value untouched. */
+  const seedSession = useCallback((seed: SessionSeed) => {
+    if (seed.model) seededModelRef.current = seed.model;
+    if (seed.thinkingLevel) seededThinkingLevelRef.current = seed.thinkingLevel;
+    setSessionData(prev => ({
+      ...(prev ?? {}),
+      ...(seed.model ? { model: seed.model } : {}),
+      ...(seed.thinkingLevel ? { thinkingLevel: seed.thinkingLevel } : {}),
+    }));
   }, []);
 
   /** Whether the optimistic bubble set currently owns the timeline tail (a
@@ -159,6 +174,14 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
         setGenerating(false);
         adoptedSessionIdRef.current = null;
         seededModelRef.current = null;
+        // Metadata (model / thinking level) belongs to ONE session: leaving it
+        // in place let a pending "new-…" composer — and any other session's
+        // composer — display a level that session never ran with, until the
+        // fetch replaced it.
+        setSessionData(null);
+        // The thinking seed belongs to the previous session's spawn; keeping it
+        // would report that level for the newly opened session.
+        seededThinkingLevelRef.current = null;
         // The placeholder/optimistic ids belong to the PREVIOUS session's
         // in-flight send; message_end never arrives after a switch away (the
         // stream is disconnected), so they must be dropped here. A stale
@@ -174,11 +197,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
       }
       // Reset pagination cursor on every session switch — the window belongs
       // to the previous session otherwise.
-      setHasMore(false);
-      setOldestIndex(0);
-      loadingOlderRef.current = false;
-      setLoadingOlder(false);
-      setLoadOlderError(false);
+      resetPages();
       // metaRefreshedRef must NOT survive a session switch — including a
       // spawn adoption. It is the once-per-session guard in onAgentStart
       // (omp-callbacks.ts); keeping the stale value here ate the retrigger,
@@ -216,8 +235,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
             } else if (!sessionId.startsWith('new-') && !optimisticOwnsTail) {
               setLocalMessages([]);
             }
-            if (typeof data.hasMore === 'boolean') setHasMore(data.hasMore);
-            if (typeof data.oldestIndex === 'number') setOldestIndex(data.oldestIndex);
+            applyWindow(data.hasMore, data.oldestIndex);
           } else {
             setSessionData(null);
             if (!timelineOwnedByOptimistic()) setLocalMessages([]);
@@ -243,79 +261,6 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sessionId, applySessionData, timelineOwnedByOptimistic, setLocalMessages, setGenerating]);
 
-  /** Page the next older window into the timeline. Called from the click
-   *  handler and the scroll handler when the viewport reaches the top; a no-op
-   *  while a page is in flight, when the session has no more history, or while
-   *  the session is a pending optimistic spawn. Prepending older rows only
-   *  grows the list ABOVE the tail, so it is safe while the agent is
-   *  generating — unlike a committed refetch, it never clobbers the AI
-   *  placeholder, and blocking it made the button feel dead mid-run. */
-  const loadOlder = useCallback(() => {
-    if (!sessionId || sessionId.startsWith('new-')) return;
-    if (!hasMore || loadingOlderRef.current) return;
-    loadingOlderRef.current = true;
-    setLoadingOlder(true);
-    setLoadOlderError(false);
-    const el = scrollRef?.current;
-    if (el) pendingScrollAnchorRef.current = { prevHeight: el.scrollHeight, prevTop: el.scrollTop };
-    // Session id snapshot: prepending a window fetched for the PREVIOUS
-    // session into the freshly-switched timeline is worse than dropping the
-    // page, so the response is discarded if the user switched mid-flight.
-    const requestedSessionId = sessionId;
-    fetch(`/api/chat/${sessionId}?before=${oldestIndex}`)
-      .then(res => {
-        if (!res.ok) throw new Error(`HTTP ${res.status}`);
-        return res.json();
-      })
-      .then((data: { session?: { messages?: ChatMessageData[] }; hasMore?: boolean; oldestIndex?: number }) => {
-        // The main load effect may have cleared/repurposed localMessages for a
-        // new session while this fetch was in flight.
-        if (sessionIdRef.current !== requestedSessionId) return;
-        const older = data.session?.messages ?? [];
-        setHasMore(Boolean(data.hasMore));
-        if (typeof data.oldestIndex === 'number') setOldestIndex(data.oldestIndex);
-        if (older.length === 0) {
-          // No rows prepended: the recorded anchor is stale — drop it so a
-          // later tick cannot apply it against the wrong geometry.
-          pendingScrollAnchorRef.current = null;
-          return;
-        }
-        setLocalMessages(prev => {
-          // Drop overlap guard: the server window is index-based, so the
-          // fetched slice is strictly older than everything already mounted.
-          return [...older, ...prev];
-        });
-        // Bump the prepend tick so the layout effect below re-runs for THIS
-        // commit — it previously depended only on stable identities and ran
-        // exactly once at mount, so the viewport anchor never fired and every
-        // pagination jump snapped the user to the (shifted) top.
-        setPrependTick(t => t + 1);
-      })
-      .catch(() => {
-        // Keep the button mounted and marked for retry; a swallowed failure
-        // previously also cleared hasMore on the next full reload path.
-        if (sessionIdRef.current === requestedSessionId) setLoadOlderError(true);
-      })
-      .finally(() => {
-        loadingOlderRef.current = false;
-        setLoadingOlder(false);
-      });
-  }, [sessionId, hasMore, oldestIndex, scrollRef, setLocalMessages]);
-
-  // Position preservation: after older rows commit above the viewport, shift
-  // scrollTop by the height delta so the rows the user was reading stay put.
-  // prependTick changes on every prepend — without it the effect ran only at
-  // mount (its other deps are stable) and never re-anchored.
-  useLayoutEffect(() => {
-    const anchor = pendingScrollAnchorRef.current;
-    if (!anchor) return;
-    const el = scrollRef?.current;
-    if (!el) return;
-    pendingScrollAnchorRef.current = null;
-    const delta = el.scrollHeight - anchor.prevHeight;
-    if (delta > 0) el.scrollTop = anchor.prevTop + delta;
-  }, [prependTick, scrollRef]);
-
   return {
     sessionData,
     hasMore,
@@ -324,10 +269,7 @@ export function useSessionLoad(deps: UseSessionLoadDeps) {
     sessionLoading,
     loadOlder,
     adoptedSessionIdRef,
-    seededModelRef,
-    applySessionData,
     refreshSessionMeta,
-    setSessionModel: setSessionModelWithSeed,
-    timelineOwnedByOptimistic,
+    seedSession,
   };
 }

package/src/client/hooks/chat/timeline/session-pagination.ts

@@ -0,0 +1,144 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Older-window pagination for the chamber timeline: pages
+ * `/api/chat/:id?before=` into the head of the message list and keeps the
+ * viewport anchored on the rows the user was reading. Extracted from
+ * useSessionLoad so that hook stays under the repo's per-file size ceiling.
+ */
+
+import type { Dispatch, RefObject, SetStateAction } from 'preact/compat';
+import { useCallback, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import type { ChatMessageData } from '@/shared/types';
+
+export interface UseSessionPaginationDeps {
+  sessionId: string | null;
+  /** Live session id, read when the page response lands: a window fetched for
+   *  the previous session is worse than a dropped page. */
+  sessionIdRef: { current: string | null };
+  setLocalMessages: Dispatch<SetStateAction<ChatMessageData[]>>;
+  /** Scroll container of the timeline: lets loadOlder preserve the viewport
+   *  position when older rows are prepended above it. */
+  scrollRef?: RefObject<HTMLDivElement>;
+}
+
+export interface SessionPagination {
+  hasMore: boolean;
+  loadingOlder: boolean;
+  /** Sticky failure flag for the "Load earlier messages" affordance: a failed
+   *  page fetch must keep the button visible (retryable) instead of silently
+   *  dropping hasMore, which made the button vanish with no feedback. */
+  loadOlderError: boolean;
+  loadOlder: () => void;
+  /** Forget the cursor and the retry flag — a window belongs to one session. */
+  resetPages: () => void;
+  /** Adopt the window metadata a session load returned. */
+  applyWindow: (hasMore: unknown, oldestIndex: unknown) => void;
+}
+
+export function useSessionPagination(deps: UseSessionPaginationDeps): SessionPagination {
+  const { sessionId, sessionIdRef, setLocalMessages, scrollRef } = deps;
+
+  const [hasMore, setHasMore] = useState(false);
+  const [oldestIndex, setOldestIndex] = useState(0);
+  const [loadingOlder, setLoadingOlder] = useState(false);
+  const [loadOlderError, setLoadOlderError] = useState(false);
+  // Bumped on every successful older-window prepend; the scroll-anchor layout
+  // effect keys on it (its other deps have stable identities, so it needs an
+  // explicit change signal per commit).
+  const [prependTick, setPrependTick] = useState(0);
+  const loadingOlderRef = useRef(false);
+  // Set while prepending older rows; the layout effect below re-anchors the
+  // viewport to the content the user was reading instead of jumping.
+  const pendingScrollAnchorRef = useRef<{ prevHeight: number; prevTop: number } | null>(null);
+
+  const resetPages = useCallback(() => {
+    setHasMore(false);
+    setOldestIndex(0);
+    loadingOlderRef.current = false;
+    setLoadingOlder(false);
+    setLoadOlderError(false);
+  }, []);
+
+  const applyWindow = useCallback((hasMoreFromLoad: unknown, oldestIndexFromLoad: unknown) => {
+    if (typeof hasMoreFromLoad === 'boolean') setHasMore(hasMoreFromLoad);
+    if (typeof oldestIndexFromLoad === 'number') setOldestIndex(oldestIndexFromLoad);
+  }, []);
+
+  /** Page the next older window into the timeline. Called from the click
+   *  handler and the scroll handler when the viewport reaches the top; a no-op
+   *  while a page is in flight, when the session has no more history, or while
+   *  the session is a pending optimistic spawn. Prepending older rows only
+   *  grows the list ABOVE the tail, so it is safe while the agent is
+   *  generating — unlike a committed refetch, it never clobbers the AI
+   *  placeholder, and blocking it made the button feel dead mid-run. */
+  const loadOlder = useCallback(() => {
+    if (!sessionId || sessionId.startsWith('new-')) return;
+    if (!hasMore || loadingOlderRef.current) return;
+    loadingOlderRef.current = true;
+    setLoadingOlder(true);
+    setLoadOlderError(false);
+    const el = scrollRef?.current;
+    if (el) pendingScrollAnchorRef.current = { prevHeight: el.scrollHeight, prevTop: el.scrollTop };
+    // Session id snapshot: prepending a window fetched for the PREVIOUS
+    // session into the freshly-switched timeline is worse than dropping the
+    // page, so the response is discarded if the user switched mid-flight.
+    const requestedSessionId = sessionId;
+    fetch(`/api/chat/${sessionId}?before=${oldestIndex}`)
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((data: { session?: { messages?: ChatMessageData[] }; hasMore?: boolean; oldestIndex?: number }) => {
+        // The main load effect may have cleared/repurposed localMessages for a
+        // new session while this fetch was in flight.
+        if (sessionIdRef.current !== requestedSessionId) return;
+        const older = data.session?.messages ?? [];
+        applyWindow(data.hasMore, data.oldestIndex);
+        if (older.length === 0) {
+          // No rows prepended: the recorded anchor is stale — drop it so a
+          // later tick cannot apply it against the wrong geometry.
+          pendingScrollAnchorRef.current = null;
+          return;
+        }
+        setLocalMessages(prev => {
+          // Drop overlap guard: the server window is index-based, so the
+          // fetched slice is strictly older than everything already mounted.
+          return [...older, ...prev];
+        });
+        // Bump the prepend tick so the layout effect below re-runs for THIS
+        // commit — it previously depended only on stable identities and ran
+        // exactly once at mount, so the viewport anchor never fired and every
+        // pagination jump snapped the user to the (shifted) top.
+        setPrependTick(t => t + 1);
+      })
+      .catch(() => {
+        // Keep the button mounted and marked for retry; a swallowed failure
+        // previously also cleared hasMore on the next full reload path.
+        if (sessionIdRef.current === requestedSessionId) setLoadOlderError(true);
+      })
+      .finally(() => {
+        loadingOlderRef.current = false;
+        setLoadingOlder(false);
+      });
+  }, [sessionId, sessionIdRef, hasMore, oldestIndex, scrollRef, setLocalMessages, applyWindow]);
+
+  // Position preservation: after older rows commit above the viewport, shift
+  // scrollTop by the height delta so the rows the user was reading stay put.
+  // prependTick changes on every prepend — without it the effect ran only at
+  // mount (its other deps are stable) and never re-anchored.
+  useLayoutEffect(() => {
+    const anchor = pendingScrollAnchorRef.current;
+    if (!anchor) return;
+    const el = scrollRef?.current;
+    if (!el) return;
+    pendingScrollAnchorRef.current = null;
+    const delta = el.scrollHeight - anchor.prevHeight;
+    if (delta > 0) el.scrollTop = anchor.prevTop + delta;
+  }, [prependTick, scrollRef]);
+
+  return { hasMore, loadingOlder, loadOlderError, loadOlder, resetPages, applyWindow };
+}

package/src/client/hooks/editor/use-code-window.ts

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'preact/hooks';
+import type { RefObject } from 'preact';
+
+import {
+  codeWindow,
+  firstWindow,
+  resolveWindow,
+  sameWindow,
+  type CodeWindow,
+  type LineGeometry,
+  type LineWindow,
+} from '@/shared/lib/code/lazy-window';
+
+export interface UseCodeWindowOptions {
+  /** The surface's root box: the frame every line offset in `geometry` is measured from. */
+  rootRef: RefObject<HTMLElement | null>;
+  /** Lines in the document on screen. */
+  lineCount: number;
+  /** Document geometry, or null until the wrap/row measurement lands. */
+  geometry: LineGeometry | null;
+  /** False for short documents (they render whole) and when geometry cannot be measured. */
+  enabled: boolean;
+}
+
+/** Nearest ancestor the document scrolls inside, or null when the page itself scrolls. */
+function findScrollContainer(element: HTMLElement): HTMLElement | null {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    const overflowY = getComputedStyle(node).overflowY;
+    if ((overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') && node.scrollHeight > node.clientHeight) {
+      return node;
+    }
+  }
+  return null;
+}
+
+/**
+ * The lines visible inside the scroll container `root` lives in.
+ *
+ * Both rectangles are read in viewport coordinates, so this needs no knowledge
+ * of scroll offsets: the part of the editor's box the container actually shows
+ * is exactly the band between the two.
+ */
+function visibleWindow(root: HTMLElement, geometry: LineGeometry): LineWindow {
+  const frameTop = root.getBoundingClientRect().top;
+  const container = findScrollContainer(root);
+  const viewTop = container ? container.getBoundingClientRect().top : 0;
+  const viewBottom = container
+    ? container.getBoundingClientRect().bottom
+    : globalThis.innerHeight || geometry.rowHeight;
+  return resolveWindow(geometry, viewTop - frameTop, viewBottom - viewTop);
+}
+
+/**
+ * Rendering window for the lazy editor surface.
+ *
+ * A long document is highlighted, gutters and all, only where it can be seen;
+ * this hook owns which lines those are and re-resolves them on scroll, on
+ * resize, and whenever the geometry moves (a keystroke re-wraps a line). The
+ * scroll listener is a capturing one on the window: scroll events do not
+ * bubble, but they do reach a capturing listener, so the surface follows
+ * whichever ancestor scrolls — the desktop editor panel, the phone's
+ * full-screen editor, or the page.
+ *
+ * Returns null for a document that renders whole, which is the caller's cue to
+ * keep the plain, unwindowed surface.
+ */
+export function useCodeWindow({ rootRef, lineCount, geometry, enabled }: UseCodeWindowOptions): CodeWindow | null {
+  const [lineWindow, setLineWindow] = useState<LineWindow | null>(null);
+
+  const compute = useCallback(() => {
+    const root = rootRef.current;
+    if (!enabled || !root) return;
+    const next = geometry ? visibleWindow(root, geometry) : firstWindow(lineCount);
+    setLineWindow((previous) => (sameWindow(previous, next) ? previous : next));
+  }, [enabled, geometry, lineCount, rootRef]);
+
+  // Layout effect: the first window has to be resolved before the browser
+  // paints, or a long document flashes its untouched opening lines.
+  useLayoutEffect(() => {
+    compute();
+  }, [compute]);
+
+  // The listeners follow `enabled`, not `compute`: re-resolving on every
+  // keystroke must not tear down and rebuild the observer each time.
+  const computeRef = useRef(compute);
+  computeRef.current = compute;
+  useEffect(() => {
+    if (!enabled) return;
+    let frame = 0;
+    const schedule = () => {
+      if (frame) return;
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        computeRef.current();
+      });
+    };
+    window.addEventListener('scroll', schedule, { passive: true, capture: true });
+    window.addEventListener('resize', schedule);
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(schedule);
+    const root = rootRef.current;
+    if (root) observer?.observe(root);
+    return () => {
+      if (frame) cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', schedule, { capture: true });
+      window.removeEventListener('resize', schedule);
+      observer?.disconnect();
+    };
+  }, [enabled, rootRef]);
+
+  if (!enabled) return null;
+  if (!geometry) {
+    // First commit: the layout effect above lands the real window in the same
+    // frame, so this only bounds how much the opening render is allowed to draw.
+    const opening = firstWindow(lineCount);
+    return { ...opening, top: 0, bottom: 0, breakAtEnd: opening.end >= lineCount };
+  }
+  return codeWindow(geometry, lineWindow ?? firstWindow(geometry.lineCount));
+}

package/src/client/hooks/ui/input-required-alert.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * App-wide "an agent is blocked on you" cue.
+ *
+ * It runs off the shared session list rather than the open timeline, which is
+ * the whole point: the agent that needs an answer is usually NOT the session on
+ * screen — you sent a prompt in one workspace and moved to another. The list is
+ * fed by the sidebar loader (which derives `awaitingInput` from the live omp
+ * process registry), so the cue reaches the client even when that process'
+ * session was never opened.
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+import type { WorkspaceFolderData } from '@/shared/types';
+import { triggerInputRequiredSound } from '@/client/hooks/ui/notification-sound';
+
+export function useInputRequiredAlert(folders: WorkspaceFolderData[]): void {
+  // Null until the first snapshot: a page load must not replay a cue for
+  // questions that were already waiting before it.
+  const knownRef = useRef<Set<string> | null>(null);
+
+  useEffect(() => {
+    const waiting = new Set<string>();
+    for (const folder of folders) {
+      for (const session of folder.sessions ?? []) {
+        if (session.awaitingInput) waiting.add(String(session.id));
+      }
+    }
+
+    const known = knownRef.current;
+    knownRef.current = waiting;
+    if (!known) return;
+    for (const id of waiting) {
+      if (known.has(id)) continue;
+      triggerInputRequiredSound();
+      return;
+    }
+  }, [folders]);
+}

package/src/client/hooks/ui/notification-sound.ts

@@ -72,6 +72,60 @@ export function playNotificationSound() {
   }
 }
 
+/**
+ * Web Audio cue for "the agent is blocked on you" — an ask question or an
+ * approval gate. Deliberately the mirror image of the completion chime: a
+ * triangle wave stepping DOWN (A5 → E5) instead of two sines climbing, so the
+ * two are never mistaken for each other when the tab is in the background.
+ */
+export function playInputRequiredSound() {
+  if (typeof window === 'undefined') return;
+
+  try {
+    const AudioCtx = window.AudioContext || (window as WebkitWindow).webkitAudioContext;
+    if (!AudioCtx) return;
+
+    const ctx = new AudioCtx();
+    if (ctx.state === 'suspended') {
+      ctx.resume();
+    }
+
+    const now = ctx.currentTime;
+    const notes = [
+      { at: 0, frequency: 880, duration: 0.18, peak: 0.11 },
+      { at: 0.16, frequency: 659.25, duration: 0.46, peak: 0.13 },
+    ];
+
+    for (const note of notes) {
+      const osc = ctx.createOscillator();
+      const gain = ctx.createGain();
+
+      osc.type = 'triangle';
+      osc.frequency.setValueAtTime(note.frequency, now + note.at);
+
+      gain.gain.setValueAtTime(0, now + note.at);
+      gain.gain.linearRampToValueAtTime(note.peak, now + note.at + 0.015);
+      gain.gain.exponentialRampToValueAtTime(0.0001, now + note.at + note.duration);
+
+      osc.connect(gain);
+      gain.connect(ctx.destination);
+
+      osc.start(now + note.at);
+      osc.stop(now + note.at + note.duration);
+    }
+
+    setTimeout(() => {
+      try {
+        ctx.close();
+      } catch {
+        // Safe to ignore
+      }
+    }, 800);
+  } catch (err) {
+    console.warn('Unable to play input-required audio cue:', err);
+  }
+}
+
 /**
  * Checks whether chat completion sound is enabled in user preferences.
  */
@@ -91,6 +145,17 @@ export function triggerChatCompletionSound(appSettings?: Record<string, any>) {
   }
 }
 
+/**
+ * Triggers the input-required cue, gated by the same notification preference as
+ * the completion chime. Reads settings from the primed snapshot: the alert fires
+ * from the app-wide session list, which has no settings props to thread.
+ */
+export function triggerInputRequiredSound() {
+  if (isChatSoundEnabled()) {
+    playInputRequiredSound();
+  }
+}
+
 export function useNotificationSound() {
   const play = useCallback(() => {
     playNotificationSound();

package/src/client/hooks/ui/theme.ts

@@ -1,6 +1,25 @@
 import { useCallback, useEffect, useState } from 'preact/hooks';
 import { useChamberSettingsWriter } from '@/client/hooks/settings/use-chamber-setting';
 
+/** Broadcast on every theme write. Detail is the new theme id; the
+ *  `data-theme` attribute on `<html>` is the durable copy of the same fact. */
+export const THEME_CHANGED_EVENT = 'omp:theme-changed';
+
+/**
+ * Point the document at `theme` and announce it.
+ *
+ * The single writer path for the theme: the navbar toggle and the settings
+ * modal both call this, because a writer that only sets `data-theme` leaves
+ * runtime consumers (the mermaid hydrator re-renders diagrams per theme) on the
+ * previous palette until the next reload. CSS reads the attribute; listeners
+ * watch the attribute too, so this stays correct even if the event is missed.
+ */
+export function applyDocumentTheme(theme: string): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.dataset.theme = theme;
+  window.dispatchEvent(new CustomEvent(THEME_CHANGED_EVENT, { detail: theme }));
+}
+
 export function useTheme() {
   const writeChamberSettings = useChamberSettingsWriter();
   const [theme, setThemeState] = useState<string>(() => {
@@ -60,12 +79,9 @@ export function useTheme() {
   }, []);
 
   const setTheme = useCallback((newTheme: string) => {
-    if (typeof document !== 'undefined') {
-      document.documentElement.dataset.theme = newTheme;
-      setThemeState(newTheme);
-      writeChamberSettings({ theme: newTheme });
-      window.dispatchEvent(new CustomEvent('omp:theme-changed', { detail: newTheme }));
-    }
+    applyDocumentTheme(newTheme);
+    setThemeState(newTheme);
+    writeChamberSettings({ theme: newTheme });
   }, [writeChamberSettings]);
 
   const toggleTheme = useCallback(() => {