@niroai/niro 0.17.0 → 0.18.0

package/src/index.js

@@ -4,11 +4,14 @@ const { Command } = require("commander");
 const pkg = require("../package.json");
 
 function main() {
+  // Windows: programs started through cmd.exe are not looked up in the current folder first.
+  require("./lib/windowsPaths").harden();
   const program = new Command();
   program
     .name("niro")
     .description("Niro CLI — onboard repos, build indexes, manage projects from the terminal.")
     .version(pkg.version)
+    .addHelpText("after", `\nLanguages: ${require("./lib/languages").supportedList()}.`)
     .option("--api-url <url>", "backend to log in to — `niro login` only (default: $NIRO_API_URL or https://aiorchestrator.niroai.dev)");
 
   // --api-url is accepted by `niro login` and REFUSED everywhere else.
@@ -40,7 +43,7 @@ function main() {
 
   program
     .command("start [path]")
-    .description("First-time setup, end to end: sign in, onboard this folder, connect your AI assistant.")
+    .description("First-time setup, end to end: check this machine, sign in, install the local engine, build this folder's graph, connect your AI assistants.")
     .action((pathArg) => run(async () => {
       const startCmd = require("./commands/start");
       await startCmd.start(pathArg, {});
@@ -57,6 +60,15 @@ function main() {
       await loginCmd.login({ ...opts, apiUrl: program.opts().apiUrl }); // login: the one command that may set it
     }));
 
+  program
+    .command("uninstall")
+    .description("Remove Niro from this machine: assistant entries, the watch daemon, ~/.niro and ~/.niro-local.")
+    .option("-y, --yes", "do not ask for confirmation")
+    .action((opts) => run(async () => {
+      const uninstallCmd = require("./commands/uninstall");
+      await uninstallCmd.uninstall(opts);
+    }));
+
   program
     .command("logout")
     .description("Remove locally stored credentials.")
@@ -65,6 +77,38 @@ function main() {
       await logoutCmd.logout();
     }));
 
+  program
+    .command("plan [action] [folder]")
+    .description("Show your plan, the folders this machine has indexed against its limit, and your options. `niro plan remove <folder>` stops indexing a folder.")
+    .option("--json", "emit machine-readable JSON (niro plan only)")
+    .action((action, folder, opts) => run(async () => {
+      const planCmd = require("./commands/plan");
+      if (action === undefined) return planCmd.plan({ json: !!opts.json });
+      if (action === "remove") return planCmd.remove(folder);
+      throw new Error(`Unknown plan action: ${action}. Use "niro plan" or "niro plan remove <folder>".`);
+    }));
+
+  program
+    .command("share [action] [folder]")
+    .description("Keep folders out of code sharing while Help improve Niro is on. `niro share` lists them, `niro share exclude <folder>` keeps one out, `niro share include <folder>` shares it again.")
+    .action((action, folder) => run(async () => {
+      const shareCmd = require("./commands/share");
+      if (action === undefined) return shareCmd.show();
+      if (action === "exclude") return shareCmd.exclude(folder);
+      if (action === "include") return shareCmd.include(folder);
+      throw new Error(`Unknown share action: ${action}. Use "niro share", "niro share exclude <folder>" or "niro share include <folder>".`);
+    }));
+
+  program
+    .command("request-integration <name>")
+    .description("Ask Niro's team to support a language, framework or tool Niro does not read yet. Asks before sending; the request is kept with your account.")
+    .option("--kind <kind>", "language, framework or tool", "language")
+    .option("--reason <text>", "what you would use it for")
+    .option("-y, --yes", "do not ask for confirmation")
+    .action((name, opts) => run(async () => {
+      await require("./commands/requestIntegration").requestIntegration(name, opts);
+    }));
+
   program
     .command("whoami")
     .description("Print the account currently logged in.")
@@ -74,6 +118,61 @@ function main() {
       await whoami.whoami(opts);
     }));
 
