Runs & the inbox
A run is one execution of a workflow. Runs and the inbox are two views of the same underlying event log: runs are organized by loop, the inbox by what needs your attention.
Lifecycle
A run moves through seven states:
| State | Meaning |
|---|---|
queued | Created, waiting for a concurrency slot. |
running | The agent is working. |
waiting | Stopped on an ask-first action; your decision resumes or ends it. |
paused | Suspended by you (or by a take-over). Resumable. |
done | Finished normally. |
failed | Error or budget exceeded. |
aborted | Ended by you, by a deny decision on a waiting run, or by a rule timeout. |
Waiting has no default timeout — loopkeep doesn't answer for you. A blocked
run just shows its age in the inbox. If you want a deadline, put it on the
policy rule (timeout: { after: "72h", then: abort }).
Worktrees and checkpoints
Every run gets its own git worktree under .loopkeep/worktrees/<run_id>/ on
branch loopkeep/<workflow>/<run_id>. After each step the daemon commits a
checkpoint (loopkeep: step <n> — <summary>). Your working tree is untouched
until you merge something.
This makes rollback ordinary git: lk abort <run> --rollback resets to the
last checkpoint before discarding the run. A plain lk abort keeps the
worktree so you can salvage whatever's in it.
In a workspace that isn't a git repository, runs still work but there are no
checkpoints — abort --rollback is unavailable; abort and pause are.
Finished runs' worktrees are cleaned up after a retention window
(lk retention <days>, or off to keep forever; lk cleanup sweeps now).
Checkpoint branches are kept.
The inbox
The inbox holds attentions — things routed to you by
policy. ask-first items arrive immediately and ring;
notify items can be bundled into digests. Every item shows which rule sent
it, and approval screens show the raw diff or command first — the agent's own
summary never stands alone.
The Inbox groups items in two: Waiting on you (ask-first approvals and runs you're driving) at the top, and Updates (notify items) below. Each ask-first card shows the raw change, then Approve, Steer, or Abort; notify cards clear with Acknowledge. The History tab is a read-only record of everything already resolved.
Intervening
Decide a waiting run from its Inbox card: Approve, Steer (send an
instruction to course-correct without stopping the run), or Abort. To control
any run, open Runs and use the ⋯ menu on its row (or inside the run):
pause (resumable), resume, abort (keep changes), abort --rollback
(reset to the last checkpoint first), or Re-run workflow. The menu only
offers the actions the run's current state allows.
Pause is graceful — it takes effect at the next step boundary, not mid-action. When you need a hard stop, use abort.
For taking the wheel entirely, see Take-over & hand-back.