@niroai/niro 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,134 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
+## Unreleased
+
+## 0.13.0 — 2026-09-08
+
+### Upgrading
+
+You do not have `niro upgrade` yet, so this one takes two commands:
+
+```bash
+npm install -g @niroai/niro@latest
+niro upgrade --finish
+```
+
+The first gets the package. The second is the half npm cannot do: it re-runs the installer for
+every assistant you have configured and restarts the background watcher. Then restart your
+assistant. Skipping the second command leaves you on this version with the previous version's
+hooks, skills and instruction files, which is the exact problem this release exists to fix.
+
+From here on it is one command, `niro upgrade`, which does all of it.
+
+### `niro upgrade` gets the new version AND the things a new version cannot bring with it
+
+Upgrading was `npm install -g @niroai/niro@latest`, and every release note in this file said so and
+nothing else. That command is not enough, and has never been enough. The MCP entry is fine: it runs
+plain `niro` off your `PATH` with no version in it, so the new server is picked up for free. But the
+hooks, the skills and the CLAUDE.md/AGENTS.md/rules text are written into your home folder as fixed
+text at install time, not read from the package as it runs. npm cannot touch them. Nothing told you
+that, and nothing re-ran the installer, so a machine that installed once in June was still running
+June's instructions in September while reporting the current version. The background watcher had the
+same problem from the other end: it is a long-running process holding the code it loaded at start,
+so replacing files on disk left it on the old version until something restarted it.
+
+`niro upgrade` does all three. It replaces the package, re-runs the installer for every assistant it
+can prove is configured, and restarts the watcher if it is running.
+
+It runs as two processes, and the reason is worth writing down. Every command in this CLI is loaded
+lazily, inside its own action handler, and `npm install -g` replaces the folder those files are
+loaded from. One process that ran npm and then carried on would be running the modules it loaded
+before the swap alongside modules loaded after it. So phase one runs npm, executes the NEW binary
+with `--finish`, and stops, requiring nothing in between; phase two is a fresh process reading the
+new tree. `niro start` has always dodged the same trap the same way, by only installing globally
+when it is running from the npx cache and then handing over.
+
+Which assistants to refresh is worked out by looking, because nothing on disk records what you
+chose. All 14 clients are covered, because the installer leaves a file this repo owns in every case:
+eight write a JSON config whose path `setup.js` builds, and the other six also get a marker appended
+to a markdown file written here and stripped by `teardown.js` (`~/.claude/CLAUDE.md`,
+`~/.gemini/GEMINI.md`, `~/.copilot/copilot-instructions.md`, `~/.factory/AGENTS.md`), plus codex's
+`[mcp_servers.niro]` table and goose's `extensions:` entry. The marker is appended only after the
+registration command succeeded, so its presence means the client really was configured. Detection is
+read-only, and it is deliberately strict: a client whose entry is `enabled: false` or
+`disabled: true` is one you switched off, so it is left alone rather than switched back on; a
+marker has to be on a line of its own, because a sentence mentioning it is not an install; and every
+path has to be absolute.
+
+`niro upgrade --finish` on its own skips npm and only refreshes the assistant files and the watcher,
+which is what you want if you already ran `npm install -g` by hand.
+
+Without a usable home folder it checks nothing and says so. Every path would otherwise resolve
+against the current folder, which is how the reverted serve-time self-heal came to write into a
+project's own `.claude/settings.json` (see the 2026-07-30 revert). "Usable" means absolute, and it
+also means rejecting a `HOME` set to the empty string even when `USERPROFILE` would fill in, because
+four of the client path builders read `HOME` directly and would otherwise hand back a relative path.
+This command never writes a settings file itself: refreshing hooks means spawning the existing
+installer, once per client.
+
+It refuses to upgrade a copy you are not running. The first real run of this command was from a
+checkout linked with `npm link`, and `npm install -g` deleted that link and put the published
+package in its place. So before npm is allowed to touch anything, `niro upgrade` looks at which
+copy is running: the global package folder being a symlink means `npm link`, and it stops and says
+so; a checkout or an npx copy that is not the global install stops too. `--force` overrides either.
+
+It also asks the version it just installed whether it has an `upgrade` command before handing over
+to it, because the newest published version can predate the one you are running. Without that
+check the hand-over fails with a bare `error: unknown command 'upgrade'` and the advice printed is
+to re-run a command that does not exist. Now it prints the two commands that do work.
+
+Failures are visible. Each one has its own exit code (npm failed, no binary after npm, hand-over
+failed, refresh incomplete), an interrupted npm is reported as interrupted rather than as "nothing
+changed", a hand-over that cannot start prints why, and the hand-over carries a marker so a version
+that does not understand `--finish` cannot loop back into running npm again.
+
+
+## 0.12.0 — 2026-09-06
+
+### Before an edit to indexed source, Claude is asked to map the method and to verify those flows afterwards
+
+Every instruction file niro writes tells the assistant to map who depends on a method before changing
+it. In practice the assistant finds the file, reads it, and edits; the rule is read early in a session
+and forgotten by the middle of it. And the map was always meant for afterwards: the point is to go back
+to the callers and flows once the edit is made and check they still hold.
+
+Claude Code now gets a third niro hook, on Edit and Write. Before an edit to source in an indexed repo
+it puts a short reminder in front of the assistant: decide whether the change can alter behaviour (a log
+line or a comment cannot, say so and go ahead); if it can, map who depends on the method now with
+get_blast_radius or get_impact_analysis and keep that list as the checklist for after the edit; and do
+not re-query the graph to verify, because it updates only after the edit is synced and rebuilt. If an
+impact call already named the file this session, the reminder instead says to go back to that list
+after the edit. Each reminder appears once per file per session. It is advisory: it never approves or
+refuses an edit. The evidence comes from the bridge, which writes one line per answered impact call
+under `~/.niro/impact/`. New files, tests, config and docs are never mentioned. Off switch:
+`touch ~/.niro/impact-gate-off`. `niro mcp uninstall` removes the hook and the evidence files.
+
+The same three points were added to every instruction surface niro writes: the rule sentence in each
+client's always-on file, the niro skill, the Cursor, Cline and Kiro rules, and the PostCompact and
+prompt hooks. The clients without hooks read them there. Details: `docs/usecases/impact-gate.md`.
+
+### `niro mcp install` now refreshes Claude Code hooks on a machine where niro was already set up
+
+Re-running the install on a machine with an existing registration failed at the first step, because
+`claude mcp add` refuses a name that already exists, and the installer read that refusal as "Claude
+Code is not installed" and stopped before writing any hook or the CLAUDE.md section. So the step the
+out-of-date notice asks for did nothing for anyone who had installed once. The installer now reads the
+existing registration first: same URL, it keeps it; a different `--url`, it replaces it; none, it adds
+it. Hooks and sections are written in every case.
+
+### CommonJS and ES-module files (.cjs, .mjs, .cts, .mts) are now uploaded for indexing
+
+When niro decided which files to upload for indexing, it skipped `.cjs`, `.mjs`, `.cts` and `.mts`,
+so a `build.cjs` or an `index.mjs` was never indexed and never appeared in the graph. Those four
+extensions are now included, matching the server's own file filter.
+
+### The niro rules now name get_exception_flow
+
+The explore-first rule niro writes into each client now mentions `get_exception_flow`, the tool that
+reports which exceptions can escape a method (and who must handle one). It is served by the niro
+backend; this only makes the assistants aware it exists.
+
 ## 0.11.0 — 2026-09-03
 
 ### The watcher stops pausing and resuming your uploads over and over

