Documentation
Troubleshoot a Nightshift run
Diagnose setup, gates, state, process leases, watchman behavior, and stop conditions without making the situation worse.
Answers: troubleshoot Nightshift · Updated
Run Doctor first. It is intentionally read-only and reports what Nightshift sees before any repair changes the evidence. Then fix the narrowest confirmed cause.
Start with Doctor
Doctor inspects the workspace, rules, markers, session identity, process lease, watchman, and classified next actions. It never repairs simply because it was invoked.
- Confirm the resolved workspace path.
- Check STOP and stall markers.
- Inspect the active session and process lease.
- Verify the watchman is looking at the same project.
Common causes
Most failures are boundary problems rather than item logic.
- A permission prompt cannot be answered headlessly.
- A stale STOP or stall marker remains from testing.
- The host and watchman run in different environments.
- A gate expects tooling the project does not have.
- The open interface is stale after headless recovery.
Preserve evidence
Do not delete state or start a second shift just to see whether it helps. Read the shift log, parking lot, and process evidence first. Export a support bundle when diagnosis needs to leave the machine.
Start with a bounded prompt
This prompt names the outcome and preserves Nightshift’s review boundary. Paste it into the supported coding host from the project you want to change.
Run Nightshift Doctor and explain its facts, warnings, and classified next actions without repairing anything.What this workflow does not claim
- Doctor is intentionally read-only and does not perform the repair it recommends.
- Recovery should not be forced when session ownership or liveness is uncertain.
Evidence and sources
These links support the released behavior, public outcomes, or problem language described on this page.
Frequently asked questions
Why is the recovered session not visible in my open window?
The headless worker can append turns that an already-open interface cannot display. Reopen the task before interacting.
Should I start another shift when one looks stuck?
No. Diagnose the existing shift first; Start refuses to arm a second live shift by design.