Repository navigation
fix(qsys-mac-installer): probe loopback for real instead of inferring it - #14
Merged
Merged
Conversation
Blocked 127.0.0.1 is the most confusing failure this wrapper produces: CEF and the embedded server ride loopback, so the Monaco script editor, help, and splash panes render BLANK with no error anywhere. The existing advisory only inferred this from Little Snitch being *installed*, and only in the installer's idle state — so it fired for every LS user whether or not anything was blocked, said nothing about LuLu / Radio Silence / pf / MDM firewalls, and was absent from the surface a user with blank panes actually reaches. - qsys-mac doctor gains a "TCP loopback" line backed by a real probe (bind a listener, connect to it). doctor is where someone with blank panes is sent, and the installer app may well be in the trash by then. - EnvChecks gains the same probe via POSIX sockets on port 0 (kernel-assigned, so it cannot collide). A measured block now leads; the Little Snitch notice is the fallback and is reworded — loopback working for the installer does not mean it works for Designer, because these rules are per-process. - Stays an advisory, not a blocker: provisioning and launch still work, only the web panes break, so it must not gate the install. Both probes fail SAFE — every inconclusive outcome reports "inconclusive", never "blocked", so the tool never sends someone hunting a firewall problem they don't have. Two traps found while building this and now covered by a hermetic test: `nc -l` LINGERS rather than exiting when a port is taken (so process-alive is not a bind test — the bash probe confirms LISTEN via lsof), and a busy probe port is not evidence of blocking (loopback is demonstrably fine if the connect still succeeds). No python3: the native-helper work removed that runtime dependency and this deliberately does not reintroduce it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The 'two things that bite' section described the symptom but gave no way to confirm it. Blank Monaco/help panes look exactly like a render bug, so the troubleshooting path now names 'qsys-mac doctor' → Host → TCP loopback, and states what the verdicts mean: BLOCKED is definite, inconclusive is not an accusation, and 'ok' only covers the helper because these rules are per-process. Also drops the Little-Snitch-specific framing where it was misleading — the probe covers LuLu, Radio Silence, pf, and MDM firewalls too. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
reowens
added a commit
that referenced
this pull request
Jul 28, 2026
Ships the loopback probe merged in #14 (squash 115d60e): `qsys-mac doctor` gains a "TCP loopback" line backed by a real bind+connect probe, and the installer's setup UI leads with a measured block instead of inferring one from Little Snitch being installed. Bumps both bundle plists, the generated launcher plist in lib/recipe.sh, and the README release link to 0.1.8. DMG sha256 b5c95937aeb3ce925b3c38216eb644b10fa83c2ab4c2c51f4e88213d65fba133 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
reowens
added a commit
that referenced
this pull request
Jul 28, 2026
Points DEFAULT_RELEASE at the qsys-mac-installer 0.1.8 signed DMG (sha256 b5c95937aeb3ce925b3c38216eb644b10fa83c2ab4c2c51f4e88213d65fba133) and bumps CLI_VERSION, the manifest, the README, and the CHANGELOG. That DMG carries the loopback probe from #14: `qsys-mac doctor` gains a "TCP loopback" line, so a blocked 127.0.0.1 — which renders Designer's script editor, help, and splash panes blank with no error — is finally diagnosable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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.
Blocked
127.0.0.1is the most confusing failure this wrapper produces: CEF and the embedded server ride loopback, so the Monaco script editor, help, and splash panes render blank with no error anywhere.The existing advisory inferred this from Little Snitch being installed, and only in the installer's
.idlestate. That meant it:pfrules, or an MDM-pushed firewall,Changes
qsys-mac doctorgains aTCP loopbackline backed by a real probe (bind a listener, connect to it).doctoris the support-diagnostics surface someone with blank panes is pointed at.EnvChecksgains the same probe via POSIX sockets on port0(kernel-assigned, so it cannot collide with anything in use). A measured block now leads; the Little Snitch notice becomes the fallback and is reworded — loopback working for the installer does not mean it works for Designer, because these filters are per-process.Fails safe
Both probes report
inconclusivefor every outcome they can't confirm, neverblocked— the tool must not send someone hunting a firewall problem they don't have.Two traps found while building this, both now covered by a hermetic test in
scripts/test.sh:nc -llingers instead of exiting when a port is already taken (verified on macOS 26), so process-is-alive is not a bind test. The bash probe confirmsLISTENvialsofbefore drawing any conclusion.ok.No
python3: the native-helper work removed that runtime dependency and this deliberately does not reintroduce it.Verification
scripts/test.sh— all checks pass, including the new probe test (ok / busy-ports-still-ok / inconclusive branches).pnpm run typecheck+pnpm testgreen.Note: this ships to users only with a new signed DMG (
qsys-mac-installer0.1.8) + aqsys-macDEFAULT_RELEASEbump — merged-but-unshipped until then.🤖 Generated with Claude Code