@niroai/niro 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,87 @@ 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

package/README.md

@@ -71,6 +71,12 @@ Rebuild the index by hand and watch it finish. Like `niro status`, it picks 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
 ```
@@ -254,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`,
@@ -302,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/package.json

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

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

package/src/commands/upgrade.js

@@ -0,0 +1,400 @@
+/**
+ * `niro upgrade` — replace this install with the latest published package, then put back the
+ * things replacing the package cannot put back for itself.
+ *
+ * Why this runs as two processes.
+ *
+ * Every command in this CLI is loaded lazily, inside its own action handler (src/index.js), and
+ * `npm install -g` replaces the folder those files are loaded from. A single process that ran npm
+ * and then carried on would be running the modules it loaded before the swap alongside modules
+ * loaded after it. Nothing tests that mixture. start.js has always avoided the same trap the same
+ * way: bootstrapIfNpx installs globally only when it is running from the npx cache, so it never
+ * overwrites the tree it is executing, and then it hands over.
+ *
+ *   phase one, this copy       run npm, then exec the NEW global binary with --finish and stop.
+ *   phase two, the new copy    a fresh process reading the new tree: restart the watcher, refresh
+ *                              each configured client's hooks and skills, ask for an assistant
+ *                              restart.
+ *
+ * Phase one requires nothing between the npm call and the hand-over, and it also catches its own
+ * errors rather than letting them reach src/index.js `run()`, whose catch does
+ * `require("./lib/printError")` — a lazy load out of the folder npm has just replaced. That is the
+ * one path where the swap could still bite, so it is closed here rather than described.
+ *
+ * What it deliberately does not do is write a settings file itself. Refreshing hooks means
+ * spawning the existing installer, once per client. A second write path into
+ * ~/.claude/settings.json was built once, reviewed three times and reverted on 2026-07-30
+ * (d3ff3d8) after it was found deleting users' own hooks, changing that file from mode 0600 to
+ * 0644 while it can hold API keys, and, with HOME unset, writing into a project's git-tracked
+ * .claude/settings.json. The installer already gets those cases right, and here it runs because
+ * the user asked for it.
+ */
+const childProcess = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const color = require("../lib/color");
+const service = require("../lib/service");
+const mcpClients = require("../lib/mcpClients");
+const mcpCmd = require("./mcp");
+const startCmd = require("./start");
+
+const PACKAGE_NAME = "@niroai/niro";
+const VERSION = require("../../package.json").version;
+
+/**
+ * Set on the process phase one hands over to. If phase one ever sees it already set, it is itself
+ * a hand-over child that failed to reach phase two, which means the newly installed version does
+ * not understand `--finish`. Without this, that version would run npm and hand over again, without
+ * bound. start.js guards its own hand-over with BOOTSTRAP_ENV for the same reason.
+ */
+const HANDOVER_ENV = "NIRO_UPGRADE_HANDOVER";
+
+/** Exit codes, so a script can tell the failures apart. */
+const EXIT_NPM_FAILED = 1;
+const EXIT_NO_BINARY = 2;
+const EXIT_HANDOVER_FAILED = 3;
+const EXIT_REFRESH_INCOMPLETE = 4;
+const EXIT_WRONG_COPY = 5;
+
+/** `niro upgrade` (phase one) and `niro upgrade --finish` (phase two). */
+async function upgrade(opts = {}) {
+  if (opts.finish) return finish(opts.from);
+  return replaceAndHandOver(Boolean(opts.force));
+}
+
+/**
+ * Phase one. Replace the package, then hand over to the copy that replaced it.
+ *
+ * Everything this function touches is already loaded by the requires at the top of this file, and
+ * every failure is reported here rather than thrown, because a throw would reach a catch that
+ * lazily loads a module out of the folder npm has just swapped.
+ */
+function replaceAndHandOver(force) {
+  if (process.env[HANDOVER_ENV]) {
+    console.error(color.red("\n  The version just installed does not support `niro upgrade --finish`."));
+    console.error("    The package itself is upgraded. Your hooks, skills and watcher are not.");
+    console.error(`    Finish by hand: ${color.cyan("niro mcp install")} for each assistant you use,`);
+    console.error(`    then ${color.cyan("niro service install")} if you run the background watcher.\n`);
+    process.exitCode = EXIT_HANDOVER_FAILED;
+    return;
+  }
+
+  const running = describeRunningCopy();
+  if (running.kind === "linked" && !force) {
+    console.error(color.yellow("\n  Not upgrading: niro is npm-linked to a working copy."));
+    console.error(`    ${color.cyan("npm prefix -g")} says the global package folder is a link:`);
+    console.error(`      ${running.pkgDir}`);
+    console.error(`      -> ${running.linkTarget}`);
+    console.error("    `npm install -g` would replace that link with the published package, and");
+    console.error("    `niro` would stop running your checkout. Your files would be untouched, but");
+    console.error(`    you would have to run ${color.cyan("npm link")} in the checkout to get it back.`);
+    console.error(`    Upgrade anyway with ${color.cyan("niro upgrade --force")}.\n`);
+    process.exitCode = EXIT_WRONG_COPY;
+    return;
+  }
+  if (running.kind === "elsewhere" && !force) {
+    console.error(color.yellow("\n  Not upgrading: you are not running the globally installed niro."));
+    console.error(`    running:  ${running.self || "unknown"}`);
+    console.error(`    would upgrade: ${running.pkgDir || "the npm global folder"}`);
+    console.error("    Those are different copies, so this would replace one you are not using and");
+    console.error("    leave the one you are.");
+    console.error(`    Upgrade the global copy anyway with ${color.cyan("niro upgrade --force")}.\n`);
+    process.exitCode = EXIT_WRONG_COPY;
+    return;
+  }
+
+  console.log(`\n  Upgrading niro. Installed now: ${VERSION}\n`);
+
+  const installed = childProcess.spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+    shell: true,
+    stdio: "inherit",
+  });
+
+  if (installed.signal) {
+    // Ctrl+C reaches the whole process group, so npm dies with this process. Whether it left the
+    // global folder half-written is npm's business and not something this can know, so it is not
+    // claimed either way.
+    console.error(color.yellow(`\n  Interrupted (${installed.signal}) while npm was running.`));
+    console.error("    Whether the package was replaced is unknown. Check with `niro --version`,");
+    console.error(`    then run ${color.cyan("niro upgrade")} again.\n`);
+    process.exitCode = EXIT_NPM_FAILED;
+    return;
+  }
+
+  if (installed.status !== 0) {
+    console.error(color.red("\n  npm could not replace the package."));
+    console.error("    The usual cause is that your npm global folder needs root. Find it with");
+    console.error(`    ${color.cyan("npm prefix -g")}, then either fix its ownership or re-run the install`);
+    console.error("    with the privileges it needs:");
+    console.error(`      ${color.cyan(`npm install -g ${PACKAGE_NAME}@latest`)}`);
+    console.error(`    Then run ${color.cyan("niro upgrade --finish")} to refresh your assistant files.\n`);
+    process.exitCode = EXIT_NPM_FAILED;
+    return;
+  }
+
+  const bin = startCmd.globalNiroPath();
+  if (!bin) {
+    console.error(color.red("\n  npm reported success, but there is no niro in your npm global folder."));
+    console.error(`    Check ${color.cyan("npm prefix -g")} and that its bin folder is on your PATH.`);
+    console.error("    The package is upgraded; only the refresh step was skipped. Run it with");
+    console.error(`    ${color.cyan("niro upgrade --finish")} once niro is back on PATH.\n`);
+    process.exitCode = EXIT_NO_BINARY;
+    return;
+  }
+
+  if (!supportsFinish(bin)) {
+    // The version just installed has no `upgrade` command, which is what happens when the newest
+    // published version predates this one. Saying "re-run niro upgrade --finish" here would send
+    // the user to a command that cannot exist.
+    console.error(color.yellow("\n  The package is upgraded, but the version now installed has no"));
+    console.error("  `niro upgrade` command, so it cannot refresh your assistant files itself.");
+    console.error("    Finish by hand:");
+    console.error(`      ${color.cyan("niro mcp install")}       once per assistant you use`);
+    console.error(`      ${color.cyan("niro service install")}   if you run the background watcher`);
+    console.error("    Then restart your assistant.\n");
+    process.exitCode = EXIT_HANDOVER_FAILED;
+    return;
+  }
+
+  // The hand-over. A fresh process reads the new tree cleanly; this one cannot. VERSION comes from
+  // package.json, so it is a semver string and safe on a Windows command line. The Windows branch
+  // is untested: spawning a .cmd shim needs a shell on current Node, and a global prefix
+  // containing spaces is why the path is quoted.
+  const env = { ...process.env, [HANDOVER_ENV]: "1" };
+  const handover = process.platform === "win32"
+    ? childProcess.spawnSync(`"${bin}" upgrade --finish --from ${VERSION}`, { stdio: "inherit", shell: true, env })
+    : childProcess.spawnSync(bin, ["upgrade", "--finish", "--from", VERSION], { stdio: "inherit", env });
+
+  if (handover.error) {
+    // spawnSync could not start the child at all: a non-executable bin link, a directory where the
+    // binary should be, a broken shim. Without this the command exits silently.
+    console.error(color.red(`\n  Could not run the upgraded niro at ${bin}:`));
+    console.error(`    ${handover.error.message}`);
+    console.error("    The package is upgraded; your hooks, skills and watcher are not.");
+    console.error(`    Try ${color.cyan("niro upgrade --finish")}, or reinstall with`);
+    console.error(`    ${color.cyan(`npm install -g ${PACKAGE_NAME}@latest`)}.\n`);
+    process.exitCode = EXIT_HANDOVER_FAILED;
+    return;
+  }
+
+  if (handover.signal) {
+    console.error(color.yellow(`\n  Interrupted (${handover.signal}) while refreshing.`));
+    console.error(`    The package is upgraded. Finish with ${color.cyan("niro upgrade --finish")}.\n`);
+    process.exitCode = EXIT_HANDOVER_FAILED;
+    return;
+  }
+
+  if (handover.status !== 0) {
+    console.error(`\n  The upgraded niro exited with ${handover.status} while refreshing.`);
+    console.error(`    The package is upgraded. Re-run ${color.cyan("niro upgrade --finish")} to try again.\n`);
+  }
+  process.exitCode = handover.status === null ? EXIT_HANDOVER_FAILED : handover.status;
+}
+
+/** Where npm would install this package globally. */
+function globalPackageDir() {
+  const r = childProcess.spawnSync("npm", ["prefix", "-g"], { shell: true, encoding: "utf8" });
+  if (r.status !== 0) return null;
+  const prefix = String(r.stdout || "").trim();
+  if (!prefix) return null;
+  return process.platform === "win32"
+    ? path.join(prefix, "node_modules", PACKAGE_NAME.replace("/", path.sep))
+    : path.join(prefix, "lib", "node_modules", PACKAGE_NAME.replace("/", path.sep));
+}
+
+/**
+ * Which copy of niro is running this, checked BEFORE npm is allowed to touch anything.
+ *
+ *   "global"     this process is the globally installed package, so replacing it is the job
+ *   "linked"     the global package folder is a symlink, which is what `npm link` leaves behind.
+ *                `npm install -g` deletes that link and puts the published package in its place,
+ *                so a developer working on niro loses the wiring between `niro` and their checkout.
+ *   "elsewhere"  running from somewhere else entirely: a checkout invoked directly, or the npx
+ *                cache. Upgrading then replaces a copy the user is not running.
+ *
+ * This exists because the first real run of `niro upgrade` was from a linked checkout and silently
+ * replaced it with the published package.
+ */
+function describeRunningCopy(pkgDirOverride) {
+  // The directory is a parameter so a unit test can exercise every branch without shelling out to
+  // npm at all. An end-to-end rehearsal takes the other route and sets npm_config_prefix, which
+  // npm does honour (scripts/rehearse-upgrade.sh).
+  const pkgDir = pkgDirOverride === undefined ? globalPackageDir() : pkgDirOverride;
+
+  let self = null;
+  try {
+    self = fs.realpathSync(process.argv[1]);
+  } catch (err) {
+    self = null;
+  }
+
+  if (pkgDir) {
+    try {
+      if (fs.lstatSync(pkgDir).isSymbolicLink()) {
+        return { kind: "linked", pkgDir, linkTarget: fs.realpathSync(pkgDir), self };
+      }
+    } catch (err) {
+      // Not installed globally at all. Falls through to "elsewhere".
+    }
+  }
+
+  let pkgReal = null;
+  try {
+    pkgReal = pkgDir ? fs.realpathSync(pkgDir) : null;
+  } catch (err) {
+    pkgReal = null;
+  }
+  if (pkgReal && self && (self === pkgReal || self.startsWith(pkgReal + path.sep))) {
+    return { kind: "global", pkgDir, linkTarget: null, self };
+  }
+  return { kind: "elsewhere", pkgDir, linkTarget: null, self };
+}
+
+/**
+ * Does the version now installed actually have `niro upgrade --finish`?
+ *
+ * Asked rather than assumed, because the newest published version can predate this one: a machine
+ * running an unreleased build upgrades "up" to a package with no `upgrade` command at all. Without
+ * this, the hand-over fails with commander's bare `error: unknown command 'upgrade'` and the user
+ * is told to re-run a command that cannot exist.
+ */
+function supportsFinish(bin) {
+  const probe = process.platform === "win32"
+    ? childProcess.spawnSync(`"${bin}" upgrade --help`, { shell: true, encoding: "utf8", stdio: "pipe" })
+    : childProcess.spawnSync(bin, ["upgrade", "--help"], { encoding: "utf8", stdio: "pipe" });
+  if (probe.error || probe.status !== 0) return false;
+  return String(probe.stdout || "").includes("--finish");
+}
+
+/** Phase two, running from the new package: put back what npm could not. */
+async function finish(fromVersion) {
+  console.log(fromVersion && fromVersion !== VERSION
+    ? `\n  niro ${fromVersion} to ${VERSION}\n`
+    : `\n  niro ${VERSION}\n`);
+
+  // The watcher first. It is one command and cannot block, whereas a client refresh can sit on a
+  // prompt for as long as the user is away, and until the restart happens the watcher is running
+  // code from a package that no longer exists on disk.
+  restartWatcher();
+
+  const complete = await refreshAssistantFiles();
+  if (!complete) process.exitCode = EXIT_REFRESH_INCOMPLETE;
+
+  console.log(`  ${color.yellow("One thing left:")} restart your AI assistant.`);
+  console.log("  Hooks and skills are read when it starts, so an assistant that is already open");
+  console.log("  is still using the old ones.\n");
+}
+
+/**
+ * Re-run the installer once per configured client, so their hooks, skills and instruction files
+ * match the package that is now installed. Returns false when anything was skipped or failed, so
+ * the caller can set a non-zero exit code: a script driving this needs to know that half of it
+ * did nothing.
+ *
+ * One client failing does not stop the others. They are separate files owned by separate tools,
+ * and a missing editor CLI is an ordinary reason for one to fail.
+ */
+async function refreshAssistantFiles() {
+  const { home, configured } = mcpClients.configuredClients();
+
+  if (!home) {
+    console.log(`  ${color.yellow("Skipped the assistant files:")} there is no usable home folder.`);
+    console.log("  HOME is unset or empty, so every path would have been read relative to the");
+    console.log("  folder you are standing in, which is not yours to read or write.");
+    console.log(`  Set HOME, then run ${color.cyan("niro upgrade --finish")}.\n`);
+    return false;
+  }
+
+  if (configured.length === 0) {
+    console.log("  No configured assistant found, so there were no hooks or skills to refresh.");
+    console.log(`  Connect one with ${color.cyan("niro mcp install")}.\n`);
+    return true;
+  }
+
+  if (!startCmd.hasCredentials()) {
+    console.log(`  ${color.yellow("Heads up:")} you are not signed in, so each client's installer will ask`);
+    console.log(`  for an API key. ${color.cyan("niro login")} first if you would rather it did not.\n`);
+  }
+
+  // Cursor's installer writes a project-scoped rule to <cwd>/.cursor/rules/niro.mdc, so refreshing
+  // it leaves a file in whatever folder the upgrade was run from. That is the installer's design,
+  // not something to change here, but it is a surprise when you only asked to upgrade.
+  if (configured.some((c) => c.id === "cursor")) {
+    console.log(`  ${color.yellow("Note:")} refreshing Cursor also writes a project rule to`);
+    console.log(`  ${path.join(process.cwd(), ".cursor", "rules", "niro.mdc")}`);
+    console.log("  because Cursor rules are per-folder. Delete it if you did not want it here.\n");
+  }
+
+  const total = configured.length;
+  console.log(`  Refreshing hooks and skills for ${total} client${total === 1 ? "" : "s"}:`);
+  for (const client of configured) {
+    console.log(`    ${client.name}  (${client.where})`);
+  }
+  console.log("");
+
+  let done = 0;
+  let failed = 0;
+  for (const client of configured) {
+    console.log(color.dim(`  [${done + failed + 1} of ${total}] ${client.name}`));
+    try {
+      await mcpCmd.install(["--client", client.id]);
+      done += 1;
+    } catch (err) {
+      failed += 1;
+      console.error(`  ${color.yellow("!")} ${client.name} was not refreshed: ${err.message}`);
+      console.error(`    Run ${color.cyan(`niro mcp install --client ${client.id}`)} to see why.\n`);
+    }
+  }
+
+  if (failed > 0) {
+    console.log(`  ${done} of ${total} refreshed, ${failed} failed.`);
+    console.log(`  Re-run ${color.cyan("niro upgrade --finish")} once the failures above are sorted.\n`);
+    return false;
+  }
+  console.log(`  ${color.green("Done.")} ${done} of ${total} refreshed.\n`);
+  return true;
+}
+
+/**
+ * Restart the background watcher, which is a long-running process still holding the code it loaded
+ * when it started. Replacing files on disk cannot change a process that is already running.
+ */
+function restartWatcher() {
+  if (!service.pm2Available()) {
+    console.log("  Background watcher: PM2 is not installed, so there is nothing to restart.\n");
+    return;
+  }
+
+  const state = service.processState();
+  if (state !== "online") {
+    const what = state === "stopped" ? "registered but not running" : "not installed";
+    console.log(`  Background watcher: ${what}, so it was left alone.\n`);
+    return;
+  }
+
+  console.log("  Restarting the background watcher, which is still running the old code...");
+  if (service.restart()) {
+    // Deliberately not "now on <version>": pm2 re-execs the script path recorded when the daemon
+    // was installed (service.js records process.argv[1]), which is not necessarily the copy that
+    // was just upgraded. All that is known here is that pm2 restarted it.
+    console.log(`  ${color.green("Done.")} niro-watch restarted. Check it with ${color.cyan("niro service status")}.\n`);
+  } else {
+    console.log(`  ${color.yellow("!")} Could not restart it. Run ${color.cyan("niro service install")}.\n`);
+  }
+}
+
+module.exports = {
+  upgrade,
+  // exported for tests
+  refreshAssistantFiles,
+  restartWatcher,
+  describeRunningCopy,
+  supportsFinish,
+  HANDOVER_ENV,
+  EXIT_NPM_FAILED,
+  EXIT_NO_BINARY,
+  EXIT_HANDOVER_FAILED,
+  EXIT_REFRESH_INCOMPLETE,
+  EXIT_WRONG_COPY,
+};

