quoxcli 0.2.0 → 0.4.0

package/lib/core/vm.js

@@ -0,0 +1,366 @@
+/**
+ * Shared engine behind `quox vm` and the QUOXON `/vm` command: drives the
+ * HYPERION (agent id atlas) Proxmox tools through the governed tool route
+ * (POST /api/v1/tools/execute). Pure functions over an injected `exec(tool, input)`
+ * so the CLI group and the TUI share one implementation and one set of tests.
+ *
+ * Tool names/inputs are the contract with the server side:
+ *   proxmox_vms, proxmox_containers, proxmox_vm_resources, proxmox_vm_action,
+ *   proxmox_vm_snapshot, proxmox_vm_resolve {name|vmid}, proxmox_pool_status,
+ *   proxmox_pool_lease, proxmox_pool_release, proxmox_pool_configure,
+ *   proxmox_node_power, proxmox_rehearse {vmid, node, command, checks?, keep_twin?} (starts, returns {rehearsal_id, state:'running'}),
+ *   proxmox_rehearsal_status {rehearsal_id}.
+ */
+
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const VM_ACTIONS = ['start', 'stop', 'reboot', 'shutdown'];
+export const NODE_ACTIONS = ['reboot', 'shutdown'];
+
+/** A write was held for a human. Callers print the hint and never re-submit. */
+export class VmPendingError extends Error {
+  constructor(tool, data) {
+    super(`${tool} is awaiting approval`);
+    this.name = 'VmPendingError';
+    this.tool = tool;
+    this.approvalId = data?.approvalId || data?.approval_id || data?._approval?.id || null;
+    this.inboxItemId = data?.inbox_item_id || null;
+    this.rehearsalId = data?.rehearsal_id || null;
+  }
+}
+
+export function pendingHint(e) {
+  const id = e.approvalId || e.inboxItemId;
+  if (!id) return `${e.tool} is awaiting approval. Check: quox approvals`;
+  return `${e.tool} is awaiting approval (approval id ${id}). After a human approves, run: quox approvals result ${id}`;
+}
+
+/**
+ * DEVFLEET-READ: HYPERION (atlas) is granted ONE read tool, proxmox_read, not the per-view read
+ * tools. Callers keep using the old names; the wire call is proxmox_read with the matching view.
+ * Writes (proxmox_vm_action, _snapshot, _rehearse, _vm_doctor, pool lease/release/config) pass through.
+ */
+export const PROXMOX_READ_VIEW_OF = {
+  proxmox_vms: 'vms', proxmox_containers: 'containers', proxmox_cluster_status: 'cluster',
+  proxmox_ha_status: 'ha', proxmox_templates_list: 'templates', proxmox_storage: 'storage',
+  proxmox_node_resources: 'node', proxmox_vm_resources: 'vm', proxmox_snapshots_list: 'snapshots',
+  proxmox_backup_status: 'backups', proxmox_vm_resolve: 'resolve', proxmox_pool_status: 'pool',
+  proxmox_rehearsal_status: 'rehearsal', proxmox_doctor_report: 'doctor_report',
+};
+
+// Tools that fan out many Proxmox reads server-side and outlive the client's 30s default.
+// VM Doctor runs 12 reads in parallel; over Bastion pvesh on a slow node that is ~30s.
+export const SLOW_TOOL_TIMEOUT_MS = { proxmox_vm_doctor: 120000, proxmox_snapshots_list: 90000 };
+
+/** Build an exec(tool, input) over an API client. Throws VmPendingError on a held call. */
+export function makeExec({ client, orgId }) {
+  return async function exec(tool, input = {}) {
+    const ep = resolveEndpoint('v1.tools.execute');
+    // HYPERION (atlas) owns these tools; without agent_id the call lands on the
+    // orchestrator, which is not granted them. An attach token's agent claim still wins server-side.
+    const view = PROXMOX_READ_VIEW_OF[tool];
+    const body = view ? { tool_name: 'proxmox_read', input: { view, ...input }, agent_id: 'atlas' } : { tool_name: tool, input, agent_id: 'atlas' };
+    if (orgId) body.org_id = orgId;
+    const timeout = SLOW_TOOL_TIMEOUT_MS[tool];
+    let data = await client.post(ep.path, { service: ep.service, body, ...(timeout ? { timeout } : {}) });
+    // The caller's own token identity wins over agent_id server-side (e.g. an attached session runs
+    // as itself, which holds the legacy reads like proxmox_vms but not proxmox_read). When proxmox_read
+    // is not granted to that identity, retry once with the legacy per-view tool it does hold.
+    if (view && data && data.success === false && /not granted/i.test(String(data.error || ''))) {
+      const legacy = { tool_name: tool, input, agent_id: 'atlas' };
+      if (orgId) legacy.org_id = orgId;
+      data = await client.post(ep.path, { service: ep.service, body: legacy });
+    }
+    if (data && data.pending) throw new VmPendingError(tool, data);
+    if (data && data.success === false) {
+      const err = new Error(`${tool} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}`);
+      err.toolError = data.error || 'unknown error';
+      err.tool = tool;
+      throw err;
+    }
+    return data;
+  };
+}
+
+/** The tool's payload, whatever envelope it came wrapped in. */
+export function payloadOf(data) {
+  let p = data;
+  if (p && typeof p === 'object' && !Array.isArray(p)) {
+    for (const k of ['result', 'output', 'data']) {
+      if (p[k] !== undefined && p[k] !== null) { p = p[k]; break; }
+    }
+  }
+  if (typeof p === 'string') { try { return JSON.parse(p); } catch { return p; } }
+  return p;
+}
+
+function arrayOf(p, ...keys) {
+  if (Array.isArray(p)) return p;
+  for (const k of [...keys, 'items', 'results', 'resources']) if (Array.isArray(p?.[k])) return p[k];
+  return [];
+}
+
+const normVm = (v, fallbackType) => ({
+  vmid: Number(v.vmid ?? v.id),
+  name: v.name ?? v.hostname ?? '',
+  node: v.node ?? null,
+  type: v.type === 'lxc' || v.type === 'qemu' ? v.type : (fallbackType || 'qemu'),
+  status: v.status ?? v.state ?? '',
+  raw: v,
+});
+
+const isUnknownTool = (e) => e?.status === 404
+  || /unknown tool|tool .*not (found|available|registered)|no such tool|unsupported tool|not implemented/i.test(e?.toolError || e?.message || '');
+
+export async function listVms(exec, { node, type } = {}) {
+  if (type && !['qemu', 'lxc'].includes(type)) throw new Error('--type must be qemu or lxc');
+  const out = [];
+  if (type !== 'lxc') {
+    const p = payloadOf(await exec('proxmox_vms', node ? { node } : {}));
+    for (const v of arrayOf(p, 'vms')) out.push(normVm(v, 'qemu'));
+  }
+  if (type === 'lxc') {
+    const p = payloadOf(await exec('proxmox_containers', node ? { node } : {}));
+    for (const v of arrayOf(p, 'containers', 'lxc')) out.push(normVm(v, 'lxc'));
+  }
+  return node ? out.filter((v) => !v.node || v.node === node) : out;
+}
+
+/**
+ * name|vmid -> { vmid, node, type, name }. Tool proxmox_vm_resolve first; if the server
+ * does not know it, fall back to client-side exact match over proxmox_vms + proxmox_containers.
+ * Ambiguity is an error listing candidates; never a guess.
+ */
+/** DEVFLEET INV-1: list rows for `quox vm list`, with each VM's Proxmox tags as one cell ('' when untagged). */
+export function vmListRows(vms) {
+  return vms.map(({ raw, ...r }) => ({ ...r, tags: Array.isArray(raw && raw.tags) ? raw.tags.join(', ') : '' }));
+}
+
+export async function resolveTarget(exec, target) {
+  const t = String(target ?? '').trim();
+  if (!t) throw new Error('a VM name or vmid is required');
+  const numeric = /^\d+$/.test(t);
+  const input = numeric ? { vmid: Number(t) } : { name: t };
+  let matches = null;
+  try {
+    const p = payloadOf(await exec('proxmox_vm_resolve', input));
+    const list = Array.isArray(p) ? p : (p?.matches || p?.candidates || (p && (p.vmid !== undefined || p.id !== undefined) ? [p] : []));
+    matches = list.map((v) => normVm(v));
+    if (!matches.length) throw new Error(`no VM matches "${t}" (proxmox_vm_resolve)`);
+  } catch (e) {
+    if (e instanceof VmPendingError || !isUnknownTool(e)) throw e;
+    matches = null;
+  }
+  if (matches === null) {
+    const all = await listVms(exec, {});
+    try { all.push(...await listVms(exec, { type: 'lxc' })); } catch (e) { if (e instanceof VmPendingError) throw e; /* containers are optional */ }
+    matches = all.filter((v) => (numeric ? v.vmid === Number(t) : v.name === t));
+    if (!matches.length) throw new Error(`no VM matches "${t}" (checked proxmox_vms and proxmox_containers; exact name match only)`);
+  }
+  if (matches.length > 1) {
+    const lines = matches.map((v) => `  ${v.vmid}  ${v.name}  ${v.node || '?'}  ${v.type}`).join('\n');
+    throw new Error(`"${t}" is ambiguous, ${matches.length} candidates (use the vmid):\n${lines}`);
+  }
+  const m = matches[0];
+  if (!m.node) throw new Error(`could not determine the node for "${t}" (vmid ${m.vmid})`);
+  return { vmid: m.vmid, node: m.node, type: m.type, name: m.name };
+}
+
+const withReason = (input, reason) => (reason ? { ...input, _reason: reason } : input);
+
+export async function vmInfo(exec, target) {
+  const vm = await resolveTarget(exec, target);
+  const data = await exec('proxmox_vm_resources', { vmid: vm.vmid, node: vm.node, type: vm.type });
+  return { vm, resources: payloadOf(data) };
+}
+
+export async function vmAction(exec, action, target, { reason } = {}) {
+  if (!VM_ACTIONS.includes(action)) throw new Error(`action must be one of ${VM_ACTIONS.join(', ')}`);
+  const vm = await resolveTarget(exec, target);
+  const data = await exec('proxmox_vm_action', withReason({ vmid: vm.vmid, node: vm.node, action, type: vm.type }, reason));
+  return { vm, result: payloadOf(data) };
+}
+
+export async function vmSnapshot(exec, target, { name, reason } = {}) {
+  const vm = await resolveTarget(exec, target);
+  // proxmox_vm_snapshot requires snapname (Proxmox: letter first, then [A-Za-z0-9_-]).
+  const snapname = name || `quox-${new Date().toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15)}`;
+  if (!/^[A-Za-z][A-Za-z0-9_-]{0,39}$/.test(snapname)) throw new Error('snapshot name must start with a letter and use only letters, digits, _ or -');
+  const input = { vmid: vm.vmid, node: vm.node, snapname };
+  const data = await exec('proxmox_vm_snapshot', withReason(input, reason));
+  return { vm, result: payloadOf(data) };
+}
+
+/**
+ * `url:http://127.0.0.1:8080/health` | `unit:nginx` | `cmd:test -f /etc/x` -> a proxmox_rehearse check.
+ * Only the shape is checked here; the server validates the characters strictly.
+ */
+export function parseCheck(spec) {
+  const m = /^(url|unit|cmd):(.+)$/.exec(String(spec ?? '').trim());
+  if (!m) throw new Error(`--check must look like url:http://127.0.0.1:PORT/path, unit:NAME or cmd:COMMAND (got "${spec}")`);
+  if (m[1] === 'url') return { type: 'url', url: m[2] };
+  if (m[1] === 'unit') return { type: 'unit', name: m[2] };
+  return { type: 'cmd', run: m[2] };
+}
+
+/** Start a rehearsal on a network-isolated twin of the VM (HYPERION proxmox_rehearse). Returns at once; the run takes minutes (a full disk copy). */
+export async function vmRehearse(exec, target, command, { checks = [], keepTwin = false } = {}) {
+  const c = String(command ?? '').trim();
+  if (!c) throw new Error('a command is required after --');
+  if (c.includes("'")) throw new Error('the command may not contain single quotes (it runs inside bash -c, use double quotes)');
+  const vm = await resolveTarget(exec, target);
+  const input = { vmid: vm.vmid, node: vm.node, command: c };
+  if (checks.length) input.checks = checks.map(parseCheck);
+  if (keepTwin) input.keep_twin = true;
+  let data;
+  try { data = await exec('proxmox_rehearse', input); } catch (e) {
+    // The rehearsal needs ONE human approval (the card lists every host command). The proposal exists and
+    // the run starts by itself once approved, so hand back the id instead of failing.
+    if (e instanceof VmPendingError && e.rehearsalId) {
+      return { vm, result: { rehearsal_id: e.rehearsalId, state: 'awaiting_approval', approval_id: e.approvalId, inbox_item_id: e.inboxItemId, hint: pendingHint(e) } };
+    }
+    throw e;
+  }
+  return { vm, result: payloadOf(data) };
+}
+
+export const REHEARSAL_POLL_MS = 10000;
+export const REHEARSAL_TIMEOUT_MS = 50 * 60 * 1000;
+
+/** Poll proxmox_rehearsal_status until the rehearsal is done (awaiting_approval and running both keep waiting). Throws on timeout (the id stays valid for a later look). */
+export async function waitRehearsal(exec, rehearsalId, { intervalMs = REHEARSAL_POLL_MS, timeoutMs = REHEARSAL_TIMEOUT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), onTick } = {}) {
+  if (!/^RH_[0-9A-F]{16}$/.test(String(rehearsalId || ''))) throw new Error('the server did not return a rehearsal id');
+  const t0 = Date.now();
+  for (;;) {
+    const rec = payloadOf(await exec('proxmox_rehearsal_status', { rehearsal_id: rehearsalId }));
+    const r = rec?.rehearsal || rec;
+    if (r && r.state === 'done') return r;
+    if (Date.now() - t0 > timeoutMs) throw new Error(`rehearsal ${rehearsalId} is still running after ${Math.round(timeoutMs / 60000)} minutes; check later with the proxmox_rehearsal_status tool`);
+    if (onTick) onTick(r);
+    await sleep(intervalMs);
+  }
+}
+
+/** Human REST surface for the pool. */
+export function makePoolRest({ client }) {
+  const call = (name, params, body, timeout) => {
+    const ep = resolveEndpoint(name, params);
+    const m = ep.method.toLowerCase();
+    const t = timeout ? { timeout } : {};
+    return m === 'get' ? client.get(ep.path, { service: ep.service, ...t }) : client[m](ep.path, { service: ep.service, body: body || {}, ...t });
+  };
+  return {
+    status: () => call('v1.proxmox.pool'),
+    configure: (body) => call('v1.proxmox.pool.config.put', {}, body),
+    // A warm lease probes ssh, installs the key and refreshes the IP; a slow auth service stretches that past 30s.
+    lease: (body) => call('v1.proxmox.pool.lease', {}, body, 180000),
+    release: (vmid) => call('v1.proxmox.pool.release', { vmid }),
+  };
+}
+
+export async function poolStatus(rest) {
+  return rest.status();
+}
+
+export function defaultLessee(env = process.env) {
+  return env.QUOX_SESSION || os.hostname();
+}
+
+/** --pubkey-file, else ~/.ssh/id_ed25519.pub when present, else a clear error. Reads the PUBLIC key only. */
+export function readPubkey(file, { home = os.homedir() } = {}) {
+  const f = file || path.join(home, '.ssh', 'id_ed25519.pub');
+  if (!file && !fs.existsSync(f)) throw new Error('no ssh public key: pass --pubkey-file <path> (default ~/.ssh/id_ed25519.pub was not found)');
+  let txt;
+  try { txt = fs.readFileSync(f, 'utf8').trim(); } catch (e) { throw new Error(`cannot read public key ${f}: ${e.message}`); }
+  if (!/^(ssh-|ecdsa-|sk-)/.test(txt)) throw new Error(`${f} does not look like an SSH public key (refusing to send it)`);
+  return txt;
+}
+
+export async function poolLease(rest, { lessee, pubkey, cores, memoryGb, diskGb, ttlH, purpose, avx, node } = {}) {
+  const input = { lessee: lessee || defaultLessee(), ssh_pubkey: pubkey };
+  if (cores != null) input.cores = Number(cores);
+  if (memoryGb != null) input.memory_gb = Number(memoryGb);
+  if (diskGb != null) input.disk_gb = Number(diskGb);
+  if (ttlH != null) input.ttl_h = Number(ttlH);
+  if (purpose) input.purpose = purpose;
+  if (avx) input.require_avx2 = true;   // set when only some nodes have AVX2; the server errors if no lane can take it
+  if (node) input.node = node;
+  return rest.lease(input);   // 201 {lease} when a warm VM fits, 202 {vmid,state:'building'} when built to order
+}
+
+/** Host key lines for a returned lease: the fingerprint to compare, and a ready known_hosts line. Never invents a key. */
+export function poolHostKeyLines(p) {
+  const l = p && p.lease;
+  if (!l || typeof l !== 'object') return [];
+  if (l.host_key_line && l.host_key_fingerprint) {
+    return [`Host key ${l.host_key_fingerprint}`, 'known_hosts line:', `${l.ip} ${l.host_key_line}`];
+  }
+  return [`host key not read: ${l.host_key_error || 'the server returned none'}`];
+}
+
+export async function poolDone(rest, vmid) {
+  if (!/^\d+$/.test(String(vmid ?? ''))) throw new Error('vmid must be a number');
+  return rest.release(Number(vmid));
+}
+
+export async function poolConfig(rest, input = {}) {
+  return rest.configure(input);
+}
+
+export async function nodePower(exec, action, node, { reason } = {}) {
+  if (!NODE_ACTIONS.includes(action)) throw new Error(`node action must be one of ${NODE_ACTIONS.join(', ')}`);
+  if (!node) throw new Error('a node name is required');
+  // The proxmox_node_power tool is not built yet. Fail loudly instead of calling a missing tool.
+  void exec; void reason;
+  throw new Error('node power (reboot, shutdown) is not built yet; there is no proxmox_node_power tool');
+}
+
+/** Plain-text lines for a VM list. */
+export function vmListLines(vms) {
+  if (!vms.length) return ['No VMs found.'];
+  return vms.map((v) => `${String(v.vmid).padEnd(6)} ${String(v.name).padEnd(28)} ${String(v.node || '?').padEnd(8)} ${String(v.type).padEnd(5)} ${v.status}`);
+}
+
+export function textOf(p) {
+  if (p === undefined || p === null) return 'done';
+  return typeof p === 'string' ? p : JSON.stringify(p, null, 2);
+}
+
+/**
+ * VM Doctor (DEVFLEET-DOCTOR): read-only diagnosis. The server resolves the name or vmid itself
+ * (proxmox_vm_doctor), so the target goes straight through. -> the report object.
+ */
+export async function vmDoctor(exec, target) {
+  const t = String(target ?? '').trim();
+  if (!t) throw new Error('a VM name or vmid is required');
+  const p = payloadOf(await exec('proxmox_vm_doctor', { target: t }));
+  if (!p || typeof p !== 'object' || !Array.isArray(p.findings)) throw new Error('proxmox_vm_doctor returned no report');
+  return p;
+}
+
+const SEV_LABEL = { critical: 'CRITICAL', warning: 'WARNING', info: 'INFO' };
+const showVal = (v) => (typeof v === 'number' ? String(Math.round(v * 1000) / 1000) : String(v));
+
+/** Human lines for a doctor report: verdict, each finding (cause / evidence / fix), then gaps. */
+export function doctorLines(report) {
+  const vm = report.vm || {};
+  const lines = [`VERDICT  ${String(report.verdict || 'unknown').toUpperCase()}  ${vm.name || vm.vmid} (vmid ${vm.vmid} on ${vm.node}, ${vm.status || 'unknown'})`];
+  if (!report.findings.length) lines.push('No problems found in what could be read.');
+  for (const f of report.findings) {
+    lines.push('', `${SEV_LABEL[f.severity] || String(f.severity).toUpperCase()}  ${f.title}: ${f.cause}`);
+    for (const e of f.evidence || []) {
+      lines.push(`  evidence: ${e.metric} = ${showVal(e.value)} (threshold ${showVal(e.threshold)}, ${e.window}, ${e.source})`);
+    }
+    lines.push(`  fix: ${f.fix && f.fix.text}`);
+    if (f.fix && f.fix.action) lines.push(`  gated action: ${f.fix.action.tool} ${JSON.stringify(f.fix.action.input)} (asks for approval; not run)`);
+  }
+  if (report.gaps && report.gaps.length) {
+    lines.push('', 'Could not check:');
+    for (const g of report.gaps) lines.push(`  ${g}`);
+  }
+  if (report.report_id) lines.push('', `report ${report.report_id}`);
+  return lines;
+}

