# Polecat Lifecycle: From Work Completion to Going Idle in Gastown

> Understand the Polecat lifecycle. Learn how Polecat completes work to going idle via gt done, terminating the session and preserving the sandbox for reuse in Gastown.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: internals
- Published: 2026-07-07

---

**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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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:

```bash

# 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:

```bash

# 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:

```bash

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

gt sling my-issue gastown

```

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

```bash

# 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`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/done.go), [`internal/cmd/polecat.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/polecat.go), and [`internal/witness/protocol.go`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/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`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/done.go), which handles branch pushing, MR creation, hook removal, and state updates. The [`internal/cmd/polecat.go`](https://github.com/gastownhall/gastown/blob/main/internal/cmd/polecat.go) file implements the CLI commands for status inspection and sandbox management, while [`internal/witness/protocol.go`](https://github.com/gastownhall/gastown/blob/main/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.