mulmoclaude 0.1.0

package/src/composables/useNotifications.ts

@@ -0,0 +1,90 @@
+// Web-side subscriber for the `notifications` pub-sub channel.
+// Stores incoming NotificationPayloads for the bell badge + panel.
+//
+// Uses a singleton subscription pattern: the first component that
+// calls useNotifications() subscribes to the pub-sub channel; the
+// last one to unmount unsubscribes. All consumers share the same
+// module-level state (notifications + readAt).
+
+import { onUnmounted, ref, computed, type Ref, type ComputedRef } from "vue";
+import { PUBSUB_CHANNELS } from "../config/pubsubChannels";
+import { usePubSub } from "./usePubSub";
+import { NOTIFICATION_KINDS } from "../types/notification";
+import type { NotificationPayload } from "../types/notification";
+import { isRecord } from "../utils/types";
+
+const MAX_RECENT = 50;
+
+const VALID_KINDS = new Set<string>(Object.values(NOTIFICATION_KINDS));
+
+function isNotificationPayload(value: unknown): value is NotificationPayload {
+  if (!isRecord(value)) return false;
+  if (typeof value.id !== "string") return false;
+  if (typeof value.kind !== "string" || !VALID_KINDS.has(value.kind)) return false;
+  if (typeof value.title !== "string") return false;
+  if (typeof value.firedAt !== "string") return false;
+  if (!isValidAction(value.action)) return false;
+  return true;
+}
+
+function isValidAction(action: unknown): boolean {
+  if (!isRecord(action)) return false;
+  return typeof action.type === "string";
+}
+
+// Module-level state so all components share the same list.
+const notifications = ref<NotificationPayload[]>([]);
+const readAt = ref<string | null>(null);
+
+// Singleton subscription — ref-counted across consumers.
+let subscriberCount = 0;
+let unsubscribeFn: (() => void) | null = null;
+
+function ensureSubscribed(subscribe: ReturnType<typeof usePubSub>["subscribe"]): void {
+  subscriberCount++;
+  if (unsubscribeFn) return; // already listening
+  unsubscribeFn = subscribe(PUBSUB_CHANNELS.notifications, (data) => {
+    if (!isNotificationPayload(data)) return;
+    notifications.value = [data, ...notifications.value].slice(0, MAX_RECENT);
+  });
+}
+
+function releaseSubscription(): void {
+  subscriberCount--;
+  if (subscriberCount <= 0 && unsubscribeFn) {
+    unsubscribeFn();
+    unsubscribeFn = null;
+    subscriberCount = 0;
+  }
+}
+
+export function useNotifications(): {
+  notifications: Ref<NotificationPayload[]>;
+  latest: ComputedRef<NotificationPayload | null>;
+  unreadCount: ComputedRef<number>;
+  markAllRead: () => void;
+  dismiss: (id: string) => void;
+} {
+  const { subscribe } = usePubSub();
+  ensureSubscribed(subscribe);
+  onUnmounted(releaseSubscription);
+
+  const latest = computed(() => notifications.value[0] ?? null);
+
+  const unreadCount = computed(() => {
+    if (!readAt.value) return notifications.value.length;
+    return notifications.value.filter((n) => n.firedAt > readAt.value!).length;
+  });
+
+  function markAllRead(): void {
+    if (notifications.value.length > 0) {
+      readAt.value = notifications.value[0].firedAt;
+    }
+  }
+
+  function dismiss(id: string): void {
+    notifications.value = notifications.value.filter((n) => n.id !== id);
+  }
+
+  return { notifications, latest, unreadCount, markAllRead, dismiss };
+}

package/src/composables/usePdfDownload.ts

