## 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.