voroa-cli 0.0.0-stage → 0.3.0

package/src/resolve.js

@@ -0,0 +1,64 @@
+// "myapp" -> a service uuid.
+//
+// TENANCY (golden rule 2, bug #14): the candidate set is EXCLUSIVELY `GET /api/apps` called with
+// the active workspace header. That response is already scoped by the server to this caller AND
+// this workspace, so a name can only ever resolve to something they own here. The CLI keeps no
+// local name->uuid map: a cached id from another workspace would be a client-side claim about
+// ownership, and the server is the only thing entitled to make that claim.
+//
+// A uuid is accepted as-is only when it matches a row in that same response - so passing a uuid is
+// a shortcut past the name lookup, not past the ownership check.
+import { listApps } from './api.js';
+import { CliError } from './errors.js';
+import { findLink } from './link.js';
+import { err } from './output.js';
+
+// The ONE name-or-id matcher (services and databases both use it). Order: uuid, then exact name, then
+// case-insensitive name. Returns { match } | { ambiguous: rows } | {}.
+//
+// `idOnly` is for a needle that did NOT come from the person typing - a `.voroa.json` link. That file is
+// meant to be committed, so a cloned repo's link saying `"serviceId": "api"` must not fall through to
+// NAME matching and pick the reader's own service called "api".
+export function pickByNameOrId(rows, needle, { idOnly = false } = {}) {
+  const byUuid = rows.find((r) => r.uuid === needle);
+  if (byUuid) return { match: byUuid };
+  if (idOnly) return {};
+  const exact = rows.filter((r) => r.name === needle);
+  const matches = exact.length ? exact : rows.filter((r) => String(r.name).toLowerCase() === String(needle).toLowerCase());
+  if (matches.length === 1) return { match: matches[0] };
+  if (matches.length > 1) return { ambiguous: matches };
+  return {};
+}
+
+export function ambiguityList(rows) {
+  return rows.map((r) => `  ${r.name}  ${r.uuid}`).join('\n');
+}
+
+export async function resolveService(ctx, needle, { useLink = true } = {}) {
+  // No name given -> the folder's link, if any. The linked id is only a NEEDLE: it goes through the
+  // same scoped listing below as a typed one, so a link is a shortcut past typing, never past ownership.
+  let linked = null;
+  if (!needle && useLink) {
+    linked = findLink();
+    if (linked) {
+      needle = linked.serviceId;
+      // The link remembers its workspace; an explicit --workspace still wins.
+      if (linked.workspaceId && !ctx.workspaceExplicit) ctx.workspaceId = linked.workspaceId;
+      // Said on stderr, so a deploy never acts on a service the user did not see named.
+      err(`Using linked service ${linked.serviceName || linked.serviceId} (${linked.file})`);
+    }
+  }
+  if (!needle) throw new CliError('Which service? Pass a service name or id, or run `voroa link <service>` in this folder.', 1, 'BAD_INPUT');
+  const apps = await listApps(ctx);
+  if (apps.length === 0) {
+    throw new CliError('There are no services in this workspace. Check `voroa workspace list`.', 1, 'NOT_FOUND');
+  }
+
+  const found = pickByNameOrId(apps, needle, { idOnly: !!linked });
+  if (found.match) return found.match;
+  if (found.ambiguous) throw new CliError(`Multiple services match "${needle}", use the id:\n${ambiguityList(found.ambiguous)}`, 1, 'AMBIGUOUS');
+  if (linked) {
+    throw new CliError(`This folder is linked to ${linked.serviceName || linked.serviceId}, which is not in this workspace. Run \`voroa link <service>\` again.`);
+  }
+  throw new CliError(`No service called "${needle}" in this workspace. Run \`voroa services\` to see them.`, 1, 'NOT_FOUND');
+}

package/src/session.js

