quoxcli 0.3.1 → 0.5.0

package/lib/core/profileTrust.js

@@ -0,0 +1,182 @@
+/**
+ * ONBOARD-P1: per-profile trust for a server's own certificate (`quox connect`).
+ *
+ * A new QuoxCORE serves a self-signed edge certificate. The sanctioned fix is to trust THAT certificate, for the
+ * profile that talks to that server, and nowhere else. This module:
+ *   - reads the certificate chain a server presents (a handshake only: nothing is ever sent over it, the
+ *     certificate is shown to the user and trusted only after they say yes),
+ *   - refuses what trusting cannot fix (expired, wrong name),
+ *   - stores the PEM under ~/.config/quox/certs/<profile>.pem and records it on the profile as `caCert`,
+ *   - makes later requests for that profile trust it: bin/quox.js re-runs itself once with NODE_EXTRA_CA_CERTS
+ *     set to the profile's file (Node 20 has no per-request CA for the built-in fetch). The global environment
+ *     is never touched, and TLS verification is never turned off.
+ */
+import tls from 'node:tls';
+import https from 'node:https';
+import { createHash, X509Certificate } from 'node:crypto';
+import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getConfigDir, getConfigFile, resolveProfileFlagFromArgv } from './config.js';
+
+const CODES_TRUST_CAN_FIX = new Set(['DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY']);
+export const isTrustFixable = (code) => CODES_TRUST_CAN_FIX.has(code);
+
+const TLS_SENTENCE_CODES = new Set([...CODES_TRUST_CAN_FIX, 'CERT_HAS_EXPIRED', 'ERR_TLS_CERT_ALTNAME_INVALID']);
+/**
+ * H4: one plain sentence for a TLS certificate failure, with the fix. undici reports all of these as a bare
+ * "fetch failed". -> null when `code` is not a certificate-trust code.
+ * A self-signed or unknown-issuer certificate is fixed by trusting it for one profile; an expired or wrong-name
+ * certificate is NOT (trusting a file would not cure it), so those say what does.
+ */
+export function tlsFailureSentence(code, url) {
+  if (!TLS_SENTENCE_CODES.has(code)) return null;
+  if (code === 'CERT_HAS_EXPIRED') return `${url} presents a certificate that has expired (${code}). Trusting it would not help: the server needs a new certificate.`;
+  if (code === 'ERR_TLS_CERT_ALTNAME_INVALID') return `${url} presents a certificate that does not name the address you used (${code}). Use an address the certificate names; trusting it would not help.`;
+  return `${url} presents a certificate this machine does not trust: it is self-signed or its issuer is unknown (${code}). If this is your own server, check its fingerprint and trust it for one profile only: quox connect ${url} --trust-cert`;
+}
+
+export const certDir = () => join(getConfigDir(), 'certs');
+const safeName = (profile) => String(profile).replace(/[^A-Za-z0-9._-]/g, '_').replace(/\.{2,}/g, '_');
+export const certPathFor = (profile) => join(certDir(), `${safeName(profile)}.pem`);
+
+/** A short, filesystem- and shell-safe profile name derived from a server URL (203.0.113.10:3000 -> 203-0-113-10). */
+export function profileNameForUrl(url) {
+  try { return new URL(url).hostname.replace(/[^A-Za-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'server'; } catch { return 'server'; }
+}
+
+const pemOf = (der) => `-----BEGIN CERTIFICATE-----\n${der.toString('base64').match(/.{1,64}/g).join('\n')}\n-----END CERTIFICATE-----\n`;
+export const fingerprint256 = (der) => createHash('sha256').update(der).digest('hex').toUpperCase().match(/../g).join(':');
+
+/**
+ * Read the certificate chain `url` presents. -> { host, port, chain: [{ subject, issuer, validFrom, validTo, san,
+ * fingerprint256, pem, isCA, selfSigned }], leaf } . Throws a plain Error when there is no TLS answer.
+ * The handshake runs with chain validation off ONLY so the certificate can be read; the socket is destroyed
+ * before any byte of application data, so nothing is trusted and nothing is sent.
+ */
+export function readPeerChain(url, { timeout = 5000, connect = tls.connect } = {}) {
+  const u = new URL(url);
+  if (u.protocol !== 'https:') return Promise.reject(new Error('the address is not https://, so there is no certificate to trust'));
+  const host = u.hostname;
+  const port = Number(u.port || 443);
+  return new Promise((resolve, reject) => {
+    const isIp = /^[\d.]+$/.test(host) || host.includes(':');
+    const sock = connect({ host, port, servername: isIp ? undefined : host, rejectUnauthorized: false, timeout }, () => {
+      try {
+        const peer = sock.getPeerCertificate(true);
+        sock.destroy();
+        if (!peer || !peer.raw) return reject(new Error('the server presented no certificate'));
+        const seen = new Set();
+        const chain = [];
+        for (let c = peer; c && c.raw && !seen.has(c.fingerprint256); c = c.issuerCertificate) {
+          seen.add(c.fingerprint256);
+          let isCA = false;
+          try { isCA = Boolean(new X509Certificate(c.raw).ca); } catch { /* unreadable: not a CA */ }
+          const fp = fingerprint256(c.raw);
+          chain.push({
+            subject: c.subject?.CN || Object.values(c.subject || {}).join(' ') || '(no subject)',
+            issuer: c.issuer?.CN || Object.values(c.issuer || {}).join(' ') || '(no issuer)',
+            validFrom: c.valid_from, validTo: c.valid_to, san: c.subjectaltname || '',
+            fingerprint256: fp, pem: pemOf(c.raw), isCA,
+            selfSigned: JSON.stringify(c.subject) === JSON.stringify(c.issuer)
+          });
+        }
+        resolve({ host, port, chain, leaf: peer });
+      } catch (e) { sock.destroy(); reject(e); }
+    });
+    sock.on('error', (e) => reject(Object.assign(new Error(e.message), { code: e.code })));
+    sock.on('timeout', () => { sock.destroy(); reject(Object.assign(new Error(`no answer within ${Math.round(timeout / 1000)} s`), { code: 'TIMEOUT' })); });
+  });
+}
+
+/** Trusting a certificate only fixes an untrusted-but-valid one. -> null when fine, else the reason it cannot be trusted. */
+export function untrustableReason(peer, host, { now = Date.now(), checkServerIdentity = tls.checkServerIdentity } = {}) {
+  const from = Date.parse(peer.leaf?.valid_from), to = Date.parse(peer.leaf?.valid_to);
+  if (Number.isFinite(to) && to < now) return `its certificate expired on ${peer.leaf.valid_to}. Trusting it would not help; the server needs a new certificate.`;
+  if (Number.isFinite(from) && from > now) return `its certificate is not valid until ${peer.leaf.valid_from} (check this machine's clock).`;
+  const err = checkServerIdentity(host, peer.leaf);
+  if (err) return `its certificate does not name ${host} (${(peer.leaf?.subjectaltname || 'no names').replace(/IP Address:/g, '')}). Trusting it would not help; use an address the certificate names.`;
+  return null;
+}
+
+/** The card the user compares with `quox server status` on the server. */
+export function certCard(url, peer) {
+  const leaf = peer.chain[0];
+  const lines = [
+    `${url} presents this certificate:`,
+    `  Subject      ${leaf.subject}`,
+    `  Issuer       ${leaf.selfSigned ? `${leaf.issuer} (self-signed)` : leaf.issuer}`,
+    `  Names        ${leaf.san.replace(/IP Address:/g, 'IP:') || '(none listed)'}`,
+    `  Valid        ${leaf.validFrom} to ${leaf.validTo}`,
+    `  SHA256       ${leaf.fingerprint256}`
+  ];
+  for (const c of peer.chain.slice(1)) lines.push(`  Signed by    ${c.subject}  SHA256 ${c.fingerprint256}`);
+  lines.push('Compare the SHA256 with the one on the server (run `quox server status` there) before you trust it.');
+  return lines.join('\n');
+}
+
+/** Write the chain's PEM for `profile` (0600 file in a 0700 directory). -> the path. */
+export function storeProfileCert(profile, peer) {
+  const dir = certDir();
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { chmodSync(dir, 0o700); } catch { /* best effort */ }
+  const file = certPathFor(profile);
+  writeFileSync(file, peer.chain.map((c) => c.pem).join(''), { mode: 0o600 });
+  try { chmodSync(file, 0o600); } catch { /* best effort */ }
+  return file;
+}
+export function removeProfileCert(profile) { try { unlinkSync(certPathFor(profile)); } catch { /* not there */ } }
+
+/** A fetch-shaped function that trusts exactly `ca` (a PEM string) for this one request. For probeQuoxCore. */
+export function fetchTrusting(ca, { request = https.request } = {}) {
+  return (target, { signal, headers } = {}) => new Promise((resolve, reject) => {
+    const req = request(target, { ca, headers, signal, method: 'GET' }, (res) => {
+      const chunks = [];
+      res.on('data', (d) => chunks.push(d));
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        resolve({ ok: res.statusCode >= 200 && res.statusCode < 300, status: res.statusCode, text: async () => body });
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/** The CA file recorded on `profileName` in a parsed config object, if it exists on disk. */
+export function profileCaPath(configData, profileName, { exists = existsSync } = {}) {
+  const f = configData?.profiles?.[profileName]?.caCert;
+  return typeof f === 'string' && f && exists(f) ? f : null;
+}
+
+/**
+ * bin/quox.js calls this first. When the profile this run uses has a stored server certificate (and the user has
+ * not set their own NODE_EXTRA_CA_CERTS), re-run the same command with NODE_EXTRA_CA_CERTS set to it, for this
+ * process tree only. -> an exit code when it ran the command, or null (carry on in this process).
+ */
+export function reexecWithProfileTrust(argv, env = process.env, {
+  readConfig = () => JSON.parse(readFileSync(getConfigFile(), 'utf8')),
+  spawn = spawnSync, exists = existsSync, execPath = process.execPath, execArgv = process.execArgv, script = process.argv[1]
+} = {}) {
+  // A NODE_EXTRA_CA_CERTS the user set themselves always wins. One WE set (QUOX_PROFILE_TRUST_APPLIED names the file)
+  // belongs to the profile that set it: a nested `quox -p other` must not inherit it.
+  const ours = env.QUOX_PROFILE_TRUST_APPLIED && env.NODE_EXTRA_CA_CERTS === env.QUOX_PROFILE_TRUST_APPLIED;
+  if (env.NODE_EXTRA_CA_CERTS && !ours) return null;
+  let data;
+  try { data = readConfig(); } catch { return null; }
+  const name = resolveProfileFlagFromArgv(argv) || env.QUOX_PROFILE || data?.activeProfile;
+  const ca = name ? profileCaPath(data, name, { exists }) : null;
+  if (ours ? ca === env.NODE_EXTRA_CA_CERTS : !ca) return null; // already right, or nothing to apply
+  const childEnv = { ...env };
+  if (ca) { childEnv.NODE_EXTRA_CA_CERTS = ca; childEnv.QUOX_PROFILE_TRUST_APPLIED = ca; }
+  else { delete childEnv.NODE_EXTRA_CA_CERTS; delete childEnv.QUOX_PROFILE_TRUST_APPLIED; }
+  // Ctrl-C reaches the whole foreground group; the child handles it, this parent must outlive it to pass on the code.
+  const hold = () => {};
+  process.on('SIGINT', hold);
+  try {
+    const r = spawn(execPath, [...execArgv, script, ...argv], { stdio: 'inherit', env: childEnv });
+    if (typeof r.status === 'number') return r.status;
+    return r.signal === 'SIGINT' ? 130 : 1;
+  } finally { process.removeListener('SIGINT', hold); }
+}

package/lib/core/quoxglyph.js

@@ -30,6 +30,7 @@ export const ICONS = {
   quoxseo: '📈 QUOXSEO', reach: '💥 REACH', vulcan: '🌋 VULCAN',
   quoxvoice: '📞 QUOXVOICE', quoxsecurity: '🛡️ QUOXSECURITY', quoxpert: '🎓 QUOXPERT',
   quoxslots: '📍 QUOXSLOTS',
+  gripe: '📣 GRIPE',
   quox: 'Ⓠ QUOX'
 };
 export const BUDGETS = { VERB_MAX: 48, RESULT_MAX: 40, LINE_MAX: 120, TREE_MAX: 6, TABLE_MAX: 6 };
@@ -74,7 +75,7 @@ export function line(surface, verb, opts = {}) {
   const col = on();
   const name = brandName(iconFor(surface), col);
   const sep = col ? `${DIM}│${R}` : '│';
-  let tail = opts.result ? trunc(opts.result, BUDGETS.RESULT_MAX) : '';
+  let tail = opts.result ? trunc(opts.result, opts.max || BUDGETS.RESULT_MAX) : '';
   if (opts.ms !== undefined) {
     const d = col ? `${DIM}${opts.ms}ms${R}` : `${opts.ms}ms`;
     tail = tail ? `${tail} ${col ? DIM + '·' + R : '·'} ${d}` : d;
@@ -85,6 +86,26 @@ export function line(surface, verb, opts = {}) {
   return tail ? `${name} ${sep} ${v} ${sep} ${tail}` : `${name} ${sep} ${v}`;
 }
 
+const GRIPE_TITLE_MAX = 50;
+const gripeTitle = (t) => trunc(String(t || '').split('\n')[0].trim(), GRIPE_TITLE_MAX);
+
+/** GRIPE-1460: `📣 GRIPE │ filed #N owner/repo │ "title" ✔` for an issue URL (the URL itself goes on the next line). */
+export function gripeFiledLine(url, title) {
+  const m = /github\.com\/([^/]+\/[^/]+)\/issues\/(\d+)/.exec(String(url || ''));
+  const verb = m ? `filed #${m[2]} ${m[1]}` : 'filed issue';
+  return line('gripe', verb, { result: `"${gripeTitle(title)}"`, status: 'ok', max: GRIPE_TITLE_MAX + 2 });
+}
+
+/** GRIPE-1460: a gripe saved earlier and filed on retry: `📣 GRIPE │ queued gripe filed │ <url> ✔`. */
+export function gripeQueuedFiledLine(url) {
+  return line('gripe', 'queued gripe filed', { result: String(url), status: 'ok', max: 200 });
+}
+
+/** GRIPE-1460: `📣 GRIPE │ file "title" │ ✖ <exact error>`. */
+export function gripeFailedLine(title, error) {
+  return line('gripe', `file "${trunc(gripeTitle(title), 30)}"`, { result: `${STATUS.fail.glyph} ${error}`, max: 400 });
+}
+
 /** Gradient progress meter: ▰▰▰▱ done/total (or pct when total omitted). */
 export function meter(done, total, width = 8) {
   const col = on();

package/lib/core/router.js

@@ -8,6 +8,7 @@
  * output is tested without a router.
  */
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxUserError } from './errors.js';
 
 /** verb -> the tool it runs. All read-only (aoclClassification layer 1, autonomy FULL). */
 export const ROUTER_TOOLS = Object.freeze({
@@ -21,6 +22,18 @@ export const ROUTER_TOOLS = Object.freeze({
   inventory: 'mikrotik_discovery_inventory',
 });
 
+/** The tool route refused because this identity lacks the router grant: say that, keep the plumbing in detail. */
+function notPermitted(tool, raw, path) {
+  const err = new QuoxUserError('This identity is not allowed to read the router: the router tools are not granted to it.', {
+    next: 'run it from an identity that has the router tools (`quox config profile list`), or ask an org owner or admin to grant them.',
+    code: 'not_permitted',
+  });
+  err.debug = { tool, route: `POST ${path}`, server_said: raw }; // --json and --verbose only; never the headline
+  err.toolError = raw;
+  err.tool = tool;
+  return err;
+}
+
 export function makeRouterExec({ client, orgId }) {
   return async function exec(tool, input = {}) {
     const ep = resolveEndpoint('v1.tools.execute');
@@ -28,6 +41,7 @@ export function makeRouterExec({ client, orgId }) {
     if (orgId) body.org_id = orgId;
     const data = await client.post(ep.path, { service: ep.service, body });
     if (data && data.success === false) {
+      if (/not granted to agent/i.test(String(data.error || ''))) throw notPermitted(tool, data.error, ep.path);
       const detail = data.detail ? ` (${data.detail})` : '';
       const err = new Error(`${tool} via POST ${ep.path} returned success:false: ${data.error || 'unknown error'}${detail}`);
       err.toolError = data.error || 'unknown error';

package/lib/core/sessionHeartbeat.js

@@ -15,7 +15,7 @@
  *    released on every exit path.
  * Pure parts take injected tmux output / held slots / attach lookup.
  */
-import { spawn as realSpawn, spawnSync as realSpawnSync } from 'node:child_process';
+import { spawnSync as realSpawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, appendFileSync, truncateSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -70,9 +70,10 @@ export function buildBeat({ probe, backend = null, agent = null, slot = null, he
   };
 }
 
-/** Live probe of one tmux session (exact match). null when it does not exist. */
+/** Live probe of one tmux session (exact match). null when it does not exist.
+ *  `=name:` (session form): tmux 3.4 answers a bare `=name` with an empty line. */
 export function probeTmux(name, spawnSync = realSpawnSync) {
-  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}`, PROBE_FORMAT], { encoding: 'utf8' });
+  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}:`, PROBE_FORMAT], { encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null;
   const p = parseProbe(r.stdout);
   return p && p.name === name ? p : null;
@@ -177,16 +178,19 @@ export function fileLogger(name, dir = HB_DIR()) {
  * Start the detached heartbeat child for a tmux session the wrapper launched.
  * The child is this same quox binary; it survives the wrapper exiting on detach.
  */
-export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawn = realSpawn, argv = process.argv, execPath = process.execPath } = {}) {
+// Spawned by a short-lived node that exits at once, so the heartbeat is never
+// the wrapper's child: the wrapper blocks in spawnSync(tmux) for the session's
+// life and could not reap it (ZOMBIES 2026-10-24, one defunct per wrapper).
+const DETACH_LAUNCHER = "const{spawn}=require('node:child_process');const c=spawn(process.argv[1],process.argv.slice(2),{detached:true,stdio:'ignore'});c.on('error',()=>{});c.unref();";
+
+export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawnSync = realSpawnSync, argv = process.argv, execPath = process.execPath } = {}) {
   if (!argv[1]) return false;
   const args = [argv[1], 'sessions', 'heartbeat', tmuxSession, '--loop'];
   if (backend) args.push('--backend', backend);
   if (agent) args.push('--agent', agent);
   if (slot) args.push('--slot', slot);
   try {
-    const child = spawn(execPath, args, { detached: true, stdio: 'ignore' });
-    if (child && child.on) child.on('error', () => {});
-    if (child && child.unref) child.unref();
-    return true;
+    const r = spawnSync(execPath, ['-e', DETACH_LAUNCHER, execPath, ...args], { stdio: 'ignore', timeout: 10_000 });
+    return !!r && !r.error && r.status === 0;
   } catch { return false; }
 }

package/lib/core/shortcut.js

@@ -0,0 +1,83 @@
+/**
+ * `quox shortcut add|remove` (QUOXON-Q): a short command (default `q`) that is a symlink to this quox.
+ *
+ * Rules: never shadow an existing command (a `q` already on PATH that is not ours is refused and named);
+ * a user-writable directory only (the one quox lives in, else ~/.local/bin); no sudo; no shell rc edits (a symlink
+ * works in every shell and script); idempotent; remove only ever removes a link that points at this quox.
+ * Local only: nothing is sent anywhere.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_NAME = 'q';
+export const NAME_OK = /^[A-Za-z][A-Za-z0-9_.-]{0,30}$/;
+export const QUOX_ENTRY = fileURLToPath(new URL('../../bin/quox.js', import.meta.url));
+
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+const isExec = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
+const writable = (d) => { try { fs.accessSync(d, fs.constants.W_OK); return fs.statSync(d).isDirectory(); } catch { return false; } };
+const pathDirs = (env) => String(env.PATH || '').split(path.delimiter).filter(Boolean);
+
+/** `command -v name` over PATH -> the first executable path, or null. */
+export function whichOnPath(name, env = process.env) {
+  for (const d of pathDirs(env)) { const p = path.join(d, name); if (isExec(p)) return p; }
+  return null;
+}
+
+/** Where the link goes: { dir, onPath, target }. target is what `q` will point at. */
+export function planShortcut({ env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  const realEntry = real(entry) || entry;
+  const quoxOnPath = whichOnPath('quox', env);
+  // The `quox` on PATH may be a wrapper script rather than a link to this entry: it is still "this quox".
+  const onPathReal = quoxOnPath;
+  const target = onPathReal || realEntry;
+  const reals = new Set([realEntry, quoxOnPath && real(quoxOnPath)].filter(Boolean));
+  const dirs = pathDirs(env).map(d => path.resolve(d));
+  const local = path.join(home, '.local', 'bin');
+  const cands = [];
+  if (onPathReal) cands.push(path.dirname(onPathReal));
+  cands.push(local);
+  const dir = cands.find(writable) || (fs.existsSync(local) ? null : local);
+  return { dir, onPath: dir ? dirs.includes(path.resolve(dir)) : false, target, realEntry, reals };
+}
+
+const ours = (p, reals) => { try { return fs.lstatSync(p).isSymbolicLink() && reals.has(real(p)); } catch { return false; } };
+
+/** -> { ok, status: 'created'|'exists'|'refused'|'error', message, link?, onPath? } */
+export function addShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name (letters, digits, _ . -, starting with a letter).` };
+  const plan = planShortcut({ env, home, entry });
+  const found = whichOnPath(name, env);
+  if (found && plan.reals.has(real(found))) return { ok: true, status: 'exists', link: found, message: `${name} already runs quox (${found}). Nothing changed.` };
+  if (found) return { ok: false, status: 'refused', message: `Not created: "${name}" already runs ${found}. Quox never shadows an existing command. Pick another name with: quox shortcut add --name <name>` };
+  if (!plan.dir) return { ok: false, status: 'error', message: 'No writable directory for the link (tried the one quox lives in and ~/.local/bin). Nothing changed.' };
+  const link = path.join(plan.dir, name);
+  if (ours(link, plan.reals)) return { ok: true, status: 'exists', link, onPath: plan.onPath, message: `${name} already points at quox (${link}).${plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run yet.`}` };
+  let present = false;
+  try { fs.lstatSync(link); present = true; } catch { /* free */ }
+  if (present) return { ok: false, status: 'refused', message: `Not created: ${link} already exists and is not a link to quox. Left alone.` };
+  try {
+    fs.mkdirSync(plan.dir, { recursive: true });
+    fs.symlinkSync(plan.target, link);
+  } catch (e) { return { ok: false, status: 'error', message: `Could not create ${link}: ${e.message}` }; }
+  const warn = plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run until you add it.`;
+  return { ok: true, status: 'created', link, onPath: plan.onPath, message: `Created ${link} -> ${plan.target}.${warn}` };
+}
+
+/** Removes the link only if it points at this quox. */
+export function removeShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name.` };
+  const plan = planShortcut({ env, home, entry });
+  const dirs = [...new Set([...(plan.dir ? [plan.dir] : []), ...pathDirs(env), path.join(home, '.local', 'bin')])];
+  for (const d of dirs) {
+    const link = path.join(d, name);
+    if (ours(link, plan.reals)) {
+      try { fs.unlinkSync(link); } catch (e) { return { ok: false, status: 'error', message: `Could not remove ${link}: ${e.message}` }; }
+      return { ok: true, status: 'removed', link, message: `Removed ${link}.` };
+    }
+  }
+  const other = whichOnPath(name, env);
+  return { ok: true, status: 'none', message: other ? `Nothing removed: ${name} (${other}) is not a link to quox, so it is left alone.` : `Nothing to remove: no ${name} link to quox found.` };
+}

package/lib/core/stepUpPrompt.js

@@ -0,0 +1,99 @@
+/**
+ * DS-010 / quox#1335: the CLI half of the human step-up PIN.
+ *
+ * The SERVER decides what needs a person and answers 403 step_up_required. This helper only reacts:
+ * on a terminal it asks for the PIN with hidden input, trades it for a short-lived step-up token
+ * (POST /api/auth/me/step-up, the same endpoint the Quox terminal uses) and retries the call ONCE with
+ * the token. Rules, all deliberate:
+ *   - the PIN is read from a hidden prompt only. NEVER from argv, an env var or a file: an agent that can
+ *     set an env var or a flag could supply it, and then the PIN proves nothing about a person
+ *   - the PIN is never logged, echoed or put in an error message; the token is never stored
+ *   - no terminal: refuse with a plain message saying a person must run it interactively
+ */
+import { QuoxUserError } from './errors.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const PIN_RE = /^\d{6}$/;
+export const MAX_PIN_TRIES = 3;
+export const STEP_UP_HEADER = 'x-step-up-token';
+const NO_PIN_NEXT = 'set one in the dashboard: Settings > Account > Approval PIN, then run this again in a terminal.';
+
+export function isStepUpRequired(err) {
+  return Boolean(err && err.status === 403 && err.body && err.body.error === 'step_up_required');
+}
+
+/** Real IO: hidden prompt via inquirer; a terminal means a TTY on both stdin and stdout. */
+export function defaultPinIO() {
+  return {
+    isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    promptPin: async (message) => {
+      const { default: inquirer } = await import('inquirer');
+      const a = await inquirer.prompt([{ type: 'password', name: 'pin', message, mask: '*' }]);
+      return a.pin;
+    },
+  };
+}
+
+function nonTtyError(what) {
+  return new QuoxUserError(`${what} needs your step-up PIN, and there is no terminal to ask for it on.`, {
+    next: 'run this command yourself in an interactive terminal; it will ask for the PIN with hidden input. The PIN cannot be passed as a flag or an environment variable.',
+    exitCode: 4, code: 'step_up_required',
+  });
+}
+
+/**
+ * Run `run(extraHeaders)`; if the server says step-up is required, get a token from the person and run it once more.
+ * @param {(headers:object)=>Promise<any>} run   performs the guarded request, merging `headers` into it
+ * @param {{client:any, orgId?:string|null, scope?:string, io?:object, what?:string}} opts
+ */
+export async function withStepUp(run, { client, orgId = null, scope = 'approve', io = defaultPinIO(), what = 'This approval' } = {}) {
+  try {
+    return await run({});
+  } catch (err) {
+    if (!isStepUpRequired(err)) throw err;
+    if (err.body?.reason === 'non_human') {
+      throw new QuoxUserError(`${what} needs a person. This login is an agent or service identity, which can never approve it.`, {
+        next: 'a person must approve it from their own login (the dashboard, or `quox` in their terminal).', exitCode: 4, code: 'step_up_human_only',
+      });
+    }
+    if (err.body?.pin_set === false) {
+      throw new QuoxUserError(`${what} needs your step-up PIN, and you have not set one yet.`, { next: NO_PIN_NEXT, exitCode: 4, code: 'no_pin_set' });
+    }
+    if (!io.isTTY()) throw nonTtyError(what);
+    const token = await collectToken({ client, orgId, scope, io, what });
+    return run({ [STEP_UP_HEADER]: token });
+  }
+}
+
+async function collectToken({ client, orgId, scope, io, what }) {
+  const ep = resolveEndpoint('stepup.verify');
+  for (let attempt = 1; attempt <= MAX_PIN_TRIES; attempt += 1) {
+    let pin = await io.promptPin(`${what} needs your step-up PIN (6 digits, hidden):`);
+    if (!PIN_RE.test(String(pin ?? ''))) {
+      pin = null;
+      if (attempt < MAX_PIN_TRIES) continue;
+      throw new QuoxUserError('A step-up PIN is exactly 6 digits. Nothing was approved.', { exitCode: 4, code: 'bad_pin_format' });
+    }
+    try {
+      const body = { pin, scopes: [scope] };
+      if (orgId) body.org_id = orgId;
+      const r = await client.post(ep.path, { service: ep.service, body });
+      pin = null;
+      if (r && r.step_up_token) return r.step_up_token;
+      throw new QuoxUserError('The server did not issue a step-up token. Nothing was approved.', { exitCode: 4, code: 'step_up_failed' });
+    } catch (e) {
+      pin = null;
+      if (e instanceof QuoxUserError) throw e;
+      const code = e?.body?.error || e?.code;
+      if (e?.status === 409 || code === 'no_pin_set') throw new QuoxUserError('You have not set a step-up PIN yet.', { next: NO_PIN_NEXT, exitCode: 4, code: 'no_pin_set' });
+      if (e?.status === 423 || code === 'pin_locked') throw new QuoxUserError('PIN entry is locked after too many wrong tries.', { next: 'wait for the lock to pass, or approve from the dashboard.', exitCode: 4, code: 'pin_locked' });
+      if (e?.status === 403 && code === 'step_up_human_only') throw new QuoxUserError(`${what} needs a person; this login is an agent identity.`, { next: 'approve from a human login.', exitCode: 4, code: 'step_up_human_only' });
+      if (e?.status === 401 || code === 'wrong_pin') {
+        if (attempt >= MAX_PIN_TRIES) throw new QuoxUserError('Wrong PIN. Nothing was approved.', { exitCode: 4, code: 'wrong_pin' });
+        continue;
+      }
+      throw e;
+    }
+  }
+  throw new QuoxUserError('Wrong PIN. Nothing was approved.', { exitCode: 4, code: 'wrong_pin' });
+}

package/lib/core/version.js

@@ -18,7 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
-export const BASE_VERSION = '0.3.1';
+export const BASE_VERSION = '0.5.0';
 
 // The CLI source root (…/cli). version.js lives at cli/lib/core/, so two
 // levels up is the tree whose HEAD identifies the running build.

package/lib/core/vm.js

@@ -134,6 +134,11 @@ export async function listVms(exec, { node, type } = {}) {
  * 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');

package/lib/core/walkthrough.js

@@ -3,13 +3,16 @@
  * 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';
+import { isDestructive } from '../quoxon/destructive.js';
+import { isDecision, needsPin, approvalAsWalkItem, 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: [] }; }
+  // Questions AND policy-held approval cards (kind approval, shaped as yes/no cards); other inbox kinds are not cards.
+  const decs = (items || []).filter((it) => isDecision(it) || it?.kind === 'approval').map(approvalAsWalkItem);
+  if (!decs.length) { io.write('No question or approval 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.`);
+  const nApp = decs.filter((d) => d.__approval).length;
+  io.write(`${decs.length - nApp ? `${decs.length - nApp} question${decs.length - nApp === 1 ? '' : 's'}` : ''}${decs.length - nApp && nApp ? ' and ' : ''}${nApp ? `${nApp} approval${nApp === 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));
@@ -21,7 +24,8 @@ export async function runWalkthrough(items, io) {
       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; }
+      if (needsPin(it) && rep.key !== 'n') { io.write('  High risk: a yes needs your PIN, which this walkthrough cannot take. Run `quox approvals approve <id>` (it asks for the PIN) or answer in `quox` with /approvals walkthrough, or skip it here.'); continue; }
+      if (it.__approval && rep.key === 'y' && isDestructive(it)) { io.write('  This deletes something: its name must be typed, which this walkthrough does not take. Run `quox approvals approve <id>` in a terminal, or skip it.'); 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;

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 };