claudebox needs a 'doctor' verb — every fault the drill's doctor catches is a user's fault too #46

New issue

Closed

opened 2026-07-14 12:23:26 +00:00 by dan-claude-bot · 0 comments

dan-claude-bot commented

2026-07-14 12:23:26 +00:00

(Migrated from github.com)

The drill grew a doctor because runs kept failing for host reasons (drill/doctor.sh). Look at what it actually diagnoses:

the Incus daemon wedged / not answering, with the #26 recovery recipe printed
claudenet's dnsmasq silently not serving (the bridge up, Incus saying "Created", every mint dying in cloud-init)
the host's resolver being a VPN/MagicDNS resolver that boxes inherit (#33) — now with the pinned-resolver read-back
security.port_isolation claimed by config but isolated off in the kernel
drill phase-D leftovers (the one genuinely drill-specific section)

All but the last are user faults, not drill faults. Today's session proved it live: a cold claudebox new died with Temporary failure resolving 'deb.debian.org' and nothing short of reading cloud-init logs said why. A user on any VPN host hits exactly that, with no drill in sight.

The CLI already half-admits this. bin/claudebox's mint-failure path greps the box's cloud-init log and points at issue #33 by hand — that is a doctor's job, done inline, in one special case.

Proposal

claudebox doctor — the host-health checks as a first-class verb:

The install tree already ships the whole repo (install.sh copies everything, drill/ included), so the verb can delegate to the installed script. No new distribution mechanism.
Reframe the vocabulary: the question is "is this host fit to mint boxes?", not "fit to drill". Same facts, right audience.
Split placement to match: the generic checks (daemon, network, dnsmasq, resolver, profile, kernel bridge view) move to a script the verb owns; the drill keeps a thin wrapper that adds its phase-D leftover checks and --fix. Or one script with the drill-only sections behind a flag — implementer's call.
--pin-dns stays with the doctor as the quick test; the durable fix is setup-host.sh (#45).
The mint-failure path in bin/claudebox should end with run: claudebox doctor instead of its hand-rolled #33 hint.

Relation to #17

The verb must survive the box rename — it is exactly the kind of generic, non-Claude-specific surface #17 is about. If #17 lands first, this is box doctor from day one; if this lands first, it is one more rename site on #17's list.

Provenance

Runs 10–12. The doctor caught or explained every host fault in that arc (#26 wedge, #33 resolver, the isolated off ground truth), and it took five of its own false alarms (#40, #43) to make it trustworthy — that hardening is exactly what a user-facing verb should inherit rather than re-learn.

🤖 Generated with Claude Code

The drill grew a doctor because runs kept failing for host reasons (`drill/doctor.sh`). Look at what it actually diagnoses: - the Incus daemon wedged / not answering, with the #26 recovery recipe printed - claudenet's dnsmasq silently not serving (the bridge up, Incus saying "Created", every mint dying in cloud-init) - the host's resolver being a VPN/MagicDNS resolver that boxes inherit (#33) — now with the pinned-resolver read-back - `security.port_isolation` claimed by config but `isolated off` in the kernel - drill phase-D leftovers (the one genuinely drill-specific section) **All but the last are user faults, not drill faults.** Today's session proved it live: a cold `claudebox new` died with `Temporary failure resolving 'deb.debian.org'` and nothing short of reading cloud-init logs said why. A user on any VPN host hits exactly that, with no drill in sight. The CLI already half-admits this. `bin/claudebox`'s mint-failure path greps the box's cloud-init log and points at issue #33 by hand — that is a doctor's job, done inline, in one special case. ## Proposal `claudebox doctor` — the host-health checks as a first-class verb: - The install tree already ships the whole repo (`install.sh` copies everything, `drill/` included), so the verb can delegate to the installed script. No new distribution mechanism. - Reframe the vocabulary: the question is **"is this host fit to mint boxes?"**, not "fit to drill". Same facts, right audience. - Split placement to match: the generic checks (daemon, network, dnsmasq, resolver, profile, kernel bridge view) move to a script the verb owns; the drill keeps a thin wrapper that adds its phase-D leftover checks and `--fix`. Or one script with the drill-only sections behind a flag — implementer's call. - `--pin-dns` stays with the doctor as the quick test; the durable fix is setup-host.sh (#45). - The mint-failure path in `bin/claudebox` should end with `run: claudebox doctor` instead of its hand-rolled #33 hint. ## Relation to #17 The verb must survive the `box` rename — it is exactly the kind of generic, non-Claude-specific surface #17 is about. If #17 lands first, this is `box doctor` from day one; if this lands first, it is one more rename site on #17's list. ## Provenance Runs 10–12. The doctor caught or explained every host fault in that arc (#26 wedge, #33 resolver, the `isolated off` ground truth), and it took five of its own false alarms (#40, #43) to make it trustworthy — that hardening is exactly what a user-facing verb should inherit rather than re-learn. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: heavy-duty/box#46

No description provided.