Run and recover work

This is the operating guide: everything between "I have an issue" and "the change is merged", including what to do when a run stops, asks you something, or fails.

It assumes you have installed Cairn and run one issue already; see Getting started if not. Two words recur: an execution is one run of a recipe over an issue, and a node is one step in it. Concepts & glossary has the rest.

Compose the run

An issue does not have to run the moment you create it. Filing it in the backlog and composing the execution later is the normal path for anything you want to think about first.

When you do start one, the Execution composer — the + Execution button in the issue footer, or ⌘N — is where you decide what this particular run looks like:

• Recipe. Which workflow runs. The default plan-then-build loop is one choice among the recipes your workspace and project define.
• Where the work lands. A new branch with a pull request at the end, or directly on the base branch. Only recipes that declare the choice offer it.
• Which machine runs it, if you have more than one enrolled.
• Per node: the agent, the model, and reasoning effort. Raise the planner to a larger model for a subtle problem, drop the builder to a smaller one for a mechanical change, or point a node at a different agent entirely.
• Which nodes run. Remove one you do not want this time — skipping review on a one-line fix, for instance.

Choosing another machine is a trust decision. That executor receives the checkout and run material it needs and may receive the selected provider credential in the agent process environment. Read Privacy and data boundaries before enrolling or selecting a host you do not control.

These are launch overrides: they apply to this execution only and never edit the recipe other issues run. Composing a run from a script instead is covered in Scripting.

The composer does not set an agent's fence. That comes from the agent's own configuration, and you can change it mid-run with the editor described below.

Follow the run

The issue's execution panel lists every node with its status. Most of the time you only need to distinguish four: a node is running, blocked because it is waiting on you, failed, or complete. A coordinator or thread agent also rests at idle between wakes, which is normal rather than stuck.

Opening a node shows everything the run has produced, each on its own tab: the transcript, its diff against the base branch, any terminals or browsers it opened, and its artifacts. The diff is the one worth checking early — it is the fastest way to see whether an agent is building what you meant.

When the run needs you

An issue that needs your attention is marked in the sidebar, and the marker tells you which of three things it is waiting for.

Needs input — the agent asked you a question. It reached something it cannot decide alone, usually offering options. Answer it in the node's chat, and it continues from your answer. The question and answer stay in the transcript.

Needs authorization — the agent tried to act outside its project. Its fence is set to ask, so it is waiting for you to allow or deny, either once or for the rest of the session. Setting that agent's fence to deny instead makes these fail immediately rather than waiting, which is what you want for a run you are not watching.

Needs approval — an artifact is waiting on your confirmation. The plan step in the default recipe is the one you will meet first. Read the artifact, edit it if you want to redirect the work, and confirm; nothing downstream starts until you do.

Change a node mid-run

You can change a node's model, prompt, or fence without stopping it, from the snapshot editor (⌘E). The three reach a running agent at different moments — some immediately, some at its next step — and the editor labels each field with when it will actually take effect, so read the label rather than assuming.

Stop, resume, restart

These are three different operations and picking the wrong one is the most common way to lose time.

Stop interrupts the node's active turn and parks its session warm. It is not a kill: the transcript, the branch, and everything committed stay exactly where they are, and the session can be picked up again. Sub-agent runs the node spawned stop with it. Stop when an agent is going the wrong way and you want to redirect it.

Resume is just sending a message. A node sitting at complete, failed, or blocked goes back to running and continues in the same session with its context intact. This is how you correct a finished agent, retry a failed one, or push past a checkpoint — no new execution required.

Restart appears on a failed node. It sets that attempt aside — its transcript stays readable — and runs the node again from the start with its current settings. Use it when the attempt itself is not worth continuing; if the node is blocked rather than failed, answer it instead.

If the whole approach was wrong, start a new execution on the same issue. It gets its own number, and the first execution's transcripts and commits stay readable alongside it.

Checks

Cairn runs a project's declared checks on its own cadence, so nobody has to remember to run the suite. Fast checks run right after a commit that touches source, and their verdicts are appended to the result of the very tool call that made the commit. The fuller suites — type-check, lint, tests, build — run in the background when a turn ends.

What makes this operationally different from CI is where the result goes. A failing turn-end check wakes the agent with the failure inlined, so it resumes already knowing what broke rather than waiting for someone to notice. A green run rides along passively on its next turn. You will often see a failure appear and be fixed without touching anything.

When you do want to look, each node has a checks tab: a live log tail while a suite is running, and pass/fail verdicts once it has settled.

A green verdict with a test count covers what a suite can assert about the diff. It does not cover whether the feature works for a person: live UI and cross-system behavior still need a browser or a running instance. See Checks for the configuration and the cadence in full.

Conflicts

When the base branch moves under a branch that is still in flight — a sibling merged, or you merged something yourself — Cairn replays the branch onto the new base. Most replays are clean and you never hear about them.

A real conflict wakes the agent, which resolves it with ordinary file edits and carries on. This usually happens without you.

If you get involved, resolve it the same way — by editing the conflicting files. Do not rebase or force-push by hand: Cairn owns these branches, and a branch still carrying a conflict is refused a push, so working around it by hand tends to make the situation worse rather than better.

Review, merge, and close

A finished builder produces a pull-request artifact, and Cairn opens or updates the pull request. The PR view shows the live state from GitHub alongside the diff.

You can merge from inside Cairn. The merge button is available once the pull request is open, is not a draft, and GitHub reports no conflicts; the merge method comes from your workspace settings and defaults to squash.

Merging is what resolves the issue — marking an issue merged while its pull request is still open is refused, since that would strand the commits. Closing an issue that still has work running asks you to confirm, and tells you what is still live before it stops anything.

After that Cairn cleans up on its own. The commits and the transcripts stay readable.

When you don't know what is wrong

Start at the node's status, because it tells you which of the sections above you are in. blocked and an attention marker mean the run is waiting on you. failed means read the last turn of its transcript. running with nothing visibly happening usually means a long command — look at its terminal. idle on a coordinator is not stuck at all; it is resting until something wakes it.

The one case none of that covers is Cairn itself failing to start, which is not a run problem at all. The app opens on a repair screen that names what it diagnosed and offers the fix.