quoxcli 0.2.0 → 0.4.0

package/lib/commands/vm.js

@@ -0,0 +1,237 @@
+/**
+ * `quox vm` : drive the HYPERION (agent id atlas) Proxmox tools from the CLI.
+ *
+ *   quox vm list [--node n] [--type qemu|lxc]
+ *   quox vm info <name|vmid>
+ *   quox vm start|stop|reboot|shutdown <name|vmid> [--reason t]
+ *   quox vm doctor <name|vmid>             why is it slow or unhealthy? ranked findings with evidence (read only)
+ *   quox vm snapshot <name|vmid> [--name s] [--reason t]
+ *   quox vm rehearse <name|vmid> [--check url:..|unit:..|cmd:..] [--keep-twin] [--no-wait] -- <command>
+ *   quox vm pool status|lease|done <vmid>|config
+ *
+ * Every action goes through the governed tool route (POST /api/v1/tools/execute).
+ * A held call prints its approval id and the `quox approvals result <id>` hint
+ * and is never re-submitted. Engine shared with the QUOXON /vm command: lib/core/vm.js.
+ */
+
+import { Option } from 'commander';
+import { resolveOrgId } from './helpers.js';
+import { formatOutput, printInfo, printWarning } from '../core/output.js';
+import {
+  VM_ACTIONS, VmPendingError, pendingHint, makeExec, makePoolRest,
+  listVms, vmListRows, vmInfo, vmDoctor, doctorLines, vmAction, vmSnapshot, vmRehearse, waitRehearsal, poolStatus, poolLease, poolDone, poolConfig, poolHostKeyLines,
+  readPubkey, textOf, payloadOf,
+} from '../core/vm.js';
+
+export function registerVmCommands(program, ctx) {
+  const { client, auth } = ctx;
+  const json = () => program.opts().output === 'json';
+
+  const vm = program
+    .command('vm')
+    .description('Proxmox VMs via the HYPERION agent tools (governed: held calls wait for approval)');
+
+  /** Run one verb: auth, exec, and turn a held call into the approval hint (exit 0, no re-submit). */
+  const run = (fn) => async (...args) => {
+    auth.requireAuth();
+    const exec = makeExec({ client, orgId: resolveOrgId(auth, program) });
+    try { await fn(exec, ...args); }
+    catch (e) {
+      if (!(e instanceof VmPendingError)) throw e;
+      if (json()) console.log(JSON.stringify({ pending: true, tool: e.tool, approvalId: e.approvalId, inbox_item_id: e.inboxItemId }));
+      else printWarning(pendingHint(e));
+    }
+  };
+  const emit = (data, human) => {
+    if (json()) console.log(JSON.stringify(data, null, 2));
+    else human();
+  };
+
+  // Read-only cluster views (HYPERION read tools; REST first, Bastion pvesh-read fallback).
+  vm.command('cluster')
+    .description('Proxmox cluster health: quorum and nodes (read only)')
+    .action(run(async (exec) => {
+      const p = payloadOf(await exec('proxmox_cluster_status', {}));
+      emit(p, () => console.log(textOf(p)));
+    }));
+
+  vm.command('ha')
+    .description('Proxmox HA status (read only)')
+    .action(run(async (exec) => {
+      const p = payloadOf(await exec('proxmox_ha_status', {}));
+      emit(p, () => console.log(textOf(p)));
+    }));
+
+  vm.command('templates')
+    .description('Golden templates you can clone from (read only)')
+    .action(run(async (exec) => { const p = payloadOf(await exec('proxmox_templates_list', {})); emit(p, () => console.log(textOf(p))); }));
+
+  vm.command('storage')
+    .description('Proxmox storage pools and usage (read only)')
+    .action(run(async (exec) => { const p = payloadOf(await exec('proxmox_storage', {})); emit(p, () => console.log(textOf(p))); }));
+
+  vm.command('node <name>')
+    .description('CPU, memory and storage of one Proxmox node (read only)')
+    .action(run(async (exec, name) => {
+      if (!/^[a-z0-9-]{1,32}$/.test(name)) throw new Error('node name must be lowercase letters, digits or -');
+      const p = payloadOf(await exec('proxmox_node_resources', { node: name })); emit(p, () => console.log(textOf(p)));
+    }));
+
+  vm.command('resolve <name>')
+    .description('Find which node and VMID a VM name lives on (read only)')
+    .action(run(async (exec, name) => {
+      const p = payloadOf(await exec('proxmox_vm_resolve', /^\d+$/.test(name) ? { vmid: Number(name) } : { name }));
+      emit(p, () => console.log(textOf(p)));
+    }));
+
+  vm.command('list')
+    .description('List VMs (--type lxc lists containers)')
+    .option('--node <name>', 'only this Proxmox node')
+    .option('--type <kind>', 'qemu | lxc', undefined)
+    .action(run(async (exec, options) => {
+      const vms = await listVms(exec, { node: options.node, type: options.type });
+      if (json()) { console.log(JSON.stringify(vms.map((v) => v.raw), null, 2)); return; }
+      formatOutput(
+        { columns: ['vmid', 'name', 'node', 'type', 'status', 'tags'], rows: vmListRows(vms) },
+        { emptyMessage: 'No VMs found.' },
+      );
+    }));
+
+  vm.command('agents')
+    .description('Which running VMs answer on the QEMU guest agent: counts and the VMs that do not (read only)')
+    .option('--node <name>', 'only this Proxmox node')
+    .option('--limit <n>', 'how many gaps to list (default 25, max 50)')
+    .action(run(async (exec, options) => {
+      const p = payloadOf(await exec('proxmox_vms', { guest: true, ...(options.node ? { node: options.node } : {}), ...(options.limit ? { limit: Number(options.limit) } : {}) }));
+      emit(p, () => {
+        printInfo(`Guest agent: ${p.agent_running} of ${p.probed} running VMs answer (${p.not_enabled} not enabled, ${p.not_running} not running, ${p.unknown} unknown; ${p.stopped} stopped VMs not checked)`);
+        formatOutput({ columns: ['vmid', 'name', 'node', 'agent'], rows: p.gaps || [] }, { emptyMessage: 'Every running VM answers on the guest agent.' });
+        if (p.gaps_truncated) printWarning(`${p.gaps_truncated} more not shown (--limit)`);
+      });
+    }));
+
+  vm.command('info <target>')
+    .description('Resources and state of one VM (name or vmid)')
+    .action(run(async (exec, target) => {
+      const { vm: v, resources } = await vmInfo(exec, target);
+      emit({ vm: v, resources }, () => {
+        printInfo(`${v.name || v.vmid}  vmid ${v.vmid}  node ${v.node}  ${v.type}`);
+        console.log(textOf(resources));
+      });
+    }));
+
+  vm.command('doctor <target>')
+    .description('Why is this VM slow or unhealthy? Verdict and ranked findings with evidence and a suggested fix (read only; name or vmid)')
+    .action(run(async (exec, target) => {
+      const report = await vmDoctor(exec, target);
+      emit(report, () => { for (const l of doctorLines(report)) console.log(l); });
+    }));
+
+  for (const action of VM_ACTIONS) {
+    vm.command(`${action} <target>`)
+      .description(`${action[0].toUpperCase()}${action.slice(1)} a VM (name or vmid); write, may need approval`)
+      .option('--reason <text>', 'why (recorded as _reason on the call)')
+      .action(run(async (exec, target, options) => {
+        const { vm: v, result } = await vmAction(exec, action, target, { reason: options.reason });
+        emit({ vm: v, action, result }, () => {
+          printInfo(`${action} ${v.name || v.vmid} (vmid ${v.vmid} on ${v.node})`);
+          console.log(textOf(result));
+        });
+      }));
+  }
+
+  vm.command('snapshot <target>')
+    .description('Snapshot a VM (name or vmid); write, may need approval')
+    .option('--name <snapshot>', 'snapshot name')
+    .option('--reason <text>', 'why (recorded as _reason on the call)')
+    .action(run(async (exec, target, options) => {
+      const { vm: v, result } = await vmSnapshot(exec, target, { name: options.name, reason: options.reason });
+      emit({ vm: v, result }, () => { printInfo(`snapshot ${v.name || v.vmid} (vmid ${v.vmid})`); console.log(textOf(result)); });
+    }));
+
+  vm.command('rehearse <target> <command...>')
+    .description('Rehearse a command on a network-isolated twin of a VM (snapshot, full clone, health checks); slow, writes a snapshot and a VM. Put the command after --')
+    .option('--check <spec>', 'health check before/after: url:http://127.0.0.1:PORT/path | unit:NAME | cmd:COMMAND (repeatable)', (v, acc) => [...acc, v], [])
+    .option('--keep-twin', 'leave the stopped, isolated twin in place')
+    .addOption(new Option('--poll-ms <ms>', 'status poll interval in milliseconds (default 10000)').hideHelp())
+    .option('--no-wait', 'print the rehearsal id and return; do not wait for the verdict')
+    .action(run(async (exec, target, commandWords, options) => {
+      const { vm: v, result: started } = await vmRehearse(exec, target, commandWords.join(' '), { checks: options.check, keepTwin: !!options.keepTwin });
+      const id = started?.rehearsal_id;
+      if (options.wait === false || !id) {
+        emit({ vm: v, result: started }, () => { printInfo(`rehearsal of ${v.name || v.vmid} started${id ? `: ${id}` : ''}`); console.log(textOf(started)); });
+        return;
+      }
+      if (started?.state === 'awaiting_approval') {
+        if (!json()) printWarning(`${started.hint} The approval card lists every host command; approving it starts the run.`);
+        if (!json()) printInfo(`waiting for approval and the run (rehearsal ${id}); Ctrl-C is safe, check later with the proxmox_rehearsal_status tool`);
+      } else if (!json()) printInfo(`rehearsal ${id} of ${v.name || v.vmid} (vmid ${v.vmid} on ${v.node}) running; this takes minutes (a full disk copy)`);
+      const result = await waitRehearsal(exec, id, { intervalMs: Number(options.pollMs) || undefined });
+      emit({ vm: v, result }, () => {
+        printInfo(`rehearsal of ${v.name || v.vmid} (vmid ${v.vmid} on ${v.node}): ${String(result?.verdict || 'unknown').toUpperCase()}  id ${id}`);
+        if (result?.error) printWarning(result.error);
+        console.log(textOf(result));
+      });
+    }));
+
+  const pool = vm.command('pool').description('VM pool: status, lease, done, config');
+
+  pool.command('status')
+    .description('Pool capacity and current leases')
+    .action(run(async (exec) => {
+      const p = await poolStatus(makePoolRest({ client }));
+      emit(p, () => {
+        console.log(textOf(p));
+        for (const v of (p && Array.isArray(p.vms) ? p.vms : [])) if (v.ip_stale) console.log(`vmid ${v.vmid}: ${v.ip} (ip may be stale)`);
+      });
+    }));
+
+  pool.command('lease')
+    .description('Lease a pool VM as you (needs your SSH public key); a warm VM returns at once, a bigger one is built to order (poll pool status)')
+    .option('--lessee <name>', 'who is leasing (default $QUOX_SESSION or hostname)')
+    .option('--pubkey-file <path>', 'SSH public key file (default ~/.ssh/id_ed25519.pub if present)')
+    .option('--cores <n>', 'vCPU cores')
+    .option('--memory-gb <n>', 'memory in GB')
+    .option('--disk-gb <n>', 'disk in GB')
+    .option('--ttl-h <n>', 'hours until the lease expires and the VM is destroyed (default and maximum: the pool lease_ttl_h)')
+    .option('--purpose <text>', 'what the VM is for')
+    .option('--avx', 'place only on an AVX2 lane (needed for local LLM chat); errors if no lane has avx2, never falls back')
+    .option('--node <name>', 'pin the VM to this pool lane (an active, non-denied lane host)')
+    .action(run(async (exec, options) => {
+      const pubkey = readPubkey(options.pubkeyFile);
+      const p = await poolLease(makePoolRest({ client }), {
+        lessee: options.lessee, pubkey, cores: options.cores, memoryGb: options.memoryGb,
+        diskGb: options.diskGb, ttlH: options.ttlH, purpose: options.purpose, avx: options.avx, node: options.node,
+      });
+      emit(p, () => { console.log(textOf(p)); for (const line of poolHostKeyLines(p)) console.log(line); });
+    }));
+
+  pool.command('done <vmid>')
+    .description('Release a leased pool VM as you; it stops being leasable at once, then is destroyed and the pool re-warms')
+    .action(run(async (exec, vmid, options) => {
+      const p = await poolDone(makePoolRest({ client }), vmid);
+      emit(p, () => console.log(poolDoneLine(p, vmid)));
+    }));
+
+  pool.command('config')
+    .description('Configure the pool (JSON settings via --set); org admins only, acting directly')
+    .option('--set <json>', 'settings as a JSON object, e.g. {"admin_keys":["ssh-ed25519 AAAA... owner"],"lanes":[{"node":"hyp-01","template_vmid":7630,"avx2":true}]} (omit to send an empty configure)')
+    .action(run(async (exec, options) => {
+      let input = {};
+      if (options.set) {
+        try { input = JSON.parse(options.set); } catch { throw new Error('--set must be a JSON object'); }
+        if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('--set must be a JSON object');
+      }
+      const p = await poolConfig(makePoolRest({ client }), input);
+      emit(p, () => console.log(textOf(p)));
+    }));
+  // `quox vm node reboot|shutdown` is intentionally not registered: the
+  // proxmox_node_power tool is not built yet, so the CLI must not advertise it.
+}
+
+/** One plain line for `vm pool done`: 202 {state:'recycling'} (current servers) or {released:{destroyed}} (older ones). */
+export function poolDoneLine(p, vmid) {
+  if (p && p.state === 'recycling') return `VM ${p.vmid ?? vmid} is recycling: nobody can lease it now. Destroy and re-warm finish in the background; check with quox vm pool status.`;
+  if (p && p.released && p.released.destroyed) return `VM ${p.released.vmid ?? vmid} destroyed; the pool re-warms.`;
+  return textOf(p);
+}

