Skip to content

The runner daemon

The runner is what makes starting a session from the console possible. It lives on your machine, holds the repositories and the coding agent’s own login, and connects outbound — so there’s no inbound port, and NAT and firewalls are nobody’s problem. The platform holds no git credential and no Claude account; the spawned session authenticates exactly the way your own terminal does.

  1. Claims it. The claim is the one moment a run’s own short-lived cawdr_ token exists — straight into the child’s environment, never into a file that outlives the run, and nowhere near your own runner:operate token.

  2. Prepares the working copy. Fetches, then checks out the branch — from the project’s default branch, or from a sprint’s base branch when the run names one.

  3. Spawns the agent in that checkout, in its own process group, with the run token in its environment and a generated .mcp.json pointing at cawdev’s own MCP server. The config is written to a temporary directory per run and thrown away — nothing lands in your repository.

  4. Reports the lifecycle back, and ends the run if the session dies without saying anything, rather than leaving it RUNNING forever.

The one hard refusal: a dirty working copy

Section titled “The one hard refusal: a dirty working copy”

If the checkout has uncommitted changes and the run wasn’t started with permission to work on top of them, the daemon refuses outright, naming the files:

/Users/you/code/cawdev has uncommitted changes:
M src/thing.js
Commit or stash them first, or start the run again and choose to work
on top of them.

An agent shouldn’t start work on top of yours by accident. If you did mean for it to build on what’s there, the console lets you say so when you start the run — the daemon then logs what it’s building on, loudly, on the run’s own transcript.

No free checkout is a queue, not a refusal

Section titled “No free checkout is a queue, not a refusal”

A project’s concurrency is the number of workspaces you’ve given it — see the config file. A run that has nowhere free to go doesn’t fail; it queues, and the console says why: “no free workspace in <project> (2 here, all busy).”

A free checkout with uncommitted work in it is not preferred over a clean one: the daemon takes the first free checkout that reads clean, and falls back to a dirty one only when every free checkout is dirty. When you start a run from the console and the checkout is dirty, a third way out beside Start anyway and Cancel is to wait for a clean one: the run stays queued, with a reason, until one is. If the workspace folder for a project is missing from disk, the run queues too and says so, rather than failing at spawn.

A checkout that a failed run left is held: it isn’t cleaned and isn’t offered to anything else until someone carries the run on or discards it from the run page.

A plan, a verify or an ask cuts no branch and takes no checkout. Left to read in the project’s first checkout, it would read whatever branch the last run happened to leave there. So such a session reads in <first>-read, beside the first checkout: a detached git worktree brought to origin/<default branch> at the start of a session whenever nobody else is reading in it. The checkout itself is never moved, because a coding run may be working in it. If the copy can’t be made (no remote, not a repository) the session reads the first checkout as before, and the log says why.

The daemon polls for requests a person makes of a checkout it serves. A request that names a path the daemon wasn’t given is refused rather than run. The ones you meet:

Action What it does
Show Diffs what’s uncommitted against HEAD, untracked files listed separately
Stash Parks the uncommitted work under a labelled stash entry
Commit Commits it with a message you give. Your repository’s hooks run; --no-verify is never passed
Reset git reset --hard && git clean -fd, then back onto origin/<branch> — or, if the branch was never pushed, onto the default branch with the local branch deleted
Hand off Pushes the branch, sends everything uncommitted to the platform as a patch, then resets — nothing is dropped before it’s somewhere else
Merge Merges the branch’s pull request (or merge request) on the host. It touches no working tree, so several branches merge safely from one clone, and a project’s merges go to machines one at a time, in the order they were asked for
Tag Asks the remote, not this clone, whether a release’s tag is there. A tag that isn’t there yet is a normal answer
Cut sprint branch Pushes the default branch’s tip to a new name on the remote, for a sprint’s branch. A branch already there counts as success
Open PR Opens the pull or merge request, or finds the existing one
Create branch Pushes a chosen branch’s tip to a new name on the remote, from the console

The code-map refresh button also arrives here. Merge, Open PR and Create branch use gh or glab; see Git hosts. A failed merge also says which kind of failure it was (a conflict, no pull request, not permitted, unreachable, or other), which is what lets the console offer Merge with an agent on a conflict and nowhere else.

