nightshift
Run an agent unattended for hours — and get a morning brief that is an audit, not a summary.
Sign a manifest before the work: what it is for, which commands prove it worked,
what must never run, and what it is allowed to spend. Then wrap each mutating
command in a checkpoint that rolls itself back when verification fails. In the
morning, get a brief generated from the run's own journal — what changed, what
was verified, what was not, and the exact command to undo the night.
dsh plugin --profile web add github:liyixuan201211/nightshift
No install needed to try it:
npx --yes github:liyixuan201211/nightshift --help
The problem this is for
The tools this belongs to each answer one question about one moment —
ctx-budget what it will cost, blastradius what it would destroy, deadend
whether this failed before, mcp-cap what a server can do, skillnotary what a
skill may do, rewind how to get it back. All of them are point-in-time and
stateless.
An unattended run is neither. Once the person leaves, nobody is standing at
those checkpoints — and the failures that matter over hours are the quiet ones.
Drift: the objective changing, the budget passing, a step failing silently, a
loop spinning. No single-point tool is watching for those.
nightshift is the layer that watches. It is also the generalisation of
something the family already does by hand — ctx-budget's own bundle notes that
it reads a tools/list dump that mcp-cap already produced.
The one idea
The manifest is a contract you sign while you are still awake. The brief is
the audit of that contract.
nightshift init --root ~/work \
--objective "finish the auth refactor and get the suite green" \
--deliverable "npm test passes" \
--accept "tests=npm test" \
--accept "types=npx tsc --noEmit" \
--forbid "git push" \
--command "npm run build"
nightshift preflight --root ~/work # may I start?
nightshift step --root ~/work --verify "npm test" -- npm run build
nightshift acceptance --root ~/work
nightshift brief --root ~/work
Only two of the declared things are enforceable, and that is the point:
acceptance[] is a list of shell commands, so "done" is an exit code rather
than a claim; forbidden[] is matched before execution, so a rule is a gate
rather than a post-mortem. An objective with no acceptance checks produces a
brief that says unclear and means it.
What the brief contains
The brief is a rendering of the journal, never a summary written from
memory. That direction is what makes it worth reading:
- a claim with no event behind it cannot appear
- a declared acceptance check that never ran is reported as not run, not omitted
- a step whose success was never verified is reported as unverified — a
different fact from "passed"
- every action the gate refused is listed, because a report of what a run
did cannot show whether the gate ever fired
- tools that were unavailable are named, with the count (
5/6 family tools)
- the baseline snapshot id and the exact
rewind undo line to reverse the night
Its bottom line is one word: verified, failed, incomplete, recovered,
nothing-done, refused, or unclear.
The gate sits next to the action, not the session
preflight judges the commands a run declares. But a step can run anything,
and an unattended run has hours in which to change its mind. So the same
judgement runs again at every execution:
- forbidden patterns — a standing instruction, matched first and never
routable-around
- irreversibility class — priced by
blastradius, read from the exit
code (lost → terminal, costly → recoverable, safe → two-way,
anything else → unknown)
- curfew — after
--curfew-minutes, no new one-way action may start
(two-way actions stay allowed: refusing to save a file at 6am would be a worse
failure than the one a curfew prevents)
- class policy — the manifest's own knobs
A refusal means the command did not run and nothing was changed.
A real disagreement between two of the tools
blastradius calls this lost:
{ "recoverability": "lost",
"why": "not inside a git repository, so nothing can restore it",
"samples": ["data.txt"], "verdict": "lost" }
It means git cannot restore it. But rewind exists precisely to restore files
git never tracked, with or without git — so for a path inside the protected
root, the checkpoint taken moments later does restore it.
Trusting either tool alone is wrong: believing blastradius refuses nearly every
real refactor; believing the snapshot treats rm -rf ~/something-else as
recoverable when the snapshot never covered it. So nightshift uses
blastradius's own samples to decide:
| at-risk paths | result |
|---|
| all inside the protected root | downgraded to one_way_recoverable — warned, allowed |
| any outside the root | stays one_way_terminal — refused |
| findings name no paths | stays one_way_terminal — refused |
The last row is deliberate: being unable to tell is never an upgrade.
Refusing to start is a feature
preflight exits 4 and starts nothing when a run would be unrecoverable. The
usual cause is that rewind is unavailable — an unattended run with no way
back is the one thing this refuses outright. Fix the cause; there is no flag
that gets past it.
Exit codes are the contract
| Exit | Meaning |
|---|
0 | ok |
1 | error |
2 | usage error |
3 | attention — a preflight warning, or a step that failed and was rolled back |
4 | refused — nothing was done, on purpose |
5 | degraded — it ran, but some checks could not be performed |
6 | nothing — there was nothing to do |
-q suppresses output and never the exit code.
Notes on the seams with its siblings
--exclude .nightshift is not optional. nightshift keeps its journal
inside the directory rewind protects, so every rewind call passes the
exclude. Without it the journal would dirty its own snapshots and rewind status would never be clean. (Tested.)- Exit codes are translated, not trusted.
3 means OVER_BUDGET in
ctx-budget, LOST in blastradius, DRIFT in deadend, CHANGED in mcp-cap, and
"the tree differs" in rewind. Each tool's dialect is data in src/tools.js,
overridable per run, and nightshift tools prints the table.
unverifiable is not ok. blastradius exits 5 for any command outside
its vocabulary, and its JSON says "verdict": "none" when it means "I have no
analysis for you". Reading that string as "no risk" waves through
curl … | sh, so nightshift maps on the exit code and treats the verdict
as corroboration only.- "Not priced" is recorded as
info, never as a pass. blastradius only
understands destructive commands, so pricing touch legitimately returns "I
cannot tell you". Escalating that to a warning every time would train the
operator to ignore warnings — so it is visible in the brief without raising the
verdict. (onUnpriced, default ignore.)
Honest limits
- It does not decide what to do. It holds a run to what was already decided.
- It is not a scheduler. It does not wake up; something drives it.
- It is not a sandbox. It predicts with
blastradius and recovers with
rewind; it does not isolate.
- It fetches nothing. There is no
npx fallback unless --allow-npx is
passed. Resolution is local: --tools-dir, $NIGHTSHIFT_TOOLS_DIR, the
configured search path, or PATH.
- The brief is only as good as the acceptance checks. No oracle, no
verification — and the brief will say so rather than implying otherwise.
Design
See DESIGN.md for the architecture, the exit-code normalisation
table, and the reasoning behind the ordering rule that a refused run must not
leave a snapshot behind.
License
MIT
