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

Context

Run has typed clients for control/job/log/artifact channels and local spool packages, but its executable behavior is still a smoke summary plus bounded lifecycle executor that immediately returns success metadata. Platform-side job leasing is already available, so the missing piece is a persistent run worker that consumes jobs safely.

Goals / Non-Goals

Goals:

• Add hello/heartbeat and job polling loops.
• Execute install/start/stop lifecycle jobs using scoped process supervision.
• Emit progress and terminal results through the job channel.
• Connect stdout/stderr to log spool and lifecycle artifacts to artifact queue hooks.
• Enforce path, credential, command, and socket safety.

Non-Goals:

• No arbitrary plugin code execution or unbounded shell access.
• No game client bridge implementation.
• No cloud host provisioning or billing.
• No external artifact/log storage backend implementation.

Decisions

Decision 1: Worker owns channel scheduling

The run worker keeps control heartbeat high priority, job claim/result next, logs durable/batched, and artifacts lower priority. Long transfers must not block heartbeat or job result submission.

Decision 2: Lifecycle actions use scoped command templates

Plugin lifecycle action references resolve to bounded command templates under a configured server workspace. Absolute paths, parent traversal, raw credentials, and socket exposure are rejected.

Decision 3: Process supervisor is an abstraction

Process management sits behind a supervisor interface so tests can use fake processes and later game-specific process handling can be added without rewriting the worker loop.

Decision 4: Smoke mode remains

Smoke mode stays available for local diagnostics. Worker mode is enabled through explicit config.

Risks / Trade-offs

• [Risk] Real process orchestration can hang. Mitigation: bounded timeouts, cancellation, progress heartbeat, and supervisor tests.
• [Risk] Command templates can become unsafe. Mitigation: validation rejects shell metacharacter abuse, absolute paths, direct sockets, and secret env leaks.
• [Risk] Worker loops can starve logs/artifacts. Mitigation: separate scheduling and priority rules.

Migration Plan

1. Add worker config and session state.
2. Implement control heartbeat and job loop.
3. Add process supervisor and lifecycle executor.
4. Wire logs/artifacts to existing queues.
5. Update command entrypoint and docs.
6. Add unit and integration-style tests.

Open Questions

• Whether future plugin action runtimes should interpret JSON action schemas directly or compile them into lifecycle command templates.
• Whether server process state should be persisted in a journal file or a small local database.