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

claude_home

~/.claude, derived from $HOME — the same base the agent wrapper probes ($HOME/.claude/projects/*/<uuid>.jsonl, agent-wrapper.sh:166). None when $HOME is unset, so callers can warn-and-skip rather than guess a path.

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.

freshen_session

T-352: move aside the on-disk Claude session JSONL for (project, agent) so the wrapper’s resume-probe misses on the next spawn and Claude opens a brand-new conversation at the same deterministic UUID (re-running BOOTSTRAP_PROMPT). The --fresh escape hatch from always-on resume (T-118); durable on-disk files are never touched — only the session JSONL.

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.