feat(cli): report workspace health in boss status and add boss doctor

[Vidhaankhare16]

Refs #418

boss status says it "Queries status and health of the running BOSS Console instance", but it only reports version, platform, project and memory. When the watchdog stops a plugin, the browser engine is missing or stuck, or an MCP fault is withholding tools, the only signal is a toast, a dialog or the bottom status bar. An agent driving BOSS from a terminal sees "running": true and nothing else. #418 asks for "one readable error" in that situation.

Change

• boss status --json gains an additive health object: degraded, findings (area, severity, code, summary, optional subject and remedy), unchecked and partial. Human boss status gets one Health: line. Exit codes are unchanged.
• New boss doctor [--json] prints the same report, one line per finding with a suggested next step. Exit 0 when healthy, 2 when degraded, 1 when BOSS is not running.
• doctor is added everywhere a subcommand has to be listed: createBossCLI, the headless gate in CliBootstrap.isHeadlessCli, OsOpenArguments.CLI_SUBCOMMANDS, and the three launchers.

Findings come from state BOSS already keeps:

Area	Source	Severity
plugins	sandbox watchdog disables, and NEEDS_ATTENTION rows from the #454 health model, across open windows	warning
browser	no usable engine installed (FluckEngine.resolveEngineDir)	warning
browser	FluckEngine.initError, or the wedge detector's exhausted verdict	critical
mcp	killSwitchFault and policyFault	critical when every tool is withheld, otherwise warning

It is read-only: nothing is enabled, reloaded or rewritten, and no recovery action is exposed over IPC. It does not fix the failures listed in #418, so #394, #399 and #410 stay open.

Notes for review

• The snapshot code in currentHealthAction moved unchanged into currentPluginHealth(manager), which the feat(plugins): add health and recovery center #454 dialog and this report now share.
• Each window registers a health source where its DefaultPlugin is created and removes it before the plugin is disposed. DefaultPlugin's init has already created the manager by then, so startup order is unchanged. With no window open, plugins are reported as unchecked.
• The engine check does not use isEngineHealthy(), which is also false for an engine that is only closed and will be recreated.
• Each area is read separately. An exception or linkage error marks that area unchecked instead of failing boss status. Plugin health goes further: it has one source per open window and each window source is contained on its own, so one window that throws cannot discard another window's findings. The area is unchecked only when no window could be read, and partial when some were read and some threw.
• Faults other than an unreadable file map to a warning without listing their types, so the provider-level policy fault in feat(mcp): trust a whole plugin's tools at once, not one at a time #542 is still reported if that lands first.
• buildStatusResponse takes its health JSON as a parameter, with the collector as the default, so a test can check the real response rather than a replaced one.
• OsOpenArgumentsTest compared CLI_SUBCOMMANDS with the text of BossCommand.kt, which cannot see a subcommand declared in its own file. It now uses createBossCLI().registeredSubcommands().

Builds on #454 (@Ayush04-C) and #349 (@Kanakk23), and complements #436 (@Lavish-Bhatti) and #544 (@aryanbajaj868's work from #526). Issue by @surfthewave-commits.

Limits

• Any finding, warnings included, makes boss doctor exit 2. On a fresh install, or where the browser engine is never downloaded, it exits 2 with browser_engine_not_installed until the engine is present. That is item 4 of Agent operator dogfood: failures humans rarely hit #418 made visible.
• A plugin stopped in one window and healthy in another is reported once, without naming the window.
• unchecked does not carry the error; the collector logs it.
• Fault messages are passed through as BOSS writes them.
• refactor(startup): split monolithic main.kt into modular startup phases #450 has landed, moving the headless CLI dispatch out of main.kt into startup/CliBootstrap.kt. This branch is rebased onto it, so main.kt is now untouched by this PR and the doctor registration lives in CliBootstrap.isHeadlessCli.
• Open PRs touching the same files, with no function-level overlap: feat(cli): add plugin init, validate, and link commands with dev hot-reload #468 changes the same subcommand lines in main.kt, OsOpenArguments.kt, docs/CLI.md and all three launchers, and also touches BossCommand.kt and SingleInstanceManager.kt; fix(mcp): publish a tool's readOnly declaration on the discovery channel #496 touches BossCommand.kt and SingleInstanceManager.kt; fix(cli): make the shims and the deep-link handler agree on parameter names, encoding and validation #527 the launchers; fix(microkernel): mode startup and runtime reliability #485, feat(logging): let the host write a rotated log file, gated by its own level and reachable from the environment #544 and Add a floating BOSS pet for task/agent status (#386) #426 main.kt, which this PR no longer edits; fix(browser): actually warn before downloading an executable file #484 FluckEngine.kt; Move a tab between running workspaces #284 BossAppStartupEffects.kt.

Validation

Windows 11, Temurin 17 (as in CI), dev @ 109fb083.