package/lib/core/vmTui.js

@@ -0,0 +1,86 @@
+/**
+ * QUOXON `/vm <verb> <target> [args]`: parse the words, call the shared engine
+ * (lib/core/vm.js, same as `quox vm`), return { lines, tone } for say().
+ * A held call becomes the approval hint (tone 'warn'); other failures throw.
+ */
+import {
+  VM_ACTIONS, NODE_ACTIONS, VmPendingError, pendingHint, makeExec,
+  listVms, vmInfo, vmDoctor, doctorLines, vmAction, vmSnapshot, poolStatus, poolLease, poolDone, poolConfig,
+  nodePower, readPubkey, vmListLines, textOf,
+} from './vm.js';
+
+/** Split argv into positionals and --flag value pairs. */
+export function splitFlags(argv) {
+  const pos = []; const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--')) flags[a.slice(2)] = argv[++i];
+      else flags[a.slice(2)] = true;
+    } else pos.push(a);
+  }
+  return { pos, flags };
+}
+
+const asLines = (t) => String(t).split('\n');
+export const VM_USAGE = 'Usage: /vm <list|info|doctor|start|stop|reboot|shutdown|snapshot|pool|node> <target> [args]';
+
+export async function runVmCommand({ client, orgId, argv, exec: injected }) {
+  const exec = injected || makeExec({ client, orgId });
+  const { pos, flags } = splitFlags(argv || []);
+  const [verb, ...rest] = pos;
+  const reason = typeof flags.reason === 'string' ? flags.reason : undefined;
+  const need = (v, what) => { if (!v) throw new Error(`${what} is required. ${VM_USAGE}`); return v; };
+  try {
+    if (!verb) return { lines: [VM_USAGE], tone: 'warn' };
+    if (verb === 'list') {
+      return { lines: vmListLines(await listVms(exec, { node: flags.node, type: flags.type })) };
+    }
+    if (verb === 'info') {
+      const { vm, resources } = await vmInfo(exec, need(rest[0], 'a VM name or vmid'));
+      return { lines: [`${vm.name || vm.vmid}  vmid ${vm.vmid}  node ${vm.node}  ${vm.type}`, ...asLines(textOf(resources))] };
+    }
+    if (verb === 'doctor') {
+      const report = await vmDoctor(exec, need(rest[0], 'a VM name or vmid'));
+      return { lines: doctorLines(report), tone: report.verdict === 'healthy' ? undefined : 'warn' };
+    }
+    if (VM_ACTIONS.includes(verb)) {
+      const { vm, result } = await vmAction(exec, verb, need(rest[0], 'a VM name or vmid'), { reason });
+      return { lines: [`${verb} ${vm.name || vm.vmid} (vmid ${vm.vmid} on ${vm.node})`, ...asLines(textOf(result))] };
+    }
+    if (verb === 'snapshot') {
+      const { vm, result } = await vmSnapshot(exec, need(rest[0], 'a VM name or vmid'), { name: typeof flags.name === 'string' ? flags.name : undefined, reason });
+      return { lines: [`snapshot ${vm.name || vm.vmid} (vmid ${vm.vmid})`, ...asLines(textOf(result))] };
+    }
+    if (verb === 'pool') {
+      const sub = rest[0];
+      if (sub === 'status') return { lines: asLines(textOf(await poolStatus(exec))) };
+      if (sub === 'lease') {
+        const pubkey = readPubkey(typeof flags['pubkey-file'] === 'string' ? flags['pubkey-file'] : undefined);
+        const p = await poolLease(exec, {
+          lessee: flags.lessee, pubkey, cores: flags.cores, memoryGb: flags['memory-gb'],
+          diskGb: flags['disk-gb'], purpose: flags.purpose, reason,
+        });
+        return { lines: asLines(textOf(p)) };
+      }
+      if (sub === 'done') return { lines: asLines(textOf(await poolDone(exec, need(rest[1], 'a vmid'), { reason }))) };
+      if (sub === 'config') {
+        let input = {};
+        if (flags.set) { try { input = JSON.parse(flags.set); } catch { throw new Error('--set must be a JSON object'); } }
+        return { lines: asLines(textOf(await poolConfig(exec, input, { reason }))) };
+      }
+      return { lines: ['Usage: /vm pool <status|lease|done <vmid>|config>'], tone: 'warn' };
+    }
+    if (verb === 'node') {
+      const [action, name] = rest;
+      if (!NODE_ACTIONS.includes(action)) return { lines: ['Usage: /vm node <reboot|shutdown> <node>'], tone: 'warn' };
+      return { lines: asLines(textOf(await nodePower(exec, action, need(name, 'a node name'), { reason }))) };
+    }
+    return { lines: [`Unknown /vm verb "${verb}". ${VM_USAGE}`], tone: 'warn' };
+  } catch (e) {
+    if (e instanceof VmPendingError) return { lines: [pendingHint(e)], tone: 'warn' };
+    throw e;
+  }
+}

