agentgui 1.0.1115 → 1.0.1117

package/AGENTS.md

@@ -8,6 +8,10 @@ ACP lifecycle lives in `lib/acp-sdk-manager.js` alone; no other module spawns or
 
 Same-origin app auth must never use the `Authorization` header when an upstream proxy may own Basic auth — a `Bearer` header overwrites the browser's cached `Authorization: Basic` credentials, and nginx `auth_basic` only accepts `Basic`, so the request is rejected at the proxy before it ever reaches agentgui. Use the **`?token=` query param** (`withToken()`, exactly like the WS / EventSource / image / download URLs) instead — it coexists with upstream Basic auth, and agentgui accepts `?token=` on every HTTP route, plus the `agentgui_token` cookie.
 
+## CRITICAL — no Chrome/Puppeteer/Playwright dependency anywhere in this repo
+
+Never add `puppeteer`/`puppeteer-core`/`playwright`/`playwright-core` as a dependency, and never hand-roll a raw headless-Chrome launch in a script. Live browser verification for this project is done via the gm skill's `browser` verb (direct CDP, no relay), not by this repo owning its own browser-automation dependency. `scripts/capture-screenshots.mjs` (puppeteer-core-driven, dead code — not wired into any CI workflow) was removed for this reason.
+
 ## Standing engineering rules
 
 - **All GUI/design decisions live in the kit (`../design`), none in agentgui.** New surface styling is a kit CSS rule, never an inline `<style>` or `style=` prop in agentgui. A new kit component must be re-exported through `src/components.js`'s barrel to be consumable — adding it to a component file alone leaves it invisible to the built bundle even with 0 lint errors; grep the built dist for the export name before wiring the app against it. New CSS class tokens in the kit must carry a registered family prefix (`ds-`, `app-`, `ws-`, `chat-`, etc. — see `scripts/lint-classes.mjs`'s `PREFIXES`/`FROZEN` lists) or the build's lint-classes check fails; a legacy bare name like `chip` being grandfathered on the FROZEN list does not cover new sub-tokens off it (e.g. a new `chip-remove` class still needs a `ds-` prefix).
@@ -79,7 +83,7 @@ Two runner protocols exist. **Direct** (`lib/claude-runner-direct.js`): claude-c
 
 ## CI / GitHub Actions
 
-**capture-screenshots must run under bun, not node** (gh-pages.yml `--ignore-scripts` leaves `better-sqlite3` uncompiled, so `bun:sqlite`'s fallback also fails under Node — detail in rs-learn). Rule: any CI step that spawns the agentgui server must invoke it with `bun`.
+Any CI step that spawns the agentgui server must invoke it with `bun`, not `node` (`--ignore-scripts` npm installs leave `better-sqlite3` uncompiled, so `bun:sqlite`'s fallback also fails under Node).
 
 ## GM Plugin Autonomy Blocker
 

package/lib/ws-handlers-util.js

@@ -87,6 +87,9 @@ export function register(router, deps) {
       features: a.supportedFeatures || [],
       available: registry.isAvailable(a.id),
       npxInstallable: !!a.npxPackage,
+      // The CLI binary name a manual (non-npx) install would need - lets the
+      // settings panel say what to install instead of just "not installed".
+      cmd: a.command || null,
     }));
     return { agents };
   });
@@ -355,7 +358,11 @@ export function register(router, deps) {
     if (p?.file) args.push('--', assertSafeRelPath(p.file, 'file'));
     try {
       const { stdout } = await execFileP('git', args, { cwd });
-      return { diff: stdout, file: p?.file || null, staged: !!p?.staged };
+      // git prints "Binary files a/x and b/x differ" for binary paths instead
+      // of a unified diff - an empty `diff` string then reads to the client as
+      // "no diff to show" with no explanation. Detect it so the UI can say why.
+      const binary = /^Binary files .* differ$/m.test(stdout);
+      return { diff: stdout, binary, file: p?.file || null, staged: !!p?.staged };
     } catch (e) { err(500, (e.stderr || e.message || 'git diff failed').trim()); }
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.1115",
+  "version": "1.0.1117",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",
@@ -34,13 +34,11 @@
     "fsbrowse": "latest",
     "lru-cache": "^11.2.7",
     "opencode-ai": "^1.2.15",
-    "puppeteer-core": "^24.37.5",
     "webjsx": "^0.0.73",
     "ws": "^8.14.2",
     "xstate": "^5.32.0"
   },
   "devDependencies": {
-    "electron": "^35.0.0",
-    "playwright": "^1.59.1"
+    "electron": "^35.0.0"
   }
 }