package/README.md

@@ -45,7 +45,9 @@ Then restart your assistant and ask it something:
 ```bash
 niro status
 ```
-Is my index up to date?
+Is my index up to date? It answers about the project this folder is synced to **on the branch you
+are on**, so once you have run `niro new-temp-project` it reports that copy rather than the shared
+project. Name one explicitly to ask about a different project: `niro status <project-id>`.
 
 ```bash
 niro start
@@ -65,7 +67,15 @@ Every project in your account.
 ```bash
 niro build
 ```
-Rebuild the index by hand and watch it finish.
+Rebuild the index by hand and watch it finish. Like `niro status`, it picks the project for the
+branch you are on, so on a branch with a temporary project it rebuilds that one. Name a project to
+rebuild a different one.
+
+```bash
+niro upgrade
+```
+Get the latest version, and bring your hooks, skills and watcher with it. See
+[Upgrading](#upgrading).
 
 ```bash
 niro doctor
@@ -224,7 +234,10 @@ Detach a repo from a project. Nothing is deleted.
 ```bash
 niro remove --project --confirm-name <name>
 ```
-Delete a whole project. Destructive, hence the confirmation.
+Delete a whole project. Destructive, hence the confirmation. It refuses on a temporary project and
+sends you to `niro discard-temp-project` instead, because that removes the copy **and** points this
+folder back at the shared project; deleting it here would leave the folder aimed at a project that
+no longer exists. `niro delete` refuses for the same reason.
 
 ---
 