package/lib/core/walkthrough.js

@@ -0,0 +1,35 @@
+/**
+ * WALKTHROUGH for a plain terminal (`quox approvals walkthrough`, `quox inbox walkthrough`): the waiting decisions one
+ * card at a time, using the same card and reply rules as the TUI (quoxon/approvalsView.js). Identity is the decision id.
+ * io = { readLine(prompt) -> Promise<string|null>, write(line), answer(item, key, note) -> Promise<void> }.
+ */
+import { isDecision, walkCard, walkReply, walkNotYesNo, walkNoCatch, walkSummary } from '../quoxon/approvalsView.js';
+
+export async function runWalkthrough(items, io) {
+  const decs = (items || []).filter(isDecision);
+  if (!decs.length) { io.write('No question is waiting for you.'); return { answered: [], skipped: [], left: [] }; }
+  const st = { answered: [], skipped: [], left: [] };
+  io.write(`${decs.length} question${decs.length === 1 ? '' : 's'} waiting for you. One at a time: a choice, then an optional note.`);
+  for (let i = 0; i < decs.length; i++) {
+    const it = decs[i]; const card = walkCard(it, i + 1, decs.length);
+    io.write(''); card.lines.forEach((l) => io.write(l));
+    for (;;) {
+      const line = await io.readLine('Your choice? ');
+      if (line == null) { for (let j = i; j < decs.length; j++) st.left.push(decs[j].title || decs[j].id); io.write(''); walkSummary(st).forEach((l) => io.write(l)); return st; }
+      const rep = walkReply(it, line);
+      if (!rep) { io.write(walkNoCatch(it)); continue; }
+      if (rep.notYesNo) { io.write(walkNotYesNo(it)); continue; }
+      if (rep.defer) { st.skipped.push(it.title || it.id); break; }
+      if (rep.ask) { io.write(`  Asked by ${it.payload.session || 'a session'} (id ${it.id}). ${it.payload.why || 'No further reason was given.'}`); continue; }
+      if (it.payload.high_risk === true && rep.key !== 'n') { io.write('  High risk: a yes needs your PIN, which this plain terminal cannot take. Answer it in `quox` with /approvals walkthrough, or skip it here.'); continue; }
+      try { await io.answer(it, rep.key, rep.note || null); }
+      catch (e) { io.write(`  Not answered (${e.message}). The question stays open.`); continue; }
+      const label = it.payload.options.find((o) => o.key === rep.key).label;
+      io.write(`✔ ${it.title || it.id}: ${label}`);
+      st.answered.push({ title: it.title || it.id, word: label });
+      break;
+    }
+  }
+  io.write(''); walkSummary(st).forEach((l) => io.write(l));
+  return st;
+}

