quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/slash/settings.js

@@ -5,18 +5,24 @@
  * which case the shell wins and the card says so.
  */
 import { PROFILE_IDS } from '../sound/mapping.js';
+import { LEVELS, DEFAULT_LEVEL, normaliseLevel } from '../motion/level.js';
 
 // Captured at import, before anything here writes it: what the user's shell set.
-const SHELL = { theme: process.env.QUOX_THEME || null, motion: process.env.QUOX_REDUCED_MOTION || null };
+const SHELL = {
+  theme: process.env.QUOX_THEME || null,
+  motion: process.env.QUOX_REDUCED_MOTION === '1' ? 'quiet' : (normaliseLevel(process.env.QUOX_MOTION) || null),
+  motionVar: process.env.QUOX_REDUCED_MOTION === '1' ? 'QUOX_REDUCED_MOTION' : 'QUOX_MOTION',
+};
 
 
 /** The settings this build can honour. Sound is the /sound controller's own profile (server-side soundProfile). */
 export function settingsList({ sound = true } = {}) {
   return [
     { id: 'theme', label: 'Theme', values: ['auto', 'dark', 'light'], def: 'auto', help: 'auto follows your terminal background' },
-    { id: 'motion', label: 'Motion', values: ['full', 'reduced'], def: 'full', help: 'reduced stills the animations' },
+    { id: 'motion', label: 'Motion', values: LEVELS, def: DEFAULT_LEVEL, help: 'quiet stills it all; expressive adds glows; cinematic adds the dragon' },
     ...(sound ? [{ id: 'sound', label: 'Sound', values: PROFILE_IDS, def: 'minimal', help: 'same as /sound; saved to your account' }] : []),
     { id: 'verbose', label: 'Verbose', values: ['off', 'on', 'full'], def: 'on', help: 'protocol lines in turns' },
+    { id: 'slotBell', label: 'Slot bell', values: ['off', 'on'], def: 'on', help: 'a terminal bell when a slot message arrives' },
     { id: 'model', label: 'Model', action: 'model', help: 'Enter opens /model' }
   ];
 }
@@ -27,7 +33,9 @@ export function applySettings(s = {}, env = process.env, shell = SHELL) {
     if (s.theme === 'dark' || s.theme === 'light') env.QUOX_THEME = s.theme; else delete env.QUOX_THEME;
   }
   if (!shell.motion) {
-    if (s.motion === 'reduced') env.QUOX_REDUCED_MOTION = '1'; else delete env.QUOX_REDUCED_MOTION;
+    const level = normaliseLevel(s.motion) || DEFAULT_LEVEL; // pre-levels profiles saved full / reduced
+    if (level === DEFAULT_LEVEL) delete env.QUOX_MOTION; else env.QUOX_MOTION = level;
+    if (level === 'quiet') env.QUOX_REDUCED_MOTION = '1'; else delete env.QUOX_REDUCED_MOTION; // every older reader agrees
   }
   return { themeFromShell: Boolean(shell.theme), motionFromShell: Boolean(shell.motion) };
 }
@@ -38,13 +46,15 @@ export const shellOverrides = () => ({ ...SHELL });
 export function configRows(list, values, { shell = SHELL, model = 'auto' } = {}) {
   return list.map(it => {
     if (it.action === 'model') return { key: it.label, text: model, note: it.help };
-    const v = values[it.id] ?? it.def;
-    const forced = (it.id === 'theme' && shell.theme) ? `QUOX_THEME=${shell.theme} in your shell wins` : (it.id === 'motion' && shell.motion) ? 'QUOX_REDUCED_MOTION in your shell wins' : null;
+    const v = it.id === 'motion' ? (normaliseLevel(values.motion) || it.def) : (values[it.id] ?? it.def);
+    const motionVar = shell.motionVar || 'QUOX_MOTION';
+    const forced = (it.id === 'theme' && shell.theme) ? `QUOX_THEME=${shell.theme} in your shell wins`
+      : (it.id === 'motion' && shell.motion) ? (motionVar === 'QUOX_MOTION' ? `QUOX_MOTION=${shell.motion} in your shell wins` : `${motionVar} in your shell wins`) : null;
     return { key: it.label, text: it.values.map(x => (x === v ? `[${x}]` : x)).join('  '), note: forced || it.help };
   });
 }
 
 export const cycle = (it, cur, dir = 1) => {
-  const i = it.values.indexOf(cur ?? it.def);
+  const i = it.values.indexOf((it.id === 'motion' ? normaliseLevel(cur) : cur) ?? it.def);
   return it.values[(i + dir + it.values.length) % it.values.length];
 };

package/lib/quoxon/slash/spawn.js