@@ -0,0 +1,60 @@
+// Shared PDF download logic used by the markdown and textResponse
+// plugin views. Encapsulates the POST /api/pdf/markdown call, the
+// in-flight `pdfDownloading` flag, the `pdfError` state, and the
+// blob-to-download dance (createObjectURL → click → revoke).
+//
+// Error handling contract: any failure path (network, non-OK HTTP,
+// malformed blob) sets pdfDownloading back to false and populates
+// pdfError with a user-facing message. Callers can render pdfError
+// below the download button.
+
+import { ref, type Ref } from "vue";
+import { API_ROUTES } from "../config/apiRoutes";
+import { apiFetchRaw } from "../utils/api";
+import { errorMessage } from "../utils/errors";
+
+export interface UsePdfDownloadHandle {
+  pdfDownloading: Ref<boolean>;
+  pdfError: Ref<string | null>;
+  downloadPdf: (markdown: string, filename: string) => Promise<void>;
+}
+
+export function usePdfDownload(): UsePdfDownloadHandle {
+  const pdfDownloading = ref(false);
+  const pdfError = ref<string | null>(null);
+
+  async function downloadPdf(markdown: string, filename: string): Promise<void> {
+    pdfError.value = null;
+    pdfDownloading.value = true;
+    let url: string | null = null;
+    try {
+      // PDF endpoint returns a binary blob, not JSON — use the raw
+      // Response escape hatch so we can call `.blob()` ourselves.
+      const response = await apiFetchRaw(API_ROUTES.pdf.markdown, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ markdown, filename }),
+      });
+      if (!response.ok) {
+        const errText = await response.text().catch(() => "");
+        pdfError.value = `PDF error ${response.status}: ${errText}`;
+        return;
+      }
+      const blob = await response.blob();
+      url = URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = filename;
+      a.click();
+    } catch (err) {
+      pdfError.value = errorMessage(err);
+    } finally {
+      // Always clean up the object URL and release the in-flight flag
+      // so the button is never left disabled forever.
+      if (url) URL.revokeObjectURL(url);
+      pdfDownloading.value = false;
+    }
+  }
+
+  return { pdfDownloading, pdfError, downloadPdf };
+}

package/src/composables/usePendingCalls.ts

@@ -0,0 +1,77 @@
+// Composable that bundles the "minimum visible duration" trick for
+// pending tool call rows: while the agent is running, tick a counter
+// every 50ms so the `pendingCalls` computed re-evaluates and any
+// freshly-resolved call stays visible for at least PENDING_MIN_MS
+// before disappearing. After the run ends, schedule one final tick
+// so the computed clears the lingering rows.
+
+import { computed, ref, watch, type ComputedRef, type Ref } from "vue";
+import type { ToolCallHistoryItem } from "../types/toolCallHistory";
+import { isCallStillPending, PENDING_MIN_MS } from "../utils/tools/pendingCalls";
+
+interface UsePendingCallsOptions {
+  isRunning: ComputedRef<boolean> | Ref<boolean>;
+  toolCallHistory: ComputedRef<ToolCallHistoryItem[]> | Ref<ToolCallHistoryItem[]>;
+}
+
+export function usePendingCalls(opts: UsePendingCallsOptions) {
+  const displayTick = ref(0);
+  let tickInterval: ReturnType<typeof setInterval> | null = null;
+  // Tracked so teardown can cancel the lingering "final tick" and we
+  // never mutate displayTick after the composable's owner unmounts.
+  let delayedTickTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  watch(
+    opts.isRunning,
+    (running) => {
+      if (running) {
+        // Guard against double-start: if the watcher fires twice with
+        // running=true (e.g. immediate + a synchronous flip), don't
+        // stack a second interval.
+        if (tickInterval !== null) return;
+        tickInterval = setInterval(() => {
+          displayTick.value++;
+        }, 50);
+      } else if (tickInterval !== null) {
+        clearInterval(tickInterval);
+        tickInterval = null;
+        // One final tick so the computed clears after the minimum
+        // duration has elapsed. Cancel any previous pending one first
+        // so back-to-back start/stop runs do not stack timeouts.
+        if (delayedTickTimeout !== null) clearTimeout(delayedTickTimeout);
+        delayedTickTimeout = setTimeout(() => {
+          displayTick.value++;
+          delayedTickTimeout = null;
+        }, PENDING_MIN_MS);
+      }
+    },
+    // immediate so a composable created while a run is already in
+    // flight (e.g. mounted mid-stream) starts ticking right away
+    // instead of waiting for the next isRunning flip.
+    { immediate: true },
+  );
+
+  const pendingCalls = computed(() => {
+    // Read displayTick to register the computed as a reactive
+    // dependency on it — that is how a freshly-resolved row stays
+    // visible for the minimum window. The `__` prefix tells ESLint
+    // (varsIgnorePattern: "^__") that the variable is intentionally
+    // unused.
+    const __tickDep = displayTick.value;
+    const now = Date.now();
+    return opts.toolCallHistory.value.filter((c) => __tickDep >= 0 && isCallStillPending(c, now));
+  });
+
+  function teardown(): void {
+    if (tickInterval !== null) {
+      clearInterval(tickInterval);
+      tickInterval = null;
+    }
+    if (delayedTickTimeout !== null) {
+      clearTimeout(delayedTickTimeout);
+      delayedTickTimeout = null;
+    }
+  }
+
+  return { pendingCalls, teardown };
+}

