@niroai/niro 0.10.1 → 0.11.0

package/src/lib/takeoverRestore.js

@@ -0,0 +1,156 @@
+/**
+ * Undoing a takeover locally: point a folder's registration back at the source project.
+ *
+ * This is the LOCAL half of discarding a temporary project. The server half (deleting the copy) is
+ * `niro discard-temp-project`; the sweep that finds copies already gone from the server is
+ * `niro cleanup-temp-projects`. Both end in exactly this loop, so it lives here rather than in
+ * either command. Copying it would be the worst option available: the two comments below record
+ * incidents that cost silent data loss, and a second copy is a second place for that reasoning to
+ * rot out of step with the first.
+ *
+ * It never contacts the server and it never deletes a registration. A folder whose temporary project
+ * is gone still needs to be synced to SOMETHING, so it is moved back to the source project rather
+ * than unregistered.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const niroProjectFile = require("./niroProjectFile");
+const watchState = require("./watchState");
+
+/**
+ * Order a group so that folders carrying a takeover backup are written LAST.
+ *
+ * The backup is the only thing on this machine that says "this project id is a temporary project".
+ * Restoring a folder spends its backup, so if the one folder holding the group's backup is written
+ * first and the run then stops (Ctrl-C, a closed lid, a full disk), the rest of the group becomes
+ * invisible: `niro cleanup-temp-projects` no longer recognises the id as a temporary project and
+ * reports "nothing to clean up", while `niro discard-temp-project` refuses because no folder records
+ * what the copy was made from. The only repair left is editing the JSON by hand.
+ *
+ * Writing the witnesses last means an interrupted run always leaves at least one behind, so the next
+ * run finds the group and finishes the job. Order within each half is untouched.
+ */
+function witnessesLast(folders) {
+  const withoutBackup = folders.filter((e) => !(e.takeover && e.takeover.sourceProjectId));
+  const withBackup = folders.filter((e) => e.takeover && e.takeover.sourceProjectId);
+  return [...withoutBackup, ...withBackup];
+}
+
+/**
+ * Move every folder in `folders` off `tempProjectId` and back onto its source project.
+ *
+ * @param {Array<object>} folders  watchState entries (each with `folderPath`), all registered
+ *                                 against the same temporary project.
+ * @param {object}  opts
+ * @param {string}  opts.tempProjectId  the temporary project being undone.
+ * @param {string}  opts.cloneOf        the source project id, used for any folder whose own
+ *                                      takeover backup does not name one.
+ * @param {string}  opts.baseUrl        backend to tag an entry with when it carries no apiUrl.
+ * @param {boolean} opts.healPins       write/delete an old-style swapped `.niro-project`. TRUE for
+ *                                      an interactive discard, FALSE for the unattended sweep — it
+ *                                      touches a git-tracked file in the developer's repo.
+ * @returns {{ repinned: string[], healed: Array<{folder: string, to: string}>,
+ *             failed: Array<{folder: string, error: string}>,
+ *             skipped: Array<{folder: string, nowGitId: string|null}>,
+ *             untracked: string[] }}
+ */
+function restoreFolders(folders, { tempProjectId, cloneOf, baseUrl, healPins = true } = {}) {
+  // ADR-018: the .niro-project file is left ALONE unless it still carries the OLD-STYLE swapped pin
+  // (pre-ADR-018 takeover) — then it points at a now-deleted project and must be healed: previousPin
+  // verbatim when recorded; explicit "no pin existed" → delete the file; otherwise the source project
+  // id. New-style folders (pin untouched) skip all of this.
+  const repinned = [];
+  const healed = [];
+  const failed = [];
+  const skipped = [];
+  const untracked = [];
+  for (const e of witnessesLast(folders)) {
+    try {
+      const backup = e.takeover || {};
+      const sourceProjectId = backup.sourceProjectId || cloneOf;
+      const entryDir = path.resolve(e.folderPath);
+
+      // Compare-and-write, exactly as watchState.remove does its compare-and-delete, and for the
+      // reason its own comment gives: a folder can be re-pointed by ANOTHER PROCESS between the read
+      // that produced `e` and this write. The sweep makes that window wide, because it reads the whole
+      // registry once and then does a server round-trip per temporary project before writing anything.
+      //
+      // What it costs to get wrong is not a stale row. A `niro new-temp-project` landing mid-sweep
+      // would be overwritten: its brand new copy is then named by no entry at all, so discard cannot
+      // find it and a later sweep cannot see it, AND the folder is left pointing at the SHARED source
+      // project's repo with an empty baseline — so the next daemon pass uploads the private
+      // feature-branch tree into the project the whole team reads.
+      //
+      // A missing entry is deliberately NOT a mismatch. `niro discard-temp-project --project <id>` can
+      // be run in a folder that has no registration yet, and creating one there is existing, intended
+      // behaviour. Only a DIFFERENT gitId means somebody re-pointed this folder under us.
+      const current = watchState.peek(e.folderPath);
+      if (current && current.gitId !== e.gitId) {
+        skipped.push({ folder: e.folderPath, nowGitId: current.gitId || null });
+        continue;
+      }
+
+      // healPins is FALSE for the unattended sweep, and that is the whole point of the option. This
+      // block writes and DELETES `.niro-project`, a file tracked in the developer's git repository. It
+      // is right for `niro discard-temp-project`, which a person just ran in that folder; it is not
+      // something a six-hourly background job should do. A fourth review found the sweep reaching it —
+      // through this module — while a test and four documents claimed pins were never touched.
+      if (healPins && fs.existsSync(entryDir)) {
+        const pin = niroProjectFile.read(entryDir);
+        const pinIsSwapped = pin && pin.id === tempProjectId
+            && path.dirname(pin.source) === entryDir; // only heal THIS folder's own pin, never a parent's
+        if (pinIsSwapped) {
+          const recordedNoPin = ("previousPin" in backup) && backup.previousPin === null;
+          if (backup.previousPin) {
+            niroProjectFile.write(entryDir, backup.previousPin, { overwrite: true });
+            healed.push({ folder: e.folderPath, to: backup.previousPin });
+          } else if (recordedNoPin) {
+            niroProjectFile.remove(entryDir);
+            healed.push({ folder: e.folderPath, to: "(no pin — removed)" });
+          } else {
+            niroProjectFile.write(entryDir, sourceProjectId, { overwrite: true });
+            healed.push({ folder: e.folderPath, to: sourceProjectId });
+          }
+        }
+      }
+
+      // Watch/daemon registration goes back to the source project regardless of pin style.
+      watchState.set(e.folderPath, {
+        ...e,
+        gitId: backup.previousGitId || null,
+        projectId: sourceProjectId,
+        // The baseline describes what the TEMPORARY project holds, so it MUST NOT survive the move
+        // back to the source repo. Carrying it across told the daemon the source already had every
+        // file at its sandbox-era fingerprint — which it did not, because those edits only ever went
+        // to the temporary copy. The next pass then compared disk against that baseline, found no
+        // difference, and uploaded nothing. Every edit made during the temporary project was silently
+        // lost to the source project, with no error and nothing to prompt a re-sync.
+        //
+        // Clearing it makes the next pass treat every file as new and upload it. That is a full
+        // re-upload once, which is the cost of being sure: the client cannot know which files the
+        // source repo is missing, so the only safe assumption is all of them.
+        //
+        // The opposite direction already gets this right — takeover.js seeds fileHashes with what it
+        // actually uploaded to the new gitId. A baseline belongs to ONE gitId; when that changes, so
+        // must it.
+        fileHashes: {},
+        lastSyncedAt: null,
+        takeover: undefined,
+      }, e.apiUrl || baseUrl);
+      repinned.push(e.folderPath);
+      // No repo id to go back to means this folder had no local registration BEFORE it was taken over
+      // (takeover.js records `previousGitId: existing ? existing.gitId : null`). Restoring null is
+      // therefore correct — it is the state the folder was in before — but the entry is now inert:
+      // watchState.allLocal filters on gitId, so the daemon stops listing it. Callers report these
+      // separately rather than counting them as "repaired and syncing", because the honest sentence is
+      // "back where it was, and not locally tracked", not "fixed".
+      if (!backup.previousGitId) untracked.push(e.folderPath);
+    } catch (err) {
+      failed.push({ folder: e.folderPath, error: err.message });
+    }
+  }
+  return { repinned, healed, failed, skipped, untracked };
+}
+
+module.exports = { restoreFolders, witnessesLast };