package/lib/dragon/companionView.js

@@ -0,0 +1,34 @@
+/**
+ * The companion view Quoxon actually uses: same contract as dragonlab's integration/companions-v1/view.mjs
+ * (initial / reduce / view -> {frame, caption, hidden, name, scene}), same reducer, same character, same scene and caption
+ * logic, but sized to the classic dragon's footprint and played from a frame cache filled by a worker (frames.js).
+ * view() never renders; it reads. `ready` resolves once the worker has loaded the art.
+ */
+import { pathToFileURL } from 'node:url';
+import { createPlayhead, createWorkerBackend, companionSlot, quantise } from './frames.js';
+
+export async function loadCompanionView(root, id, { still = false, arrival = true, mono = false, persist = true, makeBackend = createWorkerBackend, onFrame = () => {} } = {}) {
+  const url = (p) => pathToFileURL(`${root}/integration/${p}`).href;
+  const [chars, act] = await Promise.all([import(url('companions-v1/characters.mjs')), import(url('hyperion-v3/activity.mjs'))]);
+  const spec = chars.character(id);
+  const backend = await makeBackend({ root, id, still, mono });
+  const play = createPlayhead(backend, { onFirst: onFrame });
+  return {
+    id, name: spec.name, arrivalMs: spec.arrival.duration,
+    initial: act.initialActivity,
+    reduce: act.activityEvent,
+    playhead: play,
+    view(state, now, { cols = 80, rows = 24, mood = null } = {}) {
+      if (!persist && !still && now - state.started >= spec.arrival.duration && !state.approvals.length) return { frame: null, caption: null, hidden: true, name: spec.name, scene: null };
+      const slot = companionSlot(cols, Math.max(1, rows));
+      let v = chars.activityView(id, state, now, { arrival: arrival && !still });
+      // The dragon's job read found something wrong (a down route, an unhealthy host, a failed check): it acts concerned, the same scene
+      // a recorded issue gets. Never the other way round: a good read does not pick a happier scene than the activity allows.
+      if (mood === 'concerned' && !state.approvals.length && !state.issue) { const c = chars.activityView(id, { ...state, issue: true }, now, { arrival: false }); v = { ...v, scene: c.scene, time: c.time, motionTime: c.motionTime }; }
+      const frame = slot.showArt ? play.frame({ scene: v.scene, time: v.time, motionTime: v.motionTime, cols: slot.cols, rows: slot.rows }, { still }) : null;
+      return { frame, caption: v.caption, slot, name: spec.name, scene: v.scene };
+    },
+    dispose() { play.dispose(); },
+  };
+}
+export { companionSlot, quantise };

