From 683989dfd810ba802ef567cd0335445e9f3830d1 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Tue, 23 Dec 2025 15:01:05 -0800 Subject: [PATCH] Add session-lifecycle.md: unified context cycling model MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents foundational architecture for session lifecycle: - Single-Bond Principle (one bead β‰ˆ one session) - Context Budget Model (what N-heuristics really proxy for) - Unified cycling model across all roles - Mid-step handoff mechanics - Happy Path (decomposition) vs Sad Path (compaction) - Oversized Bead Protocol πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/session-lifecycle.md | 268 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 docs/session-lifecycle.md diff --git a/docs/session-lifecycle.md b/docs/session-lifecycle.md new file mode 100644 index 00000000..650e53e6 --- /dev/null +++ b/docs/session-lifecycle.md @@ -0,0 +1,268 @@ +# Session Lifecycle: Context Cycling in Gas Town + +> **Status**: Foundational Architecture +> **See also**: [beads-data-plane.md](beads-data-plane.md), [propulsion-principle.md](propulsion-principle.md) + +## Overview + +Gas Town agents have persistent identities, but their sessions are ephemeral. This is the +"cattle not pets" model from Kubernetes: the agent (Mayor, Witness, polecat Toast) is +the persistent identity; the Claude Code session running that agent is disposable cattle +that can be killed and respawned at any time. + +Work persists in beads. Sessions come and go. This document explains the unified model +for session lifecycle across all roles. + +## The Single-Bond Principle + +> A bead should be achievable in a single typical Claude Code session. + +In molecular chemistry, a single bond connects exactly two atoms. In Gas Town, a single +session should complete exactly one bead. This is the atomic unit of efficient work. + +**Why this matters:** +- Clean execution: start session β†’ do work β†’ cycle +- No mid-work state to track outside beads +- Handoffs are clean boundaries, not messy interruptions +- The system stays efficient as it scales + +**The ceiling rises over time.** What fits in "one session" grows with model capability. +Opus 4.5 can handle larger beads than earlier models. But the principle remains: if a +bead won't fit, decompose it. + +### Violating the Principle + +You can violate the Single-Bond Principle. Gas Town is flexible. But violations trigger +the **Happy Path** or **Sad Path**: + +**Happy Path** (controlled): +1. Worker recognizes mid-work: "This won't fit in one session" +2. Choose: + - (a) Partial implementation β†’ handoff with context notes β†’ successor continues + - (b) Self-decompose: convert bead to epic, create sub-tasks, continue with first task +3. If scope grew substantially β†’ notify Witness/Mayor/Human for rescheduling + +**Sad Path** (uncontrolled): +- Worker underestimates β†’ context fills unexpectedly β†’ compaction triggers +- Compaction is the least desirable handoff: sudden, no context notes, state may be unclear +- Successor must reconstruct context from beads and git state + +The Happy Path preserves continuity. The Sad Path forces recovery. + +## The Context Budget Model + +**N is not "sessions" or "rounds" - it's a proxy for context budget.** + +Every action consumes context: + +| Action Type | Context Cost | Examples | +|-------------|--------------|----------| +| Boring | ~1-5% | Health ping, empty inbox check, clean rebase | +| Interesting | 20-50%+ | Conflict resolution, debugging, implementation | + +The heuristics (N=20 for Deacon, N=1 for Polecat) estimate "when will we hit ~80% context?" +They're tuning parameters, not laws of physics. + +### Why "Interesting" Triggers Immediate Handoff + +An "interesting" event consumes context like a full bead: +- Reading conflict diffs +- Debugging test failures +- Making implementation decisions +- Writing substantial code + +After an interesting event, you've used your context budget. Fresh session handles +the next event better than a session at 80% capacity. + +## Unified Session Cycling Model + +All workers use the same model. Only the heuristic differs: + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SESSION LIFECYCLE β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Start │───▢│ Execute Step │───▢│ Check Budget│───▢│ Handoff β”‚ β”‚ +β”‚ β”‚ Session β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ or Done β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ β”‚ β”‚ +β”‚ β–Ό β–Ό β”‚ +β”‚ Budget OK? ──Yes──▢ Loop to next step β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Per-Role Heuristics + +| Role | N | Unit | "Interesting" Trigger | +|------|---|------|----------------------| +| **Polecat** | 1 | assignment | Every assignment is interesting | +| **Crew** | ∞ | human decides | Context full or human requests | +| **Deacon** | 20 | patrol rounds | Lifecycle request, remediation, escalation | +| **Witness** | 15 | polecat interactions | (interactions are the cost unit) | +| **Refinery** | 20 | simple MRs | Complex rebase, conflict resolution | + +**Polecat (N=1)**: Every assignment fills context with implementation details. There's +no "boring" polecat work - it's all interesting. Forced to cycle when work is complete +and merged. + +**Crew (N=∞)**: Human-managed. Cycle when it feels right, or when context fills naturally. + +**Patrol Workers (N=15-20)**: Routine checks are cheap. Batch many before cycling. But +any "interesting" event resets to immediate handoff. + +## Mid-Step Handoff + +Any worker can handoff mid-step. The molecule tracks state: + +``` +Step 3 of 7, context filling + β”‚ + β–Ό + gt handoff -s "Context notes" -m "Details..." + β”‚ + β–Ό + Session dies, successor spawns + β”‚ + β–Ό + gt mol status β†’ sees step 3 open β†’ continues +``` + +This is normal and supported. The Single-Bond Principle is aspirational, not mandatory. +Mid-step handoff is the Happy Path when a bead turns out larger than estimated. + +## Handoff Mechanics + +How handoff works depends on the role: + +### Polecats: Outer Ring Handoff + +Polecats can't self-respawn - they need cleanup (worktree removal). They go through +their Witness: + +``` +Polecat Witness + β”‚ β”‚ + β”‚ gt done (or gt handoff) β”‚ + β”‚ β”‚ + β–Ό β”‚ +Send LIFECYCLE mail ──────────────▢ β”‚ + β”‚ β”‚ + β”‚ (wait for termination) β–Ό + β”‚ Patrol inbox-check step + β”‚ β”‚ + β”‚ β–Ό + β”‚ Process LIFECYCLE request + β”‚ β”‚ + ◀─────────────────────────────── Kill session, cleanup worktree +``` + +### Non-Polecats: Self-Respawn + +Crew, Mayor, Witness, Refinery, Deacon are persistent. They respawn themselves: + +``` +Agent + β”‚ + β”‚ gt handoff -s "Context" -m "Notes" + β”‚ + β–Ό +Send handoff mail to self (optional) + β”‚ + β–Ό +tmux respawn-pane -k (kills self, starts fresh claude) + β”‚ + β–Ό +New session runs gt prime, finds hook, continues +``` + +No outer ring needed - they just restart in place. + +## State Persistence + +What survives a handoff: + +| Persists | Where | Example | +|----------|-------|---------| +| Pinned molecule | Beads (rig) | What you're working on | +| Handoff mail | Beads (town) | Context notes for successor | +| Git commits | Git | Code changes | +| Issue state | Beads | Open/closed, assignee, etc. | + +What doesn't survive: + +| Lost | Why | +|------|-----| +| Claude context | Session dies | +| In-memory state | Process dies | +| Uncommitted changes | Not in git | +| Unflushed beads | Not synced | + +**Key insight**: The molecule is the source of truth for work. Handoff mail is +supplementary context. You could lose all handoff mail and still know what to +work on from your hook. + +## The Oversized Bead Protocol + +When you realize mid-work that a bead won't fit in one session: + +### Option A: Partial Implementation + Handoff + +1. Commit what you have (even if incomplete) +2. Update bead description with progress notes +3. `gt handoff -s "Partial impl" -m "Completed X, remaining: Y, Z"` +4. Successor continues from your checkpoint + +Best when: Work is linear, successor can pick up where you left off. + +### Option B: Self-Decomposition + +1. Convert current bead to epic (if not already) +2. Create sub-task beads for remaining work +3. Close or update original with "decomposed into X, Y, Z" +4. Continue with first sub-task + +Best when: Work has natural breakpoints, parallelization possible. + +### When to Escalate + +Notify Witness/Mayor/Human when: +- Scope grew >2x from original estimate +- Decomposition affects other scheduled work +- Blockers require external input +- You're unsure which option to choose + +```bash +# Escalate to Witness (polecat) +gt mail send /witness -s "Scope change: " -m "..." + +# Escalate to Mayor (cross-rig) +gt mail send mayor/ -s "Scope change: " -m "..." + +# Escalate to Human +gt mail send --human -s "Need input: " -m "..." +``` + +## Summary + +1. **Single-Bond Principle**: One bead β‰ˆ one session (aspirational) +2. **Context Budget**: N-heuristics proxy for "when will context fill?" +3. **Unified Model**: All roles cycle the same way, different heuristics +4. **Mid-Step Handoff**: Normal and supported via persistent molecules +5. **Happy Path**: Recognize early, decompose or partial-handoff +6. **Sad Path**: Compaction - recover from beads + git state + +The system is designed for ephemeral sessions with persistent state. Embrace cycling. +Fresh context handles problems better than stale context at capacity. + +--- + +## Related Documents + +- [beads-data-plane.md](beads-data-plane.md) - How state persists in beads +- [propulsion-principle.md](propulsion-principle.md) - The "RUN IT" protocol +- [pinned-beads-design.md](pinned-beads-design.md) - Hook mechanics +- [wisp-architecture.md](wisp-architecture.md) - Ephemeral patrol molecules