@niroai/niro 0.17.0 → 0.18.0

package/src/lib/branchDrift.js

@@ -0,0 +1,149 @@
+/**
+ * Tell a developer when one project's folders have drifted onto different branches.
+ *
+ * **What a local project is.** The engine (`niro-local`) indexes one or more folders as one
+ * project, and every folder's nodes live in one graph. That is what makes a cross-service
+ * question possible: service A's call can be linked to service B's handler.
+ *
+ * **What goes wrong after they are attached.** Attaching is guarded: the engine reads each
+ * folder's branch from `.git/HEAD` and refuses a folder whose branch differs from the project's.
+ * Since 2026-11-04 the engine also keeps one index per folder AND branch, and on every call
+ * answers from the index of the branch the folder is on now, or offers to index it (Niraj:
+ * "when branch changes, we don't warn but we can offer to index the same folder that's on a
+ * different branch or then switch to the respective project"). So the mixed graph this notice
+ * was written for now arises only for a project attached before branches were read, whose
+ * folders have since gone separate ways. The notice stays for those.
+ *
+ * **Why the engine is asked and git is read here as well.** One folder can now be listed in two
+ * projects, one per branch, so the project holding this folder is the one whose row is for the
+ * branch git reports now (`projectHolding`).
+ *
+ * Nothing here changes an answer. It adds a line to one, once per session.
+ */
+const path = require("path");
+
+const git = require("./git");
+const localEngine = require("./localEngine");
+
+/**
+ * The project the engine says holds this folder, with the folders it holds, or null.
+ *
+ * Null for every reason that is not this notice's business: no engine on the machine, an
+ * engine that cannot answer, a folder in no project, or output that does not parse. A missing
+ * answer here must never stop a tool call.
+ */
+async function projectHolding(dir, { run = localEngine.run, inspect = git.inspect } = {}) {
+  let out;
+  try {
+    out = await run(["projects", "--json"]);
+  } catch {
+    return null;
+  }
+  let parsed = null;
+  try {
+    parsed = JSON.parse(out);
+  } catch {
+    return null;
+  }
+  const projects = (parsed && Array.isArray(parsed.projects) && parsed.projects) || [];
+  const resolved = path.resolve(dir);
+  let best = null;
+  for (const project of projects) {
+    for (const worktree of (project && project.worktrees) || []) {
+      if (!worktree || typeof worktree.path !== "string") continue;
+      const folder = path.resolve(worktree.path);
+      // The folder itself, or an ancestor of it: a session can start in a subdirectory, and
+      // the engine resolves a worktree the same way. The longest match wins, so a worktree
+      // nested inside another is attributed to the nearer one.
+      const inside = resolved === folder || resolved.startsWith(folder + path.sep);
+      if (!inside) continue;
+      if (!best || folder.length > best.folder.length) {
+        best = { folder, rows: [{ project, branch: worktree.branch || null, used: worktree.last_used_at || "" }] };
+      } else if (folder.length === best.folder.length) {
+        best.rows.push({ project, branch: worktree.branch || null, used: worktree.last_used_at || "" });
+      }
+    }
+  }
+  if (!best) return null;
+  // The project whose row is for the branch the folder is on now, as the engine chooses
+  // (`registry.choose_row`), whether the folder has one row or several. None when no row is for
+  // that branch: the engine then answers with the offer to index it and from no project, so a
+  // notice about a project's branches would describe a project that is not answering (independent
+  // check, verify/offer/drift.js). A row with no branch, or a folder git cannot name a branch for
+  // (outside git, detached), answers from the engine's last used row.
+  let now = null;
+  try {
+    now = (inspect(best.folder) || {}).branch || null;
+  } catch {
+    now = null;
+  }
+  // Several projects can hold one folder on one branch (a shared library, a copy per project): the
+  // one used last answers, as the engine chooses.
+  const lastUsed = (rows) => rows.reduce((best2, row) => (!best2 || row.used > best2.used ? row : best2), null);
+  if (now === null) return lastUsed(best.rows).project;
+  const match = lastUsed(best.rows.filter((row) => row.branch === now))
+    || (best.rows.length === 1 && best.rows[0].branch === null ? best.rows[0] : null);
+  return match ? match.project : null;
+}
+
+/**
+ * Which branch each of this project's folders was indexed on, and whether they disagree.
+ *
+ * The branch a row records is what its part of the graph holds, whichever branch the folder has
+ * moved to since: a folder that moved answers from another project, or a temporary copy, and this
+ * project's graph is still one branch's. So only a row recorded with no branch (attached before
+ * branches were read) is looked up from git (independent check, finding 1).
+ *
+ * Returns null when there is nothing to say: no project, one folder, git cannot answer for
+ * enough of them, or they all agree. A folder git cannot answer for (no repository, a detached
+ * HEAD) is left out rather than reported as a disagreement, because "no branch" is not a
+ * different branch and guessing would make this noise.
+ */
+async function check(dir, { run = localEngine.run, inspect = git.inspect } = {}) {
+  const project = await projectHolding(dir, { run, inspect });
+  if (!project) return null;
+  const folders = [];
+  for (const worktree of project.worktrees || []) {
+    if (!worktree || typeof worktree.path !== "string") continue;
+    let branch = worktree.branch || null;
+    if (!branch) {
+      try {
+        branch = (inspect(worktree.path) || {}).branch || null;
+      } catch {
+        branch = null;
+      }
+    }
+    if (branch) folders.push({ path: worktree.path, branch, recorded: worktree.branch || null });
+  }
+  // One set of branch names decides it, and it covers the small cases too: a project with
+  // one folder, or one folder git could answer for, has one name in that set and therefore
+  // nothing to disagree with. A separate count of the folders read the same way and could not
+  // be made to fail a test, so it is not here.
+  const branches = [...new Set(folders.map((entry) => entry.branch))].sort();
+  if (branches.length < 2) return null;
+  return { name: project.name, folders, branches };
+}
+
+/** The notice, as one block of text, or null when `check` found nothing. */
+function notice(found) {
+  if (!found) return null;
+  const lines = [
+    `NOTE FROM niro: the folders of project '${found.name}' are on different branches ` +
+      `(${found.branches.join(", ")}), so an answer that crosses them links one branch's ` +
+      "calls to another branch's code.",
+  ];
+  for (const entry of found.folders) {
+    lines.push(`  ${entry.path} is on ${entry.branch}`);
+  }
+  lines.push(
+    "Put them on one branch, or ask only about the folder this session is in."
+  );
+  return lines.join("\n");
+}
+
+/** `check` and `notice` in one call, which is how the bridge uses it. */
+async function noticeFor(dir, options = {}) {
+  return notice(await check(dir, options));
+}
+
+module.exports = { check, notice, noticeFor, projectHolding };

