​

Worktree Isolation Roadmap

​

Current state (what’s implemented)

• isolation = "worktree" on agents creates per-agent git worktrees
• Pool agents each get separate worktrees (worker-1, worker-2, etc.)
• Worktrees live under .gc/worktrees/<rig>/<agent>/
• Branch naming: gc/<agent>-<base36-nanos>
• .beads/redirect files point worktrees to shared bead stores
• createAgentWorktree is idempotent (reuses existing worktrees)
• gc stop preserves worktrees by default (like gt down)
• gc stop --clean removes worktrees with safety checks (like gt shutdown)
• HasUncommittedWork() safety check skips dirty worktrees during --clean

​

The problem: worktrees must persist across restarts

​

Why worktrees must persist

1. Crash recovery. Agent crashes mid-task. Its worktree has uncommitted changes representing hours of work. gc stop && gc start must not destroy that work.
2. Context continuity. A restarted agent picks up where it left off. Its worktree has the right branch checked out, local changes present, bead hook pointing to the current task.
3. Pool scaling. Pool scales down from 5 → 2 agents. The 3 scaled-down worktrees may have in-flight work. Destroying them immediately loses that work. (Gas Town uses drain timeouts for this.)
4. NDI (Nondeterministic Idempotence). Sessions come and go; the work survives. Worktrees + beads are the persistent substrate. Multiple independent observers can reconcile the same state.

​

How Gas Town handles restart discovery

1. On gt up, scan polecats/<name>/ directories for existing worktrees
2. Scan tmux for existing sessions
3. Cross-reference with beads agent registry (hook_bead field)
4. If worktree exists + bead has work assigned → reuse worktree, start session
5. If worktree exists + no work assigned → available for new assignment
6. If session exists but worktree gone → kill orphan session

​

What’s already fixed

• gc stop preserves worktrees by default
• gc stop --clean flag for explicit cleanup
• HasUncommittedWork() safety check in internal/git
• cleanupWorktrees skips dirty worktrees with stderr warning
• createAgentWorktree idempotent (reuses on gc start)

​

Roadmap: what to build when

​

Tutorial 03 (Ralph Loop)

• Auto-respawn on crash (tmux pane-died hook)
• Worktree persists across agent restarts within a running city
• Agent discovers its worktree path from GC_DIR env var

​

Tutorial 04 (Agent Team)

• Cross-rig worktrees (crew pattern)
• Identity preservation across rigs (env vars + git config)
• gc worktree add/remove/list commands for crew management

​

Tutorial 05a (Formulas)

• Merge-back flow: formula step that merges worktree branch → main
• Post-merge worktree cleanup (only after confirmed merge)

​

Tutorial 05b (Health Patrol)

• Zombie detection: tmux session alive but agent process dead
• Stale hook scanning: dead agent + hooked bead → unhook
• Worktree safety check before unhook (check for partial work)
• PID tracking for orphan process cleanup
• Mass death detection (multiple agents dying rapidly)

​

Tutorial 05d (Full Orchestration)

• Bare repo pattern (.repo.git + worktrees) for efficiency
• Full worktree lifecycle: create → work → merge → cleanup
• Name pool recycling (release polecat names after cleanup)

​

Key design patterns from Gas Town

​

1. Filesystem as source of truth (ZFC)

​

2. Beads track work assignments, not worktree state

​

3. Two-phase cleanup

1. Soft stop (gt down / gc stop): kill sessions, keep worktrees
2. Hard stop (gt shutdown / gc stop --clean): kill sessions, verify no partial work, remove worktrees, prune git

​

4. Stale hook = dead session + hooked bead

1. Check if agent session is alive (tmux + process check)
2. Check if worktree has uncommitted changes
3. If dead + clean → unhook bead (status → open, reassignable)
4. If dead + dirty → warn, don’t unhook (manual recovery needed)

​

5. Startup beacon for context restoration

​

Polecat lifecycle (Gas Town’s ephemeral agent pattern)

​

The 7-step lifecycle

​

Step 1: Work creation & assignment (gt sling)

1. AllocateName() — picks a name from the name pool (filesystem-derived, never persisted). Writes .pending marker, creates directory, removes marker.
2. AddWithOptions() — creates the git worktree (git worktree add -b) at polecats/<name>/. Sets up environment.
3. hookBead — atomically sets two fields:
   • On the agent bead: hook_bead: "<issue-id>" (what work I’m doing)
   • On the work bead: status: hooked, assignee: "<rig>/polecats/<name>" (who’s doing me)

​

Step 2: Agent spawning (SessionManager.Start())

