browser/openspec/changes/implement-secure-client-manager-lifecycle/specs/run-distribution-and-client-managers/spec.md

MODIFIED Requirements

Requirement: Run and client-manager keys are isolated singletons

Run executors and plugin-declared client managers SHALL use different authentication secrets, and each server/component SHALL have exactly one current active key stored encrypted in the platform database. A deployed Client Manager SHALL exchange proof of its current component key for a separate short-lived component session and SHALL never use a Run control session or job lease.

Scenario: Client manager is generated after run

• WHEN a plugin-declared client-manager package is generated for a server that already has a run package
• THEN platform MUST create or reuse the server's current encrypted client-manager key and MUST NOT reuse, reveal through API metadata, or derive it from the run key

Scenario: Component key reset is requested

• WHEN an operator resets a server's run key or client-manager key
• THEN platform MUST replace the encrypted database key for that component, increment the key generation, revoke all packages generated with prior generations, revoke matching component sessions and installed deployment fences, mark the affected installation as requiring current-generation rebuild and redeploy, and record an audit event identifying the component kind without logging raw key material

Scenario: Old package authenticates after reset

• WHEN a run or client-manager package generated before the latest key reset attempts to authenticate, register, heartbeat, deploy, or execute lifecycle work
• THEN platform MUST reject the old key, session, artifact, or generation and require the operator to regenerate and redeploy the corresponding run or client-manager package

Requirement: Client-manager packages are plugin-declared builds

The platform SHALL support plugin-declared client-manager build profiles for companion executables that require source checkout, configuration injection, and compilation before download or secure lifecycle deployment. Only a real available build artifact with a current component-key generation SHALL be eligible for deployment.

Scenario: SCUM-style client manager is generated

• WHEN a plugin declares a client-manager build profile with repository, revision policy, supported target platform, build system, config template, output artifact paths, deployment contract, lifecycle capabilities, health contract, compatibility constraints, and update policy
• THEN platform MUST create a run-worker build job that checks out the approved source and revision, injects configuration obtained through the authenticated job-input channel, compiles the target executable, uploads the downloadable artifact through the artifact channel, records deployable version/target/key-generation metadata, and redacts secrets and workspace paths from progress and build results

Scenario: Client-manager build is still running

• WHEN the source checkout, environment check, dependency download, compile, artifact upload, or publication stage is incomplete
• THEN platform_web MUST display the corresponding real job progress and MUST NOT mark later build or deployment stages complete on a local timer

Scenario: Unsupported client-manager target is requested

• WHEN an operator requests a client-manager build for an OS/architecture not declared by the plugin profile
• THEN platform MUST reject the request before cloning source or creating a credential

Scenario: Built artifact is selected for deployment

• WHEN an operator selects a client-manager distribution for lifecycle deployment
• THEN platform MUST require status available, current key generation, matching server/profile/component/target, approved revision and compatibility metadata, authorized server access, complete runtime binding, and an online assigned Run endpoint with the declared deployment capabilities before creating a typed deploy job