@niroai/niro 0.5.0 → 0.7.0

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,93 @@ 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();
+
+/**
+ * How long the deletes for a folder must stay quiet before any of them is believed.
+ *
+ * Not a guess at how long a git checkout takes — the timer RESETS on every new delete, so a 90-second
+ * rebase holds the queue for 90 seconds and a three-file checkout holds it for five. This only has to
+ * outlast the gap between one file vanishing and the next.
+ */
+const DELETE_SETTLE_MS = Number(process.env.NIRO_DELETE_SETTLE_MS) || 5_000;
+
+/**
+ * Deletes waiting to be believed: resolved folder -> { paths:Set, timer }.
+ *
+ * A file disappearing is not evidence it was deleted. On 2026-07-31 a customer lost 494 files because
+ * a `git checkout` removed a tree, this handler saw the gap and reported every file gone, and git then
+ * wrote them all back — by which time the server had destroyed its copies. The client's own log shows
+ * the burst (249 consecutive deletes) followed immediately by re-uploads of the very same paths.
+ *
+ * So deletes are queued rather than sent, and ONE timer per folder is reset by every new delete. When
+ * the folder finally goes quiet, whatever is still missing is really gone and is sent; whatever came
+ * back was never deleted and is dropped.
+ *
+ * Deliberately NOT volume-based, and deliberately not "detect a git operation":
+ *  - a threshold misses a small checkout that touches three files, which is just as wrong;
+ *  - lock-file detection is git-only, and the same damage comes from `npm ci`, `make clean`, a Docker
+ *    remount, Perforce (no local lock at all) or any other VCS.
+ * Waiting for quiet needs to know none of that. It is the same rule the server already applies before
+ * it rebuilds a graph.
+ *
+ * Holding a delete costs nothing: the graph only updates after its own quiet period, so a few seconds
+ * is invisible. A wrong delete costs the file AND its durable backup, at the moment the call lands.
+ */
+const pendingDeletes = new Map();
+
+/**
+ * Folders whose root we could not read, so the "cannot read" error is said ONCE rather than every
+ * 60 seconds for as long as the folder stays away. A watched folder that is renamed or unmounted is
+ * often left that way for days; repeating a red error every minute trains people to ignore the log,
+ * which is how the errors that DO matter get missed.
+ */
+const unreadableRoots = 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();
@@ -189,12 +274,7 @@ async function startWatch(targetDir, opts = {}) {
   // that drifted — the reliable, content-checked form of "also pick up changes we didn't get a live
   // event for". Re-reads fresh state, so a folder re-pointed by `niro takeover` or removed by `niro
   // release` mid-session is handled (or skipped) rather than synced to a stale gitId.
-  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}`)));
-  }, RESCAN_INTERVAL_MS);
+  const rescanTimer = setInterval(() => { backstopTick(targetDir); }, RESCAN_INTERVAL_MS);
 
   // Start file watcher
   const debounceTimers = new Map();
@@ -244,40 +324,140 @@ 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 = [];
   const deleted = [];
 
   // Walk all currently included files
-  const manifest = buildMinimalManifest(targetDir, state.includePatterns, state.excludePatterns);
+  const { files: manifest, failedDirs } = buildMinimalManifest(targetDir, state.includePatterns,
+      state.excludePatterns);
+
+  // The repo root itself could not be read — the folder was moved, unmounted, or its permissions
+  // changed. EVERY file looks missing, so a delete pass here would wipe the whole project. Abort the
+  // pass entirely; a later one recovers by itself once the folder is back.
+  if (failedDirs.includes("")) {
+    // Said once per folder, then silence until it reads again. Repeating this every 60s for a folder
+    // that has simply been moved is noise, and noise is how a real error gets missed.
+    if (!unreadableRoots.has(path.resolve(targetDir))) {
+      unreadableRoots.add(path.resolve(targetDir));
+      console.error(color.red(
+        `  Cannot read ${targetDir} — skipping this sync entirely rather than reporting every file ` +
+        `deleted. Check the folder still exists and is readable. ` +
+        `This will not be repeated until it can be read again.`));
+    }
+    return;
+  }
+  if (unreadableRoots.delete(path.resolve(targetDir))) {
+    console.log(color.green(`  ${targetDir} is readable again — syncing resumed.`));
+  }
 
+  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.
+  //
+  // "Not in the walk" only means "deleted" for parts of the tree the walk could actually READ. A
+  // directory that failed to list (permissions, a build holding it, too many open files, an NFS or
+  // Docker mount blip) yields no entries, which is indistinguishable from one whose files were all
+  // removed. Judging those would delete a subtree because we could not look at it.
+  const unreadableDirs = [];
   for (const rp of Object.keys(storedHashes)) {
-    if (!currentHashes[rp]) {
-      deleted.push(rp);
+    if (Object.prototype.hasOwnProperty.call(currentHashes, rp)) continue;
+    if (failedDirs.some(d => d && (rp === d || rp.startsWith(d + "/")))) {
+      unreadableDirs.push(rp);
+      currentHashes[rp] = storedHashes[rp]; // keep it tracked; we learned nothing about it
+      continue;
     }
+    deleted.push(rp);
+  }
+
+  if (unreadableDirs.length > 0) {
+    console.warn(color.yellow(
+      `  ${failedDirs.length} directory(ies) could not be read this pass, so ${unreadableDirs.length} ` +
+      `file(s) under them are being left alone rather than reported deleted. ` +
+      `Sample: ${failedDirs.slice(0, 3).join(", ")}`));
   }
 
   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, expectedGitId: gitId });
+    // 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 +467,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 +475,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,21 +494,189 @@ 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).
+  // expectedGitId: this whole pass computed hashes for `gitId`. If a takeover or discard re-pointed the
+  // folder while it ran, these describe a repo it is no longer registered against and must be dropped.
+  if (!watchState.mergeFileHashes(targetDir, {
+    set: currentHashes,
+    remove: [...actuallyDeleted, ...gitignoreDropped],
+    patch: { lastSyncedAt: new Date().toISOString() },
+    expectedGitId: gitId,
+  })) {
+    console.log(color.dim("  Folder was re-pointed during this sync — its results were not recorded."));
+  }
   console.log(`  ${color.green("✓")} Delta sync complete.`);
+  return { failures };
   } finally {
     syncInFlight.delete(inFlightKey);
   }
 }
 
+/** Queue one vanished path and (re)start this folder's settle timer. */
+function queueDelete(targetDir, relativePath, settleMs = DELETE_SETTLE_MS) {
+  const key = path.resolve(targetDir);
+  let entry = pendingDeletes.get(key);
+  if (!entry) {
+    entry = { paths: new Set(), timer: null };
+    pendingDeletes.set(key, entry);
+  }
+  entry.paths.add(relativePath);
+  // Reset, never extend-if-absent: while files keep vanishing the operation is still running, and
+  // nothing in the queue should be believed until it stops.
+  if (entry.timer) clearTimeout(entry.timer);
+  entry.timer = setTimeout(() => {
+    flushPendingDeletes(targetDir).catch(err =>
+      console.error(color.red(`  Delete flush failed for ${targetDir}: ${err.message}`)));
+  }, settleMs);
+  if (entry.timer.unref) entry.timer.unref(); // must never hold the daemon open
+}
+
+/**
+ * The folder has gone quiet. Look again at everything queued: send the deletes that are still real,
+ * and forget the ones that came back.
+ *
+ * A file that returned is left ALONE rather than re-uploaded here. Its baseline entry was never
+ * removed (we never sent the delete), so if the bytes changed, git's own write fires a change event
+ * that takes the normal upload path, and the 60-second backstop re-scan covers a coalesced event.
+ * Duplicating the upload path here would mean duplicating its gitignore and secret checks too.
+ */
+async function flushPendingDeletes(targetDir) {
+  const key = path.resolve(targetDir);
+  const entry = pendingDeletes.get(key);
+  if (!entry) return;
+  pendingDeletes.delete(key);
+  if (entry.timer) clearTimeout(entry.timer);
+
+  // Re-read state at flush time: a `niro takeover` or `niro release` during the settle window changes
+  // (or removes) the gitId these deletes were queued against.
+  const fresh = watchState.get(targetDir, api.currentBaseUrl());
+  if (!fresh || !fresh.gitId) return;
+  if (notHolding.has(key)) return;
+
+  const stillGone = [];
+  const returned = [];
+  for (const rp of entry.paths) {
+    if (fs.existsSync(path.join(targetDir, rp))) returned.push(rp);
+    else stillGone.push(rp);
+  }
+
+  if (returned.length > 0) {
+    console.log(color.dim(
+      `  ${returned.length} file(s) reappeared while settling — not deleted` +
+      (returned.length <= 3 ? `: ${returned.join(", ")}` : "")));
+  }
+
+  for (const rp of stillGone) {
+    try {
+      await agentApi.deleteFile(fresh.gitId, rp);
+      watchState.mergeFileHashes(targetDir, {
+        remove: [rp],
+        patch: { lastSyncedAt: new Date().toISOString() },
+        expectedGitId: fresh.gitId,
+      });
+      console.log(`  ${color.yellow("−")} ${rp}`);
+    } catch (err) {
+      // Keep the baseline entry so a later pass retries. Dropping it here is how a refused delete
+      // became permanent (see fb3ff0a).
+      console.error(color.red(`  Failed to delete ${rp}: ${err.message}`));
+    }
+  }
+}
+
+
+/**
+ * One backstop pass for a folder. Extracted from the interval so the backoff gate at the top can
+ * actually be exercised — adversarial review found the gate could be deleted with the whole suite
+ * still green, because the only thing that called it was a timer no test drives.
+ */
+function backstopTick(targetDir) {
+    const fresh = watchState.get(targetDir, api.currentBaseUrl());
+    if (!fresh || !fresh.gitId) return; // folder released — nothing to sync
+    // 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.`));
+      });
+}
+
 async function handleFileEvent(gitId, targetDir, relativePath, state) {
   // Re-read this folder's current state on every event instead of trusting the value
   // captured when the daemon started. A mid-session `niro takeover` re-points the folder
@@ -335,6 +684,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.
@@ -386,25 +739,29 @@ async function handleFileEvent(gitId, targetDir, relativePath, state) {
 
   const absPath = path.join(targetDir, relativePath);
 
+  // Symmetry: if we would never UPLOAD this path, we must never ask the server to DELETE it. The
+  // accept-set check used to sit below the delete branch, so an editor's scratch file — never sent
+  // to us in the first place — still produced a delete call for a path the server had never heard
+  // of. That is 21% of all file events in the customer's log (3,226 of 15,223), every one of them a
+  // wasted round trip, a wasted journal record, and a count against the server's delete-burst budget
+  // that could trip the guard on churn alone.
+  //
+  // Safe because uploadability is decided by the filename, which does not change for a given path:
+  // if it is not uploadable now it was never uploaded. A file the accept set USED to include is
+  // still reachable by the backstop re-scan, which works from the stored baseline rather than from
+  // live events.
+  if (!folderSync.isUploadableName(relativePath)) return;
+
   if (!fs.existsSync(absPath)) {
-    // 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() });
-      console.log(`  ${color.yellow("−")} ${relativePath}`);
-    } catch (err) {
-      console.error(color.red(`  Failed to delete ${relativePath}: ${err.message}`));
-    }
+    // Gone RIGHT NOW is not the same as deleted. Queue it and look again once the folder is quiet.
+    queueDelete(targetDir, relativePath);
     return;
   }
 
-  // Only upload files in the accept set (source / structural / committed config).
-  // matchesPatterns can pass anything when the server-supplied includePatterns are
-  // empty; this keeps the per-file event from uploading stray files (e.g. a *.txt
-  // that could carry secrets), matching what the manifest walk would offer.
-  if (!folderSync.isUploadableName(relativePath)) return;
+  // It exists, so any queued delete for it was a transient gap (a rewrite, not a removal). Drop it
+  // immediately rather than waiting for the settle timer to work it out.
+  const pending = pendingDeletes.get(path.resolve(targetDir));
+  if (pending) pending.paths.delete(relativePath);
 
   // File changed or created
   const newHash = watchState.hashFile(absPath);
@@ -422,8 +779,11 @@ 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() },
+      expectedGitId: gitId,
+    });
     console.log(`  ${color.green("+")} ${relativePath}`);
   } catch (err) {
     console.error(color.red(`  Failed to sync ${relativePath}: ${err.message}`));
@@ -435,6 +795,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));
@@ -454,12 +821,27 @@ function minimatch(filePath, pattern) {
 }
 
 /** Walk the directory respecting stored patterns to find all currently included files. */
