quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/slash/rowCmd.js

@@ -0,0 +1,157 @@
+/**
+ * QUOXON-FW17: /row, custom rows above the status line. Kept out of app.js.
+ *
+ * url rows save to the user's server-side preferences (api.setRowPrefs, namespace quoxonRows); cmd rows save to a
+ * local file only (api.setLocalCmdRows) and are never sent anywhere. The engine (rows.js) does the polling.
+ */
+import { checkRow, parseRowCmd, splitRows, rowLabel, normRows, MAX_ROWS, rowDisplay, ROLES, secretInRow, syncable } from '../rows.js';
+import { clip } from '../theme.js';
+import { createRowWalk } from './rowWalk.js';
+
+/** How a row reads its data, in words (for /row list). */
+export const whereOf = (r) => {
+  const s = r.source;
+  if (s.type === 'url') return `url ${s.url}`;
+  if (s.type === 'quox') return `quox ${s.path}${s.service === 'collector' ? ' (collector)' : ''}`;
+  if (s.type === 'plugin') return `plugin ${s.plugin} ${s.path}`;
+  return `cmd ${s.cmd}  (this machine only)`;
+};
+
+/** ROWS: rows changed elsewhere (`quox rows`, another window) reach an open window within this long. */
+export const RELOAD_MS = 60 * 1000;
+
+const cleanLine = (l) => String(l).replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, '');
+
+export function createRowCmd({ api, say, engine, bump, cols, setT = setTimeout, clearT = clearTimeout }) {
+  let url = []; // synced (url, quox and plugin rows)
+  let cmd = []; // this machine only
+  let reloadTimer = null;
+  const all = () => [...url, ...cmd];
+  const apply = () => { engine.setRows(all()); bump(); };
+
+  /** Start up: the cached/local rows at once, then the server copy. Never throws. */
+  async function load() {
+    try { url = api.localRowPrefs?.() || []; cmd = api.localCmdRows?.() || []; } catch { url = []; cmd = []; }
+    engine.setEnabled(api.settings?.().rows !== 'off');
+    apply();
+    await refreshFromStores();
+    schedule();
+  }
+
+  /** Re-read both stores; the engine keeps the state of rows that did not change. -> true when anything changed. */
+  async function refreshFromStores() {
+    const before = JSON.stringify(all());
+    try { cmd = api.localCmdRows?.() || cmd; } catch { /* keep */ }
+    try {
+      const r = await api.rowPrefs?.();
+      if (r?.source === 'server') url = normRows(r.rows);
+    } catch { /* the local copy stands */ }
+    const changed = JSON.stringify(all()) !== before;
+    if (changed) apply();
+    return changed;
+  }
+
+  function schedule() {
+    clearT(reloadTimer);
+    reloadTimer = setT(async () => { await refreshFromStores(); schedule(); }, RELOAD_MS);
+    reloadTimer?.unref?.();
+  }
+
+  /** Save one row (new, or replacing `replace`). Shared by /row add and the walk. -> { ok, text }. */
+  async function put(row, { replace = null } = {}) {
+    const exists = replace || find(row.id);
+    if (!exists && all().length >= MAX_ROWS) return { ok: false, text: `You have ${MAX_ROWS} rows already (the most there is room for). /row rm <id> makes space.` };
+    if (exists) { url = url.filter((x) => x !== exists); cmd = cmd.filter((x) => x !== exists); }
+    if (exists && !syncable(exists) && syncable(row)) api.setLocalCmdRows?.(cmd);
+    if (syncable(row)) {
+      url = [...url, row];
+      apply();
+      const r = api.setRowPrefs ? await api.setRowPrefs(url) : { synced: true };
+      if (!r.synced) return { ok: false, text: `Saved on this machine only (${r.error || 'the server did not take it'}). Making the change again retries.` };
+      return { ok: true, text: `Row ${row.id} ${exists ? 'saved' : 'added'}. It follows your account to other machines. /row test ${row.id} shows the raw value.` };
+    }
+    cmd = [...cmd, row];
+    apply();
+    if (exists && syncable(exists) && api.setRowPrefs) await api.setRowPrefs(url);
+    const ok = api.setLocalCmdRows ? api.setLocalCmdRows(cmd) : true;
+    return ok ? { ok: true, text: `Row ${row.id} ${exists ? 'saved' : 'added'}. It runs your command on THIS machine only and is never synced.` } : { ok: false, text: 'Could not save the row to the local file; it lasts until you quit.' };
+  }
+
+  const walk = createRowWalk({ say, bump, probe: (row) => engine.probe(row), save: put, existing: () => all() });
+
+  async function saveUrl(tail = '') {
+    if (!api.setRowPrefs) return;
+    const r = await api.setRowPrefs(url);
+    if (!r.synced) say(`Saved on this machine only (${r.error || 'the server did not take it'}). Making the change again retries.`, 'warn');
+    else if (tail) say(tail);
+  }
+
+  const find = (id) => all().find((r) => r.id.toLowerCase() === String(id).toLowerCase());
+
+  async function handle(arg) {
+    const sub = parseRowCmd(arg);
+    const w = Math.max(20, cols() - 4);
+    switch (sub.kind) {
+      case 'error': return say(sub.text, 'warn');
+      case 'list': {
+        const rows = all();
+        if (!rows.length) return say('No custom rows yet. /row new walks you through one (or quox rows add from a shell).');
+        say(`Custom rows (${rows.length} of ${MAX_ROWS})${engine.isEnabled() ? '' : ', hidden: /row on shows them'}:`);
+        for (const r of rows) {
+          const s = engine.state(r.id);
+          say(clip(`  ${r.id}${r.label && r.label !== r.id ? ` (${r.label})` : ''}  every ${r.source.every}  ${whereOf(r)}${r.template ? '' : '  [status-row contract]'}`, w));
+          if (s && engine.isEnabled()) say(clip(`      now: ${rowDisplay(s).text}`, w), s.status === 'error' ? 'warn' : undefined);
+        }
+        return undefined;
+      }
+      case 'on': case 'off': {
+        engine.setEnabled(sub.kind === 'on');
+        api.saveSetting?.('rows', sub.kind);
+        bump();
+        return say(sub.kind === 'on' ? 'Custom rows are on.' : 'Custom rows hidden and paused. /row on brings them back.');
+      }
+      case 'rm': {
+        const r = find(sub.id);
+        if (!r) return say(`No row "${sub.id}". /row list shows them.`, 'warn');
+        if (syncable(r)) { url = url.filter((x) => x !== r); apply(); await saveUrl(); } else { cmd = cmd.filter((x) => x !== r); apply(); api.setLocalCmdRows?.(cmd); }
+        return say(`Removed row ${r.id}.`, 'ok');
+      }
+      case 'test': {
+        const r = find(sub.id);
+        if (!r) return say(`No row "${sub.id}". /row list shows them.`, 'warn');
+        say(`Testing ${r.id}…`);
+        const p = await engine.probe(r);
+        if (!p.ok && !p.raw) return say(clip(`⚠ ${rowLabel(r)}: ${p.error}`, w), 'warn');
+        const lines = p.raw.split('\n').filter((l) => l.trim()).slice(0, 4);
+        say('Raw value:');
+        for (const l of lines) say(clip(`  ${cleanLine(l)}`, w));
+        if (p.raw.length > 400 || lines.length >= 4) say('  …');
+        if (!p.ok) return say(clip(`⚠ ${rowLabel(r)}: ${p.error}`, w), 'warn');
+        for (const wn of p.warnings || []) say(clip(`Note: ${wn}`, w), 'warn');
+        if (p.seg?.link) say(clip(`Link: ${p.seg.link}`, w));
+        return say(clip(`Row shows: ${p.text}`, w), 'ok');
+      }
+      case 'add': {
+        const v = checkRow(sub.row);
+        if (v.error) return say(v.error, 'warn');
+        const secret = secretInRow(v.row);
+        if (secret) return say(secret, 'warn');
+        const r = await put(v.row);
+        return say(r.text, r.ok ? 'ok' : 'warn');
+      }
+      case 'new': return walk.start('new');
+      case 'edit': return walk.start('edit', sub.id);
+      case 'reload': {
+        const changed = await refreshFromStores();
+        return say(changed ? `Rows reloaded: ${all().map((r) => r.id).join(', ') || 'none'}.` : 'Rows reloaded; nothing changed.');
+      }
+      default: return undefined;
+    }
+  }
+
+  return {
+    handle, load, stopEngine: () => { clearT(reloadTimer); engine.stop(); }, view: () => engine.view(), all, colours: ROLES, counts: () => splitRows(all()),
+    /** the /row new|edit walk: app.js routes typed lines, its y/N/c card and Esc here */
+    walk
+  };
+}