package/src/index.js

@@ -309,6 +309,17 @@ function main() {
       await deleteCmd.deleteProject(projectId, { ...opts });
     }));
 
+  program
+    .command("upgrade")
+    .description("Upgrade niro to the latest published version, then refresh the hooks, skills and background watcher that replacing the package leaves untouched.")
+    .option("--finish", "Only refresh hooks, skills and the watcher; do not run npm. `niro upgrade` runs this for you in the new version once the package is replaced.")
+    .option("--from <version>", "The version upgraded from, for the summary line. Set automatically by `niro upgrade`.")
+    .option("--force", "Upgrade the global copy even when you are running a linked or local checkout, which `npm install -g` would replace.")
+    .action((opts) => run(async () => {
+      const upgradeCmd = require("./commands/upgrade");
+      await upgradeCmd.upgrade(opts);
+    }));
+
   const svc = program
     .command("service")
     .description("Manage the niro-watch background daemon (auto-sync on login).");

package/src/lib/mcpClients.js

@@ -0,0 +1,241 @@
+/**
+ * Which AI clients on this machine already have niro registered?
+ *
+ * `niro upgrade` needs this list. The hooks, skills and instruction files an install writes are
+ * fixed text in the user's home folder, not read out of the package as it runs, so replacing the
+ * package leaves them exactly as they were. Putting them back means re-running the installer, and
+ * the installer configures ONE client, named with `--client`. Nothing on disk records which
+ * clients were ever chosen, so the list has to be worked out from what is there.
+ *
+ * Every client in the CLIENTS map is covered, because the installer leaves a file this repo owns
+ * in every case. Eight are registered by writing a JSON config whose path setup.js builds. The
+ * other six are registered by shelling out to another tool's CLI, but each one also gets a marker
+ * appended to a markdown file this repo writes and teardown.js later strips: ~/.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, both written here too. The marker is
+ * appended only after the registration command succeeded, so its presence means the client really
+ * was configured.
+ *
+ * Two rules keep this honest, and both exist because of what got the serve-time self-heal reverted
+ * on 2026-07-30 (d3ff3d8):
+ *
+ *   Every path must be absolute. That revert's worst finding was a settings path resolving against
+ *   the current folder and a project's own git-tracked .claude/settings.json being written. It is
+ *   not enough to check that a home folder exists: HOME can be set to the EMPTY string while
+ *   USERPROFILE is set, and userHome() then returns USERPROFILE and looks fine, while four of the
+ *   path builders in setup.js read process.env.HOME directly and hand back a relative path. So the
+ *   home is rejected unless it is absolute, and each individual path is rejected the same way.
+ *
+ *   Markers are matched on a whole line, never as a substring of prose. That revert also failed on
+ *   substring tests over prose, which captured a user's unrelated hook. A sentence mentioning the
+ *   marker is not an install.
+ *
+ * Everything here is read-only. Nothing in this file creates, writes or deletes anything.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const setup = require("../mcp/setup");
+
+const { CLIENTS, NIRO_MD_MARKER, userHome, gooseConfigPath } = setup;
+
+/**
+ * Biggest file worth reading. None of these configs is more than a few kilobytes, and without a
+ * cap a config path that is a huge file, a FIFO or a symlink to /dev/zero makes `niro upgrade`
+ * hang or allocate without limit rather than reporting a client.
+ */
+const MAX_CONFIG_BYTES = 4 * 1024 * 1024;
+
+/**
+ * The markdown file each shell-registered client gets a niro marker appended to, written by
+ * setup.js after the registration command succeeds and removed by teardown.js. Relative to home.
+ */
+const MARKER_FILES = {
+  "claude-code": [".claude", "CLAUDE.md"],
+  "gemini-cli": [".gemini", "GEMINI.md"],
+  "copilot-cli": [".copilot", "copilot-instructions.md"],
+  factory: [".factory", "AGENTS.md"],
+};
+
+/** The marker on a line of its own. A sentence that merely mentions it is not an install. */
+const MARKER_LINE = new RegExp(
+  `^[ \\t]*${NIRO_MD_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[ \\t]*$`,
+  "m"
+);
+
+/**
+ * The home folder, or null when there is not one that can be trusted.
+ *
+ * Rejects an empty or relative home, and rejects a HOME that is set to the empty string even when
+ * USERPROFILE would fill in, because setup.js's claude-desktop, windsurf, vscode and cline path
+ * builders read process.env.HOME directly and would produce paths relative to the current folder.
+ */
+function homeOrNull() {
+  if (process.env.HOME === "") return null;
+  const home = userHome();
+  return home && path.isAbsolute(home) ? home : null;
+}
+
+/** Read a config file, or null when it is missing, unreadable, not a regular file, or too big. */
+function readConfig(file) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) return null; // a directory, a FIFO, a device
+    if (stat.size > MAX_CONFIG_BYTES) return null;
+    return fs.readFileSync(file, "utf-8");
+  } catch (err) {
+    return null; // missing or unreadable is not evidence of an install
+  }
+}
+
+/**
+ * True when `file` holds a real niro registration under `key`.
+ *
+ * Presence of the key is not enough. An empty object is not a working entry, and `enabled: false`
+ * (opencode) or `disabled: true` (cline) is a registration the user switched OFF. Reporting those
+ * would make `niro upgrade` re-run the installer, which rewrites the whole entry and turns niro
+ * back on without being asked.
+ */
+function jsonHasNiro(file, key) {
+  const raw = readConfig(file);
+  if (raw === null) return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return false;
+  }
+  if (!parsed || typeof parsed !== "object") return false;
+  const section = parsed[key];
+  if (!section || typeof section !== "object") return false;
+  const entry = section.niro;
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  if (entry.disabled === true) return false;
+  if (entry.enabled === false) return false;
+  return Object.keys(entry).length > 0;
+}
+
+/** True when `file` exists and matches `re`. */
+function fileMatches(file, re) {
+  const raw = readConfig(file);
+  return raw === null ? false : re.test(raw);
+}
+
+/**
+ * The JSON config paths worth checking for a client. Antigravity has two: setup.js writes to the
+ * legacy file only while the unified one is absent, so once both exist the builder stops returning
+ * the legacy path and a registration living there becomes invisible. teardown.js already checks
+ * both unconditionally, and the reason is written up in test/mcpClientCoverage.test.js.
+ */
+function jsonPathsFor(id, client, home) {
+  if (id === "antigravity") {
+    return [
+      path.join(home, ".gemini", "antigravity", "mcp_config.json"),
+      path.join(home, ".gemini", "config", "mcp_config.json"),
+    ];
+  }
+  try {
+    return [client.configPath()];
+  } catch (err) {
+    return []; // a path built from an env var this platform does not set
+  }
+}
+
+/**
+ * claude-code leaves two markers and either one is proof: the niro-skill file, and the marked
+ * section in ~/.claude/CLAUDE.md. There is no JSON config to read, because the MCP entry itself
+ * goes in through `claude mcp add`.
+ */
+function claudeCodeConfigured(home) {
+  const skill = path.join(home, ".claude", "skills", "niro-skill", "SKILL.md");
+  try {
+    if (fs.statSync(skill).isFile()) return skill;
+  } catch (err) {
+    // fall through to the CLAUDE.md marker
+  }
+  const memory = path.join(home, MARKER_FILES["claude-code"][0], MARKER_FILES["claude-code"][1]);
+  return fileMatches(memory, MARKER_LINE) ? memory : null;
+}
+
+/** codex registers the [mcp_servers.niro] table in ~/.codex/config.toml. */
+function codexConfigured(home) {
+  const toml = path.join(home, ".codex", "config.toml");
+  return fileMatches(toml, /^\s*\[mcp_servers\.niro\]\s*$/m) ? toml : null;
+}
+
+/**
+ * goose: the same two-space-indented `niro:` line the installer writes and the uninstaller
+ * removes, but only when it sits under the top-level `extensions:` key. The installer's own guard
+ * matches that line anywhere in the file, so a `niro:` nested under some other top-level key reads
+ * as installed; here that would cost a wizard run that rewrites a config the user did not ask us
+ * to touch, so the parent key is checked as well.
+ */
+function gooseConfigured() {
+  let yaml;
+  try {
+    yaml = gooseConfigPath();
+  } catch (err) {
+    return null;
+  }
+  if (!yaml || !path.isAbsolute(yaml)) return null;
+  const raw = readConfig(yaml);
+  if (raw === null) return null;
+
+  let underExtensions = false;
+  for (const line of raw.split(/\r?\n/)) {
+    if (/^\S/.test(line)) underExtensions = /^extensions:\s*$/.test(line);
+    else if (underExtensions && /^ {2}niro:\s*$/.test(line)) return yaml;
+  }
+  return null;
+}
+
+/**
+ * Returns { home, configured }.
+ *
+ *   home        the home folder used, or null when there was no usable one
+ *   configured  [{ id, name, where }] for every client proved to have niro registered
+ */
+function configuredClients() {
+  const home = homeOrNull();
+  // Without a trustworthy home every path below could resolve against the current folder, so a
+  // repo that happens to hold a .claude or .cursor folder would be read as the user's own
+  // settings and then written to. Check nothing rather than check the wrong thing.
+  if (!home) return { home: null, configured: [] };
+
+  const configured = [];
+  const add = (id, where) => {
+    if (!where || !path.isAbsolute(where)) return;
+    configured.push({ id, name: CLIENTS[id] ? CLIENTS[id].name : id, where });
+  };
+
+  for (const [id, client] of Object.entries(CLIENTS)) {
+    if (id === "claude-code") {
+      add(id, claudeCodeConfigured(home));
+    } else if (id === "codex") {
+      add(id, codexConfigured(home));
+    } else if (id === "goose") {
+      add(id, gooseConfigured());
+    } else if (client.configPath || id === "antigravity") {
+      const key = client.topLevelKey || "mcpServers";
+      for (const file of jsonPathsFor(id, client, home)) {
+        if (file && path.isAbsolute(file) && jsonHasNiro(file, key)) {
+          add(id, file);
+          break;
+        }
+      }
+    } else if (MARKER_FILES[id]) {
+      add(id, fileMatches(path.join(home, ...MARKER_FILES[id]), MARKER_LINE)
+        ? path.join(home, ...MARKER_FILES[id])
+        : null);
+    }
+  }
+
+  return { home, configured };
+}
+
+/** Every client id in the CLIENTS map, so a caller can prove none is silently uncovered. */
+function allClientIds() {
+  return Object.keys(CLIENTS);
+}
+
+module.exports = { configuredClients, allClientIds, MARKER_FILES, MAX_CONFIG_BYTES };

