agentgui 1.0.947 → 1.0.949

package/.claude/workflows/gui-audit.js

@@ -0,0 +1,86 @@
+export const meta = {
+  name: 'gui-audit',
+  description: 'Sweep every agentgui GUI surface for jank, verify findings adversarially, and emit kit-update tasks',
+  whenToUse: 'Run a maximum-effort GUI audit of agentgui: review chat, history, settings, a11y, security, performance, and glyph hygiene across the client (site/app) and the design kit (c:\\dev\\anentrypoint-design). Fans out one reviewer per surface, verifies each finding with an independent skeptic, then synthesizes a prioritized punch-list. GUI fixes land in the design kit.',
+  phases: [
+    { title: 'Review', detail: 'one reviewer agent per GUI surface/aspect' },
+    { title: 'Verify', detail: 'independent skeptic confirms each finding is real' },
+    { title: 'Synthesize', detail: 'dedupe + prioritize into a punch-list with kit-vs-app split' },
+  ],
+};
+
+// Every GUI surface and cross-cutting aspect the audit must cover. Each becomes
+// one reviewer agent. Add a row to widen coverage; the fan-out scales with it.
+const SURFACES = [
+  { key: 'chat', prompt: 'Audit the agentgui CHAT surface for jank. Read site/app/js/app.js (chatMain, sendChat, toolPart, applyToolResult), site/app/js/backend.js (streamChat), and the kit AgentChat at c:\\dev\\anentrypoint-design/src/components/agent-chat.js + chat.js. Check: tool_use/tool_result render as structured collapsible cards (not flattened text); markdown/text/tool parts interleave in arrival order; empty state; composer stop button while streaming; thinking/working indicator during silent tool runs; aborted-empty turn pruning; multi-turn resume correctness. Report each issue with file:line, why it is jank, and whether the fix is in the kit or the app.' },
+  { key: 'history', prompt: 'Audit the agentgui HISTORY surface (site/app/js/app.js historyMain, historySide, loadSession, EventList usage). Check: event rendering consistency with chat (same event same way), expand/collapse + keyboard activation, the silent 300-event cap with no load-older, search-result click landing on the matched event, live SSE wiring, session list filtering/subagent toggle. Report each issue with file:line and kit-vs-app.' },
+  { key: 'settings', prompt: 'Audit the agentgui SETTINGS surface (site/app/js/app.js settingsMain, agentsPanel, preferencesPanel, saveBackend). Check: ACP agent start/stop/restart/health controls (read-only today), cwd surfacing + server-side validation, backend URL validation, clear-local-data flow, health summary clarity. Report each issue with file:line and kit-vs-app.' },
+  { key: 'a11y', prompt: 'Audit agentgui ACCESSIBILITY across site/app and the kit. Check: skip-link target reachability/focus, tab order on each tab, agent/model select labels, EventList row role=button keyboard activation + expand announcement, aria-live over/under-announcing, color contrast on the dark theme (WCAG AA 4.5:1 text / 3:1 UI), focus-visible rings, reduced-motion. Report each issue with file:line.' },
+  { key: 'security', prompt: 'Audit agentgui GUI-reachable SECURITY. Read lib/http-handler.js. Check: Access-Control-Allow-Origin:* with Authorization + ?token= cross-origin/leak risk; /api/image arbitrary-file-read (the .. check runs after path.normalize); markdown XSS (kit marked+dompurify) — does DOMPurify actually neutralize script/javascript: URLs in agent output. Report each issue with file:line, severity, and the concrete exploit path.' },
+  { key: 'perf', prompt: 'Audit agentgui GUI PERFORMANCE. Check: per-token render+scroll thrash on the chat stream (should be rAF-coalesced via scheduleStreamRender), history EventList rebuild cost on burst SSE loads (last-300 map per rAF), webjsx keying stability, markdown/Prism cache warmup, resize/relTime tick cost. Report each hotspot with file:line and a concrete fix.' },
+  { key: 'glyph', prompt: 'Sweep EVERY GUI source file (site/app/**, c:\\dev\\anentrypoint-design/src/**, *.css) for decorative tell-tale glyphs: arrows, box-drawing, bullets, status dots, checks, emoji, any non-ASCII decorative symbol. KEEP the typographic set (middot, ellipsis, em/en-dash in prose), SVG line-icons via Icon(), CSS-drawn discs, and intentional ascii-art (AICAT_FACE). Report every decorative glyph found with file:line and its ASCII replacement.' },
+  { key: 'responsive', prompt: 'Audit agentgui RESPONSIVE behavior from site/app/index.html media queries + the kit AppShell. Check: chat controls cluster wrap at 360/640/900px, cwd path overflow, history sidebar drawer (open/close/scrim/select-closes-it), touch-target sizes, settings two-column collapse. Report each issue with the breakpoint and file:line.' },
+  { key: 'consistency', prompt: 'Audit agentgui PREDICTABILITY/CONSISTENCY. Check that the same state reads the same way everywhere: connection/activity status vocabulary across crumb dot, chat status, AgentControls status, settings health, agentsPanel; ellipsis convention (… vs ...); rail tone semantics (green=ok/selected, purple=subagent, flame=error); button labels. Report each divergence with file:line.' },
+];
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  required: ['surface', 'findings'],
+  properties: {
+    surface: { type: 'string' },
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['title', 'where', 'why', 'fixLocation'],
+        properties: {
+          title: { type: 'string' },
+          where: { type: 'string', description: 'file:line' },
+          why: { type: 'string' },
+          fixLocation: { type: 'string', enum: ['kit', 'app', 'server', 'both'] },
+          severity: { type: 'string', enum: ['low', 'medium', 'high'] },
+        },
+      },
+    },
+  },
+};
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['isReal', 'reason'],
+  properties: {
+    isReal: { type: 'boolean' },
+    reason: { type: 'string' },
+    correctedFix: { type: 'string' },
+  },
+};
+
+phase('Review');
+
+// Pipeline: each surface is reviewed, then every finding it produced is
+// independently verified — a surface's findings start verifying the moment that
+// surface's review returns, without waiting for slower surfaces.
+const reviewed = await pipeline(
+  SURFACES,
+  (s) => agent(s.prompt, { label: 'review:' + s.key, phase: 'Review', schema: FINDINGS_SCHEMA }),
+  (review, surface) =>
+    parallel((review.findings || []).map((f) => () =>
+      agent(
+        'Adversarially verify this GUI audit finding. Default to isReal=false if you cannot confirm it from the actual source. Finding: "' + f.title + '" at ' + f.where + ' — ' + f.why,
+        { label: 'verify:' + surface.key, phase: 'Verify', schema: VERDICT_SCHEMA }
+      ).then((v) => ({ ...f, surface: surface.key, verdict: v }))
+    ))
+);
+
+const confirmed = reviewed.flat().filter(Boolean).filter((f) => f.verdict && f.verdict.isReal);
+log(confirmed.length + ' confirmed findings across ' + SURFACES.length + ' surfaces');
+
+phase('Synthesize');
+
+const punchList = await agent(
+  'Synthesize these confirmed agentgui GUI audit findings into a prioritized punch-list. Group by fixLocation (kit vs app vs server), order by severity then user impact, dedupe overlaps, and for each give a one-line concrete remedy. Findings JSON:\n' +
+    JSON.stringify(confirmed, null, 2),
+  { label: 'synthesize', phase: 'Synthesize' }
+);
+
+return { confirmedCount: confirmed.length, confirmed, punchList };

