Exit codes & environment

What each carol exit code means in v0.1.22, and the environment variables Carol reads, including CAROL_APP_KEY.

Every Carol command exits with one of these codes. The message on stderr says what to fix.

Exit codes

Code	Meaning
`0`	OK, or a plan with nothing to do. `tick` also exits 0 when some items were refused.
`2`	Usage, config or a parse error in a planning file. Also a failed `doctor` check, `handoff check` findings, several initiatives with none named, and `watch` without `--apply`.
`3`	Auth missing: `gh` isn't logged in, `board` lacks the `project` scope, `CAROL_APP_KEY` isn't set, or `[identity]` is missing
`4`	Plan refused: two items share one marker, the lock is held, `ticket` found no scope issue, `specify`, `run` or `report` refused the row, `report` found no run-report comment on the run pull request, or `skills install` met an unmanaged copy
`5`	Read-back mismatch: a write didn't stick. The message names the fields.
`6`	Tracker or Zurdo unavailable, a tracker write failed, or a PRD has no run state to read

A parse error always comes before any write. Carol reads every planning file before it opens the tracker, so a malformed file never leaves a half-applied plan.

Zurdo's codes, passed through

Command	Passes through
`specify`	`zurdo scaffold`'s exit code when it fails. Its last attempt stays under `.zurdo/scaffold/<phase>/`.
`run`	`zurdo run`'s exits 1 to 4, with nothing pushed. Exits 5 and 6 open a draft pull request, and `run` exits 0 with Zurdo's code in `data.zurdo_exit`.

carol run docs/billing/scope.md phase-02 --apply --format json | jq .data.zurdo_exit

Environment

Variable	Effect	Default
`CAROL_APP_KEY`	Path to the GitHub App's private key. The file must have no group or other permission bits.	Unset. The App commands exit 3 without it.
`CAROL_TOKEN_MAX_AGE_SECS`	The age, in seconds, at which Carol mints a new App installation token before its next write. GitHub expires one after an hour.	`2700` (45 minutes)
`CAROL_ZURDO`	The `zurdo` binary Carol calls	`zurdo` on `PATH`
`CAROL_CLAUDE_BIN`	The Claude Code CLI the engine loop runs its agent sessions with	`claude` on `PATH`
`CAROL_HOST`	The machine's name in the AI usage issue	The host name
`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`	Where `carol usage` reads each harness's store	`~/.claude`, `~/.codex`, `~/.copilot`
`GH_TOKEN`, or `gh`'s own login	The account the sync commands write as	`gh`'s login

chmod 600 ~/.config/carol/app.pem
export CAROL_APP_KEY=~/.config/carol/app.pem

Agent sessions get none of the GitHub tokens: Carol removes GH_TOKEN, GITHUB_TOKEN and the askpass helpers from their environment, and makes every write itself.

Files Carol keeps

Path	Holds
`$(git rev-parse --git-common-dir)/carol/lock`	The lock every `--apply` holds, naming its pid and command
`$(git rev-parse --git-common-dir)/carol/journal.jsonl`	One JSON line per applied op, for people. Carol never reads it.
`.carol/worktrees/<phase>`	The worktrees `specify` and `run` work in, so your checkout is never touched

Next: Internals