package/src/lib/choose.js

@@ -0,0 +1,116 @@
+/**
+ * Arrow-key pickers for the wizards: ↑/↓ (or j/k) move, space ticks (multi), a ticks all, enter confirms.
+ *
+ * No dependency: stdin raw mode plus readline's keypress events. `reduce` is the whole
+ * behaviour as a pure function, so it is tested without a terminal. Without a TTY the
+ * picker answers with its defaults instead of hanging.
+ */
+const readline = require("readline");
+const color = require("./color");
+
+/** One key applied to the picker state. Returns the next state; `done` holds the answer. */
+function reduce(state, key) {
+  const { cursor, picked, count, multi } = state;
+  const name = key && key.name;
+  if (name === "up" || name === "k") return { ...state, cursor: (cursor - 1 + count) % count };
+  if (name === "down" || name === "j") return { ...state, cursor: (cursor + 1) % count };
+  if (multi && name === "space") {
+    const next = new Set(picked);
+    if (next.has(cursor)) next.delete(cursor);
+    else next.add(cursor);
+    return { ...state, picked: next };
+  }
+  if (multi && name === "a") {
+    // Everything, or nothing when everything is already ticked.
+    const all = picked.size === count;
+    return { ...state, picked: new Set(all ? [] : Array.from({ length: count }, (_, i) => i)) };
+  }
+  if (name === "return" || name === "enter") {
+    if (!multi) return { ...state, done: [cursor] };
+    // Enter with nothing ticked means "this one", the way a single picker reads.
+    return { ...state, done: picked.size ? [...picked].sort((a, b) => a - b) : [cursor] };
+  }
+  return state;
+}
+
+function render(items, state, pad) {
+  const width = Math.max(...items.map((it) => it.label.length));
+  return items.map((it, i) => {
+    const here = i === state.cursor;
+    const pointer = here ? color.cyan("❯") : " ";
+    const box = state.multi ? `${state.picked.has(i) ? color.green("◉") : "◯"} ` : "";
+    const name = it.detail ? it.label.padEnd(width) : it.label;
+    const label = here ? color.bold(name) : name;
+    return `${pad}${pointer} ${box}${label}${it.detail ? `   ${color.dim(it.detail)}` : ""}`;
+  });
+}
+
+/**
+ * Ask once. `items` are { value, label, detail? }; `initial` the values ticked (multi) or
+ * under the cursor (single) to begin with; `echo: false` when the caller prints the answer itself.
+ * Resolves to an array of values (multi) or one value.
+ */
+function choose({ items, multi = false, initial = [], prefix = "    ", hint, echo = true } = {}) {
+  const start = items.findIndex((it) => initial.includes(it.value));
+  let state = {
+    cursor: Math.max(0, start),
+    picked: new Set(multi ? items.map((it, i) => (initial.includes(it.value) ? i : -1)).filter((i) => i >= 0) : []),
+    count: items.length,
+    multi,
+    done: null,
+  };
+  const answer = (idx) => (multi ? idx.map((i) => items[i].value) : items[idx[0]].value);
+
+  const input = process.stdin;
+  if (!input.isTTY) return Promise.resolve(answer(multi && state.picked.size ? [...state.picked] : [state.cursor]));
+
+  const out = process.stdout;
+  const help = hint || (multi ? "↑/↓ move · space select · a all · enter confirm" : "↑/↓ move · enter select");
+  let drawn = 0;
+  const draw = () => {
+    if (drawn) {
+      readline.moveCursor(out, 0, -drawn);
+      readline.clearScreenDown(out);
+    }
+    const lines = [...render(items, state, prefix), `${prefix}${color.dim(help)}`];
+    out.write(lines.join("\n") + "\n");
+    drawn = lines.length;
+  };
+
+  return new Promise((resolve) => {
+    readline.emitKeypressEvents(input);
+    const wasRaw = input.isRaw;
+    input.setRawMode(true);
+    input.resume();
+    out.write("\x1b[?25l"); // hide the caret while the list owns the screen
+    const finish = () => {
+      input.removeListener("keypress", onKey);
+      input.setRawMode(wasRaw);
+      input.pause();
+      out.write("\x1b[?25h");
+    };
+    const onKey = (_s, key) => {
+      if (key && key.ctrl && key.name === "c") {
+        finish();
+        out.write("\n");
+        process.exit(130);
+      }
+      state = reduce(state, key);
+      if (state.done) {
+        finish();
+        // Collapse the list to the answer, so the transcript keeps only what was chosen.
+        readline.moveCursor(out, 0, -drawn);
+        readline.clearScreenDown(out);
+        const chosen = state.done.map((i) => items[i].label).join(", ");
+        if (echo) out.write(`${prefix}${color.green("✓")} ${chosen}\n`);
+        resolve(answer(state.done));
+        return;
+      }
+      draw();
+    };
+    input.on("keypress", onKey);
+    draw();
+  });
+}
+
+module.exports = { choose, reduce };

