@niroai/niro 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -2,7 +2,66 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
-## Unreleased
+## 0.6.0 — 2026-08-11
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+If you are coming from 0.3.x you also still need `niro mcp install` once per assistant — see
+the 0.5.0 notes below. Upgrading from 0.5.0 needs nothing extra.
+
+### Changed — read this before upgrading
+
+- **`--api-url` now applies to `niro login` only.** Every other command refuses it and exits 1.
+
+  It was a global flag, but only half of the code honoured it. Ordinary API calls took it,
+  while the file-upload path built its own address from your stored credentials and never saw
+  it. So `niro init --api-url http://localhost:8095` while logged in to another backend listed
+  projects from localhost and uploaded your source to the backend you were logged in to. One
+  command, two servers, no warning.
+
+  The backend is a property of a session, not of a single command: your credentials, tokens,
+  repo ids and sync records are all scoped to one backend, so a per-command override could
+  only ever mix them. Choose it once instead:
+
+  ```bash
+  niro login --api-url <url>          # log in to that backend
+  NIRO_API_URL=<url> niro <command>   # or set it for every command
+  ```
+
+  `NIRO_API_URL` and the `apiUrl` config setting still work everywhere, because both feed the
+  same resolution the uploader uses. **If you script `--api-url` on any command other than
+  `login`, that script now fails with a message** telling it which of the two forms to use.
+
+- **`niro init` and `niro add repo` now refuse a folder that is not a project.** Onboarding a
+  folder used to work anywhere, including your home folder, which uploaded source from every
+  project on the machine, pinned `~/.niro-project` and started a watcher over your whole home
+  directory. Two rules now apply before anything is uploaded:
+
+  - Your home folder, the filesystem root, a parent of your home folder and the system folders
+    are refused outright. `--force` does **not** override this.
+  - Any other folder must look like a project: a build file (`package.json`, `pom.xml`, `go.mod`,
+    `*.csproj`, and the rest of the set the indexer already understands) at the folder itself or
+    just below it. A monorepo root whose build files sit one or two levels down is fine.
+
+  **If you script either command**, a folder with no build file now exits `1` where it used to
+  onboard. Pass `--force` for that case. `niro add repo` gains `--force` for this; on `niro init`
+  the existing `--force` now covers it too.
+
+  A folder this backend already has a repo for is exempt from the build-file rule, so an existing
+  sync keeps working. The home and root refusal still applies to it.
+
+  The check runs before the login and before any server call, so a refused folder leaves nothing
+  behind: no registered repo, no orphan project, no pin file, no watcher.
+
+- **`niro init` now notices nested repos deeper in the tree.** The "this folder contains repos
+  already indexed in Niro" refusal only looked two levels down, so it never fired for the common
+  `~/projects/<host>/<org>/<repo>` layout. It now looks four.
+
+## 0.5.0 — 2026-08-06
 
 ### Upgrading from 0.3.x — one manual step
 

package/README.md

@@ -98,7 +98,9 @@ During `init` you'll be asked, **per environment variable**, which value to use
 **Ask the agent**
 > "Onboard this folder into Niro." The `niro-cli` skill checks auth, runs `niro info` to see if it's already indexed, then runs `niro init` for you and walks you through the env-var values in chat.
 
-**Note for cloud:** Niro indexes your folder by **uploading its files** (it can't read your laptop's disk). Source and committed config files (`package.json`, `pom.xml`, `application.yml`, …) are uploaded; anything in your `.gitignore` (like a real `.env`) is **never** uploaded.
+**Note for cloud:** Niro indexes your folder by **uploading its files** (it can't read your laptop's disk). Source and committed config files (`package.json`, `pom.xml`, `application.yml`, …) are uploaded; anything your repo `.gitignore`s (like a real `.env`) is **never** uploaded. One caveat: that filtering needs the folder to be a git repository. If you onboard a plain folder that is not a git repository, there is no `.gitignore` to honour and only the filename rules apply, so keep secrets out of it.
+
+**What can be onboarded:** the folder has to look like a project — a build file (`package.json`, `pom.xml`, `go.mod`, `*.csproj`, …) at the folder itself or just below it. A monorepo root whose build files sit one or two levels down is fine. A folder with no build file is refused; pass `--force` if you really mean it. Your home folder, the filesystem root and system folders are refused outright, and `--force` does not override that — onboarding one of those would upload source from every project on the machine.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",

package/src/commands/add-repo.js

@@ -25,30 +25,57 @@ const { startWatch } = require("./watch");
 const color = require("../lib/color");
 const watchDaemon = require("../lib/watchDaemon");
 const { login } = require("./login");
