Every line a script or hook prints for a person to read: in a session's transcript, in /sdlc:dispatch's background output, or in a worker's own log. Exact wording is quoted; <...> marks what varies. Grouped by the situation you'd be looking at it in.
supervise.py prints these lines and exits when a person is needed, or when a newer supervisor took over. /sdlc:dispatch restarts the supervisor right away (so the rest of the work keeps going), then acts on each line:
| Line | Meaning | What to do |
|---|---|---|
blocked <task> awaiting-review: <gate> |
a human review gate is open and no worker is running for the task | /sdlc:review <task> |
blocked <task> stopped: <comment> |
the worker ended without finishing; <comment> is its last comment |
/sdlc:recover <task> |
blocked <task> failed: <comment> |
the worker's session ended in error; <comment> is its last comment |
/sdlc:recover <task> |
blocked <task> pr-opened: <url> |
an epic-pr integration task's pull request is open |
review and merge the pull request yourself; sdlc closes the task once it's merged |
blocked <task> not started: <reason> |
run-task.sh refused to start the task; see run-task.sh can't start for <reason>'s shapes |
fix the named problem, then dispatch again |
new-work <task> <task>... |
ready tasks exist outside the ids /sdlc:dispatch was given and not labelled auto (labelled work is started without a line) |
/sdlc:dispatch asks whether to add them |
taken over |
a supervisor with a higher generation took the lock | nothing; the newer one keeps going |
supervisor <generation> already running |
a higher-generation supervisor already holds the lock; this run exits without starting anything | nothing; /sdlc:dispatch reports it and doesn't restart |
workers.py prints one block per dispatched, non-closed task:
| Shape | State | What it adds | What to do |
|---|---|---|---|
<id> running on <host> started <T> ago last output <T> ago "<title>" |
running | nothing | nothing, or /sdlc:logs <task> to watch progress |
<id> crashed on <host> started <T> ago last output <T> ago "<title>" |
crashed | session:, transcript:, worktree:, commits since <base>:, uncommitted:, log:, worker runs:, result:, last events:, stderr:, machine booted: |
/sdlc:dispatch resumes it automatically when the cause looks gone, or reports why not; /sdlc:recover <task> after reading the evidence |
<id> stopped on <host> worktree <path> "<title>" |
stopped | last comment: <comment> |
/sdlc:recover <task> |
<id> failed on <host> worktree <path> "<title>" |
failed | last comment: <comment> |
/sdlc:recover <task> |
<id> awaiting-review on <host> worktree <path> "<title>" |
awaiting review | gate: <gate>, review: /sdlc:review <task> |
/sdlc:review <task> |
<id> pr-opened on <host> worktree <path> "<title>" |
pr-opened | pull request: <url>, waiting for its merge |
merge the pull request |
no dispatched task in progress |
— | — | nothing |
/sdlc:status adds one line per task needing attention, naming the same next steps.
inbox.py prints one block per item waiting on a person, oldest first, each followed by link: and next: lines:
| Shape | Kind | link: |
next: |
|---|---|---|---|
<task> review since <T> ago "<title>" |
an open human review gate finish-task.py opened |
the worktree path, or missing |
/sdlc:review <task> |
<task> gate since <T> ago "<title>" |
any other open human gate blocking the task | the gate's reason | bd gate resolve <gate> |
<task> pull request since <T> ago "<title>" |
an open gh:pr gate |
the pull request URL | merge it; the task closes once merged |
<task> stopped since <T> ago "<title>" |
a worker that ended without finishing | its last comment, or none, plus /sdlc:logs <task> |
/sdlc:recover <task> |
<task> failed since <T> ago "<title>" |
a worker whose session ended in error | its last comment, or none, plus /sdlc:logs <task> |
/sdlc:recover <task> |
<task> crashed since <T> ago "<title>" |
a claimed task with no live worker and no outcome recorded | the worker log's path | /sdlc:dispatch resumes it, or /sdlc:recover <task> |
<task> permissions since <T> ago "<title>" |
a task whose latest attempt was denied tool calls (dispatch_permission_denials) |
the suggested rules, comma-separated, e.g. Bash(cargo test:*), Bash(git status:*) |
add them to permissions.allow in the project .claude/settings.json |
inbox empty |
— | — | nothing |
Suggested rules: a Bash command gives one Bash(<prog>:*) per component (split on &&, ||, ;, |, newlines), or Bash(<prog> <sub>:*) for git, npm, cargo, bd, pnpm, yarn, go, docker, kubectl and gh. Interpreters (python, node, ruby, perl), wrappers (sh, bash, env, sudo, xargs, timeout, nohup), commands with a heredoc, and the Write and Edit tools give none; any other tool gives its bare name. A task with no suggestion isn't listed.
A line ends with seen by <actor> when /sdlc:inbox --all shows an item someone already marked seen (/sdlc:inbox seen <task>); a seen item is otherwise hidden until its state changes. See dispatch_seen.
Run by the worker itself. Exit 1 and 3 messages print to stdout, so they land in the worker's own log; exit 2 prints to stderr (a usage problem, not normally seen by a person).
| Exit | Situation | Message shape | Who acts, and how |
|---|---|---|---|
0 |
merged and closed | merged <id> into <base> and closed it, then closed <parent_id> / closed epic <epic> for any cascade |
nothing |
0 (epic-pr) |
pull request opened | opened <url> for <epic>; <id> and <epic> close once the pull request is merged |
merge the pull request |
1 |
uncommitted tracked files | not merged: uncommitted changes to tracked files: <files>. Commit or discard them. |
worker commits or discards, runs again |
1 |
agent review requested changes | not merged: review round <N> requested changes:\n<findings>\nFix them, commit, and run this again. |
worker fixes the findings, runs again |
1 |
agent review didn't complete | not merged: the review didn't complete (<timed out after 900s|exited <N>|returned no verdict>); run this again |
worker runs again |
1 |
rebase conflict | not merged: rebasing <branch> onto <base> conflicts in: <files>. Run git rebase <base>, resolve the conflicts, then run this again. |
worker resolves, runs again |
1 |
verify failed after rebase | not merged: verify for <target> failed after rebasing onto <base>: <verify output> |
worker fixes the check (verify failure shows the same shape) |
1 |
verify failed, nothing to merge (e.g. an analysis task) | not merged: verify for <target> failed: <verify output> |
worker fixes the check |
1 |
merge failed | not merged: merge into <base> failed: <stderr> |
worker investigates the merge conflict or wt error |
1 |
epic-pr: pre-merge checks failed | not merged: the project's pre-merge checks failed: <output> |
worker fixes the checks |
1 |
epic-pr: push failed | not merged: pushing <branch> to origin failed: <output> |
worker investigates the push error |
1 |
epic-pr: opening the pull request failed | not merged: opening the pull request failed: <output> |
worker investigates the gh pr create error |
1 |
counting commits failed | not merged: counting commits since <base> failed: <stderr> |
worker investigates |
3 |
pre-merge checks unapproved | needs a person: the project's pre-merge checks aren't approved on this machine; a person runs wt config approvals add in <main_root>. Record it with bd comments add <id> and stop. |
run wt config approvals add once, in the main checkout |
3 |
human review pending | needs a person: <id> waits for a human review (gate <gate>). Stop now: you'll be resumed after the review. |
/sdlc:review <task> |
3 |
agent review rounds exhausted | needs a person: the review still requests changes after 3 rounds\n<findings> |
/sdlc:review <task>, or fix by hand and /sdlc:recover <task> → Finish |
Same output whether run by finish-task.py, by /sdlc:verify, or by hand:
verify <check-id>: <check command>
<the check's captured stdout and stderr>
verify <check-id> failed
to stderr:
reproduce: cd <worktree> && <check command>
narrow it down (one test, or the system by hand) before fixing; use a debugging skill if one is installed
debug: <custom.dispatch.debug hint> (only when set)
An epic's pre-merge step instead prints pre-merge checks: wt hook pre-merge, then <output> and pre-merge checks failed. Success prints <id> passed.
What to do: /sdlc:verify <id> reproduces this on demand; it reads the output and the commits since the failing task merged, and says which change broke which check.
Printed to stderr as error: <reason>; the last line becomes not started: <reason> in a supervisor's wake line.
| Reason | What to do |
|---|---|
unknown integration mode <mode> (direct, epic-merge, epic-pr) |
fix custom.dispatch.integration or the epic's dispatch_integration |
<id> is an epic: dispatch its tasks |
dispatch the epic's tasks, not the epic |
<id> is <status>, expected open |
the task isn't ready to start (already claimed, closed, or similar) |
<id> has no metadata.verify |
add a verify command, or --role integration/analysis |
<id> waits for <blockers> |
those tasks must close first |
no branch <target> |
create the target branch, or fix custom.dispatch.target |
<id> integrates <epic>, whose other tasks aren't closed: <pending> |
close the epic's other tasks first |
epic-pr mode needs a git remote named origin / epic-pr mode needs the gh CLI |
add the remote, or install gh |
could not claim <id> |
a bd update --claim race; try again |
the project's hooks aren't approved on this machine; a person runs wt config approvals add in <root> |
run wt config approvals add once, in the main checkout |
could not create the worktree for <branch>: <wt error> |
read the wt error and fix it |
no worktree for branch <branch> |
the worktree creation silently didn't produce one; investigate wt |
could not start the worker |
claude failed to launch; check its own error |
| Message | Printed by | Meaning | What to do |
|---|---|---|---|
<id>: no running worker / <id>: no running worker under it |
stop-task.sh |
nothing to stop | nothing |
finished <id> |
stop-task.sh |
the worker had already merged and closed the task before the stop landed | nothing to recover |
stopped <id> |
stop-task.sh |
the worker ended; dispatch_state=stopped, comment Stopped by a person. |
/sdlc:recover <task> |
reset <id> |
reset-task.sh |
the task is fully reopened, every dispatch_* key cleared |
/sdlc:dispatch picks it up like new |
| Message | Printed by | Meaning | What to do |
|---|---|---|---|
resumed <id> |
resume-reviewed.sh |
the reviewed task's worker resumed to read the verdict | nothing |
not resumed <id>: <reason> |
resume-reviewed.sh |
the gate closed, but resuming the worker itself failed; dispatch_state is restored to awaiting-review |
/sdlc:recover <task> |
resumed <task> <worktree> <log> |
resume-task.sh (via start-worker.sh) |
a crashed worker resumed | nothing |
error: <id> has no dispatched worker to resume (status <status>, dispatch_state: <state>) |
resume-task.sh |
usage error: the task isn't in a resumable state | check the task's actual state |
error: the worker for <id> is still running |
resume-task.sh |
a process already holds the session | nothing; it isn't actually crashed |
error: no worktree for branch <branch> / error: no transcript for session <session> |
resume-task.sh |
the worktree or the Claude transcript is gone | /sdlc:recover <task> → Start over |
| Message | Printed by | Meaning | What to do |
|---|---|---|---|
closed <id> (then closed <epic> if it was the last task) |
close-prs.sh |
the pull request merged; the integration task, and possibly the epic, closed | nothing |
stopped <id> |
close-prs.sh |
the pull request closed without merging; comment pull request <pr> closed without merging |
/sdlc:recover <task> |
clean.sh always lists; --apply also removes. One line per leftover:
| Line | Reason |
|---|---|
worktree <branch> closed task, worktree and branch left behind |
a merge finished but the worktree was never removed |
worktree <branch> open task with no dispatch_branch, worktree left behind (reset) |
the task was reset while its worktree stayed |
branch <branch> closed task, branch left behind with no worktree |
the branch survived removal (not an ancestor of its base after a rebase), or the worktree was removed by hand |
queue <branch> held by <holder>, no running process |
a worker died mid-merge, still holding the branch's merge queue |
error: could not remove the worktree for <branch> / error: could not delete branch <branch> |
--apply itself failed on that item |
clean.sh never lists the main checkout, a claimed task's worktree, or a task whose dispatch_state is stopped, failed or awaiting-review — those need /sdlc:recover or a review first.
| Output | Meaning | What to do |
|---|---|---|
| (nothing) | this branch head was already analysed | nothing |
busy <epic> |
an open epic is already analysing or refactoring this branch | wait for it to finish |
clean <sha> |
no function crosses custom.dispatch.ccn/function_length at that commit |
nothing |
created <epic> <task> |
a refactor epic and its analysis task were filed | /sdlc:dispatch <epic> |
error: metrics.sh failed:\n<output> |
lizard isn't installed, or crashed |
install lizard (pip install lizard) |
These fire inside a worker session (DISPATCH_TASK set); a person doesn't run the denied command, but reads these to understand why a worker keeps retrying through finish-task.py instead.
worker-guard.sh denies a PreToolUse Bash call and returns this reason:
| Denied command shape | Reason given |
|---|---|
bd close / bd done |
Workers don't close issues with bd. Run <finish>: it merges and closes the task, and the epic when it is done. |
bd update --status closed |
Workers don't close issues with bd. Run <finish>: it merges and closes the task. |
wt merge |
Workers don't merge with wt. Run <finish>: it rebases, verifies and merges through the merge queue. |
git ... push |
Workers don't push. Run <finish>: it merges, or pushes and opens the PR in epic-pr mode. |
gh pr merge |
Workers don't merge PRs. Run <finish>: it merges through the merge queue. |
bd gate resolve / bd gate close |
Workers don't resolve review gates. A person runs bd gate resolve after reviewing. |
setting review or dispatch_review* metadata |
Workers don't set the review verdict. <finish> manages review and dispatch_review* metadata. |
worker-stop.sh blocks a worker's first attempt to end while its task is still claimed and open with no comment since it was dispatched: Task <id> isn't closed. Commit your work and run <finish>. If you can't finish, record what's missing with: bd comments add <id> "<what's missing>". A second attempt is let through.
| Message | Printed by | Meaning | What to do |
|---|---|---|---|
waiting for the <branch> merge queue, held by <holder> |
merge-queue.sh acquire |
printed once while it polls for the queue | wait; it retries for up to 1800s by default |
error: timed out waiting for the <branch> merge queue |
merge-queue.sh acquire |
nothing freed it in time | check what holds it (/sdlc:clean lists a stuck one) |
error: no merge queue for <branch> (run: merge-queue.sh ensure <branch>) |
merge-queue.sh acquire |
the queue was never created | shouldn't happen through normal dispatch; run ensure |
logs.py (/sdlc:logs, /sdlc:recover's own lookup):
| Message | Meaning |
|---|---|
<task> was never dispatched |
no session, and no .wt failure file either |
<task> has no recorded dispatch session; the worktree failed before one was kept: |
the worktree creation itself failed; the .wt file's contents follow |
(no log at <path>) / (unreadable log <path>) |
the expected log file is missing or unreadable |
error: --follow needs a terminal |
--follow was used outside an interactive terminal |
record-task.sh itself, once a worker ends, prints one summary line: <state> <id> · $<cost> · <M>m<SS>s · <agents-or-models> · event <event-id>, with · worktree kept, see <log>.remove appended if removing a merged task's worktree failed. no result for <id> in <log>: the worker didn't end normally (exit 1) means the process died without a result line — the task stays crashed for the next dispatch to find.