package/lib/commands/voice.js

@@ -17,6 +17,13 @@ export function friendlyNumbersError(err) {
   return err;
 }
 
+export function parseOnOff(value, flag) {
+  const v = String(value).trim().toLowerCase();
+  if (['on', 'true', 'yes', '1'].includes(v)) return true;
+  if (['off', 'false', 'no', '0'].includes(v)) return false;
+  throw new Error(`${flag} must be on or off`);
+}
+
 export function registerVoiceCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -48,13 +55,37 @@ export function registerVoiceCommands(program, ctx) {
     .command('set <number>')
     .description('Bind a number (E.164) to the active org, optionally with a label and policy')
     .option('--label <text>', 'human label for the number')
-    .option('--policy <json>', 'policy as a JSON object')
+    .option('--policy <json>', 'policy as a JSON object (merged over the current policy)')
+    .option('--brand <text>', 'policy: brand name the line answers as')
+    .option('--opener-name <text>', 'policy: name used in the call opener')
+    .option('--ivr <on|off>', 'policy: IVR menu on or off')
+    .option('--voice <text>', 'policy: voice to speak with')
+    .option('--language <text>', 'policy: language')
+    .option('--persona <text>', 'policy: persona')
+    .option('--verbosity <quiet|verbose>', 'policy: how chatty the agent is')
     .action(async (number, options) => {
       auth.requireAuth();
-      const body = { org_id: resolveOrgId(auth, program) };
+      const orgId = resolveOrgId(auth, program);
+      const body = { org_id: orgId };
       if (options.label !== undefined) body.label = options.label;
+      const flagPolicy = {};
+      if (options.brand !== undefined) flagPolicy.brand = options.brand;
+      if (options.openerName !== undefined) flagPolicy.opener_name = options.openerName;
+      if (options.ivr !== undefined) flagPolicy.ivr = parseOnOff(options.ivr, '--ivr');
+      if (options.voice !== undefined) flagPolicy.voice = options.voice;
+      if (options.language !== undefined) flagPolicy.language = options.language;
+      if (options.persona !== undefined) flagPolicy.persona = options.persona;
+      if (options.verbosity !== undefined) flagPolicy.verbosity = options.verbosity;
+      let jsonPolicy;
       if (options.policy !== undefined) {
-        try { body.policy = JSON.parse(options.policy); } catch { throw new Error('--policy must be valid JSON'); }
+        try { jsonPolicy = JSON.parse(options.policy); } catch { throw new Error('--policy must be valid JSON'); }
+      }
+      if (jsonPolicy !== undefined || Object.keys(flagPolicy).length > 0) {
+        // Read-modify-write so one flag never clobbers the other policy keys.
+        const lep = resolveEndpoint('telephony.numbers.list');
+        const cur = await client.get(lep.path, { service: lep.service, query: { org_id: orgId } });
+        const existing = ((cur && cur.numbers) || []).find((n) => n.number === number);
+        body.policy = { ...((existing && existing.policy) || {}), ...(jsonPolicy || {}), ...flagPolicy };
       }
       const ep = resolveEndpoint('telephony.numbers.set', { number });
       let data;

package/lib/commands/volt.js

@@ -27,6 +27,23 @@ function unwrapVoltBundle(data) {
   return bundle;
 }
 
+/**
+ * quox#935: a bundle is ONE JSON object carrying `manifest` and/or
+ * `events_ndjson`. An events NDJSON file also starts with '{' on every line,
+ * so a first-character check took every NDJSON file for a bundle and the
+ * whole-file JSON.parse failed. Decide by parsing instead.
+ */
+export function looksLikeBundle(raw) {
+  try {
+    const p = JSON.parse(raw);
+    return !!p && typeof p === 'object' && !Array.isArray(p) && ('manifest' in p || 'events_ndjson' in p);
+  } catch {
+    return false;
+  }
+}
+
+const ndjsonEvents = (raw) => raw.trim().split('\n').filter((l) => l.trim()).map((l) => JSON.parse(l));
+
 export function registerVoltCommands(program, ctx = {}) {
   const { client, auth } = ctx;
 
@@ -47,7 +64,7 @@ export function registerVoltCommands(program, ctx = {}) {
       const raw = await readFile(file, 'utf8');
 
       // Detect if this is a bundle (JSON with manifest) or raw NDJSON
-      const isBundle = raw.trimStart().startsWith('{');
+      const isBundle = looksLikeBundle(raw);
 
       if (isBundle) {
         // fleet #447: a persisted per-run bundle can be manifest_only (no
@@ -190,7 +207,7 @@ export function registerVoltCommands(program, ctx = {}) {
     .option('--manifest', 'show bundle manifest only')
     .action(async (file, options) => {
       const raw = await readFile(file, 'utf8');
-      const isBundle = raw.trimStart().startsWith('{');
+      const isBundle = looksLikeBundle(raw);
 
       let events;
       let manifest = null;
@@ -432,9 +449,34 @@ export function registerVoltCommands(program, ctx = {}) {
   volt
     .command('summary')
     .description('Quick summary of a bundle (no verification)')
-    .argument('<file>', 'path to bundle JSON file')
+    .argument('<file>', 'path to bundle JSON or events NDJSON file')
     .action(async (file) => {
       const raw = await readFile(file, 'utf8');
+      // quox#935: an events NDJSON file gets a chain summary instead of a crash.
+      if (!looksLikeBundle(raw)) {
+        let evs;
+        try { evs = ndjsonEvents(raw); } catch {
+          printWarning('File is neither a VOLT evidence bundle nor an events NDJSON file');
+          process.exitCode = 1;
+          return;
+        }
+        const counts = {};
+        for (const ev of evs) counts[ev.event_type] = (counts[ev.event_type] || 0) + 1;
+        console.log('');
+        console.log(chalk.bold(`VOLT NDJSON Chain Summary (${evs.length} events)`));
+        console.log(chalk.gray('─'.repeat(40)));
+        console.log(`  Run ID:     ${chalk.cyan(evs[0]?.run_id || 'N/A')}`);
+        console.log(`  Events:     ${evs.length} events`);
+        if (Object.keys(counts).length > 0) {
+          console.log('');
+          console.log(chalk.bold('  Event Types:'));
+          for (const [type, count] of Object.entries(counts).sort((a, b) => b[1] - a[1])) {
+            console.log(`    ${String(count).padStart(4)}  ${type}`);
+          }
+        }
+        console.log('');
+        return;
+      }
       const parsed = JSON.parse(raw);
 
       if (!parsed.manifest) {

package/lib/commands/walkthrough.js

@@ -0,0 +1,32 @@
+/** `quox approvals walkthrough` and `quox inbox walkthrough`: the waiting questions, one card at a time. */
+import { createInterface } from 'node:readline';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { resolveOrgId } from './helpers.js';
+import { runWalkthrough } from '../core/walkthrough.js';
+
+export function attachWalkthrough(parent, { client, auth }, program) {
+  parent
+    .command('walkthrough')
+    .description('Walk through the questions waiting for you one at a time: what it does, why, my advice, then your choice')
+    .action(async () => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const lp = resolveEndpoint('inbox.list', { orgId });
+      const data = await client.get(lp.path, { service: lp.service, query: { status: 'open', limit: 200 } });
+      const items = (data && (data.items || data)) || [];
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const lines = []; let waiting = null; let closed = false;
+      rl.on('line', (l) => { if (waiting) { const w = waiting; waiting = null; w(l); } else lines.push(l); });
+      rl.on('close', () => { closed = true; if (waiting) { const w = waiting; waiting = null; w(null); } });
+      const readLine = (prompt) => new Promise((res) => { if (lines.length) return res(lines.shift()); if (closed) return res(null); process.stdout.write(prompt); waiting = res; });
+      try {
+        await runWalkthrough(Array.isArray(items) ? items : [], {
+          readLine, write: (l) => console.log(l),
+          answer: async (it, key, note) => {
+            const ep = resolveEndpoint('inbox.respond', { orgId, itemId: it.id });
+            await client.post(ep.path, { service: ep.service, body: { action: 'answer', option: key, ...(note ? { comment: String(note).slice(0, 4000) } : {}) } });
+          },
+        });
+      } finally { rl.close(); }
+    });
+}

package/lib/commands/watch.js

@@ -7,6 +7,50 @@
 
 import chalk from 'chalk';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { joinServiceUrl } from '../core/config.js';
+
+/** Seconds to a short "1d 1h" / "3h 12m" / "45s" label. */
+function shortUptime(sec) {
+  if (typeof sec !== 'number' || !Number.isFinite(sec)) return '-';
+  const d = Math.floor(sec / 86400); const h = Math.floor((sec % 86400) / 3600); const m = Math.floor((sec % 3600) / 60);
+  if (d) return `${d}d ${h}h`;
+  if (h) return `${h}h ${m}m`;
+  return m ? `${m}m` : `${Math.floor(sec)}s`;
+}
+
+/**
+ * quox#946: one row per agent from GET /api/v1/agents (the same source as
+ * `quox fleet agents`). /api/v1/fleet/status carries totals only, which is why
+ * the old dashboard always said "No agents reporting".
+ */
+export function fleetRows(data) {
+  const list = Array.isArray(data) ? data : (Array.isArray(data?.agents) ? data.agents : []);
+  return list.map((a) => ({
+    host_id: a.host_id || a.system?.hostname || '-',
+    status: typeof a.status === 'object' ? (a.status?.health ?? a.status?.connection ?? 'unknown') : (a.status || 'unknown'),
+    cpu_percent: Math.round(a.resources?.cpu?.usage_percent ?? a.cpu_percent ?? 0),
+    memory_percent: Math.round(a.resources?.memory?.usage_percent ?? a.memory_percent ?? 0),
+    uptime: shortUptime(a.system?.uptime_seconds ?? a.uptime_seconds),
+    version: a.agent?.version || a.version || '-',
+    last_seen_seconds: typeof a.status?.last_seen_seconds === 'number' ? a.status.last_seen_seconds : null,
+  }));
+}
+
+/**
+ * quox#946: a slow service is a TIMEOUT, a refused connection is DOWN, a non-2xx
+ * answer is DEGRADED. The old dashboard called every failure "down".
+ */
+export async function probeService(url, fetchImpl = fetch, timeoutMs = 8000) {
+  const start = Date.now();
+  try {
+    const res = await fetchImpl(url, { signal: AbortSignal.timeout(timeoutMs) });
+    const latency_ms = Date.now() - start;
+    return res.ok ? { status: 'healthy', latency_ms, code: res.status } : { status: 'degraded', latency_ms, code: res.status };
+  } catch (err) {
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError') return { status: 'timeout', latency_ms: Date.now() - start };
+    return { status: 'down', reason: err?.cause?.code || err?.message || 'error' };
+  }
+}
 
 export function registerWatchCommands(program, { client, auth, config }) {
   const watch = program
@@ -20,13 +64,22 @@ export function registerWatchCommands(program, { client, auth, config }) {
     .action(async (opts) => {
       auth.requireAuth();
       const interval = Math.max(2, parseInt(opts.interval, 10) || 5) * 1000;
+      const fetchAgents = async () => {
+        const ep = resolveEndpoint('v1.agents.list');
+        return fleetRows(await client.get(ep.path, { service: ep.service }));
+      };
+
+      // --json: one snapshot, then exit (a dashboard loop is not machine output).
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ agents: await fetchAgents(), timestamp: new Date().toISOString() }, null, 2));
+        return;
+      }
 
       console.log(chalk.cyan('Fleet Watch') + chalk.dim(' (Ctrl+C to stop)\n'));
 
       const tick = async () => {
         try {
-          const data = await client.get(resolveEndpoint('v1.fleet.status.list').path, { service: resolveEndpoint('v1.fleet.status.list').service });
-          const agents = data.agents || [];
+          const agents = await fetchAgents();
 
           // Clear screen and redraw
           process.stdout.write('\x1B[2J\x1B[H');
@@ -50,7 +103,7 @@ export function registerWatchCommands(program, { client, auth, config }) {
                 `${statusColor(String(a.status || 'unknown').padEnd(10))} ` +
                 `${cpuColor(String((a.cpu_percent || 0) + '%').padEnd(7))} ` +
                 `${memColor(String((a.memory_percent || 0) + '%').padEnd(7))} ` +
-                `${String(a.uptime || '-').padEnd(10)} ` +
+                `${String(a.uptime).padEnd(10)} ` +
                 `${chalk.dim(a.version || '-')}`
               );
             }
@@ -82,29 +135,28 @@ export function registerWatchCommands(program, { client, auth, config }) {
         { name: 'orchestrator', port: 3100, path: '/health' },
       ];
 
+      const probeAll = async () => Promise.all(services.map(async (svc) => ({
+        name: svc.name,
+        ...(await probeService(joinServiceUrl(config.getServiceUrl(svc.name), svc.path).href)),
+      })));
+
+      // --json: one snapshot, then exit.
+      if (program.opts().output === 'json') {
+        console.log(JSON.stringify({ services: await probeAll(), timestamp: new Date().toISOString() }, null, 2));
+        return;
+      }
+
       const tick = async () => {
+        const results = await probeAll();
         process.stdout.write('\x1B[2J\x1B[H');
         console.log(chalk.cyan.bold('QuoxCLI Service Watch') + chalk.dim(`  ${new Date().toLocaleTimeString()}  (Ctrl+C to stop)`));
         console.log(chalk.dim('─'.repeat(50)));
-
-        for (const svc of services) {
-          try {
-            const svcUrl = config.getServiceUrl(svc.name);
-            const fullUrl = new URL(svc.path, svcUrl);
-            const start = Date.now();
-            const res = await fetch(fullUrl.href, { signal: AbortSignal.timeout(5000) });
-            const latency = Date.now() - start;
-
-            if (res.ok) {
-              console.log(`  ${chalk.green('●')} ${svc.name.padEnd(14)} ${chalk.green('healthy')}  ${chalk.dim(latency + 'ms')}`);
-            } else {
-              console.log(`  ${chalk.yellow('●')} ${svc.name.padEnd(14)} ${chalk.yellow(res.status)}     ${chalk.dim(latency + 'ms')}`);
-            }
-          } catch {
-            console.log(`  ${chalk.red('●')} ${svc.name.padEnd(14)} ${chalk.red('down')}`);
-          }
+        for (const r of results) {
+          if (r.status === 'healthy') console.log(`  ${chalk.green('●')} ${r.name.padEnd(14)} ${chalk.green('healthy')}  ${chalk.dim(r.latency_ms + 'ms')}`);
+          else if (r.status === 'degraded') console.log(`  ${chalk.yellow('●')} ${r.name.padEnd(14)} ${chalk.yellow(r.code)}     ${chalk.dim(r.latency_ms + 'ms')}`);
+          else if (r.status === 'timeout') console.log(`  ${chalk.yellow('●')} ${r.name.padEnd(14)} ${chalk.yellow('slow (no answer in ' + Math.round(r.latency_ms / 1000) + 's)')}`);
+          else console.log(`  ${chalk.red('●')} ${r.name.padEnd(14)} ${chalk.red('down')}  ${chalk.dim(r.reason || '')}`);
         }
-
         console.log(chalk.dim('\n  refreshing every ' + (interval / 1000) + 's'));
       };
 

package/lib/commands/welcome.js

@@ -0,0 +1,14 @@
+/**
+ * quox welcome: print the greeting from the first screen again. Read only: no server, no login, and it never
+ * touches the first-run marker or any config.
+ */
+export function registerWelcomeCommand(program) {
+  program
+    .command('welcome')
+    .description('Show the welcome screen again (read only; changes no setup or config)')
+    .action(async () => {
+      const { INTRO_HEAD, INTRO_LINES } = await import('../quoxon/render.js');
+      const { packageVersion } = await import('../quoxon/welcome.js');
+      console.log([INTRO_HEAD, ...INTRO_LINES, `${packageVersion()} · ${process.cwd()}`].join('\n'));
+    });
+}