Nighty Tidy — how it works (part 2)
Part 2 of the Nighty Tidy page: the machinery under an overnight run, the sessions it tags as its own, and how to drive it from an AI operator session; the boundaries to know before an unattended night are part 3.
On this page
What it is
This is part 2 of the Nighty Tidy page. It covers how a run actually happens; the boundaries to know before an unattended night are on part 3.
Where to find it
The same Nighty Tidy panel as part 1.
How it behaves
Auto-tagged sessions
Every Nighty Tidy session is tagged automatically so you can find and group them from the tag filter and the sidebar chips:
- An audit session gets two library tags:
nighty tidyand the audit's name (e.g.Test Coverage). - A spawned apply / implementation "wave" session gets those two plus
implementation.
The tags are global (they filter across every project), created once and reused on later runs (no duplicates), and created without a color — recolor or rename them anytime in Settings → Tags. Tagging is best-effort: if the tag system ever hiccups it is skipped silently and never disrupts the audit or the wave.
When the feature first ships it also runs a one-time pass over your EXISTING Nighty Tidy sessions and tags them the same way. That pass runs in the background after startup (it never slows launch) and only touches sessions that aren't already tagged, so it is safe to re-run.
Implementation: nighty-tidy-tags.ts; locked by invariant I48 in the contract. To manage the tags from outside the app, see cli-tags.md.
Operator sessions (drive Nighty Tidy with AI)
The panel sidebar carries an Operator sessions list with "+ New session".
Each spawns an AI operator — a normal Claude session, briefed by a standing-
context primer on what NT2 is and how to drive it — so you can say "go set up
Nighty Tidy" and it does it. The operator acts through a dedicated, gated CLI
control API (/nighty-tidy-2/* on the local control server; the panel is in-app React
with no bridge, so a spawned CLI session drives NT2 through this API instead):
- reads (bearer + read-budgeted):
GET /nighty-tidy-2/audits | projects | subscriptions | runs,…/runs/:runId/report | findings./auditsgives every audit itslastRunByProject: for each project the audit has run on, its newest live run — when it started (runAt), itsstatusand its totalfindingsCount. An audit that never ran on any project carries{}, and runs or projects that were deleted never appear. It is one query over the run history per list build, read in parallel with the spec files.- How the
/auditslist is built: it first waits out any provisioning pass still running, so it never shows a half-copied catalog (a spec not yet copied readsinstalledSpecPath: null, one not yet refreshed a falsehasLocalEdits). The spec reads are asynchronous because, done on the main thread (before 2026-09-30), opening the list held it for 1.7-4.5 s. Custom audits are merged after the built-ins. Both the custom-audit read and the run-history read are fail-safe: if either fails, the list still returns the built-ins, with no custom audits and everylastRunByProjectempty. …/runs/:runId/reportanswers with that run's report, ornullwhen it has none —nullis a normal success (the run is in flight, its report was cleaned up, or it is one of the stranded rows whosereport_pathwas never written). It never falls back to the newest run of the same audit, so a run with no report reads as having none rather than showing another run's findings. The slug-level viewer is the separateGET /nighty-tidy-2/report.
- manage automations (applies immediately):
POST /nighty-tidy-2/subscriptions(body carries an optionalidto edit, plusname, an optionalcustomPromptscope, and an optionalengine/model— any launchable engine; honorsX-Client-Request-Id— a retried save replays the remembered response instead of double-creating),DELETE /nighty-tidy-2/subscriptions/:id— deletes ONE automation by its id (the id rides in the URL path; a DELETE request body is dropped by the control server). - run an audit now (approval-gated — it spends a run):
POST /nighty-tidy-2/audits/:slug/run-now(body may carry an optionalcustomPromptscope + an optionalengine/model— any launchable engine) enqueuesnighty_tidy_2.run_now, which the dispatcher runs only after you approve it in the inbox. With that approval switched off the request applies inline and answers200 { ok, applied, result }— and a200there is not proof an audit started: readresult.status, which isstarted(with the newrunId) orskipped(withreason: 'already-running'and theexistingRunIdof the run it collided with, so a second concurrent run is never launched). Counting200s counts wrong. The requester is told either way, including on the queued (202) road. A skipped run-now also carries a plain sentence naming why, and the session that asked is woken with it as a not-started decision: "The user approved … but nothing was started. Reason: …", with its own card row. Before 2026-11-08 that session learned only that its request had been approved, which read as though the audit were running.
Operator sessions live in their own session-host project (__nightytidy2_agent__),
NOT the plugin project — so a session that needs you surfaces in the global Needs
You like SMS / Mind Map sessions, instead of being __plugin__-hidden. Clicking
one swaps the panel for its chat (the sidebar stays); a nav tab brings the panel
back. Operator sessions are desktop-only; the mobile React panel ships the four
audit screens (Run / Findings / History / Custom audits), not the operator-sessions dock.
Stranded runs heal on their own
A run whose findings reached the database but whose counters, report path or final status did not is
repaired automatically — at startup and on the hourly misfailed tick, never on the UI thread, and
only by the true database owner. The repair matches a run with no ingest stamp or one whose
counters disagree with its stored findings (measured 2026-10-15: a run reading 0/0/0/0 beside 331
stored findings), and it never finalises a run that is still running or queued, so an audit
publishing in batches is never frozen mid-publish; a failed row is left to the settle pass alone,
because the ingest stamp is itself what the heal arm reads as proof the run finished. A failed run
that already has findings settles
to its real findings/success outcome once nothing is working it; a live session — or a liveness
read that could not be answered — leaves it exactly as it was, and a needs_input row is never
touched by that pass. Healing is counters + status only: no fix wave is queued while waves are
paused.
A copied-home report heals its run
Sometimes a cloud audit finishes but its report never reaches the app through the normal return
lane — the machine was stopped, or the watcher gave up first. When such a tree is copied home by
hand into the project's own audit-reports/audit-<slug>/ folder (the copies are named
<run-stamp>.box-final-<copy-time>), Nighty Tidy now finds it there at the next app start, and
again on the hourly check, with no hand-run step.
The match is exact and is never a guess. The directory's own state.md or waves.json naming the
run id is the strongest proof, and a directory that names a different run of the same audit is never
used. Failing that, the directory's run stamp must fall inside that run's own dispatch window and
before the next run of that audit started, so an earlier run can never pick up a later one's report.
If two candidate directories could both be the run's and neither names it, the repair refuses and
records why in the log rather than picking one. Before it touches anything it asks whether the run's
session is still being worked: a live session, or a liveness check it could not answer, leaves the
run exactly as it was. A directory must also hold a findings.json that reads cleanly and carries
at least one finding before anything is copied or any status changes; a report without one is left
where it is, and the run keeps the status it had.
Healing means the findings are stored, the severity counters and the report link appear on the run, and its status becomes the real result it earned. The repair never wakes a machine, never resumes or messages a session, and never starts a fix wave; the fix waves stay yours to launch from the panel while the overnight fixers are paused.
Related
- Nighty Tidy — part 1, the owned-versus-shared boundary and how to run one.
- Nighty Tidy — known boundaries (part 3) — shared slugs, restarts, failed runs that had published, and audits whose sessions died.
- overseers.md — the standing coordinator that hands out worker sessions.
- night-shift.md — queuing a plan of work to run while you sleep.
Last verified 2026-10-26