Nightshift
Isolation, merging and secret scanning
Two roles editing the same working tree at the same time would overwrite each other. Isolation is what makes running them in parallel safe.
Last updated: July 25, 2026
Quick answer
With concurrency above one, each writing role works in its own git worktree on its own branch, and its gates run inside that checkout. Verified work merges back through a queue that serialises merges. A merge conflict is treated as a failure: the merge aborts, the branch is preserved, and the reason names the conflicting files. Conflicts are never resolved automatically.
- One git worktree and branch per writing role
- Gates run inside the isolated checkout
- Merges are serialised, so two merges never race
- Conflicts abort and preserve the branch for review
- Unverified work never reaches your base branch
How a cycle is isolated
- 1
A branch is created off your current base
Named nightshift/<role>/<cycle>, so you can always tell which branches Nightshift created.
- 2
The role works inside that checkout
It lives under .nightshift/worktrees, which is git-ignored.
- 3
Gates run there too
So verification tests the isolated copy, not your main working tree.
- 4
Verified work is committed and merged
Through a queue that serialises merges into the base branch.
- 5
The worktree is removed
The branch is deleted on success, and kept when there is unmerged work worth reviewing.
nightshift serve --concurrency 3
Read-only roles get no worktree
A read-only role has nothing to merge, so spending a checkout on it would be waste. It runs in the main tree, where it cannot edit anything anyway.
Merge conflicts
When two roles touch the same lines, the second merge conflicts. Nightshift aborts the merge, leaves the repository clean, preserves the branch, and fails the cycle with a reason naming the conflicting files.
[tester] MERGE FAILED: merge conflict in shared.txt; branchnightshift/tester/tester-20260725T040000Z preserved for review
Conflicts are never auto-resolved
Guessing at how to combine two roles' edits while you are asleep is how an unattended tool destroys work. The branch is kept so you can decide. Find anything waiting with: git branch --list 'nightshift/*'
git branch --list 'nightshift/*'
Secret scanning
Before any commit, the staged diff is scanned for credential shapes. A match refuses the commit, unstages the changes and leaves the worktree intact for inspection.
- Private key blocks
- AWS access keys
- GitHub, Slack, OpenAI, Anthropic and Stripe live keys
- Google API keys
- Assignments of the form password = "..." or api_key: "..." with a long value
It errs toward false positives
A refused commit costs you a review. A leaked key costs considerably more. Prose that merely mentions API keys, and code that reads them from the environment, are not flagged.
When isolation is not available
Isolation needs git and a repository with at least one commit. Without it, Nightshift stays sequential and says so, because two roles sharing one working tree would overwrite each other. This is a fallback, not a failure: everything still runs, one role at a time.
note: worktree isolation unavailable (not a git repository)note: falling back to one role at a time; concurrency needs isolation
You can also turn isolation off deliberately with --isolate=false, which forces one role at a time.
Frequently asked questions
How many roles should run at once?
Start with two. Concurrency multiplies token spend per unit of wall-clock time, and independent roles benefit most. Roles that touch the same files will conflict, so there is little point running them together.
What happens to a branch whose work failed its gates?
It is preserved. Unverified work never merges into your base branch, but it is not thrown away either, so you can look at what the agent attempted.
Does Nightshift ever push or force push?
No. It works entirely locally: branches, commits and merges in your own repository. Pushing is yours to do, and the default policy explicitly forbids force pushing to the main branch.
Was this page helpful?
Related articles
Nightshift
Verification gates
Gates are shell commands that must pass before a role's work is accepted. How to write them for code, content, research and reports.
Nightshift
The fleet file reference
Complete reference for nightshift.yaml: roles, cadences, modes, sandbox levels, limits and the policy layer.
Nightshift
Troubleshooting Nightshift
Diagnose skipped roles, failing gates, exhausted turns, missing connectors and unmerged work in Nightshift.
