@niroai/niro 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 Notable changes to `@niroai/niro`. Dates are release dates.
 
+## 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.

package/README.md

@@ -67,6 +67,13 @@ niro build
 ```
 Rebuild the index by hand and watch it finish.
 
+```bash
+niro doctor
+```
+Check this machine against the server and repair what is safe to repair. Today that is
+`niro doctor sync-registry`, which fixes folders and `.niro-project` files left pointing at projects
+that have gone or been renamed. The background watcher runs it for you every six hours.
+
 ---
 
 ## Working on a branch
@@ -85,10 +92,72 @@ niro discard-temp-project
 ```
 Run when the branch is merged. Forgotten copies are cleaned up after two weeks.
 
+If a copy is deleted for you, or a project is renamed, your machine is not told and the folder keeps
+pointing at something that is gone. `niro doctor sync-registry` sorts that out, and the background
+watcher runs it every six hours — see [When a project is deleted](#when-a-project-is-deleted).
+
 Full guide: [docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)
 
 ---
 
+## When a project is deleted
+
+Delete a project, or let an unused private copy expire, and your machine is not told. The folder
+carries on pointing at something that is no longer there.
+
+That is not just untidy. It is what makes `niro new-temp-project` in another folder say the slot is
+already taken, naming a copy that no longer exists. And a `.niro-project` file left naming a deleted
+project keeps answering, because it is read before your git remote.
+
+The background watcher checks every six hours and sorts this out for you. `niro
+doctor sync-registry` does the same thing on demand.
+
+What it does depends on what went missing:
+
+| What is gone | What happens to your folder |
+|---|---|
+| A private copy of a project | Goes back to the original project and carries on syncing |
+| The project itself | Left alone if the repo still exists; unregistered only when both are gone |
+| Neither, just a stale `.niro-project` | Repaired if your git remote says which project it should name; removed if it names nothing and is not shared; otherwise you are told |
+
+It never deletes anything on the server, and it never touches a `.niro-project` file. Everything it
+acts on has already gone. It only acts on what it can check, too: a folder git cannot read, or a
+project it could not reach, is left exactly as it is and reported. A bad connection can never cost
+you a working folder.
+
+**How it decides what to do with a stale `.niro-project`.** That file can hold a project's name
+rather than its id, so a renamed project looks exactly like a deleted one. Niro uses a second signal:
+your folder's git remote. If the remote points at exactly one project, the pin is rewritten to that
+project's id, which cannot be broken by a future rename. If the remote points at nothing either, the
+pin identifies nothing and is removed.
+
+**Unless the file is committed.** A `.niro-project` in git is shared with everyone who clones the
+repo, and what looks like a dead project to you may be a colleague's. Niro never changes a committed
+one for you. It tells you, and you decide.
+
+`niro info` also mentions it when you are standing in an affected folder, so you do not have to go
+looking.
+
+## When you run out of private copies
+
+You get a limited number of private copies of each project. If you hit that limit, Niro tells you
+which branches are holding them, and the CLI adds where each one is checked out:
+
+```
+You already have 5 working copies of this project, which is the limit (5).
+They are for: feature/a, feature/b, feature/c, feature/d, feature/e.
+
+    You have 5 working copies of this project on this machine:
+      feature/a    /home/you/work/service
+      feature/b    /home/you/work/service-wt2
+      ...
+```
+
+Run `niro discard-temp-project` in one you have finished with, then try again. Copies nobody has
+touched for a while are also cleared automatically.
+
+---
+
 ## Measure what Niro changes
 
 ```bash
@@ -181,7 +250,8 @@ Watch this folder in the foreground instead, for one session.
 ## Reference
 
 Add `--help` to any command for its flags. Add `--json` to `whoami`, `info`, `status`,
-`projects`, `build`, `ab report` and `edit --list-env` for machine-readable output.
+`projects`, `build`, `ab report`, `edit --list-env` and `doctor sync-registry` for machine-readable
+output.
 
 | File | What it holds |
 |---|---|

package/docs/working-on-branches.md

@@ -63,6 +63,61 @@ Run this in the repo folder:
 It deletes your private copy. Your local files are never touched.
 If you forget, Niro deletes unused copies by itself after two weeks.
 
+## Tidying up copies that were deleted for you
+
+When a copy goes after two weeks, or somebody deletes it in the web app,
+your machine is not told. The folder is left pointing at a copy that is
+no longer there. Nothing breaks, but "niro new-temp-project" in another
+worktree of the same repo will say the slot is already taken.
+
+Run this from anywhere to sort it out:
+
+    niro doctor sync-registry
+
+You will rarely need to type it. The background watcher runs the same
+check every six hours by itself.
+
+It sorts out three things, and treats them differently:
+
+- A folder pointing at a private copy that has gone goes back to the
+  original project, and carries on syncing.
+- A folder pointing at a project that has gone is only unregistered when
+  the repo has gone too. A project can be deleted while its repos are
+  moved somewhere else, and that folder is still syncing perfectly well.
+- A ".niro-project" file naming something the server does not know is
+  repaired where possible. That file can hold a project's NAME rather
+  than its id, so a renamed project looks exactly like a deleted one.
+  Niro checks your folder's git remote instead: if that points at one
+  project, the file is rewritten to that project's id, which a future
+  rename cannot break. If the remote points at nothing either, the file
+  names nothing and is removed.
+
+  Not if the file is committed to git, though. Then it is shared with
+  everyone who clones the repo, and a project that means nothing to you
+  may be a colleague's. Niro tells you and leaves the choice to you.
+  "niro info" mentions it too, when you are standing in that folder.
+
+Copies that are still there are left alone, and so is anything it could
+not check, so a dropped connection never costs you a working folder. Add
+"--dry-run" to see the list without changing anything.
+
+## When you run out of private copies
+
+You get a limited number of private copies of each project. When you hit
+the limit, Niro says which branches are holding them, and the CLI adds
+where each one is checked out on this machine:
+
+    You already have 5 working copies of this project, which is
+    the limit (5). They are for: feature/a, feature/b, ...
+
+        You have 5 working copies of this project on this machine:
+          feature/a    /home/you/work/service
+          feature/b    /home/you/work/service-wt2
+
+Run "niro discard-temp-project" in one you have finished with, then try
+again. Copies nobody has touched for a while are cleared automatically,
+so this usually sorts itself out.
+
 ## A feature that spans several repos
 
 Run "niro new-temp-project" in each repo folder you branch.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niroai/niro",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "Niro — one package: the niro CLI plus the Niro MCP server (code intelligence for AI coding assistants).",
   "keywords": [
     "niro",