Troubleshooting Nightshift

A role keeps skipping

A skip always carries a reason. Run status to see it. The usual causes:

• A missing connector. The reason names the capability and lists what was found. Fix it in your MCP configuration.
• The daily token ceiling was reached. Raise tokens_per_day or wait for the next day.
• A policy rule matched the role's prompt. Reword the prompt or adjust the rule.
• The role is disabled in nightshift.yaml.

nightshift status

error_max_turns

The role ran out of turns before finishing. Reading a file, editing it, running the tests and fixing what broke takes dozens of turns, so a low cap fails work that would otherwise succeed.

roles:
  engineer:
    max_turns: 60     # raise it; the default is 40

A gate always fails

Run the command yourself in the project directory. Gates are ordinary shell commands with no special environment, so if it fails for you it will fail for the role.

• Check the command is non-interactive. Anything waiting for input will hit the timeout.
• Check it exits non-zero on failure. Some tools report problems and still exit 0; use expect_stdout for those.
• On Windows, gates run through cmd, so Unix-only commands such as test -f will not work.
• The run log holds the gate's captured output, including the tail where the real error usually is.

Work is missing from my branch

Check for a preserved branch. A merge conflict, a failed gate or a refused commit all leave the work on its own branch rather than discarding it.

git branch --list 'nightshift/*'
git log --oneline nightshift/engineer/...

Provider problems

• claude or codex not found on PATH: install the CLI and sign in, then run doctor.
• Not logged in: the run log will say so. This is never retried, since retrying cannot fix it.
• Rate limited: this is retried with exponential backoff. Persistent rate limiting means your cadences are too dense; spread them out.
• Codex refuses to run outside a git repository: either git init the project, or accept that those roles will not run.

Reading the run log

Every line is one JSON record. Records are typed: cycle_start, attempt, gate, cycle_end, skip and shutdown. Attempts carry the provider, session id, exit code, error classification, token usage and, on failure, the raw output.

# Everything that failed
grep '"outcome":"failed"' .nightshift/state.ndjson

# Gate results only
grep '"kind":"gate"' .nightshift/state.ndjson

# Readable, if you have jq
jq -r 'select(.kind=="cycle_end") | "\(.time) \(.role) \(.outcome) \(.reason)"' \
  .nightshift/state.ndjson