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.
What
degraded(src/lib/doctor.js) now counts every warn and fail except a warn whose check marked itadvisory. Exactly one warn has been classified so far —queue.row_invariant'srow-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.openeron a headless hostbuildBrowserOpenerCheck(src/lib/doctor.js:167-177) returns a permanentwarnwheneverisHeadlessEnvironment(:212-217) is true —CI=true,HEADLESS=true,TOKENTRACKER_HEADLESS=1, or Linux with noDISPLAY/WAYLAND_DISPLAY/WSL_DISTRO_NAME. The detailline says "use
--no-openor 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:
So on a headless server — the population most likely to consume
doctor --jsonfrom automation —degradedreadstrueon a perfectly healthy day. That is the exact failure #130 was filed toremove, surviving in a different check.
openwiki/cli-and-operations.mdnow says so explicitlyrather 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 withoutnotifications configured. Standing, and arguably a preference rather than a problem. Same question,
lower stakes.
Why this was not decided inside PR #136
Marking
browser.openeradvisory means making a severity call about code the PR author did notwrite, 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.jsand decide, per warn rather than per check id, which arestanding conditions an operator cannot act on at read time. The per-warn distinction matters and is
not academic:
queue.row_invariantemits two warns and only one of them qualifies — an earlier cutof #136 stamped the flag per check id and silenced an actionable
queue unreadablewarn 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 whateverbuildDiagnosticsCheckscan emit.Worth adding alongside: a test that pins the headless path's contribution to
degraded, whicheverway 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.