quoxcli 0.4.0 → 0.5.0

package/lib/commands/notesSeal.js

@@ -0,0 +1,259 @@
+/**
+ * quox notes seal init|status|new|open|edit|print: ENQRYPT sealed notes (ENQRYPT stream E4, enqrypt ADR-0001/0002/0003).
+ *
+ * Sealing and opening happen HERE, on the client, with the owner's ENQRYPT identity (passphrase-protected key
+ * file, default ~/.quox/enqrypt). NotesQ only ever receives the sealed envelope: the server, the collector and
+ * agents cannot read a sealed note. Titles, collections and tags are NOT sealed (they stay searchable).
+ * ENQRYPT is an adapter dependency, loaded on demand; core Quox does not need it.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+import { randomUUID } from 'crypto';
+import { pathToFileURL } from 'url';
+import { QuoxError } from '../core/errors.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const SEAL_PURPOSE = 'notesq.note';
+export const SEAL_MARK = 'enqrypt-sealed-note';
+const FENCE = 'enqrypt-envelope';
+const FP_RE = /^[0-9a-f]{64}$/;
+const B64U_RE = /^[A-Za-z0-9_-]+$/;
+
+export const keystoreDir = (opt) => resolve(opt || join(homedir(), '.quox', 'enqrypt'));
+
+/** Markdown NotesQ stores for a sealed note: a heading, a plain explanation, and the envelope. Nothing secret. */
+export function sealedNoteMarkdown({ title, envelope, fingerprint }) {
+  const b64 = Buffer.from(envelope).toString('base64url');
+  const wrapped = b64.match(/.{1,76}/g).join('\n');
+  return `# ${title}\n\n🔐 Sealed with ENQRYPT (HPKE, RFC 9180). The server stores only this envelope and cannot read it.\n`
+    + `Open it on a device holding the key with fingerprint \`${fingerprint.slice(0, 16)}…\`: \`quox notes seal open <id>\`\n\n`
+    + '```' + FENCE + '\n' + wrapped + '\n```\n';
+}
+
+export function extractEnvelope(markdown) {
+  const blocks = [...String(markdown || '').matchAll(new RegExp('```' + FENCE + '\\n([\\s\\S]*?)\\n```', 'g'))];
+  if (blocks.length !== 1) throw new QuoxError(blocks.length ? 'This note has more than one ENQRYPT envelope; refusing to guess.' : 'This note holds no ENQRYPT envelope.', 1);
+  const b64 = blocks[0][1].replace(/\n/g, '');
+  if (!B64U_RE.test(b64)) throw new QuoxError('The ENQRYPT envelope in this note is damaged.', 1);
+  return new Uint8Array(Buffer.from(b64, 'base64url'));
+}
+
+export function sealProperties({ fingerprint, objectId, version, collection, tags }) {
+  const p = { enqrypt: SEAL_MARK, enqrypt_fp: fingerprint, enqrypt_object: objectId, enqrypt_version: version };
+  if (collection) p.collection = collection;
+  if (tags) p.tags = tags;
+  return p;
+}
+
+export function readSealProperties(props) {
+  const p = props || {};
+  const version = Number(p.enqrypt_version);
+  if (p.enqrypt !== SEAL_MARK) throw new QuoxError('This note is not an ENQRYPT sealed note.', 1);
+  if (!FP_RE.test(String(p.enqrypt_fp)) || !/^[0-9a-f-]{36}$/.test(String(p.enqrypt_object)) || !Number.isSafeInteger(version) || version < 1) {
+    throw new QuoxError('This sealed note has damaged ENQRYPT properties.', 1);
+  }
+  return { fingerprint: p.enqrypt_fp, objectId: p.enqrypt_object, version };
+}
+
+// Rollback floor: the highest version this client has opened per sealed object. Older envelopes are refused.
+const floorFile = (dir) => join(dir, 'notes-floor.json');
+export function readFloor(dir, objectId) {
+  try { return Number(JSON.parse(readFileSync(floorFile(dir), 'utf8'))[objectId]) || 0; } catch { return 0; }
+}
+export function bumpFloor(dir, objectId, version) {
+  let all = {};
+  try { all = JSON.parse(readFileSync(floorFile(dir), 'utf8')); } catch { /* first use */ }
+  if (!(Number(all[objectId]) >= version)) all[objectId] = version;
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(floorFile(dir), JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
+}
+
+/** A passphrase file must be private to its owner; anything looser is refused rather than trusted. */
+export function readPassphraseFile(path) {
+  const st = statSync(path);
+  if ((st.mode & 0o077) !== 0) throw new QuoxError(`Refusing ${path}: passphrase files must be chmod 600.`, 2);
+  return readFileSync(path, 'utf8').replace(/\r?\n$/, '');
+}
+
+async function defaultLoadEnqrypt() {
+  const base = process.env.QUOX_ENQRYPT_PATH;
+  const at = (sub) => (base ? pathToFileURL(join(base, 'src', `${sub}.mjs`)).href : `@quoxai/enqrypt-script/${sub}`);
+  try {
+    const [seal, keystore, armor] = await Promise.all([import(at('seal')), import(at('keystore')), import(at('armor'))]);
+    return { ...seal, ...keystore, ...armor };
+  } catch {
+    throw new QuoxError('ENQRYPT is not available on this machine. It is not published yet: set QUOX_ENQRYPT_PATH to a checkout of quoxai/enqrypt (never `npm install enqrypt`, that name is an unrelated malicious package).', 1);
+  }
+}
+
+async function askPassphrase(message, confirm = false) {
+  if (!process.stdin.isTTY) throw new QuoxError('No terminal to ask for the passphrase: pass --passphrase-file <chmod-600 file>.', 2);
+  const { default: inquirer } = await import('inquirer');
+  const { p } = await inquirer.prompt([{ type: 'password', name: 'p', message, mask: '*' }]);
+  if (confirm) {
+    const { q } = await inquirer.prompt([{ type: 'password', name: 'q', message: 'Repeat the passphrase', mask: '*' }]);
+    if (p !== q) throw new QuoxError('The passphrases did not match. Nothing was created.', 2);
+  }
+  return p;
+}
+
+export function registerNotesSeal(notes, ctx) {
+  const { program, client, auth, call, getNote, putNote, readContent, isJson, printJson, announce } = ctx;
+  const loadEnqrypt = ctx.loadEnqrypt || defaultLoadEnqrypt;
+  const passphrase = (options, msg, confirm) => (options.passphraseFile ? readPassphraseFile(options.passphraseFile) : askPassphrase(msg, confirm));
+  const mapErr = (e) => {
+    if (e && (e.name === 'EnqryptError' || e.name === 'KeystoreError')) return new QuoxError(`ENQRYPT refused: ${e.code} (${e.message}). Nothing was shown.`, 1);
+    return e;
+  };
+  const unlock = async (E, options) => {
+    try { return await E.unlockKeystore({ dir: keystoreDir(options.keystore), passphrase: await passphrase(options, 'ENQRYPT passphrase') }); }
+    catch (e) { throw mapErr(e); }
+  };
+
+  const seal = notes.command('seal').description('ENQRYPT sealed notes: encrypted on this device, the server stores only the envelope (prototype, security review pending)');
+  const common = (cmd) => cmd
+    .option('--keystore <dir>', 'ENQRYPT keystore directory (default ~/.quox/enqrypt)')
+    .option('--passphrase-file <path>', 'read the passphrase from a chmod-600 file instead of asking');
+
+  common(seal.command('init').description('Create your ENQRYPT key (passphrase-protected) and show the one-time recovery key'))
+    .action(async (options) => {
+      const E = await loadEnqrypt();
+      const dir = keystoreDir(options.keystore);
+      if (existsSync(join(dir, 'identity.age'))) throw new QuoxError(`An ENQRYPT key already exists in ${dir}. Nothing was changed.`, 1);
+      console.log('If you lose BOTH this passphrase and the recovery key shown next, your sealed notes cannot be recovered by anyone.');
+      let out;
+      try { out = await E.createKeystore({ dir, passphrase: await passphrase(options, 'New ENQRYPT passphrase (10+ characters)', true) }); }
+      catch (e) { throw mapErr(e); }
+      if (isJson(program)) return printJson({ dir, fingerprint: out.fingerprint, recovery_key: out.recoveryKey });
+      console.log(`\nKey created in ${dir}\nFingerprint: ${out.fingerprint}\n`);
+      console.log('RECOVERY KEY (shown once; store it offline, it opens every sealed note):');
+      console.log(`  ${out.recoveryKey}\n`);
+      announce('seal init', `key ${out.fingerprint.slice(0, 16)}…`);
+    });
+
+  common(seal.command('status').description('Show whether this device has an ENQRYPT key, and its fingerprint'))
+    .action(async (options) => {
+      const dir = keystoreDir(options.keystore);
+      let E;
+      try { E = await loadEnqrypt(); } catch (e) {
+        // status must report, not fail, when the seal backend is absent (the other verbs still refuse).
+        const reason = e && e.message ? e.message : 'ENQRYPT could not be loaded.';
+        if (isJson(program)) return printJson({ dir, backend: 'unavailable', fingerprint: null, reason });
+        return console.log(`ENQRYPT backend: not available on this machine, so no key can be read from ${dir}.\n${reason}`);
+      }
+      try {
+        const pub = await E.readPublicIdentity({ dir });
+        if (isJson(program)) return printJson({ dir, fingerprint: pub.fingerprint });
+        console.log(`ENQRYPT key in ${dir}\nFingerprint: ${pub.fingerprint}`);
+      } catch (e) {
+        if (e && e.code === 'MISSING') return console.log(`No ENQRYPT key in ${dir}. Create one: quox notes seal init`);
+        throw mapErr(e);
+      }
+    });
+
+  common(seal.command('new').description('Create a sealed note from --file or --stdin. The title is NOT sealed.'))
+    .option('--scope <scope>', 'user | org (default user)', 'user')
+    .option('--title <t>', 'visible title (not sealed)', 'Sealed note')
+    .option('--collection <c>', 'collection (not sealed)')
+    .option('--tag <t>', 'tag (repeatable, not sealed)', (v, prev) => (prev || []).concat(v))
+    .option('--file <path>', 'read the secret text from a file')
+    .option('--stdin', 'read the secret text from stdin')
+    .action(async (options) => {
+      auth.requireAuth();
+      if (!['user', 'org'].includes(options.scope)) throw new QuoxError('--scope must be user or org.', 2);
+      const text = await readContent(options);
+      if (text === null) throw new QuoxError('seal new needs --file <path> or --stdin (the secret is never taken from a flag).', 2);
+      const E = await loadEnqrypt();
+      const me = await unlock(E, options);
+      const fingerprint = await E.fingerprint(me.publicKey);
+      const objectId = randomUUID();
+      let envelope;
+      try { envelope = await E.seal({ sender: me, recipientPublicKey: me.publicKey, recipientFingerprint: fingerprint, op: E.OP.SEALED_OBJECT, purpose: SEAL_PURPOSE, objectId, seq: 1, plaintext: new TextEncoder().encode(text) }); }
+      catch (e) { throw mapErr(e); }
+      const ep = resolveEndpoint('notesq.notes.create');
+      const body = { scope: options.scope, markdown: sealedNoteMarkdown({ title: options.title, envelope, fingerprint }), properties: sealProperties({ fingerprint, objectId, version: 1, collection: options.collection, tags: options.tag }) };
+      const data = await call(() => client.post(ep.path, { service: ep.service, body }));
+      bumpFloor(keystoreDir(options.keystore), objectId, 1);
+      if (isJson(program)) return printJson({ id: data.note?.id, object: objectId, version: 1, fingerprint });
+      console.log(`Sealed note ${data.note?.id} created (${text.length} characters sealed; the title "${options.title}" is visible).`);
+      announce('seal new', `sealed note ${data.note?.id}`);
+    });
+
+  common(seal.command('print').description('Print a sealed note as a plain ASCII armour block (ciphertext only, safe to print or file; no passphrase needed)'))
+    .argument('<id>', 'note id')
+    .action(async (id) => {
+      auth.requireAuth();
+      const n = await getNote(id);
+      const props = readSealProperties(n.properties);
+      const envelope = extractEnvelope(n.markdown ?? n.body);
+      const E = await loadEnqrypt();
+      const armor = await E.toAsciiArmor(envelope, { Version: '1', Key: props.fingerprint.slice(0, 16), Object: props.objectId, Note: String(id).slice(0, 64) });
+      if (isJson(program)) return printJson({ id, armor });
+      process.stdout.write(armor);
+    });
+
+  common(seal.command('open').description('Open a sealed note on this device and print it (by note id, or offline from a printed armour block)'))
+    .argument('[id]', 'note id (omit with --armor-file)')
+    .option('--armor-file <path>', 'open a printed/saved ASCII armour block instead of fetching the note ("-" = stdin)')
+    .action(async (id, options) => {
+      let envelope, objectId, expectFp = null, label = id;
+      const E = await loadEnqrypt();
+      if (options.armorFile) {
+        if (id) throw new QuoxError('Give a note id or --armor-file, not both.', 2);
+        const text = options.armorFile === '-' ? await readContent({ stdin: true }) : readFileSync(options.armorFile, 'utf8');
+        let parsed;
+        try { parsed = await E.fromAsciiArmor(text); } catch (e) { throw new QuoxError(`That armour block was refused: ${e.message}. Nothing was opened.`, 1); }
+        envelope = parsed.envelope;
+        objectId = parsed.headers.Object;
+        if (!/^[0-9a-f-]{36}$/.test(String(objectId))) throw new QuoxError('That armour block has no valid Object header; it cannot be bound to a note.', 1);
+        label = parsed.headers.Note || 'armour';
+      } else {
+        if (!id) throw new QuoxError('seal open needs a note id or --armor-file <path>.', 2);
+        auth.requireAuth();
+        const n = await getNote(id);
+        const props = readSealProperties(n.properties);
+        envelope = extractEnvelope(n.markdown ?? n.body);
+        objectId = props.objectId;
+        expectFp = props.fingerprint;
+      }
+      const me = await unlock(E, options);
+      const fingerprint = await E.fingerprint(me.publicKey);
+      if (expectFp && fingerprint !== expectFp) throw new QuoxError(`This note was sealed to key ${expectFp.slice(0, 16)}…, not this device's key ${fingerprint.slice(0, 16)}….`, 1);
+      const dir = keystoreDir(options.keystore);
+      let plain;
+      try { plain = await E.open({ recipient: me, senderPublicKey: me.publicKey, senderFingerprint: fingerprint, envelope, op: E.OP.SEALED_OBJECT, purpose: SEAL_PURPOSE, objectId, minVersion: readFloor(dir, objectId) }); }
+      catch (e) { throw mapErr(e); }
+      const v = E.parseEnvelope(envelope).seq;
+      bumpFloor(dir, objectId, v);
+      const text = new TextDecoder().decode(plain);
+      if (isJson(program)) return printJson({ id: label, version: v, text });
+      process.stdout.write(text.endsWith('\n') ? text : text + '\n');
+    });
+
+  common(seal.command('edit').description('Replace a sealed note\'s secret text (--file or --stdin); writes a new sealed version'))
+    .argument('<id>', 'note id')
+    .option('--file <path>', 'read the new secret text from a file')
+    .option('--stdin', 'read the new secret text from stdin')
+    .action(async (id, options) => {
+      auth.requireAuth();
+      const text = await readContent(options);
+      if (text === null) throw new QuoxError('seal edit needs --file <path> or --stdin.', 2);
+      const cur = await getNote(id);
+      const props = readSealProperties(cur.properties);
+      const E = await loadEnqrypt();
+      const me = await unlock(E, options);
+      const fingerprint = await E.fingerprint(me.publicKey);
+      if (fingerprint !== props.fingerprint) throw new QuoxError('This note was sealed to a different key; refusing to re-seal it.', 1);
+      const version = props.version + 1;
+      let envelope;
+      try { envelope = await E.seal({ sender: me, recipientPublicKey: me.publicKey, recipientFingerprint: fingerprint, op: E.OP.SEALED_OBJECT, purpose: SEAL_PURPOSE, objectId: props.objectId, seq: version, plaintext: new TextEncoder().encode(text) }); }
+      catch (e) { throw mapErr(e); }
+      const title = String(cur.title || 'Sealed note');
+      const data = await putNote(id, { markdown: sealedNoteMarkdown({ title, envelope, fingerprint }), properties: { ...cur.properties, enqrypt_version: version }, base_hash: cur.content_hash });
+      bumpFloor(keystoreDir(options.keystore), props.objectId, version);
+      if (isJson(program)) return printJson({ id, version, revision: data.revision?.rev });
+      console.log(`Sealed note ${id} updated to sealed version ${version}. Earlier revisions hold earlier envelopes, never plaintext.`);
+      announce('seal edit', `sealed note ${id} v${version}`);
+    });
+}

package/lib/commands/objective.js

@@ -12,6 +12,7 @@
  *                        live loop gate: budget, risk, interval).
  */
 