package/AGENTS.md

@@ -6,7 +6,7 @@ One surface. `server.js` serves `site/app/` under `BASE_URL` (default `/gm`) and
 
 When `PASSWORD` env var is set, every HTTP route is gated by `lib/http-handler.js` accepting **Basic auth**, **`Authorization: Bearer <pwd>`**, OR **`?token=<pwd>`** query param (added 2026-05-26 so `EventSource` and direct deep-links work — neither can set headers). WS `/sync` requires `?token=` only. The HTML head script injects `window.__BASE_URL`, `window.__SERVER_VERSION`, and `window.__WS_TOKEN`; `site/app/js/backend.js` reads `__WS_TOKEN` and threads it onto every fetch (Bearer header) / EventSource (qs) / WebSocket (qs).
 
-- `site/app/index.html` — shell + CSS; imports `anentrypoint-design` from `https://unpkg.com/anentrypoint-design@latest` at runtime (always-latest; requires network — the prior offline guarantee is intentionally dropped)
+- `site/app/index.html` — shell + CSS; imports `anentrypoint-design` from the **local vendored copy** `./vendor/anentrypoint-design/247420.{js,css}` (re-vendored 2026-06-04 for a PREDICTABLE shipped UI that does not shift when upstream publishes, and offline operation — the markdown stack marked/dompurify/prismjs still fetches from jsdelivr on first chat render). Update flow: edit the kit at `c:\dev\anentrypoint-design`, `node scripts/build.mjs`, copy `dist/247420.{js,css}` into `site/app/vendor/anentrypoint-design/`, then publish the kit so unpkg stays in sync.
 - `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`
 
@@ -18,6 +18,20 @@ Dependencies:
 - `ccsniff` (>=1.1.0) — exports `createHistoryRouter({projectsDir})` mountable on Express; serves `/v1/history/{sessions,sessions/:sid/events,search,snapshot,reindex,stream}`. Reads `~/.claude/projects` (override via `CLAUDE_PROJECTS_DIR`).
 - `anentrypoint-design` (>=0.0.119) — kit library, single-file ESM from unpkg
 