package/src/lib/cloudGuard.js

@@ -0,0 +1,74 @@
+/**
+ * Stop a cloud command from being run on a folder the engine on this machine already indexes.
+ *
+ * **The problem this exists for.** Three commands put a folder into Niro's cloud: `niro init`,
+ * `niro add repo` and `niro build`. None of them knew about the local engine, so a developer
+ * whose folder is indexed on their own machine could run one of them and have that folder's
+ * source uploaded and indexed a second time. Nothing broke: the MCP bridge answers every tool
+ * call from the local graph whether or not a cloud copy exists, and the watcher takes the local
+ * branch before it reaches the cloud one. What was lost was the only reason to choose the local
+ * engine, which is that the source stays on the machine. The customer also paid for two indexes
+ * of one folder, and the cloud copy then went quietly stale, because nothing ever asked it
+ * anything again.
+ *
+ * **Why a refusal and not a prompt.** `niro build` is run from scripts, and `niro init` is run
+ * by the setup wizard. A prompt in either would hang a script with no terminal attached. A
+ * refusal with the two commands that resolve it is readable in a log and cannot hang.
+ *
+ * **Why `niro new-temp-project` is NOT guarded**, although it uploads a working tree too:
+ * temporary projects stay in the cloud on purpose (decision 3 of the plan), because they serve
+ * pull request review and root cause analysis, which the local engine does not do. It is also
+ * run automatically by an assistant following `should_create_temp_project`, so a refusal there
+ * would break that route. It gets `noticeIfIndexedLocally` instead, which says what is about to
+ * happen in one line and carries on.
+ */
+const localBuild = require("./localBuild");
+const color = require("./color");
+
+/**
+ * Refuse `command` when `dir` is indexed by the engine on this machine.
+ *
+ * Returns true when it refused, so the caller returns without doing anything else. Sets
+ * `process.exitCode`, rather than throwing, so a refusal reads as a refusal in a script
+ * instead of as a crash.
+ *
+ * A machine with no engine, or one whose engine cannot be run, answers "not indexed locally"
+ * (`localBuild.isLocallyIndexed` swallows the failure), so every existing customer is
+ * unaffected by this check.
+ */
+async function refuseIfIndexedLocally(dir, { command, log = console.error } = {}) {
+  if (!(await localBuild.isLocallyIndexed(dir))) return false;
+  log("");
+  log(color.red(`    This folder is indexed on this machine, so \`niro ${command}\` was not run.`));
+  log("");
+  log(`    ${dir}`);
+  log("    is held in the local graph by niro-local. Running this command would upload its");
+  log("    source to Niro and index it a second time, which is the one thing the local engine");
+  log("    is for, and you would be charged for both copies.");
+  log("");
+  log(`    To update the local index:   ${color.bold(`niro-local build --path ${dir}`)}`);
+  log(`    To move it to the cloud:     ${color.bold(`niro-local remove --path ${dir}`)}`);
+  log(`                                 then run \`niro ${command}\` again`);
+  log("");
+  process.exitCode = 1;
+  return true;
+}
+
+/**
+ * Say that this folder is indexed locally, and carry on.
+ *
+ * For a command that is allowed to reach the cloud for a locally indexed folder, where the
+ * developer should still know that a copy of the working tree is about to leave the machine.
+ */
+async function noticeIfIndexedLocally(dir, { what, log = console.log } = {}) {
+  if (!(await localBuild.isLocallyIndexed(dir))) return false;
+  log("");
+  log(color.yellow(`    Note: this folder is indexed on this machine by niro-local.`));
+  log(`    ${what} uploads a copy of the working tree to Niro anyway, because it serves`);
+  log("    pull request review and root cause analysis, which the local graph does not answer.");
+  log("    Your local index and the answers from it are unchanged.");
+  log("");
+  return true;
+}
+
+module.exports = { refuseIfIndexedLocally, noticeIfIndexedLocally };

