Polecat Lifecycle: From Work Completion to Going Idle in Gastown

When a Polecat finishes its assigned work, it executes a six-step automated process via gt done that terminates the session, preserves the sandbox, and sets the agent state to idle for immediate reuse.

The Polecat lifecycle in the gastownhall/gastown repository defines how autonomous agents transition from active development to a dormant, reusable state. Understanding how a Polecat moves from work completion to going idle ensures you can manage persistent development environments without manual cleanup overhead.

Triggering the Lifecycle with gt done

The transition begins when the Polecat calls gt done from inside its Claude session. According to the source code in internal/cmd/done.go, this is the only legitimate mechanism for a Polecat to mark its work as finished. The command initiates an automated sequence that handles branch management, merge request creation, and state cleanup without manual intervention.

The Six Steps to the Idle State

The gt done command orchestrates a precise six-step sequence defined in docs/concepts/polecat-lifecycle.md and implemented across the codebase:

1. Signal completion – The Polecat invokes the gt done command, which sends a POLECAT_DONE protocol message parsed by internal/witness/protocol.go.

2. Push the feature branch – The command pushes the Polecat’s feature branch to the remote repository, ensuring all commits are preserved upstream.

3. Submit a merge request – The push automatically creates a merge-request (MR) bead that enters the Refinery’s merge queue for code review and integration.

4. Clear the work-tree hook – The hook that linked the Molecule to the Polecat is removed from the work-tree, signifying that no work remains to be done.

5. Set agent state to idle – The Polecat’s agent bead is updated with state=idle in the internal state store.

6. Terminate the session – The Claude tmux pane (the session layer) is killed, but the underlying Git work-tree (the sandbox) stays intact and synced to main.

After these steps complete, the Polecat is officially idle: its sandbox is preserved, its identity (agent bead, CV chain, and mailbox) remains permanent, and the agent is ready for the next assignment.

Sandbox Persistence and Identity Durability

A key characteristic of the gastown implementation is that the Polecat’s identity never dies during normal operation. While the session layer terminates, the sandbox layer persists, avoiding the overhead of creating fresh work-trees for subsequent tasks.

When the next gt sling command executes, it locates an idle Polecat (or allocates a new slot) and reuses the existing sandbox. The temporary feature branch is deleted and the work-tree is synced back to main, leaving a clean environment for the next assignment.

This design ensures the normal lifecycle follows IDLE → WORKING → IDLE. The gt polecat nuke command—which explicitly removes the sandbox—exists only for error handling and stale agent cleanup, not for the standard workflow.

Practical Examples

Complete work and transition to idle:

# Inside a Polecat’s Claude session – finish the current task

gt done                      # triggers the six-step idle transition

Verify the Polecat is idle and ready for reuse:

# Inspect the Polecat’s state (for debugging)

gt polecat status Toast      # shows state=idle, no active session, sandbox present

Assign new work to an idle Polecat:

# The next assignment reuses the idle Polecat’s sandbox automatically

gt sling my-issue gastown

Remove a stalled or broken Polecat (explicit cleanup only):

# Remove sandbox for error cases (rare, explicit action)

gt polecat nuke Toast        # deletes the sandbox; identity persists in the bead chain

Summary

• The gt done command automates the complete transition from working to idle across six distinct steps.
• Branch management, MR submission, and hook cleanup occur automatically before the session terminates.
• The sandbox persists after going idle, allowing immediate reuse via the next gt sling command.
• Identity durability ensures agent beads, CV chains, and mailboxes survive until explicitly destroyed with gt polecat nuke.
• Implementation spans internal/cmd/done.go, internal/cmd/polecat.go, and internal/witness/protocol.go.

Frequently Asked Questions

What happens to a Polecat's sandbox when it goes idle?

The sandbox (Git work-tree) remains intact on disk. According to docs/concepts/polecat-lifecycle.md, only the Claude tmux session is killed while the underlying work-tree is preserved, synced to main, and prepared for the next assignment. This avoids the computational overhead of cloning repositories and rebuilding environments for every task.

How does gt done differ from gt polecat nuke?

The gt done command follows the happy path of IDLE → WORKING → IDLE, preserving the sandbox and agent identity for reuse. In contrast, gt polecat nuke explicitly destroys the sandbox layer and is intended only for error handling or removing stalled Polecats. The agent bead may persist even after a nuke, but the work-tree is permanently deleted.

Where is the idle state logic implemented in the gastown codebase?

The core transition logic resides in internal/cmd/done.go, which handles branch pushing, MR creation, hook removal, and state updates. The internal/cmd/polecat.go file implements the CLI commands for status inspection and sandbox management, while internal/witness/protocol.go parses the POLECAT_DONE messages that confirm completion.

Can a Polecat be assigned new work immediately after going idle?

Yes. Once the agent bead shows state=idle and the sandbox is synced, the next gt sling command will automatically locate and reuse the idle Polecat. The gastown system prioritizes existing idle sandboxes over creating new ones, significantly reducing setup time for subsequent tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}