Module session 

T-118: deterministic Claude Code session id derivation.

Every claude-code agent spawn passes --session-id <uuid> so the conversation persists across teamctl down/up cycles, crash recovery, and host reboots. The id is a UUIDv5 derived from a baked-in namespace plus the canonical agent string teamctl:<project>:<agent>.

Self-healing by construction: if the session-file at that UUID is deleted (manual cleanup, claude session-dir reset, etc.), the next spawn passes the same UUID and claude creates a fresh session at it. No operator action required.

Stable across rename of external things (claude version, host machine, tmux session) but evicts cleanly when the project or agent name changes — that’s the right semantics: a renamed agent is a new agent.

Constants

TEAMCTL_SESSION_NAMESPACE

Frozen UUIDv5 namespace for teamctl session-id derivation. Generated once on 2026-05-10 and pinned forever — changing this would invalidate every previously-resumed session across every dogfooding installation. Treat as a constant.

Functions

derive_session_id

Derive the deterministic Claude Code session id for a given project/agent pair. Same inputs always yield the same UUID; different agent or project yields a different UUID.

session_name

Compose the canonical name string for a given project/agent pair. Used as the UUIDv5 input AND surfaced verbatim to claude via the -n <name> flag so the operator sees the agent identity in claude’s session picker / prompt box.