From 02dbbf59b14774cd532dfa306f2ff4704df9d075 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:18:22 -0700
Subject: [PATCH 1/7] fix: fold never-dismissing toasts into a corner pill so
 they stop eating clicks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The toast stack is fixed, z-[9999] and pointer-events-auto, so a toast that
never dismisses is a permanent click sink over the page. On this install the
"Install out of sync" notice (duration: Infinity) sat on top of the CoS task
form and silently absorbed every click aimed at Screenshot and Attach — no file
picker, no error, nothing in the console, which is why it read as a broken
button rather than something covering one. Measured in headless Chrome against
the running instance at 1280x720: the notice blocks 520x86px starting at x=744,
and the Attach label occupies x=744-837 — a direct hit. Removing the toast from
the DOM made the same click open the picker.

A duration: Infinity toast now collapses to a 40x40px corner pill after 8s
(1600px^2, clear of the form); clicking the pill restores the full message, and
it stays open while hovered or while focus is inside it. Collapsing hides the
body with an inline display:none rather than unmounting it, so render-prop
toasts that own their own dismiss timer (the agent-feedback card) keep them.

Only unbounded toasts collapse. A finite duration is a bound the caller already
chose and clears itself — folding one early would hide an action meant to stay
offered for its whole life, e.g. the manuscript Undo-fix toast, whose 10s Undo
button is the only undo there is once the source card unmounts.

The pill takes its accessible name from string content; JSX and render-prop
content have no text to take, so those call sites now pass `label`, and
a11yConventions.test.js gains a fourth rule that fails the suite if a new one
forgets — the same shape as the existing file-input guards, because nothing at
runtime complains.
---
 .changelog/NEXT.md                         |   1 +
 client/src/a11yConventions.test.js         |  53 +++++++++
 client/src/components/ui/Toast.jsx         | 127 ++++++++++++++++++---
 client/src/components/ui/Toast.test.jsx    | 104 ++++++++++++++++-
 client/src/hooks/useAgentFeedbackToast.jsx |   1 +
 client/src/hooks/useUpdateChecker.jsx      |   6 +-
 client/src/services/staleBuildToast.jsx    |   2 +-
 7 files changed, 270 insertions(+), 24 deletions(-)

diff --git a/.changelog/NEXT.md b/.changelog/NEXT.md
index d76cb8df7e..3fc98a3df8 100644
--- a/.changelog/NEXT.md
+++ b/.changelog/NEXT.md
@@ -23,6 +23,7 @@
 
 ## Fixed
 
+- **The task form's Screenshot and Attach buttons work again — a stuck notification was eating the clicks.** A notice that never goes away (the "Install out of sync" warning, "Update available", "New build available") parks in the bottom-right corner, and on a desktop window it landed on top of the Chief of Staff task form and silently absorbed every click meant for the buttons underneath. They did nothing at all — no file picker, no error, nothing in the browser console — which is why it read as a broken button rather than something covering one, and why the same page still worked on a phone, where the layout puts those buttons elsewhere. On a 1280×720 window the notice covered a 520×86px block starting at the exact pixel the Attach button begins. Notices that never dismiss themselves now fold into a small badge in the corner after 8 seconds (1600px², clear of the page); clicking the badge brings the message back, and it stays open while you hover it or use its buttons. Toasts with a set lifetime — including the manuscript Undo prompt — are untouched.
 - **CoS agent PRs no longer open with TUI startup noise as their description.** A PR that PortOS opened for a Codex/Antigravity/OpenCode agent led with the session's own lifecycle log — `📟 TUI session started: … (codex …)`, `💡 Open the Shell tab…`, `📟 Prompt pasted…` — before getting to what the agent actually did. The PR description now starts at the agent's completion summary and drops PortOS's status lines, along with the trailing `## Branch` / `## PR` section that only repeats what the PR page already shows.
 - **Review Hub success-rate alerts now require recent runs.** Low lifetime rates for task types that have been idle no longer appear as current health anomalies; alerts are shown only after enough runs occur in the rolling 30-day performance window.
 - **Malware scan reports now open inside PortOS.** Scan links from Brain, the Review Hub, and completed CoS agents render the markdown in a mobile-friendly PortOS page instead of navigating a Home Screen install to the raw `.md` API response. Brain Links also has a Scan Reports filter, so clean and caution results are just as discoverable as dangerous findings.
diff --git a/client/src/a11yConventions.test.js b/client/src/a11yConventions.test.js
index e261cbc7b0..c9ba18024d 100644
--- a/client/src/a11yConventions.test.js
+++ b/client/src/a11yConventions.test.js
@@ -20,6 +20,10 @@
  *      picker at all in WebKit-as-installed-PWA — the shape PortOS is opened in
  *      from a second machine over the tailnet. `components/ui/FilePickerButton.jsx`
  *      is the shared widget (sr-only input + native `<label for>` activation).
+ *   4. A `duration: Infinity` toast whose content is JSX or a render prop but
+ *      which passes no `label`. Such a toast collapses to a pill after
+ *      COLLAPSE_AFTER_MS (so it stops covering the page), and the pill has no
+ *      text of its own to name itself with.
  *
  * Scoped to git-tracked `.jsx` under `client/src` so an untracked scratch file
  * can't fail the suite.
@@ -64,6 +68,25 @@ function openingTagAt(src, index, nameLength) {
 
 const lineOf = (src, index) => src.slice(0, index).split('\n').length;
 
+/**
+ * Slice a call's full argument list, `(` through its matching `)`, starting at
+ * the opening paren. Skips over string and template literals so a `)` inside
+ * one can't close the call early.
+ */
+function balancedCallAt(src, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < src.length; i++) {
+    const c = src[i];
+    if (c === '\'' || c === '"' || c === '`') {
+      for (i++; i < src.length && src[i] !== c; i++) if (src[i] === '\\') i++;
+      continue;
+    }
+    if (c === '(') depth++;
+    else if (c === ')' && --depth === 0) return src.slice(openIndex, i + 1);
+  }
+  return null;
+}
+
 describe('a11y conventions', () => {
   // Modal.jsx IS the shared implementation; Drawer and Layout use the same
   // backdrop treatment for a slide-in panel / mobile nav scrim, both of which
@@ -170,6 +193,36 @@ describe('a11y conventions', () => {
     expect(offenders, `Programmatic .click() on a ref — if it targets a file input the picker never opens in WebKit/PWA; use components/ui/FilePickerButton.jsx. If the ref is genuinely NOT a file input (e.g. a synthesized <a download>), add the file to REF_CLICK_ALLOWLIST above with a comment:\n${offenders.join('\n')}`).toEqual([]);
   });
 
+  it('names every never-dismissing toast that cannot name itself', () => {
+    // A `duration: Infinity` toast folds into an icon-only pill after
+    // COLLAPSE_AFTER_MS so it stops covering the page (components/ui/Toast.jsx).
+    // The pill takes its accessible name from string content — but JSX and
+    // render-prop content have no text to take, so without `label` the whole
+    // name is "Show notification" and the notice becomes unidentifiable to a
+    // screen reader for the rest of its (unbounded) life. Nothing at runtime
+    // complains, so this is the only thing that catches it.
+    const offenders = [];
+    for (const file of trackedSourceFiles()) {
+      const src = readFileSync(join(CLIENT_ROOT, file), 'utf8');
+      const re = /\btoast(?:\.\w+)?\s*\(/g;
+      let m;
+      while ((m = re.exec(src))) {
+        const call = balancedCallAt(src, re.lastIndex - 1);
+        if (!call || !/\bduration:\s*Infinity\b/.test(call)) continue;
+        // Only content that demonstrably isn't a string needs `label`: inline
+        // JSX and render props. A literal or a variable is left alone — the
+        // pill reads a string straight off `t.content`.
+        const firstArg = call.slice(1).trimStart();
+        const isJsx = firstArg.startsWith('<');
+        const isRenderProp = /^(\([^)]*\)|\w+)\s*=>/.test(firstArg);
+        if (!isJsx && !isRenderProp) continue;
+        if (/\blabel:/.test(call)) continue;
+        offenders.push(`${file}:${lineOf(src, m.index)}`);
+      }
+    }
+    expect(offenders, `A duration: Infinity toast with JSX/render-prop content must pass \`label\` — it collapses to a pill that has no other accessible name (see COLLAPSE_AFTER_MS in components/ui/Toast.jsx):\n${offenders.join('\n')}`).toEqual([]);
+  });
+
   it('gives every role="switch" an aria-checked state', () => {
     const offenders = [];
     for (const file of trackedJsxFiles()) {
diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index 33a3b50d2e..5a45b15389 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -2,6 +2,11 @@
  * Toast notification system — replaces react-hot-toast
  * Supports: toast(), toast.success(), toast.error(), toast.loading(), toast.dismiss(), <Toaster />
  * Render-prop toasts: toast((t) => <Component t={t} />, opts) — t has { id }
+ *
+ * A `duration: Infinity` toast collapses to a corner pill after
+ * COLLAPSE_AFTER_MS so it stops blocking clicks on the page beneath it. Such a
+ * toast with render-prop content MUST pass `label` — the pill can't name itself
+ * from JSX, and `a11yConventions.test.js` enforces it.
  */
 
 import { useState, useEffect } from 'react';
@@ -17,6 +22,19 @@ function notify() {
 const DEFAULT_DURATION = 4000;
 const DEDUP_WINDOW_MS = 1500;
 
+// How long a `duration: Infinity` toast stays at full size before folding into
+// a corner pill. The stack is `fixed`, `z-[9999]` and `pointer-events-auto`, so
+// a toast that never dismisses is a permanent click sink over the page: an
+// install whose `outOfSync` notice parked in the bottom-right corner covered
+// the CoS task form's Screenshot and Attach buttons, and clicking them did
+// nothing at all — no picker, no error, nothing in the console.
+//
+// Only unbounded toasts collapse. A finite duration is a bound the caller
+// already chose and it clears itself, so folding one early would hide an action
+// the caller meant to keep offering for the whole time (the manuscript
+// Undo-fix toast runs 10s and its Undo button is the only one there is).
+export const COLLAPSE_AFTER_MS = 8000;
+
 // Fingerprint → expiry timestamp. Same content+type within DEDUP_WINDOW_MS is
 // silently dropped so a single user action that flows through multiple error
 // channels (API client toast + socket error:occurred + error:notified) doesn't
@@ -50,7 +68,9 @@ function add(content, opts = {}, type = 'default') {
     }
   }
 
-  const entry = { id, type, content, icon: opts.icon, duration, style: opts.style };
+  // `label` names the toast once it collapses to a pill — required for
+  // render-prop content, whose JSX the pill can't summarise on its own.
+  const entry = { id, type, content, icon: opts.icon, duration, style: opts.style, label: opts.label };
 
   const idx = toasts.findIndex(t => t.id === id);
   toasts = idx !== -1
@@ -114,23 +134,94 @@ export function Toaster({ position = 'bottom-right', toastOptions = {} }) {
       role="region"
       aria-label="Notifications"
     >
-      {items.map(t => {
-        const style = { padding: '12px 16px', borderRadius: '8px', ...toastOptions.style, ...t.style };
-        const iconStr = t.icon ?? (t.type !== 'default' ? TYPE_ICON[t.type] : null);
-        const iconClass = t.type !== 'default' ? TYPE_CLASS[t.type] : '';
-        return (
-          <div
-            key={t.id}
-            style={style}
-            role={t.type === 'error' ? 'alert' : 'status'}
-            className="pointer-events-auto flex items-start gap-2 shadow-lg text-sm max-w-[calc(100vw-2rem)] sm:max-w-[520px] bg-port-card border border-port-border">
-            {iconStr && <span className={`shrink-0 ${iconClass}`} aria-hidden="true">{iconStr}</span>}
-            <div className="flex-1 min-w-0">
-              {typeof t.content === 'function' ? t.content({ id: t.id }) : <span>{t.content}</span>}
-            </div>
-          </div>
-        );
-      })}
+      {items.map(t => (
+        <ToastItem key={t.id} t={t} toastOptions={toastOptions} />
+      ))}
     </div>
   );
 }
+
+function ToastItem({ t, toastOptions }) {
+  const style = { padding: '12px 16px', borderRadius: '8px', ...toastOptions.style, ...t.style };
+  const iconStr = t.icon ?? (t.type !== 'default' ? TYPE_ICON[t.type] : null);
+  const iconClass = t.type !== 'default' ? TYPE_CLASS[t.type] : '';
+  // Only a toast that never dismisses itself can outstay its welcome and start
+  // eating clicks — see COLLAPSE_AFTER_MS.
+  const collapsible = t.duration === Infinity;
+  const [collapsed, setCollapsed] = useState(false);
+  // Held open while the pointer is over the toast or focus is inside it —
+  // collapsing out from under a hover would yank the buttons the user is
+  // reaching for, and collapsing while focus is inside would drop that focus
+  // to <body>.
+  const [held, setHeld] = useState(false);
+
+  useEffect(() => {
+    if (!collapsible || collapsed || held) return undefined;
+    const timer = setTimeout(() => setCollapsed(true), COLLAPSE_AFTER_MS);
+    return () => clearTimeout(timer);
+  }, [collapsible, collapsed, held]);
+
+  // Re-entering `add()` with the same id replaces the entry in place (a
+  // loading→success swap, a coalesced AI-status error picking up another
+  // failure). That toast has something new to say, so unfold it — otherwise the
+  // update lands inside a pill nobody opens. `content`/`type` only change
+  // identity when `add()` actually ran, so this doesn't fire on re-renders.
+  useEffect(() => { setCollapsed(false); }, [t.content, t.type]);
+
+  // Collapsing HIDES the body, it does not unmount it: render-prop toasts own
+  // their lifecycle (useAgentFeedbackToast's card runs its own auto-dismiss),
+  // and unmounting would destroy those timers and strand the pill forever.
+  // `display: none` inline beats the `flex` utility class, and takes the body
+  // out of the a11y tree and out of hit-testing — which is the whole point.
+  //
+  // `collapsible` is re-read during render, not just in the effect, so a
+  // loading→success swap on the same id (Infinity → 4000) unfolds in the same
+  // commit. The reset effect below would get there a paint later, which shows
+  // as a frame of pill over the new message.
+  const isCollapsed = collapsed && collapsible;
+  const bodyStyle = isCollapsed ? { ...style, display: 'none' } : style;
+
+  return (
+    <>
+      {isCollapsed && (
+        // Re-expanding does NOT pin the toast open: the timer restarts, so a tap
+        // on a touch device (where no mouseleave ever arrives) re-collapses on
+        // its own.
+        // No hover handlers here: the timer effect short-circuits on
+        // `collapsed` so `held` couldn't change anything, and the pill unmounts
+        // on click — browsers fire no `mouseleave` on a removed node, so a
+        // mouse click would strand `held` at true and suppress the re-collapse.
+        <button
+          type="button"
+          onClick={() => setCollapsed(false)}
+          aria-label={collapsedLabel(t)}
+          className="pointer-events-auto flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-port-card border border-port-border shadow-lg text-sm"
+        >
+          <span className={iconClass} aria-hidden="true">{iconStr ?? '•'}</span>
+        </button>
+      )}
+      <div
+        style={bodyStyle}
+        role={t.type === 'error' ? 'alert' : 'status'}
+        onMouseEnter={() => setHeld(true)}
+        onMouseLeave={() => setHeld(false)}
+        // onFocus/onBlur bubble in React, so these fire for the toast's buttons too.
+        onFocus={() => setHeld(true)}
+        onBlur={() => setHeld(false)}
+        className="pointer-events-auto flex items-start gap-2 shadow-lg text-sm max-w-[calc(100vw-2rem)] sm:max-w-[520px] bg-port-card border border-port-border">
+        {iconStr && <span className={`shrink-0 ${iconClass}`} aria-hidden="true">{iconStr}</span>}
+        <div className="flex-1 min-w-0">
+          {typeof t.content === 'function' ? t.content({ id: t.id }) : <span>{t.content}</span>}
+        </div>
+      </div>
+    </>
+  );
+}
+
+// Accessible name for the collapsed pill. String content names itself; a
+// render-prop toast has to supply `label` or it collapses to an anonymous badge.
+function collapsedLabel(t) {
+  if (t.label) return `Show notification: ${t.label}`;
+  if (typeof t.content === 'string') return `Show notification: ${t.content}`;
+  return 'Show notification';
+}
diff --git a/client/src/components/ui/Toast.test.jsx b/client/src/components/ui/Toast.test.jsx
index 94f40741dc..f066386e87 100644
--- a/client/src/components/ui/Toast.test.jsx
+++ b/client/src/components/ui/Toast.test.jsx
@@ -1,12 +1,14 @@
-import { describe, it, expect, afterEach, vi } from 'vitest';
-import { render, screen, cleanup, act } from '@testing-library/react';
+import { useEffect } from 'react';
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
+import { render, screen, cleanup, act, fireEvent } from '@testing-library/react';
 
-import { toast, Toaster } from './Toast.jsx';
+import { toast, Toaster, COLLAPSE_AFTER_MS } from './Toast.jsx';
 
 afterEach(() => {
   act(() => toast.dismiss());
   cleanup();
   vi.unstubAllGlobals();
+  vi.useRealTimers();
 });
 
 describe('Toast on an insecure origin', () => {
@@ -61,3 +63,99 @@ describe('Toaster accessibility', () => {
     expect(glyph).toHaveTextContent('✓');
   });
 });
+
+/** Why a never-dismissing toast has to fold away: see COLLAPSE_AFTER_MS. */
+describe('long-lived toasts stop blocking the page', () => {
+  const advance = (ms) => act(() => { vi.advanceTimersByTime(ms); });
+
+  // Every test here measures a timeout, so fake timers are mandatory — a test
+  // that forgot them would silently no-op every `advance()`.
+  beforeEach(() => {
+    vi.useFakeTimers();
+    render(<Toaster />);
+  });
+
+  it('collapses a persistent toast to a pill that no longer covers the page', () => {
+    act(() => { toast('Install out of sync', { duration: Infinity, icon: '⚠️' }); });
+
+    // Still a full-size toast for the first COLLAPSE_AFTER_MS.
+    expect(screen.getByRole('status')).toBeVisible();
+    expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
+
+    advance(COLLAPSE_AFTER_MS);
+
+    // The body is hidden (out of hit-testing and out of the a11y tree) and only
+    // a corner pill remains.
+    expect(screen.queryByRole('status')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Show notification: Install out of sync' })).toBeVisible();
+  });
+
+  it('leaves transient toasts alone — they never live long enough to block anything', () => {
+    act(() => { toast('Saved'); });
+
+    // The default 4s toast is dismissed well before the collapse threshold, so
+    // it must never sprout a pill on its way out.
+    advance(COLLAPSE_AFTER_MS * 2);
+    expect(screen.queryByRole('status')).toBeNull();
+    expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
+  });
+
+  it('re-expands when the pill is clicked, and re-collapses on its own', () => {
+    // Distinct text per test: identical content within DEDUP_WINDOW_MS is
+    // dropped, and the fingerprint map outlives an individual test.
+    act(() => { toast('New build available', { duration: Infinity }); });
+    advance(COLLAPSE_AFTER_MS);
+
+    fireEvent.click(screen.getByRole('button', { name: /show notification/i }));
+    expect(screen.getByRole('status')).toBeVisible();
+
+    // No pinning on expand — a tap on a touch device (no mouseleave ever
+    // arrives) must still fold the toast back away.
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.queryByRole('status')).toBeNull();
+  });
+
+  it('keeps the toast open while focus is inside it', () => {
+    act(() => {
+      toast(() => <button type="button">Reconcile</button>, { duration: Infinity, label: 'Install out of sync' });
+    });
+
+    fireEvent.focus(screen.getByRole('button', { name: 'Reconcile' }));
+    advance(COLLAPSE_AFTER_MS * 2);
+    // Collapsing here would `display: none` the focused button and dump focus
+    // on <body> mid-interaction.
+    expect(screen.getByRole('button', { name: 'Reconcile' })).toBeVisible();
+
+    fireEvent.blur(screen.getByRole('button', { name: 'Reconcile' }));
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Install out of sync' })).toBeVisible();
+  });
+
+  it('unfolds a collapsed toast when it is updated in place', () => {
+    act(() => { toast.loading('Restarting PortOS...', { id: 'restart', duration: Infinity }); });
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: /show notification/i })).toBeVisible();
+
+    // Same id, new content: the swap has something to say, so it must not land
+    // inside a pill nobody thinks to open.
+    act(() => { toast.success('PortOS restarted', { id: 'restart' }); });
+    expect(screen.getByRole('status')).toHaveTextContent('PortOS restarted');
+    expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
+  });
+
+  it('hides rather than unmounts, so a self-dismissing toast keeps its timers', () => {
+    const unmounted = vi.fn();
+    function SelfManaging() {
+      useEffect(() => unmounted, []);
+      return <span>Agent finished</span>;
+    }
+    act(() => { toast(() => <SelfManaging />, { duration: Infinity, label: 'Agent finished' }); });
+
+    advance(COLLAPSE_AFTER_MS);
+
+    // Unmounting the body would destroy the render-prop's own auto-dismiss
+    // timer and strand the pill on screen forever.
+    expect(unmounted).not.toHaveBeenCalled();
+    expect(screen.getByText('Agent finished')).toBeInTheDocument();
+  });
+});
diff --git a/client/src/hooks/useAgentFeedbackToast.jsx b/client/src/hooks/useAgentFeedbackToast.jsx
index aa78866081..412fdf9147 100644
--- a/client/src/hooks/useAgentFeedbackToast.jsx
+++ b/client/src/hooks/useAgentFeedbackToast.jsx
@@ -183,6 +183,7 @@ export function useAgentFeedbackToast() {
         {
           id: toastId,
           duration: Infinity, // Component manages its own auto-dismiss
+          label: 'Agent finished — rate the result',
           style: {
             background: 'rgb(var(--port-card))',
             border: '1px solid rgb(var(--port-border))',
diff --git a/client/src/hooks/useUpdateChecker.jsx b/client/src/hooks/useUpdateChecker.jsx
index 2a32720b60..55fc0cf003 100644
--- a/client/src/hooks/useUpdateChecker.jsx
+++ b/client/src/hooks/useUpdateChecker.jsx
@@ -51,7 +51,8 @@ export function useUpdateChecker() {
         {
           id: TOAST_ID,
           duration: Infinity,
-          icon: '🔄'
+          icon: '🔄',
+          label: `Update available: v${data.latestVersion}`
         }
       );
     };
@@ -85,7 +86,8 @@ export function useUpdateChecker() {
         {
           id: OUT_OF_SYNC_TOAST_ID,
           duration: Infinity,
-          icon: '⚠️'
+          icon: '⚠️',
+          label: 'Install out of sync'
         }
       );
     };
diff --git a/client/src/services/staleBuildToast.jsx b/client/src/services/staleBuildToast.jsx
index 152daf36b8..05e418e520 100644
--- a/client/src/services/staleBuildToast.jsx
+++ b/client/src/services/staleBuildToast.jsx
@@ -17,6 +17,6 @@ export function showStaleBuildToast() {
         Reload
       </button>
     </div>,
-    { id: 'portos-stale-build', duration: Infinity },
+    { id: 'portos-stale-build', duration: Infinity, label: 'New build available' },
   );
 }

From cad9f2d410a16456bea5c889c397adc2d43c0026 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:20:28 -0700
Subject: [PATCH 2/7] docs(toast): correct the a11y-guard header count and
 de-duplicate the pill comment

---
 client/src/a11yConventions.test.js |  4 ++--
 client/src/components/ui/Toast.jsx | 14 +++++++-------
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/client/src/a11yConventions.test.js b/client/src/a11yConventions.test.js
index c9ba18024d..e2c0b25043 100644
--- a/client/src/a11yConventions.test.js
+++ b/client/src/a11yConventions.test.js
@@ -1,8 +1,8 @@
 /**
  * Repo-wide accessibility conventions.
  *
- * These encode the two regressions that keep reappearing across a11y audit
- * passes, so a new component fails the suite instead of shipping the gap:
+ * These encode the regressions that keep reappearing across a11y audit passes,
+ * so a new component fails the suite instead of shipping the gap:
  *
  *   1. A hand-rolled `fixed inset-0 … bg-black/N` overlay instead of the shared
  *      `ui/Modal`, which owns the focus trap, the Esc stack, `role="dialog"`,
diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index 5a45b15389..c9e9ee1df5 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -184,13 +184,13 @@ function ToastItem({ t, toastOptions }) {
   return (
     <>
       {isCollapsed && (
-        // Re-expanding does NOT pin the toast open: the timer restarts, so a tap
-        // on a touch device (where no mouseleave ever arrives) re-collapses on
-        // its own.
-        // No hover handlers here: the timer effect short-circuits on
-        // `collapsed` so `held` couldn't change anything, and the pill unmounts
-        // on click — browsers fire no `mouseleave` on a removed node, so a
-        // mouse click would strand `held` at true and suppress the re-collapse.
+        // The pill deliberately carries no hover handlers: the timer effect
+        // short-circuits on `collapsed` before it reads `held`, so they couldn't
+        // change anything — and the pill unmounts on click, where no
+        // `mouseleave` ever fires, which would strand `held` at true and
+        // suppress the re-collapse below. Re-expanding doesn't pin the toast
+        // open either; the timer just restarts, so a tap on a touch device
+        // folds it away again on its own.
         <button
           type="button"
           onClick={() => setCollapsed(false)}

From 07f239fd3fefdf14d20bee412631a5813b489399 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:26:43 -0700
Subject: [PATCH 3/7] address review (codex): fold the agent-feedback card on
 its own 15s bound, not the 8s default
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The card passes `duration: Infinity` only because it runs its own
AUTO_DISMISS_MS (15s) dismiss timer, so the blanket 8s collapse hid its
rating buttons for the last 7s of a lifetime the caller had in fact
bounded. Re-opening the pill made it worse: that does not restart the
card's inner timer, so a card re-expanded at 10s disappeared 5s later,
potentially mid-click.

Toasts whose bound lives in their content now pass `collapseAfter` to
fold on their own schedule. It is a delay, not an opt-out — the value is
validated so a non-finite one falls back to the default instead of
switching the fold off, because this card clears its dismiss timer once
expanded and an unbounded 480px card in the corner is the widest click
sink of the set.
---
 client/src/components/ui/Toast.jsx         | 28 ++++++++++++++++---
 client/src/components/ui/Toast.test.jsx    | 32 ++++++++++++++++++++++
 client/src/hooks/useAgentFeedbackToast.jsx |  6 ++++
 3 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index c9e9ee1df5..9c71c97346 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -6,7 +6,8 @@
  * A `duration: Infinity` toast collapses to a corner pill after
  * COLLAPSE_AFTER_MS so it stops blocking clicks on the page beneath it. Such a
  * toast with render-prop content MUST pass `label` — the pill can't name itself
- * from JSX, and `a11yConventions.test.js` enforces it.
+ * from JSX, and `a11yConventions.test.js` enforces it. Content that runs its
+ * own dismiss timer passes `collapseAfter` to fold on its schedule instead.
  */
 
 import { useState, useEffect } from 'react';
@@ -33,6 +34,16 @@ const DEDUP_WINDOW_MS = 1500;
 // already chose and it clears itself, so folding one early would hide an action
 // the caller meant to keep offering for the whole time (the manuscript
 // Undo-fix toast runs 10s and its Undo button is the only one there is).
+//
+// A toast whose bound lives INSIDE its content rather than in `duration` passes
+// `collapseAfter` to say so. `useAgentFeedbackToast` is the case: it sets
+// `duration: Infinity` only because the card runs its own 15s dismiss, so the
+// default 8s would fold the rating controls away for the last 7s of a life the
+// caller did bound. Worse, re-opening the pill does NOT restart that inner
+// timer, so a card re-expanded at 10s vanished 5s later, mid-click. Passing the
+// content's own bound lines the two up. It is a delay, never an opt-out: when
+// that card is expanded it clears its dismiss timer and becomes truly
+// unbounded — the widest click sink of the set — so it still has to fold.
 export const COLLAPSE_AFTER_MS = 8000;
 
 // Fingerprint → expiry timestamp. Same content+type within DEDUP_WINDOW_MS is
@@ -70,7 +81,14 @@ function add(content, opts = {}, type = 'default') {
 
   // `label` names the toast once it collapses to a pill — required for
   // render-prop content, whose JSX the pill can't summarise on its own.
-  const entry = { id, type, content, icon: opts.icon, duration, style: opts.style, label: opts.label };
+  // `collapseAfter` is validated, not merely read: a non-finite value (a stray
+  // `Infinity` meaning "never fold") would disable the fold entirely and hand
+  // back the click-eating overlay, so anything but a finite positive number
+  // falls back to the default rather than being honoured.
+  const collapseAfter = Number.isFinite(opts.collapseAfter) && opts.collapseAfter > 0
+    ? opts.collapseAfter
+    : COLLAPSE_AFTER_MS;
+  const entry = { id, type, content, icon: opts.icon, duration, style: opts.style, label: opts.label, collapseAfter };
 
   const idx = toasts.findIndex(t => t.id === id);
   toasts = idx !== -1
@@ -155,11 +173,13 @@ function ToastItem({ t, toastOptions }) {
   // to <body>.
   const [held, setHeld] = useState(false);
 
+  const collapseAfter = t.collapseAfter ?? COLLAPSE_AFTER_MS;
+
   useEffect(() => {
     if (!collapsible || collapsed || held) return undefined;
-    const timer = setTimeout(() => setCollapsed(true), COLLAPSE_AFTER_MS);
+    const timer = setTimeout(() => setCollapsed(true), collapseAfter);
     return () => clearTimeout(timer);
-  }, [collapsible, collapsed, held]);
+  }, [collapsible, collapsed, held, collapseAfter]);
 
   // Re-entering `add()` with the same id replaces the entry in place (a
   // loading→success swap, a coalesced AI-status error picking up another
diff --git a/client/src/components/ui/Toast.test.jsx b/client/src/components/ui/Toast.test.jsx
index f066386e87..1a03b33430 100644
--- a/client/src/components/ui/Toast.test.jsx
+++ b/client/src/components/ui/Toast.test.jsx
@@ -143,6 +143,38 @@ describe('long-lived toasts stop blocking the page', () => {
     expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
   });
 
+  it('folds on the content\'s own schedule when it passes collapseAfter', () => {
+    // The agent-feedback card sets duration: Infinity only because it runs a
+    // 15s dismiss of its own. Folding at the 8s default would hide its rating
+    // buttons for the last 7s of a life the caller did bound.
+    const OWN_BOUND = COLLAPSE_AFTER_MS * 2;
+    act(() => {
+      toast(() => <button type="button">Rate</button>, {
+        duration: Infinity,
+        label: 'Agent finished',
+        collapseAfter: OWN_BOUND,
+      });
+    });
+
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Rate' })).toBeVisible();
+    expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
+
+    // Still folds — a longer delay is not an opt-out. The card clears its own
+    // dismiss timer once expanded, and an unbounded card is the click sink.
+    advance(OWN_BOUND - COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Agent finished' })).toBeVisible();
+  });
+
+  it('ignores a collapseAfter that would switch the fold off entirely', () => {
+    // `Infinity` here would read as "never fold" and hand back the very
+    // click-eating overlay this exists to remove, so it must not be honoured.
+    act(() => { toast('Stuck forever', { duration: Infinity, collapseAfter: Infinity }); });
+
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Stuck forever' })).toBeVisible();
+  });
+
   it('hides rather than unmounts, so a self-dismissing toast keeps its timers', () => {
     const unmounted = vi.fn();
     function SelfManaging() {
diff --git a/client/src/hooks/useAgentFeedbackToast.jsx b/client/src/hooks/useAgentFeedbackToast.jsx
index 412fdf9147..b90a89a3ed 100644
--- a/client/src/hooks/useAgentFeedbackToast.jsx
+++ b/client/src/hooks/useAgentFeedbackToast.jsx
@@ -184,6 +184,12 @@ export function useAgentFeedbackToast() {
           id: toastId,
           duration: Infinity, // Component manages its own auto-dismiss
           label: 'Agent finished — rate the result',
+          // The card's bound lives in AUTO_DISMISS_MS, not in `duration`, so
+          // the toast layer has to be told about it or its shorter default
+          // folds the rating buttons away mid-life. Still folds once the card
+          // is expanded: that clears the dismiss timer above, and an unbounded
+          // 480px card in the corner is exactly what eats clicks.
+          collapseAfter: AUTO_DISMISS_MS,
           style: {
             background: 'rgb(var(--port-card))',
             border: '1px solid rgb(var(--port-border))',

From 9af1539b1a4c5d6acdccb614f43d6192ed836269 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:38:17 -0700
Subject: [PATCH 4/7] address review (codex): hold the toast open on hover and
 focus independently
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both holds shared one `held` flag, so whichever ended last cleared the
other's. Tab to a button inside a persistent toast, then sweep the
pointer over the toast and off again: `mouseleave` released a hold that
focus still owned, and 8s later the collapse applied `display: none` to
the focused button and dropped focus to <body> — precisely the outcome
the hold exists to prevent. The mirror case (focus leaving while the
pointer stays) folded the toast out from under the cursor.

Tracked as two booleans OR'd together. Both interleavings now have
regression tests; both fail against the single-flag version.
---
 client/src/components/ui/Toast.jsx      | 23 +++++++++----
 client/src/components/ui/Toast.test.jsx | 44 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 6 deletions(-)

diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index 9c71c97346..b89b3b9615 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -171,7 +171,16 @@ function ToastItem({ t, toastOptions }) {
   // collapsing out from under a hover would yank the buttons the user is
   // reaching for, and collapsing while focus is inside would drop that focus
   // to <body>.
-  const [held, setHeld] = useState(false);
+  //
+  // Two flags, not one: hover and focus are independent holds, and a single
+  // shared boolean lets whichever ends last clear the other's. Tab to the
+  // toast's button, then sweep the pointer over the toast and off again, and
+  // `mouseleave` would release a hold that focus still owns — 8s later the
+  // still-focused button gets `display: none` and focus lands on <body>, the
+  // exact thing this is here to prevent.
+  const [hovered, setHovered] = useState(false);
+  const [focusWithin, setFocusWithin] = useState(false);
+  const held = hovered || focusWithin;
 
   const collapseAfter = t.collapseAfter ?? COLLAPSE_AFTER_MS;
 
@@ -223,11 +232,13 @@ function ToastItem({ t, toastOptions }) {
       <div
         style={bodyStyle}
         role={t.type === 'error' ? 'alert' : 'status'}
-        onMouseEnter={() => setHeld(true)}
-        onMouseLeave={() => setHeld(false)}
-        // onFocus/onBlur bubble in React, so these fire for the toast's buttons too.
-        onFocus={() => setHeld(true)}
-        onBlur={() => setHeld(false)}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        // onFocus/onBlur bubble in React, so these fire for the toast's buttons
+        // too. Moving between two buttons inside the toast fires blur then
+        // focus; both land in one batch, so the hold never blips false.
+        onFocus={() => setFocusWithin(true)}
+        onBlur={() => setFocusWithin(false)}
         className="pointer-events-auto flex items-start gap-2 shadow-lg text-sm max-w-[calc(100vw-2rem)] sm:max-w-[520px] bg-port-card border border-port-border">
         {iconStr && <span className={`shrink-0 ${iconClass}`} aria-hidden="true">{iconStr}</span>}
         <div className="flex-1 min-w-0">
diff --git a/client/src/components/ui/Toast.test.jsx b/client/src/components/ui/Toast.test.jsx
index 1a03b33430..393e7dd902 100644
--- a/client/src/components/ui/Toast.test.jsx
+++ b/client/src/components/ui/Toast.test.jsx
@@ -143,6 +143,50 @@ describe('long-lived toasts stop blocking the page', () => {
     expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
   });
 
+  it('keeps focus held even after the pointer sweeps over the toast and leaves', () => {
+    // Hover and focus are independent holds. A single shared flag lets the
+    // pointer leaving release a hold that focus still owns, and the collapse
+    // then `display: none`s the very button the keyboard user is sitting on.
+    act(() => {
+      toast(() => <button type="button">Reconcile now</button>, {
+        duration: Infinity,
+        label: 'Install out of sync',
+      });
+    });
+
+    const button = screen.getByRole('button', { name: 'Reconcile now' });
+    const body = screen.getByRole('status');
+
+    fireEvent.focus(button);       // keyboard user tabs in
+    fireEvent.mouseEnter(body);    // pointer drifts across the toast
+    fireEvent.mouseLeave(body);    // and off again — focus is still inside
+
+    advance(COLLAPSE_AFTER_MS * 2);
+    expect(screen.getByRole('button', { name: 'Reconcile now' })).toBeVisible();
+
+    // Once focus actually leaves, nothing is holding it open any more.
+    fireEvent.blur(button);
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Install out of sync' })).toBeVisible();
+  });
+
+  it('keeps hover held even after focus leaves the toast', () => {
+    // The mirror image: focus departing must not release the pointer's hold.
+    act(() => { toast('Update available', { duration: Infinity }); });
+
+    const body = screen.getByRole('status');
+    fireEvent.mouseEnter(body);
+    fireEvent.focus(body);
+    fireEvent.blur(body);
+
+    advance(COLLAPSE_AFTER_MS * 2);
+    expect(screen.getByRole('status')).toBeVisible();
+
+    fireEvent.mouseLeave(body);
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Update available' })).toBeVisible();
+  });
+
   it('folds on the content\'s own schedule when it passes collapseAfter', () => {
     // The agent-feedback card sets duration: Infinity only because it runs a
     // 15s dismiss of its own. Folding at the 8s default would hide its rating

From 24f865cbaa8f1030868071b0c4b1e324adb94dc2 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:41:43 -0700
Subject: [PATCH 5/7] address review (codex): hand focus to the toast when the
 pill is expanded by keyboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Activating the pill unmounts it, so a keyboard user pressing Enter on it
lost focus to <body> — the toast's own Reconcile/Reload/Ignore buttons
left the tab sequence and the next Tab restarted from the top of the
document, past everything on the page.

The revealed body now takes focus (tabIndex={-1}, programmatic only, so
it never sits between the page's own controls). Guarded on the pill
having actually held focus: a pointer activation in an engine that does
not focus buttons on click has nothing to rescue, and grabbing focus
anyway would take the focus hold and pin the toast open until the user
clicked elsewhere — the parked overlay this set out to remove.
---
 client/src/components/ui/Toast.jsx      | 33 +++++++++++++++++++++--
 client/src/components/ui/Toast.test.jsx | 36 +++++++++++++++++++++++++
 2 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index b89b3b9615..7d1ee9f825 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -10,7 +10,7 @@
  * own dismiss timer passes `collapseAfter` to fold on its schedule instead.
  */
 
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useRef } from 'react';
 import { uuidv4 } from '../../lib/uuid.js';
 
 let toasts = [];
@@ -210,6 +210,27 @@ function ToastItem({ t, toastOptions }) {
   const isCollapsed = collapsed && collapsible;
   const bodyStyle = isCollapsed ? { ...style, display: 'none' } : style;
 
+  // Expanding the pill unmounts the pill. If the keyboard had focus on it,
+  // focus falls to <body> and the toast's own Reconcile/Reload/Ignore buttons
+  // drop out of the tab sequence — the next Tab restarts from the top of the
+  // document, past everything. So hand focus to the body it just revealed.
+  //
+  // Only when the pill actually held focus. A pointer activation in an engine
+  // that doesn't focus buttons on click has nothing to rescue, and moving focus
+  // there anyway would take the focus hold and pin the toast open until the
+  // user clicked elsewhere — turning a click of curiosity back into the
+  // parked overlay this all exists to remove.
+  const bodyRef = useRef(null);
+  const refocusOnExpand = useRef(false);
+
+  useEffect(() => {
+    if (isCollapsed || !refocusOnExpand.current) return;
+    refocusOnExpand.current = false;
+    // Runs after commit, so the body is no longer `display: none` and can
+    // actually take focus.
+    bodyRef.current?.focus();
+  }, [isCollapsed]);
+
   return (
     <>
       {isCollapsed && (
@@ -222,7 +243,10 @@ function ToastItem({ t, toastOptions }) {
         // folds it away again on its own.
         <button
           type="button"
-          onClick={() => setCollapsed(false)}
+          onClick={e => {
+            refocusOnExpand.current = e.currentTarget === document.activeElement;
+            setCollapsed(false);
+          }}
           aria-label={collapsedLabel(t)}
           className="pointer-events-auto flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-port-card border border-port-border shadow-lg text-sm"
         >
@@ -230,7 +254,12 @@ function ToastItem({ t, toastOptions }) {
         </button>
       )}
       <div
+        ref={bodyRef}
         style={bodyStyle}
+        // Focusable only programmatically (see the refocus effect); -1 keeps
+        // the body itself out of the tab sequence so it never sits between the
+        // page's own controls.
+        tabIndex={-1}
         role={t.type === 'error' ? 'alert' : 'status'}
         onMouseEnter={() => setHovered(true)}
         onMouseLeave={() => setHovered(false)}
diff --git a/client/src/components/ui/Toast.test.jsx b/client/src/components/ui/Toast.test.jsx
index 393e7dd902..ff805da766 100644
--- a/client/src/components/ui/Toast.test.jsx
+++ b/client/src/components/ui/Toast.test.jsx
@@ -143,6 +143,42 @@ describe('long-lived toasts stop blocking the page', () => {
     expect(screen.queryByRole('button', { name: /show notification/i })).toBeNull();
   });
 
+  it('moves focus into the toast when the pill is expanded from the keyboard', () => {
+    act(() => {
+      toast(() => <button type="button">Reconcile</button>, {
+        duration: Infinity,
+        label: 'Install out of sync',
+      });
+    });
+    advance(COLLAPSE_AFTER_MS);
+
+    // Activating the pill unmounts it. Without a handover focus lands on
+    // <body> and the toast's own buttons leave the tab sequence entirely.
+    const pill = screen.getByRole('button', { name: /show notification/i });
+    pill.focus();
+    fireEvent.click(pill);
+
+    const body = screen.getByRole('status');
+    expect(document.activeElement).toBe(body);
+    expect(document.activeElement).not.toBe(document.body);
+    // ...and the toast stays put while it holds focus.
+    advance(COLLAPSE_AFTER_MS * 2);
+    expect(screen.getByRole('button', { name: 'Reconcile' })).toBeVisible();
+  });
+
+  it('does not steal focus when the pill is expanded by pointer', () => {
+    // Nothing to rescue, and taking focus here would pin the toast open until
+    // the user clicked elsewhere — back to a parked overlay.
+    act(() => { toast('Build is stale', { duration: Infinity }); });
+    advance(COLLAPSE_AFTER_MS);
+
+    fireEvent.click(screen.getByRole('button', { name: /show notification/i }));
+
+    expect(document.activeElement).toBe(document.body);
+    advance(COLLAPSE_AFTER_MS);
+    expect(screen.getByRole('button', { name: 'Show notification: Build is stale' })).toBeVisible();
+  });
+
   it('keeps focus held even after the pointer sweeps over the toast and leaves', () => {
     // Hover and focus are independent holds. A single shared flag lets the
     // pointer leaving release a hold that focus still owns, and the collapse

From 7afe8af89dfd639071e8f178d98ddf62a43d760d Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 16:48:18 -0700
Subject: [PATCH 6/7] fix(toast): detect keyboard pill activation by
 detail===0, not activeElement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The focus-handover guard from the previous commit asked whether the pill was
document.activeElement to decide "was this a keyboard activation?". Chrome
focuses a <button> on mouse-down, so that reads true for an ordinary click:
focus moved into the toast body, the body's onFocus took the focus hold, and
nothing ever released it. Measured via CDP against the running page — after a
real mouse click the toast was still expanded 11s later, with activeElement
parked on the toast. That is the click-eating overlay this branch exists to
remove, handed back to precisely the mouse users who reported it.

detail === 0 is the actual signal: a click synthesized from Enter/Space carries
no click count, a pointer click carries at least 1.

The unit test could not have caught this. jsdom's fireEvent.click neither
focuses the button nor sets detail, so an activeElement guard passes there and
fails in the browser. Both tests now state their gesture explicitly (detail 0
for keyboard, 1 for pointer) and the pointer test models Chrome by focusing the
pill first, so it fails against the old guard. Re-verified in headless Chrome:
Enter hands focus to the toast body; a mouse click leaves focus alone and the
toast folds itself away again.
---
 client/src/components/ui/Toast.jsx      | 18 ++++++++++-----
 client/src/components/ui/Toast.test.jsx | 30 ++++++++++++++++++++-----
 2 files changed, 36 insertions(+), 12 deletions(-)

diff --git a/client/src/components/ui/Toast.jsx b/client/src/components/ui/Toast.jsx
index 7d1ee9f825..d336594473 100644
--- a/client/src/components/ui/Toast.jsx
+++ b/client/src/components/ui/Toast.jsx
@@ -215,11 +215,17 @@ function ToastItem({ t, toastOptions }) {
   // drop out of the tab sequence — the next Tab restarts from the top of the
   // document, past everything. So hand focus to the body it just revealed.
   //
-  // Only when the pill actually held focus. A pointer activation in an engine
-  // that doesn't focus buttons on click has nothing to rescue, and moving focus
-  // there anyway would take the focus hold and pin the toast open until the
-  // user clicked elsewhere — turning a click of curiosity back into the
-  // parked overlay this all exists to remove.
+  // Only for a KEYBOARD activation, detected by `detail === 0` — the click a
+  // browser synthesizes from Enter/Space carries no click count, while a real
+  // pointer click carries at least 1. `document.activeElement === the pill` is
+  // NOT a usable substitute: Chrome focuses a button on mouse-down, so it reads
+  // true for an ordinary click. Measured in headless Chrome against the running
+  // page, that mis-detection moved focus into the body on a plain mouse click,
+  // `onFocus` took the focus hold, and the toast never folded again — the exact
+  // parked overlay this file exists to remove, handed back to the mouse users
+  // who reported it. jsdom hides this: `fireEvent.click` doesn't focus the
+  // button, so an activeElement-based guard passes the unit test and fails the
+  // browser. The tests below therefore pass `detail` explicitly.
   const bodyRef = useRef(null);
   const refocusOnExpand = useRef(false);
 
@@ -244,7 +250,7 @@ function ToastItem({ t, toastOptions }) {
         <button
           type="button"
           onClick={e => {
-            refocusOnExpand.current = e.currentTarget === document.activeElement;
+            refocusOnExpand.current = e.detail === 0;
             setCollapsed(false);
           }}
           aria-label={collapsedLabel(t)}
diff --git a/client/src/components/ui/Toast.test.jsx b/client/src/components/ui/Toast.test.jsx
index ff805da766..b019b371cc 100644
--- a/client/src/components/ui/Toast.test.jsx
+++ b/client/src/components/ui/Toast.test.jsx
@@ -106,7 +106,11 @@ describe('long-lived toasts stop blocking the page', () => {
     act(() => { toast('New build available', { duration: Infinity }); });
     advance(COLLAPSE_AFTER_MS);
 
-    fireEvent.click(screen.getByRole('button', { name: /show notification/i }));
+    // `detail: 1` marks this a pointer/touch activation. Say it explicitly:
+    // jsdom defaults `detail` to 0, which the component reads as a KEYBOARD
+    // activation and answers by taking focus — so a bare `fireEvent.click`
+    // here would silently test the wrong gesture and fail.
+    fireEvent.click(screen.getByRole('button', { name: /show notification/i }), { detail: 1 });
     expect(screen.getByRole('status')).toBeVisible();
 
     // No pinning on expand — a tap on a touch device (no mouseleave ever
@@ -154,9 +158,11 @@ describe('long-lived toasts stop blocking the page', () => {
 
     // Activating the pill unmounts it. Without a handover focus lands on
     // <body> and the toast's own buttons leave the tab sequence entirely.
+    // `detail: 0` is what makes this a KEYBOARD activation — the browser
+    // synthesizes Enter/Space clicks with no click count.
     const pill = screen.getByRole('button', { name: /show notification/i });
     pill.focus();
-    fireEvent.click(pill);
+    fireEvent.click(pill, { detail: 0 });
 
     const body = screen.getByRole('status');
     expect(document.activeElement).toBe(body);
@@ -167,14 +173,26 @@ describe('long-lived toasts stop blocking the page', () => {
   });
 
   it('does not steal focus when the pill is expanded by pointer', () => {
-    // Nothing to rescue, and taking focus here would pin the toast open until
-    // the user clicked elsewhere — back to a parked overlay.
     act(() => { toast('Build is stale', { duration: Infinity }); });
     advance(COLLAPSE_AFTER_MS);
 
-    fireEvent.click(screen.getByRole('button', { name: /show notification/i }));
+    // Model what a real browser does, or this test proves nothing: Chrome
+    // FOCUSES a <button> on mouse-down, so `document.activeElement` is the pill
+    // for an ordinary click too — a guard written against it reads "keyboard"
+    // here and steals focus. jsdom's bare `fireEvent.click` neither focuses the
+    // button nor sets `detail`, which is how an activeElement-based guard
+    // passed this test while parking the toast open forever in Chrome (measured
+    // via CDP against the live page). So focus the pill AND send `detail: 1`.
+    const pill = screen.getByRole('button', { name: /show notification/i });
+    pill.focus();
+    fireEvent.click(pill, { detail: 1 });
+
+    // Focus must NOT have been handed to the body: `onFocus` there takes the
+    // focus hold, and nothing would ever release it.
+    expect(document.activeElement).not.toBe(screen.getByRole('status'));
 
-    expect(document.activeElement).toBe(document.body);
+    // The invariant that actually matters — no expand path may leave the toast
+    // parked. Whatever the activation, it folds itself away again.
     advance(COLLAPSE_AFTER_MS);
     expect(screen.getByRole('button', { name: 'Show notification: Build is stale' })).toBeVisible();
   });

From d4c8e722ac5eb9c9c9e6a0c5ef832cf1feb7dd29 Mon Sep 17 00:00:00 2001
From: "[._.]/ Adam Eivy" <atomantic@gmail.com>
Date: Tue, 28 Jul 2026 17:03:22 -0700
Subject: [PATCH 7/7] address review (ollama): stop the toast-label guard
 skipping JSX with an apostrophe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`balancedCallAt` treats `'` as a string opener, so JSX text like
`<div>You're out of sync</div>` opened a "string" that never closed. The
scan ran past the call's closing paren, returned null, and the caller
skipped it silently — meaning the new `duration: Infinity` label rule
missed exactly the shape it exists to catch: JSX content, which has no
text for the collapsed pill to name itself with.

Falling off the end now retries counting parens only. A well-formed
string still returns on the first (string-skipping) pass, so a `)` inside
a literal can't close the call early.
---
 client/src/a11yConventions.test.js | 27 ++++++++++++++++++++++++---
 1 file changed, 24 insertions(+), 3 deletions(-)

diff --git a/client/src/a11yConventions.test.js b/client/src/a11yConventions.test.js
index e2c0b25043..1e91739a93 100644
--- a/client/src/a11yConventions.test.js
+++ b/client/src/a11yConventions.test.js
@@ -73,18 +73,25 @@ const lineOf = (src, index) => src.slice(0, index).split('\n').length;
  * the opening paren. Skips over string and template literals so a `)` inside
  * one can't close the call early.
  */
-function balancedCallAt(src, openIndex) {
+function balancedCallAt(src, openIndex, skipStrings = true) {
   let depth = 0;
   for (let i = openIndex; i < src.length; i++) {
     const c = src[i];
-    if (c === '\'' || c === '"' || c === '`') {
+    if (skipStrings && (c === '\'' || c === '"' || c === '`')) {
       for (i++; i < src.length && src[i] !== c; i++) if (src[i] === '\\') i++;
       continue;
     }
     if (c === '(') depth++;
     else if (c === ')' && --depth === 0) return src.slice(openIndex, i + 1);
   }
-  return null;
+  // Falling off the end means a quote opened a "string" that never closed —
+  // in practice an apostrophe in JSX text, `toast(<p>You're out of sync</p>,
+  // { duration: Infinity })`. The scan swallows the closing paren, the caller
+  // skips the unparseable call, and the toast rule silently misses the one
+  // shape it exists to catch: JSX content, which is precisely what needs
+  // `label`. Retry counting parens only — a `)` inside a real string could
+  // close early, but a well-formed string already returned on the first pass.
+  return skipStrings ? balancedCallAt(src, openIndex, false) : null;
 }
 
 describe('a11y conventions', () => {
@@ -223,6 +230,20 @@ describe('a11y conventions', () => {
     expect(offenders, `A duration: Infinity toast with JSX/render-prop content must pass \`label\` — it collapses to a pill that has no other accessible name (see COLLAPSE_AFTER_MS in components/ui/Toast.jsx):\n${offenders.join('\n')}`).toEqual([]);
   });
 
+  it('slices toast calls whose JSX text contains an apostrophe', () => {
+    // The rule above is only as good as the slicer. An apostrophe in JSX text
+    // opens a "string" that never closes, so the scan runs past the closing
+    // paren — and a `null` slice is skipped silently, letting the exact shape
+    // the rule targets (JSX content, no `label`) ship unflagged.
+    const jsx = `toast(<div>You're out of sync</div>, { duration: Infinity })`;
+    expect(balancedCallAt(jsx, jsx.indexOf('('))).toContain('duration: Infinity');
+
+    // Skipping strings still has to win where it matters: a `)` inside a
+    // string literal must not close the call early.
+    const str = `toast('done (mostly)', { duration: Infinity })`;
+    expect(balancedCallAt(str, str.indexOf('('))).toBe(str.slice(str.indexOf('(')));
+  });
+
   it('gives every role="switch" an aria-checked state', () => {
     const offenders = [];
     for (const file of trackedJsxFiles()) {