shraga 0.1.112 → 0.1.113

package/src/client/components/SkillsManager.tsx

@@ -4,6 +4,7 @@ import { Button } from './ui/button';
 import { Input } from './ui/input';
 import { Textarea } from './ui/textarea';
 import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from './ui/dialog';
+import { useIsOwner } from '@/hooks/useIsOwner';
 
 type DefaultSkillEntry = string | { name: string; capped?: boolean | number };
 
@@ -43,8 +44,21 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
   const [dirty, setDirty] = useState(false);
   const [action, setAction] = useState<SidebarAction>(null);
   const [actionName, setActionName] = useState('');
+  const [error, setError] = useState<string | null>(null);
+  const isOwner = useIsOwner(getToken, open);
+  const canEdit = isOwner === true;
 
   const isSelectedBuiltin = selected ? builtins.includes(selected) : false;
+  const readOnly = isSelectedBuiltin || !canEdit;
+
+  /** True if the mutation succeeded; otherwise surfaces the server's error and returns false. */
+  const ok = async (res: Response, what: string) => {
+    if (res.ok) { setError(null); return true; }
+    const msg = (await res.json().catch((e) => { console.warn(`[SkillsManager] ${what} error response not JSON`, res.status, e); return {}; })).error || `HTTP ${res.status}`;
+    console.warn(`[SkillsManager] ${what} failed`, msg);
+    setError(`${what} failed: ${msg}`);
+    return false;
+  };
 
   const loadList = async () => {
     const token = await getToken();
@@ -72,11 +86,11 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
   };
 
   const save = async () => {
-    if (!selected || isSelectedBuiltin) return;
+    if (!selected || readOnly) return;
     const token = await getToken();
     if (!token) return;
-    await apiFetch(`/api/skills/${selected}`, token, { method: 'PUT', body: JSON.stringify({ content }) });
-    setDirty(false);
+    const res = await apiFetch(`/api/skills/${selected}`, token, { method: 'PUT', body: JSON.stringify({ content }) });
+    if (await ok(res, 'Save')) setDirty(false);
   };
 
   const submitAction = async () => {
@@ -86,17 +100,18 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
     if (!token) return;
 
     if (action === 'create') {
-      await apiFetch(`/api/skills/${name}`, token, { method: 'PUT', body: JSON.stringify({ content: '' }) });
+      const res = await apiFetch(`/api/skills/${name}`, token, { method: 'PUT', body: JSON.stringify({ content: '' }) });
+      if (!await ok(res, 'Create')) return;
       await loadList();
       await loadSkill(name);
     } else if (action === 'duplicate' && selected) {
       const res = await apiFetch(`/api/skills/${selected}/duplicate`, token, { method: 'POST', body: JSON.stringify({ newName: name }) });
-      if (!res.ok) return;
+      if (!await ok(res, 'Duplicate')) return;
       await loadList();
       await loadSkill(name);
     } else if (action === 'rename' && selected) {
       const res = await apiFetch(`/api/skills/${selected}/rename`, token, { method: 'POST', body: JSON.stringify({ newName: name }) });
-      if (!res.ok) return;
+      if (!await ok(res, 'Rename')) return;
       await loadList();
       await loadSkill(name);
     }
@@ -109,7 +124,7 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
     const token = await getToken();
     if (!token) return;
     const res = await apiFetch(`/api/skills/${name}`, token, { method: 'DELETE' });
-    if (!res.ok) return;
+    if (!await ok(res, 'Delete')) return;
     if (selected === name) { setSelected(null); setContent(''); }
     await loadList();
   };
@@ -120,8 +135,8 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
     const next = isDefault(defaults, name)
       ? defaults.filter((d) => entryName(d) !== name)
       : [...defaults, name];
-    await apiFetch('/api/skills-defaults', token, { method: 'PUT', body: JSON.stringify(next) });
-    setDefaults(next);
+    const res = await apiFetch('/api/skills-defaults', token, { method: 'PUT', body: JSON.stringify(next) });
+    if (await ok(res, 'Update defaults')) setDefaults(next);
   };
 
 
@@ -163,9 +178,10 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                   onClick={() => loadSkill(s)}
                 >
                   <button
