feat(doctor): nomarchy-doctor — read-only health sheet + VM check (item 10)

The things that actually break user machines, one command (and menu ›
System › Doctor): failed system/user units, disk space (real
filesystems only — fstype allowlist makes it VM/live safe, device
dedupe collapses / and /nix), theme-state.json parses + is
git-tracked, flake dirty/behind as warnings, generation age (profile
symlink mtime — store paths are epoch-1), snapper timeline when
enabled. Read-only by contract; every ✖ prints the one fixing command;
exit 1 on any problem. Ships as pkgs/nomarchy-doctor so the VM check
runs on a minimal node.

Verified: V1 package build (shellcheck-gated) + a real-hardware smoke
that correctly flagged a genuinely failed user unit on the dev box;
V2 green — checks.doctor VM test: induced failed unit flips the sheet
to exit-1 naming the unit and its fix, reset-failed returns healthy.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/BACKLOG.md

@@ -26,16 +26,6 @@ next, in what order*.
 
 ## NEXT
 
-### 10. `nomarchy-doctor` — one-shot health check
-New. A single command (+ System-menu entry) that checks the things that
-actually break user machines and prints a themed pass/fail sheet:
-failed systemd units (system + user), disk space (/, /boot, the nix
-store), state-file parses + is git-tracked, downstream flake dirty/
-diverged, last rebuild generation age, snapper timeline running (when
-enabled). Read-only, no auto-fixing; each failure prints the one command
-that fixes it. Optionally later: a self-gating Waybar warning fed by the
-same script. **Verify:** V2 — a VM check with an induced failure.
-
 ### 11. State-file validation & friendly errors
 New; "the user never has to master Nix" must include *error messages*.
 A hand-edited theme-state.json (trailing comma, wrong type, unknown
@@ -126,6 +116,9 @@ earns ≥3 entries — keep the root at six.
 - **MIPI/IPU software-ISP camera** support (no-UVC machines).
 - **OCR screenshot-to-text**: a Capture › entry (grim region → tesseract
   → clipboard) — cheap once recording (#12) reshapes the submenu.
+- **Doctor Waybar warning**: a self-gating bar indicator fed by
+  `nomarchy-doctor` (shipped 2026-07-04) — appears only when the sheet
+  has a ✖; click opens the sheet.
 - **Auto-timezone Waybar tooltip** showing the detected zone (optional).
 - **VPN exit-node richer display** (country/city) (optional).
 - **NixOS release bump → v2** `[human]`: deliberate, hand-edited, never

agent/HARDWARE-QUEUE.md

@@ -86,6 +86,10 @@ QA machine), the **T14s** (webcam case).
       `sudo nomarchy-snapshots`, restore a single file (`undochange`)
       and walk a root-config rollback up to (or through) the
       typed-`yes` gate.
+- [ ] **Doctor (item 10)** — menu › System › Doctor opens the sheet in
+      a terminal; `nomarchy-doctor` over SSH shows the same minus user
+      units. On a healthy machine everything is ✔/– (dev-box run
+      2026-07-04 correctly flagged a genuinely failed user unit).
 - [ ] **Rollback menu (item 9b)** — after a couple of theme changes,
       menu › System › Rollback: recent desktop generations listed
       (newest marked current); picking an older one opens a terminal,

agent/JOURNAL.md

@@ -17,6 +17,27 @@ Template:
 
 ---
 
+## 2026-07-04 — nomarchy-doctor (iteration #20, item 10)
+- **Task:** BACKLOG NEXT#10 — one-shot read-only health check.
+- **Did:** pkgs/nomarchy-doctor (writeShellApplication → shellcheck-
+  gated; a package so the VM check runs on a minimal node): failed
+  system+user units (user bus self-skips), disk space on real
+  filesystems only (fstype allowlist skips tmpfs/9p → VM-safe; device
+  dedupe), state-file parses + git-tracked, flake dirty/behind
+  (warn-level), generation age via the profile SYMLINK mtime (store
+  paths are epoch-1), snapper timer when enabled. Every ✖ prints its
+  fix; exit 1 on any ✖. Wired: overlay, systemPackages, System ›
+  Doctor menu row (terminal), README §5.
+- **Verified:** V0; V1 package build (shellcheck) + real-hardware
+  smoke: correctly flagged a genuinely failed user unit on the dev box;
+  V2 GREEN — VM test: induced failed unit → exit 1 + names it + prints
+  fix; reset-failed → healthy exit 0. Menu rebuild bash -n ok.
+- **Pending:** V3 menu-row check queued. Waybar-warning follow-up →
+  LATER.
+- **Next suggestion:** NEXT#11 (state-file validation) — doctor's
+  "parses" check is its little sibling; 11 adds validate-before-write
+  + eval-time schema messages.
+
 ## 2026-07-04 — System › Rollback menu (iteration #19, item 9b → item 9 done)
 - **Task:** BACKLOG NEXT#9 half (b) — undo one menu away.
 - **Did:** new `rollback` case in nomarchy-menu (System submenu row):