@@ -0,0 +1,270 @@
+// `voroa` with nothing after it: an interactive session (plan docs/plans/2026-11-11-cli-interactive-session.md).
+//
+// A session adds NO commands of its own beyond /help, /clear and /exit. Every line is split into words
+// and handed to the same `run()` that `voroa <args>` uses, so a command cannot behave one way typed
+// here and another way typed in a shell (rule #10). What a session does add is the terminal: a welcome
+// box, Tab completion, Up-arrow history, and a Ctrl+C that stops a log tail without ending the session.
+//
+// The terminal itself belongs to prompt.js - ONE readline interface per process, for the reason in its
+// header. This file never creates one.
+import { askCommand, configureSession, promptsEnded, dropTypeAhead, clearTypedLine, reprompt, closePrompts } from './prompt.js';
+import { readSettings, readConfig } from './config.js';
+import { contextFrom, listApps, batchStatus, isApiToken } from './api.js';
+import { classify, TONE_WORDS } from './status.js';
+import { loadKernel, commandName } from './mcpTools.js';
+import { CliError } from './errors.js';
+import { out, err, style, fancy, glyphs } from './output.js';
+
+// The welcome box makes one call. It must never be the reason a session does not open.
+const WELCOME_TIMEOUT_MS = 3000;
+const STATUS_TIMEOUT_MS = 4000;
+const SESSION_WORDS = ['help', 'clear', 'exit'];
+
+// Both ends must be a real terminal. A pipe on either side is a script, and a script gets exactly what
+// it got before sessions existed: the usage text.
+export function wantsSession(stdin = process.stdin, stdout = process.stdout) {
+  return !!(stdin && stdin.isTTY && stdout && stdout.isTTY);
+}
+
+// Words, with quotes: `--command "node job.js"` is one argument. NOT a shell - nothing is expanded or
+// executed, so `$HOME`, backticks, `|` and `>` are ordinary text. A backslash is ordinary text too
+// (Windows paths), except before a quote or another backslash inside double quotes.
+export function tokenize(line) {
+  const words = [];
+  let word = '';
+  let quote = null;
+  let open = false; // a word has begun, even if it is empty so far ("")
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      else if (quote === '"' && c === '\\' && (line[i + 1] === '"' || line[i + 1] === '\\')) word += line[++i];
+      else word += c;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+      open = true;
+    } else if (c === ' ' || c === '\t') {
+      if (open) words.push(word);
+      word = '';
+      open = false;
+    } else {
+      word += c;
+      open = true;
+    }
+  }
+  if (quote) throw new CliError(`That line has an unclosed ${quote} quote.`);
+  if (open) words.push(word);
+  return words;
+}
+
+// Tab completion. The first word completes to a command; any later word to a service name.
+export function complete(line, { commands, services }) {
+  const lastSpace = line.lastIndexOf(' ');
+  if (lastSpace === -1) {
+    const slash = line.startsWith('/') ? '/' : '';
+    const typed = line.slice(slash.length);
+    return [commands.filter((c) => c.startsWith(typed)).map((c) => slash + c), line];
+  }
+  const typed = line.slice(lastSpace + 1);
+  if (typed.startsWith('-')) return [[], typed];
+  return [services.filter((s) => s.startsWith(typed)), typed];
+}
+
+export function box(lines) {
+  const width = Math.max(...lines.map((l) => l.length));
+  const edge = `+${'-'.repeat(width + 2)}+`;
+  // Plain ASCII on purpose: box-drawing characters depend on the terminal's code page, and on a
+  // Windows console that is not UTF-8 they arrive as garbage.
+  return [edge, ...lines.map((l) => `| ${l.padEnd(width)} |`), edge].join('\n');
+}
+
+function withDeadline(promise, ms) {
+  let timer;
+  const late = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new CliError('Voroa did not answer in time.')), ms);
+  });
+  return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+
+export async function startSession({ run, version, commands }) {
+  const state = { running: false, sigints: 0, services: [], commands: [...commands, 'tools', ...SESSION_WORDS] };
+
+  // The service names offered by Tab come from the server's own workspace-scoped list - the same one
+  // the resolver uses - and are thrown away whenever the account or the workspace may have changed.
+  async function loadServices() {
+    const settings = readSettings();
+    if (!settings.token) {
+      state.services = [];
+      return { signedIn: false };
+    }
+    const apps = await withDeadline(listApps(contextFrom(settings)), WELCOME_TIMEOUT_MS);
+    state.services = apps.map((a) => a.name);
+    return { signedIn: true, count: apps.length, viaToken: isApiToken(settings.token), apps, ctx: contextFrom(settings) };
+  }
+
+  // How many are running, idle, failed. One more read, on its own short deadline - and if it does not
+  // answer for EVERY service the line falls back to the plain count, because "7 running" over a partial
+  // answer would be a number we did not measure.
+  async function tally(w) {
+    if (!w.count) return null;
+    const statuses = await withDeadline(batchStatus(w.ctx, w.apps.map((a) => a.uuid)), STATUS_TIMEOUT_MS);
+    if (statuses.size < w.count) return null;
+    const n = { green: 0, gray: 0, amber: 0, red: 0 };
+    for (const st of statuses.values()) n[classify(st.containerStatus, st.deploymentStatus, st.verdict).tone] += 1;
+    return n;
+  }
+
+  function servicesLine(w, n, pretty) {
+    if (!n) return `${w.count} ${w.count === 1 ? 'service' : 'services'} in this workspace`;
+    const g = glyphs();
+    const part = (tone, mark) => (pretty ? `${style(tone, g[mark])} ${n[tone]} ${TONE_WORDS[tone]}` : `${n[tone]} ${TONE_WORDS[tone]}`);
+    const parts = [part('green', 'run'), part('gray', 'idle')];
+    if (n.amber) parts.push(part('amber', 'busy'));
+    parts.push(part('red', 'fail'));
+    return parts.join(pretty ? '   ' : ', ');
+  }
+
+  async function welcome() {
+    const pretty = fancy();
+    const rows = []; // [label, value] - the same facts for both renderings
+    let note = null;
+    try {
+      const w = await loadServices();
+      if (!w.signedIn) note = 'Not signed in - type /login';
+      else {
+        const email = readConfig().email;
+        rows.push(['Account', w.viaToken ? 'the API token in VOROA_TOKEN' : email || 'signed in']);
+        let n = null;
+        try {
+          n = await tally(w);
+        } catch (e) {
+          // The header simply shows the count; a command that needs statuses will report the reason.
+          state.lastTallyError = e;
+        }
+        rows.push(['Services', servicesLine(w, n, pretty)]);
+      }
+    } catch (e) {
+      // Offline, an expired session, a slow answer: say which, and open the prompt anyway.
+      note = e && e.message ? e.message : 'Could not reach Voroa right now.';
+    }
+
+    if (pretty) {
+      const g = glyphs();
+      const bar = style('violet', g.bar);
+      const lines = [`${bar} ${style('violet', style('bold', `${g.logo} voroa`))}  ${style('dim', `CLI ${version}`)}`, bar];
+      for (const [label, value] of rows) lines.push(`${bar} ${style('dim', label.padEnd(9))} ${value}`);
+      if (note) lines.push(`${bar} ${note}`);
+      out('');
+      out(lines.map((l) => `  ${l}`).join('\n'));
+      out('');
+      out(`  ${style('dim', ['/help commands', 'Tab complete', 'Ctrl+C stop', '/exit'].join(`  ${g.dot}  `))}`);
+      out('');
+      return;
+    }
+    // Off a terminal: the plain box, with the same facts as sentences.
+    const plain = [`Voroa CLI ${version}`];
+    for (const [label, value] of rows) {
+      if (label !== 'Account') plain.push(value);
+      else plain.push(value === 'signed in' ? 'Signed in' : value.startsWith('the API token') ? 'Using the API token in VOROA_TOKEN' : `Signed in as ${value}`);
+    }
+    if (note) plain.push(note);
+    plain.push('Type /help for commands, Tab to complete, /exit to leave');
+    out(box(plain));
+    out('');
+  }
+
+  function onSigint() {
+    if (state.running) {
+      // A tail registered its own stop handler on the process; give it the keypress.
+      if (process.listenerCount('SIGINT') > 0) {
+        process.emit('SIGINT');
+        return;
+      }
+      state.sigints += 1;
+      if (state.sigints >= 2) {
+        // The one deliberate hard exit in this CLI (index.js explains why it is avoided elsewhere):
+        // the person has asked twice to leave a command that cannot be interrupted.
+        process.exit(130);
+      }
+      err('This command cannot be stopped midway. Press Ctrl+C again to leave the session.');
+      return;
+    }
+    if (clearTypedLine()) return;
+    state.sigints += 1;
+    if (state.sigints >= 2) {
+      closePrompts(); // ends the loop below, exactly as Ctrl+D does
+      return;
+    }
+    err('\n(Press Ctrl+C again, or type /exit, to leave.)');
+    reprompt();
+  }
+
+  configureSession({ completer: (line) => complete(line, state), onSigint });
+  try {
+    try {
+      const kernel = await loadKernel();
+      state.commands.push(...kernel.listTools().map((t) => commandName(t.name)));
+    } catch (e) {
+      // Completion for the tool commands is a nicety; the commands themselves report this properly
+      // when one is run. Said once here so a broken install is not silent.
+      err(e && e.message ? e.message : 'The tool commands could not be loaded.');
+    }
+    state.commands = [...new Set(state.commands)].sort();
+    await welcome();
+
+    for (;;) {
+      // The prompt is drawn on stderr (prompt.js), so that is the stream that decides how it looks.
+      const prompt = fancy(process.stderr) ? `${style('violet', style('bold', `voroa ${glyphs().prompt}`, process.stderr), process.stderr)} ` : '> ';
+      const line = (await askCommand(prompt)).trim();
+      if (!line) {
+        if (promptsEnded()) break;
+        continue;
+      }
+      state.sigints = 0;
+      let words;
+      try {
+        words = tokenize(line.startsWith('/') ? line.slice(1) : line);
+      } catch (e) {
+        err(e.message);
+        continue;
+      }
+      // Habit from the shell: `voroa services` typed inside the session means `services`.
+      if (words[0] === 'voroa' && words.length > 1) words.shift();
+      const name = words[0];
+      if (!name) continue;
+      if (name === 'exit' || name === 'quit') break;
+      if (name === 'session') {
+        err('You are already in a session.');
+        continue;
+      }
+      if (name === 'clear') {
+        if (process.stdout.isTTY) process.stdout.write('\x1b[2J\x1b[H');
+        continue;
+      }
+      state.running = true;
+      try {
+        await run(name === 'help' ? ['--help'] : words);
+        if (name === 'help') out('\nIn a session: the leading / is optional, Tab completes, Ctrl+C stops a log tail, /clear and /exit.');
+      } catch (e) {
+        // Same rule as the binary: a message, never an error object (the last place a token could surface).
+        err(e && e.message ? e.message : 'Something went wrong.');
+      } finally {
+        state.running = false;
+        state.sigints = 0;
+        dropTypeAhead();
+      }
+      if (name === 'login' || name === 'workspace') {
+        try {
+          await loadServices();
+        } catch (e) {
+          // Only Tab's suggestions depend on this; the next command will report a real problem itself.
+          state.services = [];
+          state.lastRefreshError = e;
+        }
+      }
+    }
+  } finally {
+    configureSession(null);
+  }
+  return 0;
+}