package/src/composables/usePubSub.ts

@@ -0,0 +1,85 @@
+import { io, type Socket } from "socket.io-client";
+
+interface PubSubMessage {
+  channel: string;
+  data: unknown;
+}
+
+type Callback = (data: unknown) => void;
+type Unsubscribe = () => void;
+
+// Socket.IO replaces the raw WebSocket + hand-rolled reconnect
+// state machine. One multiplexed connection; channels map to
+// socket.io rooms via `subscribe` / `unsubscribe` events.
+//
+// Reconnect / backoff / heartbeat are all handled by socket.io,
+// so there's no reconnectTimer / reconnectDelay here anymore. On
+// reconnect, `connect` fires again and we re-send every
+// subscription the client still cares about.
+
+let socket: Socket | null = null;
+
+const listeners = new Map<string, Set<Callback>>();
+
+function resendSubscriptions(s: Socket): void {
+  for (const channel of listeners.keys()) {
+    s.emit("subscribe", channel);
+  }
+}
+
+function connect(): Socket {
+  if (socket) return socket;
+
+  const s = io({
+    path: "/ws/pubsub",
+    // Match the server. Long-polling is fine as a fallback but
+    // the server refuses it, so don't negotiate it here either —
+    // fail fast if the WS upgrade doesn't go through.
+    transports: ["websocket"],
+  });
+
+  s.on("connect", () => resendSubscriptions(s));
+
+  s.on("data", (msg: PubSubMessage) => {
+    const cbs = listeners.get(msg.channel);
+    if (cbs) {
+      for (const cb of cbs) cb(msg.data);
+    }
+  });
+
+  socket = s;
+  return s;
+}
+
+function maybeDisconnect(): void {
+  if (listeners.size > 0) return;
+  if (!socket) return;
+  socket.disconnect();
+  socket = null;
+}
+
+export function usePubSub() {
+  function subscribe(channel: string, callback: Callback): Unsubscribe {
+    if (!listeners.has(channel)) listeners.set(channel, new Set());
+    listeners.get(channel)!.add(callback);
+
+    const s = connect();
+    if (s.connected) s.emit("subscribe", channel);
+    // If not yet connected, the "connect" handler replays every
+    // listener's subscription, so newly-added channels are
+    // covered without extra bookkeeping.
+
+    return () => {
+      const cbs = listeners.get(channel);
+      if (!cbs) return;
+      cbs.delete(callback);
+      if (cbs.size === 0) {
+        listeners.delete(channel);
+        if (socket?.connected) socket.emit("unsubscribe", channel);
+      }
+      maybeDisconnect();
+    };
+  }
+
+  return { subscribe };
+}

package/src/composables/useRightSidebar.ts

@@ -0,0 +1,23 @@
+// Composable for the right-sidebar (tool-history) visibility toggle.
+//
+// Persists the open/closed state to localStorage so user preference
+// survives reloads. Kept out of the URL — this is pure "my personal
+// UI choice" rather than a shareable view of the session.
+
+import { ref, type Ref } from "vue";
+
+const STORAGE_KEY = "right_sidebar_visible";
+
+export function useRightSidebar(): {
+  showRightSidebar: Ref<boolean>;
+  toggleRightSidebar: () => void;
+} {
+  const showRightSidebar = ref(localStorage.getItem(STORAGE_KEY) === "true");
+
+  function toggleRightSidebar(): void {
+    showRightSidebar.value = !showRightSidebar.value;
+    localStorage.setItem(STORAGE_KEY, String(showRightSidebar.value));
+  }
+
+  return { showRightSidebar, toggleRightSidebar };
+}

package/src/composables/useRoles.ts

