quoxcli 0.0.0-stage → 0.2.0

package/lib/core/systemdInstaller.js

@@ -0,0 +1,256 @@
+/**
+ * Systemd USER unit installer for the resident supervisor, Option A
+ * persistence (DEVSUITE-DEVMODE follow-on, quox#453 phase 15 follow-on).
+ *
+ * A resident's `quox dev supervisor run` proved out one-shot passes; this
+ * module is the delivery half: a `Restart=always` systemd --user unit so the
+ * runner answers its slot channel with no session open and comes back after
+ * a crash, a logout, or a reboot (the last of those needs `loginctl
+ * enable-linger`, see installSupervisorService below).
+ *
+ * GOVERNANCE NOTE: installing this unit is deliberately NOT the autonomy
+ * grant. The unit only ever answers a message when the human-gated
+ * server-side switch (`quox dev supervisor enable`, requireHumanAdmin on the
+ * collector) is on, see supervisorEngine.js's kill-switch check in
+ * runPollOnce. A resident may install its own service on its own host (the
+ * scoped self-service pattern), while a human still decides whether it may
+ * act. Installing the unit and being allowed to act are two different
+ * switches on purpose.
+ *
+ * Every systemctl/loginctl call goes through one injectable `execFn` seam
+ * (see realExecFn below) so this is fully testable without touching the
+ * real system: tests pass a fake execFn and never spawn systemctl.
+ */
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+export const SERVICE_NAME = 'quox-resident-supervisor.service';
+export const DEFAULT_RESTART_SEC = 10;
+
+// Item 2 (found by the acceptance owner driving this on a real host,
+// 2026-08-23): `systemctl --user enable --now` reporting success only
+// proves systemd ACCEPTED the unit, not that it stayed up. A unit whose
+// ExecStart dies immediately (the item 1 slot bug is exactly this) is
+// already crash-looping under Restart=always by the time enable returns.
+// Give it a few seconds, then read the live state back through the same
+// injectable execFn seam before calling install a success.
+export const DEFAULT_VERIFY_DELAY_MS = 3000;
+
+export function defaultUnitDir() {
+  return join(homedir(), '.config', 'systemd', 'user');
+}
+
+export function defaultUnitPath() {
+  return join(defaultUnitDir(), SERVICE_NAME);
+}
+
+/**
+ * Build the unit file content. Pure string building, no I/O, so it is
+ * trivially snapshot-testable.
+ *
+ * `env`: extra `Environment=KEY=VALUE` lines, baked in at install time
+ * (item 1, live outage 2026-08-23). A systemd unit inherits none of the
+ * caller's shell environment, so this is how a resident's reach-back URLs
+ * (QUOX_URL/QUOX_AUTH_URL/QUOX_COLLECTOR_URL/QUOX_INSECURE) survive into a
+ * unit that runs with no login shell present. A value containing a newline
+ * or a quote would break the unit file's own line-based format, or the
+ * shell-like word-splitting systemd applies to `Environment=`, so it is
+ * refused outright rather than escaped: an unrenderable value is a defect
+ * in the caller, not something this function should paper over.
+ */
+export function buildUnitFile({ quoxBin, extraArgs = [], restartSec = DEFAULT_RESTART_SEC, home = homedir(), env = {} } = {}) {
+  const bin = quoxBin || 'quox';
+  const argsSuffix = extraArgs.length ? ` ${extraArgs.join(' ')}` : '';
+  const envLines = Object.entries(env || {}).map(([key, value]) => {
+    const v = String(value);
+    if (/[\n"']/.test(v)) {
+      throw new Error(
+        `buildUnitFile: refusing to bake ${key} into the unit: its value contains a newline or a quote character `
+        + `(value withheld from this message). Fix the source value rather than escaping it.`
+      );
+    }
+    return `Environment=${key}=${v}`;
+  });
+  return [
+    '[Unit]',
+    'Description=Quox resident supervisor (answers the slot channel headlessly, no session open)',
+    'After=network-online.target',
+    'Wants=network-online.target',
+    '',
+    '[Service]',
+    'Type=simple',
+    `ExecStart=${bin} dev supervisor run --service${argsSuffix}`,
+    'Restart=always',
+    `RestartSec=${restartSec}`,
+    `Environment=HOME=${home}`,
+    ...envLines,
+    '',
+    '[Install]',
+    'WantedBy=default.target',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Real systemctl/loginctl runner (the non-test default). Never throws for a
+ * nonzero exit: callers read `.ok`/`.stderr`, so a failed `enable-linger`
+ * (e.g. no permission) is data, not a crash.
+ */
+export async function realExecFn(cmd, args) {
+  return execFileAsync(cmd, args, { timeout: 15000 });
+}
+
+/** Parses `systemctl --user show <unit> -p A,B,C` stdout ("KEY=value" per line) into an object. */
+function parseSystemctlShow(stdout) {
+  const props = {};
+  for (const line of String(stdout || '').split('\n')) {
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    props[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  }
+  return props;
+}
+
+async function runExec(execFn, cmd, args) {
+  try {
+    const res = await execFn(cmd, args);
+    return { ok: true, code: 0, stdout: (res && res.stdout) || '', stderr: (res && res.stderr) || '' };
+  } catch (err) {
+    return {
+      ok: false,
+      code: err && err.code != null ? err.code : 1,
+      stdout: (err && err.stdout) || '',
+      stderr: (err && (err.stderr || err.message)) || String(err),
+    };
+  }
+}
+
+/**
+ * Write the unit, reload the daemon, enable + start it now, and attempt
+ * linger. Every step's outcome is reported back rather than thrown, because
+ * a partial success (unit written, enabled, but linger refused) is the
+ * single most important case this reports honestly: the service DOES start
+ * now, but will not survive a reboot or logout until linger is granted.
+ */
+export async function installSupervisorService({
+  execFn,
+  writeFileFn,
+  mkdirFn,
+  unitPath = defaultUnitPath(),
+  unitDir = defaultUnitDir(),
+  unitContent,
+  user,
+  // Injectable so tests never wait the real delay. Defaults to a real sleep
+  // outside tests, same seam discipline as execFn/writeFileFn/mkdirFn.
+  sleepFn = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  verifyDelayMs = DEFAULT_VERIFY_DELAY_MS,
+}) {
+  mkdirFn(unitDir, { recursive: true });
+  writeFileFn(unitPath, unitContent);
+
+  const reload = await runExec(execFn, 'systemctl', ['--user', 'daemon-reload']);
+  const enable = await runExec(execFn, 'systemctl', ['--user', 'enable', '--now', SERVICE_NAME]);
+  const linger = await runExec(execFn, 'loginctl', ['enable-linger', user]);
+
+  // Item 2: post-start verification. Only meaningful once `enable --now`
+  // itself reported success — if enable failed outright there is nothing
+  // running to crash-loop, and the enable_error above already says so.
+  let verified = false;
+  let active = false;
+  let restartCount = null;
+  let crashLoop = false;
+  let crashJournal = null;
+  if (enable.ok) {
+    await sleepFn(verifyDelayMs);
+    const show = await runExec(execFn, 'systemctl', ['--user', 'show', SERVICE_NAME, '-p', 'NRestarts,ActiveState,SubState']);
+    verified = true;
+    if (show.ok) {
+      const props = parseSystemctlShow(show.stdout);
+      active = props.ActiveState === 'active';
+      const n = Number(props.NRestarts);
+      restartCount = Number.isFinite(n) ? n : null;
+      // Restart=always means one crash silently reads as "started fine"
+      // unless something checks back: any restart already counted, or a
+      // state that isn't active, in our short observation window is a
+      // crash loop, not a success, however cheerfully `enable --now` read.
+      crashLoop = !active || (restartCount != null && restartCount > 0);
+    } else {
+      // Could not read the live state back at all: never claim success on
+      // silence — same "an error body is not data" discipline as the rest
+      // of this codebase's proof-before-claim rule.
+      crashLoop = true;
+    }
+    if (crashLoop) {
+      const journal = await runExec(execFn, 'journalctl', ['--user', '-u', SERVICE_NAME, '-n', '20', '--no-pager']);
+      crashJournal = journal.ok ? journal.stdout : null;
+    }
+  }
+
+  return {
+    unit_path: unitPath,
+    daemon_reloaded: reload.ok,
+    daemon_reload_error: reload.ok ? null : (reload.stderr || `exit ${reload.code}`),
+    enabled: enable.ok,
+    enable_error: enable.ok ? null : (enable.stderr || `exit ${enable.code}`),
+    linger_enabled: linger.ok,
+    linger_error: linger.ok ? null : (linger.stderr || `exit ${linger.code}`),
+    verified,
+    active,
+    restart_count: restartCount,
+    crash_loop: crashLoop,
+    crash_journal: crashJournal,
+  };
+}
+
+export async function uninstallSupervisorService({
+  execFn,
+  existsFn,
+  unlinkFn,
+  unitPath = defaultUnitPath(),
+}) {
+  const disable = await runExec(execFn, 'systemctl', ['--user', 'disable', '--now', SERVICE_NAME]);
+
+  let removed = false;
+  if (existsFn(unitPath)) {
+    unlinkFn(unitPath);
+    removed = true;
+  }
+
+  const reload = await runExec(execFn, 'systemctl', ['--user', 'daemon-reload']);
+
+  return {
+    disabled: disable.ok,
+    disable_error: disable.ok ? null : (disable.stderr || `exit ${disable.code}`),
+    unit_removed: removed,
+    daemon_reloaded: reload.ok,
+  };
+}
+
+/**
+ * Read-only install/enable/active/linger report for `quox dev supervisor
+ * status`. Never throws: an unreadable systemctl/loginctl reports as
+ * false/unknown rather than crashing a status check.
+ */
+export async function getServiceInstallStatus({
+  execFn,
+  existsFn,
+  unitPath = defaultUnitPath(),
+  user,
+}) {
+  const installed = existsFn(unitPath);
+  const enabledRes = await runExec(execFn, 'systemctl', ['--user', 'is-enabled', SERVICE_NAME]);
+  const activeRes = await runExec(execFn, 'systemctl', ['--user', 'is-active', SERVICE_NAME]);
+  const lingerRes = await runExec(execFn, 'loginctl', ['show-user', user, '--property=Linger', '--value']);
+
+  return {
+    installed,
+    enabled: enabledRes.stdout.trim() === 'enabled',
+    active: activeRes.stdout.trim() === 'active',
+    linger: lingerRes.stdout.trim().toLowerCase() === 'yes',
+  };
+}

package/lib/core/version.js

@@ -0,0 +1,87 @@
+/**
+ * CLI version + drift resolution — shared so `quox --version` (bin/quox.js)
+ * and `quox doctor` (commands/doctor.js) report the SAME facts and can never
+ * disagree about which build is running. Closes quoxai/quox#610.
+ *
+ * Every git call is fully guarded (stderr discarded, failure swallowed) so
+ * version/drift resolution can never break a command: a plain-package install
+ * with no .git, a missing git binary, or a detached worktree all degrade to a
+ * sensible fallback rather than throwing.
+ *
+ * Note on cost: bin/quox.js keeps its argv guard at the CALL SITE (it only
+ * calls resolveCliVersion() when --version/-V is actually present) so normal
+ * commands stay zero-cost. doctor calls both freely — the user explicitly ran
+ * a diagnostic, so spawning git is expected there.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+export const BASE_VERSION = '0.2.0';
+
+// The CLI source root (…/cli). version.js lives at cli/lib/core/, so two
+// levels up is the tree whose HEAD identifies the running build.
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function git(args) {
+  return execFileSync('git', ['-C', CLI_ROOT, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  }).trim();
+}
+
+/**
+ * Human version string: "0.1.0 (7bac4f67, session/vulcan)" — or bare
+ * "0.1.0" when git facts are unavailable. Unlike the drift check this never
+ * needs origin/main, so it works on a shallow or rem-less clone.
+ */
+export function resolveCliVersion() {
+  try {
+    const sha = git(['rev-parse', '--short', 'HEAD']);
+    if (!sha) return BASE_VERSION;
+    let ref = '';
+    try { ref = git(['rev-parse', '--abbrev-ref', 'HEAD']); } catch { /* detached HEAD / no ref */ }
+    const label = ref && ref !== 'HEAD' ? ref : 'detached';
+    return `${BASE_VERSION} (${sha}, ${label})`;
+  } catch {
+    return BASE_VERSION;
+  }
+}
+
+/**
+ * Drift of the running worktree vs the LAST-FETCHED origin/main.
+ *
+ * Deliberately does NOT fetch: a health check must not hang on a slow remote
+ * or block on credentials. The count therefore reflects the last fetch, which
+ * the detail line states plainly. This mirrors scripts/quox-cli-refresh.sh's
+ * `git rev-list --count HEAD..origin/main` so doctor and the refresh tool agree
+ * (#607 shipped the refresh side).
+ *
+ * @returns {{status:'ok'|'stale'|'unknown'|'skip', detail:string}}
+ *   ok      — HEAD == origin/main
+ *   stale   — behind origin/main; nudge quox-cli-refresh
+ *   unknown — no origin/main ref locally (never fetched here)
+ *   skip    — not a git worktree (plain-package install)
+ */
+export function checkCliDrift() {
+  let head;
+  try {
+    head = git(['rev-parse', 'HEAD']);
+  } catch {
+    return { status: 'skip', detail: 'not a git worktree' };
+  }
+  let remote;
+  try {
+    remote = git(['rev-parse', 'origin/main']);
+  } catch {
+    return { status: 'unknown', detail: 'no origin/main ref (never fetched here)' };
+  }
+  if (head === remote) return { status: 'ok', detail: 'up to date with origin/main' };
+  let behind = '?';
+  try { behind = git(['rev-list', '--count', 'HEAD..origin/main']); } catch { /* keep ? */ }
+  return {
+    status: 'stale',
+    detail: `${behind} commit(s) behind origin/main (run quox-cli-refresh) — reflects last fetch`,
+  };
+}

package/lib/core/websiteSession.js

@@ -0,0 +1,148 @@
+/**
+ * Website admin session for owner-only licence verbs (GRIPE-715 phase 2).
+ *
+ * `quox licence reissue` and `quox licence catalogue-sign` talk to the quox.ai
+ * WEBSITE admin API, not to this instance, so they need their own credential,
+ * separate from the instance profile in config.json.
+ *
+ * What is stored: per website profile, the base URL, the admin username and
+ * the website session cookie (`quox.sid`, 24h). The password is used once for
+ * POST /api/admin/login and never written anywhere. The file is 0600. Nothing
+ * here prints the cookie.
+ *
+ * File: ~/.config/quox/website-sessions.json (QUOX_WEBSITE_SESSION_FILE overrides,
+ * used by tests).
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { QuoxError, QuoxValidationError } from './errors.js';
+
+export const DEFAULT_WEBSITE_URL = 'https://quox.ai';
+export const DEFAULT_WEBSITE_PROFILE = 'default';
+const SESSION_COOKIE = 'quox.sid';
+
+export function sessionFilePath() {
+  return process.env.QUOX_WEBSITE_SESSION_FILE || join(homedir(), '.config', 'quox', 'website-sessions.json');
+}
+
+function readStore(file = sessionFilePath()) {
+  if (!existsSync(file)) return { profiles: {} };
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    return parsed && typeof parsed.profiles === 'object' ? parsed : { profiles: {} };
+  } catch {
+    return { profiles: {} };
+  }
+}
+
+function writeStore(store, file = sessionFilePath()) {
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(store, null, 2), { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+}
+
+export function normaliseWebsiteUrl(url) {
+  let u;
+  try { u = new URL(url); } catch { throw new QuoxValidationError(`Invalid website URL: ${url}`); }
+  const local = u.hostname === 'localhost' || u.hostname === '127.0.0.1';
+  if (u.protocol !== 'https:' && !local) {
+    throw new QuoxValidationError('The website URL must be https (the session cookie is a credential); http is allowed only for localhost');
+  }
+  return `${u.protocol}//${u.host}`;
+}
+
+export function getWebsiteSession(profile = DEFAULT_WEBSITE_PROFILE) {
+  return readStore().profiles[profile] || null;
+}
+
+export function saveWebsiteSession(profile, session) {
+  const store = readStore();
+  store.profiles[profile] = session;
+  writeStore(store);
+}
+
+export function clearWebsiteSession(profile) {
+  const store = readStore();
+  const had = !!store.profiles[profile];
+  delete store.profiles[profile];
+  writeStore(store);
+  return had;
+}
+
+/** Pull `quox.sid=<value>` out of the Set-Cookie header(s). */
+export function extractSessionCookie(headers) {
+  const list = typeof headers.getSetCookie === 'function'
+    ? headers.getSetCookie()
+    : [headers.get('set-cookie')].filter(Boolean);
+  for (const line of list) {
+    for (const part of String(line).split(/,(?=\s*[^;,=\s]+=)/)) {
+      const pair = part.trim().split(';')[0];
+      if (pair.startsWith(`${SESSION_COOKIE}=`)) return pair;
+    }
+  }
+  return null;
+}
+
+async function readJson(res) {
+  const text = await res.text();
+  try { return text ? JSON.parse(text) : {}; } catch { return { error: text.slice(0, 200) }; }
+}
+
+/** Log in to the website admin API. Returns the session to save; never the password. */
+export async function websiteLogin({ url, username, password, fetchImpl = globalThis.fetch }) {
+  const base = normaliseWebsiteUrl(url);
+  const res = await fetchImpl(`${base}/api/admin/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({ username, password }),
+    redirect: 'manual',
+  });
+  const body = await readJson(res);
+  if (!res.ok) throw new QuoxError(`Website login failed (HTTP ${res.status}): ${body.error || 'no detail'}`, 3);
+  const cookie = extractSessionCookie(res.headers);
+  if (!cookie) throw new QuoxError('Website login returned no session cookie; nothing saved', 3);
+  return {
+    url: base,
+    username: body.username || username,
+    cookie,
+    must_change_password: !!body.mustChangePassword,
+    saved_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * POST to a website admin route with the saved session. Checks the status
+ * before trusting the body; a 401 means the 24h session lapsed.
+ */
+export async function websitePost(profile, path, body, { fetchImpl = globalThis.fetch } = {}) {
+  const session = getWebsiteSession(profile);
+  if (!session?.cookie) {
+    throw new QuoxError(`No website session for profile "${profile}". Run: quox licence website-login${profile === DEFAULT_WEBSITE_PROFILE ? '' : ` --website-profile ${profile}`}`, 3);
+  }
+  let res;
+  try {
+    res = await fetchImpl(`${session.url}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json', Cookie: session.cookie },
+      body: JSON.stringify(body || {}),
+      redirect: 'manual',
+    });
+  } catch (err) {
+    throw new QuoxError(`Could not reach the website admin API at ${session.url}: ${err.message}`, 7);
+  }
+  const data = await readJson(res);
+  if (res.status === 401) {
+    throw new QuoxError(`Website session expired or invalid (HTTP 401 from ${session.url}). Run: quox licence website-login`, 3);
+  }
+  if (!res.ok) {
+    const err = new QuoxError(`Website API ${path} failed (HTTP ${res.status}${data.code ? ` ${data.code}` : ''}): ${data.error || 'no detail'}`, res.status === 403 ? 4 : 1);
+    err.status = res.status;
+    err.body = data;
+    throw err;
+  }
+  return data;
+}

package/lib/lucid/LucidIntro.jsx

@@ -0,0 +1,105 @@
+/**
+ * LucidIntro: the ~1.2s startup for `quox lucid deck`.
+ *
+ * Frames (50ms): the QUOX block wordmark is revealed by a gradient sweep, the
+ * ◉ LUCID mark fades in under it, then "tuning in…" resolves into
+ * "◉ LUCID │ N sources live · M need you" once the first fetch has landed.
+ * The fetch is owned by the deck and runs in parallel, never gated on this.
+ * onDone fires once: at the natural end, on a hard 2.5s cap, or on a key
+ * (the deck calls skip via the `skipSignal` prop).
+ */
+import React, { useState, useEffect, useRef } from 'react';
+import { Box, Text } from 'ink';
+import chalk from 'chalk';
+import { BLOCK_FONT, gradientColor } from '../tui/intro/Intro.jsx';
+import { PALETTE, STATE_HEX } from './fmt.js';
+
+export const FRAME_MS = 50;
+const SWEEP_FRAMES = 12;
+const MIN_FRAMES = 24;   // 1.2s
+const MAX_FRAMES = 50;   // 2.5s cap if the fetch never lands
+
+const LETTERS = ['Q', 'U', 'O', 'X'];
+const rgb = (c, s) => chalk.rgb(c[0], c[1], c[2])(s);
+
+function titleRow(row, frame, colsRevealed) {
+  let out = ''; let col = 0;
+  const total = LETTERS.reduce((n, ch) => n + BLOCK_FONT[ch][0].length + 1, 0);
+  for (const ch of LETTERS) {
+    const g = BLOCK_FONT[ch][row];
+    for (let i = 0; i < g.length; i++) {
+      const x = col + i;
+      const lit = g[i] !== ' ';
+      if (x > colsRevealed) { out += '  '; continue; }
+      if (!lit) { out += '  '; continue; }
+      const edge = colsRevealed - x < 2 && colsRevealed < total;
+      out += edge ? chalk.white('██') : rgb(gradientColor(x / total + frame * 0.02), '██');
+    }
+    out += '  ';
+    col += g.length + 1;
+  }
+  return out;
+}
+
+export function LucidIntro({ data, err, onDone, rows = 24 }) {
+  const [frame, setFrame] = useState(0);
+  const doneRef = useRef(false);
+  const readyAt = useRef(null);
+  const sit = data && data.situation;
+
+  if (sit && readyAt.current == null) readyAt.current = frame;
+
+  useEffect(() => {
+    const id = setInterval(() => setFrame((f) => f + 1), FRAME_MS);
+    return () => clearInterval(id);
+  }, []);
+
+  const finishAt = readyAt.current != null
+    ? Math.max(MIN_FRAMES, readyAt.current + 6)
+    : (err ? Math.max(MIN_FRAMES, 16) : MAX_FRAMES);
+
+  useEffect(() => {
+    if (frame >= finishAt && !doneRef.current) { doneRef.current = true; onDone(); }
+  }, [frame, finishAt, onDone]);
+
+  const tall = rows >= 16;
+  const total = LETTERS.reduce((n, ch) => n + BLOCK_FONT[ch][0].length + 1, 0);
+  const revealed = Math.round((Math.min(frame, SWEEP_FRAMES) / SWEEP_FRAMES) * (total + 2)) - 1;
+  const markOn = frame >= 6;
+  const resolved = sit && frame >= 14 && frame >= (readyAt.current ?? 0) + 2;
+  const cov = (sit && sit.cannot_see && sit.cannot_see.coverage) || { live: 0, expected: 0 };
+  const dots = '.'.repeat((frame % 3) + 1).padEnd(3, ' ');
+
+  const mark = [...'◉ LUCID'].map((ch, i) => (
+    <Text key={i} bold color={'#' + gradientColor((i / 7) + frame * 0.03).map((v) => v.toString(16).padStart(2, '0')).join('')}>{ch}</Text>
+  ));
+
+  return (
+    <Box flexDirection="column" alignItems="center" justifyContent="center" flexGrow={1} paddingY={1}>
+      {tall ? (
+        <Box flexDirection="column" alignItems="center">
+          {Array.from({ length: 5 }, (_, r) => <Text key={r}>{titleRow(r, frame, revealed)}</Text>)}
+        </Box>
+      ) : (
+        <Text bold color={PALETTE.brand}>Q U O X</Text>
+      )}
+      <Box marginTop={1}>{markOn ? mark : <Text> </Text>}</Box>
+      <Box marginTop={1}>
+        {frame < 10 ? <Text> </Text> : resolved ? (
+          <Text>
+            <Text bold color={PALETTE.brand}>◉ LUCID</Text>
+            <Text color={PALETTE.dim}> │ </Text>
+            <Text color={STATE_HEX.ok}>{cov.live} sources live</Text>
+            <Text color={PALETTE.dim}> · </Text>
+            <Text bold color={(sit.needs_you || []).length ? STATE_HEX.attention : STATE_HEX.ok}>{(sit.needs_you || []).length} need you</Text>
+          </Text>
+        ) : err && !sit ? (
+          <Text color={STATE_HEX.blind}>LUCID unreachable, still trying</Text>
+        ) : (
+          <Text color={PALETTE.muted}>tuning in{dots}</Text>
+        )}
+      </Box>
+      <Box marginTop={1}><Text color={PALETTE.dim}>any key to skip</Text></Box>
+    </Box>
+  );
+}

package/lib/lucid/blind.js

@@ -0,0 +1,71 @@
+/**
+ * `quox lucid blind`: what LUCID can and cannot hear, and what does not add up.
+ * Pure: renderBlind({ situation, feeds, expected }, { now }) -> string (plain text, no colour,
+ * so it pastes anywhere and reads the same in a pipe).
+ *
+ * A source is live, silent (expected but quiet), failing (speaking, but its own read is
+ * failing) or never heard. Contradictions list both sides of each mismatch.
+ */
+
+function ago(ms, now) {
+  if (ms == null) return '';
+  const s = Math.max(0, Math.floor((now - ms) / 1000));
+  if (s < 60) return `${s}s ago`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  return `${Math.floor(h / 24)}d ago`;
+}
+
+const nameOf = (x) => (typeof x === 'string' ? x : (x && (x.feed || x.name)) || '');
+
+/** Rows: { source, state, last, note } sorted worst first. */
+export function blindRows({ situation, feeds = [], expected = [] } = {}, now = Date.now()) {
+  const cs = (situation && situation.cannot_see) || {};
+  const byFeed = new Map(feeds.map((f) => [f.feed, f]));
+  const failing = new Map((cs.failing || []).map((x) => [nameOf(x), x]));
+  const silent = new Set((cs.silent || []).map(nameOf));
+  const unwired = new Set((cs.unwired || []).map(nameOf));
+  const names = new Set([...byFeed.keys(), ...expected, ...failing.keys(), ...silent, ...unwired]);
+  const rows = [];
+  for (const source of names) {
+    if (!source) continue;
+    const f = byFeed.get(source);
+    const last = f && f.last_heard != null ? ago(f.last_heard, now) : '';
+    if (failing.has(source)) rows.push({ rank: 0, source, state: 'failing', last, note: (failing.get(source) || {}).error || (f && f.last_error) || '' });
+    else if (silent.has(source)) rows.push({ rank: 1, source, state: 'silent', last, note: 'expected, but gone quiet' });
+    else if (unwired.has(source) || !f) rows.push({ rank: 2, source, state: 'never heard', last: '', note: 'expected, has never reported' });
+    else rows.push({ rank: 3, source, state: 'live', last, note: '' });
+  }
+  return rows.sort((a, b) => a.rank - b.rank || a.source.localeCompare(b.source));
+}
+
+export function renderBlind(data = {}, { now = Date.now() } = {}) {
+  const sit = data.situation || {};
+  const cov = (sit.cannot_see && sit.cannot_see.coverage) || null;
+  const rows = blindRows(data, now);
+  const out = [];
+  out.push(`SOURCES${cov ? ` (${cov.live} of ${cov.expected} speaking)` : ''}`);
+  if (!rows.length) out.push('  I have not heard from any source yet. That is not "all quiet".');
+  else {
+    const w = Math.max(6, ...rows.map((r) => r.source.length));
+    out.push(`  ${'SOURCE'.padEnd(w)}  ${'STATE'.padEnd(11)}  ${'LAST HEARD'.padEnd(10)}  NOTE`);
+    for (const r of rows) out.push(`  ${r.source.padEnd(w)}  ${r.state.padEnd(11)}  ${r.last.padEnd(10)}  ${r.note}`.trimEnd());
+  }
+  const stale = (sit.cannot_see && sit.cannot_see.stale) || [];
+  if (stale.length) out.push('', `Stale claims (source quiet, so these may be out of date): ${stale.map((s) => nameOf({ name: s.subject })).join(', ')}`);
+
+  const da = sit.doesnt_add_up || [];
+  out.push('', `DOESN'T ADD UP${da.length ? ` (${da.length})` : ''}`);
+  if (!da.length) out.push('  Nothing I can see contradicts anything else. I can only compare what the sources tell me.');
+  da.forEach((x, i) => {
+    out.push(`  ${i + 1}. ${x.L0}${x.urgent ? '  [TODAY]' : ''}`);
+    out.push(`     Claimed   ${x.claimed}`);
+    out.push(`     Observed  ${x.observed}`);
+    if (x.sources && x.sources.length) out.push(`     Sources   ${x.sources.join(', ')}`);
+    if (x.why) out.push(`     Why       ${x.why}`);
+    if (x.how) out.push(`     Settle    ${x.how}`);
+  });
+  return `${out.join('\n')}\n`;
+}