package/site/app/js/app.js

@@ -3,7 +3,7 @@ import * as B from './backend.js';
 
 installStyles().catch(() => {});
 
-const { AppShell, WorkspaceShell, WorkspaceRail, Topbar, Crumb, Side, Status, Chat, ChatComposer, AgentChat, ConversationList, SessionDashboard, Row, Panel, PageHeader, TextField, Select, Btn, Icon, IconButton, EventList, Spinner, Alert, FileGrid, FileSkeleton, sortFiles, FileToolbar, RootsPicker, BreadcrumbPath, EmptyState, FileViewer, FilePreviewPane, FilePreviewCode, FilePreviewText, FilePreviewMedia, ThemeToggle, ContextPane, PromptDialog, ConfirmDialog, DropZone, UploadProgress, FilterPills, SessionMeta, BulkBar, Checkbox, ShortcutList, FocusTrap, AgentListSkeleton, flashComposerNote, toast, withBusy, GitStatusPanel, GitDiffView, WorktreeSwitcher, ModelsConfig, PluginsConfig } = C;
+const { AppShell, WorkspaceShell, WorkspaceRail, Topbar, Crumb, Side, Status, Chat, ChatComposer, AgentChat, ConversationList, SessionDashboard, Row, Panel, PageHeader, TextField, Select, Btn, Icon, IconButton, EventList, Spinner, Alert, FileGrid, FileSkeleton, sortFiles, FileToolbar, RootsPicker, BreadcrumbPath, EmptyState, FileViewer, FilePreviewPane, FilePreviewCode, FilePreviewText, FilePreviewMedia, ThemeToggle, ContextPane, PromptDialog, ConfirmDialog, DropZone, UploadProgress, FilterPills, SessionMeta, BulkBar, Checkbox, ShortcutList, FocusTrap, AgentListSkeleton, flashComposerNote, toast, withBusy, GitStatusPanel, GitDiffView, WorktreeSwitcher, Badge, ModelsConfig, PluginsConfig } = C;
 
 // One duration/bytes vocabulary across every surface: prefer the kit's shared
 // formatters (exported alongside the components), fall back to the local