+## GUI audit pass (2026-06-04) — structured chat, predictable presentation
+
+A maximum-effort GUI sweep landed these, GUI changes in the kit `c:\dev\anentrypoint-design` (built+vendored locally), correctness/security in agentgui:
+
+- **Structured tool cards in chat.** `app.js sendChat` now emits structured parts — `toolPart()` builds `{kind:'tool',name,label,args,status,_id}` and `applyToolResult()` matches a `tool_result` back to its `tool_use` by id (sets `result`+done/error status). The kit `AgentChat` passes structured `{kind,...}` parts straight through to `ChatMessage.renderPart` (only bare strings are wrapped as text), so the kit's collapsible `ToolCallNode` (args/result sections, status icons) renders instead of the old flattened `'-> '+text`. Full args/result live in the card (no 120/160-char truncation).
+- **AgentChat kit additions** (`src/components/agent-chat.js`): empty state (`.agentchat-empty*`, title/sub/`suggestions`+`onSuggestionClick`), composer stop button while streaming (`busy`+`onCancel:onStop` into `ChatComposer`), a `working…` tail (`.agentchat-working`) when a content-bearing turn is still streaming (silent tool runs no longer read as frozen). CSS in `chat.css`.
+- **Streaming render is rAF-coalesced** via `scheduleStreamRender()` (was render+scroll per token).
+- **Multi-turn resume wired end-to-end.** Server `chat.sendMessage` is one-shot (new ephemeral `chat-` id per call); claude's real session id is `parsed.session_id` in the stream. `ws-handlers-util.js onEvent` now broadcasts `streaming_session{claudeSessionId}` once; `backend.js` yields `{type:'session'}`; `app.js` captures it into `state.chat.resumeSid` (claude-code only) + persists, so the next turn `--resume`s.
+- **Skip link works.** Kit `AppShell` `<main id=app-main>` now has `tabindex=-1` so the skip-link moves focus, not just scrolls.
+- **History:** `state.eventsLimit` (default 300, reset per session) + `load N older` control (no more silently-unreachable older events); expand-all/collapse-all; per-event rail tone (green=normal, purple=tool_use, flame=error) matching the GUI-wide rail semantics; search hits carry `{focusEventI,focusEventTs}` so a click scrolls to + flashes (`.event-flash`) the matched event; mobile drawer auto-closes on session select (`loadSession` removes `.side-open` since DS only auto-closes on `<a>` clicks).
+- **Security** (`lib/http-handler.js`): `/api/image` confined to an allowlist root (`CLAUDE_PROJECTS_DIR`, home, `IMAGE_ROOTS`) — was arbitrary-file-read (the `..` check was a no-op after `path.normalize`); CORS no longer advertises `Access-Control-Allow-Origin:*` when `PASSWORD` is set (reflects `CORS_ORIGIN` if set, else same-origin only). Markdown XSS verified inert (DOMPurify strips script/onerror/`javascript:`).
+- **Consistency:** unified ellipsis to `…` (kept set); settings health chip uses connection vocab (`connected/connecting/offline`) matching the crumb dot; running-chats panel now shows on chat tab too (extracted `runningPanel()`); aborted-empty turns pruned from persisted/restored chat; restored transcript reopens under its own agent (`restoredAgent`).
+- **Workflow:** `.claude/workflows/gui-audit.js` — a reusable multi-agent GUI-audit workflow (per-surface reviewers -> adversarial verify -> synthesize, kit-vs-app fixLocation).
+
 ## Orchestration agents
 
 The four flagship agents the GUI drives are **Claude Code, OpenCode, Kilo, and Antigravity (`agy`)**; the agent picker (`site/app/js/app.js`, `PRIMARY_AGENTS`) sorts these first, then other-available, then npx-installable, then not-installed.
@@ -60,13 +74,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.**
-
-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".
-
-Fix: `BUNX_RUNNERS` array iterates `['bun', 'npx']` and tries each in sequence. Error detection regex `isMissingCmdError` matches `/not recognized|ENOENT|command not found|cannot find/i` on both `error.message` and captured stdout+stderr. Only falls through to next runner when the `missing` flag is set.
-
-Pattern: When a binary might not exist on all platforms, use a runner fallback strategy. Always capture and check both error.message and process output streams. Cross-platform error detection requires regex alternation on common message patterns.
+**`lib/tool-spawner.js` iterates `BUNX_RUNNERS=['bun','npx']` and detects missing-command via regex on both error.message and stdout+stderr.** Full detail in rs-learn (recall "agentgui windows tool-spawner bunx fallback").
 
 ## GM Plugin Autonomy Blocker
 
@@ -97,9 +105,7 @@ The function previously returned "Model: X." when agentId was 'claude-code' and
 
 ## WebSocket Sync Endpoint Testing
 
-**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.
+**`/sync` sends `sync_connected`+clientId on connect; legacy handler in `lib/ws-legacy-handlers.js` (ping/subscribe/get_subscriptions/unsubscribe/latency_report) via codec; tests must register the message handler before sending.** Full detail in rs-learn (recall "agentgui websocket /sync testing handler ordering").
 
 ## better-sqlite3 & Node v24 Startup
 