package/lib/dragon/frames.js

@@ -0,0 +1,118 @@
+/**
+ * Smooth companion playback. Rendering a dragonlab frame costs 100 ms to over a second (Hyperion), and the old path did it
+ * synchronously inside every Ink render, so the whole TUI hitched and the dragon juddered. The classic Q dragon is smooth
+ * because its frames are cheap and the shared clock paces them. This does the same for companions: time is quantised to
+ * the clock's frame step, frames are rendered OFF the main thread (a worker, see renderWorker.js) a few steps ahead of the
+ * playhead into a cache, and the renderer only ever READS the cache. A frame that is not ready yet is held (the last one
+ * shown stays), never rendered inline. The same quantised time returns the same frame object, so an unchanged frame costs
+ * Ink no output at all.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** One animation step, the shared clock's FRAME_MS (about 12 fps). */
+export const STEP_MS = 83;
+/** How many steps ahead of the playhead the worker is asked to fill. */
+export const LOOKAHEAD = 3;
+const CACHE_MAX = 240;
+
+export const quantise = (ms) => Math.max(0, Math.round((Number(ms) || 0) / STEP_MS) * STEP_MS);
+
+/**
+ * Where the art goes. Sized to the classic dragon's footprint (15 rows when the terminal is short, 22 when it is tall
+ * enough that the live region still fits), not the old 39x11 cap. Below ART_MIN a one-line label is used instead.
+ */
+export const ART_MIN_COLS = 64, ART_MIN_ROWS = 30;
+export function companionSlot(cols, rows) {
+  const big = cols >= ART_MIN_COLS && rows >= ART_MIN_ROWS;
+  if (!big) return { showArt: false, cols: 0, rows: 0 };
+  const tall = rows >= 40;
+  return { showArt: true, cols: Math.max(28, Math.min(tall ? 66 : 52, cols - 26)), rows: tall ? 22 : 15 };
+}
+
+/**
+ * Cache + playhead. `backend.render(req) -> Promise<frame>` does the real work somewhere else; at most one request is in
+ * flight, and the next one asked for is always the soonest frame not cached yet (current step first, then lookahead).
+ */
+export function createPlayhead(backend, { onFirst = () => {}, lookahead = LOOKAHEAD, clock = () => Date.now() } = {}) {
+  const cache = new Map(), pending = new Set();
+  const conc = Math.max(1, backend.size || 1); // the backend may be a pool: keep every worker busy
+  let last = null, disposed = false, failed = null, renders = 0, ema = 100;
+  const keyOf = (r) => `${r.scene}|${r.time}|${r.motionTime}|${r.cols}x${r.rows}`;
+  const put = (k, f) => { cache.set(k, f); if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value); };
+  function pump(wants) {
+    for (const next of wants) {
+      if (pending.size >= conc || disposed || failed) return;
+      const k = keyOf(next);
+      if (cache.has(k) || pending.has(k)) continue;
+      pending.add(k); renders++;
+      const began = clock();
+      Promise.resolve().then(() => backend.render(next)).then((f) => {
+        ema = ema * 0.7 + (clock() - began) * 0.3;
+        if (f) { put(k, f); const first = !last; last = f; if (first) onFirst(); }
+      }, (e) => { failed = e; }).finally(() => { pending.delete(k); });
+    }
+  }
+  return {
+    /**
+     * The frame to draw for this scene/time: the cached one for this step, else the newest earlier one (held), else the last
+     * one shown. null before the first ever arrives. The worker is asked for the step the playhead will be at when the
+     * render lands (now + the measured render time), so a slow character still plays at the rate it can render, never stalls the TUI.
+     */
+    frame(req, { still = false } = {}) {
+      const base = (i) => ({ ...req, time: quantise(req.time) + i * STEP_MS, motionTime: quantise(req.motionTime) + i * STEP_MS });
+      const lead = still ? 0 : Math.min(6, Math.ceil(ema / STEP_MS));
+      pump(still ? [base(0)] : Array.from({ length: Math.max(lookahead, conc * 2) + 1 }, (_, i) => base(lead + i)));
+      for (let back = 0; back <= 4; back++) {
+        const hit = cache.get(keyOf(base(-back)));
+        if (hit) { last = hit; return hit; }
+      }
+      return last;
+    },
+    get error() { return failed; },
+    get renders() { return renders; },
+    get size() { return cache.size; },
+    get busy() { return pending.size; },
+    get lead() { return Math.min(6, Math.ceil(ema / STEP_MS)); },
+    dispose() { disposed = true; cache.clear(); backend.dispose?.(); },
+  };
+}
+
+/**
+ * The real backend: worker threads that load the character once and render on request (a small pool, because the heavier
+ * characters take several frame steps to render and the pool renders upcoming steps in parallel). Rejects if no worker can start.
+ */
+export async function createWorkerBackend({ root, id, still = false, mono = false, size = null }, { Worker, cpus = null } = {}) {
+  const W = Worker || (await import('node:worker_threads')).Worker;
+  const avail = cpus ?? (await import('node:os')).availableParallelism?.() ?? 2;
+  const n = Math.max(1, Math.min(size ?? 3, avail - 1));
+  const file = fileURLToPath(new URL('./renderWorker.js', import.meta.url));
+  const waiting = new Map();
+  let seq = 0, dead = null;
+  const fail = (e) => { dead = e; for (const w of waiting.values()) w.reject(e); waiting.clear(); };
+  const spawn = () => new Promise((resolve, reject) => {
+    const worker = new W(file, { workerData: { root, id } });
+    worker.unref?.();
+    worker.once('error', (e) => { fail(e); reject(e); });
+    worker.on('message', (m) => {
+      if (m.type === 'ready') return resolve({ worker, load: 0 });
+      const w = waiting.get(m.seq); if (!w) return;
+      waiting.delete(m.seq); w.slot.load--;
+      if (m.type === 'frame') w.resolve(m.frame); else w.reject(new Error(m.code || 'render failed'));
+    });
+    worker.once('exit', (c) => { fail(new Error(`render worker exited (${c})`)); reject(dead); });
+  });
+  const slots = await Promise.all(Array.from({ length: n }, spawn));
+  return {
+    size: n,
+    render: (req) => new Promise((resolve, reject) => {
+      if (dead) return reject(dead);
+      const slot = slots.reduce((a, b) => (b.load < a.load ? b : a));
+      const s = ++seq; slot.load++; waiting.set(s, { resolve, reject, slot });
+      slot.worker.postMessage({ seq: s, req: { ...req, still, mono } });
+    }),
+    dispose() { fail(new Error('disposed')); for (const s of slots) s.worker.terminate(); },
+  };
+}
+
+/** Test/fallback helper: path-to-URL for a dragonlab module. */
+export const labModule = (root, ...p) => pathToFileURL([root, 'integration', 'companions-v1', ...p].join('/')).href;