package/src/lib/credentials.js

@@ -52,8 +52,8 @@ function isExpired(token) {
   }
 }
 
-function requireCreds() {
-  const c = load();
+/** `c` defaults to the saved file; a caller that read it through the module (so a test can stub it) passes it in. */
+function requireCreds(c = load()) {
   // Only block when there is no usable credential at all. If the JWT is
   // expired but a durable cliToken exists, the request layer will
   // transparently refresh it, so do not throw here.

package/src/lib/docsMarked.js

@@ -0,0 +1,55 @@
+/**
+ * Whether any folder on this machine is built with `niro-local build --llm`, for `niro docs-send`.
+ * Split out of docsUpload.js so that file stays under the monorepo's 500-line flag.
+ *
+ * Two ways to find out, newest first: ask the engine `docs --marked`, which needs no licence,
+ * and, for an engine from before that flag, read what `docs --emit` printed.
+ */
+const localEngine = require("./localEngine");
+
+/**
+ * Whether `docs --emit` found any folder built with --llm, read from its standard error. Used
+ * only with an engine that cannot answer `docs --marked` (see markedFolders).
+ *
+ * `docs --model-info` cannot say: it answers before the engine looks at any folder (niro-local
+ * `reuse/command.py`, the `args.model_info` branch returns first). The emit path prints
+ * "<n> request lines for <m> methods" only after it has gone through the marked folders, and
+ * "No folder is built with --llm" instead when there are none (same file). The positive line is
+ * matched, not the negative one, so a reworded message errs towards NOT downloading 90 MB onto
+ * a machine that never asked for documentation.
+ */
+function foldersMarked(emitNotes) {
+  return /\d+ request lines for \d+ methods/.test(String(emitNotes || ""));
+}
+
+/**
+ * How many folders are built with --llm, asked of the engine without a licence:
+ * `niro-local docs --marked`, one JSON line `{"marked": <n>}` on standard output, exit 0.
+ *
+ * That flag is the engine change this needs (NOTES.md, "Engine change needed"): the engine has
+ * no unlicensed way to say it today. `docs --model-info` is the only unlicensed docs action and
+ * answers before any folder is looked at (niro-local `cli.py` `_cmd_docs`, `reuse/command.py`).
+ *
+ * Returns the number, "no-engine" when there is no engine to run, or null when this engine
+ * cannot say: an older engine refuses the unknown flag (argparse exits 2), and anything else
+ * that is not exactly the shape above is treated the same, so the round falls back to emit
+ * rather than skipping documentation on a misread.
+ */
+async function markedFolders() {
+  let out;
+  try {
+    out = await localEngine.run(["docs", "--marked"]);
+  } catch (err) {
+    const message = (err && err.message) || String(err);
+    return /^cannot run /.test(message) ? "no-engine" : null;
+  }
+  try {
+    const parsed = JSON.parse(String(out).trim());
+    const n = parsed && parsed.marked;
+    return Number.isInteger(n) && n >= 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { markedFolders, foldersMarked };

package/src/lib/docsState.js

@@ -0,0 +1,213 @@
+/**
+ * The two pieces of state `niro docs-send` keeps on disk, under ~/.niro, split out of
+ * docsUpload.js so each file has one job.
+ *
+ *   - `docs-backoff.json`: batch hashes and times, so a batch the service keeps failing on is
+ *     asked for less and less often instead of on every round. Never code.
+ *   - `docs-send.lock`: who is running a round now, so the watcher and a person typing
+ *     `niro docs-send` never send the same batch twice at once.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/** Backoff: 10 minutes after the first failure, doubling, never more than a day. */
+const BACKOFF_BASE_MS = 10 * 60 * 1000;
+const BACKOFF_MAX_MS = 24 * 60 * 60 * 1000;
+/** A backoff entry this long past its time is forgotten: the batch has gone or succeeded. */
+const BACKOFF_FORGET_MS = 7 * 24 * 60 * 60 * 1000;
+/** And the file never holds more than this many, newest kept, so it cannot grow for ever. */
+const BACKOFF_MAX_ENTRIES = 5000;
+
+/** A lock file this old with no pid in it is a crash between create and write, not a run. */
+const EMPTY_LOCK_GRACE_MS = 10_000;
+
+/**
+ * A lock not touched for this long is taken over whatever its pid says.
+ *
+ * Why it is needed: a pid is reused. A lock left by a run that died can name a pid that now
+ * belongs to an unrelated live process (the independent check found pid 1 in a three-day-old
+ * lock), and the pid test alone would then block documentation for ever.
+ *
+ * Why two hours: a live run touches the lock before every step (emit, each model file, each
+ * batch, the import), so the age is the length of ONE step, not of the round. The longest step
+ * by default is a model file download (`NIRO_DOCS_MODEL_TIMEOUT_MS`, 15 minutes) or one batch
+ * (`NIRO_DOCS_TIMEOUT_MS`, 180 seconds); emit on a large first build, which embeds every
+ * documented method, is the only step without a timeout of its own and is minutes, not hours.
+ * Two hours is eight times the longest timed step, and a stuck run is replaced within the day.
+ */
+const LOCK_STALE_MS = 2 * 60 * 60 * 1000;
+
+/** Read per call, because HOME can change between calls in a test and the answer must follow. */
+function niroDir() {
+  return path.join(os.homedir(), ".niro");
+}
+
+function backoffFile() {
+  return path.join(niroDir(), "docs-backoff.json");
+}
+
+function lockFile() {
+  return path.join(niroDir(), "docs-send.lock");
+}
+
+// ---------------------------------------------------------------------------------------------
+// One run at a time
+// ---------------------------------------------------------------------------------------------
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM: the process exists and belongs to somebody else. Still alive.
+    return Boolean(err && err.code === "EPERM");
+  }
+}
+
+/** Whether an existing lock file belongs to a run that is still going. */
+function lockHeld(file) {
+  let text;
+  let stat;
+  try {
+    text = fs.readFileSync(file, "utf8").trim();
+    stat = fs.statSync(file);
+  } catch {
+    // Gone between the failed create and this read: not held any more.
+    return false;
+  }
+  if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) return false;
+  const pid = Number(text);
+  if (Number.isInteger(pid) && pid > 0) return pidAlive(pid);
+  // Created but the pid not written yet, which is a window of microseconds for a live run. Only
+  // an old empty file is a leftover.
+  return Date.now() - stat.mtimeMs < EMPTY_LOCK_GRACE_MS;
+}
+
+/**
+ * Take the run lock, or return null when another run holds it.
+ *
+ * O_EXCL ("wx") makes the create itself the test, so two runs cannot both create it. A lock left
+ * by a run that died (its pid no longer exists), or not touched for LOCK_STALE_MS, is removed
+ * and the create tried once more.
+ *
+ * Returns the release function, which also carries `touch()`: the run calls it before each step
+ * so a live lock never looks stale.
+ *
+ * Known narrow race: two runs that both find the same dead lock at the same moment can both
+ * remove it, and the second removal can take away the first run's new lock. It needs a crash
+ * followed by two starts within the same few microseconds, and the cost is one batch documented
+ * twice, which the engine's store accepts.
+ */
+function acquireLock(file = lockFile()) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = fs.openSync(file, "wx", 0o600);
+      try {
+        fs.writeSync(fd, String(process.pid));
+      } finally {
+        fs.closeSync(fd);
+      }
+      const ours = () => {
+        try {
+          return fs.readFileSync(file, "utf8").trim() === String(process.pid);
+        } catch {
+          return false;
+        }
+      };
+      const release = () => {
+        // Removed only if it is still ours, so a lock a later run took over is left alone.
+        try {
+          if (ours()) fs.unlinkSync(file);
+        } catch {
+          // Already gone.
+        }
+      };
+      release.touch = () => {
+        try {
+          if (ours()) {
+            const now = new Date();
+            fs.utimesSync(file, now, now);
+          }
+        } catch {
+          // Gone or unwritable: the next step still runs, and only the age check is affected.
+        }
+      };
+      return release;
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") throw err;
+      if (lockHeld(file)) return null;
+      try {
+        fs.unlinkSync(file);
+      } catch (gone) {
+        if (!gone || gone.code !== "ENOENT") throw gone;
+      }
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------------------------
+// Backoff: hashes and times only
+// ---------------------------------------------------------------------------------------------
+
+const BATCH_ID = /^[0-9a-f]{40}$/;
+
+function loadBackoff() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(backoffFile(), "utf8"));
+    // An array passes `typeof === "object"` and would drop every key we set on it
+    // (the trap periodicClaim.js describes). Anything but a plain object starts empty.
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function saveBackoff(state) {
+  const file = backoffFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + "\n", { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+
+/** Forget what is long past, and keep the newest entries only, so the file stays small. */
+function pruneBackoff(state, now) {
+  const kept = Object.entries(state).filter(
+    ([batch, entry]) =>
+      BATCH_ID.test(batch) &&
+      entry &&
+      Number.isFinite(Number(entry.until)) &&
+      Number(entry.until) > now - BACKOFF_FORGET_MS
+  );
+  kept.sort((a, b) => Number(b[1].until) - Number(a[1].until));
+  return Object.fromEntries(kept.slice(0, BACKOFF_MAX_ENTRIES));
+}
+
+function waitingUntil(state, batch, now) {
+  const entry = state[batch];
+  return entry && Number(entry.until) > now ? Number(entry.until) : 0;
+}
+
+function recordFailure(state, batch, now) {
+  if (!BATCH_ID.test(String(batch))) return;
+  const failures = (Number(state[batch] && state[batch].failures) || 0) + 1;
+  const delay = Math.min(BACKOFF_MAX_MS, BACKOFF_BASE_MS * 2 ** Math.min(failures - 1, 20));
+  state[batch] = { failures, until: now + delay };
+}
+
+module.exports = {
+  acquireLock,
+  backoffFile,
+  lockFile,
+  loadBackoff,
+  saveBackoff,
+  pruneBackoff,
+  waitingUntil,
+  recordFailure,
+  BACKOFF_BASE_MS,
+  LOCK_STALE_MS,
+};