@niroai/niro 0.16.0 → 0.18.0

package/src/lib/journalUpload.js

@@ -0,0 +1,147 @@
+/**
+ * Sends the local engine's record of what it was asked to Niro.
+ *
+ * The engine answers an assistant's questions on this machine, so none of those calls are
+ * visible to the cloud the way a hosted session's are. The engine keeps its own record and
+ * this sends it, because the engine holds no account and no credential: anything that leaves
+ * the machine leaves through the CLI, which is the part that signed in.
+ *
+ * The same three steps `audit-send` uses, and the same reason for the shape: the engine builds
+ * the payload, so the wire format has one home. It is posted as the engine wrote it, free text and
+ * query arguments included (Niraj, 2026-11-06, Q11: the release's journalStrip, which nulled them, is
+ * not used; they are what makes the record useful). The engine masks secrets in every value before
+ * it records it, with llm-gateway's rules, and keeps each free-text field to about 1,000 characters
+ * (niro-local `docs/usecases/on-machine-redaction.md`); each line it emits says so with `redacted`.
+ * A line without it comes from an older engine that masked nothing: it stays in the engine's
+ * queue, unsent, until the engine is updated.
+ *
+ *   niro-local journal --emit         JSON Lines, one session per line
+ *   POST <assistant>/api/mcp/local-sessions   each session's `payload`, verbatim
+ *   niro-local journal --mark-sent     the ids that arrived, one per line
+ *
+ * **What is in a payload, and what is not.** Which tools were asked, how long each took,
+ * whether it failed and the class name of the exception when it did, plus arguments that
+ * passed an allowlist. No source, no exception messages, no account and no user: the service
+ * stamps the account and the user from this machine's token, and applies the same allowlist
+ * again, because its own filtering cannot be trusted to a program on somebody's laptop.
+ *
+ * Nothing here logs a payload. The arguments are small but they are a customer's names.
+ */
+const localEngine = require("./localEngine");
+const api = require("./api");
+const config = require("./config");
+
+/** Where ai-assistant is: the same resolution the MCP bridge uses. */
+const SAAS_URL = "https://aiassistant.niroai.dev";
+
+const UPLOAD_PATH = "/api/mcp/local-sessions";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_BATCH = 20;
+
+function assistantUrl() {
+  return (process.env.NIRO_MCP_SERVER_URL || config.load().mcpServerUrl || SAAS_URL).replace(
+    /\/+$/,
+    ""
+  );
+}
+
+/**
+ * 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.
+ */
+async function uploadPending({ limit = DEFAULT_BATCH, freshToken = api.ensureFreshToken } = {}) {
+  const result = { sent: 0, calls: 0, failed: 0, failures: [] };
+
+  // Before the engine is asked for anything, so a machine that cannot authenticate does not
+  // pull sessions out of the queue only to fail to send them. One token for the whole run:
+  // it outlives a batch, and refreshing per session would be a request each.
+  let token;
+  try {
+    token = await freshToken();
+  } catch (err) {
+    if (err && err.code === "ENOAUTH") {
+      throw new Error(`${err.message} The journal stays on this machine until then.`);
+    }
+    throw err;
+  }
+  const headers = { "Content-Type": "application/json", Authorization: `Bearer ${token}` };
+
+  const emitted = await localEngine.run(["journal", "--emit", "--limit", String(limit)]);
+  const sessions = emitted
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+
+  const arrived = [];
+  for (const session of sessions) {
+    if (!session.redacted) {
+      // An older engine: never masked. Kept in its queue, not marked, not sent.
+      result.unmasked = (result.unmasked || 0) + 1;
+      continue;
+    }
+    try {
+      // Posted verbatim: the engine owns the field names, and the free text is kept (Q11).
+      const answer = await postJson(UPLOAD_PATH, session.payload, headers);
+      if (answer.ok) {
+        result.sent += 1;
+        result.calls += (session.payload && session.payload.tool_calls
+          ? session.payload.tool_calls.length
+          : 0);
+        arrived.push(session.session_id);
+      } else if (answer.status === 400) {
+        // The service refused the body, which is our own CLI's or the engine's fault. Marked
+        // as sent anyway: it will be refused identically for ever, and a queue that can never
+        // drain blocks every session behind it. The failure is reported so it is not silent.
+        result.failed += 1;
+        result.failures.push(`${session.session_id.slice(0, 12)}: refused (${answer.status})`);
+        // Kept on disk before it leaves the queue: a 400 would be refused the same way for ever
+        // and block every session behind it, but the usage it records must not be lost.
+        keepRefused(session);
+        arrived.push(session.session_id);
+      } else {
+        // Anything else may work later: kept in the queue, which is what the engine's own
+        // record is for.
+        result.failed += 1;
+        result.failures.push(`${session.session_id.slice(0, 12)}: HTTP ${answer.status}`);
+      }
+    } catch (err) {
+      result.failed += 1;
+      result.failures.push(`${session.session_id.slice(0, 12)}: ${err.message}`);
+    }
+  }
+
+  if (arrived.length > 0) {
+    await localEngine.run(["journal", "--mark-sent"], arrived.join("\n") + "\n");
+  }
+  return result;
+}
+
+/** Where a refused session is kept, one JSON file per session, for a fix and a resend. */
+const REFUSED_DIR = () => require("path").join(require("os").homedir(), ".niro", "journal-refused");
+
+function keepRefused(session) {
+  const fs = require("fs");
+  const dir = REFUSED_DIR();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(require("path").join(dir, `${session.session_id}.json`), JSON.stringify(session) + "\n", { mode: 0o600 });
+}
+
+async function postJson(path, body, headers) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+  try {
+    return await fetch(`${assistantUrl()}${path}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+module.exports = { assistantUrl, uploadPending, UPLOAD_PATH, SAAS_URL, REFUSED_DIR };

package/src/lib/languages.js

@@ -0,0 +1,129 @@
+/**
+ * The languages the local engine reads, and which of them a folder holds.
+ *
+ * The table mirrors niro-local's `src/niro_local/languages.py` (LANGUAGES): same languages, same
+ * extensions, grouped as people name them (JSX under JavaScript, TSX under TypeScript, the PHP
+ * include extensions under PHP). Change both together. It is shown three ways: on the build line
+ * of `niro start`, in the message for a folder with none of them, and under `niro --help`.
+ *
+ * The engine's build report does not name languages, so the folder is looked at here: the files
+ * git tracks when it is a repository (which honours .gitignore), else a bounded walk that skips
+ * dependency and build folders. It only says which languages are present, never what was indexed.
+ */
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+const windowsPaths = require("./windowsPaths");
+
+const LANGUAGES = [
+  ["Java", [".java"]],
+  ["Kotlin", [".kt", ".kts"]],
+  ["JavaScript", [".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte"]],
+  ["TypeScript", [".ts", ".mts", ".cts", ".tsx", ".astro"]],
+  ["Python", [".py", ".pyw", ".pyi"]],
+  ["C#", [".cs", ".csx"]],
+  ["Go", [".go"]],
+  ["PHP", [".php", ".phtml", ".php3", ".php4", ".php5"]],
+  ["Ruby", [".rb", ".rake", ".gemspec"]],
+  ["Swift", [".swift"]],
+  ["Rust", [".rs"]],
+  ["C", [".c", ".h"]],
+  ["C++", [".cpp", ".cc", ".cxx", ".hpp", ".hxx", ".h++", ".c++", ".hh", ".tcc", ".ipp", ".inl", ".tpp"]],
+];
+
+const BY_EXTENSION = new Map(LANGUAGES.flatMap(([name, exts]) => exts.map((e) => [e, name])));
+
+// Languages Niro does not read yet, by extension: named in niro start's summary with the command
+// that asks for them (niro request-integration). Only unambiguous extensions; a few is enough.
+const OTHERS = [
+  ["Scala", [".scala", ".sc"]],
+  ["Dart", [".dart"]],
+  ["Elixir", [".ex", ".exs"]],
+  ["Erlang", [".erl"]],
+  ["Haskell", [".hs"]],
+  ["Clojure", [".clj", ".cljs", ".cljc"]],
+  ["F#", [".fs", ".fsx"]],
+  ["Lua", [".lua"]],
+  ["Perl", [".pl", ".pm"]],
+  ["R", [".r"]],
+  ["Julia", [".jl"]],
+  ["Groovy", [".groovy"]],
+  ["Objective-C", [".m", ".mm"]],
+  ["Zig", [".zig"]],
+  ["OCaml", [".ml", ".mli"]],
+  ["Visual Basic", [".vb"]],
+  ["COBOL", [".cbl", ".cob"]],
+  ["Solidity", [".sol"]],
+];
+const OTHER_BY_EXTENSION = new Map(OTHERS.flatMap(([name, exts]) => exts.map((e) => [e, name])));
+
+/** "Java, Kotlin, ... and C++", for help text and messages. */
+function supportedList() {
+  const names = LANGUAGES.map(([name]) => name);
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+// Folders whose files are not the developer's own code. Only for the walk; git already leaves
+// out what .gitignore names.
+const SKIP = new Set(["node_modules", "vendor", "dist", "build", "target", "out", "bin", "obj", "venv", ".venv", "__pycache__"]);
+const WALK_LIMIT = 50_000; // ponytail: entries looked at outside git; enough to name what a folder holds
+
+function trackedFiles(dir) {
+  const git = windowsPaths.gitProgram();
+  if (!git) return null;
+  // maxBuffer: the default 1 MiB is under a large repository's list (Keycloak 1.1 MB, OpenSearch
+  // 1.3 MB), and git then fails with ENOBUFS.
+  const r = spawnSync(git, ["ls-files", "-z"], {
+    cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, maxBuffer: 64 * 1024 * 1024,
+  });
+  return r.status === 0 ? r.stdout.split("\0").filter(Boolean) : null;
+}
+
+function walkedFiles(dir) {
+  const files = [];
+  const stack = [dir];
+  let seen = 0;
+  while (stack.length && seen < WALK_LIMIT) {
+    const current = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (++seen > WALK_LIMIT) break;
+      if (entry.name.startsWith(".")) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) { if (!SKIP.has(entry.name)) stack.push(full); } else files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * One listing of `dir`: `found`, the supported languages, and `others`, languages Niro does not read
+ * yet, each most files first. Both [] when there are none or the folder cannot be read.
+ */
+function scan(dir) {
+  const files = trackedFiles(dir) || walkedFiles(dir);
+  const found = new Map();
+  const others = new Map();
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    const name = BY_EXTENSION.get(ext);
+    const other = !name && OTHER_BY_EXTENSION.get(ext);
+    if (name) found.set(name, (found.get(name) || 0) + 1);
+    if (other) others.set(other, (others.get(other) || 0) + 1);
+  }
+  const byCount = (counts) => [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([name]) => name);
+  return { found: byCount(found), others: byCount(others) };
+}
+
+/** The supported languages in `dir`, most files first. [] when there are none or it cannot be read. */
+function detect(dir) {
+  return scan(dir).found;
+}
+
+/** At most `max` names, then "+N": "Java, TypeScript, Python +2". */
+function short(names, max = 3) {
+  return names.length > max ? `${names.slice(0, max).join(", ")} +${names.length - max}` : names.join(", ");
+}
+
+module.exports = { LANGUAGES, supportedList, scan, detect, short };

package/src/lib/lease.js

@@ -0,0 +1,375 @@
+/**
+ * Gets a licence for the local engine and hands it over while the engine runs.
+ *
+ * The engine holds no account and no credential, on purpose. This CLI signed in, so this CLI
+ * asks niro-billing for a lease and passes it to the engine. The lease is signed, so the
+ * engine can check it came from us and has not been edited, and this file never looks inside
+ * it except to work out when to ask for the next one.
+ *
+ * **The lease is never written to disk** (Niraj, 2026-10-14: it "is never written to the
+ * user's disk. It is fetched at intervals and held in memory"). That rules out the obvious
+ * reuse: `periodicClaim.js` is the CLI's existing "has this job run recently" helper and it
+ * works by writing a timestamp file so the answer outlives the process. Here the opposite is
+ * wanted. Nothing about a lease survives the engine it was issued to.
+ *
+ * **How it travels: two extra pipes, named in the environment.** Standard input and output
+ * belong to the engine's own protocol, a command-line argument is visible to every process on
+ * the machine through `ps` and cannot be replaced while the process runs, and an environment
+ * variable has both problems. So the engine is started with two more pipes and told their
+ * numbers. The engine's end is `niro_local/licence/pipe.py`, which is also where the wire
+ * format is written down:
+ *
+ *     engine -> CLI    NONCE 9f2c1b7e4a3d0c8b
+ *     CLI    -> engine LEASE <payload base64> <signature base64> <key id>
+ *     CLI    -> engine REFUSED This account is suspended.
+ *
+ * **Every request carries the nonce the engine generated**, including each refresh, because
+ * the lease is signed against it: a lease bound to another nonce belongs to another engine
+ * process and that engine refuses it. One nonce per engine process, for the life of the
+ * process.
+ *
+ * **Silence and a refusal are different things, and the difference is the whole design.** When
+ * niro-billing cannot be reached, or answers 5xx, nothing is written to the pipe: the engine
+ * keeps working on the lease it already has until that lease's own offline allowance runs out,
+ * which is what lets somebody work on a train. Only a 403, which is us saying this account may
+ * not use the engine, is passed on as REFUSED, and that stops the engine at once.
+ */
+const api = require("./api");
+const config = require("./config");
+const color = require("./color");
+
+/** Where niro-billing is. The frontend's deployed configuration names the same host. */
+const PROD_BILLING_URL = "https://billing.cloud.niroai.dev";
+
+const LEASE_PATH = "/api/local-engine/lease";
+
+/**
+ * How long to wait for a lease. Shorter than the engine's own wait for a first lease (20s), so
+ * that a slow service produces a decision here rather than the engine giving up first.
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+
+/** How long to wait before asking again after we could not reach the service. */
+const DEFAULT_RETRY_MS = 60_000;
+
+/** How early to renew: a fifth of the lease's life, kept inside these bounds. */
+const MIN_LEAD_MS = 30_000;
+const MAX_LEAD_MS = 300_000;
+
+/**
+ * The soonest a renewal is ever attempted. It exists because a lease shorter than the lead
+ * time above would otherwise be renewed immediately and in a loop.
+ */
+const DEFAULT_MIN_RENEWAL_MS = 5_000;
+
+/**
+ * All three are read when they are used rather than when this file is loaded.
+ *
+ * That is not a style choice. Read at load time, an override set by whatever started this
+ * process is ignored unless it happened to be exported before the first `require`, and a test
+ * that sets one is testing the default while appearing to test the override. One of these
+ * tests did exactly that on 2026-10-15: it asked for a 150ms timeout, got the 15s default,
+ * and passed because the fixture had already given up waiting.
+ */
+function fetchTimeoutMs() {
+  return Number(process.env.NIRO_LEASE_TIMEOUT_MS) || DEFAULT_FETCH_TIMEOUT_MS;
+}
+
+function retryMs() {
+  return Number(process.env.NIRO_LEASE_RETRY_MS) || DEFAULT_RETRY_MS;
+}
+
+function minRenewalMs() {
+  return Number(process.env.NIRO_LEASE_MIN_RENEW_MS) || DEFAULT_MIN_RENEWAL_MS;
+}
+
+/** The two extra pipes, as the engine sees them. Matches `pipe.py`. */
+const FD_IN_ENV = "NIRO_LOCAL_LEASE_FD_IN";
+const FD_OUT_ENV = "NIRO_LOCAL_LEASE_FD_OUT";
+const CHILD_FD_IN = 3;
+const CHILD_FD_OUT = 4;
+
+/** Which service to ask. Env var, then ~/.niro/config.json, then the deployed service. */
+function billingUrl() {
+  return (process.env.NIRO_BILLING_URL || config.load().billingUrl || PROD_BILLING_URL).replace(
+    /\/+$/,
+    ""
+  );
+}
+
+/** Who is asking, for niro-billing's log only. It never refuses on this. */
+function askingVersion() {
+  try {
+    return `niro-cli/${require("../../package.json").version}`;
+  } catch {
+    return "niro-cli";
+  }
+}
+
+/** What the engine is told to look at, merged into its environment when it is started. */
+function childEnvironment(env = process.env) {
+  return { ...env, [FD_IN_ENV]: String(CHILD_FD_IN), [FD_OUT_ENV]: String(CHILD_FD_OUT) };
+}
+
+/**
+ * The claims inside a lease, or null when they cannot be read.
+ *
+ * Read for one reason only: to know when to ask for the next lease. Nothing here enforces a
+ * claim and nothing here would notice an edited one. That is the engine's job, and it does it
+ * by checking the signature over these exact bytes before parsing them, which is why this
+ * function being fooled costs nothing.
+ */
+function claimsOf(leaseBase64) {
+  try {
+    const parsed = JSON.parse(Buffer.from(String(leaseBase64), "base64").toString("utf8"));
+    // An ARRAY passes `typeof === "object"`, and every claim read off it would be undefined,
+    // so the renewal would silently fall back to the retry interval for ever. The same trap
+    // cost this CLI a persisted timestamp once before (see periodicClaim.js).
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** When to ask for the next lease, in milliseconds from now. */
+function renewalDelay(claims, now = Date.now()) {
+  const expiresAt = claims && Number(claims.expires_at);
+  const issuedAt = claims && Number(claims.issued_at);
+  if (!Number.isFinite(expiresAt) || expiresAt <= 0) {
+    // A lease we cannot read the expiry of still has one, and it is at least as long as the
+    // shortest we issue. Asking again on the retry interval is wrong in no direction worse
+    // than one extra request a minute.
+    return retryMs();
+  }
+  const life = Number.isFinite(issuedAt) && issuedAt > 0 ? (expiresAt - issuedAt) * 1000 : 0;
+  const lead = Math.min(MAX_LEAD_MS, Math.max(MIN_LEAD_MS, life * 0.2));
+  return Math.max(minRenewalMs(), expiresAt * 1000 - now - lead);
+}
+
+/**
+ * Ask niro-billing for a lease bound to `nonce`.
+ *
+ * The status code is the contract, not the message (`LocalEngineController`), so each one is
+ * turned into one of three answers and nothing branches on prose:
+ *
+ *   - `{ lease, signature, keyId }` — a lease, pass it on.
+ *   - `{ refused: true, reason }`   — 403. The account may not use the engine. Tell the engine.
+ *   - `{ unreachable: true, detail }` — anything else, including 401 after a refresh, 400,
+ *     5xx, a network failure and a timeout. Say nothing to the engine and let its own
+ *     allowance decide.
+ *
+ * A 401 is not handled here because the request layer already does it: it exchanges the
+ * durable CLI token for a fresh JWT and replays the request once, sharing one refresh between
+ * concurrent callers. A 401 that survives that means this machine is not signed in, which is
+ * reported as unreachable rather than as a refusal: being signed out is a local problem, and a
+ * developer must not lose a running engine to it before the lease in hand has run its course.
+ */
+async function fetchLease(nonce, { engineVersion = askingVersion() } = {}) {
+  const abort = new AbortController();
+  const timer = setTimeout(() => abort.abort(), fetchTimeoutMs());
+  try {
+    const data = await api.request("POST", LEASE_PATH, {
+      body: { nonce, engine_version: engineVersion },
+      apiUrl: billingUrl(),
+      signal: abort.signal,
+    });
+    const lease = data && (data.lease || data.payload);
+    const signature = data && data.signature;
+    const keyId = data && (data.key_id || data.keyId);
+    if (!lease || !signature || !keyId) {
+      // A 200 with a field missing is our own fault and not something to retry hard.
+      return { unreachable: true, detail: "the lease came back incomplete" };
+    }
+    return { lease, signature, keyId };
+  } catch (err) {
+    if (err && err.status === 403) {
+      return { refused: true, reason: reasonFrom(err) };
+    }
+    return { unreachable: true, detail: reasonFrom(err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The service's own words for why it said no.
+ *
+ * The request layer turns a failure into an Error whose message names the call ("POST
+ * /api/local-engine/lease failed: ..."), which is right for a log and wrong for a sentence
+ * shown to a developer, so the message out of the response body is preferred when there is
+ * one. Only niro-billing knows why an account is refused, so nothing here rewrites its
+ * sentences; the two account codes (account_blocked, account_waiting) are put into words. A
+ * network failure has no body and falls back to the message, which does name the call: that
+ * is the right way round, because then the developer is being told we could not be reached.
+ */
+/** The account refusals the services send as codes, said in words a developer reads. */
+const ACCOUNT_REFUSALS = {
+  account_blocked: "This Niro account is suspended. Contact ask@niro.ai.",
+  account_waiting: "This Niro account is waiting for approval. Contact ask@niro.ai if it takes long.",
+};
+
+function reasonFrom(err) {
+  const said = serviceWords(err);
+  return ACCOUNT_REFUSALS[said] || said;
+}
+
+function serviceWords(err) {
+  const body = err && err.body;
+  if (body && typeof body === "object") {
+    // niro-billing's envelope puts the sentence in `message`; `error` is checked too because
+    // the CLI's own request layer writes that spelling and both reach here. Found by the Java
+    // compiler on 2026-10-15: this read `error` only, and a fixture written to match it was
+    // agreeing with the wrong shape.
+    for (const field of ["message", "error"]) {
+      if (typeof body[field] === "string" && body[field].trim()) return body[field].trim();
+    }
+  }
+  return (err && err.message) || "no reason given";
+}
+
+/** One line on the pipe, with anything that could break the format taken out of it. */
+function refusalLine(reason) {
+  const flattened = String(reason || "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 300);
+  return `REFUSED ${flattened}`;
+}
+
+/**
+ * Serve leases to a running engine until it exits.
+ *
+ * Returns a handle with `stop()`, and stops itself when the child exits, so nothing is left
+ * holding the event loop open: the renewal timer is cleared there, and is unreferenced besides
+ * so that a pending renewal can never be the reason a command does not finish.
+ */
+function attach(child, { log = console.log, fetch = fetchLease } = {}) {
+  const toEngine = child.stdio[CHILD_FD_IN];
+  const fromEngine = child.stdio[CHILD_FD_OUT];
+  const state = { nonce: null, timer: null, stopped: false, warned: false, leases: 0 };
+
+  if (!toEngine || !fromEngine) {
+    // Nothing to do, and not an error worth stopping a build for: an engine started without
+    // the extra pipes is an engine that will decide for itself whether it needs a licence.
+    return { stop() {}, state };
+  }
+
+  // The engine dying mid-write is normal (it finished, or it was interrupted). A write to a
+  // closed pipe must not take the CLI down with an unhandled error.
+  toEngine.on("error", () => {});
+  fromEngine.on("error", () => {});
+
+  function send(line) {
+    if (state.stopped || !toEngine.writable) return;
+    try {
+      toEngine.write(line + "\n");
+    } catch {
+      // Same case as above, reached when the pipe closes between the check and the write.
+    }
+  }
+
+  function later(ms) {
+    if (state.stopped) return;
+    if (state.timer) clearTimeout(state.timer);
+    state.timer = setTimeout(offer, ms);
+    if (state.timer.unref) state.timer.unref();
+  }
+
+  async function offer() {
+    if (state.stopped || !state.nonce) return;
+    const answer = await fetch(state.nonce);
+    if (state.stopped) return;
+    if (answer.refused) {
+      // The one case where the engine is stopped by us rather than by its lease running out.
+      send(refusalLine(answer.reason));
+      log(color.red(`    Niro will not license the local engine: ${answer.reason}`));
+      return;
+    }
+    if (answer.unreachable) {
+      // Deliberately nothing on the pipe. The engine carries on under the lease it has, and
+      // its offline allowance is what eventually stops it.
+      if (!state.warned) {
+        state.warned = true;
+        log(
+          color.yellow(
+            `    Could not renew the local engine's licence: ${answer.detail}. ` +
+              "It keeps working offline for up to a day."
+          )
+        );
+      }
+      later(retryMs());
+      return;
+    }
+    state.leases += 1;
+    state.warned = false;
+    send(`LEASE ${answer.lease} ${answer.signature} ${answer.keyId}`);
+    later(renewalDelay(claimsOf(answer.lease)));
+  }
+
+  let buffered = "";
+  fromEngine.on("data", (chunk) => {
+    buffered += chunk.toString();
+    let newline = buffered.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffered.slice(0, newline).trim();
+      buffered = buffered.slice(newline + 1);
+      const parts = line.split(" ");
+      if (parts[0] === "NONCE" && parts[1] && !state.nonce) {
+        state.nonce = parts[1];
+        // Not awaited: this handler must return so the pipe keeps being read while the
+        // request is in flight.
+        offer();
+      }
+      newline = buffered.indexOf("\n");
+    }
+  });
+
+  function stop() {
+    state.stopped = true;
+    if (state.timer) clearTimeout(state.timer);
+    state.timer = null;
+    fromEngine.removeAllListeners("data");
+    try {
+      toEngine.end();
+    } catch {
+      // Already gone with the child.
+    }
+  }
+
+  child.once("close", stop);
+  return { stop, state };
+}
+
+/**
+ * The claims of a fresh lease for this account, or null when none could be had.
+ *
+ * For reading what the plan says (`plan_name`, `share_code`), not for licensing anything: the
+ * nonce is thrown away. Same pattern as repoPush.permitted. Callers treat null as "unknown",
+ * and anything that would send code treats unknown as no.
+ */
+async function currentClaims({ fetch = fetchLease } = {}) {
+  const answer = await fetch(require("crypto").randomBytes(16).toString("hex"));
+  if (!answer || answer.refused || answer.unreachable) return null;
+  return claimsOf(answer.lease);
+}
+
+module.exports = {
+  attach,
+  currentClaims,
+  billingUrl,
+  childEnvironment,
+  claimsOf,
+  fetchLease,
+  reasonFrom,
+  renewalDelay,
+  CHILD_FD_IN,
+  CHILD_FD_OUT,
+  FD_IN_ENV,
+  FD_OUT_ENV,
+  LEASE_PATH,
+  PROD_BILLING_URL,
+  fetchTimeoutMs,
+  minRenewalMs,
+  retryMs,
+};