Skip to content

feat(doctor): nine checks, and the three shapes that keep them honest (T47a) - #25

Merged
haiquang9994 merged 10 commits into
masterfrom
t47a-doctor-reports
Aug 23, 2026
Merged

feat(doctor): nine checks, and the three shapes that keep them honest (T47a)#25
haiquang9994 merged 10 commits into
masterfrom
t47a-doctor-reports

Conversation

@haiquang9994

Copy link
Copy Markdown
Collaborator

Closes T47a, the read half of T47. mix doctor examines nine things and says what it found, writing
nothing: no row, no file, nothing enqueued, and no elevation prompt can result from a call.

T47 was one roadmap line covering four subsystems. The split is by what the code does to the
machine
rather than by subsystem, because that is the boundary a reviewer can accept on one side of
and reject on the other. Repair, flushing the deferred privileged queue, and stale generated
configuration are T47b's.

Nine checks, each read from the subsystem that owns the answer

The hosts block through T41's own comparison, the resolver through T45's probe, the DNS server
through T44, answering on 80 and 443 through T42, the pending queue through T40b/T64, every declared
domain through T46's report rendered rather than recomputed — which T46 asked for by name — the
home's permissions through T3a, what this system promises about a service's descendants, and the port
ranges this system has reserved.

Three shapes worth more than the checks

Note is not Problem. What MixEngine can promise about a killed daemon's descendants is total
on Windows, the immediate child on Linux, and nothing on macOS. Reporting the macOS answer as a
fault would report the operating system as broken and leave a user with nothing to do; reporting it
as nothing at all is the exact failure ADR 0007 exists to prevent. The same distinction keeps
hosts_only a supported mode — T46a closed it as one — rather than a permanent fault on every
machine that never wired a resolver.

Skipped is not silence. Every check appears in every report in a fixed order, so a shorter list
on one operating system cannot read as a clean bill of health.

A Problem carries a closed id and never advice. T46 argued that a diagnostic must not suggest a
fix it cannot perform, because the advice drifts from the thing that performs it. An id is a name for
a condition, and being closed is what stops T47b's repairs and this build's findings drifting apart
at all: a repair for a condition nothing produces will not compile.

The check that earns its keep

Windows reserves port ranges — Hyper-V, WSL, Docker Desktop and winnat all take them — and a bind
into one fails with an access error. It reads as a permission problem, so a person who hits it
goes looking at elevation, UAC and the firewall, none of which is the answer. This is the one check
that saves a wrong search rather than reporting something findable.

And it found one immediately. The GitHub Windows runner has port 80 inside a reserved range, so
mix doctor reports a problem on an empty home there — correctly, because a front end on that
machine genuinely could not bind 80. The finding was right and this PR's first test premise was
wrong: a suite may assert that its condition is absent and then present, never that the machine
running it is well.

The icacls question T3a left open is settled: keep it

T3a deferred it because the apply path was verified working and the check had no caller. This task
is the caller, and the whole of what it needs is "is inheritance still severed, yes or no" — which
icacls answers. The ~150 lines of unsafe FFI buy a trustee comparison nothing asks for. What
would reopen it: a caller that needs to know who has access rather than whether inheritance was
severed.

Design: docs/superpowers/specs/2026-08-24-t47a-doctor-design.md

@haiquang9994
haiquang9994 merged commit 8b9a394 into master Aug 23, 2026
10 checks passed
@haiquang9994
haiquang9994 deleted the t47a-doctor-reports branch September 5, 2026 20:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant