@niroai/niro 0.10.0 → 0.11.0

package/src/commands/cleanup.js

@@ -0,0 +1,689 @@
+/**
+ * `niro cleanup-temp-projects` — find local registrations whose temporary project no longer exists on
+ * the server, and put those folders back on their original project.
+ *
+ * WHY THIS EXISTS. A temporary project can disappear without this machine ever being told: someone
+ * deletes it in the web UI, or the idle sweeper reaps it after N days. The folder keeps a registration
+ * pointing at a project id that resolves to nothing, and that dead pointer is not harmless — it is what
+ * makes `niro new-temp-project` in a second worktree refuse with "already held by another folder".
+ *
+ * `niro discard-temp-project` already repairs one folder in this state (release.js). What it cannot do
+ * is find them: you have to be standing in the affected folder, or already know the id. This is the
+ * sweep. It reads the same registry, asks the server once per temporary project, and repairs the ones
+ * that are gone.
+ *
+ * THREE RULES IT WILL NOT BREAK.
+ *
+ * 1. Only a definitive "Project not found" counts as gone. A 401, a 500, a timeout or a genuine
+ *    permissions refusal leaves the entry exactly as it was and is reported as "could not check". This
+ *    command touches many entries at once, so treating an unreachable server as "everything is gone"
+ *    would wipe a whole machine's registrations on one bad connection.
+ * 2. Nothing is ever unregistered. A folder is moved back to its source project, not deleted from the
+ *    registry — the watch daemon still needs somewhere to sync it.
+ * 3. Nothing is guessed. A temporary project is only repaired when some folder registered against it
+ *    recorded which project it was a working copy of.
+ *
+ * It never deletes anything server-side. Every project it acts on is already gone.
+ *
+ * THREE KINDS OF STALE POINTER, and they need different repairs:
+ *
+ *   a temporary copy   -> the folder is pointed back at the project it was a copy OF. It has somewhere
+ *                         to fall back to, and the watch daemon still needs to sync it somewhere.
+ *   an ordinary repo   -> there is no fallback, so the registration is removed. Only when the repo is
+ *                         gone too: a project can be deleted while its repos are remapped to another
+ *                         one, and unregistering a folder that is still syncing fine would be a bug.
+ *   a `.niro-project`  -> the pin file is deleted. Nothing else sweeps these, so a pin naming a project
+ *                         somebody removed in the web app just dangles for ever.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const agentApi = require("../lib/agentApi");
+const api = require("../lib/api");
+const color = require("../lib/color");
+const credentials = require("../lib/credentials");
+const prompt = require("../lib/prompt");
+const { projectsToRows } = require("./projects");
+const tempProject = require("../lib/tempProject");
+const niroProjectFile = require("../lib/niroProjectFile");
+const takeoverRestore = require("../lib/takeoverRestore");
+const watchState = require("../lib/watchState");
+
+const ok = (s) => color.green(s);
+const warn = (s) => color.yellow(s);
+
+/**
+ * Group the local registry into one candidate per temporary project.
+ *
+ * A temporary project can cover SEVERAL folders (ADR-016 extends one copy with more repos), so the
+ * unit of work is the project, not the folder: one server call answers for all of its folders.
+ *
+ * A project becomes a unit of work when SOME folder carries a takeover backup — that backup is the only
+ * thing on this machine saying "this id is a temporary project" rather than an ordinary one, and asking
+ * the server would not help because a project that is gone answers nothing about what it used to be.
+ *
+ * Membership is then by `projectId`, which deliberately includes a sibling folder that has no backup of
+ * its own. Those siblings exist — a multi-repo takeover only needs ONE folder to record the source — and
+ * leaving them behind is what strands a folder pointing at a deleted project while its neighbour gets
+ * repaired. The `witness` is the folder that did record it, and it answers for the whole group because
+ * every folder in one copy clones the SAME source project.
+ *
+ * `sourceProjectId` comes back null when no folder recorded one (a partial backup, or one written by an
+ * older CLI). That is not the same as "not a temporary project": it is a temporary project with no way
+ * back written down, which the caller reports and leaves alone rather than guessing at, exactly as
+ * `niro discard-temp-project` does.
+ *
+ * Pure, so the grouping can be tested without a server.
+ *
+ * @returns {Array<{tempProjectId: string, folders: object[], sourceProjectId: string|null}>}
+ */
+function groupCandidates(entries) {
+  const takenOver = new Set(
+    entries.filter((e) => e.projectId && e.takeover).map((e) => e.projectId));
+  const out = [];
+  for (const tempProjectId of takenOver) {
+    const folders = entries.filter((e) => e.projectId === tempProjectId);
+    const witness = folders.find((e) => e.takeover && e.takeover.sourceProjectId);
+    out.push({
+      tempProjectId,
+      folders,
+      sourceProjectId: witness ? witness.takeover.sourceProjectId : null,
+    });
+  }
+  return out.sort((a, b) => (a.tempProjectId < b.tempProjectId ? -1 : 1));
+}
+
+/**
+ * Registry entries that are ORDINARY registrations: they name a project but were never taken over.
+ * Grouped by project so one server call answers for all of their folders, exactly as the temporary
+ * ones are.
+ *
+ * These are out of scope for the repair path — there is no source project to fall back to — but they
+ * are very much in scope for the sweep, because a folder registered against a project somebody deleted
+ * is the case that leaves the daemon throwing the same error on every start with nothing to clear it.
+ */
+function plainRegistrations(entries, tempProjectIds = new Set()) {
+  const byProject = new Map();
+  for (const e of entries) {
+    if (!e.projectId || e.takeover) continue;
+    // A folder pulled into a multi-repo takeover records no backup of its own — only one folder in a
+    // copy has to. Such a sibling looks exactly like an ordinary registration here, and treating it as
+    // one would UNREGISTER it while its neighbour was being repaired, which is the strand-a-sibling bug
+    // groupCandidates already exists to avoid. Anything naming a known temporary copy belongs to that
+    // copy's group, not here.
+    if (tempProjectIds.has(e.projectId)) continue;
+    if (!byProject.has(e.projectId)) byProject.set(e.projectId, []);
+    byProject.get(e.projectId).push(e);
+  }
+  return [...byProject.entries()]
+    .map(([projectId, folders]) => ({ projectId, folders }))
+    .sort((a, b) => (a.projectId < b.projectId ? -1 : 1));
+}
+
+/**
+ * The `.niro-project` pins that the registry's own folders OWN, as {folderPath, projectId}.
+ *
+ * niroProjectFile.read walks UP the tree, so standing in a subfolder of a pinned repo returns the
+ * parent's pin. Healing that would delete a pin belonging to a folder this sweep was never looking at,
+ * so a pin only counts when the file sits in the folder itself — the same test `niro
+ * discard-temp-project` applies before it heals an old-style pin.
+ */
+function ownedPins(entries, apiUrl) {
+  const out = [];
+  const seen = new Set();
+  for (const e of entries) {
+    let dir = path.resolve(e.folderPath);
+    // Resolved through symlinks, so a folder registered by its link and another by its target are ONE
+    // pin, not two. Without this the same file is counted, reported and deleted twice.
+    try { dir = fs.realpathSync(dir); } catch { continue; } // gone, or unreadable — nothing to do here
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    let pin = null;
+    try { pin = niroProjectFile.read(dir); } catch { continue; }
+    if (!pin || !pin.id || !pin.source) continue;
+    let pinDir;
+    try { pinDir = path.dirname(fs.realpathSync(pin.source)); } catch { continue; }
+    if (pinDir !== dir) continue; // a parent's pin, not this folder's
+    out.push({ folderPath: dir, projectId: pin.id, taggedForThisBackend: Boolean(e.apiUrl)
+      && watchState.matchesBackend(e, apiUrl) });
+  }
+  return out;
+}
+
+/**
+ * Is this string plausibly a project id or alias, rather than something that only ended up on the first
+ * line of a `.niro-project` file?
+ *
+ * niroProjectFile.parse takes the first line that is not a comment. A file left mid-merge therefore
+ * yields `<<<<<<< HEAD`, and the server reports that as not found exactly like a deleted project. One
+ * character class covers the realistic cases: ids are UUIDs and aliases are slugs, so neither contains
+ * whitespace or a conflict marker.
+ */
+function looksLikeProjectRef(id) {
+  return typeof id === "string" && id.length > 0 && id.length <= 200 && !/[\s<>=|]/.test(id);
+}
+
+/**
+ * Ask the server about one temporary project and classify it.
+ *
+ * "gone" is decided by tempProject.isProjectNotFound, which reads the MESSAGE rather than the status:
+ * the backend answers 403 both for a deleted project and for one belonging to someone else, so status
+ * alone cannot tell "it is gone" from "you may not see it". Anything that is not a definitive
+ * not-found lands in "unknown" and changes nothing.
+ */
+async function probe(candidate) {
+  try {
+    const project = await api.get(`/api/projects/${encodeURIComponent(candidate.tempProjectId)}`);
+    return { ...candidate, state: "alive", project };
+  } catch (err) {
+    if (tempProject.isProjectNotFound(err)) return { ...candidate, state: "gone" };
+    return { ...candidate, state: "unknown", error: err.message };
+  }
+}
+
+async function cleanup(opts = {}) {
+  credentials.requireCreds();
+  // `--json` reads like a formatting flag, and there is no way to ask a question down a JSON stream —
+  // so on its own, at a terminal, it would write to the registry without ever asking. Someone reaching
+  // for it to LOOK at the state would change it. Make the intent explicit instead. Unattended runs
+  // (an agent, a script) have no terminal and are unaffected.
+  if (opts.json && !opts.dryRun && !opts.yes && process.stdout.isTTY) {
+    throw new Error("`--json` cannot show a confirmation prompt, and this command writes to your local " +
+        "registry. Add `--dry-run` to look without changing anything, or `-y` to go ahead.");
+  }
+  // Quiet mode is for the daemon, which runs this every six hours into a log nobody reads by choice.
+  // It silences the routine narration ("checking 2 projects", "nothing to clean up") and keeps every
+  // line that reports something CHANGED. A background job that says nothing when it did nothing is one
+  // people still trust when it does speak.
+  const say = (...args) => { if (!opts.quiet) console.log(...args); };
+  // `--forget <path>`: drop ONE registration, because the developer said so.
+  //
+  // This is the supported way to clear a folder you have deleted, and the answer to a customer who
+  // asked whether they should edit projects.json by hand. It is deliberately a separate, explicit
+  // action rather than something the sweep does: absence is not proof a folder is gone for good, and
+  // the sweep only ever REPORTS a missing folder. Here a person has looked and decided.
+  //
+  // It never touches the folder or anything on the server — only this machine's note that the folder
+  // was being synced.
+  if (opts.forget) {
+    const target = path.resolve(opts.forget);
+    const entry = watchState.peek(target);
+    if (!entry) {
+      throw new Error(`Nothing on this machine is registered for ${target}. ` +
+          "Run `niro doctor sync-registry` to see what is.");
+    }
+    if (fs.existsSync(target) && !opts.yes && process.stdout.isTTY && !prompt.isNonInteractive()) {
+      console.log(warn(`    ${target} still exists on disk, and is being synced.`));
+      const sure = await prompt.confirm("  Stop syncing it anyway?", false);
+      if (!sure) { console.log("Aborted."); return; }
+    }
+    // Compare-and-delete on the gitId that was read a moment ago, the same guard the sweep uses: a
+    // `niro new-temp-project` landing in between must not have its fresh registration removed.
+    if (!watchState.remove(target, entry.gitId)) {
+      throw new Error(`${target} was re-registered while this ran — nothing was changed. Try again.`);
+    }
+    console.log(`    ${ok("✓")} Stopped tracking ${target}. The folder itself was not touched.`);
+    return;
+  }
+
+  const baseUrl = api.currentBaseUrl();
+  const entries = watchState.allLocal(baseUrl);
+  const candidates = groupCandidates(entries);
+  const tempIds = new Set(candidates.map((c) => c.tempProjectId));
+  const plain = plainRegistrations(entries, tempIds);
+  // Pins naming a temporary copy are deliberately left to `niro discard-temp-project`, which knows how
+  // to restore the previous pin rather than just deleting the file.
+  //
+  // The other two filters exist because a `.niro-project` is a file in the developer's REPOSITORY, and
+  // usually tracked in git. Deleting one is the most destructive thing this command does, so it gets
+  // the strictest entry conditions:
+  //
+  //  - the id must be plausible. niroProjectFile takes the first non-comment line, so a file left in a
+  //    merge conflict yields "<<<<<<< HEAD" as the "project id", which the server naturally reports as
+  //    not found. Deleting a developer's unresolved conflict mid-merge is not a cleanup.
+  //  - the folder must be tagged for THIS backend. watchState treats a missing apiUrl as matching any
+  //    backend, which is right for a registration (the repo check backstops it) and wrong here: a
+  //    legacy untagged entry swept while pointed at a local stack is judged against a different
+  //    account's project list.
+  const pins = ownedPins(entries, baseUrl)
+    .filter((pn) => !tempIds.has(pn.projectId))
+    .filter((pn) => looksLikeProjectRef(pn.projectId))
+    .filter((pn) => pn.taggedForThisBackend);
+
+  // One probe per distinct project id, whatever named it. A folder, its pin and a sibling folder very
+  // often name the SAME project, and asking three times would be three chances to get three different
+  // answers about one thing — as well as three times the load.
+  // ORDER MATTERS, and pins come LAST on purpose. A probe of a registration returns the whole project
+  // record, so it teaches us that project's alias; a pin often holds exactly that alias. Probing pins
+  // after everything else means the alias is already known-alive by the time the pin is considered, and
+  // the pin is never asked about at all. Reorder this and a live project's pin gets deleted — which is
+  // what the alias test locks.
+  const projectIds = [...new Set([
+    ...candidates.map((c) => c.tempProjectId),
+    ...plain.map((r) => r.projectId),
+    ...pins.map((p) => p.projectId),
+  ])];
+
+  if (projectIds.length === 0) {
+    if (opts.json) {
+      console.log(JSON.stringify({ checked: 0, alive: [], gone: [], orphaned: [], unknown: [],
+        repaired: [], unregistered: [], stale_pins: [], kept_repo_alive: [],
+        repo_check_failed: [], untagged: [],
+        healed: [], failed: [],
+        dry_run: Boolean(opts.dryRun) }));
+      return;
+    }
+    say(`\n    ${ok("✓")} Nothing registered on this machine — nothing to clean up.`);
+    return;
+  }
+
+  if (!opts.json) {
+    say(`\n    Checking ${projectIds.length} project` +
+        `${projectIds.length === 1 ? "" : "s"} against the server...\n`);
+  }
+
+  // The account's own project list, fetched ONCE, and it is the authority on existence.
+  //
+  // Asking `/api/projects/{x}` directly is NOT enough, and a real dry run is what proved it. A
+  // `.niro-project` file may hold an ALIAS rather than an id — this repo's own pin says `niro-cli` —
+  // and that route answers `403 Project not found: niro-cli` for a project that is alive and sitting in
+  // the list under exactly that alias. Trusting the direct lookup would have deleted the pin of a live
+  // project, which is the one thing a pin sweep must never do.
+  //
+  // So: anything the list knows, by id OR by alias, is alive and is not probed at all. Only a reference
+  // the list has never heard of goes on to the direct check, where a definitive not-found is required.
+  const known = new Set();
+  let listed;
+  try {
+    listed = await api.get("/api/projects");
+  } catch (err) {
+    throw new Error(`Could not list your projects, so nothing was checked: ${err.message}`);
+  }
+  // FAIL CLOSED on a shape we do not recognise. The first cut only refused when the request THREW,
+  // and that is not the dangerous case. api.js returns the raw body for a 200 that is not JSON, so a
+  // proxy interstitial, an SSO sign-in page or a captcha challenge all arrive as a plain string —
+  // which parsed to zero rows, looked exactly like "you own no projects", and sent every reference to
+  // the direct lookup. There an ALIAS always answers "Project not found", so the sweep would have
+  // deleted the `.niro-project` of every live repo whose pin holds one. That file is tracked in git.
+  // Proven end to end over a real socket during review: the same live project keeps its pin when the
+  // list answers JSON and loses it when the list answers HTML.
+  if (!Array.isArray(listed) && !(listed && typeof listed === "object" && Array.isArray(listed.projects))) {
+    throw new Error("Could not read your project list — the server answered with something this " +
+        "version does not recognise, so nothing was checked. Nothing has been changed.");
+  }
+  for (const r of projectsToRows(listed)) {
+    known.add(r.project_id);
+    if (r.alias) known.add(r.alias);
+  }
+
+
+  // Sequential, one per project id. Answers are shared by every folder and pin naming that project.
+  const verdicts = new Map();
+  for (const id of projectIds) {
+    if (known.has(id)) { verdicts.set(id, { tempProjectId: id, folders: [], state: "alive" }); continue; }
+    const v = await probe({ tempProjectId: id, folders: [] });
+    verdicts.set(id, v);
+    // A probe that found a live project tells us its id AND its alias. Both are now known-alive, so a
+    // pin naming the alias is never separately probed and judged gone. Review found this evidence had
+    // been fetched and thrown away: the registration's probe returned the very project whose alias the
+    // pin held, and the pin was deleted anyway.
+    const proj = v.state === "alive" ? v.project : null;
+    if (proj) {
+      if (proj.project_id) known.add(proj.project_id);
+      if (proj.alias) known.add(proj.alias);
+    }
+  }
+  // Re-check every "gone" verdict against what the probes taught us.
+  //
+  // This was deleted once, on the claim that pins are probed last so an alias is always known first.
+  // That claim was wrong and the deletion was a mistake: the ordering only puts pins after
+  // REGISTRATIONS, and two pins are ordered against each other by registry order, so one pin holding
+  // another project's alias is judged before the probe that would have revealed it. A surviving
+  // mutation was evidence the tests were thin, not that the branch was dead.
+  for (const [id, v] of verdicts) {
+    if (v.state === "gone" && known.has(id)) verdicts.set(id, { ...v, state: "alive" });
+  }
+  const isGone = (id) => verdicts.get(id).state === "gone";
+
+  const results = candidates.map((c) => {
+    const v = verdicts.get(c.tempProjectId);
+    return { ...c, state: v.state, error: v.error, project: v.project };
+  });
+  const plainGone = plain.filter((r) => isGone(r.projectId));
+  const pinsGone = pins.filter((pn) => isGone(pn.projectId));
+
+  const alive = results.filter((r) => r.state === "alive");
+  const gone = results.filter((r) => r.state === "gone" && r.sourceProjectId);
+  // Gone, but no folder recorded which project it was a copy of. There is nothing to restore it to, so
+  // it is reported and left alone rather than guessed at.
+  const orphaned = results.filter((r) => r.state === "gone" && !r.sourceProjectId);
+  const unknown = results.filter((r) => r.state === "unknown");
+
+  if (!opts.json && !opts.quiet) {
+    for (const r of results) {
+      const paths = r.folders.map((f) => f.folderPath).join(", ");
+      if (r.state === "alive") {
+        console.log(`    ${ok("✓")} ${color.bold(r.tempProjectId)}  alive` +
+            color.dim(`  (${r.folders.length} folder${r.folders.length === 1 ? "" : "s"})`));
+      } else if (r.state === "gone" && r.sourceProjectId) {
+        console.log(`    ${warn("✗")} ${color.bold(r.tempProjectId)}  gone` +
+            color.dim(`  ${paths}`));
+      } else if (r.state === "gone") {
+        console.log(`    ${warn("✗")} ${color.bold(r.tempProjectId)}  gone, but no folder records its ` +
+            `source project` + color.dim(`  ${paths} — left alone`));
+      } else {
+        console.log(`    ${color.dim("?")} ${color.bold(r.tempProjectId)}  could not check` +
+            color.dim(`  (${r.error}) — left alone`));
+      }
+    }
+    for (const r of plainGone) {
+      console.log(`    ${warn("✗")} ${color.bold(r.projectId)}  gone (not a temporary copy)` +
+          color.dim(`  ${r.folders.map((f) => f.folderPath).join(", ")}`));
+    }
+    for (const pn of pinsGone) {
+      console.log(`    ${warn("?")} ${color.bold(pn.projectId)}  named by a .niro-project file, and ` +
+          `nothing on this backend answers to it` + color.dim(`  ${pn.folderPath}`));
+    }
+  }
+
+  const toRepair = gone.flatMap((r) => r.folders);
+  const toUnpin = pinsGone;
+
+  // FOLDERS THAT ARE GONE FROM DISK.
+  //
+  // A registration whose folder no longer exists is the case a customer actually reported: three
+  // deleted git worktrees, and the daemon erroring on every start for ever with nothing able to clear
+  // them. The sweep cannot help through the server, because the project and the repo are both perfectly
+  // healthy — it is the folder that went.
+  //
+  // BUT ABSENCE IS NOT PROOF. A folder can be missing for a night: an unmounted network share, an
+  // external drive unplugged, a mount that has not come back after a reboot. Dropping the registration
+  // then costs that folder its sync baseline and forces a full re-upload later. This codebase already
+  // learned the harder version of this lesson — watch.js queues file deletions and refuses to believe
+  // them until the folder goes quiet, because a `git checkout` makes files vanish for a moment, and
+  // believing it once cost a customer 494 files.
+  //
+  // So a missing folder is REMEMBERED, not acted on. The first sweep that cannot find it stamps
+  // `missingSince`; a later sweep that still cannot find it, and only after the window has passed,
+  // reports it. Any sweep that DOES find the folder clears the stamp, so an unplugged drive resets the
+  // clock simply by being plugged back in. At the daemon's six-hourly cadence the default window means
+  // a folder has to be missing across roughly four runs, spanning more than a day, before it is even
+  // mentioned — and it is only ever mentioned. Removing the entry stays a human decision.
+  const MISSING_CONFIRM_MS = Number(process.env.NIRO_MISSING_CONFIRM_MS) || 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  const missingConfirmed = [];
+  const missingPending = [];
+  for (const e of entries) {
+    const there = fs.existsSync(e.folderPath);
+    if (there) {
+      if (e.missingSince) watchState.update(e.folderPath, { missingSince: null });
+      continue;
+    }
+    if (!e.missingSince) {
+      // First sighting. Record it and say nothing at all this run.
+      if (!opts.dryRun) watchState.update(e.folderPath, { missingSince: now });
+      missingPending.push(e.folderPath);
+      continue;
+    }
+    const since = Number(e.missingSince);
+    if (Number.isFinite(since) && now - since >= MISSING_CONFIRM_MS) missingConfirmed.push(e.folderPath);
+    else missingPending.push(e.folderPath);
+  }
+
+  // PINS ARE REPORTED. NOTHING MORE. That is the outcome of five review rounds, and the reasoning is
+  // worth keeping because the next person will want to automate this again.
+  //
+  // Every attempt to EDIT a pin automatically produced a new way to destroy a git-tracked file in
+  // somebody's repository. Deleting one, because a renamed project is indistinguishable from a deleted
+  // one when a pin holds an alias. Then repairing one, because the guard meant to spare shared files
+  // checked the wrong path, and because it read a missing `git` binary as "not shared", and because a
+  // single 500 from the resolve endpoint became permission to delete. Each fix passed the whole suite
+  // and a mutation pass, and the next round found the next hole.
+  //
+  // The value never justified it. A pin naming something unresolvable is ALREADY inert: Niro falls back
+  // to the git remote, so deleting or rewriting it changes no answer anybody gets. What has value is
+  // saying it out loud, because nothing else in the CLI does — and the repair (update it, or remove it)
+  // is one edit the developer can make, in a file they own, having seen it.
+  const stillStale = toUnpin;
+
+
+  // Decide the ordinary registrations HERE, before the dry-run gate, so a dry run reports what would
+  // actually happen rather than an upper bound. A gone project alone is not enough to unregister a
+  // folder: a project can be deleted while its repos are remapped onto another one, and that folder is
+  // still syncing perfectly well. Asking whether the REPO is gone too is the same question watch.js's
+  // self-heal asks before removing a poison entry, and it is read-only, so it is safe in a dry run.
+  const toUnregister = [];
+  const keptRepoAlive = [];
+  const untagged = [];
+  const repoCheckFailed = [];
+  for (const e of plainGone.flatMap((r) => r.folders)) {
+    // An entry with no apiUrl matches ANY backend (watchState.matchesBackend), so a registration
+    // written before backend tagging existed is judged against whichever stack the CLI happens to be
+    // pointed at — and BOTH guards then fail the same way, because both ask the wrong server. The repo
+    // check cannot backstop that, because a foreign gitId is indistinguishable from a deleted one.
+    if (!e.apiUrl) { untagged.push(e.folderPath); continue; }
+    try {
+      if (await agentApi.repoExists(e.gitId)) keptRepoAlive.push(e.folderPath);
+      else toUnregister.push(e);
+    } catch (err) {
+      // Could not ask. Changing nothing is the safe half, here as everywhere else in this command.
+      repoCheckFailed.push({ folder: e.folderPath, error: `could not check the repo: ${err.message}` });
+    }
+  }
+  // Pins are reported, not acted on, so they are not WORK — but see notes() below, which prints
+  // them even when there is no work at all. A run whose only finding is a stale pin must still say so.
+  const workCount = toRepair.length + toUnregister.length;
+
+  if (opts.json && opts.dryRun) {
+    console.log(JSON.stringify(summary({ results, alive, gone, orphaned, unknown },
+      { repinned: toRepair.map((f) => f.folderPath),
+        unregistered: toUnregister.map((f) => f.folderPath),
+        stalePins: stillStale.map((pn) => ({ folder: pn.folderPath, names: pn.projectId })),
+        keptRepoAlive, repoCheckFailed, untagged, healed: [], failed: [], dryRun: true })));
+    return;
+  }
+  // Said before any early return: a folder naming a deleted project whose repo is still alive is the
+  // most informative thing this command can find, and it produces no work. Reporting only work would
+  // print "nothing to clean up" over the top of it.
+  const notes = () => {
+    // NOTHING here in --json mode. These lines are prose, and printing them to the same stream as the
+    // payload made `JSON.parse` fail on the very first character. Everything notes() says also appears
+    // in the JSON, so a machine caller loses nothing.
+    if (opts.json) return;
+    if (keptRepoAlive.length) {
+      say(color.dim(`    ${keptRepoAlive.length} folder(s) name a deleted project but their repo still ` +
+          "exists — left alone, it may have been remapped."));
+    }
+    // Printed with console.log, not say(): a folder the sweep can never judge is exactly the thing a
+    // background run must not swallow. Quiet mode silences routine narration, not unanswerable state.
+    for (const f of repoCheckFailed) console.log(warn(`    ${f.folder} — ${f.error}`));
+    if (missingConfirmed.length) {
+      console.log(warn(`\n    ⚠ ${missingConfirmed.length} folder(s) have been missing from disk for over a ` +
+          "day. Their project and repo are fine — it is the folder that is gone, so Niro keeps failing"));
+      console.log(warn("    to sync them. Delete the entry with `niro doctor sync-registry --forget <path>`:"));
+      for (const f of missingConfirmed) console.log(color.dim(`    ${f}`));
+    }
+    if (stillStale.length) {
+      // One line when the daemon says it, the full list when a person asked. Fifteen paths four times a
+      // day, for ever, about something the run will not change, is how a log stops being read.
+      if (opts.quiet) {
+        console.log(warn(`    ${stillStale.length} .niro-project file(s) name something unknown — ` +
+            "run `niro doctor sync-registry` to see them."));
+        return;
+      }
+      console.log(warn(`\n    ⚠ ${stillStale.length} .niro-project file(s) name something this backend does ` +
+          "not recognise. They are NOT deleted — the project may have been renamed and its repo no"));
+      console.log(warn("    longer resolves either, so only you can say whether to update or remove them:"));
+      for (const pn of stillStale) console.log(color.dim(`    ${pn.folderPath}  ->  ${pn.projectId}`));
+    }
+  };
+
+  if (opts.dryRun) {
+    // Same notes a real run prints. A dry run that lists stale pins per-project but omits the "these
+    // are NOT deleted, only you can decide" explanation reads as a threat to delete them.
+    notes();
+    console.log(workCount
+      ? color.dim(`\n    --dry-run: would repair ${toRepair.length} and unregister ` +
+          `${toUnregister.length} folder(s). Nothing was changed.`)
+      : color.dim("\n    --dry-run: nothing to clean up."));
+    return;
+  }
+
+
+  if (workCount === 0) {
+    notes();
+    if (opts.json) {
+      console.log(JSON.stringify(summary({ results, alive, gone, orphaned, unknown },
+        { repinned: [], unregistered: [],
+          stalePins: stillStale.map((pn) => ({ folder: pn.folderPath, names: pn.projectId })),
+          keptRepoAlive, repoCheckFailed, untagged, healed: [], failed: [], dryRun: false })));
+      return;
+    }
+    say(`\n    ${ok("✓")} Nothing to clean up.`);
+    return;
+  }
+
+  // Confirm only where there is somebody to answer. Non-interactive runs go ahead: every project being
+  // acted on is already gone, so this repairs a broken pointer rather than destroying anything, and
+  // `niro discard-temp-project` takes the same view on its own already-gone path. Blocking here would
+  // strand exactly the unattended runs (an agent, the daemon's advice) that hit this state most.
+  if (!opts.yes && !opts.json && process.stdout.isTTY && !prompt.isNonInteractive()) {
+    // Every kind of work, named. It used to say "Repair 0 folders?" while going on to delete a
+    // `.niro-project` from a git repository — a person approving that was told nothing about the file.
+    const parts = [];
+    if (toRepair.length) parts.push(`repair ${toRepair.length} folder(s)`);
+    if (toUnregister.length) parts.push(`unregister ${toUnregister.length} folder(s)`);
+    const sure = await prompt.confirm(`\n  ${parts.join(", ")}?`, false);
+    if (!sure) {
+      console.log("Aborted.");
+      return;
+    }
+  }
+
+  const repinned = [];
+  const healed = [];
+  const failed = [];
+  const skipped = [];
+  const untracked = [];
+  for (const r of gone) {
+    const res = takeoverRestore.restoreFolders(r.folders, {
+      tempProjectId: r.tempProjectId,
+      cloneOf: r.sourceProjectId,
+      baseUrl,
+      healPins: false,   // never from here: see takeoverRestore. This runs unattended.
+    });
+    repinned.push(...res.repinned);
+    healed.push(...res.healed);
+    failed.push(...res.failed);
+    skipped.push(...res.skipped);
+    untracked.push(...res.untracked);
+  }
+
+  // NOT pushed into `failed` as well: notes() already prints these, and doing both printed the
+  // same folder and reason twice in one run.
+  const unregistered = [];
+  for (const e of toUnregister) {
+    // Confirm the entry is really there under the key `remove` will use. A registry key written with a
+    // trailing slash resolves to a DIFFERENT key, so remove deletes nothing, returns true because its
+    // compare-and-delete guard never fires on an absent entry, and the sweep reports a folder it did
+    // not unregister — every six hours, for ever.
+    if (!watchState.peek(e.folderPath)) {
+      failed.push({ folder: e.folderPath, error: "registry key does not resolve — edit ~/.niro/projects.json by hand" });
+      continue;
+    }
+    // Compare-and-delete on gitId, so a folder re-registered during the checks above keeps its fresh
+    // registration instead of being removed by a decision made about the old one.
+    if (watchState.remove(e.folderPath, e.gitId)) unregistered.push(e.folderPath);
+    else skipped.push({ folder: e.folderPath, nowGitId: null });
+  }
+
+
+  if (opts.json) {
+    console.log(JSON.stringify(summary({ results, alive, gone, orphaned, unknown },
+      { repinned, unregistered,
+        stalePins: stillStale.map((pn) => ({ folder: pn.folderPath, names: pn.projectId })),
+        keptRepoAlive, repoCheckFailed, untagged, healed, failed, skipped, untracked, dryRun: false })));
+    return;
+  }
+
+  if (unregistered.length) {
+    console.log(`\n    ${ok("✓")} Unregistered ${unregistered.length} folder(s) whose project and repo ` +
+        "are both gone. Run `niro init` in one to start syncing it again:");
+    for (const f of unregistered) console.log(color.dim(`    ${f}`));
+  }
+  notes();
+
+  const syncing = repinned.filter((f) => !untracked.includes(f));
+  if (repinned.length) console.log(`\n    ${ok("✓")} Repaired ${repinned.length} folder registration` +
+      `${repinned.length === 1 ? "" : "s"}. Niro routes them back to the original project automatically.`);
+  if (untracked.length) {
+    // Not a failure, and not something to fix: these folders had no local registration before they were
+    // taken over, so they are back where they started. Said out loud because "repaired" would otherwise
+    // imply the daemon is still syncing them, and it is not.
+    console.log(color.dim(`    ${syncing.length} of those are locally tracked and keep syncing. ` +
+        `The other ${untracked.length} had no local registration before the copy was made, so they go ` +
+        "back to not having one (run `niro init` in a folder you want synced):"));
+    for (const f of untracked) console.log(color.dim(`    ${f}`));
+  }
+  if (skipped.length) {
+    console.log(warn(`\n    ⚠ ${skipped.length} folder(s) were re-registered while this ran and were ` +
+        "left alone — run this again to pick them up:"));
+    for (const s of skipped) console.log(color.dim(`    ${s.folder}`));
+  }
+  if (healed.length) {
+    console.log(color.dim("    Healed old-style pins:"));
+    for (const h of healed) console.log(color.dim(`    ${h.folder} → ${h.to}`));
+  }
+  if (failed.length) {
+    console.log(warn(`\n    ⚠ ${failed.length} folder(s) could not be repaired:`));
+    for (const f of failed) console.log(color.dim(`    ${f.folder} — ${f.error}`));
+  }
+  if (orphaned.length || unknown.length) {
+    console.log(color.dim(`    ${orphaned.length + unknown.length} temporary project(s) were left alone ` +
+        "— see above."));
+  }
+}
+
+/** Machine-readable shape for --json. Kept in one place so every exit path emits the same keys. */
+function summary({ results, alive, gone, orphaned, unknown },
+  { repinned, unregistered = [], stalePins = [], keptRepoAlive = [], repoCheckFailed = [],
+    untagged = [], healed, failed, skipped = [],
+    untracked = [], dryRun }) {
+  const asRow = (r) => ({
+    project_id: r.tempProjectId,
+    source_project_id: r.sourceProjectId,
+    folders: r.folders.map((f) => f.folderPath),
+  });
+  return {
+    checked: results.length,
+    alive: alive.map(asRow),
+    gone: gone.map(asRow),
+    orphaned: orphaned.map(asRow),
+    unknown: unknown.map((r) => ({ ...asRow(r), error: r.error })),
+    // Under --dry-run this lists what WOULD be repaired and nothing has been written. Read `dry_run`
+    // before acting on it.
+    repaired: repinned,
+    // Ordinary registrations dropped: project AND repo both gone, so nothing to sync to.
+    unregistered,
+    // Pins are never deleted. This lists the ones the server does not recognise, so a caller can act.
+    stale_pins: stalePins,
+    // Folders naming a deleted project whose REPO is still alive, so they were left registered.
+    kept_repo_alive: keptRepoAlive,
+    // Folders the sweep could not judge, because the repo check itself failed.
+    repo_check_failed: repoCheckFailed,
+    // Legacy entries with no backend tag: never unregistered, because they would be judged against
+    // whichever backend the CLI is pointed at.
+    untagged,
+    // Repaired, but back to having no local repo id — the state they were in before the copy was made,
+    // so the daemon does not sync them. Not an error; a subset of `repaired`.
+    untracked,
+    // Re-registered by another process while the sweep ran, so deliberately left alone.
+    skipped,
+    healed,
+    failed,
+    dry_run: Boolean(dryRun),
+  };
+}
+
+module.exports = { cleanup, groupCandidates, plainRegistrations, ownedPins, probe,
+  looksLikeProjectRef };