package/src/status.js

@@ -0,0 +1,199 @@
+// Status classify - the CLI's copy of the SPA's status vocabulary.
+//
+// WHY A COPY AND NOT AN IMPORT: `frontend/src/status.js` is a Vite/ESM module inside the SPA's
+// package; this package ships with zero dependencies and is installed on its own. It cannot reach
+// across into the frontend tree at runtime. So the two `classify` / `statusLabel` bodies below are
+// a DELIBERATE, PINNED duplicate - the same arrangement `shared/planGate.mjs` has with
+// `frontend/src/lib/planGate.js`.
+//
+// PINNED REGION - `classify` and `statusLabel` are byte-identical to the SPA's, and
+// `backend/tests/cliStatusParity.test.js` fails CI the moment one side drifts from the other. It
+// pins them two ways: the extracted function bodies must match character for character, AND both
+// implementations must answer an adversarial case table identically. If you change a status label,
+// change it in `frontend/src/status.js` and copy it here in the SAME commit.
+//
+// The SPA's other exports (`isStoppedStatus`, `serviceBucket`, `parseDomains`, `primaryDomain`) are
+// deliberately NOT copied - the CLI has no tab filter and no domain chip row, and an unused copy is
+// a copy that drifts unnoticed.
+//
+// Anything outside this file that decides a state from a raw status or verdict token is a rule #10
+// violation and is caught by the deny-list in the same test. Import from here.
+
+// Platform raw status "state:health" format me deta hai (e.g. "running:healthy",
+// "running:unknown", "exited:unhealthy"). Raw string user ko dikhana confusing hai
+// (jaise "running:unknown" -> lagta hai kuch galat hai, jabki app theek chal raha).
+// Isliye saaf human label + rang me map karte hain.
+//
+// deploymentStatus (backend se) agar 'queued'/'in_progress' hai to build chal raha hai -
+// container ka transient status (jaise "exited:unhealthy") galat hota hai, isliye usko
+// override karke "Deploying..." dikhate hain.
+export function classify(status, deploymentStatus, verdict) {
+  if (deploymentStatus === 'in_progress' || deploymentStatus === 'queued') {
+    return { label: 'Deploying…', tone: 'amber', live: true };
+  }
+
+  // Honest Deploy Verdict (build finish ke baad ka runtime gate). CONTRACT-AGNOSTIC by design: verdict
+  // chahe alag `verdict` field me aaye ya EXISTING `status` field me overlay ho - dono handle. `v` =
+  // verdict (agar diya) warna status; extended enum building|live|failed|starting|failed_to_start.
+  // 'starting'/'failed_to_start'/'failed' ko explicit map karo, state:health split se PEHLE.
+  // Render-style: runtime-fail (build theek par app up nahi hua) = "Failed" (subject = deploy);
+  // build-stage fail = "Build failed". Dono distinct, warna dono includes('fail') -> generic "Failed".
+  const v = verdict || status;
+  // Idle-sleep (ADR-0010): ek SLEEPABLE free app idle par so gaya (backend `verdict:'sleeping'` bhejta jab
+  // apps.slept_at set). NEUTRAL "Sleeping" - crash/fail NAHI (red nahi). Agle request par khud jaag jaata.
+  if (v === 'sleeping') return { label: 'Sleeping', tone: 'gray', live: true };
+  // Crash-loop suspend (ADR-0124): humne rok di kyunki wo baar-baar mar rahi thi. Ye 'failed_to_start'
+  // (laal) se alag hai aur 'sleeping' (gray, khud jaag jaata) se bhi - isliye AMBER: kuch toota nahi hai
+  // is waqt, par jab tak customer khud start nahi karta tab tak kuch chalega bhi nahi. Ek hi laal badge me
+  // "aapka app crash hua" aur "humne aapka app rok diya" ko mila dena customer se agla kadam chhupa deta.
+  if (v === 'suspended') return { label: 'Stopped by Voroa', tone: 'amber' };
+  if (v === 'paused_free_hours') return { label: 'Paused: free hours used', tone: 'amber' };
+  // ADR-0314 zero setup: service ka pehla deploy uske add-on database ka intezaar kar raha hai. Amber -
+  // kuch toota nahi, ek kadam baaki hai (payment ya database ka banna); service page par do button.
+  if (v === 'waiting_for_addon') return { label: 'Waiting for database', tone: 'amber' };
+  // `unknown` (ADR-0243) - EXPLICIT, not a fallthrough. The deploy is past every deadline and the
+  // container that could have answered is gone, so we cannot say whether the service came up. It looks
+  // the same as the catch-all below and must not BE the catch-all: `status.test.js` forbids any backend
+  // verdict reaching that line, because a verdict nobody wrote a branch for renders as an unexplained
+  // grey badge. This one is explained - grey and honest, not amber (nothing is pending) and not red
+  // (nothing is wrong). A container status, when we have one, still wins over it below.
+  if (v === 'unknown') return { label: 'Unknown', tone: 'gray' };
+  if (v === 'starting') return { label: 'Starting…', tone: 'amber', live: true };
+  if (v === 'failed_to_start') return { label: 'Failed', tone: 'red' };
+  if (v === 'failed') return { label: 'Build failed', tone: 'red' };
+
+  // Koi container status hai hi nahi. Ye NORMAL hai: platform ka apna runtime read fail ho sakta
+  // hai (ya container abhi swap ho raha ho) aur tab status null aata hai - wo best-effort hai.
+  // `verdict` ek ALAG axis pe banta hai, isliye wo abhi bhi sach hota hai - use padho, "Unknown"
+  // mat bolo. (Wording yahan jaan-boojh ke SPA se alag hai: ye file customer ki disk pe as-is
+  // install hoti hai, to yahan platform ke substrate ka naam nahi jaa sakta - golden rule 6.)
+  // NOTE: ye branch SIRF tab chalti hai jab status missing ho. Ek MAUJOOD status hamesha jeetta hai
+  // (neeche state:health parse) - warna verdict:'live' ek 'restarting:unhealthy' container ko green
+  // "Running" bana deta aur bug #30 ki poori honesty ulti ho jaati.
+  if (!status) {
+    if (v === 'live') return { label: 'Running', tone: 'green' };
+    if (v === 'building') return { label: 'Deploying…', tone: 'amber', live: true };
+    return { label: 'Unknown', tone: 'gray' };
+  }
+
+  // trim() bhi (backend lib/runtimeState.js jaisa) - engine spacing me consistent nahi hai, aur ek
+  // untrimmed ' unhealthy ' crash-loop branch ko chupchaap miss kar deta tha (parity guard ne pakda).
+  const [stateRaw, healthRaw] = String(status).split(':');
+  const state = (stateRaw || '').trim().toLowerCase();
+  const health = (healthRaw || '').trim().toLowerCase();
+
+  if (state.includes('running')) {
+    // "unknown"/missing health ka matlab sirf health-check off hai - app chal raha hai.
+    if (health === 'unhealthy') return { label: 'Unhealthy', tone: 'amber' };
+    return { label: 'Running', tone: 'green' };
+  }
+  if (state.includes('start') || state.includes('restart')) {
+    // Crash-loop honestly (bug #30): ek container jo BAAR-BAAR restart ho raha hai wo "Starting…" nahi
+    // hai - wo gir raha hai. Backend ise `restarting:unhealthy` bhejta hai (native container ka apna
+    // healthcheck FAIL, ya restart-flap detect hua). Sirf tab red - `restarting:unknown` (ek transient
+    // restart, health-check off) pehle jaisa "Starting…" hi rehta hai.
+    if (state.includes('restart') && health === 'unhealthy') {
+      return { label: 'Crash looping', tone: 'red' };
+    }
+    return { label: 'Starting…', tone: 'amber', live: true };
+  }
+  if (state.includes('build') || state.includes('deploy') || state.includes('queue')) {
+    return { label: 'Deploying…', tone: 'amber', live: true };
+  }
+  if (state.includes('degraded')) {
+    return { label: 'Degraded', tone: 'red' };
+  }
+  if (state.includes('error') || state.includes('fail')) {
+    return { label: 'Failed', tone: 'red' };
+  }
+  if (state.includes('exit') || state.includes('stop') || state.includes('dead')) {
+    return { label: 'Stopped', tone: 'gray' };
+  }
+  // Anjaan state - raw dikha do par clean
+  return { label: stateRaw || 'Unknown', tone: 'gray' };
+}
+
+// Pure label mapper (bug #3) - raw "state:health" (e.g. "running:unknown") ko kabhi user ko
+// NAHI dikhate; hamesha saaf label. classify() pe delegate karta hai (single source of truth),
+// sirf string label deta hai. Regression test isi ko pin karta hai.
+export function statusLabel(status, deploymentStatus) {
+  return classify(status, deploymentStatus).label;
+}
+
+// ---------------------------------------------------------------------------------------------
+// END OF THE PINNED REGION. Everything below is CLI-only and has no counterpart in the SPA - the
+// parity test extracts the two functions above by name, so additions here never affect it.
+// ---------------------------------------------------------------------------------------------
+
+// Verdict -> process exit code. This is the CLI's published contract (README "Exit codes") and it
+// lives here, next to the vocabulary it reads, so no command file ever compares a verdict token
+// itself.
+//
+// The input is ALWAYS the honest `verdict` field, NEVER the raw build `status` (bug #24: `status`
+// stays the raw build state - 'live' there means "the image built and the start job returned", which
+// is exactly the lie the verdict field was added to stop telling).
+//
+//   done:true  -> stop waiting, exit with `code`
+//   done:false -> the deploy has not resolved yet; keep polling
+//
+// A verdict we do not recognise is treated as unresolved rather than as success. The failure mode
+// then is "we waited and timed out", which is honest, instead of "we called an unknown state a
+// green deploy".
+// One word per TONE, for a line that counts services by state (the session header). It lives here
+// because this is the only file allowed to hold status vocabulary - a second list elsewhere is how
+// two screens end up calling the same state two things.
+export const TONE_WORDS = { green: 'running', gray: 'idle', amber: 'changing', red: 'failed' };
+
+// What each `verdict` means, for a PROGRAM reading `status --json` or `services --json`. A raw
+// container status can read like a crash for a service that is merely asleep - the verdict is the
+// field that was built to be believed (bug #24), and `voroa agent` prints this table.
+export const VERDICT_MEANINGS = {
+  live: 'Running and serving.',
+  sleeping: 'Idle and asleep. NOT broken - it wakes on the next request.',
+  building: 'A deploy is in progress.',
+  starting: 'Built; waiting for the service to come up.',
+  failed: 'The build failed. Read the build log.',
+  failed_to_start: 'Built, but the service did not come up. Read the logs.',
+  suspended: 'Stopped by Voroa after repeated crashes. A person must start it.',
+  paused_free_hours: 'Paused: the free hours for this month are used.',
+  waiting_for_addon: 'Waiting for its database to be created.',
+  unknown: 'Could not be determined. Not a failure; check again.',
+};
+
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_TIMEOUT = 2;
+
+// "Is there more build log coming?" This reads the RAW build status on purpose, and only for that
+// one question - the build stream ends when the build ends, which is exactly what the raw field
+// describes. It is never turned into a state shown to a user; `classify` and `verdictOutcome` own
+// that, and the difference is the whole point of bug #24.
+// isBuildRunning - the OTHER half of isBuildFinished, and deliberately not its negation. `!isBuildFinished`
+// is TRUE for a null status, which is the "we could not read it" answer - a caller that follows on that
+// waits out its own deadline instead of saying the honest thing. Callers that must keep following a live
+// build (the build-log follow loop) need "we KNOW it is running", which is only this.
+export function isBuildRunning(buildStatus) {
+  return buildStatus === 'building';
+}
+
+export function isBuildFinished(buildStatus) {
+  return buildStatus != null && buildStatus !== 'building';
+}
+
+export function verdictOutcome(verdict) {
+  if (verdict === 'live') return { done: true, code: EXIT_OK, message: 'Live.' };
+  if (verdict === 'failed_to_start') {
+    return { done: true, code: EXIT_FAILED, message: 'The build finished but the service did not start.' };
+  }
+  if (verdict === 'failed') return { done: true, code: EXIT_FAILED, message: 'The build failed.' };
+  // UNKNOWN IS TERMINAL, and that is the whole point of handling it here. The fallback below is
+  // `{done:false}`, so without this line `--wait` would poll forever on a deploy we can never judge - and
+  // that is not a corner case: a long build plus a wait crosses the verdict window routinely.
+  // EXIT_OK, not EXIT_FAILED: the same aged-out deploy exits 0 today, and failing a customer's pipeline
+  // over OUR missing evidence would turn our gap into their red build. The message must not reuse "Live."
+  // - saying nothing happened is exactly the claim we cannot make.
+  if (verdict === 'unknown') {
+    return { done: true, code: EXIT_OK, message: 'Deploy finished. We could not confirm the service came up.' };
+  }
+  return { done: false, code: null, message: null };
+}

