@niroai/niro 0.17.0 → 0.18.0

package/src/lib/service.js

@@ -13,6 +13,7 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 const color = require("./color");
+const { system32 } = require("./windowsPaths");
 
 const PROCESS_NAME = "niro-watch";
 
@@ -23,6 +24,9 @@ const PROCESS_NAME = "niro-watch";
  * `niro status` must never do that; flows that go on to run pm2 anyway
  * (install/uninstall) don't care either way.
  */
+/** pm2 is pm2.cmd on Windows, which needs a shell; elsewhere a shell plus an args array trips DEP0190. */
+const PM2_SHELL = process.platform === "win32";
+
 function pm2Available() {
   const probe = process.platform === "win32" ? "where pm2" : "command -v pm2";
   const r = spawnSync(probe, { encoding: "utf8", shell: true, stdio: "pipe" });
@@ -45,111 +49,378 @@ function pm2DaemonAlive() {
   }
 }
 
-/** True when PM2's saved process list (pm2 save) includes niro-watch. */
-function dumpHasProcess() {
+// ─── the watcher's environment ───────────────────────────────────────────────
+//
+// `pm2 start` copies the environment of the pm2 command into the app, and `pm2 save` writes that
+// copy into ~/.pm2/dump.pm2. Run from a developer's shell, that was the whole shell: 291 names in
+// one test home, 79 of them shaped like secrets (cloud keys, tokens, passwords), in a file other
+// users could read. So the pm2 commands that create or save niro-watch are given only the names
+// below. They are what `niro watch`, the engine it starts and the two runtimes under them read:
+//
+//   - the NIRO_ settings niro-cli reads (the four NIRO_*_URL, NIRO_MCP_MODE, the timeouts and
+//     upload limits), named one by one, and every engine setting (NIRO_LOCAL_HOME, NIRO_LOCAL_BIN,
+//     NIRO_LOCAL_*). Not every NIRO_ name: a developer's shell can hold the Niro services' own
+//     settings (a JWT secret, a database password), and in one test home 5 of those got through a
+//     plain NIRO_ prefix. test/serviceWatcherEnv.test.js fails when niro-cli reads a NIRO_ name
+//     that is missing here. NIRO_API_KEY and NIRO_AUDIT_API_KEY are left out on purpose (see
+//     WATCHER_ENV_EXCLUDED): the watcher signs its uploads with the `niro login` token instead.
+//   - HOME and its Windows forms: where ~/.niro, ~/.niro-local and ~/.pm2 are.
+//   - PATH: how the engine and node are found. PM2_HOME: which PM2 this is.
+//   - USER, LOGNAME, USERNAME: who the user is, read by PM2 and by Python.
+//   - LANG, LANGUAGE, LC_*, TZ: how text is decoded and times are shown.
+//   - TMPDIR, TMP, TEMP: where the engine binary unpacks itself and writes temporary files.
+//   - NO_COLOR, FORCE_COLOR: whether the watcher's log has colour codes.
+//   - NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR, the proxy names and NODE_USE_ENV_PROXY:
+//     without them a watcher behind a company proxy or private certificate cannot upload.
+//   - Windows system names, without which node and Python do not start there, and
+//     NoDefaultCurrentDirectoryInExePath (windowsPaths.harden), so cmd.exe never runs a pm2.cmd or
+//     node.exe from the current folder.
+const WATCHER_ENV_NAMES = new Set([
+  "HOME", "USERPROFILE", "HOMEDRIVE", "HOMEPATH", "APPDATA", "LOCALAPPDATA",
+  "PATH", "PM2_HOME",
+  "USER", "LOGNAME", "USERNAME",
+  "LANG", "LANGUAGE", "TZ",
+  "TMPDIR", "TMP", "TEMP",
+  "NO_COLOR", "FORCE_COLOR",
+  "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR",
+  "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "NODE_USE_ENV_PROXY",
+  "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "PROGRAMDATA",
+  "NODEFAULTCURRENTDIRECTORYINEXEPATH",
+  "NIRO_API_URL", "NIRO_MCP_SERVER_URL", "NIRO_BILLING_URL", "NIRO_AUDIT_URL",
+  "NIRO_MCP_MODE", "NIRO_MCP_TRANSPORT", "NIRO_DISABLE_ROUTING",
+  "NIRO_ENGINE_HOME", "NIRO_ENGINE_LOCK_STALE_MS", "NIRO_ENGINE_LOCK_WAIT_MS",
+  "NIRO_LEASE_MIN_RENEW_MS", "NIRO_LEASE_RETRY_MS", "NIRO_LEASE_TIMEOUT_MS",
+  "NIRO_DOCS_TIMEOUT_MS", "NIRO_DOCS_MODEL_TIMEOUT_MS", "NIRO_DELETE_SETTLE_MS",
+  "NIRO_MISSING_CONFIRM_MS", "NIRO_SSE_LIVENESS_MS",
+  "NIRO_UPLOAD_BACKOFF_BASE_MS", "NIRO_UPLOAD_CONCURRENCY", "NIRO_UPLOAD_MAX_FILES",
+  "NIRO_UPLOAD_MAX_TOTAL_BYTES", "NIRO_UPLOAD_TIMEOUT_MS", "NIRO_SHARE_BATCH_FILES",
+]);
+const WATCHER_ENV_PREFIXES = ["NIRO_LOCAL_", "LC_"];
+// NIRO_ names niro-cli reads that hand something from one process to the next, not settings: the
+// bootstrap and upgrade markers of `niro start` / `niro upgrade`, the output indent, and the lease
+// pipe numbers the engine is given by whoever starts it. A watcher that inherited them would act
+// on a handover that was never meant for it.
+// Also the two API keys. When one is set, the coverage audit signs with it instead of the login
+// token (auditUpload.js authHeaders); in a developer's shell it is usually a key for Niro's own
+// services, and it would be saved in dump.pm2. Without them the watcher's audit and journal
+// uploads sign with the `niro login` token (Niraj, 2026-11-06: "yes drop it").
+const WATCHER_ENV_EXCLUDED = new Set([
+  "NIRO_START_BOOTSTRAPPED", "NIRO_UPGRADE_HANDOVER", "NIRO_OUTPUT_PREFIX",
+  "NIRO_LOCAL_LEASE_FD_IN", "NIRO_LOCAL_LEASE_FD_OUT",
+  "NIRO_API_KEY", "NIRO_AUDIT_API_KEY",
+]);
+
+/**
+ * True when the watcher is given this variable. Names are compared in capitals: Windows names are
+ * not case sensitive (`Path`, `SystemRoot`), and proxies are often written in lower case.
+ */
+function watcherNeeds(name) {
+  const upper = String(name).toUpperCase();
+  if (WATCHER_ENV_EXCLUDED.has(upper)) return false;
+  return WATCHER_ENV_NAMES.has(upper) || WATCHER_ENV_PREFIXES.some((p) => upper.startsWith(p));
+}
+
+/** The part of `source` the watcher is started with: the names above, values unchanged. */
+function watcherEnv(source = process.env) {
+  const env = {};
+  for (const [name, value] of Object.entries(source)) {
+    if (value !== undefined && watcherNeeds(name)) env[name] = value;
+  }
+  return env;
+}
+
+/**
+ * Make PM2's saved process list readable by this user only.
+ *
+ * PM2 creates dump.pm2 and dump.pm2.bak with the default file mode (664 under the usual umask)
+ * and afterwards rewrites them in place, which keeps whatever mode they have; so setting 600 once
+ * holds through later `pm2 save` and restart (checked with PM2 7.0.4). After a save niro-cli made,
+ * the backup is also replaced by the dump just written: PM2 fills the backup with the previous
+ * dump, and on an install made before this change that one holds the whole shell environment.
+ */
+function secureDump({ refreshBackup = false } = {}) {
+  const dump = path.join(pm2Home(), "dump.pm2");
+  const backup = path.join(pm2Home(), "dump.pm2.bak");
   try {
-    return fs.readFileSync(path.join(pm2Home(), "dump.pm2"), "utf8").includes(`"${PROCESS_NAME}"`);
+    if (refreshBackup && fs.existsSync(dump)) fs.copyFileSync(dump, backup);
+  } catch {
+    // keep going: the modes below still matter
+  }
+  for (const file of [dump, backup]) {
+    try {
+      if (fs.existsSync(file)) fs.chmodSync(file, 0o600);
+    } catch {
+      // nothing to stop for: niro-watch runs either way
+    }
+  }
+}
+
+/**
+ * True when PM2's saved niro-watch entry holds environment names the watcher is no longer given,
+ * which means a niro-cli from before this change saved it with the whole shell environment.
+ * PM2 adds names of its own (PM2_HOME, PM2_USAGE, unique_id, the app's name): those start with
+ * PM2_ or contain lower case, and are not counted. Neither are the names a shell sets by itself
+ * (PWD, OLDPWD, SHLVL, _): when `pm2` is a shell script (a pnpm global install, an asdf shim),
+ * the shell adds them to the short list on its way to PM2, and counting them restarted the
+ * watcher on every `niro start` (3 of 3 in the check of 2026-11-06). A whole-shell entry still
+ * has plenty of other names (SHELL, TERM, the cloud keys), so it is still caught.
+ */
+const SHELL_OWN_NAMES = new Set(["PWD", "OLDPWD", "SHLVL", "_"]);
+
+function savedEnvIsWide() {
+  let list;
+  try {
+    list = JSON.parse(fs.readFileSync(path.join(pm2Home(), "dump.pm2"), "utf8"));
   } catch {
     return false;
   }
+  if (!Array.isArray(list)) return false;
+  const entry = list.find((p) => p && p.name === PROCESS_NAME);
+  if (!entry || !entry.env || typeof entry.env !== "object") return false;
+  return Object.keys(entry.env).some((name) =>
+    !watcherNeeds(name) && !/^PM2_/i.test(name) && name !== "NODE_APP_INSTANCE" && !SHELL_OWN_NAMES.has(name)
+    && name === name.toUpperCase());
 }
 
 /**
- * Install and start the niro-watch PM2 process, then wire it into the OS
- * startup system. Prints an explanation before each privileged step.
- *
- * Returns true on success, false if PM2 is not installed.
+ * `pm2 start` for niro-watch. On Windows PM2's daemon starts a bare "node" without a shell, which
+ * looks in the folder niro ran from before the PATH, so it is given this node by full path. pm2 runs
+ * through cmd.exe there, and Node joins a shell command's words unquoted, so a path with a space
+ * ("C:\Program Files", a user folder) is quoted. Elsewhere the PATH's node, which keeps working
+ * after a node upgrade.
  */
-function install() {
-  if (!pm2Available()) return false;
+function pm2StartArgs(niroBin, platform = process.platform, node = process.execPath) {
+  if (platform !== "win32") return ["start", niroBin, "--name", PROCESS_NAME, "--", "watch"];
+  const word = (p) => (/\s/.test(p) ? `"${p}"` : p);
+  return ["start", word(niroBin), "--name", PROCESS_NAME, "--interpreter", word(node), "--", "watch"];
+}
 
+/**
+ * Delete, start and save niro-watch with only the environment it needs, then make the saved list
+ * private. Throws when `pm2 start` fails. Never touches the start-on-login hook.
+ */
+function startWatcher() {
   const niroBin = process.argv[1];
+  const env = watcherEnv();
 
   // Stop any existing instance so we can re-register cleanly
-  spawnSync("pm2", ["delete", PROCESS_NAME], { shell: true, stdio: "pipe" });
+  spawnSync("pm2", ["delete", PROCESS_NAME], { shell: PM2_SHELL, stdio: "pipe", env });
 
   // PM2's own output is captured, not inherited. Inheriting it put ~55 lines into the middle
   // of setup: a box-drawing process table, the entire generated systemd unit file, and the
   // user's PATH twice. None of it is ours and none of it is actionable while it is working.
   // It IS printed on failure, where it is the only diagnostic there is.
-  const startResult = spawnSync(
-    "pm2",
-    ["start", niroBin, "--name", PROCESS_NAME, "--", "watch"],
-    { shell: true, encoding: "utf8" }
-  );
+  const startResult = spawnSync("pm2", pm2StartArgs(niroBin), { shell: PM2_SHELL, encoding: "utf8", env });
   if (startResult.status !== 0) {
     console.error(color.dim(`${startResult.stdout || ""}${startResult.stderr || ""}`));
     throw new Error("pm2 start failed");
   }
 
   // Persist the process list so PM2 restores it after a manual `pm2 resurrect`
-  spawnSync("pm2", ["save"], { shell: true, encoding: "utf8" });
+  const saved = spawnSync("pm2", ["save"], { shell: PM2_SHELL, encoding: "utf8", env });
+  secureDump({ refreshBackup: saved.status === 0 });
+}
+
+/**
+ * For an install made before the watcher's environment was limited: when the saved niro-watch
+ * entry still holds the whole shell environment, start it again with the limited one, which
+ * rewrites dump.pm2 and its backup; otherwise only make the saved list private. Returns true when
+ * it started the watcher again. Asks for no password and leaves the start-on-login hook alone.
+ */
+function refreshSavedEnv() {
+  if (!pm2Available()) return false;
+  if (!savedEnvIsWide()) {
+    secureDump();
+    return false;
+  }
+  startWatcher();
+  return true;
+}
+
+/** True when PM2's saved process list (pm2 save) includes niro-watch. */
+function dumpHasProcess() {
+  try {
+    return fs.readFileSync(path.join(pm2Home(), "dump.pm2"), "utf8").includes(`"${PROCESS_NAME}"`);
+  } catch {
+    return false;
+  }
+}
+
+// ─── start on login, Windows ─────────────────────────────────────────────────
+//
+// `pm2 startup` knows systemd and launchd, not Windows: there it prints no command, which the
+// install below used to read as "already configured" while nothing would start at login. So on
+// Windows, and only there, one value under the user's own Run key starts PM2's saved list
+// (`pm2 resurrect`) at every login: per user, no administrator rights, removed by uninstall.
+const WINDOWS_RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+
+/**
+ * The Run-key value that starts niro-watch at login on Windows: its name and the command it runs.
+ *
+ * `pm2Cmd`: pm2.cmd's full path, found on the PATH when the entry is written. At sign-in Windows uses the saved PATH,
+ * which may not hold npm's folder (a PATH set only in a shell profile, some nvm, Volta or Scoop set-ups), so a bare
+ * name could go unfound and the watcher silently not start. Only when none is found is the bare name used.
+ */
+function windowsLoginEntry(pm2Cmd = require("./engine").onThePath("pm2.cmd")) {
+  // ponytail: a hidden PowerShell may flash for a moment at login; a VBScript launcher would hide
+  // it completely, add it if people notice.
+  // pm2.cmd, not pm2: PowerShell would pick npm's pm2.ps1, and Windows 10 and 11 refuse to run
+  // scripts by default (Restricted), so nothing would start and nothing would say so.
+  // A full path is called with PowerShell's & on a single-quoted string, where a quote is doubled.
+  const run = pm2Cmd ? `"& '${pm2Cmd.replace(/'/g, "''")}' resurrect"` : "pm2.cmd resurrect";
+  return {
+    key: WINDOWS_RUN_KEY,
+    name: PROCESS_NAME,
+    command: `powershell.exe -NoProfile -WindowStyle Hidden -Command ${run}`,
+  };
+}
+
+/** Add the Run-key value. True on success, "no_autostart" (the watcher still runs) otherwise. */
+function startOnWindowsLogin(run = spawnSync) {
+  const entry = windowsLoginEntry();
+  const r = run(system32("reg.exe"), ["add", entry.key, "/v", entry.name, "/t", "REG_SZ", "/d", entry.command, "/f"], {
+    stdio: "pipe", encoding: "utf8",
+  });
+  if (r.status !== 0) {
+    console.log(color.yellow(`  ⚠ Could not set niro-watch to start on login: ${(r.stderr || r.stdout || "").trim()}`));
+    return "no_autostart";
+  }
+  console.log(`  ${color.green("✓")} Starts again at every login.`);
+  return true;
+}
+
+/**
+ * Remove the Run-key value: `{ hook: "none" }` when it is not there, `"removed"`, or `"manual"` with
+ * the command when reg refuses (asked first, so a refusal is never reported as nothing there).
+ */
+function stopOnWindowsLogin(run = spawnSync) {
+  const entry = windowsLoginEntry();
+  const reg = system32("reg.exe");
+  if (run(reg, ["query", entry.key, "/v", entry.name], { stdio: "pipe" }).status !== 0) return { hook: "none" };
+  if (run(reg, ["delete", entry.key, "/v", entry.name, "/f"], { stdio: "pipe" }).status === 0) return { hook: "removed" };
+  return { hook: "manual", command: `reg delete "${entry.key}" /v ${entry.name} /f` };
+}
+
+/**
+ * What to show before sudo runs, and its `-p` prompt as one single-quoted shell word. sudo itself
+ * names the account whose password it wants (%p): the user's own, or root's where sudo is set to
+ * ask for that (targetpw, rootpw), and no user lookup is needed (os.userInfo throws in a container
+ * with no passwd entry).
+ *
+ * `sameLineAs`: the heading printed just above (niro start), with nothing after it yet. niro goes
+ * back up a line and rewrites it ending " · ", so heading and question share a line. The prompt
+ * itself never moves the cursor: sudo repeats it after a wrong password, and a cursor-up in it
+ * erased sudo's "Sorry, try again." When sudo still remembers the password it prints no prompt,
+ * so the heading is left alone (`sudo -n true` asks without prompting).
+ */
+function sudoLead(sameLineAs, pad, run = spawnSync) {
+  const quoted = (words) => `'${words.replace(/'/g, "'\\''")}'`;
+  const ask = "Password for %p: ";
+  if (sameLineAs && run("sudo", ["-n", "true"], { stdio: "ignore" }).status !== 0) {
+    return { before: `\x1b[1A\x1b[2K${sameLineAs} · `, prompt: quoted(ask) };
+  }
+  return { before: "", prompt: quoted(`${pad}${ask}`) };
+}
+
+/**
+ * Install and start the niro-watch PM2 process, then wire it into the OS
+ * startup system. Prints an explanation before each privileged step.
+ *
+ * Returns true on success, "no_autostart" when niro-watch runs but could not be added to the
+ * OS startup (still truthy: the daemon is up), false if PM2 is not installed.
+ */
+function install({ sameLineAs = null } = {}) {
+  if (!pm2Available()) return false;
+
+  startWatcher();
+
+  if (process.platform === "win32") return startOnWindowsLogin();
 
   // Wire into OS startup — pm2 startup detects systemd / launchd / etc.
   // It prints the exact privileged command we need to run.
-  console.log(
-    `\n    ${color.bold("Setting up auto-start on login")} — PM2 will ask for your password to register`
-  );
-  console.log(
-    `    with the system startup manager (${getInitSystem()}). This only needs to happen once.\n`
-  );
-
   const startupProbe = spawnSync("pm2", ["startup"], {
-    shell: true,
+    shell: PM2_SHELL,
     encoding: "utf8",
   });
 
   const setupCmd = extractSetupCommand(startupProbe.stdout + startupProbe.stderr);
   if (setupCmd) {
-    console.log(`    Running: ${color.dim(setupCmd)}\n`);
+    // sudo's own prompt says what the password is for, instead of a paragraph and the command.
+    // Spaces, not the rail: sudo mangles the multi-byte "│" in its prompt.
+    const pad = " ".repeat(require("./nestedOutput").currentPad().length + 2);
+    const lead = sudoLead(sameLineAs, pad);
+    const cmd = setupCmd.replace(/^sudo /, `sudo -p ${lead.prompt} `);
+    // pm2 writes its launchd plist before it runs its own `mkdir -p`, so a home without
+    // ~/Library/LaunchAgents (a new account) fails with ENOENT. Make the folder first.
+    if (process.platform === "darwin") {
+      fs.mkdirSync(path.join(os.homedir(), "Library", "LaunchAgents"), { recursive: true });
+    }
     // stdio is split: stdin stays connected so sudo can still prompt for the password, but
     // PM2's forty lines of generated unit file are captured and only shown if it fails.
-    const r = spawnSync(setupCmd, {
+    if (lead.before) process.stdout.write(lead.before);
+    const r = spawnSync(cmd, {
       shell: true,
       stdio: ["inherit", "pipe", "pipe"],
       encoding: "utf8",
     });
     if (r.status !== 0) {
-      console.error(color.dim(`${r.stdout || ""}${r.stderr || ""}`));
-      console.log(
-        color.yellow(
-          `    ⚠ Startup hook failed (exit ${r.status}). You can run it manually:\n    ${setupCmd}`
-        )
-      );
+      // PM2's output here is its whole generated plist/unit file; the last line is the reason.
+      const reason = `${r.stdout || ""}${r.stderr || ""}`.trim().split("\n").pop();
+      console.log(color.yellow(`  ⚠ Could not set niro-watch to start on login${reason ? `: ${reason}` : ""}`));
+      console.log(color.dim(`  To retry: ${setupCmd}`));
+      return "no_autostart";
     }
   } else {
     // PM2 may print nothing if startup is already configured
-    console.log(`    ${color.green("✓")} Startup already configured.`);
+    console.log(`  ${color.green("✓")} Startup already configured.`);
   }
 
   return true;
 }
 
 /**
- * Stop niro-watch and remove it from PM2 + OS startup hooks.
+ * Stop niro-watch and take it out of PM2, quietly, without asking for a password.
+ *
+ * PM2's start-on-login entry belongs to PM2, not to Niro: it starts every app in PM2's saved
+ * list. Once niro-watch is out of that list (`pm2 save --force`, so an empty list is saved too),
+ * nothing of Niro's starts on login, so the entry is left alone while other PM2 apps use it. When
+ * niro-watch was the only one, the entry goes too: on macOS by unloading and deleting the user's
+ * own launchd file, which needs no password; elsewhere it needs root, so the command is returned
+ * for the caller to show rather than prompting for a password in the middle of an uninstall.
+ *
+ * Returns false when PM2 is not installed (nothing to remove), else
+ * `{ hook: "removed" | "kept" | "none" | "manual", command? }`.
  */
 function uninstall() {
   if (!pm2Available()) return false;
+  const quiet = { shell: PM2_SHELL, stdio: "pipe", encoding: "utf8" };
+  spawnSync("pm2", ["delete", PROCESS_NAME], quiet);
+  const saved = spawnSync("pm2", ["save", "--force"], quiet);
+  // The backup PM2 just made is the list from before, niro-watch's environment included.
+  secureDump({ refreshBackup: saved.status === 0 });
 
-  spawnSync("pm2", ["delete", PROCESS_NAME], { shell: true, stdio: "inherit" });
-  spawnSync("pm2", ["save"], { shell: true, stdio: "inherit" });
+  const listed = spawnSync("pm2", ["jlist"], quiet);
+  let others = 0;
+  try { others = JSON.parse(listed.stdout || "[]").length; } catch { others = 1; /* unsure: keep it */ }
+  if (others > 0) return { hook: "kept" };
 
-  console.log(
-    `\n    ${color.bold("Removing auto-start hook")} — PM2 may ask for your password.\n`
-  );
-  const unstartupResult = spawnSync("pm2", ["unstartup"], {
-    shell: true,
-    encoding: "utf8",
-  });
-  const setupCmd = extractSetupCommand(
-    unstartupResult.stdout + unstartupResult.stderr
-  );
-  if (setupCmd) {
-    console.log(`    Running: ${color.dim(setupCmd)}\n`);
-    spawnSync(setupCmd, { shell: true, stdio: "inherit" });
-  }
+  if (process.platform === "win32") return stopOnWindowsLogin();
 
-  return true;
+  if (process.platform === "darwin") {
+    const user = os.userInfo().username;
+    const plist = path.join(os.homedir(), "Library", "LaunchAgents", `pm2.${user}.plist`);
+    if (!fs.existsSync(plist)) return { hook: "none" };
+    spawnSync("launchctl", ["unload", "-w", plist], { stdio: "pipe" });
+    try {
+      fs.unlinkSync(plist);
+      return { hook: "removed" };
+    } catch {
+      // fall through to the command
+    }
+  }
+  const probe = spawnSync("pm2", ["unstartup"], quiet);
+  const command = extractSetupCommand(`${probe.stdout || ""}${probe.stderr || ""}`);
+  return command ? { hook: "manual", command } : { hook: "none" };
 }
 
 /**
@@ -157,16 +428,38 @@ function uninstall() {
  *
  * `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.
+ * runs. It registers the script of the niro running this (process.argv[1]); during
+ * `niro upgrade --finish` that is the copy just installed. Returns false when PM2 is missing or
+ * the start 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;
+  // Not `pm2 restart`: that keeps the environment saved when the watcher was first started, which
+  // on an install from before 2026-11-06 is the whole shell. Delete, start and save instead, with
+  // the short list, then make the saved list private. No `pm2 startup`, so no password prompt.
+  try {
+    startWatcher();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * When the running niro-watch process started, in ms since the epoch, or null when PM2 cannot
+ * say. Compared with the install time of this copy to tell a watcher still on old code.
+ */
+function startedAt() {
+  if (!pm2Available() || !pm2DaemonAlive()) return null;
+  const r = spawnSync("pm2", ["jlist"], { shell: PM2_SHELL, stdio: "pipe", encoding: "utf8" });
+  if (r.status !== 0) return null;
+  try {
+    const proc = JSON.parse(r.stdout).find((p) => p.name === PROCESS_NAME);
+    const at = proc && proc.pm2_env && proc.pm2_env.pm_uptime;
+    return typeof at === "number" ? at : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -177,7 +470,7 @@ function status() {
     console.log(color.yellow("    PM2 is not installed. Run: npm install -g pm2"));
     return;
   }
-  spawnSync("pm2", ["show", PROCESS_NAME], { shell: true, stdio: "inherit" });
+  spawnSync("pm2", ["show", PROCESS_NAME], { shell: PM2_SHELL, stdio: "inherit" });
 }
 
 /**
@@ -196,7 +489,7 @@ function processState() {
     return dumpHasProcess() ? "stopped" : "missing";
   }
   const r = spawnSync("pm2", ["show", PROCESS_NAME], {
-    shell: true,
+    shell: PM2_SHELL,
     encoding: "utf8",
     stdio: "pipe",
   });
@@ -209,8 +502,14 @@ function processState() {
  * the user sees progress and any permission error verbatim. Returns true on
  * success. shell:true so npm.cmd resolves on Windows.
  */
-function installPm2() {
-  const r = spawnSync("npm", ["install", "-g", "pm2"], { shell: true, stdio: "inherit" });
+function installPm2({ quiet = false } = {}) {
+  const r = spawnSync("npm", ["install", "-g", "pm2"], {
+    shell: process.platform === "win32",
+    stdio: quiet ? "pipe" : "inherit",
+    encoding: "utf8",
+  });
+  // quiet: npm's lines are shown only when it failed, where they are the only diagnostic.
+  if (quiet && r.status !== 0) console.log(color.dim(`${r.stdout || ""}${r.stderr || ""}`.trim()));
   return r.status === 0;
 }
 
@@ -243,4 +542,14 @@ function getInitSystem() {
   }
 }
 
-module.exports = { install, uninstall, restart, status, processState, pm2Available, installPm2 };
+module.exports = {
+  windowsLoginEntry,
+  startOnWindowsLogin,
+  stopOnWindowsLogin,
+  pm2StartArgs,
+  sudoLead,
+  install, uninstall, restart, startedAt, status, processState, pm2Available, installPm2,
+  refreshSavedEnv,
+  // exported for tests
+  watcherEnv, savedEnvIsWide, secureDump,
+};