@niroai/niro 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,93 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
+## 0.9.0 — 2026-08-26
+
+One change to how the client waits, and two fixes for cases where Niro and your machine
+disagreed about what still exists.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.8.0. Against an older server the waiting change simply does not
+engage, because the client decides from the server's answer rather than from a version.
+
+**Creating a working copy no longer times out.** It takes 44 to 60 seconds, and it used to run
+inside a single request, against a gateway that gives up at 60. Three at once on 26 August all
+came back as gateway error pages, and because such an error says nothing about whether the work
+finished, the real cause underneath went unread for an afternoon. The client now asks the server
+to do it in the background and waits for it to finish, showing progress. A dropped connection
+while waiting is not treated as a failure, because the copy is still being made on the server; an
+expired login is, because waiting cannot fix it.
+
+**Discarding a working copy the server had already deleted.** A working copy can go away
+without your machine being told: someone deletes it in the web UI, or the server reaps it
+after it has sat idle for two weeks. The folder on your machine kept a registration pointing
+at it, and `niro discard-temp-project`, which is what clears that registration, failed before
+it got that far. The registration is also what makes `niro new-temp-project` in a second
+worktree refuse, advising you to run discard in the other folder, so the advice named the one
+command that could not work. Discard now treats a project the server says is missing as
+nothing left to delete: it skips the server call and does the local half, pointing the folder
+back at the original project. A server it could not reach, or one that refuses because the
+copy belongs to another developer, still fails loudly and changes nothing, which matters
+because the server answers both of those with the same status code as a deleted project.
+
+**A detached checkout stopped Niro answering.** During `git bisect`, or after checking out a
+tag, your repo is on no branch. `git rev-parse --abbrev-ref HEAD` does not fail there, it
+prints the word `HEAD`, and Niro passed that on as though it were a branch name. Nothing
+indexes a branch called `HEAD`, so the server treated every such question as coming from a
+diverged branch and declined to answer it, for the whole bisect. Niro now reports no branch,
+which is what the server already had a rule for, and answers from the indexed project.
+
+## 0.8.0 — 2026-08-26
+
+Needed before a server has the layered store turned on. On an older client the new
+server-side setting is not just unusable, it is misleading.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.7.0.
+
+### Why this release exists
+
+A working copy is a private index of the branch in your folder, including edits you have not
+committed. The server can now keep several of them per developer, and can store one as a
+layer over the shared project rather than a full copy. Three things in 0.7.0 get in the way.
+
+**A second working copy was refused on your own machine.** 0.7.0 decided by itself that one
+folder already held the project, and never asked the server. Once the server allows several,
+that refusal is simply wrong. Worse, run unattended, by an agent or a script, it threw an
+error advising `niro discard-temp-project` in the other folder. Following that advice
+destroys a working copy that did not need destroying. The client now asks the server and
+does what it says.
+
+**A git worktree of a repo with no remote could not be onboarded at all.** Niro records
+onboarding against the folder that was onboarded, which is the main checkout. A linked
+worktree has no entry of its own, so the repo could not be named and `niro new-temp-project`
+failed. It now resolves the main working tree through `git rev-parse --git-common-dir`.
+That combination, a worktree of a remote-less repo, is the layered store's main use case.
+
+**Large files were dropped from a working copy without telling you.** The size warning
+existed only in `niro init`. A developer ran `niro new-temp-project` and lost their three
+largest source files, the ones the whole branch was about. Niro then answered questions
+about those files from the shared project's older copy, confidently, with nothing on screen
+to say the working copy did not contain them. The warning now runs on both commands, and it
+quotes the limit the server reports rather than a number compiled into the client, which
+said 256 KiB while a server raised to 2 MiB was accepting the file happily.
+
+### Compatibility
+
+Against an older server, the per-file limit is not reported and the client falls back to its
+built-in figure, so the warning quotes an estimate rather than the server's real cap. Nothing
+else changes.
+
 ## 0.7.0 — 2026-08-17
 
 A data-loss release. If you use `niro watch`, upgrade.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.7.0",
+  "version": "0.9.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

