Make multiple Prime provider instances safe and truthful

[rynfar]

Problem

Pylon's generic instance UI already allows more than one Prime provider even though the driver reports supportsMultipleInstances: false; that metadata is not enforced or sent to clients. Most Prime control paths are instance-scoped, but native daemon multi-instance operation is not yet safe:

• recovered owned workers can receive ambient server credentials/environment instead of the owning instance's environment;
• home identity differs between daemon spawn and auth/model/capacity reads;
• blank/default or symlink-aliased homes can accidentally share account, settings, extensions, skills, harness state, logs, updates, and maintenance behavior;
• same-ID provider replacement can accept stale status, model, capacity, maintenance, rate-limit, or usage results from the prior account/configuration;
• forced teardown has an unbounded post-kill wait and owned-session completion is not observable;
• OS-user-global Prime maintenance and stop --all behavior can affect all local Prime daemons.

Treat multi-Prime as reachable today, not as a future toggle.

Required invariant

One enabled Prime instance has one immutable server-owned runtime context: { instanceId, generation, configRevision, effectiveHome, exactLaunchEnv, backendKind }. Every launch, attach, recovery, probe, catalog/model read, auth/capacity read, cache receipt, event subscription, mutation, and cleanup must consume or verify that same context. Never recompute home or environment later from raw PrimeAgentSettings. Runtime generation and config revision are correlation fences only; they never identify an account or enter public events, provider snapshots, logs, or telemetry.

Dependencies

Blocked on prime-agent#33, which owns the public SDK caller-owned recovery-environment and observable-cleanup capability. Native multi-instance mode must require all three current proofs before Pylon admits a native runtime: frozen SDK metadata containing both negotiated_daemon_session_capabilities_v1 and caller_owned_session_environment_cleanup_v1, the server's negotiated offer, and getOwnedSessionContractProof() from the successful current owned attach. Missing, stale, invalidated, or contradictory proof selects ACP. Never infer support from a version, package provenance, method presence, or an earlier attachment.

Final native enablement is also blocked on prime-agent#27 and #84 for the Pylon-restart case. A replacement Pylon process has no prior owner connection and cannot treat generic daemon shutdown, socket closure, or supervisor PID exit as proof that every old owned worker settled. The final gate requires exact adoption followed by owner-scoped cleanup, or a separate public aggregate cleanup receipt with equivalent authority. PRs 1–3 below may land before that gate; PR 4 may not advertise native multi-instance support until the restart case is proved.

Ordered implementation

1. Effective identity and capability gate. Merge the host snapshot and ordered instance overrides once; remove reserved Prime-internal/RLM keys; resolve explicit agent home, environment agent home, or the default against the merged effective OS home; canonicalize through the nearest existing ancestor; then stamp the canonical home into the exact launch environment. Apply that context to daemon, ACP, status, catalog, model, capacity, attach, recovery, and cleanup. Preflight every enabled instance before process launch and reject every participant in an equal/ancestor/symlink-aliased home overlap group. Pass exact ownedSessionLaunchEnv, require the full native proof, and add defensive MCP provider-instance assertions. Keep supportsMultipleInstances: false.
2. Provider-generation fencing. Give every materialization/config revision an opaque in-process generation. Every subscription, refresh, capacity run, overlay, maintenance action, runtime event, MCP cleanup, and cache write captures { instanceId, driver, generation } and rechecks it at commit. On replacement, synchronously clear old account/backend/volatile state. Use a server-owned random configRevision for private disk-cache correlation and rotate it for every material config/environment/secret change. Legacy, missing, invalid, or unproved revisions are cold misses. Never hash materialized environment or secret values, and never add a new key subsystem only to warm this cache.
3. Bounded teardown and durable quarantine. Bound graceful shutdown, force-kill, post-kill exit, socket cleanup, and scope close. Use single-flight disposeOwnedSession() and preserve its fixed completed, already-completed, owner-mismatch, uncertain-timeout, transport-failure, unsupported, and valid replacement-settled outcomes. Cleanup is proved only by an outcome tied to this connection's current or prior successful owned-attach proof and opaque session identity. Close only the instance-private daemon as final containment. Write a private atomic active-ownership receipt before every native client-owned create, scoped per session attempt and canonical home; remove only that attempt after the same live owner proves completion or proves ownership was never acquired. A crash, timeout, owner mismatch, transport loss, invalid result, or corrupt/unknown receipt leaves it dirty. Reload receipts before provider materialization and block every equal/ancestor/descendant home until docs: record the twelfth upstream batch #27/Prime Agent active turns cannot survive a Pylon server restart #84 identity-safe adoption and cleanup, or explicit documented remediation, clears them. Never ask an arbitrary replacement client to claim historical ownership.
4. Truthful support and UX. Propagate and enforce supportsMultipleInstances in server validation, Settings, and the Add dialog. Flip Prime to true only after PRs 1–3, feat(prime): remove sole queued inputs #33, the docs: record the twelfth upstream batch #27/Prime Agent active turns cannot survive a Pylon server restart #84 restart truth gate, real A/B isolation tests, and N=1/2/4 resource measurements pass. Require or guide users to a distinct home and separate sign-in/state per instance. Explain ACP/Windows fallback and the OS-user-global maintenance boundary. Web and desktop inherit the same server gate; mobile remains selection-only and must omit disabled, unavailable, or quarantined instances.

Acceptance coverage

• Explicit-home, environment-only home, HOME/default resolution, relative paths, symlink aliases, non-overlap, and reserved environment keys.
• Two real Prime instances with different homes, accounts, binaries, settings, model catalogs, capacity, sessions, sockets, checkpoints, MCP tokens, and credential sentinels.
• Worker crash, daemon reconnect/replacement, Pylon restart, settings replacement, one-instance removal, and concurrent stop without cross-account data or cleanup. Prove post-attach proof invalidation and republication across each native reconnect/replacement path.
• Deferred old status/catalog/capacity/usage/maintenance/rate-limit results and queued adapter events released after replacement never overwrite the new generation or clear the new MCP session.
• Legacy/missing config revisions start cold; secret changes rotate correlation without hashing, logging, or exposing secret-derived values.
• Hung graceful shutdown, hung post-kill exit, every fixed observable cleanup outcome, unsupported/contradictory capability proof, and fallback remain bounded and truthful.
• Native ownership receipt precedes create; abrupt crash leaves it dirty; the next boot launches zero overlapping instances; concurrent attempts never cross-clear; corrupt receipts fail closed; ACP writes no native receipt.
• ACP and Windows fallback stay explicit and verified.
• Measure N=1/2/4 process, memory, file-descriptor/handle, socket, and startup costs; document supported limits.
• Cover web, desktop-hosted server, mobile selection, local, remote/relay, tunnel, multi-client, macOS, Linux, and Windows ACP fallback. Verify at least one non-Prime provider remains unchanged.

Scope and non-goals

Use one PR per ordered concern. Shared Prime homes are not safe v1 and may be considered later only as an explicit opt-in. Do not mutate global process.env; persist or expose secret-derived fingerprints; treat generic shutdown/PID/socket state as owned cleanup proof; add a broad stop --all path; broaden the same-OS-user threat model; add hostile-co-tenant isolation; touch Prime #20; or include Comet.

Coordinate with #114 and prime-agent#33.

[rynfar]

Prime dependency update: pylon-code/prime-agent#37 is open at exact head 3becbe7fd2afecdaad9805b56e54cb827a10efff with the frozen caller-owned exact-environment/current-proof/observable-cleanup contract.

Local validation is green, including real A/B supervisor replacement followed by worker recovery. The PR now has a required hosted Windows named-pipe gate. Do not start Pylon #199 PR 1 or advertise native multi-instance support until Prime #37 lands at an approved exact head; the existing Prime #27/Pylon #84 restart-adoption and Pylon #199 PRs 1–3 gates remain unchanged.

[rynfar]

Prime dependency status: pylon-code/prime-agent#37 is fully green at exact head d83903f4dc9e649317e49862fcf676a02fc6d3f8, including the required hosted Windows named-pipe contract test. It now awaits exact-head maintainer approval and merge.

This proves the caller-owned environment/current-proof/observable-cleanup primitive, not secure Windows native admission. Pylon's explicit Windows ACP fallback and all Prime #27/Pylon #84 plus #199 PRs 1–3 gates remain in force.