A hand-off lands on another machine by putting the checkout on origin/<branch> (never re-branching from the default, which would be wrong for work that already has commits on the remote) and applying the patch with git apply --3way. A patch that won’t apply cleanly is never silently dropped — it’s written beside the checkout, and the run’s briefing says exactly where and how to apply it by hand.

A finished coding run is committed and pushed

Section titled “A finished coding run is committed and pushed”

Whatever the project’s rules say, a coding run reaches FINISHED only with a clean checkout and its branch’s commits on the remote. Two doors, one check:

  • report done refuses while anything is left, naming the uncommitted files and the commits the remote hasn’t seen, so the session commits what belongs and pushes in its own turn.
  • When the daemon ends the run (the lifecycle’s last stage, or a session that exited without reporting) it settles the branch itself: it commits what is left, pushes without force, and says so in the summary. It never commits anything that looks like a credential, and it doesn’t win a push the remote refuses.

A secret found, or a push refused, turns the run FAILED with the reason in its summary and the checkout held, so Carry on, Commit or Discard decide, not the next run.

A stage isn’t done while its commands are running

Section titled “A stage isn’t done while its commands are running”

A stage is one turn, closed the moment the turn ends, so a test suite started in the background and never waited for is a result lost. A stage whose turn ends with a background shell, or an Agent delegation, still running (or finished and never read) is reported FAILED with the commands named, and the run fails with it. It keeps its checkout and its session, so /continue picks it up. The re-run is told why the stage stopped and to run its commands in the foreground. IMPLEMENT and TEST are also told up front to wait for every command, and TEST to commit.

A project with a quality block in the config (see the config file) has its branch scanned with SonarQube after a coding run’s TEST stage settles and before the next stage begins, on the tree the tests just ran against. A scan that can’t run is said on the run page, and the run goes on to its next stage regardless.

A daemon that dies and is restarted keeps a note of the runs it was driving (~/.cawdev/driving/). On boot the next one fails every such run at once as DAEMON_RESTARTED, with the old and new process ids, and stops a session the old daemon left running. The workspace is held as for any failure. A machine with auto-resume on carries such a run on by itself once; a second restart on the same run waits for a person. The usual cause on a small Linux box is memory; see Troubleshooting.

Nothing is killed on a timer. A session that stops producing output for idleSeconds (1200s by default) gets one note on its own transcript saying so — it may be thinking, running something long, or genuinely stuck, and the cost of guessing wrong in either direction is asymmetric: ending a real twelve-minute test run costs somebody’s work, while a note that turns out to be nothing costs one line.

When a stage’s turn ends, the daemon closes the session’s stdin — that’s the request to stop. If it hasn’t exited after sessionExitSeconds (30s), the whole process group gets SIGTERM; if it’s still there after that again, a SIGKILL. Being forced out this way isn’t a failure — a stage is judged by whether its turn ended, not by how its process left.

The daemon spawns Claude Code, Codex or Antigravity as a run asks, and talks to GitHub through gh or to GitLab through glab. Those have their own pages: Agents and Git hosts.

stub-agent.mjs stands in for claude — spawned the same way, talking to the platform through the same tools, but following a fixed script instead of thinking.

{ "agentCommand": "/…/cawdev/tools/runner/stub-agent.mjs", "agentArgs": [] }

(Absolute path, no args — the runner puts --mcp-config first, and node would choke on it. The shebang runs the stub directly.)

Terminal window
CAWDEV_STUB_SCRIPT=ask-then-finish CAWDEV_TOKEN=cawd_… \
node tools/runner/runner.mjs --config runner.config.json
CAWDEV_STUB_SCRIPT Does
report-and-finish (default) Progress, then done
ask-then-finish Asks a question, waits for the answer, then done
permission-then-finish Asks permission for a command, waits for the decision, then done
crash Exits non-zero without reporting anything
hang Says nothing, ever — for testing cancellation
usage-limit Reports a closed usage window, ends its turn successfully, then lingers — the exact shape that once sat RUNNING for forty-three minutes holding a machine’s only slot

The stub does not exit when its turn ends, on purpose — the real CLI holds its stdin open the same way (see if a session goes quiet, above), and a stub that exited early would model away the one fact the whole stage walk depends on. CAWDEV_STUB_EXIT=1 restores the old, less honest one-shot behavior for anything that genuinely wants that.