quoxcli 0.2.0 → 0.4.0

package/lib/commands/agent.js

@@ -2,41 +2,150 @@
  * Agent commands: CRUD, activate/deactivate, tool assignments
  */
 
+import { readFileSync } from 'node:fs';
 import { formatOutput, formatDetail, printSuccess } from '../core/output.js';
 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
+// system_prompt_additions, domains[] and parent_agent_id; it has never read manifest_id.
+function agentPromptFields(options) {
+  if (options.prompt !== undefined && options.promptFile !== undefined) {
+    throw new Error('Give either --prompt or --prompt-file, not both. Nothing was sent.');
+  }
+  if (options.manifestId !== undefined) {
+    throw new Error('--manifest-id is not supported by the server (it was always ignored). Nothing was sent.');
+  }
+  const out = {};
+  if (options.prompt !== undefined) out.system_prompt_additions = String(options.prompt);
+  if (options.promptFile !== undefined) {
+    try {
+      out.system_prompt_additions = readFileSync(options.promptFile, 'utf8');
+    } catch (err) {
+      throw new Error(`cannot read --prompt-file ${options.promptFile}: ${err.code || err.message}. Nothing was sent.`);
+    }
+  }
+  if (options.domain !== undefined) out.domains = String(options.domain).split(',').map((d) => d.trim()).filter(Boolean);
+  if (options.parent !== undefined) out.parent_agent_id = options.parent;
+  return out;
+}
+
 export function registerAgentCommands(program, ctx) {
   const { client, auth } = ctx;
 
+  // Registered specialists (no org row): resolved from the collector registry, quox#927.
+  async function registryAgent(agentId) {
+    try {
+      const ep = resolveEndpoint('v1.agents.registry');
+      const data = await client.get(ep.path, { service: ep.service });
+      return (data?.agents || []).find((r) => r.agent_id === agentId) || null;
+    } catch { return null; }
+  }
+  async function registryGrants(agentId) {
+    try {
+      const ep = resolveEndpoint('v1.tools.agents.list');
+      const data = await client.get(ep.path, { service: ep.service });
+      const list = data?.agentTools?.[agentId];
+      return Array.isArray(list) ? list : null;
+    } catch { return null; }
+  }
+
   const agent = program
     .command('agent')
     .description('Manage agents');
 
   agent
     .command('list')
-    .description('List agents')
-    .option('--status <status>', 'filter by status')
+    .description('List registered specialist agents and the org\'s own agents')
+    .option('--status <status>', 'filter by status (org agents only)')
     .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();
-      const orgId = resolveOrgId(auth, program);
-      const query = {};
-      if (options.status) query.status = options.status;
-      if (options.level) query.level = options.level;
-      // fleet #392: tool_count is only computed when includeTools=true, which
-      // was never sent; and rows carry a `domains` ARRAY, not a `domain`.
-      query.includeTools = 'true';
-      const data = await client.get(resolveEndpoint('agents.list', { orgId }).path, { service: resolveEndpoint('agents.list', { orgId }).service, query });
+      const source = String(options.source || 'all').toLowerCase();
+      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).
+      let registry = [];
+      if (source !== 'org') {
+        try {
+          const ep = resolveEndpoint('v1.agents.registry');
+          const data = await client.get(ep.path, { service: ep.service });
+          if (!Array.isArray(data?.agents)) throw new Error('unexpected response');
+          registry = data.agents.map(r => ({ ...r, source: 'registry' }));
+        } 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, family: r.family || null, tool_count: null, source: 'registry',
+          }));
+        }
+      }
+
+      // The org's own agent rows.
+      let orgRows = [];
+      if (source !== 'registry') {
+        try {
+          const orgId = resolveOrgId(auth, program);
+          const query = { includeTools: 'true' };
+          if (options.status) query.status = options.status;
+          if (options.level) query.level = options.level;
+          const ep = resolveEndpoint('agents.list', { orgId });
+          const data = await client.get(ep.path, { service: ep.service, query });
+          orgRows = (data.agents || data || []).map(r => ({ ...r, source: 'org' }));
+        } catch (err) {
+          if (source === 'org') throw err;
+          notes.push(`note: org agents unavailable (${err.message}); showing registered specialists only.`);
+        }
+      }
+
+      // Merge by agent_id: org row wins for status, registry supplies plugin/description.
+      const merged = new Map();
+      for (const r of registry) merged.set(r.agent_id, r);
+      for (const o of orgRows) {
+        const key = o.agent_id || o.id;
+        const reg = merged.get(key);
+        merged.set(key, reg
+          ? { ...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);
+      }
+
+      let all = [...merged.values()];
+      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)));
+      }
+      all.sort((x, y) => String(x.agent_id).localeCompare(String(y.agent_id)));
+
+      for (const n of notes) console.error(n);
+      const dash = (v) => (v === null || v === undefined || v === '' ? '-' : v);
       formatOutput({
-        columns: ['id', 'agent_id', 'name', 'level', 'status', 'domains', 'tool_count'],
-        headers: ['ID', 'Agent ID', 'Name', 'Level', 'Status', 'Domains', 'Tools'],
-        rows: (data.agents || data || []).map(a => ({
-          ...a,
-          domains: Array.isArray(a.domains) ? a.domains.join(', ') : (a.domains ?? '-'),
+        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),
         })),
-      }, { format: program.opts().output });
+      }, { format: program.opts().output, raw: all, emptyMessage: 'No agents match.' });
     });
 
   agent
