feat: /dispatch as the default setup route, and a service-unit fix for npm deployments (issue #96)

[edgehero]

Closes #96. Makes /dispatch the default way to set up pi-dispatch, and fixes a shipped bug found while verifying it.

Fixed: service install was broken for every npm deployment

service.mjs derived a "repo root" two directories above its own module. Right in a checkout; under npm install that is node_modules/@edgehero, the scope directory, so every rendered unit pointed at files that do not exist: the worker ExecStart, the receiver ExecStart, EnvironmentFile, the plist wrapper path, the nssm paths. The wizard's service step has been installing those units since it shipped. Tests never caught it because they injected a correct repoRoot; no npm-layout fixture existed.

Three anchors replace the guess, each correct in both layouts: deployDir (the cwd service runs from) owns everything host-side (WorkingDirectory, .env, and logs/, created at install time since launchd and nssm create log files but never their directory), cliPath is cli.mjs beside the service module, and receiverStart comes from import.meta.resolve("@edgehero/pi-dispatch-receiver/start"), with a loud refusal naming the install command when the package is absent instead of writing a unit that crash-loops at boot. The wrapper stops guessing too: cwd is the deployment folder, it refuses empty argv and a missing .env naming $PWD, then runs "$@" verbatim. The exit-2 conversion and SIGTERM forwarding are preserved and still asserted against the real shipped wrapper. worker/deploy also gains docker-compose.yml, so npm deployments can run the receiver profile.

Existing service installs from 0.1.1 should re-run pi-dispatch service install --force from their deployment folder.

pi compatibility becomes strategy, not luck

As the advertised front door, a pi release must not break onboarding silently. The extension now reads pi's exported VERSION and, when it differs from the tested pin while the capability probe still passes, surfaces one info line on the first /dispatch. Never a refusal: the all-or-nothing capability probe stays the only hard gate. The peer pin widens to the "*" range pi's own packages doc prescribes for host-provided packages (the exact devDep stays the tested marker). And a weekly canary installs latest pi into a scratch dir (never the repo root, so the pinned assertions keep asserting the pin) and fails CI if any used API member or type needle disappears. Verified against pi 0.83.0, today's latest: the canary passes, so the advisory is what real operators on a newer pi will see.

The default route

• Direct entry: bare /dispatch with nothing configured no longer asks a yes/no before showing the wizard's own opening select. That select (Guided setup / Open the panel anyway / Cancel) is the consent, and one keypress no longer costs two detections. A configured deployment with a down queue still keeps the unreachable banner and never enters the wizard.
• Docker pre-check (new step 3): distinguishes not-on-PATH from daemon-down, then a Re-check / Continue anyway / Stop loop with per-OS vendor pointers and never a command to pipe into a shell. The probe carries a 10 second timeout, because it is a synchronous exec on a dialog path and a wedged docker socket would otherwise freeze pi's render loop.
• Trigger edge (new step 10): the receiver as a user-level service (consented pinned install, version assertion, then service install --receiver, correct after the fix above), or the compose profile (compose file copied create-only), or the polling command printed, or skip. A receiver version mismatch skips the unit and continues; the receiver is optional, unlike the runtime install, which stops.
• Skew notice: when the deployed runtime falls behind the console's pin, one notice per process points at /dispatch setup, which is already the upgrade path.

Docs

README quickstart leads with the extension route; the npx block moves to "Servers and headless" unchanged; the clone note stays for custom images. admin/README follows. docs/launch-kit.md gains the install line it never had. No dashes in README prose, per the house style.

Specs

DES-FIRST-RUN-SETUP-WIZARD amended (direct entry, both new steps, the skew notice, RECEIVER_VERSION, the outage rule restated as load-bearing); REQ-ADMIN-VIA-PI-EXTENSION acceptance amended (lands in the select, Cancel spawns and writes nothing; an untested-but-complete pi is an advisory; the skew notice). Revision rows in design.md and requirements.md record the service-unit fix and the compatibility strategy. CONST-BUDGET-BEFORE-TOKENS, CONST-RETRY-INFRA-ONLY, REQ-DEPLOYMENT-BOOTSTRAP unchanged, checked.

Tests

Full suite: 1871 tests, 1855 pass, 0 fail, 16 pre-existing skips (from 1843). Worker service suite 30 → 37 (real npm-layout fixtures asserting rendered targets exist and never take the scope shape, the missing-receiver refusal, live-shell wrapper tests under the new argv contract); admin 341 → 360. Workflow YAML validated; sh -n, xmllint, and plutil -lint pass on the wrapper and a live render; CI greps and control-byte scans clean.