+  program
+    .command("audit-send")
+    .description("Send the local engine's coverage-audit findings (what the graph missed) to Niro.")
+    .option("--limit <n>", "how many waiting items to send in this run (default 50)")
+    .action((opts) => run(async () => {
+      const auditSend = require("./commands/auditSend");
+      await auditSend.auditSend(opts);
+    }));
+
+  program
+    .command("engine [action]")
+    .description("Put the local engine on this machine (install), or say where it is (status).")
+    .option("--force", "download it again even if it is already here")
+    .action((action, opts) => run(async () => {
+      const engineCmd = require("./commands/engine");
+      if (action === undefined || action === "status") return engineCmd.status();
+      if (action === "install") return engineCmd.install(opts);
+      throw new Error(`Unknown engine action: ${action}. Use "install" or "status".`);
+    }));
+
+  program
+    .command("audit-push-repo [path]")
+    .description("Send this folder's indexed files to Niro, masked, so Niro can look at a problem with you. Works with code sharing on or off; asks first.")
+    .option("--force", "send it again even if this folder was sent before")
+    .option("-y, --yes", "skip the confirmation (required when there is no terminal)")
+    .action((pathArg, opts) => run(async () => {
+      const cmd = require("./commands/repoPush");
+      await cmd.pushRepo(pathArg, { ...opts });
+    }));
+
+  program
+    .command("journal-send")
+    .description("Send the local engine's record of which MCP tools were asked for to Niro.")
+    .option("--limit <n>", "how many sessions to send in this run (default 20)")
+    .action((opts) => run(async () => {
+      const journalSend = require("./commands/journalSend");
+      await journalSend.journalSend(opts);
+    }));
+
+  // LLM documentation is off in this release (src/lib/release.js `llmDocs`): the command is not listed, and typed
+  // anyway it says so in one line, the same sentence the engine gives for `niro-local docs`.
+  program
+    .command("docs-send", { hidden: !require("./lib/release").llmDocs })
+    .description("Send the local engine's documentation requests (folders built with --llm) through Niro, once.")
+    .option("--limit <n>", "how many request batches to send in this run (default 20)")
+    .action((opts) => run(async () => {
+      if (!require("./lib/release").llmDocs) {
+        console.error(require("./lib/docsUpload").NOT_IN_THIS_RELEASE);
+        process.exitCode = 2;
+        return;
+      }
+      const docsSend = require("./commands/docsSend");
+      await docsSend.docsSend(opts);
+    }));
+
   program
     .command("init [path]")
     .description("Onboard a local repo end-to-end: create project, register repo, scan env vars, build index.")
