Concept
Session lifecycle
A session is a small state machine. The orchestrator drives it the same way on every backend, recording each transition in the audit log and pushing it to the SSE stream.
Phases#
SessionPhase mirrors the underlying Kubernetes Job/pod phases. A session begins pending, becomes running, then reaches exactly one terminal phase — succeeded, failed, or killed — before being torn_down.
| Field | Type | Description |
|---|---|---|
| pending | SessionPhase | Accepted; the sandbox is not yet running. |
| running | SessionPhase | The workload is executing inside the gVisor sandbox. |
| succeeded | SessionPhase | The workload exited 0 and the result was collected. |
| failed | SessionPhase | The workload exited non-zero. |
| killed | SessionPhase | Terminated by the platform — quota, deadline, or fork-bomb guard. |
| torn_down | SessionPhase | Every per-session resource has been reclaimed. |
Kill reasons#
When phase === "killed", the session carries a killReason explaining why the platform terminated it.
| Field | Type | Description |
|---|---|---|
| cpu_exceeded | KillReason | CPU quota exhausted. |
| memory_exceeded | KillReason | Memory limit hit (OOMKilled). Live-validated on k3d. |
| wall_clock_exceeded | KillReason | Job activeDeadlineSeconds reached. Live-validated on k3d. |
| pids_exceeded | KillReason | Process count over podPidsLimit — the fork-bomb guard. |
pids_exceeded is currently modelled by the simulator and is the area called out for hardening in the evidence report. A documented boundary beats a hidden one.Lifecycle events#
As a session moves through its phases, the orchestrator records audit events and emits stream frames. A typical clean run produces: session_created → sandbox_started → (any egress_allowed /egress_denied) → workload_exited → result_collected → session_torn_down. See data contracts for the fullAuditEvent and StreamFrame shapes.