@niroai/niro 0.10.0 → 0.11.0

package/src/commands/info.js

@@ -17,6 +17,7 @@ const path = require("path");
 const api = require("../lib/api");
 const watchState = require("../lib/watchState");
 const tempProject = require("../lib/tempProject");
+const niroProjectFile = require("../lib/niroProjectFile");
 const credentials = require("../lib/credentials");
 const color = require("../lib/color");
 const { resolveContext } = require("../lib/resolveContext");
@@ -159,14 +160,19 @@ async function info(pathArg, opts = {}) {
   const indexed = projects.length > 0;
   const ambiguous = projects.length > 1;
 
-  return emit(opts, {
+  const payload = {
     git_root: ctx.gitRoot,
     repo_url: ctx.repoUrl,
     branch: ctx.branch, // null === detached HEAD
     indexed,
     ambiguous,
     projects,
-  });
+  };
+  const emitted = emit(opts, payload);
+  // Said last, after the folder's own summary, so it reads as a footnote rather than an error. Never in
+  // --json mode: that output has an exact shape and callers parse it.
+  if (!opts.json) await warnAboutStalePin(payload);
+  return emitted;
 }
 
 /** Emit either JSON (exact shape) or a plain-English human summary. */
@@ -239,4 +245,47 @@ function printHuman(p) {
   }
 }
 
+/**
+ * Tell the developer, HERE, when this folder's `.niro-project` names a project the server does not
+ * recognise.
+ *
+ * The background sweep already finds these, but a line in a daemon log is not a notification — nobody
+ * reads those, and the pin is consulted BEFORE the git remote, so a stale one quietly answers every
+ * question about the folder. `niro info` is where somebody looks when a folder behaves oddly, so this
+ * is where it belongs.
+ *
+ * Read-only, and silent unless something is actually wrong. A pin that resolves, a pin belonging to a
+ * PARENT folder, and a server that cannot be reached all print nothing: this is a hint, and a hint that
+ * fires on a bad connection is worse than no hint.
+ */
+async function warnAboutStalePin(p) {
+  if (!p || !p.git_root) return;
+  let pin;
+  try { pin = niroProjectFile.read(p.git_root); } catch { return; }
+  if (!pin || !pin.id || !pin.source) return;
+  if (path.dirname(path.resolve(pin.source)) !== path.resolve(p.git_root)) return; // a parent's pin
+  // The ACCOUNT LIST first, and this is not optional. A pin may hold an ALIAS, and an alias never
+  // resolves on the single-project route — asking about a live project by its alias answers
+  // "Project not found". Warning on that alone contradicts the sweep, which uses the list and correctly
+  // says the pin is fine. This repo's own pin holds an alias, so the first cut of this warning fired on
+  // a perfectly healthy folder and pointed at a command that would then report nothing wrong.
+  try {
+    const listed = await api.get("/api/projects");
+    const rows = Array.isArray(listed) ? listed : (listed && listed.projects) || [];
+    if (rows.some((r) => r && (r.project_id === pin.id || r.alias === pin.id))) return;
+  } catch {
+    return;                                            // could not ask: stay quiet
+  }
+  try {
+    await api.get(`/api/projects/${encodeURIComponent(pin.id)}`);
+    return;                                            // resolves by id — nothing to say
+  } catch (err) {
+    if (!tempProject.isProjectNotFound(err)) return;   // could not ask, or not allowed: stay quiet
+  }
+  console.log("");
+  console.log(color.yellow(`This folder's .niro-project names \`${pin.id}\`, which this backend does not recognise.`));
+  console.log(color.dim("    It is read before your git remote, so it may be answering for this folder."));
+  console.log(color.dim("    The project may simply have been renamed. `niro doctor sync-registry` shows it."));
+}
+
 module.exports = { info };

package/src/commands/release.js

@@ -23,6 +23,7 @@ const niroProjectFile = require("../lib/niroProjectFile");
 const prompt = require("../lib/prompt");
 const watchState = require("../lib/watchState");
 const tempProject = require("../lib/tempProject");