+/**
+ * @returns {{files: string[], failedDirs: string[]}} — `failedDirs` holds the repo-relative directories
+ * the walk could NOT read ("" means the repo root itself). A caller must treat those as UNKNOWN, never
+ * as empty: a directory that cannot be listed looks exactly like a directory whose files were all
+ * deleted, and acting on that difference is how a whole project gets wiped.
+ */
 function buildMinimalManifest(rootDir, includePatterns, excludePatterns) {
   const results = [];
+  const failedDirs = [];
 
   function walk(dir) {
     let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // Swallowing this was the defect. The walk returned a SHORT list with no signal, the caller read
+      // "absent from the walk" as "deleted", and every file under here was reported gone. Renaming a
+      // watched folder emptied the whole manifest and deleted the entire project server-side.
+      failedDirs.push(path.relative(rootDir, dir).replace(/\\/g, "/"));
+      return;
+    }
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name);
       const relativePath = path.relative(rootDir, fullPath).replace(/\\/g, "/");
@@ -490,9 +872,12 @@ function buildMinimalManifest(rootDir, includePatterns, excludePatterns) {
     }
   }
   walk(rootDir);
-  return results;
+  return { files: results, failedDirs };
 }
 
 // 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,
+  queueDelete, flushPendingDeletes, pendingDeletes, DELETE_SETTLE_MS, backstopTick, notHolding,
+  unreadableRoots,
+  nextBackoffMs, shouldAttemptBackstop, recordBackstopFailure, recordBackstopSuccess };