@@ -0,0 +1,177 @@
+/**
+ * /spawn: ask HYPERION (agent atlas) for a disposable VM. VMs are requested ONLY by posting to slot `provisioner`
+ * ("VM please <c>c <r>G <d>G for <purpose>") and released with "done <vmid>"; nothing here talks to the pool tool.
+ *
+ * Lifespan is required (max 24h). At most 3 live VMs per session, counted from local state. Leases are stored
+ * locally with their expiry. No server-side slot reminder exists, so expiry is client side: a timer while the TUI
+ * runs, `sweep()` on the next start, and /spawn list shows overdue leases in red.
+ */
+import { askText } from '../ask.js';
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const PROVISIONER = 'provisioner';
+export const MAX_LIVE = 3;
+export const MAX_LIFESPAN_MS = 24 * 3600000;
+const MAX_TIMER = 2147483647;
+export const spawnStatePath = () => join(homedir(), '.config', 'quox', 'quoxon-spawns.json');
+
+const UNIT = '(?:d|days?|h|hrs?|hours?|m|mins?|minutes?)';
+const unitMs = (u) => (/^d/i.test(u) ? 86400000 : /^h/i.test(u) ? 3600000 : 60000);
+
+/** Loose text -> { cores, ramG, diskG, lifespanMs, objective } plus `missing` (names) and `error` when it cannot proceed. */
+export function parseSpawn(text) {
+  let rest = String(text || '').trim();
+  const out = { cores: null, ramG: null, diskG: null, lifespanMs: null, objective: null };
+  const om = new RegExp(`\\b(?:for|to)\\s+(?!\\d+(?:\\.\\d+)?\\s*${UNIT}\\b)(.+)$`, 'i').exec(rest);
+  if (om) { out.objective = om[1].trim(); rest = rest.slice(0, om.index); }
+  const take = (re, fn) => { const m = re.exec(rest); if (m) { fn(m); rest = rest.replace(m[0], ' '); } };
+  take(/(\d+)\s*(?:c|cores?|cpus?|vcpus?)\b/i, (m) => { out.cores = Number(m[1]); });
+  take(/(\d+)\s*g(?:i?b)?\s*(?:of\s+)?(?:ram|mem(?:ory)?)\b/i, (m) => { out.ramG = Number(m[1]); });
+  take(/(\d+)\s*g(?:i?b)?\s*(?:of\s+)?(?:disk|storage)\b/i, (m) => { out.diskG = Number(m[1]); });
+  take(new RegExp(`(?:\\bfor\\s+)?\\b(\\d+(?:\\.\\d+)?)\\s*(${UNIT})\\b`, 'i'), (m) => { out.lifespanMs = Math.round(Number(m[1]) * unitMs(m[2])); });
+  for (let m = /(\d+)\s*g(?:i?b)?\b/i.exec(rest); m && (out.ramG == null || out.diskG == null); m = /(\d+)\s*g(?:i?b)?\b/i.exec(rest)) {
+    if (out.ramG == null) out.ramG = Number(m[1]); else out.diskG = Number(m[1]);
+    rest = rest.replace(m[0], ' ');
+  }
+  if (out.diskG == null) out.diskG = 20;
+  const missing = [];
+  if (!out.cores) missing.push('cores');
+  if (!out.ramG) missing.push('ram');
+  if (!out.lifespanMs) missing.push('lifespan');
+  if (!out.objective) missing.push('objective');
+  if (missing.length) out.missing = missing;
+  if (out.lifespanMs && out.lifespanMs > MAX_LIFESPAN_MS) out.error = 'Lifespan is capped at 24h.';
+  if (out.lifespanMs != null && out.lifespanMs <= 0) out.error = 'Lifespan must be more than zero.';
+  return out;
+}
+
+/** HYPERION's free-text reply -> { vmid, ip, user } | null (no vmid = not a lease). */
+export function parseLease(text) {
+  const t = String(text || '');
+  const v = /vm\s*id\D{0,3}(\d{3,6})/i.exec(t) || /\b(9\d{3})\b/.exec(t);
+  if (!v) return null;
+  const ip = /\b(\d{1,3}(?:\.\d{1,3}){3})\b/.exec(t);
+  const u = /\buser\W{0,3}([a-z_][\w-]*)/i.exec(t);
+  return { vmid: Number(v[1]), ip: ip ? ip[1] : null, user: u ? u[1] : 'hyp' };
+}
+
+export const fmtSpan = (ms) => { const m = Math.round(ms / 60000); return m >= 60 && m % 60 === 0 ? `${m / 60}h` : m >= 60 ? `${Math.floor(m / 60)}h${m % 60}m` : `${Math.max(m, 0)}m`; };
+
+const readAll = (p) => { try { const d = JSON.parse(readFileSync(p, 'utf8')); return Array.isArray(d?.leases) ? d : { leases: [] }; } catch { return { leases: [] }; } };
+const writeAll = (d, p) => { try { mkdirSync(dirname(p), { recursive: true }); const tmp = `${p}.${process.pid}.tmp`; writeFileSync(tmp, JSON.stringify(d, null, 2), { mode: 0o600 }); renameSync(tmp, p); } catch { /* a read-only home never breaks the TUI */ } };
+
+/**
+ * deps: api (slotSay, slotStream), say, session() -> this window's session name, from() -> slot signature,
+ * statePath, now, setTimer/clearTimer (tests), replyTimeoutMs.
+ */
+export function createSpawnCmd({ api, say, session, from, statePath = spawnStatePath(), now = Date.now, setTimer = (fn, ms) => { const t = setTimeout(fn, ms); t.unref?.(); return t; }, clearTimer = clearTimeout, replyTimeoutMs = 180000 }) {
+  const st = { pending: null, waiting: null, timers: new Map() };
+
+  const leases = ({ live = false } = {}) => readAll(statePath).leases.filter((l) => l.session === session() && (!live || l.state === 'live'));
+  const save = (fn) => { const d = readAll(statePath); d.leases = fn(d.leases); writeAll(d, statePath); };
+
+  function arm(l) {
+    clearTimer(st.timers.get(l.vmid));
+    const ms = Math.min(Math.max(l.expiresAt - now(), 0), MAX_TIMER);
+    st.timers.set(l.vmid, setTimer(() => { st.timers.delete(l.vmid); return release(l.vmid, 'lifespan reached'); }, ms));
+  }
+
+  async function release(vmid, why) {
+    const l = leases({ live: true }).find((x) => x.vmid === vmid);
+    if (!l) return say(`No live VM ${vmid} in this session. /spawn list shows yours.`, 'warn');
+    const r = await api.slotSay(PROVISIONER, `done ${vmid}`, { from: from() });
+    if (!r?.ok) return say(`Could not post "done ${vmid}" to ${PROVISIONER}: ${r?.message || 'failed'}. It is still listed; retry /spawn done ${vmid}.`, 'error');
+    clearTimer(st.timers.get(vmid)); st.timers.delete(vmid);
+    save((all) => all.map((x) => (x.vmid === vmid && x.session === l.session ? { ...x, state: 'released', releasedAt: now() } : x)));
+    return say(`VM ${vmid} released to HYPERION (${why}).`, 'ok');
+  }
+
+  function usage() {
+    return say('Usage: /spawn <cores>c <ram>G <disk>G <lifespan> for <objective>   e.g. /spawn 4 cores 8G 20G for 2h to test the installer. Also: /spawn list, /spawn done <vmid>.', 'warn');
+  }
+
+  async function run(arg = '') {
+    const t = String(arg || '').trim();
+    if (!t) return usage();
+    if (/^list$/i.test(t)) return list();
+    const d = /^done\s+(\d+)$/i.exec(t);
+    if (d) return release(Number(d[1]), 'released by you');
+    st.pending = null;
+    const p = parseSpawn(t);
+    if (p.error) return say(p.error, 'warn');
+    if (p.missing?.includes('lifespan')) return say('How long should it live? Lifespan is required (max 24h): add e.g. 2h or 90m, then run /spawn again.', 'warn');
+    if (p.missing) return say(`Missing: ${p.missing.join(', ')}. ${p.missing.includes('objective') ? 'Say what it is for: "for <objective>". ' : ''}Example: /spawn 4c 8G 20G 2h for test the installer`, 'warn');
+    const live = leases({ live: true });
+    if (live.length >= MAX_LIVE) return say(`This session already has ${live.length} live VMs (cap ${MAX_LIVE}). /spawn done <vmid> frees one: ${live.map((l) => l.vmid).join(', ')}.`, 'warn');
+    if (!api.slotSay || !api.slotStream) return say('/spawn needs slots, which this server or mode does not have.', 'warn');
+    st.pending = { p, at: now() };
+    say(`Request a VM from HYPERION: ${p.cores}c ${p.ramG}G ${p.diskG}G, lifespan ${fmtSpan(p.lifespanMs)}, for: ${p.objective}.`, 'accent');
+    say(askText('Go?', { action: `post "VM please ${p.cores}c ${p.ramG}G ${p.diskG}G" to slot ${PROVISIONER}`, reason: `This posts to slot ${PROVISIONER} (HYPERION, agent atlas), signed ${from()}; it releases the VM at expiry.` }), 'ask');
+    return undefined;
+  }
+
+  function answer(text) {
+    const pe = st.pending;
+    if (!pe) return false;
+    const t = String(text || '').trim();
+    if (t.startsWith('/')) { st.pending = null; return false; }
+    st.pending = null;
+    if (/^y(es)?$/i.test(t) && now() - pe.at < 600000) { st.waiting = request(pe.p); return true; }
+    say('Cancelled; nothing posted.', 'dim');
+    return /^no?$/i.test(t);
+  }
+
+  async function request(p) {
+    const me = from();
+    const since = new Date(now() - 1000).toISOString();
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), replyTimeoutMs);
+    try {
+      const stream = api.slotStream(PROVISIONER, { since, excludeFrom: me }, ac.signal);
+      const reader = (async () => {
+        for await (const ev of stream) {
+          if (ev?.type !== 'slot.message' || !ev.message || ev.message.from === me) continue;
+          const lease = parseLease(ev.message.text);
+          if (lease) return { lease, msg: ev.message };
+          if (/refus|cannot|can't|no capacity|denied|unable|error|not allowed/i.test(ev.message.text || '')) return { refusal: ev.message.text };
+        }
+        return null;
+      })();
+      const purpose = `${p.objective} (lifespan ${fmtSpan(p.lifespanMs)}, released by the requester at expiry)`;
+      const r = await api.slotSay(PROVISIONER, `VM please ${p.cores}c ${p.ramG}G ${p.diskG}G for ${purpose}`, { from: me });
+      if (!r?.ok) { ac.abort(); await reader.catch(() => {}); return say(`Could not post to ${PROVISIONER}: ${r?.message || 'failed'}. Nothing was requested.`, 'error'); }
+      say(`Posted to ${PROVISIONER}; waiting for HYPERION's lease reply.`, 'dim');
+      const got = await reader.catch(() => null);
+      if (got?.refusal) return say(`HYPERION: ${got.refusal}`, 'warn');
+      if (!got?.lease) return say(`No lease reply from HYPERION within ${Math.round(replyTimeoutMs / 1000)}s. The request is posted; check slot ${PROVISIONER} (/slot log) and, if a VM arrives, /spawn done <vmid> when finished.`, 'warn');
+      const { lease } = got;
+      const rec = { vmid: lease.vmid, ip: lease.ip, user: lease.user, cores: p.cores, ramG: p.ramG, diskG: p.diskG, objective: p.objective, session: session(), leasedAt: now(), expiresAt: now() + p.lifespanMs, state: 'live' };
+      save((all) => [...all, rec]);
+      arm(rec);
+      say(`VM ${lease.vmid} leased${lease.ip ? ` at ${lease.ip}` : ''}, user ${lease.user}, expires in ${fmtSpan(p.lifespanMs)}.`, 'ok');
+      if (lease.ip) say(`Connect: ssh ${lease.user}@${lease.ip}  (use the key HYPERION's reply names)`, 'ok');
+      say(`Release early with /spawn done ${lease.vmid}.`, 'dim');
+      return undefined;
+    } finally { clearTimeout(timer); }
+  }
+
+  function list() {
+    const all = leases();
+    if (!all.length) return say('No VMs spawned by this session.', 'dim');
+    for (const l of all) {
+      const overdue = l.state === 'live' && l.expiresAt < now();
+      const when = l.state === 'released' ? 'released' : overdue ? `OVERDUE by ${fmtSpan(now() - l.expiresAt)}, releases on /spawn done ${l.vmid} or next start` : `expires in ${fmtSpan(l.expiresAt - now())}`;
+      say(`${l.vmid}  ${l.ip || '?'}  ${l.user}@  ${l.cores}c ${l.ramG}G ${l.diskG}G  ${when}  ${l.objective}`, overdue ? 'error' : l.state === 'released' ? 'dim' : undefined);
+    }
+    return undefined;
+  }
+
+  /** On start: release this session's overdue leases, and re-arm timers for the rest. */
+  async function sweep() {
+    for (const l of leases({ live: true })) { if (l.expiresAt <= now()) await release(l.vmid, 'overdue at start'); else arm(l); }
+  }
+
+  return { run, answer, sweep, leases, get pending() { return st.pending; }, get waiting() { return st.waiting; } };
+}

