browser/openspec/changes/implement-run-worker-real-execution/specs/run-worker-real-execution/spec.md

ADDED Requirements

Requirement: Run worker maintains platform session

The run executable SHALL support a worker mode that registers with platform and maintains heartbeat state.

Scenario: Worker registers and heartbeats

• WHEN run starts in worker mode with valid platform configuration
• THEN it MUST send hello, store the active session token, and continue sending heartbeat metadata

Scenario: Heartbeat does not carry heavy channels

• WHEN run sends heartbeat
• THEN it MUST NOT include logs, artifact chunks, job result bodies, host paths, raw credentials, or direct sockets

Requirement: Run worker processes job lifecycle

The run worker SHALL claim, acknowledge, report progress, complete, cancel, and reconcile jobs through the platform job channel.

Scenario: Job assignment completes

• WHEN platform assigns a supported lifecycle job
• THEN run MUST ack the job, report bounded progress, execute scoped lifecycle work, and submit a terminal result

Scenario: Cancel request handled

• WHEN platform reports cancellation for an active job lease
• THEN run MUST attempt cancellation and submit a bounded cancelled or failed result

Requirement: Lifecycle execution is scoped

The run worker SHALL execute install, start, and stop lifecycle commands only inside configured server workspaces with validated command templates.

Scenario: Scoped lifecycle command accepted

• WHEN a lifecycle job resolves to a safe command template and workspace
• THEN run MUST execute it through the process supervisor and redact unsafe output before platform reporting

Scenario: Unsafe lifecycle command rejected

• WHEN a lifecycle job requests absolute paths, parent traversal, raw credentials, direct sockets, or unrestricted shell execution
• THEN run MUST reject the job with a bounded failure result

Requirement: Run channels remain prioritized

The run worker SHALL keep control, job, log, and artifact work channelized so large transfer work cannot block heartbeat or job result submission.

Scenario: Artifact work pending during heartbeat

• WHEN artifact uploads are pending and a heartbeat is due
• THEN run MUST prioritize heartbeat over artifact transfer work

Scenario: Process logs are spooled

• WHEN a managed process writes stdout or stderr
• THEN run MUST write bounded log entries to local spool for platform ingest