quoxcli 0.4.0 → 0.6.0

package/lib/core/offload.js

@@ -501,6 +501,89 @@ export async function workerStatus(deps) {
   };
 }
 
+// 2026-11-07: three worker leases expired overnight with no warning and the nightly suite died on the human-lease
+// error. Every offload command now warns inside this window, and status/leases list every configured worker.
+export const LEASE_WARN_H = 12;
+const STATE_FILE_RE = /^offload(?:-([a-z0-9][a-z0-9-]{0,31}))?\.json$/;
+
+/** Configured workers from the state files: '' is the shared default, then named ones sorted. */
+export function listWorkerNames(deps) {
+  let files = [];
+  try { files = deps.fs.readdirSync(configDir(deps.home)); } catch { return []; }
+  const names = [];
+  for (const f of files) {
+    const m = STATE_FILE_RE.exec(f);
+    if (m) names.push(m[1] || '');
+  }
+  return names.sort((a, b) => (a === '' ? -1 : b === '' ? 1 : a.localeCompare(b)));
+}
+
+/** Lease state for an expiry timestamp: EXPIRED, EXPIRING (within LEASE_WARN_H), OK, or UNKNOWN. */
+export function leaseInfo(expiresAt, now) {
+  const t = expiresAt ? Date.parse(expiresAt) : NaN;
+  if (!Number.isFinite(t)) return { lease: 'UNKNOWN', hours_left: null };
+  const hours = Math.round(((t - now) / 3600000) * 10) / 10;
+  if (t <= now) return { lease: 'EXPIRED', hours_left: hours };
+  return { lease: hours <= LEASE_WARN_H ? 'EXPIRING' : 'OK', hours_left: hours };
+}
+
+/** What a HUMAN runs to renew: there is no lease-extend verb, so lease a fresh worker (the old one is released after). */
+export function renewCommand(name) {
+  return `quox -p <human-profile> offload --fresh${name ? ` --worker ${name}` : ''} -- true`;
+}
+
+const fmtLeft = (h) => (Math.abs(h) < 1 ? `${Math.round(Math.abs(h) * 60)}m` : `${Math.round(Math.abs(h))}h`);
+export function describeLease(l) {
+  if (l.lease === 'EXPIRED') return l.hours_left == null ? 'EXPIRED (the pool no longer holds it)' : `EXPIRED ${fmtLeft(l.hours_left)} ago`;
+  if (l.lease === 'EXPIRING' || l.lease === 'OK') return `${l.lease}, expires in ${fmtLeft(l.hours_left)}`;
+  return l.lease;
+}
+
+function leaseEntry(name, st, live, now) {
+  const base = { worker: name || 'default', vmid: null, ip: null, lessee: null, pool_state: null, lease_expires_at: null, lease: 'NONE', hours_left: null, renew: null };
+  if (!st.worker) return base;
+  const expires = live?.lease_expires_at || st.worker.expires || null;
+  let info = leaseInfo(expires, now);
+  const pool = live === undefined ? 'unknown' : live ? live.state : 'missing';
+  // The pool is the truth when it answered: a VM it no longer holds (or holds for someone else) is gone.
+  if (live === null || (live && (live.state !== 'leased' || (st.worker.lessee && live.lessee && live.lessee !== st.worker.lessee)))) {
+    info = { lease: 'EXPIRED', hours_left: info.lease === 'EXPIRED' ? info.hours_left : null };
+  }
+  return {
+    ...base, vmid: st.worker.vmid, ip: live?.ip || st.worker.ip || null, lessee: st.worker.lessee || null,
+    pool_state: pool, lease_expires_at: expires, ...info,
+    renew: info.lease === 'EXPIRED' || info.lease === 'EXPIRING' ? renewCommand(name) : null,
+  };
+}
+
+/**
+ * Every configured worker's lease. `live: true` asks the pool once (a failure is reported, the cached expiry is
+ * used); `live: false` reads only the local state files (the pre-run warning must not add a pool call).
+ * Read-only: never leases, renews or releases.
+ */
+export async function allLeases(deps, { live = true } = {}) {
+  const now = deps.now();
+  let pool = null; let poolErr = null;
+  if (live) {
+    try { pool = await poolStatus(deps.rest); } catch (e) { poolErr = String(e?.message || e); }
+  }
+  const leases = listWorkerNames(deps).map((name) => {
+    const st = loadState({ ...deps, worker: name || undefined });
+    const v = pool && st.worker ? vmOf(pool, st.worker.vmid) : undefined;
+    return leaseEntry(name, st, v, now);
+  });
+  return {
+    checked_at: new Date(now).toISOString(), warn_within_h: LEASE_WARN_H, source: pool ? 'pool' : 'cache',
+    ...(poolErr ? { pool_error: poolErr } : {}),
+    any_attention: leases.some((l) => l.renew), leases,
+  };
+}
+
+/** One line per expired or expiring lease, naming the command a human runs. */
+export function leaseWarnings(report) {
+  return report.leases.filter((l) => l.renew).map((l) => `warning: worker ${l.worker} (vm ${l.vmid}) lease ${l.lease === 'EXPIRED' ? describeLease(l) : `expires in ${fmtLeft(l.hours_left)} (${l.lease_expires_at})`}; leasing needs a human, who renews it with: ${l.renew}`);
+}
+
 /** Real side effects. */
 export function realDeps({ rest, env = process.env, log = (m) => process.stderr.write(`offload: ${m}\n`) }) {
   return {
@@ -531,3 +614,40 @@ export function gitToplevel(cwd) {
   const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
   return r.status === 0 ? r.stdout.trim() : cwd;
 }
+
+// #1485: the git repo root for cwd, or null when cwd is not inside a repo.
+// Unlike gitToplevel (which falls back to cwd), this reports the no-repo case
+// so resolveSyncDir can refuse rather than sync an unbounded tree.
+export function gitRepoRoot(cwd, { run = (c, a, o) => spawnSync(c, a, o) } = {}) {
+  const r = run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+// #1485: resolve the ONE directory offload rsyncs to the shared worker, and
+// refuse an unbounded one. `quox offload` from a non-repo dir used to fall
+// back to cwd, so running it from the home directory rsynced all ~29G of $HOME
+// (including a live token file) onto the worker and filled its disk. The sync
+// must be a bounded git repo root, never $HOME and never an ancestor of it.
+export function resolveSyncDir(cwd, optionDir, { home = os.homedir(), repoRoot = gitRepoRoot } = {}) {
+  const h = path.resolve(home);
+  const guardHome = (dir, what) => {
+    if (dir === h) {
+      throw new OffloadError(`offload refuses to sync your home directory (${dir}). cd into a project repo, or pass --dir <repo-root>.`);
+    }
+    if (h === dir || h.startsWith(dir + path.sep) || dir === path.parse(dir).root) {
+      throw new OffloadError(`offload refuses to sync ${what} (${dir}): it contains your home directory, so the whole tree would be copied to the shared worker. Pass --dir <repo-root>.`);
+    }
+  };
+  if (optionDir) {
+    const d = path.resolve(optionDir);
+    guardHome(d, 'the --dir path');
+    return d;
+  }
+  const root = repoRoot(cwd);
+  if (!root) {
+    throw new OffloadError(`offload must run from inside a git repository (cwd ${cwd} is not one). cd into a repo, or pass --dir <repo-root>. Refusing so your whole home directory is not synced to the shared worker.`);
+  }
+  const d = path.resolve(root);
+  guardHome(d, 'the resolved repo root');
+  return d;
+}

package/lib/core/org-override.js

@@ -20,6 +20,10 @@ import { QuoxValidationError } from './errors.js';
 // Commands where --org legitimately means something other than "act in".
 export const EXEMPT = new Set(['login', 'logout', 'signup', 'org switch', 'invites list', 'invites accept']);
 
+// Verbs that mint a same-user token for the named org themselves (core/crossOrgApprovals.clientForTarget), so --org
+// naming another org is honoured on that org, not refused. Membership is enforced server-side by the mint.
+export const CROSS_ORG = new Set(['approvals list', 'approvals approve', 'approvals deny', 'approvals walkthrough']);
+
 export function commandPath(cmd) {
   const parts = [];
   for (let c = cmd; c && c.parent; c = c.parent) parts.unshift(c.name());
@@ -35,7 +39,7 @@ export function commandPath(cmd) {
  * @throws {QuoxValidationError} when the override differs from the session org
  */
 export function assertOrgOverrideSafe({ override, authData, hasUserToken, command = '' }) {
-  if (!override || !hasUserToken || EXEMPT.has(command)) return;
+  if (!override || !hasUserToken || EXEMPT.has(command) || CROSS_ORG.has(command)) return;
   const want = String(override).toLowerCase();
   const sid = authData?.org_id || null;
   const known = [sid, authData?.org_slug, authData?.org_name]

package/lib/core/output.js

@@ -12,7 +12,8 @@ import Table from 'cli-table3';
  * Format and print tabular data
  *
  * @param {Object} result - { columns, headers, rows } or array of objects
- * @param {Object} options - { format, title, emptyMessage, full } (full: no 60-char cell truncation in table mode)
+ * @param {Object} options - { format, title, emptyMessage, full, fit } (full: no 60-char cell truncation in table mode;
+ *   fit: { width, flex } opt-in, shortens the `flex` column with an ellipsis so each table line fits `width`)
  */
 export function formatOutput(result, options = {}) {
   const format = options.format || getOutputFormat();
@@ -45,7 +46,7 @@ export function formatOutput(result, options = {}) {
       formatCsv(rows, columns, headers);
       break;
     case 'quiet':
-      formatQuiet(rows, columns);
+      formatQuiet(rows, options.quietColumn ? [options.quietColumn] : columns);
       break;
     default:
       formatTable(rows, columns, headers, options);
@@ -167,9 +168,9 @@ function formatTable(rows, columns, headers, options) {
     },
   });
 
-  for (const row of rows) {
-    table.push(columns.map(col => formatValue(row[col], options.full === true)));
-  }
+  const cells = rows.map(row => columns.map(col => formatValue(row[col], options.full === true)));
+  if (options.fit) fitCells(cells, columns, headers, options.fit);
+  for (const r of cells) table.push(r);
 
   console.log(table.toString());
 
@@ -179,6 +180,30 @@ function formatTable(rows, columns, headers, options) {
   }
 }
 
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+const visibleLength = (s) => [...String(s).replace(ANSI, '')].length;
+
+/**
+ * Opt-in width fitting (fit: { width, flex }). cli-table3 here pads each cell by 1 on both sides and joins
+ * cells with a 2-space middle, so a line is sum(w + 2) + 2 * (n - 1). When that passes `width`, the `flex`
+ * column is cut to the remaining room with an ellipsis instead of letting the terminal wrap the row
+ * (owner 2026-11-07: wrapped `quox actions list` rows in the 73-column TUI).
+ */
+function fitCells(cells, columns, headers, { width, flex } = {}) {
+  const w = Number(width);
+  const fi = columns.indexOf(flex);
+  if (!(w > 0) || fi < 0) return;
+  const widths = columns.map((_, i) => Math.max(visibleLength(headers[i] ?? ''), ...cells.map(r => visibleLength(r[i]))));
+  const total = widths.reduce((a, b) => a + b + 2, 0) + 2 * (columns.length - 1);
+  if (total <= w) return;
+  const room = Math.max(visibleLength(headers[fi] ?? ''), 8, widths[fi] - (total - w));
+  for (const r of cells) {
+    const plain = String(r[fi]).replace(ANSI, '');
+    if ([...plain].length > room) r[fi] = [...plain].slice(0, room - 1).join('').trimEnd() + '…';
+  }
+}
+
 function formatCsv(rows, columns, headers) {
   console.log(headers.map(csvEscape).join(','));
   for (const row of rows) {

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/selfUpdate.js

@@ -20,6 +20,7 @@ import os from 'node:os';
 import { RUNNING_ROOT, findOnPath } from '../quoxon/slash/restart.js';
 import { cmpSemver } from '../server/install.js';
 import { askText } from '../quoxon/ask.js';
+import { isWebPty, SHELL_REFUSED } from '../quoxon/webPty.js';
 
 export const NPM_PACKAGE = 'quoxcli';
 export const NOTES_MAX = 5;
@@ -146,6 +147,7 @@ export async function checkUpdate(info, { deps = {} } = {}) {
 
 /** Run the update with the terminal handed over (prompts, sudo). -> { ok, code } or { ok:false, error } */
 export function runUpdate(plan, { spawn = spawnSync, env = process.env } = {}) {
+  if (isWebPty(env)) return { ok: false, error: SHELL_REFUSED }; // QUOXON web PTY: no npm/sudo on the server
   const r = spawn(plan.command.cmd, plan.command.args, { stdio: 'inherit', env });
   if (r.error) return { ok: false, error: `${r.error.code || 'failed'}: ${r.error.message}` };
   const code = r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1);

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.4.0';
+export const BASE_VERSION = '0.6.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/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;