quoxcli 0.2.0 → 0.4.0

package/lib/commands/tool.js

@@ -2,10 +2,30 @@
  * Tool commands: CRUD, catalog, install, publish
  */
 
+import fs from 'node:fs';
 import { missingReasonWarning } from '../core/callerSource.js';
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 import { resolveOrgId, parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { capInline, checkShape, shapeOutput, shapeRecord } from '../toolOutputShape.js';
+
+/**
+ * QUOXON-LATENCY L2: the per-turn credential. QUOX_AUTH_TOKEN (cold spawn) or, on a warm
+ * `claude` spare, QUOX_AUTH_TOKEN_FILE: a file the collector writes for one turn and
+ * deletes when it ends. When the file variable is set it is the ONLY credential: a
+ * missing or empty file fails closed, never falling back to a stored session or the
+ * service key.
+ */
+function readTurnToken(env) {
+  if (env.QUOX_AUTH_TOKEN) return env.QUOX_AUTH_TOKEN;
+  if (!env.QUOX_AUTH_TOKEN_FILE) return '';
+  let token = '';
+  try { token = fs.readFileSync(env.QUOX_AUTH_TOKEN_FILE, 'utf8').trim(); } catch { token = ''; }
+  if (!token) throw new Error('No turn credential: QUOX_AUTH_TOKEN_FILE holds no token (the turn has ended). Refusing to use any other credential.');
+  return token;
+}
+
+const failedOf = (data) => !!((data && data.success === false) || (data && data.result && data.result.success === false));
 
 export function registerToolCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -58,7 +78,7 @@ export function registerToolCommands(program, ctx) {
       const orgId = resolveOrgId(auth, program);
       const body = {
         name: options.name,
-        type: options.type,
+        tool_type: options.type, // #987: auth reads tool_type ('type' made every create 400)
         risk_level: options.riskLevel,
       };
       if (options.description) body.description = options.description;
@@ -132,67 +152,59 @@ export function registerToolCommands(program, ctx) {
 
   tool
     .command('exec')
-    .description('Execute a governed tool via the collector (POST /api/v1/tools/execute)')
+    .description('Execute a governed tool via the collector (POST /api/v1/tools/execute). Large output: use --select/--summary, never a shell pipe.')
     .argument('<name>', 'tool name/id (the TOOL_DEFS key, e.g. "codebase_query")')
     .option('--args <json>', "tool arguments as a JSON string, e.g. '{\"query\":\"...\"}'", '{}')
     // #620: docs/muscle-memory reach for --input; accept it as an alias for
     // --args so the documented form works. --args still wins if both given.
     .option('--input <json>', 'alias for --args (tool arguments as a JSON string)')
     .option('--reason <text>', 'why you are running this; shown on the approval card if the call is held for a human')
+    // #970: governed shaping of a large result (the receipt records the shape). Grammar:
+    // a.b, a[0], list[field=value], list[field~text], list[*].field, list[*].{a,b}, list[field=value].name, count(list).
+    .option('--select <path>', 'return only this part of the result, e.g. agents[status=disconnected].name, streams[name~license] (contains, any case), layers[*].state (every item), containers[*].{host,name,status} (several fields in one call), count(urls), or several paths at once: total,count(urls)')
+    .option('--summary', 'honest summary of the main list: total, per-status counts, first N items ("showing N of M")')
+    .option('--limit <n>', 'cap the list to N items (with --summary: the sample size, default 10)')
     .action(async (name, options) => {
-      auth.requireAuth();
       // Prefer whichever was explicitly given; --args carries the '{}' default
       // so it is always defined, hence check --input first.
       const usedInput = options.input !== undefined && (options.args === undefined || options.args === '{}');
       const raw = usedInput ? options.input : options.args;
       const input = parseJSON(raw, usedInput ? '--input' : '--args');
-      const body = { tool_name: name, input };
-      if (options.reason) body.reason = String(options.reason);
-      { const w = missingReasonWarning(name, options.reason); if (w) console.error(w); }
-
-      // Same org-resolution precedence as `fleet exec` (lib/commands/fleet.js):
-      // the collector's /api/v1/tools/execute requires org_id in the body for
-      // service-key authenticated callers (isServiceKeyAuth = !req.user,
-      // services/collector/server.js ~8326) since there is no session to
-      // derive org from. A human-logged-in caller has req.user and the
-      // server derives org from the session instead — --org / QUOX_ORG_ID
-      // still wins when set explicitly.
-      const orgId = auth.getOrgId(program.opts().org || process.env.QUOX_ORG_ID);
-      if (!orgId && process.env.QUOX_SERVICE_KEY) {
-        throw new Error(
-          'QUOX_SERVICE_KEY is set but no org could be resolved. '
-          + 'Set QUOX_ORG_ID=<org> for automation callers, or pass --org <id>.'
-        );
+      const shape = { select: options.select, summary: !!options.summary, limit: options.limit };
+      // A malformed shape fails BEFORE the tool runs: nothing executes, nothing to receipt.
+      const shapeErr = checkShape(shape);
+      if (shapeErr) throw new Error(shapeErr);
+      const outputShape = shapeRecord(shape);
+      const data = await executeGovernedTool({ client, auth, program }, name, input, { reason: options.reason, outputShape });
+      // Shape only a completed, successful result: a held or failed call is shown whole.
+      let shown = data;
+      const held = data && (data.pending || data._approval || data.status === 'pending_approval' || data.status === 'held');
+      if (outputShape && data && !held && !failedOf(data)) {
+        const wrapped = data.result !== undefined;
+        const value = shapeOutput(wrapped ? data.result : data, shape).value;
+        shown = wrapped ? { ...data, result: value, output_shape: outputShape } : { result: value, output_shape: outputShape };
       }
-      if (orgId) body.org_id = orgId;
-
-      // QUOXHAT T0 (2026-10-01): automation callers (the collector's
-      // CLI-tools chat path) carry the conversation + acting user in env,
-      // exactly like QUOX_ORG_ID above. The collector's execute route keys
-      // hat-binding resolution on body.session_id and user prefs on
-      // body.user_id; without them every CLI-tools execution ran against the
-      // org default hat and user-less. Interactive humans have neither set.
-      if (process.env.QUOX_SESSION_ID) body.session_id = process.env.QUOX_SESSION_ID;
-      if (process.env.QUOX_USER_ID) body.user_id = process.env.QUOX_USER_ID;
-      // QUOXHAT #657 P-C.2: forward the ACTING AGENT so a specialist's CLI-tools
-      // chat turn executes as that specialist, not the orchestrator. Without it
-      // the spawned CLI is a service caller with no agent_id, which the
-      // collector defaults to 'quox' — so under enforce a restricted specialist
-      // would silently run tools against the orchestrator's broad grant (the
-      // "CLI exec silently becomes quox" bypass). The collector sets this from
-      // its own selected_agent; a service-key caller's known agent_id is
-      // trusted, and the P-B gate then authorizes against the specialist's own
-      // grant ceiling ∩ the hat mode.
-      if (process.env.QUOX_AGENT_ID) body.agent_id = process.env.QUOX_AGENT_ID;
-
-      const ep = resolveEndpoint('v1.tools.execute');
-      const data = await client.post(ep.path, { service: ep.service, body, timeout: 120000 });
+      // BASH-FALLBACK: on the model-driven path (a per-turn credential is set) an oversized
+      // result would be saved to a file by the Bash tool and the model would reach for jq on
+      // it, which the guard denies. Keep it inline as the honest summary view instead. Never
+      // for a held or failed call (the approval/error is shown whole), never for a human.
+      let modelPath = false;
+      try { modelPath = !!readTurnToken(process.env); } catch { modelPath = false; }
+      if (modelPath && data && !held && !failedOf(data)) {
+        const wrapped = shown && shown.result !== undefined;
+        const capped = capInline(wrapped ? shown.result : shown);
+        if (capped.capped) shown = wrapped ? { ...shown, result: capped.value } : capped.value;
+      }
+      // quox#1031 (same class as #999): a refused or failed call must exit non-zero, or a script reads
+      // success on failure. A HELD (pending) call awaits a human, so it stays 0.
+      const failed = failedOf(data);
+      if (failed && !(data && data.pending)) process.exitCode = 1;
 
       if (program.opts().output === 'json') {
-        console.log(JSON.stringify(data, null, 2));
+        console.log(JSON.stringify(shown, null, 2));
         return;
       }
-      const result = data && (data.result !== undefined ? data.result : data);
+      const result = shown && (shown.result !== undefined ? shown.result : shown);
       if (typeof result === 'string') {
         console.log(result);
       } else {
@@ -214,3 +226,79 @@ export function registerToolCommands(program, ctx) {
       printSuccess('Tool installed.');
     });
 }
+
+/**
+ * POST /api/v1/tools/execute for one governed tool, with the full identity
+ * contract `tool exec` established (per-turn QUOX_AUTH_TOKEN, org resolution,
+ * hat session/user/agent forwarding). Shared so a named verb that wraps a tool
+ * (e.g. `quox actions list`, #839) authenticates exactly like `tool exec`.
+ * Returns the raw response body.
+ */
+// quox#1034: the HTTP budget for one governed tool call. 120 s for a person at a terminal. A caller that spawns
+// the CLI with a longer budget of its own (the collector's CLI-tools chat path, where delegate_to_agent waits up to
+// the specialist's delegation.wait_ms, Browser-Q 180 s) states it in QUOX_TOOL_EXEC_TIMEOUT_MS, so the client hop
+// never gives up before the server's own deadline and detach do. Capped at 15 minutes.
+export function toolExecTimeoutMs(env = process.env) {
+  const n = Number(env && env.QUOX_TOOL_EXEC_TIMEOUT_MS);
+  if (!Number.isFinite(n) || n < 1000) return 120000;
+  return Math.min(Math.floor(n), 900000);
+}
+
+export async function executeGovernedTool({ client, auth, program }, name, input, { reason, outputShape } = {}) {
+  // QUOXON-IDENTITY: QUOX_AUTH_TOKEN is the collector's per-turn scoped
+  // credential for the model-driven CLI-tools path. When set it is the ONLY
+  // credential: sent as the bearer, never the service key, no stored-session
+  // or refresh fallback, and org/user come from the token (not the body).
+  const turnToken = readTurnToken(process.env);
+  if (!turnToken) auth.requireAuth();
+  const body = { tool_name: name, input };
+  if (reason) body.reason = String(reason);
+  // #970: the collector records the view the caller was shown in the tool receipt.
+  if (outputShape) body.output_shape = outputShape;
+  { const w = missingReasonWarning(name, reason); if (w) console.error(w); }
+
+  // Same org-resolution precedence as `fleet exec` (lib/commands/fleet.js):
+  // the collector's /api/v1/tools/execute requires org_id in the body for
+  // service-key authenticated callers (isServiceKeyAuth = !req.user,
+  // services/collector/server.js ~8326) since there is no session to
+  // derive org from. A human-logged-in caller has req.user and the
+  // server derives org from the session instead — --org / QUOX_ORG_ID
+  // still wins when set explicitly.
+  const orgId = turnToken ? null : auth.getOrgId(program.opts().org || process.env.QUOX_ORG_ID);
+  if (!orgId && !turnToken && process.env.QUOX_SERVICE_KEY) {
+    throw new Error(
+      'QUOX_SERVICE_KEY is set but no org could be resolved. '
+      + 'Set QUOX_ORG_ID=<org> for automation callers, or pass --org <id>.'
+    );
+  }
+  if (orgId) body.org_id = orgId;
+
+  // QUOXHAT T0 (2026-10-01): automation callers (the collector's
+  // CLI-tools chat path) carry the conversation + acting user in env,
+  // exactly like QUOX_ORG_ID above. The collector's execute route keys
+  // hat-binding resolution on body.session_id and user prefs on
+  // body.user_id; without them every CLI-tools execution ran against the
+  // org default hat and user-less. Interactive humans have neither set.
+  if (process.env.QUOX_SESSION_ID) body.session_id = process.env.QUOX_SESSION_ID;
+  if (process.env.QUOX_USER_ID && !turnToken) body.user_id = process.env.QUOX_USER_ID;
+  // QUOXHAT #657 P-C.2: forward the ACTING AGENT so a specialist's CLI-tools
+  // chat turn executes as that specialist, not the orchestrator. Without it
+  // the spawned CLI is a service caller with no agent_id, which the
+  // collector defaults to 'quox' — so under enforce a restricted specialist
+  // would silently run tools against the orchestrator's broad grant (the
+  // "CLI exec silently becomes quox" bypass). The collector sets this from
+  // its own selected_agent; a service-key caller's known agent_id is
+  // trusted, and the P-B gate then authorizes against the specialist's own
+  // grant ceiling ∩ the hat mode.
+  if (process.env.QUOX_AGENT_ID) body.agent_id = process.env.QUOX_AGENT_ID;
+
+  const ep = resolveEndpoint('v1.tools.execute');
+  // noAuth: client.js adds no service key / stored session / refresh retry.
+  const data = await client.post(ep.path, {
+    service: ep.service,
+    body,
+    timeout: toolExecTimeoutMs(process.env),
+    ...(turnToken ? { noAuth: true, noActAs: true, headers: { Authorization: `Bearer ${turnToken}` } } : {}),
+  });
+  return data;
+}

package/lib/commands/trace.js

@@ -20,7 +20,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { formatOutput, formatDetail, printSuccess, printWarning, printInfo } from '../core/output.js';
-import { parseJSON } from './helpers.js';
+import { parseJSON, withTimeoutHint } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 
 /** Flatten the nested `actor` object into a display string for table rows. */
@@ -71,10 +71,14 @@ export function registerTraceCommands(program, ctx) {
       if (options.denied) query.has_denial = 'true';
       if (options.hitl) query.has_hitl = 'true';
 
-      const data = await client.get(resolveEndpoint('traces.list').path, {
-        service: resolveEndpoint('traces.list').service,
-        query,
-      });
+      const data = await withTimeoutHint(
+        'quox trace list',
+        'Try a smaller --limit or a narrower window (--after <iso>, --before <iso>).',
+        () => client.get(resolveEndpoint('traces.list').path, {
+          service: resolveEndpoint('traces.list').service,
+          query,
+        }),
+      );
       const traces = (data.traces || data || []).map(normalizeTraceSummary);
 
       formatOutput({
@@ -83,8 +87,9 @@ export function registerTraceCommands(program, ctx) {
         rows: traces,
       }, { format: program.opts().output, emptyMessage: 'No traces found.' });
 
-      if (program.opts().output !== 'json' && program.opts().output !== 'quiet' && typeof data.total === 'number') {
-        printInfo(`Showing ${traces.length} of ${data.total} trace(s).`);
+      if (program.opts().output !== 'json' && program.opts().output !== 'quiet') {
+        if (typeof data.total === 'number') printInfo(`Showing ${traces.length} of ${data.total} trace(s).`);
+        else if (data.has_more) printInfo(`Showing ${traces.length} trace(s); more available (--offset ${Number(options.offset || 0) + Number(options.limit || 30)}).`);
       }
     });
 

package/lib/commands/trigger.js

@@ -5,6 +5,8 @@
  *
  * quox trigger webhooks|schedules|events
  * quox trigger workflow-activate|workflow-deactivate <workflow-id>
+ * quox trigger pause|resume <workflow-id> [node-id]
+ * quox trigger webhook-fire <path> [--body <json|@file>]
  *
  * Backend: quoxflow (NOT the auth service, NOT proxied by collector) — see
  * cli/lib/api/endpoints/triggers.js header for the full access-path
@@ -21,7 +23,48 @@
 import { formatOutput, formatDetail, printInfo } from '../core/output.js';
 import { line as glyphLine, printEvent } from '../core/quoxglyph.js';
 import { resolveOrgId } from './helpers.js';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { resolve as resolvePath, sep, basename } from 'node:path';
 import { resolveEndpoint } from '../api/endpoints.js';
+import { QuoxApiError } from '../core/errors.js';
+
+
+// A webhook path is plain segments under /webhooks: no .., no query or fragment, no encoding tricks, no spaces.
+const WEBHOOK_SEGMENT = /^[A-Za-z0-9._~-]+$/;
+export function normalizeWebhookPath(raw) {
+  let p = String(raw || '').trim().replace(/^\/+/, '');
+  if (p.startsWith('webhooks/')) p = p.slice('webhooks/'.length);
+  const segs = p.split('/');
+  if (!p || segs.some((x) => !WEBHOOK_SEGMENT.test(x) || x === '.' || x === '..')) {
+    throw new Error(`webhook path "${raw}" is not a plain path under /webhooks (letters, digits, . _ ~ - and /; no .., query, fragment or spaces)`);
+  }
+  return segs.join('/');
+}
+// HYPERION #23: --body @file is an ALLOWLIST. The file must be a regular file whose REAL path (symlinks resolved) is
+// inside the working directory, and never a credential-shaped name: ~/.config/quox/config.json is JSON and holds the
+// user's tokens, and the fired run's trigger data is org-readable and can be forwarded by the workflow.
+const CREDENTIAL_NAME = /^(?:\.env(?:\..*)?|.*\.pem|.*\.key|id_[a-z0-9_]+(?:\.pub)?|credentials(?:\..*)?)$/i;
+export function parseWebhookBody(raw, { cwd = process.cwd() } = {}) {
+  if (raw === undefined) return {};
+  let text = String(raw);
+  if (text.startsWith('@')) {
+    const asked = text.slice(1);
+    const rule = '--body @file reads only a regular file inside the current directory';
+    let real, root;
+    try { root = realpathSync(cwd); real = realpathSync(resolvePath(cwd, asked)); }
+    catch { throw new Error(`--body @${asked}: no such file (${rule})`); }
+    if (real !== root && !real.startsWith(root + sep)) throw new Error(`--body @${asked} is not inside the current directory (${rule}; symlinks are followed)`);
+    const rel = real.slice(root.length + 1);
+    if (CREDENTIAL_NAME.test(basename(real)) || /(^|[\\/])\.config[\\/].*config\.json$/i.test(rel)) throw new Error(`--body @${asked} looks like a credential file; refused (${rule}, never a key, token or config file)`);
+    if (!statSync(real).isFile()) throw new Error(`--body @${asked} is not a regular file (${rule})`);
+    text = readFileSync(real, 'utf8');
+  }
+  try { return JSON.parse(text); } catch { throw new Error('--body is not JSON (pass a JSON string or @file with JSON in it)'); }
+}
+const apiFail = (method, path, err) => {
+  const status = err instanceof QuoxApiError ? err.status : 'network error';
+  return new Error(`${method} ${path} failed (${status}): ${err.message}`);
+};
 
 export function registerTriggerCommands(program, ctx) {
   const { client, auth } = ctx;
@@ -125,4 +168,56 @@ export function registerTriggerCommands(program, ctx) {
       printEvent(glyphLine('quox', 'workflow deactivated', { result: id, status: 'ok' }));
       formatDetail(result, { format: program.opts().output });
     });
+
+  // ── trigger pause | resume ─────────────────────────────────────────────────
+  // SITE-CLI 2026-10-19: pausing a schedule meant re-applying the workflow JSON with paused:true pasted in by hand.
+  // The node is found from the workflow when it has exactly one schedule; with several, name it (never guess).
+  const scheduleNode = async (workflowId, nodeId) => {
+    if (nodeId) return nodeId;
+    const ep = resolveEndpoint('triggers.schedule-list');
+    const data = await client.get(ep.path, { service: ep.service });
+    const rows = (Array.isArray(data?.data) ? data.data : Array.isArray(data) ? data : []).filter((r) => r.workflowId === workflowId);
+    if (rows.length === 0) throw new Error(`no schedule found for workflow ${workflowId} (is it activated? quox trigger schedules)`);
+    if (rows.length > 1) throw new Error(`workflow ${workflowId} has ${rows.length} schedule nodes (${rows.map((r) => r.nodeId).join(', ')}): name one, quox trigger pause ${workflowId} <node>`);
+    return rows[0].nodeId;
+  };
+  for (const [verb, key, done] of [['pause', 'triggers.schedule-pause', 'paused'], ['resume', 'triggers.schedule-resume', 'resumed']]) {
+    trigger
+      .command(verb)
+      .description(verb === 'pause'
+        ? 'Pause a workflow schedule (stays paused across restarts) without re-applying the workflow'
+        : 'Resume a paused workflow schedule')
+      .argument('<workflowId>', 'workflow ID')
+      .argument('[nodeId]', 'schedule node ID (needed only when the workflow has more than one schedule)')
+      .action(async (workflowId, nodeIdArg) => {
+        auth.requireAuth();
+        const nodeId = await scheduleNode(workflowId, nodeIdArg);
+        const ep = resolveEndpoint(key, { workflowId, nodeId });
+        let data;
+        try { data = await client.post(ep.path, { service: ep.service }); } catch (err) { throw apiFail('POST', ep.path, err); }
+        const result = data?.data || data;
+        printEvent(glyphLine('quox', `schedule ${done}`, { result: `${workflowId}:${nodeId}`, status: 'ok' }));
+        formatDetail(result, { format: program.opts().output });
+      });
+  }
+
+  // ── trigger webhook-fire ───────────────────────────────────────────────────
+  // Test-fire a workflow's inbound webhook through the real public ingress. The route copies every request header
+  // into the run's trigger data, so this sends NO bearer and NO service key: the run is a system:webhook:<path> run,
+  // exactly like an outside caller's.
+  trigger
+    .command('webhook-fire')
+    .description('Fire a workflow inbound webhook (POST /webhooks/<path>) as an outside caller would, with no credentials')
+    .argument('<path>', 'webhook path, e.g. orders/new (a leading /webhooks/ is fine)')
+    .option('--body <json|@file>', 'JSON body (a JSON string, or @file); default {}')
+    .action(async (rawPath, options) => {
+      const path = normalizeWebhookPath(rawPath);
+      const body = parseWebhookBody(options.body, { cwd: (ctx.cwd || (() => process.cwd()))() });
+      const ep = resolveEndpoint('triggers.webhook-fire', { path });
+      let data;
+      try { data = await client.post(ep.path, { service: ep.service, body, noAuth: true, noActAs: true, anonymous: true }); } catch (err) { throw apiFail('POST', ep.path, err); }
+      const result = data?.data || data;
+      printEvent(glyphLine('quox', 'webhook fired', { result: `/webhooks/${path}${result?.executionId ? ` · run ${result.executionId}` : ''}`, status: 'ok' }));
+      formatDetail(result, { format: program.opts().output });
+    });
 }

package/lib/commands/update.js

@@ -0,0 +1,46 @@
+/**
+ * `quox update` (and `quox --update`, rewritten to this in bin/quox.js): update this quox the way it was
+ * installed. The same updater as /update in the conversation client (lib/core/selfUpdate.js).
+ *
+ *   quox update            check, show what's new, ask y/N (a TTY), then run the update with the terminal
+ *   quox update --check    check and show, change nothing (exit 10 when an update is available)
+ *   quox update --yes      no question (needed when not a TTY)
+ */
+import chalk from 'chalk';
+import { createInterface } from 'node:readline/promises';
+import { detectInstall, checkUpdate, runUpdate, updateLines, updateAsk } from '../core/selfUpdate.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 registerUpdateCommand(program, ctx = {}) {
+  const d = ctx.updateDeps || {};
+  const out = d.log || ((l) => console.log(l));
+  program.command('update')
+    .description('Update quox to the latest version (npm, git checkout, or this box\'s shared CLI); also quox --update')
+    .option('--check', 'show what an update would do and change nothing')
+    .option('-y, --yes', 'update without asking (needed in a non-interactive shell)')
+    .action(async (o) => {
+      const info = (d.detect || detectInstall)({});
+      const plan = await (d.check || checkUpdate)(info);
+      for (const l of updateLines(plan)) out(l);
+      if (!plan.ok) { process.exitCode = 2; return; }
+      if (plan.upToDate) return;
+      if (plan.refused) { process.exitCode = 1; return; }
+      if (o.check) { out(`Update with: quox update  (runs: ${plan.command.display})`); process.exitCode = 10; return; }
+      const yes = o.yes || program.opts().yes;
+      if (!yes) {
+        const tty = d.isTTY ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+        if (!tty) { out('Not updated: this needs a yes. Re-run with quox update --yes in a non-interactive shell.'); process.exitCode = 1; return; }
+        if (!(await (d.ask || askYes)(updateAsk(plan, { restart: false })))) { out('Not updated. Nothing was changed.'); return; }
+      }
+      out(chalk.dim(`Running: ${plan.command.display}`));
+      const r = (d.run || runUpdate)(plan);
+      if (r.ok) { out(chalk.green(`✔ Updated (exit 0). The next quox you start is the new one.`)); return; }
+      process.exitCode = r.code || 1;
+      out(chalk.red(`✖ Update failed: ${plan.command.display} ${r.error ? `could not start (${r.error})` : `exited ${r.code}`}. Nothing else was changed.`));
+      out(`Run it yourself to see why: ${plan.manual}`);
+    });
+}

package/lib/commands/vault.js

@@ -943,6 +943,8 @@ export function registerVaultCommands(program, ctx) {
       const credentials = data.credentials || data;
 
       if (credentials.length === 0) {
+        // quox#920: --json always prints valid JSON, an honest empty included.
+        if (program.opts().output === 'json') { console.log('[]'); return; }
         printInfo(`No credentials expiring within ${days} days.`);
         return;
       }
@@ -1373,15 +1375,36 @@ export function registerVaultCommands(program, ctx) {
 
   vault
     .command('health')
-    .description('Lightweight vault health summary (requires QUOX_SERVICE_KEY, not a user session)')
-    .option('--org-id <orgId>', 'org ID to scope the summary to (server default: "default")')
+    .description('Vault health summary: total, healthy, failed, stale, expiring credentials')
+    .option('--org-id <orgId>', 'with QUOX_SERVICE_KEY only: org ID to scope the summary to (server default: "default")')
     .action(async (options) => {
-      const ep = resolveEndpoint('vault.health', {});
-      const data = await client.get(ep.path, {
-        service: ep.service,
-        query: options.orgId ? { org_id: options.orgId } : undefined,
-      });
-      formatDetail(data, { format: program.opts().output, title: 'QuoxVault Health' });
+      // #914: the internal route accepts only the service key, so an owner's `vault health` was a 401
+      // "invalid service key". Automation (QUOX_SERVICE_KEY) keeps that route; a signed-in person reads
+      // the same numbers from their org's vault stats.
+      if (process.env.QUOX_SERVICE_KEY) {
+        const ep = resolveEndpoint('vault.health', {});
+        const data = await client.get(ep.path, {
+          service: ep.service,
+          query: options.orgId ? { org_id: options.orgId } : undefined,
+        });
+        formatDetail(data, { format: program.opts().output, title: 'QuoxVault Health' });
+        return;
+      }
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const ep = resolveEndpoint('vault.vault-stats.list', { orgId });
+      const st = await client.get(ep.path, { service: ep.service });
+      const summary = {
+        total: st.total ?? 0,
+        healthy: st.healthy ?? 0,
+        failed: st.failed ?? 0,
+        untested: st.untested ?? 0,
+        stale: st.stale ?? 0,
+        expiring_soon: st.expiring ?? 0,
+        rotation_overdue: st.rotationOverdue ?? 0,
+        source: 'org vault stats',
+      };
+      formatDetail(summary, { format: program.opts().output, title: 'QuoxVault Health' });
     });
 
   // ── vault export (removed — WP0.2) ──────────────────────────────────────────