package/lib/quoxon/slash/stepUp.js

@@ -0,0 +1,274 @@
+/**
+ * QUOXON-STEPUP: the human step-up PIN, TUI side.
+ *
+ * Why this exists: a typed "y" cannot prove a person typed it (an agent can drive this terminal, and some
+ * hold a human profile's CLI login). The SERVER decides what needs a person (agent-raised or high-risk
+ * approvals, policy overrides) and refuses with 403 step_up_required. This module only collects a PIN,
+ * trades it for a short-lived step-up token (POST /api/me/step-up) and carries that token on the retry.
+ * Nothing here is a security boundary on its own: it is the front half of a server-enforced check.
+ *
+ * The PIN rules, all deliberate:
+ *   - the digits live in a closure box; they never enter dispatch, the composer buffer, history, the
+ *     undo/redo stacks, the dev transcript, the observer, or any log; the box is zeroed on every exit
+ *   - the card renders a COUNT of filled dots, never a digit
+ *   - 3 wrong tries lock PIN entry for this window (the server also rate-limits per user and locks)
+ *   - agent logins never get a PIN field: they are told a person must approve
+ */
+import { graphemes } from '../textBuffer.js';
+
+export const WINDOW_MS = 10 * 60 * 1000;
+export const MAX_TRIES = 3;
+export const PIN_LEN = 6;
+export const BEAT_MS = 300;       // cosmetic floor for the "verifying" beat; the request itself is real
+export const RESULT_HOLD_MS = 900; // how long AUTHORISED / DENIED stays on screen
+export const LOCK_MS = WINDOW_MS;  // local lock for this window after MAX_TRIES wrong tries
+export const NEEDS_PERSON = 'needs a person: approve from your phone or a human session';
+export const NO_PIN_LINE = 'Set a PIN in the dashboard: Settings > Account > Approval PIN';
+
+/** The PIN digits. Closure only: no accessor but take(), nothing serialisable. */
+export function createPinBox() {
+  let d = '';
+  return {
+    push(t) { for (const ch of String(t || '')) { if (d.length >= PIN_LEN) break; if (ch >= '0' && ch <= '9') d += ch; } return d.length; },
+    backspace() { d = d.slice(0, -1); return d.length; },
+    clear() { d = ''; },
+    count: () => d.length,
+    take() { const out = d; d = ''; return out; },
+    toJSON: () => '[pin]',
+    toString: () => '[pin]',
+    [Symbol.for('nodejs.util.inspect.custom')]: () => '[pin]'
+  };
+}
+
+export const mmss = (ms) => { const s = Math.max(0, Math.ceil(ms / 1000)); return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`; };
+
+/** Terminal cell width: emoji-presentation glyphs take two cells. */
+export function cellWidth(s) {
+  let w = 0;
+  for (const g of graphemes(String(s ?? ''))) w += /\p{Emoji_Presentation}/u.test(g.text) ? 2 : 1;
+  return w;
+}
+
+
+
+/** One-line collapse under this many columns. */
+export const NARROW_COLS = 50;
+export const CARD_W = 58;
+/** Below this many columns the card is drawn still: no pulse, no shimmer. */
+export const ANIM_MIN_COLS = 60;
+
+/** Word-wrap to `w` cells; a word longer than a line is split, nothing is ever dropped. */
+export function wrapCells(text, w) {
+  const out = []; let cur = '';
+  const push = () => { if (cur) out.push(cur); cur = ''; };
+  for (const word of String(text ?? '').split(/\s+/).filter(Boolean)) {
+    let rest = word;
+    while (cellWidth(rest) > w) { // hard-split an over-long word
+      push(); let part = ''; let n = 0;
+      for (const g of graphemes(rest)) { const gw = cellWidth(g.text); if (n + gw > w) break; part += g.text; n += gw; }
+      out.push(part); rest = rest.slice(part.length);
+    }
+    if (!rest) continue;
+    if (cur && cellWidth(cur) + 1 + cellWidth(rest) > w) push();
+    cur = cur ? `${cur} ${rest}` : rest;
+  }
+  push();
+  return out;
+}
+
+/**
+ * Pure: the card as lines of [{ text, role? }] segments. roles: gold (frame, title, filled slots, countdown),
+ * prose (ink, empty slots, subject), ok, error, key (the per-digit pulse and the verifying sweep). Never grey.
+ * `view` carries counts only, never digits. Optional animation inputs, both plain numbers: `pulse` (slot index
+ * just filled) and `tick` (shimmer frame). Without them the card is static, which is what narrow, slow and
+ * NO_COLOR terminals get.
+ */
+export function cardLines(view, cols) {
+  const { phase, filled = 0, subject = {}, tries = MAX_TRIES, offset = 0, until = 0, now = 0, error = null, pulse = -1, tick = null } = view;
+  const shown = phase === 'verifying' || phase === 'ok' ? PIN_LEN : filled; // the box was taken at submit: 6 were typed
+  const dots = Array.from({ length: PIN_LEN }, (_, i) => (i < shown ? '●' : '○'));
+  const shift = offset ? 1 : 0; // the "tiny shake": one redraw one cell to the right
+  const verifyText = '▰▰▰▰ verifying';
+  const status = (() => {
+    switch (phase) {
+      case 'verifying': {
+        if (tick == null) return [{ text: verifyText, role: 'gold' }];
+        const chars = [...verifyText]; const at = tick % (chars.length + 3);
+        return chars.map((ch, i) => ({ text: ch, role: i >= at - 2 && i <= at ? 'text' : 'gold' }));
+      }
+      case 'ok': return [{ text: '✔ AUTHORISED', role: 'ok' }, { text: ` · human present for ${mmss(until - now)}`, role: 'gold' }];
+      case 'denied': return [{ text: `✖ DENIED · ${tries} ${tries === 1 ? 'try' : 'tries'} left`, role: 'error' }];
+      case 'locked': return [{ text: '⛔ LOCKED · use your phone or a human session', role: 'error' }];
+      case 'nopin': return [{ text: NO_PIN_LINE, role: 'error' }];
+      case 'agent': return [{ text: NEEDS_PERSON, role: 'error' }];
+      default: return null;
+    }
+  })();
+  const pinSeg = [{ text: 'PIN  ', role: 'prose' }, ...dots.flatMap((d, i) => [{ text: d, role: d === '●' ? 'gold' : 'prose' }, { text: i < PIN_LEN - 1 ? ' ' : '', role: 'prose' }])];
+  const segW = (segs) => segs.reduce((n, s) => n + cellWidth(s.text), 0);
+  const riskSeg = (r) => (r === 'high' || r === 'urgent' ? { text: String(r), role: 'error' } : { text: String(r), role: 'prose' });
+
+  if (cols < NARROW_COLS) { // one line: no frame, nothing lost that matters
+    const head = [{ text: '🔐 ', role: 'gold' }];
+    if (status) return [[...head, ...status]];
+    return [[...head, ...pinSeg, { text: ' · Esc cancels', role: 'prose' }]];
+  }
+
+  const W = Math.min(CARD_W, cols);
+  const inner = W - 2;
+  const row = (segs, sh = 0) => { // │ + content centred + │; `sh` nudges it right (the shake)
+    const used = segW(segs);
+    const lp = Math.max(0, Math.floor((inner - used) / 2) + sh);
+    return [{ text: '│', role: 'gold' }, { text: ' '.repeat(lp), role: 'prose' }, ...segs, { text: ' '.repeat(Math.max(0, inner - used - lp)), role: 'prose' }, { text: '│', role: 'gold' }];
+  };
+  const blank = () => row([{ text: '', role: 'prose' }]);
+  const title = view.title || 'AUTHORISATION REQUIRED';
+  const topHead = `╭─ 🔐 ${title} `;
+  const top = [{ text: topHead + '─'.repeat(Math.max(1, W - 1 - cellWidth(topHead))) + '╮', role: 'gold' }];
+  const footText = phase === 'locked' || phase === 'agent' || phase === 'nopin' ? ' esc closes ' : ' a person must confirm this · Esc cancels ';
+  const foot = [{ text: '╰─' + footText + '─'.repeat(Math.max(1, W - 3 - cellWidth(footText))) + '╯', role: 'gold' }];
+
+  // The six PIN slots: three rows tall, heavy gold border once filled, a teal flash on the digit just typed,
+  // a teal sweep while verifying, green ticks when authorised, red when denied.
+  const slotRows = () => {
+    const rows = [[], [], []];
+    for (let i = 0; i < PIN_LEN; i++) {
+      const full = i < shown;
+      let role = full ? 'gold' : 'prose'; let mid = full ? '◉' : ' ';
+      if (phase === 'input' && i === pulse && full) role = 'key';
+      if (phase === 'verifying' && tick != null && i === tick % (PIN_LEN + 2)) role = 'key';
+      if (phase === 'ok') { role = 'ok'; mid = '✔'; }
+      if (phase === 'denied') { role = 'error'; mid = '✖'; }
+      const heavy = full || phase === 'denied';
+      const [t, m, b] = heavy ? ['┏━━━┓', `┃ ${mid} ┃`, '┗━━━┛'] : ['╭───╮', '│   │', '╰───╯'];
+      const gap = i < PIN_LEN - 1 ? ' ' : '';
+      rows[0].push({ text: t + gap, role }); rows[1].push({ text: m + gap, role }); rows[2].push({ text: b + gap, role });
+    }
+    return rows.map((r) => row(r, shift));
+  };
+
+  const out = [top, blank()];
+  const innerW = inner - 4;
+  for (const l of wrapCells(subject.line1 || '', innerW)) out.push(row([{ text: l, role: 'prose' }]));
+  if (subject.raisedBy || subject.risk) {
+    const segs = [];
+    if (subject.raisedBy) segs.push({ text: `raised by ${subject.raisedBy}`, role: 'prose' });
+    if (subject.risk) segs.push({ text: subject.raisedBy ? ' · risk ' : 'risk ', role: 'prose' }, riskSeg(subject.risk));
+    if (segW(segs) <= innerW) out.push(row(segs));
+    else { // too wide for one row: raised-by wraps, risk gets its own row
+      if (subject.raisedBy) for (const l of wrapCells(`raised by ${subject.raisedBy}`, innerW)) out.push(row([{ text: l, role: 'prose' }]));
+      if (subject.risk) out.push(row([{ text: 'risk ', role: 'prose' }, riskSeg(subject.risk)]));
+    }
+  }
+  out.push(blank());
+  if (phase === 'input' || phase === 'denied' || phase === 'verifying') {
+    out.push(...slotRows());
+    out.push(row([...pinSeg], shift));
+    out.push(blank());
+  }
+  if (phase === 'ok') { out.push(...slotRows()); out.push(blank()); }
+  if (phase !== 'input') out.push(row(status, shift));
+  if (phase === 'ok') out.push(blank());
+  if (error) for (const l of wrapCells(error, innerW)) out.push(row([{ text: l, role: 'error' }]));
+  out.push(foot);
+  return out;
+}
+
+/**
+ * The controller (same shape as the /login and /connect controllers: isOpen / view / onEvent).
+ *   deps.api            { stepUpVerify(pin, {orgId, scopes}) }  -> { step_up_token, expires_at, scopes }
+ *   deps.agentLogin     this window is an agent login: no PIN field, ever
+ *   deps.refresh        re-render
+ *   deps.note           (text, tone) -> a line to the transcript pane (never carries digits)
+ *   deps.emit           dispatch({ type: 'stepup.result', ok })  (sound cue; carries no digits)
+ */
+export function createStepUp({ api, agentLogin = false, onAgentLogin = () => {}, refresh = () => {}, note = () => {}, emit = () => {}, settingsUrl = () => null, now = () => Date.now(), sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const box = createPinBox();
+  let card = null;
+  let resolveCard = null;
+  let tries = MAX_TRIES;
+  let lockedUntil = 0;
+  let busy = false;
+  const tokens = new Map(); // scope -> { token, until }
+  let presentUntil = 0;     // set only by /authenticate: the "human present" window shown in the status bar
+
+  const finish = (result) => { box.clear(); const r = resolveCard; card = null; resolveCard = null; busy = false; refresh(); r?.(result); };
+  const live = (scope) => { const t = tokens.get(scope); if (t && t.until > now()) return t; tokens.delete(scope); return null; };
+
+  async function submit() {
+    if (busy || !card) return;
+    try { await submitInner(); } finally { busy = false; }
+  }
+  async function submitInner() {
+    const pin = box.take(); // out of the box in one move; the local `pin` is dropped when this function returns
+    busy = true; card.phase = 'verifying'; card.filled = 0; refresh();
+    const t0 = now();
+    let res = null; let err = null;
+    try { res = await api.stepUpVerify(pin, { orgId: card.orgId, scopes: card.scopes }); }
+    catch (e) { err = e; }
+    const waited = now() - t0;
+    if (waited < BEAT_MS) await sleep(BEAT_MS - waited); // cosmetic floor only; a slow call is never padded
+    if (!card) return;
+    if (res?.step_up_token) {
+      const until = now() + WINDOW_MS;
+      for (const s of res.scopes || card.scopes) tokens.set(s, { token: res.step_up_token, until });
+      if (card.window) presentUntil = until;
+      card.phase = 'ok'; card.until = until; card.now = now(); refresh(); emit({ type: 'stepup.result', ok: true });
+      await sleep(RESULT_HOLD_MS);
+      return finish({ ok: true, token: res.step_up_token, scopes: res.scopes || card.scopes });
+    }
+    const status = err?.status; const code = err?.body?.error || err?.code;
+    if (status === 409 || code === 'no_pin_set') { card.phase = 'nopin'; Promise.resolve(settingsUrl()).then((u) => note(u ? `${NO_PIN_LINE} (${u})` : NO_PIN_LINE, 'warn')).catch(() => {}); refresh(); emit({ type: 'stepup.result', ok: false }); return; }
+    if (status === 423 || code === 'pin_locked') { lockedUntil = now() + LOCK_MS; card.phase = 'locked'; refresh(); emit({ type: 'stepup.result', ok: false }); return; }
+    if (status === 401 || code === 'wrong_pin') {
+      tries = Number.isFinite(err?.body?.tries_left) ? Math.min(tries - 1, err.body.tries_left) : tries - 1;
+      emit({ type: 'stepup.result', ok: false });
+      if (tries <= 0) { lockedUntil = now() + LOCK_MS; card.phase = 'locked'; refresh(); return; }
+      card.phase = 'denied'; card.tries = tries; card.offset = 1; refresh();
+      await sleep(80); if (!card) return; card.offset = 0; refresh();
+      await sleep(RESULT_HOLD_MS - 80); if (!card) return;
+      card.phase = 'input'; card.error = null; refresh();
+      return;
+    }
+    if (status === 403 && (code === 'step_up_human_only')) { card.phase = 'agent'; refresh(); return; }
+    card.phase = 'input'; card.error = (err?.message || 'could not verify').replace(/\s+/g, ' ').slice(0, 80); refresh();
+  }
+
+  return {
+    /** Live token for a scope, or null. */
+    token: (scope) => live(scope)?.token || null,
+    headers: (scope) => { const t = live(scope); return t ? { 'x-step-up-token': t.token } : {}; },
+    presentMs: () => Math.max(0, presentUntil - now()),
+    drop(scope) { tokens.delete(scope); },
+    clear() { tokens.clear(); presentUntil = 0; box.clear(); },
+    isOpen: () => Boolean(card),
+    view() { return card ? { ...card, filled: box.count(), tries, now: now() } : null; },
+    /**
+     * Ask for a person. Resolves { ok, token?, reason? } and never throws. Reuses a live token for the scope.
+     * opts: { scope: 'approve'|'override', scopes?, orgId?, subject?, window?: true (the /authenticate window) }
+     */
+    request({ scope = 'approve', scopes = null, orgId = null, subject = {}, window: asWindow = false, title = null } = {}) {
+      if (typeof agentLogin === 'function' ? agentLogin() : agentLogin) { note(`This window is an agent login: ${NEEDS_PERSON}.`, 'warn'); onAgentLogin(); return Promise.resolve({ ok: false, reason: 'agent_login' }); }
+      if (!asWindow && live(scope)) return Promise.resolve({ ok: true, token: live(scope).token, scopes: [scope], reused: true });
+      if (card) return Promise.resolve({ ok: false, reason: 'busy' });
+      if (lockedUntil > now()) { note(`⛔ LOCKED · PIN entry is locked for ${mmss(lockedUntil - now())}. Use your phone or a human session.`, 'error'); return Promise.resolve({ ok: false, reason: 'locked' }); }
+      tries = MAX_TRIES;
+      box.clear();
+      card = { phase: 'input', subject, title, scope, scopes: scopes || (asWindow ? ['approve', 'override'] : [scope]), orgId, window: asWindow, error: null, offset: 0 };
+      refresh();
+      return new Promise((r) => { resolveCard = r; });
+    },
+    onEvent(e) {
+      if (!card) return false;
+      if (busy || card.phase === 'verifying' || card.phase === 'ok' || card.phase === 'denied') return true; // swallowed while the call is in flight and during the DENIED beat
+      const ph = card.phase;
+      if (ph === 'locked' || ph === 'nopin' || ph === 'agent') { if (e.type === 'key' && (e.name === 'escape' || e.name === 'enter' || e.name === 'ctrl-c')) finish({ ok: false, reason: ph }); return true; }
+      if (e.type === 'paste' || e.type === 'text') { box.push(e.text); if (box.count() >= PIN_LEN) submit(); else refresh(); return true; }
+      if (e.type !== 'key') return true;
+      if (e.name === 'escape' || e.name === 'ctrl-c') { finish({ ok: false, reason: 'cancelled' }); return true; }
+      if (e.name === 'backspace') { box.backspace(); refresh(); return true; }
+      if (e.name === 'kill-line' || e.name === 'delete-word') { box.clear(); refresh(); return true; }
+      return true; // every other key is swallowed: nothing falls through to the composer
+    }
+  };
+}

package/lib/quoxon/slash/stepUpCard.js

@@ -0,0 +1,60 @@
+/**
+ * Ink face of the step-up PIN card and the "human present" bar. All text comes from cardLines() (pure,
+ * counts only, never a digit); this file only paints roles. Roles: gold frame/title/filled dots/countdown,
+ * prose for ink, ok green, error red. Never grey.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { c, mono } from '../theme.js';
+import { cardLines, mmss, ANIM_MIN_COLS } from './stepUp.js';
+
+const h = React.createElement;
+
+/** Animate only on a roomy, coloured terminal that is keeping up. */
+export const animationOn = (cols, slow = false) => cols >= ANIM_MIN_COLS && !slow && !mono() && process.env.TERM !== 'dumb';
+const FRAME_MS = 90;
+
+export function StepUpCard({ view, cols }) {
+  const [tick, setTick] = React.useState(0);
+  const [pulse, setPulse] = React.useState(-1);
+  const [slow, setSlow] = React.useState(false);
+  const on = animationOn(cols, slow);
+  const phase = view?.phase;
+  // verifying shimmer + sweep: one timer, only while verifying. A tick that lands far late means the terminal
+  // cannot keep up, so the card goes still for good rather than stutter.
+  React.useEffect(() => {
+    if (!on || phase !== 'verifying') return undefined;
+    let last = Date.now();
+    const t = setInterval(() => {
+      const n = Date.now(); if (n - last > FRAME_MS * 4) setSlow(true);
+      last = n; setTick((x) => x + 1);
+    }, FRAME_MS);
+    return () => clearInterval(t);
+  }, [on, phase === 'verifying']);
+  // per-digit pulse: flash the slot just filled for ~150 ms. Reads only the COUNT of digits, never a digit.
+  const filled = view?.filled || 0; const prev = React.useRef(0);
+  React.useEffect(() => {
+    const was = prev.current; prev.current = filled;
+    if (!on || filled <= was || phase !== 'input') { setPulse(-1); return undefined; }
+    setPulse(filled - 1);
+    const t = setTimeout(() => setPulse(-1), 150);
+    return () => clearTimeout(t);
+  }, [filled, on]);
+  const lines = cardLines(on ? { ...view, pulse, tick: phase === 'verifying' ? tick : null } : view, cols);
+  return h(Box, { flexDirection: 'column', width: cols, marginBottom: 1 }, // QUOXON-1191b: the spacer Box above supplies the one blank row above; this adds the one below
+    ...lines.map((segs, i) => h(Text, { key: i, wrap: 'truncate-end' },
+      ...segs.map((s, j) => h(Text, { key: j, color: c(s.role === 'prose' ? 'text' : s.role), bold: (s.role === 'gold' && j === 0 && i === 0) || s.role === 'key' || (s.role === 'ok' && s.text.startsWith('✔ AUTH')) }, s.text)))));
+}
+
+/** One gold line above the status bar while the /authenticate window is live; ticks once a second. */
+export function PresentBar({ stepUp, cols }) {
+  const [, tick] = React.useReducer((n) => n + 1, 0);
+  const left = stepUp.presentMs();
+  React.useEffect(() => {
+    if (!left) return undefined;
+    const t = setInterval(() => tick(), 1000);
+    return () => clearInterval(t);
+  }, [left > 0]);
+  if (!left) return null;
+  return h(Box, { width: cols }, h(Text, { wrap: 'truncate-end' }, ' ', h(Text, { color: c('gold'), bold: true }, '◉ human present '), h(Text, { color: c('gold') }, mmss(left)), h(Text, { color: c('text') }, ' · /authenticate renews')));
+}

package/lib/quoxon/slash/stepUpCmds.js

@@ -0,0 +1,78 @@
+/**
+ * QUOXON-STEPUP: /authenticate, /authorise and /override. Logic only; app.js wires the three entries.
+ *
+ *   /authenticate            PIN once: "human present" for 10 minutes (gold bar), so approvals and overrides
+ *                            in that window do not ask again
+ *   /authorise <n>           approve item n from /approvals with a PIN (prompts when no live step-up)
+ *   /override <id|last> <reason>   a person with a fresh PIN overrides ONE blocked action; recorded and
+ *                            witnessed server-side. Honest about block types no gate honours yet.
+ */
+import { mmss, NEEDS_PERSON } from './stepUp.js';
+
+export const BLOCK_TYPES = ['safety', 'budget', 'aocl', 'ward'];
+export const MIN_REASON = 8;
+export const overrideUsage = '/override <block id|last> <reason>  (a person must confirm with a PIN; the reason is recorded)';
+
+/** "safety:org:agent:RED" -> "safety". Anything that does not start with a known block type -> null. */
+export const blockTypeOf = (id) => { const t = String(id || '').split(':')[0].toLowerCase(); return BLOCK_TYPES.includes(t) ? t : null; };
+
+/** -> { ok:true, blockId, reason } | { ok:false, error } */
+export function parseOverride(args, last = null) {
+  const words = String(args || '').trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return { ok: false, error: `Usage: ${overrideUsage}` };
+  let blockId = words[0];
+  if (blockId.toLowerCase() === 'last') {
+    if (!last?.blockId) return { ok: false, error: 'No policy block has stopped anything in this window yet. Pass the block id: /override <block id> <reason>' };
+    blockId = last.blockId;
+  }
+  const reason = words.slice(1).join(' ').trim();
+  if (reason.length < MIN_REASON) return { ok: false, error: `Give a reason (at least ${MIN_REASON} characters): it is recorded with your name. Usage: ${overrideUsage}` };
+  if (!blockTypeOf(blockId)) return { ok: false, error: `"${blockId}" is not a block id (expected ${BLOCK_TYPES.map((t) => `${t}:...`).join(', ')}). Use "last" for the most recent block.` };
+  return { ok: true, blockId, blockType: blockTypeOf(blockId), reason };
+}
+
+/** What a failed step-up means to the person, in one line. */
+export function declinedText(reason) {
+  switch (reason) {
+    case 'agent_login': return NEEDS_PERSON;
+    case 'cancelled': return 'PIN cancelled, nothing was sent';
+    case 'locked': return 'PIN entry is locked: use your phone or a human session';
+    case 'nopin': return 'no PIN set: set one in the dashboard (Settings > Account > Approval PIN)';
+    case 'busy': return 'a PIN prompt is already open';
+    default: return 'a person has not confirmed this';
+  }
+}
+
+export function createStepUpCmds({ api, stepUp, say, lastBlock = () => null, orgOf = () => null }) {
+  return {
+    async authenticate() {
+      const r = await stepUp.request({ window: true, orgId: orgOf(), subject: { line1: 'confirm a person is at this keyboard' } });
+      if (!r.ok) return say(`Not authenticated: ${declinedText(r.reason)}.`, 'warn');
+      return say(`✔ AUTHORISED · human present for ${mmss(stepUp.presentMs())}. Approvals and /override will not ask again in that window.`, 'ok');
+    },
+    /** One override. Returns the server answer or null. */
+    async override(args) {
+      const p = parseOverride(args, lastBlock());
+      if (!p.ok) return say(p.error, 'warn');
+      const lb = lastBlock();
+      const body = { blockId: p.blockId, blockType: p.blockType, reason: p.reason, agentId: lb?.blockId === p.blockId ? lb.agentId : null, action: lb?.blockId === p.blockId ? lb.text : null };
+      const subject = { line1: `override ${p.blockId}`, raisedBy: lb?.agentId ? `${lb.agentId} (blocked)` : null, risk: p.blockType === 'safety' ? 'high' : null };
+      const go = () => api.override({ ...body, stepUp: stepUp.headers('override') });
+      const ask = async () => {
+        const r = await stepUp.request({ scope: 'override', orgId: orgOf(), subject, title: 'OVERRIDE REQUIRES A PERSON' });
+        return r.ok ? null : declinedText(r.reason);
+      };
+      let res;
+      try {
+        if (!stepUp.token('override')) { const no = await ask(); if (no) return say(`Override not made: ${no}.`, 'warn'); }
+        try { res = await go(); }
+        catch (e) {
+          if (e?.status === 403 && e?.body?.error === 'step_up_required') { stepUp.drop('override'); const no = await ask(); if (no) return say(`Override not made: ${no}.`, 'warn'); res = await go(); }
+          else throw e;
+        }
+      } catch (e) { return say(`Override failed: ${e?.body?.message || e?.message || e}`, 'error'); }
+      say(`✔ Override ${res.override_id} recorded for ${p.blockId} by you, reason witnessed (AEE/WARD). ${res.note || ''}`.trim(), res.enforced ? 'ok' : 'warn');
+      return res;
+    }
+  };
+}