1. Create tmux session with startup command
2. Startup command includes a beacon — structured context about the assigned work (hook bead ID, molecule ID, rig path, worktree path)
3. Environment variables set: GT_POLECAT_PATH, GT_POLECAT_NAME, GT_RIG_PATH, etc.
4. Wait for Claude process to actually start (poll tmux pane PID)
5. Return only after agent is confirmed running

​

Step 3: Agent doing work

​

Step 4: Done flow (gt done) — the critical path

1. Validate state — branch pushed? No uncommitted work? On correct branch? If validation fails, abort with error.
2. Auto-detect cleanup mode:
   • push — just push the branch (no MR)
   • mr — create merge request
   • nuke — destroy without preserving work
3. Write done-intent label — Written EARLY in the flow as a crash detection breadcrumb. If the agent dies mid-done, the label’s presence tells the witness “this agent was trying to finish.” Without it, a dead agent with hooked work looks like a crash-mid-work (different recovery).
4. Push branch → create MR — If MR mode, push to remote and create the merge request via git forge API.
5. Notify witness — Signal the witness (polecat manager) that this agent is done. The witness handles post-merge verification.
6. Self-nuke worktree + self-kill session — The polecat: a. Verifies branch is pushed to remote (git ls-remote) b. cd / (escape the worktree CWD — learned from the CWD bug) c. git worktree remove --force <path> d. git worktree prune e. Kills own tmux session

​

Step 5: Witness cleanup (exceptional path only)

• Pending MR: MR created but not yet merged. Witness polls for merge, then does post-merge verification (run tests on merged result), then cleans up worktree.
• Crash during done: done-intent label present but agent died. Witness detects this and completes the cleanup.
• Zombie recovery: Session alive but agent process dead. Health patrol detects, kills session, witness unhooks bead.

​

Step 6: Name recycling

​

Step 7: Error cases

​

SDK implications for Gas City

1. Self-nuke is agent behavior, not framework behavior. The SDK provides the primitives (git worktree remove, session kill) but the agent’s prompt drives the done flow. The framework NEVER initiates worktree removal of a live agent.
2. Done-intent labels are essential. Any “agent finishing” flow needs a breadcrumb written early so crash recovery can distinguish “crashed mid-work” from “crashed mid-cleanup.”
3. Hook atomicity matters. The work bead and agent bead must be updated together. If only one is updated, the system enters an inconsistent state that’s hard to detect.
4. The witness is a derived pattern. It composes from: health patrol (detect death) + bead queries (find stale hooks) + git ops (cleanup worktrees). The SDK provides these primitives; the witness role is configuration.
5. Recovery strategy depends on crash timing:
   • Crash mid-work → restart in same worktree (preserve everything)
   • Crash mid-done → complete the cleanup (done-intent present)
   • Clean death → recycle name + worktree

​

Gas Town cleanup bugs: lessons for Gas City

​

Shutdown ordering (dependency order, not alphabetical)

1. Stop refineries (output consumers)
2. Stop witnesses (polecat managers)
3. Stop orchestration (mayor, deacon)
4. Stop daemon (background Go process)
5. Stop infrastructure (dolt server)
6. Kill tracked PIDs
7. Graceful orphan cleanup (SIGTERM → 60s → SIGKILL)
8. Verify shutdown (rescan for respawned processes)

​

PID reuse kills unrelated processes

// Gas Town: pidtrack.go
// Store: "12345|Wed Feb 24 10:30:00 2026"
// Before SIGTERM: read /proc/PID/stat start time, compare

​

Permission-denied on worktree removal

// Gas Town: manager.go
func forceRemoveDir(dir string) error {
    if err := os.RemoveAll(dir); err == nil { return nil }
    filepath.WalkDir(dir, func(path string, d os.DirEntry, _ error) error {
        if d.IsDir() { os.Chmod(path, 0755) } else { os.Chmod(path, 0644) }
        return nil
    })
    return os.RemoveAll(dir) // retry
}

​

Verify removal actually completed

​

Stale .pending markers from crashed allocations

​

TOCTOU in orphan detection

// Gas Town: orphan.go
func isProcessStillOrphaned(pid int) bool {
    tty := getProcessTTY(pid)
    if tty != "?" { return false }  // acquired a TTY
    protectedPIDs := getTmuxSessionPIDs()
    return !protectedPIDs[pid]
}

​

Session alive but agent process dead

​

Rollback pattern for failed multi-step operations

var worktreeCreated bool
cleanupOnError := func() {
    _ = beads.ResetAgentBead(aid, "rollback")
    if worktreeCreated { _ = git.WorktreeRemove(path, true) }
    _ = os.RemoveAll(polecatDir)
    namePool.Release(name)
}
// ... each creation step ...
if err != nil { cleanupOnError(); return err }

​

Never delete lock files

​

Minimum orphan age prevents killing during startup

​

Don’t assume CWD exists during cleanup

​

Gas Town reference files