-                    className={`shrink-0 transition-colors ${isDefault(defaults, s) ? 'text-amber-500' : 'text-muted-foreground/30 hover:text-amber-400'}`}
-                    onClick={(e) => { e.stopPropagation(); toggleDefault(s); }}
-                    title={isDefault(defaults, s) ? 'Remove from defaults' : 'Set as default (always active)'}
+                    className={`shrink-0 transition-colors ${isDefault(defaults, s) ? 'text-amber-500' : 'text-muted-foreground/30'} ${canEdit && !isDefault(defaults, s) ? 'hover:text-amber-400' : ''}`}
+                    disabled={!canEdit}
+                    onClick={(e) => { e.stopPropagation(); if (canEdit) toggleDefault(s); }}
+                    title={!canEdit ? (isDefault(defaults, s) ? 'Default (only an owner can change)' : 'Only an owner can change defaults') : isDefault(defaults, s) ? 'Remove from defaults' : 'Set as default (always active)'}
                   >
                     <Star className={`w-3 h-3 ${isDefault(defaults, s) ? 'fill-current' : ''}`} />
                   </button>
@@ -173,7 +189,7 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                   {builtins.includes(s) && (
                     <span title="Built-in (read-only)"><Lock className="w-2.5 h-2.5 text-muted-foreground/40 shrink-0" /></span>
                   )}
-                  {!builtins.includes(s) && (
+                  {!builtins.includes(s) && canEdit && (
                     <button
                       className="opacity-0 group-hover:opacity-100 text-muted-foreground hover:text-destructive transition-opacity shrink-0"
                       onClick={(e) => { e.stopPropagation(); remove(s); }}
@@ -200,11 +216,14 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                   <Button size="icon" className="h-7 w-7 shrink-0" onClick={submitAction}><Check className="w-3 h-3" /></Button>
                   <Button size="icon" variant="ghost" className="h-7 w-7 shrink-0" onClick={cancelAction}><X className="w-3 h-3" /></Button>
                 </div>
-              ) : (
+              ) : canEdit ? (
                 <Button variant="outline" size="sm" className="w-full h-7 text-xs" onClick={() => startAction('create')}>
                   <Plus className="w-3 h-3 mr-1" /> New skill
                 </Button>
+              ) : (
+                <p className="text-[11px] text-muted-foreground text-center">{isOwner === false ? 'Read-only — only an owner can change skills' : ''}</p>
               )}
+              {error && <p className="text-[11px] text-destructive mt-1 break-words">{error}</p>}
             </div>
           </div>
 
@@ -219,7 +238,7 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                     <span>{selected}</span>
                   </div>
                   <div className="flex items-center gap-1.5">
-                    {isSelectedBuiltin && (
+                    {readOnly && (
                       <span className="text-[10px] text-muted-foreground bg-muted px-1.5 py-0.5 rounded font-medium flex items-center gap-0.5">
                         <Lock className="w-2.5 h-2.5" /> read-only
                       </span>
@@ -234,14 +253,16 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                         </span>
                       </>
                     )}
-                    <Button
-                      variant="ghost" size="sm" className="h-6 text-xs px-1.5"
-                      onClick={() => startAction('duplicate')}
-                      title="Duplicate"
-                    >
-                      <Copy className="w-3 h-3" />
-                    </Button>
-                    {!isSelectedBuiltin && (
+                    {canEdit && (
+                      <Button
+                        variant="ghost" size="sm" className="h-6 text-xs px-1.5"
+                        onClick={() => startAction('duplicate')}
+                        title="Duplicate"
+                      >
+                        <Copy className="w-3 h-3" />
+                      </Button>
+                    )}
+                    {!readOnly && (
                       <Button
                         variant="ghost" size="sm" className="h-6 text-xs px-1.5"
                         onClick={() => startAction('rename')}
@@ -250,7 +271,7 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                         <Pencil className="w-3 h-3" />
                       </Button>
                     )}
-                    {dirty && !isSelectedBuiltin && (
+                    {dirty && !readOnly && (
                       <Button size="sm" className="h-6 text-xs" onClick={save}>
                         <Check className="w-3 h-3 mr-1" /> Save
                       </Button>
@@ -259,9 +280,9 @@ export function SkillsManager({ getToken, onSkillsChange, trigger }: Props) {
                 </div>
                 <Textarea
                   value={content}
-                  onChange={(e) => { if (!isSelectedBuiltin) { setContent(e.target.value); setDirty(true); } }}
-                  readOnly={isSelectedBuiltin}
-                  className={`flex-1 resize-none rounded-none border-0 font-mono text-xs focus-visible:ring-0 ${isSelectedBuiltin ? 'opacity-70 cursor-default' : ''}`}
+                  onChange={(e) => { if (!readOnly) { setContent(e.target.value); setDirty(true); } }}
+                  readOnly={readOnly}
+                  className={`flex-1 resize-none rounded-none border-0 font-mono text-xs focus-visible:ring-0 ${readOnly ? 'opacity-70 cursor-default' : ''}`}
                   placeholder="Write the skill instructions here…"
                 />
               </>

package/src/client/hooks/useAuth.ts

@@ -1,5 +1,9 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { onAuth, signOutUser, hasFirebase } from '@/lib/firebase';
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('useAuth');
 
 export interface AuthUser {
   uid: string;
@@ -47,13 +51,18 @@ export function useAuth(): AuthState {
       let m: 'local' | 'firebase' = hasFirebase ? 'firebase' : 'local';
       try {
         const r = await fetch('/api/auth/mode');
+        // The ONLY unauthenticated request the app makes, so it is the one chance to detect a hijacked
+        // backend BEFORE login. Without this a port-hijack just renders the login page forever with no
+        // explanation — the sign-in never succeeds and nothing on screen says why.
+        reportApiResponse('/api/auth/mode', r);
         if (r.ok) {
           const d = await r.json();
           m = d.provider === 'firebase' ? 'firebase' : 'local';
           setNeedsSetup(!!d.needsSetup);
         }
-      } catch {
-        /* fall back to firebase-presence heuristic */
+      } catch (err) {
+        reportApiFailure('/api/auth/mode', err);
+        log.warn('auth-mode probe failed — falling back to the firebase-presence heuristic', err);
       }
       setMode(m);
 

package/src/client/hooks/useIsOwner.ts

@@ -0,0 +1,24 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Whether the signed-in caller is an owner — `isOwner` on `GET /api/config` (derived server-side, never persisted).
+ * `undefined` until known. A UI hint only: the server enforces owner-only mutations regardless.
+ */
+export function useIsOwner(getToken: () => Promise<string | null>, enabled = true): boolean | undefined {
+  const [isOwner, setIsOwner] = useState<boolean>();
+
+  useEffect(() => {
+    if (!enabled) return;
+    let alive = true;
+    getToken().then((token) => {
+      if (!token || !alive) return;
+      fetch('/api/config', { headers: { Authorization: `Bearer ${token}` } })
+        .then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); })
+        .then((c: { isOwner?: boolean }) => { if (alive) setIsOwner(!!c.isOwner); })
+        .catch((e) => console.warn('[isOwner] load failed', e));
+    });
+    return () => { alive = false; };
+  }, [enabled, getToken]);
+
+  return isOwner;
+}

package/src/client/hooks/useModules.ts

@@ -42,7 +42,11 @@ export function useModules(getToken: () => Promise<string | null>, enabled: bool
     setLoading(true);
     setError(null);
     try {
-      const data = await api<{ installed: InstalledModule[]; available: AvailableModule[] }>('/api/modules', getToken);
+      const data = await api<{ installed: InstalledModule[]; available: AvailableModule[] }>('/api/modules', getToken, {
+        // A 404 here is the documented "server predates /api/modules" probe below — a handled outcome,
+        // not a backend fault, so it must not raise the health banner.
+        expect: [404],
+      });
       setInstalled(data.installed ?? []);
       setAvailable(data.available ?? []);
       setUnsupported(false);

package/src/client/lib/api.ts

@@ -1,10 +1,26 @@
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
+
 /** Minimal authenticated JSON fetch helper. Throws `Error("<status> <statusText>")` or the server's `error` field. */
-export async function api<T>(path: string, getToken: () => Promise<string | null>, init?: RequestInit): Promise<T> {
+export async function api<T>(
+  path: string,
+  getToken: () => Promise<string | null>,
+  /** `expect`: statuses this call site handles as normal — see `apiFetch`. Still throws; it only keeps
+   *  the backend-health banner from flagging a by-design non-2xx. */
+  init?: RequestInit & { expect?: readonly number[] },
+): Promise<T> {
   const token = await getToken();
-  const res = await fetch(path, {
-    ...init,
-    headers: { Authorization: `Bearer ${token ?? ''}`, 'Content-Type': 'application/json', ...init?.headers },
-  });
+  let res: Response;
+  try {
+    res = await fetch(path, {
+      ...init,
+      headers: { Authorization: `Bearer ${token ?? ''}`, 'Content-Type': 'application/json', ...init?.headers },
+    });
+  } catch (err) {
+    // Single choke point: every caller of api() gets backend-fault surfacing with no call-site change.
+    reportApiFailure(path, err);
+    throw err;
+  }
+  reportApiResponse(path, res, init?.expect);
   if (!res.ok) {
     const body = await res.json().catch(() => ({}));
     throw new Error(body.error || `${res.status} ${res.statusText}`);

package/src/client/lib/backendHealth.ts

@@ -0,0 +1,230 @@
+/** Backend-health classifier + tiny store.
+ *
+ *  WHY this exists: a broken backend used to be INVISIBLE in the UI. When something other than shraga
+ *  answered the app's port (e.g. another project's dev server bound `127.0.0.1:3033` while shraga held
+ *  `*:3033` — macOS routes the loopback name to the MORE SPECIFIC bind, so the proxy fed every request
+ *  to the wrong process), the foreign server 404'd `/api/config`, `/api/workspace` and refused the `/ws`
+ *  upgrade. The UI rendered a normal-looking EMPTY shell: no workspace, no terminals, no error. Every
+ *  clue was in the browser console and nothing reached the screen.
+ *
+ *  The load-bearing signal is {@link SHRAGA_VERSION_HEADER}: the shraga server stamps it on EVERY
+ *  response including 404/401/5xx (src/server/boot.ts). So a response WITHOUT it did not come from
+ *  shraga at all — which turns an ambiguous "some 404" into the exact diagnosis "something else is
+ *  serving this port".
+ *
+ *  Producers report here from the SHARED helpers (`apiFetch`, `api`, `AgentSocket`) so every existing
+ *  call site benefits with no call-site change. The single consumer is <BackendStatusBanner />.
+ */
+import { logger } from '@/lib/debug';
+
+const log = logger.forComponent('BackendHealth');
+
+/** Identity header stamped by the shraga server on every response. Lowercase: `Headers` is
+ *  case-insensitive, but keeping it lowercase avoids any doubt about what we're matching. */
+export const SHRAGA_VERSION_HEADER = 'x-shraga-version';
+
+export type BackendFaultKind = 'wrong-backend' | 'server-error' | 'offline' | 'ws-down';
+
+export interface BackendFault {
+  kind: BackendFaultKind;
+  /** One-line headline for the banner. */
+  title: string;
+  /** Actionable next step — what the user should actually go do. */
+  hint: string;
+  /** The request that exposed the fault, when there is one. */
+  path?: string;
+  status?: number;
+}
+
+/** Fault sources are tracked SEPARATELY: HTTP recovering must not erase a still-broken WebSocket
+ *  (that is exactly the "terminals stay blank while the page looks fine" half of the incident). */
+type Source = 'http' | 'ws';
+const faults: Partial<Record<Source, BackendFault>> = {};
+const raisedAt: Partial<Record<Source, number>> = {};
+
+/** A raised fault does NOT vanish on the very next good response. The app polls continuously (pty cwd,
+ *  workspace, layout), so a single interleaved success would otherwise erase the banner milliseconds
+ *  after it appeared — leaving a user staring at a flicker they can neither read nor act on. Recovery
+ *  must therefore be CONFIRMED: several consecutive good responses AND a minimum time on screen. */
+/** ...and the SAME reasoning governs the WebSocket. An ordinary reconnect blip closes and re-opens in
+ *  a couple of seconds (backoff is ~1s * 2^attempt + jitter); painting and erasing an amber banner
+ *  inside that window is the flicker described above, not information. So a close is given
+ *  `wsGraceMs` to recover before it becomes a fault at all — which still catches the case that
+ *  motivated the feature, a socket that never comes back (including one wedged in CONNECTING, where
+ *  counting reconnect ATTEMPTS would never trip) — and a recovered socket serves the same
+ *  `minDwellMs` before the banner is taken down. */
+const DEFAULT_TIMING = { okStreakToClear: 3, minDwellMs: 5_000, wsGraceMs: 5_000 };
+type Timing = typeof DEFAULT_TIMING;
+let timing: Timing = { ...DEFAULT_TIMING };
+let okStreak = 0;
+/** The single pending ws timer: a delayed RAISE while no ws fault is shown, a delayed CLEAR while one
+ *  is (`faults.ws` disambiguates, and every path that changes that state cancels it first). */
+let wsTimer: ReturnType<typeof setTimeout> | null = null;
+function cancelWsTimer() {
+  if (wsTimer) { clearTimeout(wsTimer); wsTimer = null; }
+}
+
+/** Worst-first. `wrong-backend` outranks everything: when the port is hijacked the 404s and the dead
+ *  socket are SYMPTOMS, and showing either of those instead would send the user down the wrong path. */
+const PRECEDENCE: BackendFaultKind[] = ['wrong-backend', 'offline', 'server-error', 'ws-down'];
+
+type Listener = (fault: BackendFault | null) => void;
+const listeners = new Set<Listener>();
+
+export function currentFault(): BackendFault | null {
+  const present = (Object.values(faults) as BackendFault[]).filter(Boolean);
+  if (present.length === 0) return null;
+  return present.sort((a, b) => PRECEDENCE.indexOf(a.kind) - PRECEDENCE.indexOf(b.kind))[0];
+}
+
+function emit() {
+  const f = currentFault();
+  listeners.forEach((l) => l(f));
+}
+
+export function subscribeBackendHealth(listener: Listener): () => void {
+  listeners.add(listener);
+  listener(currentFault());
+  return () => { listeners.delete(listener); };
+}
+
+function set(source: Source, fault: BackendFault) {
+  const prev = faults[source];
+  faults[source] = fault;
+  // Restart the dwell when the fault CHANGES KIND too: a wrong-backend that supersedes an older
+  // server-error is a new message and needs its own time on screen, not the predecessor's leftovers.
+  if (prev?.kind !== fault.kind) raisedAt[source] = Date.now();
+  if (source === 'http') okStreak = 0;
+  // Log the transition only, not every repeat — a broken backend is polled continuously.
+  if (prev?.kind !== fault.kind || prev?.path !== fault.path || prev?.status !== fault.status) {
+    log.warn(`${fault.kind}: ${fault.title}`, { path: fault.path, status: fault.status });
+  }
+  emit();
+}
+
+function clear(source: Source) {
+  if (!faults[source]) return;
+  log.info(`${source} recovered`);
+  delete faults[source];
+  delete raisedAt[source];
+  emit();
+}
+
+/** Describe the origin the app believes it is talking to, for the wrong-backend message. */
+function originLabel(): string {
+  try { return window.location.origin; } catch { return 'this origin'; }
+}
+
+/**
+ * Classify a COMPLETED HTTP response from the shraga API. Call for ok and !ok alike — a wrong backend
+ * can answer `200` just as easily as `404`, so the identity header is checked first, unconditionally.
+ *
+ * `expect` lists statuses this CALL SITE treats as a normal, handled outcome (e.g. the pty-cwd poller,
+ * for which 404 means "that pane is gone" and is swallowed by design). An expected status is not a
+ * fault: raising a banner for a by-design 404 is the cry-wolf failure this whole module exists to
+ * avoid. It is checked AFTER the identity header, so a hijacker answering 404 is still caught.
+ */
+export function reportApiResponse(path: string, res: Response, expect?: readonly number[]): void {
+  if (!res.headers.has(SHRAGA_VERSION_HEADER)) {
+    set('http', {
+      kind: 'wrong-backend',
+      title: `${originLabel()} is being served by something that is not Shraga.`,
+      hint:
+        'Another process is almost certainly bound to the app port and shadowing the real server ' +
+        '(a more specific 127.0.0.1 bind wins over Shraga’s wildcard bind). Find it with ' +
+        '`lsof -nP -iTCP:<port> -sTCP:LISTEN`, stop it, then retry.',
+      path,
+      status: res.status,
+    });
+    return;
+  }
+  // Genuine shraga auth responses are the ORDINARY login/permission flow — never a banner. Checked
+  // after the header so a hijacker that answers 401 is still caught above.
+  if (res.status === 401 || res.status === 403) return;
+  // Handled by the caller — neither a fault nor evidence of recovery.
+  if (expect?.includes(res.status)) return;
+
+  if (!res.ok) {
+    set('http', {
+      kind: 'server-error',
+      title: `Shraga returned ${res.status} for ${path}.`,
+      hint: 'The server is reachable but this request failed. Retry; if it persists, check the server logs.',
+      path,
+      status: res.status,
+    });
+    return;
+  }
+  okStreak++;
+  if (faults.http && okStreak >= timing.okStreakToClear && Date.now() - (raisedAt.http ?? 0) >= timing.minDwellMs) {
+    clear('http');
+  }
+}
+
+/** Classify a request that never produced a response: network down, server unreachable, or aborted.
+ *
+ *  `timedOut` says the HELPER's OWN deadline fired (`apiFetch`'s `timeoutMs` controller). It is the
+ *  only thing that separates a genuine wedged server from a CALLER-initiated `abort()` — both surface
+ *  as an indistinguishable `AbortError`. A caller abort is ordinary control flow, not a fault: the tab
+ *  palette re-issues its search on every keystroke and aborts the in-flight one, so raising here
+ *  painted a red "cannot reach the server" banner for plain typing. Raise NOTHING for it.
+ */
+export function reportApiFailure(path: string, err: unknown, opts?: { timedOut?: boolean }): void {
+  const aborted = (err as { name?: string } | null)?.name === 'AbortError';
+  if (aborted && !opts?.timedOut) return;
+  set('http', {
+    kind: 'offline',
+    title: opts?.timedOut ? `Request to ${path} timed out.` : `Cannot reach the Shraga server.`,
+    hint: opts?.timedOut
+      ? 'The server accepted the connection but did not answer in time. It may be overloaded or wedged.'
+      : 'The network is down, or nothing is listening on the app port. Check your connection and that the server is running.',
+    path,
+  });
+}
+
+/** WebSocket health, reported by {@link AgentSocket}. A dead socket is why terminals and live updates
+ *  silently stop; without this the panes just stay blank.
+ *
+ *  A close does NOT raise on its own — it starts the grace window (see {@link DEFAULT_TIMING}). Only a
+ *  socket still down when the window expires is a fault the user can act on. */
+export function reportWsDown(code?: number): void {
+  // Already on screen: a re-close during the recovery dwell just keeps the banner up.
+  if (faults.ws) { cancelWsTimer(); return; }
+  // Grace already running from an earlier close in the same outage — don't restart it, or a socket
+  // that flaps every few seconds would push the deadline out forever and never raise.
+  if (wsTimer) return;
+  const raise = () => {
+    wsTimer = null;
+    set('ws', {
+      kind: 'ws-down',
+      title: 'Live connection lost — terminals and streaming updates are offline.',
+      hint:
+        code === 1006
+          ? 'The connection was refused or dropped without a close handshake, which usually means the ' +
+            'WebSocket upgrade never reached Shraga. Reconnecting…'
+          : 'Reconnecting…',
+      status: code,
+    });
+  };
+  if (timing.wsGraceMs <= 0) raise();
+  else wsTimer = setTimeout(raise, timing.wsGraceMs);
+}
+
+export function reportWsUp(): void {
+  cancelWsTimer(); // a blip that recovered inside the grace window never earned a banner
+  if (!faults.ws) return;
+  const remaining = timing.minDwellMs - (Date.now() - (raisedAt.ws ?? 0));
+  if (remaining <= 0) { clear('ws'); return; }
+  wsTimer = setTimeout(() => { wsTimer = null; clear('ws'); }, remaining);
+}
+
+/** Test seam — drop all state, and optionally shrink the timings so a test needn't wait seconds. */
+export function __resetBackendHealth(overrides?: Partial<Timing>): void {
+  cancelWsTimer();
+  timing = { ...DEFAULT_TIMING, ...overrides };
+  delete faults.http;
+  delete faults.ws;
+  delete raisedAt.http;
+  delete raisedAt.ws;
+  okStreak = 0;
+  emit();
+}

package/src/client/lib/debug.ts

@@ -0,0 +1,48 @@
+/** Component-scoped console logger.
+ *
+ *  `debug`/`verbose` are development output and are GATED per component — they print only when the
+ *  component's name (or `*`) appears in the comma-separated `DEBUG` localStorage key:
+ *      localStorage.setItem('DEBUG', 'BackendHealth,ws')
+ *  `info`/`warn`/`error` are operational and ALWAYS print. Use this instead of raw `console.*` so a
+ *  noisy module can be silenced without deleting the logging that diagnoses a live incident.
+ */
+
+type LogFn = (...args: unknown[]) => void;
+
+export interface ComponentLogger {
+  debug: LogFn;
+  verbose: LogFn;
+  info: LogFn;
+  warn: LogFn;
+  error: LogFn;
+}
+
+/** Read once per call rather than caching: a dev flipping `DEBUG` in devtools expects it to take
+ *  effect without a reload, and this only runs on a log call that is already about to hit console. */
+function gateAllows(component: string): boolean {
+  let raw: string | null = null;
+  try {
+    raw = localStorage.getItem('DEBUG');
+  } catch {
+    return false; // storage blocked (private mode / sandboxed iframe) — dev output is not worth throwing over
+  }
+  if (!raw) return false;
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .some((s) => s === '*' || s === component);
+}
+
+export const logger = {
+  forComponent(component: string): ComponentLogger {
+    const tag = `[${component}]`;
+    const gated = (fn: LogFn): LogFn => (...args) => { if (gateAllows(component)) fn(tag, ...args); };
+    return {
+      debug: gated((...a) => console.debug(...a)),
+      verbose: gated((...a) => console.debug(...a)),
+      info: (...a) => console.info(tag, ...a),
+      warn: (...a) => console.warn(tag, ...a),
+      error: (...a) => console.error(tag, ...a),
+    };
+  },
+};

package/src/client/lib/sessionApi.ts

@@ -1,3 +1,4 @@
+import { reportApiFailure, reportApiResponse } from '@/lib/backendHealth';
 import { randomUUID } from '@/lib/utils';
 import type { ChatMessage, MessageBlock } from '@/hooks/useConversation';
 
@@ -15,24 +16,39 @@ export class ApiError extends Error {
   }
 }
 
-/** Authenticated fetch with bearer token + timeout. Throws `ApiError` (with `.status`) on !ok. */
+/** Authenticated fetch with bearer token + timeout. Throws `ApiError` (with `.status`) on !ok.
+ *
+ *  `expect` lists statuses this call site HANDLES as a normal outcome (it still throws — see `ApiError`
+ *  — the list only tells the backend-health classifier not to treat them as a fault). Use it wherever a
+ *  non-2xx is by design, or the shared banner cries wolf on routine traffic. */
 export async function apiFetch(
   path: string,
   getToken: () => Promise<string | null>,
-  init?: RequestInit & { timeoutMs?: number },
+  init?: RequestInit & { timeoutMs?: number; expect?: readonly number[] },
 ) {
   const token = await getToken();
   if (!token) throw new Error('No auth token');
   const timeout = init?.timeoutMs ?? 15_000;
   const controller = new AbortController();
   if (init?.signal) init.signal.addEventListener('abort', () => controller.abort());
-  const timer = setTimeout(() => controller.abort(), timeout);
+  // `timedOut` is the ONLY thing that distinguishes our own deadline from a caller's abort() — both
+  // reject with an identical AbortError, and only the former is a real backend fault.
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; controller.abort(); }, timeout);
   try {
-    const res = await fetch(path, {
-      ...init,
-      signal: controller.signal,
-      headers: { Authorization: `Bearer ${token}`, ...init?.headers },
-    });
+    let res: Response;
+    try {
+      res = await fetch(path, {
+        ...init,
+        signal: controller.signal,
+        headers: { Authorization: `Bearer ${token}`, ...init?.headers },
+      });
+    } catch (err) {
+      // Single choke point: every apiFetch call site gets backend-fault surfacing for free.
+      reportApiFailure(path, err, { timedOut });
+      throw err;
+    }
+    reportApiResponse(path, res, init?.expect);
     if (!res.ok) throw new ApiError(res.status, res.statusText);
     return res;
   } finally {