HEDDLE

Guide

Forking and recovering

You're mid-refactor. Two approaches look defensible; you don't know which will win until you try. Heddle's answer is to branch: start the working state forward into a second thread, let both paths run, recover whichever one wins. This guide walks the workflow end-to-end.

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. Defaults to HEAD. Pass an hd- change id or an unambiguous prefix of one.

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. Move between them with heddle thread switch <name>, which takes a thread — there is no top-level heddle switch, and no verb that checks out an arbitrary state.

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. Recovery, and what each verb is for

"Recovery" covers three different situations in Heddle, and they take three different commands. Reaching for the wrong one is the usual way people get stuck.

Picking an abandoned path back up

A dropped thread is still addressable, and its captures are still states. To carry on from one, branch a fresh thread off the capture you want — that is what start --from is for. Nothing "checks out" the old state in place.

Resume from an abandoned fork's mid-state

bash$ heddle thread show task/biscuit-authz.shim$ heddle show hd-9c4ar7tk2m0e$ heddle start task/biscuit-authz.shim.retry --from hd-9c4ar7tk2m0e --path ../retry

Unwinding something you just did

heddle undo rewinds Heddle operations. Two properties matter more than any flag:

  • It is thread-local. It only rewinds operations recorded from the current checkout. To unwind work an agent did in an isolated thread, run undo from that thread's checkout, not from the origin.
  • It will not touch your files without --hard. An undo that would rewrite the worktree refuses before changing repository state or files. That refusal is the feature.

Look, then rewind

bash# run this in the checkout you want rewound$ heddle undo --list$ heddle undo --preview$ heddle undo --hard# changed your mind about the undo:$ heddle undo --redo# or bring the pre-undo worktree back as changes, leaving HEAD alone:$ heddle undo --recover

Getting out of a stuck operation

When heddle land or heddle sync fails closed on a conflict, three top-level verbs finish the job — and the point of their design is that you do not have to remember which operation is in flight. heddle continue continues the active operation without remembering the specific subcommand; heddle abort aborts it on the same terms.

Work a conflicted land back to clean

bash$ heddle resolve --list$ heddle resolve src/auth/mod.rs# or take one side wholesale:$ heddle resolve --all --theirs$ heddle continue# give up on this attempt instead:$ heddle abort

A thread that is merely stale — its target has advanced past it — is not a conflict yet. heddle thread refresh replays it, and heddle land will refresh-then-merge for you when the replay is clean. It only fails closed when manual resolution is genuinely required.

When you want proof rather than a verdict, heddle verify exits nonzero until every check is clean — and note it exits 65, not 75, so a failing verify is never something to retry.

Next