@@ -154,3 +160,15 @@ GUI source keeps typographic product characters — the middot separator `·`, t
 ## 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").
+
+## No decorative glyphs — ASCII-only GUI (2026-06-04)
+
+**The GUI carries no decorative tell-tale glyphs; remaining non-ASCII is the deliberate typographic separator set.** The de-jank sweep removed every tell-tale (status dots `[CHAR]`, arrows, box-drawing dividers, checks) in favor of ASCII words + the CSS-drawn status disc. The middot separator `·` is kept as established product design (it reads as a real meta-separator, used consistently across rows/subs); ellipsis `…` and em/en dashes were converted to `...` / `-` on sight. Verified live on buildesk: `document.body.innerText` matches no decorative-glyph regex (excluding the kept middot) across chat/history/settings. The DS Alert dismiss control renders its own close glyph only on a dismissible alert (intentional DS icon affordance, exempt).
+
+## DS SearchInput accessible name comes from `label`, not `aria-label` (2026-06-04)
+
+**`anentrypoint-design`'s `SearchInput` (internal `De`) sets `aria-label = label || placeholder`; it ignores any `aria-label` prop you pass.** To give the search box a real accessible name, pass `label:` (and a matching `placeholder:` for the visible hint). Passing only `aria-label` leaves AT announcing the placeholder. A post-render `setAttribute` race-loses against the DS re-render, so the prop is the only durable fix.
+
+## DS load moved to unpkg @latest — offline regression, re-vendor follow-up (2026-06-04)
+
+**`index.html` currently loads the DS kit (`247420.css` + `247420.js`) from `https://unpkg.com/anentrypoint-design@latest` at runtime, NOT the local `vendor/` copy.** Commit `947086e` made this deliberate trade ("always-latest" over offline) because the GUI's chat surface now renders via the kit's **load-bearing `AgentChat` component**, which exists in `@latest` (0.0.186) but NOT in the older locally-vendored bundle (`vendor/anentrypoint-design/247420.js`). Consequences: the GUI requires network, the shipped UI shifts when the upstream package publishes, and the local vendoring (gzip-Ha CSS blob, font/CDN-const localization) is bypassed. The separate jsdelivr imports inside the vendored bundle (`si`=marked@15, `ri`=dompurify@3, `_s`=prismjs@1.30.0/components) are therefore moot while on unpkg. **Follow-up to restore offline + predictability:** re-vendor 0.0.186+ locally (it has AgentChat), re-apply the offline localization (recall "DS bundle gzip Ha vendoring") AND rewire its `si`/`ri`/`_s` markdown-stack consts to the local `vendor/cdn/{marked.js,dompurify.js,prismjs/components/}` copies, then point `index.html` back at `./vendor/`. Witnessed live (browser `page.on('request')`): on `@latest` the page fetches `unpkg.com/anentrypoint-design@latest/dist/247420.{css,js}` at load.

package/docs/demo.html

@@ -3,13 +3,13 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>AgentGUI — Live Demo Preview</title>
-  <meta name="description" content="See what AgentGUI looks like on your machine — a non-interactive preview of the Gmail-inspired multi-agent interface.">
+  <title>AgentGUI - Live Demo Preview</title>
+  <meta name="description" content="See what AgentGUI looks like on your machine - a non-interactive preview of the Gmail-inspired multi-agent interface.">
   <link rel="preconnect" href="https://fonts.googleapis.com">
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo+Black&family=JetBrains+Mono:wght@400;500;600&family=Google+Sans:wght@300;400;500;700&display=swap">
   <style>
-    /* ── Page chrome ─────────────────────────────────────── */
+    /* ---- Page chrome ---- */
     :root {
       --paper: #EFE9DD; --ink: #0B0B09; --green: #247420; --green-2: #92CEAC;
       --panel-0: var(--paper); --panel-1: #f6f1e7; --panel-2: #ece5d8; --panel-3: #ddd4c3;
@@ -37,7 +37,7 @@
       -webkit-font-smoothing: antialiased;
     }
 