@@ -0,0 +1,34 @@
+// Composable that owns the active role list, the currently
+// selected role id, and the refresh-from-server fetch. The merge
+// rule lives in src/utils/roleMerge so it can be unit-tested
+// independently.
+
+import { computed, ref, type ComputedRef, type Ref } from "vue";
+import { API_ROUTES } from "../config/apiRoutes";
+import { ROLES, type Role } from "../config/roles";
+import { mergeRoles } from "../utils/role/merge";
+import { apiGet } from "../utils/api";
+
+export function useRoles(): {
+  roles: Ref<Role[]>;
+  currentRoleId: Ref<string>;
+  currentRole: ComputedRef<Role>;
+  refreshRoles: () => Promise<void>;
+} {
+  const roles = ref<Role[]>(ROLES);
+  const currentRoleId = ref(ROLES[0].id);
+  const currentRole = computed(() => roles.value.find((r) => r.id === currentRoleId.value) ?? roles.value[0]);
+
+  async function refreshRoles(): Promise<void> {
+    const result = await apiGet<Role[]>(API_ROUTES.roles.list);
+    if (!result.ok) {
+      // Keep the current role list on failure — losing custom roles
+      // is preferable to crashing the UI on a transient API hiccup.
+      console.warn(`[useRoles] refreshRoles failed: ${result.status} ${result.error}`);
+      return;
+    }
+    roles.value = mergeRoles(ROLES, result.data);
+  }
+
+  return { roles, currentRoleId, currentRole, refreshRoles };
+}

package/src/composables/useSandboxStatus.ts

@@ -0,0 +1,67 @@
+// Lazy fetcher for `GET /api/sandbox` (#329).
+//
+// The lock popup consumes this to show which host credentials are
+// attached to the Docker sandbox. Deliberately lazy: the popup is
+// hidden most of the time, and env-var changes only take effect on
+// server restart anyway, so a page-lifetime cache populated on first
+// open is enough.
+//
+// Paired with `useHealth` (which loads `sandboxEnabled` at bootstrap)
+// — when the sandbox is disabled this composable is never called.
+
+import { ref, type Ref } from "vue";
+import { API_ROUTES } from "../config/apiRoutes";
+import { apiGet } from "../utils/api";
+
+export interface SandboxStatus {
+  sshAgent: boolean;
+  mounts: string[];
+}
+
+interface RawResponse {
+  sshAgent?: unknown;
+  mounts?: unknown;
+}
+
+function isSandboxStatus(raw: RawResponse): raw is {
+  sshAgent: boolean;
+  mounts: string[];
+} {
+  if (typeof raw.sshAgent !== "boolean") return false;
+  if (!Array.isArray(raw.mounts)) return false;
+  return raw.mounts.every((m) => typeof m === "string");
+}
+
+export interface UseSandboxStatusHandle {
+  /** Parsed status, or null while not yet loaded / sandbox disabled
+   *  / fetch failed. UI renders a placeholder in all three cases. */
+  status: Ref<SandboxStatus | null>;
+  /** One-shot loader. Safe to call repeatedly — short-circuits once a
+   *  non-null value is cached. Designed to be triggered from a
+   *  `watch(() => props.open, …)` on the popup. */
+  ensureLoaded: () => Promise<void>;
+}
+
+export function useSandboxStatus(): UseSandboxStatusHandle {
+  const status = ref<SandboxStatus | null>(null);
+  let loaded = false;
+
+  async function ensureLoaded(): Promise<void> {
+    if (loaded) return;
+    loaded = true;
+    const result = await apiGet<RawResponse>(API_ROUTES.sandbox);
+    if (!result.ok) {
+      // Leave `status` null — popup shows a neutral "state unavailable"
+      // line. Allow a retry on next open by flipping `loaded` back.
+      loaded = false;
+      return;
+    }
+    // Server returns `{}` (empty object) when the sandbox is disabled.
+    // The popup shouldn't call us in that case, but double-guard here
+    // so a stale render doesn't blow up on shape validation.
+    if (!isSandboxStatus(result.data)) return;
+    status.value = result.data;
+  }
+
+  return { status, ensureLoaded };
+}

package/src/composables/useSelectedResult.ts

