feat(settings): codeman doctor in Settings → System → Diagnostics

[opticon454]

What

Surfaces codeman doctor in the web UI: Settings → System → Diagnostics → Run checks lists which agent CLIs, tmux, Node and the optional office tools are installed on the server, with versions, paths, required/optional, and the install hint for what is missing. Backed by GET /api/doctor[?category=core|office|other].

Design

• Out of process. The probe engine (checkAll) is synchronous (which + <bin> --version per tool), and CLAUDE.md is explicit that a sync call freezes the port while the process stays alive. So the route runs codeman doctor --json in a child of the same entry script (process.execPath + process.execArgv + process.argv[1], 30 s timeout) and parses the output. The CLI exits non-zero when a required tool is missing but still prints the report, so a non-zero exit with a valid report is a normal result.
• The runner is injected (registerDoctorRoutes(app, runner)), so route tests never spawn anything; the default runner's parsing is tested against a faked execFile, and the CLI contract it depends on is tested for real.
• Admin only in multi-user mode (the report names install paths and versions on the host), with real HTTP status codes (403/400/500).
• The UI is built with DOM nodes and textContent: paths and labels come from the host.

Tests

• test/routes/doctor-routes.test.ts (11): envelope, category pass-through and rejection of an unknown one without running anything, runner failure, multi-user gating, and the default runner (args, non-zero exit with a report, empty/non-JSON/wrong-shape output, the child's error passed through).
• test/doctor-cli-json.test.ts (1): spawns the real entry script with doctor --json --category core and checks the report.
• test/doctor-settings.browser.test.ts (2, real Chromium, /api/doctor stubbed at the network layer): renders status/version/path/install hint, shows a hostile label (<img onerror>) as literal text, and shows the server's error and re-enables the button.
• Full CI gate: typecheck, lint, format, public assets, catalogue and all unit/integration tests pass.

Merge order

Rebased onto 1.34.0. Independent of my other open PRs apart from adjacent insertions in config/test-suites.ts, docs/api-reference.md, routes/index.ts and server.ts (route registration), which will need a trivial rebase for whichever lands second. I will do that as they merge.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JrzFKEdBLwVfu6ev2ZscJS

[Ark0N]

Thanks a lot for this, @opticon454! It surfaces codeman doctor in Settings → System → Diagnostics, backed by a new GET /api/doctor that runs the probe in a child process so the synchronous engine never blocks the server. The out-of-process design, allowlisting the category before it reaches argv, rendering host strings with textContent (with the hostile-label test), and the injected runner in the route tests are all exactly how I would want this built.

A few things before it can go in:

1. Installed CLIs show as missing under a service (src/web/routes/doctor-routes.ts:49, src/utils/dependency-checker.ts:96). The child inherits the server's environment, and the doctor engine only looks on PATH via which. Under systemd/launchd that PATH is minimal, so CLIs installed in ~/.local/bin, ~/.npm-global/bin, nvm and so on come back missing with an install hint. The Run menu still finds them, because the CLI resolvers fall back to each entry's discovery.searchDirs and then a login shell. I reproduced it with my production unit's PATH: every CLI row reads missing, while the same server reports Claude and Codex available at ~/.local/bin through /api/claude/status and /api/codex/status. Could you make the doctor resolve CLI rows the way the run mode does? Preferred: carry cli.discovery.searchDirs onto the CLI rows' PathResolver in cliDependencyEntries(), probe <expanded dir>/<bin> when which misses, and run --version against the resolved absolute path (that also fixes the terminal codeman doctor). If you would rather keep the engine untouched, appending every enabled CLI's expanded searchDirs to the child's PATH in defaultDoctorRunner covers the panel. Please add a test for a CLI found only in a searchDirs entry.

2. Flaky browser test (test/doctor-settings.browser.test.ts:52). page.route() does not reliably intercept requests while the service worker controls the page. When it misses, the request hits the real route (which spawns the vitest worker with doctor --json) and the first case times out. It failed 1 of 2 runs here. Creating the page from browser.newContext({ serviceWorkers: 'block' }) held 10 runs out of 10.

3. Concurrent runs are unbounded (src/web/routes/doctor-routes.ts:37). Each request forks a full Node process. Two tabs or a script can stack them. Please single-flight it (share the in-flight promise per category, or answer 409 CONFLICT while one is running).

4. Hide the group from non-admins (src/web/public/index.html:2832). In multi-user mode a non-admin sees the group but can only get a 403. The other admin-only groups hide themselves (_applyMcpSyncAdminGate and friends, re-applied on the codeman:me event near the end of settings-ui.js). A matching _applyDoctorAdminGate() would keep it consistent.

Smaller things, which I can also do at merge if you prefer:

• src/web/routes/doctor-routes.ts:80: the documented table maps OPERATION_FAILED to 422 and INTERNAL_ERROR to 500, so for an explicit 500 please use INTERNAL_ERROR. When the 30 s timeout kills the child, a message like "timed out after 30 s" would read better than the raw Command failed: ... line.
• docs/wiki/Settings-Reference.md (### System): one sentence about the Diagnostics group.

Once 1 to 4 are in, I will take another look and merge. Thanks again, this is a really useful addition.

[opticon454]

Thanks for the thorough review. All four are in (db9a394):

1. Installed CLIs missing under a service: cliDependencyEntries() now carries each CLI's expanded discovery.searchDirs onto its PathResolver. When which misses, the doctor probes <dir>/<bin> and runs --version against the resolved absolute path, so the terminal codeman doctor is fixed too. New tests cover a CLI found only in a searchDirs entry, PATH winning over a search dir, and the registry rows carrying expanded dirs.
2. Flaky browser test: the page now comes from browser.newContext({ serviceWorkers: 'block' }).
3. Concurrent runs: single-flighted per category (callers share the in-flight promise), with a test.
4. Non-admins: added _applyDoctorAdminGate(), called when settings open and on codeman:me.

Smaller items: the 500 now uses INTERNAL_ERROR, a killed child reports timed out after 30 s, and the Settings Reference has a Diagnostics sentence.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JrzFKEdBLwVfu6ev2ZscJS

[Ark0N]

Merged in 1.35.0, thanks @opticon454! Running the doctor in a child process was the right call, and both review rounds came back fast. Applied on the way in (cf26853):

• The doctor now judges candidates the way the Run menu's resolver does: the PATH hit first, then each search dir, each one version-checked on its own. So a wrong grok or pi on the PATH no longer hides the real one in its install dir. A search-dir candidate has to be an absolute path to an executable regular file (it reuses the resolver's own isExecutableRegularFile).
• Probes pass killSignal: 'SIGKILL', so a --version that ignores SIGTERM can't hold the doctor for its whole runtime.
• A missing optional tool shows ○ instead of ✗ in the panel, like the terminal doctor.
• The README no longer claims parity with the Run menu, whose login-shell step finds nvm installs that the doctor doesn't.
• test/doctor-cli-json.test.ts is hermetic now (temp HOME, a PATH with only which and node), so the CI gate never runs the machine's installed agent CLIs.