-    /* ── Page layout ─────────────────────────────────────── */
+    /* ---- Page layout ---- */
     .page { display: flex; flex-direction: column; min-height: 100vh; }
 
     .topbar {
@@ -66,7 +66,7 @@
     .hero p { color: var(--panel-text-2); font-size: 13px; margin: 0 0 8px; }
     .hero .sub { font-size: 12px; color: var(--panel-text-3); }
 
-    /* ── Browser mockup ──────────────────────────────────── */
+    /* ---- Browser mockup ---- */
     .mockup-wrap {
       margin: 0 auto;
       max-width: 1200px;
@@ -112,7 +112,7 @@
       .browser-viewport { background: #202124; }
     }
 
-    /* ── Gmail-skin app shell (inside viewport) ──────────── */
+    /* ---- Gmail-skin app shell (inside viewport) ---- */
     .app-shell {
       display: grid;
       grid-template-columns: 72px 280px 1fr;
@@ -452,7 +452,7 @@
     }
     .send-btn svg { width: 16px; height: 16px; }
 
-    /* ── Below-fold sections ─────────────────────────────── */
+    /* ---- Below-fold sections ---- */
     .features { margin-top: 64px; }
     .features h2 {
       font-family: var(--ff-display); font-size: 24px; text-transform: lowercase;
@@ -484,7 +484,7 @@
     }
     .install-note { font-size: 12px; color: var(--panel-text-3); margin-top: 8px; }
 
-    /* ── Footer ──────────────────────────────────────────── */
+    /* ---- Footer ---- */
     .footer {
       height: 24px; background: var(--panel-accent); color: var(--panel-accent-fg);
       display: flex; align-items: center; padding: 0 14px; gap: 14px;
@@ -503,7 +503,7 @@
 <body>
 <div class="page">
 
-  <!-- ── Top bar ── -->
+  <!-- ---- Top bar ---- -->
   <header class="topbar">
     <span class="brand">247420<span class="slash">/</span>agentgui</span>
     <nav>
@@ -514,7 +514,7 @@
     </nav>
   </header>
 
-  <!-- ── Main content ── -->
+  <!-- ---- Main content ---- -->
   <main class="content">
 
     <section class="hero">
@@ -523,7 +523,7 @@
       <p class="sub">Gmail-inspired layout · Claude Code · real project · real output</p>
     </section>
 
-    <!-- ── Browser mockup ── -->
+    <!-- ---- Browser mockup ---- -->
     <div class="mockup-wrap">
 
       <!-- Browser chrome -->
@@ -661,7 +661,7 @@
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
                     <span class="tool-name">Read</span>
                     <span style="flex:1;font-size:11px;color:#9aa0a6">static/css/main.css</span>
-                    <span class="tool-ok">✓ ok</span>
+                    <span class="tool-ok">[ok] ok</span>
                   </div>
                   <div class="tool-body">read 620 lines · sidebar · main-panel · conversation-item · input-card</div>
                 </div>
@@ -671,7 +671,7 @@
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>
                     <span class="tool-name">Read</span>
                     <span style="flex:1;font-size:11px;color:#9aa0a6">static/css/brand-bible.css</span>
-                    <span class="tool-ok">✓ ok</span>
+                    <span class="tool-ok">[ok] ok</span>
                   </div>
                   <div class="tool-body">read 449 lines · design tokens · panel vars · typography</div>
                 </div>
@@ -681,7 +681,7 @@
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
                     <span class="tool-name">Write</span>
                     <span style="flex:1;font-size:11px;color:#9aa0a6">static/css/gmail-skin.css</span>
-                    <span class="tool-ok">✓ written</span>
+                    <span class="tool-ok">[ok] written</span>
                   </div>
                   <div class="tool-body">363 lines · grid layout · nav-rail · gm-* tokens · pill rows · search bar</div>
                 </div>
@@ -691,7 +691,7 @@
                     <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M11 4H4a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7"/><path d="M18.5 2.5a2.121 2.121 0 0 1 3 3L12 15l-4 1 1-4 9.5-9.5z"/></svg>
                     <span class="tool-name">Edit</span>
                     <span style="flex:1;font-size:11px;color:#9aa0a6">static/index.html</span>
-                    <span class="tool-ok">✓ updated</span>
+                    <span class="tool-ok">[ok] updated</span>
                   </div>
                   <div class="tool-body">added .nav-rail · .header-search-wrap · loaded gmail-skin.css</div>
                 </div>
@@ -703,12 +703,12 @@
                   </div>
                   <div class="msg-body">
                     Done. Here's what changed:<br><br>
-                    • <strong>Three-column grid</strong> — icon nav rail (72px) → conversation list (280px) → main panel<br>
-                    • <strong>Nav rail</strong> with Compose FAB + Chats / Archived / Tools icons, pill hover/active states<br>
-                    • <strong>Header search bar</strong> — prominent pill input spanning the header, syncs to sidebar search<br>
-                    • <strong>Conversation rows</strong> — bold title, muted meta + timestamp, pill hover highlight in Google blue<br>
-                    • <strong>Input card</strong> — rounded corners, elevation shadow, Google-blue send pill<br>
-                    • <strong>Soft borders</strong> — <code>#e0e0e0</code> hairlines + drop shadows instead of brand-bible outlines
+                    - <strong>Three-column grid</strong> - icon nav rail (72px) -> conversation list (280px) -> main panel<br>
+                    - <strong>Nav rail</strong> with Compose FAB + Chats / Archived / Tools icons, pill hover/active states<br>
+                    - <strong>Header search bar</strong> - prominent pill input spanning the header, syncs to sidebar search<br>
+                    - <strong>Conversation rows</strong> - bold title, muted meta + timestamp, pill hover highlight in Google blue<br>
+                    - <strong>Input card</strong> - rounded corners, elevation shadow, Google-blue send pill<br>
+                    - <strong>Soft borders</strong> - <code>#e0e0e0</code> hairlines + drop shadows instead of brand-bible outlines
                   </div>
                   <div class="msg-ts">10:43 AM</div>
                 </div>
@@ -757,7 +757,7 @@
       </div><!-- /viewport -->
     </div><!-- /mockup-wrap -->
 
-    <!-- ── Features section ── -->
+    <!-- ---- Features section ---- -->
     <section class="features">
       <h2>what you get</h2>
       <div class="feat-grid">
@@ -784,7 +784,7 @@
         <div class="feat-card">
           <div class="feat-icon">🔄</div>
           <div class="feat-title">Queue &amp; steer</div>
-          <div class="feat-desc">Queue messages while the agent is running. Steer mid-session with a single click — no need to wait.</div>
+          <div class="feat-desc">Queue messages while the agent is running. Steer mid-session with a single click - no need to wait.</div>
         </div>
         <div class="feat-card">
           <div class="feat-icon">🧩</div>
@@ -794,21 +794,21 @@
       </div>
     </section>
 
-    <!-- ── Install section ── -->
+    <!-- ---- Install section ---- -->
     <section class="install-section">
       <h2>get started</h2>
       <div class="install-cmd">$ npx agentgui</div>
-      <p class="install-note">Requires Node.js 18+. Opens on http://localhost:3000/gm/ — no account, no cloud, runs entirely local.</p>
+      <p class="install-note">Requires Node.js 18+. Opens on http://localhost:3000/gm/ - no account, no cloud, runs entirely local.</p>
     </section>
 
   </main>
 
   <footer class="footer">
     <span>main</span>
-    <span>• agentgui</span>
+    <span>- agentgui</span>
     <span class="spread"></span>
     <a href="https://github.com/AnEntrypoint/agentgui">github</a>
-    <span>• 247420 / mmxxvi</span>
+    <span>- 247420 / mmxxvi</span>
   </footer>
 
 </div>

package/lib/codec.js

@@ -1,4 +1,4 @@
-// agentgui WS wire codec — plain JSON (UTF-8 text frames).
+// agentgui WS wire codec - plain JSON (UTF-8 text frames).
 // Browser-compatible (no msgpackr). encode() returns a string the ws library
 // sends as a text frame; decode() handles both Buffer/Uint8Array (Node) and
 // string (browser) inputs.

package/lib/http-handler.js

@@ -6,7 +6,19 @@ import * as term from './terminal.js';
 
 export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, serveFile, staticDir, messageQueues, getWss, activeExecutions, getACPStatus, discoveredAgents, PKG_VERSION, RATE_LIMIT_MAX, rateLimitMap, routes, PORT }) {
   return async function httpHandler(req, res) {
-    res.setHeader('Access-Control-Allow-Origin', '*');
+    // CORS: when PASSWORD is set the server holds credentials a cross-origin
+    // page must not be able to spend, so we do NOT advertise a wildcard origin
+    // (a wildcard + a leaked Bearer/token would let any site the user visits
+    // drive this server). Reflect an explicitly-allowed origin (CORS_ORIGIN)
+    // when configured, else same-origin only. With no PASSWORD the server is
+    // already open, so the permissive wildcard is harmless and kept for tools.
+    const _corsOrigin = process.env.CORS_ORIGIN;
+    if (_corsOrigin) {
+      res.setHeader('Access-Control-Allow-Origin', _corsOrigin);
+      res.setHeader('Vary', 'Origin');
+    } else if (!process.env.PASSWORD) {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+    } // else: no ACAO header -> browsers block cross-origin reads (same-origin still works)
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
     if (req.method === 'OPTIONS') { res.writeHead(200); res.end(); return; }
@@ -40,7 +52,7 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
       } else if (_auth.startsWith('Bearer ')) {
         _ok = _checkToken(_auth.slice(7));
       }
-      // EventSource and same-origin links can't set headers — accept ?token= as fallback.
+      // EventSource and same-origin links can't set headers - accept ?token= as fallback.
       if (!_ok) {
         try {
           const _qsTok = new URL(req.url, 'http://localhost').searchParams.get('token');
@@ -86,7 +98,7 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
         return;
       }
 
-      // Terminal sessions — gated by the Basic-auth check at the top of this handler.
+      // Terminal sessions - gated by the Basic-auth check at the top of this handler.
       // Never expose these routes without PASSWORD set.
       if (pathOnly === '/api/terminal/sessions' && req.method === 'GET') {
         sendJSON(req, res, 200, term.listSessions()); return;
@@ -124,7 +136,22 @@ export function createHttpHandler({ BASE_URL, expressApp, queries, sendJSON, ser
         const normalizedPath = path.normalize(expandedPath);
         const isWindows = os.platform() === 'win32';
         const isAbsolute = isWindows ? /^[A-Za-z]:[\\\/]/.test(normalizedPath) : normalizedPath.startsWith('/');
-        if (!isAbsolute || normalizedPath.includes('..')) { res.writeHead(403); res.end('Forbidden'); return; }
+        // Confine reads to an allowlist root. Without this the route is an
+        // arbitrary-file-read of any image-extensioned path on the host (the
+        // prior `includes('..')` guard is a no-op after path.normalize resolves
+        // the segments). Allowed roots: the Claude projects dir (history images)
+        // and the user home; override/add via IMAGE_ROOTS (path-separated).
+        const allowRoots = [
+          process.env.CLAUDE_PROJECTS_DIR || path.join(os.homedir(), '.claude', 'projects'),
+          os.homedir(),
+          ...(process.env.IMAGE_ROOTS ? process.env.IMAGE_ROOTS.split(path.delimiter) : []),
+        ].map(r => path.normalize(r));
+        const norm = isWindows ? normalizedPath.toLowerCase() : normalizedPath;
+        const withinAllowed = allowRoots.some(root => {
+          const r = isWindows ? root.toLowerCase() : root;
+          return norm === r || norm.startsWith(r + path.sep);
+        });
+        if (!isAbsolute || !withinAllowed) { res.writeHead(403); res.end('Forbidden'); return; }
         try {
           if (!fs.existsSync(normalizedPath)) { res.writeHead(404); res.end('Not found'); return; }
           const ext = path.extname(normalizedPath).toLowerCase();

package/lib/process-message.js

@@ -29,7 +29,7 @@ export function createProcessMessage({ queries, activeExecutions, rateLimitState
     queries.updateSession(sessionId, { status: 'active' });
     const cwd = conv?.workingDirectory || STARTUP_CWD;
     // Resolve agent before building stateRef so isJsonlBacked can be set correctly.
-    // claude-code (protocol: direct) writes JSONL → JsonlParser owns event broadcasting.
+    // claude-code (protocol: direct) writes JSONL -> JsonlParser owns event broadcasting.
     // All other agents (protocol: acp) rely solely on onEvent for streaming.
     let resolvedAgentId = agentId || 'claude-code';
     const wrapperAgent = discoveredAgents.find(a => a.id === resolvedAgentId && a.protocol === 'cli-wrapper' && a.acpId);

package/lib/stream-event-handler.js

@@ -4,8 +4,8 @@
  * For claude-code (isJsonlBacked=true):
  *   JsonlParser owns all event broadcasting via the JSONL file watcher.
  *   This handler only needs to:
- *     1. Extract session_id → setClaudeSessionId + registerSession
- *     2. Detect inline rate-limit messages → scheduleRetry
+ *     1. Extract session_id -> setClaudeSessionId + registerSession
+ *     2. Detect inline rate-limit messages -> scheduleRetry
  *
  * For ACP agents (isJsonlBacked=false):
  *   No JSONL file is written. This handler broadcasts streaming_start,
@@ -18,7 +18,7 @@ export function createEventHandler({ queries, activeExecutions, broadcastSync, r
     if (entry) entry.lastActivity = Date.now();
 
     // Register session with file watcher as soon as we see the session_id.
-    // This pre-maps claudeSessionId → (convId, dbSessionId) in JsonlParser before
+    // This pre-maps claudeSessionId -> (convId, dbSessionId) in JsonlParser before
     // the 16ms file-watcher debounce fires, preventing duplicate conversation creation.
     if (parsed.session_id) {
       if (!batcherRef.resumeSessionId || batcherRef.resumeSessionId !== parsed.session_id) {

package/lib/terminal.js

@@ -1,6 +1,6 @@
 // WebSocket terminal sessions. Ported from acptoapi 2026-05-21.
 // Auth: callers MUST gate /api/terminal/* + the WS upgrade behind agentgui's
-// PASSWORD Basic-auth check. This module does no auth on its own — never
+// PASSWORD Basic-auth check. This module does no auth on its own - never
 // expose without the gate.
 
 import os from 'os';

package/lib/ws-handlers-util.js

@@ -85,8 +85,17 @@ export function register(router, deps) {
     (async () => {
       let eventCount = 0;
       broadcastSync({ type: 'streaming_start', sessionId, agentId, timestamp: Date.now() });
+      let claudeSessionBroadcast = false;
       const onEvent = (parsed) => {
         eventCount++;
+        // Surface claude's REAL session id (from the stream) once, so the client
+        // can --resume this conversation on its next turn. The ephemeral
+        // 'chat-...' sessionId is not a claude session id and cannot be resumed.
+        if (!claudeSessionBroadcast && parsed?.session_id) {
+          claudeSessionBroadcast = true;
+          ctrl.claudeSessionId = parsed.session_id;
+          broadcastSync({ type: 'streaming_session', sessionId, claudeSessionId: parsed.session_id, agentId, timestamp: Date.now() });
+        }
         if (parsed?.type === 'assistant' && parsed.message?.content) {
           for (const block of parsed.message.content) {
             broadcastSync({ type: 'streaming_progress', sessionId, block, blockRole: 'assistant', seq: eventCount, timestamp: Date.now() });

package/lib/ws-setup.js

@@ -24,7 +24,7 @@ export function createWsSetup(server, { BASE_URL, watch, staticDir, _assetCache,
       hotReloadClients.push(ws);
       ws.on('close', () => { const i = hotReloadClients.indexOf(ws); if (i > -1) hotReloadClients.splice(i, 1); });
     } else if (wsRoute.startsWith('/api/terminal/sessions/')) {
-      // Terminal session WS — auth was already enforced by wss-level PASSWORD
+      // Terminal session WS - auth was already enforced by wss-level PASSWORD
       // check at the top of this connection callback. attach to existing session.
       const m = wsRoute.match(/^\/api\/terminal\/sessions\/([0-9a-f]+)$/);
       if (!m) { ws.close(4400, 'bad-terminal-path'); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.947",
+  "version": "1.0.949",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",
@@ -43,7 +43,7 @@
     "webjsx": "^0.0.73",
     "webtalk": "^1.0.31",
     "ws": "^8.14.2",
-    "xstate": "^5.28.0",
+    "xstate": "^5.32.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/scripts/build-rippleui.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 // One-time build: produces static/vendor/rippleui.css from the rippleui npm package.
-// Buildless at runtime — commit the output so `npm install` is enough to serve.
+// Buildless at runtime - commit the output so `npm install` is enough to serve.
 //
 // Source files (from node_modules/rippleui/dist/css/):
 //   base.css        - Tailwind preflight/reset         (~2KB)
 //   components.css  - RippleUI components (.btn etc.)  (~143KB)
 //   utilities.css   - RippleUI extra utilities         (~0.05KB)
-//   styles.css      - full TW + RippleUI monolith      (~4.7MB) — we only mine token defs
+//   styles.css      - full TW + RippleUI monolith      (~4.7MB) - we only mine token defs
 //
 // Output: static/vendor/rippleui.css containing
 //   1. :root / html.dark token blocks extracted from styles.css (so components.css works)
@@ -47,12 +47,12 @@ while ((m = blockRe.exec(styles))) {
 }
 
 if (tokenBlocks.length === 0) {
-    console.error('Could not find token blocks in styles.css — rippleui shape changed?');
+    console.error('Could not find token blocks in styles.css - rippleui shape changed?');
     process.exit(1);
 }
 
-const header = `/* RippleUI v${readPkgVersion()} — localized for AgentGUI.\n` +
-    ` * Generated by scripts/build-rippleui.mjs — do not edit by hand.\n` +
+const header = `/* RippleUI v${readPkgVersion()} - localized for AgentGUI.\n` +
+    ` * Generated by scripts/build-rippleui.mjs - do not edit by hand.\n` +
     ` * Regenerate: bun run scripts/build-rippleui.mjs\n` +
     ` */\n`;
 

package/scripts/capture-screenshots.mjs

@@ -33,7 +33,7 @@ function pickChrome() {
         // macOS
         '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
         '/Applications/Chromium.app/Contents/MacOS/Chromium',
-        // Windows — program files variants
+        // Windows - program files variants
         'C:/Program Files/Google/Chrome/Application/chrome.exe',
         'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe',
         path.join(home, 'AppData/Local/Google/Chrome/Application/chrome.exe'),
@@ -72,7 +72,7 @@ async function waitForHealthy(url, timeoutMs = 20000) {
 async function main() {
     fs.mkdirSync(OUT, { recursive: true });
     if (!fs.existsSync(FIXTURES)) {
-        console.warn(`[capture] fixture dir does not exist: ${FIXTURES} — using empty data dir`);
+        console.warn(`[capture] fixture dir does not exist: ${FIXTURES} - using empty data dir`);
         fs.mkdirSync(FIXTURES, { recursive: true });
     }
 
@@ -112,7 +112,7 @@ async function main() {
     try {
         await waitForHealthy(`${BASE}/api/health`);
         if (serverExitCode !== null) throw new Error(`Server exited with code ${serverExitCode} before becoming healthy`);
-        console.log('[capture] server healthy — launching browser');
+        console.log('[capture] server healthy - launching browser');
 
         const { default: puppeteer } = await import('puppeteer-core');
         const browser = await puppeteer.launch({

package/scripts/copy-vendor.js

@@ -46,5 +46,5 @@ if (fs.existsSync(webjsxDist)) {
   fs.writeFileSync(dest, iife);
   console.log('[copy-vendor] built webjsx IIFE ->', 'static/lib/webjsx.js', `(${iife.split('\n').length} lines)`);
 } else {
-  console.warn('[copy-vendor] webjsx not found in node_modules — run npm install');
+  console.warn('[copy-vendor] webjsx not found in node_modules - run npm install');
 }