feat: deskwright-doctor -- post-install health check with an action for every finding - #5
Open
timrichardson wants to merge 2 commits into
Open
timrichardson wants to merge 2 commits into
timrichardson wants to merge 2 commits into
Conversation
… had nothing to talk to A private dbus-daemon cannot activate at-spi2-registryd: the a11y broker routes the start through org.freedesktop.systemd1, and on a bus with no systemd that name is the stub that answers /bin/false. So the headless a11y bus existed but no registry ever owned org.a11y.atspi.Registry, and ui_tree/ui_find failed with 'no application named gnome-shell' while the user's real session, whose bus has real systemd behind it, worked. headless.py now starts registryd itself, BEFORE the shell: order matters, because the shell's atk-bridge stops retrying registration when no registry answers (measured: registry-after-shell = 16/18 self-test, registry-before-shell = 18/18). Unit tests for the spawn/liveness/stop paths run anywhere; the live proof is tests/test_headless_atspi.py, which fails 2/3 checks on main and passes 3/3 here, and a cold headless self-test at 18/18.
…ix for every finding setup --check proves the machine before anything exists; the doctor proves the RUNNING stack after install and registration, and every finding prints its action. Born from tristanmuzzu#3, where every static check was green and even the self-test said 16/18 while the a11y registry quietly did not exist: a doctor has to ask the live system (does anything own org.a11y.atspi.Registry on this session's a11y bus? does the registered command answer MCP on stdio?), not the package manager. Checks: session, deps (setup's probes, same install lines), the a11y flag, the registry, the extension (files/enabled/live), the server command (version + provenance + a real initialize/tools/list handshake), and each running headless session's registry. --self-test adds the headless self-test (private virtual monitor, safe unattended). Never changes anything, never sudos; exit 0 healthy / 1 action needed / 2 not a target. 11 in-process tests (seams only, subprocess booby-trapped); verified live on Ubuntu 26.04: correctly demands the one logout this machine still owes, spots a pre-fix headless session and prints the restart command.
timrichardson
marked this pull request as ready for review
September 15, 2026 03:46
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Implements #6 (and exists because of #3). Stacks on #4 -- the registry checks are the #3 lesson made executable -- so review after or with it; the diff collapses to just the doctor once #4 lands.
What this changes
Adds
deskwright-doctor, a read-only post-install health check of the running stack.deskwright-setup --checkproves the machine before anything exists; the doctor proves what is actually installed, registered and live afterwards, and every finding names its fix (install line, gsettings command, logout, restart command). It asks the live system, not the package manager: does anything ownorg.a11y.atspi.Registryon this session's a11y bus, does the registered command complete a real MCP initialize + tools/list handshake, is each running headless session's registry up.--self-testadds the headless self-test (private virtual monitor, safe unattended). Never changes anything, never sudos; exit 0 healthy / 1 needs action / 2 not a target.How it was proven
ruff check .cleanpython3 -m pytest -q-- 409 passed (11 new; every external read behind a seam, subprocess booby-trapped in tests)DESKWRIGHT_SESSION=headless deskwright --self-test-- 18/18 via the doctor's--self-testflag (with fix: start the AT-SPI registry on the headless session before the shell #4 beneath it; 16/18 without)Anything a reviewer should be suspicious of
_install_provenanceinfers version/origin from the install layout (<prefix>/lib/python*/site-packages/deskwright*.dist-info,direct_url.json) rather than asking the running server. Wheels installed by uv/poetry may land in layouts it calls "unrecognized"; the stdio handshake still covers whether the server works._registry_aliveshape on purpose: one explanation of that failure mode, not two.Dog-food window complete: a day of daily-driver use, output above. Out of draft.