agentgui 1.0.945 → 1.0.947

package/AGENTS.md

@@ -10,7 +10,7 @@ When `PASSWORD` env var is set, every HTTP route is gated by `lib/http-handler.j
 - `site/app/js/backend.js` — same-origin WS/HTTP client (`DEFAULT_BACKEND = ''`); the transport glue that wires the kit; `?backend=` query override for cross-origin debugging
 - `site/app/js/app.js` — webjsx view + state; renders the `AgentChat` kit (from `anentrypoint-design`) for the chat surface and wires agentgui's WS/ccsniff state as kit callbacks; history/settings remain agentgui-local. Exposes `window.__agentgui`
 
-The chat GUI lives in the design kit, not in agentgui. The reusable multi-agent chat surface is the `AgentChat` component in `anentrypoint-design` (`src/components/agent-chat.js`); agentgui keeps only the transport glue (WS `backend.js`, ccsniff history wiring, agent orchestration) and passes state + callbacks into the kit. To change chat UI, edit the kit and push it (CI publishes to npm → unpkg `@latest`), not agentgui.
+The chat GUI lives in the design kit, not in agentgui. The reusable multi-agent chat surface is the `AgentChat` component in `anentrypoint-design` (`src/components/agent-chat.js`); agentgui keeps only the transport glue (WS `backend.js`, ccsniff history wiring, agent orchestration) and passes state + callbacks into the kit. To change chat UI, edit the kit and push it (CI publishes to npm -> unpkg `@latest`), not agentgui.
 - `server.js` — boots ACP/agents/websocket plugins, mounts `createHistoryRouter()` from `ccsniff` at `/`, serves `site/app/` as static root
 - Plugins kept (lib/plugins/): acp, agents, database, files, stream, websocket, workflow
 
@@ -60,7 +60,7 @@ Pattern: all imports in lib/plugins/* must be either built-in (crypto, fs, path,
 
 ## Plugin Tool Provisioning on Windows
 
-**`lib/tool-spawner.js` must iterate bun → npx fallback and match cross-platform command-not-found errors.**
+**`lib/tool-spawner.js` must iterate bun -> npx fallback and match cross-platform command-not-found errors.**
 
 On Windows hosts without bun installed, the auto-provisioner on startup and 6h periodic update checker failed silently when spawnBunxProc tried `bun.cmd` directly. The missing command error came via process stderr+close, not the 'error' event, so simple ENOENT detection was insufficient. Additionally, the error message format differs by OS: Windows shows "'bun.cmd' is not recognized as an internal or external command", Linux/Mac show "command not found" or "cannot find".
 
@@ -72,7 +72,7 @@ Pattern: When a binary might not exist on all platforms, use a runner fallback s
 
 **gm plugin's pre-tool-use-hook.js enforces "must invoke gm:gm first" gate, blocking multi-tool autonomy. Hook content is NOT sourced from gm-starter/hooks/ files — it is templated from somewhere else.**
 
-The gm plugin enforces a gate via `.gm/needs-gm` marker that requires invoking `gm:gm` before any other tool use, which fragments multi-tool autonomous sessions in agentgui. A bypass patch was committed to c:/dev/gm (commit e300acf7, origin/main) in gm-starter/hooks/{pre-tool-use,prompt-submit}-hook.js to skip the gate when `.gm/prd.yml` exists, but it did NOT propagate after `/plugin update gm` (cache hash changed 495e36843d77 → 075e64d58498 but hook content unchanged).
+The gm plugin enforces a gate via `.gm/needs-gm` marker that requires invoking `gm:gm` before any other tool use, which fragments multi-tool autonomous sessions in agentgui. A bypass patch was committed to c:/dev/gm (commit e300acf7, origin/main) in gm-starter/hooks/{pre-tool-use,prompt-submit}-hook.js to skip the gate when `.gm/prd.yml` exists, but it did NOT propagate after `/plugin update gm` (cache hash changed 495e36843d77 -> 075e64d58498 but hook content unchanged).
 
 The actual hook content is generated/templated from c:/dev/gm, likely from `lib/cli-adapter.js` or `platforms/cli-config-shared.js` or `lib/template-builder.js`, not from gm-starter/hooks/. Next session must:
 1. Locate the real hook generator in the gm codebase
@@ -99,33 +99,19 @@ The function previously returned "Model: X." when agentId was 'claude-code' and
 
 **WebSocket `/sync` endpoint — message ordering requires registering handler BEFORE sending.**
 
-Server sends `sync_connected` with `clientId` on connect. Legacy handler (`lib/ws-legacy-handlers.js`) handles `ping→pong`, `subscribe→subscription_confirmed`, `get_subscriptions→subscriptions`, `unsubscribe`, `latency_report`. All responses use codec encode/decode (`lib/codec.js`). Pattern: queue outbound messages and use a waiters array + sequential promises to avoid race between send and handler registration. Test structure: `const queued = []; let waiting; ws.on('message', ...); queued.forEach(msg => ws.send(msg)); waiting.resolve(...)` ensures the handler is live before messages flow.
+Server sends `sync_connected` with `clientId` on connect. Legacy handler (`lib/ws-legacy-handlers.js`) handles `ping->pong`, `subscribe->subscription_confirmed`, `get_subscriptions->subscriptions`, `unsubscribe`, `latency_report`. All responses use codec encode/decode (`lib/codec.js`). Pattern: queue outbound messages and use a waiters array + sequential promises to avoid race between send and handler registration. Test structure: `const queued = []; let waiting; ws.on('message', ...); queued.forEach(msg => ws.send(msg)); waiting.resolve(...)` ensures the handler is live before messages flow.
 
-## better-sqlite3 & Node v24 Startup (2026-05-03)
+## better-sqlite3 & Node v24 Startup
 
-**Node v24 has no prebuilt binary for better-sqlite3 (module version 137); npm rebuild silently fails.**
-
-When npm install runs on Node v24, the postinstall hook for better-sqlite3 silently fails because no prebuilt `.node` binary exists for that module version. The server then fails to require better-sqlite3 and crashes. npm rebuild also silently fails.
-
-Fix: compile from source in postinstall:
-```json
-"postinstall": "node scripts/patch-fsbrowse.js && node scripts/copy-vendor.js && (cd node_modules/better-sqlite3 && node-gyp rebuild 2>/dev/null) || true"
-```
-
-Paired changes:
-- `package.json` `start` script: `"bun server.js || node server.js"` (prefer bun, fall back to node)
-- `bin/gmgui.cjs` runtime detection: `spawnSync('bun', ['--version'], { shell: true })` to auto-detect bun availability, fallback to node (lines 46-47)
-- better-sqlite3 bumped ^12.6.2 → ^12.9.0
-
-bun start was already working (bun has native sqlite support via `bun:sqlite`). The node path was broken due to the missing native binding. Only compile from source fixes the node path.
+Node v24 lacks a prebuilt better-sqlite3 binary; the node path needs a from-source `postinstall` compile, and `start` is `bun server.js || node server.js`. `database.js` tries `bun:sqlite` first. Detail (postinstall command, paired package.json/bin changes, CI must-run-under-bun) in rs-learn (recall "agentgui startup better-sqlite3 node v24 bun").
 
 ## webjsx applyDiff Array Keying (2026-05-04)
 
 **Children arrays that mix keyed VElements with raw text/numbers crash in `vendor/webjsx/applyDiff.js`.**
 
-`webjsx` requires all siblings in an array prop (children, right, left, breadcrumbs, etc.) to either ALL be VElements with keys or ALL be non-keyed. Passing `Crumb({ right: [h('span', { key: 'a' }, 'A'), h('span', { key: 'b' }, 'B'), '● connected'] })` crashes on render with `TypeError: Cannot read properties of undefined (reading 'key')` at line 247420.js when the render loop tries to read `.key` on the bare string.
+`webjsx` requires all siblings in an array prop (children, right, left, breadcrumbs, etc.) to either ALL be VElements with keys or ALL be non-keyed. Passing `Crumb({ right: [h('span', { key: 'a' }, 'A'), h('span', { key: 'b' }, 'B'), 'connected'] })` crashes on render with `TypeError: Cannot read properties of undefined (reading 'key')` at line 247420.js when the render loop tries to read `.key` on the bare string.
 
-Fix: wrap any bare strings as keyed VElements: `h('span', { key: 'dot' }, '● connected')`. Rule: if ANY sibling in an array has a key, ALL siblings must be VElements (no raw strings or numbers).
+Fix: wrap any bare strings as keyed VElements: `h('span', { key: 'dot' }, 'connected')`. Rule: if ANY sibling in an array has a key, ALL siblings must be VElements (no raw strings or numbers).
 
 Surfaced 2026-05-04 while validating the chat surface in `site/app/`. Fix applied to crumbRight construction in `site/app/js/app.js` view().
 
@@ -143,7 +129,7 @@ Event dispatch loop:
 
 Throttle renders via `requestAnimationFrame` to avoid event storm during burst loads.
 
-**First request to `/v1/history/*` triggers loadOnce() that walks all JSONL files under ~/.claude/projects** (env default; override with `CLAUDE_PROJECTS_DIR`). In our test env: 299 files, 80MB, 69k events → 30-90s startup latency. Health check timeouts during this window are normal and expected. Subsequent requests are fast (cached index).
+**First request to `/v1/history/*` triggers loadOnce() that walks all JSONL files under ~/.claude/projects** (env default; override with `CLAUDE_PROJECTS_DIR`). In our test env: 299 files, 80MB, 69k events -> 30-90s startup latency. Health check timeouts during this window are normal and expected. Subsequent requests are fast (cached index).
 
 The endpoints are served by ccsniff's Express router mounted in-process from `server.js`. No external proxy.
 
@@ -153,10 +139,18 @@ The GUI loads `anentrypoint-design` from `https://unpkg.com/anentrypoint-design@
 
 ## Agent/model/session management (2026-05-28)
 
-- `agents.list` (WS) returns `available` + `npxInstallable` per agent; `agents.models` returns model choices (claude-code → sonnet/opus/haiku). The chat picker is **agent-then-model**, not a flat model list. Unavailable agents are disabled/gated.
+- `agents.list` (WS) returns `available` + `npxInstallable` per agent; `agents.models` returns model choices (claude-code -> sonnet/opus/haiku). The chat picker is **agent-then-model**, not a flat model list. Unavailable agents are disabled/gated.
 - `chat.sendMessage` accepts `cwd` (defaults to STARTUP_CWD) and `model`/`agentId` separately. `chat.active` (WS) lists in-flight chats with agentId/model/cwd/startedAt/pid; the history tab polls it (3s) and shows a running panel with per-session stop.
 - Client (`app.js`): chat transcript persists to `localStorage[agentgui.chat]` and restores on load; tool_use/result events render as chat parts; keyboard shortcuts (g+c/h/s, n, /, ?); settings has an agents-status panel from `health.acp[]`.
 
+## Kit Row rail + rank contract
+
+The design-kit `Row` (`anentrypoint-design` `src/components/content.js`) renders a leading status **rail** from a `rail` prop (`green` | `purple` | `flame`, via a `.row.rail-<tone>::before` bar) and accepts `rank` as an alias for the leading `code` index. A `state: 'disabled'` Row is inert — no `onClick`/`role=button`/tab-stop, `aria-disabled=true`. agentgui's history sessions, search results, and agents panel pass `rail` + `rank` and rely on this; the rendering reaches the live GUI only after the kit publishes to npm -> unpkg `@latest`. agentgui keeps the rail semantics consistent everywhere: **green = selected/ok, purple = subagent, flame = error/unavailable**.
+
+## GUI glyph policy
+
+GUI source keeps typographic product characters — the middot separator `·`, the ellipsis `…`, and em/en dashes in prose — as established design (AGENTS.md itself uses `·`). It carries **no** decorative tells: arrows, box-drawing, bullets, status dots, checks. Status is words + the CSS-drawn `.status-dot-disc`. Convert any arrow/box-drawing/bullet glyph to ASCII on sight (`->`, `// --- x ---`, `-`/`*`).
+
 ## DS CSS cascade — overriding component styles (2026-05-28)
 
 **`installStyles()` injects DS CSS into a runtime `<style>` after the head `<style>`, so local overrides need `!important` or higher specificity than the DS's `.ds-247420`-prefixed rules.** Full detail (font vars `--ff-display`/`--ff-mono`, the `.chat-head .sub` "00 msgs" quirk, EventList `.row[role=button]`, `[data-prog-focus]` focus suppression, `projectLabel()` for cwd slugs) is in rs-learn (recall "agentgui GUI styling DS cascade installStyles").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.945",
+  "version": "1.0.947",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",

package/site/app/index.html

@@ -19,6 +19,18 @@
       --agentgui-fg: #e6e6ea;
       --agentgui-accent: #50c878;
       --agentgui-warn: #ff6b6b;
+      /* status-dot state colours, brightened for >=3:1 contrast on the dark bg */
+      --agentgui-status-connecting: #f0b84a;
+      --agentgui-status-offline: #e06b66;
+      /* unified muted text fallback (was an inconsistent mix of #888/#999) */
+      --agentgui-muted: #8a8f98;
+    }
+
+    /* visually-hidden but screen-reader-available (aria-live announcer, labels) */
+    .sr-only {
+      position: absolute !important; width: 1px; height: 1px;
+      padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0);
+      white-space: nowrap; border: 0;
     }
     html, body {
       margin: 0;
@@ -80,8 +92,8 @@
       background: var(--accent, var(--agentgui-accent, #50c878));
       animation: agentgui-pulse 2s infinite;
     }
-    .status-dot.is-connecting .status-dot-disc { background: #d9a441; }
-    .status-dot.is-offline .status-dot-disc { background: #c0504d; animation: none; }
+    .status-dot.is-connecting .status-dot-disc { background: var(--agentgui-status-connecting); }
+    .status-dot.is-offline .status-dot-disc { background: var(--agentgui-status-offline); animation: none; }
     @keyframes agentgui-pulse {
       0%   { box-shadow: 0 0 0 0 rgba(80, 200, 120, .5); }
       70%  { box-shadow: 0 0 0 6px rgba(80, 200, 120, 0); }
@@ -159,7 +171,7 @@
 
     /* empty-state: keep it from wrapping awkwardly in the narrow sidebar */
     .empty-state { white-space: normal; }
-    p.empty-state { text-align: left; padding: .6em 0; color: var(--fg-3, #888); }
+    p.empty-state { text-align: left; padding: .6em 0; color: var(--fg-3, var(--agentgui-muted)); }
 
     /* generic interactive focus ring */
     button:focus-visible, [tabindex]:focus-visible, a:focus-visible {
@@ -198,7 +210,7 @@
     }
     .cwd-bar-text {
       font-family: var(--ff-mono, ui-monospace, monospace);
-      color: var(--fg-3, #999); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 60vw;
+      color: var(--fg-3, var(--agentgui-muted)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 60vw;
     }
     .cwd-bar-btn {
       cursor: pointer; font: inherit; line-height: 1.3;
@@ -213,9 +225,8 @@
     /* History no-session empty state: fill the void with a centered prompt. */
     .history-empty {
       display: flex; flex-direction: column; align-items: center; justify-content: center;
-      gap: .4em; text-align: center; min-height: 50vh; color: var(--fg-3, #888);
+      gap: .4em; text-align: center; min-height: 50vh; color: var(--fg-3, var(--agentgui-muted));
     }
-    .history-empty-glyph { font-size: 3rem; opacity: .25; line-height: 1; }
     .history-empty-title { margin: 0; font-size: 1.05rem; color: var(--fg-2, var(--agentgui-fg)); }
     .history-empty-sub { margin: 0; max-width: 42ch; }
 
@@ -252,10 +263,21 @@
     .chat-composer textarea { overflow-y: auto; scrollbar-width: thin; }
     .chat-composer textarea:not(:focus) { overflow-y: hidden; }
 
+    /* tablet: keep the chat control cluster from wrapping the status dot alone */
+    @media (max-width: 900px) {
+      .chat-controls select,
+      .chat-controls .select,
+      .chat-controls [role="combobox"] { min-width: 110px; max-width: 170px; }
+    }
+
     /* touch targets on small screens */
     @media (max-width: 640px) {
       .pill { min-height: 36px; padding: .4em .8em; }
+      .history-actions { gap: .75em; }
       .history-actions .btn, .history-actions button { min-height: 44px; }
+      /* cwd path can't eat the whole row beside its label + buttons on a phone */
+      .cwd-bar-text { max-width: 42vw; }
+      .cwd-bar { gap: .3em; }
     }
 
     @media print {
@@ -270,7 +292,6 @@
   </style>
 </head>
 <body>
-  <a href="#agentgui-main" class="skip-link">Skip to main content</a>
   <div id="app"></div>
   <script type="module" src="./js/app.js"></script>
 </body>

package/site/app/js/app.js

@@ -85,6 +85,24 @@ function debounce(fn, ms) {
 function lsSet(k, v) { try { localStorage.setItem(k, v); } catch {} }
 function lsRemove(k) { try { localStorage.removeItem(k); } catch {} }
 
+// A single visually-hidden aria-live region for transient announcements (tab
+// changes, etc.) so screen-reader users hear context that's otherwise conveyed
+// only by focus movement or color.
+let _announcer = null;
+function announce(msg) {
+  if (typeof document === 'undefined') return;
+  if (!_announcer) {
+    _announcer = document.createElement('div');
+    _announcer.setAttribute('aria-live', 'polite');
+    _announcer.setAttribute('role', 'status');
+    _announcer.className = 'sr-only';
+    document.body.appendChild(_announcer);
+  }
+  // Clear then set on the next frame so repeated identical messages re-announce.
+  _announcer.textContent = '';
+  requestAnimationFrame(() => { if (_announcer) _announcer.textContent = msg; });
+}
+
 function pillButton(key, label, active, title, onClick) {
   return h('button', {
     key,
@@ -113,15 +131,22 @@ function timeNow() {
 }
 
 async function selectAgent(id) {
+  // Re-selecting the same agent would needlessly refetch models and reset the
+  // current model selection — no-op early.
+  if (id === state.selectedAgent && state.agentModels.length) return;
   state.selectedAgent = id;
   localStorage.setItem('agentgui.agent', id);
   state.agentModels = [];
   state.selectedModel = '';
+  state.modelsLoading = true;
   render();
   const models = await B.listAgentModels(state.backend, id);
   if (state.selectedAgent !== id) return; // changed while loading
+  state.modelsLoading = false;
   state.agentModels = models;
   const saved = localStorage.getItem('agentgui.model');
+  // Only restore a saved model that the NEW agent actually offers; otherwise
+  // fall back to its first model (never carry a stale model from a prior agent).
   state.selectedModel = (saved && models.some(m => m.id === saved)) ? saved : (models[0]?.id || '');
   render();
 }
@@ -158,6 +183,9 @@ function sortedAgents() {
 
 function navTo(tab) {
   const prev = state.tab;
+  // Leaving chat clears any pending new-chat confirmation so it doesn't linger
+  // as a stale banner when the user returns.
+  if (prev === 'chat' && tab !== 'chat') state.confirmingNewChat = false;
   state.tab = tab;
   // Live history SSE is only needed on the history tab; active-chat polling
   // runs globally (started at boot) so running chats show on every tab.
@@ -168,6 +196,7 @@ function navTo(tab) {
     closeLiveStream();
   }
   writeHash(state.selectedSid && tab === 'history' ? state.selectedSid : null);
+  announce('Now on ' + tab + ' tab');
   render();
   // Move focus into the new region for keyboard/AT users.
   requestAnimationFrame(() => {
@@ -187,7 +216,7 @@ function navTo(tab) {
   });
 }
 
-// The DS Topbar derives aria-current from href↔location.hash matching, which
+// The DS Topbar derives aria-current from href<->location.hash matching, which
 // drifts from our hash-based active tab (e.g. aria-current lands on "settings"
 // while we're on "chat"). Re-assert aria-current on the actually-active tab.
 function syncAriaCurrent() {
@@ -308,15 +337,26 @@ function view() {
     onNav: (label) => navTo(label),
   });
 
-  // The agent/model picker + new/stop now live inside the AgentChat kit (chat
-  // tab), so the crumb carries only the status dot on every tab.
+  // The crumb's right slot carries the live/connection status dot on every tab.
   const crumbRight = [dot];
 
-  // Topbar already shows "agentgui / <tab>"; the crumb is reserved for contextual
-  // controls (model picker, new/stop, live status) so it doesn't duplicate the path.
+  // Give the crumb contextual content on the left so it isn't a bare bar holding
+  // only the dot: on history it names the selected session (or "all sessions"),
+  // on chat it names the active agent, on settings it's "configuration".
+  let crumbLeaf = '';
+  if (state.tab === 'history') {
+    const sel = state.selectedSid && (Array.isArray(state.sessions) ? state.sessions : []).find(s => s.sid === state.selectedSid);
+    crumbLeaf = state.selectedSid
+      ? truncate(projectLabel(sel?.title) || projectLabel(sel?.project) || state.selectedSid, 24, 48)
+      : 'all sessions';
+  } else if (state.tab === 'chat') {
+    crumbLeaf = state.selectedAgent ? (agentById(state.selectedAgent)?.name || state.selectedAgent) : 'no agent';
+  } else if (state.tab === 'settings') {
+    crumbLeaf = 'configuration';
+  }
   const crumb = Crumb({
     trail: [],
-    leaf: '',
+    leaf: crumbLeaf,
     right: crumbRight,
   });
 
@@ -329,7 +369,7 @@ function view() {
     : 'no agent';
   const status = Status({
     left: [state.backend || 'same-origin', ok ? 'live' : 'offline'],
-    right: [agentLabel],
+    right: [agentLabel, 'press ? for shortcuts'],
   });
 
   // The design system now owns the full-height column + inner scroll for
@@ -342,7 +382,10 @@ function view() {
         children: 'g then c/h/s — chat/history/settings · n — new chat · / — focus search/composer · ? — toggle this · Esc — blur field' })
     : null;
   const main = h('div', { id: 'agentgui-main', role: 'main', 'data-chat-scroll': '', class: 'agentgui-main agentgui-main-' + state.tab, style: mainStyle }, [shortcutsHint, ...mainContent()].filter(Boolean));
-  return AppShell({ topbar, crumb, side, main, status, narrow: false });
+  // narrow drives the DS main-column class; the history sidebar itself collapses
+  // behind the DS .app-side-toggle hamburger (provided by AppShell when a side
+  // exists), so mobile users get a togglable session list.
+  return AppShell({ topbar, crumb, side, main, status, narrow: isNarrow() });
 }
 
 function mainContent() {
@@ -351,7 +394,7 @@ function mainContent() {
   return settingsMain();
 }
 
-// ── chat ───────────────────────────────────────────────────────────────────
+// --- chat ---
 function canSend() {
   return !!state.selectedAgent && agentAvailable(state.selectedAgent) && !state.chat.busy;
 }
@@ -389,12 +432,13 @@ function chatMain() {
   // above the thread. The kit holds no agentgui-specific banner logic.
   const banners = [];
   if (state.chat.resumeSid) {
+    // The agent-switched note (if any) lives inside the resume banner rather
+    // than as a separate stacked Alert, so resume context reads as one block.
     banners.push(h('div', { key: 'rb', class: 'resume-banner', role: 'status' },
-      h('span', { key: 'rbtxt', class: 'lede' }, 'resuming session ' + state.chat.resumeSid.slice(0, 8) + '… via --resume'),
+      h('span', { key: 'rbtxt', class: 'lede' },
+        'resuming session ' + state.chat.resumeSid.slice(0, 8) + '… via --resume'
+        + (state.chat.resumeNote ? ' — ' + state.chat.resumeNote : '')),
       Btn({ key: 'rclr', onClick: () => { state.chat.resumeSid = null; state.chat.resumeNote = null; render(); }, children: 'clear' })));
-    if (state.chat.resumeNote) {
-      banners.push(Alert({ key: 'rnote', kind: 'info', title: 'Agent switched', children: state.chat.resumeNote }));
-    }
   }
   if (state.selectedAgent && !agentAvailable(state.selectedAgent)) {
     banners.push(Alert({ key: 'unavail', kind: 'warn', title: agentName + ' is not installed',
@@ -407,9 +451,16 @@ function chatMain() {
         Btn({ key: 'cnyes', danger: true, onClick: newChat, children: 'clear' }),
         Btn({ key: 'cnno', onClick: () => { state.confirmingNewChat = false; render(); }, children: 'cancel' })] }));
   }
-  const lastErr = state.chat.messages.length ? state.chat.messages[state.chat.messages.length - 1].error : null;
+  if (state.cwdError) {
+    banners.push(Alert({ key: 'cwderr', kind: 'warn', title: 'Invalid working directory', children: state.cwdError }));
+  }
+  const lastMsg = state.chat.messages.length ? state.chat.messages[state.chat.messages.length - 1] : null;
+  const lastErr = lastMsg ? lastMsg.error : null;
   if (lastErr && !state.chat.busy) {
-    banners.push(Alert({ key: 'chaterr', kind: 'error', title: 'Stream error', children: lastErr }));
+    banners.push(Alert({ key: 'chaterr', kind: 'error', title: 'Stream error',
+      children: [
+        h('span', { key: 'cetxt' }, lastErr + ' '),
+        Btn({ key: 'cedismiss', onClick: () => { if (lastMsg) { delete lastMsg.error; persistChat(); render(); } }, children: 'dismiss' })] }));
   }
 
   const placeholder = !state.selectedAgent
@@ -426,10 +477,13 @@ function chatMain() {
       selectedAgent: state.selectedAgent,
       models: state.agentModels,
       selectedModel: state.selectedModel,
+      modelsLoading: !!state.modelsLoading,
       messages: state.chat.messages,
       busy: state.chat.busy,
       draft: state.chat.draft,
-      status: state.chat.busy ? 'streaming…' : (state.chat.resumeSid ? 'resume' : 'ready'),
+      status: state.chat.busy
+        ? (state.health.ws === 'reconnecting' ? 'reconnecting…' : 'streaming…')
+        : (state.modelsLoading ? 'loading models…' : (state.chat.resumeSid ? 'resume' : 'ready')),
       agentName,
       placeholder,
       canSend: canSend(),
@@ -451,13 +505,23 @@ function chatMain() {
         if (was !== now) render();
       },
       onSend: (v) => { state.chat.draft = v; sendChat(); },
-      onCwdEdit: () => { state.cwdEditing = true; state.cwdDraft = state.chatCwd || ''; render(); },
+      onCwdEdit: () => { state.cwdEditing = true; state.cwdDraft = state.chatCwd || ''; state.cwdError = null; render(); },
       onCwdSave: () => {
-        state.chatCwd = (state.cwdDraft ?? '').trim();
+        const path = (state.cwdDraft ?? '').trim();
+        // A relative cwd would resolve against the server process dir, not what
+        // the user means — require an absolute path (POSIX /…, UNC \\…, or
+        // Windows drive X:\…). Blank is valid (server default).
+        if (path && !/^([/\\]|[A-Za-z]:[/\\])/.test(path)) {
+          state.cwdError = 'enter an absolute path (e.g. /home/you/proj or C:\\proj) or leave blank';
+          render();
+          return;
+        }
+        state.cwdError = null;
+        state.chatCwd = path;
         if (state.chatCwd) lsSet('agentgui.cwd', state.chatCwd); else lsRemove('agentgui.cwd');
         state.cwdEditing = false; state.cwdDraft = undefined; render();
       },
-      onCwdCancel: () => { state.cwdEditing = false; state.cwdDraft = undefined; render(); },
+      onCwdCancel: () => { state.cwdEditing = false; state.cwdDraft = undefined; state.cwdError = null; render(); },
       onCwdClear: () => { state.chatCwd = ''; lsRemove('agentgui.cwd'); render(); },
       onCwdDraft: (v) => { state.cwdDraft = v; },
     }),
@@ -485,7 +549,12 @@ function newChat() {
   render();
 }
 
-function cancelChat() { state.chat.abort?.abort(); }
+function cancelChat() {
+  // Clear busy immediately so the composer re-enables and the "stop" button
+  // flips back to "new" without waiting for the stream's finally block.
+  state.chat.abort?.abort();
+  if (state.chat.busy) { state.chat.busy = false; render(); }
+}
 
 const CHAT_KEY = 'agentgui.chat';
 function persistChat() {
@@ -548,7 +617,7 @@ async function sendChat() {
   }
 }
 
-// ── history ────────────────────────────────────────────────────────────────
+// --- history ---
 function reconnectAlert() {
   if (!state.live.error) return null;
   return Alert({
@@ -588,7 +657,7 @@ function historyMain() {
     lede,
   });
 
-  const actions = h('div', { key: 'acts', class: 'history-actions' },
+  const actions = h('div', { key: 'acts', class: 'history-actions', role: 'status', 'aria-live': 'polite' },
     Btn({ key: 'resume', primary: true, onClick: () => resumeInChat(sess || { sid: state.selectedSid }), children: 'open in chat' }),
     Btn({ key: 'copy', onClick: copySid, children: copyToast || 'copy sid' }),
   );
@@ -597,7 +666,9 @@ function historyMain() {
     // Distinguish "still loading" from "genuinely empty" so a 0-event session
     // doesn't spin forever.
     const body = state.eventsLoaded
-      ? h('p', { key: 'noev', class: 'lede empty-state', role: 'status' }, 'no events in this session')
+      ? h('div', { key: 'noev', class: 'lede empty-state', role: 'status' },
+          h('span', { key: 'noevtxt' }, 'no events in this session — '),
+          Btn({ key: 'reload', onClick: () => loadSession(state.selectedSid), children: 'reload' }))
       : h('div', { key: 'loading', class: 'lede empty-state', role: 'status', 'aria-live': 'polite' }, Spinner({ key: 'spin', size: 'sm' }), 'loading events…');
     return [reconnectAlert(), head, actions, Panel({ title: 'events', children: body })].filter(Boolean);
   }
@@ -611,13 +682,17 @@ function historyMain() {
     head,
     actions,
     Panel({
-      title: total + ' events' + (hiddenCount > 0 ? ' (showing last 300)' : ''),
+      title: total + ' events' + (hiddenCount > 0 ? ' (showing last 300; ' + hiddenCount + ' older not rendered)' : ''),
       children: EventList({
         items: shown.map((e, i) => {
           // Stable key: prefer the server-assigned event index, else the
           // event timestamp + position, never a bare array index (which
           // collides between loaded and live-pushed events).
-          const key = e.i != null ? 'ev' + e.i : 'ev-' + (e.ts || 0) + '-' + (total - shown.length + i);
+          // Stable key: server event index when present, else ts + the event's
+          // ABSOLUTE position in state.events (not the sliced-view index, which
+          // shifts when live events append and would collide loaded vs live rows).
+          const absIdx = total - shown.length + i;
+          const key = e.i != null ? 'ev' + e.i : 'ev-' + (e.ts || 0) + '-' + (e.type || '') + '-' + absIdx;
           const role = e.role || '?';
           const type = e.type || '?';
           const tool = e.tool ? ' · tool: ' + e.tool : '';
@@ -628,9 +703,12 @@ function historyMain() {
           const full = e.toolInput ? (text + '\n\n' + JSON.stringify(e.toolInput, null, 2)) : raw;
           return {
             key,
-            code: String(total - shown.length + i + 1).padStart(4, '0'),
+            code: String(absIdx + 1).padStart(4, '0'),
             title: expanded ? (full || '(' + type + ')') : (text.slice(0, 220) || '(' + type + ')'),
-            sub: new Date(e.ts).toLocaleString() + ' · ' + role + ' · ' + type + tool + errMark + (raw.length > 220 ? ' · ' + (expanded ? 'click to collapse' : 'click to expand') : ''),
+            // Guard ts: a missing/zero timestamp renders "Invalid Date" otherwise.
+            // Every row is click-to-expand, so always show the affordance word
+            // (not only when text overflows 220 chars).
+            sub: (e.ts ? new Date(e.ts).toLocaleString() : 'no time') + ' · ' + role + ' · ' + type + tool + errMark + ' · ' + (expanded ? 'collapse' : 'expand'),
             onClick: () => { expanded ? state.expandedEvents.delete(key) : state.expandedEvents.add(key); render(); },
           };
         }),
@@ -640,20 +718,22 @@ function historyMain() {
 }
 
 let copyToast = null;
+// Hold the toast long enough to read (2.5s); the copy button label is inside a
+// role=status region (history-actions) so AT announces the change.
+function setCopyToast(msg) { copyToast = msg; render(); setTimeout(() => { copyToast = null; render(); }, 2500); }
 function copySid() {
   const sid = state.selectedSid;
   if (!sid) return;
-  const done = () => { copyToast = 'copied'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); };
   if (navigator.clipboard?.writeText) {
-    navigator.clipboard.writeText(sid).then(done).catch(() => { copyToast = 'copy failed'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); });
+    navigator.clipboard.writeText(sid).then(() => setCopyToast('copied')).catch(() => setCopyToast('copy failed'));
   } else {
     // Fallback for insecure (http) origins where navigator.clipboard is absent.
     try {
       const ta = document.createElement('textarea');
       ta.value = sid; ta.style.position = 'fixed'; ta.style.opacity = '0';
       document.body.appendChild(ta); ta.select(); document.execCommand('copy'); ta.remove();
-      done();
-    } catch { copyToast = 'copy failed'; render(); setTimeout(() => { copyToast = null; render(); }, 1500); }
+      setCopyToast('copied');
+    } catch { setCopyToast('copy failed'); }
   }
 }
 
@@ -713,11 +793,14 @@ function historySide() {
   const rows = searching
     ? visible.map((r, i) =>
         Row({
-          key: 'sr' + i,
+          // sid can repeat across hits, so key on sid+position; rank is the
+          // absolute result position (stable across the 60-row slice).
+          key: 'sr-' + (r.sid || '?') + '-' + i,
           rank: String(i + 1).padStart(3, '0'),
           title: r.snippet || '(no snippet)',
           sub: (r.project || '?') + ' · ' + (r.role || '?') + (r.tool ? ' · ' + r.tool : ''),
-          rail: 'purple',
+          // Rail carries the same semantics as session rows: error > subagent > normal.
+          rail: r.isError ? 'flame' : (r.isSubagent ? 'purple' : 'green'),
           onClick: () => loadSession(r.sid),
         })
       )
@@ -725,8 +808,10 @@ function historySide() {
         Row({
           key: 'sess' + s.sid,
           rank: String(i + 1).padStart(3, '0'),
-          title: (s.isSubagent ? '- ' : '') + (projectLabel(s.title) || projectLabel(s.project) || s.sid),
-          sub: fmtRelTime(s.last) + ' · ' + (s.events || 0) + ' ev · ' + (s.tools || 0) + ' tools' + (s.errors ? ' · ' + s.errors + ' err' : ''),
+          // Subagent is conveyed by the purple rail, not a "- " text prefix.
+          title: projectLabel(s.title) || projectLabel(s.project) || s.sid,
+          // Always show the error count so 0 reads as "no errors", not "untracked".
+          sub: fmtRelTime(s.last) + ' · ' + (s.events || 0) + ' ev · ' + (s.tools || 0) + ' tools · ' + (s.errors || 0) + ' err',
           rail: s.errors ? 'flame' : (s.isSubagent ? 'purple' : 'green'),
           active: s.sid === state.selectedSid,
           onClick: () => loadSession(s.sid),
@@ -758,8 +843,8 @@ function historySide() {
       children: [
         SearchInput({
           key: 'searchInput',
-          placeholder: 'search sessions…',
-          'aria-label': 'Search sessions by text or project',
+          placeholder: 'search event text…',
+          'aria-label': 'Search event text across sessions',
           value: state.searchQ,
           onInput: (v) => { state.searchQ = v; debouncedSearch(); },
         }),
@@ -787,7 +872,7 @@ function historySide() {
         !searching && subagentCount
           ? h('label', { key: 'subtog', class: 'lede subagent-toggle' },
               h('input', { type: 'checkbox', checked: state.showSubagents, onChange: (e) => { state.showSubagents = e.target.checked; render(); } }),
-              'show subagents (' + subagentCount + ')')
+              'show subagents (' + (state.showSubagents ? subagentCount + ' shown' : subagentCount + ' hidden') + ')')
           : null,
         state.historyError
           ? h('p', { key: 'err', class: 'lede field-error', role: 'alert' }, state.historyError)
@@ -795,12 +880,17 @@ function historySide() {
         !searching && truncatedBy > 0
           ? Btn({ key: 'more', onClick: () => { state.sessionsLimit += 60; render(); }, children: 'show '+Math.min(60, truncatedBy)+' more ('+truncatedBy+' hidden)' })
           : null,
+        // Search is server-capped at 60 hits; there is no deeper page, so tell
+        // the user the result set is truncated rather than silently hiding it.
+        searching && truncatedBy > 0
+          ? h('p', { key: 'searchmore', class: 'lede empty-state' }, 'showing first 60 matches (' + truncatedBy + ' more — refine your search)')
+          : null,
       ],
     }),
   ].filter(Boolean);
 }
 
-// ── settings ───────────────────────────────────────────────────────────────
+// --- settings ---
 function isValidUrl(s) {
   if (!s) return true; // blank = same-origin is valid
   try { new URL(s.startsWith('http') ? s : 'http://' + s); return true; }
@@ -809,6 +899,12 @@ function isValidUrl(s) {
 
 async function saveBackend() {
   if (!isValidUrl(state.backendDraft) || state.backendDraft === state.backend) return;
+  // Switching backend orphans the local chat transcript (it belongs to the old
+  // server's sessions). Confirm once if there's a transcript to lose.
+  if (state.chat.messages.length && !state.confirmingBackend) {
+    state.confirmingBackend = true; render(); return;
+  }
+  state.confirmingBackend = false;
   B.setBackend(state.backendDraft);
   state.backend = state.backendDraft;
   state.health = { status: 'unknown' };
@@ -822,14 +918,15 @@ async function saveBackend() {
 function healthSummary() {
   const hh = state.health || {};
   const ok = hh.status === 'ok';
+  // Each chip carries a title so its meaning isn't left to inference.
   const bits = [];
-  bits.push(hh.status || 'unknown');
-  if (hh.version) bits.push('v' + hh.version);
-  if (typeof hh.agents === 'number') bits.push(hh.agents + ' agents');
-  if (typeof hh.activeExecutions === 'number') bits.push(hh.activeExecutions + ' active');
-  if (hh.db) bits.push('db ' + (hh.db.ok ? 'ok' : 'down'));
-  return h('div', { key: 'hp', class: 'health-summary' + (ok ? ' health-ok' : '') },
-    ...bits.map((b, i) => h('span', { key: 'hb' + i, class: 'health-chip' }, b)));
+  bits.push([hh.status || 'unknown', 'Backend connection status']);
+  if (hh.version) bits.push(['v' + hh.version, 'Server version']);
+  if (typeof hh.agents === 'number') bits.push([hh.agents + ' agents', 'Agents registered on the server']);
+  if (typeof hh.activeExecutions === 'number') bits.push([hh.activeExecutions + ' active', 'Chats currently executing']);
+  if (hh.db) bits.push(['db ' + (hh.db.ok ? 'ok' : 'down'), 'History database status']);
+  return h('div', { key: 'hp', class: 'health-summary' + (ok ? ' health-ok' : ''), role: 'group', 'aria-label': 'Backend health' },
+    ...bits.map(([b, t], i) => h('span', { key: 'hb' + i, class: 'health-chip', title: t }, b)));
 }
 
 function settingsMain() {
@@ -861,6 +958,7 @@ function settingsMain() {
         state.backendStatus === 'connecting' ? h('p', { key: 'bst', class: 'lede', role: 'status' }, 'connecting…') : null,
         state.backendStatus === 'ok' ? h('p', { key: 'bst', class: 'lede', role: 'status' }, 'connected') : null,
         state.backendStatus === 'failed' ? h('p', { key: 'bst', class: 'lede field-error', role: 'alert' }, 'connection failed — check the URL') : null,
+        state.confirmingBackend ? h('p', { key: 'bcw', class: 'lede field-error', role: 'alert' }, 'changing backend discards this browser\'s chat transcript — press save again to confirm') : null,
         healthSummary(),
         Btn({
           key: 'savebtn',
@@ -874,10 +972,40 @@ function settingsMain() {
       ]),
     }),
     agentsPanel(),
+    preferencesPanel(),
     ]),
   ];
 }
 
+function clearLocalData() {
+  if (!state.confirmingClearData) { state.confirmingClearData = true; render(); return; }
+  state.confirmingClearData = false;
+  // Wipe agentgui's own localStorage keys (chat transcript, agent/model/cwd,
+  // backend). Leaves the page reload to re-init from defaults.
+  for (const k of ['agentgui.chat', 'agentgui.agent', 'agentgui.model', 'agentgui.cwd', 'agentgui.backend']) lsRemove(k);
+  state.chat = { messages: [], busy: false, abort: null, draft: '', resumeSid: null };
+  render();
+}
+
+function preferencesPanel() {
+  const hh = state.health || {};
+  return Panel({
+    title: 'preferences',
+    children: [
+      h('div', { key: 'ver', class: 'lede' }, 'server ' + (hh.version ? 'v' + hh.version : 'version unknown') + (window.__SERVER_VERSION ? ' · build ' + window.__SERVER_VERSION : '')),
+      h('div', { key: 'sc', class: 'lede', style: 'margin:.5em 0' },
+        'keyboard: g then c/h/s — switch tabs · n — new chat · / — focus search/composer · ? — toggle hint · Esc — blur field'),
+      state.confirmingClearData
+        ? Alert({ key: 'cld', kind: 'warn', title: 'Clear all local data?',
+            children: [
+              h('span', { key: 'cldtxt' }, 'Removes saved chat, agent/model/cwd, and backend from this browser. This cannot be undone. '),
+              Btn({ key: 'cldyes', danger: true, onClick: clearLocalData, children: 'clear' }),
+              Btn({ key: 'cldno', onClick: () => { state.confirmingClearData = false; render(); }, children: 'cancel' })] })
+        : Btn({ key: 'cldbtn', onClick: clearLocalData, children: 'clear local data' }),
+    ],
+  });
+}
+
 function acpStatusFor(agentId) {
   const acp = Array.isArray(state.health.acp) ? state.health.acp : [];
   return acp.find(a => a.id === agentId) || null;
@@ -891,6 +1019,7 @@ function agentsPanel() {
       ? state.agents.map((a, i) => {
           const acp = acpStatusFor(a.id);
           const avail = a.available !== false;
+          const usable = avail || a.npxInstallable;     // selectable from this row
           const bits = [a.protocol || 'agent'];
           if (!avail) bits.push(a.npxInstallable ? 'runs via npx' : 'not installed');
           if (acp) bits.push(acp.healthy ? 'running·healthy' : (acp.running ? 'running' : 'stopped'));
@@ -899,18 +1028,21 @@ function agentsPanel() {
           return Row({
             key: 'ag' + a.id,
             rank: String(i + 1).padStart(3, '0'),
-            title: a.name + (avail ? '' : ' ·'),
+            title: a.name,
             sub: bits.join(' · '),
             rail: a.id === state.selectedAgent ? 'green' : (avail ? 'purple' : 'flame'),
             active: a.id === state.selectedAgent,
-            onClick: () => { if (avail || a.npxInstallable) { navTo('chat'); selectAgent(a.id); } },
+            // Non-installable agents are genuinely inert: mark them disabled (no
+            // click, no button role) instead of looking clickable but doing nothing.
+            state: usable ? 'default' : 'disabled',
+            onClick: usable ? () => { navTo('chat'); selectAgent(a.id); } : undefined,
           });
         })
       : h('p', { key: 'none', class: 'lede' }, 'no agents loaded'),
   });
 }
 
-// ── data ──────────────────────────────────────────────────────────────────
+// --- data ---
 async function refreshHistory() {
   try {
     state.sessions = await B.listSessions(state.backend);
@@ -950,6 +1082,11 @@ async function loadSession(sid) {
   state.expandedEvents = new Set();   // don't carry expansion to the new session
   writeHash(sid, { push: true });
   render();
+  // Bring the now-active sidebar row into view (deep-link / back-forward may
+  // select a row that's scrolled out of the session list).
+  requestAnimationFrame(() => {
+    document.querySelector('.app-side .row.active')?.scrollIntoView({ block: 'nearest' });
+  });
   try {
     state.events = await B.getSessionEvents(state.backend, sid);
     state.eventsLoaded = true;
@@ -1058,7 +1195,13 @@ window.addEventListener('keydown', (e) => {
   }
   if (e.key === 'g') { gPending = true; setTimeout(() => { gPending = false; }, 1000); return; }
   if (e.key === 'n' && state.tab === 'chat') { e.preventDefault(); newChat(); return; }
-  if (e.key === '/') { e.preventDefault(); state.tab === 'history' ? focusSearch() : focusComposer(); return; }
+  if (e.key === '/') {
+    // / focuses search on history, composer on chat; on settings there is no
+    // such field, so ignore it cleanly rather than focusing nothing.
+    if (state.tab === 'history') { e.preventDefault(); focusSearch(); announce('search focused'); }
+    else if (state.tab === 'chat') { e.preventDefault(); focusComposer(); announce('composer focused'); }
+    return;
+  }
   if (e.key === '?') { state.showShortcuts = !state.showShortcuts; render(); return; }
 });