quoxcli 0.2.0 → 0.3.1

package/lib/quoxon/session.js

@@ -8,6 +8,8 @@ import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 
 export const INVITE = 'Ⓠ /rename this session · /slot <name> for an address · /attach <agent>';
+/** The new-session invite; the /slot segment only where slots are licensed (Z2H-R5 C). */
+export const inviteText = ({ slots = true } = {}) => (slots ? INVITE : 'Ⓠ /rename this session · /attach <agent>');
 export const MAX_NAME = 40;
 
 export const sessionsPath = () => join(homedir(), '.config', 'quox', 'sessions.json');
@@ -26,10 +28,10 @@ export function loadNames(path = sessionsPath()) {
 }
 
 /** -> { ok:true } | { ok:false, error }. Atomic write; never throws. */
-export function saveName(id, name, path = sessionsPath()) {
+export function saveName(id, name, path = sessionsPath(), meta = {}) {
   try {
     const all = loadNames(path);
-    all[id] = { name, updated_at: new Date().toISOString() };
+    all[id] = { name, ...(meta.profile ? { profile: meta.profile } : {}), ...(meta.org ? { org: meta.org } : {}), updated_at: new Date().toISOString() };
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
     writeFileSync(tmp, JSON.stringify(all, null, 2) + '\n', { mode: 0o600 });
@@ -38,6 +40,22 @@ export function saveName(id, name, path = sessionsPath()) {
   } catch (e) { return { ok: false, error: e?.message || 'failed' }; }
 }
 
+/**
+ * Resolve a saved name to a conversation. Entries saved under this profile (or legacy entries with no profile)
+ * win, newest updated_at first. Only other-profile entries left: one profile -> newest; several -> ambiguous.
+ * -> { id, entry } | { ambiguous: [ids] } | null
+ */
+export function pickNamed(names, want, profile) {
+  const w = String(want).trim().toLowerCase();
+  const all = Object.entries(names || {}).filter(([, v]) => v?.name && String(v.name).toLowerCase() === w);
+  if (!all.length) return null;
+  const newest = (xs) => xs.slice().sort((a, b) => String(b[1].updated_at || '').localeCompare(String(a[1].updated_at || '')))[0];
+  const mine = all.filter(([, v]) => !v.profile || v.profile === profile);
+  if (mine.length) { const [id, entry] = newest(mine); return { id, entry }; }
+  if (new Set(all.map(([, v]) => v.profile)).size > 1) return { ambiguous: all.map(([id]) => id) };
+  const [id, entry] = newest(all); return { id, entry };
+}
+
 const lev = (a, b) => {
   const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
   for (let j = 1; j <= b.length; j++) dp[0][j] = j;
@@ -47,6 +65,82 @@ const lev = (a, b) => {
   return dp[a.length][b.length];
 };
 
+/** Names compare ignoring case, hyphens, underscores and spaces: "triageq" is "triage-q". */
+export const squash = (s) => String(s ?? '').toLowerCase().replace(/[-_\s]+/g, '');
+
+/** The ONE name in `names` that equals `input` once squashed (exact match wins first); null when none or several. */
+export function uniqueSquash(input, names) {
+  const q = squash(input);
+  if (!q) return null;
+  const list = (names || []).map(n => String(n));
+  const exact = list.find(n => n.toLowerCase() === String(input).trim().toLowerCase());
+  if (exact) return exact;
+  const hits = [...new Set(list.filter(n => squash(n) === q))];
+  return hits.length === 1 ? hits[0] : null;
+}
+
+/**
+ * QUOXON-SAY-BY-SESSION: resolve what the user typed after /say to a slot. A slot name wins (exact, then a unique
+ * squash match); otherwise the slot HELD by a session of that name ("/say SITE-CLI" reaches slot cli-site).
+ * -> slot name | null.
+ */
+export function slotForName(input, rows, senders = null) {
+  return resolveSayTarget(input, rows, senders)?.slot || null;
+}
+
+/**
+ * SLOTS-REPLY: the full resolution behind slotForName. Order: a slot name, then the session HOLDING a slot, then a
+ * name that recently SPOKE with a verified from_slot (`senders`: slot messages, oldest first). The slot is the
+ * address; `name` is the session/sender name it was reached by (null for a plain slot name).
+ * -> { slot, via: 'slot'|'session'|'sender', name } | null.
+ */
+export function resolveSayTarget(input, rows, senders = null) {
+  const list = Array.isArray(rows) ? rows : [];
+  const byName = uniqueSquash(input, list.map(r => r?.name).filter(Boolean));
+  if (byName) return { slot: byName, via: 'slot', name: null };
+  const held = list.filter(r => r?.name && r?.holder_session && r?.state !== 'free');
+  const who = uniqueSquash(input, held.map(r => r.holder_session));
+  if (who) {
+    const slots = [...new Set(held.filter(r => r.holder_session === who).map(r => r.name))];
+    return slots.length === 1 ? { slot: slots[0], via: 'session', name: who } : null;
+  }
+  // A sender is known by its full label ("quox1 (Adam)") and by its head ("quox1"); the newest message wins.
+  const spoke = new Map();
+  for (const m of Array.isArray(senders) ? senders : []) {
+    const f = String(m?.from || '').trim();
+    if (!f || !m?.from_slot) continue;
+    spoke.set(f, m.from_slot);
+    const head = f.replace(/\s*\(.*\)\s*$/, '');
+    if (head && head !== f) spoke.set(head, m.from_slot);
+  }
+  const by = uniqueSquash(input, [...spoke.keys()]);
+  return by ? { slot: spoke.get(by), via: 'sender', name: by } : null;
+}
+
+/** SLOTS-REPLY: how an address is shown everywhere: the slot first, the session/display name in brackets. */
+export function addressLabel(slot, name) {
+  const s = String(slot || ''); const n = String(name || '').trim();
+  if (!n || n === s || n.startsWith(`${s} (`)) return n.startsWith(`${s} (`) ? n : s;
+  return `${s} (${n})`;
+}
+
+/**
+ * QUOXON-SAY-MISS: /say to a name that is neither a slot nor a session holding one. Say so plainly, suggest a close
+ * match, list who IS reachable (slot and the session holding it), and how the other session becomes reachable.
+ */
+export function sayMissText(input, rows, cap = 8) {
+  const list = (Array.isArray(rows) ? rows : []).filter(r => r?.name);
+  const held = list.filter(r => r.holder_session && r.state !== 'free');
+  const near = nearest(input, [...new Set([...list.map(r => r.name), ...held.map(r => r.holder_session)])], 2);
+  const reach = held.slice(0, cap).map(r => `${r.name} (${r.holder_session})`).join(', ');
+  return [
+    `Nothing called "${input}" can get a /say: it is not a slot, and no session by that name holds one.`,
+    near.length ? `Did you mean ${near.join(' or ')}?` : null,
+    `If ${input} is a running session, it needs a slot first; ask it to run: quox slot checkout <name> --create --session ${input}`,
+    reach ? `Reachable now: ${reach}${held.length > cap ? `, +${held.length - cap} more (/slots)` : ''}` : null,
+  ].filter(Boolean).join('\n');
+}
+
 const idOf = (a) => String(a?.agent_id ?? a?.id ?? a?.name ?? '');
 const nameOf = (a) => String(a?.name ?? a?.agent_id ?? a?.id ?? '');
 
@@ -59,6 +153,9 @@ export function matchAgent(input, agents) {
   const list = Array.isArray(agents) ? agents : [];
   const hit = list.find(a => idOf(a).toLowerCase() === q || nameOf(a).toLowerCase() === q);
   if (hit) return { agent: { id: idOf(hit), name: nameOf(hit) } };
+  const sq = squash(q);
+  const loose = sq ? list.filter(a => squash(idOf(a)) === sq || squash(nameOf(a)) === sq) : [];
+  if (new Set(loose.map(idOf)).size === 1) return { agent: { id: idOf(loose[0]), name: nameOf(loose[0]) } };
   const scored = list.map(a => {
     const ks = [idOf(a).toLowerCase(), nameOf(a).toLowerCase()];
     const d = Math.min(...ks.map(k => (k.includes(q) || (k && q.includes(k)) ? 0 : lev(q, k))));
@@ -66,3 +163,76 @@ export function matchAgent(input, agents) {
   }).filter(x => x.d <= Math.max(2, Math.floor(q.length / 3))).sort((x, y) => x.d - y.d || x.id.localeCompare(y.id));
   return { matches: scored.slice(0, 3).map(x => x.id) };
 }
+
+/**
+ * "/attach" argument -> { kind: 'slot'|'agent'|null, name, rest }. The FIRST token is the name; anything after it
+ * is a message for the target. `slot:x` / `agent:x` force the kind.
+ */
+export function parseTarget(input) {
+  const m = String(input || '').trim().match(/^(\S+)\s*([\s\S]*)$/);
+  if (!m) return { kind: null, name: '', rest: '' };
+  const p = m[1].match(/^(slot|agent):(.*)$/i);
+  return p ? { kind: p[1].toLowerCase(), name: p[2], rest: m[2].trim() } : { kind: null, name: m[1], rest: m[2].trim() };
+}
+
+/** Closest names to `input` among plain strings: substring either way, else edit distance. Best first, max 3. */
+export function nearest(input, names, max = 3) {
+  const q = String(input || '').trim().toLowerCase();
+  if (!q) return [];
+  return (names || []).map(n => String(n)).map(n => { const k = n.toLowerCase(); return { n, d: k.includes(q) || (k && q.includes(k)) ? 0 : lev(q, k) }; })
+    .filter(x => x.d <= Math.max(2, Math.floor(q.length / 3))).sort((a, b) => a.d - b.d || a.n.localeCompare(b.n)).slice(0, max).map(x => x.n);
+}
+
+/** Why a list call failed, in words a person can act on. 401/403 is "signed out", never a missing item. */
+export function listFailure(e, profile = null) {
+  const st = e?.status;
+  if (st === 401 || st === 403) return `signed out (HTTP ${st}). Run quox login -p ${profile || '<profile>'}.`;
+  if (st) return `HTTP ${st}`;
+  return /timed out/i.test(e?.message || '') ? 'timed out' : (e?.message || 'failed');
+}
+
+/** More free slots than this fold into one "+N free" line in /slots (TUI-UX #8). */
+export const FREE_COLLAPSE_OVER = 5;
+
+/**
+ * /slots as aligned columns, held first then newest use first (owner 2026-10-16: "messy output. I want columns. And last used
+ * date/time"). Without `cols` every slot prints in the full-width layout. With `cols` (TUI-UX #8) the table fits the terminal:
+ * the full layout when it fits, else a compact one (no HOST / absolute time, names clipped with an ellipsis), and free slots
+ * collapse into one "+N free" line unless `all`. Unread is never shown on a free slot.
+ */
+export function slotsTable(rows, { mine = null, now = Date.now(), cols = null, all = false } = {}) {
+  const t = (r) => Math.max(...['last_heartbeat_at', 'last_read_at', 'checked_out_at', 'released_at', 'created_at'].map(k => Date.parse(r[k] || '') || 0));
+  const ago = (ms) => { if (!ms) return '-'; const m = Math.max(0, Math.floor((now - ms) / 60000)); return m < 1 ? 'just now' : m < 60 ? `${m}m ago` : m < 2880 ? `${Math.round(m / 60)}h ago` : `${Math.round(m / 1440)}d ago`; };
+  const when = (ms) => (ms ? new Date(ms).toISOString().replace('T', ' ').slice(0, 16) : '-');
+  const isHeld = (r) => Boolean(r.holder_session && r.state !== 'free');
+  const sorted = [...rows].filter(r => r?.name).sort((a, b) => (isHeld(b) - isHeld(a)) || (t(b) - t(a)));
+  const limited = Number.isFinite(cols) && cols > 0;
+  const freeCount = sorted.filter(r => !isHeld(r)).length;
+  const collapse = limited && !all && freeCount > FREE_COLLAPSE_OVER; // a handful of free slots stay listed: folding one row into a summary saves nothing
+  const shown = collapse ? sorted.filter(isHeld) : sorted;
+  const unread = (r) => (r.unread_count && isHeld(r) ? String(r.unread_count) : '');
+  const nameOf = (r) => r.name + (r.name === mine ? ' *' : '');
+  const layout = (heads, cellsOf) => {
+    const head = heads, body = shown.map(cellsOf);
+    return { head, body, w: head.map((h, i) => Math.max(h.length, ...body.map(b => b[i].length))) };
+  };
+  let L = layout(['', 'SLOT', 'HOLDER', 'HOST', 'LAST USED (UTC)', 'AGO', 'UNREAD'],
+    r => [isHeld(r) ? '●' : '○', nameOf(r), isHeld(r) ? r.holder_session : 'free', r.host_id || '-', when(t(r)), ago(t(r)), unread(r)]);
+  const width = (w) => w.reduce((a, b) => a + b, 0) + 2 * (w.length - 1);
+  let compact = false;
+  if (limited && width(L.w) > cols) {
+    compact = true;
+    L = layout(['', 'SLOT', 'HOLDER', 'AGO', 'UNREAD'], r => [isHeld(r) ? '●' : '○', nameOf(r), isHeld(r) ? r.holder_session : 'free', ago(t(r)), unread(r)]);
+    // still too wide: shrink the two name columns (widest first) with a trailing ellipsis, never below 6
+    while (width(L.w) > cols) {
+      const k = L.w[1] >= L.w[2] ? 1 : 2;
+      if (L.w[k] <= 6) break;
+      L.w[k] -= 1;
+    }
+  }
+  const fit = (cell, n) => (cell.length > n ? cell.slice(0, Math.max(1, n - 1)) + '…' : cell);
+  const fmt = (cells) => cells.map((c, i) => (compact && (i === 1 || i === 2) ? fit(c, L.w[i]) : c).padEnd(L.w[i])).join('  ').trimEnd();
+  const out = [fmt(L.head), ...L.body.map(fmt)];
+  if (collapse) out.push(`+${freeCount} free (/slots all)`);
+  return out;
+}

package/lib/quoxon/sessionDead.js

@@ -0,0 +1,17 @@
+/**
+ * Is this error a dead session (sign in again) rather than a transient failure? Pure, so the
+ * headless client (api.js, `quox --print`) can ask without loading signin.js, which pulls
+ * React + Ink (~2 s cold) (QUOXON-LATENCY). signin.js re-exports it for the interactive client.
+ */
+export function isSessionDead(e) {
+  if (!e || e.transient) return false;
+  if (e.code === 'session_expired') return true;
+  return /session expired|No refresh token|please login again|no authentication token|valid jwt or service key|not signed in/i.test(e.message || '');
+}
+
+/** One line for "this window's sign-in is stale" (a command the palette tagged "(sign in)"). */
+export const SESSION_EXPIRED_LINE = "This window's sign-in expired. /login signs in again without leaving.";
+/** What to say when a palette row is chosen but cannot run: the sign-in line, or "<name> is <reason>." */
+export function signedOutNotice(name, reason) {
+  return reason === '(sign in)' ? SESSION_EXPIRED_LINE : `${name} is ${reason}.`;
+}

package/lib/quoxon/signin.js

@@ -0,0 +1,125 @@
+/**
+ * Signed-out handling for the TUI (QUOXON-Z2H): one clear card instead of scattered errors, and an in-TUI
+ * /login that uses the same login path as `quox login` (createAuth().login + verifyMfa). The password lives
+ * only in a secret box (closure): never dispatched, logged, put in history or saved. Only the email is kept
+ * (profile.last_email) so the next sign-in can prefill it.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { createSecretBox } from './connect.js';
+import { c, clip } from './theme.js';
+import { Rule } from './render.js';
+
+const h = React.createElement;
+
+/** The one-line answer to anything that needs a session while signed out. */
+export const SIGNED_OUT_LINE = 'Signed out. /login to sign in again';
+
+/** A definitive "this session is over" failure (not a transient hiccup, not a 401 from some other route). */
+export { isSessionDead, SESSION_EXPIRED_LINE, signedOutNotice } from './sessionDead.js'; // QUOXON-LATENCY: pure, kept off the Ink import path
+
+const WHY = {
+  idle_timeout: 'you were idle for longer than the idle limit',
+  max_session: 'it reached its maximum length',
+  session_revoked: 'the server revoked it (a session policy limit, an admin, or a sign-out elsewhere)'
+};
+
+/** The card text. reason = idle_timeout | max_session from the server's refresh response, else neutral. */
+export function signedOutCard(profile, reason) {
+  const why = WHY[reason];
+  return [
+    // SIGNOUT-WIPE: never quote a length here. An org policy can cap CLI sessions far below the
+    // 30-day default (24h on 2026-10-15), and a wrong number made a policy expiry look like data loss.
+    `You're signed out of ${profile} (how long a sign-in lasts is set by your Quox server's session policy).`,
+    ...(why ? [`This session ended because ${why}.`] : []),
+    'Sign in again: /login'
+  ].join(' ');
+}
+
+/** Controller for the /login card. onSignedIn() runs after a successful sign-in so the app can refresh. */
+export function createLoginController({ api, note, refresh, onSignedIn }) {
+  const pw = createSecretBox();
+  let card = null; let busy = false; let tokenForMfa = null;
+  const close = () => { pw.clear(); tokenForMfa = null; card = null; refresh(); };
+  async function submitCreds() {
+    busy = true; card.phase = 'working'; card.error = null; refresh();
+    let r;
+    try { r = await api.signIn(card.email.trim(), pw.take()); }
+    catch (e) { busy = false; if (!card) return; card.phase = 'password'; card.error = (e?.message || 'Sign in failed').replace(/\s+/g, ' '); refresh(); return; }
+    busy = false;
+    if (!card) return;
+    if (r?.mfa_required) { tokenForMfa = r.access_token; card.phase = 'mfa'; card.mfa = ''; refresh(); return; }
+    done(r);
+  }
+  async function submitMfa() {
+    busy = true; const code = card.mfa.trim(); card.phase = 'working'; refresh();
+    try { await api.verifyMfa(tokenForMfa, code); }
+    catch (e) { busy = false; if (!card) return; card.phase = 'mfa'; card.mfa = ''; card.error = (e?.message || 'MFA failed').replace(/\s+/g, ' '); refresh(); return; }
+    busy = false;
+    done({});
+  }
+  function done(r) {
+    const who = r?.user?.email || card.email.trim();
+    close();
+    note(`Signed in as ${who}.`, 'ok');
+    onSignedIn?.();
+  }
+  return {
+    isOpen: () => Boolean(card),
+    view: () => (card ? { card: { ...card }, mask: pw.mask() } : null),
+    open() {
+      if (!api.signIn) { note('Signing in is not available in this mode. Run: quox login', 'warn'); return false; }
+      pw.clear(); tokenForMfa = null;
+      const email = (api.lastEmail?.() || '').trim();
+      card = { phase: email ? 'password' : 'email', email, mfa: '', error: null };
+      refresh();
+      return true;
+    },
+    onEvent(e) {
+      if (!card) return false;
+      if (card.phase === 'working' || busy) return true;
+      const ph = card.phase;
+      if (e.type === 'paste' || e.type === 'text') {
+        const t = String(e.text || '').replace(/[\x00-\x1f\x7f]+/g, '');
+        if (ph === 'password') e.type === 'paste' ? pw.paste(t) : pw.type(t);
+        else if (ph === 'email') card.email += t.replace(/\s+/g, '');
+        else if (ph === 'mfa') card.mfa += t.replace(/\s+/g, '');
+        card.error = null; refresh(); return true;
+      }
+      if (e.type !== 'key') return true;
+      if (e.name === 'escape' || e.name === 'ctrl-c') { close(); note('Cancelled. Nothing was saved.'); return true; }
+      if (e.name === 'enter') {
+        if (ph === 'email') { if (!card.email.includes('@')) { card.error = 'Enter your email address.'; } else { card.phase = 'password'; card.error = null; } refresh(); }
+        else if (ph === 'password') { if (!pw.length()) { card.error = 'Enter your password, or Esc to cancel.'; refresh(); } else submitCreds(); }
+        else if (ph === 'mfa') { if (!card.mfa.trim()) { card.error = 'Enter the code from your authenticator app.'; refresh(); } else submitMfa(); }
+        return true;
+      }
+      if (e.name === 'backspace') {
+        if (ph === 'password') pw.backspace(); else if (ph === 'email') card.email = card.email.slice(0, -1); else card.mfa = card.mfa.slice(0, -1);
+        refresh(); return true;
+      }
+      if (e.name === 'kill-line' || e.name === 'delete-word') {
+        if (ph === 'password') pw.clear(); else if (ph === 'email') card.email = ''; else card.mfa = '';
+        refresh(); return true;
+      }
+      if (e.name === 'tab' && ph === 'password') { card.phase = 'email'; refresh(); return true; }
+      return true;
+    }
+  };
+}
+
+/** card: { phase: 'email'|'password'|'mfa'|'working', email, mfa, error }, mask */
+export function LoginCard({ card, mask, cols, profile }) {
+  const cur = (p) => (card.phase === p ? '▏' : '');
+  return h(Box, { flexDirection: 'column', width: cols, marginTop: 1 },
+    h(Rule, { cols, color: 'sky' }),
+    h(Text, { color: c('sky'), bold: true }, clip(`Ⓠ Sign in to ${profile} · your password goes to the server and is never stored`, cols)),
+    h(Text, { color: c('text') }, clip(`  email     ${card.email}${cur('email')}`, cols)),
+    card.phase !== 'email' ? h(Text, { color: c('text') }, clip(`  password  ${mask || ''}${cur('password')}`, cols)) : null,
+    card.phase === 'mfa' || (card.phase === 'working' && card.mfa) ? h(Text, { color: c('text') }, clip(`  code      ${card.mfa}${cur('mfa')}`, cols)) : null,
+    card.error ? h(Text, { color: c('warn') }, clip(`  ${card.error}`, cols)) : null,
+    h(Text, { color: c('dim') }, card.phase === 'working'
+      ? clip('  ◐ signing in…', cols)
+      : clip(`  ${card.phase === 'mfa' ? 'enter your authenticator code' : card.phase === 'email' ? 'type your email' : 'type your password'} · Enter continue · Esc cancel`, cols)),
+    h(Rule, { cols, color: 'sky' }));
+}

package/lib/quoxon/slash/agents.js

@@ -0,0 +1,112 @@
+/**
+ * Pure helpers for /agents (list picker, card, tools), /which, and the loose-command fallback.
+ * No I/O: app.js feeds real data in and prints what comes out.
+ */
+import { findEntry, suggestCommands } from '../commands.js';
+
+/** Words that are verbs of /agents, never agent names. */
+export const AGENT_RESERVED = new Set(['list', 'tools', 'show']);
+
+/**
+ * /agents argument -> { mode: 'list', filter } | { mode: 'card', name } | { mode: 'tools', name } | { mode: 'usage', text }.
+ * `list [filter]`, `show <name>`, `<name> [tools [list]]`, `tools [list] <name>` (name optional only for list).
+ */
+export function parseAgentsArgs(arg) {
+  const t = String(arg || '').trim().split(/\s+/).filter(Boolean);
+  const lc = t.map(x => x.toLowerCase());
+  if (!t.length) return { mode: 'list', filter: '' };
+  if (lc[0] === 'list') return { mode: 'list', filter: t.slice(1).join(' ') };
+  if (lc[0] === 'show') return t.length > 1 ? { mode: 'card', name: t.slice(1).join(' ') } : { mode: 'usage', text: 'Usage: /agents show <name>' };
+  if (lc[0] === 'tools') {
+    const rest = lc[1] === 'list' ? t.slice(2) : t.slice(1);
+    return rest.length ? { mode: 'tools', name: rest.join(' ') } : { mode: 'usage', text: 'Usage: /agents <name> tools' };
+  }
+  const last = lc[lc.length - 1];
+  if (last === 'tools' && t.length > 1) return { mode: 'tools', name: t.slice(0, -1).join(' ') };
+  if (last === 'list' && lc[lc.length - 2] === 'tools' && t.length > 2) return { mode: 'tools', name: t.slice(0, -2).join(' ') };
+  return { mode: 'card', name: t.join(' ') };
+}
+
+/** Agents matching the filter text (id, name or role), filter case-insensitive. */
+export function filterAgents(list, filter) {
+  const q = String(filter || '').trim().toLowerCase();
+  const rows = Array.isArray(list) ? list : [];
+  if (!q) return rows;
+  return rows.filter(a => [a.agent_id, a.name, a.role].some(v => String(v || '').toLowerCase().includes(q)));
+}
+
+const clipTo = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+/** One picker row: name, short role, status. */
+export const agentPickerRow = (a) => ({
+  key: String(a.name || a.agent_id),
+  text: `${a.role ? clipTo(String(a.role), 48) : 'no role recorded'} · ${a.status || 'status not reported'}`
+});
+
+/** Tool names grouped by their prefix (github_list_repos -> github) when the prefix is shared by 2+; the rest under "other". */
+export function toolLines(data) {
+  const nm = data?.name || data?.id || 'agent';
+  if (!Array.isArray(data?.tools)) return [[`${nm}: could not read tools${data?.toolsErr ? ` (${data.toolsErr})` : ''}`, 'warn']];
+  if (!data.tools.length) return [[`${nm} has no tools assigned.`, 'plain']];
+  const names = data.tools.map(x => (typeof x === 'string' ? x : x?.name || x?.tool_name || x?.tool_id || String(x)));
+  const pref = (n) => (n.includes('_') ? n.split('_')[0] : null);
+  const count = new Map();
+  for (const n of names) { const p = pref(n); if (p) count.set(p, (count.get(p) || 0) + 1); }
+  const groups = new Map();
+  for (const n of [...names].sort()) {
+    const p = pref(n); const g = p && count.get(p) > 1 ? p : 'other';
+    if (!groups.has(g)) groups.set(g, []);
+    groups.get(g).push(n);
+  }
+  const out = [[`${nm}: ${names.length} tool${names.length === 1 ? '' : 's'}`, 'plain']];
+  const order = [...groups.keys()].filter(g => g !== 'other').sort().concat(groups.has('other') ? ['other'] : []);
+  for (const g of order) out.push([`  ${g} (${groups.get(g).length}): ${groups.get(g).join(', ')}`, 'dim']);
+  return out;
+}
+
+// ---- /which ------------------------------------------------------------------------------------------------
+export const WHICH_KEYS = ['profile', 'org', 'agent', 'hat', 'model', 'slot', 'conversation'];
+const WHICH_ALIAS = { provider: 'model', session: 'conversation', chat: 'conversation', login: 'profile', user: 'profile' };
+
+/** d: { profile, agentLogin, org, agent, hat, model (text), slot, slotLive, conversationId, sessionName } -> [[key, text]] */
+export function whichRows(d = {}) {
+  return [
+    ['profile', `${d.profile || '?'} (${d.agentLogin ? 'agent login' : 'human login'})`],
+    ['org', d.org || '? not in this login'],
+    ['agent', d.agent || 'CommanderQ (quox)'],
+    ['hat', d.hat || 'none reported yet (shows after your first message; quox hat list for the org\'s hats)'],
+    ['model', d.model || '?'],
+    ['slot', d.slot ? `${d.slot} (${d.slotLive ? 'live stream connected' : 'live stream not connected'})` : 'none (/slot <name>)'],
+    ['conversation', `${d.conversationId || 'new (starts with your next message)'}${d.sessionName ? ` · ${d.sessionName}` : ''}`]
+  ];
+}
+
+/** arg -> { rows: [[key,text]] } | { error } */
+export function whichReply(arg, d) {
+  const q = String(arg || '').trim().toLowerCase();
+  const rows = whichRows(d);
+  if (!q) return { rows };
+  const key = WHICH_ALIAS[q] || q;
+  const hit = rows.find(r => r[0] === key);
+  return hit ? { rows: [hit] } : { error: `/which ${q}: not one I know. Try /which ${WHICH_KEYS.join(' | ')}` };
+}
+
+// ---- loose slash commands ----------------------------------------------------------------------------------
+/** Commands that only read: safe to run for the user from a loosely typed line. Everything else is suggested. */
+export const LOOSE_SAFE = new Set(['help', 'status', 'context', 'cost', 'agents', 'skills', 'memory', 'sitrep', 'away', 'workflow', 'crystal', 'proof', 'reconcile', 'tips', 'whatsnew', 'which', 'doctor', 'hat']);
+
+/**
+ * Unknown `/cmd words...`. Looks for a later word that is a real active command or alias.
+ * -> { run: '/x args' } | { suggest: '/x' } | { ask: 'words' } | null (fall back to the near-miss / Try /help line)
+ */
+export function looseCommand(cmd, restArg) {
+  const words = String(restArg || '').trim().split(/\s+/).filter(Boolean);
+  for (let i = 0; i < words.length; i++) {
+    const e = findEntry(words[i].replace(/^\//, ''));
+    if (!e || e.kind !== 'command' || e.status !== 'active') continue;
+    const rest = words.slice(i + 1).join(' ');
+    if (LOOSE_SAFE.has(e.id)) return { run: `/${e.id}${rest ? ` ${rest}` : ''}`, name: `/${e.id}` };
+    return { suggest: `/${e.id}${rest ? ` ${rest}` : ''}` };
+  }
+  if (words.length && !suggestCommands(cmd).length) return { ask: `${String(cmd).replace(/^\//, '')} ${words.join(' ')}` };
+  return null;
+}

package/lib/quoxon/slash/argSources.js

@@ -0,0 +1,65 @@
+/**
+ * QUOXON-FW6: the async sources behind registry `args` levels (slash/args.js). Each source reads
+ * the same api the command itself uses and returns [{ value, desc? }]. A source may throw; the
+ * palette caches that as empty and shows nothing (suggestions fail quietly, never an error row).
+ */
+import { CHOICES, connectedChoices, providerId } from '../model.js';
+import { liveModels } from '../modelPrefs.js';
+import { pathItems } from '../slotChat.js';
+
+/** Provider ids /connect understands (one per provider; the subscription has no key). */
+export const connectIds = () => [
+  ...new Map(
+    CHOICES.filter((c) => c.connect).map((c) => [c.connect, { value: c.connect, desc: c.name }]),
+  ).values(),
+];
+
+export function createArgSources({ api, getPrefs = () => ({ favourites: [], default: null }), getRows = () => [] }) {
+  return async function source(src, param) {
+    switch (src) {
+      case 'providers':
+        return connectIds();
+      case 'model.connected': {
+        if (!api.connections) return [];
+        const [res, caps] = await Promise.all([
+          api.connections(),
+          api.capabilities ? api.capabilities() : null,
+        ]);
+        return connectedChoices(res, caps).map((c) => ({ value: c.id, desc: c.name }));
+      }
+      case 'model.models': {
+        const id = providerId(param);
+        if (!id) return [];
+        const l = await liveModels(api, id);
+        return l.ids.map((v) => ({ value: v, desc: v === l.def ? 'newest' : '' }));
+      }
+      case 'model.favs':
+        return getPrefs().favourites.map((f, i) => ({
+          value: String(i + 1),
+          desc: `${f.provider} ${f.model}`,
+        }));
+      case 'rows':
+        return (getRows?.() || []).map((r) => ({ value: r.id, desc: r.source.type }));
+      case 'orgs':
+        return (await api.orgs()).map((o) => ({ value: o.slug || o.id, desc: o.name || '' }));
+      case 'agents':
+        return (await api.agents()).map((a) => ({
+          value: a.agent_id,
+          desc: a.name && a.name !== a.agent_id ? a.name : '',
+        }));
+      case 'fleetHosts':
+        return (await api.objects?.fleetNames?.()) || [];
+      case 'conversations':
+        return ((await api.conversations?.(15)) || []).map((c) => ({ value: String(c.id), desc: c.title || '' }));
+      case 'files': // QUOXON-MESH: /send <slot> <path>; param = the directory part typed so far
+        return pathItems(param || '', { cwd: process.cwd() });
+      case 'slots':
+        return (await api.slots()).map((s) => ({
+          value: String(s.name),
+          desc: s.holder_session ? `held by ${s.holder_session}` : s.assigned_to ? `for ${s.assigned_to}` : '',
+        }));
+      default:
+        return [];
+    }
+  };
+}

package/lib/quoxon/slash/args.js

@@ -0,0 +1,65 @@
+/**
+ * QUOXON-FW6: argument suggestions. After `/command ` the composer suggests the next word, driven
+ * by the registry: an entry may declare `args`, a list of levels. A level is
+ *   { after: [words...], choices?: [string | { value, desc }], src?: 'name', of?: <word index> }
+ * and applies when the words already typed match `after` ('*' matches any word). `src` names an
+ * async source the app resolves (slash/argSources.js) with the word at index `of` as its
+ * parameter. Levels are checked in order and the first match wins, so put specific levels before
+ * wildcard ones. The registry stays plain data and never holds a model list.
+ */
+import { findEntry } from '../commands.js';
+
+/** The draft as an argument context, or null unless it is `/command <something>` on one line. */
+export function argContext(draft) {
+  const t = String(draft ?? '');
+  if (!t.startsWith('/') || t.startsWith('//') || t.includes('\n')) return null;
+  const m = t.match(/^\/(\S+)\s([\s\S]*)$/);
+  if (!m) return null;
+  const entry = findEntry(m[1]);
+  if (!entry || entry.kind !== 'command' || entry.status !== 'active' || !Array.isArray(entry.args))
+    return null;
+  const rest = m[2];
+  const tokens = rest.split(/\s+/);
+  const partial = tokens.pop(); // '' when the draft ends in a space
+  const words = tokens.filter(Boolean);
+  return { entry, words, partial, start: t.length - partial.length };
+}
+
+const matches = (after, words) =>
+  after.length === words.length &&
+  after.every((a, i) => a === '*' || String(words[i]).toLowerCase() === String(a).toLowerCase());
+
+/** The level that suggests the next word after `words`, or null. */
+export function levelFor(entry, words) {
+  for (const lv of entry.args || []) if (matches(lv.after || [], words)) return lv;
+  return null;
+}
+
+const asItem = (x) =>
+  typeof x === 'string' ? { value: x } : { value: String(x.value), desc: x.desc || '' };
+
+/** Static choices of a level as items. */
+export const staticItems = (lv) => (lv?.choices || []).map(asItem);
+
+/** Prefix matches first, then substring; the exact sole match is dropped (nothing to add). */
+export function rankArgs(items, partial) {
+  const q = String(partial || '').toLowerCase();
+  const seen = new Set();
+  const uniq = items.map(asItem).filter((i) => i.value && !seen.has(i.value) && seen.add(i.value));
+  if (!q) return uniq;
+  const pre = uniq.filter((i) => i.value.toLowerCase().startsWith(q));
+  const sub = uniq.filter(
+    (i) => !i.value.toLowerCase().startsWith(q) && i.value.toLowerCase().includes(q),
+  );
+  const out = [...pre, ...sub];
+  return out.length === 1 && out[0].value.toLowerCase() === q ? [] : out;
+}
+
+/**
+ * What Tab does: replace the partial word; a trailing space only when another argument can
+ * follow.
+ */
+export function applyArg(draft, ctx, value) {
+  const more = levelFor(ctx.entry, [...ctx.words, value]) != null;
+  return draft.slice(0, ctx.start) + value + (more ? ' ' : '');
+}