package/src/mcp/setup.js

@@ -53,16 +53,27 @@ const NIRO_MD_MARKER = "<!-- niro-mcp -->";
 const NIRO_EXPLORE_FIRST_SENTENCE = "MUST FOLLOW: before you run grep, find, glob, or open a file to hunt for something, first check whether a Niro tool answers it (code_grep for content search, resolve_fqn and get_source_code for a known symbol, find_handler and find_api_endpoints for entry points). Use the connection tools (get_call_chain, get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topology) to understand how code connects BEFORE deciding which file to read or search next, rather than reading files to rebuild that picture by hand. Native search is the fallback for what Niro does not cover (config files, docs, logs, generated output, non-code text) or when the tools are unavailable. This rule does not expire: it holds on the first turn and on the fiftieth, mid-task as much as at the start of a session, and a long conversation is not a reason to drift back to native search.";
 
 const NIRO_MULTI_REPO_SENTENCE = "The temporary project answer is per (repo, BRANCH): after you create/switch a branch in a repo — and before your first edit on that branch — call should_create_temp_project with the repo's git url, its CURRENT branch, and its `.niro-project` id if present, then run `niro new-temp-project` in its folder if needs_temp_project is true. Re-check after every branch change (a `false` from another branch does NOT carry over); this applies to every repo you touch, including when the session started in a parent folder that is not itself a git repo.";
