quoxcli 0.2.0 → 0.4.0

package/lib/server/update.js

@@ -0,0 +1,234 @@
+/**
+ * C4: `quox server update` and `quox server rollback`.
+ *
+ * update:  preflight -> backup -> fetch -> build -> migrate -> health, with the state written after every
+ *          step (resumable: a re-run continues after the last completed step). A failure from fetch on
+ *          rolls back automatically: before `migrate` only the code moves back (data was never touched);
+ *          from `migrate` on, the full rollback restores the pre-update snapshot.
+ * rollback: previous snapshot + previous version: checkout, build, restore DB + config, start, health.
+ *
+ * Migrations run on service boot (each service applies its own on start), so `migrate` = `up -d`, and
+ * `health` proves they finished: every service answers and the collector's /version is the new commit.
+ */
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readInstalled, readEnvKeys, fetchAvailable, cmpSemver, parseSemver, vtag, compareUrl, releaseNotesUrl, PUBLIC_REPO, SIBLINGS } from './install.js';
+import { readState, writeState, appendHistory, compose, diskFree, runningVersion, probeHttp } from './status.js';
+import { createSnapshot, restoreSnapshot, latestSnapshot, listSnapshots } from './snapshot.js';
+import { gate } from './sys.js';
+
+export const UPDATE_STEPS = ['preflight', 'backup', 'fetch', 'build', 'migrate', 'health'];
+export const MIN_FREE_GB = 5;
+
+const sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+const lastLine = (s) => String(s || '').trim().split('\n').pop();
+
+/** Poll auth + collector /health, and (when known) the collector /version == expectCommit. */
+export async function waitHealthy({ urls, fetchImpl, expectCommit = null, tries = 40, intervalMs = 3000, sleep = sleepDefault, log = () => {} }) {
+  let last = '';
+  for (let i = 0; i < Math.max(1, tries); i++) {
+    const http = await probeHttp(urls, fetchImpl);
+    const bad = http.filter((h) => !h.ok);
+    if (!bad.length) {
+      if (!expectCommit) return { ok: true };
+      const v = await runningVersion(urls.collector, fetchImpl);
+      if (v.ok && v.commit && (String(v.commit).startsWith(expectCommit) || String(expectCommit).startsWith(v.commit))) return { ok: true, commit: v.commit };
+      last = v.ok ? `collector reports ${v.commit}, expected ${expectCommit}` : `collector /version: ${v.error}`;
+    } else last = bad.map((h) => `${h.name}: ${h.detail}`).join(', ');
+    log(`waiting for health: ${last}`);
+    if (i + 1 < tries) await sleep(intervalMs);
+  }
+  return { ok: false, error: last || 'not healthy' };
+}
+
+async function checkoutCode({ install, g, ref, siblings = {}, pullSiblings = false, log }) {
+  const r = await g.mut('git', ['-C', install.repoDir, 'checkout', '--detach', ref]);
+  if (r.code !== 0) return { ok: false, error: `git checkout ${ref} failed: ${lastLine(r.stderr)}` };
+  for (const s of SIBLINGS) {
+    const d = join(install.root, s);
+    if (!existsSync(join(d, '.git'))) continue;
+    const sr = pullSiblings ? await g.mut('git', ['-C', d, 'pull', '--ff-only'])
+      : siblings[s] ? await g.mut('git', ['-C', d, 'checkout', '--detach', siblings[s]]) : { code: 0 };
+    if (sr.code !== 0) log(`warning: ${s} did not move (${lastLine(sr.stderr) || `exit ${sr.code}`}); it stays where it was`);
+  }
+  return { ok: true };
+}
+
+async function composeBuild({ install, g, commit }) {
+  const gid = readEnvKeys(install.repoDir, ['DOCKER_GID']).DOCKER_GID;
+  const r = await g.mut('docker', compose(install, ['build']), { cwd: install.repoDir, env: { QUOXCORE_VERSION: commit, ...(gid ? { DOCKER_GID: gid } : {}) } });
+  return r.code === 0 ? { ok: true } : { ok: false, error: `docker compose build failed (exit ${r.code}): ${lastLine(r.stderr)}` };
+}
+
+async function composeUp({ install, g }) {
+  const r = await g.mut('docker', compose(install, ['up', '-d', '--remove-orphans']), { cwd: install.repoDir });
+  return r.code === 0 ? { ok: true } : { ok: false, error: `docker compose up -d failed (exit ${r.code}): ${lastLine(r.stderr)}` };
+}
+
+/**
+ * Plan + run an update. opts: { install, sys, backups, urls, fetchImpl, dryRun, to, force, restart, noRollback,
+ * log, now, healthTries, healthIntervalMs, sleep, repo }
+ * -> { ok, upToDate?, dryRun?, plan, planned?, failedStep?, error?, rolledBack?, rollback? }
+ */
+export async function runUpdate(opts) {
+  const { install, sys, backups, urls, fetchImpl = globalThis.fetch, dryRun = false, force = false, restart = false, noRollback = false,
+    log = () => {}, now = () => new Date(), healthTries = 40, healthIntervalMs = 3000, sleep = sleepDefault, repo = PUBLIC_REPO } = opts;
+  const g = gate(sys, { dryRun, log });
+
+  // ---- preflight (read-only) ----------------------------------------------------------------------
+  const installed = await readInstalled(install, sys);
+  let target = opts.to ? vtag(opts.to) : null;
+  if (!target) {
+    const av = await fetchAvailable({ fetchImpl, repo });
+    if (!av.ok) return { ok: false, failedStep: 'preflight', error: `could not read the available versions: ${av.error}` };
+    target = av.latest;
+  } else if (!parseSemver(target)) return { ok: false, failedStep: 'preflight', error: `--to ${opts.to} is not a version like 4.3.0` };
+  const current = installed.release ? vtag(installed.release) : null;
+  const plan = {
+    current, currentCommit: installed.commit, target,
+    changes: current ? compareUrl(current, target, repo) : null, releaseNotes: releaseNotesUrl(target, repo),
+    backups, steps: UPDATE_STEPS
+  };
+  const cmp = current ? cmpSemver(target, current) : 1;
+  if (cmp !== null && cmp <= 0 && !force) return { ok: true, upToDate: true, plan };
+
+  const problems = [];
+  const forceable = [];
+  if (installed.dirty) forceable.push(`the checkout at ${install.repoDir} has local changes (git status); commit or discard them, or pass --force`);
+  if (installed.dirty === null) problems.push(`${install.repoDir} is not a git checkout, so it cannot be moved to ${target}`);
+  const disk = await diskFree(install.root, sys);
+  if (disk.ok && disk.freeGB < MIN_FREE_GB) forceable.push(`only ${disk.freeGB} GB free at ${install.root}; an update needs at least ${MIN_FREE_GB} GB (backup + images)`);
+  const dv = await sys.run('docker', ['compose', 'version', '--short']);
+  if (dv.code !== 0) problems.push('docker compose is not available to this user');
+  plan.problems = [...problems, ...forceable];
+  if (problems.length || (forceable.length && !force)) return { ok: false, failedStep: 'preflight', error: plan.problems.join('; '), plan };
+
+  // ---- resume -------------------------------------------------------------------------------------
+  const prev = readState(backups);
+  let state = null;
+  if (prev && prev.op === 'update' && prev.status === 'running') {
+    if (prev.target !== target && !restart) {
+      return { ok: false, failedStep: 'preflight', error: `an update to ${prev.target} stopped after ${prev.done.slice(-1)[0] || 'preflight'}. Re-run without --to to resume it, or pass --restart to abandon it.`, plan };
+    }
+    if (prev.target === target) {
+      state = prev;
+      plan.resumedAfter = state.done.slice(-1)[0] || 'preflight';
+      log(`resuming the update to ${target} after ${plan.resumedAfter}`);
+    }
+  }
+  if (!state) state = { op: 'update', status: 'running', target, from: { release: installed.release, commit: installed.commit, siblings: installed.siblings }, done: ['preflight'], snapshot: null, startedAt: now().toISOString() };
+  const save = () => { if (!dryRun) writeState(backups, { ...state, updatedAt: now().toISOString() }); };
+  const mark = (s) => { if (!state.done.includes(s)) state.done.push(s); save(); };
+  const doneStep = (s) => state.done.includes(s);
+  const finish = (status, extra = {}) => {
+    state.status = status; save();
+    if (!dryRun) appendHistory(backups, { op: 'update', status, at: now().toISOString(), from: state.from.release || state.from.commit, to: target, snapshot: state.snapshot, ...extra });
+  };
+  save();
+
+  const fail = async (step, error) => {
+    log(`✖ ${step}: ${error}`);
+    if (noRollback || dryRun) { finish('failed', { failedStep: step, error }); return { ok: false, failedStep: step, error, plan, rolledBack: false }; }
+    log('rolling back automatically');
+    let rb;
+    if (['fetch', 'build'].includes(step)) {
+      const c = await checkoutCode({ install, g, ref: state.from.commit, siblings: state.from.siblings, log });
+      const h = c.ok ? await waitHealthy({ urls, fetchImpl, tries: healthTries, intervalMs: healthIntervalMs, sleep, log }) : c;
+      rb = { ok: c.ok && h.ok, scope: 'code only (data was never touched)', error: c.ok ? h.error : c.error };
+    } else {
+      rb = await runRollback({ ...opts, snapshotDir: state.snapshot, fromUpdate: true });
+      rb.scope = 'code + data from the pre-update snapshot';
+    }
+    finish(rb.ok ? 'rolled-back' : 'rollback-failed', { failedStep: step, error });
+    return { ok: false, failedStep: step, error, plan, rolledBack: rb.ok, rollback: rb };
+  };
+
+  // ---- backup -------------------------------------------------------------------------------------
+  if (!doneStep('backup')) {
+    const snap = await createSnapshot({ install, installed, backups, g, reason: `before update to ${target}`, now, log });
+    if (!snap.ok) {
+      finish('failed', { failedStep: 'backup', error: snap.error });
+      return { ok: false, failedStep: 'backup', error: `${snap.error}. Nothing was changed.`, plan, rolledBack: false };
+    }
+    state.snapshot = snap.dir; mark('backup');
+  }
+  plan.snapshot = state.snapshot;
+
+  // ---- fetch --------------------------------------------------------------------------------------
+  if (!doneStep('fetch')) {
+    const tagRef = `refs/tags/${target}`;
+    const has = await g.ro('git', ['-C', install.repoDir, 'rev-parse', '-q', '--verify', tagRef]);
+    if (has.code !== 0) {
+      const f1 = await g.mut('git', ['-C', install.repoDir, 'fetch', '--tags', 'origin']);
+      const again = dryRun ? { code: 1 } : await g.ro('git', ['-C', install.repoDir, 'rev-parse', '-q', '--verify', tagRef]);
+      if (f1.code !== 0 || again.code !== 0) {
+        const f2 = await g.mut('git', ['-C', install.repoDir, 'fetch', `https://github.com/${repo}.git`, `+${tagRef}:${tagRef}`]);
+        if (f2.code !== 0) return fail('fetch', `could not fetch ${target} from origin or ${repo}`);
+      }
+    }
+    const c = await checkoutCode({ install, g, ref: target, pullSiblings: true, log });
+    if (!c.ok) return fail('fetch', c.error);
+    mark('fetch');
+  }
+
+  // ---- build --------------------------------------------------------------------------------------
+  const rc = await g.ro('git', ['-C', install.repoDir, 'rev-parse', '--short', `${target}^{commit}`]);
+  const newCommit = rc.code === 0 && rc.stdout.trim() ? rc.stdout.trim() : null;
+  plan.targetCommit = newCommit;
+  if (!doneStep('build')) {
+    const b = await composeBuild({ install, g, commit: newCommit || target });
+    if (!b.ok) return fail('build', b.error);
+    mark('build');
+  }
+
+  // ---- migrate (on boot) --------------------------------------------------------------------------
+  if (!doneStep('migrate')) {
+    const u = await composeUp({ install, g });
+    if (!u.ok) return fail('migrate', u.error);
+    mark('migrate');
+  }
+
+  // ---- health -------------------------------------------------------------------------------------
+  if (dryRun) {
+    log(`[dry run] would wait for auth + collector /health and the collector /version to report ${newCommit || target}`);
+    return { ok: true, dryRun: true, plan, planned: g.planned };
+  }
+  const h = await waitHealthy({ urls, fetchImpl, expectCommit: newCommit, tries: healthTries, intervalMs: healthIntervalMs, sleep, log });
+  if (!h.ok) return fail('health', h.error);
+  mark('health');
+  finish('ok');
+  return { ok: true, plan };
+}
+
+/** opts: { install, sys, backups, urls, fetchImpl, dryRun, snapshotDir, log, healthTries, ... } */
+export async function runRollback(opts) {
+  const { install, sys, backups, urls, fetchImpl = globalThis.fetch, dryRun = false, log = () => {}, now = () => new Date(),
+    healthTries = 40, healthIntervalMs = 3000, sleep = sleepDefault, fromUpdate = false } = opts;
+  const g = gate(sys, { dryRun, log });
+  const snaps = listSnapshots(backups);
+  const snap = opts.snapshotDir ? snaps.find((s) => s.dir === opts.snapshotDir || s.dir.endsWith(`/${opts.snapshotDir}`)) : latestSnapshot(backups);
+  if (!snap) return { ok: false, error: opts.snapshotDir ? `no complete snapshot at ${opts.snapshotDir}` : `no snapshot in ${backups}; nothing to roll back to` };
+  const plan = { snapshot: snap.dir, release: snap.release, commit: snap.commit, createdAt: snap.createdAt };
+  const record = (status, extra = {}) => {
+    if (!dryRun && !fromUpdate) appendHistory(backups, { op: 'rollback', status, at: now().toISOString(), to: snap.release || snap.commit, snapshot: snap.dir, ...extra });
+  };
+  if (!snap.commit) return { ok: false, error: 'the snapshot does not record which commit it came from', plan };
+
+  const c = await checkoutCode({ install, g, ref: snap.commit, siblings: snap.siblings, log });
+  if (!c.ok) { record('failed', { error: c.error }); return { ok: false, step: 'checkout', error: c.error, plan }; }
+  const b = await composeBuild({ install, g, commit: snap.commit });
+  if (!b.ok) { record('failed', { error: b.error }); return { ok: false, step: 'build', error: b.error, plan }; }
+  const r = await restoreSnapshot({ install, snap, g, sleep });
+  if (!r.ok) { record('failed', { error: r.error }); return { ok: false, step: 'restore', error: r.error, plan }; }
+  const u = await composeUp({ install, g });
+  if (!u.ok) { record('failed', { error: u.error }); return { ok: false, step: 'start', error: u.error, plan }; }
+  if (dryRun) {
+    log(`[dry run] would wait for health and the collector /version to report ${snap.commit}`);
+    return { ok: true, dryRun: true, plan, planned: g.planned };
+  }
+  const h = await waitHealthy({ urls, fetchImpl, expectCommit: snap.commit, tries: healthTries, intervalMs: healthIntervalMs, sleep, log });
+  if (!h.ok) { record('failed', { error: h.error }); return { ok: false, step: 'health', error: h.error, plan }; }
+  if (!fromUpdate) writeState(backups, { op: 'rollback', status: 'ok', snapshot: snap.dir, at: now().toISOString() });
+  record('ok');
+  return { ok: true, plan };
+}

