@niroai/niro 0.17.0 → 1.0.0

package/src/commands/guide.js

@@ -0,0 +1,254 @@
+/**
+ * `niro guide`: read the documentation that ships in the package, from the terminal, offline.
+ *
+ *   niro guide                      every page, grouped as docs/index.md groups them, one line each
+ *   niro guide <topic>              one page (by name, title or word); a short list when several match
+ *   niro guide --search <words>     every page holding the words, with the lines that hold them
+ *   --json                          one JSON object instead, for an agent; --no-pager prints straight out
+ *
+ * Not `niro docs`, which is the engine's own route (src/commands/engineRoutes.js). Long output goes
+ * through a pager only when it is printed to a terminal and is taller than the window. A topic no page
+ * name, title or line matches shows what a search finds instead; only when that finds nothing too, and
+ * for a search with no match, does it exit with 1. Every --json answer has the same keys (envelope).
+ */
+"use strict";
+
+const { spawnSync } = require("child_process");
+const guideLib = require("../lib/guide");
+const { search } = require("../lib/guideSearch");
+
+const MAX_RESULTS = 10;
+/** How many search results a topic with no match shows in their place. */
+const FALLBACK_RESULTS = 3;
+
+/** The pager to run: $PAGER, else less (more on Windows). */
+function pagerCommand(env = process.env, platform = process.platform) {
+  return env.PAGER || (platform === "win32" ? "more" : "less");
+}
+
+/**
+ * Show `text` through the pager. Returns false when the pager could not be started, so the caller
+ * prints the text itself. `less` gets FRX unless LESS is set: quit when it fits, keep colour, leave the
+ * text on the screen afterwards. $PAGER runs through a shell, as git and man run it: the value is the
+ * person's own setting, so this runs nothing they could not run themselves.
+ *
+ * Ctrl-C while the pager shows reaches both processes. niro ignores it until the pager ends, as git does,
+ * so the pager handles it and the terminal is left as the pager leaves it. The listener is removed
+ * straight after: a signal that came in meanwhile is dropped, not delivered later.
+ */
+function runPager(text, { env = process.env, platform = process.platform, spawn = spawnSync } = {}) {
+  const command = pagerCommand(env, platform);
+  const childEnv = { ...env };
+  if (childEnv.LESS === undefined) childEnv.LESS = "FRX";
+  const ignore = () => {};
+  process.on("SIGINT", ignore);
+  let r;
+  try {
+    r = spawn(command, { shell: true, input: `${text}\n`, stdio: ["pipe", "inherit", "inherit"], env: childEnv });
+  } finally {
+    process.removeListener("SIGINT", ignore);
+  }
+  if (r.error) return false;
+  // 127 from sh, 9009 from cmd.exe: the pager was not found, and nothing was shown.
+  if (r.status === 127 || r.status === 9009) return false;
+  return true;
+}
+
+/** Print `text`, through the pager when it is for a terminal and taller than the window. */
+function show(text, io) {
+  const tall = text.split("\n").length > Math.max(1, (io.rows || 24) - 1);
+  if (io.isTTY && io.pager !== false && tall && io.runPager(text)) return;
+  io.write(`${text}\n`);
+}
+
+function cut(line, io) {
+  if (!io.isTTY || !io.columns || line.length <= io.columns) return line;
+  return `${line.slice(0, Math.max(10, io.columns - 3))}...`;
+}
+
+function pageLines(pages, io) {
+  const width = Math.min(34, Math.max(...pages.map((p) => p.page.length)) + 2);
+  return pages.map((p) => cut(`  ${p.page.padEnd(width)}${p.summary}`, io));
+}
+
+function listText(guide, io) {
+  const count = [...guide.pages.values()].filter((p) => p.listed).length;
+  const out = [
+    `Niro documentation: ${count} pages, on this computer.`,
+    "  niro guide <page>             read a page",
+    "  niro guide --search <words>   search every page",
+  ];
+  if (guide.start) out.push(`Start with: niro guide ${guide.start}`);
+  const all = guide.groups.flatMap((g) => g.pages.map((p) => guide.pages.get(p)));
+  const width = Math.min(34, Math.max(0, ...all.map((p) => p.page.length)) + 2);
+  for (const g of guide.groups) {
+    out.push("", io.bold(g.name));
+    for (const name of g.pages) {
+      const p = guide.pages.get(name);
+      out.push(cut(`  ${p.page.padEnd(width)}${p.summary}`, io));
+    }
+  }
+  return out.join("\n");
+}
+
+/** Every --json answer: the same keys whatever the form, so an agent reads one shape. */
+function envelope(mode, fields = {}) {
+  return {
+    mode, // "list" | "page" | "choose" | "search" | "none"
+    query: null,
+    note: null,
+    start: null,
+    groups: [],
+    page: null,
+    matches: [],
+    match: null, // for "search": "phrase", "words", "pages" or "closest"
+    results: [],
+    total: 0,
+    error: null,
+    ...fields,
+  };
+}
+
+function writeJson(io, value) {
+  io.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function brief(p) {
+  return { page: p.page, title: p.title, summary: p.summary || p.title };
+}
+
+function listJson(guide) {
+  const groups = guide.groups.map((g) => ({ name: g.name, pages: g.pages.map((n) => brief(guide.pages.get(n))) }));
+  return envelope("list", { start: guide.start, groups, total: groups.reduce((n, g) => n + g.pages.length, 0) });
+}
+
+/** Nothing to show: one sentence on stderr (or a JSON answer saying it), exit code 1. */
+function nothing(io, json, query, message) {
+  if (json) writeJson(io, envelope("none", { query, error: message }));
+  else io.writeErr(`${message}\n`);
+  io.setExitCode(1);
+}
+
+function searchHeading(found, typed) {
+  const n = found.results.length;
+  const query = found.searched ? found.searched : typed;
+  const from = found.searched ? ` (from "${typed}")` : "";
+  if (found.match === "closest" && found.byPage) return `No page holds every word of "${query}"${from}; closest matches:`;
+  if (found.match === "closest") return `No line holds every word of "${query}"${from}. The closest ${n === 1 ? "page" : `${n} pages`}:`;
+  if (found.match === "pages") return `No line holds every word of "${query}"${from}; ${n === 1 ? "this page holds" : `${n} pages hold`} them all, best first:`;
+  return `${n} page${n === 1 ? " matches" : "s match"} "${query}"${from}.`;
+}
+
+function searchLines(results, io, limit) {
+  const out = [];
+  for (const r of results.slice(0, limit)) {
+    out.push("", `${io.bold(`niro guide ${r.page}`)}  ${r.title}`);
+    for (const l of r.lines) out.push(cut(`    ${l.text}`, io));
+    if (r.total > r.lines.length) out.push(`    (and ${r.total - r.lines.length} more line${r.total - r.lines.length === 1 ? "" : "s"})`);
+  }
+  return out;
+}
+
+function showPage(p, io, json) {
+  if (p.unreadable) return nothing(io, json, p.page, `The page ${p.page} cannot be read (${p.unreadable}). Reinstall niro with npm install -g @niroai/niro.`);
+  if (json) {
+    writeJson(io, envelope("page", {
+      query: p.page,
+      page: { page: p.page, title: p.title, text: guideLib.render(p.text), links: guideLib.linkedPages(p.text) },
+      total: 1,
+    }));
+    return;
+  }
+  show(guideLib.render(p.text, { bold: io.bold }), io);
+}
+
+function showTopic(guide, topic, io, json) {
+  const found = guideLib.find(guide, topic);
+  if (found.page) return showPage(found.page, io, json);
+  if (found.matches.length) {
+    if (json) return writeJson(io, envelope("choose", { query: topic, matches: found.matches.map(brief), total: found.matches.length }));
+    const lines = [`${found.matches.length} pages match "${topic}". Run one of:`, ...pageLines(found.matches.map(brief), io).map((l) => l.replace(/^  /, "  niro guide "))];
+    return show(lines.join("\n"), io);
+  }
+  // No page is called that: show what a search finds, rather than only pointing at --search. A topic of
+  // one- and two-letter words ("a", "is") is in nearly every page, so it is not searched for.
+  if (guideLib.keyWords(topic).every((w) => w.length <= 2)) {
+    return nothing(io, json, topic, `No page matches "${topic}". Give a longer topic, or see every page with: niro guide`);
+  }
+  const searched = search(guide, topic);
+  if (!searched.results.length) return nothing(io, json, topic, `No page matches "${topic}". See every page with: niro guide`);
+  // Worded from how the search matched: "come closest" when no line holds every word typed.
+  const note = `No page is called "${topic}". ${searched.match === "closest" ? "These pages come closest." : "These pages mention it."}`;
+  if (json) return writeJson(io, envelope("search", { query: topic, note, match: searched.match, results: searched.results, total: searched.results.length }));
+  const more = searched.results.length > FALLBACK_RESULTS ? ` (${searched.results.length} in all: niro guide --search ${topic})` : "";
+  show([`${note}${more}`, ...searchLines(searched.results, io, FALLBACK_RESULTS)].join("\n"), io);
+}
+
+function showSearch(guide, query, io, json) {
+  if (!query.trim()) return nothing(io, json, "", "Give the words to search for: niro guide --search <words>");
+  const found = search(guide, query);
+  if (!found.results.length) return nothing(io, json, query, `No page matches "${query}". Try fewer words, or see every page with: niro guide`);
+  if (json) return writeJson(io, envelope("search", { query, match: found.match, results: found.results, total: found.results.length }));
+  const out = [searchHeading(found, query), ...searchLines(found.results, io, MAX_RESULTS)];
+  if (found.results.length > MAX_RESULTS) out.push("", `and ${found.results.length - MAX_RESULTS} more pages (--json lists them all).`);
+  show(out.join("\n"), io);
+}
+
+/**
+ * A reader that stops early (`niro guide x | head`) closes the pipe: that is not an error, so niro ends
+ * quietly with 0 rather than printing Node's crash for the write it could not finish.
+ */
+function quietOnClosedPipe(stream = process.stdout, exit = process.exit) {
+  if (stream.listenerCount("error") && stream._niroGuidePipe) return;
+  stream._niroGuidePipe = true;
+  stream.on("error", (err) => {
+    if (err && err.code === "EPIPE") return exit(0);
+    throw err;
+  });
+}
+
+/**
+ * The command. `words` are the words typed after `niro guide`; `opts` carries json, search, pager.
+ * `io` replaces the terminal in tests.
+ */
+function guide(words = [], opts = {}, io = {}) {
+  const color = require("../lib/color");
+  const json = Boolean(opts.json);
+  if (!io.write) quietOnClosedPipe();
+  const term = {
+    write: (s) => process.stdout.write(s),
+    writeErr: (s) => process.stderr.write(s),
+    setExitCode: (c) => { process.exitCode = c; },
+    isTTY: Boolean(process.stdout.isTTY),
+    rows: process.stdout.rows,
+    columns: process.stdout.columns,
+    runPager: (text) => runPager(text),
+    bold: color.bold,
+    ...io,
+  };
+  term.pager = opts.pager !== false && !json;
+  const loaded = guideLib.load(opts.docsDir);
+  const query = words.join(" ").trim();
+  if (opts.search) return showSearch(loaded, query, term, json);
+  if (!query) {
+    if (json) return writeJson(term, listJson(loaded));
+    return show(listText(loaded, term), term);
+  }
+  return showTopic(loaded, query, term, json);
+}
+
+/**
+ * Add `niro guide` to the command line. `run` is src/index.js's error wrapper. Registered after every other
+ * command, in one line of src/index.js, so the line numbers the docs pages cite in that file stay where they are.
+ */
+function register(program, run) {
+  program
+    .command("guide [topic...]")
+    .description("Read Niro's documentation in the terminal, offline. No topic lists the pages; a page name, title or word shows that page.")
+    .option("--search", "search every page for the words given, and show the lines that hold them")
+    .option("--json", "emit machine-readable JSON")
+    .option("--no-pager", "print straight out, even to a terminal")
+    .action((topic, opts) => run(async () => guide(topic, { ...opts })));
+}
+
+module.exports = { guide, register, runPager, pagerCommand, envelope, quietOnClosedPipe };

package/src/commands/init.js

@@ -41,16 +41,17 @@ const color = require("../lib/color");
 const watchDaemon = require("../lib/watchDaemon");
 const { login } = require("./login");
 const { watchStatus } = require("./build");
-const { currentIndent, withIndent } = require("../lib/nestedOutput");
+const { currentPad, withIndent } = require("../lib/nestedOutput");
 
 /** Depth as spaces, for the \r-written lines that bypass withIndent's console wrappers. */
 function nestPad() {
-  return " ".repeat(currentIndent());
+  return currentPad();
 }
 const { fetchPreview, buildCandidates } = require("./edit");
 const { resolveProjectId } = require("./_resolveProject");
 const { projectsToRows } = require("./projects");
 const { isSecretKey, looksSecretValue } = require("../lib/secret");
+const cloudGuard = require("../lib/cloudGuard");
 
 const step = (n) => color.bold(color.cyan(n));
 const ok = (s) => color.green(s);
@@ -66,6 +67,9 @@ async function init(pathArg, opts = {}) {
   const nested = !!opts.nested;
   const substep = (n) => (nested ? step("●") : step(n));
   const targetDir = resolveTargetDir(pathArg);
+  // Before anything else, including the flag checks: onboarding a folder the engine on this
+  // machine already indexes would upload its source and index it twice.
+  if (await cloudGuard.refuseIfIndexedLocally(targetDir, { command: "init" })) return;
   // Validate flag values up-front so a bad --auto-build/--confirm-build/--quiet-period
   // fails BEFORE any server-side mutation (otherwise a typo leaves an orphan project).
   parseOnOff(opts.autoBuild);

package/src/commands/initLocal.js

@@ -0,0 +1,96 @@
+/**
+ * `niro init [path]` in a release without the cloud: add one folder to the local engine and build
+ * it, on a machine `niro start` has already set up.
+ *
+ * `niro start` is the once-per-machine setup (sign-in and terminal approval, the plan, the engine,
+ * the assistant, the watch daemon). Every folder after the first only needs adding and building,
+ * so this does just that and stops with a pointer to `niro start` when the machine is not set up.
+ * An already indexed folder is built again. The line limit is the engine's rule (`planUsage.refusesBuild`):
+ * at or over it, a folder that adds new lines goes to the console's /limit page instead of building,
+ * while a folder already counted (a rebuild, a temporary copy, a service inside an indexed root) builds.
+ *
+ * `niro build` is the same with `rebuildOnly`: it rebuilds a folder already added and refuses one
+ * that is not, so each command keeps the engine's meaning (init adds, build rebuilds).
+ *
+ * Adding and building is one engine command, the engine's own `init`, which builds the folder it adds (Niraj,
+ * 2026-11-06: "niro-local init should also build it"), so the folder is built once. `niro init` takes every option
+ * of the engine's `init` with the same meaning (`--project`, `--branch`, `--path`, `--base-url`, `--force`): "niro
+ * init should also support --project <name> the same way niro-local does. support all option of niro-local init to
+ * niro init". So `niro init --project niro` in a second repository joins the project "niro" and builds it.
+ */
+const path = require("path");
+const color = require("../lib/color");
+const engine = require("../lib/engine");
+const lease = require("../lib/lease");
+const localOnboard = require("../lib/localOnboard");
+const planUsage = require("../lib/planUsage");
+const progressBar = require("../lib/progressBar");
+const start = require("./start");
+
+const n = (x) => x.toLocaleString("en-US");
+
+function stop(message) {
+  console.error(message);
+  process.exitCode = 1;
+}
+
+async function initLocal(pathArg, {
+  hasCredentials = start.hasCredentials, resolveEngine = engine.resolve, currentClaims = lease.currentClaims,
+  linesUsed = planUsage.linesUsed, alreadyCounted = planUsage.alreadyCounted, onboard = localOnboard,
+  openUrl = require("../lib/browser").open, rebuildOnly = false, buildArgs = [], initOptions = {},
+} = {}) {
+  if (!hasCredentials()) return stop(`Not signed in. Run ${color.cyan("niro start")} once to sign in and set up this machine.`);
+  if (!resolveEngine()) return stop(`The local engine is not installed. Run ${color.cyan("niro start")} once to set up this machine.`);
+  const { path: pathOption, ...engineOptions } = initOptions;
+  if (pathArg && pathOption && path.resolve(pathArg) !== path.resolve(pathOption)) {
+    return stop(`Two folders were given (${pathArg} and --path ${pathOption}). Give one.`);
+  }
+  const dir = path.resolve(pathOption || pathArg || ".");
+  const problem = start.describeProblem(dir);
+  if (problem) return stop([problem.headline, ...problem.detail].join("\n"));
+
+  const known = await onboard.worktreeFor(dir);
+  if (!known && rebuildOnly) return stop(`This folder is not added yet. Run ${color.cyan("niro init")} to add it and build it.`);
+
+  const claims = await currentClaims().catch(() => null);
+  const before = await linesUsed();
+  if (await planUsage.refusesBuild(claims, before, dir, { counted: alreadyCounted })) {
+    const url = planUsage.limitUrl(before, claims.max_lines);
+    console.error(`Not built: this machine already holds ${n(before)} lines of code, over the ${n(claims.max_lines)} line limit.`);
+    console.error(`Choose how to continue: ${color.cyan(url)}`);
+    console.error(`Or see the options with ${color.cyan("niro plan")}, or free lines by stopping a folder: ${color.cyan("niro remove --path <folder>")}`);
+    openUrl(url);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`${known && !engineOptions.project ? "Rebuilding" : "Building"} the graph for ${dir}`);
+  const bar = progressBar.create();
+  const onProgress = (d, total) => bar.update(d, total);
+  let built;
+  try {
+    // `niro build` rebuilds what is added; `niro init` asks the engine's `init`, which adds the folder if it is not
+    // yet and builds it, and refuses a folder it cannot index before writing anything, in its own words.
+    built = rebuildOnly
+      ? await onboard.build(dir, onProgress, { extraArgs: buildArgs })
+      : await onboard.initAndBuild(dir, onProgress, engineOptions);
+  } catch (err) {
+    bar.stop();
+    // A refusal such as "not in project X" is on standard output (`niro build --project X`).
+    return stop(((err && (err.refused ? err.message : (err.stderr || err.stdout || err.message))) || String(err)).replace(/^error:\s*/, ""));
+  }
+  bar.stop();
+  // What the engine's init said about the folder (the project it joined, a --branch it ignored), then the count.
+  for (const line of built.said || []) console.log(line);
+  // No build report: the engine changed nothing and said why (a subfolder of an added folder, named with --project).
+  if (built.files == null && built.lines == null && built.said && built.said.length) return;
+  const parts = [built.files != null && `${n(built.files)} files`, built.lines != null && `${n(built.lines)} lines`].filter(Boolean);
+  console.log(`${color.green("✓")} Graph built: ${parts.join(", ") || "done"} in ${built.seconds} s`);
+  const used = await linesUsed();
+  const plan = planUsage.describe(claims, used);
+  if (plan) console.log(plan);
+  const noRoom = planUsage.noRoomNote(claims, used);
+  if (noRoom) console.log(color.yellow(`${noRoom} Run niro plan to see your options, or free lines with niro remove --path <folder>.`));
+}
+
+module.exports = { initLocal };

package/src/commands/journalSend.js

@@ -0,0 +1,47 @@
+/**
+ * `niro journal-send` — hand the local engine's record of what it was asked to Niro.
+ *
+ * The engine answers an assistant's questions on this machine, so unlike a hosted session
+ * none of those calls are visible to us. The engine keeps its own record and this sends it, so
+ * the same question ("which tools get used, which fail, where does an assistant fall back to
+ * reading files") can be answered for local sessions too.
+ *
+ * A command of its own so the path can be run and watched by hand; in normal use the watcher
+ * calls the same library, next to the audit upload.
+ *
+ * Prints counts and never a payload.
+ */
+const journalUpload = require("../lib/journalUpload");
+const color = require("../lib/color");
+
+async function journalSend(opts = {}) {
+  const limit = Number(opts.limit) || 20;
+  console.log(`Sending the local engine's MCP journal to ${journalUpload.assistantUrl()}`);
+
+  const result = await journalUpload.uploadPending({ limit });
+
+  if (result.sent) {
+    console.log(`  ${result.sent} session(s) sent, ${result.calls} tool call(s)`);
+  } else if (!result.failed && !result.unmasked) {
+    // A session still in use is held back by the engine, so "nothing waiting" is the normal
+    // answer in the middle of a task rather than a sign that nothing was recorded.
+    console.log("  nothing waiting");
+  }
+
+  if (result.unmasked) {
+    // Sessions from an engine older than on-machine masking: never sent unmasked, so they wait.
+    console.log(color.yellow(
+      `  ${result.unmasked} session(s) not sent: the local engine is too old to mask secrets. Run \`niro upgrade\`.`
+    ));
+  }
+
+  if (result.failed) {
+    console.log(color.yellow(`  ${result.failed} session(s) could not be sent:`));
+    for (const failure of result.failures.slice(0, 5)) console.log(`    ${failure}`);
+    if (result.failures.length > 5) {
+      console.log(`    ... and ${result.failures.length - 5} more`);
+    }
+  }
+}
+
+module.exports = { journalSend };

package/src/commands/login.js

@@ -150,7 +150,8 @@ async function loginWithDeviceFlow({ apiUrl }) {
   const deviceCode = resp.device_code || resp.deviceCode;
   const verificationUri = resp.verification_uri_complete || resp.verificationUriComplete
     || resp.verification_uri || resp.verificationUri;
-  const interval = Number(resp.interval || DEFAULT_POLL_INTERVAL_SECONDS);
+  // `??`, not `||`: a server may legitimately say 0, and a test certainly does.
+  const interval = Number(resp.interval ?? DEFAULT_POLL_INTERVAL_SECONDS);
   const expiresIn = Number(resp.expires_in || resp.expiresIn || DEFAULT_EXPIRY_SECONDS);
 
   if (!userCode || !deviceCode || !verificationUri) {
@@ -162,11 +163,17 @@ async function loginWithDeviceFlow({ apiUrl }) {
   // without hardcoding a host that is wrong for UAT and wrong for every self-hosted install.
   rememberAppUrl(verificationUri);
 
-  console.log(`\n    Your one-time code: ${color.bold(color.cyan(userCode))}`);
-  console.log(`    Open: ${color.cyan(verificationUri)}\n`);
+  // Written past any rail prefix: the box draws its own left edge, which is the rail.
+  const nested = !!require("../lib/nestedOutput").currentPad();
+  console.log("");
+  for (const line of codeBox(userCode, expiresIn, nested)) process.stdout.write(`${line}\n`);
+  // Two columns in, so these line up with the text inside the box above.
+  console.log(`\n  Opening ${color.cyan(verificationUri)}...`);
+  console.log(color.dim("  If the browser didn't open, go to:"));
+  console.log(`    ${color.cyan(verificationUri)}\n`);
   browser.open(verificationUri);
 
-  const sp = spinner.start("        Waiting for browser approval...");
+  const sp = spinner.start("  Waiting for browser approval...");
   const deadline = Date.now() + expiresIn * 1000;
   try {
     while (Date.now() < deadline) {
@@ -181,7 +188,8 @@ async function loginWithDeviceFlow({ apiUrl }) {
         if (token) {
           const email = (tokenResp.user && tokenResp.user.email) || tokenResp.email || null;
           const cliToken = tokenResp.niro_api_key || tokenResp.niroApiKey || null;
-          sp.stop(`${color.green("✓")} Logged in${email ? ` as ${color.bold(email)}` : ""}.`);
+          // Inside `niro start` the step's own closing line names the account; say it once.
+          sp.stop(nested ? undefined : `${color.green("✓")} Logged in${email ? ` as ${color.bold(email)}` : ""}.`);
           credentials.save({
             apiUrl,
             token,
@@ -190,11 +198,16 @@ async function loginWithDeviceFlow({ apiUrl }) {
             email,
             userId: (tokenResp.user && tokenResp.user.id) || tokenResp.user_id || tokenResp.userId || null,
           });
-          return;
+          return { email };
         }
       } catch (err) {
         if (isPending(err)) continue;
-        throw err;
+        const terminal = TERMINAL_ANSWERS[errorCode(err)];
+        if (!terminal) throw err;
+        sp.stop();
+        for (const line of terminal.say) console.log(`    ${line}`);
+        process.exitCode = terminal.exitCode;
+        return terminal.result;
       }
     }
     sp.stop(`${color.red("✗")} Login timed out. Run ${color.cyan("niro login")} to try again.`);
@@ -204,6 +217,38 @@ async function loginWithDeviceFlow({ apiUrl }) {
   }
 }
 
+/**
+ * The device code in a titled box, so it stands out from the lines around it:
+ *
+ *     Approve in your browser ─────┐
+ *                                  │
+ *     Your code:                   │
+ *         ABCD-EFGH                │
+ *                                  │
+ *     Code expires in 15 minutes   │
+ *   ───────────────────────────────┘
+ */
+function codeBox(userCode, expiresIn, nested = false) {
+  const minutes = Math.max(1, Math.round(expiresIn / 60));
+  const expiry = `Code expires in ${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const rows = [
+    ["", ""],
+    [color.dim(color.bold("Your authorization code:")), "Your authorization code:"],
+    ["", ""],
+    [`    ${color.bold(color.green(userCode))}`, `    ${userCode}`],
+    ["", ""],
+    [color.dim(expiry), expiry],
+    ["", ""],
+  ];
+  const title = "Browser Authorization";
+  const width = Math.max(title.length + 4, ...rows.map(([, plain]) => plain.length + 2));
+  // The box's left edge is the setup rail itself: title on the marker row, bottom joins the rail.
+  const out = [`${color.green("◇")}  ${title} ${color.dim(`${"─".repeat(width - title.length - 1)}┐`)}`];
+  for (const [shown, plain] of rows) out.push(`│  ${shown}${" ".repeat(width - plain.length)}${color.dim("│")}`);
+  out.push(`${nested ? "├" : "└"}${color.dim(`${"─".repeat(width + 2)}┘`)}`);
+  return out;
+}
+
 /**
  * Store the web app's origin, taken from the device-flow verification URI.
  *
@@ -219,16 +264,48 @@ function rememberAppUrl(verificationUri) {
   }
 }
 
-function isPending(err) {
-  const body = err.body;
-  if (!body) return false;
+/** The error code the device-token endpoint answered with, or null. */
+function errorCode(err) {
+  const body = err && err.body;
+  if (!body) return null;
   const code = typeof body === "string" ? body : body.error || body.message;
-  if (typeof code !== "string") return false;
+  return typeof code === "string" ? code.trim() : null;
+}
+
+function isPending(err) {
+  const code = errorCode(err);
+  if (!code) return false;
   return /authorization[_-]?pending/i.test(code) || /slow[_-]?down/i.test(code);
 }
 
+/**
+ * Answers that end the wait (contract C1 + addendum). Each one is a sentence for the person
+ * at the terminal, not a stack: a waiting account used to sit on the spinner until the code
+ * expired, 30 minutes later, because only pending and slow_down were understood.
+ */
+const RESTART = ["The sign-in was not completed. Run niro start again to get a new code."];
+const TERMINAL_ANSWERS = {
+  account_waiting: {
+    say: ["You are on the list. We will email you when you are in. Then run niro start again."],
+    exitCode: 0,
+    result: { waiting: true },
+  },
+  account_blocked: {
+    say: ["This account cannot sign in to Niro. If you think that is a mistake, reply to any Niro email."],
+    exitCode: 1,
+    result: { blocked: true },
+  },
+  request_submitted: {
+    say: ["Request sent. We reply within one business day. Run niro start again once your trial starts."],
+    exitCode: 0,
+    result: { requestSubmitted: true },
+  },
+  access_denied: { say: RESTART, exitCode: 1, result: { denied: true } },
+  expired_token: { say: RESTART, exitCode: 1, result: { expired: true } },
+};
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-module.exports = { login, rememberAppUrl };
+module.exports = { login, rememberAppUrl, codeBox };

package/src/commands/mcp.js

@@ -18,18 +18,34 @@ const childProcess = require("child_process");
  * `niro upgrade` passes its own `--client <id>`, because the flags on its command line
  * (`--finish`, `--from`) are not the wizard's.
  */
-function runWizard(scriptName, label, args) {
+function runWizard(scriptName, label, args, { quiet = false } = {}) {
   const wizardArgs = Array.isArray(args) ? args : process.argv.slice(4);
   return new Promise((resolve, reject) => {
     const child = childProcess.spawn(
       process.execPath,
       [path.join(__dirname, "..", "mcp", scriptName), ...wizardArgs],
-      { stdio: "inherit" }
+      // The child prints for itself, out of reach of withPrefix; it is told the prefix instead,
+      // so inside `niro start` its lines stay on the setup rail. `quiet` keeps its lines for a
+      // failure instead (`niro uninstall` says one line per step).
+      {
+        stdio: quiet ? ["inherit", "pipe", "pipe"] : "inherit",
+        env: { ...process.env, NIRO_OUTPUT_PREFIX: require("../lib/nestedOutput").currentPad() },
+      }
     );
+    let said = "";
+    if (quiet) {
+      child.stdout.on("data", (c) => (said += c));
+      child.stderr.on("data", (c) => (said += c));
+    }
     child.on("error", reject);
     child.on("exit", (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`MCP ${label} wizard exited with code ${code}`));
+      if (code === 0) return resolve(said);
+      const err = new Error(`MCP ${label} wizard exited with code ${code}${said.trim() ? `\n${said.trim()}` : ""}`);
+      // A wizard that printed to the terminal has already said why it stopped; the CLI exits
+      // with its code and adds nothing ("Error: MCP setup wizard exited with code 1" read as a crash).
+      err.alreadySaid = !quiet;
+      err.exitCode = code;
+      reject(err);
     });
   });
 }
@@ -38,8 +54,8 @@ async function install(args) {
   return runWizard("setup.js", "setup", args);
 }
 
-async function uninstall() {
-  return runWizard("teardown.js", "uninstall");
+async function uninstall(args, opts) {
+  return runWizard("teardown.js", "uninstall", args, opts);
 }
 
 function serve() {