From da4ccdb2594f317cc34f026258934d9a3a9fb8e4 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 13:42:05 -0700
Subject: [PATCH 01/26] fix(WS-SETTINGS-A): Settings > App > Version shows
 Biorouter's version, not Electron's, in a dev launch

A launch that hands Electron .vite/build/main.js directly loads no package.json, so
app.getVersion() answered Electron's own version (39.8.10): the Version row showed it,
and the GitHub fallback updater compared release tags against it, so a dev launch was
never offered an update. utils/biorouterVersion.ts replaces that one answer with the
package.json version Vite inlines at build time; main.ts adopts it into Electron at
startup (so electron-updater's currentVersion agrees) and answers get-app-version, the
About panel, the Help menu label, the daemon version match, the dependency report and
both updater paths through it. Packaged builds keep what app.getVersion() reports.
---
 ui/desktop/src/biorouterd.ts                  |   3 +-
 .../settings/app/UpdateSection.test.tsx       |  38 +++++++
 ui/desktop/src/main.ts                        |  19 ++--
 ui/desktop/src/utils/autoUpdater.ts           |   5 +-
 ui/desktop/src/utils/biorouterVersion.test.ts | 102 ++++++++++++++++++
 ui/desktop/src/utils/biorouterVersion.ts      |  64 +++++++++++
 ui/desktop/src/utils/dependencyChecker.ts     |   3 +-
 ui/desktop/src/utils/githubUpdater.ts         |   7 +-
 .../src/utils/githubUpdaterVersion.test.ts    |  96 +++++++++++++++++
 9 files changed, 324 insertions(+), 13 deletions(-)
 create mode 100644 ui/desktop/src/utils/biorouterVersion.test.ts
 create mode 100644 ui/desktop/src/utils/biorouterVersion.ts
 create mode 100644 ui/desktop/src/utils/githubUpdaterVersion.test.ts

diff --git a/ui/desktop/src/biorouterd.ts b/ui/desktop/src/biorouterd.ts
index 354f2ae32..e9cebb1ab 100644
--- a/ui/desktop/src/biorouterd.ts
+++ b/ui/desktop/src/biorouterd.ts
@@ -14,6 +14,7 @@ import { status } from './api';
 import { Client } from './api/client';
 import { ExternalBiorouterdConfig } from './utils/settings';
 import { isSharedDaemonEnabled } from './biorouterdSingleton';
+import { biorouterVersion } from './utils/biorouterVersion';
 import {
   createDaemonProxy,
   daemonLossOf,
@@ -493,7 +494,7 @@ async function inspectExistingDaemon(app: App, runtime: DaemonRuntime): Promise<
   }
   if (!runtime.user_action_installed)
     return { kind: 'unusable', why: 'it was started without a user-action key' };
-  const appVersion = typeof app.getVersion === 'function' ? app.getVersion() : undefined;
+  const appVersion = typeof app.getVersion === 'function' ? biorouterVersion(app) : undefined;
   if (appVersion) {
     let version: string;
     try {
diff --git a/ui/desktop/src/components/settings/app/UpdateSection.test.tsx b/ui/desktop/src/components/settings/app/UpdateSection.test.tsx
index 7440d2034..1f84b56b8 100644
--- a/ui/desktop/src/components/settings/app/UpdateSection.test.tsx
+++ b/ui/desktop/src/components/settings/app/UpdateSection.test.tsx
@@ -3,6 +3,7 @@ import { render, screen, fireEvent, act, cleanup } from '@testing-library/react'
 import UpdateSection from './UpdateSection';
 import { aboutCopy } from './copy';
 import type { UpdaterEventPayload } from '../../../utils/updaterState';
+import { BUNDLED_BIOROUTER_VERSION, registerAppVersionIpc } from '../../../utils/biorouterVersion';
 
 let emit: (p: UpdaterEventPayload) => void = () => {};
 let installUpdate: ReturnType<typeof vi.fn>;
@@ -183,3 +184,40 @@ describe('Settings > App > About > Version: one-click flow', () => {
     expect(installUpdate).toHaveBeenCalledTimes(1);
   });
 });
+
+/**
+ * A development launch that hands Electron `.vite/build/main.js` directly reports Electron's own
+ * version from `app.getVersion()`, and the row read 39.8.10. The renderer asks the main process
+ * synchronously (preload: `ipcRenderer.sendSync('get-app-version')`), so this wires the row to the
+ * real main-process handler, given an app reporting Electron's version.
+ */
+describe('Settings > App > About > Version: Biorouter’s version, never Electron’s', () => {
+  const ELECTRON_VERSION = '39.8.10';
+
+  function wireRowToMainProcess() {
+    const handlers = new Map<string, (event: { returnValue?: unknown }) => void>();
+    const ipcMain = {
+      on: (channel: string, handler: (event: { returnValue?: unknown }) => void) => {
+        handlers.set(channel, handler);
+        return ipcMain;
+      },
+    };
+    registerAppVersionIpc(
+      ipcMain as never,
+      { getVersion: () => ELECTRON_VERSION },
+      ELECTRON_VERSION
+    );
+    (window as unknown as { electron: { getVersion: () => string } }).electron.getVersion = () => {
+      const event: { returnValue?: unknown } = {};
+      handlers.get('get-app-version')?.(event);
+      return String(event.returnValue ?? '');
+    };
+  }
+
+  it('shows the version Biorouter was built at in a development launch', () => {
+    wireRowToMainProcess();
+    render(<UpdateSection />);
+    expect(screen.getByText(BUNDLED_BIOROUTER_VERSION)).toBeTruthy();
+    expect(screen.queryByText(ELECTRON_VERSION)).toBeNull();
+  });
+});
diff --git a/ui/desktop/src/main.ts b/ui/desktop/src/main.ts
index 82eaf88d6..39e1c86e9 100644
--- a/ui/desktop/src/main.ts
+++ b/ui/desktop/src/main.ts
@@ -231,6 +231,15 @@ import {
 } from './utils/diagnosticsExport';
 import { Client, createClient, createConfig } from './api/client';
 import installExtension, { REACT_DEVELOPER_TOOLS } from 'electron-devtools-installer';
+import {
+  adoptBiorouterVersion,
+  biorouterVersion,
+  registerAppVersionIpc,
+} from './utils/biorouterVersion';
+
+// Before anything reads the version: a launch handed `.vite/build/main.js` directly reports
+// Electron's own version, and electron-updater reads it when first used.
+adoptBiorouterVersion(app);
 
 // Updater functions (moved here to keep updates.ts minimal for release replacement)
 function shouldSetupUpdater(): boolean {
@@ -1152,7 +1161,7 @@ app.on('will-finish-launching', () => {
   if (process.platform === 'darwin') {
     app.setAboutPanelOptions({
       applicationName: 'Biorouter',
-      applicationVersion: app.getVersion(),
+      applicationVersion: biorouterVersion(app),
     });
   }
 });
@@ -6160,7 +6169,7 @@ function buildApplicationMenu() {
           },
         },
         { type: 'separator' as const },
-        { label: `v${version || app.getVersion()}`, enabled: false },
+        { label: `v${version || biorouterVersion(app)}`, enabled: false },
       ],
     },
 
@@ -7059,10 +7068,8 @@ async function appMain() {
     notification.show();
   });
 
-  // Handler for getting app version
-  ipcMain.on('get-app-version', (event) => {
-    event.returnValue = app.getVersion();
-  });
+  // Biorouter's version for Settings > App > Version, never Electron's.
+  registerAppVersionIpc(ipcMain, app);
 
   ipcMain.handle('open-directory-in-explorer', async (event, dirPath: string) => {
     try {
diff --git a/ui/desktop/src/utils/autoUpdater.ts b/ui/desktop/src/utils/autoUpdater.ts
index 381d1a399..5cad9d6cf 100644
--- a/ui/desktop/src/utils/autoUpdater.ts
+++ b/ui/desktop/src/utils/autoUpdater.ts
@@ -21,6 +21,7 @@ import {
   updateRequiresQuitFirst,
 } from './assistedUpdateInstructions';
 import { githubUpdater } from './githubUpdater';
+import { biorouterVersion } from './biorouterVersion';
 import { loadRecentDirs } from './recentDirs';
 import { scheduleUpdateChecks, type AutomaticUpdateCheckReason } from './updateCheckSchedule';
 
@@ -66,7 +67,7 @@ export function registerUpdateIpcHandlers() {
 
   // IPC handlers for renderer process
   ipcMain.handle('check-for-updates', async () => {
-    const currentVersion = autoUpdater.currentVersion?.version || app.getVersion();
+    const currentVersion = autoUpdater.currentVersion?.version || biorouterVersion(app);
     const checkStartTime = Date.now();
 
     try {
@@ -329,7 +330,7 @@ export function setupAutoUpdater(tray?: Tray) {
   autoUpdaterConfigured = true;
 
   log.info('Setting up auto-updater...');
-  log.info(`Current app version: ${app.getVersion()}`);
+  log.info(`Current app version: ${biorouterVersion(app)}`);
   log.info(`Platform: ${process.platform}, Arch: ${process.arch}`);
   log.info(`ENABLE_DEV_UPDATES: ${process.env.ENABLE_DEV_UPDATES}`);
   log.info(`App is packaged: ${app.isPackaged}`);
diff --git a/ui/desktop/src/utils/biorouterVersion.test.ts b/ui/desktop/src/utils/biorouterVersion.test.ts
new file mode 100644
index 000000000..ecb8ad43a
--- /dev/null
+++ b/ui/desktop/src/utils/biorouterVersion.test.ts
@@ -0,0 +1,102 @@
+// @vitest-environment node
+
+/**
+ * Settings > App > Version showed 39.8.10 in a development launch: the dev launcher hands Electron
+ * the built `.vite/build/main.js` directly, there is no `package.json` beside it, and
+ * `app.getVersion()` then answers with Electron's own version. These pin the replacement: the
+ * main process answers Biorouter's version whatever Electron reports.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { readFileSync } from 'fs';
+import * as path from 'path';
+import {
+  BUNDLED_BIOROUTER_VERSION,
+  adoptBiorouterVersion,
+  biorouterVersion,
+  registerAppVersionIpc,
+} from './biorouterVersion';
+
+const ELECTRON_VERSION = '39.8.10';
+
+const packageJsonVersion = (
+  JSON.parse(readFileSync(path.resolve(__dirname, '../../package.json'), 'utf8')) as {
+    version: string;
+  }
+).version;
+
+function appReporting(version: string) {
+  return { getVersion: vi.fn(() => version), setVersion: vi.fn() };
+}
+
+describe('biorouterVersion', () => {
+  it('is built from ui/desktop/package.json, the version release.sh bumps', () => {
+    expect(BUNDLED_BIOROUTER_VERSION).toBe(packageJsonVersion);
+    expect(BUNDLED_BIOROUTER_VERSION).not.toBe(ELECTRON_VERSION);
+  });
+
+  it('answers Biorouter’s version when Electron reports its own', () => {
+    expect(biorouterVersion(appReporting(ELECTRON_VERSION), ELECTRON_VERSION)).toBe(
+      BUNDLED_BIOROUTER_VERSION
+    );
+  });
+
+  it('keeps what a packaged app reports', () => {
+    expect(biorouterVersion(appReporting('1.93.0'), ELECTRON_VERSION)).toBe('1.93.0');
+  });
+
+  it('answers Biorouter’s version when nothing is reported', () => {
+    expect(biorouterVersion(appReporting(''), ELECTRON_VERSION)).toBe(BUNDLED_BIOROUTER_VERSION);
+  });
+
+  it('keeps any report outside Electron (tests, plain Node)', () => {
+    expect(biorouterVersion(appReporting('0.0.0-test'), undefined)).toBe('0.0.0-test');
+  });
+});
+
+describe('adoptBiorouterVersion', () => {
+  it('sets Electron’s own answer to Biorouter’s, so electron-updater compares Biorouter versions', () => {
+    const app = appReporting(ELECTRON_VERSION);
+    expect(adoptBiorouterVersion(app, ELECTRON_VERSION)).toBe(BUNDLED_BIOROUTER_VERSION);
+    expect(app.setVersion).toHaveBeenCalledWith(BUNDLED_BIOROUTER_VERSION);
+  });
+
+  it('leaves a packaged app’s version alone', () => {
+    const app = appReporting('1.93.0');
+    expect(adoptBiorouterVersion(app, ELECTRON_VERSION)).toBe('1.93.0');
+    expect(app.setVersion).not.toHaveBeenCalled();
+  });
+
+  it('still answers Biorouter’s version when Electron has no setVersion', () => {
+    expect(adoptBiorouterVersion({ getVersion: () => ELECTRON_VERSION }, ELECTRON_VERSION)).toBe(
+      BUNDLED_BIOROUTER_VERSION
+    );
+  });
+});
+
+describe('get-app-version IPC', () => {
+  function register(app: { getVersion(): string }) {
+    const handlers = new Map<string, (event: { returnValue?: unknown }) => void>();
+    const ipcMain = {
+      on: vi.fn((channel: string, handler: (event: { returnValue?: unknown }) => void) => {
+        handlers.set(channel, handler);
+        return ipcMain;
+      }),
+    };
+    registerAppVersionIpc(ipcMain as never, app, ELECTRON_VERSION);
+    return (channel: string) => {
+      const event: { returnValue?: unknown } = {};
+      handlers.get(channel)?.(event);
+      return event.returnValue;
+    };
+  }
+
+  it('returns Biorouter’s version to the renderer in a development launch', () => {
+    const sendSync = register(appReporting(ELECTRON_VERSION));
+    expect(sendSync('get-app-version')).toBe(BUNDLED_BIOROUTER_VERSION);
+  });
+
+  it('returns the packaged app’s version in a packaged launch', () => {
+    const sendSync = register(appReporting('1.93.0'));
+    expect(sendSync('get-app-version')).toBe('1.93.0');
+  });
+});
diff --git a/ui/desktop/src/utils/biorouterVersion.ts b/ui/desktop/src/utils/biorouterVersion.ts
new file mode 100644
index 000000000..e373238ee
--- /dev/null
+++ b/ui/desktop/src/utils/biorouterVersion.ts
@@ -0,0 +1,64 @@
+import type { IpcMain } from 'electron';
+import { version as bundledPackageVersion } from '../../package.json';
+
+/**
+ * Biorouter's version as this bundle was built: `ui/desktop/package.json`'s `"version"`, which
+ * `scripts/release.sh bump` keeps equal to the Cargo workspace version. Vite inlines it into the
+ * main bundle, so it holds however Electron was started.
+ */
+export const BUNDLED_BIOROUTER_VERSION: string = bundledPackageVersion;
+
+/** The part of Electron's `app` this module reads. */
+export interface VersionedApp {
+  getVersion(): string;
+}
+
+/**
+ * Biorouter's version, never Electron's.
+ *
+ * `app.getVersion()` answers from the loaded app's `package.json`. A packaged app and
+ * `electron-forge start` both load `ui/desktop`, so they answer Biorouter's version. A launch that
+ * hands Electron the built `.vite/build/main.js` directly (the agent shell's dev launcher does)
+ * has no `package.json` beside it, and Electron then answers with its OWN version: Settings showed
+ * 39.8.10, and the GitHub fallback compared release tags against it, so a dev launch was never
+ * offered an update. That one answer is replaced; any other is kept.
+ */
+export function biorouterVersion(
+  app: VersionedApp,
+  electronVersion: string | undefined = process.versions.electron
+): string {
+  const reported = app.getVersion();
+  if (!reported || (electronVersion !== undefined && reported === electronVersion)) {
+    return BUNDLED_BIOROUTER_VERSION;
+  }
+  return reported;
+}
+
+/**
+ * Make Electron's own answer Biorouter's, once at startup, so code that reads `app.getVersion()`
+ * for itself agrees: electron-updater takes `currentVersion` from it when it is first used.
+ * `app.setVersion` is what Electron's default app calls with a loaded `package.json`'s version;
+ * it is missing from Electron's typings, so its absence leaves the reported version alone and
+ * every Biorouter reader still goes through `biorouterVersion`.
+ */
+export function adoptBiorouterVersion(
+  app: VersionedApp & { setVersion?: (version: string) => void },
+  electronVersion: string | undefined = process.versions.electron
+): string {
+  const version = biorouterVersion(app, electronVersion);
+  if (app.getVersion() !== version && typeof app.setVersion === 'function') {
+    app.setVersion(version);
+  }
+  return version;
+}
+
+/** The renderer's synchronous `window.electron.getVersion()` (preload: `get-app-version`). */
+export function registerAppVersionIpc(
+  ipcMain: Pick<IpcMain, 'on'>,
+  app: VersionedApp,
+  electronVersion: string | undefined = process.versions.electron
+): void {
+  ipcMain.on('get-app-version', (event) => {
+    event.returnValue = biorouterVersion(app, electronVersion);
+  });
+}
diff --git a/ui/desktop/src/utils/dependencyChecker.ts b/ui/desktop/src/utils/dependencyChecker.ts
index 68fe4c592..e983d43e8 100644
--- a/ui/desktop/src/utils/dependencyChecker.ts
+++ b/ui/desktop/src/utils/dependencyChecker.ts
@@ -18,6 +18,7 @@ import * as path from 'path';
 import * as fs from 'fs';
 import log from './logger';
 import { getBiorouterCliBinaryPath } from '../biorouterd';
+import { biorouterVersion } from './biorouterVersion';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -801,7 +802,7 @@ export function registerDependencyIpcHandlers(): void {
     return {
       platform: process.platform,
       arch: process.arch,
-      appVersion: app.getVersion(),
+      appVersion: biorouterVersion(app),
       osRelease: (unameOut?.stdout ?? '').trim() || os.release(),
       augmentedPath: AUGMENTED_PATH,
       inheritedPath: process.env.PATH ?? '',
diff --git a/ui/desktop/src/utils/githubUpdater.ts b/ui/desktop/src/utils/githubUpdater.ts
index e2f7c166b..d8b49e6e7 100644
--- a/ui/desktop/src/utils/githubUpdater.ts
+++ b/ui/desktop/src/utils/githubUpdater.ts
@@ -8,6 +8,7 @@ import { Readable, Transform } from 'stream';
 import { pipeline } from 'stream/promises';
 import log from './logger';
 import { safeJsonParse } from './conversionUtils';
+import { biorouterVersion } from './biorouterVersion';
 
 interface GitHubRelease {
   tag_name: string;
@@ -57,7 +58,7 @@ export class GitHubUpdater {
     try {
       log.info('=== GitHubUpdater: STARTING UPDATE CHECK ===');
       log.info(`GitHubUpdater: API URL: ${this.apiUrl}`);
-      log.info(`GitHubUpdater: Current app version: ${app.getVersion()}`);
+      log.info(`GitHubUpdater: Current app version: ${biorouterVersion(app)}`);
       log.info(`GitHubUpdater: Timestamp: ${new Date().toISOString()}`);
 
       log.info('GitHubUpdater: Initiating fetch request...');
@@ -70,7 +71,7 @@ export class GitHubUpdater {
       const response = await fetch(this.apiUrl, {
         headers: {
           Accept: 'application/vnd.github.v3+json',
-          'User-Agent': `Biorouter-Desktop/${app.getVersion()}`,
+          'User-Agent': `Biorouter-Desktop/${biorouterVersion(app)}`,
         },
         signal: controller.signal,
       });
@@ -96,7 +97,7 @@ export class GitHubUpdater {
       log.info(`GitHubUpdater: Release assets count: ${release.assets.length}`);
 
       const latestVersion = release.tag_name.replace(/^v/, ''); // Remove 'v' prefix if present
-      const currentVersion = app.getVersion();
+      const currentVersion = biorouterVersion(app);
 
       log.info(
         `GitHubUpdater: Current version: ${currentVersion}, Latest version: ${latestVersion}`
diff --git a/ui/desktop/src/utils/githubUpdaterVersion.test.ts b/ui/desktop/src/utils/githubUpdaterVersion.test.ts
new file mode 100644
index 000000000..87fd4c31d
--- /dev/null
+++ b/ui/desktop/src/utils/githubUpdaterVersion.test.ts
@@ -0,0 +1,96 @@
+// @vitest-environment node
+
+/**
+ * The GitHub fallback compares the latest release tag with the running version. In a development
+ * launch that hands Electron `.vite/build/main.js` directly, `app.getVersion()` is Electron's own
+ * version (39.8.10), and every Biorouter release compared older than it: the check answered "up to
+ * date" forever. The comparison must be made against Biorouter's version.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const ELECTRON_VERSION = '39.8.10';
+
+vi.mock('electron', () => ({ app: { getVersion: () => ELECTRON_VERSION } }));
+vi.mock('./logger', () => ({
+  default: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { GitHubUpdater } from './githubUpdater';
+import { BUNDLED_BIOROUTER_VERSION } from './biorouterVersion';
+
+/** The next patch release after the version this bundle was built at. */
+function nextPatch(version: string): string {
+  const [major, minor, patch] = version.split('.').map((part) => parseInt(part, 10));
+  return `${major}.${minor}.${patch + 1}`;
+}
+
+function releaseResponse(tag: string): Response {
+  const v = tag.replace(/^v/, '');
+  const names = [
+    `Biorouter-${v}-arm64.dmg`,
+    `Biorouter-${v}-x64.dmg`,
+    `Biorouter-Setup-${v}.exe`,
+    `Biorouter-win32-x64-${v}.zip`,
+    `biorouter_${v}_amd64.deb`,
+  ];
+  const body = {
+    tag_name: tag,
+    name: `Biorouter ${tag}`,
+    published_at: '2026-10-12T00:00:00Z',
+    html_url: `https://github.com/BaranziniLab/biorouter/releases/tag/${tag}`,
+    assets: names.map((name) => ({
+      name,
+      browser_download_url: `https://example.invalid/${name}`,
+      size: 1,
+    })),
+  };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+let hadElectronVersion: boolean;
+
+beforeEach(() => {
+  // What the main process sees: Electron's version in process.versions, and the same string from
+  // app.getVersion() because no package.json was loaded.
+  hadElectronVersion = 'electron' in process.versions;
+  Object.defineProperty(process.versions, 'electron', {
+    value: ELECTRON_VERSION,
+    configurable: true,
+  });
+});
+
+afterEach(() => {
+  if (!hadElectronVersion) delete (process.versions as Record<string, unknown>).electron;
+  vi.unstubAllGlobals();
+});
+
+describe('GitHubUpdater compares Biorouter versions', () => {
+  it('offers the next Biorouter release in a launch where Electron reports its own version', async () => {
+    const latest = nextPatch(BUNDLED_BIOROUTER_VERSION);
+    const fetchMock = vi.fn().mockResolvedValue(releaseResponse(`v${latest}`));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const result = await new GitHubUpdater().checkForUpdates();
+
+    expect(result.error).toBeUndefined();
+    expect(result.updateAvailable).toBe(true);
+    expect(result.latestVersion).toBe(latest);
+    const headers = (fetchMock.mock.calls[0][1] as RequestInit).headers as Record<string, string>;
+    expect(headers['User-Agent']).toBe(`Biorouter-Desktop/${BUNDLED_BIOROUTER_VERSION}`);
+  });
+
+  it('answers up to date for the release this bundle was built from', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(releaseResponse(`v${BUNDLED_BIOROUTER_VERSION}`))
+    );
+
+    const result = await new GitHubUpdater().checkForUpdates();
+
+    expect(result.updateAvailable).toBe(false);
+    expect(result.latestVersion).toBe(BUNDLED_BIOROUTER_VERSION);
+  });
+});

From 4d4149f3694307275692aa1259c074c11a69f64b Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 13:47:17 -0700
Subject: [PATCH 02/26] fix(WS-PICKERS): final check, the Tools popover's
 switches are named by their rows and each row is still announced once

The per-chat switches in the Extensions, Skills and Knowledge lists had no
accessible name, unlike every switch on the Extensions page. Each switch is
now named by the row's visible name through aria-labelledby (the base's
name, not the knowledge list's state-saying label). The wrapper keeps it out
of the accessibility tree; the switch no longer carries its own aria-hidden,
which would leave it with no name at all.

Naming it exposed a Chromium quirk: a name built from an option's content
read the hidden switch's name in again (a focusable button under
aria-hidden, and the switch's ::after), so every row said its name twice.
jsdom and Playwright's aria snapshot did not show it; Chromium's own
accessibility tree did. The option is now named by reference to its title
and note (or by its label), so nothing inside it reaches its name. The row
click still goes through the switch.

Tests query each switch by role and name in all three lists, and a Chromium
test reads the real accessibility tree for one node per row.
---
 .../BottomMenuExtensionSelection.test.tsx     | 29 ++++++
 .../BottomMenuKnowledgeSelection.test.tsx     | 31 ++++++
 .../BottomMenuSkillSelection.test.tsx         | 58 +++++++++++
 .../bottom_menu/PickerPanel.test.tsx          | 93 +++++++++++++++++-
 .../components/bottom_menu/PickerPanel.tsx    | 45 ++++++++-
 .../bottom_menu/toolsPopover.browser.test.tsx | 96 ++++++++++++++++++-
 6 files changed, 343 insertions(+), 9 deletions(-)

diff --git a/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.test.tsx b/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.test.tsx
index 72ab76a90..baac1ded9 100644
--- a/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.test.tsx
+++ b/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.test.tsx
@@ -617,6 +617,35 @@ describe('BottomMenuExtensionSelection', () => {
     expect(example).not.toHaveAttribute('title');
   });
 
+  /**
+   * UI defect 3 (final check, 2026-10-12): each row's switch is named by the
+   * row's name, as every switch on the Extensions page is, and it stays out of
+   * the accessibility tree so a screen reader hears each row once (the option).
+   */
+  it('names each row’s switch by the row’s name, and keeps the row the one control', async () => {
+    render(<BottomMenuExtensionSelection sessionId="session-1" />);
+    toggleList();
+    const rows = await screen.findAllByRole('option');
+    expect(screen.queryAllByRole('switch')).toHaveLength(0);
+    expect(screen.getAllByRole('switch', { hidden: true })).toHaveLength(rows.length);
+    for (const name of ['Example', 'Spoke']) {
+      const row = screen.getByRole('option', { name });
+      const picture = screen.getByRole('switch', { name, hidden: true });
+      expect(row).toContainElement(picture);
+      expect(picture).toHaveAttribute('aria-checked', row.getAttribute('aria-selected'));
+    }
+
+    // The row is still what a click toggles, and the named switch follows it.
+    fireEvent.click(screen.getByRole('option', { name: 'Example' }));
+    await waitFor(() =>
+      expect(screen.getByRole('switch', { name: 'Example', hidden: true })).toHaveAttribute(
+        'aria-checked',
+        'true'
+      )
+    );
+    await waitFor(() => expect(mocks.addToAgent).toHaveBeenCalledTimes(1));
+  });
+
   it('filters as the person types, with focus staying in the field', async () => {
     render(<BottomMenuExtensionSelection sessionId="session-1" />);
     toggleList();
diff --git a/ui/desktop/src/components/bottom_menu/BottomMenuKnowledgeSelection.test.tsx b/ui/desktop/src/components/bottom_menu/BottomMenuKnowledgeSelection.test.tsx
index e8a82626b..7be41711a 100644
--- a/ui/desktop/src/components/bottom_menu/BottomMenuKnowledgeSelection.test.tsx
+++ b/ui/desktop/src/components/bottom_menu/BottomMenuKnowledgeSelection.test.tsx
@@ -164,6 +164,37 @@ describe('BottomMenuKnowledgeSelection', () => {
     );
   });
 
+  /**
+   * UI defect 3 (final check, 2026-10-12): each row's switch is named by the
+   * base's name, as every switch on the Extensions page is. Not by the row's
+   * label, which says the state ("Soul, visible to this chat"): a switch's name
+   * never changes with its state (spec 2.6). It stays out of the accessibility
+   * tree, so a screen reader hears each row once (the option).
+   */
+  it('names each row’s switch by the base’s name, and keeps the row the one control', async () => {
+    mocks.state.hiddenKbIds = ['brainstorm'];
+    render(<BottomMenuKnowledgeSelection />);
+    fireEvent.click(screen.getByRole('button', { name: /Manage knowledge bases/ }));
+    await screen.findByRole('listbox', { name: KNOWLEDGE_COPY.listLabel });
+    expect(screen.queryAllByRole('switch')).toHaveLength(0);
+    expect(screen.getAllByRole('switch', { hidden: true })).toHaveLength(2);
+
+    const soul = screen.getByRole('switch', { name: 'Soul', hidden: true });
+    expect(screen.getByRole('option', { name: 'Soul, visible to this chat' })).toContainElement(
+      soul
+    );
+    expect(soul).toHaveAttribute('aria-checked', 'true');
+    const brainstorm = screen.getByRole('switch', { name: 'brainstorm', hidden: true });
+    expect(
+      screen.getByRole('option', { name: KNOWLEDGE_COPY.rowLabel('brainstorm', true) })
+    ).toContainElement(brainstorm);
+    expect(brainstorm).toHaveAttribute('aria-checked', 'false');
+
+    // The row is still what a click toggles.
+    fireEvent.click(screen.getByRole('option', { name: /^brainstorm/ }));
+    expect(mocks.toggleKbHidden).toHaveBeenCalledWith('brainstorm');
+  });
+
   it('toggles a base with one write when its row is chosen', () => {
     render(<BottomMenuKnowledgeSelection />);
     fireEvent.click(screen.getByRole('button', { name: /Manage knowledge bases/ }));
diff --git a/ui/desktop/src/components/bottom_menu/BottomMenuSkillSelection.test.tsx b/ui/desktop/src/components/bottom_menu/BottomMenuSkillSelection.test.tsx
index 43431c1a7..0076989ee 100644
--- a/ui/desktop/src/components/bottom_menu/BottomMenuSkillSelection.test.tsx
+++ b/ui/desktop/src/components/bottom_menu/BottomMenuSkillSelection.test.tsx
@@ -332,6 +332,64 @@ describe('BottomMenuSkillSelection', () => {
     expect(screen.getByText('BiorOffice')).toBeInTheDocument();
   });
 
+  /**
+   * UI defect 3 (final check, 2026-10-12): each row's switch is named by the
+   * row's name alone (not its badge, its source or a bundle's count), as every
+   * switch on the Extensions page is, and it stays out of the accessibility tree
+   * so a screen reader hears each row once (the option).
+   */
+  it('names each row’s switch by the row’s name, and keeps the row the one control', async () => {
+    const catalog = (exampleOn: boolean) =>
+      view({
+        skills: [
+          skill('example-skill', {
+            state: {
+              machineEnabled: exampleOn,
+              session: 'default',
+              sessionViaBundle: false,
+              hiddenContext: false,
+              effective: exampleOn,
+            },
+          }),
+          skill('r-scripting', { builtin: true }),
+          skill('word', {
+            sourceRoot: '/extensions/BiorOffice/skills',
+            source: { kind: 'extension', extension: 'BiorOffice', label: 'BiorOffice' },
+          }),
+        ],
+        bundles: [
+          bundle('hyperframes', ['hyperframes', 'media-use'], { displayName: 'HyperFrames' }),
+        ],
+      });
+    serve(catalog(true));
+    render(<BottomMenuSkillSelection sessionId={null} />);
+    const rows = await openMenu();
+    expect(rows).toHaveLength(4);
+    expect(screen.queryAllByRole('switch')).toHaveLength(0);
+    expect(screen.getAllByRole('switch', { hidden: true })).toHaveLength(4);
+    for (const name of ['example-skill', 'r-scripting', 'word', 'HyperFrames']) {
+      const picture = screen.getByRole('switch', { name, hidden: true });
+      expect(picture.closest('[role="option"]')).toHaveAttribute('aria-selected', 'true');
+      expect(picture).toHaveAttribute('aria-checked', 'true');
+    }
+
+    // The row is still what a click toggles, and the named switch follows it (the
+    // machine-wide write reads the catalog back, so the next read says off).
+    serve(catalog(false));
+    fireEvent.click(
+      screen
+        .getByRole('switch', { name: 'example-skill', hidden: true })
+        .closest('[role="option"]')!
+    );
+    await waitFor(() =>
+      expect(screen.getByRole('switch', { name: 'example-skill', hidden: true })).toHaveAttribute(
+        'aria-checked',
+        'false'
+      )
+    );
+    expect(mocks.overrides.get('example-skill')).toBe(false);
+  });
+
   it('asks the daemon to rescan when the menu opens, so an install made elsewhere shows up', async () => {
     render(<BottomMenuSkillSelection sessionId={null} />);
     await openMenu();
diff --git a/ui/desktop/src/components/bottom_menu/PickerPanel.test.tsx b/ui/desktop/src/components/bottom_menu/PickerPanel.test.tsx
index d4dd20746..e43db23db 100644
--- a/ui/desktop/src/components/bottom_menu/PickerPanel.test.tsx
+++ b/ui/desktop/src/components/bottom_menu/PickerPanel.test.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
 import BuiltInBadge from '../ui/BuiltInBadge';
@@ -98,16 +98,103 @@ describe('the picker shell', () => {
   it('draws each switch as the picture of its row: out of the accessibility tree and the tab order', () => {
     render(<Harness initial={ROWS} />);
     // The row is the control. A live switch inside it would be a second tab stop
-    // and a second name for one thing.
+    // and a second announcement for one thing.
     expect(screen.queryAllByRole('switch')).toHaveLength(0);
     const pictures = document.querySelectorAll('.br-switch');
     expect(pictures).toHaveLength(ROWS.length);
     pictures.forEach((picture) => {
-      expect(picture).toHaveAttribute('aria-hidden', 'true');
+      // Its wrapper hides it. The switch carries no `aria-hidden` of its own: an
+      // element hidden by its own attribute has no name at all (below).
+      expect(picture.closest('.br-picker-row__switch')).toHaveAttribute('aria-hidden', 'true');
+      expect(picture).not.toHaveAttribute('aria-hidden');
       expect(picture).toHaveAttribute('tabindex', '-1');
     });
   });
 
+  /**
+   * UI defect 3 (final check, 2026-10-12): the switches had no name, where every
+   * switch on the Extensions page is named by its row's title. A picture is still
+   * a switch to anything that reads the DOM, so it is named the same way: by the
+   * row's visible name, through `aria-labelledby`. The row stays the one thing a
+   * screen reader announces: the switch is out of the tree, and its name does not
+   * fold into the option's a second time.
+   */
+  it('names each switch by its row, and still announces each row once', () => {
+    render(<Harness initial={ROWS} />);
+    for (const row of ROWS) {
+      const option = screen.getByRole('option', { name: new RegExp(`^${row.name}`) });
+      const picture = screen.getByRole('switch', { name: row.name, hidden: true });
+      expect(option).toContainElement(picture);
+      expect(picture).toHaveAttribute('aria-checked', String(row.on));
+      // The visible name, referenced: not a second copy of it.
+      expect(picture).not.toHaveAttribute('aria-label');
+      expect(document.getElementById(picture.getAttribute('aria-labelledby')!)).toHaveTextContent(
+        row.name
+      );
+      // One announcement per row: nothing inside the option is exposed on its own,
+      // and the option says its name once.
+      expect(within(option).queryAllByRole('switch')).toHaveLength(0);
+      expect(within(option).queryAllByRole('checkbox')).toHaveLength(0);
+      expect(option).not.toHaveAccessibleName(new RegExp(`${row.name}.*${row.name}`));
+      // ...because it is named BY REFERENCE, to its visible text, and never from
+      // its content: Chromium reads the hidden switch's name into a name built from
+      // content (a focusable button, a `::after`), which jsdom never shows. The
+      // Chromium half is in toolsPopover.browser.test.tsx; this pins what it rests on.
+      const parts = option.getAttribute('aria-labelledby')!.split(' ');
+      expect(parts.map((id) => document.getElementById(id)!.className)).toEqual(
+        row.note ? ['br-picker-row__title', 'br-picker-row__note'] : ['br-picker-row__title']
+      );
+    }
+    expect(screen.getByRole('option', { name: /^gamma/ })).toHaveAccessibleName(
+      'gamma Unavailable in this chat (public model)'
+    );
+    expect(screen.getByRole('option', { name: 'alpha' })).toBeInTheDocument();
+    expect(screen.getByRole('option', { name: 'delta' })).toBeInTheDocument();
+  });
+
+  it('keeps a switch’s name when the row’s own label says its state', () => {
+    // The knowledge list's row label changes with the state ("Soul, visible to this
+    // chat"); a switch's name never does (spec 2.6), so it is the row's name alone.
+    function Base() {
+      const [visible, setVisible] = React.useState(true);
+      return (
+        <PickerPanel
+          listLabel="Knowledge bases"
+          searchPlaceholder="Search knowledge bases…"
+          query=""
+          onQueryChange={() => {}}
+          scopeLabel="This chat"
+          scopeHelp="Help."
+          emptyText="None"
+        >
+          <PickerRow
+            name="Soul"
+            checked={visible}
+            label={`Soul, ${visible ? 'visible to' : 'hidden from'} this chat`}
+            badge={<BuiltInBadge />}
+            onToggle={() => setVisible((value) => !value)}
+          />
+        </PickerPanel>
+      );
+    }
+    render(<Base />);
+    expect(screen.getByRole('switch', { name: 'Soul', hidden: true })).toHaveAttribute(
+      'aria-checked',
+      'true'
+    );
+    // The label names the row on its own: `aria-labelledby` would win over it.
+    expect(screen.getByRole('option')).not.toHaveAttribute('aria-labelledby');
+    fireEvent.click(screen.getByRole('option', { name: 'Soul, visible to this chat' }));
+    expect(screen.getByRole('option', { name: 'Soul, hidden from this chat' })).toHaveAttribute(
+      'aria-selected',
+      'false'
+    );
+    expect(screen.getByRole('switch', { name: 'Soul', hidden: true })).toHaveAttribute(
+      'aria-checked',
+      'false'
+    );
+  });
+
   it('moves the highlight with the arrow keys and toggles the highlighted row on Enter', async () => {
     const onToggled = vi.fn();
     render(<Harness initial={ROWS} onToggled={onToggled} />);
diff --git a/ui/desktop/src/components/bottom_menu/PickerPanel.tsx b/ui/desktop/src/components/bottom_menu/PickerPanel.tsx
index cdcb09804..51fc626e7 100644
--- a/ui/desktop/src/components/bottom_menu/PickerPanel.tsx
+++ b/ui/desktop/src/components/bottom_menu/PickerPanel.tsx
@@ -22,6 +22,24 @@ import { TOOLS_COPY } from './copy';
  * multi-select listbox. The switch at its end is the picture of that state, so
  * it is hidden from assistive tech and takes no pointer events: the row is the
  * control.
+ *
+ * The picture is still named, by the row's visible name through
+ * `aria-labelledby`, as every switch on the Extensions page is (UI defect 3,
+ * final check 2026-10-12: anything that reads the DOM found three lists of
+ * unnamed switches). Its wrapper hides it, not an `aria-hidden` of its own: an
+ * element hidden by its own attribute has no name at all.
+ *
+ * ⚠ **So the option is named by reference, never from its content.** Chromium
+ * reads a hidden descendant into a name built from content in more than one
+ * case: a focusable element under `aria-hidden` (the switch is a `<button>`,
+ * focusable at `tabIndex={-1}`), and any element with generated content (the
+ * switch's `::after` hit target). Either one made every option say its name
+ * twice once the switch had one ("extensions 1 extensions 1"), measured in
+ * Chromium's own accessibility tree, where jsdom and Playwright's aria snapshot
+ * both said it once; `inert` on the wrapper did not help. So the option points at
+ * its visible text (the title line, then the note) with `aria-labelledby`, or
+ * carries `label` as its `aria-label`, and nothing else inside it can reach its
+ * name. `toolsPopover.browser.test.tsx` reads Chromium's tree to pin it.
  */
 export interface PickerPanelProps {
   /** The listbox's accessible name ("Extensions"). */
@@ -132,13 +150,25 @@ export function PickerRow({
   description,
   'data-testid': testId,
 }: PickerRowProps) {
+  // The switch's name: the row's name alone. Not `label`, which may say the
+  // state ("Soul, visible to this chat"), and a switch's name never changes with
+  // its state (spec 2.6); not the badge or the count beside it either.
+  const nameId = React.useId();
+  // The option's name, by reference (see the file's header): the title line,
+  // then the note. `label` replaces both, so the two are never set together
+  // (`aria-labelledby` would win over `aria-label`).
+  const titleId = React.useId();
+  const noteId = React.useId();
+  const labelledBy = label ? undefined : note ? `${titleId} ${noteId}` : titleId;
   // The name, its badge and its count are one line, and the line is what the
   // description hangs from: a pointer resting on the "Built-in" badge gets the
   // row's tooltip too (the badge cannot hold a help glyph of its own inside a
   // row that is itself the control).
   const title = (
-    <span className="br-picker-row__title">
-      <span className="br-picker-row__name">{name}</span>
+    <span id={titleId} className="br-picker-row__title">
+      <span id={nameId} className="br-picker-row__name">
+        {name}
+      </span>
       {badge}
       {meta && <span className="br-picker-row__meta">{meta}</span>}
     </span>
@@ -155,6 +185,7 @@ export function PickerRow({
       selected={checked}
       disabled={disabled}
       aria-label={label}
+      aria-labelledby={labelledBy}
       // The tooltip is for the pointer; a screen reader hears the same text as
       // the row's description while the arrow keys rest on it. Not a hidden
       // child: text inside the option would become part of its name.
@@ -174,7 +205,11 @@ export function PickerRow({
         ) : (
           title
         )}
-        {note && <span className="br-picker-row__note">{note}</span>}
+        {note && (
+          <span id={noteId} className="br-picker-row__note">
+            {note}
+          </span>
+        )}
       </span>
       <span className="br-picker-row__switch" aria-hidden="true">
         <Switch
@@ -185,7 +220,9 @@ export function PickerRow({
           onClick={(event) => event.stopPropagation()}
           disabled={disabled}
           tabIndex={-1}
-          aria-hidden="true"
+          // Hidden by the wrapper, never by its own `aria-hidden` (see the file's
+          // header): named like the Extensions page's switches.
+          aria-labelledby={nameId}
         />
       </span>
     </CommandItem>
diff --git a/ui/desktop/src/components/bottom_menu/toolsPopover.browser.test.tsx b/ui/desktop/src/components/bottom_menu/toolsPopover.browser.test.tsx
index 0dd182e5f..e67299eee 100644
--- a/ui/desktop/src/components/bottom_menu/toolsPopover.browser.test.tsx
+++ b/ui/desktop/src/components/bottom_menu/toolsPopover.browser.test.tsx
@@ -107,6 +107,10 @@ export function ${hook}() {
 export function ${panel}({ inputRef }: { inputRef?: React.Ref<HTMLInputElement> }) {
   const [query, setQuery] = React.useState('');
   const count = (window as unknown as { __rows: Record<string, number> }).__rows['${segment}'];
+  // A test may give a row a note or a label (the knowledge list's state-saying name).
+  const extras = (
+    window as unknown as { __extras?: Record<string, Array<{ note?: string; label?: string }>> }
+  ).__extras?.['${segment}'];
   return (
     <PickerPanel
       listLabel="${segment}"
@@ -121,7 +125,13 @@ export function ${panel}({ inputRef }: { inputRef?: React.Ref<HTMLInputElement>
       data-testid="panel-${segment}"
     >
       {Array.from({ length: count }, (_, i) => (
-        <PickerRow key={i} name={'${segment} ' + (i + 1)} checked={i % 2 === 0} onToggle={() => {}} />
+        <PickerRow
+          key={i}
+          name={'${segment} ' + (i + 1)}
+          checked={i % 2 === 0}
+          onToggle={() => {}}
+          {...extras?.[i]}
+        />
       ))}
     </PickerPanel>
   );
@@ -235,7 +245,11 @@ describe('the Tools popover keeps its segmented control above the chip (R-25)',
   }, 120_000);
 
   /** The page with the chip, not yet open. `rows` replaces the lists' lengths. */
-  async function load(height: number, rows?: Record<string, number>): Promise<Page> {
+  async function load(
+    height: number,
+    rows?: Record<string, number>,
+    extras?: Record<string, Array<{ note?: string; label?: string }>>
+  ): Promise<Page> {
     const tab = await browser!.newPage({ viewport: { width: 900, height } });
     // The open keyframe moves the surface 4px; measure the layout, not the motion.
     await tab.emulateMedia({ reducedMotion: 'reduce' });
@@ -247,6 +261,11 @@ describe('the Tools popover keeps its segmented control above the chip (R-25)',
         (window as unknown as { __rows: Record<string, number> }).__rows = r;
       }, rows);
     }
+    if (extras) {
+      await tab.evaluate((e) => {
+        (window as unknown as { __extras: typeof e }).__extras = e;
+      }, extras);
+    }
     await tab.addScriptTag({ content: script });
     await tab.waitForSelector('[data-testid="composer-tools-chip"]');
     return tab;
@@ -424,6 +443,79 @@ describe('the Tools popover keeps its segmented control above the chip (R-25)',
     expect(heights[480].skills).toBeLessThan(tall.skills);
   });
 
+  /**
+   * UI defect 3 (final check, 2026-10-12): every row's switch, in all three
+   * lists, is named by the row's name, and Chromium's own accessibility tree
+   * (what a screen reader is handed) still has one node per row: the option,
+   * named once, with no switch beside it.
+   */
+  it('names every switch by its row, and leaves one announcement per row in Chromium’s tree', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const NOTE = 'Unavailable in this chat (public model)';
+    // The knowledge list names a row by a label that says its state.
+    const label = (i: number) =>
+      `knowledge ${i}, ${i % 2 === 1 ? 'visible to' : 'hidden from'} this chat`;
+    const tab = await load(
+      900,
+      { extensions: 3, skills: 2, knowledge: 2 },
+      { extensions: [{}, { note: NOTE }], knowledge: [{ label: label(1) }, { label: label(2) }] }
+    );
+    try {
+      const cdp = await tab.context().newCDPSession(tab);
+      await cdp.send('Accessibility.enable');
+      await tab.click('[data-testid="composer-tools-chip"]');
+      await tab.waitForSelector('[data-testid="composer-tools-tabs"]');
+      await settle(tab);
+      for (const [segment, count] of [
+        ['extensions', 3],
+        ['skills', 2],
+        ['knowledge', 2],
+      ] as const) {
+        if (segment !== 'extensions') await clickAndWatch(tab, segment);
+        const panel = tab.getByTestId(`panel-${segment}`);
+        // Out of the tree: no switch is reachable as one...
+        expect(await panel.getByRole('switch').count(), `${segment}: switches`).toBe(0);
+        expect(await panel.getByRole('option').count(), `${segment}: rows`).toBe(count);
+        const { nodes } = await cdp.send('Accessibility.getFullAXTree');
+        const exposed = nodes.filter((node) => !node.ignored);
+        expect(
+          exposed.filter((node) => node.role?.value === 'switch'),
+          `${segment}: switches Chromium exposes`
+        ).toHaveLength(0);
+        for (let i = 1; i <= count; i++) {
+          const name = `${segment} ${i}`;
+          // ...and yet each is named by its row, in a real engine.
+          const picture = panel.getByRole('switch', { name, exact: true, includeHidden: true });
+          expect(await picture.count(), `the switch named ${name}`).toBe(1);
+          expect(
+            await picture.evaluate((el) => el.closest('[role="option"]')?.textContent),
+            name
+          ).toMatch(new RegExp(`^${name}`));
+          // One announcement: one node carries the row's name, and it is the option,
+          // which says it once (with its note, or as its label says it).
+          const option =
+            segment === 'knowledge'
+              ? label(i)
+              : segment === 'extensions' && i === 2
+                ? `${name} ${NOTE}`
+                : name;
+          const named = exposed.filter(
+            (node) =>
+              typeof node.name?.value === 'string' &&
+              node.name.value.includes(name) &&
+              !['StaticText', 'InlineTextBox'].includes(String(node.role?.value))
+          );
+          expect(
+            named.map((node) => [node.role?.value, node.name?.value]),
+            `${segment}: nodes named ${name}`
+          ).toEqual([['option', option]]);
+        }
+      }
+    } finally {
+      await tab.close();
+    }
+  });
+
   it('opens above the chip from its first painted frame, even short of room with a long list', async (ctx) => {
     if (!browser) return ctx.skip();
     // 400px tall: the room above the chip (about 250px) is less than the 70vh the

From 8b190ecae71c8e13a117e61da2f67b7fce80b72b Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 13:52:23 -0700
Subject: [PATCH 03/26] fix(apps): an app arms an extension the person
 installed from that machine's own settings, not as a built-in server (#386)

An app's agent.extensions names an extension and nothing else. Every name
that was not a platform extension was armed as one of Biorouter's own
servers, so an installed stdio extension the drafter's catalog offered
(ucsfomopagent) failed on every connect with "Unknown builtin extension".
A name that is not built in now resolves against the extensions configured
on the machine running the app, with that machine's command and
credentials, so the manifest stays portable. An entry the person turned
off, a platform or frontend entry, and a name nothing is installed under
are not armed, and the daemon log says which. The SDK reference says how
to declare one.
---
 crates/biorouter-server/src/routes/apps.rs | 240 ++++++++++++++++++---
 docs/apps-sdk/sdk-reference.md             |   1 +
 2 files changed, 214 insertions(+), 27 deletions(-)

diff --git a/crates/biorouter-server/src/routes/apps.rs b/crates/biorouter-server/src/routes/apps.rs
index 0593a5754..26c8ff900 100644
--- a/crates/biorouter-server/src/routes/apps.rs
+++ b/crates/biorouter-server/src/routes/apps.rs
@@ -2710,8 +2710,7 @@ fn app_platform_tools(name: &str) -> Option<&'static [&'static str]> {
     None
 }
 
-/// The extension config an app arms `name` with, or `None` when an app may not
-/// have it at all.
+/// The extension config an app arms `name` with, or why it is not armed.
 ///
 /// Scoped HERE and not at the auto-arm call sites, because both app paths build
 /// their configs through this one function — the main agent's
@@ -2721,26 +2720,109 @@ fn app_platform_tools(name: &str) -> Option<&'static [&'static str]> {
 /// comment: `arm_extensions` is the only caller of `Agent::add_extension` in
 /// this file, and `an_app_arms_extensions_through_exactly_one_call_site` reads
 /// this file's own source to keep it that way.
-fn manifest_extension_config(name: &str) -> Option<ExtensionConfig> {
+fn manifest_extension_config(name: &str) -> Result<ExtensionConfig, UnarmedExtension> {
+    resolve_manifest_extension(name, configured_extension)
+}
+
+/// Why an extension an app named was not armed, worded for the daemon log.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum UnarmedExtension {
+    /// A platform extension outside [`app_platform_tools`].
+    Platform,
+    /// Not built in, and nothing on this machine is configured under the name.
+    NotInstalled,
+    /// Configured on this machine, and turned off there.
+    TurnedOff,
+    /// Configured as a kind an app may not arm (named).
+    Kind(&'static str),
+}
+
+impl UnarmedExtension {
+    fn reason(self) -> String {
+        match self {
+            Self::Platform => {
+                "refused: an app may not arm this platform extension (see `app_platform_tools`)"
+                    .to_string()
+            }
+            Self::NotInstalled => "not armed: it is not built in and no extension with this name \
+                 is installed on this machine; install it under the same name"
+                .to_string(),
+            Self::TurnedOff => "not armed: the extension with this name is turned off on this \
+                 machine; turn it on under Extensions in Biorouter"
+                .to_string(),
+            Self::Kind(kind) => {
+                format!("refused: the extension with this name is a {kind} entry, which an app may not arm")
+            }
+        }
+    }
+}
+
+/// The extension an app arms for `name`, from Biorouter's own servers or from
+/// `configured`, this machine's extension configuration.
+///
+/// Issue #386. A manifest names an extension and nothing else: no command, path,
+/// address or credential, so it reads the same on the author's machine and on a
+/// recipient's. A name that is neither a platform extension nor one of
+/// Biorouter's built-in servers is therefore an extension the person installed,
+/// and it resolves against what THIS machine has configured under that name,
+/// with this machine's own command and credentials. It used to be armed as a
+/// built-in server whatever it was, so an installed stdio extension the app
+/// catalog offered (`ucsfomopagent`) failed every time with "Unknown builtin
+/// extension".
+///
+/// An entry the person turned off is not armed: an app is not a way around
+/// their switch. Nor is a platform entry (that would side-step
+/// [`app_platform_tools`]) or a frontend one (its tools run in a desktop
+/// window, which an app's page is not).
+fn resolve_manifest_extension(
+    name: &str,
+    configured: impl FnOnce(&str) -> Option<biorouter::config::ExtensionEntry>,
+) -> Result<ExtensionConfig, UnarmedExtension> {
     if PLATFORM_EXTENSIONS.contains_key(name) {
-        return Some(ExtensionConfig::Platform {
+        let tools = app_platform_tools(name).ok_or(UnarmedExtension::Platform)?;
+        return Ok(ExtensionConfig::Platform {
             name: name.to_string(),
             bundled: None,
             description: name.to_string(),
-            available_tools: app_platform_tools(name)?
-                .iter()
-                .map(|t| (*t).to_string())
-                .collect(),
+            available_tools: tools.iter().map(|t| (*t).to_string()).collect(),
         });
     }
-    Some(ExtensionConfig::Builtin {
-        name: name.to_string(),
-        display_name: None,
-        timeout: None,
-        bundled: None,
-        description: name.to_string(),
-        available_tools: Vec::new(),
-    })
+    if biorouter_mcp::BUILTIN_EXTENSIONS.contains_key(name) {
+        return Ok(ExtensionConfig::Builtin {
+            name: name.to_string(),
+            display_name: None,
+            timeout: None,
+            bundled: None,
+            description: name.to_string(),
+            available_tools: Vec::new(),
+        });
+    }
+    let entry = configured(name).ok_or(UnarmedExtension::NotInstalled)?;
+    if !entry.enabled {
+        return Err(UnarmedExtension::TurnedOff);
+    }
+    match entry.config {
+        config @ (ExtensionConfig::Stdio { .. }
+        | ExtensionConfig::StreamableHttp { .. }
+        | ExtensionConfig::Sse { .. }
+        | ExtensionConfig::InlinePython { .. }) => Ok(config),
+        ExtensionConfig::Platform { .. } => Err(UnarmedExtension::Kind("platform")),
+        ExtensionConfig::Frontend { .. } => Err(UnarmedExtension::Kind("frontend")),
+        ExtensionConfig::Builtin { .. } => Err(UnarmedExtension::Kind("built-in")),
+    }
+}
+
+/// The entry this machine's configuration holds for the extension `name`: by
+/// its exact name, else by the key the configuration files it under (case and
+/// spaces folded), which is how an installer names it.
+fn configured_extension(name: &str) -> Option<biorouter::config::ExtensionEntry> {
+    if let Some(entry) = biorouter::config::get_extension_entry_by_name(name) {
+        return Some(entry);
+    }
+    let key = biorouter::config::extensions::name_to_key(name);
+    biorouter::config::get_all_extensions()
+        .into_iter()
+        .find(|entry| biorouter::config::extensions::name_to_key(&entry.config.name()) == key)
 }
 
 /// Arm one app agent's extensions. The **only** `Agent::add_extension` call site
@@ -2754,14 +2836,17 @@ async fn arm_extensions(
     names: Vec<String>,
 ) {
     for name in names {
-        let Some(config) = manifest_extension_config(&name) else {
-            // Refused, and said out loud: a silently missing toolset is
-            // indistinguishable from a broken extension.
-            warn!(
-                app = %manifest.id, profile = ?profile, extension = %name,
-                "refused: an app may not arm this platform extension (see `app_platform_tools`)"
-            );
-            continue;
+        let config = match manifest_extension_config(&name) {
+            Ok(config) => config,
+            Err(unarmed) => {
+                // Refused, and said out loud: a silently missing toolset is
+                // indistinguishable from a broken extension.
+                warn!(
+                    app = %manifest.id, profile = ?profile, extension = %name,
+                    "{}", unarmed.reason()
+                );
+                continue;
+            }
         };
         if let Err(e) = agent.add_extension(config).await {
             warn!(app = %manifest.id, profile = ?profile, extension = %name, "add_extension failed: {e}");
@@ -12890,7 +12975,7 @@ mod tests {
                     continue;
                 }
                 assert!(
-                    manifest_extension_config(name).is_none(),
+                    manifest_extension_config(name).is_err(),
                     "an app was armed with the platform extension `{name}`; \
                      `available_tools: Vec::new()` means ALL of its tools"
                 );
@@ -12905,7 +12990,7 @@ mod tests {
 
             // `skills` is armed, and bounded.
             match manifest_extension_config(skills) {
-                Some(ExtensionConfig::Platform {
+                Ok(ExtensionConfig::Platform {
                     available_tools, ..
                 }) => assert_eq!(
                     available_tools,
@@ -12923,7 +13008,7 @@ mod tests {
             assert!(
                 matches!(
                     manifest_extension_config("developer"),
-                    Some(ExtensionConfig::Builtin { .. })
+                    Ok(ExtensionConfig::Builtin { .. })
                 ),
                 "a builtin MCP extension must still arm for an app"
             );
@@ -12961,6 +13046,107 @@ mod tests {
             );
         }
 
+        /// Issue #386. An app that names an extension the person installed
+        /// (`ucsfomopagent`, a stdio server in their configuration) is armed with
+        /// THAT entry: its command, arguments and credential keys come from this
+        /// machine, never from the manifest. It used to be armed as a built-in
+        /// server whatever it was, and failed every time with "Unknown builtin
+        /// extension: ucsfomopagent".
+        #[test]
+        fn an_app_arms_an_installed_extension_from_this_machines_configuration() {
+            use super::super::{resolve_manifest_extension, UnarmedExtension};
+            use biorouter::agents::ExtensionConfig;
+            use biorouter::config::ExtensionEntry;
+
+            let entry = |value: serde_json::Value| -> ExtensionEntry {
+                serde_json::from_value(value).expect("a config.yaml extension entry")
+            };
+            let installed = |enabled: bool| {
+                entry(serde_json::json!({
+                    "enabled": enabled,
+                    "type": "stdio",
+                    "name": "ucsfomopagent",
+                    "description": "UCSF OMOP",
+                    "cmd": "uvx",
+                    "args": ["ucsf-omop-agent"],
+                    "env_keys": ["UCSFOMOP_PASSWORD"],
+                    "timeout": 300
+                }))
+            };
+            let only = |want: &'static str, found: ExtensionEntry| {
+                move |name: &str| (name == want).then(|| found.clone())
+            };
+
+            match resolve_manifest_extension(
+                "ucsfomopagent",
+                only("ucsfomopagent", installed(true)),
+            ) {
+                Ok(ExtensionConfig::Stdio {
+                    name,
+                    cmd,
+                    args,
+                    env_keys,
+                    ..
+                }) => {
+                    assert_eq!(name, "ucsfomopagent");
+                    assert_eq!(cmd, "uvx");
+                    assert_eq!(args, vec!["ucsf-omop-agent".to_string()]);
+                    assert_eq!(env_keys, vec!["UCSFOMOP_PASSWORD".to_string()]);
+                }
+                other => panic!("an installed stdio extension must arm as itself: {other:?}"),
+            }
+
+            // The person's off switch holds: an app is not a way around it.
+            assert_eq!(
+                resolve_manifest_extension(
+                    "ucsfomopagent",
+                    only("ucsfomopagent", installed(false))
+                ),
+                Err(UnarmedExtension::TurnedOff)
+            );
+            // Nothing installed under the name: said as that, not as a broken
+            // built-in server.
+            assert_eq!(
+                resolve_manifest_extension("ucsfomopagent", |_: &str| None),
+                Err(UnarmedExtension::NotInstalled)
+            );
+            assert!(UnarmedExtension::NotInstalled
+                .reason()
+                .contains("install it under the same name"));
+
+            // A configured entry may not smuggle in what the platform allow-list
+            // refuses, nor tools that only a desktop window can run.
+            let platform = entry(serde_json::json!({
+                "enabled": true, "type": "platform", "name": "mytools", "description": ""
+            }));
+            assert_eq!(
+                resolve_manifest_extension("mytools", only("mytools", platform)),
+                Err(UnarmedExtension::Kind("platform"))
+            );
+            let frontend = entry(serde_json::json!({
+                "enabled": true, "type": "frontend", "name": "panel", "description": "",
+                "tools": [], "instructions": null
+            }));
+            assert_eq!(
+                resolve_manifest_extension("panel", only("panel", frontend)),
+                Err(UnarmedExtension::Kind("frontend"))
+            );
+
+            // Biorouter's own servers and the platform allow-list are decided
+            // before the configuration is read at all.
+            let unread = |name: &str| -> Option<ExtensionEntry> {
+                panic!("the configuration was read for `{name}`")
+            };
+            assert!(matches!(
+                resolve_manifest_extension("autovisualiser", unread),
+                Ok(ExtensionConfig::Builtin { .. })
+            ));
+            assert_eq!(
+                resolve_manifest_extension("workspace", unread),
+                Err(UnarmedExtension::Platform)
+            );
+        }
+
         /// A blank knowledge base is not a declared one.
         ///
         /// `resolve_worker_grants` read `cfg.knowledge_base.is_some()`, so
diff --git a/docs/apps-sdk/sdk-reference.md b/docs/apps-sdk/sdk-reference.md
index bbd954c24..d2f4b7b11 100644
--- a/docs/apps-sdk/sdk-reference.md
+++ b/docs/apps-sdk/sdk-reference.md
@@ -242,6 +242,7 @@ These come from `manifest.rs`.
 - `DataSource.ids` scopes a `kind:"knowledge"` source to specific KB id(s). Empty `ids` grants **nothing** by itself — the only exception is a back-compat implicit single grant of the agent's configured `knowledge_base`. A KB id not enumerated here is denied even if it exists (see the [security model](#security-model)). `read_only` defaults `true`; setting it `false` grants write (`br.kb.ingest`).
 - `ModelRoute` (at `orchestration.routes`) has optional `provider` + `model`; an absent field inherits the session's current value. Routes resolve against the *user's* configured providers only (apps never carry keys) and are subject to the provider-class rule in the [security model](#security-model).
 - Skills scoping is advisory — the named skills are surfaced to the agent, but BioRouter's skill enable/disable is global, so true per-app skill isolation is a follow-up.
+- `agent.extensions` holds names only, never a command, path, address or credential, so a manifest reads the same on every machine. A name of one of Biorouter's own servers (`developer`, `autovisualiser`, `webdocuments`, `memory`, `knowledge`, `computercontroller`, `agent_drafter`) arms that server. Any other name is an extension the person installed: the daemon looks it up in that machine's own extension settings (`extensions:` in `config.yaml`, by the extension's name) and arms it with that machine's command and credentials. A recipient therefore installs the same extension under the same name, which is what the registry reference in `export.json` is for. An entry that is turned off is not armed (an app does not override the person's switch), nor is a `platform` or `frontend` entry, nor a name nothing on the machine has; the daemon log says which and why. Until issue #386 every such name was armed as one of Biorouter's own servers and failed with "Unknown builtin extension". The drafter's catalog offers the installed extension bundles under `extensions/` in the Biorouter folder, so an extension added to `config.yaml` by hand is declared in `requires` instead while strict validation is on.
 - `Capabilities.events` (agent→app lifecycle, advertised as `event:<name>`) is distinct from `surface.signals` (app→agent); the two channels never collide.
 - `app_uid` is server-managed, like `created_at`, `sdk_hash` and `session_id`: a random id minted when the app is created, and restored from disk by `update_app` whatever a rewritten manifest says. It is part of the key of the app's durable conversations (`app:<id>:<app_uid>:<client id>`), so an app deleted and re-created under the same id, or replaced through `create_app`, starts with none of the old app's conversations or shared state. An app created before the field existed has none and keeps the key `app:<id>:<client id>`, so its conversations still resume.
 - `kind` also reads `"agent"` as `"agentic"`, and writes it back as `"agentic"`.

From 4d9652bfab4fa9549a3f605307c14e91280d4f28 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 13:52:28 -0700
Subject: [PATCH 04/26] test(apps): pin the fallback bundler on the input
 reported in #386

The literal { omop_rules: OMOP_RULES, required_outputs: Object.keys(patient) }
keeps its values and builds, and the same literal across lines and the
local modules ./prevent and ./preventData are refused by line with nothing
written. The behaviour landed in a423670d5; this holds it to the reported
input rather than to a look-alike.
---
 .../biorouter-mcp/src/agent_drafter/bundle.rs | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/crates/biorouter-mcp/src/agent_drafter/bundle.rs b/crates/biorouter-mcp/src/agent_drafter/bundle.rs
index 0cb6bc100..5f22a4902 100644
--- a/crates/biorouter-mcp/src/agent_drafter/bundle.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/bundle.rs
@@ -3347,6 +3347,54 @@ mod tests {
         );
     }
 
+    /// Issue #386, the input that was reported. Without esbuild the stripper
+    /// turned `{ omop_rules: OMOP_RULES, required_outputs: Object.keys(patient) }`
+    /// into `{ omop_rules , required_outputs , … }`, and dropped the local
+    /// modules `./prevent` and `./preventData` without a word. The literal on
+    /// one line now keeps its values and builds; the same literal across lines
+    /// and the local modules are refused, by line, with nothing written.
+    #[test]
+    fn the_reported_literal_keeps_its_values_and_local_modules_are_refused() {
+        let literal =
+            "const req = { omop_rules: OMOP_RULES, required_outputs: Object.keys(patient) };";
+        assert_eq!(strip_colon_types(literal), literal);
+        let call = "  br.agent.send({ omop_rules: OMOP_RULES, required_outputs: Object.keys(p) });";
+        assert_eq!(strip_colon_types(call), call);
+
+        let sdk = "export function createApp(x: unknown) { globalThis.req = x; }\n";
+        let main = format!(
+            "import {{ createApp }} from \"./sdk\";\nconst OMOP_RULES = [\"r1\"];\n\
+             const patient = {{ age: 1 }};\n{literal}\ncreateApp(req);\n"
+        );
+        let dir = project(Some(sdk), &main);
+        let report = fallback_of(&dir);
+        assert!(report.ok, "{}", report.log);
+        let js = std::fs::read_to_string(dir.path().join("dist/app.js")).unwrap();
+        assert!(js.contains(literal), "{js}");
+        if let Some(parsed) = node_parses(&js) {
+            parsed.expect("the fallback bundle parses");
+        }
+
+        for (main, expect) in [
+            (
+                "import { createApp } from \"./sdk\";\nimport { risk } from \"./prevent\";\n\
+                 import { OMOP_RULES } from \"./preventData\";\ncreateApp(risk(OMOP_RULES));\n",
+                "./prevent\"",
+            ),
+            (
+                "import { createApp } from \"./sdk\";\nconst req = {\n  omop_rules: OMOP_RULES,\n  \
+                 required_outputs: Object.keys(patient),\n};\ncreateApp(req);\n",
+                "line 3",
+            ),
+        ] {
+            let dir = project(Some(sdk), main);
+            let report = fallback_of(&dir);
+            assert!(!report.ok, "refused: {main}");
+            assert!(report.log.contains(expect), "{main}\n---\n{}", report.log);
+            assert!(!dir.path().join("dist/app.js").exists(), "{main}");
+        }
+    }
+
     /// The banner is the bundle's own record of what built it, read back from
     /// the file; a bundle from before banners is recognised as a fallback only
     /// by the marker the stripper used to write.

From a67117377e34bc44031721731d439be0c0ddc78d Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 14:04:01 -0700
Subject: [PATCH 05/26] fix(WS-MOTION): final check, a toast in the corner no
 longer covers the Extensions page's load-failure actions

At 1440 the sticky '1 of 2 extensions loaded' report (1144 to 1424) covered the
right 32px of the load-failure notice's Copy error and all of its dismiss mark.
The stack has nowhere to go there that covers nothing (under the notice is the
list's first switch, beside the actions is the error), so the page's actions step
aside instead: a group marked data-toast-aside moves left while a toast stands
beside it, out from under it and 16px clear, never closer than 8px to the title
before it, as a translate (main.css 'toast clears the corner'), so nothing else
moves or rewraps. toastClearance measures it against the stack's target box,
gives it back when the toast goes or the watcher stops, follows scrolls, and
never moves it from under a resting pointer. The notice lays its title, actions
and error out in its own grid (the Note's slot cannot see the title), keeping
the error wrapped before the actions and the note 60px tall. Tests: a Chromium
case with the real notice in the real reading column, the real report and
container (fails before: Copy error and the X under the toast), hover hold, 1048;
unit cases for the step, its cap and the watcher; source pins.
---
 docs/desktop-ui/shared-controls.md            |   2 +
 .../alerts/toastAside.browser.test.tsx        | 341 ++++++++++++++++++
 .../components/alerts/toastClearance.test.ts  | 165 +++++++++
 .../src/components/alerts/toastClearance.ts   | 114 +++++-
 .../ExtensionLoadFailureNotice.test.tsx       |  19 +-
 .../extensions/ExtensionLoadFailureNotice.tsx |  40 +-
 .../extensions/extension-notice.css           |  33 +-
 .../extensionNoticeGeometry.browser.test.tsx  |   8 +-
 ui/desktop/src/styles/main.css                |  12 +
 9 files changed, 695 insertions(+), 39 deletions(-)
 create mode 100644 ui/desktop/src/components/alerts/toastAside.browser.test.tsx

diff --git a/docs/desktop-ui/shared-controls.md b/docs/desktop-ui/shared-controls.md
index 8f996ecf4..3ad713cfd 100644
--- a/docs/desktop-ui/shared-controls.md
+++ b/docs/desktop-ui/shared-controls.md
@@ -144,6 +144,8 @@ Crew is not converted. Its own recipes (`crew-*` classes) keep their lines; the
 
 A `Note`'s action is centred on the note's first line (`.br-note-action`): a 28px row pulled in by half its difference from the 12/16 line, so a one-line note with a Retry is as tall as one without (36px) and the words sit level with the button instead of 6px above its centre.
 
+Below about 1600 wide the 760px reading column reaches under the toast layer's top-right corner, so the trailing actions of a notice at the top of a page sit under any toast standing there. The toast cannot step around them, because everything near it is page content (below the notice is the list's first switch, beside its actions is its error). So the actions step aside instead: a group marked `data-toast-aside` moves left while a toast stands beside it, out from under the toast and 16px clear of it, and never closer than 8px to the element before it, the title its row names. `components/alerts/toastClearance.ts` measures it and main.css ("toast clears the corner") applies it as a `translate`, so nothing else on the page moves or rewraps, and it never moves from under a resting pointer. A `Note`'s own action slot runs the note's full height and cannot see the title, so a notice that needs this lays its title, actions and error out in its own grid. The Extensions page's load-failure notice is the one that does (final smoke, 2026-10-12); `alerts/toastAside.browser.test.tsx` measures it in Chromium.
+
 Inside a dark popover the ground is lifted to `--background-medium`, so the hairlines inside it are lifted too: `--border-subtle` and `--border-default` point at `--border-strong` there. On the lifted ground the old separator measured 1.05:1 and vanished; `--border-strong` gives back the 1.29:1 it had on the page.
 
 ## Fields and the cascade
diff --git a/ui/desktop/src/components/alerts/toastAside.browser.test.tsx b/ui/desktop/src/components/alerts/toastAside.browser.test.tsx
new file mode 100644
index 000000000..96fb3c37f
--- /dev/null
+++ b/ui/desktop/src/components/alerts/toastAside.browser.test.tsx
@@ -0,0 +1,341 @@
+// @vitest-environment node
+/**
+ * A toast in the corner never covers an action on the page under it (final smoke, 2026-10-12).
+ *
+ * On the Extensions page at 1440 the sticky "1 of 2 extensions loaded" report sat at 1144,44 to
+ * 1424,146, over the load-failure notice's actions: the right 32px of "Copy error" (1086 to 1176)
+ * and all of the dismiss mark. The stack has nowhere to go there that covers nothing (under the
+ * notice is the list's first switch, left of the actions is the error), so the notice's actions
+ * step left, out from under the stack, on the title's row and no closer to the title than 8px
+ * (`toastClearance.ts`, `data-toast-aside`). Nothing else on the page moves or rewraps, and the
+ * error keeps wrapping before the actions' column, clear of the stack.
+ *
+ * jsdom has no layout, so the real notice inside the real reading column (`ReadableContent`,
+ * `chat` size, `px-6`, under a 44px band beside a 288px sidebar, as `ExtensionsView` mounts it),
+ * the real extension-load report, the real react-toastify container as App.tsx configures it and
+ * the watcher App.tsx starts are bundled with esbuild, `styles/main.css` is compiled by Tailwind
+ * (the vendored ReactToastify.css after it, as App imports them, and the notice's own sheet), and
+ * Chromium measures.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { chromium, type Browser, type Page } from 'playwright';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const STYLES = resolve(here, '../../styles');
+const requireFromDesktop = createRequire(resolve(here, '../../../package.json'));
+
+const ERROR =
+  "invalid config: Failed to fetch secret 'CLINICAL_RECORDS_USERNAME' from config: " +
+  'Configuration value not found: CLINICAL_RECORDS_USERNAME';
+
+const ENTRY = `
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { MemoryRouter } from 'react-router-dom';
+import { ToastContainer, toast } from 'react-toastify';
+import { ReadableContent } from '../Layout/ReadableContent';
+import { ExtensionLoadFailureNotice } from '../extensions/ExtensionLoadFailureNotice';
+import { GroupedExtensionLoadingToast } from '../GroupedExtensionLoadingToast';
+import { recordExtensionLoadResults } from '../../utils/extensionLoadFailures';
+import { TOAST_SURFACE_CLASS_NAME } from './NotificationSurface';
+import { watchToastClearance } from './toastClearance';
+
+recordExtensionLoadResults([{ name: 'cdwagent', success: false, error: ${JSON.stringify(ERROR)} }]);
+
+function Harness() {
+  React.useEffect(() => watchToastClearance(), []);
+  return (
+    <MemoryRouter>
+      <div style={{ position: 'fixed', inset: 0, display: 'flex' }}>
+        <div style={{ width: 288, flex: 'none' }} />
+        <div style={{ flex: 1, minWidth: 0, display: 'flex', flexDirection: 'column' }}>
+          <div style={{ height: 44, flex: 'none' }} />
+          <ReadableContent size="chat" className="relative min-h-0 flex-1 px-6">
+            <div className="relative py-4">
+              <ExtensionLoadFailureNotice onAskBiorouter={() => {}} />
+              <div id="first-row" style={{ height: 40 }}>Crew</div>
+            </div>
+          </ReadableContent>
+        </div>
+      </div>
+      <ToastContainer
+        aria-label="Toast notifications"
+        toastClassName={() => TOAST_SURFACE_CLASS_NAME}
+        style={{
+          '--toastify-z-index': 'var(--z-toast)',
+          top: 'var(--toast-inset-top)',
+          width: 'fit-content',
+          minWidth: 'var(--toast-clear-width, 280px)',
+          maxWidth: 'var(--toast-clear-width, min(420px, calc(100vw - 32px)))',
+        } as React.CSSProperties}
+        position="top-right"
+        newestOnTop={false}
+        closeOnClick={false}
+        hideProgressBar
+        icon={false}
+      />
+    </MemoryRouter>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(<Harness />);
+const w = window as unknown as Record<string, unknown>;
+w.__toast = () =>
+  toast(
+    <GroupedExtensionLoadingToast
+      extensions={[
+        { name: 'crew', status: 'success' },
+        { name: 'cdwagent', status: 'error', error: 'invalid config' },
+      ]}
+      totalCount={2}
+      isComplete
+    />,
+    { autoClose: false, toastId: 'extension-load' }
+  );
+w.__dismiss = () => toast.dismiss('extension-load');
+`;
+
+const launchChromium = async (): Promise<Browser | null> => {
+  for (const options of [{}, { channel: 'chromium' }, { channel: 'chrome' }] as const) {
+    try {
+      return await chromium.launch(options);
+    } catch {
+      // try the next build
+    }
+  }
+  return null;
+};
+
+type Box = { left: number; top: number; right: number; bottom: number };
+type Action = Box & { name: string; reachable: boolean; hit: string };
+
+const TOAST = '.Toastify__toast-container > *';
+const NOTICE = '[data-testid="extension-load-failures"] [role="alert"]';
+
+const overlaps = (a: Box, b: Box) =>
+  a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+
+describe('a toast in the corner leaves the actions of the page under it reachable', () => {
+  let browser: Browser | null = null;
+  let script = '';
+  let css = '';
+
+  beforeAll(async () => {
+    browser = await launchChromium();
+    if (!browser) {
+      console.warn('No Chromium found: skipping the toast and in-page action tests.');
+      return;
+    }
+    const bundle = await build({
+      stdin: { contents: ENTRY, loader: 'tsx', resolveDir: here, sourcefile: 'entry.tsx' },
+      bundle: true,
+      write: false,
+      format: 'iife',
+      jsx: 'automatic',
+      platform: 'browser',
+      define: { 'process.env.NODE_ENV': '"production"' },
+      loader: { '.css': 'empty', '.svg': 'dataurl', '.png': 'dataurl' },
+      logLevel: 'silent',
+    });
+    script = bundle.outputFiles[0].text;
+    const { compile } = await import(requireFromDesktop.resolve('@tailwindcss/node'));
+    const { Scanner } = requireFromDesktop('@tailwindcss/oxide');
+    const compiler = await compile(readFileSync(resolve(STYLES, 'main.css'), 'utf8'), {
+      base: STYLES,
+      onDependency() {},
+    });
+    css =
+      compiler.build(new Scanner({}).scanFiles([{ content: script, extension: 'js' }])) +
+      '\n' +
+      readFileSync(requireFromDesktop.resolve('react-toastify/dist/ReactToastify.css'), 'utf8') +
+      '\n' +
+      readFileSync(resolve(here, '../extensions/extension-notice.css'), 'utf8');
+  }, 180_000);
+
+  afterAll(async () => {
+    await browser?.close();
+  }, 120_000);
+
+  async function open(width: number): Promise<Page> {
+    const page = await browser!.newPage({ viewport: { width, height: 900 } });
+    await page.setContent(
+      `<!doctype html><html class="light"><head><style>${css}</style></head>` +
+        `<body style="margin:0;background:var(--background-default)"><div id="root"></div></body></html>`
+    );
+    await page.addScriptTag({ content: script });
+    await page.waitForSelector(NOTICE);
+    return page;
+  }
+
+  /** Two frames, every finite animation finished, and a pause. */
+  const settle = (page: Page, ms = 150) =>
+    page.evaluate(
+      (wait) =>
+        new Promise<void>((done) =>
+          requestAnimationFrame(() =>
+            requestAnimationFrame(async () => {
+              await Promise.all(
+                document
+                  .getAnimations()
+                  .filter((a) => Number.isFinite(a.effect?.getComputedTiming().endTime ?? 0))
+                  .map((a) => a.finished.catch(() => undefined))
+              );
+              setTimeout(done, wait);
+            })
+          )
+        ),
+      ms
+    );
+
+  const call = (page: Page, fn: '__toast' | '__dismiss') =>
+    page.evaluate((name) => (window as unknown as Record<string, () => void>)[name](), fn);
+
+  const box = (page: Page, selector: string): Promise<Box> =>
+    page.evaluate((s) => {
+      const r = document.querySelector(s)!.getBoundingClientRect();
+      return { left: r.left, top: r.top, right: r.right, bottom: r.bottom };
+    }, selector);
+
+  /** Each of the notice's buttons: its box, and whether its centre and both ends take the pointer. */
+  const actions = (page: Page): Promise<Action[]> =>
+    page.evaluate((notice) => {
+      return [...document.querySelectorAll(`${notice} button`)].map((el) => {
+        const r = el.getBoundingClientRect();
+        const y = r.top + r.height / 2;
+        const probes = [r.left + 2, r.left + r.width / 2, r.right - 2].map((x) =>
+          document.elementFromPoint(x, y)
+        );
+        const miss = probes.find((hit) => !hit || !(hit === el || el.contains(hit)));
+        // The shown label only: Copy error keeps "Copied" in its cell, hidden, to hold its width.
+        const shown = [...el.querySelectorAll('span')].find(
+          (s) => !s.closest('[aria-hidden="true"]') && s.children.length === 0
+        );
+        return {
+          name: el.getAttribute('aria-label') ?? shown?.textContent ?? el.textContent ?? '',
+          left: r.left,
+          top: r.top,
+          right: r.right,
+          bottom: r.bottom,
+          reachable: miss === undefined,
+          hit: miss ? miss.outerHTML.slice(0, 80) : '',
+        };
+      });
+    }, NOTICE);
+
+  it('at rest the notice reads as the Extensions page draws it, its actions at the trailing edge (1440)', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const page = await open(1440);
+    try {
+      await settle(page);
+      const notice = await box(page, NOTICE);
+      // The page's geometry in the final smoke's screenshot: the reading column's 712px inside.
+      expect(notice.left).toBeCloseTo(508, 0);
+      expect(notice.top).toBeCloseTo(60, 0);
+      expect(notice.right).toBeCloseTo(1220, 0);
+      const all = await actions(page);
+      expect(all.map((a) => a.name)).toEqual(['Ask Biorouter', 'Copy error', 'Dismiss']);
+      // The dismiss mark ends at the note's 12px inner edge, and the error wraps 8px before the
+      // actions' column, as it did beside the Note's action slot.
+      expect(all[2].right).toBeCloseTo(notice.right - 12, 0);
+      const error = await box(page, `${NOTICE} .br-ext-notice-error`);
+      expect(error.right).toBeCloseTo(all[0].left - 8, 0);
+      for (const a of all) expect(a.reachable, `${a.name} hit ${a.hit}`).toBe(true);
+    } finally {
+      await page.close();
+    }
+  });
+
+  it('a sticky toast arrives: every action of the notice stays clear of it, and nothing below moves (1440)', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const page = await open(1440);
+    try {
+      await settle(page);
+      const noticeBefore = await box(page, NOTICE);
+      const rowBefore = await box(page, '#first-row');
+
+      await call(page, '__toast');
+      await page.waitForSelector(TOAST);
+      await settle(page, 300);
+      const toast = await box(page, TOAST);
+      // The stack keeps its corner: nothing in the corner is a surface it steps around.
+      expect(toast.top).toBeCloseTo(44, 0);
+      expect(toast.right).toBeCloseTo(1424, 0);
+      expect(overlaps(toast, noticeBefore), 'the toast does sit over the notice').toBe(true);
+
+      for (const a of await actions(page)) {
+        expect(a.reachable, `${a.name} hit ${a.hit}`).toBe(true);
+        expect(overlaps(a, toast), `${a.name} under the toast`).toBe(false);
+        // 16px clear of the stack, the gap it keeps beside the summary popover.
+        expect(a.right).toBeLessThanOrEqual(toast.left - 16 + 0.5);
+      }
+      // The notice, its height and the row under it stay where they were: only the actions moved.
+      expect(await box(page, NOTICE)).toEqual(noticeBefore);
+      expect(await box(page, '#first-row')).toEqual(rowBefore);
+      // The name and the error stay clear of the stack too: the error wraps before the actions'
+      // column, as it did in the Note's action slot, and the actions stop short of the name.
+      const name = await box(page, `${NOTICE} .br-ext-notice-name`);
+      const error = await box(page, `${NOTICE} .br-ext-notice-error`);
+      expect(overlaps(error, toast), 'the error under the toast').toBe(false);
+      expect(overlaps(name, toast), 'the name under the toast').toBe(false);
+      const [first] = await actions(page);
+      expect(first.left).toBeGreaterThanOrEqual(name.right + 8 - 0.5);
+    } finally {
+      await page.close();
+    }
+  });
+
+  it('the toast goes: the actions return to the trailing edge, but not from under a pointer resting on them', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const page = await open(1440);
+    try {
+      await settle(page);
+      const rest = await actions(page);
+      await call(page, '__toast');
+      await page.waitForSelector(TOAST);
+      await settle(page, 300);
+      const stepped = await actions(page);
+      expect(stepped[1].right).toBeLessThan(rest[1].right - 1);
+
+      // A pointer on Copy error holds the actions where they are when the toast goes.
+      const copy = stepped[1];
+      await page.mouse.move((copy.left + copy.right) / 2, (copy.top + copy.bottom) / 2);
+      await call(page, '__dismiss');
+      await page.waitForSelector(TOAST, { state: 'detached' });
+      await settle(page, 300);
+      expect((await actions(page))[1]).toMatchObject({ left: copy.left, right: copy.right });
+
+      // Away from them, they go back to the trailing edge.
+      await page.mouse.move(400, 600);
+      await settle(page, 300);
+      const back = await actions(page);
+      for (let i = 0; i < rest.length; i++) {
+        expect(back[i].left).toBeCloseTo(rest[i].left, 0);
+        expect(back[i].right).toBeCloseTo(rest[i].right, 0);
+      }
+    } finally {
+      await page.close();
+    }
+  });
+
+  it('at the narrowest window the actions stay reachable beside a standing toast (1048)', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const page = await open(1048);
+    try {
+      await call(page, '__toast');
+      await page.waitForSelector(TOAST);
+      await settle(page, 300);
+      const toast = await box(page, TOAST);
+      for (const a of await actions(page)) {
+        expect(a.reachable, `${a.name} hit ${a.hit}`).toBe(true);
+        expect(overlaps(a, toast), `${a.name} under the toast`).toBe(false);
+      }
+    } finally {
+      await page.close();
+    }
+  });
+});
diff --git a/ui/desktop/src/components/alerts/toastClearance.test.ts b/ui/desktop/src/components/alerts/toastClearance.test.ts
index c130461fc..f4c9ea70d 100644
--- a/ui/desktop/src/components/alerts/toastClearance.test.ts
+++ b/ui/desktop/src/components/alerts/toastClearance.test.ts
@@ -11,7 +11,11 @@ import {
   TOAST_CLEAR_Y,
   TOAST_OBSTACLES,
   TOAST_PLACED_ATTRIBUTE,
+  TOAST_ASIDE,
+  TOAST_ASIDE_ATTRIBUTE,
+  TOAST_ASIDE_SIBLING_GAP,
   toastClearance,
+  toastAside,
   watchToastClearance,
   type ClearanceBox,
 } from './toastClearance';
@@ -205,6 +209,54 @@ describe('toastClearance: where the stack goes', () => {
   });
 });
 
+/**
+ * Final smoke (2026-10-12), the Extensions page at 1440: the sticky "1 of 2 extensions loaded"
+ * report at 1144,44 to 1424,146 stood over the load-failure notice's actions, which end at the
+ * note's 12px inner edge (1208): Copy error ran 1086 to 1176, the dismiss mark after it. The
+ * notice's name, "CDWAgent failed to load", ends at 697 on the same row.
+ */
+const REPORT_1440 = box(1144, 44, 1424, 146);
+const NOTICE_ACTIONS_1440 = box(975, 66, 1208, 94);
+const NOTICE_NAME_1440 = box(544, 70, 697, 90);
+
+describe('toastAside: how far a group of page actions steps aside', () => {
+  it('moves out from under the stack and 16px clear of it (the finding at 1440)', () => {
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, NOTICE_NAME_1440)).toBe(
+      NOTICE_ACTIONS_1440.right - (REPORT_1440.left - TOAST_CLEAR_BESIDE_GAP)
+    );
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, NOTICE_NAME_1440)).toBe(80);
+  });
+
+  it('is zero with no stack, or one with no area', () => {
+    expect(toastAside(null, NOTICE_ACTIONS_1440)).toBe(0);
+    expect(toastAside(box(1144, 44, 1144, 44), NOTICE_ACTIONS_1440)).toBe(0);
+  });
+
+  it('is zero for actions above or below the stack, however far right they reach', () => {
+    expect(toastAside(REPORT_1440, box(975, 150, 1208, 178))).toBe(0);
+    expect(toastAside(box(1144, 102, 1424, 204), NOTICE_ACTIONS_1440)).toBe(0);
+  });
+
+  it('keeps the gap for actions that end just short of the stack, and leaves them alone past it', () => {
+    expect(toastAside(REPORT_1440, box(903, 66, 1136, 94))).toBe(8);
+    expect(toastAside(REPORT_1440, box(895, 66, 1128, 94))).toBe(0);
+  });
+
+  it('stops 8px short of the name before them on their row, even with the stack still there', () => {
+    const longName = box(544, 70, 920, 90);
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, longName)).toBe(
+      NOTICE_ACTIONS_1440.left - (longName.right + TOAST_ASIDE_SIBLING_GAP)
+    );
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, longName)).toBe(47);
+    // Already touching: nowhere to go, and never right.
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, box(544, 70, 980, 90))).toBe(0);
+  });
+
+  it('is not held back by an element on another row', () => {
+    expect(toastAside(REPORT_1440, NOTICE_ACTIONS_1440, box(544, 96, 1200, 128))).toBe(80);
+  });
+});
+
 describe('TOAST_OBSTACLES names surfaces that exist', () => {
   /**
    * The selectors are other owners' class names (find in chat, the summary rail and popover),
@@ -232,6 +284,31 @@ describe('TOAST_OBSTACLES names surfaces that exist', () => {
   });
 });
 
+describe('the page actions that step aside, and the rule that moves them', () => {
+  /**
+   * The attribute is written in another owner's component and read here and in main.css, so a
+   * rename on any side would silently put the toast back over the notice's actions.
+   */
+  it('the load-failure notice marks its actions, right after its name', () => {
+    const source = readFileSync(
+      join(__dirname, '../extensions/ExtensionLoadFailureNotice.tsx'),
+      'utf8'
+    );
+    expect(source).toContain(`<div className="br-ext-notice-actions" ${TOAST_ASIDE_ATTRIBUTE}="">`);
+    // The name is the element before them: the one the step stops short of.
+    expect(source.indexOf('br-ext-notice-name')).toBeLessThan(
+      source.indexOf('br-ext-notice-actions')
+    );
+  });
+
+  it('main.css turns the step into a translate, so nothing else moves', () => {
+    const css = readFileSync(join(__dirname, '../../styles/main.css'), 'utf8');
+    expect(css).toContain(
+      `[${TOAST_ASIDE_ATTRIBUTE}] {\n  translate: calc(-1 * var(${TOAST_ASIDE}, 0px)) 0;\n}`
+    );
+  });
+});
+
 describe('watchToastClearance', () => {
   let stop: (() => void) | null = null;
 
@@ -349,6 +426,94 @@ describe('watchToastClearance', () => {
     expect(el.style.getPropertyValue(TOAST_CLEAR_Y)).toBe('0px');
   });
 
+  /**
+   * The final smoke's page at 1440: the notice's name and its actions, and the report standing
+   * over them. The actions' box follows their own `translate`, as the browser's does.
+   */
+  function smokePage() {
+    Object.defineProperty(document.documentElement, 'clientWidth', {
+      configurable: true,
+      value: 1440,
+    });
+    Object.defineProperty(document.documentElement, 'clientHeight', {
+      configurable: true,
+      value: BOTTOM,
+    });
+    const section = layer();
+    const row = document.createElement('div');
+    row.appendChild(sized(document.createElement('div'), NOTICE_NAME_1440));
+    const actions = document.createElement('div');
+    actions.getBoundingClientRect = () => {
+      const shift = parseFloat(actions.style.getPropertyValue(TOAST_ASIDE)) || 0;
+      const r = NOTICE_ACTIONS_1440;
+      return {
+        left: r.left - shift,
+        right: r.right - shift,
+        top: r.top,
+        bottom: r.bottom,
+        x: r.left - shift,
+        y: r.top,
+        width: r.right - r.left,
+        height: r.bottom - r.top,
+      } as DOMRect;
+    };
+    actions.setAttribute(TOAST_ASIDE_ATTRIBUTE, '');
+    row.appendChild(actions);
+    document.body.appendChild(row);
+    const report = () => {
+      const el = sized(document.createElement('div'), REPORT_1440);
+      el.className = 'Toastify__toast-container Toastify__toast-container--top-right';
+      el.style.top = '44px';
+      el.style.right = '16px';
+      section.appendChild(el);
+      return el;
+    };
+    return { actions, report };
+  }
+
+  it('steps a page’s actions aside while a toast stands beside them, and back when it goes', async () => {
+    const { actions, report } = smokePage();
+    stop = watchToastClearance();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('');
+    const el = report();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('80px');
+    el.remove();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('');
+  });
+
+  it('keeps the actions under a resting pointer when the toast goes, until the pointer leaves', async () => {
+    const { actions, report } = smokePage();
+    let hovered = false;
+    actions.matches = (selector: string) =>
+      selector === ':hover' ? hovered : Element.prototype.matches.call(actions, selector);
+    stop = watchToastClearance();
+    const el = report();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('80px');
+    hovered = true;
+    el.remove();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('80px');
+    hovered = false;
+    actions.dispatchEvent(new Event('pointerleave'));
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('');
+  });
+
+  it('gives the actions back when it stops watching', async () => {
+    const { actions, report } = smokePage();
+    stop = watchToastClearance();
+    report();
+    await frames();
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('80px');
+    stop();
+    stop = null;
+    expect(actions.style.getPropertyValue(TOAST_ASIDE)).toBe('');
+  });
+
   it('stops following the page once the last toast has gone', async () => {
     Object.defineProperty(document.documentElement, 'clientWidth', {
       configurable: true,
diff --git a/ui/desktop/src/components/alerts/toastClearance.ts b/ui/desktop/src/components/alerts/toastClearance.ts
index 97516a766..e87b7dce2 100644
--- a/ui/desktop/src/components/alerts/toastClearance.ts
+++ b/ui/desktop/src/components/alerts/toastClearance.ts
@@ -43,6 +43,19 @@
  * instead of sliding there), never while the window or the sidebar is being resized, and not
  * under reduced motion. The width snaps: it changes by at most the 52px between the stack's 280
  * and the rail's narrowest card.
+ *
+ * The page's own actions are the one case where the stack stays and the page steps aside. Below
+ * about 1600 wide the 760px reading column reaches under the stack's corner, so a page whose first
+ * line carries actions at its trailing edge has them under the stack: the final smoke (2026-10-12)
+ * found the sticky "1 of 2 extensions loaded" over the Extensions page's load-failure notice, the
+ * right 32px of "Copy error" and all of its dismiss mark. There the stack has nowhere to go that
+ * covers nothing: under the notice is the list's first switch, left of the actions is the error
+ * itself. So a group of such actions says so (`data-toast-aside`), and while the stack stands
+ * beside it the watcher writes how far it moves left (`--toast-aside`: out from under the stack
+ * and 16px clear of it, but never closer than 8px to the element before it, the title its row
+ * names). main.css "toast clears the corner" turns that into a `translate`, so nothing else on the
+ * page moves or rewraps. It snaps, and it never goes back from under a pointer resting on it: it
+ * returns once the pointer leaves.
  */
 
 /** The gap under a surface the stack moves below: the find bar's own gap under the band. */
@@ -66,6 +79,12 @@ export const TOAST_CLEAR_Y = '--toast-clear-y';
 export const TOAST_CLEAR_WIDTH = '--toast-clear-width';
 /** Set on a container one frame after its first placement; main.css glides only then. */
 export const TOAST_PLACED_ATTRIBUTE = 'data-toast-placed';
+/** Marks a group of in-page trailing actions that steps left, out from under the stack. */
+export const TOAST_ASIDE_ATTRIBUTE = 'data-toast-aside';
+/** Written on such a group while the stack stands beside it: how far left it moves, in px. */
+export const TOAST_ASIDE = '--toast-aside';
+/** A group stepping aside stops this far short of the element before it on its row. */
+export const TOAST_ASIDE_SIBLING_GAP = 8;
 
 const CONTAINER = '.Toastify__toast-container';
 
@@ -164,27 +183,89 @@ export function toastClearance(
   return joined === undefined ? { x, y } : { x, y, width: joined };
 }
 
+/**
+ * How far a group of in-page actions moves left, from where it rests (`group`), so none of it sits
+ * under the stack or within the 16px gap the stack keeps beside a surface. Zero when the stack
+ * (where it stands, after its own moves) is not beside the group, or there is no stack. Never so
+ * far that it comes within 8px of `before`, the element before it, when that shares its row: a
+ * group squeezed against its title stops there, even if the stack still reaches it.
+ */
+export function toastAside(
+  stack: ClearanceBox | null,
+  group: ClearanceBox,
+  before: ClearanceBox | null = null
+): number {
+  if (!stack || !hasArea(stack) || !hasArea(group)) return 0;
+  if (!overlaps(stack, { ...group, right: group.right + TOAST_CLEAR_BESIDE_GAP })) return 0;
+  const clear = group.right - (stack.left - TOAST_CLEAR_BESIDE_GAP);
+  const sameRow = before && before.top < group.bottom && group.top < before.bottom;
+  const room = sameRow ? group.left - (before.right + TOAST_ASIDE_SIBLING_GAP) : Infinity;
+  return Math.max(0, Math.min(clear, room));
+}
+
 /**
  * Keep the toast container clear of the corner's surfaces for as long as it exists. Returns the
  * cleanup. App.tsx calls it once, beside the `ToastContainer`.
  *
  * Nothing is watched while there is no toast: an observer on the toast layer notices the
  * container arrive and leave, and only while it is there does a second one follow the page
- * (find opening, the rail docking, the popover opening, a resize, an animation ending), each
- * coalesced into one measurement per frame.
+ * (find opening, the rail docking, the popover opening, a resize, an animation ending, a scroll),
+ * each coalesced into one measurement per frame. When it leaves, one last pass gives the page's
+ * actions their place back, and so does the cleanup.
  */
 export function watchToastClearance(doc: Document = document): () => void {
   const win = doc.defaultView;
   if (!win || typeof MutationObserver === 'undefined' || !doc.body) return () => {};
 
   let frame = 0;
+  let stopped = false;
   let placed: HTMLElement | null = null;
   let page: MutationObserver | null = null;
+  const held = new WeakSet<Element>();
+
+  /**
+   * Step each `data-toast-aside` group out from under the stack where it stands (`at`), or back
+   * when it is gone (`null`). A group under a resting pointer stays where it is until the pointer
+   * leaves it, so it never moves out from under a click (checklist 14).
+   */
+  const stepAside = (at: ClearanceBox | null) => {
+    for (const group of doc.querySelectorAll<HTMLElement>(`[${TOAST_ASIDE_ATTRIBUTE}]`)) {
+      const now = parseFloat(group.style.getPropertyValue(TOAST_ASIDE)) || 0;
+      // Where it rests: its box, less the move it already makes.
+      const r = group.getBoundingClientRect();
+      const rest = { left: r.left + now, top: r.top, right: r.right + now, bottom: r.bottom };
+      const prev = group.previousElementSibling?.getBoundingClientRect();
+      const before = prev
+        ? { left: prev.left, top: prev.top, right: prev.right, bottom: prev.bottom }
+        : null;
+      const next = toastAside(at, rest, before);
+      if (Math.abs(next - now) < 0.5) continue;
+      if (next < now && group.matches(':hover')) {
+        if (!held.has(group)) {
+          held.add(group);
+          group.addEventListener(
+            'pointerleave',
+            () => {
+              held.delete(group);
+              schedule();
+            },
+            { once: true }
+          );
+        }
+        continue;
+      }
+      if (next > 0) group.style.setProperty(TOAST_ASIDE, `${next}px`);
+      else group.style.removeProperty(TOAST_ASIDE);
+    }
+  };
 
   const place = () => {
     frame = 0;
     const container = doc.querySelector<HTMLElement>(CONTAINER);
-    if (!container) return;
+    if (!container) {
+      stepAside(null);
+      return;
+    }
     const style = win.getComputedStyle(container);
     const right = doc.documentElement.clientWidth - (parseFloat(style.right) || 0);
     const top = parseFloat(style.top) || 0;
@@ -225,11 +306,23 @@ export function watchToastClearance(doc: Document = document): () => void {
       placed = container;
       win.requestAnimationFrame(() => container.setAttribute(TOAST_PLACED_ATTRIBUTE, ''));
     }
+    // Where the stack stands once moved (its target, not a frame of the glide), at the width it
+    // is taking: the page's actions step aside from that.
+    const span = width ?? stack.right - stack.left;
+    stepAside({
+      left: stack.right - x - span,
+      right: stack.right - x,
+      top: stack.top + y,
+      bottom: stack.bottom + y,
+    });
   };
 
-  const schedule = () => {
-    if (!frame) frame = win.requestAnimationFrame(place);
-  };
+  // Hoisted, as a held group's `pointerleave` above calls it; `view` carries the narrowing a
+  // hoisted function does not see on `win`.
+  const view: Window = win;
+  function schedule() {
+    if (!frame && !stopped) frame = view.requestAnimationFrame(place);
+  }
 
   const follow = () => {
     if (page) return;
@@ -238,6 +331,8 @@ export function watchToastClearance(doc: Document = document): () => void {
     win.addEventListener('resize', schedule);
     doc.addEventListener('animationend', schedule, true);
     doc.addEventListener('transitionend', schedule, true);
+    // Actions scrolled into, or out from beside, a standing stack.
+    doc.addEventListener('scroll', schedule, true);
   };
 
   const unfollow = () => {
@@ -247,6 +342,7 @@ export function watchToastClearance(doc: Document = document): () => void {
     win.removeEventListener('resize', schedule);
     doc.removeEventListener('animationend', schedule, true);
     doc.removeEventListener('transitionend', schedule, true);
+    doc.removeEventListener('scroll', schedule, true);
   };
 
   const sync = () => {
@@ -255,6 +351,8 @@ export function watchToastClearance(doc: Document = document): () => void {
       schedule();
     } else {
       unfollow();
+      // One more pass with no stack, if one stood: the page's actions go back.
+      if (placed) schedule();
       placed = null;
     }
   };
@@ -269,9 +367,13 @@ export function watchToastClearance(doc: Document = document): () => void {
   sync();
 
   return () => {
+    stopped = true;
     layer.disconnect();
     unfollow();
     if (frame) win.cancelAnimationFrame(frame);
     frame = 0;
+    for (const group of doc.querySelectorAll<HTMLElement>(`[${TOAST_ASIDE_ATTRIBUTE}]`)) {
+      group.style.removeProperty(TOAST_ASIDE);
+    }
   };
 }
diff --git a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
index 4433e587f..ce133b8ec 100644
--- a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
+++ b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
@@ -94,10 +94,13 @@ describe('ExtensionLoadFailureNotice', () => {
 
   /**
    * Compact (spec 3.11): ONE danger note holds the title, the error and every action. The two
-   * text actions and the round X share the note's trailing slot, with no second row of buttons
-   * under the error, and the note is followed by 16px, not 24.
+   * text actions and the round X share one group at the trailing edge, on the title's row, with
+   * no second row of buttons under the error, and the note is followed by 16px, not 24. The
+   * group sits in the notice's own grid rather than in the Note's action slot so that it can
+   * step aside from a toast standing over the column's right end, as far as the title before it
+   * allows (final smoke; `data-toast-aside`, `alerts/toastAside.browser.test.tsx` measures it).
    */
-  it('keeps its actions in the one trailing slot: two quiet text actions and a round X', () => {
+  it('keeps its actions in one group after the title: two quiet text actions and a round X', () => {
     recordExtensionLoadResults([{ name: 'cdwagent', success: false, error: 'spawn ENOENT' }]);
     const { container } = render(<ExtensionLoadFailureNotice onAskBiorouter={vi.fn()} />);
 
@@ -108,9 +111,13 @@ describe('ExtensionLoadFailureNotice', () => {
       COPY.copyError,
       COPY.dismiss,
     ]);
-    // All three sit in the note's action slot, which is its last child; none is under the text.
-    const slot = alert.lastElementChild as HTMLElement;
-    for (const button of buttons) expect(slot).toContainElement(button);
+    // All three sit in the one group that steps aside from a toast, right after the title (the
+    // element it stops short of); none is under the error.
+    const group = alert.querySelector('[data-toast-aside]') as HTMLElement;
+    for (const button of buttons) expect(group).toContainElement(button);
+    expect(group.previousElementSibling).toHaveTextContent(COPY.failedToLoad('CDWAgent'));
+    expect(group.nextElementSibling).toHaveTextContent('spawn ENOENT');
+    expect(group.nextElementSibling?.querySelector('button')).toBeNull();
     // Quiet: ghost, not the `secondary` wash the second row used to carry.
     expect(buttons[0].className).toMatch(/bg-transparent/);
     expect(buttons[1].className).toMatch(/bg-transparent/);
diff --git a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
index b94285b29..b9511673e 100644
--- a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
+++ b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
@@ -74,15 +74,23 @@ export function ExtensionLoadFailureNotice({
   return (
     <div className="mb-4 flex flex-col gap-2" data-testid="extension-load-failures">
       {failures.map((failure) => (
-        <Note
-          key={failure.name}
-          tone="danger"
-          role="alert"
-          icon={AlertCircle}
-          action={
-            // Two quiet text actions and a round X, in the Note's one trailing slot: the notice
-            // is a line and its error, not a card with a second row of buttons under it.
-            <div className="br-ext-notice-actions">
+        <Note key={failure.name} tone="danger" role="alert" icon={AlertCircle}>
+          {/* A line and its error, with the actions in a column at the trailing edge: two quiet
+              text actions and a round X, centred on the title, with no second row of buttons
+              under the error, which wraps before them. The Note's own action slot did this, but
+              its slot cannot see the title beside it, and the actions now step aside: below about
+              1600 wide the toast layer's corner reaches over the reading column's right end, and
+              the sticky extension-load report there covered Copy error and the X (final smoke).
+              While a toast stands beside them, `data-toast-aside` moves them left, out from under
+              it, as far as the title allows (`alerts/toastClearance.ts`); the error and
+              everything below stay put. */}
+          <div className="br-ext-notice-body">
+            {/* The extension's name as the catalogue spells it (CDWAgent), never its config key
+                title-cased (Cdwagent): principle 10, and the name the Extensions row uses. */}
+            <div className="br-ext-notice-name text-label text-text-default">
+              {LOAD_FAILURE_COPY.failedToLoad(extensionDisplayName(failure.name))}
+            </div>
+            <div className="br-ext-notice-actions" data-toast-aside="">
               {onAskBiorouter && (
                 <Button
                   size="sm"
@@ -116,17 +124,11 @@ export function ExtensionLoadFailureNotice({
                 onSelect={() => dismissExtensionLoadFailure(failure.name)}
               />
             </div>
-          }
-        >
-          {/* The extension's name as the catalogue spells it (CDWAgent), never its config key
-              title-cased (Cdwagent): principle 10, and the name the Extensions row uses. */}
-          <div className="text-label text-text-default">
-            {LOAD_FAILURE_COPY.failedToLoad(extensionDisplayName(failure.name))}
+            {/* The error, which the Note clamps behind "Show more" past its ceiling. This
+                surface has room, and the toast's hard truncation is what sent people looking
+                for details in the first place. */}
+            <div className="br-ext-notice-error mt-1 [overflow-wrap:anywhere]">{failure.error}</div>
           </div>
-          {/* The error, which the Note clamps behind "Show more" past its ceiling. This
-              surface has room, and the toast's hard truncation is what sent people looking for
-              details in the first place. */}
-          <div className="mt-1 [overflow-wrap:anywhere]">{failure.error}</div>
         </Note>
       ))}
     </div>
diff --git a/ui/desktop/src/components/extensions/extension-notice.css b/ui/desktop/src/components/extensions/extension-notice.css
index 79358ed7f..389f6f2e5 100644
--- a/ui/desktop/src/components/extensions/extension-notice.css
+++ b/ui/desktop/src/components/extensions/extension-notice.css
@@ -5,15 +5,38 @@
  * to generate (CLAUDE.md, "Desktop shell geometry").
  */
 
-/* A Note centres its action on a 16px first line (`.br-note-action`, calibrated for 12px prose).
-   This notice opens with a 20px title line (`text-label`), so the buttons sat 2px above the title's
-   middle (measured: 78 against 80, with the glyph already on 80). The 2px of top padding moves
-   the row's middle to the title's, and the notice keeps its height. */
+/* The name and its error in the first column, the actions in a second at the trailing edge, on the
+   name's row: the layout the Note's action slot gave this notice, 8px apart as the Note spaces its
+   slot, so the error wraps before the actions. The actions live in this grid rather than in that
+   slot so they can step aside from a toast standing over the column's right end
+   (`data-toast-aside`, main.css "toast clears the corner"), at most as far as the name before
+   them: the name keeps its own width (`justify-self: start`), which is what the watcher measures
+   that limit against. */
+.br-ext-notice-body {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  column-gap: 8px;
+  align-items: center;
+}
+
+.br-ext-notice-name {
+  grid-area: 1 / 1;
+  justify-self: start;
+}
+
+.br-ext-notice-error {
+  grid-area: 2 / 1;
+}
+
+/* Centred on the 20px name row, as the glyph is (the Note's slot centred on a 16px first line, 2px
+   above the name's middle). A 28px control on a 20px row is pulled in by half the difference on
+   both sides, so the row stays 20px and the notice stays as tall as its text. */
 .br-ext-notice-actions {
+  grid-area: 1 / 2;
   display: flex;
   align-items: center;
   gap: 4px;
-  padding-top: 2px;
+  margin-block: calc((var(--text-label--line-height, 20px) - var(--control-sm, 28px)) / 2);
 }
 
 /* A label that swaps for another in place (the Copy error button, `StableLabel`): both labels share
diff --git a/ui/desktop/src/components/extensions/extensionNoticeGeometry.browser.test.tsx b/ui/desktop/src/components/extensions/extensionNoticeGeometry.browser.test.tsx
index 999bfd3e7..633556729 100644
--- a/ui/desktop/src/components/extensions/extensionNoticeGeometry.browser.test.tsx
+++ b/ui/desktop/src/components/extensions/extensionNoticeGeometry.browser.test.tsx
@@ -5,9 +5,11 @@
  * A `Note` centres its action on a 16px first line (`.br-note-action`, calibrated for 12px
  * prose). This notice opens with a 20px title line, so its two text actions and the dismiss mark
  * hung 2px above the title's middle (78 against 80 in the browser), with the glyph already on 80.
- * jsdom has no layout, so the middle of the title and the middle of each action can only be
- * compared here. This renders the real `ExtensionLoadFailureNotice` to markup and lays it out in
- * Chromium with the Note's own action rule cut from `main.css` and `extension-notice.css`.
+ * They now sit in the notice's own grid, on the title's row (so they can step aside from a
+ * toast, final smoke), centred on it with the row kept at 20px. jsdom has no layout, so the
+ * middle of the title and the middle of each action can only be compared here. This renders the
+ * real `ExtensionLoadFailureNotice` to markup and lays it out in Chromium with the Note's own
+ * action rule cut from `main.css` and `extension-notice.css`.
  *
  * Second case (vision round 6, V3-R4-5): Copy error turned into the narrower Copied for two
  * seconds and Ask Biorouter, beside it, slid 22px right and back. That one needs the click, so
diff --git a/ui/desktop/src/styles/main.css b/ui/desktop/src/styles/main.css
index 5c7c75d9e..75c0c8da5 100644
--- a/ui/desktop/src/styles/main.css
+++ b/ui/desktop/src/styles/main.css
@@ -2563,6 +2563,18 @@ body.biorouter-sidebar-resizing .Toastify__toast-container {
     transition: none;
   }
 }
+
+/* The page's own actions are the one thing the stack does not step around: below about 1600 wide
+   the reading column reaches under its corner, and there is nowhere for it to go that covers
+   nothing (final smoke: the Extensions page's load-failure notice had "Copy error" and its
+   dismiss mark under the sticky extension-load report, with the list's first switch under the
+   notice). So a group of trailing actions is marked `data-toast-aside`, and while the stack
+   stands beside it `toastClearance.ts` writes how far to move left, out from under the stack
+   and 16px clear of it, never past the element before it, as `--toast-aside`. A `translate`, so
+   nothing else on the page moves or rewraps; it snaps, as the stack's own first placement does. */
+[data-toast-aside] {
+  translate: calc(-1 * var(--toast-aside, 0px)) 0;
+}
 /* @ws WS-MOTION end: toast clears the corner */
 
 /* @ws WS-MOTION begin: toast yields to an open menu */

From c3bbebbede2f11ef314d9bdac5c63682c898c032 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 14:56:13 -0700
Subject: [PATCH 06/26] fix(WS-MOTION): the Extensions page's failure notice
 takes the place of the failure toast

The live check of a67117377 found the rest of the same defect: once the
load-failure notice was dismissed, the sticky '1 of 2 extensions loaded'
stood over the list's first switch, at 1440 and at 1048 wide. The page
already says what the toast says, with the error and its actions, so while
the notice is mounted it is the announcement: a failure recorded then is
shown there and counted announced, no toast is raised for it, and a failure
toast already standing (the grouped report or the single one) is taken down
when the notice shows a failure. Progress and clean-run reports are left
alone. Leaving the page does not re-announce a failure it showed.

Tests: the reporting rules with a notice on screen and after it closes, the
withdrawal of each failure toast (and only those), and the notice's presence
and withdrawal on mount and on a failure recorded while it is open.
---
 .../ExtensionLoadFailureNotice.test.tsx       | 34 +++++++-
 .../extensions/ExtensionLoadFailureNotice.tsx | 15 +++-
 ui/desktop/src/toasts.tsx                     | 18 +++-
 .../src/utils/extensionErrorUtils.test.ts     | 86 ++++++++++++++++++-
 ui/desktop/src/utils/extensionErrorUtils.ts   | 45 ++++++++--
 ui/desktop/src/utils/extensionLoadFailures.ts | 29 +++++++
 6 files changed, 214 insertions(+), 13 deletions(-)

diff --git a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
index ce133b8ec..fd9d6ff1b 100644
--- a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
+++ b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.test.tsx
@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { render, screen, fireEvent, within } from '@testing-library/react';
+import { act, render, screen, fireEvent, within } from '@testing-library/react';
 import fs from 'node:fs';
 import path from 'node:path';
 import { ExtensionLoadFailureNotice } from './ExtensionLoadFailureNotice';
@@ -8,7 +8,14 @@ import {
   recordExtensionLoadResults,
   resetExtensionLoadFailuresForTests,
   getExtensionLoadFailures,
+  isExtensionLoadFailureNoticeShown,
 } from '../../utils/extensionLoadFailures';
+import { withdrawExtensionFailureToasts } from '../../utils/extensionErrorUtils';
+
+vi.mock('../../utils/extensionErrorUtils', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('../../utils/extensionErrorUtils')>()),
+  withdrawExtensionFailureToasts: vi.fn(),
+}));
 
 /**
  * Defect 1, second half. The recurring toast pointed at the Extensions page and
@@ -26,6 +33,31 @@ function shownText(button: HTMLElement): string {
 describe('ExtensionLoadFailureNotice', () => {
   beforeEach(() => {
     resetExtensionLoadFailuresForTests();
+    vi.mocked(withdrawExtensionFailureToasts).mockClear();
+  });
+
+  // Final check (2026-10-12): the corner's sticky report of the same failure stood over the page,
+  // over Copy error and, once the notice was dismissed, over the list's first switch.
+  it('takes the place of the failure toast while the page is open', () => {
+    const { unmount } = render(<ExtensionLoadFailureNotice />);
+    expect(isExtensionLoadFailureNoticeShown()).toBe(true);
+    expect(withdrawExtensionFailureToasts).not.toHaveBeenCalled();
+
+    // A failure recorded while the page is open is shown here, and its toast taken down.
+    act(() => {
+      recordExtensionLoadResults([{ name: 'cdwagent', success: false, error: 'spawn ENOENT' }]);
+    });
+    expect(screen.getByText(COPY.failedToLoad('CDWAgent'))).toBeInTheDocument();
+    expect(withdrawExtensionFailureToasts).toHaveBeenCalled();
+
+    unmount();
+    expect(isExtensionLoadFailureNoticeShown()).toBe(false);
+  });
+
+  it('withdraws the failure toast when the page opens on a standing failure', () => {
+    recordExtensionLoadResults([{ name: 'cdwagent', success: false, error: 'spawn ENOENT' }]);
+    render(<ExtensionLoadFailureNotice />);
+    expect(withdrawExtensionFailureToasts).toHaveBeenCalled();
   });
 
   it('renders nothing when nothing has failed', () => {
diff --git a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
index b9511673e..73477a32b 100644
--- a/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
+++ b/ui/desktop/src/components/extensions/ExtensionLoadFailureNotice.tsx
@@ -7,10 +7,14 @@ import { extensionDisplayName } from '../settings/extensions/extensionDisplayNam
 import {
   dismissExtensionLoadFailure,
   getExtensionLoadFailures,
+  showingExtensionLoadFailureNotice,
   subscribeExtensionLoadFailures,
   type ExtensionLoadFailure,
 } from '../../utils/extensionLoadFailures';
-import { createExtensionRecoverHints } from '../../utils/extensionErrorUtils';
+import {
+  createExtensionRecoverHints,
+  withdrawExtensionFailureToasts,
+} from '../../utils/extensionErrorUtils';
 import { useTransientValue } from '../../hooks/useTransientFlag';
 import { LOAD_FAILURE_COPY } from './copy';
 import './extension-notice.css';
@@ -69,6 +73,15 @@ export function ExtensionLoadFailureNotice({
     return subscribeExtensionLoadFailures(() => setFailures(getExtensionLoadFailures()));
   }, []);
 
+  // While this page is open it is where a load failure is announced, including one recorded while
+  // it is open, and the corner's report of the same failure is taken down rather than left over
+  // the page's controls: once this notice was dismissed, the sticky "1 of 2 extensions loaded"
+  // covered the list's first switch (final check, 2026-10-12). See `extensionLoadFailures.ts`.
+  useEffect(() => showingExtensionLoadFailureNotice(), []);
+  useEffect(() => {
+    if (failures.length > 0) withdrawExtensionFailureToasts();
+  }, [failures]);
+
   if (failures.length === 0) return null;
 
   return (
diff --git a/ui/desktop/src/toasts.tsx b/ui/desktop/src/toasts.tsx
index 8d7c728de..ae48f3d3f 100644
--- a/ui/desktop/src/toasts.tsx
+++ b/ui/desktop/src/toasts.tsx
@@ -51,14 +51,14 @@ class ToastService {
     }
   }
 
-  error(props: ToastErrorProps): void {
-    if (!this.silent) {
-      toastError(props);
-    }
+  /** Answers the toast's id, so a caller can take it down again; undefined while silent. */
+  error(props: ToastErrorProps): string | number | undefined {
+    const id = this.silent ? undefined : toastError(props);
 
     if (this.shouldThrow) {
       throw new Error(props.msg);
     }
+    return id;
   }
 
   loading({ title, msg }: { title: string; msg: string }): string | number | undefined {
@@ -88,6 +88,16 @@ class ToastService {
     if (toastId) toast.dismiss(toastId);
   }
 
+  /**
+   * Take down the grouped extension report if it is reporting a FAILURE. Progress is left alone,
+   * and so is a clean run, which expires on its own. See `withdrawExtensionFailureToasts`.
+   */
+  dismissExtensionFailureReport(): void {
+    if (this.extensionToastHasErrors && toast.isActive(EXTENSION_TOAST_ID)) {
+      toast.dismiss(EXTENSION_TOAST_ID);
+    }
+  }
+
   /**
    * Whether the grouped extension toast is still on screen. Lets a caller avoid
    * overwriting a live failure report with a later success — see
diff --git a/ui/desktop/src/utils/extensionErrorUtils.test.ts b/ui/desktop/src/utils/extensionErrorUtils.test.ts
index 0d4a0aeab..a4bcb1756 100644
--- a/ui/desktop/src/utils/extensionErrorUtils.test.ts
+++ b/ui/desktop/src/utils/extensionErrorUtils.test.ts
@@ -3,14 +3,21 @@ import {
   showExtensionLoadResults,
   setFocusedChatSession,
   resetExtensionToastState,
+  withdrawExtensionFailureToasts,
 } from './extensionErrorUtils';
-import { resetExtensionLoadFailuresForTests } from './extensionLoadFailures';
+import {
+  getExtensionLoadFailures,
+  resetExtensionLoadFailuresForTests,
+  showingExtensionLoadFailureNotice,
+} from './extensionLoadFailures';
 import { toastService } from '../toasts';
 
 vi.mock('../toasts', () => ({
   toastService: {
     extensionLoading: vi.fn(),
     error: vi.fn(),
+    dismiss: vi.fn(),
+    dismissExtensionFailureReport: vi.fn(),
     isExtensionToastActive: vi.fn(() => false),
   },
 }));
@@ -270,3 +277,80 @@ describe('a failure is announced once, not on every renderer load', () => {
     expect(toastService.extensionLoading).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * Final check (2026-10-12). With the Extensions page open, the sticky "1 of 2 extensions loaded"
+ * stood in the corner over the page: first over the notice's Copy error, and once the notice was
+ * dismissed, over the list's first switch. The page already says the same thing with the error
+ * and its actions, so while its notice is on screen the notice is the announcement, and the
+ * corner's report of the same failure is taken down.
+ */
+describe("the Extensions page announces a failure in the toast's place", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    resetExtensionToastState();
+    resetExtensionLoadFailuresForTests();
+    vi.mocked(toastService.isExtensionToastActive).mockReturnValue(false);
+  });
+
+  it('raises no toast while the notice is on screen, and counts the failure announced', () => {
+    const release = showingExtensionLoadFailureNotice();
+    showExtensionLoadResults([ok('medcp'), bad('cdwagent')], 'chat-a');
+    showExtensionLoadResults([bad('notion-mcp')], 'chat-a');
+
+    expect(toastService.extensionLoading).not.toHaveBeenCalled();
+    expect(toastService.error).not.toHaveBeenCalled();
+    expect(getExtensionLoadFailures().map((f) => [f.name, f.announced])).toEqual(
+      expect.arrayContaining([
+        ['cdwagent', true],
+        ['notion-mcp', true],
+      ])
+    );
+
+    // Leaving the page does not bring it back as a toast on the next load: it was announced.
+    release();
+    showExtensionLoadResults([ok('medcp'), bad('cdwagent')], 'chat-a');
+    expect(toastService.extensionLoading).not.toHaveBeenCalled();
+  });
+
+  it('toasts a new failure again once the page has closed, and a release counts once', () => {
+    const release = showingExtensionLoadFailureNotice();
+    const second = showingExtensionLoadFailureNotice();
+    release();
+    release();
+    showExtensionLoadResults([bad('notion-mcp')], 'chat-a');
+    expect(toastService.error).not.toHaveBeenCalled();
+
+    second();
+    showExtensionLoadResults([bad('cdwagent')], 'chat-a');
+    expect(toastService.error).toHaveBeenCalledTimes(1);
+  });
+
+  it('withdraws the toasts that reported a failure', () => {
+    vi.mocked(toastService.error).mockReturnValue('single-failure');
+    showExtensionLoadResults([bad('notion-mcp')], 'chat-a');
+    withdrawExtensionFailureToasts();
+    expect(toastService.dismiss).toHaveBeenCalledWith('single-failure');
+
+    vi.mocked(toastService.dismiss).mockClear();
+    vi.mocked(toastService.dismissExtensionFailureReport).mockClear();
+    showExtensionLoadResults([ok('medcp'), bad('cdwagent')], 'chat-a');
+    withdrawExtensionFailureToasts();
+    expect(toastService.dismissExtensionFailureReport).toHaveBeenCalledTimes(1);
+    expect(toastService.dismiss).not.toHaveBeenCalled();
+
+    // Each is taken down once; a second withdrawal has nothing left to take.
+    withdrawExtensionFailureToasts();
+    expect(toastService.dismissExtensionFailureReport).toHaveBeenCalledTimes(1);
+    expect(toastService.dismiss).not.toHaveBeenCalled();
+  });
+
+  it('leaves a progress or clean-run report alone', () => {
+    setFocusedChatSession('chat-a');
+    showExtensionLoadResults([ok('medcp'), ok('cdwagent')], 'chat-a');
+    withdrawExtensionFailureToasts();
+
+    expect(toastService.dismiss).not.toHaveBeenCalled();
+    expect(toastService.dismissExtensionFailureReport).not.toHaveBeenCalled();
+  });
+});
diff --git a/ui/desktop/src/utils/extensionErrorUtils.ts b/ui/desktop/src/utils/extensionErrorUtils.ts
index 2f6c84e97..91d32e53b 100644
--- a/ui/desktop/src/utils/extensionErrorUtils.ts
+++ b/ui/desktop/src/utils/extensionErrorUtils.ts
@@ -6,6 +6,7 @@ import { ExtensionLoadResult } from '../api/types.gen';
 import { toastService, ExtensionLoadingStatus } from '../toasts';
 import { isCapabilityExtension } from '../components/settings/capabilities/capabilities';
 import {
+  isExtensionLoadFailureNoticeShown,
   markExtensionLoadFailuresAnnounced,
   recordExtensionLoadResults,
 } from './extensionLoadFailures';
@@ -57,6 +58,9 @@ let focusedChatSessionId: string | null = null;
 /** True while the extension toast currently on screen is reporting a failure. */
 let extensionToastIsFailure = false;
 
+/** The single-failure toast last raised here, so the standing notice can take it down. */
+let singleFailureToastId: string | number | null = null;
+
 /**
  * Called by the chat shell as the active group changes. Readiness is only news
  * for the chat you are reading; see `showExtensionLoadResults`.
@@ -69,6 +73,26 @@ export function setFocusedChatSession(sessionId: string | null): void {
 export function resetExtensionToastState(): void {
   focusedChatSessionId = null;
   extensionToastIsFailure = false;
+  singleFailureToastId = null;
+}
+
+/**
+ * Take down the toasts that reported an extension load failure. The Extensions page's standing
+ * notice calls it whenever it shows failures: from then on the page carries that news, with the
+ * error and its actions, and the corner's report of it would only stand over the page's controls
+ * (`isExtensionLoadFailureNoticeShown` in `extensionLoadFailures.ts` has the case). A progress or
+ * clean-run report is not a failure report, and is left alone.
+ */
+export function withdrawExtensionFailureToasts(): void {
+  if (singleFailureToastId !== null) {
+    toastService.dismiss(singleFailureToastId);
+    singleFailureToastId = null;
+  }
+  if (extensionToastIsFailure) {
+    toastService.dismissExtensionFailureReport();
+    // Nothing on screen reports a failure now, so rule 2 has nothing left to protect.
+    extensionToastIsFailure = false;
+  }
 }
 
 /**
@@ -155,6 +179,14 @@ export function showExtensionLoadResults(
   // overwritten by a later clean run. It is only excluded from the *ratio*.
   const anyFailure = failedExtensions.length > 0 || shippedFailures.length > 0;
 
+  if (anyFailure && isExtensionLoadFailureNoticeShown()) {
+    // The Extensions page is open, and the record written above has already put these failures
+    // in its notice, with the error and something to do about it. That is their announcement; a
+    // toast saying the same thing would stand over the page's own controls.
+    markExtensionLoadFailuresAnnounced(unannounced.map((entry) => entry.name));
+    return;
+  }
+
   if (anyFailure && unannounced.length === 0) {
     // Every failure here has already had its one announcement. Repeating it is
     // the recurrence this rule exists to stop; the Extensions page still shows
@@ -185,12 +217,13 @@ export function showExtensionLoadResults(
     const recoverHints = createExtensionRecoverHints(errorMsg);
     const displayMsg = formatExtensionErrorMessage(errorMsg, 'Failed to load extension');
 
-    toastService.error({
-      title: failed.name,
-      msg: displayMsg,
-      traceback: errorMsg,
-      recoverHints,
-    });
+    singleFailureToastId =
+      toastService.error({
+        title: failed.name,
+        msg: displayMsg,
+        traceback: errorMsg,
+        recoverHints,
+      }) ?? null;
     // Only now — a failure that was never rendered has not been announced, and
     // must keep its one announcement for the load that does render it.
     markExtensionLoadFailuresAnnounced([failed.name]);
diff --git a/ui/desktop/src/utils/extensionLoadFailures.ts b/ui/desktop/src/utils/extensionLoadFailures.ts
index 81c86df0e..cc187f0e3 100644
--- a/ui/desktop/src/utils/extensionLoadFailures.ts
+++ b/ui/desktop/src/utils/extensionLoadFailures.ts
@@ -171,6 +171,34 @@ export function markExtensionLoadFailuresAnnounced(names: readonly string[]): vo
   write(current.map((entry) => (wanted.has(entry.name) ? { ...entry, announced: true } : entry)));
 }
 
+/**
+ * How many standing notices are on screen: the Extensions page's, from mount to unmount.
+ *
+ * While one is, the page is where a failure is announced. It lists every failure in this record,
+ * including one recorded while it is open (it subscribes), with the error text and something to do
+ * about it, so the corner's report of the same failure adds nothing and stands over the page's own
+ * controls. The final check (2026-10-12) found exactly that: once the notice's Dismiss had taken
+ * the notice away, the sticky "1 of 2 extensions loaded" covered the list's first switch, at 1440
+ * and at 1048 wide. `showExtensionLoadResults` asks this before it raises a failure toast.
+ */
+let noticesOnScreen = 0;
+
+/** The notice calls this on mount; the function it answers takes the presence back, once. */
+export function showingExtensionLoadFailureNotice(): () => void {
+  noticesOnScreen += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    noticesOnScreen -= 1;
+  };
+}
+
+/** Whether a standing notice is on screen to announce a failure in the toast's place. */
+export function isExtensionLoadFailureNoticeShown(): boolean {
+  return noticesOnScreen > 0;
+}
+
 /** Drop one extension's record — the Dismiss control on the standing notice. */
 export function dismissExtensionLoadFailure(name: string): void {
   const current = read();
@@ -181,6 +209,7 @@ export function dismissExtensionLoadFailure(name: string): void {
 /** Test seam — the record is persistent by design, so it must be cleared explicitly. */
 export function resetExtensionLoadFailuresForTests(): void {
   cache = null;
+  noticesOnScreen = 0;
   try {
     localStorage.removeItem(STORAGE_KEY);
   } catch {

From fcc83fdcd7a4c3efe29dafa2159cf86cba8702fa Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:03:49 -0700
Subject: [PATCH 07/26] feat(crew): Crew is a Biorouter capability, switched in
 Settings, not an extension

Crew ships with Biorouter (PLATFORM_EXTENSIONS["crew"]) and the daemon already
classified it as a capability, but the desktop's CAPABILITIES list left it out,
so it still showed on the Extensions page, in its count, in the Tools popover
and in the load toast's denominator. It is now a capability row in
Settings > Chat > Capabilities, labelled Crew, with the same switch: the row
writes the same crew entry in config.yaml the Extensions page did, so a saved
on or off carries over with no migration. A chat connected with /crew and a
Crew task still get the tools from their grant, and only Revoke ends access.

- capabilities.ts: add the crew entry (default on) and its InfoTip.
- Tools popover: drop the Crew row lock (crewLocked, lockedByCrew,
  accessCopy.extensionLocked, isCrewExtensionName), dead once the row is gone.
- /ext: palette: Crew is listed as a capability; its row reads
  "Crew tools (advanced)".
- Rust: display name "Crew" for /ext: messages, crew in the capability name
  table and defaults test, and a crew_is_a_capability test.
- CLI status line: count extensions with ExtensionConfig::is_capability instead
  of a stale six-key list that counted Crew and seven other capabilities.
- Docs: Crew listed with the capabilities; landing/docs.html regenerated.
---
 crates/biorouter-cli/src/session/tui/mod.rs   | 34 +++------
 crates/biorouter/src/agents/extension.rs      | 16 ++++
 .../biorouter/src/agents/extension_manager.rs |  1 +
 crates/biorouter/src/config/extensions.rs     |  2 +
 docs/crew/agents-and-chat-access.md           |  2 +
 docs/extensions/README.md                     |  2 +-
 docs/extensions/built-in/README.md            |  1 +
 .../extensions/extensions-and-skills-guide.md |  1 +
 docs/getting-started/installation.md          |  2 +-
 docs/website/pages/extensions.html            |  2 +-
 landing/docs.html                             |  2 +-
 .../MentionPopover.crewRows.test.tsx          |  2 +-
 ui/desktop/src/components/MentionPopover.tsx  |  7 +-
 .../BottomMenuExtensionSelection.tsx          | 46 +++---------
 ui/desktop/src/components/composer/copy.ts    |  4 +-
 .../components/crew/access/chatCrewAccess.ts  | 14 +---
 ui/desktop/src/components/crew/access/copy.ts |  2 -
 ...ck.test.tsx => crewIsACapability.test.tsx} | 73 ++++++++-----------
 .../src/components/crew/access/index.ts       |  3 +-
 .../extensions/ExtensionsView.test.tsx        |  1 +
 .../capabilities/CapabilitiesSection.test.tsx | 44 ++++++++++-
 .../capabilities/capabilities.test.ts         | 10 ++-
 .../settings/capabilities/capabilities.ts     | 19 +++++
 .../chatRowsGeometry.browser.test.tsx         |  2 +-
 .../extensions/ExtensionsSection.test.tsx     | 26 +++++++
 25 files changed, 187 insertions(+), 131 deletions(-)
 rename ui/desktop/src/components/crew/access/{crewExtensionLock.test.tsx => crewIsACapability.test.tsx} (53%)

diff --git a/crates/biorouter-cli/src/session/tui/mod.rs b/crates/biorouter-cli/src/session/tui/mod.rs
index f70ad5ae9..ca5ffedb2 100644
--- a/crates/biorouter-cli/src/session/tui/mod.rs
+++ b/crates/biorouter-cli/src/session/tui/mod.rs
@@ -1590,33 +1590,17 @@ fn count_skills() -> usize {
     count_user_skills_in(&list_skills())
 }
 
-/// The six foundational built-ins surfaced as their own "Capabilities" section
-/// in the GUI and intentionally excluded from the extension list/count there
-/// (see ui/desktop/.../capabilities/capabilities.ts). The CLI status line was
-/// counting them as extensions, so it showed e.g. 11 where the GUI shows 5.
-/// Keys are normalized like the GUI's `nameToKey` (whitespace removed, lowercased).
-const CAPABILITY_KEYS: [&str; 6] = [
-    "developer",
-    "extensionmanager",
-    "skills",
-    "todo",
-    "memory",
-    "knowledge",
-];
-
-fn name_to_key(name: &str) -> String {
-    name.chars()
-        .filter(|c| !c.is_whitespace())
-        .collect::<String>()
-        .to_lowercase()
-}
-
-/// Enabled extensions, excluding the foundational capabilities — matches the
-/// count the GUI shows.
+/// Enabled extensions, excluding Biorouter's own capabilities, which the GUI
+/// lists in Settings → Chat → Capabilities and leaves out of every extension
+/// count (`ui/desktop/.../capabilities/capabilities.ts`). It asks
+/// `ExtensionConfig::is_capability`, the daemon's own classification, rather
+/// than a list of keys here: the list this replaced named six of the fourteen
+/// capabilities, so the status line counted Biorouter Copilot, Crew, Workspace
+/// Control and five more as extensions the person had installed.
 fn count_non_capability_extensions() -> usize {
     biorouter::config::get_enabled_extensions()
         .iter()
-        .filter(|ext| !CAPABILITY_KEYS.contains(&name_to_key(&ext.name()).as_str()))
+        .filter(|ext| !ext.is_capability())
         .count()
 }
 
@@ -2411,7 +2395,7 @@ mod tests {
     /// (#77). The five Contexts are seeded into the same directory on every
     /// start, so before this exclusion the terminal reported "5 skills" on a
     /// machine with none and disagreed with the GUI chip about the same word —
-    /// the drift `CAPABILITY_KEYS` already fixes for extensions.
+    /// the drift `count_non_capability_extensions` already fixes for extensions.
     ///
     /// Nothing asserted it. `count_skills` reads the real config directory, and
     /// on the common machine (contexts seeded, no user skills) the filtered and
diff --git a/crates/biorouter/src/agents/extension.rs b/crates/biorouter/src/agents/extension.rs
index 66d030ead..60e88ad13 100644
--- a/crates/biorouter/src/agents/extension.rs
+++ b/crates/biorouter/src/agents/extension.rs
@@ -954,9 +954,25 @@ mod tests {
         assert!(PLATFORM_EXTENSIONS["extensionmanager"].default_enabled);
         assert!(PLATFORM_EXTENSIONS["skills"].default_enabled);
         assert!(PLATFORM_EXTENSIONS["code_execution"].default_enabled);
+        assert!(PLATFORM_EXTENSIONS["crew"].default_enabled);
         assert!(!PLATFORM_EXTENSIONS["chatrecall"].default_enabled);
     }
 
+    /// Crew is a capability, not an extension: the desktop lists it in Settings → Chat →
+    /// Capabilities and leaves it off the Extensions page, and this side agrees, so Extension
+    /// Manager refuses to enable or disable it (`capability_management_refusal`) and the
+    /// agent's extension listings leave it out.
+    #[test]
+    fn crew_is_a_capability() {
+        let crew = ExtensionConfig::Platform {
+            name: "crew".to_string(),
+            description: String::new(),
+            bundled: Some(true),
+            available_tools: Vec::new(),
+        };
+        assert!(crew.is_capability());
+    }
+
     #[test]
     fn builtin_transport_is_not_itself_a_capability_classification() {
         let capability = ExtensionConfig::Builtin {
diff --git a/crates/biorouter/src/agents/extension_manager.rs b/crates/biorouter/src/agents/extension_manager.rs
index 30c995a1b..0841b000e 100644
--- a/crates/biorouter/src/agents/extension_manager.rs
+++ b/crates/biorouter/src/agents/extension_manager.rs
@@ -5615,6 +5615,7 @@ mod tests {
             ("Todo", "todo"),
             ("Web & Documents", "webdocuments"),
             ("Agent Drafter", "agent_drafter"),
+            ("Crew", "crew"),
         ] {
             let target = resolve_bundled_extension(label).expect(label);
             assert_eq!(target.key(), id);
diff --git a/crates/biorouter/src/config/extensions.rs b/crates/biorouter/src/config/extensions.rs
index fe1e1709a..a4f9c1a76 100644
--- a/crates/biorouter/src/config/extensions.rs
+++ b/crates/biorouter/src/config/extensions.rs
@@ -230,6 +230,8 @@ pub fn bundled_extension_display_name(name: &str) -> Option<&'static str> {
         "code_execution" => return Some("Code Execution"),
         "skills" => return Some("Skills"),
         "todo" => return Some("Todo"),
+        // A capability in the desktop's Settings, named as its row there names it.
+        "crew" => return Some("Crew"),
         _ => {}
     }
     BUILTIN_EXTENSION_METADATA
diff --git a/docs/crew/agents-and-chat-access.md b/docs/crew/agents-and-chat-access.md
index ab36ae831..8ac52a17f 100644
--- a/docs/crew/agents-and-chat-access.md
+++ b/docs/crew/agents-and-chat-access.md
@@ -145,6 +145,8 @@ The chat sees its channels' messages much as you do, with posts by an agent mark
 
 It cannot use other Biorouter tools (no shell, web or local files), post elsewhere, act as another person, change memberships or privacy, or grant or revoke its own access. Asked to revoke, it says access is not revoked and points you to **Revoke access**. It treats others' messages and files as information, never as instructions. These limits stay permanently, even after access ends.
 
+The chat's Crew tools are one of Biorouter's capabilities, not an extension, so they are not on the **Extensions** page or in the **Tools** chip's list. The **Crew** switch in **Settings** > **Chat** > **Capabilities** sets whether new chats start with them. A chat you connect gets them with its access whatever the switch says. Turning the switch off does not end a chat's access; **Revoke access** does.
+
 ### A chat's fixed channel and model
 
 The first grant fixes the chat's workspace, channel and model permanently, and a later grant keeps its earlier "Also read" channels. Crew refuses any other channel, workspace or model. In such a chat, **Switch models** says "This chat's model is fixed by its Crew access. Start a new chat to use another model." and offers no other model. **Diverge**, which copies a chat into a new window, shows "Diverge failed" and "Could not diverge this chat.", or the chat's access message once access has ended. Exporting the chat and creating a workflow from it are refused too, with a sentence that says why. **Make this chat public** in the chat history is refused with "This chat read Crew channels, so it can't be made public. Start a new chat for public work." For other work:
diff --git a/docs/extensions/README.md b/docs/extensions/README.md
index d1b68cba9..12baa9d31 100644
--- a/docs/extensions/README.md
+++ b/docs/extensions/README.md
@@ -16,7 +16,7 @@ Come here when you want to install an extension, understand a shipped capability
 
 ## Built-in capability reference
 
-The [`built-in/`](built-in/README.md) subdirectory holds one user-facing reference page per built-in capability: Developer, Biorouter Copilot, Web & Documents, Memory, Auto Visualiser, Chat Recall, Code Execution, Extension Manager, Skills, Todo and Workspace Control.
+The [`built-in/`](built-in/README.md) subdirectory holds one user-facing reference page per built-in capability: Developer, Biorouter Copilot, Web & Documents, Memory, Auto Visualiser, Chat Recall, Code Execution, Extension Manager, Skills, Todo and Workspace Control. Crew is a capability too, and its guide lives with the rest of Crew: [Agents and chat access](../crew/agents-and-chat-access.md).
 
 Two pages are worth knowing about before you go. [Developer](built-in/developer.md) carries the most substantive security guidance, and [Biorouter Copilot](built-in/computer-controller.md) documents the highest-blast-radius capability because it acts on your real desktop.
 
diff --git a/docs/extensions/built-in/README.md b/docs/extensions/built-in/README.md
index 7e515c488..221d7b570 100644
--- a/docs/extensions/built-in/README.md
+++ b/docs/extensions/built-in/README.md
@@ -13,6 +13,7 @@ Come here when you want to know what a specific built-in capability can do, or w
 | [Code Execution](code-execution.md) | Code Mode: instead of calling MCP tools one at a time, the model writes a short JavaScript program that batches many tool calls into a single execution. |
 | [Biorouter Copilot](computer-controller.md) | Native application observation, capture and control with per-chat task approval. |
 | [Web & Documents](web-documents.md) | URL fetching, document utilities, and cache tools independent of the desktop runtime. |
+| [Crew](../../crew/agents-and-chat-access.md) | The `crew__connections` and `crew__request` tools a chat uses to read the Crew channels it was connected to with `/crew` and post updates there. Its switch in Settings → Chat → Capabilities sets whether new chats start with the tools; a chat you connect gets them from its grant either way, and only Revoke ends that access. The page lives with the rest of the Crew guide. |
 | [Developer](developer.md) | A walkthrough of the Developer capability and its code, file, image, and shell tools, plus a reference on constraining it with permission modes, tool permissions, and `.biorouterignore`. |
 | [Extension Manager](extension-manager.md) | How BioRouter discovers other extensions and attaches or detaches them mid-session so the active tool count stays small — and how it searches the trusted BAAM marketplace to install a package you do not have, or permanently delete one you no longer want. |
 | [Memory](memory.md) | The trigger words that store, recall, and forget memories, where memories live on disk, and a worked example teaching BioRouter a lab's analysis standards. Predates the Knowledge feature; the page explains how the two relate. |
diff --git a/docs/extensions/extensions-and-skills-guide.md b/docs/extensions/extensions-and-skills-guide.md
index 50a844ffc..058384ae7 100644
--- a/docs/extensions/extensions-and-skills-guide.md
+++ b/docs/extensions/extensions-and-skills-guide.md
@@ -39,6 +39,7 @@ Additional in-process capabilities:
 | **Chat Recall** | Search conversation content across all session history | Disabled |
 | **Code Execution** | Execute JavaScript in a sandboxed environment for tool discovery and calling | Enabled |
 | **Workspace Control** | Work across conversations and delegate to visible subagents | Enabled |
+| **Crew** | Lets a chat you connect with `/crew` read its Crew channels and post updates there. A chat has Crew tools only once you grant it access, and only Revoke ends that access. | Enabled |
 
 ### The Extensions page
 
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index a2a9b8de3..ae9ff5e9c 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -150,7 +150,7 @@ biorouter configure
 # Select "Add Extension" > "Built-in Extension"
 ```
 
-Available built-in capabilities: Developer, Biorouter Copilot, Web & Documents, Memory, Auto Visualiser, Knowledge, Agent Drafter, Code Execution, Extension Manager, Skills, Todo, and Workspace Control are enabled by default. Chat Recall ships disabled by default. You can change any of these choices in Settings → Chat → Capabilities.
+Available built-in capabilities: Developer, Biorouter Copilot, Web & Documents, Memory, Auto Visualiser, Knowledge, Agent Drafter, Code Execution, Extension Manager, Skills, Todo, Workspace Control, and Crew are enabled by default. Chat Recall ships disabled by default. You can change any of these choices in Settings → Chat → Capabilities.
 
 ### Add external MCP servers
 
diff --git a/docs/website/pages/extensions.html b/docs/website/pages/extensions.html
index b600453ac..3d6fc6e17 100644
--- a/docs/website/pages/extensions.html
+++ b/docs/website/pages/extensions.html
@@ -94,7 +94,7 @@ <h2 id="extensions-switches">Turn extensions on and off</h2>
   <thead><tr><th>Where</th><th>What it changes</th></tr></thead>
   <tbody>
     <tr><td>The switch beside an extension on the <strong>Extensions</strong> page</td><td>Whether new chats start with it.</td></tr>
-    <tr><td><strong>Settings → Chat → Capabilities</strong></td><td>Which built-in extensions new chats start with. Crew is the exception: its switch is on the Extensions page.</td></tr>
+    <tr><td><strong>Settings → Chat → Capabilities</strong></td><td>Which built-in extensions new chats start with, Crew included.</td></tr>
     <tr><td>The <strong>Tools</strong> chip in the composer, on its <strong>Extensions</strong> list</td><td>This chat only. The choice is saved with the chat. The built-in extensions under Capabilities are not in this list.</td></tr>
     <tr><td>The Extension Manager, when the agent attaches one</td><td>This chat only, until it ends.</td></tr>
     <tr><td><code>biorouter configure</code>, then <strong>Toggle Extensions</strong></td><td>Whether new chats start with it, from a terminal.</td></tr>
diff --git a/landing/docs.html b/landing/docs.html
index ca0c5f3e3..9a7f2708e 100644
--- a/landing/docs.html
+++ b/landing/docs.html
@@ -1084,7 +1084,7 @@ <h2 id="extensions-switches">Turn extensions on and off</h2>
   <thead><tr><th>Where</th><th>What it changes</th></tr></thead>
   <tbody>
     <tr><td>The switch beside an extension on the <strong>Extensions</strong> page</td><td>Whether new chats start with it.</td></tr>
-    <tr><td><strong>Settings → Chat → Capabilities</strong></td><td>Which built-in extensions new chats start with. Crew is the exception: its switch is on the Extensions page.</td></tr>
+    <tr><td><strong>Settings → Chat → Capabilities</strong></td><td>Which built-in extensions new chats start with, Crew included.</td></tr>
     <tr><td>The <strong>Tools</strong> chip in the composer, on its <strong>Extensions</strong> list</td><td>This chat only. The choice is saved with the chat. The built-in extensions under Capabilities are not in this list.</td></tr>
     <tr><td>The Extension Manager, when the agent attaches one</td><td>This chat only, until it ends.</td></tr>
     <tr><td><code>biorouter configure</code>, then <strong>Toggle Extensions</strong></td><td>Whether new chats start with it, from a terminal.</td></tr>
diff --git a/ui/desktop/src/components/MentionPopover.crewRows.test.tsx b/ui/desktop/src/components/MentionPopover.crewRows.test.tsx
index 710112cce..5e5bfab1a 100644
--- a/ui/desktop/src/components/MentionPopover.crewRows.test.tsx
+++ b/ui/desktop/src/components/MentionPopover.crewRows.test.tsx
@@ -158,7 +158,7 @@ describe('the / palette’s Crew rows', () => {
       const items = ref.current?.getDisplayFiles() ?? [];
       expect(items.some((item) => item.itemType === 'Builtin' && item.name === 'crew')).toBe(false);
       expect(await screen.findByText(CREW_EXTENSION_DESCRIPTION)).toBeInTheDocument();
-      expect(CREW_EXTENSION_DESCRIPTION).toBe('Crew tools extension (advanced)');
+      expect(CREW_EXTENSION_DESCRIPTION).toBe('Crew tools (advanced)');
       expect(screen.queryByText(/human-approved channel context/)).toBeNull();
     }
   );
diff --git a/ui/desktop/src/components/MentionPopover.tsx b/ui/desktop/src/components/MentionPopover.tsx
index 59e7f2a72..42c17a17c 100644
--- a/ui/desktop/src/components/MentionPopover.tsx
+++ b/ui/desktop/src/components/MentionPopover.tsx
@@ -78,12 +78,13 @@ export const CREW_COMMAND_BEFORE_FIRST_MESSAGE = COMPOSER_COPY.commands.crewBefo
 // first for any query it starts with. Round 3 still found the second row confusing, so the
 // extension's row is left out of any list that shows the `/crew` command. It stays reachable: a
 // query aimed at extensions ("/ext", "/ext:crew") never matches the command, so that list shows
-// the extension's row — labelled as the tools, for someone who knows they want them.
+// the row, labelled as the tools, for someone who knows they want them. Crew is a capability now,
+// so the row is `ext:Crew` from `CAPABILITIES` and is there whether or not the chat has it on.
 
-/** The Crew extension's row, when a query reaches it without the `/crew` command. */
+/** The Crew capability's `/ext:` row, when a query reaches it without the `/crew` command. */
 export const CREW_EXTENSION_DESCRIPTION = COMPOSER_COPY.commands.crewExtension;
 
-/** The Crew platform extension's key (as `isCrewExtensionName` in `crew/access` reads it). */
+/** The Crew capability's key (`crew` in `CAPABILITIES`, the daemon's `PLATFORM_EXTENSIONS`). */
 const isCrewExtensionItem = (item: DisplayItem) =>
   item.itemType === 'Extension' && item.relativePath.trim().toLowerCase() === 'crew';
 
diff --git a/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.tsx b/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.tsx
index cff307062..7dfdad9f2 100644
--- a/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.tsx
+++ b/ui/desktop/src/components/bottom_menu/BottomMenuExtensionSelection.tsx
@@ -11,8 +11,6 @@ import { ExtensionConfig, getSessionExtensions } from '../../api';
 import { userActionHeaders } from '../../utils/userAction';
 import { addToAgent, removeFromAgent } from '../settings/extensions/agent-api';
 import { extensionPairingRefused } from '../settings/extensions/extensionPrivacy';
-import { isCrewExtensionName, useChatCrewAccessState } from '../crew/access/chatCrewAccess';
-import { accessCopy } from '../crew/access/copy';
 import { useBoundProviderTier } from '../privacy/useBoundProviderTier';
 import { setExtensionOverride, getExtensionOverrides } from '../../store/extensionOverrides';
 import { CATALOG_CHANGED_EVENT } from '../../utils/catalogSubscription';
@@ -51,7 +49,6 @@ export interface ExtensionRow {
   /** The name a person reads, as the catalogue spells it (see `extensionDisplayName`). */
   title: string;
   pairingRefused: boolean;
-  lockedByCrew: boolean;
   disabled: boolean;
   pending: boolean;
 }
@@ -88,10 +85,6 @@ export function useExtensionPicker(
    * on it — a tier nobody could read must not wall a working tool.
    */
   const pairingTier = useBoundProviderTier();
-  // A Crew-scoped chat's access ends only through Revoke. Switching the Crew extension off leaves
-  // the grant active, so while it is active the Crew row stays on and says where Revoke is. Read
-  // from the chat's own lookup; this menu never fetches it.
-  const crewAccessState = useChatCrewAccessState(sessionId);
   const [searchQuery, setSearchQuery] = useState('');
   const isOpen = open;
   const onOpenRequestRef = useRef(onOpenRequest);
@@ -363,17 +356,9 @@ export function useExtensionPicker(
    * leaves the fourth looking broken, which is the failure this state exists to
    * remove.
    */
-  const crewLocked = useCallback(
-    (ext: FixedExtensionEntry) =>
-      crewAccessState === 'active' && ext.enabled && isCrewExtensionName(ext.name),
-    [crewAccessState]
-  );
   const toggleableExtensions = useMemo(
-    () =>
-      sortedExtensions.filter(
-        (ext) => !extensionPairingRefused(ext.name, pairingTier) && !crewLocked(ext)
-      ),
-    [sortedExtensions, pairingTier, crewLocked]
+    () => sortedExtensions.filter((ext) => !extensionPairingRefused(ext.name, pairingTier)),
+    [sortedExtensions, pairingTier]
   );
 
   /**
@@ -382,9 +367,10 @@ export function useExtensionPicker(
    * Two independent decisions, and they are easy to conflate:
    *
    * 1. *What is counted* — user-installed extensions only. Shipped capabilities
-   *    (Developer, Biorouter Copilot, Auto Visualiser, Memory, Knowledge,
-   *    Agent Drafter, Todo, Chat Recall, Extension Manager, Code Execution,
-   *    Skills) are excluded; see the note inside. A chat whose only extensions
+   *    (every entry of `CAPABILITIES`: Developer, Biorouter Copilot, Web &
+   *    Documents, Auto Visualiser, Memory, Knowledge, Agent Drafter, Todo, Chat
+   *    Recall, Extension Manager, Code Execution, Skills, Workspace Control and
+   *    Crew) are excluded; see the note inside. A chat whose only extensions
    *    are capabilities therefore reads `0`, and that is the number meaning
    *    "you have added none", not the v1.89.0 P-04 defect wearing the same face.
    * 2. *Where the number comes from* — the SESSION's extensions, which is what
@@ -533,17 +519,15 @@ export function useExtensionPicker(
         // tell the user why the tool did nothing. The row stays, disabled, and
         // says why on a visible second line.
         const pairingRefused = extensionPairingRefused(ext.name, pairingTier);
-        const lockedByCrew = crewLocked(ext);
         return {
           ext,
           title: titleOf(ext),
           pairingRefused,
-          lockedByCrew,
-          disabled: bulkInFlight || pairingRefused || lockedByCrew,
+          disabled: bulkInFlight || pairingRefused,
           pending: pendingExtensionNames.has(ext.name),
         };
       }),
-    [sortedExtensions, titleOf, pairingTier, crewLocked, bulkInFlight, pendingExtensionNames]
+    [sortedExtensions, titleOf, pairingTier, bulkInFlight, pendingExtensionNames]
   );
 
   const bulk =
@@ -592,7 +576,7 @@ export function ExtensionsPanel({
       emptyText={picker.query ? EXTENSIONS_COPY.noMatch : EXTENSIONS_COPY.empty}
       inputRef={inputRef}
     >
-      {picker.rows.map(({ ext, title, pairingRefused, lockedByCrew, disabled, pending }) => (
+      {picker.rows.map(({ ext, title, pairingRefused, disabled, pending }) => (
         <PickerRow
           key={ext.name}
           name={title}
@@ -601,19 +585,11 @@ export function ExtensionsPanel({
           busy={pending}
           onToggle={() => picker.toggle(ext, !ext.enabled)}
           badge={isBuiltInExtension(ext) ? <BuiltInBadge /> : undefined}
-          note={
-            pairingRefused
-              ? EXTENSIONS_COPY.pairingRefused
-              : lockedByCrew
-                ? accessCopy.extensionLocked
-                : undefined
-          }
+          note={pairingRefused ? EXTENSIONS_COPY.pairingRefused : undefined}
           description={
             pairingRefused
               ? EXTENSIONS_COPY.pairingRefusedReason
-              : lockedByCrew
-                ? undefined
-                : ext.description || (isBuiltInExtension(ext) ? uiCopy.builtInHelp : undefined)
+              : ext.description || (isBuiltInExtension(ext) ? uiCopy.builtInHelp : undefined)
           }
         />
       ))}
diff --git a/ui/desktop/src/components/composer/copy.ts b/ui/desktop/src/components/composer/copy.ts
index 4584214cc..7e3495785 100644
--- a/ui/desktop/src/components/composer/copy.ts
+++ b/ui/desktop/src/components/composer/copy.ts
@@ -98,8 +98,8 @@ export const COMPOSER_COPY = {
     crew: 'Connect this chat to a Crew channel',
     /** `/crew` in a chat with no session yet: Enter can only say to send a message first. */
     crewBeforeFirstMessage: 'Connect this chat to a Crew channel after your first message',
-    /** The Crew extension's row, when a query reaches it without the `/crew` command. */
-    crewExtension: 'Crew tools extension (advanced)',
+    /** The Crew capability's `/ext:` row, when a query reaches it without the `/crew` command. */
+    crewExtension: 'Crew tools (advanced)',
     diverge: 'Continue in a new chat with the full history',
   },
 
diff --git a/ui/desktop/src/components/crew/access/chatCrewAccess.ts b/ui/desktop/src/components/crew/access/chatCrewAccess.ts
index 42563682d..d641beacf 100644
--- a/ui/desktop/src/components/crew/access/chatCrewAccess.ts
+++ b/ui/desktop/src/components/crew/access/chatCrewAccess.ts
@@ -140,16 +140,15 @@ export function forgetChannelLabels(): void {
 }
 
 // ── The per-chat answer, shared with controls that must not fetch on their own ──────────────
-// The chat's extension menu reads this so its Crew row can refuse to look switched off while the
-// grant stays active. It only ever reads what the chat's own lookup published.
+// The model picker reads this so a chat with Crew access says up front that its model is fixed
+// (`SwitchModelModal`). It only ever reads what the chat's own lookup published.
 
 type Listener = () => void;
 const published = new Map<string, { token: object; state: ChatCrewAccessState }>();
 
 /**
- * What the extension menu is told: whether the grant stands, not how the bar words it. An offline
- * chat's grant is still active — switching the Crew extension off would not end it — so the menu
- * keeps the Crew row locked on.
+ * What a reader is told: whether the grant stands, not how the bar words it. An offline chat's
+ * grant is still active, so it is published as active.
  */
 function publishedState(state: ChatCrewAccessState): ChatCrewAccessState {
   return state === 'offline' ? 'active' : state;
@@ -189,11 +188,6 @@ export function useChatCrewAccessState(
   );
 }
 
-/** The extension key the Crew platform extension is registered under. */
-export function isCrewExtensionName(name: string): boolean {
-  return name.trim().toLowerCase() === 'crew';
-}
-
 // ── The lookup ───────────────────────────────────────────────────────────────────────────────
 
 interface SavedConnection {
diff --git a/ui/desktop/src/components/crew/access/copy.ts b/ui/desktop/src/components/crew/access/copy.ts
index 916d4ed19..69a82f648 100644
--- a/ui/desktop/src/components/crew/access/copy.ts
+++ b/ui/desktop/src/components/crew/access/copy.ts
@@ -297,8 +297,6 @@ export const accessCopy = {
   /** A destination whose channel name this computer has not seen: the workspace instead. */
   chatDestinationWorkspace: (workspace: string) => `a channel in ${workspace}`,
   chatDestinationUnknown: 'a Crew channel',
-  /** The Crew row of the chat's extension menu while a grant is active. */
-  extensionLocked: 'On while this chat has Crew access. Revoke access to turn it off.',
 
   // ── Errors ─────────────────────────────────────────────────────────────────────────────────
   revokeFallback: 'Crew couldn’t complete that action.',
diff --git a/ui/desktop/src/components/crew/access/crewExtensionLock.test.tsx b/ui/desktop/src/components/crew/access/crewIsACapability.test.tsx
similarity index 53%
rename from ui/desktop/src/components/crew/access/crewExtensionLock.test.tsx
rename to ui/desktop/src/components/crew/access/crewIsACapability.test.tsx
index dd883cb0e..933509f8a 100644
--- a/ui/desktop/src/components/crew/access/crewExtensionLock.test.tsx
+++ b/ui/desktop/src/components/crew/access/crewIsACapability.test.tsx
@@ -6,14 +6,14 @@ import {
   useExtensionPicker,
 } from '../../bottom_menu/BottomMenuExtensionSelection';
 import { useChatCrewAccess } from './chatCrewAccess';
-import { accessCopy } from './copy';
 import { connection, grantRow } from './testing';
 
 /**
- * The chat's extension menu must not let the Crew row read as "removed" while the chat's grant is
- * still active (NOVICE-BASELINE F3: "crew · Extension removed" left `expired: false`). The row stays
- * on, says where Revoke is, and Disable all leaves it alone. It reads the chat's own lookup, so the
- * menu itself asks the daemon nothing.
+ * Crew ships with Biorouter, so it is a capability: it is switched on or off in Settings → Chat →
+ * Capabilities and is not one of the chat's extensions. The Tools popover used to list it, and then
+ * had to lock its row while a grant was active (NOVICE-BASELINE F3: "crew · Extension removed" left
+ * the grant standing). The row is gone, so neither the row nor Disable all can touch a granted
+ * chat's Crew tools, and only Revoke ends that access.
  */
 
 const mocks = vi.hoisted(() => ({
@@ -36,7 +36,7 @@ vi.mock('../../ConfigContext', () => ({
       { name: 'versa_azure', is_configured: true, resolved_tier: 'private' },
     ],
     extensionsList: [
-      { type: 'platform', name: 'crew', description: 'Crew', enabled: true },
+      { type: 'platform', name: 'crew', description: 'Crew', bundled: true, enabled: true },
       { type: 'stdio', name: 'spoke', description: 'Spoke', cmd: 'spoke', args: [], enabled: true },
     ],
   }),
@@ -54,37 +54,35 @@ vi.mock('../../settings/extensions/agent-api', () => ({
 }));
 vi.mock('../../../toasts', () => ({ toastService: { success: vi.fn(), error: vi.fn() } }));
 
-function ChatWithMenu({ grant }: { grant: boolean }) {
-  // What BaseChat does: the chat looks its grant up; the menu only reads the answer.
-  const access = useChatCrewAccess(grant ? 'chat-1' : null);
+function ChatWithMenu({ sessionId }: { sessionId: string | null }) {
+  // What BaseChat does: the chat looks its grant up.
+  const access = useChatCrewAccess(sessionId);
   // The Tools popover's extensions list, as ToolsChip holds it (spec 3.7).
-  const picker = useExtensionPicker('chat-1', { open: true });
+  const picker = useExtensionPicker(sessionId, { open: true });
   return (
     <>
       <p data-testid="state">{access.state}</p>
+      <p data-testid="count">{picker.answered ? picker.activeCount : ''}</p>
       <ExtensionsPanel picker={picker} />
     </>
   );
 }
 
-function renderMenu(grants: unknown[], lookUp = true) {
+function renderMenu(sessionId: string | null) {
   mocks.crewHttp.mockImplementation(async (path: string) => {
     if (path === '/connections') return { connections: [connection] };
-    if (path === '/connections/conn-1/grants') return { grants };
+    if (path === '/connections/conn-1/grants')
+      return { grants: [grantRow({ session_id: 'chat-1' })] };
     return {};
   });
   render(
     <MemoryRouter>
-      <ChatWithMenu grant={lookUp} />
+      <ChatWithMenu sessionId={sessionId} />
     </MemoryRouter>
   );
 }
 
-async function openMenu() {
-  return screen.findByRole('option', { name: /^Crew/ });
-}
-
-describe('the Crew row of a chat’s extension menu', () => {
+describe('Crew in the Tools popover', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.getSessionExtensions.mockResolvedValue({
@@ -97,38 +95,27 @@ describe('the Crew row of a chat’s extension menu', () => {
     });
   });
 
-  it('stays on and points to Revoke while the chat’s grant is active', async () => {
-    renderMenu([grantRow({ session_id: 'chat-1' })]);
+  it('lists no Crew row in a granted chat, and Disable all leaves its tools alone', async () => {
+    renderMenu('chat-1');
     await waitFor(() => expect(screen.getByTestId('state')).toHaveTextContent('active'));
-    const crew = await openMenu();
-    await waitFor(() => expect(crew).toHaveAttribute('aria-selected', 'true'));
-    expect(crew).toHaveAttribute('aria-disabled', 'true');
-    expect(crew).toHaveTextContent(accessCopy.extensionLocked);
+    const spoke = await screen.findByRole('option', { name: /^spoke/i });
+    await waitFor(() => expect(spoke).toHaveAttribute('aria-selected', 'true'));
+    expect(screen.queryByRole('option', { name: /crew/i })).toBeNull();
+    expect(screen.getAllByRole('option')).toHaveLength(1);
 
-    fireEvent.click(crew);
-    expect(mocks.removeFromAgent).not.toHaveBeenCalled();
+    // The chip counts what the person added: spoke, not the Crew capability the chat also holds.
+    await waitFor(() => expect(screen.getByTestId('count')).toHaveTextContent('1'));
 
-    // Disable all leaves the Crew row alone.
     fireEvent.click(screen.getByRole('button', { name: 'Disable all (1)' }));
     await waitFor(() => expect(mocks.removeFromAgent).toHaveBeenCalledTimes(1));
     expect(mocks.removeFromAgent).toHaveBeenCalledWith('spoke', 'chat-1', true);
+    expect(mocks.removeFromAgent).not.toHaveBeenCalledWith('crew', expect.anything(), true);
   });
 
-  it('toggles as before once the grant is revoked', async () => {
-    renderMenu([grantRow({ session_id: 'chat-1', expired: true })]);
-    await waitFor(() => expect(screen.getByTestId('state')).toHaveTextContent('revoked'));
-    const crew = await openMenu();
-    await waitFor(() => expect(crew).toHaveAttribute('aria-selected', 'true'));
-    expect(crew).not.toHaveAttribute('aria-disabled', 'true');
-    fireEvent.click(crew);
-    await waitFor(() => expect(mocks.removeFromAgent).toHaveBeenCalledWith('crew', 'chat-1', true));
-  });
-
-  it('toggles as before in a chat that never looked anything up', async () => {
-    renderMenu([grantRow({ session_id: 'chat-1' })], false);
-    const crew = await openMenu();
-    await waitFor(() => expect(crew).toHaveAttribute('aria-selected', 'true'));
-    expect(crew).not.toHaveAttribute('aria-disabled', 'true');
-    expect(mocks.crewHttp).not.toHaveBeenCalled();
+  it('lists no Crew row on Home either, and does not count it for the next chat', async () => {
+    renderMenu(null);
+    await screen.findByRole('option', { name: /^spoke/i });
+    expect(screen.queryByRole('option', { name: /crew/i })).toBeNull();
+    expect(screen.getByTestId('count')).toHaveTextContent('1');
   });
 });
diff --git a/ui/desktop/src/components/crew/access/index.ts b/ui/desktop/src/components/crew/access/index.ts
index 331176ca3..a62a2737b 100644
--- a/ui/desktop/src/components/crew/access/index.ts
+++ b/ui/desktop/src/components/crew/access/index.ts
@@ -11,7 +11,7 @@
  * - `useAgentAccessCount` — the channel header's agent-access chip.
  *
  * Outside Crew, `useChatCrewAccess` + `ChatCrewAccessBar` give an ordinary chat its Crew state, and
- * `useChatCrewAccessState` lets the chat's extension menu read it without fetching.
+ * `useChatCrewAccessState` lets the model picker read it without fetching.
  */
 export { AccessList, type AccessListProps } from './AccessList';
 export { AccessTab, type AccessTabProps } from './AccessTab';
@@ -33,7 +33,6 @@ export {
   type AgentAccessCount,
 } from './accessRows';
 export {
-  isCrewExtensionName,
   useChatCrewAccess,
   useChatCrewAccessState,
   type ChatCrewAccess,
diff --git a/ui/desktop/src/components/extensions/ExtensionsView.test.tsx b/ui/desktop/src/components/extensions/ExtensionsView.test.tsx
index 514d954fa..5353152cc 100644
--- a/ui/desktop/src/components/extensions/ExtensionsView.test.tsx
+++ b/ui/desktop/src/components/extensions/ExtensionsView.test.tsx
@@ -240,6 +240,7 @@ describe('ExtensionsView — the band', () => {
       { type: 'stdio', name: 'spokeagent', description: 'SPOKE graph', enabled: false },
       // A shipped capability has no row here, so it is not counted.
       { type: 'platform', name: 'Workspace', description: 'Workspace Control', enabled: true },
+      { type: 'platform', name: 'crew', description: 'Crew', bundled: true, enabled: true },
     ];
     renderView();
 
diff --git a/ui/desktop/src/components/settings/capabilities/CapabilitiesSection.test.tsx b/ui/desktop/src/components/settings/capabilities/CapabilitiesSection.test.tsx
index 92294aec3..6d2745f25 100644
--- a/ui/desktop/src/components/settings/capabilities/CapabilitiesSection.test.tsx
+++ b/ui/desktop/src/components/settings/capabilities/CapabilitiesSection.test.tsx
@@ -27,6 +27,8 @@ vi.mock('../extensions', () => ({
 vi.mock('../../copilot/copilotApi', () => ({ copilotSetup: mocks.copilotSetup }));
 
 const labelOf = (key: string) => CAPABILITIES.find((capability) => capability.key === key)!.label;
+const helpOf = (key: string) =>
+  CAPABILITIES.find((capability) => capability.key === key)!.description;
 
 describe('CapabilitiesSection', () => {
   beforeEach(() => {
@@ -38,12 +40,13 @@ describe('CapabilitiesSection', () => {
   it('shows all capabilities and uses their declared defaults while config loads', () => {
     render(<CapabilitiesSection />);
 
-    expect(screen.getAllByRole('switch')).toHaveLength(13);
+    expect(screen.getAllByRole('switch')).toHaveLength(14);
     expect(screen.getByRole('switch', { name: 'Auto Visualiser' })).toBeChecked();
     expect(screen.getByRole('switch', { name: 'Code Execution' })).toBeChecked();
     expect(screen.getByRole('switch', { name: 'Biorouter Copilot' })).toBeChecked();
     expect(screen.getByRole('switch', { name: 'Agent Drafter' })).toBeChecked();
     expect(screen.getByRole('switch', { name: 'Chat Recall' })).not.toBeChecked();
+    expect(screen.getByRole('switch', { name: 'Crew' })).toBeChecked();
   });
 
   // Spec 2.6: a switch is named by its row's visible label, never by "Toggle …" and never by its
@@ -62,7 +65,7 @@ describe('CapabilitiesSection', () => {
   it('prints one line per row: the description is help, not a paragraph', () => {
     const { container } = render(<CapabilitiesSection />);
 
-    expect(container.querySelectorAll('.biorouter-settings-row')).toHaveLength(13);
+    expect(container.querySelectorAll('.biorouter-settings-row')).toHaveLength(14);
     expect(container.querySelectorAll('p')).toHaveLength(0);
     // Each row carries its explanation as an InfoTip, named after the row.
     expect(screen.getByRole('button', { name: 'About Developer' })).toBeInTheDocument();
@@ -94,6 +97,43 @@ describe('CapabilitiesSection', () => {
     expect(mocks.getExtensions).toHaveBeenCalledWith(true);
   });
 
+  // Crew left the Extensions page for this list. Its switch reads and writes the same `crew`
+  // entry the Extensions page did, so a person who had switched it off finds it off here, and
+  // turning it back on is the same config write.
+  it('keeps a saved Crew off and turns it on through the same config entry', async () => {
+    mocks.extensionsList = [
+      {
+        type: 'platform',
+        name: 'crew',
+        description: 'Use saved Crew connections',
+        bundled: true,
+        enabled: false,
+      },
+    ];
+    render(<CapabilitiesSection />);
+
+    const crew = screen.getByRole('switch', { name: 'Crew' });
+    expect(crew).not.toBeChecked();
+    expect(crew).toBeEnabled();
+    expect(crew).toHaveAccessibleDescription(helpOf('crew'));
+
+    fireEvent.click(crew);
+    await waitFor(() =>
+      expect(mocks.toggleExtensionDefault).toHaveBeenCalledWith(
+        expect.objectContaining({
+          toggle: 'toggleOn',
+          extensionConfig: expect.objectContaining({
+            type: 'platform',
+            name: 'crew',
+            enabled: false,
+          }),
+          addToConfig: mocks.addExtension,
+          itemKind: 'capability',
+        })
+      )
+    );
+  });
+
   it('disables a switch whose config entry has not loaded yet', () => {
     render(<CapabilitiesSection />);
     // No entry yet (config still loading): shown at its default, and not togglable.
diff --git a/ui/desktop/src/components/settings/capabilities/capabilities.test.ts b/ui/desktop/src/components/settings/capabilities/capabilities.test.ts
index c9a5405fa..fd044000b 100644
--- a/ui/desktop/src/components/settings/capabilities/capabilities.test.ts
+++ b/ui/desktop/src/components/settings/capabilities/capabilities.test.ts
@@ -16,6 +16,7 @@ const expectedDefaults = {
   agent_drafter: true,
   chatrecall: false,
   workspace: true,
+  crew: true,
 };
 
 describe('capabilities', () => {
@@ -29,7 +30,14 @@ describe('capabilities', () => {
       expect(isCapabilityDefaultEnabled(extension), extension.name).toBe(extension.enabled);
     }
 
-    for (const name of ['todo', 'chatrecall', 'extensionmanager', 'skills', 'code_execution']) {
+    for (const name of [
+      'todo',
+      'chatrecall',
+      'extensionmanager',
+      'skills',
+      'code_execution',
+      'crew',
+    ]) {
       expect(isCapabilityExtension({ name }), name).toBe(true);
     }
   });
diff --git a/ui/desktop/src/components/settings/capabilities/capabilities.ts b/ui/desktop/src/components/settings/capabilities/capabilities.ts
index c3e5cccf8..dcee8dc72 100644
--- a/ui/desktop/src/components/settings/capabilities/capabilities.ts
+++ b/ui/desktop/src/components/settings/capabilities/capabilities.ts
@@ -123,6 +123,25 @@ export const CAPABILITIES: CapabilityMeta[] = [
       'Work across several chats: open, read and steer other chats, and run subagents in visible tabs.',
     defaultEnabled: true,
   },
+  {
+    /*
+     * Crew ships with Biorouter (`PLATFORM_EXTENSIONS["crew"]`), so it is a
+     * capability like Workspace Control above, and this entry moves it off the
+     * Extensions page, its count, the Tools popover and the load toast's
+     * denominator at once. The switch writes the same `crew` entry in
+     * `config.yaml` the Extensions page did, so a saved on or off carries over.
+     *
+     * It is the default for new chats only. A chat a person connects with
+     * `/crew`, and a Crew task, get the tools from their grant
+     * (`grant_session` and `configure_run_agent` in `routes/crew.rs`), and only
+     * Revoke ends that access.
+     */
+    key: 'crew',
+    label: 'Crew',
+    description:
+      'Lets a chat you connect with /crew read its Crew channels and post updates there.',
+    defaultEnabled: true,
+  },
 ];
 
 /** Set of normalized capability keys, for quick membership checks. */
diff --git a/ui/desktop/src/components/settings/capabilities/chatRowsGeometry.browser.test.tsx b/ui/desktop/src/components/settings/capabilities/chatRowsGeometry.browser.test.tsx
index 06ceae0a4..d31a1d60d 100644
--- a/ui/desktop/src/components/settings/capabilities/chatRowsGeometry.browser.test.tsx
+++ b/ui/desktop/src/components/settings/capabilities/chatRowsGeometry.browser.test.tsx
@@ -258,7 +258,7 @@ describe('the Chat tab rows in a real layout engine (spec 3.14, 5.7)', () => {
           (row) => row.getBoundingClientRect().height
         )
       );
-      expect(heights).toHaveLength(13);
+      expect(heights).toHaveLength(14);
       for (const height of heights) near(height, 40, 'capability row');
     } finally {
       await tab.close();
diff --git a/ui/desktop/src/components/settings/extensions/ExtensionsSection.test.tsx b/ui/desktop/src/components/settings/extensions/ExtensionsSection.test.tsx
index 50a257852..fec8c308f 100644
--- a/ui/desktop/src/components/settings/extensions/ExtensionsSection.test.tsx
+++ b/ui/desktop/src/components/settings/extensions/ExtensionsSection.test.tsx
@@ -123,6 +123,32 @@ describe('ExtensionsSection — Workspace is a capability, not an extension', ()
   });
 });
 
+/**
+ * Crew is a capability too: it ships with Biorouter (`PLATFORM_EXTENSIONS["crew"]` in
+ * `crates/biorouter/src/agents/extension.rs`), and its switch is in Settings → Chat →
+ * Capabilities. The daemon lists it as `{ type: 'platform', name: 'crew' }`.
+ */
+describe('ExtensionsSection — Crew is a capability, not an extension', () => {
+  it('does not render Crew among the extensions, on or off', async () => {
+    mocks.extensionsList = [
+      { type: 'platform', name: 'crew', description: 'Crew', bundled: true, enabled: false },
+      {
+        type: 'stdio',
+        name: 'medcp',
+        description: 'Local clinical MCP',
+        cmd: 'node',
+        args: ['server.js'],
+        enabled: true,
+      },
+    ];
+    render(<ExtensionsSection />);
+
+    await screen.findByText('Local clinical MCP');
+    expect(screen.queryByRole('switch', { name: /crew/i })).not.toBeInTheDocument();
+    expect(screen.queryByText(/^crew$/i)).not.toBeInTheDocument();
+  });
+});
+
 const customEntry = {
   type: 'stdio',
   name: 'medcp',

From 5c9522cea3e0c2a22d5e2573cc585ef79532b63d Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:10:38 -0700
Subject: [PATCH 08/26] fix(knowledge): Daily Meditation upgrades every
 Meditation text Biorouter shipped (diagnostics 20261006_2)

The stock-copy list held two hashes that match no Meditation text ever
committed, so startup never upgraded an install. A v1.85.2 copy kept
requiring soul-writer, the skill v1.85.3 renamed to update-soul, and since
v1.90.0 made workflow skills required the job failed every night.

The list now holds the hash of every text that shipped, and a test reads each
text back from tests/fixtures/meditation/ and hashes it. A pin on the current
text's hash fails when the text changes without its outgoing hash being
recorded. The reporter's exact bytes upgrade in both the library and the
schedule's copy, with the job's bookkeeping kept.
---
 crates/biorouter/src/knowledge/soul.rs        | 173 ++++++++++++++++++
 .../tests/fixtures/meditation/573f3f9c.yaml   |  67 +++++++
 .../tests/fixtures/meditation/7d316d31.yaml   |  67 +++++++
 .../tests/fixtures/meditation/b03af2d3.yaml   |  67 +++++++
 .../tests/fixtures/meditation/c060d3b5.yaml   |  67 +++++++
 .../tests/fixtures/meditation/c1dcdbd5.yaml   |  67 +++++++
 .../tests/fixtures/meditation/e457b997.yaml   |  67 +++++++
 7 files changed, 575 insertions(+)
 create mode 100644 crates/biorouter/tests/fixtures/meditation/573f3f9c.yaml
 create mode 100644 crates/biorouter/tests/fixtures/meditation/7d316d31.yaml
 create mode 100644 crates/biorouter/tests/fixtures/meditation/b03af2d3.yaml
 create mode 100644 crates/biorouter/tests/fixtures/meditation/c060d3b5.yaml
 create mode 100644 crates/biorouter/tests/fixtures/meditation/c1dcdbd5.yaml
 create mode 100644 crates/biorouter/tests/fixtures/meditation/e457b997.yaml

diff --git a/crates/biorouter/src/knowledge/soul.rs b/crates/biorouter/src/knowledge/soul.rs
index 91ca365ef..15dabbd39 100644
--- a/crates/biorouter/src/knowledge/soul.rs
+++ b/crates/biorouter/src/knowledge/soul.rs
@@ -69,7 +69,41 @@ pub const MEDITATION_CRON: &str = "0 0 3 * * *";
 pub const SOUL_COLOR: &str = "#9c6b3f";
 
 const SOUL_RECONCILE_LOCK: &str = ".soul-reconcile.lock";
+/// The SHA-256 of every Meditation workflow text Biorouter shipped before the
+/// current [`MEDITATION_WORKFLOW_YAML`]. A library or schedule copy whose bytes
+/// hash to one of these is stock, and startup replaces it with the current
+/// text; any other copy is the person's own and is left alone.
+///
+/// ⚠ Each entry is the hash of REAL shipped bytes, and a test reads every one
+/// of those texts back from `tests/fixtures/meditation/` and hashes it
+/// (`every_meditation_text_biorouter_shipped_is_recognised_as_stock`). Until
+/// diagnostics 20261006_2 this list held only the last two entries, which
+/// match no text ever committed, so no install was ever upgraded. A v1.85.2
+/// copy kept requiring `soul-writer`, the skill v1.85.3 renamed to
+/// `update-soul`, and once v1.90.0 made a workflow's skills required, Daily
+/// Meditation failed every night with "requires skill 'soul-writer'". The
+/// upgrade tests used made-up hashes, so nothing tied this list to what had
+/// shipped.
+///
+/// When [`MEDITATION_WORKFLOW_YAML`] changes, add the outgoing text's hash
+/// here and its bytes as a fixture; the test that pins the current hash fails
+/// until both are done.
 const PREVIOUS_MEDITATION_WORKFLOW_SHA256: &[&str] = &[
+    // 6ba0bf201, before v1.85.2: requires `soul-writer`.
+    "e457b997531525b0c023b9b6929e12c4045aa037649f9268296b572433af0fb8",
+    // v1.85.2 (60703d513): requires `soul-writer`. The copy in diagnostics
+    // 20261006_2, byte for byte.
+    "b03af2d3bf2143573ac1229eee7d56e22ba92a9577ac598c4099c22623124bab",
+    // v1.85.3 (6151978bb): the skill renamed to `update-soul`.
+    "c1dcdbd5268789e8dd1e612c4508ed32de65fdf2d620a1dc9581e6acff823ab5",
+    // 8c1ea5d34, before v1.89.0.
+    "7d316d31f17e6d4e8599b971f90c3bd2d9614221bba14d83d9eb6cdb2ad68656",
+    // v1.89.0 (cd7de3504).
+    "573f3f9c6ce2c9b821632d77a64ee029d525db7aaa832562cebb7d5d7cb397d1",
+    // v1.89.7 (eb594ded3).
+    "c060d3b563139f2d1a7fa8c8425fec1f3d178241cb939482e95b1959f2db762c",
+    // Listed before any of the above, and matching no text ever committed on
+    // any ref. Kept: a hash that matches nothing upgrades nothing.
     "142edbf98aca3e521649ddec05ed156ab16936303cc42cbe8cce1bc79c630772",
     "a0558805057ffae5257fa805b73253a1b615300bec563a0126f4a23884f9884c",
 ];
@@ -1336,6 +1370,145 @@ mod tests {
         assert_eq!(std::fs::read_to_string(scheduled_copy).unwrap(), customized);
     }
 
+    /// Every Meditation text Biorouter has shipped, as the bytes it wrote to
+    /// disk, with where it came from. Read back from
+    /// `tests/fixtures/meditation/`, extracted from soul.rs at each commit that
+    /// changed the text.
+    const SHIPPED_MEDITATION_TEXTS: &[(&str, &[u8])] = &[
+        (
+            "6ba0bf201, before v1.85.2",
+            include_bytes!("../../tests/fixtures/meditation/e457b997.yaml"),
+        ),
+        (
+            "v1.85.2 (60703d513), diagnostics 20261006_2",
+            include_bytes!("../../tests/fixtures/meditation/b03af2d3.yaml"),
+        ),
+        (
+            "v1.85.3 (6151978bb)",
+            include_bytes!("../../tests/fixtures/meditation/c1dcdbd5.yaml"),
+        ),
+        (
+            "8c1ea5d34, before v1.89.0",
+            include_bytes!("../../tests/fixtures/meditation/7d316d31.yaml"),
+        ),
+        (
+            "v1.89.0 (cd7de3504)",
+            include_bytes!("../../tests/fixtures/meditation/573f3f9c.yaml"),
+        ),
+        (
+            "v1.89.7 (eb594ded3)",
+            include_bytes!("../../tests/fixtures/meditation/c060d3b5.yaml"),
+        ),
+    ];
+
+    /// The hash of [`MEDITATION_WORKFLOW_YAML`] as it ships today (v1.90.0,
+    /// f81f5d64c). Changing the text fails this pin, and the message says what
+    /// else has to move with it.
+    const CURRENT_MEDITATION_WORKFLOW_SHA256: &str =
+        "4c3e2f773574c46a7ed4572aabf475fd90bf197020a83fdd86fb02084c0a1ac1";
+
+    fn sha256_hex(bytes: &[u8]) -> String {
+        format!("{:x}", Sha256::digest(bytes))
+    }
+
+    /// Diagnostics 20261006_2: the stock-copy list held two hashes that match
+    /// no Meditation text ever committed, so every install kept whatever text
+    /// it was first given. This holds the list to the real bytes.
+    #[test]
+    fn every_meditation_text_biorouter_shipped_is_recognised_as_stock() {
+        for (shipped, bytes) in SHIPPED_MEDITATION_TEXTS {
+            let hash = sha256_hex(bytes);
+            assert!(
+                PREVIOUS_MEDITATION_WORKFLOW_SHA256.contains(&hash.as_str()),
+                "the Meditation text shipped in {shipped} ({hash}) is not in \
+                 PREVIOUS_MEDITATION_WORKFLOW_SHA256, so an install that has it is never upgraded"
+            );
+            // A fixture that is the current text would make this test pass
+            // while proving nothing about an older install.
+            assert_ne!(bytes, &MEDITATION_WORKFLOW_YAML.as_bytes(), "{shipped}");
+        }
+        let current = sha256_hex(MEDITATION_WORKFLOW_YAML.as_bytes());
+        assert_eq!(
+            current, CURRENT_MEDITATION_WORKFLOW_SHA256,
+            "MEDITATION_WORKFLOW_YAML changed. Add the outgoing text's hash \
+             ({CURRENT_MEDITATION_WORKFLOW_SHA256}) to PREVIOUS_MEDITATION_WORKFLOW_SHA256, save \
+             its bytes as tests/fixtures/meditation/<first 8 hex>.yaml and list it in \
+             SHIPPED_MEDITATION_TEXTS, then update this pin"
+        );
+        assert!(
+            !PREVIOUS_MEDITATION_WORKFLOW_SHA256.contains(&current.as_str()),
+            "the current text must not be listed as a previous one, or every startup rewrites it"
+        );
+    }
+
+    /// Diagnostics 20261006_2, end to end on the reporter's own bytes: the
+    /// v1.85.2 text in both the workflow library and the schedule's copy.
+    /// Startup must replace both with today's text, which needs `update-soul`,
+    /// and keep the schedule's bookkeeping. Before the fix both copies kept
+    /// `skills: [soul-writer]` and the job failed every night.
+    #[test]
+    fn a_v1_85_2_meditation_copy_is_upgraded_in_the_library_and_the_schedule() {
+        let reporter_copy = SHIPPED_MEDITATION_TEXTS[1].1;
+        assert!(String::from_utf8_lossy(reporter_copy).contains("soul-writer"));
+        let tmp = tempfile::tempdir().unwrap();
+
+        let library = tmp.path().join("workflows").join(MEDITATION_WORKFLOW_FILE);
+        std::fs::create_dir_all(library.parent().unwrap()).unwrap();
+        std::fs::write(&library, reporter_copy).unwrap();
+        assert_eq!(ensure_meditation_workflow(tmp.path()).unwrap(), library);
+        assert_eq!(
+            std::fs::read_to_string(&library).unwrap(),
+            MEDITATION_WORKFLOW_YAML
+        );
+
+        let scheduled_copy = tmp.path().join("daily-meditation.yaml");
+        std::fs::write(&scheduled_copy, reporter_copy).unwrap();
+        let jobs = vec![ScheduledJob {
+            id: MEDITATION_SCHEDULE_ID.to_string(),
+            source: scheduled_copy.to_string_lossy().into_owned(),
+            cron: MEDITATION_CRON.to_string(),
+            last_run: Some(chrono::Utc::now()),
+            currently_running: false,
+            paused: false,
+            current_session_id: None,
+            process_start_time: None,
+            run_count: 94,
+            max_runs: None,
+            creator_session_id: None,
+            last_error: Some(
+                "workflow requires skill 'soul-writer', but it is not installed".to_string(),
+            ),
+            owns_source: None,
+            armed_with_private_reach: None,
+        }];
+        let metadata_before = serde_json::to_value(&jobs[0]).unwrap();
+        assert_eq!(
+            upgrade_existing_meditation_workflow(
+                &jobs,
+                MEDITATION_WORKFLOW_YAML,
+                PREVIOUS_MEDITATION_WORKFLOW_SHA256,
+            )
+            .unwrap(),
+            Some(true)
+        );
+        let upgraded = std::fs::read_to_string(&scheduled_copy).unwrap();
+        assert_eq!(upgraded, MEDITATION_WORKFLOW_YAML);
+        assert_eq!(serde_json::to_value(&jobs[0]).unwrap(), metadata_before);
+        let workflow: Workflow = serde_yaml::from_str(&upgraded).unwrap();
+        assert_eq!(workflow.skills, Some(vec![SOUL_SKILL_DIR.to_string()]));
+
+        // The next startup finds today's text and leaves it alone.
+        assert_eq!(
+            upgrade_existing_meditation_workflow(
+                &jobs,
+                MEDITATION_WORKFLOW_YAML,
+                PREVIOUS_MEDITATION_WORKFLOW_SHA256,
+            )
+            .unwrap(),
+            Some(false)
+        );
+    }
+
     fn make_legacy(svc: &KnowledgeService, id: &str, name: &str) {
         svc.create_base(id, name, None).unwrap();
         let root = biorouter_mcp::knowledge::paths::kb_root(svc.root(), id);
diff --git a/crates/biorouter/tests/fixtures/meditation/573f3f9c.yaml b/crates/biorouter/tests/fixtures/meditation/573f3f9c.yaml
new file mode 100644
index 000000000..4bf1b45f9
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/573f3f9c.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Review the user's recent Biorouter sessions and save what matters about them
+  into the built-in "Soul" knowledge base: how they approach scientific
+  questions, the tools and commands they use, the tool responses they rely on,
+  and lasting personal details such as name, role, and preferences. Runs daily
+  at 3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `update-soul` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER, not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:"), especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: link related entities/concepts with [[wiki-links]],
+     avoid duplicating facts already present, and prefer updating an existing
+     page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Search the skills installed on this machine and load the one that matches the task in hand
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Keep a running checklist through a multi-step task, so Biorouter tracks what is done and what is left
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search your earlier chats and load a summary of one, so work you already did can be picked up here
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- update-soul
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []
diff --git a/crates/biorouter/tests/fixtures/meditation/7d316d31.yaml b/crates/biorouter/tests/fixtures/meditation/7d316d31.yaml
new file mode 100644
index 000000000..47392c3ec
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/7d316d31.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Review the user's recent Biorouter sessions and save what matters about them
+  into the built-in "Soul" knowledge base: how they approach scientific
+  questions, the tools and commands they use, the tool responses they rely on,
+  and lasting personal details such as name, role, and preferences. Runs daily
+  at 3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `update-soul` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER, not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:"), especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: link related entities/concepts with [[wiki-links]],
+     avoid duplicating facts already present, and prefer updating an existing
+     page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Load and use skills from relevant directories
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Enable a todo list for biorouter so it can keep track of what it is doing
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search past conversations and load session summaries for contextual memory
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- update-soul
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []
diff --git a/crates/biorouter/tests/fixtures/meditation/b03af2d3.yaml b/crates/biorouter/tests/fixtures/meditation/b03af2d3.yaml
new file mode 100644
index 000000000..638efe51d
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/b03af2d3.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Review the user's recent Biorouter sessions and save what matters about them
+  into the built-in "Soul" knowledge base: how they approach scientific
+  questions, the tools and commands they use, the tool responses they rely on,
+  and lasting personal details such as name, role, and preferences. Runs daily
+  at 3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `soul-writer` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER — not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:") — especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: link related entities/concepts with [[wiki-links]],
+     avoid duplicating facts already present, and prefer updating an existing
+     page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Load and use skills from relevant directories
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Enable a todo list for biorouter so it can keep track of what it is doing
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search past conversations and load session summaries for contextual memory
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- soul-writer
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []
diff --git a/crates/biorouter/tests/fixtures/meditation/c060d3b5.yaml b/crates/biorouter/tests/fixtures/meditation/c060d3b5.yaml
new file mode 100644
index 000000000..af8eccc27
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/c060d3b5.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Review the user's recent Biorouter sessions and save what matters about them
+  into the built-in "Soul" knowledge base: how they approach scientific
+  questions, the tools and commands they use, the tool responses they rely on,
+  and lasting personal details such as name, role, and preferences. Runs daily
+  at 3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `update-soul` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER, not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:"), especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: use ordinary OKF markdown links to related page
+     paths, avoid duplicating facts already present, and prefer updating an
+     existing page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Search the skills installed on this machine and load the one that matches the task in hand
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Keep a running checklist through a multi-step task, so Biorouter tracks what is done and what is left
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search your earlier chats and load a summary of one, so work you already did can be picked up here
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- update-soul
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []
diff --git a/crates/biorouter/tests/fixtures/meditation/c1dcdbd5.yaml b/crates/biorouter/tests/fixtures/meditation/c1dcdbd5.yaml
new file mode 100644
index 000000000..3f5809ed6
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/c1dcdbd5.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Review the user's recent Biorouter sessions and save what matters about them
+  into the built-in "Soul" knowledge base: how they approach scientific
+  questions, the tools and commands they use, the tool responses they rely on,
+  and lasting personal details such as name, role, and preferences. Runs daily
+  at 3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `update-soul` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER — not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:") — especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: link related entities/concepts with [[wiki-links]],
+     avoid duplicating facts already present, and prefer updating an existing
+     page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Load and use skills from relevant directories
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Enable a todo list for biorouter so it can keep track of what it is doing
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search past conversations and load session summaries for contextual memory
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- update-soul
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []
diff --git a/crates/biorouter/tests/fixtures/meditation/e457b997.yaml b/crates/biorouter/tests/fixtures/meditation/e457b997.yaml
new file mode 100644
index 000000000..6a5238396
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/meditation/e457b997.yaml
@@ -0,0 +1,67 @@
+version: 1.0.0
+title: Meditation
+description: >-
+  Reflect on the user's recent BioRouter interactions and digest them into the
+  built-in "Soul" knowledge base — capturing how they approach scientific
+  questions, the tools and commands they use, the tool responses they act on,
+  and durable personal details (name, occupation, preferences). Runs daily at
+  3:00 AM by default as "Daily Meditation".
+instructions: |-
+  You are maintaining the user's personal "Soul" knowledge base (id: soul).
+  Follow the `soul-writer` skill exactly.
+
+  Goal: turn the user's recent interaction history into durable, high-signal,
+  personalised knowledge about THE USER — not a summary of every chat.
+
+  Procedure:
+  1. Find the user's recent REAL chat sessions with the `chatrecall` tool
+     (search mode, with a recent date range and broad queries). Collect their
+     session ids. Skip scheduled-job sessions (names starting with
+     "Scheduled job:") — especially this very session.
+  2. Call `platform__ingest_conversation` with EXPLICIT `session_ids` for the
+     most relevant recent session(s), targeting the `soul` knowledge base.
+     Never omit `session_ids`: omitting it defaults to the current scheduled
+     session, which contains nothing about the user. Prefer sessions since
+     the last Meditation. If chatrecall surfaces no real user sessions, stop
+     and make no changes.
+  3. Prioritise capturing:
+       - the way the user approaches different scientific questions,
+       - the tools and extensions they use and how they call them,
+       - the commands they run and the responses they rely on,
+       - personal information they reveal: name, role/occupation, affiliations,
+         stated preferences and working style.
+  4. Explicitly DISCARD low-value noise: greetings, chit-chat, one-off
+     irrelevant details, and anything that would not help a future assistant
+     serve this user better.
+  5. Keep the Soul coherent: link related entities/concepts with [[wiki-links]],
+     avoid duplicating facts already present, and prefer updating an existing
+     page over creating a near-duplicate.
+
+  If there is nothing new worth recording, say so and make no changes.
+extensions:
+- type: platform
+  name: skills
+  description: Load and use skills from relevant directories
+  bundled: true
+  available_tools: []
+- type: platform
+  name: todo
+  description: Enable a todo list for biorouter so it can keep track of what it is doing
+  bundled: true
+  available_tools: []
+- type: platform
+  name: chatrecall
+  description: Search past conversations and load session summaries for contextual memory
+  bundled: true
+  available_tools: []
+knowledge_bases:
+  default: soul
+  visible:
+  - soul
+skills:
+- soul-writer
+activities:
+- Update my Soul from recent interactions
+- Learn my preferences and working style
+- Record the tools and commands I use
+parameters: []

From ee2f0c5050c2423673b6c997466b45705370080a Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:10:43 -0700
Subject: [PATCH 09/26] fix(skills): a workflow naming soul-writer loads
 update-soul, and a missing skill says what to do (diagnostics 20261006_2)

A Meditation copy the person edited is not upgraded at startup, and named
soul-writer, a skill startup deletes and nothing can install. The old name
now resolves to the skill it became, unless a skill or bundle by that name is
installed. A workflow skill that really is missing is refused with the next
step: add it under Skills, or remove it from the workflow's skills.
---
 .../biorouter/src/agents/skills_extension.rs  | 112 +++++++++++++++++-
 1 file changed, 106 insertions(+), 6 deletions(-)

diff --git a/crates/biorouter/src/agents/skills_extension.rs b/crates/biorouter/src/agents/skills_extension.rs
index 593947d0a..6f61406b9 100644
--- a/crates/biorouter/src/agents/skills_extension.rs
+++ b/crates/biorouter/src/agents/skills_extension.rs
@@ -404,6 +404,43 @@ pub fn count_user_skills() -> usize {
         .count()
 }
 
+/// Skills Biorouter itself renamed: (old name, current name). A workflow saved
+/// before the rename still names the old one.
+///
+/// Diagnostics 20261006_2: a Daily Meditation copied in v1.85.2 named
+/// `soul-writer`, which v1.85.3 renamed to `update-soul` (and startup deletes
+/// the old folder), so once workflow skills became required every run failed
+/// with "requires skill 'soul-writer'", a skill nothing can install. A stock
+/// copy is now upgraded at startup (`knowledge::soul`); this covers a copy the
+/// person edited, which startup leaves alone.
+const RENAMED_SKILLS: &[(&str, &str)] = &[(
+    crate::knowledge::soul::SOUL_SKILL_DIR_LEGACY,
+    crate::knowledge::soul::SOUL_SKILL_DIR,
+)];
+
+/// `name`, or the current name of a skill Biorouter renamed when the old name
+/// is neither a skill nor a bundle here. An installed skill that happens to
+/// carry an old name keeps it.
+fn current_skill_name(name: &str, view: &skill_catalog::CatalogView) -> String {
+    let installed = view.skills.iter().any(|skill| skill.name == name)
+        || view.bundles.iter().any(|bundle| bundle.name == name);
+    if !installed {
+        if let Some((_, current)) = RENAMED_SKILLS.iter().find(|(old, _)| *old == name) {
+            return (*current).to_string();
+        }
+    }
+    name.to_string()
+}
+
+/// The refusal for a workflow skill this machine does not have, saying what
+/// the person can do about it.
+fn missing_workflow_skill(name: &str) -> anyhow::Error {
+    anyhow::anyhow!(
+        "workflow requires skill '{name}', but it is not installed. Add the skill under Skills, \
+         or remove '{name}' from the workflow's skills."
+    )
+}
+
 /// Resolve workflow-declared skills to the exact installed bodies visible to
 /// one session. This is intentionally stricter than the model-facing search:
 /// a workflow names required procedure, so missing or disabled instructions
@@ -436,6 +473,7 @@ pub async fn workflow_skill_instructions(
     let expanded: Vec<String> = {
         let mut out: Vec<String> = Vec::new();
         for name in requested {
+            let name = &current_skill_name(name, &view);
             match view.bundles.iter().find(|bundle| bundle.name == *name) {
                 Some(bundle) => {
                     if bundle.skills.is_empty() {
@@ -460,17 +498,15 @@ pub async fn workflow_skill_instructions(
             .skills
             .iter()
             .find(|entry| entry.name == *name)
-            .ok_or_else(|| {
-                anyhow::anyhow!("workflow requires skill '{name}', but it is not installed")
-            })?;
+            .ok_or_else(|| missing_workflow_skill(name))?;
         if !visible.state.effective {
             anyhow::bail!(
                 "workflow requires skill '{name}', but it is disabled for this conversation"
             );
         }
-        let skill = skills.get(name).ok_or_else(|| {
-            anyhow::anyhow!("workflow requires skill '{name}', but it is not installed")
-        })?;
+        let skill = skills
+            .get(name)
+            .ok_or_else(|| missing_workflow_skill(name))?;
 
         if !rendered.is_empty() {
             rendered.push_str("\n\n");
@@ -6299,6 +6335,70 @@ Working dir biorouter content
 
         skill_catalog::invalidate();
     }
+
+    /// Diagnostics 20261006_2: a Daily Meditation saved in v1.85.2 names
+    /// `soul-writer`, the Soul skill's name before v1.85.3, and startup deletes
+    /// that folder. A stock copy is upgraded at startup; a copy the person
+    /// edited is not, and failed every night with a skill nothing can install.
+    /// The old name now loads the skill it became, and a skill that really is
+    /// missing is refused with what to do about it.
+    #[tokio::test(flavor = "current_thread")]
+    async fn a_workflow_naming_the_renamed_soul_skill_loads_update_soul() {
+        if !crate::test_sandbox::in_a_process_of_its_own() {
+            return;
+        }
+        let temp = TempDir::new().unwrap();
+        let _env = crate::test_sandbox::relocate_path_root(temp.path().to_str().unwrap());
+        crate::knowledge::soul::ensure_soul_skill(&Paths::config_dir()).unwrap();
+        skill_catalog::invalidate();
+
+        let manager = SessionManager::new(temp.path().join("sessions"));
+        let session = manager
+            .create_session(
+                temp.path().to_path_buf(),
+                "Scheduled job: daily-meditation".into(),
+                crate::session::SessionType::Scheduled,
+            )
+            .await
+            .unwrap();
+
+        let rendered = workflow_skill_instructions(
+            &manager,
+            &session.id,
+            &[crate::knowledge::soul::SOUL_SKILL_DIR_LEGACY.to_string()],
+        )
+        .await
+        .expect("the Soul skill's old name must load the renamed skill");
+        assert!(
+            rendered.contains("# Required workflow skill: update-soul"),
+            "{rendered}"
+        );
+        assert!(rendered.contains("# Writing the Soul"), "{rendered}");
+
+        // Naming both inlines the skill once.
+        let both = workflow_skill_instructions(
+            &manager,
+            &session.id,
+            &["soul-writer".to_string(), "update-soul".to_string()],
+        )
+        .await
+        .unwrap();
+        assert_eq!(both.matches("# Writing the Soul").count(), 1, "{both}");
+
+        let error =
+            workflow_skill_instructions(&manager, &session.id, &["no-such-skill".to_string()])
+                .await
+                .unwrap_err()
+                .to_string();
+        assert!(
+            error.contains("requires skill 'no-such-skill', but it is not installed")
+                && error.contains("Add the skill under Skills")
+                && error.contains("remove 'no-such-skill' from the workflow's skills"),
+            "{error}"
+        );
+
+        skill_catalog::invalidate();
+    }
     /// **`<config>/skills` is spelled once.**
     ///
     /// Three helpers claim to resolve the same path — `skill_catalog::roots()`'s

From 4e2529a9a66658dd32751be5510a8f2cdbac0400 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:10:43 -0700
Subject: [PATCH 10/26] fix(scheduler): a run that fails before its first
 message leaves no empty chat (diagnostics 20261006_2)

The required-skill check runs after a scheduled run makes its chat, so each
night's Daily Meditation failure left one empty 'Scheduled job' row in the
store, hidden from History. Setup after the chat is made (the bind, the
workflow's skills and its own setup) now deletes that chat when it fails, and
the run's error still stands.
---
 crates/biorouter/src/scheduler.rs | 140 ++++++++++++++++++++++++------
 1 file changed, 113 insertions(+), 27 deletions(-)

diff --git a/crates/biorouter/src/scheduler.rs b/crates/biorouter/src/scheduler.rs
index 4ccf541e0..4860bb02f 100644
--- a/crates/biorouter/src/scheduler.rs
+++ b/crates/biorouter/src/scheduler.rs
@@ -2657,6 +2657,20 @@ fn scheduled_prompt(job: &ScheduledJob, workflow: &Workflow) -> String {
     )
 }
 
+/// Delete the chat a scheduled run made for itself when the run failed before
+/// its first message: nothing happened in it, and nobody can open it, because
+/// History lists only chats with messages. A failure to delete is logged and
+/// the run's own error still stands.
+async fn discard_unstarted_run_session(session_manager: &SessionManager, session_id: &str) {
+    if let Err(error) = session_manager.delete_session(session_id).await {
+        tracing::warn!(
+            session_id,
+            "could not delete the empty chat of a scheduled run that failed before it started: \
+             {error:#}"
+        );
+    }
+}
+
 #[allow(clippy::too_many_lines)]
 async fn execute_job(
     job: ScheduledJob,
@@ -2754,36 +2768,51 @@ async fn execute_job(
         )
         .await?;
 
-    agent.update_provider(agent_provider, &session.id).await?;
+    // Everything from here to the first message can still refuse the run: the
+    // bind, a required skill that is missing or switched off, the workflow's
+    // own setup. Such a run never started, so it must not leave its chat
+    // behind. Diagnostics 20261006_2: Daily Meditation failed its skill check
+    // every night, and each failure left one empty "Scheduled job:
+    // daily-meditation" row in the store, hidden from History because it has
+    // no messages.
+    let setup = async {
+        agent.update_provider(agent_provider, &session.id).await?;
+
+        let prepared_workflow_prompt = crate::workflow::runtime::prepare_prompt(
+            agent.config.session_manager.as_ref(),
+            &session.id,
+            &workflow,
+        )
+        .await?;
 
-    let prepared_workflow_prompt = crate::workflow::runtime::prepare_prompt(
-        agent.config.session_manager.as_ref(),
-        &session.id,
-        &workflow,
-    )
-    .await?;
+        // Persist and apply the workflow before the first model call. Scheduled
+        // runs used to load only `extensions`; their declared knowledge base,
+        // required skills, instructions, and structured-output components were
+        // silently ignored until after the turn had already finished.
+        agent
+            .config
+            .session_manager
+            .update(&session.id)
+            .schedule_id(Some(job.id.clone()))
+            .workflow(Some(workflow.clone()))
+            .apply()
+            .await?;
 
-    // Persist and apply the workflow before the first model call. Scheduled
-    // runs used to load only `extensions`; their declared knowledge base,
-    // required skills, instructions, and structured-output components were
-    // silently ignored until after the turn had already finished.
-    agent
-        .config
-        .session_manager
-        .update(&session.id)
-        .schedule_id(Some(job.id.clone()))
-        .workflow(Some(workflow.clone()))
-        .apply()
+        crate::workflow::runtime::install_prepared(
+            &agent,
+            &session.id,
+            &workflow,
+            true,
+            prepared_workflow_prompt,
+        )
         .await?;
-
-    crate::workflow::runtime::install_prepared(
-        &agent,
-        &session.id,
-        &workflow,
-        true,
-        prepared_workflow_prompt,
-    )
-    .await?;
+        Ok::<(), anyhow::Error>(())
+    }
+    .await;
+    if let Err(error) = setup {
+        discard_unstarted_run_session(agent.config.session_manager.as_ref(), &session.id).await;
+        return Err(error);
+    }
 
     let mut jobs_guard = jobs.lock().await;
     if let Some((_, job_def)) = jobs_guard.get_mut(job_id.as_str()) {
@@ -3974,6 +4003,63 @@ mod tests {
         );
     }
 
+    /// Diagnostics 20261006_2: Daily Meditation failed its required-skill check
+    /// every night, and that check runs after the run has made its chat, so
+    /// each failure left an empty "Scheduled job: daily-meditation" row in the
+    /// store. A run that fails before its first message now leaves no chat.
+    ///
+    /// Driven through `execute_job` itself, on a loopback Ollama that is not
+    /// listening: the model is never asked anything, because the skill check
+    /// comes first. The rows live in `SessionManager::instance()`, which
+    /// `Agent::new()` reads, so the run's chat is found by its job id.
+    #[tokio::test(flavor = "current_thread")]
+    async fn a_run_that_fails_before_its_first_message_leaves_no_chat() {
+        let dir = tempdir().unwrap();
+        let workflow = dir.path().join("needs_a_missing_skill.yaml");
+        fs::write(
+            &workflow,
+            "version: 1.0.0\ntitle: Needs a missing skill\ndescription: probe\nprompt: test\n\
+             extensions: []\nskills:\n- no-such-skill-20261006\n",
+        )
+        .unwrap();
+        let job_id = format!("missing-skill-{}", uuid::Uuid::new_v4().simple());
+        let overrides = HashMap::from([
+            ("BIOROUTER_PROVIDER".to_string(), "ollama".to_string()),
+            ("BIOROUTER_MODEL".to_string(), "llama3.1:8b".to_string()),
+            ("OLLAMA_HOST".to_string(), "http://127.0.0.1:9".to_string()),
+        ]);
+        let error = crate::config::with_config_overrides(
+            overrides,
+            execute_job(
+                dormant_job(&job_id, &workflow),
+                Arc::new(Mutex::new(JobsMap::new())),
+                job_id.clone(),
+                CancellationToken::new(),
+            ),
+        )
+        .await
+        .expect_err("a workflow whose required skill is missing must not run");
+        assert!(
+            error.to_string().contains("no-such-skill-20261006"),
+            "precondition: the run failed at its skill check, not before it made its chat: \
+             {error:#}"
+        );
+
+        let name = format!("Scheduled job: {job_id}");
+        let left: Vec<String> = SessionManager::instance()
+            .list_sessions_by_types_including_empty(&[SessionType::Scheduled])
+            .await
+            .unwrap()
+            .into_iter()
+            .filter(|session| session.name == name)
+            .map(|session| session.id)
+            .collect();
+        assert!(
+            left.is_empty(),
+            "a run that never started left its empty chat behind: {left:?}"
+        );
+    }
+
     /// Issue #148B, the half that loses data. Cancellation `break`s the reply
     /// loop rather than erroring, so `execute_job` returned `Ok` and both
     /// completion paths advanced `last_run` — which, for `daily-meditation`, IS

From 1399987d7e9e77c22e2ed8ca31519f5b5d3b443c Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:15:57 -0700
Subject: [PATCH 11/26] docs(extensions): the load toast's comments date the
 twelve-entry capability count

---
 ui/desktop/src/utils/extensionErrorUtils.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/ui/desktop/src/utils/extensionErrorUtils.ts b/ui/desktop/src/utils/extensionErrorUtils.ts
index 91d32e53b..91a7a16b0 100644
--- a/ui/desktop/src/utils/extensionErrorUtils.ts
+++ b/ui/desktop/src/utils/extensionErrorUtils.ts
@@ -17,7 +17,7 @@ export const MAX_ERROR_MESSAGE_LENGTH = 70;
 //
 // One lived at this spot, reading `bundled-extensions.json` for entries typed
 // `builtin` — seven of them — while the composer's extension menu asked the
-// capability catalog, which has twelve. Two answers to one question, five
+// capability catalog, which had twelve then. Two answers to one question, five
 // extensions apart, on two surfaces the user reads against each other. The
 // catalog (`isCapabilityExtension`) is the only definition now, and it lives
 // with the list the menu renders, so a capability added there cannot silently
@@ -136,8 +136,8 @@ export function showExtensionLoadResults(
   //
   // This filter used to ask `isBuiltinExtension`, whose set is the SEVEN entries
   // of `bundled-extensions.json` with `type: "builtin"`. The composer's
-  // extension menu asks `isCapabilityExtension`, whose set is the TWELVE entries
-  // of the capability catalog. The five in the gap — code_execution,
+  // extension menu asks `isCapabilityExtension`, whose set was then the TWELVE
+  // entries of the capability catalog (fourteen since Crew joined it). The five in the gap — code_execution,
   // extensionmanager, skills, todo, chatrecall — ship with Biorouter, are hidden
   // by the chip, and were counted here as if the user had installed them.
   //

From 285ea0fd72e72ad973a970f6695a8ec9dfa6ea23 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:19:27 -0700
Subject: [PATCH 12/26] fix(scheduler): a run whose turn was aborted is a
 failure, and Daily Meditation's cursor stays put (diagnostics 20261006_2)

The agent ends a turn that did not do its work (the model call failed, the
loop guard stopped it) with a 'Ran into this error' message and a TurnAborted
event, and the stream then ends normally. The scheduler ignored the event and
recorded a success: last_error cleared and last_run, Daily Meditation's Chat
Recall cursor, moved past a day nobody digested. Found re-running the
reporter's Daily Meditation once its skill check passed, against a local model
that was not running. TurnAborted now fails the run with its code and message.
---
 crates/biorouter/src/scheduler.rs | 55 +++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/crates/biorouter/src/scheduler.rs b/crates/biorouter/src/scheduler.rs
index 4860bb02f..6c7d67b27 100644
--- a/crates/biorouter/src/scheduler.rs
+++ b/crates/biorouter/src/scheduler.rs
@@ -3050,6 +3050,17 @@ fn finish_scheduled_run(
     }
 }
 
+/// Fold one stream item into the run's transcript, or fail the run.
+///
+/// ⚠ **`TurnAborted` fails the run.** The agent ends a turn that did not do
+/// its work (the model call failed, the loop guard stopped it, the store
+/// failed) with a "Ran into this error" message and then this event, and the
+/// stream ends normally. Read as a completed run, that cleared `last_error`
+/// and advanced `last_run`, which for `daily-meditation` is the Chat Recall
+/// cursor: each night the model could not answer, a day of the person's chats
+/// was skipped and the schedule reported success. Found re-running the Daily
+/// Meditation of diagnostics 20261006_2 once its skill check passed, against a
+/// local model that was not running.
 fn apply_scheduled_stream_item(
     conversation: &mut Conversation,
     item: Result<AgentEvent>,
@@ -3057,6 +3068,13 @@ fn apply_scheduled_stream_item(
     match item? {
         AgentEvent::Message(message) => conversation.push(message),
         AgentEvent::HistoryReplaced(updated) => *conversation = updated,
+        AgentEvent::TurnAborted { code, message } => {
+            return Err(anyhow!(
+                "the run stopped before it did its work ({}), and the schedule's last-run \
+                 cursor was not advanced: {message}",
+                code.wire_code()
+            ));
+        }
         _ => {}
     }
     Ok(())
@@ -5001,6 +5019,43 @@ mod tests {
             .contains("fixture scheduled stream failed"));
     }
 
+    /// A turn the agent aborted (here, the model call failed) ends its stream
+    /// normally, after the "Ran into this error" message. Before this, the run
+    /// was then classified a success: `last_error` cleared and, for Daily
+    /// Meditation, the Chat Recall cursor advanced past a day nobody digested.
+    #[test]
+    fn an_aborted_turn_fails_the_scheduled_run() {
+        let mut conversation = Conversation::default();
+        apply_scheduled_stream_item(
+            &mut conversation,
+            Ok(AgentEvent::Message(Message::assistant().with_text(
+                "Ran into this error: Request failed: error sending request for url \
+                 (http://127.0.0.1:9/api/chat) (failed to connect to 127.0.0.1:9).",
+            ))),
+        )
+        .unwrap();
+        let error = apply_scheduled_stream_item(
+            &mut conversation,
+            Ok(AgentEvent::TurnAborted {
+                code: crate::agents::turn_abort::TurnAbortCode::ProviderFailure {
+                    kind: crate::providers::errors::ProviderErrorKind::Network,
+                },
+                message: "Request failed: failed to connect to 127.0.0.1:9".to_string(),
+            }),
+        )
+        .expect_err("an aborted turn must fail the scheduled run");
+        let error = error.to_string();
+        assert!(
+            error.contains("provider_failure")
+                && error.contains("failed to connect to 127.0.0.1:9")
+                && error.contains("cursor was not advanced"),
+            "{error}"
+        );
+        // The person-facing explanation the agent wrote is still in the run's
+        // transcript.
+        assert_eq!(conversation.len(), 1);
+    }
+
     #[test]
     fn meditation_prompt_uses_the_last_successful_run_as_its_recall_cursor() {
         let cursor = chrono::DateTime::parse_from_rfc3339("2026-08-28T10:11:12Z")

From 75553203eb7284185a8216a5261146831381b196 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:46:25 -0700
Subject: [PATCH 13/26] fix(providers): a reply of tool calls written as text
 is asked about or says nothing ran (diagnostics 20261006_2)

The reporter's llama3.1:8b, in a chat with Code Execution on, answered with
calls written as JSON, and the person read the JSON as the answer with no word
that nothing had happened.

- Two call objects in one reply (reply 11: workspace_read_conversation then
  workspace_read_panel) were neither a call nor an attempt, so the turn ended
  on the JSON. attempted_calls now reads the shapes recovery reads, a run or
  an array of objects, and Ollama's one corrective retry names every tool.
- A reply that is nothing but calls nothing can run (reply 1 text_editor,
  reply 7 shell, reply 15 agent_drafter: tools that chat did not offer) gets
  one line after it, for the person only, saying nothing ran and what may
  help. The agent adds it, so it covers every provider; the model never sees
  it, and the call is never run from text.

The reporter's exact replies are fixtures, and a unit test classifies each:
nothing runs from text, 9 and 11 are asked about, 1, 7 and 15 are noticed,
and the answers (3, 5, 13, 17, 19) are left alone.
---
 crates/biorouter/src/agents/reply_parts.rs    | 243 ++++++++++++-
 .../src/providers/formats/text_tool_calls.rs  | 329 +++++++++++++++++-
 crates/biorouter/src/providers/ollama.rs      |  75 ++--
 .../diagnostics_20261006_2/replies.json       |  45 +++
 4 files changed, 658 insertions(+), 34 deletions(-)
 create mode 100644 crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/replies.json

diff --git a/crates/biorouter/src/agents/reply_parts.rs b/crates/biorouter/src/agents/reply_parts.rs
index a0df0e5bf..3f22fcd6b 100644
--- a/crates/biorouter/src/agents/reply_parts.rs
+++ b/crates/biorouter/src/agents/reply_parts.rs
@@ -508,16 +508,90 @@ impl HeldThinking {
 ///
 /// Split out of [`Agent::stream_response_from_provider`] so the request
 /// plumbing and what is done to each item read separately.
+/// Watches a reply for the one shape that leaves a person reading JSON where an
+/// answer should be: a WHOLE reply of tool calls written as text, in a turn
+/// that offered tools and made no call. Nothing in it ran, and before this
+/// nothing said so.
+///
+/// Diagnostics 20261006_2: llama3.1:8b, in a Code Execution chat, answered
+/// three requests with `text_editor`, `shell` and `agent_drafter` calls
+/// written as JSON. None names a tool that chat offered, so the provider
+/// neither recovered them nor asked the model again, and each turn ended on the
+/// JSON. The person gave up and asked for code to run by hand. The calls are
+/// never run from here either; the person is only told.
+#[derive(Default)]
+struct UnrunCallWatch {
+    text: String,
+    called: bool,
+}
+
+impl UnrunCallWatch {
+    fn observe(&mut self, message: &Message) {
+        self.called |= message.content.iter().any(|content| {
+            matches!(
+                content,
+                MessageContent::ToolRequest(_) | MessageContent::FrontendToolRequest(_)
+            )
+        });
+        for content in &message.content {
+            if let MessageContent::Text(text) = content {
+                self.text.push_str(&text.text);
+            }
+        }
+    }
+
+    /// The notice for a finished reply, when it needs one.
+    fn notice(&self) -> Option<Message> {
+        if self.called {
+            return None;
+        }
+        let names = crate::providers::formats::text_tool_calls::whole_reply_call_names(&self.text)?;
+        Some(unrun_call_notice(&names))
+    }
+}
+
+/// What the person reads under a reply that is only tool calls written as
+/// text. User-only: the model never sees it.
+fn unrun_call_notice(names: &[String]) -> Message {
+    const SHOWN: usize = 3;
+    let mut quoted: Vec<String> = names
+        .iter()
+        .take(SHOWN)
+        .map(|name| format!("'{name}'"))
+        .collect();
+    if names.len() > SHOWN {
+        quoted.push(format!("{} more", names.len() - SHOWN));
+    }
+    let what = match quoted.as_slice() {
+        [one] => format!("a call to {one}"),
+        [first, second] => format!("calls to {first} and {second}"),
+        [init @ .., last] => format!("calls to {} and {last}", init.join(", ")),
+        [] => "a tool call".to_string(),
+    };
+    Message::assistant()
+        .with_system_notification(
+            crate::conversation::message::SystemNotificationType::InlineMessage,
+            format!(
+                "Nothing ran: this reply is {what} written as text, not a tool call Biorouter \
+                 can run. Smaller local models often do this. A larger model, or fewer \
+                 extensions turned on in this chat, may help."
+            ),
+        )
+        .user_only()
+}
+
 fn agent_facing_stream(
     mut stream: MessageStream,
     toolshim_interpreter: Option<OllamaInterpreter>,
     toolshim_tools: Vec<Tool>,
+    tools_offered: bool,
     streaming: bool,
     stream_open_start: std::time::Instant,
 ) -> MessageStream {
     Box::pin(try_stream! {
         let mut toolshim_reply = ToolshimReply::default();
         let mut held_thinking = HeldThinking::default();
+        let mut unrun_calls = UnrunCallWatch::default();
         while let Some(result) = stream.next().await {
             let (message, usage, pending) = match result {
                 Ok(item) => item,
@@ -542,6 +616,9 @@ fn agent_facing_stream(
             if let (Some(message), Some(_)) = (message.as_ref(), toolshim_interpreter.as_ref()) {
                 toolshim_reply.observe(message);
             }
+            if let (Some(message), true) = (message.as_ref(), tools_offered) {
+                unrun_calls.observe(message);
+            }
 
             // Thinking waits for the end of its phase; see `HeldThinking`.
             let message = match message {
@@ -577,10 +654,17 @@ fn agent_facing_stream(
         // provider's own text-then-call stream has.
         if let Some(interpreter) = toolshim_interpreter.as_ref() {
             if let Some(calls) = toolshim_reply.interpret(interpreter, &toolshim_tools).await {
+                unrun_calls.observe(&calls);
                 yield (Some(calls), None, None);
             }
         }
 
+        // Last, after any call the toolshim found: a reply that is nothing but
+        // calls written as text, none of which ran, gets one line saying so.
+        if let Some(notice) = unrun_calls.notice() {
+            yield (Some(notice), None, None);
+        }
+
         // The stream is drained: generation is genuinely finished. This is
         // the marker the old instrumentation lacked entirely, which is why
         // generation time was invisible and prior investigations attributed
@@ -947,10 +1031,12 @@ impl Agent {
             }
         };
 
+        let tools_offered = !tools.is_empty() || !toolshim_tools.is_empty();
         Ok(agent_facing_stream(
             stream,
             toolshim_interpreter,
             toolshim_tools,
+            tools_offered,
             streaming,
             stream_open_start,
         ))
@@ -2389,6 +2475,14 @@ mod tests {
     /// one entry per yielded item.
     async fn through_the_agent_stream(
         items: Vec<Result<crate::providers::base::ProviderStreamItem, ProviderError>>,
+    ) -> Vec<Result<crate::providers::base::ProviderStreamItem, ProviderError>> {
+        through_the_agent_stream_offering(items, &[]).await
+    }
+
+    /// [`through_the_agent_stream`] for a request that offered `tools`.
+    async fn through_the_agent_stream_offering(
+        items: Vec<Result<crate::providers::base::ProviderStreamItem, ProviderError>>,
+        tools: &[Tool],
     ) -> Vec<Result<crate::providers::base::ProviderStreamItem, ProviderError>> {
         let provider: Arc<dyn Provider> = Arc::new(ScriptedStreamProvider {
             items: std::sync::Mutex::new(Some(items)),
@@ -2397,7 +2491,7 @@ mod tests {
             provider,
             "system",
             &[Message::user().with_text("how many rows?")],
-            &[],
+            tools,
             &[],
             None,
         )
@@ -2585,4 +2679,151 @@ mod tests {
             ("second item".to_string(), Some("rs_2".to_string()))
         );
     }
+
+    /// Diagnostics 20261006_2: one of the reporter's exact assistant replies.
+    fn reporter_reply(index: u64) -> String {
+        let doc: Value = serde_json::from_str(include_str!(
+            "../../tests/fixtures/ollama/diagnostics_20261006_2/replies.json"
+        ))
+        .unwrap();
+        doc["replies"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|reply| reply["index"] == index)
+            .and_then(|reply| reply["reply"].as_str())
+            .unwrap_or_else(|| panic!("no reply {index} in the fixture"))
+            .to_string()
+    }
+
+    fn reply_item(text: &str) -> Result<crate::providers::base::ProviderStreamItem, ProviderError> {
+        Ok((
+            Some(Message::assistant().with_text(text).with_id("r1")),
+            None,
+            None,
+        ))
+    }
+
+    /// The inline notice text of an item, when it is one.
+    fn notice_text(
+        item: &Result<crate::providers::base::ProviderStreamItem, ProviderError>,
+    ) -> Option<String> {
+        let (Some(message), None, None) = item.as_ref().ok()? else {
+            return None;
+        };
+        match message.content.as_slice() {
+            [MessageContent::SystemNotification(note)]
+                if note.notification_type
+                    == crate::conversation::message::SystemNotificationType::InlineMessage =>
+            {
+                assert!(
+                    !message.is_agent_visible() && message.is_user_visible(),
+                    "the notice is for the person only: {message:?}"
+                );
+                assert_ne!(message.id.as_deref(), Some("r1"), "its own row");
+                Some(note.msg.clone())
+            }
+            _ => None,
+        }
+    }
+
+    /// Diagnostics 20261006_2: llama3.1:8b, in a chat with Code Execution on,
+    /// answered three requests with a call written as JSON to `text_editor`,
+    /// `shell` and `agent_drafter`, none of them a tool that chat offered.
+    /// Nothing ran and nothing said so; the reporter read the JSON as the
+    /// answer and gave up. The reply still shows as it came, and one line
+    /// after it, for the person only, says that nothing ran.
+    #[tokio::test]
+    async fn a_reply_of_calls_written_as_text_says_that_nothing_ran() {
+        for (index, name) in [
+            (1, "'text_editor'"),
+            (7, "'shell'"),
+            (15, "'agent_drafter'"),
+        ] {
+            let reply = reporter_reply(index);
+            let out = through_the_agent_stream_offering(
+                vec![reply_item(&reply), usage_item()],
+                &[shell_tool()],
+            )
+            .await;
+            assert_eq!(out.len(), 3, "reply {index}: {out:?}");
+            let (Some(shown), None, None) = out[0].as_ref().unwrap() else {
+                panic!("reply {index}: the reply first: {:?}", out[0]);
+            };
+            assert_eq!(
+                shown.as_concat_text(),
+                reply,
+                "the reply is shown as it came"
+            );
+            assert!(matches!(out[1].as_ref().unwrap(), (None, Some(_), None)));
+            let notice = notice_text(&out[2])
+                .unwrap_or_else(|| panic!("reply {index}: a notice last: {:?}", out[2]));
+            assert!(
+                notice.starts_with("Nothing ran: this reply is a call to ")
+                    && notice.contains(name)
+                    && notice.contains("written as text"),
+                "{notice}"
+            );
+        }
+
+        // Reply 11, two calls in one reply.
+        let out = through_the_agent_stream_offering(
+            vec![reply_item(&reporter_reply(11)), usage_item()],
+            &[shell_tool()],
+        )
+        .await;
+        let notice = out.iter().find_map(notice_text).expect("a notice");
+        assert!(
+            notice.contains("calls to 'workspace_read_conversation' and 'workspace_read_panel'"),
+            "{notice}"
+        );
+    }
+
+    /// Answers are never noticed: the reporter's prose, its code for the person
+    /// to run, and the JSON it was asked for. Nor is a reply in a turn that
+    /// offered no tools, nor one whose call was made after all (Ollama's one
+    /// corrective retry turning reply 9 into a real `search_modules` call).
+    #[tokio::test]
+    async fn answers_and_made_calls_get_no_notice() {
+        for index in [3, 5, 13, 17, 19] {
+            let out = through_the_agent_stream_offering(
+                vec![reply_item(&reporter_reply(index)), usage_item()],
+                &[shell_tool()],
+            )
+            .await;
+            assert!(
+                out.iter().all(|item| notice_text(item).is_none()),
+                "reply {index}: {out:?}"
+            );
+        }
+
+        let out =
+            through_the_agent_stream(vec![reply_item(&reporter_reply(7)), usage_item()]).await;
+        assert!(out.iter().all(|item| notice_text(item).is_none()));
+
+        let call = Message::assistant()
+            .with_tool_request(
+                "call-1",
+                Ok(rmcp::model::CallToolRequestParams {
+                    task: None,
+                    name: "code_execution__search_modules".into(),
+                    arguments: Some(object!({"terms": "llama"})),
+                    meta: None,
+                }),
+            )
+            .with_id("r1");
+        let out = through_the_agent_stream_offering(
+            vec![
+                reply_item(&reporter_reply(9)),
+                Ok((Some(call), None, None)),
+                usage_item(),
+            ],
+            &[shell_tool()],
+        )
+        .await;
+        assert!(
+            out.iter().all(|item| notice_text(item).is_none()),
+            "{out:?}"
+        );
+    }
 }
diff --git a/crates/biorouter/src/providers/formats/text_tool_calls.rs b/crates/biorouter/src/providers/formats/text_tool_calls.rs
index 282473d7e..baa44ea37 100644
--- a/crates/biorouter/src/providers/formats/text_tool_calls.rs
+++ b/crates/biorouter/src/providers/formats/text_tool_calls.rs
@@ -314,13 +314,14 @@ fn fence_body(text: &str) -> Option<&str> {
     Some(body)
 }
 
-/// `callseq | callarray`: every element a valid call (G7), or `None`.
-fn payload(text: &str, tools: &[Tool]) -> Option<(Vec<RecoveredCall>, bool)> {
-    let objects: Vec<Value> = if text.starts_with('[') {
+/// The JSON values of `callseq | callarray`, unchecked: one non-empty array,
+/// or one or more values separated only by whitespace, and nothing else.
+fn payload_values(text: &str) -> Option<Vec<Value>> {
+    if text.starts_with('[') {
         // One array, and nothing after it (serde rejects trailing characters).
         match serde_json::from_str::<Value>(text).ok()? {
-            Value::Array(items) if !items.is_empty() => items,
-            _ => return None,
+            Value::Array(items) if !items.is_empty() => Some(items),
+            _ => None,
         }
     } else if text.starts_with('{') {
         // One object, or several separated only by whitespace (llama3.1's raw
@@ -333,10 +334,15 @@ fn payload(text: &str, tools: &[Tool]) -> Option<(Vec<RecoveredCall>, bool)> {
         if objects.is_empty() || values.byte_offset() != text.len() {
             return None;
         }
-        objects
+        Some(objects)
     } else {
-        return None;
-    };
+        None
+    }
+}
+
+/// `callseq | callarray`: every element a valid call (G7), or `None`.
+fn payload(text: &str, tools: &[Tool]) -> Option<(Vec<RecoveredCall>, bool)> {
+    let objects = payload_values(text)?;
     let mut calls = Vec::with_capacity(objects.len());
     let mut phi4 = false;
     for object in &objects {
@@ -479,14 +485,40 @@ pub struct AttemptedCall {
 /// a quote becomes an execution. Measured, it did not even help: llama3.1:8b,
 /// asked once after "I will use the following tool call: {..}", repeated
 /// itself.
+///
+/// The one-call case of [`attempted_calls`].
 pub fn attempted_call(text: &str, tools: &[Tool]) -> Option<AttemptedCall> {
+    let mut calls = attempted_calls(text, tools)?;
+    (calls.len() == 1).then(|| calls.remove(0))
+}
+
+/// [`attempted_call`] for a whole reply of one or more call objects, in the
+/// shapes recovery reads (L2): objects separated only by whitespace, or one
+/// array, optionally fenced or tag-wrapped as one block. Every object must be
+/// a call whose name stands for an advertised tool, or nothing is an attempt,
+/// just as one bad call rejects a whole recovery.
+///
+/// Diagnostics 20261006_2: llama3.1:8b answered "find the blasts in these
+/// notes" with two objects, `workspace_read_conversation` then
+/// `workspace_read_panel`, each a real workspace tool without its prefix.
+/// Read as one value, the pair was neither a call nor an attempt, so the turn
+/// ended on the JSON with nothing asked or run, while either object alone
+/// drew the corrective question.
+pub fn attempted_calls(text: &str, tools: &[Tool]) -> Option<Vec<AttemptedCall>> {
     if tools.is_empty() {
         return None;
     }
     let trimmed = text.trim();
     let inner = unwrap_tags(trimmed, ATTEMPT_TAGS).unwrap_or(trimmed).trim();
     let inner = fence_body(inner).map(str::trim).unwrap_or(inner);
-    let value = serde_json::from_str::<Value>(inner).ok()?;
+    payload_values(inner)?
+        .iter()
+        .map(|value| attempted_object(value, tools))
+        .collect()
+}
+
+/// One call object of an attempt: its name must stand for an advertised tool.
+fn attempted_object(value: &Value, tools: &[Tool]) -> Option<AttemptedCall> {
     let object = value.as_object()?;
     let (name, arguments) = match flat_call(object, true) {
         Some(call) => call,
@@ -608,6 +640,76 @@ pub fn forged_tool_result(text: &str, tools: &[Tool]) -> Option<ForgedResult> {
     })
 }
 
+/// The names of the calls a WHOLE reply writes as text, as written, or `None`.
+///
+/// Every block of the reply must be a call object, a whitespace-separated run
+/// of them or an array of them, bare or in a ```` ```json ```` fence; the
+/// whole may sit in a call or result tag. A name need not be a tool: this
+/// answers "is this reply nothing but calls?", not "which tool was meant?".
+/// Any prose, any other JSON, or one object that is not call-shaped, and it
+/// is `None`.
+///
+/// Detection only, for the notice the agent puts under such a reply
+/// (`agents::reply_parts`): the reply is shown as it is, and the person is
+/// told that nothing ran. Diagnostics 20261006_2: llama3.1:8b in a Code
+/// Execution chat answered with `text_editor`, `shell` and `agent_drafter`
+/// calls written as JSON, none of them a tool that chat offered, so nothing
+/// recovered or asked about them, and the person read raw JSON as the answer
+/// with no word that nothing had happened. Several blocks are read because a
+/// corrective retry that repeats the call joins a second block to the first.
+pub fn whole_reply_call_names(text: &str) -> Option<Vec<String>> {
+    let trimmed = text.trim();
+    let mut rest = unwrap_tags(trimmed, ATTEMPT_TAGS).unwrap_or(trimmed).trim();
+    let mut names = Vec::new();
+    while !rest.is_empty() {
+        let values = if let Some(after_open) = rest.strip_prefix("```") {
+            let after_tag = after_open
+                .strip_prefix("json")
+                .or_else(|| after_open.strip_prefix("JSON"))
+                .unwrap_or(after_open);
+            let (tag, body) = after_tag.split_once('\n')?;
+            if !tag.trim().is_empty() {
+                // ```python and the like: code, not a call.
+                return None;
+            }
+            let (inner, after_fence) = body.split_once("```")?;
+            rest = after_fence.trim_start();
+            payload_values(inner.trim())?
+        } else {
+            // One JSON value, then whitespace, another block, or the end.
+            let mut values = serde_json::Deserializer::from_str(rest).into_iter::<Value>();
+            let value = values.next()?.ok()?;
+            rest = rest.get(values.byte_offset()..)?.trim_start();
+            match value {
+                Value::Array(items) if !items.is_empty() => items,
+                Value::Object(_) => vec![value],
+                _ => return None,
+            }
+        };
+        for value in &values {
+            names.push(written_call_name(value)?);
+        }
+    }
+    (!names.is_empty()).then_some(names)
+}
+
+/// The name of one call object as written (S1-S3), or `None` when the object
+/// is not call-shaped or names nothing.
+fn written_call_name(value: &Value) -> Option<String> {
+    let object = value.as_object()?;
+    let (name, _) = match flat_call(object, true) {
+        Some(call) => call,
+        None if has_exactly(object, &["type", "function"])
+            && object.get("type").and_then(Value::as_str) == Some("function") =>
+        {
+            flat_call(object.get("function")?.as_object()?, false)?
+        }
+        None => return None,
+    };
+    let name = name.trim();
+    (!name.is_empty()).then(|| name.to_string())
+}
+
 // ---------------------------------------------------------------------------
 // R16: argument normalisation, for structured AND recovered calls.
 // ---------------------------------------------------------------------------
@@ -1851,4 +1953,213 @@ mod tests {
         }
         assert_eq!(forged_tool_result(cases[0].0, &[]), None);
     }
+
+    /// Diagnostics 20261006_2: every assistant reply of the reporter's chat,
+    /// verbatim (`tests/fixtures/ollama/diagnostics_20261006_2/replies.json`).
+    fn reporter_reply(index: u64) -> String {
+        let doc: Value = serde_json::from_str(include_str!(
+            "../../../tests/fixtures/ollama/diagnostics_20261006_2/replies.json"
+        ))
+        .unwrap();
+        doc["replies"]
+            .as_array()
+            .unwrap()
+            .iter()
+            .find(|reply| reply["index"] == index)
+            .and_then(|reply| reply["reply"].as_str())
+            .unwrap_or_else(|| panic!("no reply {index} in the fixture"))
+            .to_string()
+    }
+
+    /// What the reporter's Code Execution chat offered the model directly:
+    /// Code Execution's three tools (schemas mirroring its parameter structs),
+    /// a todo tool, and the real workspace tools. Developer and Agent Drafter
+    /// were reachable only from a script.
+    fn reporter_code_execution_roster() -> Vec<Tool> {
+        let mut tools = vec![
+            tool(
+                "code_execution__execute_code",
+                json!({"type": "object", "properties": {
+                    "code": {"type": "string"},
+                    "tool_graph": {"type": "array"}
+                }, "required": ["code"]}),
+            ),
+            tool(
+                "code_execution__read_module",
+                json!({"type": "object", "properties": {"module_path": {"type": "string"}}, "required": ["module_path"]}),
+            ),
+            tool(
+                "code_execution__search_modules",
+                json!({"type": "object", "properties": {
+                    "terms": {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
+                    "regex": {"type": "boolean"}
+                }, "required": ["terms"]}),
+            ),
+            tool(
+                "todo__todo_write",
+                json!({"type": "object", "properties": {"content": {"type": "string"}}, "required": ["content"]}),
+            ),
+        ];
+        for mut workspace in crate::agents::workspace_extension::WorkspaceClient::get_tools() {
+            workspace.name = format!("workspace__{}", workspace.name).into();
+            tools.push(workspace);
+        }
+        tools
+    }
+
+    /// The same chat with Code Execution off: Developer offered directly.
+    fn reporter_direct_roster() -> Vec<Tool> {
+        let mut tools: Vec<Tool> = reporter_code_execution_roster()
+            .into_iter()
+            .filter(|tool| !tool.name.starts_with("code_execution__"))
+            .collect();
+        tools.push(tool(
+            "developer__shell",
+            json!({"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}),
+        ));
+        tools.push(tool(
+            "developer__text_editor",
+            json!({"type": "object", "properties": {
+                "command": {"type": "string"}, "path": {"type": "string"}, "file_text": {"type": "string"}
+            }, "required": ["command", "path"]}),
+        ));
+        tools
+    }
+
+    fn attempt_names(text: &str, tools: &[Tool]) -> Option<Vec<String>> {
+        attempted_calls(text, tools).map(|calls| {
+            calls
+                .into_iter()
+                .flat_map(|call| call.meant)
+                .collect::<Vec<_>>()
+        })
+    }
+
+    /// Diagnostics 20261006_2, reply by reply: what Biorouter makes of each of
+    /// the reporter's exact assistant replies. llama3.1:8b on Ollama, in a chat
+    /// with Code Execution on; the reporter saw raw JSON as the answer to every
+    /// request that needed a tool.
+    ///
+    /// - Nothing is RUN from text: no reply names an offered tool byte for byte
+    ///   with arguments that fit (G5, G6).
+    /// - A whole reply naming an offered tool without its prefix is ASKED for
+    ///   once (`attempted_calls`): reply 9, and since this report reply 11,
+    ///   whose two objects each name a workspace tool.
+    /// - A whole reply of calls that cannot be asked for (a tool Code Execution
+    ///   hides, an extension's name) is shown with a notice that nothing ran
+    ///   (`whole_reply_call_names`): replies 1, 7 and 15, and the same three of
+    ///   9 and 11 if their retry fails.
+    /// - Prose, code for the person to run, and the JSON answer the person asked
+    ///   for (reply 13) are answers: never asked about, never noticed.
+    #[test]
+    fn the_replies_in_diagnostics_20261006_2_are_classified() {
+        let code = reporter_code_execution_roster();
+        let direct = reporter_direct_roster();
+        for index in [1, 3, 5, 7, 9, 11, 13, 15, 17, 19] {
+            let text = reporter_reply(index);
+            for roster in [&code, &direct] {
+                assert_eq!(
+                    recover(&text, roster, Tiers::WholeMessage),
+                    None,
+                    "reply {index} must not run from text"
+                );
+                assert_eq!(forged_tool_result(&text, roster), None, "reply {index}");
+            }
+        }
+
+        let asked = |index: u64, roster: &[Tool]| attempt_names(&reporter_reply(index), roster);
+        assert_eq!(
+            asked(9, &code),
+            Some(vec!["code_execution__search_modules".to_string()])
+        );
+        assert_eq!(
+            asked(11, &code),
+            Some(vec![
+                "workspace__workspace_read_conversation".to_string(),
+                "workspace__workspace_read_panel".to_string(),
+            ]),
+            "each of reply 11's two objects names a workspace tool without its prefix"
+        );
+        // `text_editor` and `shell` are Developer's, which Code Execution
+        // offers only from a script: nothing to ask the model to call there.
+        // Offered directly, they are asked for.
+        assert_eq!(asked(1, &code), None);
+        assert_eq!(asked(7, &code), None);
+        assert_eq!(
+            asked(1, &direct),
+            Some(vec!["developer__text_editor".to_string()])
+        );
+        assert_eq!(
+            asked(7, &direct),
+            Some(vec!["developer__shell".to_string()])
+        );
+        // An extension's name is not a tool's.
+        assert_eq!(asked(15, &code), None);
+        for answer in [3, 5, 13, 17, 19] {
+            assert_eq!(asked(answer, &code), None, "reply {answer}");
+            assert_eq!(asked(answer, &direct), None, "reply {answer}");
+        }
+
+        let noticed = |index: u64| whole_reply_call_names(&reporter_reply(index));
+        assert_eq!(noticed(1), Some(vec!["text_editor".to_string()]));
+        assert_eq!(noticed(7), Some(vec!["shell".to_string()]));
+        assert_eq!(noticed(9), Some(vec!["search_modules".to_string()]));
+        assert_eq!(
+            noticed(11),
+            Some(vec![
+                "workspace_read_conversation".to_string(),
+                "workspace_read_panel".to_string(),
+            ])
+        );
+        assert_eq!(noticed(15), Some(vec!["agent_drafter".to_string()]));
+        for answer in [3, 5, 13, 17, 19] {
+            assert_eq!(noticed(answer), None, "reply {answer} is an answer");
+        }
+    }
+
+    /// The shapes `whole_reply_call_names` reads, beyond the reporter's: a
+    /// retry that repeats the call joins a second block to the first, and an
+    /// array or tag-wrapped payload is still only calls.
+    #[test]
+    fn a_whole_reply_of_calls_is_named_and_anything_else_is_not() {
+        let fenced = "```json\n{\"name\": \"shell\", \"arguments\": {\"commands\": [\"ls\"]}}\n```";
+        for (text, names) in [
+            (
+                format!("{fenced}\n\n{fenced}"),
+                vec!["shell", "shell"],
+            ),
+            (
+                "[{\"name\": \"a\", \"arguments\": {}}, {\"name\": \"b\", \"parameters\": {}}]"
+                    .to_string(),
+                vec!["a", "b"],
+            ),
+            (
+                "<tool_call>\n{\"type\": \"function\", \"function\": {\"name\": \"read\", \"arguments\": \"{}\"}}\n</tool_call>"
+                    .to_string(),
+                vec!["read"],
+            ),
+        ] {
+            assert_eq!(
+                whole_reply_call_names(&text),
+                Some(names.iter().map(|name| name.to_string()).collect()),
+                "{text}"
+            );
+        }
+        for text in [
+            "",
+            "42",
+            "[]",
+            r#"{"sum": 42}"#,
+            r#"{"name": "", "arguments": {}}"#,
+            r#"{"name": "shell", "arguments": {}, "note": "extra key"}"#,
+            // A call followed or preceded by prose is never noticed.
+            "{\"name\": \"shell\", \"arguments\": {}}\nThat lists the folder.",
+            "I will run {\"name\": \"shell\", \"arguments\": {}}",
+            "```python\nprint(1)\n```",
+            // One call and one non-call: not a reply of calls.
+            "{\"name\": \"shell\", \"arguments\": {}}\n{\"total\": 3}",
+        ] {
+            assert_eq!(whole_reply_call_names(text), None, "{text}");
+        }
+    }
 }
diff --git a/crates/biorouter/src/providers/ollama.rs b/crates/biorouter/src/providers/ollama.rs
index 641e63201..1b562f12e 100644
--- a/crates/biorouter/src/providers/ollama.rs
+++ b/crates/biorouter/src/providers/ollama.rs
@@ -1234,31 +1234,56 @@ fn echoes_conversation(
 /// tells the model to run anything, and it never claims what did or did not
 /// run before — only that text is not a call.
 fn attempted_call_nudge(
-    call: &super::formats::text_tool_calls::AttemptedCall,
+    calls: &[super::formats::text_tool_calls::AttemptedCall],
     tools: &[Tool],
 ) -> String {
-    let meant = call
-        .meant
+    let quoted = |names: &[String], joiner: &str| {
+        names
+            .iter()
+            .map(|name| format!("'{name}'"))
+            .collect::<Vec<_>>()
+            .join(joiner)
+    };
+    let written = quoted(
+        &calls
+            .iter()
+            .map(|call| call.name.clone())
+            .collect::<Vec<_>>(),
+        " and ",
+    );
+    let meant = calls
         .iter()
-        .map(|name| format!("'{name}'"))
+        .map(|call| quoted(&call.meant, " or "))
         .collect::<Vec<_>>()
-        .join(" or ");
-    if call.meant.len() == 1 && call.meant[0] == call.name {
-        format!(
-            "Your last reply was a call to '{}' written as text, and text in a reply is never \
-             run as a tool call. If you intended to call {meant}, make it as a tool call with \
-             arguments that match its parameters; otherwise answer in text.",
-            call.name
-        )
-    } else {
-        format!(
-            "Your last reply was a call to '{}' written as text, and text in a reply is never \
-             run as a tool call; there is also no tool with that name. If you intended to call \
-             {meant}, make it as a tool call; otherwise answer in text. The tools you can call \
-             are: {}.",
-            call.name,
+        .join(" and ");
+    let exact = calls
+        .iter()
+        .all(|call| call.meant.len() == 1 && call.meant[0] == call.name);
+    match (calls.len(), exact) {
+        (1, true) => format!(
+            "Your last reply was a call to {written} written as text, and text in a reply is \
+             never run as a tool call. If you intended to call {meant}, make it as a tool call \
+             with arguments that match its parameters; otherwise answer in text."
+        ),
+        (1, false) => format!(
+            "Your last reply was a call to {written} written as text, and text in a reply is \
+             never run as a tool call; there is also no tool with that name. If you intended to \
+             call {meant}, make it as a tool call; otherwise answer in text. The tools you can \
+             call are: {}.",
             correction_tool_names(tools)
-        )
+        ),
+        (_, true) => format!(
+            "Your last reply was calls to {written} written as text, and text in a reply is \
+             never run as a tool call. If you intended to call {meant}, make them as tool calls \
+             with arguments that match their parameters; otherwise answer in text."
+        ),
+        (_, false) => format!(
+            "Your last reply was calls to {written} written as text, and text in a reply is \
+             never run as a tool call; not every one of those names is a tool. If you intended \
+             to call {meant}, make them as tool calls; otherwise answer in text. The tools you \
+             can call are: {}.",
+            correction_tool_names(tools)
+        ),
     }
 }
 
@@ -1704,11 +1729,13 @@ fn native_turn(turn: NativeTurn, first: Response, first_log: RequestLog) -> Mess
                     && !called_a_tool
                     && guard.finish_reason.as_deref() != Some("length"))
                 .then(|| {
-                    super::formats::text_tool_calls::attempted_call(&shown_text, &tools)
-                        .filter(|call| !echoes_conversation(&payload, call))
-                        .map(|call| {
+                    super::formats::text_tool_calls::attempted_calls(&shown_text, &tools)
+                        .filter(|calls| {
+                            !calls.iter().any(|call| echoes_conversation(&payload, call))
+                        })
+                        .map(|calls| {
                             (
-                                attempted_call_nudge(&call, &tools),
+                                attempted_call_nudge(&calls, &tools),
                                 "the model's whole reply was a tool call written as text; asking \
                                  it once more to make it as a call",
                             )
diff --git a/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/replies.json b/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/replies.json
new file mode 100644
index 000000000..fb7f99c9a
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/replies.json
@@ -0,0 +1,45 @@
+{
+  "note": "Every assistant reply in session 20261006_2 of diagnostics bundle 20261006_2 (Biorouter 1.92.0 on an Intel Mac, Ollama with llama3.1:8b and qwen2.5-coder:7b, Code Execution on). Verbatim, except that the account name in file paths is replaced with reporter. index is the message index in the session; the user message before each reply is at index - 1.",
+  "replies": [
+    {
+      "index": 1,
+      "reply": "```json\n{\n  \"name\": \"text_editor\",\n  \"arguments\": {\n    \"language\": \"python\",\n    \"content\": \"def factorial(n):\\n    if n == 0:\\n        return 0\\n    elif n == 1:\\n        return 1\\n    else:\\n        return n * factorial(n - 1)\"\n  }\n}\n```"
+    },
+    {
+      "index": 3,
+      "reply": "Sure! Here's the equivalent data in straight Python with JSON formatted strings as function arguments:\n\n```python\nimport json\n\nfunction_calls = [\n    {\n        \"name\": \"workspace__workspace_read_panel\",\n        \"arguments\": json.dumps({\n            \"capture\": False,\n            \"max_chars\": 20000,\n            \"session_id\": None\n        })\n    },\n    {\n        \"name\": \"workspace__workspace_send_prompt\",\n        \"arguments\": json.dumps({\n            \"mode\": \"turn\",\n            \"session_id\": None,\n            \"text\": \"Inject some prompt here\",\n            \"timeout_s\": None,\n            \"wait\": \"final_message\"\n        })\n    },\n    {\n        \"name\": \"workspace__workspace_set_tools\",\n        \"arguments\": json.dumps({\n            \"add_extensions\": [],\n            \"add_skills\": [\"skill1\", \"skill2\"],\n            \"model\": None,\n            \"primary_knowledge_base\": None,\n            \"provider\": None,\n            \"remove_extensions\": [],\n            \"remove_skills\": [],\n            \"session_id\": None,\n            \"set_knowledge_bases\": [\"kb1\", \"kb2\"]\n        })\n    },\n    {\n        \"name\": \"workspace__workspace_watch\",\n        \"arguments\": json.dumps({\n            \"assume_running\": False,\n            \"mode\": \"any\",\n            \"session_ids\": [\"session_id1\", \"session_id2\"],\n            \"timeout_s\": 120\n        })\n    }\n]\n```\n\nTo invoke these functions, you can create a function that takes the function name and arguments, and calls the appropriate Python function based on the name. However, since the actual function implementations aren't provided, I'll show you how you might structure this:\n\n```python\ndef call_function(function_name, arguments):\n    if function_name == \"workspace__workspace_read_panel\":\n        return workspace__workspace_read_panel(json.loads(arguments))\n    elif function_name == \"workspace__workspace_send_prompt\":\n        return workspace__workspace_send_prompt(json.loads(arguments))\n    elif function_name == \"workspace__workspace_set_tools\":\n        return workspace__workspace_set_tools(json.loads(arguments))\n    elif function_name == \"workspace__workspace_watch\":\n        return workspace__workspace_watch(json.loads(arguments))\n    else:\n        raise ValueError(f\"Unknown function: {function_name}\")\n\n# Example usage:\nresults = [call_function(call[\"name\"], call[\"arguments\"]) for call in function_calls]\n```\n\nIn this example, `workspace__workspace_read_panel`, `workspace__workspace_send_prompt`, `workspace__workspace_set_tools`, and `workspace__workspace_watch` should be defined elsewhere in your codebase to handle the actual logic. Each function would take a single argument, which is a dictionary of the function's arguments."
+    },
+    {
+      "index": 5,
+      "reply": "Understood. To create a simple Python script that calculates the factorial of a given number and exits, you can follow these steps:\n\n1. Create a new file called `factorial.py`.\n2. Write the Python code to calculate the factorial.\n3. Ensure the script halts and exits after calculating the factorial.\n\nHere's an example of what the `factorial.py` file might look like:\n\n```python\nimport sys\n\ndef factorial(n):\n    if n < 0:\n        return \"Factorial is not defined for negative numbers\"\n    elif n == 0:\n        return 1\n    else:\n        result = 1\n        for i in range(1, n + 1):\n            result *= i\n        return result\n\nif __name__ == \"__main__\":\n    if len(sys.argv) != 2:\n        print(\"Usage: python factorial.py <integer>\")\n        sys.exit(1)\n\n    try:\n        n = int(sys.argv[1])\n    except ValueError:\n        print(\"Please provide a valid integer\")\n        sys.exit(1)\n\n    print(factorial(n))\n    sys.exit(0)\n```\n\nExplanation:\n- The script takes one argument from the command line, which is converted to an integer.\n- It defines a function `factorial` that calculates the factorial of a non-negative integer.\n- The script checks if the number of arguments is correct and if the argument is a valid integer.\n- It prints the factorial of the number and then exits using `sys.exit(0)`.\n\nTo use this script, you would save it as `factorial.py`, and then run it from the command line like this:\n\n```sh\npython factorial.py 5\n```\n\nThis should output:\n\n```\n120\n```\n\nAnd the script will exit."
+    },
+    {
+      "index": 7,
+      "reply": "{\"name\": \"shell\", \"arguments\": {\"commands\": [\"cat ~/temp\"]}}"
+    },
+    {
+      "index": 9,
+      "reply": "```json\n{\n  \"name\": \"search_modules\",\n  \"arguments\": {\n    \"query\": \"llama3.1:8b\"\n  }\n}\n```"
+    },
+    {
+      "index": 11,
+      "reply": "{\n  \"name\": \"workspace_read_conversation\",\n  \"arguments\": {\n    \"session_id\": \"/Users/reporter/temp\"\n  }\n}\n\n{\n  \"name\": \"workspace_read_panel\",\n  \"arguments\": {\n    \"capture\": false,\n    \"session_id\": \"/Users/reporter/temp\"\n  }\n}"
+    },
+    {
+      "index": 13,
+      "reply": "{\n  \"diagnoses\": 0,\n  \"medications\": 0,\n  \"procedures\": 0,\n  \"symptoms\": 0,\n  \"relevant_dates\": 0,\n  \"negated_findings\": 0,\n  \"family_history_only_findings\": 0,\n  \"uncertainty_rule_out_statements\": 0\n}"
+    },
+    {
+      "index": 15,
+      "reply": "{\n  \"name\": \"agent_drafter\",\n  \"arguments\": {\n    \"text\": \"In the provided notes, count all occurrences of the word 'urine', case insensitive.\"\n  }\n}"
+    },
+    {
+      "index": 17,
+      "reply": "Based on the provided information, the code that solves the problem is as follows:\n\n```javascript\nimport { shell } from \"developer\";\n\nconst tempDir = \"/Users/reporter/temp\";\nconst notesFilePath = `${tempDir}/clinical_notes.txt`;\n\n// Read the notes file and count occurrences of \"urine\" (case insensitive)\nshell.cat(notesFilePath).then(notes => {\n  const count = (notes.match(/\\braine/gi) || []).length;\n  console.log(`The word \"urine\" appears ${count} times.`);\n});\n```\n\nPlease note that, as mentioned in the description, the `shell.cat` tool is not defined by default, and you need to make sure it's available in your local environment. If it's not, you can define a custom function that reads the file and returns its contents.\n\nAdditionally, you might want to consider handling errors and edge cases, depending on your specific requirements."
+    },
+    {
+      "index": 19,
+      "reply": "Here is the Python code as a .py file based on the specified calling parameter to return the count of occurrences of \"urine\" (case-insensitive):\n```python\nimport sys\n\ndef countoccurrences():\n    result = {}\n    with open('/var/log/brat.log', 'r') as f:\n        for line in f:\n            linesplit = line.split()\n            for word in linesplit:\n                word = word.lower()\n                if word in result:\n                    result[word] += 1\n                else:\n                    result[word] = 1\n    return result\n\ndef searchparams(params_str, word):\n    word = word.lower()\n    paramsplit = params_str.split()\n    count = 0\n    newparams = []\n    for param in paramsplit:\n        if word in param:\n            count += 1\n        else:\n            newparams.append(param)\n    return count, ' '.join(newparams)\n\ndef main():\n    if len(sys.argv) < 2:\n        print(\"Error: missing parameter\")\n        return\n    with open('/var/log/brat.log', 'r') as f:\n        for line in f:\n            linesplit = line.split()\n            for word in linesplit:\n                if word.lower() == sys.argv[1]:\n                    print(1)\n                    return\n\n    params_str = ''\n    with open('/var/log/brat.log', 'r') as f:\n        found = False\n        for line in f:\n            linesplit = line.split()\n            if found:\n                params_str += ' ' + ' '.join(linesplit)\n            else:\n                for word in linesplit:\n                    if word.lower() == sys.argv[1]:\n                        params_str = ' '.join(linesplit)\n                        found = True\n        if not found:\n            print(\"No occurrences found\")\n            return\n\n    try:\n        if sys.argv[1].lower() == 'workspace_read_conversation':\n            params_str = workspace__workspace_read_conversation(sys.argv[1])\n        elif sys.argv[1].lower() == 'workspace_send_prompt':\n            params_str = workspace__workspace_send_prompt(sys.argv[1])\n        elif sys.argv[1].lower() == 'workspace_set_tools':\n            params_str = workspace__workspace_set_tools(sys.argv[1])\n        elif sys.argv[1].lower() == 'workspace_watch':\n            params_str = workspace__workspace_watch(sys.argv[1])\n\n    except Exception as e:\n        print(\"exception found:\", e)\n\n    count = 0\n    paramsdict = {}\n    words = sys.argv[1].strip().lower().split()\n    for word in words:\n        count += 1\n    if count == 0:\n        params_str = sys.argv[1]\n        count, newparams = searchparams(params_str, sys.argv[1])\n\n        print(\"Parameter: \" + params_str)\n        print(\"Parameter after removal of '\" + sys.argv[1] + \"': \" + newparams)\n        print(\"Count of '\" + sys.argv[1] + \"': \" + str(count))\n    else:\n        print(str(count))\nif __name__ == \"__main__\":\n    main()\n```\nJust copy and paste this code into a .py file and run it, passing in the desired string as a parameter. For example, for searching for the word \"hepatitis b\" you should call it with `python stringcount.py \"hepatitis b\"`. The output will be the count of occurrences of the string. \n\nNote: The code assumes that the brat.log file contains information needed for the workspace tools (i.e. `workspace_read_conversation`, `workspace_send_prompt`, etc.) and the counts are obtained by reading this file."
+    }
+  ]
+}

From 06efc28b500b846f62431b253ec93ea4531c4892 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:53:09 -0700
Subject: [PATCH 14/26] fix(ollama): a first prompt that outlasts
 OLLAMA_TIMEOUT says so and is sent once (diagnostics 20261006_2)

Ollama sends nothing while it reads a prompt. On the reporter's Intel Mac
(about 25 prompt tokens a second) the whole first prompt of about 37,000
tokens outlasts the 600-second bound, and the person read 'Request failed:
error sending request for url (.../api/chat) (timeout)'. The provider already
refuses to re-send a timeout, since the server is still reading the first
copy, but the agent classed it as a network blip and sent the whole prompt
again: twenty minutes for a sentence that names neither the bound nor the
prompt.

A timeout before the reply begins is now ProviderError::IdleTimeout, a
sentence naming the seconds waited, the prompt's rough size in tokens and the
setting to raise (OLLAMA_TIMEOUT, or a custom provider's timeout_seconds). It
is classed as network for exit codes and wire frames, and the agent never
retries it.
---
 crates/biorouter/src/agents/mistakes.rs  |   3 +
 crates/biorouter/src/providers/errors.rs |  17 +++
 crates/biorouter/src/providers/ollama.rs | 131 ++++++++++++++++++++++-
 crates/biorouter/src/providers/retry.rs  |   1 +
 4 files changed, 148 insertions(+), 4 deletions(-)

diff --git a/crates/biorouter/src/agents/mistakes.rs b/crates/biorouter/src/agents/mistakes.rs
index b4675968e..27e8f4e0c 100644
--- a/crates/biorouter/src/agents/mistakes.rs
+++ b/crates/biorouter/src/agents/mistakes.rs
@@ -186,6 +186,9 @@ pub fn is_recoverable(error: &ProviderError) -> bool {
                 | crate::providers::errors::ProviderErrorKind::Network
                 | crate::providers::errors::ProviderErrorKind::Other
         ),
+        // Already given up on by the provider, for a reason a re-send cannot
+        // change: the local server is still reading the first copy.
+        ProviderError::IdleTimeout(_) => false,
         ProviderError::Authentication(_)
         | ProviderError::RateLimitExceeded { .. }
         | ProviderError::NotImplemented(_)
diff --git a/crates/biorouter/src/providers/errors.rs b/crates/biorouter/src/providers/errors.rs
index 7a9d07876..4fe055d20 100644
--- a/crates/biorouter/src/providers/errors.rs
+++ b/crates/biorouter/src/providers/errors.rs
@@ -30,6 +30,21 @@ pub enum ProviderError {
 
     #[error("Unsupported operation: {0}")]
     NotImplemented(String),
+
+    /// A local inference server sent nothing for the provider's idle bound
+    /// (`OLLAMA_TIMEOUT`). The text is a whole sentence naming the setting to
+    /// raise.
+    ///
+    /// Its own variant because it must not be re-sent by ANYONE. The provider
+    /// already hands a timeout straight back (`retry::TimeoutRetry::GiveUp`):
+    /// the server is still reading the abandoned request, and a second copy
+    /// queues behind it. As a `RequestFailed` it was classed a network blip
+    /// and the agent re-sent the whole prompt once anyway. Diagnostics
+    /// 20261006_2: on an Intel Mac reading about 25 prompt tokens a second, a
+    /// first prompt of about 37,000 tokens outlasts a 600-second bound, so the
+    /// person waited twenty minutes for "error sending request ... (timeout)".
+    #[error("{0}")]
+    IdleTimeout(String),
 }
 
 /// The coarse class of a provider failure — enough for a caller to decide
@@ -252,6 +267,7 @@ impl ProviderError {
             | ProviderError::ExecutionError(details)
             | ProviderError::UsageError(details) => classify_provider_details(details),
             ProviderError::NotImplemented(_) => ProviderErrorKind::InvalidRequest,
+            ProviderError::IdleTimeout(_) => ProviderErrorKind::Network,
         }
     }
 
@@ -265,6 +281,7 @@ impl ProviderError {
             ProviderError::ExecutionError(_) => "execution",
             ProviderError::UsageError(_) => "usage",
             ProviderError::NotImplemented(_) => "not_implemented",
+            ProviderError::IdleTimeout(_) => "timeout",
         }
     }
 }
diff --git a/crates/biorouter/src/providers/ollama.rs b/crates/biorouter/src/providers/ollama.rs
index 1b562f12e..a6e9f83d7 100644
--- a/crates/biorouter/src/providers/ollama.rs
+++ b/crates/biorouter/src/providers/ollama.rs
@@ -128,6 +128,21 @@ const BUILTIN_WINDOW_SETTING: &str = "OLLAMA_NUM_CTX";
 /// which `BIOROUTER_CONTEXT_LIMIT` is the way to set.
 const CUSTOM_WINDOW_SETTING: &str = "BIOROUTER_CONTEXT_LIMIT";
 
+/// The setting that bounds how long the built-in provider waits on a silent
+/// server.
+const BUILTIN_TIMEOUT_SETTING: &str = "OLLAMA_TIMEOUT";
+/// The same for an Ollama-engine provider declared in a `custom_providers`
+/// file: that file's `timeout_seconds`.
+const CUSTOM_TIMEOUT_SETTING: &str = "timeout_seconds";
+
+/// The settings a provider's errors tell the person to change: the built-in
+/// provider's, or a custom provider's.
+#[derive(Clone, Copy)]
+struct SettingNames {
+    window: &'static str,
+    timeout: &'static str,
+}
+
 /// An output budget below this is spent on reasoning before an answer begins,
 /// so a request that pins one gets thinking off unless Deep effort asked for it.
 /// `biorouter configure` probes with 50 tokens: qwen3.8:27b at its default
@@ -1865,6 +1880,13 @@ pub struct OllamaProvider {
     /// nothing.
     #[serde(skip)]
     window_setting: &'static str,
+    /// How long this server may stay silent before a request is given up on,
+    /// and the setting that changes it, both named when that happens
+    /// ([`waited_too_long`]).
+    #[serde(skip)]
+    idle: Duration,
+    #[serde(skip)]
+    timeout_setting: &'static str,
     /// The `num_ctx` chosen per model, once. Only filled from a resolution that
     /// had `/api/show`'s answer, so a server that was briefly unreachable is
     /// asked again rather than pinned to a window chosen without the model's
@@ -1909,7 +1931,10 @@ impl OllamaProvider {
             true,
             Self::metadata().name,
             read_settings(config),
-            BUILTIN_WINDOW_SETTING,
+            SettingNames {
+                window: BUILTIN_WINDOW_SETTING,
+                timeout: BUILTIN_TIMEOUT_SETTING,
+            },
         )
     }
 
@@ -1931,7 +1956,10 @@ impl OllamaProvider {
             config.supports_streaming.unwrap_or(true),
             config.name.clone(),
             OllamaSettings::defaults(),
-            CUSTOM_WINDOW_SETTING,
+            SettingNames {
+                window: CUSTOM_WINDOW_SETTING,
+                timeout: CUSTOM_TIMEOUT_SETTING,
+            },
         )
     }
 
@@ -1942,7 +1970,7 @@ impl OllamaProvider {
         supports_streaming: bool,
         name: String,
         settings: OllamaSettings,
-        window_setting: &'static str,
+        names: SettingNames,
     ) -> Result<Self> {
         let auth = AuthMethod::Custom(Box::new(NoAuth));
         let resolved_base_url = base_url.to_string();
@@ -1958,7 +1986,9 @@ impl OllamaProvider {
             name,
             resolved_base_url,
             settings,
-            window_setting,
+            window_setting: names.window,
+            idle,
+            timeout_setting: names.timeout,
             windows: Mutex::new(HashMap::new()),
             live_context_limit: AtomicUsize::new(0),
             openai_compat: AtomicBool::new(false),
@@ -2400,6 +2430,7 @@ impl OllamaProvider {
                 .await
             })
             .await
+            .map_err(|e| waited_too_long(e, self.idle, self.timeout_setting, check.text_bytes))
             .inspect_err(|e| {
                 let _ = log.provider_error(e);
             })?;
@@ -2579,6 +2610,7 @@ impl OllamaProvider {
             })
             .await
             .map_err(|e| v1_capability_error(e, &self.model.model_name))
+            .map_err(|e| waited_too_long(e, self.idle, self.timeout_setting, check.text_bytes))
             .inspect_err(|e| {
                 let _ = log.provider_error(e);
             })?;
@@ -2599,6 +2631,50 @@ impl OllamaProvider {
     }
 }
 
+/// A request this server answered with nothing at all for `idle`, as the error
+/// the person reads; any other error is returned as it came.
+///
+/// Ollama sends no byte while it reads a prompt, so the first sign of a prompt
+/// too long for this computer is this bound firing before the reply begins.
+/// It used to arrive as "Request failed: error sending request for url
+/// (.../api/chat) (timeout)", which names neither the bound nor the prompt, and
+/// as a network blip the agent re-sent the whole prompt once more behind the
+/// first. Diagnostics 20261006_2: an Intel Mac reading about 25 prompt tokens a
+/// second against a first prompt of about 37,000 tokens and a 600-second
+/// bound. [`ProviderError::IdleTimeout`] is re-sent by nobody.
+///
+/// The token count is the request's text at four bytes a token, rounded: an
+/// order of magnitude to act on, not a measurement.
+fn waited_too_long(
+    error: ProviderError,
+    idle: Duration,
+    timeout_setting: &str,
+    text_bytes: usize,
+) -> ProviderError {
+    if !super::retry::is_timeout(&error) || matches!(error, ProviderError::IdleTimeout(_)) {
+        return error;
+    }
+    let tokens = ((text_bytes / 4 + 500) / 1000).max(1) * 1000;
+    let tokens = tokens
+        .to_string()
+        .as_bytes()
+        .rchunks(3)
+        .rev()
+        .map(|digits| String::from_utf8_lossy(digits).into_owned())
+        .collect::<Vec<_>>()
+        .join(",");
+    let waited = match idle.as_secs() {
+        1 => "1 second".to_string(),
+        seconds => format!("{seconds} seconds"),
+    };
+    ProviderError::IdleTimeout(format!(
+        "Ollama sent nothing back for {waited}, so Biorouter stopped waiting. This request's \
+         prompt is about {tokens} tokens, and a computer without a fast GPU can take longer \
+         than that just to read it. Raise {timeout_setting}, or turn off extensions this chat \
+         does not need so the prompt is shorter."
+    ))
+}
+
 /// R19 on the `/v1` fallback: OpenAI's error shape carries the same sentence
 /// as the native 400 (`{"error":{"message":"... does not support tools",
 /// "type":"invalid_request_error"}}` from gemma3:4b), and is answered the same
@@ -5385,4 +5461,51 @@ mod tests {
         assert!(text.contains("reasoning only"), "{text}");
         assert!(!text.contains("could not parse"), "{text}");
     }
+
+    /// Diagnostics 20261006_2: what the reporter would read when the built-in
+    /// provider's 600-second bound fires before Ollama has read their 164,005
+    /// bytes of prompt. Anything that is not a timeout passes through as it
+    /// came.
+    #[test]
+    fn a_timeout_before_the_reply_names_the_setting_and_the_prompt_size() {
+        let timed_out = ProviderError::RequestFailed(
+            "error sending request for url (http://127.0.0.1:11434/api/chat) (timeout)".to_string(),
+        );
+        let error = waited_too_long(
+            timed_out,
+            Duration::from_secs(OLLAMA_TIMEOUT),
+            BUILTIN_TIMEOUT_SETTING,
+            164_005,
+        );
+        let ProviderError::IdleTimeout(text) = &error else {
+            panic!("{error:?}");
+        };
+        assert_eq!(
+            text,
+            "Ollama sent nothing back for 600 seconds, so Biorouter stopped waiting. This \
+             request's prompt is about 41,000 tokens, and a computer without a fast GPU can take \
+             longer than that just to read it. Raise OLLAMA_TIMEOUT, or turn off extensions this \
+             chat does not need so the prompt is shorter."
+        );
+        assert!(!crate::agents::mistakes::is_recoverable(&error));
+        assert!(super::super::retry::is_timeout(&error));
+
+        let others = || {
+            [
+                ProviderError::RequestFailed(
+                    "error sending request for url (http://127.0.0.1:9/api/chat) (failed to \
+                     connect to 127.0.0.1:9)"
+                        .to_string(),
+                ),
+                ProviderError::ServerError("502".to_string()),
+                ProviderError::IdleTimeout("already said".to_string()),
+            ]
+        };
+        for (other, unchanged) in others().into_iter().zip(others()) {
+            assert_eq!(
+                waited_too_long(other, Duration::from_secs(600), "X", 10),
+                unchanged
+            );
+        }
+    }
 }
diff --git a/crates/biorouter/src/providers/retry.rs b/crates/biorouter/src/providers/retry.rs
index 8e7f2aa06..698a06446 100644
--- a/crates/biorouter/src/providers/retry.rs
+++ b/crates/biorouter/src/providers/retry.rs
@@ -147,6 +147,7 @@ pub enum TimeoutRetry {
 /// reqwest timeout `(timeout)`; a body read that stalls says "timed out".
 pub fn is_timeout(error: &ProviderError) -> bool {
     match error {
+        ProviderError::IdleTimeout(_) => true,
         ProviderError::RequestFailed(details) | ProviderError::ExecutionError(details) => {
             let details = details.to_ascii_lowercase();
             error.kind() == super::errors::ProviderErrorKind::Network

From 6dc074763cc62a7631f9ccd6ccb7741bacee8281 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 15:53:09 -0700
Subject: [PATCH 15/26] test(ollama): replay diagnostics 20261006_2 through the
 provider and the agent

The reporter's exact replies, served from a mock Ollama with the usage the
bundle measured, through the real provider: the cut first turn (164,005
bytes answered from 2,046 + 4 prompt tokens) is refused and the request asks
for the window it needs; qwen2.5-coder at its 32,768 trained window refuses the
reporter's prompt size; replies 9 and 11 are asked about once, naming the real
tools; replies 1, 7 and 15 in the Code Execution chat are shown and never run;
reply 7 with Developer offered is asked about; the answers are left alone; a
first prompt slower than the idle bound names the setting and is sent once.
Through the agent, reply 7 gets the line saying nothing ran, stored for the
person only and kept out of the model's next request.
---
 .../tests/ollama_diagnostics_20261006_2.rs    | 797 ++++++++++++++++++
 1 file changed, 797 insertions(+)
 create mode 100644 crates/biorouter/tests/ollama_diagnostics_20261006_2.rs

diff --git a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
new file mode 100644
index 000000000..5af3e04e6
--- /dev/null
+++ b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
@@ -0,0 +1,797 @@
+//! Diagnostics bundle 20261006_2, replayed against the real Ollama provider.
+//!
+//! The report: Biorouter 1.92.0 on an Intel Mac, Ollama with llama3.1:8b and
+//! qwen2.5-coder:7b, a chat with Code Execution on. Every request that needed a
+//! tool came back as JSON, and the person "decided just to ask for the code and
+//! run it myself". The cause (fixed in #393) was the `/v1` route, which cannot
+//! set Ollama's context window: each ~160 KB request was cut to 2,050 tokens,
+//! so the model saw the end of the tool list and the question, and wrote calls
+//! to tools it could not see as text.
+//!
+//! Each test serves one of the reporter's exact assistant replies
+//! (`tests/fixtures/ollama/diagnostics_20261006_2/replies.json`, the account
+//! name in paths replaced) from a mock Ollama, with the reporter's measured
+//! usage where it matters, and asserts what Biorouter does with it today: the
+//! cut turn is refused, a call to an offered tool written as text is asked for
+//! once, a call nothing can run is shown and never run (the agent adds a line
+//! saying so; `agents::reply_parts` tests that), an answer is an answer, and a
+//! first prompt that outlasts the idle bound says which setting to raise and is
+//! sent once.
+//!
+//! Nothing here reaches a network beyond the loopback mock server.
+
+use biorouter::agents::workspace_extension::WorkspaceClient;
+use biorouter::config::declarative_providers::{DeclarativeProviderConfig, ProviderEngine};
+use biorouter::conversation::message::{Message, MessageContent, ToolRequest};
+use biorouter::model::ModelConfig;
+use biorouter::providers::base::{Provider, ProviderStreamItem};
+use biorouter::providers::errors::{ProviderError, ProviderErrorKind};
+use biorouter::providers::ollama::OllamaProvider;
+use futures::StreamExt;
+use rmcp::model::Tool;
+use serde_json::{json, Value};
+use wiremock::matchers::{method, path};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+/// Sandbox this binary's config root before any test runs: the request log
+/// directory and `Config::global()` resolve from `BIOROUTER_PATH_ROOT` the
+/// first time anything touches them. An outer root wins.
+#[ctor::ctor]
+fn sandbox_config_root_for_this_test_binary() {
+    if biorouter::config::paths::Paths::path_root_override().is_some() {
+        return;
+    }
+    let root = tempfile::TempDir::new().expect("a scratch config root");
+    std::env::set_var("BIOROUTER_PATH_ROOT", root.path());
+    static ROOT: std::sync::OnceLock<tempfile::TempDir> = std::sync::OnceLock::new();
+    let _ = ROOT.set(root);
+}
+
+const FIXTURES: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures/ollama");
+
+/// The reporter's exact reply at `index` in the session.
+fn reply(index: u64) -> String {
+    let doc: Value = serde_json::from_str(
+        &std::fs::read_to_string(format!("{FIXTURES}/diagnostics_20261006_2/replies.json"))
+            .unwrap(),
+    )
+    .unwrap();
+    doc["replies"]
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|reply| reply["index"] == index)
+        .and_then(|reply| reply["reply"].as_str())
+        .unwrap_or_else(|| panic!("no reply {index} in the fixture"))
+        .to_string()
+}
+
+fn tool(name: &str, schema: Value) -> Tool {
+    Tool::new(
+        name.to_string(),
+        format!("{name} tool"),
+        rmcp::model::object(schema),
+    )
+}
+
+/// What the reporter's chat offered the model directly with Code Execution
+/// on: its three tools (schemas mirroring its parameter structs), a todo tool,
+/// and the real workspace tools. Developer and Agent Drafter were reachable
+/// only from a script.
+fn code_execution_roster() -> Vec<Tool> {
+    let mut tools = vec![
+        tool(
+            "code_execution__execute_code",
+            json!({"type": "object", "properties": {
+                "code": {"type": "string"}, "tool_graph": {"type": "array"}
+            }, "required": ["code"]}),
+        ),
+        tool(
+            "code_execution__read_module",
+            json!({"type": "object", "properties": {"module_path": {"type": "string"}}, "required": ["module_path"]}),
+        ),
+        tool(
+            "code_execution__search_modules",
+            json!({"type": "object", "properties": {
+                "terms": {"anyOf": [{"type": "string"}, {"type": "array", "items": {"type": "string"}}]},
+                "regex": {"type": "boolean"}
+            }, "required": ["terms"]}),
+        ),
+        tool(
+            "todo__todo_write",
+            json!({"type": "object", "properties": {"content": {"type": "string"}}, "required": ["content"]}),
+        ),
+    ];
+    for mut workspace in WorkspaceClient::get_tools() {
+        workspace.name = format!("workspace__{}", workspace.name).into();
+        tools.push(workspace);
+    }
+    tools
+}
+
+/// The same chat with Code Execution off: Developer offered directly.
+fn direct_roster() -> Vec<Tool> {
+    let mut tools: Vec<Tool> = code_execution_roster()
+        .into_iter()
+        .filter(|tool| !tool.name.starts_with("code_execution__"))
+        .collect();
+    tools.push(tool(
+        "developer__shell",
+        json!({"type": "object", "properties": {"command": {"type": "string"}}, "required": ["command"]}),
+    ));
+    tools
+}
+
+/// `/api/show` for a model that calls tools, trained on `context_length`.
+fn show(context_length: u64, template: Option<String>) -> Value {
+    let mut body = json!({
+        "capabilities": ["completion", "tools"],
+        "model_info": {"general.architecture": "llama", "llama.context_length": context_length},
+    });
+    if let Some(template) = template {
+        body["template"] = json!(template);
+    }
+    body
+}
+
+/// One non-streamed native body answering `content`, with the prompt counts
+/// the server reported.
+fn text_body(content: &str, prompt: u64, cached: u64) -> String {
+    json!({
+        "model": "model",
+        "message": {"role": "assistant", "content": content},
+        "done": true, "done_reason": "stop",
+        "prompt_eval_count": prompt, "prompt_eval_cached_count": cached, "eval_count": 120,
+    })
+    .to_string()
+}
+
+/// One native body making a structured call.
+fn structured_call(name: &str, arguments: Value) -> String {
+    json!({
+        "model": "model",
+        "message": {"role": "assistant", "content": "",
+                    "tool_calls": [{"id": "call_ok", "function": {"name": name, "arguments": arguments}}]},
+        "done": true, "done_reason": "stop", "prompt_eval_count": 31_000, "eval_count": 40,
+    })
+    .to_string()
+}
+
+/// A mock Ollama whose `/api/chat` answers `replies` in order (the last one
+/// repeats), each after `delay`, and a provider pointed at it with an idle
+/// bound of `timeout_seconds`.
+async fn serve(
+    model: &str,
+    show: Value,
+    replies: &[(u16, String)],
+    delay: std::time::Duration,
+    timeout_seconds: u64,
+) -> (MockServer, OllamaProvider) {
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/api/show"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(show))
+        .mount(&server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path("/api/version"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({"version": "0.40.2"})))
+        .mount(&server)
+        .await;
+    for (index, (status, body)) in replies.iter().enumerate() {
+        let mock = Mock::given(method("POST"))
+            .and(path("/api/chat"))
+            .respond_with(
+                ResponseTemplate::new(*status)
+                    .set_delay(delay)
+                    .set_body_raw(body.clone(), "application/x-ndjson"),
+            );
+        let mock = if index + 1 < replies.len() {
+            mock.up_to_n_times(1)
+        } else {
+            mock
+        };
+        mock.mount(&server).await;
+    }
+    let provider = OllamaProvider::from_custom_config(
+        ModelConfig::new_or_fail(&format!("{model}-{}", uuid::Uuid::new_v4().simple())),
+        DeclarativeProviderConfig {
+            name: "ollama-diagnostics-20261006-2".to_string(),
+            engine: ProviderEngine::Ollama,
+            display_name: "Ollama diagnostics 20261006_2".to_string(),
+            description: None,
+            api_key_env: "NOT_USED".to_string(),
+            base_url: server.uri(),
+            models: vec![],
+            headers: None,
+            timeout_seconds: Some(timeout_seconds),
+            supports_streaming: Some(true),
+        },
+    )
+    .expect("the provider constructs");
+    (server, provider)
+}
+
+async fn serve_replies(model: &str, replies: &[(u16, String)]) -> (MockServer, OllamaProvider) {
+    serve(
+        model,
+        show(131_072, None),
+        replies,
+        std::time::Duration::ZERO,
+        10,
+    )
+    .await
+}
+
+async fn chat_requests(server: &MockServer) -> Vec<Value> {
+    server
+        .received_requests()
+        .await
+        .unwrap()
+        .iter()
+        .filter(|request| request.url.path() == "/api/chat")
+        .map(|request| serde_json::from_slice(&request.body).unwrap())
+        .collect()
+}
+
+/// The user message the provider sent last in `request`: on a corrective
+/// retry, the question it asked.
+fn last_user_text(request: &Value) -> String {
+    request["messages"]
+        .as_array()
+        .and_then(|messages| messages.last())
+        .and_then(|message| message["content"].as_str())
+        .unwrap_or_default()
+        .to_string()
+}
+
+struct Turn {
+    items: Vec<ProviderStreamItem>,
+    error: Option<ProviderError>,
+}
+
+impl Turn {
+    fn text(&self) -> String {
+        self.items
+            .iter()
+            .filter_map(|(message, _, _)| message.as_ref())
+            .map(Message::as_concat_text)
+            .collect()
+    }
+
+    fn calls(&self) -> Vec<&ToolRequest> {
+        self.items
+            .iter()
+            .filter_map(|(message, _, _)| message.as_ref())
+            .flat_map(|message| message.content.iter())
+            .filter_map(MessageContent::as_tool_request)
+            .collect()
+    }
+
+    fn call_names(&self) -> Vec<String> {
+        self.calls()
+            .iter()
+            .map(|call| call.tool_call.as_ref().unwrap().name.to_string())
+            .collect()
+    }
+}
+
+async fn turn(provider: &OllamaProvider, system: &str, user: &str, tools: &[Tool]) -> Turn {
+    let mut stream = match provider
+        .stream(system, &[Message::user().with_text(user)], tools)
+        .await
+    {
+        Ok(stream) => stream,
+        Err(error) => {
+            return Turn {
+                items: Vec::new(),
+                error: Some(error),
+            }
+        }
+    };
+    let mut items = Vec::new();
+    while let Some(item) = stream.next().await {
+        match item {
+            Ok(item) => items.push(item),
+            Err(error) => {
+                return Turn {
+                    items,
+                    error: Some(error),
+                }
+            }
+        }
+    }
+    Turn { items, error: None }
+}
+
+/// The reporter's first turn as 1.92.0 sent it: a 164,005-byte request
+/// (`llm_request.0.jsonl`) that Ollama answered from 2,046 new and 4 cached
+/// prompt tokens, its 4,096-token default window keeping 4 head tokens and the
+/// last 2,046. Today the request asks for the window it needs and refuses a
+/// cut, and a reply that comes back cut anyway is an error, never the JSON the
+/// reporter read.
+#[tokio::test]
+async fn the_reporters_cut_first_turn_is_refused_and_the_window_is_asked_for() {
+    let template =
+        std::fs::read_to_string(format!("{FIXTURES}/templates/llama3.1_8b.tmpl")).unwrap();
+    let (server, provider) = serve(
+        "llama3.1:8b",
+        show(131_072, Some(template)),
+        &[(200, text_body(&reply(1), 2046, 4))],
+        std::time::Duration::ZERO,
+        10,
+    )
+    .await;
+    let system = "s".repeat(164_005 - 60);
+    let turn = turn(
+        &provider,
+        &system,
+        "write me some code to find the factorial of any number",
+        &code_execution_roster(),
+    )
+    .await;
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 1);
+    assert!(requests[0]["options"]["num_ctx"].as_u64().unwrap() >= 65_536);
+    assert_eq!(requests[0]["truncate"], false);
+    assert!(
+        matches!(turn.error, Some(ProviderError::ContextLengthExceeded(_))),
+        "{:?}",
+        turn.error
+    );
+    assert!(turn.calls().is_empty());
+    assert!(
+        !turn.text().contains("text_editor"),
+        "the cut reply is never shown"
+    );
+    assert_eq!(
+        provider.get_model_config().context_limit,
+        requests[0]["options"]["num_ctx"]
+            .as_u64()
+            .map(|n| n as usize),
+        "the gauge and compaction read the window really asked for, not the name's guess"
+    );
+}
+
+/// qwen2.5-coder:7b was trained on 32,768 tokens, and the reporter's prompt
+/// was about 37,000. The request asks for the trained window and Ollama's
+/// over-window refusal is a context error, sent once. (Whether a small model
+/// should get a smaller prompt is an open product decision, not tested here.)
+#[tokio::test]
+async fn qwen25_coder_at_its_trained_window_refuses_the_reporters_prompt_size() {
+    let overflow = r#"{"error":"{\"error\":{\"code\":400,\"message\":\"request (37274 tokens) exceeds the available context size (32768 tokens), try increasing it\",\"type\":\"exceed_context_size_error\",\"n_prompt_tokens\":37274,\"n_ctx\":32768}}"}"#;
+    let (server, provider) = serve(
+        "qwen2.5-coder:7b",
+        show(32_768, None),
+        &[(400, overflow.to_string())],
+        std::time::Duration::ZERO,
+        10,
+    )
+    .await;
+    let turn = turn(&provider, "system", "hello", &code_execution_roster()).await;
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 1);
+    assert_eq!(requests[0]["options"]["num_ctx"], 32_768);
+    assert!(
+        matches!(turn.error, Some(ProviderError::ContextLengthExceeded(_))),
+        "{:?}",
+        turn.error
+    );
+}
+
+/// Reply 9: `search_modules` without its prefix, `query` for `terms`. The
+/// model is asked once, naming the real tool, and its call completes the turn.
+#[tokio::test]
+async fn reply_9_is_asked_for_once_naming_code_execution_search_modules() {
+    let (server, provider) = serve_replies(
+        "qwen2.5-coder:7b",
+        &[
+            (200, text_body(&reply(9), 31_000, 30_500)),
+            (
+                200,
+                structured_call("code_execution__search_modules", json!({"terms": "llama"})),
+            ),
+        ],
+    )
+    .await;
+    let turn = turn(
+        &provider,
+        "system",
+        "can you actually execute llama3.1:8b against those notes",
+        &code_execution_roster(),
+    )
+    .await;
+    assert!(turn.error.is_none(), "{:?}", turn.error);
+    assert_eq!(turn.call_names(), ["code_execution__search_modules"]);
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 2, "one corrective retry");
+    let nudge = last_user_text(&requests[1]);
+    assert!(
+        nudge.contains("a call to 'search_modules' written as text")
+            && nudge.contains("If you intended to call 'code_execution__search_modules'"),
+        "{nudge}"
+    );
+}
+
+/// Reply 11: two objects, `workspace_read_conversation` then
+/// `workspace_read_panel`, each a real workspace tool without its prefix.
+/// Read as one value the pair was neither a call nor an attempt, so the turn
+/// ended on the JSON; now the model is asked once about both.
+#[tokio::test]
+async fn reply_11_two_calls_in_one_reply_are_asked_for_once() {
+    let (server, provider) = serve_replies(
+        "llama3.1:8b",
+        &[
+            (200, text_body(&reply(11), 31_000, 30_500)),
+            (
+                200,
+                structured_call(
+                    "workspace__workspace_read_conversation",
+                    json!({"session_id": "20261006_2"}),
+                ),
+            ),
+        ],
+    )
+    .await;
+    let turn = turn(
+        &provider,
+        "system",
+        "take the file called ~/temp and find any occurrences of blasts",
+        &code_execution_roster(),
+    )
+    .await;
+    assert!(turn.error.is_none(), "{:?}", turn.error);
+    assert_eq!(
+        turn.call_names(),
+        ["workspace__workspace_read_conversation"]
+    );
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 2, "one corrective retry");
+    let nudge = last_user_text(&requests[1]);
+    assert!(
+        nudge.contains("calls to 'workspace_read_conversation' and 'workspace_read_panel'")
+            && nudge.contains(
+                "'workspace__workspace_read_conversation' and 'workspace__workspace_read_panel'"
+            )
+            && nudge.contains("otherwise answer in text"),
+        "{nudge}"
+    );
+}
+
+/// Replies 1 (`text_editor`), 7 (`shell`) and 15 (`agent_drafter`) in the
+/// reporter's Code Execution chat: none names a tool that chat offered, so
+/// nothing is run and nothing is asked. The reply is shown as it came; the
+/// agent then adds a line saying nothing ran.
+#[tokio::test]
+async fn replies_1_7_and_15_in_a_code_execution_chat_are_shown_and_never_run() {
+    for index in [1, 7, 15] {
+        let (server, provider) = serve_replies(
+            "llama3.1:8b",
+            &[(200, text_body(&reply(index), 31_000, 30_500))],
+        )
+        .await;
+        let turn = turn(&provider, "system", "do it", &code_execution_roster()).await;
+        assert!(turn.error.is_none(), "reply {index}: {:?}", turn.error);
+        assert!(turn.calls().is_empty(), "reply {index}");
+        assert_eq!(turn.text().trim(), reply(index).trim(), "reply {index}");
+        assert_eq!(
+            chat_requests(&server).await.len(),
+            1,
+            "reply {index}: no retry"
+        );
+    }
+}
+
+/// Reply 7 where Developer IS offered directly: the same `shell` call is
+/// asked for once, naming `developer__shell`.
+#[tokio::test]
+async fn reply_7_with_developer_offered_is_asked_for_once() {
+    let (server, provider) = serve_replies(
+        "llama3.1:8b",
+        &[
+            (200, text_body(&reply(7), 31_000, 30_500)),
+            (
+                200,
+                structured_call("developer__shell", json!({"command": "cat ~/temp"})),
+            ),
+        ],
+    )
+    .await;
+    let turn = turn(&provider, "system", "do it", &direct_roster()).await;
+    assert!(turn.error.is_none(), "{:?}", turn.error);
+    assert_eq!(turn.call_names(), ["developer__shell"]);
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 2);
+    assert!(
+        last_user_text(&requests[1]).contains("If you intended to call 'developer__shell'"),
+        "{}",
+        last_user_text(&requests[1])
+    );
+}
+
+/// The reporter's answers: prose with code for the person to run (3, 5, 17,
+/// 19) and the JSON the person asked for (13). Shown, never asked about.
+#[tokio::test]
+async fn the_reporters_answers_are_never_asked_about() {
+    for index in [3, 5, 13, 17, 19] {
+        let (server, provider) = serve_replies(
+            "llama3.1:8b",
+            &[(200, text_body(&reply(index), 31_000, 30_500))],
+        )
+        .await;
+        let turn = turn(&provider, "system", "do it", &code_execution_roster()).await;
+        assert!(turn.error.is_none(), "reply {index}: {:?}", turn.error);
+        assert!(turn.calls().is_empty(), "reply {index}");
+        assert_eq!(turn.text().trim(), reply(index).trim(), "reply {index}");
+        assert_eq!(
+            chat_requests(&server).await.len(),
+            1,
+            "reply {index}: no retry"
+        );
+    }
+}
+
+/// The reporter's machine read about 25 prompt tokens a second (llama3.1:8b)
+/// with `OLLAMA_TIMEOUT` at 600 s, so a whole first prompt of about 37,000
+/// tokens would be a quarter of an hour of silence before Ollama's first byte.
+/// Scaled down (a 1 s bound, 3 s of silence): the person reads which setting to
+/// raise and how large the prompt is, the request is sent once, and the agent
+/// does not send it again either.
+#[tokio::test]
+async fn a_first_prompt_slower_than_the_idle_bound_names_the_bound_and_is_sent_once() {
+    let (server, provider) = serve(
+        "llama3.1:8b",
+        show(131_072, None),
+        &[(200, text_body("hello", 37_000, 0))],
+        std::time::Duration::from_secs(3),
+        1,
+    )
+    .await;
+    let system = "s".repeat(160_000);
+    let turn = turn(&provider, &system, "hello", &code_execution_roster()).await;
+    let error = turn.error.expect("the bound fires before the first byte");
+    let text = error.to_string();
+    assert!(matches!(error, ProviderError::IdleTimeout(_)), "{error:?}");
+    assert!(
+        text.contains("sent nothing back for 1 second,")
+            && text.contains("Raise timeout_seconds")
+            && text.contains("about 4")
+            && text.contains(",000 tokens"),
+        "{text}"
+    );
+    assert_eq!(error.kind(), ProviderErrorKind::Network);
+    assert!(
+        !biorouter::agents::mistakes::is_recoverable(&error),
+        "the agent must not send the whole prompt again behind the first"
+    );
+    assert_eq!(chat_requests(&server).await.len(), 1, "sent once");
+}
+
+// ---------------------------------------------------------------------------
+// Through the agent: what the person reads, and what the model is sent next.
+// ---------------------------------------------------------------------------
+
+/// A model that answers its first request with the reporter's reply 7 and
+/// every later one with "ok", recording what each request carried.
+struct ReporterModel {
+    requests: std::sync::Mutex<Vec<Vec<Message>>>,
+}
+
+#[async_trait::async_trait]
+impl Provider for ReporterModel {
+    async fn complete(
+        &self,
+        _system: &str,
+        messages: &[Message],
+        _tools: &[Tool],
+    ) -> Result<(Message, biorouter::providers::base::ProviderUsage), ProviderError> {
+        let first = {
+            let mut requests = self.requests.lock().unwrap();
+            requests.push(messages.to_vec());
+            requests.len() == 1
+        };
+        let text = if first { reply(7) } else { "ok".to_string() };
+        let mut usage = biorouter::providers::base::ProviderUsage::new(
+            "llama3.1:8b".to_string(),
+            biorouter::providers::base::Usage::new(Some(31_000), Some(20), Some(31_020)),
+        );
+        usage.finish_reason = Some("stop".to_string());
+        Ok((Message::assistant().with_text(text), usage))
+    }
+
+    async fn complete_with_model(
+        &self,
+        _model: &ModelConfig,
+        system: &str,
+        messages: &[Message],
+        tools: &[Tool],
+    ) -> Result<(Message, biorouter::providers::base::ProviderUsage), ProviderError> {
+        self.complete(system, messages, tools).await
+    }
+
+    fn get_model_config(&self) -> ModelConfig {
+        ModelConfig::new_or_fail("llama3.1:8b")
+    }
+
+    fn metadata() -> biorouter::providers::base::ProviderMetadata {
+        biorouter::providers::base::ProviderMetadata::empty()
+    }
+
+    fn get_name(&self) -> &str {
+        "diagnostics-20261006-2-model"
+    }
+}
+
+fn is_unrun_call_notice(message: &Message) -> bool {
+    message.content.iter().any(|content| {
+        matches!(
+            content,
+            MessageContent::SystemNotification(note) if note.msg.starts_with("Nothing ran")
+        )
+    })
+}
+
+/// End to end through the agent, on the reporter's reply 7 (`shell` written as
+/// JSON) in a turn that offered tools: the reply is shown and stored as it
+/// came, one line after it tells the person that nothing ran, that line is
+/// stored for the person only, and the model's next request does not carry it.
+#[tokio::test]
+async fn the_agent_tells_the_person_nothing_ran_and_keeps_it_from_the_model() {
+    use biorouter::agents::extension::ExtensionConfig;
+    use biorouter::agents::{Agent, AgentConfig, AgentEvent, SessionConfig};
+
+    let work = tempfile::TempDir::new().unwrap();
+    let data = tempfile::TempDir::new().unwrap();
+    let permissions = tempfile::TempDir::new().unwrap();
+    let manager = std::sync::Arc::new(biorouter::session::SessionManager::new(
+        data.path().to_path_buf(),
+    ));
+    let agent = Agent::with_config(AgentConfig::new(
+        manager.clone(),
+        std::sync::Arc::new(biorouter::config::permission::PermissionManager::new(
+            permissions.path().to_path_buf(),
+        )),
+        None,
+        biorouter::config::BioRouterMode::Auto,
+    ));
+    let session = manager
+        .create_session(
+            work.path().to_path_buf(),
+            "diagnostics 20261006_2".to_string(),
+            biorouter::session::session_manager::SessionType::Hidden,
+        )
+        .await
+        .unwrap();
+    let model = std::sync::Arc::new(ReporterModel {
+        requests: std::sync::Mutex::new(Vec::new()),
+    });
+    agent
+        .update_provider(model.clone(), &session.id)
+        .await
+        .unwrap();
+    agent
+        .add_extension(ExtensionConfig::Frontend {
+            name: "notes".to_string(),
+            description: "Read the person's notes".to_string(),
+            tools: vec![tool(
+                "notes__read",
+                json!({"type": "object", "properties": {"path": {"type": "string"}}}),
+            )],
+            instructions: None,
+            bundled: None,
+            available_tools: Vec::new(),
+        })
+        .await
+        .unwrap();
+    let config = || SessionConfig {
+        id: session.id.clone(),
+        schedule_id: None,
+        max_turns: Some(3),
+        max_tool_calls: Some(3),
+        budget: None,
+        retry_config: None,
+        reasoning_effort: None,
+    };
+
+    let mut shown = Vec::new();
+    for user in ["count the word urine in ~/temp", "thanks"] {
+        let stream = agent
+            .reply(Message::user().with_text(user), config(), None)
+            .await
+            .unwrap();
+        tokio::pin!(stream);
+        tokio::time::timeout(std::time::Duration::from_secs(30), async {
+            while let Some(event) = stream.next().await {
+                if let AgentEvent::Message(message) = event.unwrap() {
+                    shown.push(message);
+                }
+            }
+        })
+        .await
+        .expect("a bounded turn");
+    }
+
+    let notices: Vec<&Message> = shown
+        .iter()
+        .filter(|message| is_unrun_call_notice(message))
+        .collect();
+    assert_eq!(
+        notices.len(),
+        1,
+        "one notice, after the first turn: {shown:?}"
+    );
+    let MessageContent::SystemNotification(note) = &notices[0].content[0] else {
+        unreachable!()
+    };
+    assert!(
+        note.msg.contains("a call to 'shell' written as text"),
+        "{}",
+        note.msg
+    );
+    assert!(shown
+        .iter()
+        .any(|message| message.as_concat_text() == reply(7)));
+
+    let stored = manager
+        .get_session(&session.id, true)
+        .await
+        .unwrap()
+        .conversation
+        .unwrap();
+    let stored_notice = stored
+        .iter()
+        .find(|message| is_unrun_call_notice(message))
+        .expect("the notice is stored, so a reload shows it");
+    assert!(stored_notice.is_user_visible() && !stored_notice.is_agent_visible());
+
+    let requests = model.requests.lock().unwrap();
+    let second = requests
+        .iter()
+        .find(|request| {
+            request
+                .iter()
+                .any(|message| message.as_concat_text().contains("thanks"))
+        })
+        .unwrap_or_else(|| panic!("the second turn reached the model: {requests:?}"));
+    // Providers are handed the whole history and every wire format keeps only
+    // the agent-visible messages (the mechanism compaction relies on too), so
+    // what the model is sent is exactly this filter.
+    let sent_to_the_model: Vec<&Message> = second
+        .iter()
+        .filter(|message| message.is_agent_visible())
+        .collect();
+    assert!(
+        sent_to_the_model
+            .iter()
+            .all(|message| !is_unrun_call_notice(message)
+                && !message.as_concat_text().contains("Nothing ran")),
+        "the notice is the person's, never the model's: {sent_to_the_model:?}"
+    );
+    assert!(
+        sent_to_the_model
+            .iter()
+            .any(|message| message.as_concat_text() == reply(7)),
+        "the reply itself stays in the model's history"
+    );
+    // And through Ollama's own request builder, which is what the reporter's
+    // model was sent.
+    let wire = biorouter::providers::formats::ollama::create_request(
+        &biorouter::providers::formats::ollama::ChatRequest {
+            model: "llama3.1:8b",
+            system: "system",
+            messages: second,
+            tools: &[],
+            stream: true,
+            num_ctx: 65_536,
+            temperature: None,
+            num_predict: None,
+            think: None,
+            keep_alive: None,
+            vision: false,
+            calls_without_text: false,
+        },
+    )
+    .unwrap()
+    .to_string();
+    assert!(!wire.contains("Nothing ran"), "{wire}");
+}

From 433897fe8052bf445e2ac9e10e36b449e69058d9 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:00:29 -0700
Subject: [PATCH 16/26] docs(ollama): a reply of calls nothing ran is said, two
 calls are asked about, a first-byte timeout names its setting (diagnostics
 20261006_2)

---
 CLAUDE.md                                       | 17 ++++++++++++++---
 .../ollama/context-window-and-settings.md       | 15 ++++++++++-----
 docs/providers/ollama/tool-call-protocols.md    |  3 ++-
 3 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8b4f16132..990d9444f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -745,7 +745,10 @@ prompt both catalog models made structured tool calls reliably.
   sticky per instance, text held until the size check passes.
 - **Every request streams**, blocking ones collected, so `OLLAMA_TIMEOUT`
   (600 s) bounds silence, never a whole generation; a timeout is never retried
-  (`TimeoutRetry::GiveUp`), a connection failure still is. An unpinned turn gets
+  (`TimeoutRetry::GiveUp`), a connection failure still is. One before the reply
+  begins is `ProviderError::IdleTimeout`, naming the seconds, the prompt's rough
+  size and the setting, and the agent does not re-send it either (it used to,
+  as a network blip: diagnostics 20261006_2). An unpinned turn gets
   `num_predict` 16384, or 32768 when the model may think.
 - **Thinking:** `think` only to models whose `/api/show` capabilities include
   `thinking` (others answer `think:true` with a 400). Quick sends `false`;
@@ -856,14 +859,22 @@ prompt both catalog models made structured tool calls reliably.
     beyond a ceiling for the reasoning (characters/2 + 16 tokens) plus 8, else
     "returned reasoning only (N output tokens)"; a reply cut at `length`, or
     one with no reasoning and at most 8 tokens, fails at once; (3) a WHOLE reply
-    that is a call recovery declined (`text_tool_calls::attempted_call`: a name
+    that is a call recovery declined (`text_tool_calls::attempted_calls`: a name
     without its `extension__` prefix, arguments that do not fit, the
-    `<tool_response>` tag), whose name stands for an offered tool. That one
+    `<tool_response>` tag; several objects or an array, each one naming an
+    offered tool), whose name stands for an offered tool. That one
     asks rather than orders, is skipped when the call echoes the conversation
     (made by an earlier turn, or quoted in a tool result or earlier assistant
     reply; `echoes_conversation`), and is best-effort: if it cannot be sent,
     fails or comes back empty, the turn ends with the reply already shown. A
     retry after shown text starts a new paragraph.
+  - **A reply of calls nothing ran is SAID, never run** (diagnostics
+    20261006_2): when a turn that offered tools ends on a reply made only of
+    call objects written as text (`whole_reply_call_names`), `agents::reply_parts`
+    adds one user-only inline notice after it ("Nothing ran: ..."), for every
+    provider. It is stored, so a reload shows it, and every wire format drops it
+    because it is not agent-visible. Calls Code Execution hides (`shell`,
+    `text_editor`) still get no retry: the provider cannot see them.
   - **Tool roster for templates that hide tools** (R8): when `/api/show`'s
     template shows tools only next to the last user message (llama3.1,
     mistral-small3.2, mistral-nemo; `ModelFacts::tools_only_near_last_user`),
diff --git a/docs/providers/ollama/context-window-and-settings.md b/docs/providers/ollama/context-window-and-settings.md
index f373fb1c4..cd5191503 100644
--- a/docs/providers/ollama/context-window-and-settings.md
+++ b/docs/providers/ollama/context-window-and-settings.md
@@ -191,13 +191,18 @@ tools were offered, the turn ends with an error saying the model returned reason
   loaded.
 - **Timeouts.** `OLLAMA_TIMEOUT` (default 600 seconds) limits silence between pieces of the
   reply, not the whole reply, because a local model can stream for longer than any fixed
-  deadline. A timeout is never retried: the original inference may still be running, so
-  resending can duplicate work or queue behind it, depending on Ollama's parallel slots.
-  Connection failures before a reply starts are still retried.
+  deadline. A timeout is never retried, by the provider or by the agent: the original
+  inference may still be running, so resending can duplicate work or queue behind it,
+  depending on Ollama's parallel slots. Connection failures before a reply starts are still
+  retried.
 
 > **Note.** The first piece of a reply arrives only after the model has read the whole prompt.
-> On a slow machine a cold ~31,000-token prompt can take longer than `OLLAMA_TIMEOUT`; raise it
-> if a first reply times out.
+> On a slow machine a cold ~31,000-token prompt can take longer than `OLLAMA_TIMEOUT`. When it
+> does, the error says how long Biorouter waited, the prompt's rough size in tokens and the
+> setting to raise (`OLLAMA_TIMEOUT`, or `timeout_seconds` for a custom Ollama provider).
+> Diagnostics 20261006_2 measured about 25 prompt tokens a second for `llama3.1:8b` on an
+> Intel Mac, so a 37,000-token first prompt needs `OLLAMA_TIMEOUT` well above 1,500 seconds
+> there, or a shorter prompt.
 
 ### A timeout with two models loaded and parallel slots
 
diff --git a/docs/providers/ollama/tool-call-protocols.md b/docs/providers/ollama/tool-call-protocols.md
index 283d5cba8..c0f5cee91 100644
--- a/docs/providers/ollama/tool-call-protocols.md
+++ b/docs/providers/ollama/tool-call-protocols.md
@@ -228,7 +228,8 @@ follows.
 | --- | --- |
 | Structured calls | Collects every call of the reply, across chunks, and holds them until the reply's usage shows the prompt was not cut; only then do they run. A missing id is minted, and arguments may be an object or a JSON string. Arguments are normalised against the tool's schema: Cohere's `{tool_name, parameters}` wrapper is unwrapped, an object or array sent as a JSON string is decoded, and `"10"` or `"true"` becomes a number or boolean where the schema asks for one. An enum violation is left for the tool to report, so the model sees the error and can correct it. |
 | The whole reply is a call written as text (L1, L2, L5, L8) | Recovered under the guards above. While the reply starts like a call (`{`, `[`, a code fence or `<tool_call>`) its text is held back; thinking still streams. A recovered call carries a `recovered_from_text` marker and its format, and one log line names the model, the format and the count. If the guards reject it, the held text is shown unchanged. |
-| The whole reply is a call that recovery declined (a name without its extension prefix, such as `execute_code` for `code_execution__execute_code`; arguments that do not fit; the `<tool_response>` tag around it) | Asked once, using the turn's one retry. The note says text in a reply is never run as a tool call, and asks the model to make the call as a call if it intended one, otherwise to answer in text. It never orders a call. No retry when the name stands for no offered tool (a JSON answer shaped like a call), or when the same call already appears in the conversation: made by an earlier turn, or quoted in a tool result or an earlier assistant reply. Best-effort: if the retry cannot be sent, fails, overflows, or comes back empty, the turn ends with the reply already shown. |
+| The whole reply is a call that recovery declined (a name without its extension prefix, such as `execute_code` for `code_execution__execute_code`; arguments that do not fit; the `<tool_response>` tag around it) | Asked once, using the turn's one retry. The note says text in a reply is never run as a tool call, and asks the model to make the call as a call if it intended one, otherwise to answer in text. It never orders a call. A reply of several call objects, or an array of them, is asked about once, naming every tool, when each object names an offered tool (diagnostics 20261006_2: `llama3.1:8b` wrote `workspace_read_conversation` and `workspace_read_panel` in one reply). No retry when a name stands for no offered tool (a JSON answer shaped like a call), or when the same call already appears in the conversation: made by an earlier turn, or quoted in a tool result or an earlier assistant reply. Best-effort: if the retry cannot be sent, fails, overflows, or comes back empty, the turn ends with the reply already shown. |
+| The whole reply is only calls written as text, and none ran (a tool the chat does not offer directly, such as Developer's `shell` in a chat with Code Execution on; an extension's name; a retry that repeated the call) | Shown as it came, then one line for the person only: "Nothing ran: this reply is a call to 'shell' written as text, not a tool call Biorouter can run." with a note that a larger model or fewer extensions may help. The agent adds the line after the reply, so it appears for every provider; it is stored with the chat and never sent to the model. Nothing in the reply is run. |
 | Prose, then a call (L3, L4) | Left as text, and never acted on: a reply that quotes a call (a summary, a relayed tool result, a requested example) cannot be told from one that meant it. Only the tool shim (`BIOROUTER_TOOLSHIM`), where text is the tool protocol by design, recovers this form, on whichever provider it is turned on for, and it does so before asking its interpreter model. |
 | An empty reply to a request with tools | Retried once when its tokens may be a call Ollama swallowed: with no reasoning, more than 8 output tokens; with reasoning, always, because measured reasoning ran 2.4-4.7 characters per token and `qwen3:1.7b`'s swallowed call fell inside that band. The retry carries a note listing the tools the model can call. The error then says only what the numbers show. "Could not parse as a tool call" appears when the output exceeds a ceiling for the reasoning (characters/2 + 16 tokens) by more than 8. Otherwise the error says the model "returned reasoning only (N output tokens)" and may also have written an unparsable call. The advice names only the recommended model not in use. A reply cut at its output budget, or one with no reasoning and at most 8 tokens, fails at once. |
 | `tool '<name>' not found` | Text already shown is kept, and the model is asked once more with a note that the tool does not exist and the list of tools it can call. If that fails too, the error names the tool. It is never reported as a missing model. |

From f4fb03bda561199b97e3ff290822ba8992bb6853 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:02:40 -0700
Subject: [PATCH 17/26] fix(settings): the top of Settings and the setup page
 is never left under the band, with 24px of headroom [R-17 R-34]

Opening Settings at a section (the update notice's "update", "usage",
"project", even "privacy") left the first lines under the 44px band after
the wheel reached the top, on every tab, until Settings was reopened.

The ScrollArea viewport was not positioned, so absolutely positioned
content without a positioned box of its own (every InfoTip's sr-only
description) was placed against the overflow:hidden ROOT, past the
viewport's clip, and gave the root up to ~1,600px of overflow. A wheel
cannot scroll a hidden box; scrollIntoView can, so the deep link scrolled
the root as well, and nothing scrolled it back.

- main.css: `.br-scroll-viewport { position: relative }`, so that content
  belongs to the viewport and the root has nothing to scroll.
- ui/scroll-area.tsx: the root is put back at 0 whenever anything scrolls
  it; `data-scrolled` (the top fade's hook) counts a whole pixel, so a
  sub-pixel rest at the top keeps no fade.
- `--page-headroom: 24px` and `.br-page-headroom`: one clear space under the
  band for Settings (was py-5, 20px), the first-run setup page and the
  provider page (were py-6), taller than the 10px fade.

Tests: settings/pageHeadroom.browser.test.tsx mounts the real SettingsView
and ProviderGuard first-run page in Chromium under main.css compiled by
Tailwind, wheels/flings back to the top on every tab and after deep links
at 1048x600 and 1440x900, and asserts scrollTop 0 (viewport and root),
data-scrolled false, no mask, and the first row >= 24px under the band.
Its instrument removes both halves of the fix and sees the defect return
(each half alone holds). Run against HEAD's code it fails 9/9 (20px
headroom; root scrolled 174/411px on landing). Unit tests for the root
guard and the threshold; settingsScrollFade.test.ts pins the token.
---
 ui/desktop/src/components/ProviderGuard.tsx   |   4 +-
 .../src/components/settings/SettingsView.tsx  |   6 +-
 .../settings/pageHeadroom.browser.test.tsx    | 689 ++++++++++++++++++
 .../providers/ProviderSettingsPage.tsx        |   4 +-
 .../src/components/ui/scroll-area.test.tsx    |  61 ++
 ui/desktop/src/components/ui/scroll-area.tsx  |  28 +-
 ui/desktop/src/styles/main.css                |  52 +-
 .../src/styles/settingsScrollFade.test.ts     |  46 +-
 8 files changed, 883 insertions(+), 7 deletions(-)
 create mode 100644 ui/desktop/src/components/settings/pageHeadroom.browser.test.tsx

diff --git a/ui/desktop/src/components/ProviderGuard.tsx b/ui/desktop/src/components/ProviderGuard.tsx
index dc408124b..b6b2d2a96 100644
--- a/ui/desktop/src/components/ProviderGuard.tsx
+++ b/ui/desktop/src/components/ProviderGuard.tsx
@@ -315,8 +315,10 @@ export default function ProviderGuard({ didSelectProvider, children }: ProviderG
           </div>
         </header>
 
+        {/* `br-page-headroom`: the clear space under the band at the top, the one Settings
+            keeps too (`--page-headroom`). */}
         <ScrollArea className="w-full flex-1">
-          <div className="mx-auto w-full max-w-measure-chat px-6 py-6">
+          <div className="br-page-headroom mx-auto w-full max-w-measure-chat px-6 pb-6">
             {hostManaged ? (
               <HostManagedModelPanel />
             ) : (
diff --git a/ui/desktop/src/components/settings/SettingsView.tsx b/ui/desktop/src/components/settings/SettingsView.tsx
index ae70c986d..56042296b 100644
--- a/ui/desktop/src/components/settings/SettingsView.tsx
+++ b/ui/desktop/src/components/settings/SettingsView.tsx
@@ -227,9 +227,11 @@ export default function SettingsView({
         {/* `biorouter-scroll-fade-top` fades the clipped top edge only while the scroller is
             scrolled, so a row cut off at the band's hairline does not read as a second rule.
             Guarded at the source by `styles/settingsScrollFade.test.ts`, because jsdom computes
-            no `mask-image`. */}
+            no `mask-image`. `br-page-headroom` is the page's clear space under the band at the
+            top (`--page-headroom`, shared with the setup page), so the column takes only its
+            bottom padding here; `settings/pageHeadroom.browser.test.tsx` measures both. */}
         <ScrollArea className="biorouter-scroll-fade-top flex-1" paddingX={1}>
-          <ReadableContent size="chat" className="br-rows-flat px-6 py-5">
+          <ReadableContent size="chat" className="br-page-headroom br-rows-flat px-6 pb-5">
             {/* `tabIndex={-1}` on all three panels (vision V4-05): Radix makes a panel a Tab stop,
                 and a panel has no focus treatment by design, so Tab from the tab list landed on an
                 invisible stop before the first control. Every Settings panel opens with a control,
diff --git a/ui/desktop/src/components/settings/pageHeadroom.browser.test.tsx b/ui/desktop/src/components/settings/pageHeadroom.browser.test.tsx
new file mode 100644
index 000000000..08e9354be
--- /dev/null
+++ b/ui/desktop/src/components/settings/pageHeadroom.browser.test.tsx
@@ -0,0 +1,689 @@
+// @vitest-environment node
+/**
+ * The top of Settings and of the first-run setup page, at rest, measured in Chromium (owner,
+ * 2026-10-12: "the user interface doesn't go all the way up even when the scroll is scrolled all
+ * the way up ... leave plenty of headroom at the top").
+ *
+ * **The defect.** The `ScrollArea` root is `overflow: hidden` around its viewport, and its viewport
+ * was not positioned, so every absolutely positioned box in the scrolled content without a
+ * positioned box of its own above it was placed against the ROOT: an InfoTip's `sr-only`
+ * description on every row with help. Those 1px spans sat past the viewport's clip and gave the
+ * root up to 1,600px of overflow. A wheel cannot scroll a hidden box; `scrollIntoView` can, and
+ * Settings calls it to open at a section (the update notice's "update", "usage", "project", and by
+ * the 10px of scroll padding even "privacy"). The root scrolled with the viewport, the wheel
+ * brought only the viewport back to 0, and the page's first lines stayed under the band, on every
+ * tab, until Settings was reopened. Wheel scrolling alone never showed it, which is why it read
+ * as "sometimes".
+ *
+ * **What holds it now.** `.br-scroll-viewport` is `position: relative` (`main.css`), so those
+ * boxes are the viewport's and the root has nothing to scroll, and `ui/scroll-area.tsx` puts the
+ * root back if anything ever scrolls it. Either one alone holds the top; the instrument at the end
+ * removes both and watches the defect come back, and removes each in turn and watches it stay
+ * gone. The page's first row then sits `--page-headroom` (24px) under the band, one value for
+ * Settings and the setup page (`.br-page-headroom`), where Settings used to keep 20px of its own.
+ *
+ * **What is real.** `SettingsView` (its band, tabs, scroller, reading column and deep-link
+ * scrolling) and `ProviderGuard`'s first-run page are bundled with esbuild and rendered by React
+ * in Chromium, styled by `styles/main.css` compiled by Tailwind with the classes the bundle uses,
+ * plus the component stylesheets they import. The Settings tabs' sections are stubbed with the real
+ * `SettingSection` and `SettingRow` (every row has help, so every row has the InfoTip span that
+ * escaped), and the provider catalog with a list of rows behind real InfoTips; the daemon, the
+ * router state and the privacy notice are stubbed because a bare page has none.
+ *
+ * Set `PAGE_HEADROOM_SHOTS=<dir>` to save a screenshot of every state measured.
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build, type Plugin } from 'esbuild';
+import { chromium, type Browser, type Page } from 'playwright';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const COMPONENTS = resolve(here, '..');
+const STYLES = resolve(here, '../../styles');
+const requireFromDesktop = createRequire(resolve(here, '../../../package.json'));
+const SHOTS = process.env.PAGE_HEADROOM_SHOTS;
+
+/** What the owner asked for, in pixels: the first row at least this far under the band. */
+const MIN_HEADROOM = 24;
+/** The band's height (`--chrome-height`), which the fix must not move. */
+const BAND = 44;
+/** The window sizes measured: the smallest the window allows (its width floor), and a laptop. */
+const SIZES = [
+  { width: 1048, height: 600 },
+  { width: 1440, height: 900 },
+] as const;
+
+/** A Settings tab's sections: [DOM id, title, rows]. Every row carries help (an InfoTip). */
+type Sections = Array<[string, string, number]>;
+const MODELS: Sections = [
+  ['settings-default-model', 'Default model', 8],
+  ['settings-local-models', 'Local models', 8],
+  ['settings-models-danger-zone', 'Danger zone', 3],
+];
+const CHAT: Sections = [
+  ['settings-approvals', 'Approvals', 6],
+  ['settings-display', 'Display', 6],
+  ['settings-capabilities', 'Capabilities', 6],
+  ['settings-memory', 'Memory', 5],
+  ['settings-contexts', 'Contexts', 5],
+  ['settings-app-sdk', 'App SDK', 4],
+  ['settings-project', 'Project', 3],
+];
+const APP_TAIL: Sections = [
+  ['settings-general', 'General', 6],
+  ['settings-appearance', 'Appearance', 4],
+  ['settings-usage', 'Usage', 4],
+  ['settings-about', 'About', 3],
+  ['settings-app-danger-zone', 'Danger zone', 2],
+];
+
+const tabStub = (sections: Sections, wrap?: string) => `
+  import * as React from 'react';
+  import { Sections } from 'stub:sections';
+  export default function Stub() {
+    const body = React.createElement(Sections, { sections: ${JSON.stringify(sections)} });
+    return ${wrap ? `React.createElement('div', { className: '${wrap}' }, body)` : 'body'};
+  }
+`;
+
+/** Modules the bundle takes from here instead of the app, by import specifier. */
+const STUBS: Array<{ filter: RegExp; contents: string }> = [
+  {
+    filter: /^stub:sections$/,
+    contents: `
+      import * as React from 'react';
+      import { SettingSection, SettingRow } from '${COMPONENTS}/ui/setting-row';
+      import { Switch } from '${COMPONENTS}/ui/switch';
+      const h = React.createElement;
+      export function Sections({ sections }) {
+        return h(React.Fragment, null, sections.map(([id, title, rows]) =>
+          h(SettingSection, { key: id, id, title, help: 'What the ' + title + ' section holds.' },
+            Array.from({ length: rows }, (_, i) =>
+              h(SettingRow, {
+                key: i,
+                label: title + ' setting ' + (i + 1),
+                help: 'What ' + title + ' setting ' + (i + 1) + ' changes.',
+                controlId: id + '-control-' + i,
+              }, h(Switch, { checked: i % 2 === 0, onCheckedChange: () => {} }))))));
+      }
+    `,
+  },
+  // Settings: the five sections components, and what Settings warms while it opens.
+  { filter: /\/models\/ModelsSection$/, contents: tabStub(MODELS) },
+  { filter: /\/chat\/ChatSettingsSection$/, contents: tabStub(CHAT, 'pb-8') },
+  {
+    filter: /\/config\/ConfigSettings$/,
+    contents: tabStub([['settings-configuration', 'Configuration', 1]]),
+  },
+  { filter: /\/privacy\/PrivacyPanel$/, contents: tabStub([['settings-privacy', 'Privacy', 2]]) },
+  { filter: /\/app\/AppSettingsSection$/, contents: tabStub(APP_TAIL) },
+  {
+    filter: /\/disclosureCopy$/,
+    contents: `export const readDisclosureAcknowledgement = async () => null;`,
+  },
+  { filter: /\/warmSettings$/, contents: `export const useWarmSettings = () => {};` },
+  // The first-run page: a daemon with no provider and no skip, and no day-one notice.
+  {
+    filter: /^\.\/ConfigContext$/,
+    contents: `
+      const api = {
+        read: async (key) => (key === 'BIOROUTER_PROVIDER' ? '' : false),
+        upsert: async () => {},
+        getProviders: async () => [],
+      };
+      export const useConfig = () => api;
+    `,
+  },
+  {
+    filter: /\/settings\/providers\/ProviderCatalog$/,
+    contents: `
+      import * as React from 'react';
+      import { createPortal } from 'react-dom';
+      import { InfoTip } from '${COMPONENTS}/ui/info-tip';
+      import '${COMPONENTS}/settings/providers/providers.css';
+      const h = React.createElement;
+      export default function ProviderCatalog({ tabsHost }) {
+        const tabs = h('div', { role: 'tablist', 'aria-label': 'Provider kinds', className: 'flex' },
+          ['Local', 'Institutional', 'Public'].map((name) =>
+            h('button', { key: name, role: 'tab', type: 'button' }, name)));
+        return h(React.Fragment, null,
+          tabsHost ? createPortal(tabs, tabsHost) : null,
+          h('p', { 'data-first-row': '', className: 'text-supporting text-text-muted' },
+            'Private because inference runs on this machine. Nothing leaves it.'),
+          Array.from({ length: 24 }, (_, i) =>
+            h('div', { key: i, className: 'br-first-run-card', style: { marginTop: 16 } },
+              h('div', { className: 'flex items-center gap-2' },
+                h('span', { className: 'text-label' }, 'Provider ' + (i + 1)),
+                h(InfoTip, { label: 'Provider ' + (i + 1), help: 'Where provider ' + (i + 1) + ' runs.' })),
+              h('p', { className: 'text-supporting text-text-muted' }, 'A line about provider ' + (i + 1) + '.'))));
+      }
+    `,
+  },
+  { filter: /^\.\.\/toasts$/, contents: `export const toastService = { error() {} };` },
+  {
+    filter: /\/onboarding\/CommercialSetupCard$/,
+    contents: `export const persistDetectedProviderSetup = async () => {};`,
+  },
+  {
+    filter: /\/utils\/navigationUtils$/,
+    contents: `export const createNavigationHandler = () => () => {};`,
+  },
+  { filter: /\/utils\/surface$/, contents: `export const isBrowserSurface = () => false;` },
+  {
+    filter: /\/privacy\/HostManagedModelPanel$/,
+    contents: `export const HostManagedModelPanel = () => null;`,
+  },
+  {
+    filter: /\/privacy\/firstRunNoticeDecision$/,
+    contents: `export const useFirstRunNoticeHold = () => false;`,
+  },
+  {
+    filter: /\/privacy\/firstRunNoticeHandoff$/,
+    contents: `export const markFirstPageDrawn = () => {};`,
+  },
+  {
+    filter: /\/Layout\/TitlebarControls$/,
+    contents: `export const getTitlebarControlInset = (mac) => (mac ? 100 : 16);`,
+  },
+  {
+    filter: /\/SecureStorageNotice$/,
+    contents: `export const KEY_STORAGE_NOTICE = 'Keys stay in your system keychain.';`,
+  },
+];
+
+/** A defect put back into one source file (relative to `components/`). Must match, or throw. */
+type Mutation = { file: string; from: string; to: string };
+
+function stubPlugin(mutations: Mutation[]): Plugin {
+  return {
+    name: 'page-headroom-stubs',
+    setup(b) {
+      for (const { filter, contents } of STUBS) {
+        b.onResolve({ filter }, (args) => ({
+          path: args.path,
+          namespace: 'stub',
+          pluginData: contents,
+        }));
+      }
+      b.onLoad({ filter: /.*/, namespace: 'stub' }, (args) => ({
+        contents: args.pluginData as string,
+        loader: 'js',
+        resolveDir: here,
+      }));
+      const hits = new Set<string>();
+      for (const mutation of mutations) {
+        const path = resolve(COMPONENTS, mutation.file);
+        b.onLoad({ filter: /\.tsx?$/ }, (args) => {
+          if (args.path !== path) return undefined;
+          const source = readFileSync(path, 'utf8');
+          if (!source.includes(mutation.from)) {
+            throw new Error(`the mutation of ${mutation.file} matches nothing`);
+          }
+          hits.add(mutation.file);
+          return {
+            contents: source.replace(mutation.from, mutation.to),
+            loader: path.endsWith('.tsx') ? 'tsx' : 'ts',
+          };
+        });
+      }
+      b.onEnd(() => {
+        for (const { file } of mutations) {
+          if (!hits.has(file)) throw new Error(`the mutated ${file} was never loaded`);
+        }
+      });
+    },
+  };
+}
+
+const ENTRY = `
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { MemoryRouter } from 'react-router-dom';
+import SettingsView from './SettingsView';
+import ProviderGuard from '../ProviderGuard';
+
+const surface = (window as any).__surface;
+const section = (window as any).__section;
+
+createRoot(document.getElementById('root')!).render(
+  surface === 'setup' ? (
+    <MemoryRouter>
+      <ProviderGuard didSelectProvider={false}>
+        <p>The application</p>
+      </ProviderGuard>
+    </MemoryRouter>
+  ) : (
+    <div id="shell">
+      <SettingsView onClose={() => {}} setView={() => {}} viewOptions={section ? { section } : {}} />
+    </div>
+  )
+);
+`;
+
+/** The app's stylesheet edited before Tailwind compiles it. Must match, or throw. */
+type CssEdit = { from: string; to: string };
+
+type Variant = { mutations?: Mutation[]; css?: CssEdit[] };
+type Prepared = { script: string; css: string };
+
+async function prepare(variant: Variant = {}): Promise<Prepared> {
+  const out = await build({
+    stdin: { contents: ENTRY, loader: 'tsx', resolveDir: here, sourcefile: 'entry.tsx' },
+    bundle: true,
+    write: false,
+    outdir: '/page-headroom',
+    format: 'iife',
+    jsx: 'automatic',
+    platform: 'browser',
+    plugins: [stubPlugin(variant.mutations ?? [])],
+    define: { 'process.env.NODE_ENV': '"production"' },
+    loader: { '.svg': 'dataurl', '.png': 'dataurl' },
+    logLevel: 'silent',
+  });
+  const script = out.outputFiles.find((file) => file.path.endsWith('.js'))!.text;
+  // The stylesheets the real components import (settings.css, onboarding.css, providers.css).
+  const componentCss = out.outputFiles.find((file) => file.path.endsWith('.css'))?.text ?? '';
+  let main = readFileSync(resolve(STYLES, 'main.css'), 'utf8');
+  for (const edit of variant.css ?? []) {
+    if (!main.includes(edit.from))
+      throw new Error(`the main.css edit matches nothing: ${edit.from}`);
+    main = main.replace(edit.from, edit.to);
+  }
+  const { compile } = await import(requireFromDesktop.resolve('@tailwindcss/node'));
+  const { Scanner } = requireFromDesktop('@tailwindcss/oxide');
+  const compiler = await compile(main, { base: STYLES, onDependency() {} });
+  const css = compiler.build(new Scanner({}).scanFiles([{ content: script, extension: 'js' }]));
+  return { script, css: `${css}\n${componentCss}` };
+}
+
+const launchChromium = async (): Promise<Browser | null> => {
+  for (const options of [{}, { channel: 'chromium' }, { channel: 'chrome' }] as const) {
+    try {
+      return await chromium.launch(options);
+    } catch {
+      // try the next build
+    }
+  }
+  return null;
+};
+
+/** Everything the assertions read, from one frame. */
+type Measure = {
+  bandBottom: number;
+  viewportTop: number;
+  viewportBottom: number;
+  viewportScrollTop: number;
+  rootScrollTop: number;
+  rootOverflow: number;
+  scrolled: string | null;
+  mask: string;
+  headroomToken: string;
+  rowClearance: number;
+  textClearance: number;
+  textBottom: number;
+  textHit: boolean;
+  text: string;
+};
+
+/**
+ * Read the page in one frame. The first ROW is the first Settings section box (its top is where
+ * the column's own padding ends) or the setup page's first line; the first TEXT is the first
+ * glyph run a person sees (not an `sr-only` description), and it is "visible" only when the
+ * element under its middle is the text's own, not the band or anything else.
+ */
+const measure = (tab: Page): Promise<Measure> =>
+  tab.evaluate(() => {
+    const band = document.querySelector('header[data-band]')!;
+    const root = document.querySelector<HTMLElement>('.br-scroll-root')!;
+    const viewport = root.querySelector<HTMLElement>(':scope > [data-radix-scroll-area-viewport]')!;
+    const row = viewport.querySelector('.biorouter-settings-section, [data-first-row]')!;
+    const walker = document.createTreeWalker(viewport, NodeFilter.SHOW_TEXT);
+    let text: { rect: DOMRect; el: Element } | null = null;
+    while (!text && walker.nextNode()) {
+      const node = walker.currentNode;
+      const el = node.parentElement;
+      if (!el || !node.textContent?.trim() || el.closest('.sr-only')) continue;
+      const range = document.createRange();
+      range.selectNodeContents(node);
+      const rect = range.getBoundingClientRect();
+      if (rect.width > 0 && rect.height > 0) text = { rect, el };
+    }
+    if (!text) throw new Error('no visible text in the scroller');
+    const bandBottom = band.getBoundingClientRect().bottom;
+    const box = viewport.getBoundingClientRect();
+    const { rect } = text;
+    const hit = document.elementFromPoint(
+      rect.left + Math.min(4, rect.width / 2),
+      rect.top + rect.height / 2
+    );
+    const style = getComputedStyle(viewport);
+    return {
+      bandBottom,
+      viewportTop: box.top,
+      viewportBottom: box.bottom,
+      viewportScrollTop: viewport.scrollTop,
+      rootScrollTop: root.scrollTop,
+      rootOverflow: root.scrollHeight - root.clientHeight,
+      scrolled: root.getAttribute('data-scrolled'),
+      mask: style.maskImage || style.getPropertyValue('-webkit-mask-image') || 'none',
+      headroomToken: getComputedStyle(document.documentElement)
+        .getPropertyValue('--page-headroom')
+        .trim(),
+      rowClearance: row.getBoundingClientRect().top - bandBottom,
+      textClearance: rect.top - bandBottom,
+      textBottom: rect.bottom,
+      textHit: Boolean(hit && (hit === text.el || text.el.contains(hit) || hit.contains(text.el))),
+      text: (text.el.textContent ?? '').trim().slice(0, 60),
+    };
+  });
+
+/** Wait until neither the viewport nor the root has moved for 400ms (smooth scrolls included). */
+const settle = (tab: Page) =>
+  tab.evaluate(
+    () =>
+      new Promise<void>((done) => {
+        const root = document.querySelector<HTMLElement>('.br-scroll-root')!;
+        const viewport = root.querySelector<HTMLElement>(
+          ':scope > [data-radix-scroll-area-viewport]'
+        )!;
+        let last = '';
+        let since = performance.now();
+        const tick = () => {
+          const now = `${viewport.scrollTop}|${root.scrollTop}`;
+          if (now !== last) {
+            last = now;
+            since = performance.now();
+          }
+          if (performance.now() - since > 400) done();
+          else requestAnimationFrame(tick);
+        };
+        requestAnimationFrame(tick);
+      })
+  );
+
+async function pointAtScroller(tab: Page) {
+  const box = await tab
+    .locator('.br-scroll-root > [data-radix-scroll-area-viewport]')
+    .first()
+    .boundingBox();
+  if (!box) throw new Error('the scroller has no box');
+  await tab.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+}
+
+/** The wheel, as a mouse sends it: notched steps. */
+async function wheel(tab: Page, deltaY: number, steps: number) {
+  await pointAtScroller(tab);
+  for (let i = 0; i < steps; i++) {
+    await tab.mouse.wheel(0, deltaY);
+    await tab.waitForTimeout(16);
+  }
+  await settle(tab);
+}
+
+/** A trackpad fling back to the top: many small deltas with no pause between them. */
+async function fling(tab: Page) {
+  await pointAtScroller(tab);
+  for (let i = 0; i < 160; i++) await tab.mouse.wheel(0, -24);
+  await settle(tab);
+}
+
+/** Wheel up until the scroller reports its top, the way a person keeps turning the wheel. */
+async function wheelToTop(tab: Page) {
+  for (let round = 0; round < 6; round++) {
+    await wheel(tab, -400, 8);
+    const top = await tab.evaluate(
+      () => document.querySelector('.br-scroll-root > [data-radix-scroll-area-viewport]')!.scrollTop
+    );
+    if (top === 0) return;
+  }
+}
+
+/**
+ * The owner's acceptance, at the top: the viewport and the root at 0, the fade off, and the
+ * first row and its first line fully visible with at least 24px of clear space under the band.
+ */
+function expectAtTop(m: Measure, label: string) {
+  const at = `${label}: ${JSON.stringify(m)}`;
+  expect(m.bandBottom, at).toBe(BAND);
+  expect(m.viewportTop, at).toBe(BAND);
+  expect(m.viewportScrollTop, at).toBe(0);
+  expect(m.rootScrollTop, at).toBe(0);
+  expect(m.scrolled, at).toBe('false');
+  expect(m.mask, at).toBe('none');
+  expect(m.rowClearance, at).toBeGreaterThanOrEqual(MIN_HEADROOM);
+  expect(m.textClearance, at).toBeGreaterThanOrEqual(MIN_HEADROOM);
+  expect(m.textBottom, at).toBeLessThanOrEqual(m.viewportBottom);
+  expect(m.textHit, at).toBe(true);
+  // The clear space is the shared token, not a per-page number that happens to be large enough.
+  expect(m.rowClearance, at).toBeCloseTo(parseFloat(m.headroomToken), 1);
+}
+
+describe('the top of Settings and the setup page', () => {
+  let browser: Browser | null = null;
+  let real: Prepared = { script: '', css: '' };
+
+  beforeAll(async () => {
+    browser = await launchChromium();
+    if (!browser) {
+      console.warn('No Chromium found: skipping the page headroom tests.');
+      return;
+    }
+    real = await prepare();
+    if (SHOTS) mkdirSync(SHOTS, { recursive: true });
+  }, 180_000);
+
+  afterAll(async () => {
+    await browser?.close();
+  }, 120_000);
+
+  async function open(
+    prepared: Prepared,
+    options: {
+      surface: 'settings' | 'setup';
+      section?: string;
+      size: { width: number; height: number };
+    }
+  ): Promise<Page> {
+    const tab = await browser!.newPage({ viewport: options.size, deviceScaleFactor: 2 });
+    await tab.setContent(
+      `<!doctype html><html><head><meta charset="utf-8"><style>${prepared.css}
+        #shell { height: 100vh; display: flex; flex-direction: column; }</style></head>` +
+        `<body style="margin:0;background:var(--background-canvas)"><div id="root"></div></body></html>`
+    );
+    await tab.evaluate(
+      ([surface, section]) => {
+        const w = window as unknown as Record<string, unknown>;
+        w.__surface = surface;
+        w.__section = section;
+        w.electron = { platform: 'darwin', on: () => () => {} };
+      },
+      [options.surface, options.section ?? null] as const
+    );
+    await tab.addScriptTag({ content: prepared.script });
+    await tab.waitForSelector(
+      options.surface === 'setup' ? '[data-first-row]' : '.biorouter-settings-section'
+    );
+    await settle(tab);
+    return tab;
+  }
+
+  async function shot(tab: Page, name: string) {
+    if (SHOTS) await tab.screenshot({ path: join(SHOTS, `${name}.png`) });
+  }
+
+  async function check(tab: Page, label: string) {
+    const m = await measure(tab);
+    await shot(tab, label);
+    expectAtTop(m, label);
+    return m;
+  }
+
+  for (const size of SIZES) {
+    const at = `${size.width}x${size.height}`;
+
+    it(`Settings: every tab, wheeled down and back to the top, at ${at}`, async (ctx) => {
+      if (!browser) return ctx.skip();
+      const tab = await open(real, { surface: 'settings', size });
+      try {
+        await check(tab, `settings-${at}-models-open`);
+        for (const name of ['models', 'chat', 'app'] as const) {
+          if (name !== 'models') {
+            await tab.click(`[data-testid="settings-${name}-tab"]`);
+            await settle(tab);
+            await check(tab, `settings-${at}-${name}-open`);
+          }
+          await wheel(tab, 300, 4);
+          const down = await measure(tab);
+          expect(down.viewportScrollTop, `${name} scrolled`).toBeGreaterThan(0);
+          expect(down.scrolled, `${name} scrolled`).toBe('true');
+          if (name === 'app') await fling(tab);
+          else await wheelToTop(tab);
+          await check(tab, `settings-${at}-${name}-back-at-top`);
+        }
+      } finally {
+        await tab.close();
+      }
+    }, 120_000);
+
+    it(`Settings opened at a section, then wheeled back to the top, at ${at}`, async (ctx) => {
+      if (!browser) return ctx.skip();
+      // `update` is the update notice's key (the About section, near the App tab's end), `project`
+      // the last section of Chat, and `privacy` a section near the top, which shortchanged the top
+      // by the viewport's 10px scroll padding alone.
+      for (const section of ['update', 'project', 'privacy']) {
+        const tab = await open(real, { surface: 'settings', section, size });
+        try {
+          const landed = await measure(tab);
+          expect(landed.viewportScrollTop, `${section} landed`).toBeGreaterThan(0);
+          expect(landed.rootScrollTop, `${section} landed`).toBe(0);
+          await shot(tab, `settings-${at}-${section}-landed`);
+          await wheelToTop(tab);
+          await check(tab, `settings-${at}-${section}-back-at-top`);
+          // Changing tab afterwards starts each tab at its top, with nothing left under the band.
+          for (const name of ['models', 'chat', 'app'] as const) {
+            await tab.click(`[data-testid="settings-${name}-tab"]`);
+            await settle(tab);
+            await check(tab, `settings-${at}-${section}-then-${name}`);
+          }
+        } finally {
+          await tab.close();
+        }
+      }
+    }, 180_000);
+
+    it(`the setup page, wheeled down and flung back to the top, at ${at}`, async (ctx) => {
+      if (!browser) return ctx.skip();
+      const tab = await open(real, { surface: 'setup', size });
+      try {
+        await check(tab, `setup-${at}-open`);
+        await wheel(tab, 300, 4);
+        expect((await measure(tab)).viewportScrollTop).toBeGreaterThan(0);
+        await wheelToTop(tab);
+        await check(tab, `setup-${at}-wheeled-back`);
+        await wheel(tab, 300, 4);
+        await fling(tab);
+        await check(tab, `setup-${at}-flung-back`);
+      } finally {
+        await tab.close();
+      }
+    }, 120_000);
+  }
+
+  /**
+   * Within a pixel of the top. A rest a fraction short of 0 is the top (`data-scrolled` counts a
+   * whole pixel), so the fade is off; and the smallest offset that does turn it on fades only the
+   * empty headroom, never the first row. Measured as the engine stores each offset: the Chromium
+   * this was written against stored a programmatic 0.5 as 1 at 2x, so the fractional branch is
+   * asserted only when the engine keeps a fraction, and the whole-pixel branch always.
+   */
+  it('fades nothing but the headroom within a pixel of the top', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const tab = await open(real, { surface: 'settings', size: SIZES[0] });
+    try {
+      for (const target of [0.5, 1, 2]) {
+        await wheel(tab, 300, 2);
+        const top = await tab.evaluate((value) => {
+          const viewport = document.querySelector<HTMLElement>(
+            '.br-scroll-root > [data-radix-scroll-area-viewport]'
+          )!;
+          viewport.scrollTop = value;
+          return viewport.scrollTop;
+        }, target);
+        await settle(tab);
+        const m = await measure(tab);
+        const fade = await tab.evaluate(() =>
+          parseFloat(
+            getComputedStyle(document.documentElement).getPropertyValue('--scroll-fade-top')
+          )
+        );
+        const at = JSON.stringify({ target, top, fade, ...m });
+        expect(fade, at).toBeGreaterThan(0);
+        // An engine that rounds the fraction down has put the scroller at its top, measured above.
+        if (top === 0) continue;
+        if (top < 1) {
+          expect(m.scrolled, at).toBe('false');
+          expect(m.mask, at).toBe('none');
+        } else {
+          expect(m.scrolled, at).toBe('true');
+        }
+        // The fade's whole height ends above the first row, so the row is drawn at full ink.
+        expect(m.rowClearance - (m.viewportTop - m.bandBottom), at).toBeGreaterThan(fade);
+        expect(m.rowClearance, at).toBeGreaterThan(MIN_HEADROOM - 3);
+        expect(m.textHit, at).toBe(true);
+      }
+    } finally {
+      await tab.close();
+    }
+  }, 60_000);
+
+  /**
+   * THE INSTRUMENT. A harness that cannot show the defect would pass anything, so the defect is put
+   * back: the viewport unpositioned (`main.css`) and the root's guard gone (`ui/scroll-area.tsx`).
+   * Opening Settings at `update` must then leave the root scrolled and the first row under the
+   * band after the wheel reaches the top, exactly as the owner saw it. Each half alone holds.
+   */
+  const UNPOSITIONED: CssEdit = {
+    from: '.br-scroll-viewport {\n  position: relative;\n',
+    to: '.br-scroll-viewport {\n',
+  };
+  const UNGUARDED: Mutation = {
+    file: 'ui/scroll-area.tsx',
+    from: "root.addEventListener('scroll', pin, { passive: true });",
+    to: '',
+  };
+
+  async function updateThenTop(prepared: Prepared): Promise<Measure> {
+    const tab = await open(prepared, { surface: 'settings', section: 'update', size: SIZES[1] });
+    try {
+      await wheelToTop(tab);
+      return await measure(tab);
+    } finally {
+      await tab.close();
+    }
+  }
+
+  it('the instrument: with both halves removed, the top stays under the band', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const broken = await updateThenTop(
+      await prepare({ css: [UNPOSITIONED], mutations: [UNGUARDED] })
+    );
+    expect(broken.rootOverflow, JSON.stringify(broken)).toBeGreaterThan(0);
+    expect(broken.viewportScrollTop, JSON.stringify(broken)).toBe(0);
+    expect(broken.rootScrollTop, JSON.stringify(broken)).toBeGreaterThan(0);
+    expect(broken.rowClearance, JSON.stringify(broken)).toBeLessThan(MIN_HEADROOM);
+    expect(broken.textHit, JSON.stringify(broken)).toBe(false);
+  }, 180_000);
+
+  it('the instrument: either half alone keeps the top in view', async (ctx) => {
+    if (!browser) return ctx.skip();
+    const positionedOnly = await updateThenTop(await prepare({ mutations: [UNGUARDED] }));
+    expect(positionedOnly.rootOverflow, JSON.stringify(positionedOnly)).toBe(0);
+    expectAtTop(positionedOnly, 'viewport positioned, no guard');
+    const guardOnly = await updateThenTop(await prepare({ css: [UNPOSITIONED] }));
+    expect(guardOnly.rootOverflow, JSON.stringify(guardOnly)).toBeGreaterThan(0);
+    expectAtTop(guardOnly, 'guard, viewport unpositioned');
+  }, 180_000);
+});
diff --git a/ui/desktop/src/components/settings/providers/ProviderSettingsPage.tsx b/ui/desktop/src/components/settings/providers/ProviderSettingsPage.tsx
index a983b1f84..2a7f8e17f 100644
--- a/ui/desktop/src/components/settings/providers/ProviderSettingsPage.tsx
+++ b/ui/desktop/src/components/settings/providers/ProviderSettingsPage.tsx
@@ -153,8 +153,10 @@ export default function ProviderSettings({
         onBack={onClose}
         tabs={<div ref={setTabsHost} className="br-provider-band-tabs-host" />}
       />
+      {/* `br-page-headroom`: the clear space under the band at the top, the one Settings and the
+          first-run page keep too (`--page-headroom`). */}
       <ScrollArea className="flex-1 w-full">
-        <div className="mx-auto w-full max-w-measure-chat px-6 py-6">
+        <div className="br-page-headroom mx-auto w-full max-w-measure-chat px-6 pb-6">
           {/* Mounted at once, so the coding-agent probe runs while the list loads; the catalog
               draws the skeleton until it knows which tab opens, then opens there at rest. */}
           <ProviderCatalog
diff --git a/ui/desktop/src/components/ui/scroll-area.test.tsx b/ui/desktop/src/components/ui/scroll-area.test.tsx
index d6e07b47c..be220b557 100644
--- a/ui/desktop/src/components/ui/scroll-area.test.tsx
+++ b/ui/desktop/src/components/ui/scroll-area.test.tsx
@@ -239,6 +239,67 @@ describe('ScrollArea scrollbar visibility', () => {
     expect(root).not.toHaveAttribute('data-scrolling');
   });
 
+  /**
+   * The 2026-10-12 defect: `scrollIntoView` scrolled the `overflow: hidden` root along with the
+   * viewport, the wheel returned only the viewport to 0, and the page's first lines stayed under
+   * the band. Chromium is where the root stops having anything to scroll
+   * (`settings/pageHeadroom.browser.test.tsx`); this is the component's own promise that a root
+   * which does scroll is put back.
+   */
+  it('puts its root back at the origin whenever anything scrolls it', () => {
+    const { container } = render(
+      <ScrollArea>
+        <div />
+      </ScrollArea>
+    );
+    const root = container.querySelector<HTMLElement>('.br-scroll-root')!;
+    const offset = { top: 0, left: 0 };
+    Object.defineProperty(root, 'scrollTop', {
+      configurable: true,
+      get: () => offset.top,
+      set: (value: number) => {
+        offset.top = value;
+      },
+    });
+    Object.defineProperty(root, 'scrollLeft', {
+      configurable: true,
+      get: () => offset.left,
+      set: (value: number) => {
+        offset.left = value;
+      },
+    });
+    offset.top = 435;
+    offset.left = 12;
+    act(() => {
+      root.dispatchEvent(new Event('scroll'));
+    });
+    expect(offset).toEqual({ top: 0, left: 0 });
+  });
+
+  it('counts a whole pixel as scrolled, so a fractional rest at the top keeps no fade', () => {
+    const { container } = render(
+      <ScrollArea>
+        <div />
+      </ScrollArea>
+    );
+    const root = container.querySelector('.br-scroll-root')!;
+    const viewport = container.querySelector<HTMLElement>('.br-scroll-viewport')!;
+    const state = scriptViewport(viewport, { height: 100, content: 1000 });
+    const scrollTo = (top: number) =>
+      act(() => {
+        state.top = top;
+        viewport.dispatchEvent(new Event('scroll'));
+      });
+    scrollTo(40);
+    expect(root).toHaveAttribute('data-scrolled', 'true');
+    scrollTo(0.5);
+    expect(root).toHaveAttribute('data-scrolled', 'false');
+    scrollTo(1);
+    expect(root).toHaveAttribute('data-scrolled', 'true');
+    scrollTo(0);
+    expect(root).toHaveAttribute('data-scrolled', 'false');
+  });
+
   it('hides the thumb at rest and shows it on hover or while scrolling, in main.css', async () => {
     const { readFileSync } = await import('node:fs');
     const { resolve } = await import('node:path');
diff --git a/ui/desktop/src/components/ui/scroll-area.tsx b/ui/desktop/src/components/ui/scroll-area.tsx
index d52c65361..c76d78f29 100644
--- a/ui/desktop/src/components/ui/scroll-area.tsx
+++ b/ui/desktop/src/components/ui/scroll-area.tsx
@@ -226,7 +226,11 @@ const ScrollArea = React.forwardRef<ScrollAreaHandle, ScrollAreaProps>(
         onScrollChange?.(true);
       }
 
-      setIsScrolled(scrollTop > 0);
+      // A whole pixel, not "above 0": where the engine keeps sub-pixel scroll offsets, a scroller
+      // can come to rest a fraction short of its top, and "> 0" then left the top fade on over a
+      // page that reads as at its top. Under a page's headroom (`--page-headroom`, taller than the
+      // fade) the first pixels of fade cover no row either way.
+      setIsScrolled(scrollTop >= 1);
 
       if (handleScrollProp) {
         handleScrollProp(viewport);
@@ -370,6 +374,28 @@ const ScrollArea = React.forwardRef<ScrollAreaHandle, ScrollAreaProps>(
       };
     }, []);
 
+    // THE ROOT NEVER SCROLLS; the viewport does. The root is `overflow: hidden`, which stops a
+    // wheel but not `scrollIntoView` or focus scrolling, and nothing a person can do scrolls it
+    // back. That is the 2026-10-12 defect: opening Settings at a section scrolled the root along
+    // with the viewport, the wheel returned only the viewport to 0, and the page's first lines
+    // stayed under the band. Its cause, absolutely positioned content measured against the root,
+    // is closed in `main.css` (`.br-scroll-viewport`, `position: relative`), which leaves the root
+    // nothing to scroll. This puts it back if anything ever does, in the frame it moved (scroll
+    // events run before paint); with the CSS half removed, it alone holds the top through a smooth
+    // `scrollIntoView` (`settings/pageHeadroom.browser.test.tsx`, the instrument). Scroll events
+    // do not bubble, so the viewport's own never reach this listener.
+    React.useEffect(() => {
+      const root = rootRef.current;
+      if (!root) return;
+      const pin = () => {
+        if (root.scrollTop !== 0) root.scrollTop = 0;
+        if (root.scrollLeft !== 0) root.scrollLeft = 0;
+      };
+      pin();
+      root.addEventListener('scroll', pin, { passive: true });
+      return () => root.removeEventListener('scroll', pin);
+    }, []);
+
     return (
       <ScrollAreaPrimitive.Root
         ref={rootRef}
diff --git a/ui/desktop/src/styles/main.css b/ui/desktop/src/styles/main.css
index 75c0c8da5..b896c2179 100644
--- a/ui/desktop/src/styles/main.css
+++ b/ui/desktop/src/styles/main.css
@@ -499,6 +499,25 @@
      a visible pink rule at 4x. Two clear pixels remove it outright, and cost
      nothing visible: at 10px those pixels were already under 20% alpha. */
   --scroll-fade-clear: 2px;
+  /* THE PAGE'S HEADROOM: the clear space between a page band's bottom edge
+     (`--chrome-height`) and the first row of the page under it, while the page
+     is at its top. ONE value for every page that puts a scrolled reading column
+     under a band: Settings, the first-run setup page and the provider page
+     (`.br-page-headroom`, authored below the scroll fade). It is padding on the
+     scrolled content, not a gap above the scroller, so it scrolls away with the
+     first row and a page in motion keeps every pixel of its height.
+
+     ⚠ It must stay taller than `--scroll-fade-top`. At the top the fade is off
+     (`data-scrolled` is false below a whole pixel of scroll), and for the first
+     pixels after it turns on it covers only this empty space, never a row.
+     `styles/settingsScrollFade.test.ts` holds the two apart.
+
+     24px is the owner's floor ("leave plenty of headroom at the top", the
+     2026-10-12 report): Settings drew its first section 20px under the band and
+     the setup page 24px, each from its own padding literal (`py-5`, `py-6`), so
+     the one page read cramped against the band beside the other.
+     `settings/pageHeadroom.browser.test.tsx` measures it in Chromium. */
+  --page-headroom: 24px;
 
   /* Rows. Two rhythms and no more: the rail (sidebar, nav, menu item, recents,
      select option) and the content list. They are separate because they answer
@@ -5012,6 +5031,18 @@ body:has(.biorouter-modal-surface [data-slot='select-content'][data-state='open'
   );
 }
 
+/* THE PAGE'S HEADROOM (`--page-headroom`), on the first box INSIDE a page's
+   scroller: Settings' reading column (`settings/SettingsView.tsx`), the
+   first-run setup page (`ProviderGuard.tsx`) and the provider page
+   (`settings/providers/ProviderSettingsPage.tsx`). Inside, so it scrolls away
+   with the first row rather than standing as a dead strip under the band.
+   Authored rather than a Tailwind arbitrary value, for the class-scanning
+   reason the fade above gives; the call sites keep their bottom padding as a
+   `pb-*` utility and give the top to this rule alone. */
+.br-page-headroom {
+  padding-top: var(--page-headroom);
+}
+
 .biorouter-settings-section {
   padding-block: 14px;
 }
@@ -6081,8 +6112,27 @@ body:has(.biorouter-modal-surface [data-slot='select-content'][data-state='open'
 /* ScrollArea (`ui/scroll-area.tsx`): the viewport's native scrollbar rests hidden and shows
    while the pointer is over the area or it is scrolling (`data-scrolling`, set by the
    component). `scrollbar-color` for Chromium's standard scrollbar, the thumb pseudo-element for
-   the WebKit one; both beat the global `*` rule by specificity. */
+   the WebKit one; both beat the global `*` rule by specificity.
+
+   ⚠ `position: relative` makes the VIEWPORT the containing block of everything absolutely
+   positioned in the scrolled content that has no positioned box of its own above it, and is the
+   fix for the 2026-10-12 report "the first lines do not show when scrolled all the way up".
+   Unpositioned, the viewport handed those boxes to the ROOT: an InfoTip's `sr-only` description
+   (a 1px absolute span on every row with help) was placed against the root, past the viewport's
+   clip, and gave the `overflow: hidden` root up to 1,600px of overflow. A wheel cannot scroll a
+   hidden box, but `scrollIntoView` and focus scrolling can, and they did: opening Settings at a
+   section (the update notice's "update", "usage", "project", even "privacy" by the 10px of the
+   viewport's scroll padding) scrolled the root too, the wheel brought only the viewport back to
+   0, and the top of the page stayed under the band, on every tab, until Settings was reopened.
+   Positioned here, those boxes are clipped and scrolled by the viewport like the rows they
+   describe, the root has nothing to scroll, and `ui/scroll-area.tsx` puts the root back if
+   anything ever scrolls it again. The transcripts' viewports already ran this way after their
+   first find (`SearchHighlighter` sets it inline, and never unsets it), and the component views
+   (Workflows, the Scheduler, Built apps, Extensions, Skills, Chat history) wrap their content in a
+   positioned box of their own, so neither moves. `settings/pageHeadroom.browser.test.tsx` opens
+   Settings at a section and wheels back to the top. */
 .br-scroll-viewport {
+  position: relative;
   scrollbar-color: transparent transparent;
 }
 
diff --git a/ui/desktop/src/styles/settingsScrollFade.test.ts b/ui/desktop/src/styles/settingsScrollFade.test.ts
index ef7ff319e..4f1c163e0 100644
--- a/ui/desktop/src/styles/settingsScrollFade.test.ts
+++ b/ui/desktop/src/styles/settingsScrollFade.test.ts
@@ -142,6 +142,50 @@ describe('the settings scroll-edge fade', () => {
    */
   it('keeps the data-scrolled attribute the selector depends on', () => {
     expect(SCROLL_AREA).toContain('data-scrolled={isScrolled}');
-    expect(SCROLL_AREA).toContain('setIsScrolled(scrollTop > 0)');
+    // A whole pixel: a scroller resting a fraction short of its top is at its top, and the fade
+    // must be off there (the 2026-10-12 report's "including fractional scrollTop values").
+    expect(SCROLL_AREA).toContain('setIsScrolled(scrollTop >= 1)');
+  });
+});
+
+/**
+ * The page's headroom (`--page-headroom`), the clear space under the band while the page is at
+ * its top (2026-10-12: "leave plenty of headroom at the top"). Measured in Chromium by
+ * `components/settings/pageHeadroom.browser.test.tsx`; what only the source can say is that it is
+ * ONE value, that it clears the fade, and that both pages read it rather than a padding literal.
+ */
+describe('the page headroom under the band', () => {
+  const px = (name: string) => {
+    const match = CSS.match(new RegExp(`--${name}:\\s*(\\d+)px;`));
+    if (!match) throw new Error(`main.css declares no --${name} in px`);
+    return Number(match[1]);
+  };
+
+  it('is at least 24px, and taller than the top fade, so a resting fade covers no row', () => {
+    expect(px('page-headroom')).toBeGreaterThanOrEqual(24);
+    expect(px('page-headroom')).toBeGreaterThan(px('scroll-fade-top'));
+  });
+
+  it('is declared once and read by one authored rule', () => {
+    expect(CSS.match(/--page-headroom:/g)).toHaveLength(1);
+    expect(CSS).toMatch(/\n\.br-page-headroom \{\s*padding-top: var\(--page-headroom\);\s*\}/);
+  });
+
+  it('is what Settings and the two provider pages start their column with', () => {
+    const read = (rel: string) => readFileSync(join(__dirname, '../components', rel), 'utf8');
+    const bodies: Record<string, string | undefined> = {
+      'settings/SettingsView.tsx': SETTINGS_VIEW.match(
+        /<ReadableContent size="chat" className="([^"]+)"/
+      )?.[1],
+    };
+    for (const rel of ['ProviderGuard.tsx', 'settings/providers/ProviderSettingsPage.tsx']) {
+      bodies[rel] = read(rel).match(/<ScrollArea[^>]*>\s*<div className="([^"]+)"/)?.[1];
+    }
+    for (const [rel, classes] of Object.entries(bodies)) {
+      expect(classes?.split(' '), rel).toContain('br-page-headroom');
+      // The top is the rule's alone: a `py-*` or `pt-*` beside it would be a second opinion
+      // that the unlayered rule silently overrules.
+      expect(classes, rel).not.toMatch(/\bp[ty]-\d/);
+    }
   });
 });

From c241780e438cf8f362b270b804a053603ee992c3 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:10:41 -0700
Subject: [PATCH 18/26] fix(agent): the live copy of a reply keeps who it is
 for, so a user-only notice streams as user-only (diagnostics 20261006_2)

categorize_tool_requests rebuilt the message the client is shown live with
default metadata. The notice that nothing ran was stored for the person only
but streamed as visible to the model, so a client holding the live copy held
the wrong one. The rebuilt message now carries the reply's own metadata; the
agent replay of diagnostics 20261006_2 asserts the live notice is user-only.
---
 crates/biorouter/src/agents/reply_parts.rs              | 4 ++++
 crates/biorouter/tests/ollama_diagnostics_20261006_2.rs | 5 +++++
 2 files changed, 9 insertions(+)

diff --git a/crates/biorouter/src/agents/reply_parts.rs b/crates/biorouter/src/agents/reply_parts.rs
index 3f22fcd6b..b3cb55984 100644
--- a/crates/biorouter/src/agents/reply_parts.rs
+++ b/crates/biorouter/src/agents/reply_parts.rs
@@ -1114,6 +1114,10 @@ impl Agent {
         if let Some(id) = response.id.clone() {
             filtered_message = filtered_message.with_id(id);
         }
+        // And who the message is for: this copy is the one the client is
+        // shown live, and a user-only notice (`UnrunCallWatch`) streamed as
+        // visible to the model while its stored row said otherwise.
+        filtered_message.metadata = response.metadata.clone();
 
         // Categorize tool requests
         let mut frontend_requests = Vec::new();
diff --git a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
index 5af3e04e6..122a11f51 100644
--- a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
+++ b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
@@ -728,6 +728,11 @@ async fn the_agent_tells_the_person_nothing_ran_and_keeps_it_from_the_model() {
         "{}",
         note.msg
     );
+    assert!(
+        notices[0].is_user_visible() && !notices[0].is_agent_visible(),
+        "the live copy says who the notice is for, as the stored row does: {:?}",
+        notices[0].metadata
+    );
     assert!(shown
         .iter()
         .any(|message| message.as_concat_text() == reply(7)));

From 50a6a3c14126b3955c0d66310bca37732c11f5ab Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:31:50 -0700
Subject: [PATCH 19/26] test(crew): cover capability placement in the self-test
 workflow

---
 biorouter-self-test.yaml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/biorouter-self-test.yaml b/biorouter-self-test.yaml
index aa1f06600..9bef2ff5a 100644
--- a/biorouter-self-test.yaml
+++ b/biorouter-self-test.yaml
@@ -163,6 +163,7 @@ instructions: |
   - Enable/disable extensions
   - Test extension interactions
   - Verify isolation between extensions
+  - In the desktop, verify Crew appears in Settings > Chat > Capabilities and is absent from the Extensions page and the composer's Tools popover. Preserve the fixture's existing Crew on/off choice.
   - In a disposable chat, browse `/` and `/ext:` and confirm current capability labels including Biorouter Copilot. Select a session-only extension and verify its exact reference identity.
   - Submit `/extend Biorouter Copilot` and verify guidance names `/ext:BiorouterCopilot` without model execution or a permission grant.
   - Verify `/effort` and a harmless configured workflow in the desktop, TUI, and classic CLI. A missing workflow must report its problem instead of falling through to the model.
@@ -210,6 +211,7 @@ instructions: |
   fixture or desktop leaves GUI evidence unavailable; never claim a skipped action passed.
 
   For a Crew-enabled fixture, additionally:
+  - Toggle Crew in Settings > Chat > Capabilities, reload the disposable fixture, and verify the choice persists; restore its original value.
   - Confirm the empty `/crew` view identifies the isolated profile and does not imply authentication success when no workspace exists
   - Exercise the workspace form's required connection, invitation, and pinned-key validation using synthetic values only
   - Verify first-host preparation is explicit, host-key trust is visible, and no private key or provider credential is entered into the fixture

From 49443a73a18480ae0200d066b7d87a4694c370bb Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:33:49 -0700
Subject: [PATCH 20/26] fix(extensions): withdraw failure toasts from every
 chat

---
 .../src/utils/extensionErrorUtils.test.ts     | 17 ++++++++++++
 ui/desktop/src/utils/extensionErrorUtils.ts   | 26 +++++++++----------
 2 files changed, 29 insertions(+), 14 deletions(-)

diff --git a/ui/desktop/src/utils/extensionErrorUtils.test.ts b/ui/desktop/src/utils/extensionErrorUtils.test.ts
index a4bcb1756..4cb3c58e2 100644
--- a/ui/desktop/src/utils/extensionErrorUtils.test.ts
+++ b/ui/desktop/src/utils/extensionErrorUtils.test.ts
@@ -345,6 +345,23 @@ describe("the Extensions page announces a failure in the toast's place", () => {
     expect(toastService.dismiss).not.toHaveBeenCalled();
   });
 
+  it('withdraws every distinct single-extension failure across chats', () => {
+    vi.mocked(toastService.error)
+      .mockReturnValueOnce('chat-a-failure')
+      .mockReturnValueOnce('chat-b-failure');
+    showExtensionLoadResults([bad('notion-mcp')], 'chat-a');
+    showExtensionLoadResults([bad('cdwagent')], 'chat-b');
+
+    withdrawExtensionFailureToasts();
+
+    expect(vi.mocked(toastService.dismiss).mock.calls).toEqual([
+      ['chat-a-failure'],
+      ['chat-b-failure'],
+    ]);
+    withdrawExtensionFailureToasts();
+    expect(toastService.dismiss).toHaveBeenCalledTimes(2);
+  });
+
   it('leaves a progress or clean-run report alone', () => {
     setFocusedChatSession('chat-a');
     showExtensionLoadResults([ok('medcp'), ok('cdwagent')], 'chat-a');
diff --git a/ui/desktop/src/utils/extensionErrorUtils.ts b/ui/desktop/src/utils/extensionErrorUtils.ts
index 91a7a16b0..819da22df 100644
--- a/ui/desktop/src/utils/extensionErrorUtils.ts
+++ b/ui/desktop/src/utils/extensionErrorUtils.ts
@@ -58,8 +58,8 @@ let focusedChatSessionId: string | null = null;
 /** True while the extension toast currently on screen is reporting a failure. */
 let extensionToastIsFailure = false;
 
-/** The single-failure toast last raised here, so the standing notice can take it down. */
-let singleFailureToastId: string | number | null = null;
+/** Single-failure reports from every chat, so the standing notice can take them all down. */
+const singleFailureToastIds = new Set<string | number>();
 
 /**
  * Called by the chat shell as the active group changes. Readiness is only news
@@ -73,7 +73,7 @@ export function setFocusedChatSession(sessionId: string | null): void {
 export function resetExtensionToastState(): void {
   focusedChatSessionId = null;
   extensionToastIsFailure = false;
-  singleFailureToastId = null;
+  singleFailureToastIds.clear();
 }
 
 /**
@@ -84,10 +84,8 @@ export function resetExtensionToastState(): void {
  * clean-run report is not a failure report, and is left alone.
  */
 export function withdrawExtensionFailureToasts(): void {
-  if (singleFailureToastId !== null) {
-    toastService.dismiss(singleFailureToastId);
-    singleFailureToastId = null;
-  }
+  for (const id of singleFailureToastIds) toastService.dismiss(id);
+  singleFailureToastIds.clear();
   if (extensionToastIsFailure) {
     toastService.dismissExtensionFailureReport();
     // Nothing on screen reports a failure now, so rule 2 has nothing left to protect.
@@ -217,13 +215,13 @@ export function showExtensionLoadResults(
     const recoverHints = createExtensionRecoverHints(errorMsg);
     const displayMsg = formatExtensionErrorMessage(errorMsg, 'Failed to load extension');
 
-    singleFailureToastId =
-      toastService.error({
-        title: failed.name,
-        msg: displayMsg,
-        traceback: errorMsg,
-        recoverHints,
-      }) ?? null;
+    const id = toastService.error({
+      title: failed.name,
+      msg: displayMsg,
+      traceback: errorMsg,
+      recoverHints,
+    });
+    if (id !== undefined) singleFailureToastIds.add(id);
     // Only now — a failure that was never rendered has not been announced, and
     // must keep its one announcement for the load that does render it.
     markExtensionLoadFailuresAnnounced([failed.name]);

From 786d027f7adc9452c64ce9c9c9b4536a51eb450d Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:36:17 -0700
Subject: [PATCH 21/26] fix(ollama): explain response body idle timeouts

---
 crates/biorouter/src/providers/ollama.rs      |  66 ++++++++++-
 .../tests/ollama_diagnostics_20261006_2.rs    | 109 ++++++++++++++++++
 2 files changed, 170 insertions(+), 5 deletions(-)

diff --git a/crates/biorouter/src/providers/ollama.rs b/crates/biorouter/src/providers/ollama.rs
index a6e9f83d7..4fa3dc410 100644
--- a/crates/biorouter/src/providers/ollama.rs
+++ b/crates/biorouter/src/providers/ollama.rs
@@ -1425,7 +1425,24 @@ async fn collect_reply(
 
 /// An error out of the format module: the [`ProviderError`] it carries, or a
 /// decode failure.
-fn provider_error(error: anyhow::Error) -> ProviderError {
+fn provider_error(
+    error: anyhow::Error,
+    idle: Duration,
+    timeout_setting: &str,
+    text_bytes: usize,
+) -> ProviderError {
+    if error.chain().any(|cause| {
+        cause
+            .downcast_ref::<reqwest::Error>()
+            .is_some_and(reqwest::Error::is_timeout)
+    }) {
+        return waited_too_long(
+            ProviderError::RequestFailed("response body read timed out".to_string()),
+            idle,
+            timeout_setting,
+            text_bytes,
+        );
+    }
     error.downcast::<ProviderError>().unwrap_or_else(|error| {
         ProviderError::RequestFailed(format!("Stream decode error: {error}"))
     })
@@ -1524,6 +1541,9 @@ fn decode_native(
     mut log: RequestLog,
     options: DecodeOptions,
     unknown_tool: Arc<Mutex<Option<UnknownToolCalled>>>,
+    idle: Duration,
+    timeout_setting: &'static str,
+    text_bytes: usize,
 ) -> MessageStream {
     let bytes = response.bytes_stream().map_err(io::Error::other);
     Box::pin(try_stream! {
@@ -1541,7 +1561,7 @@ fn decode_native(
                         }
                         mapped
                     }
-                    Err(error) => provider_error(error),
+                    Err(error) => provider_error(error, idle, timeout_setting, text_bytes),
                 };
                 let _ = log.provider_error(&error);
                 error
@@ -1560,6 +1580,8 @@ struct NativeTurn {
     model_config: ModelConfig,
     check: TurnCheck,
     window_setting: &'static str,
+    idle: Duration,
+    timeout_setting: &'static str,
     /// Every item of the turn, retry included, carries this id, so the agent
     /// folds them into one assistant message.
     message_id: String,
@@ -1595,6 +1617,8 @@ fn native_turn(turn: NativeTurn, first: Response, first_log: RequestLog) -> Mess
             model_config,
             mut check,
             window_setting,
+            idle,
+            timeout_setting,
             message_id,
             tools,
             mut retried,
@@ -1631,6 +1655,9 @@ fn native_turn(turn: NativeTurn, first: Response, first_log: RequestLog) -> Mess
                     message_id: Some(message_id.clone()),
                 },
                 unknown_tool.clone(),
+                idle,
+                timeout_setting,
+                check.text_bytes,
             );
             let mut recovered = recover_leaked_tool_calls(
                 decoded,
@@ -2440,6 +2467,8 @@ impl OllamaProvider {
             model_config: model_config.clone(),
             check,
             window_setting: self.window_setting,
+            idle: self.idle,
+            timeout_setting: self.timeout_setting,
             message_id: format!("ollama_{}", uuid::Uuid::new_v4().simple()),
             tools: tools.to_vec(),
             retried: false,
@@ -2615,7 +2644,13 @@ impl OllamaProvider {
                 let _ = log.provider_error(e);
             })?;
         let decoded = recover_leaked_tool_calls(
-            stream_openai_compat_checked(response, log),
+            stream_openai_compat_checked(
+                response,
+                log,
+                self.idle,
+                self.timeout_setting,
+                check.text_bytes,
+            ),
             RecoveryContext {
                 tools: tools.to_vec(),
                 provider: "ollama",
@@ -2696,7 +2731,13 @@ fn v1_capability_error(error: ProviderError, model: &str) -> ProviderError {
 /// Measured on Ollama 0.40.2: when ministral-3:8b called an undeclared tool
 /// after streaming text, `/v1` silently dropped the error and just ended the
 /// body, which the generic decoder handed on as a complete, successful reply.
-fn stream_openai_compat_checked(response: Response, mut log: RequestLog) -> MessageStream {
+fn stream_openai_compat_checked(
+    response: Response,
+    mut log: RequestLog,
+    idle: Duration,
+    timeout_setting: &'static str,
+    text_bytes: usize,
+) -> MessageStream {
     let bytes = response.bytes_stream().map_err(io::Error::other);
     Box::pin(try_stream! {
         let ended = Arc::new(AtomicBool::new(false));
@@ -2719,7 +2760,7 @@ fn stream_openai_compat_checked(response: Response, mut log: RequestLog) -> Mess
         tokio::pin!(decoded);
         while let Some(item) = decoded.next().await {
             let item = item.map_err(|error| {
-                let error = provider_error(error);
+                let error = provider_error(error, idle, timeout_setting, text_bytes);
                 let _ = log.provider_error(&error);
                 error
             })?;
@@ -5508,4 +5549,19 @@ mod tests {
             );
         }
     }
+
+    #[test]
+    fn a_decode_error_that_mentions_timeout_keeps_its_original_classification() {
+        let error = provider_error(
+            anyhow::anyhow!("invalid JSON in a reply about a timeout"),
+            Duration::from_secs(600),
+            BUILTIN_TIMEOUT_SETTING,
+            160_000,
+        );
+        assert!(matches!(error, ProviderError::RequestFailed(_)));
+        assert_eq!(
+            error.to_string(),
+            "Request failed: Stream decode error: invalid JSON in a reply about a timeout"
+        );
+    }
 }
diff --git a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
index 122a11f51..5eb0abb19 100644
--- a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
+++ b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
@@ -567,6 +567,115 @@ async fn a_first_prompt_slower_than_the_idle_bound_names_the_bound_and_is_sent_o
     assert_eq!(chat_requests(&server).await.len(), 1, "sent once");
 }
 
+#[tokio::test]
+async fn a_body_timeout_after_headers_names_the_bound_and_is_sent_once() {
+    use std::sync::atomic::{AtomicUsize, Ordering};
+    use std::sync::Arc;
+    use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let address = listener.local_addr().unwrap();
+    let requests = Arc::new(AtomicUsize::new(0));
+    let counted = requests.clone();
+    let server = tokio::spawn(async move {
+        let mut clients = tokio::task::JoinSet::new();
+        loop {
+            let (mut socket, _) = listener.accept().await.unwrap();
+            let counted = counted.clone();
+            clients.spawn(async move {
+                let mut request = Vec::new();
+                let mut buf = [0_u8; 4096];
+                let header_end = loop {
+                    let n = socket.read(&mut buf).await.unwrap();
+                    if n == 0 {
+                        return;
+                    }
+                    request.extend_from_slice(&buf[..n]);
+                    if let Some(end) = request.windows(4).position(|w| w == b"\r\n\r\n") {
+                        break end + 4;
+                    }
+                };
+                let headers = String::from_utf8_lossy(&request[..header_end]).into_owned();
+                let content_length = headers
+                    .lines()
+                    .find_map(|line| {
+                        let (name, value) = line.split_once(':')?;
+                        name.eq_ignore_ascii_case("content-length")
+                            .then(|| value.trim().parse::<usize>().unwrap())
+                    })
+                    .unwrap_or(0);
+                while request.len() < header_end + content_length {
+                    let n = socket.read(&mut buf).await.unwrap();
+                    if n == 0 {
+                        return;
+                    }
+                    request.extend_from_slice(&buf[..n]);
+                }
+                let route = headers.split_whitespace().nth(1).unwrap();
+                let body = match route {
+                    "/api/show" => show(131_072, None).to_string(),
+                    "/api/version" => json!({"version": "0.40.2"}).to_string(),
+                    "/api/ps" => json!({"models": []}).to_string(),
+                    "/api/chat" => {
+                        counted.fetch_add(1, Ordering::SeqCst);
+                        text_body("hello", 37_000, 0)
+                    }
+                    _ => panic!("unexpected route {route}"),
+                };
+                socket
+                    .write_all(
+                        format!(
+                            "HTTP/1.1 200 OK\r\nContent-Type: application/x-ndjson\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+                            body.len()
+                        )
+                        .as_bytes(),
+                    )
+                    .await
+                    .unwrap();
+                if route == "/api/chat" {
+                    tokio::time::sleep(std::time::Duration::from_secs(3)).await;
+                }
+                let _ = socket.write_all(body.as_bytes()).await;
+            });
+        }
+    });
+    let provider = OllamaProvider::from_custom_config(
+        ModelConfig::new_or_fail(&format!("llama3.1:8b-{}", uuid::Uuid::new_v4().simple())),
+        DeclarativeProviderConfig {
+            name: "ollama-body-timeout".to_string(),
+            engine: ProviderEngine::Ollama,
+            display_name: "Ollama body timeout".to_string(),
+            description: None,
+            api_key_env: "NOT_USED".to_string(),
+            base_url: format!("http://{address}"),
+            models: vec![],
+            headers: None,
+            timeout_seconds: Some(1),
+            supports_streaming: Some(true),
+        },
+    )
+    .unwrap();
+    let turn = turn(
+        &provider,
+        &"s".repeat(160_000),
+        "hello",
+        &code_execution_roster(),
+    )
+    .await;
+    server.abort();
+    let error = turn
+        .error
+        .expect("headers alone do not satisfy the idle bound");
+    assert!(matches!(error, ProviderError::IdleTimeout(_)), "{error:?}");
+    assert!(
+        error.to_string().contains("Raise timeout_seconds"),
+        "{error}"
+    );
+    assert_eq!(error.kind(), ProviderErrorKind::Network);
+    assert!(!biorouter::agents::mistakes::is_recoverable(&error));
+    assert_eq!(requests.load(Ordering::SeqCst), 1, "sent once");
+}
+
 // ---------------------------------------------------------------------------
 // Through the agent: what the person reads, and what the model is sent next.
 // ---------------------------------------------------------------------------

From 4f950d98aae318093a1ed7589f2aaaa47404d16b Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 16:47:00 -0700
Subject: [PATCH 22/26] fix(ollama): retain timeout causes and notice malformed
 text calls

---
 .../src/providers/formats/text_tool_calls.rs  |  74 ++++++++++-
 crates/biorouter/src/providers/ollama.rs      |   6 +-
 .../qwen-malformed-call.txt                   |   3 +
 .../tests/ollama_diagnostics_20261006_2.rs    | 116 ++++++++++++++++++
 4 files changed, 197 insertions(+), 2 deletions(-)
 create mode 100644 crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt

diff --git a/crates/biorouter/src/providers/formats/text_tool_calls.rs b/crates/biorouter/src/providers/formats/text_tool_calls.rs
index baa44ea37..0d00e9a36 100644
--- a/crates/biorouter/src/providers/formats/text_tool_calls.rs
+++ b/crates/biorouter/src/providers/formats/text_tool_calls.rs
@@ -658,7 +658,8 @@ pub fn forged_tool_result(text: &str, tools: &[Tool]) -> Option<ForgedResult> {
 /// with no word that nothing had happened. Several blocks are read because a
 /// corrective retry that repeats the call joins a second block to the first.
 pub fn whole_reply_call_names(text: &str) -> Option<Vec<String>> {
-    let trimmed = text.trim();
+    let notice_text = escape_unknown_json_string_escapes(text);
+    let trimmed = notice_text.trim();
     let mut rest = unwrap_tags(trimmed, ATTEMPT_TAGS).unwrap_or(trimmed).trim();
     let mut names = Vec::new();
     while !rest.is_empty() {
@@ -693,6 +694,38 @@ pub fn whole_reply_call_names(text: &str) -> Option<Vec<String>> {
     (!names.is_empty()).then_some(names)
 }
 
+// Models sometimes embed code with JSON-invalid escapes such as `\d` or
+// `\${n}`. Only the notice detector reads this copy; recovery and retry still
+// require the original arguments to be valid JSON.
+fn escape_unknown_json_string_escapes(text: &str) -> Cow<'_, str> {
+    let mut inside_string = false;
+    let mut escaped = false;
+    let mut changed = false;
+    let mut result = String::with_capacity(text.len());
+    for character in text.chars() {
+        if escaped {
+            if !matches!(
+                character,
+                '"' | '\\' | '/' | 'b' | 'f' | 'n' | 'r' | 't' | 'u'
+            ) {
+                result.push('\\');
+                changed = true;
+            }
+            escaped = false;
+        } else if inside_string && character == '\\' {
+            escaped = true;
+        } else if character == '"' {
+            inside_string = !inside_string;
+        }
+        result.push(character);
+    }
+    if changed {
+        Cow::Owned(result)
+    } else {
+        Cow::Borrowed(text)
+    }
+}
+
 /// The name of one call object as written (S1-S3), or `None` when the object
 /// is not call-shaped or names nothing.
 fn written_call_name(value: &Value) -> Option<String> {
@@ -2162,4 +2195,43 @@ mod tests {
             assert_eq!(whole_reply_call_names(text), None, "{text}");
         }
     }
+
+    #[test]
+    fn the_live_qwen_reply_with_invalid_code_escapes_is_noticed_but_never_run() {
+        let text = include_str!(
+            "../../../tests/fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt"
+        );
+        let tools = [tool("agent_drafter__create_app", json!({"type": "object"}))];
+        assert_eq!(
+            whole_reply_call_names(text),
+            Some(vec!["agent_drafter__create_app".to_string()])
+        );
+        assert_eq!(recover(text, &tools, Tiers::WholeMessage), None);
+        assert_eq!(attempted_calls(text, &tools), None);
+    }
+
+    #[test]
+    fn noticing_invalid_string_escapes_still_requires_a_whole_call_envelope() {
+        let call = r#"{"name": "shell", "arguments": {"command": "printf '\d'"}}"#;
+        for text in [
+            call.to_string(),
+            format!("```json\n{call}\n```"),
+            format!("[{call}]"),
+            format!("<tool_call>{call}</tool_call>"),
+        ] {
+            assert_eq!(whole_reply_call_names(&text), Some(vec!["shell".into()]));
+        }
+        for text in [
+            format!("Here is an example:\n{call}"),
+            format!("{call}\nThis is code for you to run."),
+            format!("```python\n{call}\n```"),
+            r#"{"name": "regex example", "pattern": "\d"}"#.to_string(),
+            r#"{"name": "shell", "arguments": {"command": "printf '\d'"}, "note": "example"}"#
+                .to_string(),
+            format!("{call}\n{{\"count\": 3}}"),
+            r#"{"name": "shell", "arguments": {"command": "\uZZZZ"}}"#.to_string(),
+        ] {
+            assert_eq!(whole_reply_call_names(&text), None, "{text}");
+        }
+    }
 }
diff --git a/crates/biorouter/src/providers/ollama.rs b/crates/biorouter/src/providers/ollama.rs
index 4fa3dc410..6d063af2f 100644
--- a/crates/biorouter/src/providers/ollama.rs
+++ b/crates/biorouter/src/providers/ollama.rs
@@ -72,7 +72,7 @@ use std::io;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::{Arc, LazyLock, Mutex};
 use std::time::Duration;
-use tokio_util::codec::{FramedRead, LinesCodec};
+use tokio_util::codec::{FramedRead, LinesCodec, LinesCodecError};
 use tokio_util::io::StreamReader;
 use url::Url;
 
@@ -1434,6 +1434,10 @@ fn provider_error(
     if error.chain().any(|cause| {
         cause
             .downcast_ref::<reqwest::Error>()
+            .or_else(|| match cause.downcast_ref::<LinesCodecError>()? {
+                LinesCodecError::Io(error) => error.get_ref()?.downcast_ref::<reqwest::Error>(),
+                _ => None,
+            })
             .is_some_and(reqwest::Error::is_timeout)
     }) {
         return waited_too_long(
diff --git a/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt b/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt
new file mode 100644
index 000000000..f8a9ff06a
--- /dev/null
+++ b/crates/biorouter/tests/fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt
@@ -0,0 +1,3 @@
+```json
+{"name": "agent_drafter__create_app", "arguments": {"title": "Factorial Calculator", "description": "Calculate the factorial of a number using a Python script", "archetype": "explorer", "src/main.ts": "import { createApp } from \"./sdk\";\n\nconst br = createApp({ autoChat: false });\n\nbr.actions.register(\"calculate_factorial\", async (n) => {\n  const response = await fetch(\"http://localhost:8000/factorial?n=\${n}\");\n  const result = await response.text();\n  return result;\n});\n\nbr.on(\"message\", async (e) => {\n  if (e.type === \"message\") {\n    const { content } = e;\n    const match = content.match(/calculate factorial (\d+)/);\n    if (match) {\n      const n = parseInt(match[1], 10);\n      const result = await br.call(\"calculate_factorial\", n);\n      await br.run(`Factorial of ${n} is ${result}`, \"#result\");\n    }\n  }\n});", "system_prompt": "You are a calculator that can compute the factorial of a number using a Python script. Respond to user messages by calculating the factorial and displaying the result.", "greeting": "Welcome to the Factorial Calculator! Enter 'calculate factorial n' to get the factorial of n.", "model": "qwen2_5-coder-7b", "extensions": [], "skills": [], "knowledge_base": [], "capabilities": {"data_sources": []}, "guardrails": [], "reliability": [], "orchestration": {}, "output_type": "json"}}
+```
\ No newline at end of file
diff --git a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
index 5eb0abb19..3f11e6c0c 100644
--- a/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
+++ b/crates/biorouter/tests/ollama_diagnostics_20261006_2.rs
@@ -909,3 +909,119 @@ async fn the_agent_tells_the_person_nothing_ran_and_keeps_it_from_the_model() {
     .to_string();
     assert!(!wire.contains("Nothing ran"), "{wire}");
 }
+
+#[tokio::test]
+async fn the_live_malformed_qwen_reply_gets_a_user_only_notice_without_dispatch() {
+    use biorouter::agents::extension::ExtensionConfig;
+    use biorouter::agents::{Agent, AgentConfig, AgentEvent, SessionConfig};
+
+    let text = include_str!("fixtures/ollama/diagnostics_20261006_2/qwen-malformed-call.txt");
+    let (server, provider) = serve_replies(
+        "llama3.1:8b",
+        &[
+            (200, text_body(text, 31_000, 30_500)),
+            (200, text_body("ok", 31_000, 30_500)),
+        ],
+    )
+    .await;
+    let work = tempfile::TempDir::new().unwrap();
+    let data = tempfile::TempDir::new().unwrap();
+    let permissions = tempfile::TempDir::new().unwrap();
+    let manager = std::sync::Arc::new(biorouter::session::SessionManager::new(
+        data.path().to_path_buf(),
+    ));
+    let agent = Agent::with_config(AgentConfig::new(
+        manager.clone(),
+        std::sync::Arc::new(biorouter::config::permission::PermissionManager::new(
+            permissions.path().to_path_buf(),
+        )),
+        None,
+        biorouter::config::BioRouterMode::Auto,
+    ));
+    let session = manager
+        .create_session(
+            work.path().to_path_buf(),
+            "synthetic malformed qwen replay".to_string(),
+            biorouter::session::session_manager::SessionType::Hidden,
+        )
+        .await
+        .unwrap();
+    agent
+        .update_provider(std::sync::Arc::new(provider), &session.id)
+        .await
+        .unwrap();
+    agent
+        .add_extension(ExtensionConfig::Frontend {
+            name: "notes".to_string(),
+            description: "Read synthetic notes".to_string(),
+            tools: vec![tool("notes__read", json!({"type": "object"}))],
+            instructions: None,
+            bundled: None,
+            available_tools: Vec::new(),
+        })
+        .await
+        .unwrap();
+    let mut shown = Vec::new();
+    for user in ["count urine in the synthetic notes", "thanks"] {
+        let stream = agent
+            .reply(
+                Message::user().with_text(user),
+                SessionConfig {
+                    id: session.id.clone(),
+                    schedule_id: None,
+                    max_turns: Some(3),
+                    max_tool_calls: Some(3),
+                    budget: None,
+                    retry_config: None,
+                    reasoning_effort: None,
+                },
+                None,
+            )
+            .await
+            .unwrap();
+        tokio::pin!(stream);
+        tokio::time::timeout(std::time::Duration::from_secs(30), async {
+            while let Some(event) = stream.next().await {
+                if let AgentEvent::Message(message) = event.unwrap() {
+                    shown.push(message);
+                }
+            }
+        })
+        .await
+        .expect("a bounded fixture replay");
+    }
+    assert!(shown.iter().any(|message| message.as_concat_text() == text));
+    assert!(shown
+        .iter()
+        .all(|message| message.content.iter().all(|content| !matches!(
+            content,
+            MessageContent::ToolRequest(_) | MessageContent::FrontendToolRequest(_)
+        ))));
+    let notices: Vec<_> = shown
+        .iter()
+        .filter(|message| is_unrun_call_notice(message))
+        .collect();
+    assert_eq!(notices.len(), 1, "{shown:?}");
+    assert!(notices[0].is_user_visible() && !notices[0].is_agent_visible());
+    let MessageContent::SystemNotification(note) = &notices[0].content[0] else {
+        unreachable!()
+    };
+    assert!(note.msg.contains("'agent_drafter__create_app'"));
+    let stored = manager
+        .get_session(&session.id, true)
+        .await
+        .unwrap()
+        .conversation
+        .unwrap();
+    let stored_notice = stored
+        .iter()
+        .find(|message| is_unrun_call_notice(message))
+        .expect("the notice remains after reload");
+    assert!(stored_notice.is_user_visible() && !stored_notice.is_agent_visible());
+    let requests = chat_requests(&server).await;
+    assert_eq!(requests.len(), 2, "no corrective retry or tool dispatch");
+    assert!(!requests[1].to_string().contains("Nothing ran"));
+    assert!(requests[1]
+        .to_string()
+        .contains("agent_drafter__create_app"));
+}

From d2edbb4ad288db46211156fd18d1e65c96bf561f Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 17:16:40 -0700
Subject: [PATCH 23/26] feat(apps): reuse verified service and check pages by
 default

---
 biorouter-self-test.yaml                      |   2 +-
 .../biorouter-mcp/src/agent_drafter/bundle.rs | 143 +++-
 .../biorouter-mcp/src/agent_drafter/export.rs |  34 +
 crates/biorouter-mcp/src/agent_drafter/mod.rs | 222 +++++-
 .../src/agent_drafter/page_check.rs           | 435 ++++++++++
 .../biorouter-mcp/src/agent_drafter/render.rs | 744 +++++++++++++++++-
 docs/apps-sdk/sdk-reference.md                |  14 +-
 7 files changed, 1541 insertions(+), 53 deletions(-)
 create mode 100644 crates/biorouter-mcp/src/agent_drafter/page_check.rs

diff --git a/biorouter-self-test.yaml b/biorouter-self-test.yaml
index 9bef2ff5a..7bee9bbd0 100644
--- a/biorouter-self-test.yaml
+++ b/biorouter-self-test.yaml
@@ -689,7 +689,7 @@ prompt: |
   1. Call `agent_drafter__list_apps`. If that exact app id already exists or matches the preview id `{{ preview_app_id }}`, stop this phase and report the collision without modifying any app. Do not overwrite, reuse, or remove a prior run's app.
   2. Call `create_app` with that id, kind `agentic`, archetype `dashboard`, a concise title and description, and a system prompt that updates dashboard metrics through the declared action.
   3. Call `read_app` and verify the resolved manifest has the dashboard state schema, `set_metric` action, `refresh_requested` signal, and nonblank `surface.state_initial` metric labels. Missing measurements must be explicitly unavailable, not invented zero values. Keep declared initial state as the source of first-load values; do not add duplicate imperative initialization to work around the smoke harness.
-  4. Call `build_app`; require a successful bundle.
+  4. Call `build_app`; require a successful bundle and a passing default browser-free page check. This checks page files and JavaScript structure; it does not establish browser execution. A quality-check error must fail the build rather than produce a success card.
   5. Call `build_app` with `check_only: true`; require zero ERROR findings.
   6. Call `smoke_app`; require the real-browser harness to execute successfully. A missing browser or skipped execution is a failure, not a pass.
   7. Record setup, manifest assertions, build output, lint output, and smoke output in {{ workspace_dir }}/phase2b_apps.md.
diff --git a/crates/biorouter-mcp/src/agent_drafter/bundle.rs b/crates/biorouter-mcp/src/agent_drafter/bundle.rs
index 5f22a4902..d44f146c1 100644
--- a/crates/biorouter-mcp/src/agent_drafter/bundle.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/bundle.rs
@@ -81,6 +81,11 @@ pub fn lint_app(project_dir: &Path) -> Vec<LintFinding> {
     let manifest: Option<Manifest> = std::fs::read_to_string(project_dir.join("manifest.json"))
         .ok()
         .and_then(|s| serde_json::from_str(&s).ok());
+    out.extend(super::page_check::findings(
+        project_dir,
+        manifest.as_ref().map_or("index.html", |m| m.entry.as_str()),
+        true,
+    ));
     let is_agentic = manifest
         .as_ref()
         .is_none_or(|manifest| manifest.kind == ArtifactKind::Agentic);
@@ -934,7 +939,7 @@ pub fn format_lint(findings: &[LintFinding]) -> String {
         s.push_str(&format!("  {tag}: {}\n", f.msg));
     }
     if findings.iter().any(|f| f.level == LintLevel::Error) {
-        s.push_str("Fix the ERRORs (they break backend access or portability), then rebuild.");
+        s.push_str("Fix the ERRORs, then rebuild.");
     }
     s
 }
@@ -958,7 +963,7 @@ pub struct BuildReport {
 }
 
 impl BuildReport {
-    fn not_built(used: &str, log: impl Into<String>) -> Self {
+    pub(super) fn not_built(used: &str, log: impl Into<String>) -> Self {
         Self {
             ok: false,
             used: used.to_string(),
@@ -1741,6 +1746,15 @@ impl BundleMaking<'_> {
             let staging = Staging::new(&dist)?;
             match run_esbuild(&cmd, &entry, &staging.0.join("app.js")) {
                 Ok(mut report) if report.ok => {
+                    let js = std::fs::read_to_string(staging.0.join("app.js"))?;
+                    if let Some(finding) =
+                        super::page_check::javascript_error(&js, "dist/app.js", false)
+                    {
+                        return Ok(BuildReport::not_built("esbuild", finding.msg));
+                    }
+                    if let Some(error) = staged_page_error(self.project_dir, &staging.0, true) {
+                        return Ok(BuildReport::not_built("esbuild", error));
+                    }
                     let banner = BundleBanner {
                         builder: "esbuild".into(),
                         sdk: self.sdk.clone(),
@@ -1782,6 +1796,23 @@ impl BundleMaking<'_> {
     }
 }
 
+fn staged_page_error(project_dir: &Path, staging: &Path, replaces_css: bool) -> Option<String> {
+    let manifest: Option<Manifest> = std::fs::read_to_string(project_dir.join("manifest.json"))
+        .ok()
+        .and_then(|s| serde_json::from_str(&s).ok());
+    if manifest.is_none() && !project_dir.join("index.html").is_file() {
+        return None;
+    }
+    let entry = manifest.as_ref().map_or("index.html", |m| m.entry.as_str());
+    let findings = super::page_check::staged_findings(project_dir, entry, staging, replaces_css);
+    (!findings.is_empty()).then(|| {
+        format!(
+            "Browser-free page check failed:\n{}",
+            format_lint(&findings)
+        )
+    })
+}
+
 /// A fresh hidden directory in `dist/` for esbuild to write into, removed when
 /// dropped.
 ///
@@ -2186,6 +2217,16 @@ fn fallback_bundle(
         strip_module_syntax(&sdk_source),
         strip_module_syntax(main)
     );
+    if let Some(finding) =
+        super::page_check::javascript_error(&js, "dist/app.js fallback output", false)
+    {
+        return Ok(BuildReport::not_built("fallback", format!("The fallback bundler's output does not parse, so it was not installed:\n{}\n{FALLBACK_NEEDS_ESBUILD}", finding.msg)));
+    }
+    let staging = Staging::new(out.parent().unwrap_or(project_dir))?;
+    write_atomic(&staging.0.join("app.js"), js.as_bytes())?;
+    if let Some(error) = staged_page_error(project_dir, &staging.0, false) {
+        return Ok(BuildReport::not_built("fallback", error));
+    }
     let verified = match node_check(&js, out.parent().unwrap_or(project_dir)) {
         Ok(None) => "It passed `node --check`.",
         Ok(Some(error)) => {
@@ -3035,6 +3076,104 @@ mod tests {
         assert_eq!(names, vec!["app.js".to_string()]);
     }
 
+    #[test]
+    #[cfg(unix)]
+    fn a_page_check_failure_keeps_the_previous_javascript_and_stylesheet() {
+        let dir = TempDir::new().unwrap();
+        std::fs::create_dir_all(dir.path().join("src")).unwrap();
+        std::fs::write(
+            dir.path().join("src/main.ts"),
+            "document.body.dataset.ready = 'new';",
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join("index.html"),
+            r#"<link rel="stylesheet" href="dist/app.css"><p>App</p>"#,
+        )
+        .unwrap();
+        let dist = dir.path().join("dist");
+        std::fs::create_dir(&dist).unwrap();
+        std::fs::write(dist.join("app.js"), "old();\n").unwrap();
+        std::fs::write(dist.join("app.css"), "body{color:red}\n").unwrap();
+        let make = || BundleMaking {
+            project_dir: dir.path(),
+            main: "document.body.dataset.ready = 'new';",
+            includes_sdk: false,
+            sdk: "none".into(),
+            sdk_version: None,
+        };
+        let compiler = || {
+            EsbuildCommand {
+            program: "/bin/sh".into(),
+            lead: vec!["-c".into(), r#"for arg in "$@"; do case "$arg" in --outfile=*) printf 'updated();\n' > "${arg#--outfile=}";; esac; done"#.into(), "fixture-compiler".into()],
+            child_path: None,
+            source: "fixture",
+        }
+        };
+        let failed = make().build(Some(compiler())).unwrap();
+        assert!(
+            !failed.ok && failed.log.contains("dist/app.css"),
+            "{}",
+            failed.log
+        );
+        assert_eq!(
+            std::fs::read_to_string(dist.join("app.js")).unwrap(),
+            "old();\n"
+        );
+        assert_eq!(
+            std::fs::read_to_string(dist.join("app.css")).unwrap(),
+            "body{color:red}\n"
+        );
+        std::fs::write(dir.path().join("index.html"), "<p>No stylesheet needed</p>").unwrap();
+        assert!(make().build(Some(compiler())).unwrap().ok);
+        assert!(!dist.join("app.css").exists());
+    }
+
+    #[test]
+    fn a_failed_fallback_page_check_does_not_replace_its_previous_bundle() {
+        let dir = project(None, "document.body.dataset.ready = 'old';\n");
+        let first = fallback_of(&dir);
+        assert!(first.ok, "{}", first.log);
+        let old = std::fs::read_to_string(dir.path().join("dist/app.js")).unwrap();
+        std::fs::write(dir.path().join("dist/app.css"), "body{color:red}\n").unwrap();
+        std::fs::write(
+            dir.path().join("index.html"),
+            r#"<link rel="stylesheet" href="dist/app.css"><script src="assets/missing.js"></script><p>App</p>"#,
+        )
+        .unwrap();
+        std::fs::write(
+            dir.path().join("src/main.ts"),
+            "document.body.dataset.ready = 'new';\n",
+        )
+        .unwrap();
+        let report = fallback_of(&dir);
+        assert!(
+            !report.ok && report.log.contains("assets/missing.js"),
+            "{}",
+            report.log
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("dist/app.js")).unwrap(),
+            old
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("dist/app.css")).unwrap(),
+            "body{color:red}\n"
+        );
+        std::fs::create_dir(dir.path().join("assets")).unwrap();
+        std::fs::write(dir.path().join("assets/missing.js"), "const value = 1;").unwrap();
+        let fixed = fallback_of(&dir);
+        assert!(fixed.ok, "{}", fixed.log);
+        assert_ne!(
+            std::fs::read_to_string(dir.path().join("dist/app.js")).unwrap(),
+            old
+        );
+        assert_eq!(
+            std::fs::read_to_string(dir.path().join("dist/app.css")).unwrap(),
+            "body{color:red}\n"
+        );
+    }
+
     /// ⚠ esbuild used to write straight to a hidden temp outfile, and it puts
     /// an imported stylesheet beside the outfile with the extension swapped, so
     /// `dist/app.css` was never written and hidden `.css` files piled up. Needs
diff --git a/crates/biorouter-mcp/src/agent_drafter/export.rs b/crates/biorouter-mcp/src/agent_drafter/export.rs
index b72090472..805ae6c38 100644
--- a/crates/biorouter-mcp/src/agent_drafter/export.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/export.rs
@@ -693,6 +693,12 @@ fn prepare(
     // races a page load's build, and a build that failed on these very inputs
     // is not run again.
     match super::ensure_bundle_fresh(&store, id) {
+        Ok(super::BundleCheck {
+            quality_error: Some(error),
+            ..
+        }) => {
+            return Err(ExportError::Unexportable(error));
+        }
         Ok(check) if check.build.as_ref().is_some_and(|build| !build.ok) => {
             report.notes.push(if check.has_bundle {
                 "the app's bundle could not be rebuilt; the export carries the last one that \
@@ -2287,6 +2293,34 @@ mod tests {
         PathBuf::from(&report.target)
     }
 
+    #[test]
+    fn a_broken_page_is_not_exported_even_with_the_lint_override() {
+        let f = fixture();
+        let app = f.app("broken-page", ArtifactKind::Static);
+        std::fs::write(
+            app.join("index.html"),
+            "<html><body><script>const value = ;</script></body></html>",
+        )
+        .unwrap();
+
+        let error = f
+            .export(
+                "broken-page",
+                &ExportRequest {
+                    allow_lint_errors: true,
+                    ..Default::default()
+                },
+            )
+            .unwrap_err();
+        assert!(matches!(error, ExportError::Unexportable(_)), "{error}");
+        assert!(error.to_string().contains("index.html"), "{error}");
+        assert_eq!(std::fs::read_dir(&f.work).unwrap().count(), 0);
+
+        let error = legacy_export_map(&f.store_root, "broken-page").unwrap_err();
+        assert!(matches!(error, ExportError::Unexportable(_)), "{error}");
+        assert!(error.to_string().contains("index.html"), "{error}");
+    }
+
     #[test]
     fn binary_assets_round_trip_byte_identical_and_runtime_data_stays_home() {
         let f = fixture();
diff --git a/crates/biorouter-mcp/src/agent_drafter/mod.rs b/crates/biorouter-mcp/src/agent_drafter/mod.rs
index 505905b5a..b67ed8ea0 100644
--- a/crates/biorouter-mcp/src/agent_drafter/mod.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/mod.rs
@@ -21,6 +21,7 @@ pub mod declare;
 pub mod evidence;
 pub mod export;
 pub mod manifest;
+mod page_check;
 pub mod render;
 pub mod resolved;
 pub mod store;
@@ -1463,6 +1464,7 @@ fn build_inputs_fingerprint(dir: &Path, manifest: &Manifest) -> u64 {
         .hash(&mut h);
     manifest.built_at.hash(&mut h);
     manifest.sdk_hash.hash(&mut h);
+    page_check::inputs_fingerprint(dir, &manifest.entry).hash(&mut h);
     bundle::sdk_fingerprint().hash(&mut h);
     bundle::esbuild_available().hash(&mut h);
     h.finish()
@@ -1490,6 +1492,36 @@ fn build_and_stamp_locked(
     id: &str,
     dir: &Path,
 ) -> std::io::Result<bundle::BuildReport> {
+    let manifest = store.load_manifest(id)?;
+    let findings = page_check::findings(dir, &manifest.entry, true);
+    if !findings.is_empty() {
+        return Ok(bundle::BuildReport::not_built(
+            "none",
+            format!(
+                "Browser-free page check failed:\n{}",
+                bundle::format_lint(&findings)
+            ),
+        ));
+    }
+    if manifest.kind == ArtifactKind::Static && !dir.join("src/main.ts").is_file() {
+        let findings = page_check::findings(dir, &manifest.entry, false);
+        return Ok(if findings.is_empty() {
+            bundle::BuildReport {
+                ok: true,
+                used: "none".into(),
+                log: page_check::PASSED.into(),
+                stamp: None,
+            }
+        } else {
+            bundle::BuildReport::not_built(
+                "none",
+                format!(
+                    "Browser-free page check failed:\n{}",
+                    bundle::format_lint(&findings)
+                ),
+            )
+        });
+    }
     // Keep a vendored SDK that a NEWER Biorouter put there: its bundle's banner
     // names that version and the very SDK the app still vendors. Refreshing it
     // would rebuild the app down to this binary's older runtime. The version
@@ -1511,6 +1543,20 @@ fn build_and_stamp_locked(
             keep_sdk_from: keep_sdk_from.clone(),
         },
     )?;
+    if report.ok {
+        let findings = page_check::findings(dir, &manifest.entry, false);
+        if findings.is_empty() {
+            report.log = format!("{}\n{}", report.log, page_check::PASSED);
+        } else {
+            report.ok = false;
+            report.stamp = None;
+            report.log = format!(
+                "Browser-free page check failed:\n{}\n{}",
+                bundle::format_lint(&findings),
+                report.log
+            );
+        }
+    }
     if let Some(kept) = keep_sdk_from {
         report.log = format!(
             "Kept src/sdk.ts: it is the App SDK of Biorouter {kept}, which is newer than this one ({}).\n{}",
@@ -1546,6 +1592,8 @@ pub fn rebuild_and_stamp(store: &ArtifactStore, id: &str) -> std::io::Result<bun
 /// What [`ensure_bundle_fresh`] found, and did.
 #[derive(Debug, Clone)]
 pub struct BundleCheck {
+    /// A proven page defect, independent of advisory/source lint findings.
+    pub quality_error: Option<String>,
     /// Why the bundle was stale, `None` when it was fresh.
     pub stale_because: Option<&'static str>,
     /// The build that ran — or the remembered result of an identical earlier
@@ -1564,6 +1612,9 @@ impl BundleCheck {
     /// The failed build behind a missing bundle, when that is the situation:
     /// the app needs a bundle, has none, and the build said why.
     pub fn missing_bundle_log(&self) -> Option<String> {
+        if let Some(error) = &self.quality_error {
+            return Some(error.clone());
+        }
         if !self.needs_bundle || self.has_bundle {
             return None;
         }
@@ -1609,7 +1660,15 @@ pub fn ensure_bundle_fresh(store: &ArtifactStore, id: &str) -> std::io::Result<B
                 }
             }
         };
+        let findings = page_check::findings(&dir, &manifest.entry, false);
+        let quality_error = (!findings.is_empty()).then(|| {
+            format!(
+                "Browser-free page check failed:\n{}",
+                bundle::format_lint(&findings)
+            )
+        });
         Ok(BundleCheck {
+            quality_error,
             stale_because,
             build,
             remembered,
@@ -2608,6 +2667,18 @@ impl AgentDrafterServer {
         if p.check_only.unwrap_or(false) {
             return self.lint_app(Parameters(AppIdParams { id: p.id })).await;
         }
+        let app_dir = store.artifact_dir(&p.id).map_err(internal)?;
+        let lint = bundle::lint_app(&app_dir);
+        if lint.iter().any(|f| f.level == bundle::LintLevel::Error) {
+            return Err(err(
+                ErrorCode::INTERNAL_ERROR,
+                format!(
+                    "harness ERRORs block build for '{}':\n{}",
+                    p.id,
+                    bundle::format_lint(&lint)
+                ),
+            ));
+        }
         let store2 = store.clone();
         let id2 = p.id.clone();
         let report = tokio::task::spawn_blocking(move || rebuild_and_stamp(&store2, &id2))
@@ -2632,14 +2703,17 @@ impl AgentDrafterServer {
             } else {
                 ""
             };
+            let outcome = if report.used == "none" {
+                format!("Checked '{}' (no TypeScript bundle needed).", p.id)
+            } else {
+                format!("Built '{}' with {} → dist/app.js.", p.id, report.used)
+            };
             // A fresh bundle is a new visible state: show the rebuilt app, don't
             // just tell the user it compiled.
             Ok(CallToolResult::success(vec![
                 self.card_content(&manifest)?,
                 Content::text(format!(
-                    "Built '{}' with {} → dist/app.js.{fallback_warning}\n{}\n\n{}",
-                    p.id,
-                    report.used,
+                    "{outcome}{fallback_warning}\n{}\n\n{}",
                     bundle::format_lint(&lint),
                     report.log
                 ))
@@ -2701,6 +2775,9 @@ impl AgentDrafterServer {
             .await
             .map_err(internal)?
             .map_err(internal)?;
+        if let Some(error) = check.quality_error.as_ref() {
+            return Err(err(ErrorCode::INTERNAL_ERROR, error.clone()));
+        }
         // A failed rebuild blocks the launch only when there is nothing to
         // serve. With an earlier bundle on disk the daemon serves that one, as
         // `serve_index` does, so the address works and the agent is told that
@@ -2760,7 +2837,7 @@ impl AgentDrafterServer {
         let mut content = vec![Content::resource_link(link).with_audience(vec![Role::User])];
         content.push(
             Content::text(format!(
-                "App '{}' is ready at {}{build_warning}\n(A browser can open this address only through a one-time launch link: the user opens the app from its preview in this chat or with \"Launch in browser\" in Applications. Pasted on its own, the address answers \"Open this app from Biorouter\". In a terminal, run `biorouter apps open {}`.)",
+                "App '{}' can be opened at {}{build_warning}\nBrowser-free page check passed; runtime behavior was not verified.\n(A browser can open this address only through a one-time launch link: the user opens the app from its preview in this chat or with \"Launch in browser\" in Applications. Pasted on its own, the address answers \"Open this app from Biorouter\". In a terminal, run `biorouter apps open {}`.)",
                 manifest.id, browser_url, manifest.id
             ))
             .with_audience(vec![Role::Assistant]),
@@ -4290,7 +4367,7 @@ run.addEventListener("click", async () => {
     }
 
     #[tokio::test]
-    async fn harness_errors_block_launch_and_export() {
+    async fn harness_errors_block_build_launch_and_export() {
         let (_d, s) = server();
         let mut p = create("Broken Harness", None);
         p.html = Some(
@@ -4315,8 +4392,8 @@ br.run("hello", "#missing");
                 check_only: None,
             }))
             .await
-            .unwrap();
-        let build_text = text_of(&build);
+            .unwrap_err();
+        let build_text = build.message;
         assert!(build_text.contains("ERROR"));
         assert!(build_text.contains("#missing"));
 
@@ -4404,6 +4481,7 @@ br.run("hello", "#missing");
             .await
             .unwrap();
         assert!(text_of(&res).contains("dist/app.js"));
+        assert!(text_of(&res).contains(page_check::PASSED));
         assert!(s.store().file_exists("launchy", "dist/app.js"));
         assert!(s
             .store()
@@ -4419,6 +4497,136 @@ br.run("hello", "#missing");
             .await
             .unwrap();
         assert!(text_of(&res).contains("/apps/launchy/"));
+        assert!(text_of(&res).contains("runtime behavior was not verified"));
+    }
+
+    #[tokio::test]
+    async fn browser_free_checks_block_broken_static_pages_without_a_bundler() {
+        let (_d, s) = server();
+        let mut p = create("Broken static", Some("static"));
+        p.html = Some("<p>Page</p><script>const value = ;</script>".into());
+        s.create_app_inner(p, None, &KbCaller::restricted())
+            .await
+            .unwrap();
+        let check = ensure_bundle_fresh(&s.store(), "broken-static").unwrap();
+        assert!(!check.needs_bundle && check.build.is_none());
+        assert!(check.quality_error.as_ref().unwrap().contains("index.html"));
+        assert_eq!(check.missing_bundle_log(), check.quality_error);
+        let build = s
+            .build_app(Parameters(BuildAppParams {
+                id: "broken-static".into(),
+                check_only: None,
+            }))
+            .await
+            .unwrap_err();
+        assert!(build.message.contains("index.html"));
+        let launch = s
+            .launch_app(Parameters(AppIdParams {
+                id: "broken-static".into(),
+            }))
+            .await
+            .unwrap_err();
+        assert!(launch.message.contains("invalid browser JavaScript"));
+        assert!(s
+            .store()
+            .load_manifest("broken-static")
+            .unwrap()
+            .built_at
+            .is_none());
+    }
+
+    #[tokio::test]
+    async fn browser_free_checks_allow_static_pages_with_advisory_lint_warnings() {
+        let (_d, s) = server();
+        let mut p = create("Checked static", Some("static"));
+        p.html = Some("<p style=\"color:red\">Static content</p>".into());
+        s.create_app_inner(p, None, &KbCaller::restricted())
+            .await
+            .unwrap();
+        let findings = bundle::lint_app(&s.store().artifact_dir("checked-static").unwrap());
+        assert!(findings.iter().any(|f| f.level == bundle::LintLevel::Warn));
+        assert!(!findings.iter().any(|f| f.level == bundle::LintLevel::Error));
+        let result = s
+            .build_app(Parameters(BuildAppParams {
+                id: "checked-static".into(),
+                check_only: None,
+            }))
+            .await
+            .unwrap();
+        assert!(text_of(&result).contains("no TypeScript bundle needed"));
+        assert!(text_of(&result).contains(page_check::PASSED));
+        assert!(!s.store().file_exists("checked-static", "dist/app.js"));
+        assert!(s
+            .launch_app(Parameters(AppIdParams {
+                id: "checked-static".into()
+            }))
+            .await
+            .is_ok());
+    }
+
+    #[test]
+    fn page_edits_retry_a_failed_build_and_preserve_the_previous_bundle() {
+        bundle::tests_without_esbuild::run(|| {
+            let (_d, store) = agentic_app("page-fix", DEFAULT_MAIN);
+            let first = rebuild_and_stamp(&store, "page-fix").unwrap();
+            assert!(first.ok, "{}", first.log);
+            let original = store.read_file("page-fix", "dist/app.js").unwrap();
+            store
+                .write_file("page-fix", "index.html", "<script>const x = ;</script>")
+                .unwrap();
+            let broken = ensure_bundle_fresh(&store, "page-fix").unwrap();
+            assert!(broken.quality_error.is_some());
+            assert_eq!(
+                store.read_file("page-fix", "dist/app.js").unwrap(),
+                original
+            );
+            store
+                .write_file("page-fix", "index.html", "<p>Fixed page</p>")
+                .unwrap();
+            let fixed = ensure_bundle_fresh(&store, "page-fix").unwrap();
+            assert!(fixed.quality_error.is_none());
+            assert!(fixed.missing_bundle_log().is_none());
+
+            store
+                .write_file(
+                    "page-fix",
+                    "src/main.ts",
+                    "import { createApp } from \"./sdk\";\ncreateApp();\n",
+                )
+                .unwrap();
+            store
+                .write_file(
+                    "page-fix",
+                    "index.html",
+                    "<script src=\"assets/helper.js\"></script>",
+                )
+                .unwrap();
+            let missing = ensure_bundle_fresh(&store, "page-fix").unwrap();
+            assert!(missing.build.as_ref().is_some_and(|b| !b.ok));
+            store
+                .write_file("page-fix", "assets/helper.js", "const value = 1;")
+                .unwrap();
+            let added = ensure_bundle_fresh(&store, "page-fix").unwrap();
+            assert!(!added.remembered);
+            assert!(added.build.as_ref().is_some_and(|b| b.ok), "{added:?}");
+        });
+    }
+
+    #[test]
+    fn a_corrupted_fresh_bundle_is_blocked_without_rebuilding_it() {
+        let (_d, store) = agentic_app("corrupt", DEFAULT_MAIN);
+        fake_bundle(&store, "corrupt", "esbuild", bundle::biorouter_version());
+        store
+            .write_file("corrupt", "dist/app.js", "(()=>{const value = ;")
+            .unwrap();
+        let check = ensure_bundle_fresh(&store, "corrupt").unwrap();
+        assert!(check.build.is_none());
+        assert!(check
+            .quality_error
+            .as_ref()
+            .unwrap()
+            .contains("dist/app.js"));
+        assert_eq!(check.missing_bundle_log(), check.quality_error);
     }
 
     // --- build freshness, the build lock, and what a build is stamped with ---
diff --git a/crates/biorouter-mcp/src/agent_drafter/page_check.rs b/crates/biorouter-mcp/src/agent_drafter/page_check.rs
new file mode 100644
index 000000000..6a7ac3fa9
--- /dev/null
+++ b/crates/biorouter-mcp/src/agent_drafter/page_check.rs
@@ -0,0 +1,435 @@
+use std::collections::HashSet;
+use std::hash::{Hash, Hasher};
+use std::io::{self, Read};
+use std::path::{Path, PathBuf};
+
+use super::bundle::{LintFinding, LintLevel};
+use super::render::{is_handler_name, scan_tags, script_is_executable, Tag, TagAttr};
+
+pub(super) const PASSED: &str = "Browser-free page check passed: entry, local scripts/styles and JavaScript structure checked. Runtime behavior was not verified.";
+const MAX_SOURCE_BYTES: u64 = 16 * 1024 * 1024;
+
+fn error(msg: impl Into<String>) -> LintFinding {
+    LintFinding {
+        level: LintLevel::Error,
+        msg: msg.into(),
+    }
+}
+
+fn read_source(root: &Path, path: &Path) -> io::Result<String> {
+    let canonical = path.canonicalize()?;
+    if !canonical.starts_with(root.canonicalize()?) {
+        return Err(io::Error::other("the file is outside the app directory"));
+    }
+    if !canonical.metadata()?.is_file() {
+        return Err(io::Error::other("the path is not a regular source file"));
+    }
+    let mut source = String::new();
+    std::fs::File::open(canonical)?
+        .take(MAX_SOURCE_BYTES + 1)
+        .read_to_string(&mut source)?;
+    if source.len() as u64 > MAX_SOURCE_BYTES {
+        return Err(io::Error::other(
+            "the source exceeds the 16 MiB check limit",
+        ));
+    }
+    Ok(source)
+}
+
+fn attr<'a>(attrs: &'a [TagAttr], key: &str) -> Option<&'a str> {
+    attrs
+        .iter()
+        .find(|a| !a.duplicate && a.key == key)
+        .map(|a| a.value.as_str())
+}
+
+/// Resolve against the same app-root base the served page receives. URLs are
+/// parsed, never fetched; canonicalization below also catches encoded traversal.
+fn local_asset(root: &Path, value: &str) -> Result<Option<PathBuf>, String> {
+    let base = url::Url::parse("https://biorouter.invalid/apps/check/").expect("static URL");
+    let value = value.trim();
+    let resolved = base.join(value).map_err(|e| e.to_string())?;
+    if resolved.origin() != base.origin() {
+        return Ok(None);
+    }
+    let relative = resolved.path().strip_prefix(base.path()).ok_or_else(|| {
+        "the URL leaves the app's serving directory; use an app-relative path".to_string()
+    })?;
+    let file_base = url::Url::from_directory_path(root)
+        .map_err(|()| "the app directory is not an absolute path".to_string())?;
+    let decoded = file_base
+        .join(relative)
+        .map_err(|e| e.to_string())?
+        .to_file_path()
+        .map_err(|()| "the URL is not a local file path".to_string())?;
+    let relative = decoded.strip_prefix(root).map_err(|e| e.to_string())?;
+    if !relative.starts_with("assets") && !relative.starts_with("dist") {
+        return Err("the app serves local scripts and styles only from assets/ or dist/; move the file there and update the URL".into());
+    }
+    Ok(Some(decoded))
+}
+
+pub(super) fn inputs_fingerprint(root: &Path, entry: &str) -> u64 {
+    let mut hash = std::collections::hash_map::DefaultHasher::new();
+    if let Ok(html) = read_source(root, &root.join(entry)) {
+        html.hash(&mut hash);
+        scan_tags(&html, |tag| {
+            if let Tag::Start { name, attrs, .. } = tag {
+                let value = match name.as_str() {
+                    "script" => attr(&attrs, "src"),
+                    "link" => attr(&attrs, "href"),
+                    _ => None,
+                };
+                if let Some(Ok(Some(path))) = value.map(|v| local_asset(root, v)) {
+                    path.hash(&mut hash);
+                    let metadata = path
+                        .canonicalize()
+                        .ok()
+                        .filter(|p| root.canonicalize().is_ok_and(|r| p.starts_with(r)))
+                        .and_then(|p| p.metadata().ok());
+                    metadata
+                        .as_ref()
+                        .map(std::fs::Metadata::len)
+                        .hash(&mut hash);
+                    metadata.and_then(|m| m.modified().ok()).hash(&mut hash);
+                }
+            }
+        });
+    }
+    hash.finish()
+}
+
+pub(super) fn javascript_error(source: &str, label: &str, module: bool) -> Option<LintFinding> {
+    let mut parser = tree_sitter::Parser::new();
+    parser
+        .set_language(&tree_sitter_javascript::LANGUAGE.into())
+        .expect("the compiled JavaScript grammar is valid");
+    let Some(tree) = parser.parse(source, None) else {
+        return Some(error(format!(
+            "{label}: JavaScript could not be parsed. Fix the script and rebuild."
+        )));
+    };
+    let mut nodes = vec![tree.root_node()];
+    while let Some(node) = nodes.pop() {
+        let invalid = node.is_error()
+            || node.is_missing()
+            || node.kind().starts_with("jsx_")
+            || (!module && matches!(node.kind(), "import_statement" | "export_statement"));
+        if invalid {
+            let at = node.start_position();
+            return Some(error(format!(
+                "{label}: invalid browser JavaScript near line {}, column {}. Fix the syntax (and use type=\"module\" for imports/exports), then rebuild.",
+                at.row + 1,
+                at.column + 1
+            )));
+        }
+        let mut cursor = node.walk();
+        nodes.extend(node.children(&mut cursor));
+    }
+    None
+}
+
+pub(super) fn findings(root: &Path, entry: &str, building: bool) -> Vec<LintFinding> {
+    findings_with(root, entry, building, None, false)
+}
+
+pub(super) fn staged_findings(
+    root: &Path,
+    entry: &str,
+    staging: &Path,
+    replaces_css: bool,
+) -> Vec<LintFinding> {
+    findings_with(root, entry, false, Some(staging), replaces_css)
+}
+
+fn findings_with(
+    root: &Path,
+    entry: &str,
+    building: bool,
+    staging: Option<&Path>,
+    replaces_css: bool,
+) -> Vec<LintFinding> {
+    let mut out = Vec::new();
+    let html = match read_source(root, &root.join(entry)) {
+        Ok(html) if !html.trim().is_empty() => html,
+        Ok(_) => return vec![error(format!("{entry}: the entry page is empty. Add its HTML before building or launching."))],
+        Err(e) => return vec![error(format!("{entry}: the entry page could not be read ({e}). Restore the file or fix the manifest entry."))],
+    };
+    let mut checked = HashSet::new();
+    let mut bundle_loaded = false;
+    let mut template_depth = 0usize;
+    let mut script_number = 0usize;
+    scan_tags(&html, |tag| {
+        let Tag::Start {
+            name,
+            attrs,
+            script_text,
+        } = tag
+        else {
+            if let Tag::End { name } = tag {
+                if name == "template" {
+                    template_depth = template_depth.saturating_sub(1);
+                }
+            }
+            return;
+        };
+        if name == "template" {
+            template_depth += 1;
+        }
+        if template_depth > 0 {
+            return;
+        }
+        for handler in attrs
+            .iter()
+            .filter(|a| !a.duplicate && is_handler_name(&a.key))
+        {
+            let source = format!("function __handler(event){{\n{}\n}}", handler.value);
+            if let Some(finding) =
+                javascript_error(&source, &format!("{entry} {} handler", handler.key), false)
+            {
+                out.push(finding);
+            }
+        }
+        let mut asset = None;
+        let mut module = false;
+        if name == "script" {
+            let kind = attr(&attrs, "type");
+            if !script_is_executable(kind, attr(&attrs, "language")) {
+                return;
+            }
+            if kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("importmap")) {
+                if let Err(e) =
+                    serde_json::from_str::<serde_json::Value>(script_text.unwrap_or_default())
+                {
+                    out.push(error(format!(
+                        "{entry} importmap: invalid JSON ({e}). Fix the import map before launch."
+                    )));
+                }
+                return;
+            }
+            module = kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("module"));
+            if let Some(src) = attr(&attrs, "src") {
+                asset = Some((src, true));
+            } else {
+                script_number += 1;
+                if let Some(finding) = javascript_error(
+                    script_text.unwrap_or_default(),
+                    &format!("{entry} inline script {script_number}"),
+                    module,
+                ) {
+                    out.push(finding);
+                }
+            }
+        } else if name == "link"
+            && attr(&attrs, "rel").is_some_and(|rel| {
+                rel.split_ascii_whitespace()
+                    .any(|word| word.eq_ignore_ascii_case("stylesheet"))
+            })
+        {
+            asset = attr(&attrs, "href").map(|href| (href, false));
+        }
+        if let Some((url, script)) = asset {
+            match local_asset(root, url) {
+                Ok(Some(path)) => {
+                    let generated =
+                        path == root.join("dist/app.js") || path == root.join("dist/app.css");
+                    if building && generated && root.join("src/main.ts").is_file() {
+                        return;
+                    }
+                    if script && path == root.join("dist/app.js") {
+                        bundle_loaded = true;
+                    }
+                    if !checked.insert((path.clone(), script, module)) {
+                        return;
+                    }
+                    let replaced = path == root.join("dist/app.js")
+                        || (replaces_css && path == root.join("dist/app.css"));
+                    let path = staging.filter(|_| replaced).map_or(path.clone(), |dir| {
+                        dir.join(path.file_name().expect("generated asset has a name"))
+                    });
+                    match read_source(root, &path) {
+                        Ok(source) if script => {
+                            if let Some(finding) = javascript_error(&source, &format!("{entry} script '{url}'"), module) {
+                                out.push(finding);
+                            }
+                        }
+                        Ok(_) => {}
+                        Err(e) => out.push(error(format!("{entry}: local {} '{url}' could not be read ({e}). Add the file or correct its path.", if script { "script" } else { "stylesheet" }))),
+                    }
+                }
+                Ok(None) => {}
+                Err(e) => out.push(error(format!(
+                    "{entry}: asset '{url}' is invalid ({e}). Correct the URL."
+                ))),
+            }
+        }
+    });
+    let bundle = staging.map_or_else(|| root.join("dist/app.js"), |dir| dir.join("app.js"));
+    if !building && bundle.is_file() && !bundle_loaded {
+        match read_source(root, &bundle) {
+            Ok(source) => {
+                if let Some(finding) = javascript_error(&source, "dist/app.js", false) {
+                    out.push(finding);
+                }
+            }
+            Err(e) => out.push(error(format!(
+                "dist/app.js could not be checked ({e}). Rebuild the bundle."
+            ))),
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn page(html: &str) -> tempfile::TempDir {
+        let dir = tempfile::tempdir().unwrap();
+        std::fs::write(dir.path().join("index.html"), html).unwrap();
+        dir
+    }
+
+    #[test]
+    fn broken_scripts_handlers_and_local_assets_are_actionable() {
+        let dir = page(
+            r#"<script>const value = ;</script><button onclick="const x = ;">Go</button><script src="assets/missing.js?v=1#x"></script><link rel="stylesheet" href="assets/missing.css">"#,
+        );
+        let errors = findings(dir.path(), "index.html", false);
+        assert_eq!(errors.len(), 4);
+        assert!(errors.iter().all(|f| f.msg.contains("index.html")));
+        assert!(errors.iter().any(|f| f.msg.contains("missing.js?v=1#x")));
+        assert!(errors.iter().any(|f| f.msg.contains("missing.css")));
+    }
+
+    #[test]
+    fn valid_modules_data_templates_and_query_urls_are_not_runtime_tests() {
+        let dir = page(
+            r#"<script type="module">import {x} from './assets/helper.js';</script><script type="application/json">not JavaScript</script><script type="importmap">{"imports":{}}</script><template><script>const broken = ;</script></template><textarea><script>const broken = ;</script></textarea><button onclick="return false">Go</button><script src="assets/helper.js?v=2#hash"></script><script src="https://example.test/no-fetch.js"></script><link rel="stylesheet" href="assets/styles.css?x=1">"#,
+        );
+        std::fs::create_dir(dir.path().join("assets")).unwrap();
+        std::fs::write(dir.path().join("assets/helper.js"), "const x = 1;").unwrap();
+        std::fs::write(dir.path().join("assets/styles.css"), "body { color: red; }").unwrap();
+        assert!(findings(dir.path(), "index.html", false).is_empty());
+        assert!(PASSED.contains("Runtime behavior was not verified"));
+    }
+
+    #[test]
+    fn nested_entries_use_the_served_app_root_and_encoded_paths() {
+        let dir = page("placeholder");
+        std::fs::create_dir(dir.path().join("pages")).unwrap();
+        std::fs::write(
+            dir.path().join("pages/home.html"),
+            r#"<script src="assets/helper%20file.js?cache=1"></script>"#,
+        )
+        .unwrap();
+        std::fs::create_dir(dir.path().join("assets")).unwrap();
+        std::fs::write(dir.path().join("assets/helper file.js"), "const x = 1;").unwrap();
+        assert!(findings(dir.path(), "pages/home.html", false).is_empty());
+        std::fs::write(
+            dir.path().join("pages/home.html"),
+            r#"<script src="../outside.js"></script>"#,
+        )
+        .unwrap();
+        assert!(findings(dir.path(), "pages/home.html", false)[0]
+            .msg
+            .contains("leaves the app"));
+    }
+
+    #[test]
+    fn empty_entries_importmaps_and_corrupted_existing_bundles_fail() {
+        let dir = page("");
+        assert!(findings(dir.path(), "index.html", false)[0]
+            .msg
+            .contains("empty"));
+        std::fs::write(
+            dir.path().join("index.html"),
+            "<script type=importmap>{bad}</script>",
+        )
+        .unwrap();
+        assert!(findings(dir.path(), "index.html", false)[0]
+            .msg
+            .contains("importmap"));
+        std::fs::write(dir.path().join("index.html"), "<p>Valid page</p>").unwrap();
+        std::fs::create_dir(dir.path().join("dist")).unwrap();
+        std::fs::write(dir.path().join("dist/app.js"), "(()=>{ const x = ;").unwrap();
+        assert!(findings(dir.path(), "index.html", false)[0]
+            .msg
+            .contains("dist/app.js"));
+        assert!(javascript_error("<div />", "inline", false).is_some());
+        assert!(javascript_error("import x from './x.js';", "inline", false).is_some());
+    }
+
+    #[test]
+    fn less_common_handlers_share_the_renderers_predicate() {
+        let dir = page(
+            r#"<div onwheel="const broken = ;" onscroll="const broken = ;" data-onclick="not JS"></div>"#,
+        );
+        let errors = findings(dir.path(), "index.html", false);
+        assert_eq!(errors.len(), 2);
+        assert!(errors.iter().any(|f| f.msg.contains("onwheel handler")));
+        assert!(errors.iter().any(|f| f.msg.contains("onscroll handler")));
+    }
+
+    #[test]
+    fn source_paths_cannot_read_directories_or_escape_the_app() {
+        let dir = page(r#"<script src="assets/"></script>"#);
+        std::fs::create_dir(dir.path().join("assets")).unwrap();
+        assert!(findings(dir.path(), "index.html", false)[0]
+            .msg
+            .contains("not a regular source file"));
+        let outside = tempfile::tempdir().unwrap();
+        std::fs::write(outside.path().join("external.js"), "const x = 1;").unwrap();
+        assert!(read_source(dir.path(), &outside.path().join("external.js"))
+            .unwrap_err()
+            .to_string()
+            .contains("outside the app"));
+        #[cfg(unix)]
+        {
+            std::os::unix::fs::symlink(
+                outside.path().join("external.js"),
+                dir.path().join("assets/escape.js"),
+            )
+            .unwrap();
+            std::fs::write(
+                dir.path().join("index.html"),
+                r#"<script src="assets/escape.js"></script>"#,
+            )
+            .unwrap();
+            assert!(findings(dir.path(), "index.html", false)[0]
+                .msg
+                .contains("outside the app"));
+        }
+    }
+
+    #[test]
+    fn each_script_loading_context_is_checked_even_after_a_stylesheet() {
+        let dir = page(
+            r#"<script type="module" src="assets/shared.js"></script><script src="assets/shared.js"></script>"#,
+        );
+        std::fs::create_dir(dir.path().join("assets")).unwrap();
+        std::fs::write(dir.path().join("assets/shared.js"), "export const x = 1;").unwrap();
+        assert_eq!(findings(dir.path(), "index.html", false).len(), 1);
+        std::fs::write(dir.path().join("index.html"), r#"<link rel="stylesheet" href="assets/shared.js"><script src="assets/shared.js"></script>"#).unwrap();
+        assert_eq!(findings(dir.path(), "index.html", false).len(), 1);
+        std::fs::write(
+            dir.path().join("index.html"),
+            r#"<script type="module" src="assets/shared.js"></script>"#,
+        )
+        .unwrap();
+        assert!(findings(dir.path(), "index.html", false).is_empty());
+    }
+
+    #[test]
+    fn local_files_must_have_a_served_asset_path() {
+        let dir =
+            page(r#"<script src="helper.js"></script><link rel="stylesheet" href="style.css">"#);
+        std::fs::write(dir.path().join("helper.js"), "const x = 1;").unwrap();
+        std::fs::write(dir.path().join("style.css"), "body{}").unwrap();
+        let errors = findings(dir.path(), "index.html", false);
+        assert_eq!(errors.len(), 2);
+        assert!(errors
+            .iter()
+            .all(|f| f.msg.contains("only from assets/ or dist/")));
+    }
+}
diff --git a/crates/biorouter-mcp/src/agent_drafter/render.rs b/crates/biorouter-mcp/src/agent_drafter/render.rs
index dcb08e6b4..630616827 100644
--- a/crates/biorouter-mcp/src/agent_drafter/render.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/render.rs
@@ -476,7 +476,7 @@ const HANDLER_BINDER_ID: &str = "biorouter-inline-handlers";
 const HANDLER_MARKER: &str = "data-br-on-";
 
 /// Whether an attribute name is an `on…` event handler's.
-fn is_handler_name(key: &str) -> bool {
+pub(crate) fn is_handler_name(key: &str) -> bool {
     key.len() > 2 && key.starts_with("on")
 }
 
@@ -692,20 +692,20 @@ const JS_MIME_TYPES: &[&str] = &[
 
 /// One attribute of a start tag, as the tokenizer reads it.
 #[derive(Debug, Clone)]
-struct TagAttr {
+pub(crate) struct TagAttr {
     /// Lowercase name.
-    key: String,
+    pub(crate) key: String,
     /// Decoded value.
-    value: String,
+    pub(crate) value: String,
     /// Where the whole attribute, name through value, sits in the page.
-    span: std::ops::Range<usize>,
+    pub(crate) span: std::ops::Range<usize>,
     /// A later attribute of the same name on the same tag, which a browser
     /// drops (the first occurrence wins).
-    duplicate: bool,
+    pub(crate) duplicate: bool,
 }
 
 /// A tag as [`scan_tags`] reports it.
-enum Tag<'a> {
+pub(crate) enum Tag<'a> {
     Start {
         /// Lowercase name.
         name: String,
@@ -727,7 +727,7 @@ enum Tag<'a> {
 /// It is deliberately a scanner, not a parser, and errs toward MISSING code
 /// (which then stays blocked, as it always was) rather than inventing it: a
 /// hash can only ever allow text that is really in the page.
-fn scan_tags<'a>(html: &'a str, mut visit: impl FnMut(Tag<'a>)) {
+pub(crate) fn scan_tags<'a>(html: &'a str, mut visit: impl FnMut(Tag<'a>)) {
     let bytes = html.as_bytes();
     let mut i = 0;
     while i < bytes.len() {
@@ -864,7 +864,7 @@ pub fn authored_inline_code(html: &str) -> InlineCode {
     code
 }
 
-fn script_is_executable(type_attr: Option<&str>, language: Option<&str>) -> bool {
+pub(crate) fn script_is_executable(type_attr: Option<&str>, language: Option<&str>) -> bool {
     let mime = match (type_attr.map(str::trim), language.map(str::trim)) {
         (Some(t), _) if !t.is_empty() => t.to_ascii_lowercase(),
         (Some(_), _) => return true,
@@ -1619,28 +1619,30 @@ port_alive() { curl -sf -o /dev/null --max-time 1 "http://127.0.0.1:$1/status" 2
 # ── 3. A daemon whose secret this launcher knows ──────────────────────────
 # A daemon serves an app's page only to a browser holding that app's access
 # cookie, and the one-time link that sets the cookie is handed only to a caller
-# holding the daemon's secret. So this launcher uses a daemon it started (its
-# port and secret are kept, readable by you alone, in $LAUNCHER_STATE) or one you
-# name with BIOROUTERD_PORT and BIOROUTER_SERVER__SECRET_KEY. It cannot open the
-# app on any other daemon, whatever answers /status.
+# holding the daemon's secret. The profile's verified background service comes
+# first, then a daemon this launcher started or one you explicitly name.
 LAUNCHER_STATE="$LAUNCHER_HOME/daemon"
 SECRET=""
 LOG=""
+SHARED_SOCKET=""
+SHARED_IDENTITY=""
 
 new_secret() { od -An -N32 -tx1 /dev/urandom | tr -d ' \n'; }
 
 # Every request that carries the secret hands it to curl on stdin, never on a
 # command line, where other accounts on this machine can read it.
 secret_ok() {
+  if [ -n "$SHARED_SOCKET" ]; then shared_daemon apps >/dev/null; return; fi
   printf 'X-Secret-Key: %s\n' "$2" \
     | curl -sf -o /dev/null --max-time 2 -H @- "http://127.0.0.1:$1/apps" 2>/dev/null
 }
 
 # The path of this app's one-time launch link, from the daemon on :$1.
 launch_path() {
-  printf 'X-Secret-Key: %s\n' "$2" \
-    | curl -sf --max-time 5 -X POST -H @- "http://127.0.0.1:$1/apps/$APP_ID/launch" 2>/dev/null \
-    | sed -n 's|.*"path":"\(/apps/[A-Za-z0-9_-]*/?t=[0-9a-f]*\)".*|\1|p'
+  { if [ -n "$SHARED_SOCKET" ]; then shared_daemon launch "$APP_ID"
+    else printf 'X-Secret-Key: %s\n' "$2" \
+      | curl -sf --max-time 5 -X POST -H @- "http://127.0.0.1:$1/apps/$APP_ID/launch" 2>/dev/null; fi
+  } | sed -n 's|.*"path":"\(/apps/[A-Za-z0-9_-]*/?t=[0-9a-f]*\)".*|\1|p'
 }
 
 save_daemon() {
@@ -1650,6 +1652,132 @@ save_daemon() {
   ) || echo "  (could not remember this daemon; the next run starts another)" >&2
 }
 
+# Read the existing shared-daemon protocol, not a port scan. Python is optional:
+# an installation without it keeps the standalone launcher path below.
+shared_daemon() {
+  command -v python3 >/dev/null 2>&1 || return 1
+  python3 - "$CFG" "$SHARED_IDENTITY" "$@" <<'PY'
+import hashlib, http.client, json, os, re, socket, stat, sys
+from urllib.parse import urlsplit
+
+def private(path, kind):
+    s = os.lstat(path)
+    valid = {'file': stat.S_ISREG, 'directory': stat.S_ISDIR, 'socket': stat.S_ISSOCK}[kind]
+    if not valid(s.st_mode) or s.st_uid != os.getuid() or s.st_mode & 0o7777 != (0o700 if kind == 'directory' else 0o600):
+        raise ValueError('private metadata required')
+    return s
+
+def record(path):
+    private(path, 'file')
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    try:
+        s = os.fstat(fd)
+        if not stat.S_ISREG(s.st_mode) or s.st_uid != os.getuid() or s.st_mode & 0o7777 != 0o600 or s.st_nlink != 1 or s.st_size > 16384:
+            raise ValueError('invalid metadata')
+        with os.fdopen(fd, 'rb', closefd=False) as f:
+            data = f.read(16385)
+        if len(data) > 16384:
+            raise ValueError('oversized metadata')
+        return json.loads(data)
+    finally:
+        os.close(fd)
+
+try:
+    root = os.environ.get('BIOROUTER_PATH_ROOT', '')
+    xdg = os.environ.get('XDG_STATE_HOME', '')
+    state = os.path.join(root, 'state') if root.strip() else os.path.join(xdg if os.path.isabs(xdg) else os.path.expanduser('~/.local/state'), 'biorouter')
+    directory = os.path.join(state, 'daemon')
+    private(directory, 'directory')
+    config = os.path.realpath(sys.argv[1])
+    profile = record(os.path.join(config, 'daemon-profile.json'))
+    runtime = record(os.path.join(directory, 'runtime.json'))
+    uuid = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', re.I)
+    if profile.get('version') != 1 or not isinstance(profile.get('profile_id'), str) or not uuid.fullmatch(profile['profile_id']) or profile.get('config_dir') != config:
+        raise ValueError('profile mismatch')
+    endpoint = runtime.get('endpoint', {})
+    path = endpoint.get('path')
+    secret = runtime.get('api_secret')
+    if runtime.get('version') != 1 or runtime.get('profile_id') != profile['profile_id'] or not isinstance(runtime.get('instance_id'), str) or not uuid.fullmatch(runtime['instance_id']) or type(runtime.get('pid')) is not int or runtime['pid'] < 1 or type(runtime.get('user_action_installed')) is not bool or endpoint.get('kind') != 'unix' or path != os.path.join(directory, 'daemon.sock') or not os.path.isabs(path) or '\n' in path or not isinstance(secret, str) or len(secret) < 32 or not re.fullmatch(r'[A-Za-z0-9._~+/=-]+', secret):
+        raise ValueError('runtime mismatch')
+    expected = {key: runtime[key] for key in ('version', 'profile_id', 'instance_id', 'pid', 'user_action_installed')}
+    pinned = json.loads(sys.argv[2]) if sys.argv[2] else None
+    if pinned and (pinned['identity'] != expected or pinned['key_digest'] != hashlib.sha256(secret.encode()).hexdigest()):
+        raise ValueError('daemon instance changed')
+    private(path, 'socket')
+    class Connection(http.client.HTTPConnection):
+        connected = False
+        def connect(self):
+            if self.connected:
+                raise ValueError('daemon connection changed')
+            self.connected = True
+            private(path, 'socket')
+            self.sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            self.sock.settimeout(2)
+            self.sock.connect(path)
+    connection = Connection('localhost', timeout=2)
+    def request(route):
+        connection.request('GET', route, headers={'X-Secret-Key': secret})
+        response = connection.getresponse()
+        body = response.read(16385)
+        if response.status != 200 or len(body) > 16384:
+            raise ValueError('daemon refused')
+        return json.loads(body)
+    identity = request('/daemon/identity')
+    if identity != expected:
+        raise ValueError('identity mismatch')
+    origin = urlsplit(request('/headless/health').get('api_base_url', ''))
+    if origin.scheme != 'http' or origin.hostname not in ('127.0.0.1', 'localhost', '0.0.0.0') or origin.username or origin.password or origin.path not in ('', '/') or origin.query or origin.fragment or not origin.port:
+        raise ValueError('not a local listener')
+    named = os.environ.get('BIOROUTERD_PORT')
+    if (named and int(named) != origin.port) or (pinned and pinned['port'] != origin.port):
+        raise ValueError('another port was requested')
+    if len(sys.argv) == 3:
+        print(origin.port)
+        print(secret)
+        print(path)
+        print(json.dumps({'identity': expected, 'port': origin.port, 'key_digest': hashlib.sha256(secret.encode()).hexdigest()}, separators=(',', ':')))
+    else:
+        operation = sys.argv[3]
+        if operation == 'import':
+            archive = sys.argv[4]
+            source = os.path.basename(archive)[:-5]
+            if not re.fullmatch(r'[a-z0-9][a-z0-9-]{0,79}', source):
+                raise ValueError('invalid archive filename')
+            size = os.stat(archive).st_size
+            if size > 128 * 1024 * 1024:
+                raise ValueError('oversized archive')
+            boundary = 'biorouter-' + os.urandom(16).hex()
+            header = (f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{source}.brkb"\r\nContent-Type: application/octet-stream\r\n\r\n').encode()
+            footer = f'\r\n--{boundary}--\r\n'.encode()
+            connection.sock.settimeout(120)
+            connection.putrequest('POST', '/knowledge/bases/import')
+            connection.putheader('X-Secret-Key', secret)
+            connection.putheader('Content-Type', f'multipart/form-data; boundary={boundary}')
+            connection.putheader('Content-Length', str(len(header) + size + len(footer)))
+            connection.endheaders(header)
+            with open(archive, 'rb') as stream:
+                while True:
+                    chunk = stream.read(65536)
+                    if not chunk:
+                        break
+                    connection.send(chunk)
+            connection.send(footer)
+        else:
+            route = '/apps' if operation == 'apps' else '/apps/' + sys.argv[4] + '/launch'
+            connection.request('GET' if operation == 'apps' else 'POST', route, headers={'X-Secret-Key': secret})
+        response = connection.getresponse()
+        body = response.read(1024 * 1024 + 1)
+        if response.status != 200 or len(body) > 1024 * 1024:
+            raise ValueError('daemon refused')
+        print(body.decode('utf-8'))
+    connection.close()
+except Exception:
+    if sys.argv[2]:
+        print("Biorouter's background service changed or closed; run the launcher again.", file=sys.stderr)
+    sys.exit(1)
+PY
+}
+
 start_daemon() {
   if [ -n "${BIOROUTER_SERVER__SECRET_KEY:-}" ] && [ -n "${BIOROUTERD_PORT:-}" ] \
     && secret_ok "$BIOROUTERD_PORT" "$BIOROUTER_SERVER__SECRET_KEY"; then
@@ -1657,6 +1785,13 @@ start_daemon() {
     echo "Using the Biorouter daemon on :$PORT"
     return 0
   fi
+  shared="$(shared_daemon)" || shared=""
+  if [ -n "$shared" ]; then
+    { IFS= read -r PORT; IFS= read -r SECRET; IFS= read -r shared_socket; IFS= read -r SHARED_IDENTITY; } <<< "$shared"
+    SHARED_SOCKET="$shared_socket"
+    echo "Using this profile's Biorouter background service on :$PORT"
+    return 0
+  fi
   if [ -f "$LAUNCHER_STATE" ]; then
     saved_port=""; saved_secret=""
     read -r saved_port saved_secret < "$LAUNCHER_STATE" || true
@@ -1890,9 +2025,13 @@ import_knowledge_archive() {
   [ -n "$PORT" ] && [ -n "$SECRET" ] || return 1
   [ "$(wc -c < "$f")" -le 134217728 ] || return 1
   escaped="${f//\\/\\\\}"; escaped="${escaped//\"/\\\"}"
-  response="$(printf 'X-Secret-Key: %s\n' "$SECRET" | curl -fsS --max-time 120 -H @- \
-    -F "file=@\"$escaped\";filename=\"$source.brkb\";type=application/octet-stream" \
-    "http://127.0.0.1:$PORT/knowledge/bases/import")" || return 1
+  if [ -n "$SHARED_SOCKET" ]; then
+    response="$(shared_daemon import "$f")" || return 1
+  else
+    response="$(printf 'X-Secret-Key: %s\n' "$SECRET" | curl -fsS --max-time 120 -H @- \
+      -F "file=@\"$escaped\";filename=\"$source.brkb\";type=application/octet-stream" \
+      "http://127.0.0.1:$PORT/knowledge/bases/import")" || return 1
+  fi
   imported="$(printf '%s' "$response" | sed -n 's/^[[:space:]]*{[[:space:]]*"id"[[:space:]]*:[[:space:]]*"\([a-z0-9-]*\)"[[:space:]]*}[[:space:]]*$/\1/p')"
   knowledge_id_ok "$imported" || return 1
   printf '%s\n' "$imported"
@@ -2519,7 +2658,8 @@ function Test-Port([int]$Port) {
 # cookie, and the one-time link that sets it is handed only to a caller holding
 # the daemon's secret. So this launcher uses a daemon it started (its port and
 # secret are kept in $StateFile, under your profile) or one you name with
-# BIOROUTERD_PORT and BIOROUTER_SERVER__SECRET_KEY, and no other.
+# BIOROUTERD_PORT and BIOROUTER_SERVER__SECRET_KEY. Windows has no shared
+# background-service discovery transport in this Biorouter build.
 $StateFile = Join-Path $LauncherHome "daemon"
 
 function New-Secret {
@@ -2672,10 +2812,11 @@ const SERVE_MJS_TEMPLATE: &str = r##"// Dev server for the exported Biorouter ap
 // daemon, including the agent WebSocket at /apps/<id>/agent, so the page and its
 // agent share an origin and no port is ever hard-coded. The app's dist/ and
 // authored files are safely installed on refresh and served by the daemon.
-import { createServer, request as httpRequest } from "node:http";
+import { Agent as HttpAgent, createServer, request as httpRequest } from "node:http";
+import { createConnection } from "node:net";
 import { spawn, spawnSync } from "node:child_process";
 import { readFile, writeFile, rename, mkdir, cp, rm, access } from "node:fs/promises";
-import { readdirSync, lstatSync, statSync, readFileSync, realpathSync, createReadStream, constants } from "node:fs";
+import { readdirSync, lstatSync, statSync, fstatSync, openSync, closeSync, readSync, readFileSync, realpathSync, createReadStream, constants } from "node:fs";
 import { randomBytes, createHash } from "node:crypto";
 import { join, dirname, isAbsolute, win32, posix } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -2742,10 +2883,10 @@ const STORE = join(CFG, "agent_drafter", APP_ID);
 const LAUNCHER_HOME = join(CFG, "app-launcher");
 // A daemon serves an app's page only to a browser holding that app's access
 // cookie, and the one-time link that sets it is handed only to a caller holding
-// the daemon's secret. So this server uses a daemon it (or run.sh) started, whose
-// port and secret are kept here readable by you alone, or one you name with
-// BIOROUTERD_PORT and BIOROUTER_SERVER__SECRET_KEY, and no other.
+// the daemon's secret. Prefer this profile's verified background service, then
+// a daemon started for these apps. Explicit daemon settings take precedence.
 const LAUNCHER_STATE = join(LAUNCHER_HOME, "daemon");
+let sharedDaemon;
 const APP_PREFIX = `/apps/${APP_ID}/`;
 const PAYLOAD_STATE = join(LAUNCHER_HOME, "payload", APP_ID, SOURCE_DIGEST);
 const exists = (p) => access(p, constants.F_OK).then(() => true, () => false);
@@ -3013,27 +3154,133 @@ function probe(port) {
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
+function daemonTransport(port, connection) {
+  return connection && connection.socketPath && (connection.port === undefined || connection.port === port)
+    ? { socketPath: connection.socketPath, agent: connection.agent }
+    : { host: "127.0.0.1", port };
+}
+
+async function verifiedDaemonConnection(port, secret) {
+  if (!sharedDaemon || sharedDaemon.port !== port) return;
+  const connection = await profileDaemon(sharedDaemon.identity);
+  if (!connection || connection.port !== port || connection.secret !== secret) {
+    connection?.agent.destroy();
+    throw new Error("Biorouter's background service changed or closed; run the launcher again.");
+  }
+  return connection;
+}
+
 /** One request to the daemon on `port` carrying its secret; resolves to { status, body }. */
-function withSecret(port, secret, method, path) {
-  return new Promise((res) => {
+async function withSecret(port, secret, method, path, connection) {
+  const owned = connection === undefined;
+  if (owned) connection = await verifiedDaemonConnection(port, secret);
+  try { return await new Promise((res) => {
     const r = httpRequest(
-      { host: "127.0.0.1", port, path, method, timeout: 5000, headers: { "X-Secret-Key": secret } },
+      { ...daemonTransport(port, connection), path, method, timeout: 5000, headers: { "X-Secret-Key": secret } },
       (resp) => {
         let body = "";
         resp.setEncoding("utf8");
-        resp.on("data", (chunk) => { body += chunk; });
+        resp.on("data", (chunk) => {
+          body += chunk;
+          if (connection && connection.metadata && body.length > 16384) resp.destroy();
+        });
+        resp.on("error", () => res({ status: 0, body: "" }));
+        resp.on("close", () => { if (!resp.complete) res({ status: 0, body: "" }); });
         resp.on("end", () => res({ status: resp.statusCode, body }));
       }
     );
     r.on("error", () => res({ status: 0, body: "" }));
     r.on("timeout", () => { r.destroy(); res({ status: 0, body: "" }); });
     r.end();
-  });
+  }); } finally { if (owned) connection?.agent.destroy(); }
 }
 
 const secretWorks = async (port, secret) =>
   (await withSecret(port, secret, "GET", "/apps")).status === 200;
 
+function privateOwned(path, kind) {
+  const s = lstatSync(path);
+  const valid = kind === "directory" ? s.isDirectory() : kind === "socket" ? s.isSocket() : s.isFile();
+  if (!valid || s.uid !== process.getuid() || (s.mode & 0o7777) !== (kind === "directory" ? 0o700 : 0o600)) {
+    throw new Error("Invalid private daemon metadata");
+  }
+}
+
+function privateRecord(path) {
+  privateOwned(path, "file");
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || s.uid !== process.getuid() || (s.mode & 0o7777) !== 0o600 || s.nlink !== 1 || s.size > 16384) {
+      throw new Error("Invalid private daemon metadata");
+    }
+    const bytes = Buffer.alloc(16385);
+    const count = readSync(fd, bytes, 0, bytes.length, 0);
+    if (count > 16384) throw new Error("Invalid private daemon metadata");
+    return JSON.parse(bytes.subarray(0, count).toString("utf8"));
+  } finally { closeSync(fd); }
+}
+
+async function profileDaemon(expectedIdentity) {
+  // Shared daemon IPC has no Windows transport in this Biorouter build.
+  if (process.platform === "win32") return;
+  const root = process.env.BIOROUTER_PATH_ROOT;
+  const xdg = process.env.XDG_STATE_HOME;
+  const state = root && root.trim() ? join(root, "state")
+    : join(xdg && isAbsolute(xdg) ? xdg : join(homedir(), ".local", "state"), "biorouter");
+  const directory = join(state, "daemon");
+  const location = join(directory, "runtime.json");
+  try { lstatSync(location); } catch (error) { if (error.code === "ENOENT") return; }
+  let agent;
+  try {
+    privateOwned(directory, "directory");
+    const config = realpathSync.native(CFG);
+    const profile = privateRecord(join(config, "daemon-profile.json"));
+    const runtime = privateRecord(location);
+    const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (!profile || profile.version !== 1 || typeof profile.profile_id !== "string" || !uuid.test(profile.profile_id) || profile.config_dir !== config) {
+      throw new Error("Daemon profile mismatch");
+    }
+    if (!runtime || runtime.version !== 1 || runtime.profile_id !== profile.profile_id || typeof runtime.instance_id !== "string" || !uuid.test(runtime.instance_id)
+      || !Number.isSafeInteger(runtime.pid) || runtime.pid < 1 || typeof runtime.user_action_installed !== "boolean"
+      || runtime.endpoint?.kind !== "unix" || runtime.endpoint.path !== join(directory, "daemon.sock") || !isAbsolute(runtime.endpoint.path)
+      || typeof runtime.api_secret !== "string" || runtime.api_secret.length < 32 || !/^[A-Za-z0-9._~+/=-]+$/.test(runtime.api_secret)) {
+      throw new Error("Daemon runtime mismatch");
+    }
+    const keys = ["version", "profile_id", "instance_id", "pid", "user_action_installed"];
+    if (expectedIdentity && keys.some(key => expectedIdentity[key] !== runtime[key])) {
+      throw new Error("Daemon instance changed");
+    }
+    privateOwned(runtime.endpoint.path, "socket");
+    agent = new HttpAgent({ keepAlive: true, maxSockets: 1 });
+    let connected = false;
+    agent.createConnection = () => {
+      if (connected) throw new Error("Biorouter's background service connection closed; run the launcher again.");
+      connected = true;
+      privateOwned(runtime.endpoint.path, "socket");
+      return createConnection({ path: runtime.endpoint.path });
+    };
+    const connection = { socketPath: runtime.endpoint.path, agent, metadata: true };
+    const identityReply = await withSecret(0, runtime.api_secret, "GET", "/daemon/identity", connection);
+    const identity = JSON.parse(identityReply.body);
+    if (identityReply.status !== 200 || !identity || Object.keys(identity).length !== keys.length || keys.some(key => identity[key] !== runtime[key])) {
+      throw new Error("Daemon identity mismatch");
+    }
+    const healthReply = await withSecret(0, runtime.api_secret, "GET", "/headless/health", connection);
+    const origin = new URL(JSON.parse(healthReply.body).api_base_url);
+    const port = Number(origin.port);
+    if (healthReply.status !== 200 || origin.protocol !== "http:" || !["127.0.0.1", "localhost", "0.0.0.0"].includes(origin.hostname)
+      || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash || !Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error("Daemon has no local listener");
+    }
+    if (process.env.BIOROUTERD_PORT && Number(process.env.BIOROUTERD_PORT) !== port) { agent.destroy(); return; }
+    return { port, secret: runtime.api_secret, socketPath: runtime.endpoint.path, agent, identity };
+  } catch {
+    agent?.destroy();
+    if (!expectedIdentity) console.warn("This profile's background service could not be verified; using the standalone launcher.");
+  }
+}
+
 async function rememberDaemon(port, secret) {
   try {
     await mkdir(dirname(LAUNCHER_STATE), { recursive: true, mode: 0o700 });
@@ -3053,6 +3300,12 @@ async function ensureDaemon() {
     console.log(`Using the Biorouter daemon on :${preferred}`);
     return { port: preferred, secret: named };
   }
+  sharedDaemon = await profileDaemon();
+  if (sharedDaemon) {
+    sharedDaemon.agent.destroy();
+    console.log(`Using this profile's Biorouter background service on :${sharedDaemon.port}`);
+    return sharedDaemon;
+  }
   try {
     const [port, secret] = (await readFile(LAUNCHER_STATE, "utf8")).trim().split(/\s+/);
     if (port && secret && (await secretWorks(Number(port), secret))) {
@@ -3228,10 +3481,12 @@ async function importPayloadKnowledge(port, secret, kb) {
   const boundary = `biorouter-${randomBytes(16).toString("hex")}`;
   const header = Buffer.from(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${kb.source}.brkb"\r\nContent-Type: application/octet-stream\r\n\r\n`);
   const footer = Buffer.from(`\r\n--${boundary}--\r\n`);
-  const response = await new Promise((resolve, reject) => {
+  const connection = await verifiedDaemonConnection(port, secret);
+  let response;
+  try { response = await new Promise((resolve, reject) => {
     const stream = createReadStream(kb.path);
     const request = httpRequest({
-      host: "127.0.0.1", port, path: "/knowledge/bases/import", method: "POST", timeout: 120000,
+      ...daemonTransport(port, connection), path: "/knowledge/bases/import", method: "POST", timeout: 120000,
       headers: { "X-Secret-Key": secret, "Content-Type": `multipart/form-data; boundary=${boundary}`, "Content-Length": header.length + size + footer.length },
     }, (reply) => {
       let body = "";
@@ -3249,7 +3504,7 @@ async function importPayloadKnowledge(port, secret, kb) {
     request.write(header);
     stream.pipe(request, { end: false });
     stream.on("end", () => request.end(footer));
-  });
+  }); } finally { connection?.agent.destroy(); }
   if (response.status !== 200) throw new Error(`daemon returned HTTP ${response.status}`);
   let allocated;
   try { allocated = JSON.parse(response.body).id; } catch { }
@@ -3460,8 +3715,8 @@ That's the whole thing. The launcher:
 1. installs the app into your local Biorouter store (`manifest.json` and all),
 2. installs any first-run payload this export carries (`payload/`: knowledge
    bases and skills, with your consent; `export.json` lists them),
-3. reuses the `biorouterd` it started last time, or starts one on the first
-   free port,
+3. reuses your profile's running Biorouter background service when available,
+   otherwise reuses its earlier daemon or starts one on the first free port,
 4. asks that daemon for a one-time link to the app, and
 5. opens the link in your web browser, and prints it in the terminal too.
 
@@ -3477,9 +3732,13 @@ put there.
 
 A daemon serves an app only to a browser that opened such a link, and hands one
 out only to a caller that knows the daemon's secret, so another account on the
-same computer cannot open your app. That is why the launcher starts a daemon of
-its own rather than using one that happens to be running: it keeps that
-daemon's port and secret, readable by you alone, in `app-launcher/daemon` in
+same computer cannot open your app. On macOS and Linux, the launcher verifies
+your profile's private discovery records and the running service's identity
+before using it. Closing the launcher never stops that shared service. The
+shell launchers use Python 3 for this optional discovery; without it, they use
+the standalone path. Windows uses the standalone path because this build has
+no shared-service discovery transport there. When starting its own daemon,
+the launcher keeps its port and secret, readable by you alone, in `app-launcher/daemon` in
 your Biorouter folder (`~/.config/biorouter` on macOS and Linux,
 `%APPDATA%\{windows_author}\{windows_app}\config` on Windows (or the older
 Biorouter folder in `%APPDATA%`, until Biorouter has moved it), or
@@ -3586,6 +3845,415 @@ mod tests {
         find_command("bash", work_dir)
     }
 
+    #[cfg(unix)]
+    struct LauncherFixture(std::process::Child);
+
+    #[cfg(unix)]
+    impl Drop for LauncherFixture {
+        fn drop(&mut self) {
+            let _ = self.0.kill();
+            let _ = self.0.wait();
+        }
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn generated_launchers_reuse_verified_profile_without_owning_it() {
+        use std::os::unix::fs::PermissionsExt;
+        use std::process::{Command, Stdio};
+
+        let directory = tempfile::Builder::new()
+            .prefix("br-launch-")
+            .tempdir_in("/tmp")
+            .unwrap();
+        let Some(node) = find_command("node", directory.path()) else {
+            eprintln!("skipped: no node for shared launcher lifecycle test");
+            return;
+        };
+        let root = directory.path().join("profile");
+        let folder = directory.path().join("export");
+        std::fs::create_dir_all(&folder).unwrap();
+        let m = manifest(ArtifactKind::Static);
+        for (name, content) in launcher_files(&m, None) {
+            std::fs::write(folder.join(name), content).unwrap();
+        }
+        std::fs::write(folder.join("manifest.json"), exported_manifest_json(&m)).unwrap();
+        std::fs::write(folder.join("index.html"), "<html>exported copy</html>").unwrap();
+        std::fs::create_dir_all(folder.join("payload/knowledge")).unwrap();
+        std::fs::write(
+            folder.join("payload/knowledge/demo-kb.brkb"),
+            "test archive",
+        )
+        .unwrap();
+        std::fs::write(folder.join("export.json"), "{}").unwrap();
+        let fixture_script = directory.path().join("daemon.cjs");
+        std::fs::write(
+            &fixture_script,
+            r#"const http = require('node:http'), fs = require('node:fs'), path = require('node:path');
+const root = process.env.BIOROUTER_PATH_ROOT;
+const config = path.join(root, 'config'), directory = path.join(root, 'state/daemon');
+fs.mkdirSync(config, {recursive:true});fs.mkdirSync(directory, {recursive:true, mode:0o700});fs.chmodSync(directory, 0o700);
+const profile = 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa';
+const instance = 'bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb';
+const secret = 'dd'.repeat(32), explicit = 'ee'.repeat(32);
+const socket = path.join(directory, 'daemon.sock');
+const identity = {version:1, profile_id:profile, instance_id:instance, pid:process.pid, user_action_installed:true};
+const controlPath = path.join(root, 'control.json');fs.writeFileSync(controlPath, '{}');
+let port;
+const handle = transport => (req, res) => {
+  const control = JSON.parse(fs.readFileSync(controlPath));
+  fs.appendFileSync(path.join(root, 'requests.jsonl'), JSON.stringify({transport, route:req.url, shared_secret:req.headers['x-secret-key']===secret})+'\n');
+  const json = value => {res.setHeader('content-type','application/json');res.end(JSON.stringify(value));};
+  if (transport==='http' && req.url==='/status') return res.end('ok');
+  if (transport==='http' && req.url.startsWith('/apps/demo/?t=') && !req.headers['x-secret-key']) return res.end(fs.readFileSync(path.join(config, 'agent_drafter/demo/index.html')));
+  if (req.headers['x-secret-key'] !== (transport==='unix' ? secret : explicit)) {res.writeHead(401);return res.end();}
+  if (req.url==='/daemon/identity') return json(control.badIdentity ? {...identity,pid:identity.pid+1} : identity);
+  if (req.url==='/headless/health') {
+    if (control.closeAfterHealth) {
+      fs.writeFileSync(controlPath, '{}');
+      res.setHeader('connection','close');
+      res.on('finish', () => {
+        if (control.changedDescriptor) {
+          const record = JSON.parse(fs.readFileSync(path.join(directory, 'runtime.json')));
+          record.instance_id = 'cccccccc-cccc-4ccc-cccc-cccccccccccc';
+          fs.writeFileSync(path.join(directory, 'runtime.json'), JSON.stringify(record));
+        }
+        if (control.replaceAfterHealth) {
+          unix.close(() => {
+            if (fs.existsSync(socket)) fs.unlinkSync(socket);
+            fs.writeFileSync(controlPath, JSON.stringify({badIdentity:true}));
+            unix = http.createServer(handle('unix'));
+            unix.listen(socket, () => {fs.chmodSync(socket,0o600);fs.writeFileSync(path.join(root,'lifecycle-ready'),'ready');});
+          });
+        } else fs.writeFileSync(path.join(root,'lifecycle-ready'),'ready');
+      });
+    }
+    return json({api_base_url:control.origin || `http://127.0.0.1:${port}`});
+  }
+  if (req.url==='/apps') return json([]);
+  if (req.method==='POST' && req.url==='/knowledge/bases/import') {
+    let body='';req.on('data',chunk=>body+=chunk);req.on('end',()=> {
+      if (!body.includes('filename="demo-kb.brkb"') || !body.includes('test archive')) {res.writeHead(400);return res.end();}
+      json({id:'demo-kb'});
+    });return;
+  }
+  if (req.method==='POST' && req.url==='/apps/demo/launch') return json({path:'/apps/demo/?t='+'ab'.repeat(32)});
+  res.writeHead(404);res.end();
+};
+const tcp = http.createServer(handle('http'));
+let unix = http.createServer(handle('unix'));
+tcp.listen(0, '127.0.0.1', () => {
+  port = tcp.address().port;
+  unix.listen(socket, () => {
+    fs.chmodSync(socket, 0o600);
+    fs.writeFileSync(path.join(config, 'daemon-profile.json'),JSON.stringify({version:1,profile_id:profile,config_dir:fs.realpathSync(config)}),{mode:0o600});
+    fs.writeFileSync(path.join(directory, 'runtime.json'),JSON.stringify({...identity,endpoint:{kind:'unix',path:socket},api_secret:secret}),{mode:0o600});
+    fs.writeFileSync(path.join(root, 'ready'),String(port));
+  });
+});
+setTimeout(()=>process.exit(0),120000).unref();
+"#,
+        )
+        .unwrap();
+        let mut fixture = LauncherFixture(
+            Command::new(&node)
+                .arg(&fixture_script)
+                .env("BIOROUTER_PATH_ROOT", &root)
+                .stdin(Stdio::null())
+                .stdout(Stdio::null())
+                .stderr(Stdio::null())
+                .spawn()
+                .unwrap(),
+        );
+        let ready = root.join("ready");
+        for _ in 0..100 {
+            if ready.exists() {
+                break;
+            }
+            assert!(fixture.0.try_wait().unwrap().is_none(), "fixture exited");
+            std::thread::sleep(std::time::Duration::from_millis(20));
+        }
+        let port: u16 = std::fs::read_to_string(&ready)
+            .expect("shared fixture ready")
+            .parse()
+            .unwrap();
+        let runtime_path = root.join("state/daemon/runtime.json");
+        let original = std::fs::read_to_string(&runtime_path).unwrap();
+        let (definitions, _) = serve_mjs("demo", 5123, "")
+            .split_once("\nlet daemonPort;")
+            .map(|(prefix, suffix)| (prefix.to_string(), suffix.to_string()))
+            .unwrap();
+        let probe = folder.join("probe.mjs");
+        std::fs::write(
+            &probe,
+            format!(
+                "{definitions}\ndaemonPaths = () => [];\ntry {{ await installApp(); const daemon = await ensureDaemon(); if(process.env.LAUNCHER_TEST_LIFECYCLE==='1') {{const marker=join(process.env.BIOROUTER_PATH_ROOT,'lifecycle-ready');for(let i=0;!payloadKind(marker)?.isFile()&&i<100;i++)await sleep(10);if(!payloadKind(marker)?.isFile())throw Error('lifecycle fixture not ready');}} await installPayload(daemon.port,daemon.secret); const launch = await launchPath(daemon.port,daemon.secret); console.log('SELECTED:'+daemon.port+':'+(sharedDaemon?'socket':'http')); if(sharedDaemon) {{ const page = await new Promise((resolve,reject)=>{{ const request=httpRequest({{host:'127.0.0.1',port:daemon.port,path:launch}},response=>{{let body='';response.on('data',chunk=>body+=chunk);response.on('end',()=>resolve(body));}});request.on('error',reject);request.end();}});if(!page.includes('exported copy'))throw Error('not exported app'); }} }} catch(error) {{console.error(error.message);process.exitCode=1;}} finally {{sharedDaemon?.agent.destroy();}}\n"
+            ),
+        )
+        .unwrap();
+        let bash = find_usable_bash(&folder).unwrap();
+        let shell_probe = folder.join("probe.sh");
+        std::fs::write(
+            &shell_probe,
+            "set -euo pipefail\n. ./biorouter-launch.sh\nfind_biorouterd() { echo standalone-fallback >&2; return 1; }\ninstall_app\nstart_daemon\nif [ \"${LAUNCHER_TEST_LIFECYCLE:-}\" = 1 ]; then for i in {1..100}; do [ -f \"$BIOROUTER_PATH_ROOT/lifecycle-ready\" ] && break; sleep 0.01; done; [ -f \"$BIOROUTER_PATH_ROOT/lifecycle-ready\" ]; fi\ninstall_payload\nlaunch_url\nprintf 'SELECTED:%s:%s\\n' \"$PORT\" \"${SHARED_SOCKET:+socket}\"\n",
+        )
+        .unwrap();
+        let python = find_command("python3", &folder);
+        let run = |backend: &str, env: &[(&str, String)]| {
+            let mut command = Command::new(if backend == "node" { &node } else { &bash });
+            command
+                .arg(if backend == "node" {
+                    &probe
+                } else {
+                    &shell_probe
+                })
+                .current_dir(&folder)
+                .env("BIOROUTER_PATH_ROOT", &root)
+                .env("BIOROUTER_EXPORT_YES", "1")
+                .env_remove("BIOROUTERD_PORT")
+                .env_remove("BIOROUTER_SERVER__SECRET_KEY")
+                .env_remove("BIOROUTERD_BIN")
+                .stdin(Stdio::null());
+            for (key, value) in env {
+                command.env(key, value);
+            }
+            let out = command.output().unwrap();
+            let printed = format!(
+                "{}{}",
+                String::from_utf8_lossy(&out.stdout),
+                String::from_utf8_lossy(&out.stderr)
+            );
+            assert!(!printed.contains(&"dd".repeat(32)), "shared secret printed");
+            assert!(
+                !printed.contains(&"ee".repeat(32)),
+                "explicit secret printed"
+            );
+            (out.status.success(), printed)
+        };
+        let import_count = || {
+            std::fs::read_to_string(root.join("requests.jsonl"))
+                .unwrap_or_default()
+                .lines()
+                .filter(|line| {
+                    serde_json::from_str::<serde_json::Value>(line).unwrap()["route"]
+                        == "/knowledge/bases/import"
+                })
+                .count()
+        };
+        let backends: Vec<&str> = if python.is_some() {
+            vec!["node", "bash"]
+        } else {
+            vec!["node"]
+        };
+        for backend in &backends {
+            let _ = std::fs::remove_dir_all(root.join("config/app-launcher/payload"));
+            let before_imports = import_count();
+            let (ok, printed) = run(backend, &[]);
+            assert!(ok, "{backend}: {printed}");
+            assert_eq!(
+                import_count() - before_imports,
+                1,
+                "{backend} duplicated the shared payload import"
+            );
+            assert!(
+                printed.contains(&format!("SELECTED:{port}:socket")),
+                "{printed}"
+            );
+            assert!(
+                printed.contains("Payload installed."),
+                "{backend} did not import full payload: {printed}"
+            );
+            assert!(
+                fixture.0.try_wait().unwrap().is_none(),
+                "launcher killed reused daemon"
+            );
+        }
+        for case in [
+            "wrong-profile",
+            "wrong-identity",
+            "unsafe-record",
+            "unsafe-socket",
+            "remote-origin",
+            "named-other-port",
+            "stale-record",
+            "oversized-record",
+            "wrong-socket",
+        ] {
+            let mut descriptor: serde_json::Value = serde_json::from_str(&original).unwrap();
+            let mut control = serde_json::json!({});
+            let mut env = Vec::new();
+            match case {
+                "wrong-profile" => {
+                    descriptor["profile_id"] = "cccccccc-cccc-4ccc-cccc-cccccccccccc".into()
+                }
+                "wrong-identity" => control["badIdentity"] = true.into(),
+                "unsafe-record" => {
+                    std::fs::set_permissions(&runtime_path, std::fs::Permissions::from_mode(0o644))
+                        .unwrap()
+                }
+                "unsafe-socket" => std::fs::set_permissions(
+                    root.join("state/daemon/daemon.sock"),
+                    std::fs::Permissions::from_mode(0o666),
+                )
+                .unwrap(),
+                "remote-origin" => control["origin"] = "http://example.test:1234".into(),
+                "named-other-port" => env.push((
+                    "BIOROUTERD_PORT",
+                    (if port == 65535 { port - 1 } else { port + 1 }).to_string(),
+                )),
+                "stale-record" => std::fs::remove_file(&runtime_path).unwrap(),
+                "oversized-record" => descriptor["padding"] = "x".repeat(16385).into(),
+                "wrong-socket" => {
+                    descriptor["endpoint"]["path"] = root
+                        .join("another.sock")
+                        .to_string_lossy()
+                        .into_owned()
+                        .into()
+                }
+                _ => unreachable!(),
+            }
+            if case != "stale-record" {
+                std::fs::write(&runtime_path, serde_json::to_vec(&descriptor).unwrap()).unwrap();
+            }
+            std::fs::write(
+                root.join("control.json"),
+                serde_json::to_vec(&control).unwrap(),
+            )
+            .unwrap();
+            for backend in &backends {
+                let (ok, printed) = run(backend, &env);
+                assert!(!ok, "{backend} reused {case}: {printed}");
+                assert!(
+                    printed.contains(if *backend == "bash" {
+                        "standalone-fallback"
+                    } else {
+                        "Could not find or start biorouterd"
+                    }),
+                    "{backend} did not reach standalone fallback for {case}: {printed}"
+                );
+                assert!(
+                    fixture.0.try_wait().unwrap().is_none(),
+                    "refusal killed shared daemon"
+                );
+            }
+            std::fs::write(&runtime_path, &original).unwrap();
+            std::fs::set_permissions(&runtime_path, std::fs::Permissions::from_mode(0o600))
+                .unwrap();
+            std::fs::set_permissions(
+                root.join("state/daemon/daemon.sock"),
+                std::fs::Permissions::from_mode(0o600),
+            )
+            .unwrap();
+            std::fs::write(root.join("control.json"), "{}").unwrap();
+        }
+        for case in ["idle-close", "replacement-socket", "changed-descriptor"] {
+            for backend in &backends {
+                let before = std::fs::read_to_string(root.join("requests.jsonl")).unwrap();
+                let _ = std::fs::remove_file(root.join("lifecycle-ready"));
+                let _ = std::fs::remove_dir_all(root.join("config/app-launcher/payload"));
+                std::fs::write(
+                    root.join("control.json"),
+                    serde_json::to_vec(&serde_json::json!({
+                        "closeAfterHealth": true,
+                        "replaceAfterHealth": case == "replacement-socket",
+                        "changedDescriptor": case == "changed-descriptor",
+                    }))
+                    .unwrap(),
+                )
+                .unwrap();
+                let before_imports = import_count();
+                let (ok, printed) = run(backend, &[("LAUNCHER_TEST_LIFECYCLE", "1".to_string())]);
+                if case == "idle-close" {
+                    assert!(ok, "idle-close did not reverify and recover: {printed}");
+                    assert!(printed.contains("Payload installed."), "{printed}");
+                    assert_eq!(
+                        import_count() - before_imports,
+                        1,
+                        "{backend} duplicated the idle-close import"
+                    );
+                } else {
+                    assert!(!ok, "stale connection followed {case}: {printed}");
+                    assert!(
+                        printed.contains("run the launcher again"),
+                        "no recovery advice: {printed}"
+                    );
+                    let after = std::fs::read_to_string(root.join("requests.jsonl")).unwrap();
+                    let added = &after[before.len()..];
+                    let requests: Vec<serde_json::Value> = added
+                        .lines()
+                        .map(|line| serde_json::from_str(line).unwrap())
+                        .collect();
+                    assert!(
+                        requests
+                            .iter()
+                            .all(|request| request["route"] == "/daemon/identity"
+                                || request["route"] == "/headless/health"),
+                        "an app request reached the replacement service: {added}"
+                    );
+                    if case == "changed-descriptor" {
+                        assert_eq!(
+                            requests.len(),
+                            2,
+                            "secret sent after descriptor changed: {added}"
+                        );
+                    }
+                }
+                assert!(
+                    fixture.0.try_wait().unwrap().is_none(),
+                    "connection change killed shared daemon"
+                );
+                std::fs::write(root.join("control.json"), "{}").unwrap();
+                std::fs::write(&runtime_path, &original).unwrap();
+            }
+        }
+        for backend in &backends {
+            let _ = std::fs::remove_dir_all(root.join("config/app-launcher/payload"));
+            let before_imports = import_count();
+            let (ok, printed) = run(
+                backend,
+                &[
+                    ("BIOROUTERD_PORT", port.to_string()),
+                    ("BIOROUTER_SERVER__SECRET_KEY", "ee".repeat(32)),
+                ],
+            );
+            assert!(ok, "explicit daemon configuration: {backend}: {printed}");
+            assert_eq!(
+                import_count() - before_imports,
+                1,
+                "{backend} duplicated the explicit HTTP import"
+            );
+            assert!(
+                !printed.contains("background service"),
+                "explicit daemon lost precedence: {printed}"
+            );
+            assert!(
+                printed.contains("Payload installed."),
+                "explicit HTTP payload import failed: {printed}"
+            );
+        }
+        let requests = std::fs::read_to_string(root.join("requests.jsonl")).unwrap();
+        let mut imports = 0;
+        for line in requests.lines() {
+            let request: serde_json::Value = serde_json::from_str(line).unwrap();
+            if request["route"] == "/knowledge/bases/import" {
+                imports += 1;
+            }
+            assert!(
+                request["transport"] != "http" || request["shared_secret"] != true,
+                "shared secret left private socket"
+            );
+        }
+        assert_eq!(
+            imports,
+            backends.len() * 3,
+            "one full payload import per backend for shared, recovered and explicit transports"
+        );
+        assert!(
+            fixture.0.try_wait().unwrap().is_none(),
+            "launcher exit killed shared daemon"
+        );
+    }
+
     #[cfg(windows)]
     fn push_git_bash_candidates(candidates: &mut Vec<PathBuf>, git_root: &Path) {
         candidates.push(git_root.join("bin").join("bash.exe"));
diff --git a/docs/apps-sdk/sdk-reference.md b/docs/apps-sdk/sdk-reference.md
index d2f4b7b11..7f26c66b1 100644
--- a/docs/apps-sdk/sdk-reference.md
+++ b/docs/apps-sdk/sdk-reference.md
@@ -38,7 +38,7 @@ create_app  →  (edit src/main.ts + index.html)  →  build_app  →  launch_ap
 1. **Create.** `create_app { title, description, archetype?, extensions?, skills?, knowledge_base?, capabilities?, … }`. Omitting `html`/`src/main.ts` seeds a working, lint-clean **archetype** starter (explorer / dashboard / workbench / wizard / canvas / chat) plus a matching declared `manifest.surface`. Default kind is `agentic`; pass `kind: "static"` for a plain page with no agent. An explicit `id` that is already taken is refused unless this chat created that app, or the call passes `replace: true` (see [deleting, re-creating and broken apps](#deleting-re-creating-and-broken-apps)).
 2. **Edit.** `update_app { id, path?, content? | old_str+new_str }`. Editing anything under `src/` marks the bundle stale. Author your UI in `src/main.ts` (which `import`s `./sdk`) and your shell in `index.html`.
 3. **Configure (optional).** `configure_app { id, system_prompt?, model?, extensions?, skills?, knowledge_base?, max_turns?, capabilities?, guardrails?, reliability?, orchestration?, output_type?, durable_session? }`.
-4. **Build.** `build_app { id }` bundles `src/main.ts → dist/app.js` with esbuild, refreshes the vendored `src/sdk.ts`, stamps `manifest.sdk_hash`, and runs the lint harness. Fix any harness **ERROR** before launch or export. See [building and serving](#building-and-serving) for where esbuild comes from and when an app is rebuilt on its own.
+4. **Build.** `build_app { id }` bundles `src/main.ts → dist/app.js` with esbuild, refreshes the vendored `src/sdk.ts`, and runs the lint harness and default browser-free page check. A check error fails the build; only a successful bundle receives a current `manifest.sdk_hash` stamp. Static pages without TypeScript are checked without creating a bundle. Fix the reported errors before launch or export. See [building and serving](#building-and-serving) for where esbuild comes from and when an app is rebuilt on its own.
 5. **Launch.** `launch_app { id }` returns `http://<host>/apps/<id>/`. That address carries no access cookie, so it is a name for the app rather than a way in. The desktop opens it as a live preview in the chat's artifact panel, on the window's own daemon whatever port the link names (a link from an earlier run names a port that is gone), through a launch link it mints itself. Only `http://127.0.0.1:<port>/apps/<id>/`, the spelling the daemon writes, is taken for an app this way; a `localhost` link is left alone, because that is usually a web development server and the person's own project. The preview's **Open in browser** opens the app in the default browser the same way, and it is always the app the preview shows, whatever address the app's page has put in the toolbar. On Linux, a default browser packaged as a snap (stock Ubuntu's Firefox and Chromium) cannot read the page the desktop hands the link over in, so the desktop offers to copy a one-time link to paste into it instead. The CLI prints the URL, and `biorouter apps open <id>` opens the app from a terminal.
 6. **Export.** `export_app { id, target_dir, replace?, mode?, include?, bundle_daemon? }` writes a folder that runs the app on another computer; the Applications view's **Export** does the same through the daemon. See the [export guide](#export-guide).
 
@@ -90,9 +90,9 @@ Serving `GET /apps/<id>/` and `launch_app` rebuild an app first when its bundle
 - the fallback bundler built it and esbuild can run now;
 - it was built against a different App SDK than this daemon ships, unless the SDK it carries came from a newer Biorouter (`sdkv=`, or the builder's version when that is absent). A daemon never rebuilds an app down to its own older SDK, and when it rebuilds such an app for another reason it keeps the newer SDK and records where it came from, so two daemons of different versions serving one store no longer rebuild each app back and forth.
 
-Builds of one app are serialised: a second request waits for the first, then finds the bundle fresh. Bundles and the refreshed `src/sdk.ts` are written to a temporary file and renamed into place, so a browser never loads half a bundle. A build that failed is remembered against its inputs (the files under `src/`, the bundle and the manifest stamps), so an app whose code does not compile is not rebuilt on every page load; any edit is a new attempt.
+Builds of one app are serialised: a second request waits for the first, then finds the bundle fresh. Bundles and the refreshed `src/sdk.ts` are written to a temporary file and renamed into place, so a browser never loads half a bundle. A build that failed is remembered against its inputs (source files, page and asset metadata, the bundle and the manifest stamps), so an app whose code does not compile is not rebuilt on every page load. Fixing the page or adding a missing asset permits another attempt.
 
-When an app that cannot run without a bundle (an agentic app, or one with a `src/main.ts`) has none and its build failed, `GET /apps/<id>/` answers `500` with a short page that shows the escaped build log and asks the person to have the agent fix the app and rebuild it. An app that still has an older bundle keeps serving it, and `launch_app` then returns the address with a warning that the browser gets the previous bundle, without the latest changes, and the build log.
+When an app that cannot run without a bundle (an agentic app, or one with a `src/main.ts`) has none and its build failed, `GET /apps/<id>/` answers `500` with a short page that shows the escaped build log and asks the person to have the agent fix the app and rebuild it. An app that still has an older bundle can keep serving it if its current page passes the default check; `launch_app` then returns the address with a warning that the browser gets the previous bundle, without the latest changes, and the build log. A page-check error blocks serving and launch even when an older bundle exists.
 
 ### Static apps and inline scripts
 
@@ -100,7 +100,7 @@ A static app is a page written in `index.html`. Inline `<script>` blocks and `on
 
 Code inserted at runtime, a `<script>` or a handler an agent or a data binding adds later, is still blocked. `'unsafe-inline'` and `'unsafe-hashes'` are never sent. `'unsafe-hashes'` was sent until 2026-10, and it let markup injected later (an agent's `html` node, say) run any handler the author wrote, on an element the injection chose: with `onclick="br.chat(this.dataset.q)"` on the page, an injected `<img src=x data-q="…" onerror="br.chat(this.dataset.q)">` sent its own prompt with no click.
 
-What does not run: a handler inside a `<template>` (a clone cannot carry the listener, and binding clones later would bind injected markup too; wire those in code), a handler the binder script cannot hold safely (one that does not parse, or contains `</script` or `<!--`), a handler added or changed at runtime, and a `javascript:` URL in `href`, `src` or `action`, which the lint harness warns about. A static app needs `build_app` only when it has a `src/main.ts`.
+What does not run: a handler inside a `<template>` (a clone cannot carry the listener, and binding clones later would bind injected markup too; wire those in code), a handler the binder script cannot hold safely (one that does not parse, or contains `</script` or `<!--`), a handler added or changed at runtime, and a `javascript:` URL in `href`, `src` or `action`, which the lint harness warns about. A static app is bundled only when it has a `src/main.ts`; `build_app` checks its page either way.
 
 The served page gets `<script src="dist/app.js">` only when `dist/app.js` exists and the page does not already load it itself. Agentic apps keep their code in `src/main.ts`, because the SDK (`createApp`, `br.*`) exists only inside the bundle.
 
@@ -108,6 +108,10 @@ Assembly is idempotent: before injecting the theme, the config island, the bundl
 
 `configure_app` on a static app makes it agentic and adds whichever of `src/sdk.ts` and `src/main.ts` it lacks, leaving `index.html` and an existing `src/main.ts` alone. A blank `kind` is refused rather than read as `static`.
 
+### Default browser-free page check
+
+Build, launch, page serving and export check the manifest's entry, the declared local script and stylesheet files, and JavaScript structure in executable inline scripts, handlers and built code. Local scripts and styles must use the server's `assets/` or `dist/` paths; a file elsewhere in the app can exist but still return 404. Generated assets are checked before replacing an earlier working bundle. The check uses Biorouter's parser, requires no Node.js or browser, does not fetch external URLs, and never executes app code. It also runs on static pages. A proven page defect produces an error naming the file and blocks a successful launch or export; advisory lint warnings remain advisory. Passing this check verifies these static conditions. Rendering, interactions, runtime state, module resolution and JavaScript early/runtime errors still need runtime or compiler verification; CSS is checked for presence, not syntax or visual quality.
+
 ### Checking an app in a real browser
 
 `smoke_app` runs the app in a headless browser against a mock daemon. It is optional: it needs Node.js and Playwright's Chromium on this machine and the harness script from a source checkout, which an installed Biorouter does not ship. When any of them is missing it says which, and that says nothing about the app.
@@ -752,7 +756,7 @@ A launcher installs the app into the store the daemon reads, starts or reuses a
 - **How a launcher tells an unchanged copy.** `updated_at` alone could not: only the drafter's own tools bump it, so an edit made in the installed copy with the developer shell or a text editor, or a newer Biorouter refreshing `src/sdk.ts` on a rebuild, left it equal, and the old folder's launcher reverted the edit or brought back the old SDK. So the export records one SHA-256 over the authored runtime files a launcher replaces (`src/sdk.ts` and `dist/` are omitted for an app with `src/main.ts`, because the daemon derives them; `.DS_Store` files and links left out; one `<hash> <path>` line per file, sorted by byte, then hashed), and every launcher computes the same digest over the store before it re-syncs. Each install writes both a hash of the export folder's real path and the installed runtime digest to `app-launcher/installed/<id>`, so an older folder cannot trust another folder's install record. The loop keeps working after the daemon refreshes its SDK; the refreshed SDK is retained. `bash run.sh` needs `sha256sum` or `shasum` for this; without either, a copy with the same `updated_at` is opened as it is. A test holds the bash and Node digests to the export's.
 - **A re-sync keeps the store's bundle.** It keeps the store's manifest, which on the author's machine still names the chat the app was built in, and that manifest's build stamp describes the store's own `dist/`. So for an app with `src/main.ts` the folder's `dist/` is not copied, the store's refreshed SDK is retained, and the daemon rebuilds from the synced `src/` when that changed. Authored files or whole subtrees removed from the export are removed from an unchanged installation too. Copying it under the kept stamp could serve an older SDK that the stamp called current, and the daemon would never rebuild it.
 - **Payload paths are bash arrays**, so a folder unzipped under a path with a space installs the right skills. A skill already installed under the same name is moved to backups first. A skill that ships with Biorouter is never installed from a payload, even one that carries it.
-- **The daemon.** A launcher uses a daemon whose secret it knows: one it started before (port and secret kept, readable by you alone, in `app-launcher/daemon`) or one named by `BIOROUTERD_PORT` and `BIOROUTER_SERVER__SECRET_KEY`. Otherwise it starts one headlessly (via `BIOROUTER_PORT`), waits up to 60 seconds for it, and stops it before trying another port, so no daemon is left running whose secret nobody knows. The daemon's log goes to `app-launcher/logs/`, a folder only you can read.
+- **The daemon.** A launcher honors an explicitly configured `BIOROUTERD_PORT` and `BIOROUTER_SERVER__SECRET_KEY`. On macOS and Linux it otherwise tries the running desktop service for the same configuration profile, verifying its private descriptor, socket and instance identity before attaching. Every authenticated shared-service operation, including archive imports, uses a freshly verified Unix connection and checks the original instance; a changed instance requires rerunning the launcher. Shell launchers use Python 3 for automatic reuse when available; `serve.mjs` uses Node's built-in facilities. A reused service stays running when the launcher exits. Windows has no shared-service discovery protocol in this build, so automatic attachment is unavailable there; explicit daemon configuration still works. If no usable shared service is found, the launcher reuses one it started before (port and secret kept, readable by you alone, in `app-launcher/daemon`) or starts one headlessly (via `BIOROUTER_PORT`), waits up to 60 seconds for it, and stops it before trying another port. The daemon's log goes to `app-launcher/logs/`, a folder only you can read.
 - **The browser.** The link is written into a page only you can read, and that page is opened in the default web browser (on macOS the `https:` handler through `open -a`, on Linux the `xdg-settings` browser through `gtk-launch`, else `xdg-open`). Handing it to `open` or `xdg-open` alone opened whatever edits `.html` files, often an editor.
 
 `serve.mjs` (`npm start`) is the editing loop. It installs the app under the same rules, starts or reuses a daemon, and proxies `/apps/**` to it, including the agent WebSocket. On page refresh it rechecks the installed runtime digest and safely syncs the folder's edits, retaining independent changes in the installed copy. All app files, including bundles and images, are served through the daemon's authorization and security policy, so an upgraded or rebuilt daemon bundle is the one the browser receives. Only a `Host` of `127.0.0.1:<port>` or `localhost:<port>` is answered, which closes DNS rebinding. `/` redirects to the app's page on the daemon: only the daemon can put the run's socket token into the page. `payload/`, `export.json` and the scripts are never served.

From ec003654b1a04395a929204697dc0b5e1eb273fc Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 17:23:12 -0700
Subject: [PATCH 24/26] test(apps): verify appended request logs without string
 slicing

---
 crates/biorouter-mcp/src/agent_drafter/render.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/crates/biorouter-mcp/src/agent_drafter/render.rs b/crates/biorouter-mcp/src/agent_drafter/render.rs
index 630616827..bf9537e7e 100644
--- a/crates/biorouter-mcp/src/agent_drafter/render.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/render.rs
@@ -4178,7 +4178,9 @@ setTimeout(()=>process.exit(0),120000).unref();
                         "no recovery advice: {printed}"
                     );
                     let after = std::fs::read_to_string(root.join("requests.jsonl")).unwrap();
-                    let added = &after[before.len()..];
+                    let added = after
+                        .strip_prefix(&before)
+                        .expect("requests retain their prefix");
                     let requests: Vec<serde_json::Value> = added
                         .lines()
                         .map(|line| serde_json::from_str(line).unwrap())

From f364196523d1ba8a8a1334c18206419588c83852 Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 17:31:29 -0700
Subject: [PATCH 25/26] refactor(apps): split authored page inspection for lint
 compliance

---
 .../src/agent_drafter/page_check.rs           | 116 ++++++++++--------
 1 file changed, 66 insertions(+), 50 deletions(-)

diff --git a/crates/biorouter-mcp/src/agent_drafter/page_check.rs b/crates/biorouter-mcp/src/agent_drafter/page_check.rs
index 6a7ac3fa9..ff8175675 100644
--- a/crates/biorouter-mcp/src/agent_drafter/page_check.rs
+++ b/crates/biorouter-mcp/src/agent_drafter/page_check.rs
@@ -142,6 +142,63 @@ pub(super) fn staged_findings(
     findings_with(root, entry, false, Some(staging), replaces_css)
 }
 
+fn authored_asset<'a>(
+    name: &str,
+    attrs: &'a [TagAttr],
+    script_text: Option<&str>,
+    entry: &str,
+    script_number: &mut usize,
+    out: &mut Vec<LintFinding>,
+) -> Option<(&'a str, bool, bool)> {
+    for handler in attrs
+        .iter()
+        .filter(|a| !a.duplicate && is_handler_name(&a.key))
+    {
+        let source = format!("function __handler(event){{\n{}\n}}", handler.value);
+        if let Some(finding) =
+            javascript_error(&source, &format!("{entry} {} handler", handler.key), false)
+        {
+            out.push(finding);
+        }
+    }
+    if name == "script" {
+        let kind = attr(attrs, "type");
+        if !script_is_executable(kind, attr(attrs, "language")) {
+            return None;
+        }
+        if kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("importmap")) {
+            if let Err(e) =
+                serde_json::from_str::<serde_json::Value>(script_text.unwrap_or_default())
+            {
+                out.push(error(format!(
+                    "{entry} importmap: invalid JSON ({e}). Fix the import map before launch."
+                )));
+            }
+            return None;
+        }
+        let module = kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("module"));
+        if let Some(src) = attr(attrs, "src") {
+            return Some((src, true, module));
+        }
+        *script_number += 1;
+        if let Some(finding) = javascript_error(
+            script_text.unwrap_or_default(),
+            &format!("{entry} inline script {script_number}"),
+            module,
+        ) {
+            out.push(finding);
+        }
+    } else if name == "link"
+        && attr(attrs, "rel").is_some_and(|rel| {
+            rel.split_ascii_whitespace()
+                .any(|word| word.eq_ignore_ascii_case("stylesheet"))
+        })
+    {
+        return attr(attrs, "href").map(|href| (href, false, false));
+    }
+    None
+}
+
 fn findings_with(
     root: &Path,
     entry: &str,
@@ -179,56 +236,15 @@ fn findings_with(
         if template_depth > 0 {
             return;
         }
-        for handler in attrs
-            .iter()
-            .filter(|a| !a.duplicate && is_handler_name(&a.key))
-        {
-            let source = format!("function __handler(event){{\n{}\n}}", handler.value);
-            if let Some(finding) =
-                javascript_error(&source, &format!("{entry} {} handler", handler.key), false)
-            {
-                out.push(finding);
-            }
-        }
-        let mut asset = None;
-        let mut module = false;
-        if name == "script" {
-            let kind = attr(&attrs, "type");
-            if !script_is_executable(kind, attr(&attrs, "language")) {
-                return;
-            }
-            if kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("importmap")) {
-                if let Err(e) =
-                    serde_json::from_str::<serde_json::Value>(script_text.unwrap_or_default())
-                {
-                    out.push(error(format!(
-                        "{entry} importmap: invalid JSON ({e}). Fix the import map before launch."
-                    )));
-                }
-                return;
-            }
-            module = kind.is_some_and(|t| t.trim().eq_ignore_ascii_case("module"));
-            if let Some(src) = attr(&attrs, "src") {
-                asset = Some((src, true));
-            } else {
-                script_number += 1;
-                if let Some(finding) = javascript_error(
-                    script_text.unwrap_or_default(),
-                    &format!("{entry} inline script {script_number}"),
-                    module,
-                ) {
-                    out.push(finding);
-                }
-            }
-        } else if name == "link"
-            && attr(&attrs, "rel").is_some_and(|rel| {
-                rel.split_ascii_whitespace()
-                    .any(|word| word.eq_ignore_ascii_case("stylesheet"))
-            })
-        {
-            asset = attr(&attrs, "href").map(|href| (href, false));
-        }
-        if let Some((url, script)) = asset {
+        let asset = authored_asset(
+            &name,
+            &attrs,
+            script_text,
+            entry,
+            &mut script_number,
+            &mut out,
+        );
+        if let Some((url, script, module)) = asset {
             match local_asset(root, url) {
                 Ok(Some(path)) => {
                     let generated =

From cbb6600f8574106a246836d89fa0209350163e4f Mon Sep 17 00:00:00 2001
From: Wanjun Gu <wanjun.gu@ucsf.edu>
Date: Mon, 12 Oct 2026 18:06:53 -0700
Subject: [PATCH 26/26] test(extensions): wait for the dialog overlay before
 clicking outside

---
 .../extensions/extensionsDialogFocus.browser.test.tsx           | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ui/desktop/src/components/extensions/extensionsDialogFocus.browser.test.tsx b/ui/desktop/src/components/extensions/extensionsDialogFocus.browser.test.tsx
index 3ba480c54..21e8963f4 100644
--- a/ui/desktop/src/components/extensions/extensionsDialogFocus.browser.test.tsx
+++ b/ui/desktop/src/components/extensions/extensionsDialogFocus.browser.test.tsx
@@ -297,7 +297,7 @@ describe('keyboard focus returns to Add after a dialog closes (V3-R3-2)', () =>
     try {
       await pickByKeyboard(tab, EXTENSIONS_COPY.browse);
       // A press on the scrim dismisses an `info` dialog; the window corner is the scrim.
-      await tab.mouse.click(5, 5);
+      await tab.locator('[data-slot="dialog-overlay"]').click({ position: { x: 5, y: 5 } });
       await tab.getByRole('dialog').waitFor({ state: 'detached' });
       await tab.waitForTimeout(150);
       expect((await focused(tab)).tag).toBe('BODY');