Skip to content

doctor: audit all checks for standing warns — browser.opener still pins degraded on a headless host #137

Description

@pitimon

What

degraded (src/lib/doctor.js) now counts every warn and fail except a warn whose check marked it
advisory. Exactly one warn has been classified so far — queue.row_invariant's
row-invariant/malformed-row warn (#130 / PR #136). Nobody has audited the remaining checks for the
same property.

At least one of them provably has it.

The known instance: browser.opener on a headless host

buildBrowserOpenerCheck (src/lib/doctor.js:167-177) returns a permanent warn whenever
isHeadlessEnvironment (:212-217) is true — CI=true, HEADLESS=true,
TOKENTRACKER_HEADLESS=1, or Linux with no DISPLAY/WAYLAND_DISPLAY/WSL_DISTRO_NAME. The detail
line says "use --no-open or open the printed URL manually", and doing so does not clear the check —
the warn is a property of the environment, not of anything the operator left undone.

Reproduced on macOS by forcing the flag:

$ node bin/tracker.js doctor --json | jq -c '{degraded, degraded_checks}'
{"degraded":true,"degraded_checks":["ingest.transcript_suppressed"]}

$ CI=true node bin/tracker.js doctor --json | jq -c '{degraded, degraded_checks}'
{"degraded":true,"degraded_checks":["browser.opener","ingest.transcript_suppressed"]}

So on a headless server — the population most likely to consume doctor --json from automation —
degraded reads true on a perfectly healthy day. That is the exact failure #130 was filed to
remove, surviving in a different check. openwiki/cli-and-operations.md now says so explicitly
rather than implying the alert-wiring advice is general, but saying so is not fixing it.

Weaker sibling

notify.configured (src/lib/doctor.js:~423) warns for a user who deliberately runs without
notifications configured. Standing, and arguably a preference rather than a problem. Same question,
lower stakes.

Why this was not decided inside PR #136

Marking browser.opener advisory means making a severity call about code the PR author did not
write, under review pressure, with no test coverage for the headless path. The author declined on
record and narrowed the documentation instead. That is the right trade for one PR and the wrong
place to leave it permanently.

What this issue is asking for

Walk all nine checks in src/lib/doctor.js and decide, per warn rather than per check id, which are
standing conditions an operator cannot act on at read time. The per-warn distinction matters and is
not academic: queue.row_invariant emits two warns and only one of them qualifies — an earlier cut
of #136 stamped the flag per check id and silenced an actionable queue unreadable warn as a result.

Checks to rule on: runtime.node_version, browser.opener, runtime.dashboard_url,
runtime.http_timeout_ms, runtime.debug, fs.tracker_dir, fs.config_json, cli.entrypoint,
notify.configured, plus whatever buildDiagnosticsChecks can emit.

Worth adding alongside: a test that pins the headless path's contribution to degraded, whichever
way it is decided, since nothing covers it today.

Context

Raised by an independent review of PR #136 as its Finding 3. Closes nothing on its own; #136 is
mergeable without it.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions