browser/openspec/changes/make-run-autonomous-lifecycle-owner/design.md

Context

Generated Run packages currently register with Platform and then wait for Platform to enqueue lifecycle work before any game bootstrap can happen. That makes Platform the practical lifecycle starter even though the machine-side Run is the only component that can observe process truth, supervise local execution, and safely decide whether install/update/start work is needed.

The corrected ownership model is: Platform builds and authenticates a server-scoped Run package, the package contains plugin-declared lifecycle assets plus a bounded autonomous lifecycle plan, Run executes that plan locally on startup, and Platform updates persisted projections from Run-reported lifecycle facts. Plugin manifests remain the source of game-specific instructions; Platform and Run remain generic.

Goals / Non-Goals

Goals:

• Stop generated Run registration from enqueueing process.start or process.status jobs as a bootstrap side effect.
• Add a generated-package autonomous lifecycle plan containing plugin lifecycle action refs, dependency declarations, safe deployment inputs, log sources, and selected runtime profile metadata.
• Keep Platform responsible for server records, registration binding, auth, distribution builds, audit, and visible projections from Run reports.
• Update governance and protocol docs so future work treats Run as the lifecycle authority.

Non-Goals:

• Implement the independent run repository's plan executor in this repo.
• Add game-specific SCUM install/start behavior to Platform.
• Move distribution builds to machine-side Run endpoints or expose distribution-build authority to generated Runs.
• Remove explicit operator lifecycle command APIs in this change.

Decisions

• Embed lifecycle intent at package-build time. Platform already has the server instance, plugin manifest, selected profile, lifecycle assets, and deployment definition when it builds a generated Run package. Encoding those into the package avoids waiting on /run/jobs/claim after registration and keeps the startup path deterministic.
• Use plugin declarations, not Platform logic, for game behavior. The plan references action files, dependency probes/install plans, process log sources, DLL extension declarations, and sanitized deployment inputs already declared by the plugin. It does not include SCUM executable names, Steam app IDs, ports, or platform-side command synthesis.
• Make registration binding-only for generated Run bootstrap. RegisterRunHello continues to authenticate the component, upsert endpoint metadata, and issue a session token. It does not dispatch lifecycle or reconciliation work merely because a generated Run appeared.
• Keep Platform projections report-driven. Existing terminal job/result projection can remain for explicit lifecycle commands, but generated Run startup state must converge through Run reports rather than Platform's stale stored state or registration-time probes.
• Preserve builder security boundaries. The platform-owned builder receives the plaintext component auth key internally and the autonomous plan as build input. Machine-side run endpoints still cannot claim distribution.build jobs or fetch plaintext build input.

Risks / Trade-offs

• Run repository lag -> The generated package can carry the plan before the independent Run executable consumes it. Mitigation: protocol and build input are explicit, and this repo does not re-add Run source.
• Stored Platform state may look stale until Run reports -> Registration no longer paper-over probes with Platform jobs. Mitigation: UI/API must treat persisted lifecycle state as projection, not observed process truth.
• Plan drift between build and execution -> A package carries the plugin declarations and deployment revision available at build time. Mitigation: include plugin version, profile key, deployment revision, and target release so Run and Platform can report stale-plan evidence.
• Operator command APIs still dispatch jobs -> This change fixes generated Run autonomous startup first. Explicit commands remain auditable Platform requests until a later change redesigns command transport around Run-owned intent handling.

Migration Plan

• Stop queuing registration-time lifecycle/status jobs for generated Runs.
• Extend run distribution build input and DTOs with autonomousLifecycle for Run packages only.
• Update platform builder input materialization so the generated package has a serialized plan alongside the existing workspace seed.
• Update service tests to assert registration does not enqueue bootstrap/reconciliation jobs and build input includes the plan.

Open Questions

• The independent run repository must define exactly how it consumes autonomousLifecycle, persists local bootstrap state, and reports lifecycle phases back to Platform.
• A future change may replace explicit Platform-dispatched start/stop jobs with Run-owned desired-intent handling for all lifecycle commands.