@@ -247,6 +260,58 @@ Watch this folder in the foreground instead, for one session.
 
 ---
 
+## Upgrading
+
+**Check which you are on first:**
+
+```bash
+niro --version
+```
+
+**On 0.13.0 or newer**, one command:
+
+```bash
+niro upgrade
+```
+
+Replaces the package with the latest published version, then puts back the two things replacing the
+package cannot reach: it re-runs the installer for every assistant you have configured, and
+restarts the background watcher. Restart your assistant afterwards.
+
+**On anything older than 0.13.0**, you do not have `niro upgrade` yet, so it is two commands, once:
+
+```bash
+npm install -g @niroai/niro@latest
+niro upgrade --finish
+```
+
+The first gets the package. The second does the half npm cannot: your hooks, skills and the
+watcher. After that, `niro upgrade` on its own is enough. Do not stop after the first command:
+that leaves you on the new version running the old version's hooks, skills and instruction files,
+which is the problem `niro upgrade` exists to solve.
+
+**Why it is more than an npm install.** The hooks, skills and instruction files are written into
+your home folder as fixed text when you install, not read out of the package as it runs, so a newer
+package does not change them. The watcher is a long-running process still holding the code it
+started with. The MCP config is the one part that needs nothing done to it: it runs plain `niro`
+from your `PATH` with no version pinned in it, so the new server is picked up on its own.
+
+**Restart your assistant last.** Skills and hooks are read when it starts, so nothing above reaches
+a session that is already open.
+
+Fully by hand, if you would rather:
+
+```bash
+npm install -g @niroai/niro@latest
+niro mcp install       # once per assistant you use
+niro service install   # only if you run the watcher
+```
+
+`niro start` upgrades nothing. On a machine that has connected an assistant once it skips the
+connect step, so the old hooks and skills stay where they are.
+
+---
+
 ## Reference
 
 Add `--help` to any command for its flags. Add `--json` to `whoami`, `info`, `status`,
@@ -295,6 +360,10 @@ does nothing until you do.
 
 **Auto-sync is not running.** `npm install -g pm2`, then `niro service install`.
 