+import { withStepUp } from '../core/stepUpPrompt.js';
 import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/output.js';
 import { parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
@@ -181,7 +182,8 @@ export function registerObjectiveCommands(program, ctx) {
     .argument('<id>', 'objective ID')
     .action(async (id) => {
       auth.requireAuth();
-      const data = await client.post(resolveEndpoint('objectives.approve-plan', { id }).path, { service: resolveEndpoint('objectives.approve-plan', { id }).service });
+      const planEp = resolveEndpoint('objectives.approve-plan', { id });
+      const data = await withStepUp((headers) => client.post(planEp.path, { service: planEp.service, headers }), { client, orgId: auth.getOrgId?.(program.opts().org) || null, io: ctx.stepUpIO, what: 'Approving this plan' });
       printSuccess(`Objective ${id}: ${data.status}${data.message ? ` — ${data.message}` : ''}`);
     });
 
@@ -231,7 +233,8 @@ export function registerObjectiveCommands(program, ctx) {
       const body = {};
       if (options.notes) body.notes = options.notes;
       const params = { id: objectiveId, checkpointId };
-      const data = await client.post(resolveEndpoint('objectives.checkpoint-approve', params).path, { service: resolveEndpoint('objectives.checkpoint-approve', params).service, body });
+      const cpEp = resolveEndpoint('objectives.checkpoint-approve', params);
+      const data = await withStepUp((headers) => client.post(cpEp.path, { service: cpEp.service, headers, body }), { client, orgId: auth.getOrgId?.(program.opts().org) || null, io: ctx.stepUpIO, what: 'Approving this checkpoint' });
       // LOOPQ-HALT: "approved" is not "running". When the server says the loop did not start, say so in words.
       if (data.started === false) {
         printWarning(`Checkpoint ${checkpointId}: ${data.status}, but the objective did NOT start (objective ${data.objective_status || 'pending'}).`);

package/lib/commands/offload.js

@@ -9,10 +9,9 @@
  * (same as `quox vm pool lease`) with a dedicated key at ~/.config/quox/offload_ed25519.
  */
 
-import path from 'node:path';
 import { printInfo } from '../core/output.js';
 import { makePoolRest } from '../core/vm.js';
-import { OffloadError, realDeps, runOffload, releaseWorker, workerStatus, gitToplevel, WORKER_NAME_RE } from '../core/offload.js';
+import { OffloadError, realDeps, runOffload, releaseWorker, workerStatus, resolveSyncDir, WORKER_NAME_RE } from '../core/offload.js';
 
 export function registerOffloadCommands(program, ctx, { deps: injected } = {}) {
   const { client, auth } = ctx;
@@ -45,8 +44,8 @@ export function registerOffloadCommands(program, ctx, { deps: injected } = {}) {
     .action(async (command, options) => {
       auth.requireAuth();
       const cwd = process.cwd();
-      const dir = path.resolve(options.dir || gitToplevel(cwd));
       try {
+        const dir = resolveSyncDir(cwd, options.dir);
         const code = await runOffload(mk(options), {
           dir, cwd, command, fresh: !!options.fresh, docker: !!options.docker,
           cores: options.cores, memoryGb: options.memoryGb, diskGb: options.diskGb,

package/lib/commands/plan.js

@@ -207,6 +207,22 @@ function renderStreamList(payload, { lens = 'tier' } = {}) {
   return lines;
 }
 
+/** Honest count of what was printed, plus a one-line glyph legend (the list itself prints glyphs only). */
+function renderListFooter(payload, lens) {
+  const streams = (payload && payload.streams) || [];
+  if (streams.length === 0) return [];
+  const tiers = lens === 'tier' ? streams : null;
+  const top = tiers ? tiers.flatMap((g) => g.streams || []) : streams;
+  const subs = top.reduce((n, s) => n + (s.substreams || []).length, 0);
+  const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
+  const count = `${plural(top.length, 'stream')}${subs ? ` + ${plural(subs, 'substream')}` : ''}${tiers ? ` in ${plural(tiers.length, 'tier')}` : ''}`;
+  return [
+    '',
+    chalk.dim(`  ${count}`),
+    chalk.dim('  ◇ not started  ⬗ in progress  ◈ decision needed  ◆ blocked (red) or complete (dim)  └ substream'),
+  ];
+}
+
 // ── render: stream detail ───────────────────────────────────────────────
 
 function renderStreamDetail(detail) {
@@ -601,6 +617,7 @@ export function registerPlanCommands(program, ctx) {
       if (isJsonOutput(program)) return printJson(data);
       console.log(`\n  ${roadmapId}  (lens: ${options.lens})`);
       console.log(renderStreamList(data, { lens: options.lens }).join('\n'));
+      console.log(renderListFooter(data, options.lens).join('\n'));
     });
 
   // ── focus ────────────────────────────────────────────────────────────

package/lib/commands/provider.js

@@ -58,17 +58,19 @@ export function registerProviderCommands(program, ctx) {
   // ── provider list ──────────────────────────────────────────────────────────
   provider
     .command('list')
-    .description('Show which AI providers this org can use, and how each is connected')
-    .action(async () => {
+    .description('Show which AI providers this org can use, and how each is connected (--all adds the other integrations in the vault)')
+    .option('--all', 'also list the other integrations in the vault (Slack, GitHub, bastion...), not just AI providers')
+    .action(async (opts = {}) => {
       auth.requireAuth();
       const a = api();
       const [vault, caps] = await Promise.all([a.connections(), a.capabilities ? a.capabilities() : null]);
       if (program.opts().output === 'json') {
-        const rows = vault?.ok ? vault.rows.map((r) => Object.fromEntries(SAFE_ROW.filter((k) => r[k] !== undefined).map((k) => [k, r[k]]))) : null;
+        const known = new Set(Object.values(PROVIDERS).map((p) => p.type));
+        const rows = vault?.ok ? vault.rows.filter((r) => opts.all || known.has(r.integration_type)).map((r) => Object.fromEntries(SAFE_ROW.filter((k) => r[k] !== undefined).map((k) => [k, r[k]]))) : null;
         formatDetail({ connections: rows, ...(vault?.ok ? {} : { error: vault?.error || 'vault not readable' }), capabilities: caps?.ok ? caps.capabilities : null }, { format: 'json' });
         return;
       }
-      say(connectionLines(vault, caps));
+      say(connectionLines(vault, caps, { includeOthers: Boolean(opts.all) }));
     });
 
   // ── provider connect ───────────────────────────────────────────────────────
@@ -202,16 +204,35 @@ export function registerProviderCommands(program, ctx) {
       const rows = vault.rows.filter((r) => types.has(r.integration_type) && (r.is_default === 1 || r.is_default === true));
       if (!rows.length) throw new Error(p ? `No ${p.id} connection is stored for this org. Connect one: quox provider connect ${p.id}` : 'No provider connection is stored for this org. Connect one: quox provider connect <kind>');
       const orgId = resolveOrgId(auth, program);
+      const asJson = program.opts().output === 'json';
+      const results = [];
       let failed = 0;
       for (const row of rows) {
-        const name = (Object.values(PROVIDERS).find((x) => x.type === row.integration_type) || {}).name || row.integration_type;
+        const meta = Object.values(PROVIDERS).find((x) => x.type === row.integration_type) || {};
+        const name = meta.name || row.integration_type;
         const ep = resolveEndpoint('vault.test', { orgId, id: row.id });
-        let res;
+        let res; let reason = null;
         try { res = await client.post(ep.path, { service: ep.service, retries: 0 }); }
-        catch (e) { res = { success: false, message: e?.message || 'failed' }; }
-        if (res?.success === false) { failed++; printInfo(`✖ ${name}  ${row.label || row.id}  failed: ${res?.message || 'no reason given'}`); }
+        catch (e) {
+          res = { success: false, message: e?.message || 'failed' };
+          reason = e?.body?.reason || (String(e?.message || '').match(/\(reason: ([^)]+)\)/) || [])[1] || null;
+        }
+        const ok = res?.success !== false;
+        if (!ok) failed++;
+        results.push({
+          id: row.id, kind: meta.id || row.integration_type, label: row.label || row.id, ok,
+          ...(ok ? (res?.message ? { message: res.message } : {}) : { error: res?.message || 'no reason given', reason }),
+        });
+        if (asJson) continue;
+        if (!ok) printInfo(`✖ ${name}  ${row.label || row.id}  failed: ${res?.message || 'no reason given'}`);
         else printInfo(`✔ ${name}  ${row.label || row.id}  ok${res?.message ? `: ${res.message}` : ''}`);
       }
+      if (asJson) formatDetail({
+        results,
+        summary: { total: results.length, ok: results.length - failed, failed },
+        // a top-level error string is what the collector's quox_cli wrapper quotes to the model on a non-zero exit
+        ...(failed ? { error: results.filter((r) => !r.ok).map((r) => `${r.kind}: ${r.error}`).join('; ') } : {}),
+      }, { format: 'json' });
       if (failed) process.exitCode = 1;
     });
 }

package/lib/commands/qlarity.js

@@ -49,6 +49,25 @@ function annotate(err) {
   throw err;
 }
 
+/**
+ * Inspectors whose server-side run() calls assertSelector (qlarity/src/inspectors.js).
+ * The registry lives in another repo and `inspectors list` does not expose the
+ * flag, so this mirrors it; storage, dom_summary, layout_health and
+ * responsive_sweep default or skip the selector and are deliberately absent.
+ */
+export const SELECTOR_INSPECTORS = ['computed_style', 'pseudo_style', 'text_content', 'attribute', 'count', 'bounding_box', 'expect'];
+
+/** Keep scheme+host+port only (lowercased); anything unparseable goes through for the server to explain. */
+export function normaliseOrigin(input) {
+  try {
+    const u = new URL(String(input).trim());
+    if (!/^https?:$/.test(u.protocol)) return input;
+    return u.origin;
+  } catch {
+    return input;
+  }
+}
+
 // quox#907: a browser login is slower than a read; well above the client's 30s default.
 const LOGIN_TIMEOUT_MS = 120000;
 
@@ -308,14 +327,21 @@ export function registerQlarityCommands(program, ctx) {
   al.command('add <origin>')
     .description('Declare an origin this org may inspect, e.g. https://staging.example.com')
     .option('--note <text>', 'why it is allowed, shown alongside it later')
-    .action(async (origin, opts) => {
+    .action(async (rawOrigin, opts) => {
+      const origin = normaliseOrigin(rawOrigin);
       try {
+        if (origin !== rawOrigin) process.stdout.write(`allowlisting ${origin} (scheme+host+port of ${rawOrigin})\n`);
         const d = await call(client, 'qlarity.orgAllowlist.add', {}, { origin, note: opts.note });
         process.stdout.write(`\u{1F50D} QLARITY: added ${d.entry.origin}\n`);
         process.stdout.write(`  ${d.origins.length} origin(s) now declared for this org\n`);
       } catch (err) {
         // A refusal here is usually a wildcard or a typo, and the server sends
         // the reason. Surface it instead of a bare 400.
+        if (err?.status === 403) {
+          process.stderr.write(`Not added: adding an origin is an org-admin action by design (an agent cannot self-authorize egress).\nRetry as an org admin: quox -p <admin-profile> qlarity origins add ${origin}\n`);
+          process.exitCode = 4;
+          return;
+        }
         if (err?.status === 400 && err?.message) {
           process.stderr.write(`Not added: ${err.message}\n`);
           process.exitCode = 1;
@@ -395,6 +421,11 @@ export function registerQlarityCommands(program, ctx) {
     .option('--session <id>', 'reuse an existing session (e.g. one left open by `quox qlarity login`) instead of opening a fresh one')
     .option('--json', 'raw JSON output')
     .action(async (url, options) => {
+      if (SELECTOR_INSPECTORS.includes(options.inspector) && !options.selector) {
+        process.stderr.write(`${options.inspector} needs --selector. Try: quox qlarity read ${url} --inspector ${options.inspector} --selector 'body'\n`);
+        process.exitCode = 2;
+        return;
+      }
       let sessionId = null;
       let reused = false;
       try {

package/lib/commands/run.js

@@ -39,7 +39,8 @@ export function registerRunCommands(program, ctx) {
         let items = data.data || data.items || (Array.isArray(data) ? data : []);
         // an older engine that ignores the filter must still never show another workflow's runs
         if (options.workflow) items = items.filter((it) => (it.workflowId ?? it.workflow_id) === options.workflow);
-        rows = items.map((item) => ({ ...item, source: 'engine' }));
+        // quoxflow rows are camelCase (workflowName, startedAt, completedAt); the table reads snake_case columns.
+        rows = items.map((item) => ({ ...item, workflow_name: item.workflow_name ?? item.workflowName, started_at: item.started_at ?? item.startedAt, finished_at: item.finished_at ?? item.completedAt ?? item.finishedAt, source: 'engine' }));
         source = 'engine';
       } catch (err) {
         printWarning(`Engine (quoxflow) execution list failed, falling back to the auth-service store: ${err.message}`);

package/lib/commands/server.js

@@ -24,6 +24,7 @@ import { planUninstall, runUninstall } from '../server/uninstall.js';
 import { serverChecks } from '../server/doctor.js';
 import { writeDiagBundle } from '../server/diag.js';
 import { latestSnapshot, listSnapshots } from '../server/snapshot.js';
+import { runInstallFlow } from '../server/installFlow.js';
 import { loadRegistry, saveServer, buildRows, planGo, hereIdentity, registryPath } from '../server/devServers.js';
 
 const icon = (s) => (s === 'pass' ? chalk.green('✔') : s === 'warn' ? chalk.yellow('⚠') : s === 'skip' ? chalk.dim('·') : chalk.red('✖'));
@@ -70,6 +71,42 @@ export function registerServerCommands(program, ctx = {}) {
   const server = program.command('server').description('Your self-hosted Quox install: status, update, rollback, uninstall, doctor, diag');
   const withDir = (c) => c.option('--dir <path>', 'the install directory (default: the one Getting started recorded)');
 
+  server.command('install')
+    .description('Install Quox on this machine: checks, download, start, owner account, one-time dashboard link (the same installer Getting started runs)')
+    .option('--dir <path>', 'where to install (default: ~/quox-install)')
+    .option('--dry-run', 'check this machine, print the plan, change nothing')
+    .option('-y, --yes', 'skip the confirmation (required without a terminal)')
+    .option('--json', 'one JSON object per line: stage events, then a result')
+    .option('--email <address>', 'owner account email (asked when there is a terminal)')
+    .option('--password-stdin', 'read the owner password from stdin, one line (never an argument)')
+    .option('--print-login-link', 'print the live one-time sign-in link (default: only on an interactive terminal, never in --json)')
+    .action(async (o) => {
+      const asJson = Boolean(o.json) || json();
+      const human = (e) => {
+        if (e.type === 'log') { console.log(chalk.dim(`    ${e.line}`)); return; }
+        if (e.type === 'stage') {
+          if (e.status === 'running') console.log(` ${chalk.cyan('◐')} ${e.stage}`);
+          else if (e.status === 'ok') console.log(` ${chalk.green('✔')} ${e.stage}${e.detail ? chalk.dim(`  ${e.detail}`) : ''}`);
+          else if (e.status === 'skip') console.log(` ${chalk.dim('·')} ${e.stage} skipped${e.detail ? `: ${e.detail}` : ''}${e.next ? `. ${e.next}` : ''}`);
+          else if (e.status === 'fail') { console.log(chalk.red(` ✖ ${e.stage} failed: ${e.error}`)); console.log(`   Next: ${e.next}`); }
+        } else if (e.type === 'plan') {
+          console.log(chalk.bold(`\n Plan: install Quox into ${e.dir || '~/quox-install'}`));
+          for (const c of e.checks) console.log(`   ${c.status === 'fail' ? chalk.red('✖') : c.status === 'warn' ? chalk.yellow('⚠') : chalk.green('✔')} ${c.id.padEnd(8)} ${c.body}`);
+          console.log(' It will:'); e.steps.forEach((s, i) => console.log(`   ${i + 1}. ${s}`));
+          console.log(chalk.dim('\n Dry run: nothing was changed. Run quox server install to install.\n'));
+        } else if (e.type === 'result' && e.ok && !e.dryRun) {
+          console.log(chalk.green('\n ✔ Your Quox is running.'));
+          if (e.link) console.log(` Dashboard sign-in link (single use, 10 minutes): ${e.link}`);
+          else console.log(` A one-time sign-in link was issued but not printed (stdout is not a terminal). Get one with: ${e.linkHow}`);
+          console.log(chalk.dim(' Your browser will warn about the certificate once: it is the self-signed one this install made.\n'));
+        }
+      };
+      const emit = (e) => (asJson ? console.log(JSON.stringify(e)) : human(e));
+      const r = await runInstallFlow({ dir: o.dir, dryRun: dry(o), yes: yes(o), email: o.email, passwordStdin: Boolean(o.passwordStdin), printLink: Boolean(o.printLoginLink) || (!asJson && Boolean(process.stdout.isTTY)) }, deps.installFlowDeps || {}, emit);
+      if (!r.ok && !r.dryRun) process.exitCode = r.declined ? 1 : 2;
+      if (!r.ok && r.dryRun === undefined && r.failedStage && dry(o)) process.exitCode = 2;
+    });
+
   withDir(server.command('status').description('Version, health per service, disk, ports and the last update (read-only)'))
     .action(async (o) => {
       const i = await install(o);