@@ -0,0 +1,49 @@
+// Writable computed that bridges activeSession.selectedResultUuid
+// with the URL's ?result= query parameter.
+
+import { computed, watch, type ComputedRef, type WritableComputedRef } from "vue";
+import { useRoute, useRouter, isNavigationFailure } from "vue-router";
+import type { ActiveSession } from "../types/session";
+
+export function useSelectedResult(opts: {
+  activeSession: ComputedRef<ActiveSession | undefined>;
+  sessionMap: Map<string, ActiveSession>;
+  currentSessionId: { readonly value: string };
+}): {
+  selectedResultUuid: WritableComputedRef<string | null>;
+} {
+  const { activeSession } = opts;
+  const route = useRoute();
+  const router = useRouter();
+
+  const selectedResultUuid = computed({
+    get: () => activeSession.value?.selectedResultUuid ?? null,
+    set: (val: string | null) => {
+      if (activeSession.value) activeSession.value.selectedResultUuid = val;
+      const { result: __result, ...restQuery } = route.query;
+      const nextQuery = val ? { ...restQuery, result: val } : restQuery;
+      router.replace({ query: nextQuery }).catch((err: unknown) => {
+        if (!isNavigationFailure(err)) {
+          console.error("[selectedResultUuid] navigation failed:", err);
+        }
+      });
+    },
+  });
+
+  // External URL changes for ?result= → sync into the session.
+  watch(
+    () => route.query.result,
+    (newResult) => {
+      const session = opts.sessionMap.get(opts.currentSessionId.value);
+      if (!session) return;
+      // Ignore malformed (array) values rather than clobbering state.
+      if (Array.isArray(newResult)) return;
+      const resultId = typeof newResult === "string" ? newResult : null;
+      if (resultId !== session.selectedResultUuid) {
+        session.selectedResultUuid = resultId;
+      }
+    },
+  );
+
+  return { selectedResultUuid };
+}

package/src/composables/useSessionDerived.ts

@@ -0,0 +1,51 @@
+// Computed properties derived from sessionMap + sessions list.
+// Extracted from App.vue to reduce the component's reactive surface.
+
+import { computed, type Ref } from "vue";
+import type { ToolResultComplete } from "gui-chat-protocol/vue";
+import type { ActiveSession, SessionSummary } from "../types/session";
+import type { ToolCallHistoryItem } from "../types/toolCallHistory";
+import { deduplicateResults } from "../utils/tools/dedup";
+
+export function useSessionDerived(opts: { sessionMap: Map<string, ActiveSession>; currentSessionId: Ref<string>; sessions: Ref<SessionSummary[]> }) {
+  const { sessionMap, currentSessionId, sessions } = opts;
+
+  const activeSession = computed(() => sessionMap.get(currentSessionId.value));
+
+  const toolResults = computed<ToolResultComplete[]>(() => activeSession.value?.toolResults ?? []);
+
+  const sidebarResults = computed(() => deduplicateResults(toolResults.value));
+
+  const currentSummary = computed(() => sessions.value.find((s) => s.id === currentSessionId.value));
+
+  // The server-side summary already merges pendingGenerations into
+  // `isRunning` (see server/api/routes/sessions.ts), but pub/sub events
+  // for background generations arrive faster than the next sessions
+  // refetch — fold the in-memory map in so ChatInput reflects the new
+  // state immediately.
+  const isRunning = computed(() => {
+    const active = activeSession.value;
+    const pending = active ? Object.keys(active.pendingGenerations).length > 0 : false;
+    return currentSummary.value?.isRunning || active?.isRunning || pending || false;
+  });
+
+  const statusMessage = computed(() => currentSummary.value?.statusMessage ?? activeSession.value?.statusMessage ?? "");
+
+  const toolCallHistory = computed<ToolCallHistoryItem[]>(() => activeSession.value?.toolCallHistory ?? []);
+
+  const activeSessionCount = computed(() => sessions.value.filter((s) => s.isRunning).length);
+
+  const unreadCount = computed(() => sessions.value.filter((s) => s.hasUnread).length);
+
+  return {
+    activeSession,
+    toolResults,
+    sidebarResults,
+    currentSummary,
+    isRunning,
+    statusMessage,
+    toolCallHistory,
+    activeSessionCount,
+    unreadCount,
+  };
+}

package/src/composables/useSessionHistory.ts

