quoxcli 0.3.1 → 0.5.0

package/lib/commands/setup.js

@@ -8,6 +8,9 @@ import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError, QuoxValidationError } from '../core/errors.js';
 import { confirmDestructive } from '../core/confirm.js';
 import { passwordProblem } from '../quoxon/onboarding/finish.js';
+import {
+  renderLinkCard, renderLinkedCard, linkedDetails, startWaiting, colorFor, animateFor,
+} from './licenceLinkView.js';
 
 // The auth service's rule (services/auth/utils/passwordValidation.js), said up front.
 export const PASSWORD_POLICY = 'Passwords need at least 12 characters, with an uppercase letter, a lowercase letter, a number and a special character (for example - or !).';
@@ -348,93 +351,142 @@ export function registerSetupCommands(program, ctx) {
         interval,
       });
 
+      // QUOXON (owner 2026-11-05): a framed card with the code, the full
+      // link and a countdown, then a live waiting line on a TTY. Not a TTY
+      // (CI, logs): plain lines, no ANSI, nothing animated.
+      const term = ctx.term || process.stdout;
+      const format = program.opts().output;
+      const pretty = !json && (format === undefined || format === 'table');
+      const color = pretty && colorFor(term);
+      const verificationUrl = started.verification_url || 'https://quox.ai/link';
+      let waiting = null;
       if (!json) {
-        printInfo(`Open ${started.verification_url || 'https://quox.ai/link'} and enter this code:`);
-        console.log('');
-        console.log(chalk.bold.cyan(`    ${started.user_code}`));
-        console.log('');
-        printInfo(`The code is good for ${Math.round(expiresIn / 60)} minutes. Waiting for approval...`);
+        if (pretty) {
+          console.log(renderLinkCard({
+            userCode: started.user_code, url: verificationUrl, remainingMs: expiresIn * 1000, color, cols: term.columns || 80,
+          }));
+          if (term.isTTY) {
+            waiting = startWaiting({ term, deadline, totalMs: expiresIn * 1000, color, animate: animateFor(term) });
+          }
+        } else {
+          printInfo(`Open ${verificationUrl} and enter this code:`);
+          console.log('');
+          console.log(chalk.bold.cyan(`    ${started.user_code}`));
+          console.log('');
+          printInfo(`The code is good for ${Math.round(expiresIn / 60)} minutes. Waiting for approval...`);
+        }
       }