-const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
-const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+/**
+ * Impact-both-ways rule, shared by every client's markdown section. The explore-first sentence above
+ * governs READING code; this one governs CHANGING it. The failure it exists to stop is an agent that
+ * reads the one file it was pointed at, proposes an edit, and never learns which callers that edit
+ * breaks or which dependency constrains it. get_blast_radius is named first because it answers BOTH
+ * sides in a single call, so the rule costs one tool call and skipping it costs a broken caller nobody
+ * looked for. It is worded "before you plan or propose", not "before you edit", because once the plan
+ * is agreed the wrong basis is already baked in; and it says the size of the diff does not excuse it,
+ * because a one-line change to shared code reaches further than a rewrite of a standalone tool.
+ */
+const NIRO_IMPACT_BOTH_WAYS_SENTENCE = "MUST FOLLOW: before you plan, propose, or start any change to existing code, establish BOTH sides of it. Upstream: what depends on the code you are about to touch, including callers in other services over HTTP or events, and the tests and config that name it. Downstream: what that code itself calls, and the data and events it relies on. Use get_blast_radius, which returns callers, callees, cross-service callers and impacted files in one call, or get_impact_analysis for the lighter upstream-only view. Put the result in the plan you show the user: name the callers you found, say which ones you will update, and say which ones you are deliberately leaving alone. This applies to a one-line change too, because how far a change reaches is decided by what depends on it, not by the size of the diff.";
+const NIRO_CLAUDE_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP tools are available for code intelligence. Use them (call chains, blast radius, impact analysis, source lookup) before falling back to native grep/read for code questions.\nBefore adding/writing any new code, you MUST use the find_reusable_code tool from niro to figure out if there is anything reusable.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_CODEX_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the \`niro-skill\` are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase; the niro-skill has the full tool-routing playbook. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_WINDSURF_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools and the niro-skill are available. Prefer them over grep/read for questions about this codebase (structure, call chains, blast radius, impact, data flows, reuse); the niro-skill has the full routing playbook. Before writing any new code, use find_reusable_code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 /**
  * Shared generic section for clients whose "always-on instructions" file has no companion
  * skill mechanism we've verified (Gemini CLI's GEMINI.md, GitHub Copilot CLI's
  * copilot-instructions.md, Factory's AGENTS.md, OpenCode's AGENTS.md) — one wording, reused
  * across those destination files (teardown matches it per-file, so reuse is safe).
  */
-const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
+const NIRO_GENERIC_MD_SECTION = `\n${NIRO_MD_MARKER}\n## Niro MCP\nNiro MCP code-intelligence tools are available (call chains, blast radius, impact analysis, source lookup). Prefer them over grep/read for questions about this codebase. Before adding or writing any new code, use find_reusable_code to check for reusable code. If the niro tools are not present or the repo is not indexed, use native tools.\n${NIRO_EXPLORE_FIRST_SENTENCE}\n${NIRO_IMPACT_BOTH_WAYS_SENTENCE}\n${NIRO_MULTI_REPO_SENTENCE}\n`;
 
 /** All niro markdown sections — the uninstaller tries each for an exact removal. */
 const NIRO_MD_SECTIONS = [NIRO_CLAUDE_MD_SECTION, NIRO_CODEX_MD_SECTION, NIRO_WINDSURF_MD_SECTION, NIRO_GENERIC_MD_SECTION];