@@ -0,0 +1,81 @@
+// Composable for the session-history dropdown in the header.
+//
+// Owns the `sessions` list (what the server knows about) and the
+// `showHistory` open/closed flag, plus the fetch + toggle helpers.
+// The dropdown lazy-loads the list only when opened, and callers
+// can invoke `fetchSessions()` directly after an end-of-run so the
+// sidebar title cache stays fresh.
+//
+// Since #205, `fetchSessions()` sends the server's last-issued
+// cursor back as `?since=<cursor>` so the server can reply with
+// only the rows that changed. The first call has no cursor (full
+// fetch); subsequent calls receive a diff that we merge into the
+// existing cache via `applySessionDiff`.
+
+import { ref, type Ref } from "vue";
+import { API_ROUTES } from "../config/apiRoutes";
+import type { SessionSummary } from "../types/session";
+import { apiGet } from "../utils/api";
+import { applySessionDiff } from "../utils/session/mergeSessions";
+
+interface SessionsResponse {
+  sessions: SessionSummary[];
+  cursor: string;
+  deletedIds: string[];
+}
+
+export function useSessionHistory(): {
+  sessions: Ref<SessionSummary[]>;
+  showHistory: Ref<boolean>;
+  historyError: Ref<string | null>;
+  fetchSessions: () => Promise<SessionSummary[]>;
+  toggleHistory: () => Promise<void>;
+} {
+  const sessions = ref<SessionSummary[]>([]);
+  const showHistory = ref(false);
+  // Surfaces the most recent fetch failure. Kept alongside the (stale)
+  // sessions list rather than wiping it — a dropdown that goes blank
+  // the moment the network hiccups is worse UX than one that shows
+  // "⚠ using cached list" with the last-known good entries.
+  const historyError = ref<string | null>(null);
+  // Opaque cursor the server hands back on every successful call.
+  // Tab-scoped — issue #205 calls out cross-tab sharing via
+  // localStorage as out of scope.
+  let cursor: string | null = null;
+
+  async function fetchSessions(): Promise<SessionSummary[]> {
+    const query: Record<string, string> = {};
+    if (cursor !== null) query.since = cursor;
+    const result = await apiGet<SessionsResponse>(API_ROUTES.sessions.list, query);
+    if (!result.ok) {
+      historyError.value = result.error;
+      // Intentionally preserve `sessions.value` — callers keep showing
+      // whatever list was last known to work.
+      return sessions.value;
+    }
+    historyError.value = null;
+    const body = result.data;
+    if (cursor === null) {
+      // First call in this composable instance — server returned the
+      // full list; seed the cache directly.
+      sessions.value = body.sessions;
+    } else {
+      sessions.value = applySessionDiff(sessions.value, body.sessions, body.deletedIds);
+    }
+    cursor = body.cursor;
+    return sessions.value;
+  }
+
+  async function toggleHistory(): Promise<void> {
+    showHistory.value = !showHistory.value;
+    if (showHistory.value) await fetchSessions();
+  }
+
+  return {
+    sessions,
+    showHistory,
+    historyError,
+    fetchSessions,
+    toggleHistory,
+  };
+}

package/src/composables/useSessionSync.ts

@@ -0,0 +1,57 @@
+// Keep in-memory session state in sync with the server via pub/sub.
+// Subscribes to the global `sessions` channel and refetches summaries
+// whenever any session's state changes. Also provides markSessionRead
+// for clearing the unread flag on the server.
+
+import { onScopeDispose } from "vue";
+import type { Ref } from "vue";
+import type { ActiveSession, SessionSummary } from "../types/session";
+import { usePubSub } from "./usePubSub";
+import { PUBSUB_CHANNELS } from "../config/pubsubChannels";
+import { apiPost } from "../utils/api";
+import { API_ROUTES } from "../config/apiRoutes";
+
+export function useSessionSync(opts: {
+  sessionMap: Map<string, ActiveSession>;
+  currentSessionId: Ref<string>;
+  fetchSessions: () => Promise<SessionSummary[]>;
+}) {
+  const { sessionMap, currentSessionId, fetchSessions } = opts;
+  const { subscribe } = usePubSub();
+
+  async function refreshSessionStates(): Promise<void> {
+    let summaries: SessionSummary[];
+    try {
+      summaries = await fetchSessions();
+    } catch (err) {
+      // Network / HTTP failure — log and bail so the pub/sub
+      // callback doesn't produce an unhandled rejection.
+      console.warn("[session-sync] failed to fetch sessions:", err);
+      return;
+    }
+    for (const s of summaries) {
+      const live = sessionMap.get(s.id);
+      if (!live) continue;
+      live.isRunning = s.isRunning ?? false;
+      live.statusMessage = s.statusMessage ?? "";
+      const unread = s.hasUnread ?? false;
+      if (!(unread && s.id === currentSessionId.value)) {
+        live.hasUnread = unread;
+      }
+    }
+  }
+
+  async function markSessionRead(id: string): Promise<void> {
+    const result = await apiPost<{ ok: boolean }>(API_ROUTES.sessions.markRead.replace(":id", encodeURIComponent(id)));
+    if (!result.ok || result.data.ok === false) {
+      await refreshSessionStates();
+    }
+  }
+
+  const unsub = subscribe(PUBSUB_CHANNELS.sessions, () => {
+    void refreshSessionStates();
+  });
+  if (typeof unsub === "function") onScopeDispose(unsub);
+
+  return { refreshSessionStates, markSessionRead };
+}