quoxcli 0.3.1 → 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,9 +12,11 @@
  *                        live loop gate: budget, risk, interval).
  */
 
-import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
+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';
+import { QuoxUserError } from '../core/errors.js';
 
 /**
  * Format a timestamp as a short relative-time string ("5m ago").
@@ -75,6 +77,13 @@ export function registerObjectiveCommands(program, ctx) {
     .option('--loop-backend <backend>', 'claude|codex, loop mode only (default claude)')
     .option('--capability-scope <tools>', 'comma-separated tool names the loop may call (repeatable); empty scope escalates every tool', collectScope)
     .option('--system-prompt <text>', 'per-objective system prompt, carried verbatim to the run')
+    .option('--observe-every <n>', 'loop mode: emit a status line every N turns while it runs (watch with `quox loop watch <id>`)')
+    .option('--observe-milestones', 'loop mode: lift MILESTONE: lines from the loop output into headline updates')
+    .option('--until <text>', 'loop mode: the done criterion in plain words. The loop runs turn after turn until the model ends a turn with "DONE: <evidence>" (or --max-iterations / --max-duration-ms stops it)')
+    .option('--every-seconds <n>', 'loop mode: the runner waits N seconds (30-3600) between turns; the model is never asked to sleep')
+    .option('--workspace <name>', 'loop mode: name the durable workspace dir, so a follow-up loop can work in the same files (default: one per loop)')
+    .option('--done-file <path>', 'loop mode: DONE only counts once this file exists in the loop workspace; the runner checks it itself (repeatable)', (v, prev = []) => prev.concat(v))
+    .option('--done-command <cmd>', 'loop mode: DONE only counts once this command exits 0 in the loop workspace; must be one the loop scope lets it run (repeatable)', (v, prev = []) => prev.concat(v))
     .action(async (goal, options) => {
       auth.requireAuth();
       const body = { title: goal };
@@ -98,6 +107,28 @@ export function registerObjectiveCommands(program, ctx) {
         if (scope.length > 0) body.capability_scope = scope;
       }
       if (options.systemPrompt) body.system_prompt = options.systemPrompt;
+      if (options.until) body.until = options.until;
+      if (options.everySeconds !== undefined) {
+        const n = Number(options.everySeconds);
+        if (!Number.isInteger(n) || n < 30 || n > 3600) throw new QuoxUserError('--every-seconds needs a whole number of seconds between 30 and 3600.');
+        body.every_seconds = n;
+      }
+      if (options.workspace) body.workspace = options.workspace;
+      const doneChecks = [
+        ...(options.doneFile || []).map((path) => ({ kind: 'file_exists', path })),
+        ...(options.doneCommand || []).map((command) => ({ kind: 'command_ok', command })),
+      ];
+      if (doneChecks.length) body.done_check = doneChecks;
+      if (options.observeEvery !== undefined || options.observeMilestones) {
+        const observe = {};
+        if (options.observeEvery !== undefined) {
+          const n = Number(options.observeEvery);
+          if (!Number.isInteger(n) || n < 1) throw new QuoxUserError('--observe-every needs a whole number of turns (1 or more).');
+          observe.every_turns = n;
+        }
+        if (options.observeMilestones) observe.milestones = true;
+        body.observe = observe;
+      }
 
       const data = await client.post(resolveEndpoint('objectives.create').path, { service: resolveEndpoint('objectives.create').service, body });
       printSuccess(`Objective created: ${data.id}`);
@@ -151,10 +182,22 @@ 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}` : ''}`);
     });
 
+  objective
+    .command('retry')
+    .description('Retry a failed or partially completed objective: failed and skipped steps are reset and the plan comes back for approval')
+    .argument('<id>', 'objective ID')
+    .action(async (id) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('objectives.retry', { id });
+      const data = await client.post(ep.path, { service: ep.service });
+      printSuccess(`Objective ${id}: ${data.steps_reset ?? 0} step(s) reset, plan is back for approval. Run \`quox objective approve ${id}\` to run them again.`);
+    });
+
   objective
     .command('checkpoints')
     .description('List pending HITL checkpoints across the org (approval queue)')
@@ -190,7 +233,14 @@ 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'}).`);
+        if (data.hint) printWarning(data.hint);
+        return;
+      }
       printSuccess(`Checkpoint ${checkpointId}: ${data.status}${data.objective_status ? ` (objective ${data.objective_status})` : ''}`);
     });
 

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

@@ -7,6 +7,7 @@ import { formatOutput, formatDetail, printSuccess, printWarning } from '../core/
 import { otherProfileUsers, listProcs } from '../core/profileUsers.js';
 import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { numberedOrgLines, pickOrgByInput, sharedSwitchHint } from '../quoxon/orgSwitch.js';
 
 export function registerOrgCommands(program, ctx) {
   const { client, auth, config } = ctx;
@@ -90,9 +91,26 @@ export function registerOrgCommands(program, ctx) {
   org
     .command('switch')
     .description('Switch active organization context')
-    .argument('<orgId>', 'organization ID or slug')
-    .action(async (orgId) => {
+    .argument('[orgId]', 'organization ID, slug, or the number from the list (omit to pick from a numbered list)')
+    .action(async (orgIdArg) => {
       auth.requireAuth();
+      let orgId = orgIdArg;
+      if (!orgId || /^\d+$/.test(orgId)) {
+        const l = await client.get(resolveEndpoint('orgs.list').path, { service: resolveEndpoint('orgs.list').service });
+        const orgs = Array.isArray(l) ? l : (l?.organizations || l?.orgs || l?.data || []);
+        if (!orgs.length) throw new QuoxError('No organisations returned for this login.', 1);
+        if (!orgId) {
+          const curId = (() => { try { return auth.getOrgId(); } catch { return null; } })();
+          for (const line of numberedOrgLines(orgs, curId)) console.log(line);
+          if (!process.stdin.isTTY) throw new QuoxError('Pass a number, slug or ID: quox org switch <number>.', 1);
+          const rl = (await import('node:readline/promises')).createInterface({ input: process.stdin, output: process.stdout });
+          try { orgId = await rl.question('Switch to which? (number, slug, or Enter to cancel) '); } finally { rl.close(); }
+          if (!orgId.trim()) { console.log('Not switched.'); return; }
+        }
+        const pick = pickOrgByInput(orgId, orgs);
+        if (pick.org) orgId = pick.org.id;
+        else if (/^\d+$/.test(orgId)) throw new QuoxError(`No org numbered ${orgId}. Run \`quox org switch\` to see the list.`, 1);
+      }
       // The server matches memberships by org ID only. Accept a slug (or exact name) by
       // resolving it against the caller's org list first; a 26-char ULID passes through.
       let targetId = orgId;
@@ -126,8 +144,7 @@ export function registerOrgCommands(program, ctx) {
         const name = config.getActiveProfileName?.();
         const others = name ? otherProfileUsers({ profile: name, defaultProfile: config._data?.activeProfile, procs: listProcs(), selfPids: [process.pid, process.ppid] }) : [];
         if (others.length) {
-          printWarning(`${others.length} other quox session${others.length === 1 ? '' : 's'} use profile "${name}" (pid ${others.map(p => p.pid).join(', ')}). `
-            + 'They follow this org on their next token refresh or restart. To move one window only, use /org switch inside it.');
+          printWarning(sharedSwitchHint({ name, pids: others.map(p => p.pid) }));
         }
       } catch { /* best effort: never fail the switch over the warning */ }
     });

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