+const onboardTarget = require("../lib/onboardTarget");
 
 async function addRepo(pathArg, opts = {}) {
+  const targetRaw = pathArg || ".";
+  const isRemote = targetRaw.startsWith("http://") || targetRaw.startsWith("https://") || targetRaw.startsWith("git@");
+
+  // Backend URL as it looks BEFORE the login. Used for ONE thing only: the gate's
+  // already-registered lookup, which has to run before the login. It is NOT reused
+  // afterwards — a login can change which backend this session talks to, and tagging a
+  // watchState entry with a stale value stamps it with a backend that did not issue its
+  // gitId, which silently stops the daemon syncing that folder. See the same note in
+  // init.js. The authoritative value is re-read after ensureLoggedIn below.
+  const apiUrlBeforeLogin = api.currentBaseUrl();
+
+  // LOCAL FOLDER: validate and gate BEFORE the login, for two reasons. Refusing a folder
+  // should not first cost the user a browser device-flow. And an abandoned login used to
+  // swallow the refusal entirely: ensureLoggedIn returned null, the bare `return` printed
+  // nothing and left process.exitCode undefined, so `niro add repo ~ && echo ok` printed
+  // ok. A remote URL has no folder to gate, so it stays behind the login.
+  let targetDir = null;
+  if (!isRemote) {
+    targetDir = path.isAbsolute(targetRaw) ? path.resolve(targetRaw) : path.resolve(process.cwd(), targetRaw);
+    if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
+      console.error(color.red(`Not a directory: ${targetDir}`));
+      process.exitCode = 1;
+      return;
+    }
+    // Same onboarding gate as `niro init` — this command uploads a folder too, so it must
+    // refuse $HOME / the filesystem root on the same terms. A folder this backend already
+    // has a repo for is exempt from the BUILD-DESCRIPTOR half: that half gates new
+    // onboarding, and must not break the re-sync branch below for a descriptor-less folder
+    // onboarded by an earlier CLI. See src/lib/onboardTarget.js.
+    const known = watchState.get(targetDir, apiUrlBeforeLogin);
+    const alreadyRegistered = !!(known && known.gitId);
+    if (!onboardTarget.ensureOnboardable(targetDir, { ...opts, alreadyRegistered })) {
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   const creds = await ensureLoggedIn(opts);
   if (!creds) return;
 
-  // Backend the CLI is pointed at — scopes watchState so a cached gitId from
-  // another stack is never reused here.
+  // Authoritative backend, re-read AFTER the login (see the note above).
   const currentApiUrl = api.currentBaseUrl();
 
-  const targetRaw = pathArg || ".";
-
-  // Remote URL?
-  if (targetRaw.startsWith("http://") || targetRaw.startsWith("https://") || targetRaw.startsWith("git@")) {
+  if (isRemote) {
     await addRemoteRepo(targetRaw, opts);
     return;
   }
 
-  const targetDir = path.isAbsolute(targetRaw) ? path.resolve(targetRaw) : path.resolve(process.cwd(), targetRaw);
-  if (!fs.existsSync(targetDir) || !fs.statSync(targetDir).isDirectory()) {
-    console.error(color.red(`Not a directory: ${targetDir}`));
-    process.exitCode = 1;
-    return;
-  }
-
   // --sync-mode local|remote skips the interactive [1]/[2] sync-type choice.
   // --no-confirm skips any confirmation prompt.
   const syncMode = parseSyncMode(opts.syncMode);

package/src/commands/info.js

@@ -13,7 +13,10 @@
  * NEVER prints secrets: it only emits project ids, aliases and status fields —
  * no env-var values, tokens or credentials are touched here.
  */
+const path = require("path");
 const api = require("../lib/api");
+const watchState = require("../lib/watchState");
+const tempProject = require("../lib/tempProject");
 const credentials = require("../lib/credentials");
 const color = require("../lib/color");
 const { resolveContext } = require("../lib/resolveContext");
@@ -91,8 +94,58 @@ async function info(pathArg, opts = {}) {
       // A status fetch failure for one project must not abort the whole command.
       status = null;
     }
+    // Which local folders sync to THIS project, and on what branch. Purely local: ~/.niro/projects.json
+    // already records branch and projectId per folder.
+    //
+    // A developer gets ONE temporary project per project, and creating another RELABELS it onto the new
+    // branch. So with several worktrees open, exactly one of them is reflected by Niro and the others
+    // are not, with nothing on screen to say which. This is that missing line: it lets someone see that
+    // the temporary project is bound to worktree A on feature/x while they are standing in worktree B.
+    //
+    // Matching on projectId ALONE could never show the one folder this line exists for. Taking over a
+    // folder rewrites its entry's projectId to the TEMPORARY project's id, and /api/projects/resolve
+    // deliberately never returns temporary projects (they share the source project's git URL, so
+    // including them would make every teammate's resolution ambiguous). So for a taken-over worktree
+    // the two ids can never be equal, and the folder Niro actually reflects was the only one missing
+    // from the list, while the folder it does NOT reflect was the only one shown.
+    //
+    // takeover.sourceProjectId is the link back to the source project. It is written when the temporary
+    // project is created and cleared on discard, so it is present exactly while there is something to
+    // report. `niro release` already pairs the two this way.
+    //
+    // apiUrl comes from api.currentBaseUrl(), not opts: `--api-url` is refused outside `niro login`, so
+    // opts.apiUrl is always undefined here, and an undefined backend makes allLocal match entries
+    // belonging to ANY backend.
+    const localEntries = watchState.allLocal(api.currentBaseUrl())
+      .filter(e => e.projectId === p.project_id
+        || (e.takeover && e.takeover.sourceProjectId === p.project_id));
+    const folders = localEntries.map(e => ({
+      path: e.folderPath,
+      branch: e.branch || null,
+      // The temporary project's own id when this folder is bound to one, else null.
+      temp_project_id: e.takeover && e.takeover.sourceProjectId === p.project_id ? e.projectId : null,
+      // Whether the temporary project is currently reflecting THIS folder. null when it has none, or
+      // when the server could not be asked.
+      reflected: null,
+    }));
+
+    // A temporary project can only be bound to one branch at a time, so listing several folders as
+    // "via temporary project X" implies they are all covered when at most one is. That is not
+    // hypothetical: two worktrees of one project end up sharing a repo id, and I have watched this
+    // command mark "you are here" against a folder the server had stopped reflecting. The branch the
+    // copy is on is the answer, and only the server knows it, so ask once per temporary project.
+    const tempIds = [...new Set(folders.map(f => f.temp_project_id).filter(Boolean))];
+    for (const tempId of tempIds) {
+      const owner = localEntries.find(e => e.projectId === tempId);
+      const heldBranch = await tempProject.currentBranch(tempId, owner && owner.gitId);
+      if (!heldBranch) continue; // could not ask — say nothing rather than guess
+      for (const f of folders) {
+        if (f.temp_project_id === tempId) f.reflected = f.branch === heldBranch;
+      }
+    }
     projects.push({
       project_id: p.project_id,
+      folders,
       alias: p.alias || null,
       // Matched repo's registration kind (REMOTE_GIT / LOCAL_PATH / AGENT_UPLOAD),
       // or null. Lets agents warn on remote-git projects (auto-build only on commits).
@@ -166,6 +219,23 @@ function printHuman(p) {
     if (proj.doc_gen_status) bits.push(`docs: ${proj.doc_gen_status}`);
     if (proj.updated_at) bits.push(`updated: ${proj.updated_at}`);
     console.log(`  - ${name}${bits.length ? "  — " + color.dim(bits.join(", ")) : ""}`);
+    for (const f of proj.folders || []) {
+      // Marked so the folder you are STANDING IN is obvious at a glance; the whole point is telling
+      // "this worktree is the one Niro reflects" from "this one is not".
+      const here = path.resolve(f.path) === path.resolve(p.git_root) ? color.green("  <- you are here") : "";
+      // Say plainly which folder holds the temporary project. Without this the line reads as though
+      // Niro were answering from the source project for that folder, which is the opposite of the truth.
+      let temp = "";
+      if (f.temp_project_id && f.reflected === false) {
+        // The line that used to mislead. Say plainly that this folder is not the one being reflected.
+        temp = color.yellow(` — NOT reflected: temporary project ${f.temp_project_id} is on another branch`);
+      } else if (f.temp_project_id) {
+        temp = color.dim(` via temporary project ${f.temp_project_id}`)
+          + (f.reflected === null ? color.dim(" (could not confirm)") : "");
+      }
+      console.log(color.dim(`      syncing from ${f.path}`) +
+        (f.branch ? color.dim(` on branch ${f.branch}`) : "") + temp + here);
+    }
   }
 }
 

package/src/commands/init.js

@@ -36,6 +36,7 @@ const credentials = require("../lib/credentials");
 const prompt = require("../lib/prompt");
 const git = require("../lib/git");
 const niroProjectFile = require("../lib/niroProjectFile");
+const onboardTarget = require("../lib/onboardTarget");
 const color = require("../lib/color");
 const watchDaemon = require("../lib/watchDaemon");
 const { login } = require("./login");
@@ -62,6 +63,36 @@ async function init(pathArg, opts = {}) {
     process.exitCode = 1;
     return;
   }
+  // Backend URL as it looks BEFORE the login. Used for ONE thing only: the gate's
+  // already-registered lookup, which has to happen before the login prompt.
+  //
+  // It is deliberately NOT reused after the login. currentBaseUrl() reads the backend out
+  // of the stored credentials, so a login can CHANGE it: `niro init --api-url <local>` on a
+  // machine with no session resolves the production URL here and the local one afterwards.
+  // Tagging a watchState entry with this stale value would stamp an entry with a backend
+  // that did not issue its gitId, after which watchState.get(dir, realBackend) returns null,
+  // the daemon never syncs the folder, and the next run re-registers a duplicate repo and
+  // re-uploads everything. The authoritative value is re-read below, after the login.
+  //
+  // Being wrong here only affects the alreadyRegistered waiver, which can at worst refuse a
+  // folder that --force reopens. It can never waive the protected-root refusal.
+  const apiUrlBeforeLogin = api.currentBaseUrl();
+
+  // Onboarding gate — runs BEFORE the login prompt and before any server call, so a
+  // refused folder leaves nothing behind: no registered repo, no orphan project, no
+  // .niro-project pin, no watcher. Refuses $HOME / the filesystem root outright, and
+  // refuses a folder with no build descriptor at it or just below it. --force covers only
+  // that second rule, and so does alreadyRegistered: a folder this backend already has a
+  // repo for must not start failing its re-run just because it has no build file.
+  // See src/lib/onboardTarget.js.
+  const knownEntry = watchState.get(targetDir, apiUrlBeforeLogin);
+  if (!onboardTarget.ensureOnboardable(targetDir, {
+    ...opts,
+    alreadyRegistered: !!(knownEntry && knownEntry.gitId),
+  })) {
+    process.exitCode = 1;
+    return;
+  }
 
   let creds = credentials.load();
   if (!creds || !creds.token) {
@@ -71,8 +102,9 @@ async function init(pathArg, opts = {}) {
     if (!creds || !creds.token) return;
   }
 
-  // The backend the CLI is pointed at. watchState entries (cached gitIds) are
-  // scoped to this so a backend switch never reuses a gitId from another stack.
+  // Authoritative backend, re-read AFTER the login: the login is what establishes which
+  // stack this session talks to. Every watchState read and write below uses THIS value, so
+  // an entry is always tagged with the backend that actually issued its gitId.
   const currentApiUrl = api.currentBaseUrl();
 
   const gitInfo = git.inspect(targetDir);
@@ -640,7 +672,13 @@ const CHILD_SCAN_SKIP = new Set([
   "node_modules", "target", "dist", "build", "out", ".next", "vendor", "__pycache__",
 ]);
 const CHILD_SCAN_MAX = 60;       // bound the number of nested repos we resolve
-const CHILD_SCAN_MAX_DEPTH = 2;  // immediate children + one level of grouping dirs (services/, packages/, apps/)
+// Immediate children plus three levels of grouping dirs. Real checkout layouts nest
+// deeper than one grouping level (~/projects/github/<org>/<repo> is depth 3), and at
+// depth 2 this scan silently found NOTHING there — so the "parent of indexed repos"
+// refusal never fired for the most common layout. The walk never descends INTO a git
+// repo, so the extra depth only costs readdir on grouping dirs: measured 9 dirs for a
+// single repo and 50 for this monorepo, versus 5 and 13 at depth 2.
+const CHILD_SCAN_MAX_DEPTH = 4;
 
 /**
  * Collect directories under `root` that are their OWN git repo (have a `.git` entry),

package/src/commands/takeover.js

@@ -13,6 +13,7 @@
  *
  * Undo with `niro discard-temp-project` (deletes P'; routing falls back to P automatically).
  */
+const path = require("path");
 const api = require("../lib/api");
 const color = require("../lib/color");
 const folderSync = require("../lib/folderSync");
@@ -27,12 +28,14 @@ const warn = (s) => color.yellow(s);
 const step = (s) => color.cyan(s);
 
 async function takeover(pathArg, opts = {}) {
-  // --api-url is threaded only into project resolution, not the clone/build POSTs or the agentApi upload
-  // chain — so a global `--api-url X` would resolve against X but clone/upload/watch-tag against the DEFAULT
-  // backend, mixing two stacks in one flow. Fail fast BEFORE any server mutation rather than corrupt state
-  // across backends. (Full per-backend threading is future work; set the default backend via login/config.)
+  // Second layer. src/index.js refuses `--api-url` for every command except `niro login`
+  // before the action ever runs, so a CLI user never reaches this. It stays for a
+  // PROGRAMMATIC caller (a test, a skill, a future internal call) that constructs opts
+  // directly and bypasses commander entirely: a per-command backend override mixes two
+  // stacks in one flow, and this is the one command that clones, uploads and tags watchState
+  // in a single pass.
   if (opts.apiUrl) {
-    throw new Error("`--api-url` is not supported for `niro new-temp-project` yet (it would mix backends). "
+    throw new Error("`--api-url` is not supported for `niro new-temp-project` (it would mix backends). "
         + "Select the backend with `niro login` / your config first, then run this without --api-url.");
   }
   const targetDir = require("path").resolve(pathArg || process.cwd());
@@ -71,6 +74,40 @@ async function takeover(pathArg, opts = {}) {
     throw new Error("Server did not report which repo of the project matches this folder (git_id missing).");
   }
 
+  // ONE temporary project per project. If a DIFFERENT folder already holds it, moving it here stops
+  // Niro reflecting that folder — and until now that happened silently: the other folder kept uploading
+  // its own branch into the copy, so two branches blended into one and every answer drawn from it was a
+  // mixture. Verified live with two worktrees.
+  //
+  // The SAME folder is deliberately not asked. Switching branch in place loses nothing: the copy was
+  // already reflecting this folder, and the branch it names has moved on. The server relabels it, which
+  // is right, and a prompt there would be pure friction.
+  const here = path.resolve(repoRoot);
+  const holder = watchState.allLocal(api.currentBaseUrl()).find((e) =>
+    e.takeover && e.takeover.sourceProjectId === source.project_id
+    && path.resolve(e.folderPath) !== here);
+  if (holder) {
+    const onBranch = holder.branch ? ` on branch \`${holder.branch}\`` : "";
+    console.log(warn("\n  Niro keeps ONE temporary project per project, and this project's is already"));
+    console.log(warn("  held by another folder:"));
+    console.log(`    ${holder.folderPath}${onBranch}`);
+    console.log(color.dim("  Moving it here stops Niro reflecting that folder: it falls back to the original"));
+    console.log(color.dim("  project until `niro new-temp-project` is run there again."));
+    if (prompt.isNonInteractive()) {
+      // Refuse rather than hang, and rather than proceed. Proceeding is what caused the problem; hanging
+      // would break any agent or script that runs this unattended. The way forward is two explicit
+      // commands, which is clearer than a flag that quietly takes the slot from another folder.
+      throw new Error(
+        "Refusing to move the temporary project without confirmation (nothing to prompt on). "
+        + "Niro keeps ONE temporary project per project, and this one is held by "
+        + holder.folderPath + (holder.branch ? ` on branch ${holder.branch}` : "")
+        + ". Run `niro discard-temp-project` in that folder first, then re-run this here.");
+    }
+    if (!(await prompt.confirm("  Move the temporary project to this folder?", false))) {
+      throw new Error("Cancelled — the temporary project stays where it is.");
+    }
+  }
+
   console.log(`\n  Creating a temporary private project of ${color.bold(source.alias || source.project_id)}...`);
   console.log(color.dim("  Your original project is not changed."));
 

package/src/commands/watch.js

@@ -19,6 +19,8 @@ const credentials = require("../lib/credentials");
 const prompt = require("../lib/prompt");
 const color = require("../lib/color");
 const folderSync = require("../lib/folderSync");
+const git = require("../lib/git");
+const tempProject = require("../lib/tempProject");
 const {
   SOURCE_EXTENSIONS, STRUCTURAL_EXTENSIONS, STRUCTURAL_FILENAMES,
   IGNORED_DIRS, isConfigName, chunk,
@@ -31,10 +33,52 @@ const DEBOUNCE_MS = 2_000;
 // so a slower run would clobber a faster one's hash updates. A per-folder guard serializes them (a skipped
 // run is safe — the in-progress one re-hashes the whole tree and so already covers the skipped trigger).
 const syncInFlight = new Set();
+// Folders that are NOT the one their temporary project currently reflects. Uploads from these are held
+// back until the slot returns, so two branches cannot blend into one copy. Set by deltaSyncOnResume and
+// honoured by the live file handler, so one check per sync pass covers both paths rather than asking
+// the server on every save.
+const notHolding = new Set();
 // The state file is rewritten several times during a `niro takeover` (per-file hashes), so debounce
 // before reconciling the watch set. Also the interval for the mtime backstop re-scan below.
 const STATE_RELOAD_DEBOUNCE_MS = 1_500;
 const RESCAN_INTERVAL_MS = 60_000;
+/** Ceiling for the backstop's exponential backoff. Long enough to stop hammering a broken server,
+ *  short enough that a recovered one is picked up within half an hour without anyone intervening. */
+const BACKSTOP_BACKOFF_MAX_MS = 30 * 60_000;
+
+/**
+ * Per-folder retry state for the backstop re-scan: { failures, nextAttemptAt }.
+ *
+ * The backstop used to fire every 60s regardless of how many times it had just failed, with no
+ * backoff, no cap and no notion that anything was wrong. When the server broke on 8-9 August it
+ * minted a fresh sync session every single tick — roughly 1,400 failed requests a day, for two days,
+ * per watched folder. The bug was ours, but the client turned it into a flood.
+ */
+const backstopBackoff = new Map();
+
+/** Doubling delay, capped. failures=1 gives 2 minutes; the cap is reached after about six. */
+function nextBackoffMs(failures) {
+  return Math.min(RESCAN_INTERVAL_MS * Math.pow(2, failures), BACKSTOP_BACKOFF_MAX_MS);
+}
+
+/** False while a folder is still serving a backoff from its last failure. */
+function shouldAttemptBackstop(key, now = Date.now()) {
+  const state = backstopBackoff.get(key);
+  return !state || now >= state.nextAttemptAt;
+}
+
+/** @return the delay applied, so the caller can say how long it is waiting. */
+function recordBackstopFailure(key, now = Date.now()) {
+  const failures = (backstopBackoff.get(key)?.failures || 0) + 1;
+  const delay = nextBackoffMs(failures);
+  backstopBackoff.set(key, { failures, nextAttemptAt: now + delay });
+  return delay;
+}
+
+/** @return true if this success ended a run of failures (so recovery is worth announcing). */
+function recordBackstopSuccess(key) {
+  return backstopBackoff.delete(key);
+}
 
 async function watch(pathArg, opts = {}) {
   const creds = credentials.requireCreds();
@@ -192,8 +236,42 @@ async function startWatch(targetDir, opts = {}) {
   const rescanTimer = setInterval(() => {
     const fresh = watchState.get(targetDir, api.currentBaseUrl());
     if (!fresh || !fresh.gitId) return; // folder released — nothing to sync
-    deltaSyncOnResume(fresh.gitId, targetDir, fresh, { quiet: true }).catch(err =>
-      console.error(color.red(`  Backstop re-scan failed for ${targetDir}: ${err.message}`)));
+    // Back off after failures instead of retrying every 60s forever. Retrying at full rate against a
+    // server that is failing does not fix anything and buries the real error in its own noise.
+    const backoffKey = path.resolve(targetDir);
+    if (!shouldAttemptBackstop(backoffKey)) return;
+    deltaSyncOnResume(fresh.gitId, targetDir, fresh, { quiet: true })
+      .then(result => {
+        // A run that never reached the server proves nothing about the server. The in-flight guard
+        // returns at once when another sync for this folder is already going, and during an outage a
+        // large delta holds that flag for minutes — so a skipped tick was clearing the failure count
+        // and printing a green "Sync recovered" in the middle of the incident, while the real run was
+        // still heading for its own failure. The count then never grew past one, so the backoff never
+        // climbed towards its ceiling and kept hammering every two minutes: both things this backoff
+        // was added to stop.
+        // Only a pass that actually reached the server and had nothing fail counts as a recovery.
+        // A skipped run (another sync in flight) and a no-change run both contact nothing, and a pass
+        // whose per-file deletes were all refused resolves cleanly — so all three used to clear the
+        // failure count and print a green "Sync recovered" during an outage, which is how the retry rate
+        // never decayed and the real error stayed buried.
+        if (!result || result.skipped || result.noContact || result.notHolder) return;
+        if (result.failures > 0) {
+          const delayMs = recordBackstopFailure(backoffKey, Date.now());
+          console.error(color.red(
+            `  ${result.failures} file operation(s) failed for ${targetDir} — retrying in ` +
+            `${Math.round(delayMs / 60_000)} min.`));
+          return;
+        }
+        if (recordBackstopSuccess(backoffKey)) {
+          console.log(color.green(`  Sync recovered for ${targetDir}.`));
+        }
+      })
+      .catch(err => {
+        const delayMs = recordBackstopFailure(backoffKey, Date.now());
+        console.error(color.red(
+          `  Backstop re-scan failed for ${targetDir}: ${err.message} — retrying in ` +
+          `${Math.round(delayMs / 60_000)} min.`));
+      });
   }, RESCAN_INTERVAL_MS);
 
   // Start file watcher
@@ -244,11 +322,51 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
   if (syncInFlight.has(inFlightKey)) {
     // A sync (startup, live event, or backstop) is already running for this folder — skip to avoid the
     // whole-map fileHashes clobber race; the in-progress run re-hashes the whole tree and covers this trigger.
-    return;
+    // Reported so the caller can tell "nothing to do" from "the server answered": this run never
+    // contacted it, so it is not evidence that anything is working.
+    return { skipped: true };
   }
   syncInFlight.add(inFlightKey);
   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.
+  //
+  // 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 (!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}\`.`));
+      }
+      return { notHolder: true };
+    }
+    if (notHolding.delete(inFlightKey)) {
+      console.log(color.green(`  ${targetDir} holds the temporary project again — resuming uploads.`));
+    }
+  }
   const storedHashes = state.fileHashes || {};
   const currentHashes = {};
   const changed = [];
@@ -257,27 +375,50 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
   // Walk all currently included files
   const manifest = buildMinimalManifest(targetDir, state.includePatterns, state.excludePatterns);
 
+  const unreadable = [];
   for (const relativePath of manifest) {
     const absPath = path.join(targetDir, relativePath);
     const hash = watchState.hashFile(absPath);
-    if (!hash) continue;
+    if (!hash) {
+      // The walk that produced this manifest JUST FOUND this file, so it exists. Failing to READ it
+      // is not evidence that it was deleted — it is a permission error, a transient lock, a file being
+      // rewritten, or simply too many open files. hashFile returns null for every one of those.
+      //
+      // Skipping the file here used to leave it out of currentHashes, and the loop below reads
+      // "absent from currentHashes" as "deleted", so an unreadable file became a delete instruction to
+      // the server. Carrying the stored hash forward keeps it in the baseline and out of `deleted`.
+      unreadable.push(relativePath);
+      if (Object.prototype.hasOwnProperty.call(storedHashes, relativePath)) {
+        currentHashes[relativePath] = storedHashes[relativePath];
+      }
+      continue;
+    }
     currentHashes[relativePath] = hash;
     if (storedHashes[relativePath] !== hash) {
       changed.push(relativePath);
     }
   }
 
-  // Files that were in stored hashes but no longer exist
+  if (unreadable.length > 0) {
+    console.warn(color.yellow(
+      `  ${unreadable.length} file(s) could not be read this pass — keeping them as-is rather than ` +
+      `reporting them deleted. Sample: ${unreadable.slice(0, 5).join(", ")}`));
+  }
+
+  // Files that were in stored hashes but are no longer present in the walk at all.
   for (const rp of Object.keys(storedHashes)) {
-    if (!currentHashes[rp]) {
+    if (!Object.prototype.hasOwnProperty.call(currentHashes, rp)) {
       deleted.push(rp);
     }
   }
 
   if (changed.length === 0 && deleted.length === 0) {
     if (!quiet) console.log(`  No changes since last sync.`);
-    watchState.update(targetDir, { fileHashes: currentHashes });
-    return;
+    watchState.mergeFileHashes(targetDir, { set: currentHashes });
+    // Nothing to send, so the server was never contacted and this pass is not evidence it is healthy.
+    // This is the MAJORITY of backstop ticks: treated as a success it cleared the failure count on the
+    // very next tick after one, so the backoff could never grow past its first step.
+    return { noContact: true };
   }
 
   // A quiet backstop run only speaks up when it actually found something fs.watch missed.
@@ -287,6 +428,7 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
   // using the same helper as init/add-repo. A gitignored secret edited after
   // onboarding (e.g. a raw .env) must never be re-uploaded here.
   let changedToUpload = changed;
+  const gitignoreDropped = [];
   if (changed.length > 0) {
     const drops = folderSync.gitignoreDrops(targetDir, changed);
     if (drops.size > 0) {
@@ -294,7 +436,7 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
       // Don't persist hashes for dropped (gitignored / unverifiable) files — they
       // were never uploaded, so leave them out of state so they're re-evaluated
       // rather than recorded as synced.
-      for (const rp of drops) delete currentHashes[rp];
+      for (const rp of drops) { delete currentHashes[rp]; gitignoreDropped.push(rp); }
     }
   }
 
@@ -313,16 +455,61 @@ async function deltaSyncOnResume(gitId, targetDir, state, opts = {}) {
     await agentApi.completeSync(gitId, sessionId);
   }
 
+  // Re-check each file immediately before telling the server to remove it. The walk that built this
+  // list ran BEFORE the uploads above, which on a large delta take minutes, so by now a file may exist
+  // again — or may never have been gone, having merely been unreadable at the wrong moment. The live
+  // per-file path already stats before deleting; this one fired blind.
+  // Per-file failures are swallowed below so one bad path cannot abort the pass. They still have to be
+  // REPORTED, or a pass in which everything failed is indistinguishable from one in which all was well.
+  let failures = 0;
+  const reappeared = [];
+  // Only paths the server actually accepted. Marking a FAILED delete as done drops it from the
+  // baseline, and once dropped it can never re-enter `deleted` — so the file stays on the server, stays
+  // indexed, and nothing retries it. With the burst guard that is systematic: delete 500 files, the
+  // first 100 land, the rest are refused, and all 500 were being forgotten.
+  const deletedOk = [];
   for (const rp of deleted) {
+    // Existing on disk is NOT on its own a reason to keep it. A file leaves the manifest for two
+    // different reasons: it was removed from disk, or it stopped matching the include/exclude
+    // patterns. Only the first can "come back". Rescuing on existence alone meant adding an exclude
+    // pattern no longer removed the file from Niro — so a path excluded BECAUSE it holds secrets
+    // would have gone on being indexed for ever.
+    if (fs.existsSync(path.join(targetDir, rp)) && inManifestScope(rp, state)) {
+      reappeared.push(rp);
+      continue;
+    }
     try {
       await agentApi.deleteFile(gitId, rp);
+      deletedOk.push(rp);
     } catch (err) {
+      // Swallowed so one bad path cannot abort the pass, but COUNTED: a pass whose deltas are deletes
+      // only never throws, so without this the caller saw a clean resolve while every single delete was
+      // being refused, cleared the backoff, and retried the whole set 60 seconds later. Forever.
+      failures++;
       console.warn(color.yellow(`  Warning: failed to delete ${rp}: ${err.message}`));
     }
   }
-
-  watchState.update(targetDir, { fileHashes: currentHashes, lastSyncedAt: new Date().toISOString() });
+  if (reappeared.length > 0) {
+    console.warn(color.yellow(
+      `  ${reappeared.length} file(s) were back on disk by the time the delete ran — not deleted. ` +
+      `Sample: ${reappeared.slice(0, 5).join(", ")}`));
+    // Deliberately NOT re-hashed into the baseline. The file may have come back with DIFFERENT bytes
+    // (a branch switch or stash pop mid-upload), and it was in `deleted` rather than `changed`, so it
+    // was never uploaded — recording the new hash would claim the server holds content it never
+    // received. Leaving its OLD entry untouched is what makes the next pass see a hash mismatch and
+    // upload it. It is in scope and on disk, so that pass finds it in the manifest.
+  }
+  const actuallyDeleted = deletedOk;
+
+  // Merge rather than replace. Removals are explicit: the files we actually deleted, plus any the
+  // gitignore policy dropped (those were never uploaded, so they must not stay recorded as synced).
+  watchState.mergeFileHashes(targetDir, {
+    set: currentHashes,
+    remove: [...actuallyDeleted, ...gitignoreDropped],
+    patch: { lastSyncedAt: new Date().toISOString() },
+  });
   console.log(`  ${color.green("✓")} Delta sync complete.`);
+  return { failures };
   } finally {
     syncInFlight.delete(inFlightKey);
   }
@@ -335,6 +522,10 @@ async function handleFileEvent(gitId, targetDir, relativePath, state) {
   // daemon kept uploading to the OLD gitId — every edit failed with "Repository not found"
   // until the daemon was manually restarted. Reading fresh also picks up include/exclude
   // pattern changes from `niro edit`.
+  //
+  // Held back by the last sync pass: this folder is not the one its temporary project reflects, so
+  // uploading would mix two branches into one copy. Re-checked every pass, so it clears by itself.
+  if (notHolding.has(path.resolve(targetDir))) return;
   const fresh = watchState.get(targetDir, api.currentBaseUrl());
   if (!fresh || !fresh.gitId) {
     // Folder was released / is no longer tracked for this backend — stop syncing it.
@@ -390,9 +581,10 @@ async function handleFileEvent(gitId, targetDir, relativePath, state) {
     // File deleted
     try {
       await agentApi.deleteFile(gitId, relativePath);
-      const hashes = { ...(watchState.get(targetDir) || {}).fileHashes };
-      delete hashes[relativePath];
-      watchState.update(targetDir, { fileHashes: hashes, lastSyncedAt: new Date().toISOString() });
+      watchState.mergeFileHashes(targetDir, {
+        remove: [relativePath],
+        patch: { lastSyncedAt: new Date().toISOString() },
+      });
       console.log(`  ${color.yellow("−")} ${relativePath}`);
     } catch (err) {
       console.error(color.red(`  Failed to delete ${relativePath}: ${err.message}`));
@@ -422,8 +614,10 @@ async function handleFileEvent(gitId, targetDir, relativePath, state) {
 
   try {
     await agentApi.upsertFile(gitId, relativePath, absPath);
-    const hashes = { ...storedHashes, [relativePath]: newHash };
-    watchState.update(targetDir, { fileHashes: hashes, lastSyncedAt: new Date().toISOString() });
+    watchState.mergeFileHashes(targetDir, {
+      set: { [relativePath]: newHash },
+      patch: { lastSyncedAt: new Date().toISOString() },
+    });
     console.log(`  ${color.green("+")} ${relativePath}`);
   } catch (err) {
     console.error(color.red(`  Failed to sync ${relativePath}: ${err.message}`));
@@ -435,6 +629,13 @@ function shouldIgnore(relativePath) {
   return parts.some(p => IGNORED_DIRS.has(p) || p.startsWith("."));
 }
 
+/** Mirrors buildMinimalManifest's membership rule: empty includePatterns means everything is in. */
+function inManifestScope(relativePath, state) {
+  const include = state.includePatterns;
+  if (!include || include.length === 0) return true;
+  return matchesPatterns(relativePath, include, state.excludePatterns);
+}
+
 function matchesPatterns(relativePath, includePatterns, excludePatterns) {
   if (!includePatterns || includePatterns.length === 0) return true;
   const matched = includePatterns.some(p => minimatch(relativePath, p));
@@ -495,4 +696,5 @@ 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, handleFileEvent, deltaSyncOnResume, handleEntryFailure,
+  nextBackoffMs, shouldAttemptBackstop, recordBackstopFailure, recordBackstopSuccess };

package/src/index.js

@@ -9,7 +9,34 @@ function main() {
     .name("niro")
     .description("Niro CLI — onboard repos, build indexes, manage projects from the terminal.")
     .version(pkg.version)
-    .option("--api-url <url>", "override API base URL (default: $NIRO_API_URL or https://aiorchestrator.niroai.dev)");
+    .option("--api-url <url>", "backend to log in to — `niro login` only (default: $NIRO_API_URL or https://aiorchestrator.niroai.dev)");
+
+  // --api-url is accepted by `niro login` and REFUSED everywhere else.
+  //
+  // It used to be a global override, but it was only half honoured. api.request takes it
+  // (api.js: `const base = apiUrl || baseUrl(creds)`), while the upload chain builds its own
+  // URL from the stored credentials and never sees it (agentApi.js:113 and :175). So
+  // `niro init --api-url <local>` while logged in elsewhere listed projects from one backend
+  // and uploaded the folder's source to the other — one command, two servers, no warning.
+  //
+  // Threading it through every path is the other possible fix, but the backend is a property
+  // of a SESSION, not of a single command: credentials, tokens, gitIds and watchState tags are
+  // all scoped to one backend, so a per-command override can only ever be a way to mix them.
+  // Choosing it once, at login, is the honest contract. NIRO_API_URL and the config file still
+  // work for every command, because both feed the same resolution chain the uploader uses.
+  //
+  // `niro new-temp-project` already refused this flag for exactly this reason; that local
+  // check is now redundant and has been removed in favour of this one.
+  program.hook("preAction", (_thisCommand, actionCommand) => {
+    if (!program.opts().apiUrl) return;
+    if (actionCommand.name() === "login") return;
+    console.error("`--api-url` only applies to `niro login`.");
+    console.error("  It was ignored by the upload path, so using it here would read from one");
+    console.error("  backend and write to another. Pick the backend once instead:");
+    console.error("    niro login --api-url <url>        log in to that backend");
+    console.error("    NIRO_API_URL=<url> niro <cmd>     or set it for every command");
+    process.exit(1);
+  });
 
   program
     .command("login")
@@ -19,7 +46,7 @@ function main() {
     .option("--email <email>", "email address (password flow only)")
     .action((opts) => run(async () => {
       const loginCmd = require("./commands/login");
-      await loginCmd.login({ ...opts, apiUrl: program.opts().apiUrl });
+      await loginCmd.login({ ...opts, apiUrl: program.opts().apiUrl }); // login: the one command that may set it
     }));
 
   program
@@ -48,7 +75,7 @@ function main() {
     .option("--quiet-period <seconds>", "debounce seconds before an auto-build (used with --auto-build on)")
     .option("--confirm-build <yes|no>", "whether to trigger the initial index build now without prompting")
     .option("--defaults", "accept default values for all env vars without prompting")
-    .option("--force", "proceed past cross-project/overlap warnings without confirming")
+    .option("--force", "onboard a folder with no build file, and proceed past cross-project/overlap warnings without confirming (never bypasses the home/root refusal)")
     .option("--no-watch", "return immediately after triggering the build instead of watching")
     .option(
       "-X, --module-exclude <pattern>",
@@ -64,7 +91,7 @@ function main() {
     )
     .action((pathArg, opts) => run(async () => {
       const initCmd = require("./commands/init");
-      await initCmd.init(pathArg, { ...opts, apiUrl: program.opts().apiUrl });
+      await initCmd.init(pathArg, { ...opts });
     }));
 
   // `niro add` subcommand group
@@ -79,6 +106,7 @@ function main() {
     .option("--name <name>", "display name for this repo")
     .option("--sync-mode <local|remote>", "sync on local file changes or remote commits (skips the interactive choice)")
     .option("--no-confirm", "skip confirmation prompts (non-interactive)")
+    .option("--force", "onboard a folder with no build file in it (never bypasses the home/root refusal)")
     .option("--token-id <id>", "git token ID for private repos")
     .option(
       "-X, --module-exclude <pattern>",
@@ -94,7 +122,7 @@ function main() {
     )
     .action((pathArg, opts) => run(async () => {
       const cmd = require("./commands/add-repo");
-      await cmd.addRepo(pathArg, { ...opts, apiUrl: program.opts().apiUrl });
+      await cmd.addRepo(pathArg, { ...opts });
     }));
 
   add
@@ -103,7 +131,7 @@ function main() {
     .option("--no-watch", "return immediately after triggering the build")
     .action((opts) => run(async () => {
       const cmd = require("./commands/add-project");
-      await cmd.addProject({ ...opts, apiUrl: program.opts().apiUrl });
+      await cmd.addProject({ ...opts });
     }));
 
   program
@@ -112,7 +140,7 @@ function main() {
     .option("--json", "emit machine-readable JSON")
     .action((pathArg, opts) => run(async () => {
       const infoCmd = require("./commands/info");
-      await infoCmd.info(pathArg, { ...opts, apiUrl: program.opts().apiUrl });
+      await infoCmd.info(pathArg, { ...opts });
     }));
 
   program
@@ -131,7 +159,7 @@ function main() {
     .option("--json", "emit machine-readable JSON where supported (set-env, list-env)")
     .action((opts) => run(async () => {
       const editCmd = require("./commands/edit");
-      await editCmd.edit({ ...opts, apiUrl: program.opts().apiUrl });
+      await editCmd.edit({ ...opts });
     }));
 
   program
@@ -143,7 +171,7 @@ function main() {
     .option("--confirm-name <value>", "required for --project: must equal the project's alias or id")
     .action((opts) => run(async () => {
       const removeCmd = require("./commands/remove");
-      await removeCmd.remove({ ...opts, apiUrl: program.opts().apiUrl });
+      await removeCmd.remove({ ...opts });
     }));
 
   program
@@ -161,7 +189,7 @@ function main() {
     .option("--project <id_or_alias>", "which project to base the temporary project on when the repo maps to several")
     .action((pathArg, opts) => run(async () => {
       const cmd = require("./commands/takeover");
-      await cmd.takeover(pathArg, { ...opts, apiUrl: program.opts().apiUrl });
+      await cmd.takeover(pathArg, { ...opts });
     }));
 
   program
@@ -172,7 +200,7 @@ function main() {
     .option("--project <temp_project_id>", "the temporary project to discard, when this machine has no local record of it (e.g. created elsewhere)")
     .action((pathArg, opts) => run(async () => {
       const cmd = require("./commands/release");
-      await cmd.release(pathArg, { ...opts, apiUrl: program.opts().apiUrl });
+      await cmd.release(pathArg, { ...opts });
     }));
 
   program
@@ -181,7 +209,7 @@ function main() {
     .option("--json", "emit machine-readable JSON")
     .action((projectId, opts) => run(async () => {
       const statusCmd = require("./commands/status");
-      await statusCmd.status(projectId, { ...opts, apiUrl: program.opts().apiUrl });
+      await statusCmd.status(projectId, { ...opts });
     }));
 
   program
@@ -191,7 +219,7 @@ function main() {
     .option("--json", "emit machine-readable JSON")
     .action((opts) => run(async () => {
       const projectsCmd = require("./commands/projects");
-      await projectsCmd.projects({ ...opts, apiUrl: program.opts().apiUrl });
+      await projectsCmd.projects({ ...opts });
     }));
 
   program
@@ -202,7 +230,7 @@ function main() {
     .option("--json", "emit machine-readable JSON status (NDJSON: one object per status change + a final summary)")
     .action((projectId, opts) => run(async () => {
       const buildCmd = require("./commands/build");
-      await buildCmd.build(projectId, { ...opts, apiUrl: program.opts().apiUrl });
+      await buildCmd.build(projectId, { ...opts });
     }));
 
   program
@@ -211,7 +239,7 @@ function main() {
     .option("-y, --yes", "skip the confirmation prompt")
     .action((projectId, opts) => run(async () => {
       const deleteCmd = require("./commands/delete");
-      await deleteCmd.deleteProject(projectId, { ...opts, apiUrl: program.opts().apiUrl });
+      await deleteCmd.deleteProject(projectId, { ...opts });
     }));
 
   const svc = program

package/src/lib/onboardTarget.js

@@ -0,0 +1,258 @@
+/**
+ * Is this folder a sane thing to onboard? The check that runs BEFORE
+ * `niro init` / `niro add repo` register anything on the server or upload a byte.
+ *
+ * Two independent rules:
+ *
+ *   1. PROTECTED ROOT — never bypassable. $HOME, the filesystem root, any ancestor
+ *      of $HOME (/home, /Users) and the well-known system dirs are refused outright.
+ *      Onboarding one of these is never intended, and the damage is not the kind
+ *      --force should be able to cause by accident: source from every project on the
+ *      machine uploaded as one blob, a .niro-project pin dropped at $HOME, and a
+ *      watch daemon streaming the whole home tree. Worse, .gitignore is only honoured
+ *      when the onboarded folder is itself a git work tree, so onboarding $HOME
+ *      silently uploads files that each nested repo deliberately ignores.
+ *
+ *   2. PROJECT INDICATOR — bypassable with --force. The folder must LOOK like a
+ *      project: a build descriptor at the folder itself, or in a directory just below
+ *      it. This mirrors ai-orchestrator
+ *      ProjectStructureResolverService.detectProjects(), which marks any directory
+ *      holding a descriptor from the ConfigFileParser SUPPORTED_FILES union as a
+ *      project root. folderSync already carries that union as STRUCTURAL_FILENAMES /
+ *      STRUCTURAL_EXTENSIONS (documented there as byte-identical to the server), so
+ *      this REUSES those sets. There is deliberately no second list to drift.
+ *
+ * Two deliberate differences from the server:
+ *
+ *   - Depth-bounded (INDICATOR_MAX_DEPTH) instead of a full-tree walk. The question
+ *     here is "is THIS folder a project", not "which projects live somewhere inside
+ *     it". A descriptor buried deep is precisely the accident being caught: $HOME
+ *     contains thousands of them.
+ *   - No parser veto. The server asks the owning parser isProjectIndicator(file) to
+ *     reject a false match (a Python module literally named setup.py). The CLI cannot
+ *     parse, so a name match is accepted. That errs toward ALLOWING onboarding, which
+ *     is the safe direction for a guard: the worst case is the behaviour we had before.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const color = require("./color");
+const folderSync = require("./folderSync");
+
+// How far below the target we look for a build descriptor. 0 = the folder itself.
+// 2 covers a monorepo root whose deployables sit under a grouping dir
+// (services/foo/pom.xml, packages/foo/package.json) and still refuses a folder whose
+// only descriptors are buried deeper than any real project root would be.
+const INDICATOR_MAX_DEPTH = 2;
+
+// Hard bound on the walk so a pathological tree cannot stall the command.
+const MAX_DIRS_SCANNED = 2000;
+
+// Refused outright, by exact path match. Ancestors of $HOME (/home, /Users) are
+// caught by the ancestor rule below as well; listed here for the case where $HOME
+// lives somewhere unusual.
+const SYSTEM_DIRS = new Set([
+  "/", "/bin", "/boot", "/dev", "/etc", "/home", "/lib", "/lib64", "/media",
+  "/mnt", "/opt", "/proc", "/root", "/run", "/sbin", "/srv", "/sys", "/tmp",
+  "/usr", "/var", "/Applications", "/Library", "/System", "/Users", "/Volumes",
+]);
+
+// Windows paths are case-insensitive; POSIX paths are not.
+function samePath(a, b) {
+  if (process.platform === "win32") return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+// Resolve symlinks before comparing, so a symlinked route to a protected path (macOS
+// /tmp -> /private/tmp, an $HOME reached through /mnt/home/<user>) cannot walk past the
+// refusal on a string mismatch. Falls back to the lexical path when the target does not
+// exist or is unreadable — the comparison is then no worse than before.
+function realPath(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Why this folder must never be onboarded, or null when it is fine.
+ * Returns a human phrase that slots into "Refusing to onboard <phrase>".
+ */
+function protectedRootReason(dir) {
+  const target = realPath(path.resolve(dir));
+
+  if (samePath(target, path.parse(target).root)) return "the filesystem root";
+
+  let home = null;
+  try {
+    home = os.homedir() ? realPath(path.resolve(os.homedir())) : null;
+  } catch {
+    home = null; // no home resolvable -> only the root/system rules apply
+  }
+  if (home) {
+    if (samePath(target, home)) return "your home folder";
+    // home lives INSIDE target => target is an ancestor of home (/home, /Users, ...).
+    const rel = path.relative(target, home);
+    if (rel && !rel.startsWith("..") && !path.isAbsolute(rel)) {
+      return "a parent of your home folder";
+    }
+  }
+
+  if (SYSTEM_DIRS.has(target)) return "a system folder";
+  // Also refuse the lexical path when it differs from the resolved one, so a symlink
+  // POINTING AT an ordinary folder cannot be used to name a protected path either way.
+  if (SYSTEM_DIRS.has(path.resolve(dir))) return "a system folder";
+  return null;
+}
+
+/**
+ * The indicator kind this filename represents, or null. Name match wins over
+ * extension match, mirroring the server's parserRegistry-then-extensionRegistry
+ * lookup order. Returned as a display label ("pom.xml", "*.csproj").
+ */
+function indicatorName(fileName) {
+  const lower = path.basename(fileName).toLowerCase();
+  if (folderSync.STRUCTURAL_FILENAMES.has(lower)) return lower;
+  const ext = path.extname(lower);
+  if (ext && folderSync.STRUCTURAL_EXTENSIONS.has(ext)) return `*${ext}`;
+  return null;
+}
+
+/**
+ * Look for project roots at `targetDir` and just below it.
+ *
+ * Stops descending as soon as a directory IS a project root: once a descriptor is
+ * found there is nothing further to prove, and it keeps the common case (a normal
+ * repo with a descriptor at its top) down to a single readdir.
+ *
+ * Returns { roots, indicators: Map(label -> count), truncated }.
+ */
+function findProjectIndicators(targetDir, opts = {}) {
+  const maxDepth = Number.isInteger(opts.maxDepth) ? opts.maxDepth : INDICATOR_MAX_DEPTH;
+  // Injectable so the breadth-first guarantee can be tested without a 2000-directory fixture.
+  const maxDirs = Number.isInteger(opts.maxDirs) ? opts.maxDirs : MAX_DIRS_SCANNED;
+  const indicators = new Map();
+  let roots = 0;
+  let dirsScanned = 0;
+  let truncated = false;
+
+  // Breadth-first, one depth level at a time. Depth-first would let a single wide or
+  // deep subtree spend the whole MAX_DIRS_SCANNED budget before the walk ever looked
+  // at the target's own siblings, so a real project root could go unseen while junk
+  // was scanned. Breadth-first means level 0 is always examined, then all of level 1,
+  // and only the deepest level can ever be cut short.
+  let frontier = [path.resolve(targetDir)];
+  for (let depth = 0; depth <= maxDepth && frontier.length > 0; depth++) {
+    const next = [];
+    for (const dir of frontier) {
+      if (dirsScanned >= maxDirs) { truncated = true; break; }
+      dirsScanned++;
+
+      let entries;
+      try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+      } catch {
+        continue; // unreadable (permissions, vanished) -> nothing to prove here
+      }
+
+      let isRoot = false;
+      for (const entry of entries) {
+        if (!entry.isFile()) continue;
+        const label = indicatorName(entry.name);
+        if (!label) continue;
+        isRoot = true;
+        indicators.set(label, (indicators.get(label) || 0) + 1);
+      }
+      // A project root proves what we came to prove; there is no reason to look inside it.
+      if (isRoot) { roots++; continue; }
+      if (depth >= maxDepth) continue;
+
+      // Sorted so the walk is deterministic: readdir order is filesystem-dependent, and
+      // which directories fall inside the budget must not vary between machines.
+      const children = entries
+        .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !folderSync.IGNORED_DIRS.has(e.name))
+        .map((e) => e.name)
+        .sort();
+      for (const name of children) next.push(path.join(dir, name));
+    }
+    if (truncated) break;
+    frontier = next;
+  }
+
+  return { roots, indicators, truncated };
+}
+
+// "pom.xml x10, package.json x1" — the three commonest kinds, then a tail count.
+function describeIndicators(indicators) {
+  const sorted = [...indicators.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const shown = sorted.slice(0, 3).map(([label, n]) => (n > 1 ? `${label} x${n}` : label));
+  const rest = sorted.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, and ${rest} more` : shown.join(", ");
+}
+
+/**
+ * The gate itself. Prints the refusal and returns false when this folder must not be
+ * onboarded; returns true when the caller may proceed.
+ *
+ * opts.force bypasses the INDICATOR rule only. It deliberately does not bypass a
+ * protected root: there is no legitimate reason to upload $HOME, and a scripted
+ * --force must not be able to do it by accident.
+ *
+ * opts.alreadyRegistered likewise bypasses the INDICATOR rule only, for a folder this
+ * backend already holds a repo for. Callers pass it from watchState so that adding the
+ * gate never breaks a sync that was already working.
+ */
+function ensureOnboardable(targetDir, opts = {}) {
+  const resolved = path.resolve(targetDir);
+
+  const reason = protectedRootReason(resolved);
+  if (reason) {
+    console.error(color.red(`\n  ✗ Refusing to onboard ${reason} (${resolved}).`));
+    console.error("    That would upload source from every project underneath it, pin this folder");
+    console.error("    with a .niro-project file, and watch the whole tree for changes.");
+    console.error(`    Change into the project folder you meant, then run the command there.`);
+    return false;
+  }
+
+  const { roots, indicators, truncated } = findProjectIndicators(resolved, opts);
+  if (indicators.size === 0) {
+    // A folder this backend ALREADY has a repo for is exempt from the descriptor rule.
+    // That rule gates NEW onboarding; it is not a reason to start failing a re-sync of a
+    // folder onboarded by an earlier CLI, which would strand the user with no way back in.
+    // The protected-root rule above still applied, and still refuses.
+    if (opts.alreadyRegistered) {
+      console.log(color.dim(
+        `  No build file in ${resolved}, but it is already registered here — continuing.`
+      ));
+      return true;
+    }
+    if (opts.force) {
+      console.log(color.yellow(
+        `\n  ⚠ No project found in ${resolved}, but --force was passed. Onboarding it anyway.`
+      ));
+      return true;
+    }
+    console.error(color.red(`\n  ✗ No project found in ${resolved}.`));
+    console.error("    Niro looks for a build file (package.json, pom.xml, go.mod, ...) in this");
+    console.error(`    folder or just below it${truncated ? " (the scan stopped early — the tree is very large)" : ""}. None found.`);
+    console.error("    Pass --force if you really mean to upload this folder.");
+    return false;
+  }
+
+  console.log(
+    `  ${color.green("✓")} Found ${roots} project${roots === 1 ? "" : "s"} ` +
+    `(${describeIndicators(indicators)}).`
+  );
+  return true;
+}
+
+module.exports = {
+  ensureOnboardable,
+  protectedRootReason,
+  findProjectIndicators,
+  indicatorName,
+  describeIndicators,
+  INDICATOR_MAX_DEPTH,
+  MAX_DIRS_SCANNED,
+};

package/src/lib/tempProject.js

@@ -0,0 +1,37 @@
+/**
+ * Reading the state of a temporary project.
+ *
+ * A developer gets ONE temporary project per project, and `niro new-temp-project` MOVES it rather than
+ * adding a second. So "which folder does Niro currently reflect?" has exactly one answer, and it lives
+ * on the server: the branch recorded against the temporary project's repo.
+ *
+ * That matters because a folder cannot tell locally whether it still holds the slot. Every folder taken
+ * over for one project shares the SAME repo id, so the server cannot tell them apart either — if two
+ * folders upload, their branches blend into one copy and every answer drawn from it is a mixture. The
+ * only way to know is to ask which branch the copy is on and compare it with your own.
+ */
+const api = require("./api");
+
+/**
+ * The branch a temporary project is currently bound to, or null if it cannot be determined.
+ *
+ * Returns null rather than throwing on a server or network problem: this is used to decide whether to
+ * hold back an upload, and "I could not reach the server" must never be read as "you have lost the
+ * slot" — that would stop a perfectly healthy folder syncing every time the network hiccuped.
+ */
+async function currentBranch(tempProjectId, gitId, opts = {}) {
+  if (!tempProjectId) return null;
+  let project;
+  try {
+    project = await api.get(`/api/projects/${encodeURIComponent(tempProjectId)}`, opts);
+  } catch {
+    return null;
+  }
+  const repos = project.git_details || project.gitDetails || [];
+  // Match the repo by id when we can. Falling back to the first is safe for the single-repo case and
+  // still right for multi-repo: every repo in one temporary project is taken over onto one branch.
+  const match = repos.find((r) => r.id === gitId) || repos[0];
+  return match && match.branch ? match.branch : null;
+}
+
+module.exports = { currentBranch };

package/src/lib/watchState.js

@@ -127,6 +127,34 @@ function update(folderPath, patch) {
   save(state);
 }
 
+/**
+ * Merge per-path hash changes into an entry instead of replacing the whole map.
+ *
+ * `update({ fileHashes })` replaces the map wholesale, so whichever writer saves last wins and every
+ * entry the other writer added in the meantime is silently gone. The delta sync computes a map from
+ * its own walk and writes it at the end, which can take minutes on a large upload; any live per-file
+ * event that landed during that window is erased. Losing a baseline entry is not cosmetic — the file
+ * stops being tracked, so it is never re-sent and the divergence is permanent. That is the difference
+ * between the 27 July incident, which healed itself in 35 minutes, and 31 July, which never did.
+ *
+ * Removals must be explicit rather than implied by absence, so nothing disappears by accident.
+ *
+ * load/save are synchronous and save renames atomically, so this is safe against other writers in
+ * THIS process. The watch daemon is a separate process, so a cross-process interleave is still
+ * possible; this shrinks the window from minutes to microseconds rather than closing it entirely.
+ */
+function mergeFileHashes(folderPath, { set = {}, remove = [], patch = {} } = {}) {
+  const state = load();
+  const key = path.resolve(folderPath);
+  if (!state[key]) return;
+  const merged = { ...(state[key].fileHashes || {}) };
+  for (const rp of remove) delete merged[rp];
+  // Applied after the removals, so a file deleted and re-created within one run keeps its new hash.
+  Object.assign(merged, set);
+  state[key] = { ...state[key], ...patch, fileHashes: merged };
+  save(state);
+}
+
 /**
  * Remove a folder's entry. When `expectedGitId` is given, only remove if the CURRENT entry still has that
  * gitId (compare-and-delete): the self-heal path removes a poison entry after an async repoExists round-trip,
@@ -214,4 +242,5 @@ function hashFile(filePath) {
   }
 }
 
-module.exports = { get, peek, set, update, remove, allLocal, findOverlapping, matchesBackend, hashFile, FILE };
+module.exports = { get, peek, set, update, remove, allLocal, findOverlapping, matchesBackend, hashFile,
+  mergeFileHashes, FILE };