feat(local-collector): make doctor's verdict readable by a process supervisor

[tnunamak]

A local collector — a one-shot program that uploads a machine's data on a timer, started by a process supervisor such as systemd — can be reporting that it is in trouble on every scheduled run without anything on the host noticing.

Its command-line tool already has a doctor command that checks four things about the machine it runs on: the local queue of records waiting to upload, records that failed repeatedly and were set aside for an operator, whether any queue entries are held by a worker that has gone away, and whether the server is reachable. It rolls those into one of ok, warning, or critical. But it printed that verdict inside a JSON document and always exited 0, and a process supervisor decides whether a program succeeded by reading its exit status alone. So the collector's own diagnosis was unreadable by the only thing watching it, unless a person ran the command by hand and read the output.

doctor --exit-code exits 1 when the rollup is critical and 0 otherwise. A supervisor can then act on it — the systemd documentation in this repository gains a section on wiring it to OnFailure=, a directive that runs another unit when one fails, to raise a local desktop notification.

Two choices worth explaining. The flag is opt-in rather than the new default because the existing contract is "print JSON on stdout, exit 0", and callers already parsing that output would suddenly see a failure status for a document they were reading successfully. And only critical exits non-zero: the warning conditions are ones the next scheduled run clears on its own — an expired queue lease, a missing database, a coverage gap — so treating them as failure would make a supervisor flap on states that are already resolving. That is the same reasoning the existing rollup uses to keep them out of critical.

This also renames one piece of console text. On a source's detail page each device carries a link to the device exporters page, and the link's visible text was the raw device identifier — a generated string with no meaning to a reader, which is worst exactly where the link matters most, next to a line saying the collector stopped checking in. It now reads "View this device", with the identifier moved to the tooltip and left in the URL fragment that scrolls the target page to the right row.

What this does not do

It does not detect a collector that has stopped running. OnFailure= requires the program to have run and exited non-zero, on a host whose service manager is up and whose desktop session is present to show a notification. It covers none of the cases — timer stopped firing, host powered off, person working elsewhere — where a collector goes quiet and only the server can notice. The documentation says so in place, because that limit is easy to mistake for a liveness answer. Server-side silence detection is separate work, in #74.

Verifying it

Eleven of eleven doctor tests pass in the local collector package, including three new ones: the flag is parsed and stays off by default, the severity mapping is pinned across all three values, and a real dead-lettered outbox produces a non-zero status. The mapping is a separate exported function rather than an inline comparison so it can be tested without invoking the command-line entry point.

Six tests parse the systemd unit documented in this repository and assert on the directives it declares; they still pass, so the new documentation section did not disturb the block they read. The console change is covered by that file's existing structural tests, which read the component as text and assert on its literals: 41 of 41 pass, and none pinned the previous link text.

Assisted-by: AI