@@ -17,6 +17,9 @@ import { createApi, isInteractiveHuman } from '../quoxon/api.js';
 import { PROVIDERS, providerFor, looksLikeKey, connectionLines, connectFlow, connectOllamaFlow, connectCompatFlow } from '../quoxon/connect.js';
 import { needsConsent, consentCovers, connectConsentNote, providerLabel } from '../quoxon/consent.js';
 import { readStdin } from '../quoxon/print.js';
+import { INSTALL_TOOLS, toolFor, planLine, offerQuestion, runInstall, isAgentCaller } from '../quoxon/installCli.js';
+import { YN_OPTIONS, waitForDecision } from '../core/askDecision.js';
+import { detectCallerSource } from '../core/callerSource.js';
 
 const KINDS = Object.keys(PROVIDERS);
 const SAFE_ROW = ['id', 'integration_type', 'label', 'is_default', 'test_status', 'last_tested_at', 'created_at'];
@@ -25,6 +28,8 @@ const CONTAINER_NOTE = 'Quox runs in containers: 127.0.0.1 or localhost means th
 function defaultIO() {
   return {
     isTTY: () => isInteractiveHuman(),
+    isAgent: () => isAgentCaller(process.env),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
     readStdin: () => readStdin(),
     promptSecret: async (message) => {
       const { default: inquirer } = await import('inquirer');
@@ -53,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 ───────────────────────────────────────────────────────
@@ -129,6 +136,59 @@ export function registerProviderCommands(program, ctx) {
       await consentAfter(p.type);
     });
 
+  // ── provider install (LAZY-AI-CLI) ────────────────────────────────────────
+  // The user's own server downloads the vendor's npm package (never a binary Quox ships). A person decides: y/N on
+  // a terminal, a high-risk approval card when an agent runs it (an agent's --yes is not a person's yes).
+  provider
+    .command('install')
+    .description('Install Claude Code or Codex on this Quox server from npm (the vendor\'s own package), so Claude sign-in and Codex work. Instance admin only')
+    .argument('<tool>', `what to install: ${Object.keys(INSTALL_TOOLS).join(', ')}`)
+    .option('--yes', 'install without the y/N question (a script; an agent still gets an approval card)')
+    .action(async (toolArg, opts) => {
+      auth.requireAuth();
+      const tool = toolFor(toolArg);
+      if (!tool) throw new Error(`No installable CLI called "${toolArg}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`);
+      const t = INSTALL_TOOLS[tool];
+      const a = api();
+      const st = await a.providerCliStatus();
+      const cur = st?.ok ? st.tools.find((x) => x.id === tool) : null;
+      if (cur?.installed) { printInfo(`✔ ${t.name} is already installed on this server (${cur.version || 'version unknown'}${cur.location ? `, ${cur.location}` : ''}). Nothing to do.`); return; }
+      const plan = await a.providerCliPlan(tool);
+      if (!plan?.ok) {
+        if (plan?.status === 404 || plan?.status === 405) throw new Error(`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`);
+        throw new Error(plan?.status === 403 ? (plan.error || 'Only an instance admin can install software on this server.') : `Could not plan the install: ${plan?.error || 'no answer'}`);
+      }
+      printInfo(planLine(plan));
+      let approvalId = null;
+      if (io.isAgent()) {
+        const orgId = resolveOrgId(auth, program);
+        const src = (() => { try { return detectCallerSource(process.env); } catch { return {}; } })();
+        const session = process.env.QUOX_SESSION || src?.label || 'agent';
+        const ep = resolveEndpoint('inbox.decision.create', { orgId });
+        const filed = await client.post(ep.path, { service: ep.service, body: {
+          session, title: `Install ${t.name} on this server?`, why: planLine(plan), options: YN_OPTIONS, recommend: 'y', high_risk: true,
+          justification: `${session} asked to install ${t.vendor}'s ${plan.package} ${plan.version} from npm on this Quox server, so ${t.name} works. It runs as the Quox service user, never root, and every install is audited.`,
+          agent: process.env.QUOX_AGENT_ID || undefined,
+        } });
+        const id = filed?.decision?.id;
+        if (!id) throw new Error('Could not file the approval card. Nothing was installed.');
+        printInfo(`An agent is running this, so a person decides: approval card ${id} is in /approvals (needs the step-up PIN).`);
+        const r = await waitForDecision({
+          poll: (w) => { const g = resolveEndpoint('inbox.decision.get', { orgId, id }); return client.get(g.path, { service: g.service, query: { wait: w }, timeout: (w + 15) * 1000, retries: 0 }); },
+          log: (m) => process.stderr.write(`${m}\n`),
+        });
+        if (r.decision?.state !== 'answered' || r.decision?.answer?.option !== 'y') { printInfo(`Not installed: the card was not approved. Nothing was downloaded.`); process.exitCode = 2; return; }
+        approvalId = id;
+      } else if (!opts.yes) {
+        if (!io.isTTY()) throw new Error(`Run again with --yes to install ${t.name}, or run it in a terminal to be asked. Nothing was installed.`);
+        if (!(await io.confirm(offerQuestion(tool, plan)))) { printInfo('Not installed. Nothing was downloaded.'); return; }
+      }
+      printInfo(`◐ installing ${t.name} ${plan.version} on the server (this takes a minute or two)`);
+      const r = await runInstall(a, tool, { approvalId, onProgress: printInfo, sleep: io.sleep || undefined });
+      if (!r.ok) throw new Error(r.lines.join(' '));
+      for (const l of r.lines) printInfo(l);
+    });
+
   // ── provider test ──────────────────────────────────────────────────────────
   provider
     .command('test')
@@ -144,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;
     });
 }