package/src/lib/service.js

@@ -152,6 +152,23 @@ function uninstall() {
   return true;
 }
 
+/**
+ * Restart niro-watch so it re-execs its script and picks up a replaced package.
+ *
+ * `npm install -g` swaps the files on disk. A process that is already running keeps the code it
+ * loaded when it started, so after an upgrade the watcher is still on the old version until this
+ * runs. Returns false when PM2 is missing or the restart failed; the caller decides what to say.
+ */
+function restart() {
+  if (!pm2Available()) return false;
+  const r = spawnSync("pm2", ["restart", PROCESS_NAME], {
+    shell: true,
+    stdio: "pipe",
+    encoding: "utf8",
+  });
+  return r.status === 0;
+}
+
 /**
  * Print PM2 process status for niro-watch.
  */
@@ -226,4 +243,4 @@ function getInitSystem() {
   }
 }
 
-module.exports = { install, uninstall, status, processState, pm2Available, installPm2 };
+module.exports = { install, uninstall, restart, status, processState, pm2Available, installPm2 };

package/src/mcp/setup.js

@@ -2783,6 +2783,9 @@ module.exports = {
   addAgentsSkill,
   addAgentsCliSkill,
   CLIENTS,
+  // Exported so `niro upgrade` can detect a configured Goose install by reading the same
+  // file setupGoose writes, instead of rebuilding that platform-specific path a second time.
+  gooseConfigPath,
   NIRO_MD_MARKER,
   NIRO_MD_SECTIONS,
   isNiroPostCompactHook,