@niro-divya/niro-uat 0.0.0-stage → 0.17.0-uat.1376acf

package/CHANGELOG.md

@@ -0,0 +1,918 @@
+# Changelog
+
+Notable changes to `@niroai/niro`. Dates are release dates.
+
+## Unreleased
+
+### The coverage audit sends a few lines, not the whole flagged file
+
+When a build flags a line it thinks the parser missed, only the method that holds that line (or, when
+no method holds it, at most 10 lines before to 40 after) and one line for each name those lines use
+from the same file are sent, with secrets masked. Every other line of the file goes as an empty line,
+so line numbers stay where they were. `niro status` and `niro plan` say so. niro-cli refuses to post
+a snippet that holds any other line. Removing a copyright holder's name no longer drops a line after a
+`*/` header, which used to move every flag below it one line up on the server.
+
+### The background watcher no longer saves your whole shell environment
+
+`niro-watch` runs under PM2, and PM2 saves the environment it was started with in
+`~/.pm2/dump.pm2`. That used to be the whole shell, cloud keys and tokens included, in a file other
+users on the machine could read. The watcher is now started with only what it reads (HOME, PATH,
+locale, temp folders, proxy and certificate settings, and the Niro settings), and `dump.pm2` and its
+backup are made readable by you only. An install made by an earlier version is started again with
+the smaller environment the next time you run `niro start` or `niro service install`, which also
+rewrites the saved files.
+
+`niro status` and `niro plan` now say what leaves the machine: your code stays on it, and the files
+the coverage audit flags are sent with secrets masked, on every plan.
+
+### `niro watch` re-checks a locally indexed folder every few minutes
+
+A file event that fs.watch dropped, or a file added while one was lost, was not built into the local
+graph until some later edit arrived. The watcher now lists a locally indexed folder every five minutes
+(file names, sizes and modification times; no file is read) and builds it when the listing changed
+since the last build started. A folder with a build running or due is left to that build, so two
+builds never run at once. Set `NIRO_LOCAL_RECHECK_MS` to change the interval.
+
+### The MCP bridge speaks Streamable HTTP
+
+`niro mcp serve` now talks to the Niro server over MCP Streamable HTTP (`POST /mcp`) when the server
+offers it: each call is answered in its own HTTP response, so there is no long-lived stream to drop.
+An expired session is renewed and the call resent once; a failed call returns an error instead of
+hanging. A dropped connection is retried only when the call cannot run twice (it never left, or it
+is a read like `tools/list`); a `tools/call` that may have run returns an error instead. Servers without it (404/405 on `/mcp`) get the old SSE transport, unchanged. Force one with
+`NIRO_MCP_TRANSPORT=http` or `sse`. Editor configs do not change.
+
+### `niro audit-push-repo`, for the plans that include it
+
+Sends this folder's whole source to Niro, so we can measure what the local engine's parser
+misses on code we never see rather than only on the files it already failed to parse. It lands
+in the account-scoped object store, the same place a repository uploaded through `niro add repo`
+goes, and nothing in that chain creates a project.
+
+It is explicit: no watcher runs it and no other command triggers it, and it prints the folder,
+the file count and the size, then asks. With no terminal it refuses unless you pass `--yes`.
+
+Permission is a claim in the licence lease, and anything that is not a clear yes is a refusal,
+including a licence service that cannot be reached. The folder goes through the same gate as
+`niro init`, which refuses your home directory, the filesystem root and a folder that holds no
+project of its own. The file set is the manifest the CLI already uses, so `.gitignore` is
+honoured and, when git cannot answer on a work tree, every file whose name could carry a secret
+is dropped rather than uploaded unverified; the service then decides what it will take, as it
+does for every other upload. A folder that has been sent is remembered in
+`~/.niro/audit-repos.json`; a second run says when the first one was, and `--force` sends it
+again into the same workspace.
+
+### A machine that cannot run the local engine is offered Niro's cloud, and asked first
+
+The local engine keeps its graph in Memgraph, which runs as a container, and some machines
+forbid a container runtime outright. `niro engine install` now finds that out and says so in the
+engine's own words, with that platform's install instructions, then offers to index in Niro's
+cloud instead and asks before switching. The answer is remembered in `~/.niro/config.json`, so
+it is asked once per machine. With no terminal and no recorded answer nothing happens and the
+command exits 1, because uploading somebody's source when nobody was there to say no is the one
+outcome this must never produce; a script approves it deliberately with
+`NIRO_APPROVE_CLOUD_INDEXING=1`.
+
+A developer who runs Memgraph themselves, natively or on their network, is not asked at all: the
+check passes as soon as a graph database answers, whatever started it.
+
+`niro engine status` gained two lines, `database` and `route`, and now prints them whichever way
+the engine was found, including from `NIRO_LOCAL_BIN`.
+
+### A folder indexed on your own machine is no longer indexed in the cloud as well
+
+`niro build`, `niro init` and `niro add repo` now refuse a folder that the local engine
+(`niro-local`) already indexes, and name the two ways out: `niro-local build --path <folder>` to
+update the local index, or `niro-local remove --path <folder>` first if you do want it in the
+cloud. Before this, either command uploaded the folder's source and indexed it a second time,
+which is the one thing the local engine exists to avoid, and the second index was charged for and
+then went stale, because questions in that folder are answered from the local graph.
+
+A machine without the engine is unaffected, and so is any folder the engine does not index.
+`niro new-temp-project` is deliberately **not** refused: a temporary project is a cloud project on
+purpose, because it serves pull request review and root cause analysis, which the local graph does
+not answer. It now says so in one line before it uploads.
+
+## 0.17.0 — 2026-09-23
+
+### `niro init --defaults` still asks which project
+
+`--defaults` accepts default values: env vars, indexing scope, the project name. It also used to
+skip the "new project, or add to an existing one?" question and always create a new project, which
+put repos in the wrong place for anyone who already had a project for them. Which project is not a
+default value, so in a terminal the question is now asked with `--defaults` too.
+
+Unattended runs are unchanged. With no terminal (CI, a piped script, an agent's shell) there is no
+question and a new project is created, as before. A script that wants an existing project passes
+`--add-to <alias|id>`; `--project-name <name>` still skips the question everywhere.
+
+## 0.16.0 — 2026-09-22
+
+### A reverse proxy's routing table is offered for upload
+
+Most services do not call each other directly. They call a proxy, and a routing table decides who
+really answers. That table is the only place the hop is written down, and the CLI was not offering
+it, so the server never saw it and the graph stopped at the proxy.
+
+Newly offered:
+
+- `nginx.conf`, `haproxy.cfg`, `httpd.conf`, `apache2.conf`
+- compose files named for their environment, not just `docker-compose.yml`: a Traefik routing table
+  lives in container labels, and those labels are routinely in `docker-compose.production.yml`
+- Kubernetes Ingress manifests under the names teams actually use: `ingress.yaml`,
+  `*-ingress.yaml`, `*_ingress.yaml`
+
+Deliberately still NOT offered: every `.yaml`. An Ingress can be in any file, and claiming all of
+them would upload every Helm chart, kustomization and CI file in a repository to find the occasional
+routing table. An Ingress under an unconventional name is a stated limit rather than a silent one.
+
+Envoy was left out on purpose. A file that is uploaded and then read by nothing is cost with no
+benefit, and the server has no Envoy reader yet.
+
+### A drift guard for the config list
+
+`CONFIG_FILENAMES` is a hand-kept copy of the server's list and nothing compared the two.
+`test/configFilenameDrift.test.js` now does, alongside the existing extension guard. This matters
+more than it did: if the copies drift now, the CLI stops offering `nginx.conf`, the server never
+receives it, and every connection through that proxy quietly disappears from the graph. The symptom
+reads as "proxy support is broken" and is nowhere near the list that caused it.
+
+### Upgrade order
+
+The server's filter remains the final say, so either order is safe: an older CLI offers fewer files,
+and a newer CLI against an older server has its extra offers declined. The routing tables reach the
+graph once both sides are current (ai-orchestrator `25131e94` or later). Repositories the server
+clones itself are unaffected by this release; their files never went through the CLI.
+
+## 0.15.0 — 2026-09-21
+
+### Twenty more file types are offered for upload
+
+`niro init` and the folder sync decide which files to offer the server from a fixed list of
+extensions (`src/lib/folderSync.js`). That list was a hand-kept copy of the server's own list and
+had fallen behind it in two places:
+
+- the ten C++ extensions the parser routes to its C++ grammar besides `.cpp`, `.h` and `.hpp`:
+  `.cc`, `.cxx`, `.hxx`, `.hh`, `.h++`, `.c++`, `.tcc`, `.ipp`, `.inl`, `.tpp`. A C++ project with
+  `include/widget.hxx` and `detail/vector.tcc` never had those two files in its graph, because the
+  CLI never offered them.
+- ten more the parser has always understood but the CLI never offered: `.kts`, `.csx`, `.rake`,
+  `.gemspec`, `.phtml`, `.php3`, `.php4`, `.php5`, `.pyi`, `.pyw`.
+
+A test now reads the server's Java list and fails if the two drift apart again
+(`test/sourceExtensionDrift.test.js`); the server carries the mirror-image test.
+
+The server's own filter remains the final say, so an older CLI simply offers fewer files and a
+newer CLI against an older server has its extra offers declined. Either order of upgrade is safe;
+the new files reach the graph once both sides are current (ai-orchestrator `cadb5360` or later).
+
+Note: 0.14.0 was cut in this repository but never published to npm, so upgrading from 0.13.0 brings
+the 0.14.0 change below as well.
+
+### A file whose name contains `+` no longer stops a folder syncing
+
+After `niro init`, the server replies with the patterns saying which paths belong to the
+project, and the watch daemon checks every path against them: on each file event, on each
+delta and backstop pass, and once more before it asks the server to delete anything.
+
+For a file at the top level of a repository, the pattern the server sends is the filename
+itself. The daemon turned patterns into regular expressions but escaped only the dot, so a
+name carrying a character that means something in a regular expression was read as an
+instruction rather than as a name. With `main.c++` at a repository root, `main.c++` became
+`/^main\.c++$/`, which is not a valid expression. Every sync pass for that folder then failed.
+The daemon stayed up and printed nothing, so the folder simply went quiet.
+
+The `.c++` and `.h++` file types added in this same release are what would have exposed it. The
+same flaw had a quieter form that needed no C++ at all: a root-level file called `app (copy).js`
+built a valid expression with a capture group, so the file stopped matching its own pattern and
+was never synced again. A directory named `libstdc++` hit the throwing form, because saying yes
+to "New directory detected. Add to sync?" stores the directory's own name as a pattern.
+
+The matcher now escapes every character that has a special meaning, leaving only `*` and `**`
+as wildcards, so a pattern can no longer fail to compile. Behaviour for patterns that already
+worked is unchanged: old and new were compared over 10,701 path-and-pattern pairs taken from
+three real repositories and agreed on every one.
+
+## 0.14.0 — 2026-09-19
+
+### `niro init` on a folder of repos now indexes each repo, not the folder
+
+If you run `niro init` in a folder that is not itself a git repository but contains repositories —
+an `apps/` folder, a `~/projects/github/<org>/` folder, anything that groups checkouts — each
+repository is now onboarded in its own right, with its own git URL and its own branch, into one
+project.
+
+Before this, the folder itself was registered as a single repo. A folder has no git remote, so it
+got a synthetic `local://<folder-name>` URL and no branch at all, and the monorepo splitter then
+tried to recover the structure by reading folder layout. On one customer's tree that produced 92
+internal repos from 14 real ones: 92 of 92 carried `local://apps`, none had a branch, 58 of them
+were vendored copies and reference checkouts of other people's projects, and 45% of the indexing
+spend went on code the customer had never written. Because no repo had a URL of its own, MCP could
+not match a repo from inside its own folder, and kept offering to create a temporary project in
+code that was already indexed.
+
+The repositories underneath were the boundaries the customer had already declared. Reading them is
+better than re-deriving them.
+
+What you will see:
+
+```
+    apps is not a git repository, but contains 14 that are.
+    Niro will index each repo separately, with its own git URL and branch.
+
+        + voibe-backend
+        + voibe_app
+        - legal-docs — not a git repository, NOT indexed
+```
+
+Folders holding code but no repository are reported rather than skipped in silence: from that point
+on, editing a file in one of them does nothing, and you should know which ones they are. Run
+`niro init` inside one to add it.
+
+The scan stops at the first repository it finds down any path, so a repository vendored inside
+another — a submodule, a `third_party/` checkout — is indexed as part of its parent rather than as a
+service of its own.
+
+Unchanged: a folder that IS a git repository still indexes whole, submodules and all. A folder with
+no git anywhere still uploads as one repo, as before.
+
+### A folder whose repositories sit deeper than one level is no longer refused
+
+`niro init` requires a build file at the folder or just below it, which is right for a folder of
+documents and wrong for `~/projects/github/<org>/<repo>`, where the repositories are three levels
+down and every folder above them is empty. That was refused with "No project found" and a pointer to
+`--force`, and `--force` would then upload the entire tree as one repo. A folder holding
+repositories is now exempt from that rule, because it has already declared its projects.
+
+The refusal message for a folder that genuinely holds nothing indexable now says what Niro looks
+for, and suggests running from the folder where the code actually is.
+
+### Fixed
+
+- The background watcher was being installed once per repository when onboarding several at once,
+  asking for your password each time. It is one process; it is now set up once per run.
+
+
+## 0.13.0 — 2026-09-08
+
+### Upgrading
+
+You do not have `niro upgrade` yet, so this one takes two commands:
+
+```bash
+npm install -g @niroai/niro@latest
+niro upgrade --finish
+```
+
+The first gets the package. The second is the half npm cannot do: it re-runs the installer for
+every assistant you have configured and restarts the background watcher. Then restart your
+assistant. Skipping the second command leaves you on this version with the previous version's
+hooks, skills and instruction files, which is the exact problem this release exists to fix.
+
+From here on it is one command, `niro upgrade`, which does all of it.
+
+### `niro upgrade` gets the new version AND the things a new version cannot bring with it
+
+Upgrading was `npm install -g @niroai/niro@latest`, and every release note in this file said so and
+nothing else. That command is not enough, and has never been enough. The MCP entry is fine: it runs
+plain `niro` off your `PATH` with no version in it, so the new server is picked up for free. But the
+hooks, the skills and the CLAUDE.md/AGENTS.md/rules text are written into your home folder as fixed
+text at install time, not read from the package as it runs. npm cannot touch them. Nothing told you
+that, and nothing re-ran the installer, so a machine that installed once in June was still running
+June's instructions in September while reporting the current version. The background watcher had the
+same problem from the other end: it is a long-running process holding the code it loaded at start,
+so replacing files on disk left it on the old version until something restarted it.
+
+`niro upgrade` does all three. It replaces the package, re-runs the installer for every assistant it
+can prove is configured, and restarts the watcher if it is running.
+
+It runs as two processes, and the reason is worth writing down. Every command in this CLI is loaded
+lazily, inside its own action handler, and `npm install -g` replaces the folder those files are
+loaded from. One process that ran npm and then carried on would be running the modules it loaded
+before the swap alongside modules loaded after it. So phase one runs npm, executes the NEW binary
+with `--finish`, and stops, requiring nothing in between; phase two is a fresh process reading the
+new tree. `niro start` has always dodged the same trap the same way, by only installing globally
+when it is running from the npx cache and then handing over.
+
+Which assistants to refresh is worked out by looking, because nothing on disk records what you
+chose. All 14 clients are covered, because the installer leaves a file this repo owns in every case:
+eight write a JSON config whose path `setup.js` builds, and the other six also get a marker appended
+to a markdown file written here and stripped by `teardown.js` (`~/.claude/CLAUDE.md`,
+`~/.gemini/GEMINI.md`, `~/.copilot/copilot-instructions.md`, `~/.factory/AGENTS.md`), plus codex's
+`[mcp_servers.niro]` table and goose's `extensions:` entry. The marker is appended only after the
+registration command succeeded, so its presence means the client really was configured. Detection is
+read-only, and it is deliberately strict: a client whose entry is `enabled: false` or
+`disabled: true` is one you switched off, so it is left alone rather than switched back on; a
+marker has to be on a line of its own, because a sentence mentioning it is not an install; and every
+path has to be absolute.
+
+`niro upgrade --finish` on its own skips npm and only refreshes the assistant files and the watcher,
+which is what you want if you already ran `npm install -g` by hand.
+
+Without a usable home folder it checks nothing and says so. Every path would otherwise resolve
+against the current folder, which is how the reverted serve-time self-heal came to write into a
+project's own `.claude/settings.json` (see the 2026-07-30 revert). "Usable" means absolute, and it
+also means rejecting a `HOME` set to the empty string even when `USERPROFILE` would fill in, because
+four of the client path builders read `HOME` directly and would otherwise hand back a relative path.
+This command never writes a settings file itself: refreshing hooks means spawning the existing
+installer, once per client.
+
+It refuses to upgrade a copy you are not running. The first real run of this command was from a
+checkout linked with `npm link`, and `npm install -g` deleted that link and put the published
+package in its place. So before npm is allowed to touch anything, `niro upgrade` looks at which
+copy is running: the global package folder being a symlink means `npm link`, and it stops and says
+so; a checkout or an npx copy that is not the global install stops too. `--force` overrides either.
+
+It also asks the version it just installed whether it has an `upgrade` command before handing over
+to it, because the newest published version can predate the one you are running. Without that
+check the hand-over fails with a bare `error: unknown command 'upgrade'` and the advice printed is
+to re-run a command that does not exist. Now it prints the two commands that do work.
+
+Failures are visible. Each one has its own exit code (npm failed, no binary after npm, hand-over
+failed, refresh incomplete), an interrupted npm is reported as interrupted rather than as "nothing
+changed", a hand-over that cannot start prints why, and the hand-over carries a marker so a version
+that does not understand `--finish` cannot loop back into running npm again.
+
+
+## 0.12.0 — 2026-09-06
+
+### Before an edit to indexed source, Claude is asked to map the method and to verify those flows afterwards
+
+Every instruction file niro writes tells the assistant to map who depends on a method before changing
+it. In practice the assistant finds the file, reads it, and edits; the rule is read early in a session
+and forgotten by the middle of it. And the map was always meant for afterwards: the point is to go back
+to the callers and flows once the edit is made and check they still hold.
+
+Claude Code now gets a third niro hook, on Edit and Write. Before an edit to source in an indexed repo
+it puts a short reminder in front of the assistant: decide whether the change can alter behaviour (a log
+line or a comment cannot, say so and go ahead); if it can, map who depends on the method now with
+get_blast_radius or get_impact_analysis and keep that list as the checklist for after the edit; and do
+not re-query the graph to verify, because it updates only after the edit is synced and rebuilt. If an
+impact call already named the file this session, the reminder instead says to go back to that list
+after the edit. Each reminder appears once per file per session. It is advisory: it never approves or
+refuses an edit. The evidence comes from the bridge, which writes one line per answered impact call
+under `~/.niro/impact/`. New files, tests, config and docs are never mentioned. Off switch:
+`touch ~/.niro/impact-gate-off`. `niro mcp uninstall` removes the hook and the evidence files.
+
+The same three points were added to every instruction surface niro writes: the rule sentence in each
+client's always-on file, the niro skill, the Cursor, Cline and Kiro rules, and the PostCompact and
+prompt hooks. The clients without hooks read them there. Details: `docs/usecases/impact-gate.md`.
+
+### `niro mcp install` now refreshes Claude Code hooks on a machine where niro was already set up
+
+Re-running the install on a machine with an existing registration failed at the first step, because
+`claude mcp add` refuses a name that already exists, and the installer read that refusal as "Claude
+Code is not installed" and stopped before writing any hook or the CLAUDE.md section. So the step the
+out-of-date notice asks for did nothing for anyone who had installed once. The installer now reads the
+existing registration first: same URL, it keeps it; a different `--url`, it replaces it; none, it adds
+it. Hooks and sections are written in every case.
+
+### CommonJS and ES-module files (.cjs, .mjs, .cts, .mts) are now uploaded for indexing
+
+When niro decided which files to upload for indexing, it skipped `.cjs`, `.mjs`, `.cts` and `.mts`,
+so a `build.cjs` or an `index.mjs` was never indexed and never appeared in the graph. Those four
+extensions are now included, matching the server's own file filter.
+
+### The niro rules now name get_exception_flow
+
+The explore-first rule niro writes into each client now mentions `get_exception_flow`, the tool that
+reports which exceptions can escape a method (and who must handle one). It is served by the niro
+backend; this only makes the assistants aware it exists.
+
+## 0.11.0 — 2026-09-03
+
+### The watcher stops pausing and resuming your uploads over and over
+
+The background watcher holds back uploads from a folder whose branch disagrees with the branch its
+private copy is labelled with, so two branches cannot be written into one copy. One developer's log
+carried 306 pauses against 286 resumes. Those counts being nearly equal is the whole story: it was
+toggling, not failing 306 times.
+
+Once a minute the watcher asks which branch the copy is on. A request that failed returned nothing,
+which was read as "everything is fine again": it printed "resuming uploads" and cleared the pause, so
+the next check paused and warned all over again. It also let a folder that genuinely should not be
+uploading start writing again on any slow request. Now a question the server could not answer changes
+nothing at all, in either direction. The same six alternating checks went from 3 warnings and 3 resumes
+down to 1 and 0.
+
+The message was wrong too. When it paused it looked for another folder on the same *project* and blamed
+it. A project can hold several repositories and each folder can have its own, so it regularly named a
+folder that was writing nowhere near yours and told you to discard it. It now matches on the repository
+actually being written to, so it either names the folder that really shares your copy or tells you
+plainly that you switched branch in that folder yourself.
+
+**The pause itself is unchanged, deliberately.** While a folder's branch and its copy's label disagree,
+your assistant's questions are not sent to that copy anyway, so uploading into it would only fill it
+with the wrong branch's files. Run `niro new-temp-project` in that folder to put it back in step.
+
+### Servlet apps declare their endpoints in a file that was never sent
+
+A Java web app written before Spring Boot lists its whole HTTP surface in `WEB-INF/web.xml` rather than
+in annotations. That file was missing from the set the CLI offers, so such a project indexed as a
+servlet application with no endpoints at all. Measured on one repository: 11 real endpoints, 0 detected,
+against an otherwise complete and healthy index.
+
+
+### Stale pointers clean themselves up
+
+Delete a project, or let an unused private copy expire, and your machine is never told. The folder
+carries on naming something that is gone. That is what makes `niro new-temp-project` in another
+worktree say the slot is taken, naming a copy that no longer exists.
+
+That command never shipped: it went in under this same Unreleased section and has been renamed since,
+so `niro doctor sync-registry` is its first public name. It also only helped if you remembered to run
+it. Now the background watcher runs it every six hours by itself, and it covers two more cases:
+
+- **Ordinary registrations**, not just private copies. A folder registered against a deleted project
+  used to sit there for ever: the daemon retried it on every start and nothing could clear it. One
+  developer asked whether they should edit `~/.niro/projects.json` by hand. They were right that there
+  was no supported way.
+- **`.niro-project` files** naming something the server does not recognise. Nothing has ever surfaced
+  these, and they are not inert: that file is read before your git remote, so a stale one keeps
+  answering. They are REPORTED, never deleted — the file can hold a project's name rather than its id,
+  and a renamed project is indistinguishable from a deleted one from the client, so the right repair
+  (update it, or remove it) is yours to choose.
+
+**What it refuses to do matters more than what it does.** A deleted project is not enough to
+unregister a folder, because a project can be deleted while its repos are moved to another one and
+that folder is still syncing fine, so the repo is checked too. On the machine this was built on that
+took the count from 18 folders to 1. And a `.niro-project` may hold an *alias* rather than an id, which
+the direct lookup reports as "not found" for a project that is perfectly alive; the account's project
+list is now the authority. Both of those were caught by dry runs against real data after the unit tests
+were green.
+
+The watcher remembers when it last swept, so restarting it does not re-run the job, and a `niro watch`
+left in a terminal cannot sweep at the same moment as the background one. It stays silent when there
+was nothing to do.
+
+### When you run out of private copies, it says where they are
+
+The server already tells you which branches are holding your copies. It cannot tell you where those
+branches are checked out, because that is a fact about your machine. The CLI now adds the folder next
+to each branch, so you can go straight to one and discard it.
+
+### Multi-line error messages are no longer cut off
+
+Errors printed only their first line, so any message built over several lines lost the rest. Two were
+affected: "Multiple projects match this repo — pass --project:" showed no projects, and the
+working-copy-limit refusal showed no folders. The text was always correct and simply never reached the
+screen. Found by running the real CLI against a real backend until it refused; no unit test could have
+caught it, because both features assert on the message and the message was right.
+
+
+### `niro doctor sync-registry` tidies up copies the server deleted for you
+
+A temporary project can go without this machine ever being told: somebody deletes it in the web
+app, or the sweeper reaps it after two weeks. The folder keeps a registration pointing at an id
+that resolves to nothing. That is not harmless, because it is exactly what makes
+`niro new-temp-project` in a second worktree refuse with "already held by another folder".
+
+`niro discard-temp-project` already repaired one folder in that state. What nothing did was find
+them. On the machine this was built on, 13 of 14 registered copies had gone and every one of the
+14 folders was still pointing at a dead id.
+
+```bash
+niro doctor sync-registry            # check and repair
+niro doctor sync-registry --dry-run  # list, change nothing
+```
+
+It asks the server once per copy and moves the folders whose copy has gone back onto their
+original project. Three things it will not do. It never treats an unreachable server as an
+answer: only a definitive "Project not found" counts, so a 500, a timeout, or a project you are
+simply not allowed to see leaves every entry exactly as it was. It never unregisters a folder,
+because the watch daemon still needs somewhere to sync it. And it never guesses: a copy that no
+folder recorded a source project for is reported and left alone.
+
+`--json` for scripts, `--dry-run` to look first, `-y` to skip the prompt. At a terminal, `--json`
+asks for one of the last two rather than writing without a prompt it cannot show.
+
+Two guards came out of review and apply to `niro discard-temp-project` as well, because both commands
+now share one repair routine. A folder re-registered by another process while the command runs is
+left alone and reported, instead of being overwritten by a stale snapshot. And within a copy that
+covers several folders, the one holding the record of the original project is always written last, so
+a run interrupted half way through can still be finished by running it again.
+
+Folders that had no local registration before the copy was made are now listed separately from the
+ones that keep syncing. They go back to not having one, which is where they started, but calling that
+"repaired" and stopping there implied the daemon was still watching them.
+
+## 0.10.0 — 2026-08-28
+
+One command to get started, and a way to check what Niro is worth.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.9.0. Every existing command works exactly as before; the new
+ones sit alongside them.
+
+**`niro start` replaces four steps with one.** Getting started used to mean learning a sequence
+from a README: install, `niro login`, change into the right folder, `niro init`, then
+`niro mcp install`. Each step was fine on its own; the sequence was the problem, because the
+entry point was documentation and documentation is optional. One user ran `niro init` in their
+home folder. Typing `niro` on its own printed an eighteen-command help listing, which is the
+worst possible first screen for someone who knows none of them.
+
+```bash
+npx @niroai/niro start
+```
+
+That signs you in, installs itself properly, shows you what it is about to index and asks
+before uploading anything, builds the graph, connects your assistant, and offers to measure
+the difference. Run it again in any other repo and it skips whatever is already done. It opens
+by saying what Niro does and roughly how long this takes, and it asks whether you have an
+access code before it installs anything, so nobody without one fills in a form that rejects
+them at the end.
+
+Two screens are worth calling out. Before uploading, it shows you the folder, the build files
+it recognised, the module count and the git branch, and waits: the one screen worth reading
+rather than skipping. And a folder it refuses, such as your home folder, now asks for a
+different one instead of exiting, which is what made that mistake so easy to make.
+
+`niro init`, `niro login` and `niro mcp install` are untouched. They are the scriptable path,
+they take flags, and `niro start` simply calls them in order.
+
+**`niro ab` measures what Niro changes.** Rather than take our word for it, Niro can run
+*itself off* for half your sessions and show you the two halves side by side. While a window is
+open each session lands in an "on" or "off" bucket by a deterministic split; the off half works
+without Niro.
+
+```bash
+niro ab enable          # start a 14-day window (it states the scope and asks first)
+niro ab report          # the with-Niro / without-Niro comparison
+niro ab disable         # stop early
+```
+
+It applies to your whole account, not just the repo you are standing in, and it says so before
+starting. `niro start` offers it once, at the end of a first setup, and defaults to no.
+
+**Setup prints about half as much.** A real run printed roughly 230 lines and only half were
+ours. PM2's process table and generated systemd unit file, about 55 lines, are captured now and
+shown only if something fails. The assistant list shows five clients and a count rather than all
+fourteen with their config paths (`niro mcp install --list` for the rest). `niro init` stopped
+telling you to run `niro mcp install` two seconds before the wizard did it for you.
+
+**Output is indented consistently.** Printed lines used eight different indents across the CLI,
+so nothing said what belonged to what. Everything now sits on one ladder: headings and step
+markers, their messages one level in, detail one level further. Output from `niro init`, and
+from the editor CLIs it shells out to, is folded into that ladder instead of printing flush
+left in the middle of a step.
+
+**Fixes.** The spinner and the upload progress bar wrote straight to the terminal and so
+ignored indentation entirely. `niro mcp install --list` was added. Two em-dashes and one
+invented URL were removed from text you read on screen.
+
+## 0.9.0 — 2026-08-26
+
+One change to how the client waits, and two fixes for cases where Niro and your machine
+disagreed about what still exists.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.8.0. Against an older server the waiting change simply does not
+engage, because the client decides from the server's answer rather than from a version.
+
+**Creating a working copy no longer times out.** It takes 44 to 60 seconds, and it used to run
+inside a single request, against a gateway that gives up at 60. Three at once on 26 August all
+came back as gateway error pages, and because such an error says nothing about whether the work
+finished, the real cause underneath went unread for an afternoon. The client now asks the server
+to do it in the background and waits for it to finish, showing progress. A dropped connection
+while waiting is not treated as a failure, because the copy is still being made on the server; an
+expired login is, because waiting cannot fix it.
+
+**Discarding a working copy the server had already deleted.** A working copy can go away
+without your machine being told: someone deletes it in the web UI, or the server reaps it
+after it has sat idle for two weeks. The folder on your machine kept a registration pointing
+at it, and `niro discard-temp-project`, which is what clears that registration, failed before
+it got that far. The registration is also what makes `niro new-temp-project` in a second
+worktree refuse, advising you to run discard in the other folder, so the advice named the one
+command that could not work. Discard now treats a project the server says is missing as
+nothing left to delete: it skips the server call and does the local half, pointing the folder
+back at the original project. A server it could not reach, or one that refuses because the
+copy belongs to another developer, still fails loudly and changes nothing, which matters
+because the server answers both of those with the same status code as a deleted project.
+
+**A detached checkout stopped Niro answering.** During `git bisect`, or after checking out a
+tag, your repo is on no branch. `git rev-parse --abbrev-ref HEAD` does not fail there, it
+prints the word `HEAD`, and Niro passed that on as though it were a branch name. Nothing
+indexes a branch called `HEAD`, so the server treated every such question as coming from a
+diverged branch and declined to answer it, for the whole bisect. Niro now reports no branch,
+which is what the server already had a rule for, and answers from the indexed project.
+
+## 0.8.0 — 2026-08-26
+
+Needed before a server has the layered store turned on. On an older client the new
+server-side setting is not just unusable, it is misleading.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.7.0.
+
+### Why this release exists
+
+A working copy is a private index of the branch in your folder, including edits you have not
+committed. The server can now keep several of them per developer, and can store one as a
+layer over the shared project rather than a full copy. Three things in 0.7.0 get in the way.
+
+**A second working copy was refused on your own machine.** 0.7.0 decided by itself that one
+folder already held the project, and never asked the server. Once the server allows several,
+that refusal is simply wrong. Worse, run unattended, by an agent or a script, it threw an
+error advising `niro discard-temp-project` in the other folder. Following that advice
+destroys a working copy that did not need destroying. The client now asks the server and
+does what it says.
+
+**A git worktree of a repo with no remote could not be onboarded at all.** Niro records
+onboarding against the folder that was onboarded, which is the main checkout. A linked
+worktree has no entry of its own, so the repo could not be named and `niro new-temp-project`
+failed. It now resolves the main working tree through `git rev-parse --git-common-dir`.
+That combination, a worktree of a remote-less repo, is the layered store's main use case.
+
+**Large files were dropped from a working copy without telling you.** The size warning
+existed only in `niro init`. A developer ran `niro new-temp-project` and lost their three
+largest source files, the ones the whole branch was about. Niro then answered questions
+about those files from the shared project's older copy, confidently, with nothing on screen
+to say the working copy did not contain them. The warning now runs on both commands, and it
+quotes the limit the server reports rather than a number compiled into the client, which
+said 256 KiB while a server raised to 2 MiB was accepting the file happily.
+
+### Compatibility
+
+Against an older server, the per-file limit is not reported and the client falls back to its
+built-in figure, so the warning quotes an estimate rather than the server's real cap. Nothing
+else changes.
+
+## 0.7.0 — 2026-08-17
+
+A data-loss release. If you use `niro watch`, upgrade.
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+Nothing extra is needed from 0.6.0. **From 0.4.x or earlier, upgrade urgently** — every fix
+below is client-side, so a server update alone does not protect you.
+
+### Why this release exists
+
+On 31 July a repository lost 494 source files. The client reported them deleted, the server
+removed the working copy and the durable backup, and the client's own record then said
+"deleted", so nothing ever re-sent them. Eleven days passed before anyone noticed.
+
+The cause was a `git checkout`. Git removed a directory of test files and wrote it straight
+back a moment later. In that gap the watcher looked, saw nothing, and reported 249 files
+deleted. Everything below follows from that one sentence: **the watcher believed a file was
+gone because it could not see it at one instant.**
+
+### Fixed — the client no longer infers a deletion from a failure to look
+
+- **Deletes now wait for the folder to go quiet.** A file that disappears is queued, not
+  reported. One timer per folder resets on every new disappearance, so a three-file checkout
+  holds for a few seconds and a ninety-second rebase holds for ninety seconds. When the folder
+  settles, whatever is still missing is deleted and whatever came back is dropped.
+
+  This covers `git checkout`, `git stash`, rebases, `npm ci`, `make clean`, a Docker remount and
+  editors that save by deleting and rewriting — without needing to know which of them is
+  happening. A real deletion now reaches the server about five seconds later than before.
+  Set `NIRO_DELETE_SETTLE_MS` to change that.
+
+- **A file that cannot be READ is no longer treated as deleted.** A permission error, a
+  transient lock, a file being rewritten or simply too many open files all made the hash return
+  nothing, and the file was then reported gone. It now keeps its previous state.
+
+- **A DIRECTORY that cannot be read is no longer treated as "everything under it was deleted".**
+  The same mistake one level up, and worse: an unreadable folder lists as empty, which is
+  indistinguishable from one whose files were all removed. Renaming a watched folder and
+  restarting reported the entire project as deleted, in a pass that reported itself successful.
+  An unreadable root now aborts the pass; an unreadable subdirectory keeps its files while the
+  rest of the tree syncs.
+
+- **A delete the server refuses is retried instead of forgotten.** It was marked done regardless
+  of the outcome, and once out of the local record it could never be re-attempted — so a
+  transient error became permanent.
+
+- **`niro discard-temp-project` no longer loses the work done in the temporary project.** The
+  file record followed the folder back to the source repository, so the source appeared to
+  already hold edits it had never received, and the next sync uploaded nothing. Discarding now
+  clears that record and re-uploads once.
+
+- **Excluding a path removes it again.** A guard added in the same work stopped an excluded file
+  ever being removed from the index, which mattered most for a path excluded *because* it holds
+  secrets.
+
+- **No delete calls for files that were never uploaded.** Editor scratch files are rejected on
+  the way in, but a delete was still sent when the editor renamed them away — 21% of all file
+  events on one real repository, every one of them pointless traffic.
+
+### Fixed — the retry flood
+
+- **The 60-second re-scan now backs off.** It retried at full rate forever, so a two-day server
+  problem became roughly 1,400 failed requests a day per folder and buried the real error. The
+  delay now doubles to a 30-minute ceiling and resets on success. It never gives up entirely, so
+  a recovered server is picked up within half an hour on its own.
+
+- **A pass whose file operations failed is no longer counted as a recovery**, which previously
+  reset the backoff mid-incident and printed a green "Sync recovered" while the outage continued.
+
+### Changed — worktrees and temporary projects
+
+You get one temporary project per project, and creating another moves it rather than adding one.
+With several worktrees open that meant they silently took it from each other.
+
+- A second worktree is no longer told to create one. It is told which branch currently holds it
+  and to use its own tools for that folder.
+- `niro discard-temp-project` asks before moving the slot away from another folder.
+- A folder that has lost the slot stops uploading, instead of blending two branches into one copy.
+- A branch switch is now told apart from another folder taking the slot.
+- `niro info` shows which local folder and branch syncs each project, and marks the one you are
+  standing in.
+
+### Also fixed
+
+- **A sync finishing after the folder was re-pointed no longer writes its stale record.** A pass takes
+  minutes on a large tree; if `niro new-temp-project` or `niro discard-temp-project` re-pointed the
+  folder while it ran, its results were written anyway, against a repository they did not describe.
+  For discard that undid the clean slate above and the re-upload was skipped. The record now belongs
+  to one repository and a pass that no longer matches is dropped, the same way a folder release has
+  always been handled.
+
+- **A folder whose root cannot be read now says so once**, and says when it can be read again. It used
+  to repeat the same error every sixty seconds for as long as the folder stayed away.
+
+## 0.6.0 — 2026-08-11
+
+### Upgrading
+
+```bash
+npm install -g @niroai/niro@latest
+```
+
+If you are coming from 0.3.x you also still need `niro mcp install` once per assistant — see
+the 0.5.0 notes below. Upgrading from 0.5.0 needs nothing extra.
+
+### Changed — read this before upgrading
+
+- **`--api-url` now applies to `niro login` only.** Every other command refuses it and exits 1.
+
+  It was a global flag, but only half of the code honoured it. Ordinary API calls took it,
+  while the file-upload path built its own address from your stored credentials and never saw
+  it. So `niro init --api-url http://localhost:8095` while logged in to another backend listed
+  projects from localhost and uploaded your source to the backend you were logged in to. One
+  command, two servers, no warning.
+
+  The backend is a property of a session, not of a single command: your credentials, tokens,
+  repo ids and sync records are all scoped to one backend, so a per-command override could
+  only ever mix them. Choose it once instead:
+
+  ```bash
+  niro login --api-url <url>          # log in to that backend
+  NIRO_API_URL=<url> niro <command>   # or set it for every command
+  ```
+
+  `NIRO_API_URL` and the `apiUrl` config setting still work everywhere, because both feed the
+  same resolution the uploader uses. **If you script `--api-url` on any command other than
+  `login`, that script now fails with a message** telling it which of the two forms to use.
+
+- **`niro init` and `niro add repo` now refuse a folder that is not a project.** Onboarding a
+  folder used to work anywhere, including your home folder, which uploaded source from every
+  project on the machine, pinned `~/.niro-project` and started a watcher over your whole home
+  directory. Two rules now apply before anything is uploaded:
+
+  - Your home folder, the filesystem root, a parent of your home folder and the system folders
+    are refused outright. `--force` does **not** override this.
+  - Any other folder must look like a project: a build file (`package.json`, `pom.xml`, `go.mod`,
+    `*.csproj`, and the rest of the set the indexer already understands) at the folder itself or
+    just below it. A monorepo root whose build files sit one or two levels down is fine.
+
+  **If you script either command**, a folder with no build file now exits `1` where it used to
+  onboard. Pass `--force` for that case. `niro add repo` gains `--force` for this; on `niro init`
+  the existing `--force` now covers it too.
+
+  A folder this backend already has a repo for is exempt from the build-file rule, so an existing
+  sync keeps working. The home and root refusal still applies to it.
+
+  The check runs before the login and before any server call, so a refused folder leaves nothing
+  behind: no registered repo, no orphan project, no pin file, no watcher.
+
+- **`niro init` now notices nested repos deeper in the tree.** The "this folder contains repos
+  already indexed in Niro" refusal only looked two levels down, so it never fired for the common
+  `~/projects/<host>/<org>/<repo>` layout. It now looks four.
+
+## 0.5.0 — 2026-08-06
+
+### Upgrading from 0.3.x — one manual step
+
+```bash
+npm install -g @niroai/niro@latest
+niro mcp install            # once per assistant you use
+```
+
+**The second command is required.** niro's hooks and instruction files are written to your disk at
+install time, so upgrading the package alone leaves the old versions in place — including the
+once-per-session reminder this release fixes. Restart your assistant afterwards; hooks are read at
+startup.
+
+Nothing else is required.
+
+### Added
+
+- **You can now see what Niro did, without asking.** At the end of a task you get one line:
+
+  ```
+  [NIRO] Mapped 29 callers across 8 files that a grep would have missed · 3 calls instead of ~14 searches
+  ```
+
+  The call count is measured by the server. The number of searches it stands in for, and the
+  description, are the assistant's own account of its own work, so that number always carries a `~`
+  to mark it as an estimate. We would rather you trusted a smaller number than doubted a bigger one.
+
+  On a turn where Niro found nothing useful, the description is dropped rather than invented, and
+  you see the bare call count.
+
+- **It also tells you when Niro went unused.** On a turn where the assistant searched your code
+  without asking Niro, you get `[NIRO] Not consulted: this turn used grep and file reads instead`.
+  Until now a skipped turn looked exactly like Niro not being installed, which meant every one of
+  our failures was invisible. Nothing is printed after a turn that did no code work.
+
+- **On by default, including on upgrade.** Turn it off with `niro mcp receipt --off` and back on
+  with `--on`; run it with no flags to see the current state. The setting is per machine.
+
+  Works the same in all twelve supported assistants: the line travels back inside the
+  `mark_task_complete` tool result and your assistant prints it, wrapped in backticks so it renders
+  as code rather than as more of its own prose. If the assistant never calls `mark_task_complete`,
+  no line appears.
+
+### Fixed
+
+- **Codex no longer asks permission for every Niro tool call.** Two causes, both fixed by re-running
+  `niro mcp install`:
+
+  The approval mode was set to `"auto"`, which asks Codex to decide for itself — and it decides to
+  ask. It is now `"writes"`: prompt only for tools that write, and Niro writes nothing. An existing
+  `"auto"` is migrated; a value you chose yourself is left alone.
+
+  Codex also records a per-tool override whenever you answer a prompt with "approve once" rather than
+  "always allow", and a per-tool setting beats the default. Those are now cleared on install.
+
+- **A malformed tool response when a reply contained a backslash, tab or quote.** The
+  `mark_task_complete` response was assembled by a hand-written JSON builder that escaped only the
+  double quote. That was survivable while every value was a fixed keyword, but any free text
+  containing a Windows path or a tab produced JSON the client could not parse, losing the whole
+  response. All control characters are now escaped.
+
+- **The reminder to prefer niro's tools no longer goes quiet mid-session.** Claude Code's
+  `Grep|Glob|Read` hook deduplicated to once per session, per repo, per branch — so it fired early
+  in a session and then said nothing, which is precisely when an agent drifts back to `grep`. It now
+  fires on every native search.
+- **The same reminder was permanently silent in some folders.** It resolved the repo with
+  `git rev-parse --show-toplevel` and gave up when that was empty, so a folder tracked by niro but
+  not a git checkout never got a reminder at all. It now walks up for the `.niro-project` marker
+  directly, and resolves symlinks, so a path reached through a symlinked directory works too.
+- **The reminder's wording let the agent excuse itself.** It offered an "out of scope" escape hatch,
+  which is the exit drift actually takes. Removed; the legitimate native-tool cases (config, docs,
+  logs, generated files) are now named explicitly instead.
+- **A typed project name is now treated as an account-scoped alias.** It was sent as `project_id` and
+  checked with a global lookup, so a name already used by an unrelated account read as taken — or
+  returned a 403 — for a name that was genuinely free for you. The server now assigns the opaque id,
+  and availability is checked against your own account.
+- **`niro init` no longer records a broken project pin.** If the create response carried no
+  `project_id`, the literal text `undefined` was written into `.niro-project` while init reported
+  success; every later tool call then failed with `Project 'undefined' not found`. It now fails
+  loudly at that boundary and pins nothing.
+
+### Added
+
+- The bridge now reports its version and identifies itself (`X-Niro-Cli-Version`,
+  `X-Niro-Bridge`) so the server can tell an out-of-date install to upgrade. The notice is off until
+  a server is deployed with `niro.mcp.cli.min-version` set.
+
+### Not shipped
+
+Two features were built during this cycle and pulled before release. Both are recorded here so the
+reasoning is in the repo rather than only in commit messages.
+
+- **A serve-time self-heal** that would have refreshed stale hooks automatically. Three independent
+  reviews found it deleting users' own settings, widening file permissions on a file that can hold
+  API keys, replacing symlinked configs with regular files, and — with `HOME` unset, the normal case
+  on Windows — writing into the current project folder instead of the home directory. Refreshing
+  hooks stays a manual `niro mcp install`.
+- **A per-prompt reminder hook for Codex.** Codex does support hooks, and the approach works, but
+  installing one means editing `~/.codex/config.toml` — the same file that holds
+  `[mcp_servers.niro]`, so a malformed edit makes Codex reject the whole file and takes niro's
+  registration down with it. Three review rounds found successive defects in that editing, including
+  an uninstall that could delete a hook of the user's own and leave a config Codex would not load.
+  Held back rather than shipped on a fourth attempt; the risk sat entirely in the config surgery,
+  not in the idea.