package/src/stepup.js

@@ -0,0 +1,69 @@
+// "Confirm it is you" from a terminal.
+//
+// A few routes (revealing a database password, minting an API token) need a FRESH proof of identity
+// on the session - ten minutes old at most - on top of being signed in. The server answers
+// 403 { code: 'step_up_required' } when it is missing. We react to exactly that answer, ask for the
+// proof, and retry the call ONCE. We never ask up front: the server decides what needs it, and a
+// prompt the server did not ask for teaches people to type secrets on reflex.
+//
+// What can be used here, in the server's own order (services/mfa.js verifyForStepUp):
+//   * 2FA on  -> an authenticator code, or a recovery code with --recovery. A passkey cannot be used
+//                from a terminal - the dashboard is the answer for a passkey-only account.
+//   * 2FA off -> the password, or an emailed code for an account without one.
+// None of these is ever echoed, and none is kept after the call.
+import { ApiError, isApiToken, securityState, reauth, reauthEmailCode } from './api.js';
+import { askHidden } from './prompt.js';
+import { err } from './output.js';
+import { CliError } from './errors.js';
+
+const PROMPT_MS = 5 * 60_000;
+
+function isStepUpRequired(e) {
+  return e instanceof ApiError && e.httpStatus === 403 && e.code === 'step_up_required';
+}
+
+async function confirmIdentity(ctx, { recovery = false } = {}) {
+  const state = await securityState(ctx);
+  const mfa = (state && state.mfa) || {};
+  // stderr: stdout may be JSON or a URL a script is capturing.
+  err('Please confirm it is you to continue.');
+
+  let body;
+  if (mfa.enabled) {
+    if (recovery) {
+      body = { method: 'recovery', code: await askHidden('Recovery code: ', { timeoutMs: PROMPT_MS }) };
+    } else if (mfa.totp && mfa.totp.confirmed) {
+      body = { method: 'totp', code: await askHidden('Authenticator code: ', { timeoutMs: PROMPT_MS }) };
+    } else {
+      throw new CliError('Your account confirms with a passkey, which cannot be used from a terminal. Use --recovery with a recovery code, or do this in the dashboard.');
+    }
+  } else if (mfa.hasPassword) {
+    body = { method: 'password', password: await askHidden('Password: ', { timeoutMs: PROMPT_MS }) };
+  } else {
+    await reauthEmailCode(ctx);
+    err('We have emailed you a 6-digit code.');
+    body = { method: 'email_code', code: await askHidden('Code: ', { timeoutMs: PROMPT_MS }) };
+  }
+  if (!body.code && !body.password) throw new CliError('Nothing was entered - stopped.');
+  await reauth(ctx, body);
+}
+
+export async function withStepUp(ctx, fn, { recovery = false } = {}) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (!isStepUpRequired(e)) throw e;
+    // A token has no session to step up on. The server refuses these routes to a token anyway; this
+    // just says it in words.
+    if (isApiToken(ctx.token)) throw new CliError('This needs a signed-in session, not an API token. Run `voroa login`.');
+    await confirmIdentity(ctx, { recovery });
+    try {
+      return await fn();
+    } catch (again) {
+      // Retried exactly once. A second demand means the confirmation did not stick - say that, not the
+      // generic "you do not have access", which would read as a permissions problem.
+      if (isStepUpRequired(again)) throw new CliError('The confirmation did not go through. Please try again.');
+      throw again;
+    }
+  }
+}