+const takeoverRestore = require("../lib/takeoverRestore");
 
 const ok = (s) => color.green(s);
 const warn = (s) => color.yellow(s);
@@ -171,66 +172,11 @@ async function release(pathArg, opts = {}) {
     await api.post(`/api/projects/${encodeURIComponent(tempProjectId)}/clone/release`, {});
   }
 
-  // Restore each folder's local registration. ADR-018: the .niro-project file is left ALONE unless it
-  // still carries the OLD-STYLE swapped pin (pre-ADR-018 takeover) — then it points at a now-deleted
-  // project and must be healed: previousPin verbatim when recorded; explicit "no pin existed" → delete
-  // the file; otherwise the source project id. New-style folders (pin untouched) skip all of this.
-  const repinned = [];
-  const healed = [];
-  const failed = [];
-  for (const e of folders) {
-    try {
-      const backup = e.takeover || {};
-      const sourceProjectId = backup.sourceProjectId || cloneOf;
-      const entryDir = path.resolve(e.folderPath);
-
-      if (fs.existsSync(entryDir)) {
-        const pin = niroProjectFile.read(entryDir);
-        const pinIsSwapped = pin && pin.id === tempProjectId
-            && path.dirname(pin.source) === entryDir; // only heal THIS folder's own pin, never a parent's
-        if (pinIsSwapped) {
-          const recordedNoPin = ("previousPin" in backup) && backup.previousPin === null;
-          if (backup.previousPin) {
-            niroProjectFile.write(entryDir, backup.previousPin, { overwrite: true });
-            healed.push({ folder: e.folderPath, to: backup.previousPin });
-          } else if (recordedNoPin) {
-            niroProjectFile.remove(entryDir);
-            healed.push({ folder: e.folderPath, to: "(no pin — removed)" });
-          } else {
-            niroProjectFile.write(entryDir, sourceProjectId, { overwrite: true });
-            healed.push({ folder: e.folderPath, to: sourceProjectId });
-          }
-        }
-      }
-
-      // Watch/daemon registration goes back to the source project regardless of pin style.
-      watchState.set(e.folderPath, {
-        ...e,
-        gitId: backup.previousGitId || null,
-        projectId: sourceProjectId,
-        // The baseline describes what the TEMPORARY project holds, so it MUST NOT survive the move
-        // back to the source repo. Carrying it across told the daemon the source already had every
-        // file at its sandbox-era fingerprint — which it did not, because those edits only ever went
-        // to the temporary copy. The next pass then compared disk against that baseline, found no
-        // difference, and uploaded nothing. Every edit made during the temporary project was silently
-        // lost to the source project, with no error and nothing to prompt a re-sync.
-        //
-        // Clearing it makes the next pass treat every file as new and upload it. That is a full
-        // re-upload once, which is the cost of being sure: the client cannot know which files the
-        // source repo is missing, so the only safe assumption is all of them.
-        //
-        // The opposite direction already gets this right — takeover.js seeds fileHashes with what it
-        // actually uploaded to the new gitId. A baseline belongs to ONE gitId; when that changes, so
-        // must it.
-        fileHashes: {},
-        lastSyncedAt: null,
-        takeover: undefined,
-      }, e.apiUrl || baseUrl);
-      repinned.push(e.folderPath);
-    } catch (err) {
-      failed.push({ folder: e.folderPath, error: err.message });
-    }
-  }
+  // Restore each folder's local registration. Shared with `niro cleanup-temp-projects`, which reaches
+  // the same point by a different route (it finds copies already gone from the server instead of being
+  // pointed at one), so the loop itself lives in lib/takeoverRestore.
+  const { repinned, healed, failed, skipped } = takeoverRestore.restoreFolders(folders,
+    { tempProjectId, cloneOf, baseUrl });
 
   if (alreadyGone) {
     console.log(`\n    ${ok("✓")} Temporary project ${color.bold(tempProjectId)} was already gone from the server` +
@@ -242,6 +188,13 @@ async function release(pathArg, opts = {}) {
   } else {
     console.log(`\n    ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
   }
+  if (skipped.length) {
+    // Somebody re-pointed the folder while this ran. Leaving it alone is the safe half; saying so is
+    // the other half, because a silently skipped folder looks exactly like a repaired one.
+    console.log(warn(`\n    ⚠ ${skipped.length} folder(s) were re-registered while this ran and were ` +
+        "left alone:"));
+    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}`));

package/src/commands/takeover.js

@@ -147,7 +147,38 @@ async function takeover(pathArg, opts = {}) {
   // 2. Create-or-extend server-side (ADR-016). If you already have a temporary project of this project,
   // the backend EXTENDS it — adds this repo to the same copy — instead of minting a second one, so
   // cross-repo answers stay coherent. Either way this folder's repo becomes AGENT_UPLOAD.
-  const outcome = await requestClone(source.project_id, source.git_id, branch);
+  let outcome;
+  try {
+    outcome = await requestClone(source.project_id, source.git_id, branch);
+  } catch (err) {
+    // The server refuses a copy when you already hold the limit, and its message is good: it says how
+    // many, what the limit is, and which BRANCHES the copies are for. What it cannot say is where those
+    // branches are checked out, because that is a fact about this machine — and its own advice is "run
+    // `niro discard-temp-project` in the folder for one you have finished with". So the folder is the
+    // one thing the developer still has to work out, and it is the one thing this side knows.
+    //
+    // Matched on the refusal, not attached to every failure. The closing line of this hint tells you to
+    // discard a copy, and that is only sound advice when capacity is what stopped you: on a dropped
+    // connection it would send somebody deleting a working copy for nothing. The existing one-slot
+    // guard tests caught exactly that by failing when the hint arrived on their sentinel error.
+    //
+    // The fragment is short and drawn from the server's own text (ProjectCloneService: "You already
+    // have N working copies of this project, which is the limit (N)"), and it survives the generic
+    // handler's "An unexpected error occurred: " prefix. If the server ever rewords it, the hint stops
+    // appearing — a false negative, which costs a developer one lookup, rather than a false positive,
+    // which costs them a copy.
+    const isCapacityRefusal = /working cop(y|ies) of this project/i.test(err.message || "");
+    const held = isCapacityRefusal ? copiesOfSourceProject(source.project_id) : [];
+    if (held.length) {
+      const rows = held.map((h) => `      ${(h.branch || "(unknown branch)").padEnd(28)}${h.folderPath}`);
+      // No closing instruction: the server's message already ends with "Run `niro
+      // discard-temp-project` in the folder for one you have finished with". Repeating it made the
+      // developer read the same sentence twice. This side adds the one thing the server cannot know —
+      // where each of those branches is checked out.
+      err.message = `${err.message}\n\n    Those copies are checked out here:\n${rows.join("\n")}`;
+    }
+    throw err;
+  }
   const newProjectId = outcome.new_project_id || outcome.newProjectId;
   const gitIdMap = outcome.git_id_map || outcome.gitIdMap || {};
   const newGitId = gitIdMap[source.git_id];
@@ -286,6 +317,25 @@ async function takeover(pathArg, opts = {}) {
  * field and returns the outcome inline exactly as before, which is the shape this already handled. So
  * there is no capability check to keep in step, and no flag day.
  */
+/**
+ * The folders on THIS machine that hold a working copy of `sourceProjectId`, with the branch each was
+ * taken over on.
+ *
+ * Read-only and local: no server call, no parsing of anybody's message. Used to turn the branches the
+ * server names in a capacity refusal into folders the developer can actually go and stand in.
+ *
+ * Not the same question as the holder guard above, which asks whether a DIFFERENT folder holds the slot
+ * for this particular repo and therefore matches on sourceGitId and excludes the current folder. This
+ * one wants all of them, including the folder you are standing in — that copy is as discardable as any
+ * other, and leaving it out of the list would be confusing when it is the one you had forgotten about.
+ */
+function copiesOfSourceProject(sourceProjectId) {
+  return watchState.allLocal(api.currentBaseUrl())
+    .filter((e) => e.takeover && e.takeover.sourceProjectId === sourceProjectId)
+    .map((e) => ({ folderPath: e.folderPath, branch: e.branch || null }))
+    .sort((a, b) => (a.folderPath < b.folderPath ? -1 : 1));
+}
+
 async function requestClone(projectId, gitId, branch, opts = {}) {
   const started = await api.post(
     `/api/projects/${encodeURIComponent(projectId)}/clone`,
@@ -355,4 +405,4 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-module.exports = { takeover, requestClone};
+module.exports = { takeover, requestClone, copiesOfSourceProject };

package/src/commands/watch.js

@@ -21,6 +21,7 @@ const color = require("../lib/color");
 const folderSync = require("../lib/folderSync");
 const git = require("../lib/git");
 const tempProject = require("../lib/tempProject");
+const periodicClaim = require("../lib/periodicClaim");
 const {
   SOURCE_EXTENSIONS, STRUCTURAL_EXTENSIONS, STRUCTURAL_FILENAMES,
   IGNORED_DIRS, isConfigName, chunk,
@@ -177,6 +178,8 @@ async function watch(pathArg, opts = {}) {
     } catch (err) {
       console.error(color.yellow(`    Could not watch the state file for new folders: ${err.message}`));
     }
+    startPeriodicSweep();
+
     // Keep process alive
     await new Promise(() => {});
     return;
@@ -186,6 +189,56 @@ async function watch(pathArg, opts = {}) {
   await startWatch(targetDir, opts);
 }
 
+/**
+ * How often the daemon sweeps for temporary projects that have gone from the server. Six hours, not
+ * six seconds: its job is repairing pointers that go stale over days, not reacting to keystrokes.
+ * Every run is a handful of small GETs.
+ */
+const SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+/**
+ * A short delay before the first sweep rather than one at startup. The daemon has a burst of work when
+ * it starts (a delta sync per folder), and the sweep is in no hurry — it can wait for that to settle.
+ */
+const SWEEP_STARTUP_DELAY_MS = 60 * 1000;
+
+/**
+ * Periodically run `niro cleanup-temp-projects`. Machine-wide, so it belongs HERE, in the no-path
+ * branch, and not in startWatch — startWatch runs once per folder, and this must run once per machine.
+ *
+ * It runs the sweep in its DEFAULT mode, which only repairs local registrations whose temporary project
+ * the server no longer has. It never deletes anything server-side. That is what makes it safe to run
+ * unattended: every project it acts on is already gone, so the worst case is a pointer left as it was.
+ *
+ * Every run is gated by periodicClaim, which persists the last run time. That stops two things that
+ * would otherwise both happen: PM2 restarting the daemon (on a crash, a reboot, or
+ * `niro service restart`) turning a six-hourly job into a job that runs on every restart, and a
+ * `niro watch` left running in a terminal sweeping at the same moment as the PM2 daemon.
+ *
+ * Never throws: a sweep failure must not touch the daemon's actual job, which is syncing files.
+ * Exported so tests can drive it without starting a daemon.
+ */
+function startPeriodicSweep({ intervalMs = SWEEP_INTERVAL_MS, startupDelayMs = SWEEP_STARTUP_DELAY_MS,
+  claimName = "tempProjectSweep" } = {}) {
+  const run = async () => {
+    if (!periodicClaim.claim(claimName, intervalMs)) return;
+    try {
+      const cleanupCmd = require("./cleanup");
+      await cleanupCmd.cleanup({
+        yes: true,   // nobody is at the terminal to answer a prompt
+        quiet: true, // only speak when it actually changed something
+      });
+    } catch (err) {
+      console.error(color.yellow(`    Temporary-project sweep skipped: ${err && err.message}`));
+    }
+  };
+  const first = setTimeout(run, startupDelayMs);
+  const timer = setInterval(run, intervalMs);
+  // unref so neither timer holds the process open on its own; the daemon is kept alive by its watchers.
+  if (first.unref) first.unref();
+  if (timer.unref) timer.unref();
+  return { stop: () => { clearTimeout(first); clearInterval(timer); } };
+}
+
 /**
  * One watch entry failed to start (its startup delta sync threw). Contain the failure to that
  * entry — and when the cause is "the repo no longer exists on this backend" (a poison entry left
@@ -332,40 +385,55 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
   try {
   const quiet = opts.quiet === true; // periodic backstop re-scan runs silently unless it actually syncs
 
-  // Am I still the folder this temporary project reflects? Every folder taken over for one project
-  // shares the SAME repo id, so the server cannot tell us apart. If I keep uploading after the slot has
-  // moved, my branch blends into the copy that is reflecting someone else, and every answer drawn from
-  // it is a mixture — with nothing on screen to say so. Verified live with two worktrees.
+  // Is this folder still in step with the temporary project it uploads to? If my branch and the copy's
+  // branch label disagree, uploading writes this branch's files into a copy labelled with another one,
+  // and every answer later drawn from that copy is wrong with nothing on screen to say so.
+  //
+  // Pausing costs the developer nothing while they are out of step, which is the part that is easy to
+  // get wrong. ai-assistant will not route a session to a copy whose label is not the caller's branch
+  // (`if (branch.equals(repo.getBranch())) return true;`, TempProjectRoutingService.java:358, and the
+  // copies are pre-filtered to that branch key at :325). So a drifted copy is already answering nobody.
+  // Uploading into it does not restore anything, it only fills it with the wrong branch's files, and
+  // nothing in the upload path ever relabels it (zero setBranch calls under service/agent). The fix is
+  // for the developer to run `niro new-temp-project`, which is what the message says.
   //
   // Nothing is changed or discarded here. The local record is left exactly as it is, so running
   // `niro new-temp-project` here picks straight back up. This only declines to WRITE.
   if (state.takeover && state.takeover.sourceProjectId) {
     const heldBranch = await tempProject.currentBranch(state.projectId, gitId);
     const myBranch = ((git.inspect(targetDir) || {}).branch) || state.branch;
-    // A null heldBranch means the server could not be asked. That must NEVER be read as "you lost the
-    // slot", or one network hiccup would stop a perfectly healthy folder syncing.
-    if (heldBranch && myBranch && heldBranch !== myBranch) {
+
+    if (!heldBranch || !myBranch) {
+      // COULD NOT ASK. This used to fall through to the release below, which both printed "resuming
+      // uploads" and let a folder that had genuinely lost its slot start writing again on any network
+      // hiccup. It is also where a customer's 306 pauses against 286 resumes came from: nearly equal
+      // counts because it was flapping, one warning printed on every re-entry.
+      //
+      // Not knowing is not news. Whatever was decided last time stands until the server answers again.
+      if (notHolding.has(inFlightKey)) return { notHolder: true };
+    } else if (heldBranch !== myBranch) {
       if (!notHolding.has(inFlightKey)) {
         notHolding.add(inFlightKey);
-        // TWO very different causes, and they need different advice. Another folder bound to the same
-        // copy is the stealing case. NO other folder means you simply switched branch in place, and
-        // saying "another folder holds it" there sends you hunting for a folder that does not exist —
-        // which is exactly what it did on a real repo the first time this ran.
-        const otherFolder = watchState.allLocal(api.currentBaseUrl()).find((e) =>
-          e.projectId === state.projectId && path.resolve(e.folderPath) !== inFlightKey);
-        console.warn(color.yellow(otherFolder
-          ? `  ${targetDir} is on \`${myBranch}\`, but this project's temporary project is on ` +
-            `\`${heldBranch}\`, held by ${otherFolder.folderPath}. Pausing uploads from here so the ` +
-            `two branches do not mix. Run \`niro new-temp-project\` here to move it, or ` +
-            `\`niro discard-temp-project\` in that folder.`
-          : `  ${targetDir} is on \`${myBranch}\`, but its temporary project is still on ` +
-            `\`${heldBranch}\` — you switched branch in this folder. Pausing uploads so the two ` +
-            `branches do not mix. Run \`niro new-temp-project\` here to move the temporary project ` +
-            `onto \`${myBranch}\`.`));
+        // TWO very different causes needing different advice, and this is where the old message was
+        // wrong. It looked for another folder on the same PROJECT id, but a project can hold several
+        // repos and each folder can have its own, so it named folders that were writing nowhere near
+        // this one and told the developer to go and discard them. `gitId` is the repo this pass
+        // actually uploads to, so another folder carrying the same gitId is, by definition, writing to
+        // the same place. That is the only thing that makes it somebody else's doing rather than yours.
+        const rival = watchState.allLocal(api.currentBaseUrl()).find((e) =>
+          e.gitId === gitId && path.resolve(e.folderPath) !== inFlightKey);
+        console.warn(color.yellow(rival
+          ? `  ${targetDir} and ${rival.folderPath} are both uploading to the same temporary project. ` +
+            `This folder is on \`${myBranch}\`, the copy is on \`${heldBranch}\`. Pausing uploads from ` +
+            `here so the two branches do not mix. Run \`niro new-temp-project\` here to give this folder ` +
+            `a copy of its own, or \`niro discard-temp-project\` in the other folder.`
+          : `  ${targetDir} is on \`${myBranch}\`, but its temporary project is still labelled ` +
+            `\`${heldBranch}\`. You switched branch in this folder. Your sessions will not use this copy ` +
+            `until the two agree, so uploads are paused rather than filling it with the wrong branch. ` +
+            `Run \`niro new-temp-project\` here to move it onto \`${myBranch}\`.`));
       }
       return { notHolder: true };
-    }
-    if (notHolding.delete(inFlightKey)) {
+    } else if (notHolding.delete(inFlightKey)) {
       console.log(color.green(`    ${targetDir} holds the temporary project again — resuming uploads.`));
     }
   }
@@ -877,7 +945,7 @@ function buildMinimalManifest(rootDir, includePatterns, excludePatterns) {
 
 // handleFileEvent + deltaSyncOnResume are exported for unit testing the
 // gitignore/fail-closed guards without a live server or fs.watch loop.
-module.exports = { watch, startWatch, handleFileEvent, deltaSyncOnResume, handleEntryFailure,
+module.exports = { watch, startWatch, startPeriodicSweep, handleFileEvent, deltaSyncOnResume, handleEntryFailure,
   queueDelete, flushPendingDeletes, pendingDeletes, DELETE_SETTLE_MS, backstopTick, notHolding,
   unreadableRoots,
   nextBackoffMs, shouldAttemptBackstop, recordBackstopFailure, recordBackstopSuccess };

package/src/index.js

@@ -249,7 +249,28 @@ function main() {
       await cmd.release(pathArg, { ...opts });
     }));
 
-  program
+  // `niro doctor` — checks that compare this machine against the server and repair what is safe to
+  // repair. A group from the start, because there is more than one of these coming; `sync-registry` is
+  // simply the first. Published commands (`status`, `info`, `service status`) deliberately stay where
+  // they are: they shipped in 0.10.1 and that surface is stable.
+  const doctor = program
+    .command("doctor")
+    .description("Check this machine against the server and repair what is safe to repair.");
+
+  const syncRegistry = (opts) => run(async () => {
+    const cmd = require("./commands/cleanup");
+    await cmd.cleanup({ ...opts });
+  });
+
+  doctor
+    .command("sync-registry", { isDefault: true })
+    .description("Bring this machine's record of your projects back in line with the server: folders pointing at projects that are gone, and .niro-project files naming something unknown.")
+    .option("--dry-run", "list what would change and change nothing")
+    .option("--forget <path>", "drop one folder's registration (for a folder you have deleted); the folder itself is never touched")
+    .option("-y, --yes", "skip the confirmation prompt")
+    .option("--json", "emit machine-readable JSON")
+    .action(syncRegistry);
+ program
     .command("status [project_id]")
     .description("Show the current build status for a project.")
     .option("--json", "emit machine-readable JSON")
@@ -372,8 +393,7 @@ function run(fn) {
         console.error(err.message);
         process.exit(1);
       }
-      console.error(err && err.stack ? err.stack.split("\n")[0] : String(err));
-      if (err && err.status) console.error(`    (HTTP ${err.status})`);
+      require("./lib/printError").printError(err);
       process.exit(1);
     });
 }

package/src/lib/folderSync.js

@@ -69,6 +69,12 @@ const STRUCTURAL_FILENAMES = new Set([
   "project.json", "directory.build.props", "next.config.js", "next.config.mjs",
   "next.config.ts", "vite.config.ts", "vite.config.js", "setupproxy.js",
   "setupproxy.ts",
+  // Java servlet deployment descriptor. A pre-Spring-Boot web app declares its whole
+  // HTTP surface here rather than in annotations, so without this the server sees a
+  // servlet application with zero endpoints. Measured on one customer repo: 11 real
+  // endpoints, 0 detected. Read server-side by WebXmlServletRouteReader.
+  // MIRROR: ai-orchestrator SourceFileFilterService.STRUCTURAL_FILENAMES.
+  "web.xml",
 ]);
 const STRUCTURAL_EXTENSIONS = new Set([
   ".csproj", ".fsproj", ".sln", ".gemspec", ".rockspec", ".nimble", ".opam",

package/src/lib/periodicClaim.js

@@ -0,0 +1,100 @@
+/**
+ * "Has this periodic job already run recently, and may I be the one to run it now?"
+ *
+ * Two problems, one answer.
+ *
+ * PM2 restarts the watch daemon on a crash, on a reboot, and on `niro service restart`. A job wired to
+ * a plain setInterval that also runs at startup therefore runs on every restart, and a crash loop turns
+ * a daily job into a hot loop. So the last run time has to OUTLIVE the process, which means a file.
+ *
+ * And two daemons can be up at once — the PM2 one plus a `niro watch` somebody left running in a
+ * terminal. Both would fire the same job at the same moment. For a job that only reads that is waste;
+ * for one that deletes on the server it is two processes racing over the same decision.
+ *
+ * A timestamp file answers both: whoever writes it first owns the interval, and everybody else sees a
+ * recent stamp and stands down. The write is atomic (tmp + rename, the same technique watchState uses)
+ * so a reader never sees a half-written file.
+ *
+ * NOT a mutex. Two processes calling claim() in the same millisecond can both win: each reads the old
+ * stamp before either writes. Closing that needs an O_EXCL lock file plus stale-lock recovery, which
+ * costs more than it saves here — the jobs this guards are idempotent (a second sweep finds the work
+ * already done) and the interval is hours, so the collision window is milliseconds wide once a day.
+ * The comment is here so nobody later mistakes this for a lock and puts something non-idempotent
+ * behind it.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const DIR = path.join(os.homedir(), ".niro");
+const FILE = path.join(DIR, "periodic.json");
+
+function load() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(FILE, "utf8"));
+    // An ARRAY passes `typeof === "object"`, and JSON.stringify then drops the named property we set on
+    // it — so the stamp never persisted and the job claimed on EVERY tick, which is precisely the crash
+    // loop this module exists to prevent. Anything that is not a plain object starts again from empty.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function save(state) {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  const tmp = `${FILE}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, FILE);
+}
+
+/** When `name` last ran, in epoch millis, or null if it never has (or the stamp is unreadable). */
+/** Said once per process, not once per tick — a six-hourly job would otherwise fill the log. */
+let warnedAboutWrite = false;
+
+function lastRun(name) {
+  const at = load()[name];
+  const n = Number(at);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/**
+ * Try to claim the current interval for `name`.
+ *
+ * Returns true and stamps the file when `intervalMs` has passed since the last run (or it has never
+ * run). Returns false and writes nothing otherwise.
+ *
+ * The stamp is written BEFORE the job runs, not after. A job that dies half way through must not be
+ * retried immediately on the next tick — that is the crash loop this exists to prevent — and these
+ * jobs are safe to skip for one interval. The cost of the choice is that a run interrupted at 1% waits
+ * a full interval to try again, which is the right trade for something that runs every few hours.
+ *
+ * A stamp in the FUTURE (a clock that jumped back, or a file copied between machines) would otherwise
+ * block the job until real time caught up, potentially for years. Treated as "never ran" instead.
+ */
+function claim(name, intervalMs, now = Date.now()) {
+  const last = lastRun(name);
+  if (last !== null && last <= now && now - last < intervalMs) return false;
+  const state = load();
+  state[name] = now;
+  try {
+    save(state);
+  } catch (err) {
+    // Cannot persist the stamp (read-only home, a file left by a `sudo` run, a full disk). Refuse the
+    // claim rather than run: an unstampable job would run on EVERY tick, which is worse than not
+    // running at all.
+    //
+    // But SAY SO, once. Returning a quiet false disables the job for good, and the developer has no
+    // way to know: their folders simply stop being tidied and nothing ever mentions it.
+    if (!warnedAboutWrite) {
+      warnedAboutWrite = true;
+      console.warn(`    Could not write ${FILE} (${err.message}). Periodic housekeeping is paused; ` +
+          "fix the permissions on ~/.niro to re-enable it.");
+    }
+    return false;
+  }
+  return true;
+}
+
+module.exports = { claim, lastRun, FILE };

package/src/lib/printError.js

@@ -0,0 +1,46 @@
+/**
+ * How a failed command is written to the terminal.
+ *
+ * Extracted from index.js's `run` for one reason: it was dropping text the user needed, and there was
+ * no way to test that. index.js calls main() at load, so nothing could require it.
+ *
+ * The bug it exists to stop: the printer took `err.stack.split("\n")[0]`, which is the error's class
+ * name plus the FIRST LINE of its message. Any message built over several lines therefore printed its
+ * opening line and silently swallowed the rest. Two real cases, both of which end in the user staring
+ * at a sentence that promises a list and then shows nothing:
+ *
+ *   "Multiple projects match this repo — pass --project:"   ...and then no projects.
+ *   "You already have 5 working copies..."                  ...and then no folders to go and look in.
+ *
+ * Nothing was broken in either feature. The text existed, was correct, and never reached the screen.
+ */
+
+/**
+ * Print `err` the way the CLI always has, plus the lines that were being lost.
+ *
+ * The first line still comes from the stack, so an error's real class name survives (a TypeError says
+ * TypeError, not Error). Subsequent lines come from the MESSAGE, never the stack, because a stack trace
+ * is noise to somebody running a CLI and this repo deliberately does not print them.
+ *
+ * A single-line message prints exactly as it did before, byte for byte.
+ *
+ * @param {*} err the thrown value; need not be an Error
+ * @param {(...args: any[]) => void} write where to send each line (console.error by default)
+ */
+function printError(err, write = console.error) {
+  // With a stack, its first line already carries the class name and the message's first line, so only
+  // the REMAINING message lines are added. Without one — anything thrown that is not an Error — there
+  // is no such line, so the whole message is printed rather than silently starting at line two.
+  const hasStack = Boolean(err && err.stack);
+  const first = hasStack ? String(err.stack).split("\n")[0] : String(err);
+  write(first);
+  // Only lines the FIRST line did not already carry. With a stack that is everything after line one.
+  // Without one, String(err) may already be the whole message (an Error whose stack was stripped
+  // stringifies to "Error: <the lot>"), so printing from line one again said it all twice.
+  const messageLines = err && typeof err.message === "string" ? err.message.split("\n") : [];
+  const rest = hasStack ? messageLines.slice(1) : messageLines.filter((l) => !first.includes(l));
+  for (const line of rest) write(line);
+  if (err && err.status) write(`    (HTTP ${err.status})`);
+}
+
+module.exports = { printError };