lifecycle¶

Provenance¶

Source: .spec/spexcode/spec-cli/sessions/lifecycle/spec.md
Source SHA-256: b7b1d73fb224690ccdab32495a6a54c7458bd6d8f40a980e5fbf40084e978c3b

lifecycle¶

raw source¶

The durable thing is the worktree, not the tmux process: a session survives a kill, a reboot, or a moved folder. So a session's life is three concerns over that one anchor — how it comes up, what state it declares while running, and where its private runtime bookkeeping is kept so the worktree root stays clean and the scratch dies with it. The agent authors its own state; nothing about its life is inferred behind its back.

expanded spec¶

The three concerns each own their detail:

[[launch]] — bringing a worker up: the reclaude wrapper, the per-session rendezvous socket, the non-truncating launch-prompt delivery, the materialized-contract auto-discovery (no --append-system-prompt, no hidden CLAUDE.md), and the concurrency cap with its durable launch queue.
[[state]] — the lifecycle state machine: the declared statuses, the per-session Stop / PreToolUse / Notification hooks that gate them, AskUserQuestion → asking, and adapter-derived liveness. Lifecycle is agent-authored except for a proven hard runtime outcome: a headless turn's non-zero exit may compare-and-set an otherwise undeclared active record to error, never overwrite a declaration.
[[runtime]] — the per-session GLOBAL store under ~/.spexcode (keyed by session_id, grouped per project), NOT the worktree: every harness-written artifact (state record, originating + queued prompts, launch script, recorded comms, spec sentinels) lives there, so the worktree holds zero per-session SpexCode files and stays mergeable-clean.

The shared guarantee: state is read from the global store every time (no in-memory map), so a session's life is reconstructed from disk after any backend restart — the durable worktree, its global state record, and its socket liveness are the whole truth.