+**A command or feature in the changelog is missing.** You are on an older version. Check with
+`niro --version`, then see [Upgrading](#upgrading): before 0.13.0 it takes two commands, after it
+one. Plain `npm install -g` on its own always leaves your hooks and skills on the old version.
+
 **A folder was refused.** Niro will not index your home folder, or a folder with no build file
 in it. Point it at the repo you meant.
 

package/docs/working-on-branches.md

@@ -46,6 +46,14 @@ It creates your own private copy of the project inside Niro.
 
 From then on, answers come from YOUR code.
 
+The commands follow too. `niro status` and `niro build` act on the copy for the branch you are on,
+not on the shared project, so "is my index up to date" and "rebuild it" mean what you expect while
+you are working on a branch. Name a project explicitly if you want a different one.
+
+`niro delete` and `niro remove --project` will not delete a private copy. They send you to
+`niro discard-temp-project`, which removes the copy AND points your folder back at the shared
+project. Deleting it any other way leaves your folder aimed at something that is gone.
+
 ## Switching branches
 
 Nothing to do. Niro checks which branch you are on for every question.

package/package.json

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

package/src/commands/_resolveProject.js

@@ -7,11 +7,16 @@
  *        - an alias or git URL        -> resolved via GET /api/projects/resolve.
  *      If an alias/URL maps to MULTIPLE projects, a clear ambiguity error is
  *      thrown listing the candidates (we never silently pick the first).
- *   2. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
+ *   2. The project THIS FOLDER IS CURRENTLY SYNCED TO, when it was recorded for the
+ *      branch that is checked out. See resolveFromSyncedFolder for why this comes
+ *      before the pin.
+ *   3. Walk up from cwd looking for .niro-project (same logic the MCP bridge uses).
  */
 const api = require("../lib/api");
 const prompt = require("../lib/prompt");
 const niroProjectFile = require("../lib/niroProjectFile");
+const git = require("../lib/git");
+const watchState = require("../lib/watchState");
 const { normalizeProjects, resolveContext } = require("../lib/resolveContext");
 
 // A canonical project_id is a UUID. Anything that doesn't look like one and
@@ -119,6 +124,36 @@ async function resolveProjectFromGit(opts = {}) {
   throw e;
 }
 
+/**
+ * The project this folder is actually synced to right now, when the recorded branch is the
+ * one checked out. Null when nothing is recorded, when the branch has moved on, or on any error.
+ *
+ * <p>Why this has to come BEFORE the .niro-project pin. The pin holds the SHARED project's id and
+ * never changes. When a developer runs `niro new-temp-project`, the folder starts syncing to a
+ * private temporary project that indexes their branch, and only ~/.niro/projects.json records it.
+ * Reading the pin therefore answers about a project the developer is not working in. Measured on
+ * 2026-09-08: in a repo on branch feat/shipping-wrap-rethrow, `niro status` reported the shared
+ * project with "Updated 2026-09-06T09:28", two days stale, while the branch's own project had
+ * finished a build four minutes earlier. `niro build` had the same fault and would have rebuilt the
+ * shared project.
+ *
+ * <p>The branch comparison is the safety catch. An entry recorded on another branch must not
+ * redirect the command, so a mismatch falls through to the pin, which is the old behaviour.
+ */
+function resolveFromSyncedFolder(opts = {}) {
+  try {
+    const ctx = git.inspect(process.cwd());
+    if (!ctx || !ctx.repoRoot) return null;
+    const entry = watchState.get(ctx.repoRoot, opts.apiUrl || api.currentBaseUrl());
+    if (!entry || !entry.projectId) return null;
+    if (entry.branch && ctx.branch && entry.branch !== ctx.branch) return null;
+    return entry.projectId;
+  } catch (_) {
+    // Never block a command on this: falling through to the pin is the previous behaviour.
+    return null;
+  }
+}
+
 async function resolveProjectId(explicit, opts = {}) {
   if (explicit) {
     // A UUID is used directly — unchanged behavior. Anything else is an
@@ -126,7 +161,10 @@ async function resolveProjectId(explicit, opts = {}) {
     if (looksLikeProjectId(explicit)) return explicit;
     return resolveAliasOrUrl(explicit, opts);
   }
-  // No explicit arg: prefer a .niro-project pin (walk up from cwd).
+  // No explicit arg: the project this folder is synced to on THIS branch wins over the pin.
+  const fromFolder = resolveFromSyncedFolder(opts);
+  if (fromFolder) return fromFolder;
+  // Then a .niro-project pin (walk up from cwd).
   const fromFile = readNiroProjectFile(process.cwd());
   if (fromFile) {
     // A pin that is already a project_id is used directly. A pin holding an
@@ -139,4 +177,22 @@ async function resolveProjectId(explicit, opts = {}) {
   return resolveProjectFromGit(opts);
 }
 
-module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId };
+/**
+ * The temporary project this id names, or null when it is an ordinary shared project.
+ *
+ * <p>Used by the destructive commands. Deleting a temporary project through `niro delete` leaves
+ * the folder pinned to a project that is gone and skips the local cleanup that
+ * `niro discard-temp-project` does, so those commands send the developer there instead.
+ * Never throws: if the project cannot be fetched, the caller carries on as before.
+ */
+async function tempProjectSourceId(projectId, opts = {}) {
+  try {
+    const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
+    return (project && (project.cloneOfProjectId || project.clone_of_project_id)) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+module.exports = { resolveProjectId, readNiroProjectFile, resolveAliasOrUrl, looksLikeProjectId,
+  resolveFromSyncedFolder, tempProjectSourceId };

package/src/commands/delete.js

@@ -14,12 +14,27 @@ const api = require("../lib/api");
 const credentials = require("../lib/credentials");
 const prompt = require("../lib/prompt");
 const color = require("../lib/color");
-const { resolveProjectId, readNiroProjectFile } = require("./_resolveProject");
+const { resolveProjectId, readNiroProjectFile, tempProjectSourceId } = require("./_resolveProject");
 
 async function deleteProject(projectIdArg, opts = {}) {
   credentials.requireCreds();
   const projectId = await resolveProjectId(projectIdArg, { apiUrl: opts.apiUrl });
 
+  // A temporary project is not deleted through here. It belongs to a folder and a branch, and
+  // `discard-temp-project` is what unwinds both: it removes the project AND points the folder back
+  // at the shared one, repairing the local pin. Deleting it server-side does neither, so the folder
+  // is left aimed at a project that no longer exists. Refusing costs one command; the alternative is
+  // a broken checkout the developer then has to work out how to repair.
+  const cloneOf = await tempProjectSourceId(projectId, opts);
+  if (cloneOf) {
+    console.log(`${color.yellow("⚠")}  ${color.bold(projectId)} is a temporary project for your branch, not a shared one.`);
+    console.log(color.dim(`    It is a private copy of ${cloneOf}.`));
+    console.log(`    Use ${color.bold("niro discard-temp-project")} in this folder instead — that removes it AND`);
+    console.log(`    points this folder back at the shared project. ${color.dim("Nothing has been deleted.")}`);
+    process.exitCode = 1;
+    return;
+  }
+
   if (!opts.yes) {
     console.log(`${color.yellow("⚠")}  About to delete project ${color.bold(projectId)}.`);
     console.log(color.dim("    This removes the project and its graph from the server. Registered repos stay."));

package/src/commands/mcp.js

@@ -2,19 +2,28 @@
  * `niro mcp install` / `niro mcp uninstall` / `niro mcp serve` — drive the in-package MCP server.
  *
  * install():   spawn the bundled editor-config wizard as a child so it can prompt.
+ *              Takes optional wizard arguments; see runWizard.
  * uninstall(): spawn the teardown wizard — the exact inverse of install.
  * serve():     run the in-package stdio bridge directly in this process so the
  *              editor's MCP stdio talks straight to it.
  */
 const path = require("path");
-const { spawn } = require("child_process");
+const childProcess = require("child_process");
 
-/** Spawn a bundled wizard (setup.js / teardown.js) as a child so it can prompt on the TTY. */
-function runWizard(scriptName, label) {
+/**
+ * Spawn a bundled wizard (setup.js / teardown.js) as a child so it can prompt on the TTY.
+ *
+ * `args` overrides what is forwarded to the wizard. Callers that are themselves a `niro mcp ...`
+ * command leave it out and the user's own flags after `niro mcp install` are passed through.
+ * `niro upgrade` passes its own `--client <id>`, because the flags on its command line
+ * (`--finish`, `--from`) are not the wizard's.
+ */
+function runWizard(scriptName, label, args) {
+  const wizardArgs = Array.isArray(args) ? args : process.argv.slice(4);
   return new Promise((resolve, reject) => {
-    const child = spawn(
+    const child = childProcess.spawn(
       process.execPath,
-      [path.join(__dirname, "..", "mcp", scriptName), ...process.argv.slice(4)],
+      [path.join(__dirname, "..", "mcp", scriptName), ...wizardArgs],
       { stdio: "inherit" }
     );
     child.on("error", reject);
@@ -25,8 +34,8 @@ function runWizard(scriptName, label) {
   });
 }
 
-async function install() {
-  return runWizard("setup.js", "setup");
+async function install(args) {
+  return runWizard("setup.js", "setup", args);
 }
 
 async function uninstall() {

package/src/commands/remove.js

@@ -57,14 +57,27 @@ async function remove(opts = {}) {
   // --project: destructive. Fetch the project so we can match --confirm-name
   // against either the alias or the project_id.
   let alias = null;
+  let cloneOf = null;
   try {
     const project = await api.get(`/api/projects/${encodeURIComponent(projectId)}`, { apiUrl: opts.apiUrl });
     alias = (project && (project.alias)) || null;
+    cloneOf = (project && (project.cloneOfProjectId || project.clone_of_project_id)) || null;
   } catch (err) {
     // If we can't read the project, fall back to matching the id only.
     alias = null;
   }
 
+  // Same rule as `niro delete`: a temporary project is unwound by discard-temp-project, which also
+  // points this folder back at the shared project. Removing it here would leave the folder aimed at
+  // a project that is gone. Read from the fetch above rather than a second request.
+  if (cloneOf) {
+    console.log(`${color.yellow("⚠")}  ${color.bold(projectId)} is a temporary project for your branch, not a shared one.`);
+    console.log(color.dim(`    It is a private copy of ${cloneOf}.`));
+    console.log(`    Use ${color.bold("niro discard-temp-project")} in this folder instead. ${color.dim("Nothing has been removed.")}`);
+    process.exitCode = 1;
+    return;
+  }
+
   const confirm = opts.confirmName == null ? null : String(opts.confirmName).trim();
   const matches = confirm != null && (confirm === projectId || (alias != null && confirm === alias));
   if (!matches) {

package/src/commands/start.js

@@ -560,6 +560,7 @@ module.exports = {
   printNextSteps,
   BOOK_A_CALL,
   runningFromNpxCache,
+  globalNiroPath,
   isOlder,
   describeProblem,
   expandHome,