@niroai/niro 0.11.0 → 0.13.0

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/folderSync.js

@@ -36,6 +36,7 @@ const color = require("./color");
 const BATCH_SIZE = 50;
 const SOURCE_EXTENSIONS = new Set([
   ".java", ".py", ".go", ".js", ".ts", ".tsx", ".jsx",
+  ".cjs", ".mjs", ".cts", ".mts",
   ".kt", ".scala", ".rs", ".rb", ".php", ".cs", ".swift",
   ".c", ".cpp", ".h", ".hpp", ".dart",
 ]);

package/src/lib/impactLog.js

@@ -0,0 +1,251 @@
+/**
+ * Record of the impact checks an agent made through the bridge, read by the Edit|Write impact gate.
+ *
+ * Why this exists: CLAUDE.md, the niro skill and the UserPromptSubmit hook all tell the agent to map
+ * who depends on code before changing it (get_blast_radius, get_impact_analysis). Prose decays over a
+ * session: the agent obeys early, then reads a method with sed and edits it. Niraj, 2026-09-04: "I
+ * always felt that before you make any code changes in any method you would want to check what's
+ * the impact of that but you hardly ever care to check." The only thing that survives a long session
+ * is a check at the moment of the edit. The PreToolUse hook in setup.js (NIRO_IMPACT_COMMAND) is that
+ * check, and it needs evidence of what the agent actually called. The bridge sees every tools/call and
+ * every answer, so it keeps that evidence here.
+ *
+ * What is written: one JSON line per answered impact call under ~/.niro/impact/<key>.jsonl, where
+ * <key> is the bridge's working directory, symlinks resolved, with every byte that is not an ASCII
+ * letter or digit replaced by "-". The hook derives the same key from the payload's cwd with
+ * `cd -P` and `tr -c 'A-Za-z0-9' '-'`, so the two sides agree without sharing code (tested in
+ * test/impactGateHook.test.js). A line carries the tool name, the names the agent asked about
+ * (method_fqn, class_fqn and friends) and every source path the answer mentioned. Lines older than
+ * WINDOW_MS are pruned on every write, so the file cannot grow past one hour of checks.
+ *
+ * Liveness: <key>.alive is touched whenever the server answers. The hook denies an unchecked edit only
+ * while that file is fresh; with the bridge gone it can only advise, so Niro being unreachable never
+ * blocks an edit. Fail-open by design.
+ *
+ * Every function here swallows filesystem errors: this sits on the message path between the host and
+ * the server, and a full disk or an unwritable home must cost the gate and nothing else.
+ */
+const fs = require("fs");
+const path = require("path");
+const { niroHome } = require("./receiptStore");
+
+/** The calls that count as "checked who depends on it". Downstream-only walks (get_call_chain) do not. */
+const IMPACT_TOOLS = new Set(["get_blast_radius", "get_impact_analysis", "get_reverse_call_chain"]);
+/** How long a recorded check keeps a file unlocked. */
+const WINDOW_MS = 60 * 60 * 1000;
+const MAX_LINES = 500;
+const MAX_NAMES = 50;
+const MAX_FILES = 200;
+const MAX_IN_FLIGHT = 100;
+/** The alive file is rewritten at most this often; answers arrive far more frequently than that. */
+const ALIVE_TOUCH_MIN_MS = 10 * 1000;
+/** Argument names across the impact tools that carry what the agent asked about. */
+const NAME_ARGS = [
+  "method_fqn", "method_fqns", "class_fqn", "entity_fqn", "entity_fqns", "fqn", "fqns", "targets",
+  "http_path", "event_fqn",
+];
+const SOURCE_EXT = "java|js|mjs|cjs|ts|tsx|jsx|py|go|rb|kt|kts|cs|php|rs|scala|swift|c|cc|cpp|h|hpp";
+/**
+ * A source path inside an answer: optional leading "/", slash-separated segments, a known extension,
+ * bounded by whitespace, quotes, brackets, ":" or ",". The ":" lets `repo::src/a/B.java` yield the
+ * repo-relative path, which is what the hook compares against the edited file's path.
+ */
+const PATH_RE = new RegExp(
+  "(?:^|[\\s\"'(:,])(/?(?:[A-Za-z0-9_.\\-]+/)*[A-Za-z0-9_.\\-]+\\.(?:" + SOURCE_EXT + "))(?=$|[\\s\"'),:])",
+  "g",
+);
+
+function impactDir() {
+  return path.join(niroHome(), "impact");
+}
+
+/** Presence of this file switches the gate off for every session on this machine. */
+function offSwitchPath() {
+  return path.join(niroHome(), "impact-gate-off");
+}
+
+/**
+ * The per-folder key, byte for byte what `printf '%s' "$(cd -P dir && pwd -P)" | tr -c 'A-Za-z0-9' '-'`
+ * produces. Byte-based on purpose: tr works on bytes, so a non-ASCII character becomes several dashes
+ * there and must here too, or the hook looks for a file the bridge never wrote.
+ */
+function keyForCwd(cwd) {
+  let real = String(cwd || "");
+  try {
+    real = fs.realpathSync(real);
+  } catch (_) {
+    /* a folder that does not exist keeps its lexical path, as the hook's `cd -P || printf` fallback does */
+  }
+  let out = "";
+  for (const b of Buffer.from(real, "utf8")) {
+    const alnum = (b >= 48 && b <= 57) || (b >= 65 && b <= 90) || (b >= 97 && b <= 122);
+    out += alnum ? String.fromCharCode(b) : "-";
+  }
+  return out;
+}
+
+function logPathFor(cwd) {
+  return path.join(impactDir(), keyForCwd(cwd) + ".jsonl");
+}
+
+function alivePathFor(cwd) {
+  return path.join(impactDir(), keyForCwd(cwd) + ".alive");
+}
+
+function toolNameOf(message) {
+  if (!message || message.method !== "tools/call" || !message.params) return null;
+  return typeof message.params.name === "string" ? message.params.name : null;
+}
+
+function isImpactCall(message) {
+  const name = toolNameOf(message);
+  return !!name && IMPACT_TOOLS.has(name);
+}
+
+/** The strings the agent asked about, deduplicated and bounded; routing extras like _niroPin are ignored. */
+function namesFromArgs(args) {
+  const out = [];
+  const push = (v) => {
+    if (typeof v !== "string") return;
+    const s = v.trim().slice(0, 300);
+    if (s && !out.includes(s)) out.push(s);
+  };
+  if (args && typeof args === "object") {
+    for (const key of NAME_ARGS) {
+      const v = args[key];
+      if (Array.isArray(v)) v.forEach(push);
+      else push(v);
+    }
+  }
+  return out.slice(0, MAX_NAMES);
+}
+
+/** All text parts of a tool result, joined; "" for anything that is not a text result. */
+function resultText(msg) {
+  const content = msg && msg.result && msg.result.content;
+  if (!Array.isArray(content)) return "";
+  return content.map((c) => (c && typeof c.text === "string" ? c.text : "")).join("\n");
+}
+
+/** Every distinct source path an answer mentions, in order of appearance, bounded. */
+function filesFromResultText(text) {
+  const out = [];
+  if (typeof text !== "string" || !text) return out;
+  PATH_RE.lastIndex = 0;
+  let m;
+  while ((m = PATH_RE.exec(text)) && out.length < MAX_FILES) {
+    if (!out.includes(m[1])) out.push(m[1]);
+  }
+  return out;
+}
+
+/** Drop lines older than the window, then cap the count; the newest lines win. */
+function pruneLines(lines, now) {
+  const cutoff = now - WINDOW_MS;
+  const kept = lines.filter((line) => {
+    const m = /"ts":(\d+)/.exec(line);
+    return !!m && Number(m[1]) >= cutoff;
+  });
+  return kept.length > MAX_LINES ? kept.slice(kept.length - MAX_LINES) : kept;
+}
+
+/** Append one record, pruning first. Returns false, never throws, when the file cannot be written. */
+function appendRecord(file, record, now) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    let lines = [];
+    try {
+      lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    } catch (_) {
+      /* first record for this folder */
+    }
+    lines = pruneLines(lines, now);
+    lines.push(JSON.stringify(record));
+    fs.writeFileSync(file, lines.join("\n") + "\n", { mode: 0o600 });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * One recorder per bridge process. `noteRequest` on every outgoing message, `noteResult` and
+ * `touchAlive` on every incoming one; each returns true only when it wrote something, which the
+ * tests use and the bridge ignores.
+ */
+function createImpactRecorder({ cwd = process.cwd(), now = Date.now } = {}) {
+  const inFlight = new Map();
+  let lastAlive = 0;
+  return {
+    noteRequest(message) {
+      if (!isImpactCall(message) || message.id === undefined || message.id === null) return false;
+      const args = message.params.arguments || {};
+      inFlight.set(message.id, { tool: message.params.name, names: namesFromArgs(args), ts: now() });
+      if (inFlight.size > MAX_IN_FLIGHT) inFlight.delete(inFlight.keys().next().value);
+      return true;
+    },
+    noteResult(msg) {
+      if (!msg || msg.id === undefined || msg.id === null) return false;
+      const meta = inFlight.get(msg.id);
+      if (!meta) return false;
+      inFlight.delete(msg.id);
+      // An error answer is still recorded: the agent asked, which is the behaviour the gate exists to
+      // produce, and a name the server could not resolve must not leave the file locked.
+      const files = filesFromResultText(resultText(msg));
+      return appendRecord(logPathFor(cwd), { ts: meta.ts, tool: meta.tool, names: meta.names, files }, now());
+    },
+    clearAlive() {
+      try {
+        fs.rmSync(alivePathFor(cwd), { force: true });
+        return true;
+      } catch (_) {
+        return false;
+      }
+    },
+    touchAlive() {
+      const t = now();
+      if (t - lastAlive < ALIVE_TOUCH_MIN_MS) return false;
+      lastAlive = t;
+      try {
+        fs.mkdirSync(impactDir(), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(alivePathFor(cwd), String(t), { mode: 0o600 });
+        return true;
+      } catch (_) {
+        return false;
+      }
+    },
+  };
+}
+
+/** Remove the evidence files and the off switch. Used by `niro mcp uninstall`. Best effort. */
+function purge() {
+  try {
+    fs.rmSync(impactDir(), { recursive: true, force: true });
+  } catch (_) {
+    /* best effort */
+  }
+  try {
+    fs.rmSync(offSwitchPath(), { force: true });
+  } catch (_) {
+    /* best effort */
+  }
+}
+
+module.exports = {
+  purge,
+  IMPACT_TOOLS,
+  WINDOW_MS,
+  MAX_LINES,
+  keyForCwd,
+  impactDir,
+  offSwitchPath,
+  logPathFor,
+  alivePathFor,
+  isImpactCall,
+  namesFromArgs,
+  resultText,
+  filesFromResultText,
+  pruneLines,
+  appendRecord,
+  createImpactRecorder,
+};