quoxcli 0.2.0 → 0.3.1

package/lib/commands/workflow.js

@@ -5,7 +5,7 @@
 import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 import yaml from 'js-yaml';
-import { formatOutput, formatDetail, printWarning, printInfo } from '../core/output.js';
+import { formatOutput, formatDetail, printWarning, printInfo, getOutputFormat } from '../core/output.js';
 import { events, printEvent, line as glyphLine } from '../core/quoxglyph.js';
 import { resolveOrgId, parseJSON } from './helpers.js';
 import { resolveEndpoint } from '../api/endpoints.js';
@@ -77,6 +77,33 @@ function printApplyDiff(workflowId, changes) {
   console.log('');
 }
 
+// Read one engine workflow by id, or by its exact name when no id matches (proof cases and people know
+// names; engine ids are wf-<ms>-<6>). An ambiguous name is refused with the matching ids, never guessed.
+async function getEngineWorkflow(client, ref) {
+  const ep = resolveEndpoint('workflows.applyGet', { workflowId: ref });
+  try {
+    const res = await client.get(ep.path, { service: ep.service });
+    return res.data || res;
+  } catch (err) {
+    if (err.status !== 404) throw err;
+    const listEp = resolveEndpoint('workflows.applyList');
+    const matches = [];
+    for (let offset = 0, guard = 0; guard < 200; guard++) {
+      const data = await client.get(listEp.path, { service: listEp.service, query: { limit: 100, offset } });
+      const items = data.data || data.items || data.workflows || (Array.isArray(data) ? data : []);
+      for (const w of items) if (w && w.name === ref) matches.push(w);
+      offset += items.length;
+      const pg = data.pagination;
+      if (!pg || !items.length || !(offset < pg.total)) break;
+    }
+    if (matches.length > 1) throw new Error(`Workflow name "${ref}" matches ${matches.length} workflows (${matches.map((m) => m.id).join(', ')}); give the id instead.`);
+    if (!matches.length) throw err;
+    const byId = resolveEndpoint('workflows.applyGet', { workflowId: matches[0].id });
+    const res = await client.get(byId.path, { service: byId.service });
+    return res.data || res;
+  }
+}
+
 export function registerWorkflowCommands(program, ctx) {
   const { client, auth } = ctx;
 
@@ -105,9 +132,17 @@ export function registerWorkflowCommands(program, ctx) {
 
       try {
         const ep = resolveEndpoint('workflows.applyList');
-        const data = await client.get(ep.path, { service: ep.service });
-        const items = data.data || data.items || data.workflows || (Array.isArray(data) ? data : []);
-        for (const item of items) rows.push({ ...item, source: 'engine' });
+        // The engine pages (default 20, max 100). Walk every page so the list is the
+        // whole store, not the first page (121 workflows read as 20 before).
+        const PAGE = 100;
+        for (let offset = 0, guard = 0; guard < 200; guard++) {
+          const data = await client.get(ep.path, { service: ep.service, query: { limit: PAGE, offset } });
+          const items = data.data || data.items || data.workflows || (Array.isArray(data) ? data : []);
+          for (const item of items) rows.push({ ...item, source: 'engine' });
+          const pg = data.pagination;
+          offset += items.length;
+          if (!pg || !items.length || !(offset < pg.total)) break;
+        }
       } catch (err) {
         printWarning(`Engine (quoxflow) workflow list failed: ${err.message}`);
       }
@@ -131,16 +166,14 @@ export function registerWorkflowCommands(program, ctx) {
   workflow
     .command('get')
     .description('Get workflow details')
-    .argument('<workflowId>', 'workflow ID')
+    .argument('<workflowId>', 'workflow ID or exact name')
     .action(async (workflowId) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
 
       let data, source;
       try {
-        const ep = resolveEndpoint('workflows.applyGet', { workflowId });
-        const res = await client.get(ep.path, { service: ep.service });
-        data = res.data || res;
+        data = await getEngineWorkflow(client, workflowId);
         source = 'engine';
       } catch (err) {
         if (err.status !== 404) throw err;
@@ -160,20 +193,85 @@ export function registerWorkflowCommands(program, ctx) {
       formatDetail({ ...data, source }, { format: program.opts().output, title: data.name });
     });
 
+  // ── workflow schedule <id> ──────────────────────────────────────────────────
+  // Is the schedule REALLY registered, and when does it fire next? Read from the live scheduler
+  // (GET /api/triggers/schedules), never inferred from the saved config (SITE-CLI 2026-10-17).
+  workflow
+    .command('schedule')
+    .description('Show whether a workflow\'s schedule trigger is registered with the live scheduler, and its next fire time')
+    .argument('<workflowId>', 'workflow ID or exact name')
+    .action(async (workflowId) => {
+      auth.requireAuth();
+      const wf = await getEngineWorkflow(client, workflowId);
+      const id = wf.id || workflowId;
+      const nodes = (wf.definition && wf.definition.nodes) || wf.nodes || [];
+      const schedNodes = nodes.filter((n) => n && n.type === 'trigger:schedule');
+
+      const liveEp = resolveEndpoint('triggers.schedules');
+      const liveRes = await client.get(liveEp.path, { service: liveEp.service });
+      const live = liveRes.data || liveRes;
+      const ownedByTasks = live.owned_by === 'tasks';
+      const rows = (live.schedules || []).filter((r) => r.workflowId === id);
+
+      const schedules = schedNodes.map((n) => {
+        const cfg = n.config || {};
+        const saved = cfg.expression || cfg.cron || null;
+        const reg = rows.find((r) => r.nodeId === n.id);
+        if (ownedByTasks) {
+          return { nodeId: n.id, registered: null, state: 'unknown', saved, expression: null, timezone: cfg.timezone || 'UTC', nextFireAt: null,
+            reason: 'Scheduling is owned by the tasks service on this instance; the workflow engine cannot see registrations.' };
+        }
+        if (!reg) {
+          return { nodeId: n.id, registered: false, state: 'not registered', saved, expression: null, timezone: cfg.timezone || 'UTC', nextFireAt: null,
+            reason: wf.active === false ? 'The workflow is not active, so its schedule is not registered. Activate it to register.' : 'Not registered with the scheduler.' };
+        }
+        return { nodeId: n.id, registered: true, state: reg.active ? 'active' : 'paused', saved, expression: reg.expression, timezone: reg.timezone || 'UTC', nextFireAt: reg.nextFireAt || null };
+      });
+
+      const result = { workflowId: id, name: wf.name, active: wf.active, ...(live.owned_by ? { owned_by: live.owned_by } : {}), schedules,
+        ...(schedNodes.length ? {} : { note: 'This workflow has no schedule trigger.' }) };
+      if (getOutputFormat() === 'json' || program.opts().output === 'json') { formatDetail(result, { format: 'json' }); return; }
+      if (!schedNodes.length) { printInfo(`${id}: ${result.note}`); return; }
+      if (ownedByTasks) printInfo(live.note || 'Schedules are managed by the tasks service.');
+      formatOutput({
+        columns: ['nodeId', 'registeredLabel', 'state', 'expression', 'timezone', 'nextFireAt', 'reason'],
+        headers: ['Node', 'Registered', 'State', 'Cron (live)', 'Timezone', 'Next Fire', 'Note'],
+        rows: schedules.map((r) => ({ ...r, registeredLabel: r.registered === true ? 'yes' : r.registered === false ? 'no' : 'unknown', expression: r.expression || '-', nextFireAt: r.nextFireAt || '-', reason: r.reason || '' })),
+      }, { format: program.opts().output });
+    });
+
   workflow
     .command('create')
-    .description('Create a new workflow')
+    .description('Create a new workflow in the workflow engine (quoxflow). --steps takes a JSON array of nodes (chained in order) or an object with nodes and optional edges')
     .requiredOption('--name <name>', 'workflow name')
     .option('--description <desc>', 'description')
-    .option('--steps <json>', 'workflow steps as JSON')
+    .option('--steps <json>', 'nodes as a JSON array (chained sequentially), or {"nodes":[...],"edges":[...]}')
     .action(async (options) => {
       auth.requireAuth();
-      const orgId = resolveOrgId(auth, program);
-      const body = { name: options.name };
+      // #1190: the engine is the one workflow store. Same id shape as `workflow apply`.
+      const id = `wf-${Date.now()}-${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}`;
+      let nodes = [];
+      let edges = [];
+      if (options.steps) {
+        const steps = parseJSON(options.steps, '--steps');
+        if (Array.isArray(steps)) {
+          nodes = steps;
+          edges = steps.slice(1).map((n, i) => ({ id: `e${i + 1}`, source: steps[i].id ?? `n${i}`, target: n.id ?? `n${i + 1}` }));
+        } else if (steps && typeof steps === 'object' && Array.isArray(steps.nodes)) {
+          nodes = steps.nodes;
+          edges = Array.isArray(steps.edges) ? steps.edges : [];
+        } else {
+          throw new Error('--steps must be a JSON array of nodes, or an object with a "nodes" array (and optional "edges").');
+        }
+      }
+      const body = { id, name: options.name, nodes, edges };
       if (options.description) body.description = options.description;
-      if (options.steps) body.steps = parseJSON(options.steps, '--steps');
-      await client.post(resolveEndpoint('workflows.create', { orgId }).path, { service: resolveEndpoint('workflows.create', { orgId }).service, body });
-      printEvent(events.created('quox', 'workflow', options.name));
+      const ep = resolveEndpoint('workflows.applyCreate');
+      const res = await client.post(ep.path, { service: ep.service, body });
+      const created = res?.data || res;
+      printEvent(events.created('quox', 'workflow', `${options.name} (quoxflow) id:${created.id || id}`));
+      // #1000: --json gets the saved workflow (the event line is suppressed in json mode, which left nothing)
+      if (getOutputFormat() === 'json') formatDetail(created, { format: 'json' });
     });
 
   workflow
@@ -190,8 +288,9 @@ export function registerWorkflowCommands(program, ctx) {
       if (options.name) body.name = options.name;
       if (options.description) body.description = options.description;
       if (options.status) body.status = options.status;
-      await client.patch(resolveEndpoint('workflows.update', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.update', { orgId, workflowId }).service, body });
+      const data = await client.patch(resolveEndpoint('workflows.update', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.update', { orgId, workflowId }).service, body });
       printEvent(events.updated('quox', 'workflow', workflowId));
+      if (getOutputFormat() === 'json') formatDetail(data?.workflow || data, { format: 'json' });
     });
 
   workflow
@@ -201,8 +300,17 @@ export function registerWorkflowCommands(program, ctx) {
     .action(async (workflowId) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      await client.delete(resolveEndpoint('workflows.delete', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.delete', { orgId, workflowId }).service });
-      printEvent(glyphLine('quox', 'workflow deleted', { result: workflowId, status: 'ok' }));
+      // #997: engine (quoxflow) first, the auth store only on an engine 404 (same order as `workflow get`)
+      let source = 'engine';
+      try {
+        const ep = resolveEndpoint('workflows.applyDelete', { workflowId });
+        await client.delete(ep.path, { service: ep.service });
+      } catch (err) {
+        if (err.status !== 404) throw err;
+        source = 'auth';
+        await client.delete(resolveEndpoint('workflows.delete', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.delete', { orgId, workflowId }).service });
+      }
+      printEvent(glyphLine('quox', 'workflow deleted', { result: `${workflowId} (${source})`, status: 'ok' }));
     });
 
   workflow
@@ -232,7 +340,8 @@ export function registerWorkflowCommands(program, ctx) {
           }
           if (engineExists) {
             const exEp = resolveEndpoint('workflows.applyExecute', { workflowId });
-            const run = await client.post(exEp.path, { service: exEp.service, body: body.context || {} });
+            // #1029: the engine reads triggerData (a bare body lost --input), and async returns the run id at once
+            const run = await client.post(exEp.path, { service: exEp.service, body: { triggerData: body.context || {}, async: true } });
             const runId = run.executionId || run.execution_id || run.runId || run.run_id || run.id || run.execution?.id || 'ok';
             const st = run.status || run.execution?.status;
             printEvent(glyphLine('quox', 'workflow run', { result: `${workflowId} (quoxflow) -> run ${runId}${st ? ` [${st}]` : ''}`, status: 'ok' }));
@@ -299,15 +408,27 @@ export function registerWorkflowCommands(program, ctx) {
     .action(async (workflowId) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      // No dedicated GET .../steps route exists — steps are a field on the
-      // workflow object itself.
-      const data = await client.get(resolveEndpoint('workflows.get', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.get', { orgId, workflowId }).service });
-      const workflow = data.workflow || data;
+      // No dedicated GET .../steps route exists: steps are a field on the
+      // workflow object itself. quox#928: look in the same stores `workflow get`
+      // does, engine (quoxflow) first, so engine workflows (wf-obj-*) resolve too.
+      let rows;
+      try {
+        const ep = resolveEndpoint('workflows.applyGet', { workflowId });
+        const res = await client.get(ep.path, { service: ep.service });
+        const wf = res.data || res;
+        const nodes = wf?.definition?.nodes || wf?.nodes;
+        if (!Array.isArray(nodes)) throw Object.assign(new Error('not an engine workflow'), { status: 404 });
+        rows = nodes.map((n, idx) => ({ idx, label: n.name || n.id, step_type: n.type, ref_id: n.config?.tool || n.config?.toolName || '-' }));
+      } catch (err) {
+        if (err.status !== 404) throw err;
+        const data = await client.get(resolveEndpoint('workflows.get', { orgId, workflowId }).path, { service: resolveEndpoint('workflows.get', { orgId, workflowId }).service });
+        rows = (data.workflow || data).steps || [];
+      }
       formatOutput({
         // fleet #392: workflow_steps columns are idx/label/step_type/ref_id.
         columns: ['idx', 'label', 'step_type', 'ref_id'],
         headers: ['#', 'Name', 'Type', 'Tool'],
-        rows: workflow.steps || [],
+        rows,
       }, { format: program.opts().output });
     });
 
@@ -319,10 +440,35 @@ export function registerWorkflowCommands(program, ctx) {
     .action(async (workflowId, options) => {
       auth.requireAuth();
       const orgId = resolveOrgId(auth, program);
-      await client.put(resolveEndpoint('workflows.steps', { orgId, workflowId }).path, {
-        service: resolveEndpoint('workflows.steps', { orgId, workflowId }).service,
-        body: { steps: parseJSON(options.steps, '--steps') },
-      });
+      const stepList = parseJSON(options.steps, '--steps');
+      try {
+        await client.put(resolveEndpoint('workflows.steps', { orgId, workflowId }).path, {
+          service: resolveEndpoint('workflows.steps', { orgId, workflowId }).service,
+          body: { steps: stepList },
+        });
+      } catch (err) {
+        if (err.status !== 404) throw err;
+        // #997: `steps list` reads engine workflows too, so an engine id 404'd here with a bare 'Workflow not found'.
+        // An engine workflow is a node/edge graph, not a step list: refuse it by name, like `workflow publish`.
+        let engineExists = false;
+        try {
+          const getEp = resolveEndpoint('workflows.applyGet', { workflowId });
+          await client.get(getEp.path, { service: getEp.service });
+          engineExists = true;
+        } catch (engineErr) {
+          if (engineErr.status !== 404) throw engineErr;
+        }
+        if (engineExists) {
+          throw new Error(
+            `Workflow "${workflowId}" lives in the engine (quoxflow) store, where it is a graph of nodes and edges, `
+            + 'not the step list `workflow steps set` replaces. Edit it with `quox workflow apply -f <file>` '
+            + `(start from \`quox -o json workflow get ${workflowId}\`).`
+          );
+        }
+        throw new Error(
+          `Workflow "${workflowId}" was not found in either the engine (quoxflow) or auth-service workflow store.`
+        );
+      }
       printEvent(events.updated('quox', 'workflow steps', workflowId));
     });
 
@@ -390,7 +536,10 @@ export function registerWorkflowCommands(program, ctx) {
       }
 
       const createEp = resolveEndpoint('workflows.applyCreate');
-      const data = await client.post(createEp.path, { service: createEp.service, body: wf });
+      // #1000: quoxflow's WorkflowSchema requires an id, so "no id = create" 400'd. Mint one in the
+      // engine's own wf-<ms>-<6> shape; the created id is printed, so the file can be given it to update later.
+      const body = wf.id ? wf : { ...wf, id: `wf-${Date.now()}-${Math.random().toString(36).slice(2, 8).padEnd(6, '0')}` };
+      const data = await client.post(createEp.path, { service: createEp.service, body });
       const created = data.data || data;
       printEvent(events.created('quox', 'workflow', `${created.name || wf.name || created.id} (quoxflow) id:${created.id}`));
       formatDetail(created, { format: program.opts().output });
@@ -421,10 +570,18 @@ export function registerWorkflowCommands(program, ctx) {
         try {
           await client.get(getEp.path, { service: getEp.service });
         } catch (err) {
-          if (err.status === 404) {
-            throw new Error(`Workflow "${workflowId}" was not found on the read path \`quox workflow get\` uses. Use -f <file> to validate a local file instead.`);
+          if (err.status !== 404) throw err;
+          // `workflow get` also reads the engine (quoxflow) store; engine-only workflows
+          // (most of them) are not in the auth store, so fall back the same way.
+          try {
+            const engEp = resolveEndpoint('workflows.applyGet', { workflowId });
+            await client.get(engEp.path, { service: engEp.service });
+          } catch (err2) {
+            if (err2.status === 404) {
+              throw new Error(`Workflow "${workflowId}" was not found on the read path \`quox workflow get\` uses. Use -f <file> to validate a local file instead.`);
+            }
+            throw err2;
           }
-          throw err;
         }
         targetId = workflowId;
       } else {

package/lib/commands/x.js

@@ -340,10 +340,19 @@ export function registerXCommands(program, ctx) {
       const orgId = resolveOrgId(auth, program);
       const ep = resolveEndpoint('v1.tools.execute');
 
-      const budgetData = await client.post(ep.path, {
-        service: ep.service,
-        body: { tool_name: 'x_budget_status', input: {}, org_id: orgId },
-      });
+      // Budget over the org-scoped REST route, not the x_budget_status tool: that tool left the
+      // Default hat (cap room), so the tool path answered "not granted" for every caller.
+      let budgetData;
+      try {
+        const actEp = resolveEndpoint('x.activity');
+        const act = await client.get(actEp.path, { service: actEp.service, query: { org_id: orgId } });
+        const b = act && act.budget;
+        budgetData = b && typeof b === 'object'
+          ? { success: true, daily_used: b.dailyUsed, daily_limit: b.dailyLimit, monthly_used: b.monthlyUsed, monthly_limit: b.monthlyLimit, org_id: act.org_id || orgId }
+          : { success: false, error: (act && act.error) || 'budget missing from /x/activity response' };
+      } catch (err) {
+        budgetData = { success: false, error: err.message };
+      }
 
       let credResult = null;
       let credError = null;

package/lib/core/actingAs.js

@@ -83,14 +83,14 @@ export function hasExplicitProfile(argv, env = process.env) {
  * session's sole attach (implicit default), else the profile identity.
  * @returns {{name: string|null, source: 'flag'|'env'|'self'|'profile'|'default'|null}}
  */
-export async function resolveActing({ argv = process.argv.slice(2), env = process.env, resolveAttach } = {}) {
+export async function resolveActing({ argv = process.argv.slice(2), env = process.env, resolveAttach, explicitProfile = false } = {}) {
   const explicit = actingAsName(env);
   if (explicit) {
     const source = env.QUOX_AS_FLAG === '1' ? 'flag' : 'env';
     if (explicit.toLowerCase() === 'self') return { name: null, source: 'self', via: source };
     return { name: explicit, source };
   }
-  if (hasExplicitProfile(argv, env)) return { name: null, source: 'profile' };
+  if (explicitProfile || hasExplicitProfile(argv, env)) return { name: null, source: 'profile' };
   if (isDefaultExempt(argv)) return { name: null, source: null };
   const mine = resolveAttach ? resolveAttach() : (await import('../commands/agentAttach.js')).resolveMyAttach();
   if (mine?.agentId) return { name: mine.agentId, source: 'default' };

package/lib/core/activeSummary.js

@@ -0,0 +1,186 @@
+/**
+ * `quox active` / TUI `/active` (QUOXON-1208, owner: "summary of who is doing what"). ONE simplified list over the
+ * org session index (GET /api/v1/sessions: tmux sessions, held slots, residents, work, working chats), one line per
+ * active worker, newest activity first, grouped Working / Waiting on you / Idle (+ Failing when there is any).
+ * Real data only: a worker's "doing" text is what the index carries (its state reason, slot, agent), never invented;
+ * a source the index could not read is named in one line. Pure: activeLines(index, opts) -> [{ text, tone }].
+ */
+import { formatAge } from './claudeLs.js';
+
+export const ACTIVE_KINDS = ['sessions', 'slots', 'agents'];
+export const PER_GROUP = 10;
+export const ASLEEP_AFTER_S = 6 * 3600; // a resting worker with no activity for this long reads as asleep
+
+const clip = (v, n) => { const a = [...String(v ?? '')]; return a.length > n ? a.slice(0, n - 1).join('') + '…' : String(v ?? ''); };
+const t = (r) => { const x = Date.parse(r.last_active); return Number.isFinite(x) ? x : -Infinity; };
+
+/** Which filter(s) a row belongs to. sessions = terminal sessions, slots = held slots, agents = residents or agent-attached rows. */
+export function rowKinds(r) {
+  const k = new Set();
+  if (r.kind === 'tmux') k.add('sessions');
+  if (r.kind === 'slot') k.add('slots');
+  if (r.kind === 'resident' || r.agent) k.add('agents');
+  return k;
+}
+
+function doing(r) {
+  const bits = [];
+  if (r.state_reason) bits.push(String(r.state_reason).replace(/\s+/g, ' ').trim());
+  if (r.kind === 'tmux' && r.backend) bits.push(`${r.backend} session`);
+  else if (r.kind === 'slot') bits.push('holding a slot');
+  else if (r.kind === 'conversation') bits.push('chat');
+  else if (r.kind) bits.push(r.kind);
+  if (r.slot && r.kind !== 'slot') bits.push(`slot ${r.slot}`);
+  if (r.agent) bits.push(`agent ${r.agent}`);
+  return bits.length ? bits.join(', ') : 'no activity detail recorded';
+}
+
+function stateWord(r, ageS) {
+  if (r.state === 'working') return 'working';
+  if (r.state === 'waiting') return 'waiting on you';
+  if (r.state === 'failing') return 'failing';
+  if (ageS != null && ageS >= ASLEEP_AFTER_S) return 'asleep';
+  return ageS != null ? `idle ${formatAge(ageS)}` : 'idle';
+}
+
+/** -> { rows: [{ name, doing, state, group, since, ts, kinds }], groups: {working, waiting, failing, idle}, down: [..] } */
+export function prepareActive(index, { filter = null, now = Date.now() } = {}) {
+  const rows = (index?.rows || (index?.groups || []).flatMap((g) => g.rows) || [])
+    .filter((r) => r.kind !== 'conversation' || r.state === 'working' || r.state === 'waiting')
+    .filter((r) => !filter || rowKinds(r).has(filter))
+    .sort((a, b) => t(b) - t(a))
+    .map((r) => {
+      const ts = t(r);
+      const ageS = Number.isFinite(ts) ? Math.max(0, (now - ts) / 1000) : null;
+      const group = r.state === 'working' ? 'working' : r.state === 'waiting' ? 'waiting' : r.state === 'failing' ? 'failing' : 'idle';
+      const name = r.kind === 'slot' ? (r.holder_session || r.name || '(unnamed slot)') : (r.name || '(unnamed)');
+      return { name, doing: doing(r), state: stateWord(r, ageS), group, since: ageS == null ? 'no activity recorded' : `${formatAge(ageS)} ago`, ts };
+    });
+  const groups = { working: [], waiting: [], failing: [], idle: [] };
+  for (const r of rows) groups[r.group].push(r);
+  const down = (index?.sources || []).filter((s) => s.state !== 'connected');
+  return { rows, groups, down };
+}
+
+const TITLES = { working: 'Working', waiting: 'Waiting on you', failing: 'Failing', idle: 'Idle' };
+const TONES = { working: 'ok', waiting: 'warn', failing: 'warn', idle: 'dim' };
+
+export function activeLines(index, { filter = null, now = Date.now(), all = false } = {}) {
+  const p = prepareActive(index, { filter, now });
+  const out = [{ text: `Active${filter ? ` ${filter}` : ''}: ${p.rows.length} · ${p.groups.working.length} working · ${p.groups.waiting.length} waiting on you · ${p.groups.idle.length} idle${p.groups.failing.length ? ` · ${p.groups.failing.length} failing` : ''}`, tone: 'accent' }];
+  if (!p.rows.length) out.push({ text: p.down.some((s) => s.state !== 'unavailable') ? 'Nothing to show (see the sources below).' : `No active ${filter || 'workers'} in this org.`, tone: 'dim' });
+  for (const g of ['working', 'waiting', 'failing', 'idle']) {
+    const rs = p.groups[g];
+    if (!rs.length) continue;
+    out.push({ text: `${TITLES[g]} (${rs.length})`, tone: 'accent' });
+    for (const r of all ? rs : rs.slice(0, PER_GROUP)) out.push({ text: `  ${clip(r.name, 28).padEnd(28)} ${clip(r.doing, 44).padEnd(44)} ${r.state}, ${r.since}`, tone: TONES[g] });
+    if (!all && rs.length > PER_GROUP) out.push({ text: `  +${rs.length - PER_GROUP} more`, tone: 'dim' });
+  }
+  // 'unavailable' is a source the server declares it does not list yet (residents): an expected absence, not a failed read.
+  // Only a real fault (error, timeout) is "could not read". Residents that hold a slot already show up as rows above.
+  const failed = p.down.filter((s) => s.state !== 'unavailable');
+  const absent = p.down.filter((s) => s.state === 'unavailable');
+  if (failed.length) out.push({ text: `could not read: ${failed.map((s) => `${s.id} (${s.state}${s.note ? `: ${s.note}` : ''})`).join(' · ')}`, tone: 'warn' });
+  if (absent.length) out.push({ text: `not listed separately yet: ${absent.map((s) => s.id).join(' · ')} (shown above when they hold a slot)`, tone: 'dim' });
+  return out;
+}
+
+// ---- TUI /active: one clean row per session -------------------------------------------------------------
+const GLYPH = { working: '◐', waiting: '⚠', failing: '✖', idle: '·' };
+const RANK = { waiting: 0, failing: 1, working: 2, idle: 3 };
+const TUI_TONES = { working: undefined, waiting: undefined, failing: undefined, idle: undefined }; // the row's own glyph carries status; a tone would prefix a second glyph on every wrapped line
+const GROUP_TITLES = { waiting: 'Waiting on you', failing: 'Failing', working: 'Working', idle: 'Idle' };
+
+/** "resident:hyp-01" -> { name: 'hyp-01', tag: 'resident' }: the machine prefix becomes a readable tag. */
+function readableName(raw) {
+  const m = String(raw).match(/^(resident|agent|slot|tmux):(.+)$/i);
+  return m ? { name: m[2], tag: m[1].toLowerCase() } : { name: String(raw), tag: null };
+}
+const humanReason = (reason) => String(reason || '').replace(/\s+/g, ' ').trim().replace(/^unread slot messages?$/i, 'unread messages');
+
+/** Word-wrap `rest` after `first`; continuation lines get a 4-space hanging indent. Never clips, never exceeds `width`. */
+function wrapHanging(first, rest, width, sep = '  ') {
+  const out = [];
+  let cur = first, fresh = true; // fresh: only the label is on this line so far
+  for (const w of String(rest).split(/\s+/).filter(Boolean)) {
+    const joined = fresh ? `${cur}${sep}${w}` : `${cur} ${w}`;
+    if ([...joined].length <= width) { cur = joined; fresh = false; continue; }
+    out.push(cur); cur = `    ${w}`; fresh = false;
+  }
+  out.push(cur);
+  return out;
+}
+
+/**
+ * The window's /active: one row per session (deduped by readable name; the row that needs you wins), shaped
+ * `  <glyph> <name>  <what it needs> · <age>`, word-wrapped under a hanging indent at `cols`, never clipped, grouped
+ * Waiting on you / Failing / Working / Idle. The `quox active` CLI keeps activeLines(); this is the TUI-only view.
+ */
+export function activeRows(index, { now = Date.now(), cols = 80, filter = null, unread = null } = {}) {
+  const raw = (index?.rows || (index?.groups || []).flatMap((g) => g.rows) || [])
+    .filter((r) => r.kind !== 'conversation' || r.state === 'working' || r.state === 'waiting')
+    .filter((r) => !filter || rowKinds(r).has(filter));
+  const byName = new Map();
+  for (const r of raw) {
+    const base = r.kind === 'slot' ? (r.holder_session || r.name || '(unnamed slot)') : (r.name || '(unnamed)');
+    const { name, tag } = readableName(base);
+    const ts = t(r), ageS = Number.isFinite(ts) ? Math.max(0, (now - ts) / 1000) : null;
+    const group = r.state === 'working' ? 'working' : r.state === 'waiting' ? 'waiting' : r.state === 'failing' ? 'failing' : 'idle';
+    const needs = [];
+    let why = humanReason(r.state_reason);
+    const nUnread = unread && (unread.get?.(r.kind === 'slot' ? (r.name || '') : (r.slot || '')) ?? null); // optional per-slot count from the slots list
+    if (why === 'unread messages' && nUnread > 0) why = `${nUnread} unread message${nUnread === 1 ? '' : 's'}`;
+    if (why) needs.push(why);
+    else needs.push(group === 'idle' ? (ageS != null && ageS >= ASLEEP_AFTER_S ? 'asleep' : 'idle') : group);
+    if (r.kind === 'slot') needs.push('holding a slot'); else if (r.slot) needs.push(`holding slot ${r.slot}`);
+    if (r.agent) needs.push(`agent ${r.agent}`);
+    const cand = { name, tag: tag || (r.kind === 'resident' ? 'resident' : null), group, needs, ageS, ts };
+    const key = name.toLowerCase(), old = byName.get(key);
+    if (!old) { byName.set(key, cand); continue; }
+    const better = RANK[cand.group] < RANK[old.group] || (RANK[cand.group] === RANK[old.group] && cand.ts > old.ts);
+    const win = better ? cand : old, lose = better ? old : cand;
+    const hasUnread = win.needs.some((n) => /unread/.test(n));
+    win.needs = [...new Set([...win.needs, ...lose.needs.filter((n) => !/^(working|idle|asleep|failing)$/.test(n) && !(hasUnread && /unread/.test(n)) && !(/^holding a slot$/.test(n) && win.needs.some((x) => /^holding/.test(x))))])];
+    win.tag = win.tag || lose.tag;
+    byName.set(key, win);
+  }
+  const rows = [...byName.values()].sort((a, b) => RANK[a.group] - RANK[b.group] || b.ts - a.ts);
+  const n = (g) => rows.filter((r) => r.group === g).length;
+  const width = Math.max(30, cols - 4);
+  const hdr = `${rows.length} · ${n('waiting')} need you · ${n('working')} working · ${n('idle')} idle${n('failing') ? ` · ${n('failing')} failing` : ''}`;
+  const out = wrapHanging(`Active${filter ? ` ${filter}` : ''}:`, hdr, width, ' ').map((text) => ({ text, tone: 'accent' }));
+  if (!rows.length) out.push({ text: `No active ${filter || 'workers'} in this org.`, tone: undefined });
+  let last = null;
+  for (const r of rows) {
+    if (r.group !== last) { last = r.group; out.push({ text: `${GROUP_TITLES[r.group]} (${n(r.group)})`, tone: 'accent' }); }
+    const label = `${r.name}${r.tag ? ` (${r.tag})` : ''}`;
+    const what = `${r.needs.join(' · ')}${r.ageS == null ? '' : ` · ${formatAge(r.ageS)} ago`}`;
+    for (const text of wrapHanging(`  ${GLYPH[r.group]} ${label}`, what, width)) out.push({ text, tone: TUI_TONES[r.group] });
+  }
+  // a source that could not be read is never an empty org: name it ('unavailable' is an expected absence, not a fault)
+  const failed = (index?.sources || []).filter((x) => x.state !== 'connected' && x.state !== 'unavailable');
+  if (failed.length) for (const text of wrapHanging('could not read:', failed.map((x) => `${x.id} (${x.state}${x.note ? `: ${x.note}` : ''})`).join(' · '), width, ' ')) out.push({ text, tone: 'warn' });
+  return out;
+}
+
+/** Bare `quox active [sessions|slots|agents] [--json] [--all]`. A failed fetch prints its status and exits 1 (never an empty list). */
+export async function runActive({ filter = null, json = false, all = false, lines = false, cols = null } = {}, over = {}) {
+  const d = { write: (s) => process.stdout.write(s), now: () => Date.now(), ...over };
+  if (filter && !ACTIVE_KINDS.includes(filter)) { d.write(`quox active: unknown filter "${filter}" (sessions, slots or agents)\n`); return 1; }
+  try {
+    const idx = await d.fetchIndex();
+    if (json) {
+      const p = prepareActive(idx, { filter, now: d.now() });
+      d.write(JSON.stringify({ filter, counts: Object.fromEntries(Object.entries(p.groups).map(([k, v]) => [k, v.length])), workers: p.rows.map(({ ts, ...r }) => r), sources_down: p.down }, null, 2) + '\n');
+    } else if (lines) d.write(activeLines(idx, { filter, now: d.now(), all }).map((l) => l.text).join('\n') + '\n');
+    else {
+      let unread = null;
+      if (d.fetchSlots) { try { unread = new Map((await d.fetchSlots() || []).map((x) => [x.name, x.unread_count || 0])); } catch { unread = null; } } // the count is a nicety: a failed slots read never hides the list
+      d.write(activeRows(idx, { filter, now: d.now(), cols: cols || process.stdout.columns || 100, unread }).map((l) => l.text).join('\n') + '\n');
+    }
+    return 0;
+  } catch (e) {
+    d.write(`quox active: ${e && e.status ? `HTTP ${e.status}: ` : ''}${(e && e.message) || 'request failed'}\n`);
+    return 1;
+  }
+}

package/lib/core/aside.js

@@ -0,0 +1,54 @@
+/**
+ * ASIDE: a read-only side question. `quox aside "<question>"` and the TUI /aside share this.
+ *
+ * It goes to the collector's no-tools invoke (POST /api/internal/agents/invoke with no_tools: true): the model
+ * gets no tools at all, and no conversation or session id is sent, so the main conversation's history is never
+ * touched. The TUI passes the last few exchanges as plain read-only context so "what did it just say about X?"
+ * works; nothing is written back.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+export const ASIDE_MAX_CONTEXT = 6000;
+
+const ASIDE_NOTE = 'This is a read-only side question. You have no tools: answer from what you know and from the conversation excerpt below. Do not offer to run anything. Be brief.';
+
+/** Recent [{ role: 'user'|'assistant', text }] -> one plain excerpt, newest kept when it is too long. */
+export function asideExcerpt(turns, max = ASIDE_MAX_CONTEXT) {
+  const lines = (Array.isArray(turns) ? turns : [])
+    .filter(t => t && typeof t.text === 'string' && t.text.trim())
+    .map(t => `${t.role === 'assistant' ? 'Quox' : 'User'}: ${t.text.trim()}`);
+  let out = '';
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const next = out ? `${lines[i]}\n\n${out}` : lines[i];
+    if (next.length > max) { if (!out) out = lines[i].slice(-max); break; }
+    out = next;
+  }
+  return out;
+}
+
+/** The request body: never a session or conversation id, always no_tools. */
+export function asideBody({ question, turns = [], agent = 'quox', maxTokens = 1024 }) {
+  const q = String(question ?? '').trim();
+  const excerpt = asideExcerpt(turns);
+  return {
+    agent_id: agent || 'quox',
+    task: q,
+    no_tools: true,
+    max_tokens: maxTokens,
+    context: excerpt ? `${ASIDE_NOTE}\n\nConversation so far (read only):\n${excerpt}` : ASIDE_NOTE,
+  };
+}
+
+/**
+ * -> { text, model, provider, tools } . Throws the client error (with .status) on a non-2xx, and an error
+ * with code 'aside_used_tools' if the server reports any tool use (it must not happen; we say so if it does).
+ */
+export async function askAside(client, { question, turns, agent, timeoutMs = 120000 }) {
+  if (!String(question ?? '').trim()) { const e = new Error('Ask a question: aside <question>'); e.code = 'usage'; throw e; }
+  const ep = resolveEndpoint('agents.invoke.notools');
+  const r = await client.post(ep.path, { service: ep.service, body: asideBody({ question, turns, agent }), retries: 0, timeout: timeoutMs });
+  if (r && r.success === false) { const e = new Error(r.error || 'the server could not answer'); e.status = 502; throw e; }
+  const tools = Array.isArray(r?.tools_used) ? r.tools_used : [];
+  if (tools.length) { const e = new Error(`the server reported tool use (${tools.join(', ')}) on a no-tools aside`); e.code = 'aside_used_tools'; throw e; }
+  return { text: String(r?.result ?? '').trim(), model: r?.usage?.model || null, provider: r?.provider || r?.usage?.provider || null, tools };
+}