@@ -23,7 +23,12 @@ const state = {
   chatCwd: lsGet('agentgui.cwd') || '',
   chat: { messages: [], busy: false, abort: null, draft: '', resumeSid: null, confirmingEdit: null, totalCost: 0 },
   agentsError: null,
-  agentsLoading: false,
+  // true until the boot loadAgents() call resolves - starting false left a
+  // real window (mount -> boot's first render -> loadAgents() actually
+  // starting) where the picker rendered with an empty options list instead
+  // of the "loading agents…" placeholder, a transient state a toolbar button
+  // could source an undefined label/type from.
+  agentsLoading: true,
   settingsSection: null,
   eventFilter: 'all',         // history event-type filter: all | text | tool | errors
   sessionSearchQ: null,       // the query the selected session was opened from (search-hit highlight)
@@ -44,6 +49,9 @@ const state = {
   eventsLimit: 300,   // how many of the most-recent events to render; grows via "load older"
   files: { path: '', segments: [], entries: [], roots: [], loading: false, error: null, preview: null, sort: 'name', sortDir: 'asc', filter: '' },
   git: { loading: false, error: null, diff: '', commits: [], worktrees: [], files: [], file: '', worktreeBusy: false },
+  // One-time welcome banner naming what each tab is for. Shown until
+  // dismissed once, ever - a returning user has already learned the tabs.
+  showOnboarding: lsGet('agentgui.onboarded') !== '1',
   // Models tab: composed agent/provider availability (models.availability WS
   // handler), fed into the design SDK's ModelsConfig component.
   models: { data: null, loading: false, error: null, selectedProviderId: null },
@@ -177,6 +185,12 @@ function lsGet(k) { try { return localStorage.getItem(k); } catch { return null;
 function lsSet(k, v) { try { localStorage.setItem(k, v); } catch {} }
 function lsRemove(k) { try { localStorage.removeItem(k); } catch {} }
 
+function dismissOnboarding() {
+  state.showOnboarding = false;
+  lsSet('agentgui.onboarded', '1');
+  render();
+}
+
 // 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.
@@ -627,13 +641,19 @@ const SHORTCUTS = [
 
 function view() {
   const ok = state.health.status === 'ok';
-  const liveActive = state.tab === 'history' && state.live.connected && (Date.now() - state.live.lastEventTs < 30000);
-  const dotLabel = state.tab === 'history'
+  // history/live both read the SSE stream, not the REST health poll - a tab
+  // that shows its own "connecting to live stream" widget must agree with the
+  // header badge, since they are the same underlying connection. Showing the
+  // REST-derived "connected" here while the tab's own widget says otherwise
+  // is exactly the mismatch this guards against.
+  const streamTab = state.tab === 'history' || state.tab === 'live';
+  const liveActive = streamTab && state.live.connected && (Date.now() - state.live.lastEventTs < 30000);
+  const dotLabel = streamTab
     ? (state.live.error
         ? 'stream: ' + state.live.error + (state.live.reconnects ? ' · ' + state.live.reconnects + ' reconnects' : '')
         : (liveActive ? 'stream: live · ' + state.live.eventCount : (state.live.connected ? 'stream: live' : 'stream: connecting…')))
     : (ok ? (state.health.ws === 'reconnecting' ? 'connecting…' : 'connected') : 'offline');
-  const dotLive = state.tab === 'history' ? (liveActive || state.live.connected) : ok;
+  const dotLive = streamTab ? (liveActive || state.live.connected) : ok;
   // The status dot is drawn entirely by CSS (.status-dot::before) - a small
   // colored disc, real product design, not a text glyph. State drives its colour
   // via the modifier class; the label carries only words so AT reads "live", and
@@ -659,7 +679,15 @@ function view() {
       ? 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';
+    // A resumed conversation loses the agent picker's own visual weight (it
+    // collapses to two small <select>s once turns exist) - the only other
+    // place the bound agent showed was this same tiny crumb text, easy to
+    // miss. Render it as a real badge on resumed threads so "which agent is
+    // this" reads as a persistent, visible indicator, not header trivia.
+    const chatAgentName = state.selectedAgent ? (agentById(state.selectedAgent)?.name || state.selectedAgent) : null;
+    crumbLeaf = chatAgentName
+      ? (state.chat.resumeSid ? Badge({ children: 'agent: ' + chatAgentName, tone: 'neutral' }) : chatAgentName)
+      : 'no agent';
   } else if (state.tab === 'files') {
     // ONE breadcrumb owner: the in-page BreadcrumbPath is the interactive
     // navigator, so the top crumb names only the tab (mirroring live/settings).
@@ -684,8 +712,13 @@ function view() {
     : 'no agent';
   // The default (same-origin) backend is implementation detail, not status -
   // the footer names a backend only when the user pointed at a custom one.
+  // On history/live, the persistent footer chip must agree with the crumb dot
+  // and the tab's own stream widget - reporting REST-health "connected" here
+  // while the Live tab's widget says "connecting to live stream" indefinitely
+  // is the exact contradiction users can't resolve into a real signal.
+  const footerConnLabel = streamTab ? (dotLive ? 'connected' : 'connecting…') : (ok ? 'connected' : 'offline');
   const status = Status({
-    left: [state.backend || null, ok ? 'connected' : 'offline'].filter(Boolean),
+    left: [state.backend || null, footerConnLabel].filter(Boolean),
     right: [agentLabel, 'press ? for shortcuts'],
   });
 
@@ -698,7 +731,18 @@ function view() {
           h('div', { key: 'sc-body', class: 'ds-alert-body' }, ShortcutList({ shortcuts: SHORTCUTS })),
         ] }))
     : null;
-  const main = h('div', { id: 'agentgui-main', role: 'region', 'aria-label': 'main content', 'data-chat-scroll': '', class: 'agentgui-main agentgui-main-' + state.tab }, [shortcutsHint, ...mainContent()].filter(Boolean));
+  // One-time welcome naming what each tab is for - a brand-new user's only
+  // other guidance is installHint (zero-agents case) or the calm chat empty
+  // state (agents-but-no-conversation case); neither explains History/Files/
+  // Live exist at all. Dismissed once, ever, via localStorage.
+  const onboardingBanner = state.showOnboarding
+    ? Alert({
+        key: 'onboarding', kind: 'info', title: 'Welcome to AgentGUI',
+        onDismiss: dismissOnboarding,
+        children: 'Chat with an agent here. History holds every past conversation, Files browses and edits project directories, Live shows every running session at once, and Settings covers connection, appearance, and keyboard shortcuts.',
+      })
+    : null;
+  const main = h('div', { id: 'agentgui-main', role: 'region', 'aria-label': 'main content', 'data-chat-scroll': '', class: 'agentgui-main agentgui-main-' + state.tab }, [shortcutsHint, onboardingBanner, ...mainContent()].filter(Boolean));
 
   // Claude-Desktop three-column shell: a persistent left rail (workspace nav), an
   // optional sessions column (chat + history share the conversation list), the
@@ -993,8 +1037,9 @@ async function loadGitPanel() {
 async function loadGitDiff(file) {
   state.git.diffLoading = true; state.git.diffError = null; render();
   try {
-    const { diff } = await B.gitDiff(state.backend, { file: file || undefined });
+    const { diff, binary } = await B.gitDiff(state.backend, { file: file || undefined });
     state.git.diff = diff || '(no changes)';
+    state.git.diffBinary = !!binary;
     state.git.file = file || '';
   } catch (e) {
     state.git.diffError = e.message || 'Could not load diff.';
@@ -1054,7 +1099,7 @@ function gitMain() {
       GitStatusPanel({ files: g.files, active: g.file, onFileClick: (f) => loadGitDiff(f.path) }) }),
     Panel({ id: 'git-diff', title: g.file ? ('diff: ' + g.file) : 'diff', children:
       g.diffError ? h('p', { key: 'de', class: 't-meta field-error' }, g.diffError)
-      : GitDiffView({ diff: g.diff || '', filename: g.file }) }),
+      : GitDiffView({ diff: g.diff || '', filename: g.file, binary: !!g.diffBinary }) }),
     Panel({ id: 'git-log', title: 'recent commits', children:
       !g.commits.length ? h('p', { key: 'nc', class: 't-meta' }, g.loading ? 'loading…' : 'no commits')
       : h('ul', { key: 'cl', class: 'git-commit-list' }, g.commits.map(c =>
@@ -1303,7 +1348,9 @@ async function runBulkDelete() {
     state.files.dialog = null;
     restoreFileDialogFocus(d._trigger);
     marked.clear(); state.files._lastMarkIdx = null;
-    announce('deleted ' + okCount + ' ' + (okCount === 1 ? 'entry' : 'entries'));
+    const successMsg = 'deleted ' + okCount + ' ' + (okCount === 1 ? 'entry' : 'entries');
+    announce(successMsg);
+    toast({ message: successMsg, kind: 'success' });
     // Patch the visible list immediately instead of waiting on a second full
     // directory round-trip - the server already confirmed every deletion.
     const gone = new Set(targets.map((e) => e.path || e.name));
@@ -1353,7 +1400,9 @@ async function runBulkMove(destDir) {
     state.files.dialog = null;
     restoreFileDialogFocus(d._trigger);
     marked.clear(); state.files._lastMarkIdx = null;
-    announce('moved ' + okCount + ' ' + (okCount === 1 ? 'entry' : 'entries'));
+    const successMsg = 'moved ' + okCount + ' ' + (okCount === 1 ? 'entry' : 'entries');
+    announce(successMsg);
+    toast({ message: successMsg, kind: 'success' });
     // Moved entries leave the current dir - patch them out immediately rather
     // than waiting on a second full directory round-trip.
     const gone = new Set(targets.map((e) => e.path || e.name));
@@ -1389,8 +1438,11 @@ async function runFileMutation(fn, doneMsg, patch) {
     restoreFileDialogFocus(d._trigger);
     announce(doneMsg);
     // A soft-delete's trashId (if this mutation was a delete) rides the
-    // return value straight to the undo-toast caller.
+    // return value straight to the undo-toast caller - that banner is its own
+    // dedicated real-undo-action UI, not a generic dismiss-only confirmation,
+    // so it stays separate from toast() rather than being replaced by it.
     if (result && result.trashId) offerUndoDelete(result.trashId, doneMsg);
+    else toast({ message: doneMsg, kind: 'success' });
     if (patch) {
       // Patch the visible list immediately, matching the bulk-delete/move
       // pattern, instead of stalling the dialog on a second full round-trip.
@@ -2585,7 +2637,7 @@ function chatMain() {
           state.selectedModel || null,
           {
             label: state.chatCwd ? pathBasename(state.chatCwd) : 'server default',
-            title: 'change working directory',
+            title: state.chatCwd ? 'change working directory' : ('change working directory (default: ' + (state.serverHome?.cwd || '…') + ')'),
             onClick: () => { state.cwdEditing = true; state.cwdDraft = state.chatCwd || ''; state.cwdError = null; render(); requestAnimationFrame(() => { const inp = document.querySelector('.chat-cwd-input, .agentchat-cwd-input'); if (inp) inp.focus(); }); },
           },
           userTurnCount > 0 ? plural(userTurnCount, 'turn') : null,
@@ -2625,6 +2677,7 @@ function chatMain() {
       onArmEdit: (m) => armEditAndResend(m),
       onEditMessage: (m) => armEditAndResend(m),
       cwd: state.chatCwd,
+      defaultCwd: state.serverHome?.cwd || null,
       cwdEditing: !!state.cwdEditing,
       cwdDraft: state.cwdDraft,
       cwdError: state.cwdError || null,
@@ -3619,18 +3672,51 @@ function resumeInChat(sess, { fromHash = false } = {}) {
     B.getSessionEvents(state.backend, sidToLoad).then(evs => {
       // Only populate if still on the same resume (user may have switched).
       if (state.chat.resumeSid !== sidToLoad || state.chat.messages.length) return;
+      // Replay the FULL event history (not a fixed-size slice of raw events -
+      // a slice taken before filtering to human/assistant turns can leave only
+      // a couple of visible messages on a long thread). The kit's own
+      // shownMessages/onShowEarlier windowing (wired above) handles the
+      // "load earlier" pagination the same way History's eventsLimit does.
       const msgs = [];
-      for (const e of (evs || []).slice(-50)) {
+      let cur = null; // the in-progress assistant message, so interleaved
+                       // tool_use/tool_result/text events land on one bubble
+                       // instead of one bubble per event.
+      let totalCost = 0; // ccsniff's stored 'result' events already carry the
+                          // real total_cost_usd (as e.cost) - the live path
+                          // sums these as they stream in, but a resumed
+                          // historical session never re-derived it, leaving
+                          // totalCost stuck at 0 regardless of turn/tool count.
+      for (const e of (evs || [])) {
         if (e.type === 'human' || e.role === 'user') {
+          cur = null;
           const text = e.text || e.content || '';
           if (text) msgs.push({ id: 'rh' + e.ts, role: 'user', content: text, time: e.ts, historical: true });
+        } else if (e.type === 'tool_use') {
+          if (!cur) { cur = { id: 'ra' + e.ts, role: 'assistant', content: '', time: e.ts, parts: [], historical: true }; msgs.push(cur); }
+          cur.parts.push(toolPart({ name: e.tool, input: e.toolInput, id: e.toolUseId || e.id }));
+        } else if (e.type === 'tool_result') {
+          if (!cur) { cur = { id: 'ra' + e.ts, role: 'assistant', content: '', time: e.ts, parts: [], historical: true }; msgs.push(cur); }
+          applyToolResult(cur.parts, { tool_use_id: e.toolUseId || e.id, content: e.text, is_error: e.isError });
+        } else if (e.type === 'result') {
+          if (typeof e.cost === 'number') totalCost += e.cost;
         } else if (e.type === 'assistant' || e.role === 'assistant') {
           const text = e.text || '';
-          if (text) msgs.push({ id: 'ra' + e.ts, role: 'assistant', content: '', time: e.ts, parts: [{ kind: 'md', text }], historical: true });
+          if (!text) continue;
+          if (!cur) { cur = { id: 'ra' + e.ts, role: 'assistant', content: '', time: e.ts, parts: [], historical: true }; msgs.push(cur); }
+          appendText(cur.parts, text);
         }
       }
       if (state.chat.resumeSid === sidToLoad && !state.chat.messages.length) {
+        // Attach the summed cost to the last message's costUsd (rather than a
+        // side-channel field) so computeTotalCost() - which every subsequent
+        // send/discard recomputes from message.costUsd - naturally includes
+        // it instead of silently resetting it back to 0 on the next turn.
+        if (totalCost > 0) {
+          const last = msgs[msgs.length - 1];
+          if (last) last.costUsd = (last.costUsd || 0) + totalCost;
+        }
         state.chat.messages = msgs;
+        state.chat.totalCost = computeTotalCost();
       }
     }).catch(() => {}) // history may not be available; silent fail
     .finally(() => {
@@ -3888,9 +3974,9 @@ function settingsMain() {
             render();
           },
         }),
-        state.backendStatus === 'connecting' ? h('p', { key: 'bst-connecting', class: 't-meta', role: 'status' }, 'connecting…') : null,
-        state.backendStatus === 'ok' ? h('p', { key: 'bst-ok', class: 't-meta', role: 'status' }, 'connected') : null,
-        state.backendStatus === 'failed' ? h('p', { key: 'bst-failed', class: 't-meta field-error', role: 'alert' }, 'connection failed - check the URL') : null,
+        state.backendStatus === 'connecting' ? h('span', { key: 'bst-connecting', class: 'ds-status-chip', role: 'status' }, 'connecting…') : null,
+        state.backendStatus === 'ok' ? h('span', { key: 'bst-ok', class: 'ds-status-chip ds-status-chip-ok', role: 'status' }, 'connected') : null,
+        state.backendStatus === 'failed' ? h('span', { key: 'bst-failed', class: 'ds-status-chip ds-status-chip-error', role: 'alert' }, 'connection failed - check the URL') : null,
         (state.confirmingBackend !== undefined && state.confirmingBackend === state.backendDraft && isValid && state.backendDraft !== state.backend)
           ? h('p', { key: 'bcw', class: 't-meta field-error', role: 'alert' }, 'changing backend discards this browser\'s chat transcript - press save again to confirm') : null,
         healthSummary(),
@@ -4067,6 +4153,15 @@ function agentsPanel() {
   const title = (state.agentsLoading && !state.agents.length)
     ? 'agents · loading…'
     : 'agents · ' + installed.length + '/' + state.agents.length + ' installed';
+  // A 16-agent list with only ~4 installed is dominated by disabled-looking
+  // rows; default to hiding not-installed/non-npx-installable agents so the
+  // list reads as "what can I use" rather than a wall of grey entries. The
+  // toggle stays visible (and the count in its label) so nothing is hidden
+  // silently.
+  const hiddenCount = state.agents.filter(a => a.available === false && !a.npxInstallable).length;
+  const visibleAgents = state.hideUnavailableAgents
+    ? state.agents.filter(a => a.available !== false || a.npxInstallable)
+    : state.agents;
   return Panel({
     id: 'agents',
     title,
@@ -4076,14 +4171,22 @@ function agentsPanel() {
     // manual start/stop controls by design. This note makes that explicit so
     // a 'stopped' row doesn't read as a missing action.
     hasAcp ? h('p', { key: 'acpnote', class: 't-meta agentgui-field-mb' }, 'ACP agents start on demand and restart automatically; selecting one launches it.') : null,
-    h('div', { key: 'agrefreshrow', class: 'agentgui-field-mb' }, Btn({ key: 'agrefresh', onClick: () => loadAgents(), disabled: state.agentsLoading, children: state.agentsLoading ? 'refreshing…' : 'refresh' })),
-    ...(state.agents.length
-      ? state.agents.map((a, i) => {
+    h('div', { key: 'agrefreshrow', class: 'agentgui-field-mb' }, [
+      Btn({ key: 'agrefresh', onClick: () => loadAgents(), disabled: state.agentsLoading, children: state.agentsLoading ? 'refreshing…' : 'refresh' }),
+      hiddenCount > 0 ? Checkbox({
+        key: 'aghidetoggle',
+        checked: !!state.hideUnavailableAgents,
+        label: 'hide unavailable (' + hiddenCount + ')',
+        onChange: (v) => { state.hideUnavailableAgents = v; render(); },
+      }) : null,
+    ].filter(Boolean)),
+    ...(visibleAgents.length
+      ? visibleAgents.map((a, i) => {
           const acp = acpStatusFor(a.id);
           const avail = a.available !== false;
           const usable = avail || a.npxInstallable;     // selectable from this row
           const bits = [PROTOCOL_WORDS[a.protocol] || 'agent'];
-          if (!avail) bits.push(a.npxInstallable ? 'installs automatically when used' : 'not installed');
+          if (!avail) bits.push(a.npxInstallable ? 'installs automatically when used (via npx)' : ('not installed' + (a.cmd ? ' - install the "' + a.cmd + '" CLI to enable' : '')));
           if (acp) bits.push(acp.healthy ? 'connected' : (acp.running ? 'connecting' : 'offline'));
           if (acp && acp.restartCount >= 1) bits.push('restarted ' + acp.restartCount + (acp.restartCount === 1 ? ' time' : ' times'));
           if (acp && !acp.healthy && acp.providerInfo?.error) {
@@ -4100,9 +4203,13 @@ function agentsPanel() {
             // Rail tone keeps its GUI-wide meaning: green=ok/selected,
             // flame=error/unavailable. Selection is shown via `active`, not by
             // borrowing purple (purple is reserved for subagents).
-            // Flame also covers ACP agents that are installed but running-unhealthy
-            // (provider auth error, etc.) so the error state is visually distinct.
-            rail: (!avail || (acp && !acp.healthy)) ? 'flame' : (a.id === state.selectedAgent ? 'green' : undefined),
+            // flame is a REAL error signal (Row's shared rail renders it as an
+            // sr-only "error" a11y label) - "not installed" is the normal,
+            // expected state for most of the 16-agent list and must not carry
+            // that label. Only an ACP agent that is actually running-unhealthy
+            // (started, but connection/auth failed) is a genuine error; a
+            // merely-absent binary with no restart in flight is not.
+            rail: (acp && !acp.healthy) ? 'flame' : (a.id === state.selectedAgent ? 'green' : undefined),
             active: a.id === state.selectedAgent,
             // Non-installable agents are genuinely inert: mark them disabled (no
             // click, no button role) instead of looking clickable but doing nothing.
@@ -4117,15 +4224,20 @@ function agentsPanel() {
               : (!avail ? [Btn({ key: 'agrecheck', onClick: (e) => { e.stopPropagation(); withBusy(e.currentTarget, () => loadAgents(), 'checking…'); }, children: 're-check' })] : undefined),
           });
         })
-      // The empty array means one of three things; never let an in-flight load
-      // read as a broken registry.
+      // The empty array means one of several things; never let an in-flight
+      // load read as a broken registry, and never let the hide-unavailable
+      // filter read as "no agents" either.
       : [state.agentsLoading
           ? AgentListSkeleton({ rows: 5 })
           : (state.agentsError
               ? h('div', { key: 'agfail', class: 't-meta empty-state' },
                   h('span', { key: 'agfailtxt' }, 'the agent list failed to load'),
                   Btn({ key: 'agretry2', onClick: (e) => withBusy(e.currentTarget, () => loadAgents(), 'retrying…'), children: 'retry' }))
-              : h('p', { key: 'none', class: 't-meta' }, 'no agents loaded'))]),
+              : (state.agents.length
+                  ? h('div', { key: 'agallhidden', class: 't-meta empty-state' },
+                      h('span', { key: 'agallhiddentxt' }, 'all agents are hidden by the unavailable filter'),
+                      Btn({ key: 'agshowall', onClick: () => { state.hideUnavailableAgents = false; render(); }, children: 'show all' }))
+                  : h('p', { key: 'none', class: 't-meta' }, 'no agents loaded')))]),
     ].filter(Boolean),
   });
 }
@@ -4440,6 +4552,9 @@ async function init() {
   render();
   if (!(await loadAgents())) retryLoadAgents();
   startBuildFreshnessPoll();
+  // Fetch once: lets the cwd "use default" button show what it resolves to
+  // via a tooltip, instead of only revealing it after the click.
+  B.getHome(state.backend).then(h => { state.serverHome = h; render(); }).catch(() => {});
 
   const hp = readHash();
   const bootTab = hp.tab || (hp.sid ? 'history' : 'chat');

package/site/app/js/backend.js

@@ -398,6 +398,13 @@ export async function listAgents(base) {
   return agents || [];
 }
 
+// Server's home/STARTUP_CWD - fetched once so "use default" can show what it
+// actually resolves to (a tooltip) before the user clicks it, instead of only
+// after.
+export async function getHome(base) {
+  return wsCall(base, 'home', {});
+}
+
 export async function listActiveChats(base) {
   try { const { sessions } = await wsCall(base, 'chat.active', {}); return sessions || []; }
   catch { return []; }