package/lib/quoxon/slash/rowWalk.js

@@ -0,0 +1,175 @@
+/**
+ * ROWS (owner 2026-10-17): /row new and /row edit <id> in the quox window. The same shape as the hat walk
+ * (hatWalk.js): every question is a y/N/c card (askText) or a one-line text capture. Esc, or any slash command,
+ * ends the walk and nothing is saved. Before the last card the row is fetched ONCE and the card shows what it
+ * will say, so a row is never saved blind.
+ *
+ * Command rows get their own card naming the exact command, because a command runs a shell on this machine every
+ * refresh. This file has no I/O beyond the functions it is given (probe, save, existing).
+ */
+import { askText } from '../ask.js';
+import { checkRow, secretInRow, validId, parseEvery, rowLabel } from '../rows.js';
+
+export const KINDS = [
+  { key: 'url', name: 'a web address (URL) that returns JSON or text', ask: 'Which URL? It is fetched with no credentials.' },
+  { key: 'quox', name: 'a path on your own Quox, read with your session', ask: 'Which path? It starts with /api/; {org} is filled in for you. Example: /api/orgs/{org}/inbox/stats' },
+  { key: 'plugin', name: 'a status row a plugin ships', ask: 'Which plugin and row path? Example: qpe row' },
+  { key: 'cmd', name: 'a command on THIS machine (never synced or shared)', ask: 'Which command? It runs through your shell, 5 s at most.' }
+];
+
+const slug = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
+
+/** A kind and the typed target -> a source, or { error }. */
+export function sourceFrom(kind, line, every = '60s') {
+  const t = String(line ?? '').trim();
+  if (!t) return { error: 'That is empty.' };
+  if (kind === 'url') return { source: { type: 'url', url: t, every } };
+  if (kind === 'cmd') return { source: { type: 'cmd', cmd: t, every } };
+  if (kind === 'quox') return { source: { type: 'quox', service: t.startsWith('/api/v1/') ? 'collector' : 'auth', path: t, every } };
+  const [plugin, ...rest] = t.split(/\s+/);
+  if (!rest.length) return { error: 'Give the plugin id and the row path, e.g. qpe row.' };
+  return { source: { type: 'plugin', plugin, path: rest.join(''), every } };
+}
+
+/** "1", "url", "a URL" -> a KINDS key, or null. */
+export function pickKind(line) {
+  const t = String(line ?? '').trim().toLowerCase();
+  if (/^[1-4]$/.test(t)) return KINDS[Number(t) - 1].key;
+  const hit = KINDS.find((k) => k.key === t || (t.length >= 3 && k.name.toLowerCase().includes(t)));
+  return hit ? hit.key : (t === 'command' || t === 'shell' ? 'cmd' : null);
+}
+
+export function createRowWalk({ say, bump = () => {}, probe, save, existing }) {
+  let W = null;
+
+  const ask = (question, reason = '') => { const st = { at: Date.now() }; W.card = st; say(askText(question, { reason }), 'ask'); return st; };
+  const yn = (question, on, reason) => { W.wait = { kind: 'yn', on }; ask(question, reason); bump(); };
+  // path: the answer may itself start with / (a quox path like /api/...), so only a known slash command ends the walk
+  const text = (prompt, on, { empty = false, path = false } = {}) => { W.wait = { kind: 'text', on, empty, path }; W.card = null; say(prompt); bump(); };
+  const end = () => { W = null; bump(); };
+
+  /** Validate, preview once, then the final card. */
+  async function preview(draft, verb) {
+    const c = checkRow(draft);
+    if (c.error) { say(c.error, 'warn'); return W?.retry?.(); }
+    const secret = secretInRow(c.row);
+    if (secret) { say(secret, 'warn'); return W?.retry?.(); }
+    const row = c.row;
+    say(`Fetching ${rowLabel(row)} once to show you what it will say…`);
+    const p = await probe(row);
+    if (!W) return undefined; // cancelled while fetching
+    if (p.ok) {
+      say(`It will show: ${p.text}`, 'ok');
+      for (const w of p.warnings || []) say(`Note: ${w}`, 'warn');
+    } else say(`It could not be read just now (${p.error}). You can still save it; the row shows the problem until it works.`, 'warn');
+    yn(`${verb} the ${rowLabel(row)} row?`, async (yes) => {
+      if (!yes) { say('Nothing saved.'); return end(); }
+      const r = await save(row, { replace: W.replace || null });
+      say(r.text, r.ok ? 'ok' : 'warn');
+      end();
+    }, row.source.type === 'cmd' ? 'Runs on this machine only, never synced' : 'Follows your account to your other machines');
+    return undefined;
+  }
+
+  // Shared tail: template, interval, then preview.
+  function tail(draft, verb) {
+    const askTemplate = () => text(draft.template
+      ? `Template? Enter keeps ${draft.template}; "-" uses the status-row contract ({"text": ...}).`
+      : 'Template? Enter reads the status-row contract ({"text": ..., "value": ..., "tone": ...}) or plain text. Or type one, e.g. {{pending_approvals}} waiting', (line) => {
+      const t = line.trim();
+      if (t === '-') delete draft.template; else if (t) draft.template = t;
+      askEvery();
+    }, { empty: true });
+    const askEvery = () => yn(`Refresh every ${draft.source.every}?`, (yes) => {
+      if (yes) return preview(draft, verb);
+      const again = () => text('How often? 30s, 5m or 1h (5 s to 1 day).', (line) => {
+        if (parseEvery(line) === null) { say(`"${line.trim()}" is not an interval.`, 'warn'); return again(); }
+        draft.source.every = line.trim(); preview(draft, verb);
+      });
+      again();
+    });
+    W.retry = askTemplate;
+    askTemplate();
+  }
+
+  function askSource(draft, verb) {
+    KINDS.forEach((k, i) => say(`  ${i + 1}. ${k.name}`));
+    const pick = () => text('Where does it read from? A number.', (line) => {
+      const kind = pickKind(line);
+      if (!kind) { say('Pick 1, 2, 3 or 4.', 'warn'); return pick(); }
+      const target = () => text(KINDS.find((k) => k.key === kind).ask, (l2) => {
+        const s = sourceFrom(kind, l2, draft.source?.every || '60s');
+        if (s.error) { say(s.error, 'warn'); return target(); }
+        draft.source = s.source;
+        const c = checkRow({ ...draft, template: draft.template });
+        if (c.error && !/template|Template/.test(c.error)) { say(c.error, 'warn'); return target(); }
+        const secret = secretInRow(draft);
+        if (secret) { say(secret, 'warn'); return target(); }
+        if (kind === 'cmd') return yn(`Run \`${s.source.cmd}\` on this machine every ${s.source.every}?`, (yes) => {
+          if (!yes) { say('Nothing saved.'); return end(); }
+          tail(draft, verb);
+        }, 'A command row runs a shell here and is never synced or shared');
+        tail(draft, verb);
+      }, { path: kind === 'quox' });
+      target();
+    });
+    pick();
+  }
+
+  function startNew() {
+    W = { mode: 'new' };
+    const draft = { source: { every: '60s' } };
+    const askName = () => text('What should the row be called? A short label, e.g. Approvals.', (line) => {
+      const label = line.trim().slice(0, 24);
+      const id = slug(label);
+      if (!validId(id)) { say('Use letters or digits in the name.', 'warn'); return askName(); }
+      if (existing().some((r) => r.id.toLowerCase() === id)) { say(`A row called ${id} exists. /row edit ${id} changes it, or pick another name.`, 'warn'); return askName(); }
+      draft.id = id; draft.label = label;
+      askSource(draft, 'Add');
+    });
+    askName();
+  }
+
+  function startEdit(id) {
+    const cur = existing().find((r) => r.id.toLowerCase() === String(id).toLowerCase());
+    if (!cur) { say(`No row "${id}". /row list shows them.`, 'warn'); return; }
+    W = { mode: 'edit', replace: cur };
+    const draft = JSON.parse(JSON.stringify(cur));
+    yn(`Change where ${rowLabel(cur)} reads from?`, (yes) => {
+      if (yes) return askSource(draft, 'Save');
+      yn('Rename it?', (y2) => {
+        if (!y2) return tail(draft, 'Save');
+        const again = () => text('What is the new label?', (line) => { const l = line.trim().slice(0, 24); if (!l) { say('A label cannot be empty.', 'warn'); return again(); } draft.label = l; tail(draft, 'Save'); });
+        again();
+      });
+    });
+  }
+
+  return {
+    active: () => Boolean(W),
+    card: () => (W?.wait?.kind === 'yn' ? W.card : null),
+    start(kind, arg = '') {
+      if (W) { say('A row walk is already open. Esc cancels it.', 'warn'); return; }
+      if (kind === 'new') return startNew();
+      return startEdit(arg);
+    },
+    /** One typed line. true = consumed. A slash command ends the walk and is left to run. */
+    answer(line) {
+      if (!W?.wait) return false;
+      const t = String(line ?? '').trim();
+      const isPath = W.wait.kind === 'text' && W.wait.path && t.startsWith('/api/');
+      if (t.startsWith('/') && !isPath) { W = null; say('Row walk ended. Nothing was saved.'); bump(); return false; }
+      const w = W.wait;
+      if (w.kind === 'yn') {
+        const yes = /^y(es)?$/i.test(t);
+        if (!yes && t && !/^no?$/i.test(t)) return false; // c or free text: the card's normal chat behaviour
+        W.wait = null; Promise.resolve(w.on(yes)).catch((e) => { say(`Row walk failed: ${e?.message || 'error'}.`, 'warn'); end(); });
+        return true;
+      }
+      if (!t && !w.empty) return true;
+      W.wait = null; Promise.resolve(w.on(t)).catch((e) => { say(`Row walk failed: ${e?.message || 'error'}.`, 'warn'); end(); });
+      return true;
+    },
+    cancel() { if (!W) return false; W = null; say('Row walk cancelled. Nothing was saved.'); bump(); return true; }
+  };
+}

package/lib/quoxon/slash/settings.js

@@ -0,0 +1,60 @@
+/**
+ * /config settings, saved on the CLI config profile (profile.quoxon = { theme, motion, verbose }), so a
+ * choice survives restarts and follows `-p`. Theme replaces the env-only QUOX_THEME: the saved value is
+ * applied by setting the variable the theme module already reads, unless the user's shell set it, in
+ * 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 === '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: 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' }
+  ];
+}
+
+/** Apply saved look settings to this process. -> { themeFromShell, motionFromShell }. */
+export function applySettings(s = {}, env = process.env, shell = SHELL) {
+  if (!shell.theme) {
+    if (s.theme === 'dark' || s.theme === 'light') env.QUOX_THEME = s.theme; else delete env.QUOX_THEME;
+  }
+  if (!shell.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) };
+}
+
+export const shellOverrides = () => ({ ...SHELL });
+
+/** The card rows. `values` = current settings, `extra` = { model: label, verbose: current }. */
+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 = 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((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; } };
+}