quoxcli 0.3.1 → 0.5.0

package/lib/commands/agent.js

@@ -8,6 +8,7 @@ import { resolveOrgId } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { QuoxApiError } from '../core/errors.js';
 import { loadBundledAssistantsRoster } from '../core/agentAlias.js';
+import { AGENT_FAMILY_IDS } from '../core/agentFamilies.js';
 import { registerAgentAttachCommands } from './agentAttach.js';
 
 // quox#1169: the prompt, domains and parent a user gives their own agent. Auth reads
@@ -64,6 +65,7 @@ export function registerAgentCommands(program, ctx) {
     .option('--level <level>', 'filter by level (0-4)')
     .option('--source <source>', 'registry | org | all', 'all')
     .option('--plugin <id>', 'only agents that require this plugin')
+    .option('--family <id>', `only agents in this family (${AGENT_FAMILY_IDS.join(', ')})`)
     .option('--search <text>', 'substring match on id, name or description')
     .action(async (options) => {
       auth.requireAuth();
@@ -71,6 +73,9 @@ export function registerAgentCommands(program, ctx) {
       if (!['registry', 'org', 'all'].includes(source)) {
         throw new Error(`--source must be registry, org or all (got "${options.source}")`);
       }
+      if (options.family !== undefined && !AGENT_FAMILY_IDS.includes(options.family)) {
+        throw new Error(`unknown family "${options.family}". Valid families: ${AGENT_FAMILY_IDS.join(', ')}`);
+      }
       const notes = [];
 
       // Registered specialists (server roster; bundled roster if the server lacks the route).
@@ -84,7 +89,7 @@ export function registerAgentCommands(program, ctx) {
         } catch (err) {
           notes.push(`note: server registry unavailable (${err.message}); showing the bundled roster, which may be out of date.`);
           registry = loadBundledAssistantsRoster().map(r => ({
-            agent_id: r.id, name: r.name || r.id, level: null, requires_plugin: null, tool_count: null, source: 'registry',
+            agent_id: r.id, name: r.name || r.id, level: null, requires_plugin: null, family: r.family || null, tool_count: null, source: 'registry',
           }));
         }
       }
@@ -113,7 +118,7 @@ export function registerAgentCommands(program, ctx) {
         const key = o.agent_id || o.id;
         const reg = merged.get(key);
         merged.set(key, reg
-          ? { ...reg, ...o, requires_plugin: reg.requires_plugin, description: reg.description ?? o.description, tool_count: o.tool_count ?? reg.tool_count, source: 'org+registry' }
+          ? { ...reg, ...o, requires_plugin: reg.requires_plugin, family: reg.family ?? null, description: reg.description ?? o.description, tool_count: o.tool_count ?? reg.tool_count, source: 'org+registry' }
           : o);
       }
 
@@ -121,6 +126,7 @@ export function registerAgentCommands(program, ctx) {
       if (options.level !== undefined) all = all.filter(r => String(r.level) === String(options.level));
       if (options.status) all = all.filter(r => r.status === options.status);
       if (options.plugin) all = all.filter(r => r.requires_plugin === options.plugin);
+      if (options.family) all = all.filter(r => r.family === options.family);
       if (options.search) {
         const q = options.search.toLowerCase();
         all = all.filter(r => [r.agent_id, r.name, r.description].some(v => String(v ?? '').toLowerCase().includes(q)));
@@ -130,10 +136,11 @@ export function registerAgentCommands(program, ctx) {
       for (const n of notes) console.error(n);
       const dash = (v) => (v === null || v === undefined || v === '' ? '-' : v);
       formatOutput({
-        columns: ['agent_id', 'name', 'source', 'level', 'state', 'tool_count'],
-        headers: ['Agent ID', 'Name', 'Source', 'Level', 'Status/Plugin', 'Tools'],
+        columns: ['agent_id', 'name', 'family', 'source', 'level', 'state', 'tool_count'],
+        headers: ['Agent ID', 'Name', 'Family', 'Source', 'Level', 'Status/Plugin', 'Tools'],
         rows: all.map(r => ({
           ...r,
+          family: dash(r.family),
           level: dash(r.level),
           state: r.status ? r.status : (r.requires_plugin ? `plugin:${r.requires_plugin}` : '-'),
           tool_count: dash(r.tool_count),

package/lib/commands/agentAttach.js

@@ -435,6 +435,38 @@ export function execResultFailed(data) {
   return negative(data.success) || negative(data.ok);
 }
 
+/**
+ * A governed tool that was held for a human returns { success:false, pending:true, approvalId }. That is not a
+ * failure: the approval is filed and waiting. Returns the approval id, or null when the result is not pending.
+ */
+export function execResultPending(data) {
+  if (!data || typeof data !== 'object') return null;
+  const src = data.pending === true ? data : (data.result && typeof data.result === 'object' && data.result.pending === true ? data.result : null);
+  if (!src) return null;
+  return src.approvalId || src.approval_id || (src._approval && src._approval.id) || 'unknown';
+}
+
+/**
+ * A governed tool held by the policy layer answers HTTP 403 with {pending:true, approvalId}: the approval IS filed.
+ * Returns that body when an API error carries one (so the caller renders awaiting approval), else null.
+ */
+export function pendingBodyOfError(err) {
+  const body = err && err.body && typeof err.body === 'object' ? err.body : null;
+  return body && execResultPending(body) ? body : null;
+}
+
+/**
+ * Is this 401/403 really about the attach token? 401 is an unauthenticated bearer. A 403 counts only when the server
+ * says so (attach/lease/token in its code or message); any other 403 is the server's own refusal and is shown verbatim.
+ */
+export function isAttachTokenError(err) {
+  const status = err && err.status;
+  if (status === 401) return true;
+  if (status !== 403) return false;
+  const text = [err && err.code, err && err.body && err.body.error, err && err.body && err.body.error_code, err && err.message].filter(Boolean).join(' ');
+  return /attach|lease|token/i.test(text);
+}
+
 /** The first human-readable error string a failed tool result carries, or a default. */
 function execResultError(data) {
   return (data && (data.error || data.error_code || data.reason || data.message)) || 'tool reported failure';
@@ -1290,6 +1322,21 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       if (program.opts().output === 'json') formatDetail(data, { format: 'json' });
     });
 
+  agent
+    .command('attaches')
+    .description('List every live agent attach in the org (agent, splinter, session, lease, heartbeat, expiry)')
+    .action(async () => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('agent-attach.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const rows = Array.isArray(data?.attaches) ? data.attaches : [];
+      if (program.opts().output === 'json') return formatDetail(data, { format: 'json' });
+      if (!rows.length) return printInfo('No live agent attaches in this org.');
+      for (const a of rows) {
+        printInfo(`${a.agent_id} ${a.splinter || 'S1'} · ${a.session_label || '(no label)'} · lease ${a.lease_id} · heartbeat ${fmtAge(a.last_heartbeat_at)} · expires ${a.expires_at || '?'}`);
+      }
+    });
+
   agent
     .command('attach-heartbeat')
     .description("Heartbeat this session's attach lease, rotating the stored token if one is issued")
@@ -1343,13 +1390,17 @@ export function registerAgentAttachCommands(agent, ctx, program) {
         });
       } catch (err) {
         const status = err instanceof QuoxApiError ? err.status : 'network error';
-        if (err instanceof QuoxApiError && (err.status === 401 || err.status === 403)) {
+        const held = err instanceof QuoxApiError ? pendingBodyOfError(err) : null;
+        if (held) {
+          data = held; // the policy layer filed an approval: that is a result, not an error
+        } else if (err instanceof QuoxApiError && isAttachTokenError(err)) {
           throw new Error(
             `POST ${ep.path} failed (${status}): the attach token for "${agentId}" is no longer valid `
             + `(expired or revoked lease). Re-attach with \`quox agent attach ${agentId}\`.`
           );
+        } else {
+          throw new Error(`POST ${ep.path} failed (${status}): ${err.message}`);
         }
-        throw new Error(`POST ${ep.path} failed (${status}): ${err.message}`);
       }
 
       // finding (autonomous loop): the glyph must reflect the TOOL result, not
@@ -1358,14 +1409,17 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       // agent read failures as passes ([error-body-is-not-data] at the CLI
       // surface). Set a non-zero exit code too so a scripted / feedback-loop
       // caller can't mistake it for a pass.
-      const toolOk = !execResultFailed(data);
+      const pendingId = execResultPending(data);
+      const toolOk = pendingId ? true : !execResultFailed(data);
       // Skip the announce line under --json/-o json: a scripted caller parses
       // stdout as a single JSON document, and the glyph line would break that.
       if (program.opts().output !== 'json') {
-        printEvent(line('quox', `exec ${options.tool}`, {
-          result: toolOk ? agentId : `${agentId} · ${execResultError(data)}`,
-          status: toolOk ? 'ok' : 'fail',
-        }));
+        printEvent(line('quox', `exec ${options.tool}`, pendingId
+          ? { result: `${agentId} · awaiting approval ${pendingId}`, status: 'busy' }
+          : {
+            result: toolOk ? agentId : `${agentId} · ${execResultError(data)}`,
+            status: toolOk ? 'ok' : 'fail',
+          }));
       }
       formatDetail(data, { format: program.opts().output, title: `Tool result: ${options.tool}` });
       if (!toolOk) process.exitCode = 1;

package/lib/commands/approvals.js

@@ -8,9 +8,23 @@
 import { resolveEndpoint } from '../api/endpoints.js';
 
 import { attachWalkthrough } from './walkthrough.js';
+import { resolveOrgId } from './helpers.js';
+import { confirmInteractive, askTyped } from '../core/confirm.js';
+import { QuoxUserError } from '../core/errors.js';
+import { announce, announceFailure, announceOnFail } from '../core/announce.js';
+import { withStepUp } from '../core/stepUpPrompt.js';
+import { formatOutput, printSuccess } from '../core/output.js';
+import { needsPin } from '../quoxon/approvalsView.js';
+import { describeInboxItem, approvalSourceLabel } from '../quoxon/events.js';
+import { runCallMe, statusLines } from '../core/callMe.js';
+import { isDestructive, destructiveObject } from '../quoxon/destructive.js';
+import { otherOrgsWaiting, crossOrgLines, clientForTarget } from '../core/crossOrgApprovals.js';
 
 export function registerApprovalsCommands(program, ctx) {
-  const { client, auth } = ctx;
+  const { client: baseClient, auth, clientForOrg } = ctx;
+  // The client for the org a verb targets: --org another org (a verb in CROSS_ORG, see core/org-override.js) uses that org's own token.
+  const clientFor = (orgId) => clientForTarget({ client: baseClient, clientForOrg, sessionOrgId: auth.getOrgId(), orgId });
+  const client = baseClient; // `result`, grants and the rest stay on the session org
 
   const approvals = program
     .command('approvals')
@@ -34,6 +48,15 @@ export function registerApprovalsCommands(program, ctx) {
       }
       console.log(`Approval ${data.approval_id}  tool: ${data.tool}  status: ${data.status}`
         + (data.executed_at ? `  executed: ${data.executed_at}` : ''));
+      if (data.decided_by) {
+        const who = data.decided_by.name || data.decided_by.id;
+        const via = data.decided_via && data.decided_via.channel ? ` via ${data.decided_via.channel}` : '';
+        console.log(`decided by ${who} (${data.decided_by.actor_type || 'user'})${via} at ${data.decided_at || 'unknown time'}`);
+      }
+      if (data.human_decision) {
+        const hd = { yes: 'yes (a person approved it with a verified step-up PIN)', no: 'no (not human-verified: denied, withdrawn, expired, approved by an agent, or approved without a verified PIN)', pending: 'pending' }[data.human_decision] || data.human_decision;
+        console.log(`human decision: ${hd}`);
+      }
       if (data.result === null || data.result === undefined) {
         if (data.status === 'pending') console.log('Still pending: a human has not decided yet.');
         else if (data.status === 'resuming') console.log('Approved, executing. Re-run shortly.');
@@ -48,6 +71,26 @@ export function registerApprovalsCommands(program, ctx) {
       else console.log(JSON.stringify(r, null, 2));
     });
 
+  // Call-me: the switch for the ApprovalsQ watcher that phones a human when a high-risk
+  // approval sits unanswered. It never approves anything; the call only asks the human.
+  approvals
+    .command('call-me [action]')
+    .description('Phone me when a high-risk approval sits unanswered: status (default), on or off (human org admin only)')
+    .option('--after <minutes>', 'ring after this many minutes unanswered (1-1440)')
+    .option('--quiet <HH:MM-HH:MM>', 'quiet hours, no calls in this window (e.g. 22:00-08:00)')
+    .action(announceOnFail('quox', 'approvals call-me', async (action, options) => {
+      auth.requireAuth();
+      const act = action || 'status';
+      if (act === 'status' && (options.after || options.quiet)) {
+        throw new QuoxUserError('--after and --quiet change the policy: use `quox approvals call-me on --after 10` (or off).', { code: 'bad_args' });
+      }
+      const { data, changed } = await runCallMe(client, { action: act, after: options.after, quiet: options.quiet });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const p = (data && data.policy) || {};
+      announce('quox', 'approvals call-me', { result: `${changed ? 'set ' : ''}${p.enabled ? `ON after ${p.age_threshold_minutes} min` : 'OFF'}` });
+      for (const l of statusLines(data)) console.log(l);
+    }));
+
   // Fleet standing grants: an org admin pre-approves ONE host + an anchored command
   // shape + a VMID range until an expiry, for ssh_exec. Every use still lands in
   // approvals history with an AEE envelope; anything outside the grant files HITL.
@@ -56,7 +99,7 @@ export function registerApprovalsCommands(program, ctx) {
     .description('Standing grants: org-admin pre-approved fleet command lanes (ssh_exec)');
 
   grants
-    .command('list')
+    .command('list', { isDefault: true })
     .description('List active standing grants (--all includes revoked and expired)')
     .option('--all', 'include revoked and expired grants')
     .action(async (options) => {
@@ -69,7 +112,7 @@ export function registerApprovalsCommands(program, ctx) {
       for (const g of rows) {
         const state = g.revoked_at ? `revoked ${g.revoked_at}` : `expires ${g.expires_at}`;
         const range = g.vmid_min != null ? `  vmids ${g.vmid_min}-${g.vmid_max}` : '';
-        console.log(`${g.grant_id}  ${g.tool}@${g.host}${range}  ${g.preset || `${g.patterns.length} patterns`}  uses ${g.use_count}  ${state}`);
+        console.log(`${g.tool} on ${g.host}${range}  ${g.preset || `${(g.patterns || []).length} patterns`}  uses ${g.use_count}  ${state}  [${g.grant_id}]`);
         console.log(`  reason: ${g.reason}  (by ${g.created_by})`);
       }
     });
@@ -102,6 +145,7 @@ export function registerApprovalsCommands(program, ctx) {
       const data = await client.post(ep.path, { service: ep.service, body });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
       const g = data.grant || {};
+      announce('approvals', `grant created ${g.tool || 'ssh_exec'}@${g.host || options.host}`, { result: g.grant_id });
       console.log(`Created ${g.grant_id}: ${g.tool}@${g.host}${g.vmid_min != null ? ` vmids ${g.vmid_min}-${g.vmid_max}` : ''}, expires ${g.expires_at}`);
       console.log(`Revoke any time: quox approvals grants revoke ${g.grant_id}`);
     });
@@ -114,6 +158,157 @@ export function registerApprovalsCommands(program, ctx) {
       const ep = resolveEndpoint('v1.approvals.grants.revoke', { id: grantId });
       const data = await client.post(ep.path, { service: ep.service, body: {} });
       if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      announce('approvals', `grant revoked ${grantId}`);
       console.log(`Revoked ${data.grant?.grant_id || grantId} at ${data.grant?.revoked_at || 'now'}.`);
     });
+
+  // ---- list | approve | deny: the verb people expect, over the SAME server path as `quox inbox respond`.
+  const OPEN_QUERY = { status: 'open', kind: 'approval', limit: 200 };
+  const listOpen = async (orgId, status, cl = client) => {
+    const ep = resolveEndpoint('inbox.list', { orgId });
+    const data = await cl.get(ep.path, { service: ep.service, query: { ...OPEN_QUERY, ...(status ? { status } : {}) } });
+    const items = (data && (data.items || data)) || [];
+    return Array.isArray(items) ? items : [];
+  };
+  const shortId = (id) => String(id).slice(-6);
+
+  async function pickApproval(orgId, given, cl = client) {
+    const want = String(given).trim().toUpperCase();
+    const items = await listOpen(orgId, undefined, cl);
+    const hits = items.filter((it) => {
+      const id = String(it.id).toUpperCase();
+      return id === want || id.endsWith(want) || String(it.aee_correlation_id || '').toUpperCase() === want;
+    });
+    const exact = hits.filter((it) => String(it.id).toUpperCase() === want);
+    if (exact.length === 1) return exact[0];
+    if (hits.length === 1) return hits[0];
+    if (hits.length > 1) {
+      throw new QuoxUserError(`"${given}" is ambiguous: it matches ${hits.length} open approvals (${hits.map((h) => shortId(h.id)).join(', ')}).`, {
+        next: 'use more of the id, or the full id from `quox approvals list`.', exitCode: 2, code: 'ambiguous_id',
+      });
+    }
+    throw new QuoxUserError(`No open approval matches "${given}" in this org.`, {
+      next: '`quox approvals list` shows what is waiting; `quox inbox get <id>` finds an answered one.', exitCode: 5, code: 'not_found',
+    });
+  }
+
+  function summaryLine(it) {
+    const d = describeInboxItem(it);
+    const what = [d.tool, d.target && d.target !== d.tool ? d.target : null].filter(Boolean).join(' on ') || d.title || it.title || it.id;
+    const who = d.by || approvalSourceLabel(it);
+    return `[${shortId(it.id)}] ${what}  (asked by ${who})`;
+  }
+
+  async function decide(verb, given, options) {
+    auth.requireAuth();
+    const orgId = resolveOrgId(auth, program);
+    const client = await clientFor(orgId); // another org only when --org names one
+    const it = await pickApproval(orgId, given, client);
+    const approve = verb === 'approve';
+    console.log(`${approve ? 'Approve' : 'Deny'}: ${summaryLine(it)}`);
+    if (approve) {
+      if (needsPin(it)) {
+        throw new QuoxUserError('High risk: a yes needs your step-up PIN, which a plain command cannot take.', {
+          next: 'answer it in `quox` with /approvals, or deny it here with `quox approvals deny`.', exitCode: 4, code: 'step_up_required',
+        });
+      }
+      if (isDestructive(it)) {
+        const { name } = destructiveObject(it);
+        if (!process.stdin.isTTY) {
+          throw new QuoxUserError(`This deletes "${name}": its name must be typed at a terminal. --yes does not cover it.`, {
+            next: 'run this command in an interactive terminal.', exitCode: 2, code: 'no_terminal',
+          });
+        }
+        const typed = await askTyped(`This is destructive. Type "${name}" to approve`);
+        if (String(typed ?? '').trim() !== name) {
+          throw new QuoxUserError(`What you typed did not match "${name}". Nothing was approved.`, { exitCode: 1, code: 'confirm_mismatch' });
+        }
+      } else if (!options.yes) {
+        const ok = await confirmInteractive('Approve this?', { flag: '--yes', purpose: 'approve' });
+        if (!ok) { console.log('Not approved. The request stays open.'); return; }
+      }
+    }
+    const ep = resolveEndpoint('inbox.respond', { orgId, itemId: it.id });
+    try {
+      const body = { action: approve ? 'approve' : 'reject', ...(options.note ? { comment: options.note } : {}) };
+      // DS-010 / #1335: only an approve can hit a step-up sink; ask for the PIN (hidden, TTY only) and retry once.
+      if (approve) await withStepUp((headers) => client.post(ep.path, { service: ep.service, headers, body }), { client, orgId, io: ctx.stepUpIO, what: 'This approval' });
+      else await client.post(ep.path, { service: ep.service, body });
+    } catch (err) {
+      announceFailure('approvals', `${approve ? 'approve' : 'deny'} ${shortId(it.id)}`, err);
+      if (err && (err.status === 403 || err.status === 401) && !(err instanceof QuoxUserError)) {
+        const msg = err.body?.message || err.body?.error || err.message;
+        const denied = new QuoxUserError(String(msg), { exitCode: 4, code: err.body?.error || 'forbidden', status: err.status, body: err.body });
+        Object.defineProperty(denied, 'quoxAnnounced', { value: true });
+        throw denied;
+      }
+      throw err;
+    }
+    announce('approvals', `${approve ? 'approved' : 'denied'} ${shortId(it.id)}`, { result: summaryLine(it).replace(/^\[\w+\]\s*/, '').replace(/\s+\(asked by .*$/, '') });
+    printSuccess(`${approve ? 'Approved' : 'Denied'} ${shortId(it.id)}.`);
+  }
+
+  approvals
+    .command('list')
+    .description('List approvals waiting for a human (same call as `quox inbox list`, approvals only)')
+    .option('--status <status>', 'open (default), all, or a status list')
+    .option('--limit <n>', 'max results', '50')
+    .action(async (options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      const cl = await clientFor(orgId);
+      const ep = resolveEndpoint('inbox.list', { orgId });
+      const data = await cl.get(ep.path, { service: ep.service, query: { ...OPEN_QUERY, limit: options.limit, ...(options.status ? { status: options.status } : {}) } });
+      const items = ((data && (data.items || data)) || []).map((it) => ({ ...it, short: shortId(it.id), what: summaryLine(it).replace(/^\[\w+\]\s*/, '') }));
+      formatOutput({
+        columns: ['short', 'what', 'status', 'created_at', 'id'],
+        headers: ['ID', 'What', 'Status', 'Created', 'Full id'],
+        rows: items,
+      }, { format: program.opts().output, emptyMessage: 'No approvals are waiting.' });
+      // Waiting in the user's OTHER orgs: a count and the exact command, table output only (json stays pure data).
+      if (program.opts().output === 'table' || !program.opts().output) {
+        for (const l of crossOrgLines(await otherOrgsWaiting({ client: baseClient, currentOrgId: orgId }))) console.log(l);
+      }
+    });
+
+  approvals
+    .command('approve <id>')
+    .description('Approve one waiting request by id (full id or the short tail on its card). A high-risk yes needs a PIN, so use `quox`.')
+    .option('--note <text>', 'a note recorded with the decision')
+    .option('-y, --yes', 'skip the y/N question (not a destructive delete, which needs its name typed)')
+    .addHelpText('after', '\nExamples:\n  quox approvals list\n  quox approvals approve D05HQY\n  quox approvals approve D05HQY --yes --note "checked the host"\n')
+    .action(announceOnFail('approvals', (id) => `approve ${id}`, (id, options) => decide('approve', id, options)));
+
+  approvals
+    .command('deny <id>')
+    .description('Deny one waiting request by id (full id or the short tail on its card)')
+    .option('--note <text>', 'why, recorded with the decision')
+    .addHelpText('after', '\nExamples:\n  quox approvals deny FJ340S --note "wrong host"\n')
+    .action(announceOnFail('approvals', (id) => `deny ${id}`, (id, options) => decide('deny', id, options)));
+
+  approvals
+    .command('withdraw <id>')
+    .description('Take back an approval request YOU raised (full id). It is marked withdrawn, never denied; the held call cannot run; only the identity that raised it may do this')
+    .option('--note <text>', 'why, recorded with the withdrawal')
+    .addHelpText('after', '\nExamples:\n  quox approvals withdraw 01KXYZ... --note "raised by mistake"\n')
+    .action(announceOnFail('approvals', (id) => `withdraw ${id}`, async (given, options) => {
+      auth.requireAuth();
+      const orgId = resolveOrgId(auth, program);
+      // The full item id or approval id goes straight to the server, which checks you are the requester. A short tail is
+      // looked up among the open approvals you can see; one you cannot see is not yours to withdraw by tail.
+      let id = String(given).trim();
+      if (id.length < 20) { const it = await pickApproval(orgId, id); id = it.id; }
+      const ep = resolveEndpoint('inbox.withdraw', { orgId, itemId: id });
+      try {
+        await client.post(ep.path, { service: ep.service, body: { ...(options.note ? { reason: options.note } : {}) } });
+      } catch (err) {
+        if (err && (err.status === 403 || err.status === 404 || err.status === 400) && !(err instanceof QuoxUserError)) {
+          const msg = err.body?.message || err.body?.error || err.message;
+          throw new QuoxUserError(String(msg), { exitCode: err.status === 403 ? 4 : 5, code: err.body?.error || 'withdraw_refused', status: err.status, body: err.body });
+        }
+        throw err;
+      }
+      announce('approvals', `withdrew ${shortId(id)}`, { result: 'withdrawn, nothing ran' });
+      printSuccess(`Withdrew ${shortId(id)}. It is marked withdrawn and cannot run.`);
+    }));
 }

package/lib/commands/ask.js

@@ -96,6 +96,7 @@ export function registerAskCommands(program, { client, auth }) {
     .option('--paths <files...>', 'every test file the commit edits (absolute, worktree or repo-relative: all are normalised)')
     .option('--justify <text>', 'why it is safe, in plain words (required)')
     .option('--why <text>', 'detail: the findings, before and after lines')
+    .option('--recommend <y|n>', 'your advice for the card: y or n (shown as the recommendation)')
     .option('--session <name>', 'which session is asking (default: $QUOX_SESSION)')
     .option('--slot <name>', 'your slot')
     .option('--expires <dur>', 'how long it stays open')
@@ -105,6 +106,7 @@ export function registerAskCommands(program, { client, auth }) {
       // commander lets the parent `ask` swallow flags it shares with this verb (--justify, --why, --session...), so merge both
       const options = { ...ask.opts(), ...Object.fromEntries(Object.entries(subOptions).filter(([, v]) => v !== undefined)) };
       if (!String(options.justify || '').trim()) { err('say why it is safe: --justify "<plain words>"'); process.exitCode = 2; return; }
+      if (!options.recommend) err('tip: add --recommend y|n so the card shows your advice');
       const raw = [].concat(options.paths || []).flatMap((x) => String(x).split(',')).map((x) => x.trim()).filter(Boolean);
       let root;
       try { root = execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' }).trim(); } catch { root = process.cwd(); }
@@ -114,7 +116,7 @@ export function registerAskCommands(program, { client, auth }) {
       // 2026-10-19: the server truncates long titles, and the attestation names only paths found in title+body,
       // so a 7-file ask covered 3. Every path also goes in the body.
       const files = `Files (${paths.length}):\n${paths.map((p) => `- ${p}`).join('\n')}`;
-      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify });
+      await fileAsk({ ...options, title: `Approve test edits: ${paths.join(' ')}`, why: options.why ? `${files}\n\n${options.why}` : files, yn: true, highRisk: true, justify: options.justify, recommend: options.recommend });
     });
 
   ask
@@ -128,7 +130,7 @@ export function registerAskCommands(program, { client, auth }) {
       const d = (await client.get(ep.path, { service: ep.service })).decision;
       if (program.opts().output === 'json') { console.log(JSON.stringify(d, null, 2)); return; }
       console.log(`${d.state}${d.answer?.option ? ` ${d.answer.option}` : ''}${d.answer?.note ? ` (${d.answer.note})` : ''}`);
-      if (d.state === 'expired' || d.state === 'denied') process.exitCode = EXIT_NO_ANSWER;
+      if (d.state === 'expired' || d.state === 'denied' || d.state === 'withdrawn') process.exitCode = EXIT_NO_ANSWER;
     });
 
   ask

package/lib/commands/auth.js

@@ -7,7 +7,19 @@ import { formatDetail, printSuccess, printInfo } from '../core/output.js';
 import { resolveEndpoint } from '../api/endpoints.js';
 import { loadResidentProfile, residentLogin, resolveResidentBaseUrl } from '../core/residentAuth.js';
 import { readStoredKit, resolveMyAttach, sessionKey, myAttachState } from './agentAttach.js';
+import { loginPrefillEmail, profileHoldingEmail, isNonDefaultProfile, sameIdentityWarning } from '../core/loginGuard.js';
 import { resolveActing } from '../core/actingAs.js';
+import { QuoxUserError } from '../core/errors.js';
+
+const PASSWORD_POLICY_HINT = 'Password policy: at least 12 characters, with an upper-case letter, a lower-case letter, a digit and a symbol.';
+
+/** whoami line for "-p/--profile given": say which agent is acting when the profile is an agent identity. */
+export function profileActingLine({ actorType, profile, user }) {
+  if (actorType === 'agent') {
+    return `  Acting as agent ${user || 'unknown'} via profile ${profile || 'unknown'} (-p/--profile given)`;
+  }
+  return '  Acting as yourself (-p/--profile given)';
+}
 
 export function registerAuthCommands(program, ctx) {
   const { config, auth, client } = ctx;
@@ -122,6 +134,7 @@ export function registerAuthCommands(program, ctx) {
             type: 'input',
             name: 'email',
             message: 'Email:',
+            default: loginPrefillEmail(config) || undefined,
             validate: v => v.includes('@') || 'Please enter a valid email',
           }]);
           email = ans.email;
@@ -138,6 +151,21 @@ export function registerAuthCommands(program, ctx) {
         }
       }
 
+      // Stop agent-only profiles quietly becoming another profile's (the owner's) identity.
+      if (isNonDefaultProfile(config)) {
+        const holder = profileHoldingEmail(config, email, config.getActiveProfile?.()?.url || null);
+        if (holder) {
+          const msg = sameIdentityWarning(email, holder, config.getActiveProfileName());
+          if (!process.stdin.isTTY) {
+            console.error(`Error: ${msg}\nRefusing in a non-interactive shell. Use the profile's own account, or run interactively and answer y.`);
+            process.exit(1);
+          }
+          const { default: inquirer } = await import('inquirer');
+          const ans = await inquirer.prompt([{ type: 'confirm', name: 'ok', message: msg.replace(/ y\/N$/, ''), default: false }]);
+          if (!ans.ok) { printInfo('Cancelled. Nothing was sent.'); return; }
+        }
+      }
+
       const baseUrl = config.getServiceUrl('auth');
       const ora = (await import('ora')).default;
       const spinner = ora('Authenticating...').start();
@@ -196,6 +224,7 @@ export function registerAuthCommands(program, ctx) {
   program
     .command('whoami')
     .description('Show current user and session info')
+    .addHelpText('after', '\nAdd --json for machine output (user, email, org, role, mfa, session, profile, actor_type, host_id).')
     .action(async () => {
       auth.requireAuth();
       const data = await client.get(resolveEndpoint('auth.me.list').path, { service: resolveEndpoint('auth.me.list').service });
@@ -309,7 +338,7 @@ export function registerAuthCommands(program, ctx) {
         } else if (acting.source === 'self') {
           printInfo('  Acting as yourself (--as self)');
         } else if (acting.source === 'profile') {
-          printInfo('  Acting as yourself (-p/--profile given)');
+          printInfo(profileActingLine({ actorType, profile: info.profile, user: info.user }));
         } else if (myAttachState().state === 'ambiguous') {
           printInfo('  Acting as yourself: this session has more than one attach (ambiguous), so no agent default applies. Pick one with --as <agent>.');
         }
@@ -337,18 +366,42 @@ export function registerAuthCommands(program, ctx) {
     .command('signup')
     .description('Create a new user account')
     .requiredOption('--email <email>', 'email address')
-    .requiredOption('--password <password>', 'password')
+    .option('--password <password>', 'password (prefer --password-stdin: argv is visible in process lists)')
+    .option('--password-stdin', 'read the password from stdin (one line), no secret in argv or shell history')
     .requiredOption('--name <name>', 'display name')
     .action(async (options) => {
-      const data = await client.post(resolveEndpoint('auth.signup').path, {
-        service: resolveEndpoint('auth.signup').service,
-        body: {
-          email: options.email,
-          password: options.password,
-          display_name: options.name,
-        },
-        noAuth: true,
-      });
+      let password = options.password;
+      if (!password && options.passwordStdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        password = Buffer.concat(chunks).toString('utf8').split('\n')[0].trim();
+        if (!password) throw new QuoxUserError('--password-stdin given but stdin was empty', { next: 'Pipe the password in, for example: printf %s "$PW" | quox signup --password-stdin ...' });
+      } else if (password) {
+        console.error('Warning: argv is visible to other users (process list) and lands in shell history, so a password given with --password is exposed. Prefer --password-stdin.');
+      }
+      if (!password) {
+        throw new QuoxUserError('A password is required. Use --password-stdin (reads one line from stdin) or --password <password>.');
+      }
+      const ep = resolveEndpoint('auth.signup');
+      try {
+        await client.post(ep.path, {
+          service: ep.service,
+          body: { email: options.email, password, display_name: options.name },
+          noAuth: true,
+        });
+      } catch (err) {
+        if (err?.status === 400 && err?.code === 'validation_error') {
+          const reason = err.body?.message || err.message;
+          const list = Array.isArray(err.body?.errors) ? err.body.errors.filter((e) => typeof e === 'string' && e !== reason) : [];
+          const detail = [reason, ...list].join('; ');
+          const aboutPassword = /password/i.test(detail);
+          throw new QuoxUserError(`Signup was rejected: ${detail}`, {
+            next: aboutPassword ? PASSWORD_POLICY_HINT : null,
+            code: 'validation_error', status: 400, body: err.body,
+          });
+        }
+        throw err;
+      }
       printSuccess(`Account created for ${options.email}. Check your email for verification.`);
     });
 

package/lib/commands/backup.js

@@ -37,12 +37,19 @@ export function registerBackupCommands(program, ctx) {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
       const data = await client.get(resolveEndpoint('backups.list', { orgId }).path, { service: resolveEndpoint('backups.list', { orgId }).service, query: { limit: options.limit } });
+      const items = data.items || data.backups || data;
+      // Name leads (ids are for scripting: --json, -q). A failed row says why, clipped.
+      const clip = (t, n = 60) => { const x = String(t).replace(/\s+/g, ' ').trim(); return x.length > n ? `${x.slice(0, n - 1)}…` : x; };
+      const rows = (Array.isArray(items) ? items : []).map((b) => ({
+        ...b,
+        status: b.status === 'failed' && b.error_message ? `failed: ${clip(b.error_message)}` : b.status,
+      }));
       formatOutput({
         // fleet #392: backups has name/backup_type/archive_size_bytes.
-        columns: ['id', 'name', 'backup_type', 'archive_size_bytes', 'status', 'created_at'],
-        headers: ['ID', 'Name', 'Type', 'Size (bytes)', 'Status', 'Created'],
-        rows: data.items || data.backups || data,
-      }, { format: program.opts().output });
+        columns: ['name', 'backup_type', 'archive_size_bytes', 'status', 'created_at', 'id'],
+        headers: ['Name', 'Type', 'Size (bytes)', 'Status', 'Created', 'ID'],
+        rows,
+      }, { format: program.opts().output, raw: Array.isArray(items) ? items : undefined, quietColumn: 'id' });
     });
 
   backup