@@ -337,8 +436,10 @@ function main() {
     .description("Stop niro-watch and remove it from system startup.")
     .action(() => run(async () => {
       const service = require("./lib/service");
-      service.uninstall();
-      console.log("✓ niro-watch removed.");
+      const r = service.uninstall();
+      if (r === false) return console.log("PM2 is not installed, so there is no niro-watch to remove.");
+      console.log(`${require("./lib/color").green("✓")} niro-watch stopped and removed.`);
+      if (r.hook === "manual") console.log(`  PM2 still starts on login (with nothing of Niro's). To remove that too:  ${r.command}`);
     }));
   svc
     .command("status")
@@ -377,6 +478,12 @@ function main() {
     .option("--on", "Turn the end-of-task line back on.")
     .option("--off", "Stop showing the end-of-task line.")
     .action((opts) => { require("./commands/mcp").receipt(opts); });
+  // Listed so `niro mcp --help` names it. bin/niro.js answers it before this file is loaded,
+  // because it runs at the end of every turn in Claude Code (src/mcp/lineCheck.js).
+  mcp
+    .command("line-check")
+    .description("The Claude Code Stop hook: asks the assistant, once, for the end-of-task line it forgot.")
+    .action(() => {});
 
   // Bare `niro` used to print an 18-command help listing, which is the worst possible
   // first screen for someone who does not yet know what any of them do. With no stored
@@ -386,6 +493,69 @@ function main() {
     process.argv.push("start");
   }
 
+  // The cloud project commands, left out of a release without the cloud (src/lib/release.js).
+  // Registered above and filtered here, so switching the cloud back on is one constant.
+  if (!require("./lib/release").cloud) {
+    const CLOUD_COMMANDS = new Set([
+      "init", "add", "info", "edit", "remove", "new-temp-project", "discard-temp-project",
+      "doctor", "projects", "build", "delete",
+      // Not cloud project commands, but only the cloud serves them so far: `ab` switches the hosted
+      // MCP's A/B window, and `status <project_id>` names a cloud project. Back when local has them.
+      "ab", "status",
+    ]);
+    program.commands = program.commands.filter((c) => !CLOUD_COMMANDS.has(c.name()));
+    // `niro watch` stays: it is what the niro-watch daemon runs (`service.install`), and without it
+    // the daemon crash-looped on "unknown command 'watch'" (2026-11-05). Hidden from --help, since
+    // nobody types it; with no cloud it watches only the local engine's folders (watch.js).
+    const watchCmd = program.commands.find((c) => c.name() === "watch");
+    if (watchCmd) watchCmd._hidden = true;
+    // `niro init` is the local one in this release: add a folder to the engine and build it, with every option of
+    // the engine's own `init`, meaning the same (Niraj, 2026-11-06: "support all option of niro-local init to niro init").
+    program
+      .command("init [path]")
+      .description("Add a folder to the local engine and build its graph, on a machine `niro start` has set up.")
+      .option("--project <name>", "project to join or create (defaults to the folder's own name; a new branch of a repository already indexed becomes that project's temporary copy)")
+      .option("--branch <name>", "the branch of a folder that is not in git; for a folder in git the branch is read from git and this is ignored")
+      .option("--path <folder>", "folder to add (defaults to [path], or the current folder)")
+      .option("--base-url <url>", "the address this folder's service answers on (worked out from the source when left out; an empty value leaves it unset)")
+      .option("--force", "add a folder that holds nothing resembling a project (never a home folder, the filesystem root or a system folder)")
+      .action((pathArg, opts) => run(async () => {
+        await require("./commands/initLocal").initLocal(pathArg, {
+          initOptions: { project: opts.project, branch: opts.branch, path: opts.path, baseUrl: opts.baseUrl, force: Boolean(opts.force) },
+        });
+      }));
+    program
+      .command("status")
+      .description("This folder's graph: indexed or not, last build, plan, connected assistants; then the local engine's own status for the folder.")
+      .option("--json", "emit machine-readable JSON (niro's part only)")
+      .action((opts) => run(async () => {
+        await require("./commands/status").status(undefined, { ...opts });
+        // Then the engine's own answer for this folder (which project holds it, or which it can
+        // join). Not with --json, whose reader expects one JSON object; niro's exit code stands.
+        if (opts.json) return;
+        const own = process.exitCode;
+        console.log("");
+        await require("./commands/engineRoutes").routeToEngine("status", [], { licensed: false });
+        process.exitCode = own;
+      }));
+    program
+      .command("build [path]")
+      .description("Rebuild the graph of a folder already added with `niro init`.")
+      .option("--full", "parse every file again, rather than only what changed")
+      .option("--project <name>", "for a folder several projects hold: build only this project's copy")
+      .action((pathArg, opts) => run(async () => {
+        const buildArgs = [];
+        if (opts.full) buildArgs.push("--full");
+        if (opts.project) buildArgs.push("--project", opts.project);
+        await require("./commands/initLocal").initLocal(pathArg, { rebuildOnly: true, buildArgs });
+      }));
+  }
+
+  // The local engine's other commands, as niro commands (src/commands/engineRoutes.js). After the
+  // filter above, because `remove` and `projects` are routed only while the cloud is off.
+  require("./commands/engineRoutes").register(program, require("./lib/release"));
+  require("./commands/guide").register(program, run); // `niro guide`, the docs in the package (both releases)
+
   program.parseAsync(process.argv).catch((err) => {
     console.error(err && err.message ? err.message : err);
     process.exit(1);
@@ -400,6 +570,7 @@ function run(fn) {
   return Promise.resolve()
     .then(fn)
     .catch((err) => {
+      if (err && err.alreadySaid) process.exit(err.exitCode || 1);
       if (err && (err.code === "ENOAUTH" || err.code === "ENOPROJECT" || err.code === "EAMBIGUOUS")) {
         console.error(err.message);
         process.exit(1);

package/src/lib/agentApi.js

@@ -60,6 +60,37 @@ async function registerRepo({ displayName, repositoryUrl, branch, moduleExcludeP
   return data.git_id;
 }
 
+/**
+ * Register a workspace for `niro audit-push-repo`, marked as shared to help improve Niro.
+ *
+ * The mark is what lets the server delete this code when the account switches sharing off
+ * (ai-orchestrator keeps one `shared_code_repos` record per marked workspace and deletes the
+ * code 7 days after it first sees sharing off). A workspace from `niro init` or `niro add repo`
+ * goes through `registerRepo` above and is never marked, so it is never deleted that way.
+ *
+ * Returns `{ gitId, sharedForImprovement }`. `sharedForImprovement` is true only when the
+ * server echoed the mark back as a real boolean: an older server ignores the unknown field
+ * without saying so, and the caller must then refuse to upload.
+ */
+async function registerSharedRepo({ displayName }) {
+  const data = await api.post("/api/agent/repos", {
+    display_name: displayName,
+    shared_for_improvement: true,
+  });
+  return {
+    gitId: data && data.git_id,
+    sharedForImprovement: Boolean(data) && data.shared_for_improvement === true,
+  };
+}
+
+/**
+ * Delete a workspace record this CLI registered. Used only to take back a shared workspace the
+ * server did not mark (see `registerSharedRepo`), so nothing unmarked is left behind.
+ */
+async function deleteRepo(gitId) {
+  return api.del(`/api/git/${encodeURIComponent(gitId)}`);
+}
+
 /**
  * Fetch backend-suggested module exclude patterns for a repo.
  * Returns an array of { pattern, label, module_count, sample_modules }.
@@ -273,4 +304,4 @@ async function getFormDataImpl() {
   throw new Error("FormData/Blob not available. Node 18+ is required.");
 }
 
-module.exports = { registerRepo, filterManifest, startSync, uploadFileBatch, completeSync, upsertFile, deleteFile, heartbeat, getStatus, repoExists, isRepoNotFound, getModuleExcludeSuggestions, updateModuleExcludePatterns };
+module.exports = { registerRepo, registerSharedRepo, deleteRepo, filterManifest, startSync, uploadFileBatch, completeSync, upsertFile, deleteFile, heartbeat, getStatus, repoExists, isRepoNotFound, getModuleExcludeSuggestions, updateModuleExcludePatterns };

package/src/lib/api.js

@@ -65,7 +65,7 @@ let inFlightRefresh = null;
  *   return the new token.
  * Never logs request/response bodies (they carry the token/api_key).
  */
-async function ensureFreshToken(opts = {}) {
+async function ensureFreshToken() {
   const creds = credentials.load();
   const durable = creds && (creds.cliToken || creds.niroApiKey);
   if (!creds || (!creds.token && !durable)) {
@@ -88,7 +88,7 @@ async function ensureFreshToken(opts = {}) {
   if (inFlightRefresh) {
     return inFlightRefresh;
   }
-  inFlightRefresh = doRefresh(creds, opts.apiUrl || baseUrl(creds)).finally(() => {
+  inFlightRefresh = doRefresh(creds, baseUrl(creds)).finally(() => {
     inFlightRefresh = null;
   });
   return inFlightRefresh;
@@ -126,7 +126,7 @@ async function doRefresh(creds, base) {
   return newToken;
 }
 
-async function request(method, path, { body, query, apiUrl, token, expectStatus, skipRefresh, noAuth, isRetry } = {}) {
+async function request(method, path, { body, query, apiUrl, token, expectStatus, skipRefresh, noAuth, isRetry, signal } = {}) {
   const creds = credentials.load();
   const base = apiUrl || baseUrl(creds);
   const url = new URL(path.startsWith("/") ? path : `/${path}`, base);
@@ -143,6 +143,10 @@ async function request(method, path, { body, query, apiUrl, token, expectStatus,
 
   const init = { method, headers };
   if (body !== undefined) init.body = typeof body === "string" ? body : JSON.stringify(body);
+  // Caller-supplied cancellation, used by anything that must not wait indefinitely (the
+  // licence lease). Nothing changes for a caller that does not pass one: fetch has no timeout
+  // of its own either way.
+  if (signal) init.signal = signal;
 
   let res;
   try {
@@ -159,12 +163,22 @@ async function request(method, path, { body, query, apiUrl, token, expectStatus,
   if (res.status === 401 && !isRetry && !skipRefresh && !token && !noAuth) {
     let fresh;
     try {
-      fresh = await ensureFreshToken({ apiUrl: base });
-    } catch {
+      // At the sign-in service, not at `base`: billing, niro-audit and ai-assistant check a token
+      // but never issue one, so refreshing against them failed and every call to them stayed
+      // refused once the token had expired (2026-11-05: the licence, `niro plan` and the engine
+      // download all broke an hour into a session).
+      fresh = await ensureFreshToken();
+    } catch (err) {
+      // The sign-in service refusing the renewal with 403 is the account itself being refused
+      // (account_blocked, account_waiting: OnPremiseAuthController.cliTokenLogin), not this machine
+      // being signed out. Passed on as that 403, so the licence channel tells the engine REFUSED
+      // instead of reading it as "billing unreachable" and letting an open session run on until
+      // the lease's offline allowance ends (2026-11-11). Any other failure stays the original 401.
+      if (err && err.status === 403) throw err;
       fresh = null;
     }
     if (fresh) {
-      return request(method, path, { body, query, apiUrl, token: fresh, expectStatus, isRetry: true });
+      return request(method, path, { body, query, apiUrl, token: fresh, expectStatus, isRetry: true, signal });
     }
   }
 

package/src/lib/auditUpload.js

@@ -0,0 +1,293 @@
+/**
+ * Sends the local engine's coverage-audit findings to niro-audit.
+ *
+ * Why this lives here and not in the engine: the engine holds no account and no credential,
+ * by design. It indexes code and writes what it found to its own queue. Anything that
+ * leaves the machine leaves through the CLI, which is the part that signed in.
+ *
+ * So the engine is asked for finished payloads and told which ones arrived, and this file
+ * never builds a payload itself:
+ *
+ *   niro-local audit --emit                 JSON Lines, one per waiting item
+ *   POST <audit>/api/audit/items            each item's `payload`, verbatim
+ *   POST <audit>/api/audit/items/resolve    for a file that came back clean
+ *   niro-local audit --mark-sent            tab-separated rows of what arrived
+ *   POST <audit>/api/audit/catalog          a folder's catalogue signals (kind "catalog", since 2026-11-09)
+ *   niro-local audit --mark-catalog-sent    tab-separated (folder id, sha) of the catalogues that arrived
+ *
+ * Keeping the field names on the engine's side of that line means the wire format has one
+ * home. If the server adds a field, the engine changes and this file does not.
+ *
+ * A 409 is success, not failure: the server's unique dedup index refused a file it already
+ * holds for that content hash, which is exactly what we want it to do. The row is marked
+ * sent so the engine stops offering it.
+ *
+ * Nothing here logs a payload. They carry the customer's source.
+ *
+ * **Two gates before anything leaves.** The lease must be readable (a machine that is not signed
+ * in, or cannot reach its plan, sends nothing at all, not even a request); sharing is NOT asked,
+ * because the coverage audit is sent on every plan (2026-11-05; until then it needed
+ * `share_code: true`, design §6.6). Then every payload is redacted. The engine has already masked
+ * its secrets with llm-gateway's rules (niro-local `docs/usecases/on-machine-redaction.md`) and
+ * says so with `redacted` on each line; a line without it comes from an older engine that masked
+ * nothing, so it is left in the queue, not sent, until the engine is updated. Here redact.js then
+ * removes author and company names, with `sha` kept as the dedup key. The engine's payload is
+ * otherwise posted as it came; a clean file goes byte for byte.
+ */
+const path = require("path");
+
+const localEngine = require("./localEngine");
+const api = require("./api");
+const lease = require("./lease");
+const credentials = require("./credentials");
+const git = require("./git");
+const { redactItem } = require("./redact");
+
+/** Production niro-audit (ECS niro-aws-audit-service behind niro-aws-lb). NIRO_AUDIT_URL overrides it. */
+const DEFAULT_AUDIT_URL = "https://audit.cloud.niroai.dev";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_BATCH = 50;
+
+/** Which audit service to post to. */
+/** Env var, then `auditUrl` in ~/.niro/config.json (as journalUpload reads mcpServerUrl), then the service. */
+function auditUrl() {
+  let configured = null;
+  try { configured = require("./config").load().auditUrl; } catch { /* the default */ }
+  return (process.env.NIRO_AUDIT_URL || configured || DEFAULT_AUDIT_URL).replace(/\/+$/, "");
+}
+
+/** An API key, only if one was deliberately put in the environment. */
+function apiKey() {
+  return process.env.NIRO_AUDIT_API_KEY || process.env.NIRO_API_KEY || "";
+}
+
+/**
+ * What this machine authenticates with, resolved once per run.
+ *
+ * Normally it is the login token: `niro login` leaves a short-lived JWT behind, and
+ * niro-audit now verifies it on the two routes this file uses. Niraj, 2026-10-15: "we don't
+ * work with any api tokens any more", and "niro-audit should also accept a cli token from a
+ * developer machine". So a developer needs nothing beyond being logged in, and no API key is
+ * ever created for, or stored on, their machine.
+ *
+ * `api.ensureFreshToken` is reused rather than reimplemented: it returns the stored token when
+ * it is still good and otherwise exchanges the durable CLI token for a new one, sharing a
+ * single refresh between concurrent callers. A second copy of that logic here would be a
+ * second thing to get wrong, and this runs from a watcher that may be up for hours.
+ *
+ * An API key in the environment wins when one is set, for the upload's own header only. It is
+ * not a way round `niro login`: the plan is read through the sign-in first (uploadPending), and
+ * the watcher is never given the key. Letting it win keeps a deployment working whose niro-audit
+ * has no JWT secret configured yet. Nothing creates it; it is only read.
+ */
+async function authHeaders(freshToken) {
+  const key = apiKey();
+  if (key) {
+    return { "Content-Type": "application/json", "X-API-Key": key };
+  }
+  try {
+    return {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${await freshToken()}`,
+    };
+  } catch (err) {
+    if (err && err.code === "ENOAUTH") {
+      // The key is not a way round the sign-in: the plan is read through the `niro login` sign-in
+      // before anything is sent (uploadPending, lease.currentClaims), and the watcher is never given
+      // the key (service.js WATCHER_ENV_EXCLUDED). Saying "set the key instead" sent people to a
+      // dead end (docs/connect-ci.md).
+      throw new Error(
+        `${err.message} The audit is not sent without that sign-in, because it reads your plan through it first. ` +
+          "NIRO_AUDIT_API_KEY only changes the key the upload itself is signed with, so it does not help on its own."
+      );
+    }
+    throw err;
+  }
+}
+
+async function postJson(path, body, headers) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    return await fetch(`${auditUrl()}${path}`, {
+      method: "POST",
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Send everything the engine is holding.
+ *
+ * Returns counts rather than printing, so a caller can report it its own way: the command
+ * prints, and the watcher will log one line.
+ */
+/** The owner in a git remote: `acme` from git@github.com:acme/x.git or https://host/acme/x. */
+function remoteOwner(originUrl) {
+  const m = /[:/]([^/:]+)\/[^/]+?(?:\.git)?\/?$/.exec(originUrl || "");
+  return m ? m[1] : null;
+}
+
+/** worktree id → its git remote owner, from the engine's project list. Empty when unknown. */
+async function ownersByWorktree() {
+  const owners = {};
+  try {
+    const parsed = JSON.parse(await localEngine.run(["projects", "--json"]));
+    for (const project of parsed.projects || []) {
+      for (const w of project.worktrees || []) {
+        owners[w.id] = remoteOwner(git.inspect(path.resolve(String(w.path))).originUrl);
+      }
+    }
+  } catch {
+    // Without an owner the email domain and copyright holders are still removed.
+  }
+  return owners;
+}
+
+/**
+ * A niro-audit older than the catalogue route (2026-11-09) refuses it: a login token on a route that is not one
+ * of its sending routes is answered 403 `admin_required`, and an admin's or a key's request finds no route (404 or
+ * 405). The catalogue then waits in the engine's queue for a server that takes it; it is not a failure of the audit.
+ */
+async function serverTakesNoCatalogue(response) {
+  if (response.status === 404 || response.status === 405) return true;
+  if (response.status !== 403) return false;
+  const text = await response.text().catch(() => "");
+  return text.includes("admin_required");
+}
+
+async function uploadPending({ limit = DEFAULT_BATCH, freshToken = api.ensureFreshToken } = {}) {
+  const result = {
+    submitted: 0, duplicate: 0, resolved: 0, closedNothing: 0, catalogs: 0, catalogsWaiting: 0, failed: 0, failures: [],
+  };
+
+  // First of all: is there a `niro login` sign-in? Without one the plan read below fails too, and the
+  // user saw only "the plan could not be read", which hid the cause. The same rule as every command
+  // that needs a sign-in (credentials.requireCreds); an API key in the environment does not count.
+  try {
+    credentials.requireCreds(credentials.load());
+  } catch (err) {
+    if (!err || err.code !== "ENOAUTH") throw err;
+    result.skipped = "not signed in. The audit reads your plan through your `niro login` sign-in, so run `niro login` first";
+    return result;
+  }
+
+  // Then, before a token or the queue: is this machine signed in to a readable plan?
+  // Sharing is not asked: the coverage audit (redacted flagged files) is sent on every plan,
+  // like the tool-usage record. Only a whole-repository push needs sharing on (repoPush.js).
+  // Divya, 2026-11-05: "only full repo audit should not come when sharing is off".
+  // Since 2026-11-11 that holds for the background code sharing (shareCode.js) only: a typed
+  // `niro audit-push-repo` sends with sharing off, because typing it and answering yes is the consent.
+  const claims = await lease.currentClaims().catch(() => null);
+  if (!claims) {
+    result.skipped = "the plan could not be read, so nothing was sent";
+    return result;
+  }
+
+  // Before the engine is asked for anything, so a machine that cannot authenticate does not
+  // pull payloads out of the queue only to fail to send them. Resolved once for the whole run:
+  // the token outlives a batch, and refreshing per item would be a request per file.
+  const headers = await authHeaders(freshToken);
+
+  const emitted = await localEngine.run(["audit", "--emit", "--limit", String(limit)]);
+  const items = emitted
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  const email = (credentials.load() || {}).email || null;
+  const owners = items.some((i) => i.kind === "submission") ? await ownersByWorktree() : {};
+
+  const sent = [];
+  const catalogsSent = [];
+  for (const item of items) {
+    if (item.kind === "not_sent") {
+      // Flagged files the engine dropped: not UTF-8 text (it cannot mask them), or, since 2026-11-09, a
+      // whole file an older engine queued that could not be cut to a snippet, or a snippet that failed its
+      // check. Counted, never named. A line with no reason is from an engine that only had the first.
+      const count = Number(item.count) || 0;
+      if (!item.reason || item.reason === "not UTF-8 text") result.notText = (result.notText || 0) + count;
+      else result.notSnippet = (result.notSnippet || 0) + count;
+      continue;
+    }
+    if (!item.redacted) {
+      // An older engine: its payload was never masked. Kept in its queue, not marked, not sent.
+      result.unmasked = (result.unmasked || 0) + 1;
+      continue;
+    }
+    try {
+      if (item.kind === "submission") {
+        // Throws on source it cannot read, which lands in the catch below: kept, not sent.
+        const payload = redactItem(item.payload, { email, remoteOwner: owners[item.worktree_id] || null });
+        const response = await postJson("/api/audit/items", payload, headers);
+        if (response.status === 201 || response.ok) {
+          result.submitted += 1;
+        } else if (response.status === 409) {
+          // Already held for this content hash. The server's dedup index did its job.
+          result.duplicate += 1;
+        } else {
+          result.failed += 1;
+          result.failures.push(`${item.source_id}: HTTP ${response.status}`);
+          continue;
+        }
+        sent.push([item.worktree_id, item.source_id, item.sha].join("\t"));
+      } else if (item.kind === "catalog") {
+        // What one build of one folder tells the catalogue: extensions read in no language and outside library
+        // names, with counts. The engine leaves out every file name, path, import line and own-code name
+        // (niro-local audit/catalog.py), so there is no source to redact; it is posted as the engine wrote it.
+        const response = await postJson("/api/audit/catalog", item.payload, headers);
+        if (response.status === 201 || response.ok) {
+          result.catalogs += 1;
+          catalogsSent.push([item.worktree_id, item.sha].join("\t"));
+        } else if (await serverTakesNoCatalogue(response)) {
+          result.catalogsWaiting += 1;
+        } else {
+          result.failed += 1;
+          result.failures.push(`catalogue: HTTP ${response.status}`);
+        }
+      } else if (item.kind === "resolution") {
+        // repoId matters: the server's resolve matches on (project, repo, file), so a
+        // request without it matches nothing and still answers 200. Reading the count it
+        // returns is what tells a real close from a no-op.
+        const query = new URLSearchParams({
+          projectId: item.project_id,
+          repoId: item.repo_id || "",
+          // The path as the server holds it: masked by the engine exactly as the submission was.
+          sourceId: item.masked_source_id || item.source_id,
+        });
+        const response = await postJson(`/api/audit/items/resolve?${query}`, undefined, headers);
+        if (!response.ok) {
+          result.failed += 1;
+          result.failures.push(`${item.source_id} (resolve): HTTP ${response.status}`);
+          continue;
+        }
+        const closed = await response
+          .json()
+          .then((body) => (body && body.data && body.data.resolved) || 0)
+          .catch(() => 0);
+        result.resolved += closed;
+        result.closedNothing += closed === 0 ? 1 : 0;
+        sent.push([item.worktree_id, item.source_id].join("\t"));
+      }
+    } catch (problem) {
+      // One item failing must not lose the rest: it stays queued and is retried next time.
+      result.failed += 1;
+      result.failures.push(`${item.source_id || item.kind}: ${problem.message}`);
+    }
+  }
+
+  // Only what actually arrived is marked, so a failure is retried rather than forgotten.
+  if (sent.length > 0) await localEngine.run(["audit", "--mark-sent"], sent.join("\n") + "\n");
+  if (catalogsSent.length > 0) {
+    await localEngine.run(["audit", "--mark-catalog-sent"], catalogsSent.join("\n") + "\n");
+  }
+
+  return result;
+}
+
+module.exports = { uploadPending, auditUrl, remoteOwner, DEFAULT_AUDIT_URL };