Forking and recovering

When to reach for fork

Fork is for genuine uncertainty: two approaches both defensible, no way to know which pays off without trying. Don't fork for every disagreement; threads can hold retries and aborts inline. Reach for fork when:

• A second agent will explore in parallel.
• You want to keep the not-yet-resolved path as evidence of what was considered.
• The decision is reversible and the cost of being wrong is a few hours of agent time.

Read the fork-from-capture concept page first if you want the full mental model. This guide is the operational walk-through.

1. Create the fork

From any state, run heddle start <name>. The thread name is a positional argument; the --from flag picks the fork point:

• <name> is the thread to create or resume. The new thread gets its own isolated working state.
• --from <state> is the base state to branch from. Accepts a state ID, a marker, HEAD, @, or HEAD~N. Defaults to HEAD.

Branch the current state into a named thread

bash# team is unsure whether to keep a JWT compat layer$ heddle start task/biscuit-authz.shimStarted isolated thread 'task/biscuit-authz.shim' at '.heddle/threads/task/biscuit-authz.shim/repo' (Heddle-managed checkout, no .git directory)

The parent thread keeps running. The new thread has its own isolated working state, its own captures, its own agent identity if you set one. Switch back and forth with heddle thread switch (or its alias heddle switch).

2. Let the fork run

From here, the fork behaves like any other thread. Make changes, capture, retry, sign. The parent and the fork have no special relationship beyond the shared ancestor at the fork point.

Work on the fork

bash$ heddle thread switch task/biscuit-authz.shim# try the JWT compat layer approach$ heddle capture --intent "keep JWT compat layer"Captured state hd-9c4ar7tk2m0e (7e2c8b91)$ heddle capture --intent "two auth lanes drift; 4 tests fail"Captured state hd-9c5ent3vq8wd (ab02174d)

3. Abandon if it doesn't pay off

Heddle distinguishes dropping a thread (no further work; mark abandoned but keep the record) from destroying it (which Heddle never does). To stop work on the fork:

Drop the fork as abandoned

bash$ heddle thread drop task/biscuit-authz.shimDropped thread 'task/biscuit-authz.shim'

The thread is now flagged abandoned (it won't appear by default in heddle thread list) but everything in it persists. The captures stay attributed and addressable. The agent identity and the reason for abandoning are part of the record.

4. Inspect an abandoned fork later

Months later you might want to revisit what was abandoned. heddle thread show renders it as a single record:

Read an abandoned fork's record

bash$ heddle thread show task/biscuit-authz.shimtask/biscuit-authz.shim   ·  gpt · 5.4 · forked from hd-d01a8q3z7m1k  3 captures · 4 retries · 1 abort (cost outweighs migration)  state: abandoned · still addressable

A dropped thread is still addressable by name, so heddle thread show task/biscuit-authz.shim works long after the drop. Separately, add --include-auto to heddle thread list to surface threads created automatically by harness integrations (which are hidden from the default view).

5. Recover from any state

If the abandoned path becomes interesting again (different constraints, new context, a teammate's question), heddle switch <state> lands you back at any capture in any thread.

Resume from an abandoned fork's mid-state

bash$ heddle switch hd-9c4ar7tk2m0eNow at: hd-9c4ar7tk2m0e  keep JWT compat layer

From there you can fork again, continue the abandoned thread, or just inspect the working tree to remember what was there.

Next

• Fork from capture: the conceptual depth, why this isn't just git stash with extra steps.
• heddle start: the full flag surface.
• heddle thread: the thread management family (switch, list, drop, cleanup, and 16 more).