Harden assisted update against legacy pinned-symlink Linux installs

[selfcontained]

Builds idea legacy-linux-pinned-symlink-update-hardening from the shared brain inbox, prompted by a real Cloudy Linux update failure after v0.32.2 went stable.

The failure

On ≤v0.31.x Linux installs whose ExecStart resolves through a symlink hard-pinned to a versioned binary (e.g. bin/dispatch → dist/bun/dispatch-0.31.4-bun-linux-x64), migration 0010's managed-update-first ordering extracts the target release, writes release state, and restarts — straight back into the old pinned binary. The old runtime's boot-time release-binary pruning then deletes the freshly extracted target artifact, while every validation false-greens because service_restarted/version_converged trust release.json and expected_runtime_artifact accepted the (symlinked) fixed path.

Changes

Migration 0010 reorder (the piece that reaches the legacy population — manifest text ships in the target tarball and is executed verbatim by old installs' assisted agents):

• Inspect the service entrypoint shape first, resolving symlinks to the real executable.
• On Linux with a version-pinned entrypoint: perform the fixed-runtime cutover before the first restart — checksum-verify and extract the exact target member, preserve .previous, hardlink/copy to the fixed path as a regular file, repoint ExecStart, daemon-reload, then restart. macOS keeps the launchd bridge (managed update first).
• Hygiene: repoint/remove dangling legacy bin/dispatch symlinks and refresh unit backups so a restore can't reintroduce the legacy entrypoint.
• Rollback now prefers the fixed runtime .previous over pre-update unit backups that name the legacy bin path.
• Final verification instruction requires proving the actual running process version (X-Dispatch-Version / /proc/<MainPID>/exe), not release.json alone.

New running_version required check (framework-side):

• Fetches the health endpoint and compares the X-Dispatch-Version response header — which is baked into the binary at build time — against the target tag. No header, wrong version, or unreachable ⇒ fail.
• Enforced implicitly by the assisted framework at launch time and again at check-run time, so a run launched by an older server but validated by the freshly restarted target binary still gets it.
• Deliberately not added to any manifest's requiredChecks: pre-v0.33 runtimes parse manifests with a strict check-name enum and would silently drop the whole manifest on an unknown name. A new test guards that shipped manifests stay within the legacy-parser-safe set.

Check hardening:

• expected_runtime_artifact now uses lstat and rejects a symlinked fixed runtime path (the exact legacy shape that false-greened).
• Manifest requiredChecks schema accepts unknown well-formed names at parse time; unknown names fail closed at run time (unknown required check) instead of erasing the migration from the pending set. This removes the trap for all future check additions.

VM fixture (idea item 3):

• scripts/vm-fixtures/legacy-pinned-symlink.sh converts a healthy fixed-path Linux install into the ≤v0.31.x pinned-symlink shape (pinned bin/dispatch symlink, no fixed runtime file, no KillMode=process, fixed-runtime migrations un-applied), wired into the docs' "Existing legacy Linux service" procedure. Per repo policy, no VM was provisioned or run for this PR — say the word if you want the VM row exercised before this ships in a release.

Validation

• pnpm run check ✅
• pnpm run test ✅ (718 tests, includes new coverage for running_version, symlink rejection, fail-closed unknown checks, implicit enforcement, and shipped-manifest parser compatibility)
• pnpm run test:e2e ✅ (176 passed, 12 skipped)
• No apps/web changes.

🤖 Generated with Claude Code