• Full :composeApp:desktopTest on the final code: 4577 tests in 476 classes, 15 skipped, 2 failures. Both failures need a Windows privilege this machine does not grant: DesktopFileScannerTest and DiscardDownloadContainmentTest create symlinks and fail with A required privilege is not held by the client. Every other test passes, including the new StatusHealthWiringTest.
• ktlintCheck and detekt report nothing.
• Manual run of the built jar with an isolated user.home:
  • BOSS not running: status and doctor exit 1 with the error on stderr only.
  • Clean profile with no browser engine downloaded: status exits 0 with Health: 1 problem; doctor exits 2 with a browser_engine_not_installed warning whose suggestion is the engine's own advice, and lists plugins as not checked, because a signed-out BOSS has no window yet.
  • Truncated mcp-disabled-tools.json and mcp-tool-policy.json: doctor exits 2 with mcp_policy_unreadable and mcp_tools_withheld, one line each, including the kill-switch message that contains a line break; status still exits 0.
  • boss.bat doctor and boss.ps1 doctor --json forward the command and return 2.
• Not run: macOS, Linux, or a signed-in build with a real watchdog stop.

No merge or auto-merge is authorized.

Review follow-up (2026-09-13)

Original health model, CLI, source wiring and initial tests are by @Vidhaankhare16; foundation credit to @Kanakk23 (#349) and @Ayush04-C (#454) remains above. Agent commit bb0cf4343 separates read-only cache inspection from startup repair recording and qualifies unchecked human reports, with regression tests. These repairs are agent work, not original contributor credit.

Not ready: one throwing window source still discards other windows' plugin health snapshots; preserve successful findings with explicit partial coverage. Kotlin tests, ktlint and detekt were queued under the shared local build lock but did not start, and hosted CI requires maintainer approval. Shell harness and diff checks pass. The new regressions and extracted-function detekt baseline need exact-head validation. See the author-facing review handoff for evidence and required cases.

[kshivang]

@claude Please review workspace health/status and doctor at 9a826c8 against dev. Focus on actual health sources, lifecycle registration/removal, IPC behavior, diagnostic safety and meaningful tests. This is the first review request for this head.

[claude]

Claude finished @kshivang's task in 6m 36s —— View job

---

Review: workspace health, boss status health, boss doctor @ 9a826c8

• Gather context (diff, new files, surrounding subsystems)
• Health sources: are they the right signals, read safely?
• Lifecycle: per-window source registration / removal
• IPC behavior (status response shape, timeouts, size)
• Diagnostic safety (side effects, message pass-through, path/content disclosure)
• Tests: do they pin behavior that matters?

The shape of this is right: a pure report function, injectable sources, containment per area, an additive wire contract, and a CLI that reads nothing but the health object. Below are one correctness finding I'd want fixed before merge, two design questions about what "degraded" means, and three smaller items.

---

1. The browser probe is not read-only on macOS, and can burn a one-shot repair budget

currentBrowserEngineHealth() calls FluckEngine.resolveEngineDir() with its default argument (composeApp/src/desktopMain/kotlin/ai/rever/boss/health/WorkspaceHealthCollector.kt:76). That default is cacheIsHealthy() → ChromiumAutoDownloader.isChromiumInstalled(), which is not a predicate: on macOS, when the cached engine still declares CFBundleURLTypes/CFBundleDocumentTypes, it calls recordRepairAttempt() and writes ~/.boss/boss-chromium.types-repair (ChromiumAutoDownloader.kt:229-251).

That marker is the one-attempt-per-version bound AGENTS.md documents for the engine-bundle repair. The health collector spends it without downloading anything, and the window is real rather than theoretical:

• SingleInstanceManager.acquireLock() → startServer() publishes the channel at main.kt:457, so STATUS is answerable from that point on.
• The startup engine check is ~290 lines later at main.kt:745.

A boss doctor (or any boss status) served in between makes the collector the first caller in the process. It records the attempt, reports the engine as browser_engine_not_installed, and downloads nothing — and then main.kt:745 asks again, sees repairAlreadyAttempted(), logs "keeping it", and skips the re-download. The hijacking engine stays, on every launch after that. It also re-logs a WARN per status query in the already-repaired state.

This also makes the docs claim in docs/CLI.md ("Both commands are read-only: they never change plugin, browser or MCP state") depend on a main.kt ordering rather than on the code. Suggested fix: split isChromiumInstalled() into a pure predicate plus the repair-recording wrapper and pass the pure value as resolveEngineDir(cacheHealthy = …), with a test asserting a health collection never touches the marker. Fix this →

2. Any warning makes the workspace "degraded", so the exit code is permanently 2 on many installs

WorkspaceHealthReport.degraded is findings.isNotEmpty() and BossDoctorCommand.kt:38 exits 2 on that. The PR lists this under Limits, but I'd push back on it rather than accept it: browser_engine_not_installed is the normal steady state for any install that never downloaded the engine, so boss doctor exits 2 forever and boss status prints Health: 1 problem forever. An exit code that is always 2 is one agents learn to ignore, which defeats the purpose of adding it.

The severity enum already carries the distinction. Exiting 2 only when something is critical (with warnings still listed, and a --strict flag if the current behaviour is wanted) would keep the code meaningful without hiding anything. Fix this →

3. An all-unchecked report prints "No problems found." and exits 0

formatDoctorReport (BossDoctorCommand.kt:64) prints No problems found. whenever findings is empty, then appends Not checked: …. If all three sources fail — exactly the case the containment in WorkspaceHealthCollector.read exists for — the tool reports a clean bill of health and exits 0, and "degraded": false says the same to a script. The KDoc's "neither healthy nor degraded" is the right intent, but neither the wire field nor the exit code can express it.

At minimum the wording should not claim a clean result when areas were skipped. Worth deciding, too, whether all-unchecked deserves its own exit code, since "plugins unchecked because no window is open" is the common benign case and "every source threw" is not.

Related, in the same function: the human report branches on findings, but the exit code branches on degraded (BossDoctorCommand.kt:85). A future BOSS that sets degraded: true off something other than findings makes boss doctor print "No problems found." and exit 2. Fix this →

4. One window's failure blanks the plugins area for every window

WorkspaceHealthSources.pluginSnapshots() is pluginSources.values.map { it() } (WorkspaceHealthSources.kt:35), and the collector contains the whole call. So with three windows open, one source throwing (a manager mid-dispose, say) turns plugins into unchecked and silently discards the findings the other two windows would have contributed — the "watchdog stopped a plugin" case that motivated the feature. The containment decision is documented, but per-source would be strictly better: keep what could be read, and only mark unchecked when nothing could. Fix this →

5. Fault text reaches the IPC response and stdout raw and unbounded

killSwitchFinding uses fault.message as the summary (WorkspaceHealth.kt:202). For PersistedSetUnreadable, error is t.message from json.decodeFromString (McpToolRegistryImpl.kt:1001), and kotlinx appends the offending document to a malformed-input error — the same property this repo's AGENTS.md warns about for Supabase payloads. So the contents of mcp-disabled-tools.json can be inlined into the status response and then re-flowed onto one line by text(). The file holds tool names rather than secrets, so this is a bounding issue rather than a leak, but the messages also carry absolute paths (hence usernames), and EngineInitError.Other passes e.message through verbatim.

Suggest bounding summary length — buildLlmTokenResponse in the same file already does .take(180) on an error message for this reason. The 4 MB MAX_DATA_RESPONSE_BYTES cap is the only limit today. Fix this →

---

What I checked and found sound

• Lifecycle. Registration sits after DefaultPlugin(...) (so the manager exists) and unregistration is the first statement of onDispose, before plugin.dispose() — the ordering the comment claims. unregisterPlugins using ConcurrentHashMap.remove(key, value) with the captured lambda instance is the right shape for a keyed DisposableEffect that can re-run for the same windowId, and WorkspaceHealthSourcesTest pins exactly that. No leak beyond one entry per live window.
• Thread safety. The IPC handler thread reads only StateFlow.value and PluginSandboxManager.disabledPlugins, which is a ConcurrentHashMap.newKeySet (PluginSandboxManager.kt:184). No lock is taken on the read path, so a status query cannot deadlock behind the UI thread or a plugin load — worth keeping that way if currentPluginHealth grows.
• IPC additivity. health is added inside the existing buildJsonObject, exit codes unchanged, and healthSummaryOf returns null for a response without the field, so a new CLI against an old BOSS prints no Health: line rather than a wrong one. BossDoctorCliTest covers both directions.
• Headless path. BossDoctorCommand imports nothing but SingleInstanceManager and kotlinx-json, so the headless gate in main.kt does not drag FluckEngine into a GUI-less JVM. Good, and easy to regress.
• The currentPluginHealth extraction is behaviour-preserving for currentHealthAction, and pulling it out of composition is what makes it callable off the UI thread.
• OsOpenArgumentsTest asking createBossCLI().registeredSubcommands() instead of regexing BossCommand.kt is a real improvement — the old test structurally could not see a subcommand in its own file.
• Launchers propagate the code (exec in scripts/boss, exit /b %ERRORLEVEL% in boss.bat), and doctor is in the dispatch branch, not just the help text, in all three.
• Docs are unusually complete for a wire contract (codes listed, unchecked explained, exit 2 scoped to doctor), and no em-dashes were added.

Smaller notes

• pluginFindings dedupes attention rows with distinctBy { it.pluginId to it.detail } (WorkspaceHealth.kt:143), so one plugin reported with different details in two windows yields two findings for one plugin. The PR's "reported once" limit holds only for identical details.
• StatusHealthWiringTest proves the field is wired but always injects healthJson, so nothing exercises the default — the real WorkspaceHealthCollector(). A smoke test that collect() with default sources neither throws nor writes anything would cover both the wiring and finding 1.
• The headless set in main.kt:252 is deliberately a subset of the registered subcommands, so the new OsOpenArgumentsTest equality cannot pin it; a subset assertion would still catch a typo there.
• PluginHealthSnapshot.sandboxDisabledPluginIds is derived by filtering states.keys, so a watchdog-disabled plugin absent from pluginStates is not reported. Same as the existing dialog, so not a regression — just not a guarantee the report can make.

I did not run Gradle in this environment, so ktlintCheck, detekt and desktopTest are unverified here; I reviewed against the PR's own Windows run.
· branch feat/workspace-health-doctor

[kshivang]

@Vidhaankhare16 Reviewed against dev e1926cc6f; current Claude review: #579 (comment).

I pushed bounded agent fixes in bb0cf4343 (separate from your contribution):

• Health cache inspection no longer invokes the repair-recording path. Startup retains the same recording behavior through the shared chromiumInstalledAt predicate. The regression builds a disposable stale macOS bundle, checks repeated read-only probes leave its repair marker absent, then checks startup still records exactly once. No real profile or engine was touched.
• Human status names unchecked areas; doctor qualifies incomplete reports and does not say no problems when degraded=true has no details. Added actual CLI/socket cases. Existing warning/exit-2 policy remains as your documented design; changing it to critical-only is not a correctness requirement.
• The existing ReturnCount baseline follows the extracted cache predicate; no new class-wide suppression.

Outstanding author issue: WorkspaceHealthSources.pluginSnapshots() maps all windows without per-source containment. One throwing source discards successful snapshots from other windows, so a watchdog-stopped plugin in window A disappears when window B's source throws. Please preserve successful snapshots while explicitly reporting partial coverage, and test a failing source beside a stopped-plugin source. Do not silently label partial results complete. This is independent of the new read-only repair.

Validation blockers are separate: shell harness and git diff --check pass. Gradle tests plus ktlint/detekt were requested through the shared build-lock wrapper, but waited without starting; no Kotlin success is claimed. The expanded validation request includes WorkspaceHealth*, BossDoctorCliTest, StatusHealthWiringTest, OsOpenArgumentsTest and ChromiumAutoDownloaderTest. Hosted Build & Test run 34601195267 is action_required, a maintainer approval gate, not a failing assertion. Please validate the pushed tests and baseline identity when a runner is available, including the exact final head. Current code paths were inspected, but the candidate repairs are not represented as test-validated.

Optional diagnostic-length limits and unknown-health exit semantics remain review notes, not requests to redesign this feature. After this bounded repair attempt, the partial-window correctness case and required validation remain unresolved, so this is NOT ready; converting to draft under the handoff policy. Your implementation and authorship, including credit for #349/#454 foundations, are preserved. No merge or auto-merge.

[Vidhaankhare16]

Thank you for bb0cf4343, and for fixing both of those yourself rather than bouncing them back. I have rebased onto it rather than over it: your commit is in the history as f9c710e3 after the rebase, authored by you, and I have left both of its fixes untouched. isChromiumInstalledReadOnly() is still what the health probe calls, isChromiumInstalled() still owns the one-shot repair marker, and your test read-only cache inspection leaves the startup repair attempt available passes on the rebased head. I have also taken your ruling on the exit-code question and changed nothing there.

On the one outstanding defect you named: pluginSnapshots() now contains each window source individually instead of mapping them in one expression. Every snapshot that could be read is kept, each failure is counted, and each failure is logged through BossLogger with LogCategory.SYSTEM the same way the collector's unreadable() already logs an unreadable area. LinkageError is caught beside Exception for the same reason the collector catches it. A watchdog-stopped plugin in window A now survives window B's source throwing.

Preserving those snapshots meant the report needed a way to say the coverage was incomplete, because unchecked is binary per area and cannot express it. Rather than overload unchecked, I added an additive partial set beside it. unchecked keeps its exact meaning, nothing could be read at all; partial means an area was read from several sources and some of them failed, so the findings listed are real but do not cover the area. An area is never in both: if every window source fails, nothing was read, so the area is unchecked and not partial. Today only plugins can be partial, since it is the only area with one source per window.

Partial coverage is stated in words, not just on the wire. boss doctor prints a Partially checked: plugins. Some sources could not be read, so problems there may be missing. line, and it no longer prints No problems found. when an area is partial; it prints No problems found in checked areas. boss status appends partially checked: plugins to its Health: line. Neither affects the exit code, matching how unchecked already behaves.

The partial field is additive in both directions and docs/CLI.md documents it with the rest of the wire contract. A reader that does not know the field sees exactly what it saw before, and both CLI commands read an absent partial as empty, so an old CLI against a new BOSS and a new CLI against an old BOSS both still parse. There is a test for that second direction.

The test you asked for is a failing window source does not hide a stopped plugin in another window in WorkspaceHealthSourcesTest. It registers a real failing source beside a real source reporting a sandbox-stopped plugin, runs them through the actual WorkspaceHealthCollector, and asserts all three things: the stopped plugin is still reported, plugins is not unchecked, and the report declares plugins partial. Alongside it: a sources test that a failing source is counted while the others are still read (covering both Exception and LinkageError), collector tests that snapshots survive a failing source and that all-sources-failed is unchecked rather than partial, report and JSON tests for the partial semantics, and four BossDoctorCliTest cases covering the doctor line, the status line, both qualifiers together, and the absent-field back-compatibility case.

The branch is also rebased onto dev at 109fb083. That was forced by #450 landing, which moved the headless CLI dispatch out of main.kt; main.kt was the only conflicting file. doctor now joins the headless command set in CliBootstrap.isHeadlessCli instead, CliBootstrapTest pins it there, and main.kt is now byte-identical to dev. OsOpenArguments.CLI_SUBCOMMANDS is unaffected by the move and OsOpenArgumentsTest still checks it against createBossCLI().registeredSubcommands().

Validation on the rebased head, JDK 17: :composeApp:desktopTest ktlintCheck detekt. 4577 tests across 476 classes, 15 skipped, 2 failures. Both failures are environmental on my Windows machine and fail identically on untouched dev: DesktopFileScannerTest > directoryHasChildren follows a symlink to a non-empty directory and DiscardDownloadContainmentTest > a symlink inside staging pointing out is refused, both needing symlink creation privilege. ktlint and detekt are clean. As on the other PR, I have left this as a draft rather than flipping it myself, since you converted it under your own validation policy: tell me if you would like it marked ready for review, or flip it yourself. No merge or auto-merge is authorized.

[Vidhaankhare16]

Rebased onto the current dev at f91633d3. This PR reported mergeable: CONFLICTING because dev was rewritten upstream rather than fast-forwarded: 109fb083, the commit this branch was previously rebased onto, is no longer an ancestor of dev, and the same merged PRs now appear under new SHAs (for example #450 as 2197b80d and #505 as f91633d3). The rebase used git rebase --onto origin/dev 109fb083, which replays only this branch's own three commits.

Your commit is preserved. fix(cli): keep health inspection read-only and qualify unchecked reports is now cda502a9, still authored by you; I confirmed it was present in the branch history before pushing. Otherwise no source change: the diff is the same 28 files and the same +1558/-53 as before the rebase, with identical file-set membership. New head is 698b840d. I am stating that explicitly because you asked that no further source change be made just to trigger CI: this push was only to restore mergeability after the upstream rewrite.

Validation on 698b840d, Windows, JDK 17: 4577 tests, 476 classes, 15 skipped, 2 failures. Both are the environmental pair this PR has disclosed throughout, DesktopFileScannerTest and DiscardDownloadContainmentTest, each failing with java.nio.file.FileSystemException when creating a symlink, which needs a privilege this machine does not grant. :composeApp:ktlintCheck and :composeApp:detekt both ran and passed; the only failing task was :composeApp:desktopTest. Not run on macOS or Linux.

No merge or auto-merge is authorized.

[kshivang]

@claude Please review current head 43d5688 against current dev, focusing on the latest contributor revisions and prior handoff. One focused review requested for this sweep.

[kshivang]

@Vidhaankhare16 Your follow-up at 43d56885 fixes the previous substantive handoff: each window source is contained independently, findings from responding windows survive, and partial accurately distinguishes incomplete coverage from wholly unchecked coverage. The additive JSON, human doctor/status qualifiers, registration ownership and headless CliBootstrap wiring are coherent. The original read-only cache repair is preserved; no new source edits were made by this sweep.

A focused compiled probe of the exact current WorkspaceHealthSources.kt passed: successful snapshots survive both Exception and LinkageError from other windows, failure counts are retained, and an old unregister cannot remove a replacement source. The probe uses a minimal snapshot/logging double, so it is not a full host/collector integration test. I inspected the contributor collector/report/CLI tests and actual cache-read implementation; I did not run a new full Gradle suite. The current head merges cleanly in a non-mutating simulation against dev.

The remaining gate is required validation, not an established author defect. I approved current-head Build & Test run https://github.com/risa-labs-inc/BossConsole/actions/runs/34841797578. Shell/version checks have passed, but build/test, code quality, compatibility and contracts remain queued at this disposition. Prior Windows evidence is retained, including the disclosed symlink-privilege failures; I am not reclassifying those as regressions here.

The latest completed Claude review predates this repair. Its per-window loss and read-only-cache concerns are addressed; diagnostic length limits and unknown-health exit semantics remain optional follow-ups, not reasons to redesign this feature. One fresh review was requested for this head and remains pending.

Converting to draft solely for the incomplete current-head validation under the sweep policy. Next steps: let the approved run finish, resolve any real failures with logs and baseline comparison, review the requested Claude result, then recheck current dev and mark ready. No source push is requested merely to trigger CI. Manual follow-up: boss status/boss doctor with a stopped plugin in one window and an unreadable second source, partial/all-unchecked output, and confirmation that status inspection leaves browser repair available. No recovery mutation or live app test was performed. Your original contribution and the separately authored earlier agent repairs remain credited.

[claude]

Claude finished @kshivang's task in 6m 51s —— View job

---

Review: workspace health, boss status health, boss doctor @ 43d5688

• Gather context (diff vs base, new commits since last review)
• Per-window containment + the new partial field
• Read-only cache inspection fix (abf923a)
• CLI / wire contract and back-compat
• Tests: do they pin what matters?

The two blocking items from the last sweep are closed, and closed properly. Per-window containment keeps what it can read and says so on the wire rather than overloading unchecked; the read-only engine probe is sound on both of its branches, which is more than the fix strictly promised. One new correctness item below (small, concrete), plus notes.

Base note: origin/dev in this checkout is a depth-1 shallow ref (5dc8211, #593) and this branch's base is 5a2e818 (#661), so there is no merge base to diff from. I reviewed git diff 5a2e818...HEAD - the branch's own three commits - which is the PR diff (28 files, +1558/-53, matching the reported figures).

---

1. boss status and boss doctor disagree on degraded: true with no findings

abf923a hardened the doctor for a report that declares itself degraded without details (BossDoctorCommand.kt:69, tested at BossDoctorCliTest.kt:114-118). healthSummaryOf - the Health: line the same file serves to boss status - never reads that field:

val count = health.findings().size          // BossDoctorCommand.kt:98
…
count > 0 -> "${problemCount(count)} (run 'boss doctor')"
qualifiers.isEmpty() -> "OK"                // ← reached with degraded:true, findings:[]

So for {"degraded":true,"findings":[],"unchecked":[]}, boss status prints Health: OK while boss doctor on the same response prints "BOSS reports degraded health without finding details." and exits 2. Two commands, one instance, opposite stories - the shape of defect the Settings > Browser / Default Apps disagreement in AGENTS.md is recorded for.

Not reachable against this host (WorkspaceHealthReport.degraded is findings.isNotEmpty()), which is exactly why the doctor branch is forward-compat hardening - and the status line is the half that did not get it. One-line fix: let isDegraded() drive the count == 0 case in healthSummaryOf, and add the status mirror of the existing doctor test. Fix this →

2. The read-only probe is correct, and its two log lines are not

Verified rather than assumed, because the fix only removed the write:

• currentBrowserEngineHealth passes isChromiumInstalledReadOnly() into resolveEngineDir(cacheHealthy = …), so cacheIsHealthy() (the recording variant) is never reached from the health path.
• The other branch is clean too: noUsableEngineReason() → engineLocations() (BossDirectories.resolve + getBundledChromiumPath) → isValidChromiumDir / chromiumVersionMismatch, all reads. Had it gone through getChromiumDir() (FluckEngine.kt:1304, which calls resolveEngineDir() with the default) the marker would have been spent by the other door.
• The only surviving recording callers are ChromiumBootstrap.kt:44 and FluckEngine.cacheIsHealthy(), i.e. startup and engine creation - which is the split the fix intended.
• recordRepair has no default, so a new caller has to answer the question. Right call, same discipline as blockingDependentsOf's isDisabled.

What is left is log accuracy. chromiumInstalledAt still logs, on a read-only probe of a stale macOS bundle, either "Cached Chromium still registers itself as a browser, will re-download" (nothing will - the probe returns false and downloads nothing) or, once startup has spent the attempt, a WARN per status query. An agent polling boss doctor writes a WARN a tick into the host log, and the INFO line states an action that is not going to happen. Cheapest fix is to gate those two lines the same way the write is gated, or hand the function a log sink alongside recordRepair. Fix this →

3. unchecked still conflates "no window open" with "every window source threw"

plugins?.snapshots?.takeIf { it.isNotEmpty() } (WorkspaceHealthCollector.kt:34) sends both cases to unchecked, and docs/CLI.md documents the first as the normal reading ("including plugins while no BOSS window is open"). The first is benign and the common case; the second means every open window's manager threw, which is a fault. failedSources now distinguishes them and the report drops it on the floor (tested, deliberately, at WorkspaceHealthCollectorTest.kt:67).

Not a defect in what is documented - just the one place where the new data could answer a question the report still cannot. A plugin_health_unreadable finding, or listing the count, would make the difference visible without touching the unchecked/partial split.

4. The "empty means unchecked" rule lives in the collector, not in the model

workspaceHealthReport(plugins = emptyList()) reports plugins as fully checked and healthy - the null-means-unchecked encoding is only honoured because WorkspaceHealthCollector maps empty → null first. WorkspaceHealthReportTest.inputs defaults plugins to emptyList(), so the test helper's own default is the shape that would misreport if a second caller of the pure function ever appeared. Passing PluginSnapshotRead into workspaceHealthReport (it already takes pluginSourceFailures from it) would put both halves of that read in one place.

5. Carryover, unchanged by design

Prior item 5 (unbounded fault text) is still open and was ruled an optional note, so just the one-line restatement: killSwitchFinding uses fault.message verbatim (WorkspaceHealth.kt:218), and for PersistedSetUnreadable that embeds a kotlinx malformed-input message, which carries the offending document - so mcp-disabled-tools.json contents can ride the STATUS response and boss doctor stdout, bounded only by MAX_DATA_RESPONSE_BYTES. buildLlmTokenResponse in the same file already .take(180)s for this reason. Prior item 2 (warning ⇒ exit 2) stands as the documented design per the maintainer's ruling.

6. One observation about "read-only", worth a sentence in the docs

The health probe can be the first thing in the process to touch FluckEngine: the single-instance server is published by acquireLock() at main.kt:283, and the first FluckEngine reference in main.kt is at 533, inside composition. FluckEngine's init runs BrowserSettingsManager.ensureLoaded() (a read - loadSettingsSync only reads) and startHostThemeObserver(), which creates a process-wide CoroutineScope and a permanent snapshotFlow collector. Nothing is written and setColorScheme is a no-op with a null engine, so the outcome is benign - but a status query arriving in that window does start the engine singleton's observer earlier than the app would have, which is slightly more than docs/CLI.md's "never change plugin, browser or MCP state" claims. Same class of thing for McpToolRegistryImpl, whose init reads the disabled-tools file (and deliberately does not call onFault from the constructor, so no status message is stolen).

---

What I checked and found sound

• Per-window containment (WorkspaceHealthSources.kt:59-74) is the right shape: LinkageError beside Exception, VirtualMachineError left alone, each failure logged with its windowId through BossLogger/LogCategory.SYSTEM, and the count returned rather than inferred. The registry iteration stays contained in the collector as belt-and-braces now that the inner loop cannot throw.
• partial is a genuinely additive field, not an overload of unchecked, and the invariant "never both" is enforced by construction (partial is only added when plugins != null) and pinned three ways - pure function, collector, and end-to-end through the real socket. a failing window source does not hide a stopped plugin in another window asserts all three things at once (finding survives, not unchecked, declared partial) using real sources through the real collector, which is the test the handoff asked for.
• Back-compat both directions. New CLI against an old BOSS: partialAreas() reads an absent key as empty and a BOSS that does not send partial is still read as fully checked pins Health: OK plus no "Partially checked". Old reader against a new BOSS: partial is a new key inside the existing object. HEALTHY in the test corpus deliberately omits the field.
• Human output does not claim a clean result it cannot support. No problems found. / No problems found in checked areas. - and note the assertion at BossDoctorCliTest.kt:157 works because the qualified string does not contain the unqualified one as a substring, which is easy to get wrong the other way round.
• ChromiumAutoDownloaderTest's new case is a real before/after regression, not a restatement: two read-only probes leave the marker absent, then a recording probe creates it exactly once, then inspect { error(...) } proves the one-shot holds. It builds a disposable stale bundle rather than touching a real engine.
• Lifecycle is unchanged from the version I checked last time and still correct: registration after DefaultPlugin(...) (manager already constructed), unregistration as the first statement of onDispose before plugin.dispose(), and remove(key, value) against the captured lambda identity.
• Thread safety of the off-UI read. currentPluginHealth reads StateFlow.values plus PluginCrashRegistry, whose _crashedPluginsMap is a ConcurrentHashMap explicitly documented "used by watchdog and non-UI queries", and PluginSandboxManager.disabledPlugins is a concurrent set. No lock on the read path, so a status query still cannot deadlock behind the UI thread.
• detekt baseline follows the extracted predicate's exact signature (one ReturnCount entry moved, Path is imported unqualified as the entry renders it), with no new class-wide suppression - which is what the handoff asked for.
• OsOpenArgumentsTest asking createBossCLI().registeredSubcommands(), CliBootstrap.isHeadlessCli carrying doctor with CliBootstrapTest pinning it, and all three launchers dispatching (not merely documenting) doctor - all still hold after the main.kt move. main.kt is untouched by this PR.
• Docs. partial is documented with the invariant, the additivity and the exit-code neutrality; exit 2 is scoped to doctor. git diff --check is clean and no em-dash was added to any .md.

Validation status

I did not run Gradle in this environment, so ktlintCheck, detekt and :composeApp:desktopTest are unverified here. Note for the handoff: the PR's validation log names head 698b840d, and the head under review is 43d5688 - the tree was replayed again onto a newer dev after that run. If the rebase was diff-preserving the result should stand, but the exact-head run the handoff asked for has not been reported for this SHA.
· branch feat/workspace-health-doctor

[Vidhaankhare16]

Run https://github.com/risa-labs-inc/BossConsole/actions/runs/34841797578 has completed. All ten checks are green on 43d56885aa7434858c40af9b1ec2836c684059c7: build-test on ubuntu, macOS and windows, code-quality, compatibility-test, BOSS AI contracts, Shell Script Tests, Database (pgTAP), version-check and build-summary. Required current-head validation was the gate you named, so I have marked this ready for review.

Rechecked against current dev, now 54ab77f6. The head still merges clean against it and is untouched, so the approval you granted covers exactly what is published.

Thank you for the compiled probe of WorkspaceHealthSources.kt. Confirming that successful snapshots survive a LinkageError as well as an Exception, and that an old unregister cannot remove a replacement source, goes past what my own tests establish, and the second of those is a case I had not covered.

The Claude review at this head

It closes both prior blockers and raises one new item. I would rather name it than let it pass quietly.

Item 1 is a real inconsistency, and I have reproduced it. healthSummaryOf derives the Health: line from the findings count alone and never reads degraded, while formatDoctorReport does. So for {"degraded":true,"findings":[],"unchecked":[]}, boss status prints Health: OK while boss doctor, reading the same response, prints "BOSS reports degraded health without finding details." and exits 2.

It is not reachable against this host. WorkspaceHealthReport.degraded is findings.isNotEmpty(), so that combination cannot be produced by the BOSS in this repo. It is forward-compat hardening, and abf923a gave it to the doctor half while the status half did not get it.

I have the fix written and validated, and I have deliberately not pushed it, because pushing discards the green run above and returns this PR to action_required. It is 3 files, +23/-1:

• healthSummaryOf gains one branch, ordered after the findings-count branch so it can only fire on an explicit degraded: true with no findings.
• One case in BossDoctorCliTest serves a single response to both commands and asserts they agree.
• docs/CLI.md gains the degraded bullet. It was the only field in that object with no description, and the doc now states the reading rule instead of leaving it implied.

Evidence, applied on top of 43d56885 on Temurin 17:

• Against the unpatched source the new test fails, and fails for the right reason: the assertion message is the status report showing Health: OK. 17 tests, 1 failure, no other case affected.
• With the fix, BossDoctorCliTest is 17 tests, 0 failures, 0 skipped.
• Full :composeApp:desktopTest: 4954 tests across 518 classes, 15 skipped, 2 failures, both the disclosed symlink-privilege ones on this Windows machine (DesktopFileScannerTest.directoryHasChildren follows a symlink to a non-empty directory and DiscardDownloadContainmentTest.a symlink inside staging pointing out is refused).
• :composeApp:ktlintCheck clean, :composeApp:detekt clean with an empty checkstyle report.

Your call. Say the word and I will push it here and we spend one more CI approval on it, or it lands as a follow-up and this merges on the run that is already green. I am not pushing it unilaterally, given you said no source push is requested merely to trigger CI and this cannot fire at runtime today.

The remaining Claude items

My reading, offered rather than asserted. Item 3, unchecked conflating "no window open" with "every window source threw", would be a genuine improvement and failedSources already carries the data, but it changes what the wire means and belongs in its own change rather than riding this one. Item 4 is a fair note that the empty-means-unchecked rule lives in the collector instead of the model. Item 5 is the unbounded fault text you already ruled an optional note. Item 6 observes that a status query can be the first thing to touch FluckEngine, which is benign but slightly more than docs/CLI.md's "never change plugin, browser or MCP state" claims; worth one doc sentence whenever this file is next open.

Not claimed

The manual pass you named remains unperformed: boss status and boss doctor with a stopped plugin in one window and an unreadable second source, the partial and all-unchecked output shapes, and confirming that a status inspection leaves browser repair available. No app was launched from here, and no recovery mutation was exercised.

No merge or auto-merge is authorized.

[kshivang]

@Vidhaankhare16 The required run is now green on exact head 43d56885aa7434858c40af9b1ec2836c684059c7. I verified the current Claude review, per-window source containment, ownership-safe unregister, read-only Chromium repair probe, partial/unchecked semantics and CLI routing. Current dev merges cleanly; its only change to a PR-touched file is unrelated detekt baseline entries. The headless launcher suite passes locally. No new source repair was needed in this batch.

The proposed degraded=true/empty-findings status consistency improvement is worthwhile follow-up, but the current host computes degraded from nonempty findings and cannot emit that shape. Please keep your prepared patch for a separate follow-up; it is not a reason to discard this validated head. The remaining log wording/repeated warning, singleton initialization, diagnostic bounds and all-unchecked distinction are recorded limitations, not new destructive health-read behavior. The read-only path never spends the repair marker. No repeated Claude request is needed.

Proceeding with a serialized final base/head/check refresh and squash merge into dev only. Original contribution credit and prior 7/10 rating are unchanged; earlier agent repairs are not scored as your new work. Manual checks still outstanding: partial/all-unchecked human output, stopped plugin in a second window, and confirming browser repair remains available after a health query. No live app or plugin was altered for this review.