@@ -174,6 +174,7 @@ async function addRepo(pathArg, opts = {}) {
   // Get filter recommendation
   console.log(`  Analyzing project structure...`);
   const filterResult = await agentApi.filterManifest(gitId, manifest);
+  folderSync.warnOversizeFiles(manifest, filterResult, (m) => console.log(color.yellow(m)));
   const includedCount = filterResult.included_count || filterResult.includedCount || 0;
   const excludedCount = filterResult.excluded_count || filterResult.excludedCount || 0;
 

package/src/commands/init.js

@@ -422,16 +422,9 @@ async function init(pathArg, opts = {}) {
     process.stdout.write(`\n  Scanning ${color.cyan(targetDir)}...`);
     const manifest = folderSync.buildManifest(targetDir);
     process.stdout.write(` ${manifest.length} files found.\n`);
-    for (const m of manifest) {
-      if (m.size_bytes > folderSync.PER_FILE_CAP_BYTES) {
-        console.log(warn(
-          `       ⚠ ${m.path} (${Math.round(m.size_bytes / 1024)} KiB) exceeds the ` +
-          `256 KiB per-file cap — it will be skipped and not indexed.`
-        ));
-      }
-    }
-
     const filterResult = await agentApi.filterManifest(gitId, manifest);
+    // After the filter, not before: the limit is the SERVER's, and it reports it back to us.
+    folderSync.warnOversizeFiles(manifest, filterResult, (m) => console.log(warn(m)));
     const includedPaths = filterResult.included_paths || filterResult.includedPaths || [];
     const includedCount = filterResult.included_count || filterResult.includedCount || includedPaths.length;
     const excludedCount = filterResult.excluded_count || filterResult.excludedCount || 0;

package/src/commands/release.js

@@ -22,6 +22,7 @@ const git = require("../lib/git");
 const niroProjectFile = require("../lib/niroProjectFile");
 const prompt = require("../lib/prompt");
 const watchState = require("../lib/watchState");
+const tempProject = require("../lib/tempProject");
 
 const ok = (s) => color.green(s);
 const warn = (s) => color.yellow(s);
@@ -56,26 +57,80 @@ async function release(pathArg, opts = {}) {
         "`niro discard-temp-project --project <temp-project-id>`. The server refuses to delete anything " +
         "that is not a temporary project, so this is always safe.");
   }
-  const project = await api.get(`/api/projects/${encodeURIComponent(tempProjectId)}`);
-  const cloneOf = project.clone_of_project_id || project.cloneOfProjectId;
-  if (!cloneOf) {
-    throw new Error(`Project ${tempProjectId} is not a temporary project — refusing. ` +
-        "(discard only deletes projects created by `niro new-temp-project`)");
+  // The temporary project may ALREADY be gone from the server, and nothing tells this machine when
+  // that happens: the idle sweeper reaps it after N days, and deleting it in the UI goes down the
+  // ordinary project-delete path. This fetch used to throw on that, BEFORE any local cleanup ran, so
+  // the folder kept a registration pointing at a project that no longer exists — and the only advice
+  // anything offered ("run `niro discard-temp-project` in that folder first") named this very command,
+  // which then failed the same way. A definitive not-found means there is nothing left to delete, so
+  // skip the server half and do the local half, which is the half that was still needed.
+  let project = null;
+  let cloneOf = null;
+  let alreadyGone = false;
+  try {
+    project = await api.get(`/api/projects/${encodeURIComponent(tempProjectId)}`);
+  } catch (err) {
+    // Only a definitive "no such project" counts. A network blip, a 401, a 500 or a genuine
+    // permissions refusal must still fail loudly — rewriting local registrations because the server
+    // could not be reached is exactly the mistake this command exists to undo.
+    if (!tempProject.isProjectNotFound(err)) throw err;
+    alreadyGone = true;
+  }
+  if (alreadyGone && !opts.project && !(entry && entry.takeover)) {
+    // The id did not come from a takeover backup or from the user — it came from a `.niro-project`
+    // pin that happens to name a missing project. Nothing here says this folder was ever taken over,
+    // so there is no warrant to touch its registration.
+    throw new Error(`Project ${tempProjectId} does not exist on this backend, and nothing on this ` +
+        "machine records a temporary project for this folder — refusing to change anything. " +
+        "If you know the temporary project's id, pass it explicitly: " +
+        "`niro discard-temp-project --project <temp-project-id>`.");
+  }
+  if (!alreadyGone) {
+    cloneOf = project.clone_of_project_id || project.cloneOfProjectId;
+    if (!cloneOf) {
+      throw new Error(`Project ${tempProjectId} is not a temporary project — refusing. ` +
+          "(discard only deletes projects created by `niro new-temp-project`)");
+    }
   }
 
   // Every folder registered against this temp project (multi-repo takeover, ADR-016).
   const currentDir = path.resolve(targetDir);
-  const folders = watchState.allLocal(baseUrl).filter((e) => e.projectId === tempProjectId);
+  let folders = watchState.allLocal(baseUrl).filter((e) => e.projectId === tempProjectId);
   if (!folders.some((e) => path.resolve(e.folderPath) === currentDir)) {
     folders.push({ folderPath: targetDir, ...(entry || {}) });
   }
+  if (alreadyGone) {
+    // Two corrections that only matter once the server is no longer there to check the id against.
+    //
+    // Drop any folder not actually registered against THIS project. The line above adds the current
+    // folder unconditionally, which is right when the id came from that folder, and wrong when it came
+    // from `--project`: a mistyped or already-discarded id, run from a folder holding a DIFFERENT live
+    // working copy, would rewrite that copy's registration and report it as cleaned up. On the alive
+    // path the server's own answer bounds the damage; here nothing does.
+    folders = folders.filter((e) => e.projectId === tempProjectId);
+    // Then recover the source project from whichever folder recorded it. Every folder in one working
+    // copy is a clone of the SAME source project (ADR-016 extends a copy with more repos, it never
+    // spans two sources), so any one backup answers for all of them — including a sibling that has no
+    // backup of its own, which would otherwise be left pointing at the deleted project while the alive
+    // path restores it from `clone_of_project_id`.
+    const witness = folders.find((e) => e.takeover && e.takeover.sourceProjectId);
+    if (!witness) {
+      throw new Error(`Project ${tempProjectId} does not exist on this backend, and no folder on this ` +
+          "machine records which project it was a working copy of — refusing to guess. " +
+          "Nothing has been changed.");
+    }
+    cloneOf = witness.takeover.sourceProjectId;
+  }
 
   // ADR-018 discard guard: deleting the temp project kills coverage for EVERY repo in it. Check each
   // folder's CURRENT branch against its recorded source branch; a folder still on a feature branch is
   // in-flight work whose coverage this discard would destroy. Old entries without sourceBranch can't be
   // verified client-side (the server-side nudge guard still covers the agent-driven path).
+  // Skipped when the copy is already gone: this guard exists to warn BEFORE destroying coverage, and
+  // there is no coverage left to destroy. Leaving it on would ask the developer to confirm losing
+  // something they have already lost, and then refuse non-interactively over it.
   const stillDiverged = [];
-  for (const e of folders) {
+  for (const e of alreadyGone ? [] : folders) {
     const sourceBranch = e.takeover && e.takeover.sourceBranch;
     if (!sourceBranch || !fs.existsSync(e.folderPath)) continue;
     try {
@@ -103,7 +158,7 @@ async function release(pathArg, opts = {}) {
         return;
       }
     }
-  } else if (process.stdout.isTTY && !opts.yes) {
+  } else if (!alreadyGone && process.stdout.isTTY && !opts.yes) {
     const sure = await prompt.confirm(
       `Discard temporary project ${color.bold(project.alias || tempProjectId)}?`);
     if (!sure) {
@@ -112,7 +167,9 @@ async function release(pathArg, opts = {}) {
     }
   }
 
-  await api.post(`/api/projects/${encodeURIComponent(tempProjectId)}/clone/release`, {});
+  if (!alreadyGone) {
+    await api.post(`/api/projects/${encodeURIComponent(tempProjectId)}/clone/release`, {});
+  }
 
   // Restore each folder's local registration. ADR-018: the .niro-project file is left ALONE unless it
   // still carries the OLD-STYLE swapped pin (pre-ADR-018 takeover) — then it points at a now-deleted
@@ -175,7 +232,16 @@ async function release(pathArg, opts = {}) {
     }
   }
 
-  console.log(`\n  ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
+  if (alreadyGone) {
+    console.log(`\n  ${ok("✓")} Temporary project ${color.bold(tempProjectId)} was already gone from the server` +
+        color.dim(" (deleted from the UI, or reaped after sitting idle)."));
+    console.log(repinned.length
+      ? `  ${ok("✓")} Cleaned up ${repinned.length} local registration(s) that still pointed at it. ` +
+        "Niro routes back to the original project automatically."
+      : `  ${ok("✓")} Nothing left to clean up locally.`);
+  } else {
+    console.log(`\n  ${ok("✓")} Temporary project discarded. Niro routes back to the original project automatically.`);
+  }
   if (healed.length) {
     console.log(color.dim("  Healed old-style pins:"));
     for (const h of healed) console.log(color.dim(`    ${h.folder} → ${h.to}`));

package/src/commands/takeover.js

@@ -22,6 +22,7 @@ const git = require("../lib/git");
 const prompt = require("../lib/prompt");
 const watchState = require("../lib/watchState");
 const resolveCtxLib = require("../lib/resolveContext");
+const spinner = require("../lib/spinner");
 
 const ok = (s) => color.green(s);
 const warn = (s) => color.yellow(s);
@@ -48,7 +49,18 @@ async function takeover(pathArg, opts = {}) {
   const ctx = await resolveCtxLib.resolveContext(targetDir, { apiUrl: opts.apiUrl });
   if (ctx.state === "error") throw new Error(`Could not resolve project: ${ctx.error}`);
   if (!ctx.projects.length) {
-    throw new Error("This folder's git remote doesn't match any Niro project. Run `niro init` first.");
+    // Two different dead ends, and telling them apart is the difference between a fix and a guess.
+    // A folder with no git remote is not a broken setup: `niro init` never required one. What is
+    // missing is the LOCAL record naming the repo, and for a git worktree that record belongs to the
+    // main checkout, not to the folder you are standing in. The old message sent every such user off
+    // to add a remote, which does not help: the repo keeps the URL it was registered with.
+    if (ctx.state === "no_origin") {
+      throw new Error(
+        "This folder has no git remote, and no Niro repo is recorded for it on this machine. "
+        + "Run `niro init` here, or, if this is a git worktree, run it once in the main checkout, "
+        + "then re-run this command.");
+    }
+    throw new Error("This folder's git remote does not match any Niro project. Run `niro init` first.");
   }
   let source = ctx.projects[0];
   if (opts.project) {
@@ -83,8 +95,29 @@ async function takeover(pathArg, opts = {}) {
   // 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) =>
+  // Matched on the REPO as well as the project, and that second clause is the whole point.
+  //
+  // The hazard this guard exists for is one REPO checked out in two folders on two branches, both
+  // uploading into one copy until every answer is a blend of the two. Matching on the project alone
+  // also caught the case immediately below this block: a DIFFERENT repo of the same project, which is
+  // the multi-repo extend the very next call performs on purpose (ADR-016).
+  //
+  // So a developer whose change spans ai-orchestrator and ai-assistant was told their project's copy
+  // was "already held by another folder" and asked to take it away from themselves, when the server
+  // would have happily added the second repo to the same copy. Verified 2026-08-22.
+  //
+  // It stands down only when it can PROVE the other folder holds a different repo. An entry written
+  // before sourceGitId existed records no repo at all, and for those the honest answer is "cannot
+  // tell", which has to mean warn: skipping on an unknown would quietly remove the guard for exactly
+  // the older entries most likely to have been left behind. Two tests cover that case.
+  // ...and it does not apply at all when the server allows several copies per developer. The hazard
+  // named above is two folders uploading into ONE copy; when each folder gets its own, there is no
+  // blending to prevent. Refusing anyway is what made LAYERED_STORE_MULTIPLE_WORKTREES_PER_DEVELOPER
+  // unreachable: the server answers `multiple_worktrees_allowed: true` on every resolve and the CLI
+  // refused the second worktree regardless.
+  const holder = ctx.multipleWorktreesAllowed ? null : watchState.allLocal(api.currentBaseUrl()).find((e) =>
     e.takeover && e.takeover.sourceProjectId === source.project_id
+    && (e.takeover.sourceGitId == null || e.takeover.sourceGitId === source.git_id)
     && path.resolve(e.folderPath) !== here);
   if (holder) {
     const onBranch = holder.branch ? ` on branch \`${holder.branch}\`` : "";
@@ -114,9 +147,7 @@ async function takeover(pathArg, opts = {}) {
   // 2. Create-or-extend server-side (ADR-016). If you already have a temporary project of this project,
   // the backend EXTENDS it — adds this repo to the same copy — instead of minting a second one, so
   // cross-repo answers stay coherent. Either way this folder's repo becomes AGENT_UPLOAD.
-  const outcome = await api.post(
-    `/api/projects/${encodeURIComponent(source.project_id)}/clone`,
-    { local_git_ids: [source.git_id], branch });
+  const outcome = await requestClone(source.project_id, source.git_id, branch);
   const newProjectId = outcome.new_project_id || outcome.newProjectId;
   const gitIdMap = outcome.git_id_map || outcome.gitIdMap || {};
   const newGitId = gitIdMap[source.git_id];
@@ -154,6 +185,9 @@ async function takeover(pathArg, opts = {}) {
     const manifest = folderSync.buildManifest(repoRoot);
     const filterResult = await agentApi.filterManifest(newGitId, manifest);
     const includedPaths = filterResult.included_paths || filterResult.includedPaths || [];
+    // The gap that cost a day: this command had no oversize warning at all, so a working copy
+    // silently omitted the three largest source files in the repo.
+    folderSync.warnOversizeFiles(manifest, filterResult, (m) => console.log(warn(m)));
     const sizes = {};
     for (const m of manifest) sizes[m.path] = m.size_bytes;
     console.log(`  ${step("●")}  Uploading working tree: ${includedPaths.length} files ` +
@@ -238,4 +272,87 @@ async function takeover(pathArg, opts = {}) {
   console.log(color.dim("  routing falls back to the original project by itself."));
 }
 
-module.exports = { takeover };
+
+/**
+ * Ask the server for a working copy, and wait for it without holding the request open.
+ *
+ * WHY. The copy takes 44 to 60 seconds. It used to run inside the POST, and the gateway in front of
+ * the server gives up at 60, so three requests at once on 2026-08-26 all came back as HTML 504 pages.
+ * A 504 also says nothing about whether the work finished: the real error underneath, a duplicate key
+ * from a migration that had not been run, went unread for an afternoon because of it.
+ *
+ * WORKS AGAINST BOTH SERVERS, and that is why it branches on the RESPONSE rather than on a version.
+ * A server that understands `async` returns 202 and a job id to poll. An older one ignores the unknown
+ * field and returns the outcome inline exactly as before, which is the shape this already handled. So
+ * there is no capability check to keep in step, and no flag day.
+ */
+async function requestClone(projectId, gitId, branch, opts = {}) {
+  const started = await api.post(
+    `/api/projects/${encodeURIComponent(projectId)}/clone`,
+    { local_git_ids: [gitId], branch, async: true });
+
+  const jobId = started && (started.job_id || started.jobId);
+  if (!jobId) {
+    return started; // older server: it did the work inline and this IS the outcome
+  }
+
+  // Poll until it finishes. The interval is deliberately not tight: nothing is waiting on the answer
+  // faster than a person reads, and a shorter one only adds load to the server doing the copy.
+  // A seam, not a knob: tests pass a small value so they do not sit through real polls.
+  const POLL_MS = opts.pollMs || 2000;
+  const GIVE_UP_MS = opts.giveUpMs || 15 * 60 * 1000;
+  const startedAt = Date.now();
+  const deadline = startedAt + GIVE_UP_MS;
+  const sp = spinner.start("Building your temporary project...");
+  try {
+    for (;;) {
+      await sleep(POLL_MS);
+      let job;
+      try {
+        job = await api.get(`/api/projects/clone/job/${encodeURIComponent(jobId)}`);
+      } catch (e) {
+        // A blip while polling is not a failed clone. The copy is running on the server regardless of
+        // whether this one request reached it, so keep waiting rather than reporting a failure that
+        // has not happened. A 404 is different: the job is gone, and waiting cannot bring it back.
+        // Waiting cannot fix an expired token or a revoked account, and 15 minutes of silent retrying
+        // before finally reporting it is worse than saying so at once.
+        if (e && (e.status === 401 || e.status === 403)) {
+          throw e;
+        }
+        if (e && e.status === 404) {
+          throw new Error(
+            `The server has no record of clone job ${jobId}. It may have expired, or the server was `
+            + "restarted mid-copy. Run `niro new-temp-project` again.");
+        }
+        if (Date.now() > deadline) throw e;
+        continue;
+      }
+      const state = job && job.state;
+      if (state === "SUCCEEDED") {
+        sp.stop();
+        return job.outcome;
+      }
+      if (state === "FAILED") {
+        sp.stop();
+        throw new Error(job.error || "The server could not create the temporary project.");
+      }
+      if (Date.now() > deadline) {
+        sp.stop();
+        throw new Error(
+          `Still building after ${Math.round(GIVE_UP_MS / 60000)} minutes. The server may still finish; `
+          + `check with \`niro status\` before running this again.`);
+      }
+      // Deliberately NOT re-labelled with the elapsed time. Without a TTY the spinner prints a fresh
+      // line every time the label CHANGES, so putting the seconds in it produced one line per poll:
+      // measured at 10 lines in 11 seconds. The spinner already shows elapsed time where it can.
+    }
+  } finally {
+    sp.stop();
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { takeover, requestClone};

package/src/lib/folderSync.js

@@ -126,8 +126,9 @@ const IGNORED_DIRS = new Set([
   "dist", ".venv", "vendor", ".idea", ".gradle", "out",
 ]);
 
-// Server-side per-file cap (256 KiB). Oversize files are skipped server-side at
-// /filter; we surface them as a warning so missing source is never silent.
+// Fallback only, for a server too old to report its own limit. The real limit comes back from
+// /filter as max_file_size_bytes, because a duplicated number is wrong the moment either side is
+// configured: this constant said 256 KiB while a server raised to 2 MiB took the file happily.
 const PER_FILE_CAP_BYTES = 262144;
 
 const DEFAULT_CONCURRENCY = 4;
@@ -482,6 +483,46 @@ async function doInitialSync(gitId, targetDir, includedPaths, { sizes } = {}) {
   return hashes;
 }
 
+
+/**
+ * Tell the developer which files the server is going to drop for being too large.
+ *
+ * <p>This is not cosmetic. `niro new-temp-project` silently dropped a developer's three largest source
+ * files -- the ones the whole branch was about -- because the warning lived only in `niro init`. Niro
+ * then answered questions about those files from the shared project's older copy, confidently, with
+ * nothing on screen to say the working copy did not contain them.
+ *
+ * Uses the limit the SERVER reports, so it cannot drift from what the server actually did. Falls back
+ * to the built-in constant only when talking to a server too old to report one.
+ *
+ * Cross-referenced against excluded_paths where the server sends it, so a file dropped for some other
+ * reason (a doc, a lockfile, a property file) is not blamed on its size.
+ *
+ * @returns the number of files warned about
+ */
+function warnOversizeFiles(manifest, filterResult, log) {
+  const cap = Number(filterResult.max_file_size_bytes || filterResult.maxFileSizeBytes) || PER_FILE_CAP_BYTES;
+  // Over the limit AND a file that would otherwise have been indexed. The second half is what keeps
+  // this honest: a 900 KiB markdown file is over the limit too, but it was never going to be indexed,
+  // so blaming its size teaches the reader to ignore the warning.
+  //
+  // Deliberately NOT cross-referenced against excluded_paths, though that was the first attempt. It
+  // reads as the more precise test and is strictly worse: a file the server never saw is absent from
+  // that list, so a 3 MB source file went unwarned in testing. Size plus type needs no agreement
+  // between two lists to be right.
+  const hits = (manifest || []).filter((m) =>
+    m.size_bytes > cap && isUploadableName(m.path.split("/").pop()));
+  for (const m of hits) {
+    log(`       \u26a0 ${m.path} (${Math.round(m.size_bytes / 1024)} KiB) is over this server's `
+      + `${Math.round(cap / 1024)} KiB per-file limit \u2014 it will NOT be indexed.`);
+  }
+  if (hits.length) {
+    log(`       ${hits.length} file(s) will be missing from this project. Niro will answer about them `
+      + "from whatever version it already has, if any.");
+  }
+  return hits.length;
+}
+
 module.exports = {
   buildManifest,
   walkDir,
@@ -500,4 +541,5 @@ module.exports = {
   IGNORED_DIRS,
   BATCH_SIZE,
   PER_FILE_CAP_BYTES,
+  warnOversizeFiles,
 };

package/src/lib/git.js

@@ -7,6 +7,25 @@ const fs = require("fs");
 const path = require("path");
 const { execSync } = require("child_process");
 
+/**
+ * The branch name from `git rev-parse --abbrev-ref HEAD`, or null when there is no branch.
+ *
+ * On a detached HEAD (a bisect, a tag checkout, a plain commit checkout) that command does not
+ * fail — it prints the literal string "HEAD". A caller that trusts it verbatim therefore reports a
+ * branch named "HEAD", which no repository has, and everything downstream reads the checkout as
+ * being on an unknown branch rather than on no branch at all.
+ *
+ * `inspect` below has always collapsed that to null, matching what the `.git/HEAD` file read
+ * returns. This is that one rule, shared, so a second caller cannot drift from it. One already had:
+ * the MCP bridge sent "HEAD" straight through, so the server's routing ladder took every detached
+ * checkout for a diverged branch and refused to answer it, even though the ladder has an explicit
+ * guard meant to route exactly that case to the indexed project.
+ */
+function normalizeBranch(raw) {
+  const b = typeof raw === "string" ? raw.trim() : "";
+  return b && b !== "HEAD" ? b : null;
+}
+
 function findGitDir(startDir) {
   let dir = path.resolve(startDir);
   const root = path.parse(dir).root;
@@ -93,12 +112,33 @@ function inspect(startDir) {
   // unavailable the calls return null and behaviour is identical to before.
   if (originUrl === null) originUrl = redactRemoteCreds(gitOut("git remote get-url origin", found.repoRoot));
   if (branch === null) {
-    const b = gitOut("git rev-parse --abbrev-ref HEAD", found.repoRoot);
-    branch = b && b !== "HEAD" ? b : null; // "HEAD" = detached; keep null like the file read
+    branch = normalizeBranch(gitOut("git rev-parse --abbrev-ref HEAD", found.repoRoot));
   }
   return { repoRoot: found.repoRoot, originUrl, branch };
 }
 
+/**
+ * The root of the MAIN working tree for `repoRoot`.
+ *
+ * A linked worktree (`git worktree add`) is its own folder on its own branch, but Niro onboarding is
+ * recorded against the folder that was actually onboarded, which is the main checkout. Without this a
+ * worktree has NO local identity: nothing in ~/.niro/projects.json is keyed by its path, so the repo it
+ * belongs to cannot be named at all. That is why `niro new-temp-project` could not be run from a
+ * worktree of a repo with no git remote, which is the layered store's main use case.
+ *
+ * Falls back to `repoRoot` itself when this IS the main working tree, when git cannot answer, or when
+ * the common dir is not the usual `<root>/.git` (a bare repo, or an unusual layout). That fallback is
+ * the behaviour that existed before this function, so it can only add an answer, never change one.
+ */
+function mainWorktreeRoot(repoRoot) {
+  if (!repoRoot) return null;
+  const common = gitOut("git rev-parse --git-common-dir", repoRoot);
+  if (!common) return repoRoot;
+  const abs = path.resolve(repoRoot, common);
+  if (path.basename(abs) !== ".git") return repoRoot;
+  return path.dirname(abs);
+}
+
 /**
  * Run ONE `git check-ignore --stdin` in `repoRoot` and report BOTH the matched
  * paths AND whether the check itself succeeded. Paths must be POSIX-relative to
@@ -187,4 +227,5 @@ function isTracked(repoRoot, relativePath) {
   }
 }
 
-module.exports = { inspect, deriveRepoName, checkIgnored, checkIgnoredPaths, redactRemoteCreds, isTracked };
+module.exports = { inspect, mainWorktreeRoot, deriveRepoName, checkIgnored, checkIgnoredPaths,
+  redactRemoteCreds, isTracked, normalizeBranch };

package/src/lib/resolveContext.js

@@ -27,9 +27,17 @@
  *
  * Never logs secrets. Resolution failures degrade gracefully (state: "error")
  * rather than throwing, so callers/agents can branch on `state`.
+ *
+ * A git URL is not an identity every repo has. `niro init` on a folder with no remote registers it
+ * with a synthetic `local://<name>` URL (see init.js / add-repo.js) that this module never sends back,
+ * and a folder that gains a remote AFTER onboarding keeps the URL it had at the time. Either way the
+ * URL join can never match, so when it comes back empty this falls back to the repo id recorded for
+ * the folder locally, and asks the server by that instead. See resolveByLocalGitId below.
  */
+const path = require("path");
 const git = require("./git");
 const api = require("./api");
+const watchState = require("./watchState");
 
 async function resolveContext(startPath = process.cwd(), opts = {}) {
   const { repoRoot, originUrl, branch } = git.inspect(startPath);
@@ -39,7 +47,11 @@ async function resolveContext(startPath = process.cwd(), opts = {}) {
   }
 
   if (!originUrl) {
-    return { gitRoot: repoRoot, repoUrl: null, branch: branch || null, state: "no_origin", projects: [] };
+    // No remote to ask about, but the folder may still be a repo Niro knows: onboarding does not
+    // require one. Try the local identity before giving up.
+    return resolveByLocalGitId(repoRoot, branch, opts, {
+      gitRoot: repoRoot, repoUrl: null, branch: branch || null, state: "no_origin", projects: [],
+    });
   }
 
   // Omit branch when null (detached HEAD) -> URL-only resolve. Do NOT normalize
@@ -62,13 +74,83 @@ async function resolveContext(startPath = process.cwd(), opts = {}) {
   }
 
   const projects = normalizeProjects(data);
-  return {
+  const byUrl = {
     gitRoot: repoRoot,
     repoUrl: originUrl,
     branch: branch || null,
     state: projects.length ? "resolved" : "unresolved",
     projects,
+    // Whether THIS server lets a developer hold more than one working copy of a project. It is a
+    // property of the server's configuration, not of the match, and it was being dropped here: the
+    // payload carries it on every resolve precisely so the CLI can stop applying a limit the server
+    // no longer enforces, and nothing in the CLI read it. The effect was that the server-side
+    // multi-worktree support could not be reached from any client.
+    multipleWorktreesAllowed: !!(data && data.multiple_worktrees_allowed),
   };
+  if (projects.length) return byUrl;
+  // The remote matched nothing. That is the normal answer for a folder onboarded before it had this
+  // remote, whose stored URL is the `local://` form. Same fallback as the no-origin case.
+  return resolveByLocalGitId(repoRoot, branch, opts, byUrl);
+}
+
+/**
+ * Resolve by the repo id this machine already recorded for the folder, and return `unresolved`
+ * unchanged when that cannot be done. Only ever called after the URL join came back empty, so it can
+ * add a match but never replace one.
+ *
+ * The id is exact where a URL is a guess: `local://demo` is derived from the folder name, so two
+ * unrelated folders both called `demo` would resolve to each other, while the id names one repo.
+ */
+async function resolveByLocalGitId(repoRoot, branch, opts, unresolved) {
+  const apiUrl = opts.apiUrl || api.currentBaseUrl();
+  for (const gitId of localGitIdCandidates(repoRoot, apiUrl)) {
+    const query = { git_id: gitId };
+    if (branch) query.branch = branch;
+    let data;
+    try {
+      data = await api.get("/api/projects/resolve", { query, apiUrl: opts.apiUrl });
+    } catch {
+      // A server that predates `git_id` rejects the whole request, and would reject it for every
+      // candidate. Give back exactly what this folder resolved to before the parameter existed.
+      return unresolved;
+    }
+    const projects = normalizeProjects(data);
+    if (projects.length) {
+      return {
+        ...unresolved,
+        state: "resolved",
+        projects,
+        multipleWorktreesAllowed: !!(data && data.multiple_worktrees_allowed),
+      };
+    }
+  }
+  return unresolved;
+}
+
+/**
+ * Repo ids worth asking the server about for this folder, most specific first.
+ *
+ * Two folders are consulted: this one, and the MAIN working tree when this is a linked worktree. The
+ * second is the one that matters. A worktree is never itself onboarded, so it has no entry of its own,
+ * and looking only at the folder we are standing in is why a worktree could not be resolved at all.
+ *
+ * A folder that has already been taken over holds the COPY's gitId in `gitId`; the repo to resolve is
+ * the source it was taken from, which is why `takeover.sourceGitId` wins where it is present. Without
+ * that a re-run would ask about a temporary project's own repo, which the server correctly refuses.
+ */
+function localGitIdCandidates(repoRoot, apiUrl) {
+  const folders = [path.resolve(repoRoot)];
+  const main = git.mainWorktreeRoot(repoRoot);
+  if (main && path.resolve(main) !== folders[0]) folders.push(path.resolve(main));
+
+  const ids = [];
+  for (const folder of folders) {
+    const entry = watchState.get(folder, apiUrl);
+    if (!entry) continue;
+    const id = (entry.takeover && entry.takeover.sourceGitId) || entry.gitId;
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  return ids;
 }
 
 /**
@@ -129,4 +211,4 @@ function projectIdFromCreateResponse(project) {
   return id.trim();
 }
 
-module.exports = { resolveContext, normalizeProjects, projectIdFromCreateResponse };
+module.exports = { resolveContext, normalizeProjects, projectIdFromCreateResponse, localGitIdCandidates };

package/src/lib/tempProject.js

@@ -34,4 +34,28 @@ async function currentBranch(tempProjectId, gitId, opts = {}) {
   return match && match.branch ? match.branch : null;
 }
 
-module.exports = { currentBranch };
+/**
+ * True when an error from a project read means "this project does not exist on this backend".
+ *
+ * Status alone cannot answer it. A deleted project fails its access check before anything looks for
+ * the row, and that check raises AccessDeniedException, which the backend maps to 403 — the SAME
+ * status it returns when the project is alive but belongs to someone else
+ * (AccessControlService.validateProjectAccess, GlobalExceptionHandler). Treating every 403 as "gone"
+ * would let a permissions problem wipe a healthy local registration, and treating none of them as
+ * gone is what left dead registrations behind in the first place. So the message decides: only a
+ * missing row produces "Project not found", while the other two say "User does not have access to
+ * project" and "User not found".
+ *
+ * A bare status is deliberately NOT enough, not even a 404. This route does not produce one today,
+ * so a 404 here means something other than the API answered: a proxy, or an HTML error page. Its
+ * sibling agentApi.isRepoNotFound does accept a bare 404, and can afford to — being wrong there
+ * costs a re-registration. Being wrong here destroys the record of how to undo a takeover, so this
+ * one fails toward keeping it: an unrecognised failure throws and changes nothing.
+ */
+function isProjectNotFound(err) {
+  if (!err) return false;
+  const text = `${err.message || ""} ${typeof err.body === "string" ? err.body : ""}`;
+  return /project not found/i.test(text);
+}
+
+module.exports = { currentBranch, isProjectNotFound };

package/src/mcp/server.js

@@ -41,7 +41,7 @@ const path = require("path");
 const readline = require("readline");
 const { execSync } = require("child_process");
 const niroProjectFile = require("../lib/niroProjectFile");
-const { redactRemoteCreds } = require("../lib/git");
+const { redactRemoteCreds, normalizeBranch } = require("../lib/git");
 const receiptStore = require("../lib/receiptStore");
 
 /** Absolute path to ~/.niro/projects.json. Uses os.homedir() so it also resolves on Windows, where HOME is
@@ -161,8 +161,13 @@ function detectGitContext(dir) {
     if (dir) opts.cwd = dir;
     const remote = execSync("git remote get-url origin 2>/dev/null", opts).trim();
     if (!remote) return null;
+    // normalizeBranch, not a bare trim: on a detached HEAD this command PRINTS "HEAD" instead of
+    // failing, and sending that verbatim told the server the checkout was on a branch called "HEAD".
+    // Nothing indexes such a branch, so the routing ladder read every bisect / tag checkout as
+    // diverged and refused to answer it — past its own guard for detached HEAD, which only fires on
+    // a null branch. `git.inspect` has always collapsed "HEAD" to null; this shares that one rule.
     let branch = null;
-    try { branch = execSync("git rev-parse --abbrev-ref HEAD 2>/dev/null", opts).trim(); } catch (_) {}
+    try { branch = normalizeBranch(execSync("git rev-parse --abbrev-ref HEAD 2>/dev/null", opts)); } catch (_) {}
     // The freshness/takeover notices compare the local HEAD + dirty state against what Niro indexed, so
     // the bridge must report them — without git_commit the server-side check no-ops entirely.
     let commit = null;