Omniscio

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 tidy and 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.
    • /audits gives every audit its lastRunByProject: for each project the audit has run on, its newest live run — when it started (runAt), its status and its total findingsCount. 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 /audits list is built: it first waits out any provisioning pass still running, so it never shows a half-copied catalog (a spec not yet copied reads installedSpecPath: null, one not yet refreshed a false hasLocalEdits). 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 every lastRunByProject empty.
    • …/runs/:runId/report answers with that run's report, or null when it has none — null is a normal success (the run is in flight, its report was cleaned up, or it is one of the stranded rows whose report_path was 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 separate GET /nighty-tidy-2/report.
  • manage automations (applies immediately): POST /nighty-tidy-2/subscriptions (body carries an optional id to edit, plus name, an optional customPrompt scope, and an optional engine/model — any launchable engine; honors X-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 optional customPrompt scope + an optional engine/model — any launchable engine) enqueues nighty_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 answers 200 { ok, applied, result } — and a 200 there is not proof an audit started: read result.status, which is started (with the new runId) or skipped (with reason: 'already-running' and the existingRunId of the run it collided with, so a second concurrent run is never launched). Counting 200s 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.

Last verified 2026-10-26