first commit

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

@@ -0,0 +1,58 @@
+## 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.