-
-      const pollEp = resolveEndpoint('setup.licensing.device.poll');
-      let lastState = 'started';
-
-      while (Date.now() < deadline) {
-        await sleepFn(interval * 1000);
-
-        let result;
-        try {
-          result = await client.post(pollEp.path, {
-            service: pollEp.service,
-            body: { device_code: deviceCode, interval },
-          });
-        } catch (err) {
-          // 503 means quox.ai blipped, NOT that the activation died: the code
-          // is still live upstream and the customer may still be approving it.
-          // Anything else (409 seat_limit_reached, 403, 400) is terminal.
-          if (err instanceof QuoxApiError && err.status === 503) {
-            if (lastState !== 'unreachable') {
-              emit({ state: 'unreachable', message: err.message });
-              if (!json) printInfo('The licence server is unreachable right now. Still waiting...');
-              lastState = 'unreachable';
+      try {
+        await pollUntilDone();
+      } finally {
+        if (waiting) waiting.stop();
+      }
+      return;
+
+      async function pollUntilDone() {
+        const pollEp = resolveEndpoint('setup.licensing.device.poll');
+        let lastState = 'started';
+
+        while (Date.now() < deadline) {
+          await sleepFn(interval * 1000);
+
+          let result;
+          try {
+            result = await client.post(pollEp.path, {
+              service: pollEp.service,
+              body: { device_code: deviceCode, interval },
+            });
+          } catch (err) {
+            // 503 means quox.ai blipped, NOT that the activation died: the code
+            // is still live upstream and the customer may still be approving it.
+            // Anything else (409 seat_limit_reached, 403, 400) is terminal.
+            if (err instanceof QuoxApiError && err.status === 503) {
+              if (lastState !== 'unreachable') {
+                emit({ state: 'unreachable', message: err.message });
+                if (waiting) waiting.note('licence server unreachable, still waiting');
+                else if (!json) printInfo('The licence server is unreachable right now. Still waiting...');
+                lastState = 'unreachable';
+              }
+              continue;
             }
-            continue;
+            throw enrichLicenseError(err);
           }
-          throw enrichLicenseError(err);
-        }
 
-        const state = result.state || 'pending';
+          const state = result.state || 'pending';
 
-        if (state === 'slow_down') {
-          interval = Number(result.interval) > 0 ? Number(result.interval) : interval + 5;
-        } else if (Number(result.interval) > 0) {
-          interval = Number(result.interval);
-        }
+          if (state === 'slow_down') {
+            interval = Number(result.interval) > 0 ? Number(result.interval) : interval + 5;
+          } else if (Number(result.interval) > 0) {
+            interval = Number(result.interval);
+          }
 
-        if (state !== lastState) {
-          emit({ state, interval, ...(result.error ? { error: result.error } : {}) });
-          lastState = state;
-        }
+          if (state !== lastState) {
+            emit({ state, interval, ...(result.error ? { error: result.error } : {}) });
+            lastState = state;
+          }
 
-        if (state === 'approved') {
-          const lease = result.lease || {};
-          emit({ state: 'approved', lease });
-          if (!json) {
-            formatDetail({
-              license_id: lease.license_id || null,
-              entitlements: lease.entitlements || [],
-              lease_expires_at: lease.expires_at || null,
-            }, { format: program.opts().output, title: 'Licence activated' });
-            printSuccess('This instance is activated. No key was ever pasted into it.');
+          if (state === 'approved') {
+            const lease = result.lease || {};
+            // QUOXON (owner 2026-11-05): read the licence back through the
+            // route `quox licence status` uses, so the run NAMES what was
+            // linked (plan, plugins, seats). A failed read never hides the
+            // activation: the lease is the fallback, and the failure is said.
+            let status = null;
+            let readBackError = null;
+            if (json || pretty) {
+              try {
+                const readEp = resolveEndpoint('setup.licensing.entitlements.list');
+                status = await client.get(readEp.path, { service: readEp.service });
+              } catch (err) {
+                readBackError = err && err.message ? err.message : String(err);
+              }
+            }
+            const details = linkedDetails(lease, status, result);
+            // --json: the pre-existing { state, lease } plus an ADDITIVE `licence`.
+            emit({ state: 'approved', lease, licence: details });
+            if (waiting) { waiting.stop(); waiting = null; }
+            if (pretty) {
+              console.log(renderLinkedCard(details, {
+                color, cols: term.columns || 80, leaseExpiresAt: lease.expires_at || null,
+                profile: program.opts().profile || null, readBackError,
+              }));
+            } else if (!json) {
+              formatDetail({
+                license_id: lease.license_id || null,
+                entitlements: lease.entitlements || [],
+                lease_expires_at: lease.expires_at || null,
+              }, { format: program.opts().output, title: 'Licence activated' });
+              printSuccess('This instance is activated. No key was ever pasted into it.');
+            }
+            return;
           }
-          return;
-        }
 
-        if (state === 'denied') {
-          throw new QuoxApiError(403, 'access_denied',
-            'The activation was denied on quox.ai. Nothing was activated on this instance.');
-        }
-        if (state === 'expired') {
-          throw new QuoxApiError(410, 'expired_token',
-            'The code expired before it was approved. Run `quox setup license link` again for a fresh one.');
-        }
-        if (state === 'consumed') {
-          throw new QuoxApiError(409, 'consumed',
-            'That code was already used. Run `quox setup license link` again for a fresh one.');
-        }
-        if (state === 'activation_failed') {
-          throw new QuoxApiError(502, result.error || 'activation_failed',
-            `The approval landed but the licence could not be stored on this instance: ${result.message || result.error || 'unknown error'}. `
-            + 'Run `quox setup license link` again.');
-        }
-        if (state === 'error') {
-          throw new QuoxApiError(502, result.error || 'device_poll_failed',
-            result.message || 'Device activation failed.');
+          if (state === 'denied') {
+            throw new QuoxApiError(403, 'access_denied',
+              'The activation was denied on quox.ai. Nothing was activated on this instance.');
+          }
+          if (state === 'expired') {
+            throw new QuoxApiError(410, 'expired_token',
+              'The code expired before it was approved. Run `quox setup license link` again for a fresh one.');
+          }
+          if (state === 'consumed') {
+            throw new QuoxApiError(409, 'consumed',
+              'That code was already used. Run `quox setup license link` again for a fresh one.');
+          }
+          if (state === 'activation_failed') {
+            throw new QuoxApiError(502, result.error || 'activation_failed',
+              `The approval landed but the licence could not be stored on this instance: ${result.message || result.error || 'unknown error'}. `
+              + 'Run `quox setup license link` again.');
+          }
+          if (state === 'error') {
+            throw new QuoxApiError(502, result.error || 'device_poll_failed',
+              result.message || 'Device activation failed.');
+          }
         }
-      }
 
-      throw new QuoxApiError(410, 'expired_token',
-        'The code expired before it was approved. Run `quox setup license link` again for a fresh one.');
+        throw new QuoxApiError(410, 'expired_token',
+          'The code expired before it was approved. Run `quox setup license link` again for a fresh one.');
+      }
     });
 
   license

package/lib/commands/shortcut.js

@@ -0,0 +1,41 @@
+// `quox shortcut add|remove`: a short command (default `q`) for quox. Local only; never shadows an existing command.
+import chalk from 'chalk';
+import { createInterface } from 'node:readline/promises';
+import { addShortcut, removeShortcut, DEFAULT_NAME } from '../core/shortcut.js';
+import { askText } from '../quoxon/ask.js';
+
+async function askYes(line) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try { return /^y(es)?$/i.test((await rl.question(`${line} `)).trim()); } finally { rl.close(); }
+}
+
+export function registerShortcutCommand(program, ctx = {}) {
+  const d = ctx.shortcutDeps || {};
+  const out = d.log || ((l) => console.log(l));
+  const sc = program.command('shortcut')
+    .description('A short command for quox, like q (add / remove); refuses if the name already runs something else, never uses sudo');
+  sc.command('add')
+    .description('Make a "q" command that runs quox: a symlink in a directory you own that is on PATH. Refuses (and says what it found) if q already resolves to something else on PATH; never shadows an existing command, no sudo, no shell rc edits. Safe to repeat.')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .option('-y, --yes', 'create without asking (needed in a non-interactive shell)')
+    .action(async (o) => {
+      const name = o.name || DEFAULT_NAME;
+      const yes = o.yes || program.opts().yes;
+      if (!yes) {
+        const tty = d.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (!tty) { out('Not created: this needs a yes. Re-run with quox shortcut add --yes in a non-interactive shell.'); process.exitCode = 1; return; }
+        if (!(await (d.ask || askYes)(askText(`Make \`${name}\` run quox?`, { keys: 'y/N' })))) { out('Not created. Nothing was changed.'); return; }
+      }
+      const r = (d.add || addShortcut)({ name, ...(d.opts || {}) });
+      out(r.ok ? chalk.green(`✔ ${r.message}`) : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+  sc.command('remove')
+    .description('Remove the short command, only if it is a link to this quox (anything else named q is left alone)')
+    .option('--name <name>', 'the short command name', DEFAULT_NAME)
+    .action(async (o) => {
+      const r = (d.remove || removeShortcut)({ name: o.name || DEFAULT_NAME, ...(d.opts || {}) });
+      out(r.ok ? r.message : chalk.red(`✖ ${r.message}`));
+      if (!r.ok) process.exitCode = 1;
+    });
+}

package/lib/commands/skills.js

@@ -84,6 +84,8 @@ export function registerSkillsCommands(program, ctx) {
           for (const it of Array.isArray(items) ? items : []) if (it && it.skill_id) active.set(it.skill_id, it.status || status);
         }
         rows = rows.map((r) => ({ ...r, review_status: active.get(r.id) || null, runnable: !active.has(r.id) }));
+        // Runnable first (stable): a skill that can run leads, so the first row is never one skill_view must refuse.
+        rows = [...rows.filter((r) => r.runnable), ...rows.filter((r) => !r.runnable)];
       } catch (err) {
         printWarning(`Skill review queue could not be read, so which skills can run is unknown: ${err.message}`);
       }
@@ -585,11 +587,27 @@ export function registerSkillsCommands(program, ctx) {
   sealed
     .command('show')
     .description('Show a sealed skill\'s manifest (name, description, input contract, content hash). Manifest only.')
-    .argument('<sealedId>', 'sealed skill ID')
-    .action(async (sealedId) => {
+    .argument('<sealedId>', 'sealed skill ID or name')
+    .action(async (idOrName) => {
       auth.requireAuth();
-      const ep = resolveEndpoint('skills.sealed.get', { sealedId });
-      const data = await client.get(ep.path, { service: ep.service });
+      let sealedId = idOrName;
+      let data;
+      try {
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      } catch (err) {
+        // Coverage wave (ev_mvg4iwfp_d0b2e3): chat passed the skill's name. A 404 that matches exactly one sealed
+        // skill's name resolves to its id; anything else keeps the original error.
+        if (err.status !== 404) throw err;
+        const lep = resolveEndpoint('skills.sealed.list');
+        const list = await client.get(lep.path, { service: lep.service });
+        const rows = (list && (list.sealed ?? list)) || [];
+        const hits = (Array.isArray(rows) ? rows : []).filter((r) => r && r.name === idOrName);
+        if (hits.length !== 1) throw err;
+        sealedId = hits[0].sealedId;
+        const ep = resolveEndpoint('skills.sealed.get', { sealedId });
+        data = await client.get(ep.path, { service: ep.service });
+      }
       printInfo('Manifest only. The sealed content is never returned by the API.');
       formatDetail(data, { format: program.opts().output, title: `Sealed skill: ${sealedId}` });
     });
@@ -625,7 +643,8 @@ export function registerSkillsCommands(program, ctx) {
       try {
         const ep = resolveEndpoint('skills.sealed.create');
         const data = await client.post(ep.path, { service: ep.service, body });
-        printSuccess(`Sealed. sealedId ${data.sealedId}`);
+        // the collector answers { sealed: {...}, evidence }; an older/flat body carries sealedId at the top
+        printSuccess(`Sealed. sealedId ${(data && data.sealed && data.sealed.sealedId) || (data && data.sealedId)}`);
         formatDetail(data, { format: program.opts().output, title: 'Sealed skill' });
         printInfo(SEALED_SECTION_G_SENTENCE);
       } catch (err) {

package/lib/commands/slot.js

@@ -19,6 +19,7 @@ import { dirname, join } from 'node:path';
 
 import { formatDetail, formatOutput, printSuccess, printWarning, printInfo } from '../core/output.js';
 import { events, printEvent } from '../core/quoxglyph.js';
+import { announce, announceOnFail } from '../core/announce.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError, QuoxNetworkError } from '../core/errors.js';
 import { resolveOrgId } from './helpers.js';
@@ -400,6 +401,23 @@ export function registerSlotCommands(program, ctx) {
     }
   }
 
+  // SLOT-FROM: the session name this process holds a slot under (held-slots.json lists it, or QUOX_SLOT
+  // names a held slot), sent as holder_session so the server's hold record stamps from_slot even when
+  // senderSlot() could not bind a live process. The server re-checks identity + session; never trusted.
+  function heldSessionFor(from) {
+    try {
+      const all = readHeldSlots();
+      const want = from ? String(from).toLowerCase() : null;
+      const bySlot = process.env.QUOX_SLOT ? all[String(process.env.QUOX_SLOT).trim()] : null;
+      if (bySlot && !bySlot.member && bySlot.session && (!want || String(bySlot.session).toLowerCase() === want)) return bySlot.session;
+      if (!want) return null;
+      const hit = Object.values(all).find((e) => e && !e.member && String(e.session || '').toLowerCase() === want);
+      return hit ? hit.session : null;
+    } catch {
+      return null;
+    }
+  }
+
   // P10: the collector recognises splinter members only via the ATTACH token.
   // When this Claude session is attached to an agent whose recorded slot is
   // `name`, send that token (same noAuth + Authorization pattern as
@@ -866,7 +884,7 @@ export function registerSlotCommands(program, ctx) {
     .option('--session <s>', 'session name to speak as (default: $QUOX_STREAM)')
     .option('--room', 'post as a joined room member (no hold needed); signed "session (person)" by the server')
     .option('--run <command>', 'ask the human to run ONE command in their own terminal (the text is why); the quox TUI shows it in full and runs it only on their y. Never run server-side')
-    .action(async (name, textParts, options) => {
+    .action(announceOnFail('quoxslots', (name) => `say into ${name}`, async (name, textParts, options) => {
       auth.requireAuth();
       // SLOT-RUN: same rule as the collector (one line, max 2000, no control/bidi characters), checked before sending.
       if (options.run !== undefined) {
@@ -900,6 +918,8 @@ export function registerSlotCommands(program, ctx) {
       // A room post already has its address (the room), so it carries none.
       const fromSlot = options.room ? null : senderSlot(from);
       if (fromSlot) body.from_slot = fromSlot;
+      const heldAs = options.room ? null : heldSessionFor(from);
+      if (heldAs) body.holder_session = heldAs;
       // A freshly created slot gets its Matrix room a few seconds AFTER
       // checkout returns (provisioning is async), so a say straight after
       // checkout used to fail with 409 "no Matrix room yet" (slots audit
@@ -952,6 +972,7 @@ export function registerSlotCommands(program, ctx) {
           throw err;
         }
       }
+      announce('quoxslots', `said into ${name}`, { result: data?.presence?.state === 'listening' ? 'delivered, listening' : 'posted' });
       printSuccess(`Said into ${name}.`);
       if (!options.room && !fromSlot) {
         printWarning(`${from || 'This session'} holds no slot, so replies cannot reach it. Claim one: quox slot checkout <name> --create --session ${from || '<session>'}`);
@@ -962,7 +983,7 @@ export function registerSlotCommands(program, ctx) {
       reportHumanPresence(data?.human_presence);
       reportBridgeDelivery(data?.bridges);
       if (program.opts().output === 'json') formatDetail(data, { format: 'json' });
-    });
+    }));
 
   // QUOXON-BROADCAST: one call fans a message out to every held slot in the org (or --slots).
   slot
@@ -972,24 +993,38 @@ export function registerSlotCommands(program, ctx) {
     .option('--slots <list>', 'comma-separated slot names instead of every held slot')
     .option('--priority <p>', 'normal or urgent', 'normal')
     .option('--ack', 'ask recipients to acknowledge with /ack <id>')
+    .option('--active', 'only sessions listening right now; dormant slots are skipped, not woken')
+    .option('--dry-run', 'with --active: print who would be reached and who is skipped dormant, send nothing')
     .option('--session <s>', 'session name to sign as (default: $QUOX_STREAM)')
-    .action(async (textParts, options) => {
+    .action(announceOnFail('quoxslots', 'broadcast', async (textParts, options) => {
       auth.requireAuth();
       const parsed = parseBroadcastArgs([
-        options.slots ? `--slots ${options.slots}` : '', `--priority ${options.priority}`, options.ack ? '--ack' : '', textParts.join(' '),
+        options.slots ? `--slots ${options.slots}` : '', `--priority ${options.priority}`, options.ack ? '--ack' : '', options.active ? '--active' : '', options.dryRun ? '--dry-run' : '', textParts.join(' '),
       ].filter(Boolean).join(' '));
       if (!parsed.ok) throw new Error(parsed.message);
       const from = options.session || process.env.QUOX_STREAM || null;
+      const bcFromSlot = senderSlot(from);
+      const bcHeldAs = heldSessionFor(from);
       const ep = resolveEndpoint('v1.slots.broadcast');
       const data = await client.post(ep.path, {
         service: ep.service, retries: 0,
-        body: { text: parsed.text, priority: parsed.priority, ack: parsed.ack, ...(parsed.slots ? { slots: parsed.slots } : {}), ...(from ? { from } : {}), org_id: resolveOrgId(auth, program) },
+        body: { text: parsed.text, priority: parsed.priority, ack: parsed.ack, ...(parsed.active ? { active: true } : {}), ...(parsed.dryRun ? { dry_run: true } : {}), ...(parsed.slots ? { slots: parsed.slots } : {}), ...(from ? { from } : {}), ...(bcFromSlot ? { from_slot: bcFromSlot } : {}), ...(bcHeldAs ? { holder_session: bcHeldAs } : {}), org_id: resolveOrgId(auth, program) },
       });
       if (program.opts().output === 'json') return formatDetail(data, { format: 'json' });
+      if (data?.dry_run) { // BROADCAST-ACTIVE --dry-run: nothing was sent
+        const would = data.would_reach || []; const dorm = data.skipped_dormant || [];
+        announce('quoxslots', 'broadcast to active', { result: `${would.length} would reach \u00B7 ${dorm.length} skipped dormant` });
+        if (would.length) printInfo(`  would reach: ${would.join(', ')}`);
+        if (dorm.length) printInfo(`  skipped dormant: ${dorm.join(', ')}`);
+        return printInfo('Dry run: nothing was sent.');
+      }
+      if (parsed.active && data?.skipped_dormant) {
+        announce('quoxslots', 'broadcast to active', { result: `${data.counts?.delivered || 0} reached \u00B7 ${data.skipped_dormant.length} skipped dormant` });
+      } else announce('quoxslots', 'broadcast sent', { result: data?.id || data?.broadcast?.id });
       for (const [line, kind] of broadcastSummary(data)) (kind === 'warn' ? printWarning : printInfo)(line);
       reportHumanPresence(data?.human_presence);
       return undefined;
-    });
+    }));
 
   slot
     .command('broadcast-status')
@@ -1052,12 +1087,14 @@ export function registerSlotCommands(program, ctx) {
   }
   function reportBridgeDelivery(bridges) {
     if (!Array.isArray(bridges) || bridges.length === 0) return;
-    for (const b of bridges) {
-      const where = b.target ? `${b.platform} (${b.target})` : b.platform || 'bridge';
+    // Two bridges that both report "still sending" with no platform/target printed two identical "bridge:" lines;
+    // number them so each line says which bridge it is about.
+    bridges.forEach((b, i) => {
+      const where = b.target ? `${b.platform} (${b.target})` : b.platform || (bridges.length > 1 ? `bridge ${i + 1} of ${bridges.length}` : 'bridge');
       if (b.ok === true) printInfo(`  rendered to ${where}`);
       else if (b.ok === null) printInfo(`  ${where}: still sending, check \`quox slot read\``);
       else printWarning(`  NOT rendered to ${where}: ${b.reason}`);
-    }
+    });
   }
 
   async function readMessages(name, options) {
@@ -1134,6 +1171,7 @@ export function registerSlotCommands(program, ctx) {
       let cursor = options.since || null;
       let netFailures = 0;
       let authSince = null; // start of the current run of consecutive 401/403s
+      let downSince = null; // start of the current outage, for the single resume line
 
       for (;;) {
         const query = { org_id: resolveOrgId(auth, program), timeout_ms: 50000 };
@@ -1145,6 +1183,7 @@ export function registerSlotCommands(program, ctx) {
         let data;
         try {
           data = await client.get(ep.path, { service: ep.service, ...attachAuthFor(name), query, timeout: 65000 });
+          if (downSince !== null) { printInfo(`reconnected after ${Math.round((Date.now() - downSince) / 1000)}s`); downSince = null; }
           netFailures = 0;
           authSince = null;
         } catch (err) {
@@ -1182,6 +1221,7 @@ export function registerSlotCommands(program, ctx) {
             authSince = null;
           }
           netFailures += 1;
+          if (downSince === null) downSince = Date.now();
           let delay = Math.min(2000 * 2 ** Math.min(netFailures - 1, 5), 60000);
           delay = Math.round(delay * (0.75 + Math.random() * 0.5));
           if (Number.isFinite(err.retryAfterMs)) delay = Math.min(Math.max(delay, err.retryAfterMs), 300000);