fix(doctor): resolve CLIs via searchDirs, single-flight runs, admin-gate the group (#536 review)

- doctor probes each CLI's discovery.searchDirs when which misses and runs --version on the resolved path, so a service with a minimal PATH no longer reports installed CLIs as missing
- GET /api/doctor shares one in-flight run per category
- Diagnostics group hidden from non-admins in multi-user mode (_applyDoctorAdminGate)
- 500 uses INTERNAL_ERROR; a killed child reports 'timed out after 30 s'
- browser test blocks service workers so page.route() is reliable
- wiki: Diagnostics sentence

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JrzFKEdBLwVfu6ev2ZscJS

test/dependency-checker.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import { dependencyRegistry } from '../src/config/dependency-registry.js';
 import {
   detectEnvironment,
@@ -259,6 +259,53 @@ describe('checkTool with requireVersionMatch (generic binary names)', () => {
   });
 });
 
+describe('checkTool with searchDirs (service PATH is minimal)', () => {
+  const claudeLike: ToolDependency = {
+    ...tmuxTool,
+    id: 'claude',
+    label: 'Claude CLI',
+    resolvers: [
+      {
+        match: ['linux'],
+        resolver: { kind: 'path', bins: ['claude'], searchDirs: ['/home/u/.local/bin', '/opt/npm/bin/'] },
+      },
+    ],
+  };
+
+  it('finds a CLI that only lives in a searchDirs entry and runs --version on the absolute path', () => {
+    const runVersion = vi.fn(() => 'claude 2.1.0');
+    const host = fakeHost('linux', { fileExists: (p) => p === '/opt/npm/bin/claude', runVersion });
+    expect(checkTool(claudeLike, host)).toMatchObject({
+      status: 'ok',
+      path: '/opt/npm/bin/claude',
+      version: '2.1.0',
+    });
+    expect(runVersion).toHaveBeenCalledWith('/opt/npm/bin/claude', ['--version']);
+  });
+
+  it('still reports missing when neither PATH nor any search dir has it', () => {
+    expect(checkTool(claudeLike, fakeHost('linux'))).toMatchObject({ status: 'missing' });
+  });
+
+  it('prefers the PATH hit over a search dir', () => {
+    const host = fakeHost('linux', {
+      which: () => '/usr/bin/claude',
+      fileExists: () => true,
+      runVersion: () => '1.0.0',
+    });
+    expect(checkTool(claudeLike, host)).toMatchObject({ path: '/usr/bin/claude' });
+  });
+
+  it('carries each enabled CLI’s expanded discovery.searchDirs onto its registry row', () => {
+    const rows = dependencyRegistry().flatMap((t) => t.resolvers.map((r) => r.resolver));
+    const withDirs = rows.filter((r) => r.kind === 'path' && r.searchDirs?.length);
+    expect(withDirs.length).toBeGreaterThan(0);
+    for (const r of withDirs) {
+      if (r.kind === 'path') for (const d of r.searchDirs ?? []) expect(d.startsWith('~')).toBe(false);
+    }
+  });
+});
+
 describe('checkAll', () => {
   it('maps every tool to a result', () => {
     const results = checkAll([tmuxTool, msTool], fakeHost('linux'));

test/doctor-settings.browser.test.ts

@@ -49,7 +49,9 @@ describe('Diagnostics panel in a real browser', () => {
     server = new WebServer(PORT, false, true);
     await server.start();
     browser = await chromium.launch({ headless: true });
-    page = await browser.newPage();
+    // A controlling service worker can swallow requests before page.route() sees them, letting the
+    // real /api/doctor (a forked Node process) answer instead; block it so the stub is reliable.
+    page = await (await browser.newContext({ serviceWorkers: 'block' })).newPage();
     await page.goto(`http://localhost:${PORT}`, { waitUntil: 'domcontentloaded' });
     await page.waitForFunction(() => (window as any).app?.terminal, null, { timeout: 30000 });
     await page.evaluate(() => (window as any).app.openAppSettings());

test/routes/doctor-routes.test.ts

@@ -61,6 +61,26 @@ describe('GET /api/doctor', () => {
     const res = await app.inject({ method: 'GET', url: '/api/doctor' });
     expect(res.statusCode).toBe(500);
     expect(res.json().error).toContain('spawn blew up');
+    expect(res.json().errorCode).toBe('INTERNAL_ERROR');
+  });
+
+  it('single-flights: concurrent requests for a category share one run, and a later one runs again', async () => {
+    const releases: Array<(r: DependencyReportJson) => void> = [];
+    const runner = vi.fn<DoctorRunner>(() => new Promise<DependencyReportJson>((res) => releases.push(res)));
+    const { app } = await createRouteTestHarness((a) => registerDoctorRoutes(a, runner));
+    const first = app.inject({ method: 'GET', url: '/api/doctor' });
+    const second = app.inject({ method: 'GET', url: '/api/doctor' });
+    const other = app.inject({ method: 'GET', url: '/api/doctor?category=office' });
+    await vi.waitFor(() => expect(runner).toHaveBeenCalledTimes(2));
+    releases[0](REPORT);
+    expect((await first).statusCode).toBe(200);
+    expect((await second).statusCode).toBe(200);
+    expect(runner).toHaveBeenCalledTimes(2); // unfiltered (shared) + office
+    releases[1](REPORT);
+    await other;
+    runner.mockImplementation(async () => REPORT);
+    await app.inject({ method: 'GET', url: '/api/doctor' });
+    expect(runner).toHaveBeenCalledTimes(3);
   });
 
   it('multi-user: a non-admin is refused and nothing is probed', async () => {
@@ -112,6 +132,11 @@ describe('defaultDoctorRunner', () => {
     await expect(defaultDoctorRunner()).rejects.toThrow();
   });
 
+  it('reports a killed child (the 30 s timeout) as a timeout, not the raw command line', async () => {
+    respond(Object.assign(new Error('Command failed: node doctor --json'), { killed: true, signal: 'SIGTERM' }), '');
+    await expect(defaultDoctorRunner()).rejects.toThrow('timed out after 30 s');
+  });
+
   it('passes the child’s own error through when there is no report at all', async () => {
     respond(new Error('ETIMEDOUT'), '');
     await expect(defaultDoctorRunner()).rejects.toThrow('ETIMEDOUT');