quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/rows.js

@@ -0,0 +1,954 @@
+/**
+ * QUOXON-FW17: custom rows. User-defined lines rendered just above the status line.
+ *
+ * A row is { id, label?, source: { type: 'url', url, every } | { type: 'cmd', cmd, every }, template, colour? }.
+ * The template pulls values out of the fetched JSON (or the command's stdout, as {{text}}) with a tiny
+ * SAFE evaluator: {{a.b[0].c}}, {{count(list)}}, {{count(list[field=value])}}, list[field~text] (contains, any
+ * case, a plain includes), list[*] (every item) and {a,b} (only these fields). Nothing is eval'd.
+ *
+ * Sync split (a security line, enforced here and tested): url rows sync per user (preference namespace
+ * quoxonRows); cmd rows are LOCAL ONLY. normRows() on anything that arrives from the server drops every cmd
+ * row, so a synced row can never make another machine run a shell command.
+ *
+ * ROWS (2026-10-17): the status-row contract. A row with NO template reads the public JSON shape
+ *   { text, label?, value?, tone?: ok|warn|error|info|neutral, trend?: up|down|flat|<number>, link? }
+ * (docs/STATUS_ROWS.md). Plain text output counts as { text }. Two more keyless, sync-safe sources:
+ *   quox:   { type: 'quox', service: auth|collector, path: '/api/...{org}...' }  your own Quox, with your session
+ *   plugin: { type: 'plugin', plugin: '<id>', path: '<relative>' }             GET /api/v1/plugins/<id>/<path>
+ * Everything a row prints passes cleanText(): terminal escapes and control characters never reach the screen.
+ */
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { cellWidth } from './cells.js';
+
+export const MAX_ROWS = 3;
+/** Lines drawn above the status bar (a row can bring several with `lines`); the stored-row cap stays MAX_ROWS. */
+export const MAX_LINES = 4;
+export const FETCH_TIMEOUT_MS = 5000;
+/** url rows fetch from busy boxes (the proof board is ~400 KB): 15 s. cmd rows keep FETCH_TIMEOUT_MS. */
+export const URL_TIMEOUT_MS = 15000;
+/** A failed refresh keeps showing the last good value (with an age marker) for this long, then warns. */
+export const STALE_MAX_MS = 30 * 60 * 1000;
+export const BACKOFF_CAP_MS = 10 * 60 * 1000;
+export const OUTPUT_CAP = 64 * 1024;
+/** A JSON body is parsed whole or not at all: cutting it leaves nothing to read (2026-10-14: the proof board grew to 347 KB and the row showed only dashes). */
+export const JSON_CAP = 2 * 1024 * 1024;
+export const ROLES = ['prose', 'command', 'value', 'ok', 'warn', 'error', 'brand', 'quiet'];
+const ROLE_TO_THEME = { value: 'id' }; // palette role -> theme.js name
+export const themeRole = (r) => ROLE_TO_THEME[r] || r || 'prose';
+
+const BLOCKED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/* ---- what a row may print ------------------------------------------------------------------ */
+
+// CSI, OSC (title, hyperlink, clipboard), DCS/SOS/PM/APC strings and lone 2-byte escapes.
+const ANSI_RE = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[PX^_][^\x1b]*(?:\x1b\\)?|\x1b[@-Z\\-_]?/g;
+// C0, DEL, C1, zero-width space, LRM/RLM, bidi embeddings, overrides and isolates, BOM. ZWJ stays (emoji).
+const CTRL_RE = /[\u0000-\u001f\u007f-\u009f\u200b\u200e\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g;
+
+/**
+ * Text from a URL, a command or a plugin -> one safe line. A remote endpoint must never be able to move the
+ * cursor, retitle the terminal, write the clipboard (OSC 52) or reorder text with bidi overrides.
+ */
+export function cleanText(v, max = 500) {
+  return String(v ?? '').replace(ANSI_RE, '').replace(/[\t\n\r\v\f]+/g, ' ').replace(CTRL_RE, '').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+
+/* ---- durations --------------------------------------------------------------------------- */
+
+/** '60s' | '5m' | '1h' -> ms, or null. Floor 5 s, ceiling 1 day. */
+export function parseEvery(s) {
+  const m = /^(\d+)\s*(s|m|h)$/i.exec(String(s ?? '').trim());
+  if (!m) return null;
+  const ms = Number(m[1]) * { s: 1000, m: 60000, h: 3600000 }[m[2].toLowerCase()];
+  return ms >= 5000 && ms <= 86400000 ? ms : null;
+}
+
+/* ---- the template evaluator ------------------------------------------------------------- */
+
+/** A path -> steps, or null when malformed. */
+export function parsePath(src) {
+  const s = String(src ?? '').trim();
+  if (!s) return null;
+  const steps = [];
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === '.') { i++; continue; }
+    if (s[i] === '[') {
+      const end = s.indexOf(']', i);
+      if (end < 0) return null;
+      const inner = s.slice(i + 1, end).trim();
+      i = end + 1;
+      if (/^\d+$/.test(inner)) steps.push({ index: Number(inner) });
+      else if (inner === '*') steps.push({ wildcard: true }); // list[*]: every item
+      else {
+        const eq = /^([^=~\s\[\]]+)\s*=\s*(.*)$/.exec(inner);
+        if (eq) steps.push({ field: eq[1], value: eq[2].trim().replace(/^(["'])(.*)\1$/, '$2') });
+        else {
+          // list[field~text]: case-insensitive contains, a plain includes (never a regex from input).
+          const ct = /^([^=~\s\[\]]+)\s*~\s*(.*)$/.exec(inner);
+          if (!ct) return null;
+          const text = ct[2].trim().replace(/^(["'])(.*)\1$/, '$2');
+          if (!text) return null;
+          steps.push({ field: ct[1], contains: text.toLowerCase() });
+        }
+      }
+      continue;
+    }
+    if (s[i] === '{') {
+      // #1044: {a,b,c} keeps only these fields (of every item when on a list).
+      const end = s.indexOf('}', i);
+      if (end < 0) return null;
+      const fields = s.slice(i + 1, end).split(',').map((f) => f.trim());
+      if (!fields.length || fields.some((f) => !/^[A-Za-z0-9_-]+$/.test(f))) return null;
+      steps.push({ fields });
+      i = end + 1;
+      continue;
+    }
+    let j = i;
+    while (j < s.length && s[j] !== '.' && s[j] !== '[') j++;
+    const key = s.slice(i, j).trim();
+    if (!key || /[\s(){}=,;+*\/]/.test(key)) return null;
+    steps.push({ key });
+    i = j;
+  }
+  return steps.length ? steps : null;
+}
+
+const own = (o, k) => o !== null && typeof o === 'object' && !Array.isArray(o) && !BLOCKED_KEYS.has(k) && Object.hasOwn(o, k);
+
+function walk(data, steps) {
+  let cur = data;
+  for (const st of steps) {
+    if (cur === undefined || cur === null) return undefined;
+    if ('key' in st) { 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) { if (!Array.isArray(cur)) return undefined; }
+    else if (st.fields) {
+      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(pick) : pick(cur);
+    }
+    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;
+}
+
+/** 1234 -> 1.2k, 12345 -> 12k, 1500000 -> 1.5M. Small numbers stay as they are. */
+export function fmtNum(n) {
+  if (!Number.isFinite(n)) return String(n);
+  const a = Math.abs(n);
+  if (a < 1000) return String(Number.isInteger(n) ? n : Number(n.toFixed(1)));
+  for (const [u, sfx] of [[1e12, 'T'], [1e9, 'B'], [1e6, 'M'], [1e3, 'k']]) {
+    if (a >= u) {
+      const v = n / u;
+      return `${Math.abs(v) < 10 ? v.toFixed(1).replace(/\.0$/, '') : Math.round(v)}${sfx}`;
+    }
+  }
+  return String(n);
+}
+
+const show = (v) => {
+  if (v === undefined || v === null) return '–';
+  if (typeof v === 'number') return fmtNum(v);
+  if (typeof v === 'string') return cleanText(v);
+  if (typeof v === 'boolean') return String(v);
+  if (Array.isArray(v)) return String(v.length);
+  return '{…}';
+};
+
+/** One {{ expr }} body -> { ok, value } | { ok: false, error }. */
+function parseExpr(body) {
+  const e = String(body ?? '').trim();
+  const fn = /^([A-Za-z_]+)\s*\(([\s\S]*)\)$/.exec(e);
+  if (fn) {
+    if (fn[1] !== 'count') return { error: `unknown function ${fn[1]}() (only count)` };
+    const steps = parsePath(fn[2]);
+    return steps ? { fn: 'count', steps } : { error: 'count() needs a path' };
+  }
+  const steps = parsePath(e);
+  return steps ? { steps } : { error: e ? `bad path "${e}"` : 'empty {{ }}' };
+}
+
+const countOf = (v) => (Array.isArray(v) ? v.length : v && typeof v === 'object' ? Object.keys(v).length : undefined);
+
+/** Syntax check for a template at add time -> an error string or null. */
+export function checkTemplate(tpl) {
+  const t = String(tpl ?? '');
+  if (!t.trim()) return 'The template is empty.';
+  if ((t.match(/\{\{/g) || []).length !== (t.match(/\}\}/g) || []).length) return 'Unbalanced {{ }} in the template.';
+  for (const m of t.matchAll(/\{\{([\s\S]*?)\}\}/g)) { const p = parseExpr(m[1]); if (p.error) return p.error; }
+  return null;
+}
+
+/** Fill a template from parsed data. Unknown paths show as "–". Never throws. */
+export function evalTemplate(tpl, data) {
+  return String(tpl ?? '').replace(/\{\{([\s\S]*?)\}\}/g, (_, body) => {
+    const p = parseExpr(body);
+    if (p.error) return '–';
+    const v = walk(data, p.steps);
+    return show(p.fn === 'count' ? countOf(v) : v);
+  });
+}
+
+/** Raw text (a response body or stdout) -> the object the template reads: parsed JSON, else { text }. */
+export function dataFrom(raw) {
+  const text = String(raw ?? '');
+  const t = text.trim();
+  if (t.startsWith('{') || t.startsWith('[')) { try { const j = JSON.parse(t); if (j && typeof j === 'object') return j; } catch { /* plain text */ } }
+  return { text: t };
+}
+
+/* ---- the status-row contract (docs/STATUS_ROWS.md) ---------------------------------------- */
+
+export const STATUS_ROW_TONES = ['ok', 'warn', 'error', 'info', 'neutral'];
+const TONE_ROLE = { ok: 'ok', warn: 'warn', error: 'error', info: 'command', neutral: 'prose' };
+const TONE_GLYPH = { ok: '✔', warn: '⚠', error: '✖', info: '◆' };
+export const toneRole = (t) => TONE_ROLE[t] || null;
+
+const trendText = (t) => {
+  if (t === 'up') return '▲';
+  if (t === 'down') return '▼';
+  if (t === 'flat') return '▬';
+  if (typeof t === 'number' && Number.isFinite(t)) return t > 0 ? `▲${fmtNum(t)}` : t < 0 ? `▼${fmtNum(-t)}` : '▬';
+  return '';
+};
+
+/* ---- cells (contract v1.1, TUI-QPE 2026-10-19) --------------------------------------------------
+ * A row may carry `cells`: [{ parts: [{ text, tone?, bold?, keep?, group? }], keep? }]. Each part has its own colour
+ * (a tone), so one row can say "70%" in amber and "▼12 broke" in red. `keep` says what goes first when the window is
+ * narrow: the lowest keep is dropped whole (a part, the parts sharing its group, or a cell; never half a word); no keep
+ * = never dropped. Rows with the same `grid` share one keep order and line their cells up in columns; `min_cols` hides
+ * a row in a narrower window.
+ */
+export const CELL_LIMITS = { cells: 6, parts: 12, text: 80 };
+const keepOf = (k) => (typeof k === 'number' && Number.isFinite(k) ? Math.max(0, Math.min(99, k)) : null);
+
+function parseCells(list, warnings) {
+  if (!Array.isArray(list)) { warnings.push('"cells" is a list of {parts: [{text, tone}]}; ignored.'); return []; }
+  const out = [];
+  for (const c of list.slice(0, CELL_LIMITS.cells)) {
+    const raw = Array.isArray(c?.parts) ? c.parts : typeof c?.text === 'string' ? [c] : null;
+    if (!raw) { warnings.push('A cell needs "parts" (or "text"); skipped.'); continue; }
+    const parts = [];
+    for (const p of raw.slice(0, CELL_LIMITS.parts)) {
+      // Keep edge spaces (a part's own joiner, " · reach 214/266"): clean the middle, not the ends.
+      const t = typeof p?.text === 'string' ? p.text : typeof p?.text === 'number' ? fmtNum(p.text) : '';
+      const lead = /^\s/.test(t) ? ' ' : ''; const trail = /\s$/.test(t) ? ' ' : '';
+      const body = cleanText(t, CELL_LIMITS.text);
+      if (!body) continue;
+      const part = { text: lead + body + trail };
+      if (p.tone !== undefined && p.tone !== null) {
+        if (STATUS_ROW_TONES.includes(p.tone)) { if (p.tone !== 'neutral') part.tone = p.tone; }
+        else warnings.push(`a part's "tone" is one of ${STATUS_ROW_TONES.join(', ')}; "${cleanText(p.tone, 16)}" shows as neutral.`);
+      }
+      if (p.bold === true) part.bold = true;
+      const k = keepOf(p.keep); if (k !== null) part.keep = k;
+      if (typeof p.group === 'string' && /^[A-Za-z0-9_-]{1,16}$/.test(p.group)) part.group = p.group; // parts that drop together
+      parts.push(part);
+    }
+    if (!parts.length) continue;
+    const cell = { parts };
+    const k = keepOf(c.keep); if (k !== null) cell.keep = k;
+    out.push(cell);
+  }
+  return out;
+}
+
+/** cells -> one plain line (screen context, /row list, a narrow fallback). */
+export const cellsText = (cells) => (cells || []).map((c) => c.parts.map((p) => p.text).join('').trim()).join(' │ ');
+
+/**
+ * Parsed data -> { seg, warnings } | { error }. Lenient on read (an unknown tone shows neutral and is named
+ * in warnings, so `quox rows test` can say so); strict on what it prints (everything passes cleanText).
+ */
+export function parseStatusRow(d, depth = 0) {
+  if (!d || typeof d !== 'object' || Array.isArray(d)) return { error: 'A status row is a JSON object: {"text": "..."}.' };
+  const warnings = [];
+  const seg = {};
+  const text = typeof d.text === 'string' ? cleanText(d.text, 160) : typeof d.text === 'number' ? fmtNum(d.text) : '';
+  if (text) seg.text = text;
+  if (typeof d.value === 'number' && Number.isFinite(d.value)) seg.value = fmtNum(d.value);
+  else if (typeof d.value === 'string' && cleanText(d.value, 24)) seg.value = cleanText(d.value, 24);
+  else if (d.value !== undefined && d.value !== null) warnings.push('"value" is a number or a short string; ignored.');
+  if (depth === 0 && d.lines !== undefined && d.lines !== null) { // TUI-QPE 2026-10-20: one source, several lines (v1.1)
+    if (!Array.isArray(d.lines)) warnings.push('"lines" is a list of status rows; ignored.');
+    else {
+      const lines = [];
+      for (const x of d.lines.slice(0, MAX_LINES)) { const q = parseStatusRow(x, 1); if (q.error) warnings.push(`a line: ${q.error}`); else { lines.push(q.seg); warnings.push(...q.warnings); } }
+      if (lines.length) { seg.lines = lines; if (!seg.text) seg.text = lines.map((l) => l.text).join(' / ').slice(0, 160); }
+    }
+  }
+  if (d.cells !== undefined && d.cells !== null) { // TUI-QPE: coloured, responsive cells (v1.1)
+    const cells = parseCells(d.cells, warnings);
+    if (cells.length) { seg.cells = cells; if (!seg.text) seg.text = cellsText(cells); }
+  }
+  if (!seg.text && !seg.value) return { error: 'Not a status row: it needs "text" (see quox rows contract).' };
+  if (d.grid !== undefined && d.grid !== null) {
+    if (typeof d.grid === 'string' && /^[A-Za-z0-9_-]{1,16}$/.test(d.grid)) seg.grid = d.grid; else warnings.push('"grid" is a short name (letters, digits, - and _); ignored.');
+  }
+  if (d.min_cols !== undefined && d.min_cols !== null) {
+    if (Number.isInteger(d.min_cols) && d.min_cols >= 20 && d.min_cols <= 400) seg.minCols = d.min_cols; else warnings.push('"min_cols" is a whole number from 20 to 400; ignored.');
+  }
+  if (d.tone !== undefined && d.tone !== null) {
+    if (STATUS_ROW_TONES.includes(d.tone)) { if (d.tone !== 'neutral') seg.tone = d.tone; }
+    else warnings.push(`"tone" is one of ${STATUS_ROW_TONES.join(', ')}; "${cleanText(d.tone, 16)}" shows as neutral.`);
+  }
+  if (d.trend !== undefined && d.trend !== null) {
+    const tt = trendText(d.trend);
+    if (tt) seg.trend = tt; else warnings.push('"trend" is up, down, flat or a number; ignored.');
+  }
+  if (typeof d.label === 'string' && cleanText(d.label, 16)) seg.label = cleanText(d.label, 16);
+  if (d.link !== undefined && d.link !== null) {
+    let ok = false;
+    try { const u = new URL(String(d.link)); ok = (u.protocol === 'http:' || u.protocol === 'https:') && !u.username && !u.password && String(d.link).length <= 500; } catch { ok = false; }
+    if (ok) seg.link = new URL(String(d.link)).href; else warnings.push('"link" must be an http(s) URL with no credentials; ignored.');
+  }
+  return { seg, warnings };
+}
+
+/**
+ * Data that is not a status row -> the paths a template could use (scalars, one level deep), for a helpful
+ * "try --template" hint. -> ['open', 'connection.connected', ...] (at most `max`).
+ */
+export function fieldHints(data, max = 12) {
+  const out = [];
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return out;
+  for (const [k, v] of Object.entries(data)) {
+    if (out.length >= max) break;
+    if (!/^[A-Za-z0-9_-]+$/.test(k) || BLOCKED_KEYS.has(k)) continue;
+    if (v !== null && typeof v !== 'object') out.push(k);
+    else if (Array.isArray(v)) out.push(`count(${k})`);
+    else if (v && typeof v === 'object') for (const [k2, v2] of Object.entries(v)) {
+      if (out.length >= max) break;
+      if (/^[A-Za-z0-9_-]+$/.test(k2) && !BLOCKED_KEYS.has(k2) && v2 !== null && typeof v2 !== 'object') out.push(`${k}.${k2}`);
+    }
+  }
+  return out;
+}
+
+/** seg -> the one-line text (screen context, /row list, tests): "value text trend". */
+export const segText = (seg) => [seg.value, seg.text, seg.trend].filter(Boolean).join(' ');
+
+/**
+ * A row + the raw text its source returned -> { ok, text, seg, warnings } | { ok: false, error }.
+ * With a template: the template fills from the data. Without one: the status-row contract.
+ */
+export function rowValue(row, raw) {
+  // Empty output is not a value (owner frame 2026-10-17: "QPE │" drew blank). The engine keeps the last good value.
+  if (!cleanText(raw)) return { ok: false, error: 'no output' };
+  const data = dataFrom(raw);
+  if (row.template) {
+    const text = evalTemplate(row.template, data);
+    return text.trim() ? { ok: true, text, seg: null, warnings: [] } : { ok: false, error: 'no output' };
+  }
+  const p = parseStatusRow(data);
+  if (p.error) return { ok: false, error: p.error };
+  return { ok: true, text: segText(p.seg), seg: p.seg, warnings: p.warnings };
+}
+
+/* ---- row records -------------------------------------------------------------------------- */
+
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,23}$/;
+export const validId = (s) => ID_RE.test(String(s ?? ''));
+export const SOURCE_TYPES = ['url', 'cmd', 'quox', 'plugin'];
+export const QUOX_SERVICES = ['auth', 'collector'];
+const PLUGIN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/** A quox or plugin path -> an error string or null. GET only, no traversal, no other host. */
+function badPath(path, { absolute }) {
+  if (!path) return 'The path is empty.';
+  if (path.length > 300) return 'That path is too long (300 characters).';
+  if (/[\s#\\]/.test(path) || /[\u0000-\u001f\u007f]/.test(path)) return 'A path has no spaces, # or backslashes.';
+  if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith('//')) return 'A path, not a URL: it is read from your own Quox.';
+  if (path.split(/[/?]/).some((seg) => seg === '..' || seg === '.' || /%2e%2e|%2f/i.test(seg))) return 'A path cannot step out with .. or encoded slashes.';
+  if (absolute && !path.startsWith('/api/')) return 'A quox path starts with /api/.';
+  if (!/^[A-Za-z0-9._~\-/?=&%{}:,+]+$/.test(path)) return 'That path has characters a row path cannot use.';
+  return null;
+}
+
+/** True when a row reads data that is safe to sync and share (no shell). */
+export const syncable = (r) => r?.source?.type !== 'cmd';
+
+// Names a secret-bearing query parameter, or a value that looks like a token.
+const SECRET_KEY_RE = /^(.*[_-])?(token|access[_-]?token|api[_-]?key|apikey|key|secret|password|passwd|pwd|sig|signature|auth|authorization|session|sessionid|jwt|bearer|credential|creds)$/i;
+const SECRET_VAL_RE = /^(eyJ[A-Za-z0-9_-]{8,}\.|(sk|pk|ghp|gho|xox[abp]|qmcp)[-_][A-Za-z0-9]|[A-Fa-f0-9]{32,}$|[A-Za-z0-9+/_-]{40,}={0,2}$)/;
+
+/**
+ * Never put a secret in a row definition (it syncs to your account and can be shared). -> a reason or null.
+ * Checked when a row is ADDED, EDITED, IMPORTED or SHARED; a stored row is never silently dropped for it.
+ */
+export function secretInRow(v) {
+  const src = v?.source || {};
+  const target = src.type === 'url' ? src.url : (src.type === 'quox' || src.type === 'plugin') ? src.path : null;
+  if (typeof target === 'string') {
+    let q = '';
+    try { q = src.type === 'url' ? new URL(target).search : (target.split('?')[1] || ''); } catch { q = ''; }
+    for (const [k, val] of new URLSearchParams(q)) {
+      if (SECRET_KEY_RE.test(k)) return `The "${k}" parameter looks like a secret. Rows never carry secrets: use a ${src.type === 'url' ? 'quox or plugin row (your session is used)' : 'path without it'} or a local command that reads the secret itself.`;
+      if (SECRET_VAL_RE.test(val)) return `The value of "${k}" looks like a token. Rows never carry secrets.`;
+    }
+  }
+  if (src.type === 'cmd' && typeof src.cmd === 'string' && /(authorization:\s*bearer\s+\S{8,}|\b(sk|ghp|xox[abp]|qmcp)[-_][A-Za-z0-9]{8,}|\beyJ[A-Za-z0-9_-]{8,}\.)/i.test(src.cmd))
+    return 'That command has a token written into it. Read the secret inside your script (from a file or the vault), never in the row.';
+  return null;
+}
+
+/** Validate one row -> { row } | { error }. Strict: used for typed input and for everything stored. */
+export function checkRow(v) {
+  const id = typeof v?.id === 'string' ? v.id.trim() : '';
+  if (!validId(id)) return { error: 'Row ids are letters, digits, - and _ (24 at most).' };
+  const src = v?.source;
+  const every = src?.every === undefined ? '60s' : String(src.every).trim();
+  if (parseEvery(every) === null) return { error: `"${every}" is not an interval. Use 30s, 5m or 1h (5s to 1 day).` };
+  let source;
+  if (src?.type === 'url') {
+    let u;
+    try { u = new URL(String(src.url)); } catch { return { error: 'That is not a URL.' }; }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return { error: 'Only http and https URLs.' };
+    if (u.username || u.password) return { error: 'Put no credentials in the URL; none are sent.' };
+    if (String(src.url).length > 500) return { error: 'That URL is too long.' };
+    source = { type: 'url', url: u.href, every };
+  } else if (src?.type === 'cmd') {
+    const cmd = typeof src.cmd === 'string' ? src.cmd.trim() : '';
+    if (!cmd || cmd.length > 500) return { error: 'The command must be 1 to 500 characters.' };
+    source = { type: 'cmd', cmd, every };
+  } else if (src?.type === 'quox') {
+    const service = src.service === undefined ? 'auth' : String(src.service);
+    if (!QUOX_SERVICES.includes(service)) return { error: `A quox row reads the ${QUOX_SERVICES.join(' or ')} service.` };
+    const path = typeof src.path === 'string' ? src.path.trim() : '';
+    const bad = badPath(path, { absolute: true });
+    if (bad) return { error: bad };
+    source = { type: 'quox', service, path, every };
+  } else if (src?.type === 'plugin') {
+    const plugin = typeof src.plugin === 'string' ? src.plugin.trim() : '';
+    if (!PLUGIN_ID_RE.test(plugin)) return { error: 'A plugin id is letters, digits, dots, - and _ (64 at most).' };
+    const path = typeof src.path === 'string' ? src.path.trim().replace(/^\/+/, '') : '';
+    const bad = badPath(path, { absolute: false });
+    if (bad) return { error: bad };
+    source = { type: 'plugin', plugin, path, every };
+  } else return { error: `A row source is one of ${SOURCE_TYPES.join(', ')}.` };
+  // No template = the status-row contract ({ text, value?, tone?, trend?, link? }, or plain text).
+  const template = typeof v.template === 'string' ? v.template.trim() : '';
+  if (template.length > 300) return { error: 'The template is too long (300 characters).' };
+  if (template) { const bad = checkTemplate(template); if (bad) return { error: bad }; }
+  const row = { id, source };
+  if (template) row.template = template;
+  const label = typeof v.label === 'string' ? v.label.trim().slice(0, 24) : '';
+  if (label) row.label = label;
+  if (v.colour !== undefined && v.colour !== null && v.colour !== '') {
+    if (!ROLES.includes(v.colour)) return { error: `Colour is one of ${ROLES.join(', ')}.` };
+    if (v.colour !== 'prose') row.colour = v.colour;
+  }
+  return { row };
+}
+
+/**
+ * Anything stored or received -> clean rows (bad ones dropped, duplicate ids dropped, capped).
+ * cmd rows survive ONLY with { cmd: true }; the server copy is always read without it.
+ */
+export function normRows(v, { cmd = false } = {}) {
+  const out = [];
+  for (const x of Array.isArray(v) ? v : Array.isArray(v?.rows) ? v.rows : []) {
+    if (x?.source?.type === 'cmd' && !cmd) continue;
+    const r = checkRow(x);
+    if (r.row && !out.some((o) => o.id === r.row.id) && out.length < MAX_ROWS) out.push(r.row);
+  }
+  return out;
+}
+
+/** url = every row that syncs (url, quox, plugin); cmd = this machine only. */
+export const splitRows = (rows) => ({
+  url: rows.filter(syncable),
+  cmd: rows.filter((r) => !syncable(r))
+});
+export const rowLabel = (r) => r.label || r.id;
+
+/* ---- /row argument parsing ---------------------------------------------------------------- */
+
+/** Quote-aware split: "double" and 'single' quotes group, \" escapes. -> tokens, or null on an open quote. */
+export function tokenize(s) {
+  const out = [];
+  let i = 0;
+  const str = String(s ?? '');
+  while (i < str.length) {
+    if (/\s/.test(str[i])) { i++; continue; }
+    let tok = '';
+    if (str[i] === '"' || str[i] === "'") {
+      const q = str[i++];
+      let closed = false;
+      while (i < str.length) {
+        if (str[i] === '\\' && i + 1 < str.length && (str[i + 1] === q || str[i + 1] === '\\')) { tok += str[i + 1]; i += 2; continue; }
+        if (str[i] === q) { closed = true; i++; break; }
+        tok += str[i++];
+      }
+      if (!closed) return null;
+    } else while (i < str.length && !/\s/.test(str[i])) tok += str[i++];
+    out.push(tok);
+  }
+  return out;
+}
+
+/**
+ * The words after /row -> { kind, ... }. kinds: list add rm on off test error.
+ * add: /row add <id> url <url> "<template>" [every 60s] [label X] [colour role]
+ *      /row add <id> cmd "<shell cmd>" "<template>" [every 60s] ...
+ */
+export function parseRowCmd(arg) {
+  const toks = tokenize(arg);
+  if (!toks) return { kind: 'error', text: 'A quote is not closed.' };
+  const sub = (toks[0] || 'list').toLowerCase();
+  if (sub === 'list' || sub === 'ls') return { kind: 'list' };
+  if (sub === 'on' || sub === 'off') return { kind: sub };
+  if (['rm', 'remove', 'del', 'delete'].includes(sub))
+    return toks[1] ? { kind: 'rm', id: toks[1] } : { kind: 'error', text: 'Usage: /row rm <id>' };
+  if (sub === 'test') return toks[1] ? { kind: 'test', id: toks[1] } : { kind: 'error', text: 'Usage: /row test <id>' };
+  if (sub === 'new') return { kind: 'new' };
+  if (sub === 'reload') return { kind: 'reload' };
+  if (sub === 'edit') return toks[1] ? { kind: 'edit', id: toks[1] } : { kind: 'error', text: 'Usage: /row edit <id>' };
+  if (sub === 'add') {
+    const USAGE = 'Usage: /row add <id> url <url> "<template>" [every 60s]   or   /row add <id> cmd "<shell cmd>" "<template>"';
+    let [, id, type, target, template, ...rest] = toks;
+    // No template (nothing after the target, or straight into an option) = the status-row contract.
+    if (template !== undefined && ['every', 'label', 'colour', 'color'].includes(template.toLowerCase()) && rest.length % 2 === 1) { rest = [template, ...rest]; template = ''; }
+    if (template === undefined && target !== undefined) template = '';
+    if (!id || !target || (type !== 'url' && type !== 'cmd')) return { kind: 'error', text: USAGE };
+    const opts = {};
+    for (let i = 0; i < rest.length; i += 2) {
+      const k = (rest[i] || '').toLowerCase();
+      if (!['every', 'label', 'colour', 'color'].includes(k) || rest[i + 1] === undefined)
+        return { kind: 'error', text: `Unexpected "${rest[i]}". Options: every 60s, label <text>, colour <role>.` };
+      opts[k === 'color' ? 'colour' : k] = rest[i + 1];
+    }
+    const row = { id, source: { type, ...(type === 'url' ? { url: target } : { cmd: target }), ...(opts.every ? { every: opts.every } : {}) } };
+    if (template) row.template = template;
+    if (opts.label) row.label = opts.label;
+    if (opts.colour) row.colour = opts.colour;
+    return { kind: 'add', row };
+  }
+  return { kind: 'error', text: 'Usage: /row [new | add | list | edit <id> | rm <id> | test <id> | reload | on | off]' };
+}
+
+/* ---- fetching and running ----------------------------------------------------------------- */
+
+/** Plain fetch of an http(s) URL, no credentials, 15 s timeout, body capped. -> text. Throws a short reason. */
+export async function plainFetch(url, { timeoutMs = URL_TIMEOUT_MS, fetchImpl = globalThis.fetch } = {}) {
+  let u;
+  try { u = new URL(url); } catch { throw new Error('bad URL'); }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error('only http(s)');
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeoutMs);
+  try {
+    const r = await fetchImpl(u.href, { signal: ctl.signal, redirect: 'follow', credentials: 'omit', headers: { accept: 'application/json, text/plain;q=0.9, */*;q=0.5' } });
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    const text = await r.text();
+    const t0 = text.trimStart();
+    if (t0.startsWith('{') || t0.startsWith('[')) {
+      if (text.length > JSON_CAP) throw new Error(`response too large (${Math.round(text.length / 1024)} KB)`);
+      return text;
+    }
+    return text.length > OUTPUT_CAP * 4 ? text.slice(0, OUTPUT_CAP * 4) : text;
+  } catch (e) {
+    if (ctl.signal.aborted) throw new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`);
+    if (/^HTTP \d+|^response too large/.test(e?.message)) throw e;
+    const code = e?.cause?.code || e?.code || '';
+    throw new Error(code ? String(code) : 'unreachable');
+  } finally { clearTimeout(t); }
+}
+
+/** Run a shell command via the user's shell: timeout, output cap. -> stdout. Throws a short reason. */
+export function runShell(cmd, { timeoutMs = FETCH_TIMEOUT_MS, shell = process.env.SHELL || '/bin/sh', exec = execFile } = {}) {
+  return new Promise((resolve, reject) => {
+    exec(shell, ['-c', cmd], { timeout: timeoutMs, maxBuffer: OUTPUT_CAP, killSignal: 'SIGKILL', windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] }, (err, stdout) => {
+      if (!err) return resolve(String(stdout ?? ''));
+      if (err.killed || err.signal === 'SIGKILL') return reject(new Error(`timed out after ${Math.round(timeoutMs / 1000)}s`));
+      if (/maxBuffer/i.test(err.message || '') || err.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return reject(new Error('output too large'));
+      reject(new Error(typeof err.code === 'number' ? `exit ${err.code}` : 'could not run'));
+    });
+  });
+}
+
+/* ---- the engine --------------------------------------------------------------------------- */
+
+/** Next retry delay after `fails` consecutive failures: 5 s doubling, capped at 10 minutes. */
+export const backoffMs = (fails) => Math.min(BACKOFF_CAP_MS, 5000 * 2 ** Math.max(0, fails - 1));
+
+const sameRow = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/**
+ * Owns the polling. Injected: fetchUrl(url) -> text, runCmd(cmd) -> text, onChange(), timer fns (tests).
+ * Never blocks input: every poll is async and a failure is state, not an exception.
+ */
+export function createRowEngine({ fetchUrl, runCmd, fetchQuox = () => Promise.reject(new Error('not available here')), onChange = () => {}, now = Date.now, setT = setTimeout, clearT = clearTimeout }) {
+  let rows = [];
+  let enabled = true;
+  let stopped = false;
+  const st = new Map(); // id -> { row, status, text, error, fails, timer, running }
+
+  const note = () => { try { onChange(); } catch { /* a render hiccup never kills polling */ } };
+
+  async function probe(row) {
+    let raw;
+    try {
+      const t = row.source.type;
+      raw = t === 'url' ? await fetchUrl(row.source.url) : t === 'cmd' ? await runCmd(row.source.cmd) : await fetchQuox(row.source);
+    } catch (e) { return { ok: false, error: cleanText(e?.message || 'failed', 60) || 'failed' }; }
+    const v = rowValue(row, raw);
+    return v.ok ? { ok: true, raw: String(raw ?? ''), text: v.text, seg: v.seg, warnings: v.warnings } : { ok: false, raw: String(raw ?? ''), error: v.error.slice(0, 60) };
+  }
+
+  function arm(s, ms) {
+    clearT(s.timer);
+    if (stopped || !enabled) { s.timer = null; return; }
+    s.timer = setT(() => poll(s), ms);
+    s.timer?.unref?.();
+  }
+
+  async function poll(s) {
+    if (stopped || !enabled || s.running || st.get(s.row.id) !== s) return;
+    s.running = true;
+    const r = await probe(s.row);
+    s.running = false;
+    if (stopped || st.get(s.row.id) !== s) return; // removed or replaced while in flight
+    if (r.ok) { s.status = 'ok'; s.text = r.text; s.seg = r.seg || null; s.error = null; s.fails = 0; s.at = now(); arm(s, parseEvery(s.row.source.every) ?? 60000); }
+    else { // s.text and s.at stay: the last good value is still shown
+      s.status = 'error'; s.error = r.error; s.fails += 1; arm(s, backoffMs(s.fails)); }
+    note();
+  }
+
+  return {
+    /** Replace the row set. Unchanged rows keep their state; new or edited ones start at once. */
+    setRows(next) {
+      rows = next.slice(0, MAX_ROWS);
+      const ids = new Set(rows.map((r) => r.id));
+      for (const [id, s] of st) if (!ids.has(id)) { clearT(s.timer); st.delete(id); }
+      for (const row of rows) {
+        const cur = st.get(row.id);
+        if (cur && sameRow(cur.row, row)) continue;
+        if (cur) clearT(cur.timer);
+        const s = { row, status: 'loading', text: '', seg: null, error: null, fails: 0, timer: null, running: false };
+        st.set(row.id, s);
+        if (enabled && !stopped) setT(() => poll(s), 0)?.unref?.();
+      }
+      note();
+    },
+    setEnabled(on) {
+      enabled = Boolean(on);
+      for (const s of st.values()) {
+        if (!enabled) { clearT(s.timer); s.timer = null; }
+        else if (!s.running) { s.status = s.status === 'ok' ? 'ok' : 'loading'; setT(() => poll(s), 0)?.unref?.(); }
+      }
+      note();
+    },
+    isEnabled: () => enabled,
+    /** The rows to draw, in order: [{ row, status, text, error }]. Empty when hidden. */
+    view() { return enabled ? rows.map((r) => st.get(r.id)).filter(Boolean) : []; },
+    state: (id) => st.get(id) || null,
+    probe,
+    stop() { stopped = true; for (const s of st.values()) clearT(s.timer); }
+  };
+}
+
+const ageMark = (ms) => { const s = Math.max(0, Math.floor(ms / 1000)); return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}`; };
+
+/** One row's display -> { text, role }. Pure; the caller clips to the width. */
+export function rowDisplay({ row, status, text, error, at }, now = Date.now()) {
+  if (status === 'error' && text && at != null && now - at <= STALE_MAX_MS)
+    return { text: `${text} · ${ageMark(now - at)} old`, role: row.colour || 'prose' };
+  if (status === 'error') return { text: `⚠ ${rowLabel(row)}: ${String(error || 'failed').slice(0, 40)}`, role: 'error' };
+  if (status === 'loading' || !text) return { text: `${rowLabel(row)} …`, role: row.colour || 'prose' };
+  return { text, role: row.colour || 'prose' };
+}
+
+/** The width a label column takes for these rows (labels align across rows), 0 when none has a label. */
+export const labelWidth = (states) => Math.min(16, Math.max(0, ...(states || []).map((st) => [...String(st?.row?.label || st?.seg?.label || '')].length)));
+
+/**
+ * One row as coloured segments -> [[text, role, bold?]]. A row without a label or contract fields draws exactly
+ * as rowDisplay always has (one run); a labelled or contract row reads `✔ Label │ value text ▲3`. Roles are
+ * palette roles (never a grey): label for the name and separators, value for the number, the tone for the text.
+ */
+export function rowParts(st, { now = Date.now(), labelW = 0 } = {}) {
+  // Never a bare label: an ok state with nothing to show draws as still loading ("QPE …").
+  if (st.status === 'ok' && !String(st.text ?? '').trim() && !st.seg?.value && !st.seg?.text) st = { ...st, status: 'loading' };
+  const d = rowDisplay(st, now);
+  const { row, seg } = st;
+  const live = st.status === 'ok' || (st.status === 'error' && d.role !== 'error');
+  if (!live || st.status === 'loading') return [[d.text, d.role]];
+  const label = row.label || seg?.label || '';
+  if (seg?.cells?.length) { // TUI-QPE: one cells row on its own (quox rows test); RowsBar uses layoutRows
+    const out = label ? [[label + ' ', 'brand', true]] : [];
+    seg.cells.forEach((c, i) => { if (i) out.push([CELL_SEP, 'label']); for (const p of c.parts) out.push(partSeg(p)); });
+    if (st.status === 'error') out.push([` · ${ageMark(now - st.at)} old`, 'warn']);
+    return out;
+  }
+  const toneR = seg?.tone ? toneRole(seg.tone) : null;
+  if (!label && !seg?.tone && !seg?.value && !seg?.trend) return [[d.text, d.role]];
+  const out = [];
+  if (seg?.tone && TONE_GLYPH[seg.tone]) out.push([TONE_GLYPH[seg.tone] + ' ', toneR]);
+  if (label) out.push([label.padEnd(Math.max(labelW, [...label].length)), 'label', true], [' │ ', 'label']);
+  const role = toneR || row.colour || 'prose';
+  if (seg) {
+    if (seg.value) out.push([seg.value, 'value', true]);
+    if (seg.text) out.push([(seg.value ? ' ' : '') + seg.text, role]);
+    if (seg.trend) out.push([' ' + seg.trend, 'label']);
+  } else out.push([st.text, role]);
+  if (st.status === 'error') out.push([` · ${ageMark(now - st.at)} old`, 'warn']);
+  return out;
+}
+
+/** Fit segments into `width` columns (code points), ending in … when cut. */
+export function clipParts(parts, width) {
+  const out = []; let used = 0;
+  const w = Math.max(1, width);
+  for (const part of parts) {
+    const [t, role, bold] = part;
+    const cs = [...String(t)];
+    if (used + cs.length <= w) { out.push(part); used += cs.length; continue; }
+    const room = w - used - 1;
+    if (room > 0) out.push([cs.slice(0, room).join(''), role, bold]);
+    out.push(['…', role, bold]);
+    return out;
+  }
+  return out;
+}
+
+/* ---- cells layout (TUI-QPE) ---------------------------------------------------------------- */
+
+export const CELL_SEP = ' │ ';
+const W = (t) => cellWidth(String(t));
+const cellW = (c) => c.parts.reduce((a, p) => a + W(p.text), 0);
+const cellsW = (cs) => cs.reduce((a, c, i) => a + cellW(c) + (i ? W(CELL_SEP) : 0), 0);
+
+/**
+ * cells -> the cells that fit in `room` columns. Whole items go, lowest `keep` first (a tie drops the rightmost); an
+ * item with no keep stays. If even the kept items do not fit, the line ends at a word boundary with … (never mid-word).
+ */
+/** Drop the one lowest-keep item (a tie drops the rightmost; a part takes its group with it). -> new cells, or null. */
+export function dropLowest(cells) {
+  let best = null;
+  cells.forEach((c, i) => {
+    const cand = (keep, pos, j) => { if (keep == null) return; if (!best || keep < best.keep || (keep === best.keep && pos > best.pos)) best = { keep, pos, i, j }; };
+    cand(c.keep, i * 1000 + 999, -1);
+    c.parts.forEach((p, j) => cand(p.keep, i * 1000 + j, j));
+  });
+  if (!best) return null;
+  const cs = cells.map((c) => ({ ...c, parts: [...c.parts] }));
+  if (best.j < 0) cs.splice(best.i, 1);
+  else {
+    const c = cs[best.i]; const g = c.parts[best.j].group;
+    c.parts = lead(g ? c.parts.filter((p) => p.group !== g) : c.parts.filter((_, j) => j !== best.j));
+    if (!c.parts.length) cs.splice(best.i, 1);
+  }
+  return cs;
+}
+
+export function fitCells(cells, room) {
+  let cs = (cells || []).map((c) => ({ ...c, parts: c.parts.map((p) => ({ ...p })) }));
+  while (cellsW(cs) > room) { const next = dropLowest(cs); if (!next) break; cs = next; }
+  if (cellsW(cs) <= room) return { cells: cs, clipped: false };
+  // Still too wide with only the must-keep items: cut at the last word that fits.
+  const out = []; let used = 0; const max = Math.max(1, room - 1);
+  for (let i = 0; i < cs.length; i++) {
+    const parts = [];
+    if (i) { if (used + W(CELL_SEP) > max) break; used += W(CELL_SEP); }
+    let full = true;
+    for (const p of cs[i].parts) {
+      const w = W(p.text);
+      if (used + w <= max) { parts.push(p); used += w; continue; }
+      const words = p.text.split(/(\s+)/); let t = '';
+      for (const wd of words) { if (used + W(t + wd) > max) break; t += wd; }
+      t = t.replace(/\s+$/, '');
+      if (t.trim()) { parts.push({ ...p, text: t }); used += W(t); } // whole words only, so this is a word boundary
+      full = false; break;
+    }
+    if (parts.length) out.push({ ...cs[i], parts });
+    if (!full) break;
+  }
+  if (!out.length) out.push({ parts: [{ text: '' }] });
+  const last = out[out.length - 1].parts; last[last.length - 1] = { ...last[last.length - 1], text: last[last.length - 1].text.replace(/\s+$/, '') };
+  last.push({ text: '…' });
+  return { cells: out, clipped: true };
+}
+
+/** A cell whose first item was dropped must not start with its joiner (" · CLI 578/958"): trim a leading " · ". */
+const lead = (parts) => (parts.length && /^\s*·\s*/.test(parts[0].text) ? [{ ...parts[0], text: parts[0].text.replace(/^\s*·\s*/, '') }, ...parts.slice(1)] : parts);
+
+/** One part -> a [text, role, bold] segment (the RowsBar shape). Tones are palette roles, never grey. */
+const partSeg = (p) => [p.text, p.tone ? toneRole(p.tone) : 'prose', Boolean(p.bold)];
+
+/** States whose seg has cells and something to show. */
+const hasCells = (st) => Boolean(st?.seg?.cells?.length) && (st.status === 'ok' || (st.status === 'error' && st.text));
+
+/**
+ * The rows RowsBar draws at `cols`, in order -> [{ st, parts }]: rows below their min_cols are left out; cells rows
+ * are fitted, and rows sharing a `grid` share a lead (label) column and pad their cells so the separators line up.
+ * Other rows keep the classic rowParts + clipParts path, unchanged.
+ */
+/**
+ * Rows -> one state per drawn line: a row whose seg has `lines` becomes one state per line (ids `<id>.<n>`, the row's
+ * label on the first only, the row's grid unless a line names its own). Other rows pass through unchanged.
+ */
+export function expandLines(states) {
+  const out = [];
+  for (const st of states || []) {
+    const ls = st?.seg?.lines;
+    if (!ls?.length || !(st.status === 'ok' || (st.status === 'error' && st.text))) { out.push(st); continue; }
+    ls.forEach((seg, i) => out.push({ ...st, row: { ...st.row, id: `${st.row.id}.${i + 1}`, label: i === 0 ? st.row.label : '' },
+      text: seg.text, seg: { ...seg, grid: seg.grid || st.seg.grid || `#${st.row.id}`, ...(i === 0 ? {} : { label: undefined }) } }));
+  }
+  return out;
+}
+
+export function layoutRows(states, cols, { now = Date.now() } = {}) {
+  const shown = expandLines(states).filter((st) => !(st?.seg?.minCols && cols < st.seg.minCols)).slice(0, MAX_LINES);
+  const room = Math.max(1, cols - 2);
+  const labelW = labelWidth(shown.filter((st) => !hasCells(st)));
+  const groups = new Map();
+  for (const st of shown) if (hasCells(st)) { const g = st.seg.grid || `#${st.row.id}`; if (!groups.has(g)) groups.set(g, []); groups.get(g).push(st); }
+  const done = new Map();
+  for (const list of groups.values()) {
+    const leadOf = (st) => String(st.row.label || st.seg.label || '');
+    const leadW = Math.min(16, Math.max(0, ...list.map((st) => W(leadOf(st)))));
+    const leadCols = leadW ? leadW + 1 : 0;
+    const roomL = room - leadCols;
+    const base = list.map((st) => {
+      const cells = st.seg.cells.map((c) => ({ ...c, parts: [...c.parts] }));
+      return cells;
+    });
+    // `keep` is ONE priority across the grid. The layout drops the shortest prefix of the grid-wide order (lowest keep
+    // first; a tie drops the rightmost, then the lower row) that lets every row fit with its columns lined up. A wider
+    // window can only shorten that prefix, so it never shows less (2026-10-20: a greedy per-row pass did, at 68/69 cols).
+    const units = [];
+    base.forEach((cells, r) => cells.forEach((c, i) => {
+      if (c.keep != null) units.push({ r, i, j: -1, keep: c.keep, pos: i * 1000 + 999 });
+      const seenG = new Set();
+      c.parts.forEach((p, j) => {
+        if (p.keep == null) return;
+        if (p.group) { if (seenG.has(p.group)) return; seenG.add(p.group); }
+        units.push({ r, i, j, group: p.group, keep: p.keep, pos: i * 1000 + j });
+      });
+    }));
+    units.sort((x, y) => x.keep - y.keep || y.pos - x.pos || y.r - x.r);
+    const build = (k) => {
+      const gone = units.slice(0, k);
+      return base.map((cells, r) => cells.map((c, i) => {
+        if (gone.some((u) => u.r === r && u.i === i && u.j < 0)) return null;
+        const parts = c.parts.filter((p, j) => !gone.some((u) => u.r === r && u.i === i && u.j >= 0 && (u.group ? p.group === u.group : u.j === j)));
+        return parts.length ? { ...c, parts: lead(parts) } : null;
+      }).filter(Boolean));
+    };
+    const colWidths = (rows) => { const w = []; for (const cs of rows) cs.forEach((c, i) => { if (i < cs.length - 1) w[i] = Math.max(w[i] || 0, cellW(c)); }); return w; };
+    const alignedW = (cs, w) => cs.reduce((a, c, i) => a + (i < cs.length - 1 ? Math.max(w[i] || 0, cellW(c)) : cellW(c)) + (i ? W(CELL_SEP) : 0), 0);
+    let rows = null;
+    for (let k = 0; k <= units.length; k++) {
+      const cand = build(k);
+      // A row whose must-keep items alone are too wide is cut at a word below and left out of the column widths.
+      const over = cand.map((cs) => cellsW(cs) > roomL);
+      const w = colWidths(cand.filter((_, r) => !over[r]));
+      if (cand.every((cs, r) => over[r] ? !units.slice(k).some((u) => u.r === r) : alignedW(cs, w) <= roomL)) { rows = cand; break; }
+    }
+    rows ??= build(units.length);
+    const over = rows.map((cs) => cellsW(cs) > roomL);
+    const colW = colWidths(rows.filter((_, r) => !over[r]));
+    list.forEach((st, r) => {
+      const f = over[r] ? fitCells(rows[r], roomL) : { cells: rows[r], clipped: false };
+      const pads = f.cells.map((c, i) => (!f.clipped && i < f.cells.length - 1 ? Math.max(0, (colW[i] || 0) - cellW(c)) : 0));
+      const out = [];
+      if (leadCols) out.push([leadOf(st) + ' '.repeat(Math.max(0, leadW - W(leadOf(st)))) + ' ', 'brand', true]);
+      f.cells.forEach((c, i) => {
+        if (i) out.push([CELL_SEP, 'label']);
+        for (const p of c.parts) out.push(partSeg(p));
+        if (pads[i]) out.push([' '.repeat(pads[i]), 'prose']);
+      });
+      done.set(st, out);
+    });
+    // The age of a stale value is said ONCE per grid and only in space the fit left over, never in the fit budget:
+    // appended per line it pushed whole items out every minute as the data aged (coordinator 2026-10-20 03:39Z).
+    // It goes on the first stale line that has room, else the line with the most room; with no room it is left out.
+    const stale = list.filter((st) => st.status === 'error' && st.at != null);
+    if (stale.length) {
+      const age = ` · ${ageMark(now - Math.min(...stale.map((st) => st.at)))} old`;
+      const used = (st) => done.get(st).reduce((a, [t]) => a + W(t), 0);
+      const roomOf = (st) => room - used(st);
+      const pick = stale.find((st) => roomOf(st) >= W(age)) || [...list].sort((a, b) => roomOf(b) - roomOf(a))[0];
+      if (pick && roomOf(pick) >= W(age)) done.get(pick).push([age, 'warn']);
+    }
+  }
+  return shown.map((st) => ({ st, parts: done.get(st) || clipParts(rowParts(st, { now, labelW }), room) }));
+}
+
+/** /qpe rows N: keep the first n rows of a grid (0 hides the grid). Rows not in the grid are untouched. */
+export function limitGrid(states, grid, n) {
+  if (n == null || !Number.isInteger(n) || n < 0) return states;
+  let seen = 0;
+  return (states || []).filter((st) => st?.seg?.grid !== grid || ++seen <= n);
+}
+
+/* ---- local-only store for cmd rows -------------------------------------------------------- */
+
+export const localRowsFile = () => join(homedir(), '.config', 'quox', 'quoxon-rows.local.json');
+
+/** The local cmd rows. Never throws. */
+export function loadLocalCmdRows(file = localRowsFile()) {
+  try { return normRows(JSON.parse(readFileSync(file, 'utf8')), { cmd: true }).filter((r) => r.source.type === 'cmd'); }
+  catch { return []; }
+}
+/** -> true when written. Only cmd rows are ever written here. */
+export function saveLocalCmdRows(rows, file = localRowsFile()) {
+  try {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify({ rows: rows.filter((r) => r.source.type === 'cmd') }, null, 2), { mode: 0o600 });
+    return true;
+  } catch { return false; }
+}
+
+
+/* ---- share and import --------------------------------------------------------------------- */
+
+export const BUNDLE_KIND = 'quox.status-rows';
+
+/**
+ * Rows -> a share bundle. ONLY syncable rows go in: a command row runs a shell on the machine that holds it and is
+ * never shared (it is listed in `skipped`). A row that names a secret is refused (in `refused`).
+ */
+export function shareBundle(rows) {
+  const out = []; const skipped = []; const refused = [];
+  for (const r of rows || []) {
+    if (!syncable(r)) { skipped.push(r.id); continue; }
+    const why = secretInRow(r);
+    if (why) { refused.push({ id: r.id, why }); continue; }
+    out.push(r);
+  }
+  return { bundle: { kind: BUNDLE_KIND, version: 1, rows: out }, skipped, refused };
+}
+
+/**
+ * Untrusted JSON -> { rows, commands, errors }. rows are syncable and valid; commands are cmd rows, NEVER added by
+ * an import on their own (the caller shows each command and needs a person to say yes to it, one by one).
+ */
+export function readBundle(input) {
+  let v = input;
+  if (typeof v === 'string') { try { v = JSON.parse(v); } catch { return { rows: [], commands: [], errors: ['That is not JSON.'] }; } }
+  const list = Array.isArray(v) ? v : v && typeof v === 'object' && (v.kind === undefined || v.kind === BUNDLE_KIND) && Array.isArray(v.rows) ? v.rows : null;
+  if (!list) return { rows: [], commands: [], errors: [`Not a status-row bundle (expected {"kind":"${BUNDLE_KIND}","rows":[...]}).`] };
+  const rows = []; const commands = []; const errors = [];
+  for (const x of list.slice(0, 20)) {
+    const c = checkRow(x);
+    const id = cleanText(x?.id, 24) || '?';
+    if (c.error) { errors.push(`${id}: ${c.error}`); continue; }
+    const why = secretInRow(c.row);
+    if (why) { errors.push(`${id}: ${why}`); continue; }
+    (syncable(c.row) ? rows : commands).push(c.row);
+  }
+  return { rows, commands, errors };
+}