@@ -46,7 +155,16 @@ export function registerAgentCommands(program, ctx) {
     .action(async (agentId) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const data = await client.get(resolveEndpoint('agents.get', { orgId, agentId }).path, { service: resolveEndpoint('agents.get', { orgId, agentId }).service });
+      let data;
+      try {
+        data = await client.get(resolveEndpoint('agents.get', { orgId, agentId }).path, { service: resolveEndpoint('agents.get', { orgId, agentId }).service });
+      } catch (err) {
+        // quox#927: `agent list` also shows registered specialists that have no org row;
+        // resolve those from the registry instead of answering 404 for an id list printed.
+        const reg = err?.status === 404 ? await registryAgent(agentId) : null;
+        if (!reg) throw err;
+        data = { agent: { ...reg, source: 'registry' } };
+      }
       formatDetail(data.agent || data, {
         format: program.opts().output,
         title: data.agent?.name || data.name,
@@ -62,19 +180,22 @@ export function registerAgentCommands(program, ctx) {
     .option('--domain <domain>', 'agent domain')
     .option('--description <desc>', 'description')
     .option('--parent <parentId>', 'parent agent ID')
-    .option('--manifest-id <id>', 'manifest ID')
+    .option('--manifest-id <id>', 'not supported: refused (the server never read it)')
+    .option('--prompt <text>', "the agent's instructions (its system prompt)")
+    .option('--prompt-file <path>', "read the agent's instructions from a file")
     .action(async (options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
+      const fields = agentPromptFields(options);
       const body = {
         name: options.name,
         level: parseInt(options.level, 10),
+        ...fields,
       };
       if (options.agentId) body.agent_id = options.agentId;
+      // legacy key kept so older servers and tests see it; auth reads domains[] (set above)
       if (options.domain) body.domain = options.domain;
       if (options.description) body.description = options.description;
-      if (options.parent) body.parent_id = options.parent;
-      if (options.manifestId) body.manifest_id = options.manifestId;
       await client.post(resolveEndpoint('agents.create', { orgId }).path, { service: resolveEndpoint('agents.create', { orgId }).service, body });
       printSuccess(`Agent "${options.name}" created.`);
     });
@@ -87,10 +208,14 @@ export function registerAgentCommands(program, ctx) {
     .option('--description <desc>', 'new description')
     .option('--level <level>', 'new level')
     .option('--status <status>', 'new status')
+    .option('--prompt <text>', "new instructions (system prompt)")
+    .option('--prompt-file <path>', 'read new instructions from a file')
+    .option('--domain <domains>', 'comma-separated domains')
+    .option('--parent <parentId>', 'parent agent ID')
     .action(async (agentId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const body = {};
+      const body = { ...agentPromptFields(options) };
       if (options.name) body.name = options.name;
       if (options.description) body.description = options.description;
       if (options.level) body.level = parseInt(options.level, 10);
@@ -133,7 +258,7 @@ export function registerAgentCommands(program, ctx) {
       const orgId = resolveOrgId(auth, program);
       await client.patch(resolveEndpoint('agents.update', { orgId, agentId }).path, {
         service: resolveEndpoint('agents.update', { orgId, agentId }).service,
-        body: { status: 'inactive' },
+        body: { status: 'paused' }, // #985: auth accepts draft|active|paused|retired; 'inactive' 400'd
       });
       printSuccess('Agent deactivated.');
     });
@@ -150,7 +275,15 @@ export function registerAgentCommands(program, ctx) {
     .action(async (agentId) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      const data = await client.get(resolveEndpoint('agents.tools.list', { orgId, agentId }).path, { service: resolveEndpoint('agents.tools.list', { orgId, agentId }).service });
+      let data;
+      try {
+        data = await client.get(resolveEndpoint('agents.tools.list', { orgId, agentId }).path, { service: resolveEndpoint('agents.tools.list', { orgId, agentId }).service });
+      } catch (err) {
+        // quox#927: a registered specialist's tools are its registry grants, not org assignments.
+        const grants = err?.status === 404 ? await registryGrants(agentId) : null;
+        if (!grants) throw err;
+        data = { tools: grants.map((name) => ({ tool_id: name, tool_name: name, category: '-', access_mode: 'registry grant', enabled: true })) };
+      }
       formatOutput({
         // fleet #392: assignment rows carry tool_name/category/enabled.
         columns: ['tool_id', 'tool_name', 'category', 'access_mode', 'enabled'],
@@ -168,10 +301,20 @@ export function registerAgentCommands(program, ctx) {
     .action(async (agentId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      await client.post(resolveEndpoint('agents.tools.create', { orgId, agentId }).path, {
-        service: resolveEndpoint('agents.tools.create', { orgId, agentId }).service,
-        body: { tool_id: options.tool, access_mode: options.accessMode },
-      });
+      try {
+        await client.post(resolveEndpoint('agents.tools.create', { orgId, agentId }).path, {
+          service: resolveEndpoint('agents.tools.create', { orgId, agentId }).service,
+          body: { tool_id: options.tool, access_mode: options.accessMode },
+        });
+      } catch (err) {
+        // quox#1072: a built-in agent's tools come from its registry grant and
+        // hat. The server says so in prose; surface that sentence as the error
+        // with a stable code, so it does not read as a generic conflict.
+        if (err?.status === 409 && err.body?.code === 'BUILTIN_AGENT_TOOLS_FROM_GRANT') {
+          throw new QuoxApiError(409, err.body.code, err.body.message || err.body.error, undefined, err.body);
+        }
+        throw err;
+      }
       printSuccess(`Tool assigned to agent.`);
     });
 

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';
@@ -699,6 +731,36 @@ export async function heartbeatAttachLease(client, agentId, { getOrgId } = {}) {
   return { leaseId, expires: newExpiry || 'unchanged' };
 }
 
+/**
+ * #893: re-lease an attach that LAPSED (expired while heartbeats could not get
+ * through, e.g. an auth stall longer than the TTL). Never takes over: a 409
+ * here means another session holds the agent, and the keeper then exits as
+ * before. Rewrites only the token, lease id and expiry; the installed kit
+ * (prompt, tools, memory) is unchanged.
+ */
+const leaseMetaPath = (agentId) => join(dirname(tokenPath(agentId)), 'lease-meta.json');
+
+export async function reacquireAttachLease(client, agentId) {
+  const stored = readStoredKit(agentId);
+  if (!stored?.lease?.id) throw new QuoxApiError(404, 'no_local_lease', `No local attach state for "${agentId}"`);
+  let meta = {};
+  try { meta = JSON.parse(readFileSync(leaseMetaPath(agentId), 'utf-8')); } catch { /* defaults */ }
+  const ep = resolveEndpoint('agent-attach.lease.create', { agentId });
+  const data = await client.post(ep.path, {
+    service: ep.service,
+    body: {
+      session_label: meta.session_label || agentId,
+      ttl_seconds: meta.ttl_seconds || 900,
+      takeover: false,
+    },
+  });
+  if (!data?.token || !data?.lease?.id) throw new Error('re-lease returned no token or lease id');
+  writeFile0600(tokenPath(agentId), `${data.token}\n`);
+  stored.lease = { ...stored.lease, id: data.lease.id, expires_at: data.lease.expires_at || data.expires_at || null };
+  writeFile0600(kitPath(agentId), `${JSON.stringify(stored, null, 2)}\n`);
+  return { leaseId: data.lease.id };
+}
+
 /**
  * P10: keep the bound slot (or this session's membership of it) alive with the
  * ATTACH token. Failures are logged, never fatal to the lease heartbeat.
@@ -897,15 +959,36 @@ export function registerAgentAttachCommands(agent, ctx, program) {
         });
       } catch (err) {
         const status = err instanceof QuoxApiError ? err.status : 'network error';
+        // quox#1026 (b): the kit cannot resolve this agent at all, so no retry can succeed. Release the lease
+        // just granted (never leave it held) and say plainly which agents are attachable.
+        if (err instanceof QuoxApiError && err.status === 404 && err.code === 'unknown_agent' && lease.id) {
+          let released = false;
+          try {
+            const relEp = resolveEndpoint('agent-attach.lease.release', { leaseId: lease.id });
+            await client.post(relEp.path, { service: relEp.service, body: {} });
+            released = true;
+          } catch { /* reported below */ }
+          throw new Error(
+            `"${agentId}" is not attachable: only core registry agents and custom assistants can be attached `
+            + '(an agent made with `quox agent create` has no attach kit yet, quox#1026). '
+            + (released ? `The lease ${lease.id} was released.` : `Releasing lease ${lease.id} failed: run \`quox agent detach ${agentId} --lease ${lease.id}\`.`)
+          );
+        }
         throw new Error(
           `GET ${kitEp.path} failed (${status}) after the lease was granted (lease ${lease.id || 'unknown'}). `
-          + `The lease is still active: retry the kit fetch, or run \`quox agent detach ${agentId}\` to release it. `
+          + `The lease is still active: retry the kit fetch, or run \`quox agent detach ${agentId}${lease.id ? ` --lease ${lease.id}` : ''}\` to release it. `
           + `Original error: ${err.message}`
         );
       }
 
       const splinter = splinterInfoFrom(leaseData?.splinter);
       const paths = installAttachKit(agentId, { kit, token, splinter });
+      // #893: remember the label and TTL (beside the token, not in kit.json,
+      // which stays exactly what the server sent) so the keeper can re-lease a
+      // lapsed attach under the same identity.
+      try {
+        writeFile0600(leaseMetaPath(agentId), `${JSON.stringify({ session_label: attachLabel, ttl_seconds: options.ttl })}\n`);
+      } catch { /* the attach stands; a re-lease falls back to defaults */ }
       // ONE-BRAIN CX4: agents whose resolved tool list carries brain_context get
       // a primer from the brain. Best effort, bounded, never fails the attach.
       let primer = '';
@@ -1074,6 +1157,7 @@ export function registerAgentAttachCommands(agent, ctx, program) {
     .option('--handoff <file>', 'path to a file with a handoff note (state, open threads, next moves) to store before detaching')
     .option('--handoff-text <text>', 'handoff note text, provided inline instead of a file')
     .option('--force-detach', 'release the lease even if storing the handoff note fails')
+    .option('--lease <leaseId>', 'release this lease when there is no local attach kit (an attach that failed after its lease was granted); the server allows only its holder or an org admin')
     .option('--no-brain-note', 'do not also save the handoff to the knowledge brain as a private note')
     .action(async (agentId, options) => {
       auth.requireAuth();
@@ -1081,7 +1165,20 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       agentId = await resolveAgentId(client, agentId);
       const stored = readStoredKit(agentId);
       const leaseId = stored?.lease?.id;
-      if (!leaseId) throw noLocalLeaseError(agentId, 'attach-status');
+      // #1003: no local kit (attach failed after the lease was granted). Release exactly the lease the caller
+      // names, never a guessed one: a lease held by another session must not be released by inference.
+      if (!leaseId && options.lease) {
+        const relEp = resolveEndpoint('agent-attach.lease.release', { leaseId: options.lease });
+        await client.post(relEp.path, { service: relEp.service, body: {} });
+        removeAttachDir(agentId);
+        printEvent(events.released('quox', `attach ${agentId}`, `lease ${String(options.lease).slice(0, 8)} (no local kit)`));
+        return;
+      }
+      if (!leaseId) {
+        throw new Error(`${noLocalLeaseError(agentId, 'attach-status').message} `
+          + `If an attach failed after its lease was granted, release that lease with \`quox agent detach ${agentId} --lease <leaseId>\` `
+          + `(the lease id is in the attach error and in \`quox agent attach-status ${agentId}\`).`);
+      }
 
       if (options.handoff && options.handoffText) {
         throw new QuoxError('Pass only one of --handoff or --handoff-text.', 2);
@@ -1173,6 +1270,7 @@ export function registerAgentAttachCommands(agent, ctx, program) {
         sleep: ctx.sleep,
         dir: ctx.keeperDir,
         heartbeat: () => heartbeatAttachLease(client, agentId, { getOrgId: () => resolveOrgId(auth, program) }),
+        reacquire: () => reacquireAttachLease(client, agentId),
         release: async () => {
           const leaseId = readStoredKit(agentId)?.lease?.id;
           if (!leaseId) return;
@@ -1213,10 +1311,10 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       // the route deployed) degrades to silence, not an error.
       try {
         const bindingEp = resolveEndpoint('agent-attach.slot-binding.get', { agentId });
-        const binding = await client.get(bindingEp.path, { service: bindingEp.service });
-        if (binding?.name) {
-          printInfo(`  slot: ${binding.name}${binding.holder_session ? ` (held by ${binding.holder_session})` : ' (free)'}`);
-        }
+        // quox#1308: the route answers { binding: { slot_name, ... } }; this read .name off the body and never printed.
+        const res = await client.get(bindingEp.path, { service: bindingEp.service });
+        const slotName = res?.binding?.slot_name;
+        if (slotName) printInfo(`  slot: ${slotName}`);
       } catch {
         // No binding, or the route isn't deployed yet: not a status-command failure.
       }
@@ -1277,13 +1375,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
@@ -1292,14 +1394,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;
@@ -1328,6 +1433,28 @@ export function registerAgentAttachCommands(agent, ctx, program) {
       if (program.opts().output === 'json') formatDetail(data, { format: 'json' });
     });
 
+  // quox#1308: bind-slot was write-only. Reading an address is open to any org member (the GET route has no
+  // admin gate). No binding is an answer, not a failure: exit 0, and --json prints { binding: null }.
+  agent
+    .command('slot')
+    .description("Show which slot an agent is bound to (the only slot a user-made agent may post to)")
+    .argument('<agentId>', 'registry agent id')
+    .action(async (agentId) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('agent-attach.slot-binding.get', { agentId });
+      let binding = null;
+      try {
+        const res = await client.get(ep.path, { service: ep.service });
+        binding = res?.binding || null;
+      } catch (err) {
+        const status = err instanceof QuoxApiError ? err.status : 'network error';
+        if (!(status === 404 && err.code === 'no_binding')) throw new Error(`GET ${ep.path} failed (${status}): ${err.message}`);
+      }
+      if (program.opts().output === 'json') { formatDetail({ binding }, { format: 'json' }); return; }
+      if (!binding) { printInfo(`${agentId} has no slot binding. An org admin can bind one: quox agent bind-slot ${agentId} <slot>`); return; }
+      printInfo(`${agentId} is bound to slot ${binding.slot_name}${binding.created_at ? ` (since ${binding.created_at})` : ''}`);
+    });
+
   agent
     .command('unbind-slot')
     .description("Remove an agent identity's slot binding (org admin only)")

package/lib/commands/approvals.js

@@ -1,5 +1,5 @@
 /**
- * Approvals commands: result (quox#791)
+ * Approvals commands: result (quox#791), grants list|create|revoke (fleet standing grants, 2026-10-13)
  *
  * After a human approves a held tool call (e.g. a gated ssh_exec) the collector
  * runs it and stores the outcome. `quox approvals result <id>` reads it back.
@@ -7,12 +7,15 @@
 
 import { resolveEndpoint } from '../api/endpoints.js';
 
+import { attachWalkthrough } from './walkthrough.js';
+
 export function registerApprovalsCommands(program, ctx) {
   const { client, auth } = ctx;
 
   const approvals = program
     .command('approvals')
     .description('Tool approvals (held actions awaiting or past a human decision)');
+  attachWalkthrough(approvals, ctx, program);
 
   approvals
     .command('result <approvalId>')
@@ -31,6 +34,11 @@ 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.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.');
@@ -44,4 +52,73 @@ export function registerApprovalsCommands(program, ctx) {
       if (out !== undefined) console.log(typeof out === 'string' ? out : JSON.stringify(out, null, 2));
       else console.log(JSON.stringify(r, null, 2));
     });
+
+  // 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.
+  const grants = approvals
+    .command('grants')
+    .description('Standing grants: org-admin pre-approved fleet command lanes (ssh_exec)');
+
+  grants
+    .command('list')
+    .description('List active standing grants (--all includes revoked and expired)')
+    .option('--all', 'include revoked and expired grants')
+    .action(async (options) => {
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.approvals.grants.list');
+      const data = await client.get(ep.path, { service: ep.service, ...(options.all ? { query: { all: '1' } } : {}) });
+      if (program.opts().output === 'json') { console.log(JSON.stringify(data, null, 2)); return; }
+      const rows = data.grants || [];
+      if (!rows.length) { console.log('No standing grants.'); return; }
+      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(`  reason: ${g.reason}  (by ${g.created_by})`);
+      }
+    });
+
+  grants
+    .command('create')
+    .description('Create a standing grant (human org admin only)')
+    .requiredOption('--host <hostId>', 'the ONE host the grant covers')
+    .requiredOption('--reason <text>', 'why (shown in history and evidence)')
+    .option('--preset <name>', 'proxmox-test-vm-lane (clone/power/destroy/guest-exec in a VMID range)')
+    .option('--template <vmid>', 'template VMID the lane clones from (preset)')
+    .option('--vmid-range <min-max>', 'VMID range, e.g. 9100-9199')
+    .option('--name-prefix <prefix>', 'VM name prefix the lane may create (preset)', 'z2h')
+    .option('--pattern <regex>', 'custom anchored command regex (repeatable; instead of --preset)', (v, a) => (a || []).concat([v]))
+    .option('--days <n>', 'expiry in days (max 30)', '14')
+    .action(async (options) => {
+      auth.requireAuth();
+      const body = { tool: 'ssh_exec', host: options.host, reason: options.reason, expires_in_days: Number(options.days) };
+      if (options.vmidRange) {
+        const m = /^(\d+)-(\d+)$/.exec(options.vmidRange);
+        if (!m) { console.error('--vmid-range must look like 9100-9199'); process.exitCode = 1; return; }
+        body.vmid_min = Number(m[1]); body.vmid_max = Number(m[2]);
+      }
+      if (options.preset) {
+        body.preset = options.preset; body.template_vmid = Number(options.template); body.name_prefix = options.namePrefix;
+      } else {
+        body.patterns = options.pattern || [];
+      }
+      const ep = resolveEndpoint('v1.approvals.grants.create');
+      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 || {};
+      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}`);
+    });
+
+  grants
+    .command('revoke <grantId>')
+    .description('Revoke a standing grant now (human org admin only)')
+    .action(async (grantId) => {
+      auth.requireAuth();
+      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; }
+      console.log(`Revoked ${data.grant?.grant_id || grantId} at ${data.grant?.revoked_at || 'now'}.`);
+    });
 }

package/lib/commands/aside.js

@@ -0,0 +1,24 @@
+/**
+ * quox aside "<question>"
+ *
+ * A read-only side question: the model gets no tools and no conversation, so nothing it says can change
+ * anything or land in a conversation's history. The TUI's /aside is the same call with the recent
+ * exchanges passed as read-only context.
+ */
+import { askAside } from '../core/aside.js';
+
+export function registerAsideCommand(program, ctx) {
+  const { client, auth } = ctx;
+  program
+    .command('aside')
+    .description('Ask a read-only side question: no tools, not saved to any conversation')
+    .argument('<question...>', 'the question')
+    .option('--agent <id>', 'who answers (default quox)')
+    .action(async (words, opts) => {
+      auth.requireAuth();
+      const r = await askAside(client, { question: words.join(' '), agent: opts.agent });
+      if (program.opts().output === 'json') { console.log(JSON.stringify({ answer: r.text, model: r.model, provider: r.provider, tools_used: r.tools, read_only: true }, null, 2)); return; }
+      console.log(r.text || '(no answer)');
+      console.log(`· aside, read only: no tools, not saved${r.model ? ` · ${r.provider ? `${r.provider}/` : ''}${r.model}` : ''}`);
+    });
+}