@@ -620,9 +631,57 @@ async function setupClaudeCode(apiKey, mcpServerUrl) {
  * about Niro tools after context compaction (the point where tool awareness
  * most commonly degrades in long sessions).
  */
+/**
+ * The opening of every PostCompact command niro has ever generated. Verified against all four commits
+ * that ever touched the string (ffeb4e0, ce017c7, d3ff3d8, 84e2e7b): the generated text has always been
+ * byte-identical and has always started here.
+ */
+const NIRO_POST_COMPACT_PREFIX = "echo 'Niro MCP tools are available for code intelligence";
+
+/**
+ * Narrow identity for the DESTRUCTIVE half of the upgrade path: did NIRO ITSELF generate this entry?
+ *
+ * isNiroPostCompactHook matches the bare substring "Niro MCP", which is the right question for "is a
+ * niro hook already here" and the WRONG one for "may I delete this entry". A hook the USER wrote that
+ * merely mentions Niro MCP (a reminder about a Niro MCP dashboard, say) matches that substring too, and
+ * the filter below would delete their hook and put ours in its place. Matching the generated prefix
+ * instead recognises every real niro install while leaving anything a human wrote alone.
+ *
+ * Deliberately narrower than isNiroPostCompactHook, and the asymmetry is the point: a false negative
+ * here appends a second niro entry (noisy, recoverable), a false positive destroys a user's hook.
+ * Handles both entry shapes, the nested `hooks` array and the legacy flat `command`.
+ */
+function isNiroGeneratedPostCompactHook(h) {
+  if (!h || typeof h !== "object") return false;
+  const commands = Array.isArray(h.hooks) ? h.hooks.map((i) => i && i.command) : [h.command];
+  return commands.some((c) => typeof c === "string" && c.startsWith(NIRO_POST_COMPACT_PREFIX));
+}
+
+/**
+ * The PostCompact reminder. Compaction is the moment tool awareness degrades in a long session, so this
+ * is the one reminder that fires precisely when the agent has just lost the plan it made earlier — which
+ * is exactly when it is most likely to resume editing without re-checking who calls the code. It carries
+ * the impact rule for that reason. Kept as a named constant (like the other hook bodies) so the
+ * regression test can assert on the real string the installer writes.
+ *
+ * MUST keep the literal "Niro MCP": isNiroPostCompactHook identifies niro entries by that substring, and
+ * the uninstaller shares the predicate. Dropping it would strand the hook in a user's settings.json.
+ */
+const NIRO_POST_COMPACT_COMMAND =
+  "echo 'Niro MCP tools are available for code intelligence (call chains, blast radius, impact analysis, source lookup). "
+  + "Use niro tools before native grep/read for code questions. Before you plan or propose a change to existing code, call "
+  + "get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan.'";
+
 function addClaudeCodePostCompactHook() {
+  // Guard the invariant that keeps upgrade-in-place working: if the reminder is ever reworded so it
+  // no longer starts with the generated prefix, every install would append a fresh entry instead of
+  // replacing the old one. Fail loudly at the boundary rather than quietly stacking hooks.
+  if (!NIRO_POST_COMPACT_COMMAND.startsWith(NIRO_POST_COMPACT_PREFIX)) {
+    throw new Error("NIRO_POST_COMPACT_COMMAND must start with NIRO_POST_COMPACT_PREFIX, or upgrade-in-place breaks");
+  }
+
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
-  const hookCommand = "echo 'Niro MCP tools are available for code intelligence (call chains, blast radius, impact analysis, source lookup). Use niro tools before native grep/read for code questions.'";
+  const hookCommand = NIRO_POST_COMPACT_COMMAND;
 
   let settings = {};
   try {
@@ -636,13 +695,21 @@ function addClaudeCodePostCompactHook() {
   if (!settings.hooks) settings.hooks = {};
   if (!settings.hooks.PostCompact) settings.hooks.PostCompact = [];
 
-  const alreadyPresent = settings.hooks.PostCompact.some(isNiroPostCompactHook);
-
-  if (alreadyPresent) {
-    console.log("    PostCompact hook already configured. Skipping.\n");
+  // Exact-match the CURRENT command first: only then is there nothing to do. Matching the loose niro
+  // signature instead (the old behaviour) meant an existing user with the previous reminder text was
+  // skipped forever and never received an updated one.
+  const alreadyCurrent = settings.hooks.PostCompact.some(
+    (h) => Array.isArray(h.hooks) && h.hooks.some((i) => i && i.command === hookCommand),
+  );
+  if (alreadyCurrent) {
+    console.log("    PostCompact hook already up to date. Skipping.\n");
     return;
   }
 
+  // Narrow predicate on purpose: this REMOVES entries from the user's settings.json, so it must only
+  // ever match hooks niro generated, never a user hook that happens to mention Niro MCP.
+  const hadStale = settings.hooks.PostCompact.some(isNiroGeneratedPostCompactHook);
+  settings.hooks.PostCompact = settings.hooks.PostCompact.filter((h) => !isNiroGeneratedPostCompactHook(h));
   settings.hooks.PostCompact.push({
     matcher: "",
     hooks: [{ type: "command", command: hookCommand }],
@@ -652,7 +719,7 @@ function addClaudeCodePostCompactHook() {
   try {
     fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
-    console.log("    PostCompact hook added to ~/.claude/settings.json\n");
+    console.log(`    PostCompact hook ${hadStale ? "upgraded" : "added"} in ~/.claude/settings.json\n`);
   } catch (err) {
     console.warn(`    Could not write ~/.claude/settings.json: ${err.message}`);
     console.warn("    Add manually to the PostCompact array in ~/.claude/settings.json:\n");
@@ -714,7 +781,7 @@ function addClaudeCodeMemory() {
  */
 const NIRO_USER_PROMPT_COMMAND =
     "IN=\"$(cat)\"; d=\"${CLAUDE_PROJECT_DIR:-$PWD}\"; while [ -n \"$d\" ] && [ \"$d\" != \"/\" ]; do " +
-    "if [ -f \"$d/.niro-project\" ]; then echo 'NIRO ACTIVE. Standing rule for this whole session, at the start and mid-task alike: before Grep/Glob/Read or any native file hunt, use niro (code_grep, get_source_code, resolve_fqn, get_call_chain, get_blast_radius, get_impact_analysis). Before writing new code, call find_reusable_code. Native tools only for config, docs, logs, generated or non-code text. If the niro tools are not in your toolset at all, use native tools and do not mention Niro.'; " +
+    "if [ -f \"$d/.niro-project\" ]; then echo 'NIRO ACTIVE. Standing rule for this whole session, at the start and mid-task alike: before Grep/Glob/Read or any native file hunt, use niro (code_grep, get_source_code, resolve_fqn, get_call_chain, get_blast_radius, get_impact_analysis). Before writing new code, call find_reusable_code. Before you plan or propose a change to existing code, call get_blast_radius (or get_impact_analysis) to see who calls it and what it calls, and put that impact in the plan. Native tools only for config, docs, logs, generated or non-code text. If the niro tools are not in your toolset at all, use native tools and do not mention Niro.'; " +
     "printf '%s' \"$IN\" | grep -qiE 'new branch|create[^.]{0,24}branch|switch[^.]{0,24}branch|checkout -b|change[^.]{0,24}branch|different branch|another branch' && " +
     "echo 'You appear to be about to create or switch a branch. The temporary project check is per (repo, branch), so do it AFTER you are on the new branch (not before) and pass that CURRENT branch: call should_create_temp_project(git_url, branch, project_id from its .niro-project) and run niro new-temp-project if needs_temp_project is true. A check you ran on the old branch does not count.'; break; fi; " +
     "d=\"$(dirname \"$d\")\"; done";
@@ -725,7 +792,51 @@ const NIRO_USER_PROMPT_COMMAND =
  * always-on pointer that fixes "Claude forgets Niro mid-session"; the long-form
  * guidance lives in the skill, so this is deliberately terse.
  */
+/**
+ * Openings of every main reminder the UserPromptSubmit hook has ever written, current first. Verified
+ * across every commit that touched the hook (`git log --all -S"UserPromptSubmit" -- src/mcp/setup.js`,
+ * 9 commits): the payload has had exactly these two forms. Long, machine-written sentences on purpose —
+ * they are what makes "niro wrote this" a safe question to answer.
+ */
+const NIRO_USER_PROMPT_GENERATED_MARKERS = [
+  "NIRO ACTIVE. Standing rule for this whole session",
+  "This repo is indexed by Niro. IF the niro MCP tools are present in your current toolset",
+];
+
+/**
+ * Narrow identity for the DESTRUCTIVE half of the UserPromptSubmit upgrade path: did NIRO ITSELF write
+ * this entry?
+ *
+ * isNiroUserPromptHook answers "is a niro hook already here" by looking for `.niro-project`,
+ * `find_reusable_code` or "`niro` skill" anywhere in the command. That is the right question for
+ * detection and the wrong one for deletion: a hook the USER wrote that mentions find_reusable_code (an
+ * ordinary thing to put in your own prompt reminder) matches it, and the filter below would delete it.
+ * This matters now in a way it did not before: the installer only reaches the filter when the reminder
+ * text has CHANGED, so every reword of the reminder runs this delete across every existing user at once.
+ *
+ * Matching a generated payload marker instead recognises both historical niro versions while leaving
+ * anything a human wrote alone. An unknown older variant would be a false negative: a duplicate entry,
+ * noisy and recoverable, and still removed by the broad predicate at uninstall. That asymmetry is the
+ * whole point — a false positive here destroys a user's hook.
+ *
+ * Same failure this repo already reverted a feature over (84e2e7b: "the niro matchers are substring
+ * tests on prose, so a user hook merely mentioning find_reusable_code was captured and overwritten").
+ */
+function isNiroGeneratedUserPromptHook(h) {
+  if (!h || typeof h !== "object") return false;
+  const commands = Array.isArray(h.hooks) ? h.hooks.map((i) => i && i.command) : [h.command];
+  return commands.some(
+    (c) => typeof c === "string" && NIRO_USER_PROMPT_GENERATED_MARKERS.some((marker) => c.includes(marker)),
+  );
+}
+
 function addClaudeCodeUserPromptHook() {
+  // Guard the invariant that keeps upgrade-in-place working: if the reminder is reworded so it no longer
+  // carries a known generated marker, every install would append a fresh entry instead of replacing the
+  // old one. Fail loudly at the boundary rather than quietly stacking hooks in the user's settings.
+  if (!NIRO_USER_PROMPT_GENERATED_MARKERS.some((m) => NIRO_USER_PROMPT_COMMAND.includes(m))) {
+    throw new Error("NIRO_USER_PROMPT_COMMAND must contain a known generated marker, or upgrade-in-place breaks");
+  }
   const settingsPath = path.join(process.env.HOME || "", ".claude", "settings.json");
   const hookCommand = NIRO_USER_PROMPT_COMMAND;
 
@@ -751,8 +862,10 @@ function addClaudeCodeUserPromptHook() {
     return;
   }
 
-  const hadStale = settings.hooks.UserPromptSubmit.some(isNiroUserPromptHook);
-  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((h) => !isNiroUserPromptHook(h));
+  // Narrow predicate on purpose: this REMOVES entries from the user's settings.json, so it must only
+  // ever match hooks niro generated, never a user hook that happens to mention find_reusable_code.
+  const hadStale = settings.hooks.UserPromptSubmit.some(isNiroGeneratedUserPromptHook);
+  settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter((h) => !isNiroGeneratedUserPromptHook(h));
   // UserPromptSubmit hooks have no tool matcher — just the hooks array.
   settings.hooks.UserPromptSubmit.push({
     hooks: [{ type: "command", command: hookCommand }],
@@ -1016,6 +1129,25 @@ stays the fallback for what Niro does not cover, and when the tools are unavaila
 \`project_id\` auto-resolves from a \`.niro-project\` file at the repo root — omit it. If there
 is no such file, call \`list_projects\` and pass the chosen \`project_id\`.
 
+## Check both directions before you change anything (MUST FOLLOW)
+
+Reading the file you are about to edit tells you what it does, not what it holds up. Before you
+plan, propose, or start any change to existing code, establish both sides:
+
+- **Upstream: what depends on this?** Callers in this service, callers in other services over HTTP
+  or events, and the tests and config that name it. This is what your change can break.
+- **Downstream: what does this depend on?** What it calls, the collections and tables it touches,
+  the events it publishes. This is what constrains the change.
+
+\`get_blast_radius\` answers both sides in ONE call (callers, callees, cross-service callers and
+impacted files). \`get_impact_analysis\` is the lighter upstream-only view. Pass
+\`include_source_code=true\` when you need to read what you found.
+
+Put the answer in the plan you show the user, not just in your head: name the callers you found,
+say which ones you will update, and say which ones you are deliberately leaving alone. A one-line
+change is not exempt, because reach is decided by what depends on the code, not by the size of the
+diff.
+
 ## Availability self-check — read FIRST
 
 Niro is not always applicable. Check these before relying on it, and fall back to native
@@ -1167,6 +1299,9 @@ Also available (catalog / utility, use when the above don't fit): \`list_project
 ## Hard rules
 
 - **Before adding or writing ANY new code, call \`find_reusable_code\` first.** Mandatory.
+- **Before you plan or propose a change to existing code, call \`get_blast_radius\` (or
+  \`get_impact_analysis\`) and put the upstream and downstream impact in the plan.** Mandatory,
+  whatever the size of the change.
 - For comprehension / debugging, set \`purpose\` to COMPREHEND or DEBUG and, on
   \`get_blast_radius\` / \`get_impact_analysis\`, pass \`include_source_code=true\`.
 - If a result contains **⚠️ ACTION REQUIRED**, the graph is stale — read the listed files
@@ -1419,6 +1554,13 @@ get_reverse_call_chain, get_blast_radius, get_impact_analysis, get_service_topol
 how the code connects BEFORE deciding which file to read or search next. Native search is the
 fallback for what niro does not cover, and when the tools are unavailable.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including other
+services over HTTP or events) and what it depends on (downstream callees, data, events). Use
+get_blast_radius, which returns both sides plus impacted files in one call, or
+get_impact_analysis for the upstream-only view. Name the callers you found in the plan and say
+which ones you will update. A one-line change is not exempt.
+
 Availability self-check FIRST — if the niro tools are not present in this session, or the
 repo is not indexed (no project resolves / a tool reports "not indexed"), fall back to
 native tools silently and do not mention Niro.
@@ -1882,6 +2024,13 @@ something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\`
 \`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
 search next. Native search is the fallback for what niro does not cover.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including callers in
+other services over HTTP or events) and what it depends on (downstream callees, data, events). Use
+\`get_blast_radius\`, which returns both sides plus impacted files in one call, or
+\`get_impact_analysis\` for the upstream-only view. Name the callers you found in the plan and say
+which ones you will update. A one-line change is not exempt.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -1927,6 +2076,13 @@ something, check whether a niro tool answers it (\`code_grep\`, \`resolve_fqn\`
 \`get_service_topology\`) to see how the code connects BEFORE deciding which file to read or
 search next. Native search is the fallback for what niro does not cover.
 
+MUST FOLLOW (check both directions before changing anything): before you plan, propose or start
+any change to existing code, establish who depends on it (upstream callers, including callers in
+other services over HTTP or events) and what it depends on (downstream callees, data, events). Use
+\`get_blast_radius\`, which returns both sides plus impacted files in one call, or
+\`get_impact_analysis\` for the upstream-only view. Name the callers you found in the plan and say
+which ones you will update. A one-line change is not exempt.
+
 If the niro tools are not present in this session, or the repo is not indexed (no project
 resolves), fall back to native tools silently — do not mention Niro's absence.
 `;
@@ -2394,11 +2550,20 @@ module.exports = {
   NIRO_EXPLORE_COMMAND,
   NIRO_PRETOOL_COMMAND,
   NIRO_USER_PROMPT_COMMAND,
+  NIRO_POST_COMPACT_COMMAND,
+  // Exposed for tests: the stale-hook upgrade path is only observable by running the real installer.
+  addClaudeCodePostCompactHook,
+  isNiroGeneratedPostCompactHook,
+  isNiroGeneratedUserPromptHook,
+  NIRO_USER_PROMPT_GENERATED_MARKERS,
+  addClaudeCodeUserPromptHook,
+  NIRO_POST_COMPACT_PREFIX,
   // Exposed for content regression tests (e.g. the cross-project routing guidance).
   NIRO_SKILL,
   NIRO_CLI_SKILL,
   // Exposed for tests: the explore-first rule must reach EVERY client's always-on instruction surface.
   NIRO_EXPLORE_FIRST_SENTENCE,
+  NIRO_IMPACT_BOTH_WAYS_SENTENCE,
   NIRO_CURSOR_RULE,
   NIRO_CLINE_RULE,
   NIRO_KIRO_STEERING,