@niroai/niro 0.16.0 → 0.18.0

package/src/lib/localWorktrees.js

@@ -0,0 +1,243 @@
+/**
+ * New git worktrees of repositories the local engine holds, so the watcher can build them.
+ *
+ * `git worktree add` makes a new folder on a new branch. niro-local indexes it the moment somebody
+ * runs `niro-local build` there (it makes a temporary copy of the project that holds the repository),
+ * but nothing on the machine ran that build: the watcher only knew the folders niro-local already
+ * listed, so a new worktree stayed unindexed until a person noticed (release finding 6).
+ *
+ * **Which worktrees count as new.** Those that appear after the watcher first saw the repository.
+ * The first time a repository is seen, every worktree it has is written down and none is built:
+ * switching this on must not start a build of every old worktree on the machine, some of which
+ * nobody wants indexed. What has been seen is kept in `~/.niro/local-worktrees.json` (with a copy
+ * one round old beside it, `.bak`), so a worktree made while the watcher was stopped is still built
+ * when it starts again. A build that fails is started again twice, minutes apart, then given up.
+ *
+ * **The engine decides what happens.** This only finds the folder. The build is the same
+ * `niro-local build --path <folder>` a person would type, so a refusal (another checkout already
+ * holds that branch, say) is the engine's own words.
+ *
+ * Read with git's own command, `git worktree list --porcelain`, rather than by reading files under
+ * `.git`: the layout of those files is git's business and differs for bare repositories.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFile } = require("child_process");
+const windowsPaths = require("./windowsPaths");
+
+const STATE_FILE = () => path.join(os.homedir(), ".niro", "local-worktrees.json");
+
+/** Run git in `cwd`, resolving its standard output, or null when git cannot answer. Never throws. */
+function git(args, cwd) {
+  return new Promise((resolve) => {
+    const program = windowsPaths.gitProgram();
+    if (!program) return resolve(null);
+    execFile(program, args, { cwd, encoding: "utf8", timeout: 5000 }, (err, stdout) => {
+      resolve(err ? null : String(stdout));
+    });
+  });
+}
+
+/**
+ * The repository this folder is in: `{ common, top }`, git's shared directory (one per repository,
+ * whichever worktree asks) and the top of this folder's own worktree. Null outside git.
+ */
+async function repositoryOf(folder) {
+  // The common directory may come back relative to `folder` (git before 2.31 has no
+  // --path-format), so it is resolved against it; the top is always absolute.
+  const out = await git(["rev-parse", "--git-common-dir", "--show-toplevel"], folder);
+  if (!out) return null;
+  const [common, top] = out.trim().split("\n");
+  return common && top ? { common: path.resolve(folder, common), top: path.resolve(top) } : null;
+}
+
+/**
+ * The worktrees of the repository `folder` is in, from `git worktree list --porcelain`: a path for
+ * each one that is on a branch. Detached and bare entries are left out, since a build there has no
+ * branch to make a copy for.
+ */
+async function worktreesOf(folder) {
+  const out = await git(["worktree", "list", "--porcelain"], folder);
+  if (!out) return [];
+  const found = [];
+  for (const block of out.split(/\n\s*\n/)) {
+    const lines = block.split("\n");
+    const at = lines.find((l) => l.startsWith("worktree "));
+    if (!at || !lines.some((l) => l.startsWith("branch "))) continue;
+    found.push(path.resolve(at.slice("worktree ".length)));
+  }
+  return found;
+}
+
+/** How many times a new worktree's build is started before giving up, and the waits between tries. */
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAYS_MS = [2 * 60_000, 10 * 60_000];
+
+/** One repository's record: worktree folders already dealt with, and builds still being retried. */
+function repositoryRecord(value) {
+  if (Array.isArray(value)) return { seen: value, retry: {} }; // the first shape (439af22)
+  if (value && typeof value === "object" && Array.isArray(value.seen)) {
+    return { seen: value.seen, retry: value.retry && typeof value.retry === "object" ? value.retry : {} };
+  }
+  return null;
+}
+
+function readState(file) {
+  const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("not an object");
+  const repositories = parsed.version === 2 ? parsed.repositories || {} : parsed;
+  const out = {};
+  for (const [common, value] of Object.entries(repositories)) {
+    const record = repositoryRecord(value);
+    if (record) out[common] = record;
+  }
+  return out;
+}
+
+/**
+ * The state, and how it was got: `fresh` (no file yet), `file`, `backup` (the file could not be
+ * read, so the copy kept from the round before was used), or `lost` (neither could be read).
+ *
+ * A file that cannot be read used to count as empty, so every repository was "seen for the first
+ * time" and a worktree made in that window was recorded and never built (VP-rel-watch N3). The
+ * copy from the round before is at most one round old, so the window is still worked out.
+ */
+function loadState(file = STATE_FILE()) {
+  try {
+    return { state: readState(file), from: "file" };
+  } catch (err) {
+    if (err && err.code === "ENOENT") return { state: {}, from: "fresh" };
+  }
+  try {
+    return { state: readState(`${file}.bak`), from: "backup" };
+  } catch {
+    return { state: {}, from: "lost" };
+  }
+}
+
+/**
+ * Write the state for this round. The file as it was (when it could be read) is kept as `.bak`
+ * first, so a file damaged later still has a readable copy one round old beside it.
+ */
+function saveState(state, { file = STATE_FILE(), keepBackup = true } = {}) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    if (keepBackup) {
+      try {
+        fs.copyFileSync(file, `${file}.bak`);
+      } catch {
+        // No file yet: nothing to keep.
+      }
+    }
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify({ version: 2, repositories: state }, null, 2) + "\n", { mode: 0o600 });
+    try {
+      fs.renameSync(tmp, file);
+    } catch (err) {
+      fs.rmSync(tmp, { force: true });
+      throw err;
+    }
+    return null;
+  } catch (err) {
+    // Not fatal: the caller keeps the state in memory while the file cannot be written.
+    return (err && err.code) || (err && err.message) || "unknown error";
+  }
+}
+
+/**
+ * The last state worked out for each file path, kept while that file cannot be written: then the
+ * file on disk is old or unreadable, and reading it again would forget what was seen and how often
+ * a build was tried, so a refused worktree would be offered every round and never given up
+ * (VP-rel-watch-2 note 3). One entry per file path (one in practice), dropped once it is written.
+ */
+const unsaved = new Map();
+
+/**
+ * Folders to build: for each repository holding one of `held` (the folders niro-local lists), the
+ * same place inside each of its worktrees that are new since the repository was first seen and that
+ * niro-local does not hold yet. `held` folders inside one service of a monorepo map to that service's
+ * folder in the new worktree, which is where `niro-local build` would be typed.
+ *
+ * A folder is returned, and its build started by the caller, at most `MAX_ATTEMPTS` times: again
+ * after 2 minutes and after 10 more while niro-local still does not hold it (a build that failed, or
+ * one refused for a reason that has since gone), then given up with one line. It counts as dealt with
+ * once niro-local holds it. Entries for folders gone from disk, and for repositories no held folder is
+ * in any more, are dropped, so the file does not grow for ever.
+ */
+async function newWorktreeFolders(held, { file = STATE_FILE(), repositoryOf: repoOf = repositoryOf,
+  worktreesOf: listOf = worktreesOf, log = () => {}, now = Date.now() } = {}) {
+  const heldSet = new Set(held.map((f) => path.resolve(f)));
+  const kept = unsaved.get(file);
+  const { state: before, from } = kept ? { state: kept, from: "memory" } : loadState(file);
+  const next = {};
+  const wanted = [];
+  const byRepository = new Map();
+  for (const folder of heldSet) {
+    const repo = await repoOf(folder);
+    if (!repo) continue;
+    const relative = path.relative(repo.top, folder);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) continue;
+    if (!byRepository.has(repo.common)) byRepository.set(repo.common, { folder, relatives: new Set() });
+    byRepository.get(repo.common).relatives.add(relative);
+  }
+  for (const [common, { folder, relatives }] of byRepository) {
+    const old = before[common];
+    const firstSight = !old;
+    const seen = new Set(firstSight ? [] : old.seen);
+    const retry = firstSight ? {} : old.retry;
+    const record = { seen: [], retry: {} };
+    for (const tree of await listOf(folder)) {
+      for (const relative of relatives) {
+        const target = path.join(tree, relative);
+        // A worktree on a commit without this folder (the service was added later) has nothing to build.
+        if (!isDirectory(target)) continue;
+        if (firstSight || seen.has(target) || heldSet.has(target)) {
+          record.seen.push(target);
+          continue;
+        }
+        const tried = retry[target] || { attempts: 0, nextAt: 0 };
+        if (tried.attempts >= MAX_ATTEMPTS) {
+          log(`    Gave up building ${target} after ${tried.attempts} tries; run \`${require("./release").rebuildCommand()}\` there to see why.`);
+          record.seen.push(target);
+          continue;
+        }
+        if (now < tried.nextAt) {
+          record.retry[target] = tried;
+          continue;
+        }
+        wanted.push(target);
+        const attempts = tried.attempts + 1;
+        record.retry[target] = { attempts, nextAt: now + (RETRY_DELAYS_MS[attempts - 1] || 0) };
+      }
+    }
+    record.seen.sort();
+    next[common] = record;
+  }
+  const problem = saveState(next, { file, keepBackup: from === "file" });
+  // Said after the write, so each line says what happened; and once, not every round, because a
+  // file that cannot be written is read from memory on the next round and nothing new is to be said.
+  if (from === "backup") {
+    log(`    ${file} could not be read; used its copy from the round before${problem ? "" : ", and wrote it again"}.`);
+  } else if (from === "lost") {
+    log(`    ${file} could not be read and has no readable copy${problem ? "" : "; it is written again from now on"}. A worktree made just before is not built by itself: run \`${require("./release").rebuildCommand()}\` there.`);
+  }
+  if (problem) {
+    if (!kept) log(`    ${file} could not be written (${problem}). What this watcher has seen is kept in memory until it can be, so a refused worktree is still given up after ${MAX_ATTEMPTS} tries; after a restart it may be offered again.`);
+    unsaved.set(file, next);
+  } else {
+    if (kept) log(`    ${file} is written again.`);
+    unsaved.delete(file);
+  }
+  return wanted;
+}
+
+function isDirectory(folder) {
+  try {
+    return fs.statSync(folder).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { newWorktreeFolders, worktreesOf, repositoryOf, loadState, STATE_FILE, MAX_ATTEMPTS, RETRY_DELAYS_MS };

package/src/lib/machineCheck.js

@@ -0,0 +1,58 @@
+/**
+ * Step 1 of `niro start`: can this machine run Niro Local, before any account exists?
+ *
+ * Read-only, and every probe can be injected so a test never reads a disk. There is no Docker
+ * check: the engine's graph is one SQLite file, and whether it opens is asked of the engine
+ * itself once it is installed (graphCheck.js, step 3).
+ */
+const fs = require("fs");
+const os = require("os");
+
+const engine = require("./engine");
+
+const MIN_NODE_MAJOR = 18;
+const LOW_DISK_BYTES = 2 * 1024 ** 3;
+
+/** "macOS 15" from Darwin 24, which is how the kernel and the product number differ. */
+function osName(platform, release) {
+  const major = Number(String(release).split(".")[0]);
+  if (platform === "darwin") return major >= 20 ? `macOS ${major - 9}` : `macOS (Darwin ${release})`;
+  if (platform === "linux") return "Linux";
+  if (platform === "win32") return "Windows";
+  return platform;
+}
+
+function check({
+  platform = process.platform,
+  arch = process.arch,
+  release = os.release(),
+  nodeVersion = process.version,
+  statfs = (p) => fs.statfsSync(p),
+  home = os.homedir(),
+} = {}) {
+  let platformProblem = null;
+  try {
+    engine.label(platform, arch);
+  } catch (err) {
+    platformProblem = err.message;
+  }
+  let freeBytes = null;
+  try {
+    const s = statfs(home);
+    freeBytes = Number(s.bavail) * Number(s.bsize);
+  } catch {
+    // Unknown is reported as unknown, never as low.
+  }
+  const nodeMajor = Number(/^v?(\d+)/.exec(nodeVersion || "")?.[1] || 0);
+  return {
+    os: osName(platform, release),
+    arch,
+    freeBytes,
+    lowDisk: freeBytes !== null && freeBytes < LOW_DISK_BYTES,
+    node: nodeVersion,
+    nodeOk: nodeMajor >= MIN_NODE_MAJOR,
+    platformProblem,
+  };
+}
+
+module.exports = { check, osName, LOW_DISK_BYTES };

package/src/lib/mcpClients.js

@@ -238,4 +238,13 @@ function allClientIds() {
   return Object.keys(CLIENTS);
 }
 
-module.exports = { configuredClients, allClientIds, MARKER_FILES, MAX_CONFIG_BYTES };
+/**
+ * Display names, as the installer shows them ("Claude Code"). Takes client ids or what
+ * configuredClients() returns ({ configured: [{ id }] }), which is what callers pass.
+ */
+function clientNames(found) {
+  const ids = Array.isArray(found) ? found : ((found && found.configured) || []).map((c) => c.id);
+  return ids.map((id) => (CLIENTS[id] && CLIENTS[id].name) || id);
+}
+
+module.exports = { configuredClients, clientNames, allClientIds, MARKER_FILES, MAX_CONFIG_BYTES };

package/src/lib/migrationNotice.js

@@ -0,0 +1,118 @@
+/**
+ * What to tell a developer, after an upgrade, about where their folders are indexed.
+ *
+ * The local engine indexes a repository on the developer's own machine instead of uploading it.
+ * A machine that has used Niro for a while has folders set up the other way: watched, hashed
+ * and uploaded into a cloud project. Both keep working, and nothing here changes either.
+ *
+ * **What this exists to prevent.** A developer installs the engine, or upgrades into a version
+ * that has it, and assumes their code has stopped leaving the machine. It has not: the folders
+ * they onboarded before are still being uploaded by the same daemon as yesterday. Saying so
+ * once, with the command that moves one, is the difference between a product they understand
+ * and a nasty surprise.
+ *
+ * **What it deliberately does NOT do.** It does not stop the uploading daemon and it does not
+ * offer to release a cloud project. The plan's migration list asks for both, with the line "the
+ * CLI no longer refreshes them", and that will be true when the CLI stops maintaining cloud
+ * projects. It does not today: a pinned repository is still answered by the cloud by design,
+ * and the bridge still routes to it. Telling somebody we no longer refresh something we do
+ * refresh would be worse than saying nothing.
+ *
+ * It reads local state only: no network call, nothing that can hang an upgrade.
+ */
+const watchState = require("./watchState");
+const engine = require("./engine");
+const color = require("./color");
+const release = require("./release");
+
+/**
+ * Is the engine on this machine at all, cache or PATH or named by the environment?
+ *
+ * Whichever of those it is, the daemon will run it, so the notice is owed. Reading the
+ * download cache alone said nothing to a developer running an engine from their PATH, who
+ * is exactly the person indexing locally and still uploading yesterday's folders.
+ */
+function engineHere() {
+  const found = engine.resolve();
+  return found ? found.path : null;
+}
+
+/**
+ * The lines to print, or an empty list when there is nothing worth saying.
+ *
+ * Nothing is said on a machine with no engine, which is every existing customer until they ask
+ * for one: an upgrade is not the place to advertise. Nothing is said either when no folder is
+ * uploaded, because then there is nothing to be surprised by.
+ */
+function lines({ installed = engineHere, folders = watchState.allLocal, cloud = release.cloud } = {}) {
+  if (!cloud) return webLines(listed(folders));
+  let enginePath = null;
+  try {
+    enginePath = installed();
+  } catch {
+    enginePath = null;
+  }
+  if (!enginePath) return [];
+
+  let uploaded = [];
+  try {
+    uploaded = folders() || [];
+  } catch {
+    uploaded = [];
+  }
+  if (uploaded.length === 0) return [];
+
+  const count = uploaded.length;
+  const out = [
+    `  ${color.yellow("Where your code is indexed:")} ${count} folder${count === 1 ? "" : "s"} ` +
+      `on this machine ${count === 1 ? "is" : "are"} still indexed in the cloud,`,
+    "  which means the watcher uploads changed files from them as you work. The local engine",
+    "  is installed, so you can move a folder onto it instead:",
+    "",
+  ];
+  for (const folder of uploaded.slice(0, 5)) {
+    out.push(`    ${folder.folderPath}`);
+  }
+  if (uploaded.length > 5) {
+    out.push(`    ... and ${uploaded.length - 5} more`);
+  }
+  out.push(
+    "",
+    // `init` adds the folder and builds it (both the engine's and niro's). Without the cloud it is `niro init`, which
+    // passes the licence on; the released engine refuses a build typed directly.
+    `  To move one:  cd <folder> && ${color.cyan(require("./release").cloud ? "niro-local init" : "niro init")}`,
+    "  Its questions are then answered from the graph on this machine, and nothing from it",
+    "  is uploaded. The folders you leave alone keep working exactly as they do now.",
+    ""
+  );
+  return out;
+}
+
+function listed(folders) {
+  try {
+    return folders() || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * A release without the cloud: the folders set up with Niro web are no longer uploaded at all,
+ * because the watcher has nothing to sync in this release. Say so, and how to keep using Niro on
+ * one, instead of letting the developer find out when a cloud answer goes stale.
+ */
+function webLines(uploaded) {
+  if (uploaded.length === 0) return [];
+  const count = uploaded.length;
+  const out = [
+    `  ${color.yellow("Folders from Niro web:")} ${count} folder${count === 1 ? " was" : "s were"} set up with Niro web on this machine.`,
+    "  This version indexes on this machine and no longer uploads them:",
+    "",
+  ];
+  for (const folder of uploaded.slice(0, 5)) out.push(`    ${folder.folderPath}`);
+  if (count > 5) out.push(`    ... and ${count - 5} more`);
+  out.push("", `  To keep using Niro on one:  cd <folder> && ${color.cyan("niro init")}`, "");
+  return out;
+}
+
+module.exports = { lines, webLines };

package/src/lib/modelFetch.js

@@ -0,0 +1,153 @@
+/**
+ * Puts the local engine's embedding model on disk for `niro docs-send`, split out of
+ * docsUpload.js so each file has one job.
+ *
+ * The engine never downloads anything (niro-local `reuse/embed.py`): `niro-local docs
+ * --model-info` names the files with their URL, size and sha256, and this fetches them. A file
+ * reaches its final name only after its size and sha256 match, so the engine sees either the
+ * right file or no file.
+ */
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+const { Readable } = require("stream");
+const { pipeline } = require("stream/promises");
+
+const localEngine = require("./localEngine");
+
+/** How long one model file download may take. The larger file is about 90 MB. */
+const DEFAULT_MODEL_TIMEOUT_MS = 15 * 60 * 1000;
+
+/** Read when used, not when this file is loaded (the trap `lease.js` describes). */
+function modelTimeoutMs() {
+  return Number(process.env.NIRO_DOCS_MODEL_TIMEOUT_MS) || DEFAULT_MODEL_TIMEOUT_MS;
+}
+
+// ---------------------------------------------------------------------------------------------
+// The embedding model
+// ---------------------------------------------------------------------------------------------
+
+/** Files already checked this process, keyed by path, so a 90 MB file is not hashed every round. */
+const verified = new Map();
+
+function sha256Of(file) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash("sha256");
+    fs.createReadStream(file)
+      .on("data", (chunk) => hash.update(chunk))
+      .on("error", reject)
+      .on("end", () => resolve(hash.digest("hex")));
+  });
+}
+
+async function alreadyInPlace(dest, spec) {
+  let stat;
+  try {
+    stat = fs.statSync(dest);
+  } catch {
+    return false;
+  }
+  if (stat.size !== spec.bytes) return false;
+  const key = `${stat.size}:${stat.mtimeMs}`;
+  if (verified.get(dest) === key) return true;
+  if ((await sha256Of(dest)) !== spec.sha256) return false;
+  verified.set(dest, key);
+  return true;
+}
+
+/** The engine's manifest, checked before anything is written where it points. */
+function readManifest(text) {
+  const info = JSON.parse(text);
+  const directory = info && info.directory;
+  if (typeof directory !== "string" || !path.isAbsolute(directory)) {
+    throw new Error("the engine's model manifest has no absolute directory");
+  }
+  const files = Array.isArray(info.files) ? info.files : [];
+  for (const spec of files) {
+    const ok =
+      spec &&
+      typeof spec.name === "string" &&
+      // A plain file name: letters, digits, dots, dashes and underscores, not starting with a
+      // dot. That rules out "" (which joins to the folder itself, so the download landed
+      // beside it), ".", "..", hidden names and anything with a separator in it.
+      /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(spec.name) &&
+      typeof spec.url === "string" &&
+      /^https:\/\//.test(spec.url) &&
+      typeof spec.sha256 === "string" &&
+      /^[0-9a-f]{64}$/.test(spec.sha256) &&
+      Number.isInteger(spec.bytes) &&
+      spec.bytes > 0;
+    if (!ok) throw new Error("the engine's model manifest has a file entry this cannot use");
+  }
+  return { directory, files };
+}
+
+async function downloadOne(spec, dest, fetchImpl) {
+  const part = `${dest}.${process.pid}.part`;
+  const abort = new AbortController();
+  const timer = setTimeout(() => abort.abort(), modelTimeoutMs());
+  try {
+    const response = await fetchImpl(spec.url, { signal: abort.signal });
+    if (!response || !response.ok || !response.body) {
+      throw new Error(`HTTP ${response ? response.status : "no answer"}`);
+    }
+    const hash = crypto.createHash("sha256");
+    let size = 0;
+    await pipeline(
+      Readable.fromWeb(response.body),
+      async function* check(source) {
+        for await (const chunk of source) {
+          size += chunk.length;
+          // Stopped as soon as it is too big, so a wrong file cannot fill the disk.
+          if (size > spec.bytes) throw new Error("larger than the manifest says");
+          hash.update(chunk);
+          yield chunk;
+        }
+      },
+      fs.createWriteStream(part, { mode: 0o644 })
+    );
+    if (size !== spec.bytes) throw new Error(`size ${size}, expected ${spec.bytes}`);
+    if (hash.digest("hex") !== spec.sha256) throw new Error("sha256 does not match the manifest");
+    fs.renameSync(part, dest);
+  } catch (err) {
+    // Nothing half-downloaded or wrong is ever left where the engine looks.
+    try {
+      fs.unlinkSync(part);
+    } catch {
+      // Never created.
+    }
+    if (abort.signal.aborted) throw new Error(`${spec.name}: timed out`);
+    throw new Error(`${spec.name}: ${(err && err.message) || "download failed"}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Put the embedding model where the engine looks for it, if it is not there yet.
+ *
+ * The engine never downloads anything; it names the files, their size and sha256 in
+ * `docs --model-info`, which needs no licence (niro-local `cli.py`, `_cmd_docs`). Each file is
+ * downloaded beside its final name and renamed into place only after its size and sha256 match,
+ * so the engine sees either the right file or no file.
+ */
+async function ensureModel({ fetchImpl = (...args) => fetch(...args), beforeEach = () => {} } = {}) {
+  // Off in this release (src/lib/release.js `llmDocs`): the 90 MB model is not fetched.
+  if (!require("./release").llmDocs) return { fetched: 0, present: 0, off: true };
+  const { directory, files } = readManifest(await localEngine.run(["docs", "--model-info"]));
+  const result = { fetched: 0, present: 0 };
+  fs.mkdirSync(directory, { recursive: true });
+  for (const spec of files) {
+    beforeEach();
+    const dest = path.join(directory, spec.name);
+    if (await alreadyInPlace(dest, spec)) {
+      result.present += 1;
+      continue;
+    }
+    await downloadOne(spec, dest, fetchImpl);
+    result.fetched += 1;
+  }
+  return result;
+}
+
+module.exports = { ensureModel };

package/src/lib/nestedOutput.js

@@ -14,36 +14,50 @@
  * process.stdout.write is untouched: the upload progress bar repaints one line with \r, and
  * prefixing every repaint would smear it across the terminal.
  */
-let current = 0;
+let current = "";
 
-/** How deep the output is nested right now. prompt.js prefixes its questions with this. */
+/** How deep the output is nested right now, in columns. */
 function currentIndent() {
+  return current.length;
+}
+
+/** What starts every nested line right now: spaces, or the setup rail ("│  "). Writers that
+ * bypass console (prompt, spinner, progress) prefix their own lines with this. */
+function currentPad() {
   return current;
 }
 
 function withIndent(spaces, fn) {
-  const pad = " ".repeat(spaces);
+  return withPrefix(" ".repeat(spaces), fn);
+}
+
+/**
+ * withIndent with any prefix. `niro start` passes its rail, "│  ", so what a command prints
+ * inside a step stays on the rail instead of breaking it.
+ */
+function withPrefix(prefix, fn) {
   const shift = (orig) => (...args) => {
     const text = args.map((a) => (typeof a === "string" ? a : String(a))).join(" ");
-    // A line with nothing but spaces is emitted empty. Some callers print a whitespace-only
-    // string as a spacer, and padding it left a visible run of trailing whitespace.
-    orig(text.split("\n").map((l) => (l.trim() ? pad + l : "")).join("\n"));
+    // A line with nothing but spaces is emitted as the prefix alone, trimmed: empty for an
+    // indent, a bare "│" for the rail. Never trailing whitespace.
+    orig(text.split("\n").map((l) => (l.trim() ? prefix + l : prefix.trimEnd())).join("\n"));
   };
   const log = console.log;
   const error = console.error;
   const warn = console.warn;
-  current += spaces;
+  const outer = current;
+  current += prefix;
   console.log = shift(log);
   console.error = shift(error);
   console.warn = shift(warn);
   return Promise.resolve()
     .then(fn)
     .finally(() => {
-      current -= spaces;
+      current = outer;
       console.log = log;
       console.error = error;
       console.warn = warn;
     });
 }
 
-module.exports = { withIndent, currentIndent };
+module.exports = { withIndent, withPrefix, currentIndent, currentPad };

package/src/lib/onboardingLog.js

@@ -0,0 +1,34 @@
+/**
+ * Where `niro start` notes how long each step took and how it ended, in
+ * ~/.niro/onboarding.json, as `[{step, startedAt, endedAt, outcome}]`.
+ *
+ * Kept on the machine only; whether it is ever sent is an open question (Q11). A failure to
+ * write is swallowed: a note about the wizard must never stop the wizard.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+function file(home = os.homedir()) {
+  return path.join(home, ".niro", "onboarding.json");
+}
+
+function record(entry, { home = os.homedir() } = {}) {
+  try {
+    const where = file(home);
+    let list = [];
+    try {
+      list = JSON.parse(fs.readFileSync(where, "utf8"));
+      if (!Array.isArray(list)) list = [];
+    } catch {
+      list = [];
+    }
+    list.push(entry);
+    fs.mkdirSync(path.dirname(where), { recursive: true });
+    fs.writeFileSync(where, JSON.stringify(list, null, 2) + "\n");
+  } catch {
+    // ponytail: best effort by design, see above.
+  }
+}
+
+module.exports = { record, file };