mulmoclaude 0.5.2 → 0.6.0

package/src/composables/usePdfDownload.ts

@@ -13,17 +13,31 @@ import { API_ROUTES } from "../config/apiRoutes";
 import { apiFetchRaw } from "../utils/api";
 import { errorMessage } from "../utils/errors";
 
+export interface DownloadPdfOptions {
+  /** Workspace-relative source directory of the markdown (e.g.
+   *  `"data/wiki/pages"` for Wiki pages). The server uses it to
+   *  resolve relative `<img>` references to the right base path
+   *  before inlining. Omit for the legacy `markdowns/` default. */
+  baseDir?: string;
+  /** When true, the server strips a leading YAML frontmatter envelope
+   *  (`---\n…\n---\n`) before rendering, so the YAML header doesn't
+   *  appear as plain text on page 1 of the PDF. Wiki pages set this.
+   *  Other callers leave it false so a chat-generated document that
+   *  literally starts with `---` is preserved. */
+  stripFrontmatter?: boolean;
+}
+
 export interface UsePdfDownloadHandle {
   pdfDownloading: Ref<boolean>;
   pdfError: Ref<string | null>;
-  downloadPdf: (markdown: string, filename: string) => Promise<void>;
+  downloadPdf: (markdown: string, filename: string, options?: DownloadPdfOptions) => 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> {
+  async function downloadPdf(markdown: string, filename: string, options: DownloadPdfOptions = {}): Promise<void> {
     pdfError.value = null;
     pdfDownloading.value = true;
     let url: string | null = null;
@@ -33,7 +47,7 @@ export function usePdfDownload(): UsePdfDownloadHandle {
       const response = await apiFetchRaw(API_ROUTES.pdf.markdown, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ markdown, filename }),
+        body: JSON.stringify({ markdown, filename, baseDir: options.baseDir, stripFrontmatter: options.stripFrontmatter }),
       });
       if (!response.ok) {
         const errText = await response.text().catch(() => "");

package/src/composables/usePendingCalls.ts

@@ -1,9 +1,5 @@
-// 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.
+// "Minimum visible duration" trick: tick every 50ms while running so a freshly-resolved call stays on-screen for
+// PENDING_MIN_MS before clearing. One final tick after the run ends sweeps lingering rows out of the computed.
 
 import { computed, ref, watch, type ComputedRef, type Ref } from "vue";
 import type { ToolCallHistoryItem } from "../types/toolCallHistory";
@@ -17,17 +13,14 @@ interface UsePendingCallsOptions {
 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.
+  // Tracked so teardown can cancel the trailing tick — never mutate displayTick after the 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.
+        // Guard against double-start (immediate + a synchronous flip would otherwise stack intervals).
         if (tickInterval !== null) return;
         tickInterval = setInterval(() => {
           displayTick.value++;
@@ -35,9 +28,7 @@ export function usePendingCalls(opts: UsePendingCallsOptions) {
       } 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.
+        // Cancel any previous trailing tick so back-to-back start/stop runs don't stack timeouts.
         if (delayedTickTimeout !== null) clearTimeout(delayedTickTimeout);
         delayedTickTimeout = setTimeout(() => {
           displayTick.value++;
@@ -45,24 +36,15 @@ export function usePendingCalls(opts: UsePendingCallsOptions) {
         }, 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 so a composable mounted mid-stream starts ticking right away instead of waiting for the next 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.
+    // Reads displayTick purely to register a reactive dep — that's how rows linger for the minimum window.
     const __tickDep = displayTick.value;
     const now = Date.now();
-    // Project to a narrower shape that carries `elapsedMs` so the
-    // consumer doesn't need its own ticker for the per-tool badge —
-    // the 50ms re-evaluation here already drives the display
-    // (#731 PR2).
+    // #731 PR2: project to elapsedMs so the per-tool badge piggybacks on this 50ms ticker (no second ticker downstream).
     return opts.toolCallHistory.value
       .filter((entry) => __tickDep >= 0 && isCallStillPending(entry, now))
       .map((entry) => ({

package/src/composables/usePluginErrorBoundary.ts

@@ -0,0 +1,68 @@
+// State and reset logic for the plugin error boundary mounted in
+// `<PluginScopedRoot>`. Extracted from the SFC so the behaviour
+// (error capture, details toggle, retry-remount key bump, error
+// detail composition) can be unit-tested without a DOM — Codex
+// review iter-1 #1147 flagged the absence of automated coverage
+// for the boundary's wiring.
+//
+// The host component still owns `onErrorCaptured` registration —
+// that hook must be called inside `setup()` and is not portable —
+// but every observable side-effect of "an error was captured" lives
+// here and is fully testable in isolation.
+
+import { computed, ref, type ComputedRef, type Ref } from "vue";
+
+export interface PluginErrorBoundary {
+  /** Captured error object, or `null` while the plugin renders
+   *  normally. The host SFC reads this to switch to the fallback
+   *  panel. */
+  readonly error: Readonly<Ref<Error | null>>;
+  /** Toggle for the "Show details" / "Hide details" disclosure. */
+  readonly showDetails: Ref<boolean>;
+  /** Bumped on every Retry. The SFC binds it as `<slot :key>` so
+   *  Vue treats the slotted subtree as a brand-new component on
+   *  each retry — transient bugs (stale refs, momentary endpoint
+   *  outages) clear without a full page reload. */
+  readonly mountKey: Readonly<Ref<number>>;
+  /** Composed `<message>\n\n<stack>` text shown inside the
+   *  details `<pre>`. Empty string when there's no error. */
+  readonly errorDetails: ComputedRef<string>;
+  /** Forward an unknown thrown value into the boundary's error
+   *  state. Coerces non-Error throws to `new Error(String(err))`
+   *  so `.stack` access stays type-safe in the template. Logs to
+   *  the console with a `[plugin/<pkgName>]` prefix so devs can
+   *  trace which plugin owned the crash. */
+  readonly captureError: (err: unknown) => void;
+  /** Clear the error and bump `mountKey`. */
+  readonly retry: () => void;
+}
+
+/** @param pkgName plugin package name; used as the console log
+ *                 prefix so the owning plugin is obvious in dev
+ *                 tools. */
+export function usePluginErrorBoundary(pkgName: string): PluginErrorBoundary {
+  const error = ref<Error | null>(null);
+  const showDetails = ref(false);
+  const mountKey = ref(0);
+
+  const errorDetails = computed((): string => {
+    if (!error.value) return "";
+    const message = error.value.message || String(error.value);
+    const stack = error.value.stack ?? "";
+    return stack ? `${message}\n\n${stack}` : message;
+  });
+
+  function captureError(err: unknown): void {
+    const captured = err instanceof Error ? err : new Error(String(err));
+    console.error(`[plugin/${pkgName}] uncaught error`, captured);
+    error.value = captured;
+  }
+
+  function retry(): void {
+    error.value = null;
+    showDetails.value = false;
+    mountKey.value += 1;
+  }
+
+  return { error, showDetails, mountKey, errorDetails, captureError, retry };
+}

package/src/composables/usePubSub.ts

@@ -8,15 +8,7 @@ interface PubSubMessage {
 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.
-
+// On reconnect we re-emit every live subscription so the rooms list survives the bounce.
 let socket: Socket | null = null;
 
 const listeners = new Map<string, Set<Callback>>();
@@ -32,9 +24,7 @@ function connect(): Socket {
 
   const sock = 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.
+    // Server refuses long-polling fallback, so fail fast here too if the WS upgrade doesn't go through.
     transports: ["websocket"],
   });
 
@@ -60,14 +50,16 @@ function maybeDisconnect(): void {
 
 export function usePubSub() {
   function subscribe(channel: string, callback: Callback): Unsubscribe {
-    if (!listeners.has(channel)) listeners.set(channel, new Set());
-    listeners.get(channel)!.add(callback);
+    let entry = listeners.get(channel);
+    if (!entry) {
+      entry = new Set();
+      listeners.set(channel, entry);
+    }
+    entry.add(callback);
 
     const sock = connect();
     if (sock.connected) sock.emit("subscribe", channel);
-    // If not yet connected, the "connect" handler replays every
-    // listener's subscription, so newly-added channels are
-    // covered without extra bookkeeping.
+    // If not yet connected, the "connect" handler replays every subscription — no extra bookkeeping needed.
 
     return () => {
       const cbs = listeners.get(channel);

package/src/composables/useRunElapsed.ts

@@ -1,18 +1,5 @@
-// Tracks how long the active agent run has been going. While
-// `isRunning` is true, `elapsedMs` updates once per second so the
-// rendered string ("12s" / "1m 23s") moves visibly. When the run
-// ends, `elapsedMs` flips back to null and the timer is cleared.
-//
-// Separated from `usePendingCalls` (which ticks every 50ms for the
-// minimum-visible-duration trick) — the run-elapsed display only
-// needs second-granularity, and the consumer renders one badge per
-// run rather than one per pending row, so a tighter tick would just
-// burn re-renders.
-//
-// Why a watcher + setInterval rather than a `requestAnimationFrame`
-// driven computed: tab-throttled rAF freezes when the tab is in the
-// background, and the user expects the elapsed counter to keep
-// running across tab switches.
+// setInterval, not rAF: tab-throttled rAF freezes in background tabs and the user expects elapsed to keep ticking
+// across tab switches. Second-granularity is enough — the consumer renders one badge per run, not per pending row.
 
 import { computed, ref, watch, type ComputedRef, type Ref, type WatchStopHandle } from "vue";
 
@@ -35,9 +22,7 @@ export function useRunElapsed(opts: UseRunElapsedOptions): {
     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.
+        // Guard against double-start (immediate + synchronous flip would otherwise stack intervals).
         if (interval !== null) return;
         startedAt.value = Date.now();
         now.value = startedAt.value;
@@ -52,8 +37,7 @@ export function useRunElapsed(opts: UseRunElapsedOptions): {
       }
       startedAt.value = null;
     },
-    // immediate so a composable created while a run is already in
-    // flight (mounted mid-stream) starts ticking right away.
+    // Immediate: a composable mounted mid-stream starts ticking right away.
     { immediate: true },
   );
 
@@ -63,8 +47,7 @@ export function useRunElapsed(opts: UseRunElapsedOptions): {
   });
 
   function teardown(): void {
-    // Stop the watcher first — otherwise an isRunning flip after
-    // teardown would recreate the interval (Codex iter-1 #798).
+    // Stop the watcher first — otherwise an isRunning flip after teardown recreates the interval (#798 Codex iter-1).
     if (stopWatch !== null) {
       stopWatch();
       stopWatch = null;

package/src/composables/useSandboxStatus.ts

@@ -1,13 +1,4 @@
-// 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.
+// #329. Lazy because env-var changes only take effect on server restart, so a page-lifetime cache is enough.
 
 import { ref, type Ref } from "vue";
 import { API_ROUTES } from "../config/apiRoutes";
@@ -33,12 +24,8 @@ function isSandboxStatus(raw: RawResponse): raw is {
 }
 
 export interface UseSandboxStatusHandle {
-  /** Parsed status, or null while not yet loaded / sandbox disabled
-   *  / fetch failed. UI renders a placeholder in all three cases. */
+  // null = not yet loaded / sandbox disabled / fetch failed (UI renders a placeholder for all three).
   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>;
 }
 
@@ -51,14 +38,11 @@ export function useSandboxStatus(): UseSandboxStatusHandle {
     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.
+      // Allow retry on next open — `status` stays null so the popup shows "state unavailable".
       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.
+    // Server returns `{}` when the sandbox is disabled — popup shouldn't call us then, but double-guard.
     if (!isSandboxStatus(result.data)) return;
     status.value = result.data;
   }

package/src/composables/useSessionDerived.ts

@@ -1,6 +1,3 @@
-// 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";
@@ -14,17 +11,16 @@ export function useSessionDerived(opts: { sessionMap: Map<string, ActiveSession>
 
   const toolResults = computed<ToolResultComplete[]>(() => activeSession.value?.toolResults ?? []);
 
+  // `sidebarResults` is the canonical "what the user sees and can
+  // navigate through" list — keyboard nav (useKeyNavigation), the
+  // sidebar render, and StackView all consume it.
   const sidebarResults = computed(() => deduplicateResults(toolResults.value));
 
   const currentSummary = computed(() => sessions.value.find((summary) => summary.id === currentSessionId.value));
 
-  // Global "is anything running" across every known session — in-memory
-  // map (which reflects pub/sub events faster than server refetch) and
-  // server-side summaries (for sessions not yet hydrated into the map).
-  // Used for consumers that must stay true across page navigation:
-  // favicon spinner and the FilesView refresh watcher (which would
-  // otherwise fire before a background run actually finishes, because
-  // leaving /chat drops activeSession to undefined).
+  // OR of in-memory map (pub/sub-fast) + server summaries (covers un-hydrated sessions). Must stay true across page
+  // nav so favicon + FilesView refresh-watcher don't fire before a background run finishes (leaving /chat drops
+  // activeSession to undefined).
   const isRunning = computed(() => {
     for (const session of sessionMap.values()) {
       if (session.isRunning) return true;
@@ -33,11 +29,7 @@ export function useSessionDerived(opts: { sessionMap: Map<string, ActiveSession>
     return sessions.value.some((summary) => summary.isRunning);
   });
 
-  // True only when the session on screen has a run in flight. Drives
-  // UX touchpoints that should react per-session — ChatInput disable,
-  // sendMessage guard, chat-list auto-scroll, pending-call row tick —
-  // so a background run in session B doesn't disable the composer
-  // while the user is actively chatting in session A.
+  // Per-session: a background run in session B must not disable session A's composer or block its auto-scroll.
   const activeSessionRunning = computed(() => {
     const active = activeSession.value;
     const pending = active ? Object.keys(active.pendingGenerations).length > 0 : false;

package/src/composables/useSessionHistory.ts

@@ -1,22 +1,12 @@
-// Composable for the session-history view at `/history`.
-//
-// Owns the `sessions` list (what the server knows about) plus the
-// fetch helper. The view's open/closed state is now URL-backed (see
-// plans/done/feat-history-url-route.md) — callers watch `route.name` and
-// invoke `fetchSessions()` on route enter rather than going through
-// an in-memory toggle flag.
-//
-// 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`.
+// #205: send the server's last cursor as ?since=<cursor> so the server replies with a diff. First call has no cursor.
 
-import { ref, type Ref } from "vue";
+import { getCurrentScope, onScopeDispose, ref, type Ref } from "vue";
 import { API_ROUTES } from "../config/apiRoutes";
+import { PUBSUB_CHANNELS, type SessionsChannelPayload } from "../config/pubsubChannels";
 import type { SessionSummary } from "../types/session";
-import { apiGet } from "../utils/api";
+import { apiDelete, apiGet, apiPost } from "../utils/api";
 import { applySessionDiff } from "../utils/session/mergeSessions";
+import { usePubSub } from "./usePubSub";
 
 interface SessionsResponse {
   sessions: SessionSummary[];
@@ -24,20 +14,25 @@ interface SessionsResponse {
   deletedIds: string[];
 }
 
-export function useSessionHistory(): {
+function readDeletedIds(payload: unknown): string[] {
+  if (!payload || typeof payload !== "object") return [];
+  const ids = (payload as SessionsChannelPayload).deletedIds;
+  return Array.isArray(ids) ? ids.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+export interface UseSessionHistory {
   sessions: Ref<SessionSummary[]>;
   historyError: Ref<string | null>;
   fetchSessions: () => Promise<SessionSummary[]>;
-} {
+  setBookmark: (sessionId: string, bookmarked: boolean) => Promise<boolean>;
+  deleteSession: (sessionId: string) => Promise<boolean>;
+}
+
+export function useSessionHistory(): UseSessionHistory {
   const sessions = ref<SessionSummary[]>([]);
-  // Surfaces the most recent fetch failure. Kept alongside the (stale)
-  // sessions list rather than wiping it — a panel that goes blank
-  // the moment the network hiccups is worse UX than one that shows
-  // "⚠ using cached list" with the last-known good entries.
+  // Held alongside the stale list, not in place of it — a blank panel on a network blip is worse UX than "⚠ cached".
   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.
+  // Tab-scoped; #205 explicitly leaves cross-tab sharing via localStorage out of scope.
   let cursor: string | null = null;
 
   async function fetchSessions(): Promise<SessionSummary[]> {
@@ -46,26 +41,72 @@ export function useSessionHistory(): {
     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.
+      // Preserve sessions.value so callers keep showing the last-known-good list.
       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;
+    ({ cursor } = body);
     return sessions.value;
   }
 
+  async function setBookmark(sessionId: string, bookmarked: boolean): Promise<boolean> {
+    const path = API_ROUTES.sessions.bookmark.replace(":id", encodeURIComponent(sessionId));
+    const result = await apiPost<{ ok: boolean }>(path, { bookmarked });
+    if (!result.ok) {
+      historyError.value = result.error;
+      return false;
+    }
+    // Optimistic local update so the green-icon flip is immediate;
+    // the pub/sub round-trip will reaffirm via the cursor diff (meta
+    // mtime feeds into changeMs) and also reach other tabs.
+    sessions.value = sessions.value.map((session) => (session.id === sessionId ? { ...session, isBookmarked: bookmarked } : session));
+    return true;
+  }
+
+  async function deleteSession(sessionId: string): Promise<boolean> {
+    const path = API_ROUTES.sessions.detail.replace(":id", encodeURIComponent(sessionId));
+    const result = await apiDelete<{ ok: boolean }>(path);
+    if (!result.ok) {
+      historyError.value = result.error;
+      return false;
+    }
+    // Don't update locally — the server publishes `deletedIds` on the
+    // sessions channel and the subscriber below removes the row in
+    // every tab (including this one) the same way. One code path, no
+    // race between the optimistic write and the broadcast.
+    return true;
+  }
+
+  // Cross-tab cache pruning: cursor diffs don't carry deletions
+  // (deletedIds is always [] in the REST response — see #205 comments
+  // in routes/sessions.ts), so we rely on the channel payload.
+  //
+  // Gated on getCurrentScope() so unit tests that instantiate the
+  // composable outside a Vue setup don't open a real socket.io
+  // connection (which would keep node's event loop alive and hang
+  // the test process).
+  if (getCurrentScope()) {
+    const { subscribe } = usePubSub();
+    const unsubscribe = subscribe(PUBSUB_CHANNELS.sessions, (data) => {
+      const ids = readDeletedIds(data);
+      if (ids.length === 0) return;
+      const drop = new Set(ids);
+      sessions.value = sessions.value.filter((session) => !drop.has(session.id));
+    });
+    if (typeof unsubscribe === "function") onScopeDispose(unsubscribe);
+  }
+
   return {
     sessions,
     historyError,
     fetchSessions,
+    setBookmark,
+    deleteSession,
   };
 }

package/src/composables/useSessionSync.ts

@@ -7,16 +7,27 @@ 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 { PUBSUB_CHANNELS, type SessionsChannelPayload } from "../config/pubsubChannels";
 import { apiPost } from "../utils/api";
 import { API_ROUTES } from "../config/apiRoutes";
 
+function readDeletedIds(payload: unknown): string[] {
+  if (!payload || typeof payload !== "object") return [];
+  const ids = (payload as SessionsChannelPayload).deletedIds;
+  return Array.isArray(ids) ? ids.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
 export function useSessionSync(opts: {
   sessionMap: Map<string, ActiveSession>;
   currentSessionId: Ref<string>;
   fetchSessions: () => Promise<SessionSummary[]>;
+  /** Called when the session the user is currently viewing has been
+   *  hard-deleted (typically from another tab). The host owns the
+   *  recovery action — usually navigate to a fresh session so the
+   *  blank chat view doesn't linger on a dead URL. */
+  onCurrentSessionDeleted?: () => void;
 }) {
-  const { sessionMap, currentSessionId, fetchSessions } = opts;
+  const { sessionMap, currentSessionId, fetchSessions, onCurrentSessionDeleted } = opts;
   const { subscribe } = usePubSub();
 
   async function refreshSessionStates(): Promise<void> {
@@ -48,7 +59,18 @@ export function useSessionSync(opts: {
     }
   }
 
-  const unsub = subscribe(PUBSUB_CHANNELS.sessions, () => {
+  const unsub = subscribe(PUBSUB_CHANNELS.sessions, (data) => {
+    // Hard-deleted sessions need to leave sessionMap immediately —
+    // refreshSessionStates only updates entries it still finds in the
+    // server response, so a deleted live session would otherwise
+    // linger in mergedSessions until the tab reloads.
+    const deletedIds = readDeletedIds(data);
+    let currentWasDeleted = false;
+    for (const deletedId of deletedIds) {
+      sessionMap.delete(deletedId);
+      if (deletedId === currentSessionId.value) currentWasDeleted = true;
+    }
+    if (currentWasDeleted) onCurrentSessionDeleted?.();
     void refreshSessionStates();
   });
   if (typeof unsub === "function") onScopeDispose(unsub);

package/src/composables/useSkillsList.ts

@@ -0,0 +1,59 @@
+import { readonly, ref, type Ref, type DeepReadonly } from "vue";
+import { apiGet } from "../utils/api";
+import { API_ROUTES } from "../config/apiRoutes";
+
+export interface SkillSummary {
+  name: string;
+  description: string;
+  source: "user" | "project";
+}
+
+// Module-level shared state across consumers. Failed fetch keeps the previous list (no visual wipe on a blip) and
+// surfaces the message via `error` — the Skills tab renders that as a banner so stale vs current is distinguishable.
+const skills = ref<SkillSummary[]>([]);
+const error = ref<string | null>(null);
+let bootstrapped = false;
+let inflight: Promise<void> | null = null;
+
+async function refresh(): Promise<void> {
+  if (inflight) return inflight;
+  inflight = (async () => {
+    try {
+      const result = await apiGet<{ skills: SkillSummary[] }>(API_ROUTES.skills.list.url);
+      if (result.ok && Array.isArray(result.data.skills)) {
+        skills.value = result.data.skills;
+        error.value = null;
+        return;
+      }
+      // Leave `skills` untouched (stale > wiped); surface on `error` AND console.warn — silent failures here had
+      // historically made "Skills tab won't refresh" hard to diagnose without breakpoints.
+      const message = !result.ok ? result.error || "Failed to load skills" : "Skills response missing `skills` array";
+      error.value = message;
+      console.warn("[useSkillsList] refresh failed:", message);
+    } catch (err) {
+      // Runtime throw must not become an unhandled rejection — the bootstrap call site is `void refresh()`.
+      const message = err instanceof Error ? err.message : String(err);
+      error.value = message;
+      console.warn("[useSkillsList] refresh threw:", err);
+    } finally {
+      inflight = null;
+    }
+  })();
+  return inflight;
+}
+
+export function useSkillsList(): {
+  skills: DeepReadonly<Ref<SkillSummary[]>>;
+  error: DeepReadonly<Ref<string | null>>;
+  refresh: () => Promise<void>;
+} {
+  if (!bootstrapped) {
+    bootstrapped = true;
+    void refresh();
+  }
+  return {
+    skills: readonly(skills),
+    error: readonly(error),
+    refresh,
+  };
+}