package/lib/toolOutputShape.js

@@ -0,0 +1,315 @@
+/**
+ * #970: governed output shaping for `quox tool exec` (--select / --summary / --limit).
+ *
+ * On the chat CLI-tools path every shell call except `quox tool exec` is denied, so a model
+ * facing a large result (wazuh agents, seo urls, a 618 KB calendar overlay) has no honest
+ * way to narrow it. This is that way, inside the governed call: the path grammar is the
+ * safe evaluator QuoxOn rows already use (parsePath: a.b, a[0], list[field=value], list[field~text], list[*], {a,b},
+ * count(path)), no eval and no new dependency. The shape is sent to the collector so the
+ * receipt records what view of the result the caller was shown.
+ *
+ * Honesty rules: a truncated list always says "showing N of M"; a path that matches
+ * nothing says so rather than returning null; a malformed path is an error BEFORE the
+ * tool runs.
+ */
+
+import { parsePath } from './quoxon/rows.js';
+
+const BLOCKED = new Set(['__proto__', 'constructor', 'prototype']);
+const GRAMMAR = 'use a.b, a[0], list[field=value] (exact), list[field~text] (contains, any case), list[*].field (that field of every item), list[*].{a,b} (several fields of every item, one call), list[field=value].name, count(list), or several paths at once: total,count(list)';
+export const DEFAULT_SAMPLE = 10;
+const COUNT_KEY_RE = /^(status|state|type|kind|level|severity|health|healthy|enabled|active|category|source|platform|os|role|priority|result|outcome|connected|online)$/i;
+
+// Split on commas outside [], {} and (): "total, count(a[x=1]), b.{c,d}" -> three paths. null when there is no
+// top-level comma (a single path), [] entries kept so an empty part is an error, never silently dropped.
+function splitTopLevel(e) {
+  const parts = [];
+  let depth = 0, start = 0;
+  for (let i = 0; i < e.length; i++) {
+    const c = e[i];
+    if (c === '[' || c === '{' || c === '(') depth++;
+    else if (c === ']' || c === '}' || c === ')') depth = Math.max(0, depth - 1);
+    else if (c === ',' && depth === 0) { parts.push(e.slice(start, i).trim()); start = i + 1; }
+  }
+  if (!parts.length) return null;
+  parts.push(e.slice(start).trim());
+  return parts;
+}
+
+function parseSelect(expr) {
+  const e = String(expr ?? '').trim();
+  // GUIDES-FIX: several paths in one call ("total,active_total"): each must be a valid path on its own.
+  const parts = splitTopLevel(e);
+  if (parts) {
+    if (parts.some((x) => !x)) return { error: `--select: empty path in ${JSON.stringify(e)}; separate several paths with commas, e.g. total,count(list); ${GRAMMAR}` };
+    const multi = [];
+    for (const x of parts) {
+      const p = parseSelect(x);
+      if (p.error) return p;
+      multi.push({ expr: x, ...p });
+    }
+    return { multi };
+  }
+  const fn = /^([A-Za-z_]+)\s*\(([\s\S]*)\)$/.exec(e);
+  if (fn) {
+    if (fn[1] !== 'count') return { error: `--select: unknown function ${fn[1]}() (only count); ${GRAMMAR}` };
+    const steps = parsePath(fn[2]);
+    return steps ? { fn: 'count', steps } : { error: `--select: count() needs a path; ${GRAMMAR}` };
+  }
+  const steps = parsePath(e);
+  return steps ? { steps } : { error: `--select: bad path ${JSON.stringify(e)}; ${GRAMMAR}` };
+}
+
+function parseLimit(v) {
+  if (v === undefined || v === null || v === true) return { value: undefined };
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 1 || n > 10000) return { error: `--limit: expected a whole number from 1 to 10000, got ${JSON.stringify(String(v))}` };
+  return { value: n };
+}
+
+/** Validate a shape before the tool runs -> error string or null. */
+export function checkShape({ select, limit } = {}) {
+  if (select !== undefined) { const p = parseSelect(select); if (p.error) return p.error; }
+  const l = parseLimit(limit);
+  return l.error || null;
+}
+
+/** The content-free record of the shape, as sent to the collector for the receipt. */
+export function shapeRecord({ select, summary, limit } = {}) {
+  const r = {};
+  if (select !== undefined) r.select = String(select);
+  if (summary) r.summary = true;
+  const l = parseLimit(limit);
+  if (l.value !== undefined) r.limit = l.value;
+  return Object.keys(r).length ? r : null;
+}
+
+const isObj = (o) => o !== null && typeof o === 'object' && !Array.isArray(o);
+const own = (o, k) => isObj(o) && !BLOCKED.has(k) && Object.hasOwn(o, k);
+
+/** Like the rows evaluator, plus projection: a key step on a list maps over its items. */
+function walk(data, steps) {
+  let cur = data;
+  for (const st of steps) {
+    if (cur === undefined || cur === null) return undefined;
+    if ('key' in st) {
+      if (Array.isArray(cur)) cur = cur.filter((it) => own(it, st.key)).map((it) => it[st.key]);
+      else { if (!own(cur, st.key)) return undefined; cur = cur[st.key]; }
+    } else if ('index' in st) {
+      if (!Array.isArray(cur)) return undefined; cur = cur[st.index];
+    } else if (st.wildcard) {
+      // list[*]: every item; the key steps after it already map over a list.
+      if (!Array.isArray(cur)) return undefined;
+    } else if (st.fields) {
+      // #1044: {a,b}: only these fields, of every item on a list. Blocked keys are never copied.
+      const pick = (o) => { const r = {}; for (const f of st.fields) if (own(o, f)) r[f] = o[f]; return r; };
+      cur = Array.isArray(cur) ? cur.map((it) => (isObj(it) ? pick(it) : {})) : isObj(cur) ? pick(cur) : undefined;
+    } else {
+      if (!Array.isArray(cur)) return undefined;
+      const sub = parsePath(st.field);
+      cur = cur.filter((it) => {
+        const v = sub ? walk(it, sub) : undefined;
+        if (v === undefined || v === null || typeof v === 'object') return false;
+        return 'contains' in st ? String(v).toLowerCase().includes(st.contains) : String(v) === st.value;
+      });
+    }
+  }
+  return cur;
+}
+
+const countOf = (v) => (Array.isArray(v) ? v.length : isObj(v) ? Object.keys(v).length : v === undefined ? 0 : 1);
+
+/** The main list of a value: itself, else its largest array (top level, then one level down). */
+function mainList(value) {
+  if (Array.isArray(value)) return { path: '', list: value };
+  if (!isObj(value)) return null;
+  let best = null;
+  const consider = (path, v) => { if (Array.isArray(v) && (!best || v.length > best.list.length)) best = { path, list: v }; };
+  for (const [k, v] of Object.entries(value)) consider(k, v);
+  if (!best) for (const [k, v] of Object.entries(value)) if (isObj(v)) for (const [k2, v2] of Object.entries(v)) consider(`${k}.${k2}`, v2);
+  return best;
+}
+
+function fieldCounts(list) {
+  const counts = {};
+  const keys = new Set();
+  for (const it of list) if (isObj(it)) for (const k of Object.keys(it)) if (COUNT_KEY_RE.test(k)) keys.add(k);
+  for (const k of keys) {
+    const c = {};
+    for (const it of list) {
+      const v = isObj(it) ? it[k] : undefined;
+      if (v === undefined || v === null || typeof v === 'object') continue;
+      const key = String(v);
+      c[key] = (c[key] || 0) + 1;
+    }
+    if (Object.keys(c).length && Object.keys(c).length <= 20) counts[k] = c;
+  }
+  return counts;
+}
+
+/** Honest summary: total, per-field counts where obvious, a bounded sample, "showing N of M". */
+export function summarize(value, { limit = DEFAULT_SAMPLE } = {}) {
+  const found = mainList(value);
+  if (!found) {
+    return isObj(value)
+      ? { note: 'no list in this result; showing its keys', keys: Object.keys(value) }
+      : { note: 'no list in this result', value };
+  }
+  const M = found.list.length;
+  const N = Math.min(limit, M);
+  const out = { list_path: found.path || '(root)', total: M, showing: N, note: `showing ${N} of ${M}` };
+  const counts = fieldCounts(found.list);
+  if (Object.keys(counts).length) out.counts = counts;
+  if (isObj(value)) {
+    const scalars = Object.fromEntries(Object.entries(value).filter(([, v]) => v === null || typeof v !== 'object'));
+    if (Object.keys(scalars).length) out.fields = scalars;
+  }
+  out.sample = found.list.slice(0, N);
+  return out;
+}
+
+function truncate(value, n) {
+  if (Array.isArray(value)) {
+    if (value.length <= n) return value;
+    return { total: value.length, showing: n, note: `showing ${n} of ${value.length}`, items: value.slice(0, n) };
+  }
+  const found = mainList(value);
+  if (!found || !found.path || found.list.length <= n) return value;
+  const copy = structuredClone(value);
+  const parts = found.path.split('.');
+  let host = copy;
+  for (const p of parts.slice(0, -1)) host = host[p];
+  host[parts[parts.length - 1]] = found.list.slice(0, n);
+  copy._truncated = { path: found.path, total: found.list.length, showing: n, note: `showing ${n} of ${found.list.length}` };
+  return copy;
+}
+
+function asData(raw) {
+  if (typeof raw !== 'string') return raw;
+  const t = raw.trim();
+  if (t.startsWith('{') || t.startsWith('[')) { try { return JSON.parse(t); } catch { /* text */ } }
+  return raw;
+}
+
+/** Apply select, then summary or limit. -> { value } (throws on a malformed shape). */
+export function shapeOutput(raw, shape = {}) {
+  const err = checkShape(shape);
+  if (err) throw new Error(err);
+  let value = asData(raw);
+  if (shape.select !== undefined) {
+    const p = parseSelect(shape.select);
+    if (p.multi) {
+      // each path under its own expression; a path that matched nothing is named, never dropped
+      const out = {};
+      const unmatched = [];
+      for (const q of p.multi) {
+        const v = walk(value, q.steps);
+        if (q.fn === 'count') out[q.expr] = countOf(v);
+        else if (v === undefined) unmatched.push(q.expr);
+        else out[q.expr] = v;
+      }
+      if (!Object.keys(out).length) {
+        return { value: { select: String(shape.select), matched: false, note: 'none of the --select paths matched anything in the result', top_keys: isObj(value) ? Object.keys(value) : [] } };
+      }
+      if (unmatched.length) { out._unmatched = unmatched; out._note = `${unmatched.length} of ${p.multi.length} --select paths matched nothing in the result`; }
+      value = out;
+    } else {
+    const v = walk(value, p.steps);
+    if (p.fn === 'count') value = countOf(v);
+    else if (v === undefined) {
+      return { value: { select: String(shape.select), matched: false, note: 'the --select path matched nothing in the result', top_keys: isObj(value) ? Object.keys(value) : [] } };
+    } else value = v;
+    }
+  }
+  const { value: limit } = parseLimit(shape.limit);
+  if (shape.summary) return { value: summarize(value, { limit: limit ?? DEFAULT_SAMPLE }) };
+  if (limit !== undefined) return { value: truncate(value, limit) };
+  return { value };
+}
+
+/**
+ * BASH-FALLBACK: keep an unshaped result inline on the model-driven path.
+ *
+ * Claude Code saves Bash output above its inline limit (30000 chars by default) to a file
+ * and shows only a path plus a 2 KB preview. The model then reaches for jq/python/grep on
+ * that file, which the CLI-tools Bash guard denies (55 of 64 Bash attempts in the
+ * 2026-10-14/15 proof evidence). Capping here, below that limit, means the model never
+ * gets a file to post-process: it gets the honest --summary view plus how to re-run with
+ * --select. The cap only ever shrinks what is SHOWN; the call itself already ran governed.
+ */
+export const INLINE_MAX_CHARS = 20000;
+
+const jsonLen = (v) => (typeof v === 'string' ? v.length : JSON.stringify(v, null, 2).length);
+
+/** A {output: "<json>"} envelope (quox_cli and some tools) -> its parsed body, else null. */
+function innerOutput(value) {
+  if (!isObj(value) || typeof value.output !== 'string') return null;
+  const parsed = asData(value.output);
+  return typeof parsed === 'string' ? null : parsed;
+}
+
+/**
+ * FLEET-UNHEALTHY: the small non-scalar top-level fields beside the main list (a short "not_healthy" list, a
+ * "by_state" count object) are often the answer itself; the summary used to drop every non-scalar. Each kept
+ * whole or left out whole, never cut: at most SMALL_FIELD_MAX chars each and SMALL_FIELDS_MAX in total.
+ */
+const SMALL_FIELD_MAX = 6000;
+const SMALL_FIELDS_MAX = 9000;
+function smallTopFields(body, found) {
+  if (!isObj(body)) return null;
+  const mainKey = found && found.path ? found.path.split('.')[0] : null;
+  const out = {};
+  let used = 0;
+  for (const [k, v] of Object.entries(body)) {
+    if (k === mainKey || BLOCKED.has(k) || v === null || typeof v !== 'object') continue;
+    const n = jsonLen(v);
+    if (n > SMALL_FIELD_MAX || used + n > SMALL_FIELDS_MAX) continue;
+    out[k] = v;
+    used += n;
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+export function capInline(value, { maxChars = INLINE_MAX_CHARS } = {}) {
+  const size = jsonLen(value);
+  if (size <= maxChars) return { value, capped: false };
+  const fullKb = Math.round(size / 1024);
+  const data = asData(value);
+  if (typeof data === 'string') {
+    const wrap = (keep) => ({
+      oversized: true,
+      full_size_kb: fullKb,
+      note: `showing the first ${keep} of ${data.length} characters`,
+      next: "Too large to show whole. Run the same call again with narrower --args, or --select '<path>' / --limit N if it is JSON. Never read or post-process a saved output with a shell.",
+      text: data.slice(0, keep),
+    });
+    // JSON escaping (newlines, quotes) inflates the text: shrink until the wrapper fits.
+    let keep = Math.max(0, maxChars - 1200);
+    let out = wrap(keep);
+    while (keep > 0 && jsonLen(out) > maxChars) { keep = Math.floor(keep * 0.8); out = wrap(keep); }
+    return { capped: true, value: out };
+  }
+  const inner = innerOutput(data);
+  const body = inner ?? data;
+  const via = inner ? 'output (a JSON string: --select cannot reach inside it, so narrow it with --args or the tool\'s own filters)' : null;
+  const found = mainList(body);
+  const lp = found && found.path ? found.path : (found ? '' : null);
+  const example = lp === null
+    ? "--select '<key>'"
+    : `--select '${lp ? `${lp}[field=value].name` : '[0]'}', --select 'count(${lp || ''})' or --select '${lp ? `${lp}[*].field` : '[*].field'}'`;
+  const next = `Result is ${fullKb} KB, too large to show whole, so this is the --summary view. For the exact part you need, run the same quox tool exec again with ${example} (or --summary --limit N for a bigger sample)${via ? `; the list is inside ${via}` : ''}. Never read or post-process a saved output with a shell.`;
+  const head = { oversized: true, full_size_kb: fullKb, next, top_keys: isObj(body) ? Object.keys(body).slice(0, 40) : undefined };
+  const extra = smallTopFields(body, found);
+  for (const limit of [DEFAULT_SAMPLE, 5, 3, 1, 0]) {
+    const s = summarize(body, { limit });
+    const out = { ...head, ...s, ...(extra ? { fields: { ...(s.fields || {}), ...extra } } : {}) };
+    if (jsonLen(out) <= maxChars) return { capped: true, value: out };
+  }
+  for (const limit of [DEFAULT_SAMPLE, 5, 3, 1, 0]) {
+    const out = { ...head, ...summarize(body, { limit }) };
+    if (jsonLen(out) <= maxChars) return { capped: true, value: out };
+  }
+  // Even an empty sample is too big (a huge scalar field): keep only the counts and shape.
+  const s = summarize(body, { limit: 0 });
+  return { capped: true, value: { ...head, list_path: s.list_path, total: s.total, showing: 0, note: s.note || 'fields too large to show', counts: s.counts } };
+}

package/lib/tui/views/HyperionDeck.jsx

@@ -0,0 +1,79 @@
+/**
+ * HyperionDeck: the full-screen live HYPERION activity view (`quox hyperion deck`), in the Quoxon look.
+ * Refreshes every intervalMs; r refreshes now, q quits. A failed fetch never blanks the screen: the last
+ * good data stays, marked STALE, with the error named in the header. Props are injected (api, intervalMs)
+ * so the component is testable without a network. api = { activity() }.
+ *
+ * Refresh props live in refs so the fetch loop is created once (the LUCID deck ran out of memory when a
+ * changing prop restarted its loop on every redraw).
+ */
+import React, { useState, useEffect, useRef, useCallback } from 'react';
+import { Box, Text, useInput, useApp, useStdout } from 'ink';
+import { statusLines, summaryText } from '../../core/hyperion.js';
+import { c, gradient } from '../../quoxon/theme.js';
+
+function roleFor(line) {
+  if (/^(Node load|Pool|Recent ops)/.test(line)) return 'sky';
+  if (/^VMID/.test(line)) return 'label';
+  if (/unavailable|^⚠/.test(line)) return 'warn';
+  return 'value';
+}
+
+export function HyperionDeck({ api, intervalMs = 10000 }) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const rows = (stdout && stdout.rows) || 30;
+  const [data, setData] = useState(null);
+  const [err, setErr] = useState(null);
+  const [at, setAt] = useState(null);
+  const inflight = useRef(false);
+  const apiRef = useRef(api);
+  apiRef.current = api;
+
+  const refresh = useCallback(async () => {
+    if (inflight.current) return;
+    inflight.current = true;
+    try {
+      setData(await apiRef.current.activity());
+      setErr(null);
+      setAt(Date.now());
+    } catch (e) {
+      setErr(e);
+    } finally {
+      inflight.current = false;
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+    const t = setInterval(refresh, intervalMs);
+    return () => clearInterval(t);
+  }, [refresh, intervalMs]);
+
+  useInput((input) => {
+    if (input === 'q') exit();
+    else if (input === 'r') refresh();
+  });
+
+  const lines = data ? statusLines(data, { now: Date.now() }) : [];
+  const shown = lines.slice(0, Math.max(5, rows - 4));
+  const stale = err && data;
+  return (
+    <Box flexDirection="column">
+      <Text wrap="truncate">
+        {gradient(' HYPERION ').map((g, i) => <Text key={i} bold color={g.color}>{g.ch}</Text>)}
+        <Text color={c('value')}> {data ? summaryText(data) : 'loading'}</Text>
+        {stale ? <Text color={c('warn')}>  STALE: {String(err.message || err).slice(0, 60)}</Text> : null}
+        {err && !data ? <Text color={c('error')}>  unreachable: {String(err.message || err).slice(0, 60)}</Text> : null}
+      </Text>
+      <Text> </Text>
+      {shown.map((l, i) => <Text key={i} wrap="truncate" color={c(roleFor(l))}>{l}</Text>)}
+      <Text> </Text>
+      <Text wrap="truncate">
+        <Text bold color={c('key')}>r</Text><Text color={c('value')}> refresh   </Text>
+        <Text bold color={c('key')}>q</Text><Text color={c('value')}> quit   </Text>
+        <Text color={c('value')}>{at ? `updated ${new Date(at).toISOString().slice(11, 19)} UTC, every ${Math.round(intervalMs / 1000)}s` : ''}</Text>
+      </Text>
+    </Box>
+  );
+}