browser/openspec/changes/implement-real-process-supervision-and-config-file-execution/specs/bounded-process-supervision/spec.md

ADDED Requirements

Requirement: Lifecycle execution uses declared typed actions

Platform and Run SHALL execute local lifecycle jobs only from the server's selected plugin runtime profile and a bounded typed action declaration whose action matches the requested capability. Run MUST reject arbitrary shell, unrestricted PATH execution, absolute executables, undeclared environment fields, and unsafe argument content.

Scenario: Declared start action executes

• WHEN an authorized start Job carries the selected profile scope and its declared relative action ref
• THEN Run validates the typed start declaration and starts only the workspace-contained executable with the declared argument vector

Scenario: Shell or mismatched action is rejected

• WHEN an action declaration contains shell execution, an unsafe executable, or an action different from the Job capability
• THEN Run fails the Job without creating a supervised process

Requirement: Process start and stop are real and idempotent

Run SHALL supervise at most one matching game process per server/profile scope and SHALL make repeated start and stop operations converge without creating duplicate processes or failing solely because the desired state already exists.

Scenario: Start already-running process

• WHEN a start Job targets a scope whose matching supervised process is alive
• THEN Run returns a successful typed running result and does not spawn another process

Scenario: Stop running process

• WHEN a stop Job targets a live supervised process
• THEN Run requests bounded graceful termination, escalates only within the declared policy, records the exit, and returns a safe stopped result

Scenario: Stop already-stopped process

• WHEN a stop Job targets a scope with no live supervised process
• THEN Run returns an idempotent successful stopped result without exposing process identifiers

Requirement: Process state survives Run restart reconciliation

Run SHALL persist private controlled process identity/state atomically with owner-only permissions and SHALL reconcile every record against OS liveness before accepting new lifecycle work after startup or session rotation.

Scenario: Live process survives Run restart

• WHEN Run restarts while a recorded supervised process remains alive
• THEN startup reconciliation retains the logical process as running and a later status/start operation observes the same process rather than spawning a duplicate

Scenario: Process exited while Run was offline

• WHEN a recorded process is no longer alive during startup reconciliation
• THEN Run records a safe exited state and does not treat the stale PID as running

Requirement: Unexpected exits and status queries are typed

Run SHALL observe exits of processes it starts and SHALL return bounded typed state, exit classification, timestamps, and audit summary for status Jobs without returning PID, host path, command bytes, environment credentials, sockets, sessions, leases, or hashes.

Scenario: Managed process exits unexpectedly

• WHEN a supervised process exits without a completed stop operation
• THEN Run records an unexpected-exit classification and a subsequent status result reports exited with bounded safe evidence

Scenario: User reads process result

• WHEN an authorized owner or administrator reads the completed lifecycle/status Job
• THEN Platform returns safe process state and exit classification and omits all private machine identity and fencing fields

Requirement: Process operations honor cancellation and attempt fencing

Run SHALL bind process mutations to the current reconciled Job attempt and Platform SHALL apply typed terminal results only after endpoint, session generation, attempt, lease, deadline, cancellation, and signature checks succeed.

Scenario: Start is cancelled before commit

• WHEN the current start attempt is cancelled or times out before Run commits its process record
• THEN Run terminates any child created by that attempt and returns a cancelled result

Scenario: Stale attempt reports process result

• WHEN an older attempt or stale session submits a process result after retry/reconciliation
• THEN Platform rejects it and does not change the server process projection

Requirement: Process traffic remains channel-isolated

Process execution, monitoring, and result reporting SHALL use the existing Job channel and MUST NOT block control heartbeat or Job acknowledgement/result traffic when log or artifact work is blocked.

Scenario: Artifact or log request blocks during process operation

• WHEN a log upload or artifact transfer remains blocked while a process Job completes
• THEN control heartbeat and the process Job acknowledgement/result continue through their independent paths