Repository navigation
Add opt-in side-by-side Pylon Prime install and updates #194
Description
Problem
After Pylon can verify a fork distribution, users still need an explicit and reversible way to install and update it without overwriting their global stock Prime installation. Bundling Prime into Pylon, mutating a user-managed global package, or swapping package roots while a daemon/session is active would violate provider ownership and can mix an old SDK module with a new daemon.
Required outcome
Add an opt-in, side-by-side managed Prime tool store owned by the Pylon server:
- stable is the default channel; preview requires explicit opt-in;
- download the exact signed manifest and root tarball, verify provenance/digest before extraction or execution, and install under a content-addressed runtime path such as
userdata/provider-tools/prime-agent/<buildId>/; - record the verified receipt from Verify Pylon Prime distributions without weakening runtime negotiation #193 and set only that provider instance's binary path to the managed POSIX
.bin/prime-agentlauncher; WSL2 uses the Linux path; - stage every update in a new build directory and switch atomically only when the target instance has no active session, admission, daemon, or imported SDK context;
- reject or schedule changes while active work exists; never interrupt a turn for maintenance;
- compare signed channel sequence/build id rather than SemVer and reject implicit downgrade/replay;
- provide an explicit rollback to an already verified build;
- provide the reverse Use stock/configured Prime action and prune only unreferenced, receipt-owned managed directories;
- never mutate the user's global npm/pnpm/yarn/bun/Homebrew/binary installation.
The server/environment owns downloads and files. Web and desktop Settings can invoke the same server command in local or remote/relay/tunnel modes. Mobile must show host-maintenance status and instructions unless a shared safe control already exists; do not silently omit the state.
Acceptance coverage
- clean stable install, explicit preview install, staged update, explicit rollback, switch-back, and exact unreferenced cleanup;
- tampered manifest/tarball/attestation, path traversal, install-script escape, wrong package/bin, invalid receipt, replay, and wrong signer fail before execution;
- stock installation remains byte-for-byte untouched through every flow;
- active admission/turn/session/daemon blocks switching and succeeds after exact quiescence;
- distinct package roots prevent ESM cache and daemon/SDK version mixing;
- interrupted download/install/promotion recovers without selecting partial bytes;
- offline feed keeps the current verified build and reports update availability truthfully;
- macOS/Linux managed builds use native mode only after exact negotiated proof;
- native Windows managed install/update and native ACP fallback are out of scope until upstream Prime supports Windows; show WSL2 setup guidance instead;
- web, desktop, mobile status, local, remote/relay, tunnel, multi-client, and multiple environment behavior are explicit;
- Settings and all applicable maintenance entry points expose install, update, rollback, switch-back, progress, and actionable failure states.
Scope and dependencies
Depends on #193 and a published, tested preview from prime-agent#29. This issue owns download/install/update/switch/rollback/prune commands, settings/UI, focused cross-surface tests, user documentation, and the operations rollback runbook.
Prime remains unbundled and stock/configured Prime remains the default unless the user opts in. Runtime capability still comes only from frozen SDK metadata plus exact post-attach negotiation. Coordinate with #114. Comet is out of scope.
Activity
fix(prime): preserve managed install bindings
feat(prime): install managed distributions safely
fix(prime): preserve managed install bindings
ci(prime): require real artifact graduation