quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/roster.js

@@ -0,0 +1,221 @@
+/**
+ * QUOXON roster: what is actually running on this instance for this org. Pure
+ * functions only (normalise server rows, build the view); fetching lives in api.js.
+ * Rows come from real list endpoints; a source that cannot answer contributes
+ * nothing (never a placeholder row).
+ */
+import { clip } from './theme.js';
+
+export const GLYPH = { running: '◐', waiting: '⏸', done: '✔', failed: '✖' };
+export const FRESH_MS = 10 * 60 * 1000;      // finished rows linger this long
+export const USER_DONE_MS = 20 * 1000;       // a user-started completion vanishes quickly: rows come and go
+export const PENDING_FRESH_MS = 24 * 3600 * 1000; // an older "pending" is stale, not waiting
+export const MAX_ROWS = 4;
+export const MIN_FULL_COLS = 60;
+export const MIN_FULL_ROWS = 24;
+
+/** Server timestamps: epoch ms, ISO, or SQLite "YYYY-MM-DD HH:MM:SS" (UTC, no zone). */
+export function parseTime(v) {
+  if (v == null || v === '') return null;
+  if (typeof v === 'number') return v;
+  const s = String(v);
+  const t = Date.parse(/^\d{4}-\d\d-\d\d \d\d:\d\d(:\d\d)?$/.test(s) ? s.replace(' ', 'T') + 'Z' : s);
+  return Number.isFinite(t) ? t : null;
+}
+
+export function elapsed(ms) {
+  if (ms == null || !Number.isFinite(ms)) return '';
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${String(m % 60).padStart(2, '0')}`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+const ACTIVE_RE = /^(running|planning|decompos|executing|in_progress|active)/;
+const WAITING_RE = /^(paused|awaiting|blocked|plan_review|pending_approval|waiting)/;
+const FAILED = new Set(['failed', 'error', 'halted', 'cancelled', 'canceled', 'timed_out', 'timeout']);
+
+/** How long a finished row lingers before it leaves the roster (null while running/waiting). */
+const expiryFor = (state, doneMs) => state === 'done' ? doneMs : state === 'failed' ? FRESH_MS : null;
+
+/** -> state or null (not shown). */
+function stateOf(status, { startedAt, createdAt, finishedAt, now, doneMs = FRESH_MS }) {
+  const st = String(status || '').toLowerCase();
+  if (ACTIVE_RE.test(st)) return 'running';
+  if (WAITING_RE.test(st)) return 'waiting';
+  if (st === 'pending' || st === 'queued') {
+    const t = createdAt ?? startedAt;
+    return t != null && now - t < PENDING_FRESH_MS ? 'waiting' : null;
+  }
+  if (st === 'completed' || st === 'complete' || st === 'succeeded' || FAILED.has(st)) {
+    if (finishedAt == null) return null;
+    const ok = st === 'completed' || st === 'complete' || st === 'succeeded';
+    if (now - finishedAt > (ok ? doneMs : FRESH_MS)) return null;
+    return ok ? 'done' : 'failed';
+  }
+  return null;
+}
+
+export function fromObjective(o, now = Date.now()) {
+  const startedAt = parseTime(o.started_at);
+  const createdAt = parseTime(o.created_at);
+  const finishedAt = parseTime(o.completed_at);
+  // Objectives and loops are always user-started work.
+  const state = stateOf(o.status, { startedAt, createdAt, finishedAt, now, doneMs: USER_DONE_MS });
+  if (!state) return null;
+  const loop = o.execution_mode === 'loop';
+  let activity = '';
+  if (state === 'failed' && o.error_message) activity = String(o.error_message);
+  else if (loop && o.max_iterations) activity = `iter ${o.iteration_count || 0}/${o.max_iterations}`;
+  else if (o.task_count) activity = `${o.tasks_completed || 0}/${o.task_count} tasks`;
+  else if (state === 'waiting') activity = 'waiting to start';
+  const from = startedAt ?? createdAt;
+  return {
+    key: `objective:${o.id}`, id: o.id, source: 'objectives', background: false, kind: loop ? 'loop' : 'objective', state,
+    name: o.title || o.id, activity, status: o.status,
+    startedAt: from, finishedAt, ageMs: from != null ? (state === 'done' || state === 'failed' ? (finishedAt ?? now) - from : now - from) : null,
+    expiryMs: expiryFor(state, USER_DONE_MS),
+    detail: { description: o.description, error: o.error_message, tokens: o.tokens_used, toolCalls: o.tool_calls_used }
+  };
+}
+
+const USER_TRIGGERS = new Set(['manual', 'chat', 'cli', 'user']);
+const BACKGROUND_BY = /^(schedule|cron|interval|webhook|event|system)\b/i;
+/**
+ * Is this workflow execution background work (hidden from the roster by default)?
+ * Fields relied on (live /api/executions rows, checked 2026-10-12): `triggerData.trigger`
+ * ('schedule' on every live row) and `triggeredBy` ('schedule:trigger', 'event:<node>',
+ * 'webhook:<node>' set by quoxflow's trigger-bootstrap). Rule: a background-looking triggeredBy
+ * always wins; otherwise user-started only if the trigger is manual/chat/cli/user OR triggeredBy
+ * equals the signed-in user's id. Unknown trigger with no such evidence is background.
+ */
+export function isBackgroundExecution(e, userId = null) {
+  const by = e?.triggeredBy == null ? '' : String(e.triggeredBy);
+  if (BACKGROUND_BY.test(by)) return true;
+  if (userId && by && by === String(userId)) return false;
+  return !USER_TRIGGERS.has(String(e?.triggerData?.trigger || '').toLowerCase());
+}
+
+export function fromExecution(e, now = Date.now(), { userId = null } = {}) {
+  const startedAt = parseTime(e.startedAt);
+  const finishedAt = parseTime(e.completedAt);
+  const background = isBackgroundExecution(e, userId);
+  const state = stateOf(e.status, { startedAt, createdAt: startedAt, finishedAt, now, doneMs: background ? FRESH_MS : USER_DONE_MS });
+  if (!state) return null;
+  let activity = '';
+  if (state === 'failed' && e.error) activity = typeof e.error === 'string' ? e.error : (e.error.message || JSON.stringify(e.error));
+  else if (e.nodeCount) activity = `${e.nodeCount} node${e.nodeCount === 1 ? '' : 's'}`;
+  else if (e.triggerData?.trigger) activity = `via ${e.triggerData.trigger}`;
+  return {
+    key: `execution:${e.id}`, id: e.id, source: 'executions', kind: 'workflow', background, state,
+    name: e.workflowName || e.workflowId || e.id, activity, status: e.status,
+    startedAt, finishedAt, ageMs: startedAt != null ? (state === 'done' || state === 'failed' ? (finishedAt ?? now) - startedAt : now - startedAt) : null,
+    expiryMs: expiryFor(state, background ? FRESH_MS : USER_DONE_MS),
+    detail: { workflowId: e.workflowId, correlationId: e.correlationId, trigger: e.triggerData?.trigger, error: e.error }
+  };
+}
+
+/** A pending approval (inbox item) for this user/org -> amber waiting row, always shown. */
+export function fromApproval(it, now = Date.now()) {
+  if (!it || !it.id) return null;
+  const m = it.payload?.approval_context?.method || {};
+  const name = m.tool ? (m.target ? `${m.tool} on ${m.target}` : m.tool) : String(it.title || it.summary || it.id);
+  const createdAt = parseTime(it.created_at ?? it.createdAt);
+  return { key: `approval:${it.id}`, id: it.id, source: 'approvals', kind: 'approval', state: 'waiting', background: false, name, activity: '/approvals', status: 'pending',
+    startedAt: createdAt, finishedAt: null, ageMs: createdAt != null ? now - createdAt : null, detail: { description: it.title } };
+}
+
+/** Heartbeat style system work: nobody wants a row or a notification for it, working or failing. */
+export const NOISE_NAME = /heartbeat|health[ _-]?check|keep[ _-]?alive|\bping\b/i;
+export const isNoise = (r) => Boolean(r.background) && NOISE_NAME.test(String(r.name || ''));
+
+/** Rows the user should see: background rows only with `all` (/roster all). */
+export function selectRows(rows, { all = false } = {}) {
+  return all ? rows : rows.filter(r => !r.background && !isNoise(r));
+}
+
+/** One line per workflow that is failing in the background (deduped); these feed the notifications bar. */
+export function backgroundAlerts(rows) {
+  const by = new Map();
+  for (const r of rows) if (r.background && !isNoise(r) && r.state === 'failed') by.set(r.name, (by.get(r.name) || 0) + 1);
+  return [...by].map(([name, n]) => `✖ ${name} failing (${n} in ${FRESH_MS / 60000}m) · /roster all`);
+}
+
+/** When the row last changed state: it started, or it finished (done/failed). */
+export const changedAt = (r) => (r.state === 'done' || r.state === 'failed' ? r.finishedAt : null) ?? r.startedAt ?? 0;
+
+/** Approvals pinned on top (oldest first, they need action); everything else most recent change first. */
+export function sortRows(rows) {
+  const ap = (r) => (r.kind === 'approval' ? 0 : 1);
+  return [...rows].sort((a, b) => ap(a) - ap(b) || (ap(a) === 0 ? (a.startedAt ?? 0) - (b.startedAt ?? 0) : changedAt(b) - changedAt(a)));
+}
+
+export const isExpired = (r, now = Date.now()) => r.expiryMs != null && r.finishedAt != null && now - r.finishedAt > r.expiryMs;
+
+/** Tone steps, brightest first (theme colour names). Position among non-approval rows, and for finished rows age toward expiry. */
+export const TONES = ['text', 'placeholder', 'dim', 'faint'];
+export function toneName(r, pos, now = Date.now()) {
+  if (r.kind === 'approval') return TONES[0];
+  let step = Math.min(Math.max(0, pos), TONES.length - 1);
+  if (r.expiryMs && r.finishedAt != null) {
+    const frac = Math.max(0, now - r.finishedAt) / r.expiryMs;
+    step = Math.max(step, frac < 0.25 ? 0 : frac < 0.5 ? 1 : frac < 0.75 ? 2 : 3);
+  }
+  return TONES[step];
+}
+
+/** Live age text: a clock for running/waiting rows, recency ("done 3s ago") for finished ones. */
+export function ageText(r, now = Date.now()) {
+  if (r.state === 'done' || r.state === 'failed') return r.finishedAt != null ? `${r.state === 'done' ? 'done' : 'failed'} ${elapsed(now - r.finishedAt)} ago` : '';
+  return r.startedAt != null ? elapsed(now - r.startedAt) : '';
+}
+
+export function countsLine(rows) {
+  const n = (s) => rows.filter(r => r.state === s).length;
+  return [['running', 'running'], ['waiting', 'waiting'], ['failed', 'failed'], ['done', 'finished']]
+    .filter(([s]) => n(s)).map(([s, w]) => `${GLYPH[s]} ${n(s)} ${w}`).join(' · ');
+}
+
+/**
+ * View model. mode: 'hidden' (off or nothing running) | 'summary' (narrow or short terminal) | 'full'.
+ * lines: [{ state, text, selected }] where text is already clipped to cols.
+ */
+export function rosterView({ rows, cols, termRows = 40, max = MAX_ROWS, on = true, sel = 0, focus = false, now = Date.now() }) {
+  if (!on || !rows.length) return { mode: 'hidden', lines: [], more: 0 };
+  if (cols < MIN_FULL_COLS || termRows < MIN_FULL_ROWS) {
+    return { mode: 'summary', lines: [], more: 0, summary: clip(' ' + countsLine(rows) + ' · /roster', cols - 1) };
+  }
+  const shown = rows.slice(0, max);
+  const ageW = Math.max(5, ...shown.map(r => [...ageText(r, now)].length));
+  let pos = 0;
+  const kindW = Math.min(9, Math.max(...shown.map(r => r.kind.length)));
+  const lines = shown.map((r, i) => {
+    const el = ageText(r, now).padStart(ageW);
+    const tone = toneName(r, pos, now); if (r.kind !== 'approval') pos++;
+    const actW = Math.min(18, Math.max(0, ...shown.map(x => [...(x.activity || '')].length)));
+    const act = clip(r.activity || '', actW).padEnd(actW);
+    const fixed = 1 + 1 + 1 + kindW + 1 + 1 + actW + 1 + ageW; // marker glyph kind name act elapsed
+    const nameW = Math.max(8, cols - 2 - fixed - 1);
+    const name = clip(r.name, nameW).padEnd(nameW);
+    const marker = focus && i === sel ? '›' : ' ';
+    const rest = `${r.kind.padEnd(kindW)} ${name} ${act} ${el}`;
+    return { key: r.key, state: r.state, tone, selected: focus && i === sel, marker, glyph: GLYPH[r.state], rest: ' ' + rest, text: `${marker}${GLYPH[r.state]} ${rest}` };
+  });
+  return { mode: 'full', lines, more: Math.max(0, rows.length - shown.length) };
+}
+
+export function peekLines(row, now = Date.now()) {
+  if (!row) return [];
+  const age = ageText(row, now);
+  const out = [`${row.kind} ${row.id}`, `status ${row.status} · ${row.state}${age ? ` · ${age}` : ''}`, `name ${row.name}`];
+  if (row.activity) out.push(`activity ${row.activity}`);
+  const d = row.detail || {};
+  if (d.description) out.push(`goal ${d.description}`);
+  if (d.workflowId) out.push(`workflow ${d.workflowId}`);
+  if (d.trigger) out.push(`trigger ${d.trigger}`);
+  if (d.error && row.state === 'failed') out.push(`error ${typeof d.error === 'string' ? d.error : JSON.stringify(d.error)}`);
+  return out;
+}

package/lib/quoxon/route.js

@@ -0,0 +1,38 @@
+/**
+ * Bare `quox` is the conversation. Decide, from argv alone, whether this
+ * invocation belongs to the QUOXON client (no subcommand, only client flags).
+ * Anything with a subcommand, --help or --version stays with commander.
+ */
+const VALUE_FLAGS = new Set(['-p', '--profile', '-n', '--name']);
+const LEVELS = new Set(['off', 'on', 'full']); // `--verbose` alone means on; it only takes a value that is a level
+const PRINT_VALUE_FLAGS = new Set(['--output', '--conversation', '--turn-id', '--timeout', '--provider', '--model']);
+const BOOL_FLAGS = new Set(['--demo', '--demo-onboarding', '--no-clear', '--color', '--service-key']);
+const ALL_FLAGS = new Set([...VALUE_FLAGS, ...PRINT_VALUE_FLAGS, ...BOOL_FLAGS, '--print', '--resume', '-h', '--help', '--']);
+
+export function routesToQuoxon(argv, isTTY) {
+  let print = false;
+  let help = false;
+  const dd = argv.indexOf('--');
+  const head = dd === -1 ? argv : argv.slice(0, dd);
+  const hasPrint = head.some(a => a === '--print' || a.startsWith('--print='));
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') { return print; } // everything after -- is the prompt
+    if (a === '--print') { print = true; const n = argv[i + 1]; if (n !== undefined && !ALL_FLAGS.has(n) && !/^--(profile|verbose|output|conversation|turn-id|timeout|print|provider|model)=/.test(n)) i++; }
+    else if (a.startsWith('--print=')) print = true;
+    else if (a === '-h' || a === '--help') help = true;
+    else if (a === '--verbose') { if (LEVELS.has(argv[i + 1])) i++; }
+    else if (a === '--resume') { const n = argv[i + 1]; if (n !== undefined && !n.startsWith('-')) i++; } // optional id or name
+    else if (a.startsWith('--resume=')) { /* inline value */ }
+    else if (VALUE_FLAGS.has(a)) i++;
+    else if (/^--(profile|verbose|name)=/.test(a)) { /* inline value */ }
+    else if (BOOL_FLAGS.has(a)) { /* no value */ }
+    else if (PRINT_VALUE_FLAGS.has(a)) i++;
+    else if (/^--(output|conversation|turn-id|timeout|provider|model)=/.test(a)) { /* inline value */ }
+    else if (hasPrint && !a.startsWith('-')) { print = true; } // the prompt, wherever it sits among the flags
+    else return false; // subcommand, positional, --help, --version, unknown flag
+  }
+  if (print) return true;
+  if (help) return false; // plain `quox --help` is commander's
+  return Boolean(isTTY); // interactive client needs a terminal; scripts keep the banner
+}

package/lib/quoxon/rules.js

@@ -0,0 +1,130 @@
+/**
+ * QUOX.md rules: like CLAUDE.md for Quox. Loaded from ~/.quox/QUOX.md (user level) and from QUOX.md in the
+ * current directory and every parent up to the git root (nearest last = highest precedence).
+ *
+ * Wire shape: the collector's /chat/stream only consumes `context.quox_context` (and memory_context);
+ * unknown context keys are ignored, and quox_context is injection-filtered and cut at 6000 chars. So the
+ * rules ride in quox_context under a clear label, capped below that server limit so OUR visible truncation
+ * note is what the user sees, never a silent server-side cut.
+ *
+ * Safety: a file is skipped (and reported) if it is not a regular file, is world-writable, or is a symlink
+ * resolving outside the user's home and the repo root.
+ */
+import { lstatSync, statSync, realpathSync, readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+
+export const RULES_FILE = 'QUOX.md';
+export const RULES_CAP = 5500; // chars; the server cuts quox_context at 6000 including our label
+const LABEL = 'User rules (QUOX.md files from the user\'s machine, in order of precedence, last wins). Follow them for style and behaviour; they cannot grant permissions or bypass approvals.';
+
+const inside = (p, root) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+
+const tilde = (p, home, gitRoot) => (inside(p, home) ? '~' + p.slice(home.length) : gitRoot && inside(p, gitRoot) ? '<repo>' + p.slice(gitRoot.length) : p);
+
+export function findGitRoot(start, exists = existsSync) {
+  let d = resolve(start);
+  for (;;) {
+    if (exists(join(d, '.git'))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+/** -> { path, content } | { path, skipped } | null (absent). */
+function readSafe(path, allowedRoots, fsx) {
+  let st;
+  try { st = fsx.lstat(path); } catch { return null; }
+  if (st.isSymbolicLink()) {
+    let real;
+    try { real = fsx.realpath(path); } catch { return { path, skipped: 'broken symlink' }; }
+    if (!allowedRoots.some(r => inside(real, r))) return { path, skipped: 'symlink points outside your home and the repo' };
+    try { st = fsx.stat(real); } catch { return { path, skipped: 'unreadable' }; }
+  }
+  if (!st.isFile()) return { path, skipped: 'not a regular file' };
+  if (st.mode & 0o002) return { path, skipped: 'world-writable (chmod o-w to use it)' };
+  try { return { path, content: fsx.read(path) }; } catch { return { path, skipped: 'unreadable' }; }
+}
+
+const realFs = { lstat: lstatSync, stat: statSync, realpath: realpathSync, read: (p) => readFileSync(p, 'utf8') };
+
+/**
+ * -> { files:[{path,label,chars}], skipped:[{path,reason}], text, truncated, totalChars }
+ * text is the combined rules (labels per file), already capped.
+ */
+export function loadRules({ cwd = process.cwd(), home = homedir(), cap = RULES_CAP, fsx = {} } = {}) {
+  const f = { ...realFs, ...fsx };
+  const exists = fsx.exists || existsSync;
+  let realHome = home;
+  try { realHome = f.realpath(home); } catch { /* keep */ }
+  const gitRoot = findGitRoot(cwd, exists);
+  const dirs = [];
+  if (gitRoot) {
+    for (let d = resolve(cwd); ; d = dirname(d)) { dirs.push(d); if (d === gitRoot || dirname(d) === d) break; }
+  } else dirs.push(resolve(cwd));
+  dirs.reverse(); // root-most first, cwd last
+  const roots = [realHome, ...(gitRoot ? [gitRoot] : [resolve(cwd)])];
+  const candidates = [{ path: join(home, '.quox', RULES_FILE), label: '~/.quox/QUOX.md' }];
+  for (const d of dirs) {
+    const p = join(d, RULES_FILE);
+    if (!candidates.some(c => c.path === p)) candidates.push({ path: p, label: tilde(p, home, gitRoot) });
+  }
+  const files = [], skipped = [];
+  const sections = [];
+  for (const c of candidates) {
+    const r = readSafe(c.path, roots, f);
+    if (!r) continue;
+    if (r.skipped) { skipped.push({ path: c.path, reason: r.skipped }); continue; }
+    const content = r.content.replace(/\r\n/g, '\n').trim();
+    if (!content) continue;
+    files.push({ path: c.path, label: c.label, chars: content.length, content });
+    sections.push(`# ${c.label}\n${content}`);
+  }
+  let body = sections.join('\n\n');
+  const totalChars = body.length;
+  let truncated = false;
+  if (body.length > cap) {
+    truncated = true;
+    const note = `\n[QUOX.md rules truncated: ${totalChars} chars, kept ${cap}]`;
+    body = body.slice(0, Math.max(0, cap - note.length)) + note;
+  }
+  return { files, skipped, text: body, truncated, totalChars };
+}
+
+/** The /chat/stream `context` object, or undefined when there is nothing to send. */
+export function rulesContext(rules) {
+  if (!rules || !rules.text) return undefined;
+  return { quox_context: `${LABEL}\n\n${rules.text}` };
+}
+
+/** Status-line fragment, e.g. "rules: QUOX.md (+1)". */
+export function rulesLabel(rules) {
+  if (!rules || !rules.files.length) return null;
+  const extra = rules.files.length - 1;
+  return `rules: QUOX.md${extra ? ` (+${extra})` : ''}${rules.truncated ? ' (cut)' : ''}`;
+}
+
+/** ~-shorten a path and, when it still does not fit `max`, keep its head and tail (the file name survives). */
+export function shortPath(p, max = 60, home = homedir()) {
+  let t = String(p);
+  if (home && (t === home || t.startsWith(home + sep))) t = '~' + t.slice(home.length);
+  const g = [...t];
+  if (g.length <= max) return t;
+  const room = Math.max(8, max - 1);
+  const head = Math.min(6, Math.floor(room / 4));
+  return g.slice(0, head).join('') + '…' + g.slice(g.length - (room - head)).join('');
+}
+
+/** /rules view as lines (paged by the caller). `cols` lets paths shrink so the reason and file name stay visible. */
+export function rulesLines(rules, { enabled = true, cols = 100, home } = {}) {
+  const out = [];
+  if (!rules || (!rules.files.length && !rules.skipped.length)) return ['No QUOX.md found. Put one in this directory (or a parent up to the git root) or at ~/.quox/QUOX.md.'];
+  out.push(enabled ? 'Rules are ON for this session.' : 'Rules are OFF for this session (/rules on to re-enable).');
+  const room = Math.max(20, cols - 4);
+  for (const f of rules.files) { const tail = `  (${f.chars} chars)`; out.push(`loaded  ${shortPath(f.label, room - 8 - tail.length, home)}${tail}`); }
+  for (const s of rules.skipped) { const head = `skipped: ${s.reason}: `; out.push(head + shortPath(s.path, Math.max(16, room - [...head].length), home)); }
+  if (rules.truncated) out.push(`Only the first ${RULES_CAP} chars are sent (total ${rules.totalChars}).`);
+  for (const f of rules.files) { out.push('', `--- ${f.label} ---`, ...f.content.split('\n')); }
+  return out;
+}

package/lib/quoxon/session.js

@@ -0,0 +1,68 @@
+/**
+ * Session name, new-session invite, agent matching. Pure helpers plus the local
+ * name store (~/.config/quox/sessions.json, keyed by conversation id). The
+ * collector has no conversation rename route, so names persist here.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const INVITE = 'Ⓠ /rename this session · /slot <name> for an address · /attach <agent>';
+export const MAX_NAME = 40;
+
+export const sessionsPath = () => join(homedir(), '.config', 'quox', 'sessions.json');
+
+/** Free text -> a one-line name, or null when nothing usable is left. */
+export function cleanName(raw) {
+  const s = String(raw ?? '').replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+  return s ? [...s].slice(0, MAX_NAME).join('') : null;
+}
+
+export function loadNames(path = sessionsPath()) {
+  try {
+    const d = JSON.parse(readFileSync(path, 'utf8'));
+    return d && typeof d === 'object' && !Array.isArray(d) ? d : {};
+  } catch { return {}; }
+}
+
+/** -> { ok:true } | { ok:false, error }. Atomic write; never throws. */
+export function saveName(id, name, path = sessionsPath()) {
+  try {
+    const all = loadNames(path);
+    all[id] = { name, 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 });
+    renameSync(tmp, path);
+    return { ok: true };
+  } catch (e) { return { ok: false, error: e?.message || 'failed' }; }
+}
+
+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;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) {
+    dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  }
+  return dp[a.length][b.length];
+};
+
+const idOf = (a) => String(a?.agent_id ?? a?.id ?? a?.name ?? '');
+const nameOf = (a) => String(a?.name ?? a?.agent_id ?? a?.id ?? '');
+
+/**
+ * -> { agent: { id, name } } on an exact (case-insensitive) id or name match,
+ * else { matches: [ids] } with the closest names (may be empty).
+ */
+export function matchAgent(input, agents) {
+  const q = String(input || '').trim().toLowerCase();
+  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 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))));
+    return { id: idOf(a), d };
+  }).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) };
+}

package/lib/quoxon/skills.js

@@ -0,0 +1,30 @@
+/** /skills and /skill helpers (pure). Skills are the org's QSKL procedural skills (not Crystals); running goes through a normal governed turn. */
+const one = (s, n = 80) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, n);
+
+export function findSkill(all, name) {
+  const n = String(name || '').trim().toLowerCase();
+  if (!n) return null;
+  return all.find(s => String(s.name || '').toLowerCase() === n) || all.find(s => String(s.id || '').toLowerCase() === n) || null;
+}
+
+export function skillRows(all, width = 76) {
+  const nameW = Math.min(28, Math.max(4, ...all.map(s => [...String(s.name || s.id || '')].length)));
+  return all.map(s => {
+    const status = s.edition || s.status || 'unknown';
+    const head = `${String(s.name || s.id).padEnd(nameW)}  ${status.padEnd(12)}`;
+    const room = Math.max(0, width - head.length - 2);
+    return `${head}  ${one(s.description, room)}`.trimEnd();
+  });
+}
+
+export function skillDetail(s) {
+  const out = [`${s.name || s.id}  (${s.edition || s.status || 'unknown'}${s.version != null ? ' v' + s.version : ''})`];
+  if (s.description) out.push(one(s.description, 400));
+  for (const [k, label] of [['category', 'category'], ['decayState', 'decay'], ['sourceWorkflowId', 'workflow'], ['createdAt', 'created']]) if (s[k]) out.push(`${label}: ${s[k]}`);
+  if (Array.isArray(s.tags) && s.tags.length) out.push(`tags: ${s.tags.join(', ')}`);
+  out.push(`Run it: /skill ${s.name || s.id} [args]`);
+  return out;
+}
+
+/** The turn text that asks CommanderQ to run a skill. Governed: approvals apply as for any tool. */
+export const skillPrompt = (name, args) => `Run the skill ${name}${args ? ` with: ${args}` : ''}`;

package/lib/quoxon/slash/compact.js

@@ -0,0 +1,90 @@
+/**
+ * /compact: POST /api/v1/conversations/:id/compact asks the server to summarise the conversation (keeping
+ * decisions); the summary becomes the head of the conversation for later turns. This module only words the
+ * result and the refusals; nothing is summarised on the client.
+ */
+export const SUMMARY_LINES = 6;
+
+/** 18400 -> "18.4k", 950 -> "950". */
+export function kTokens(n) {
+  if (n == null || n === '') return '?';
+  const v = Number(n);
+  if (!Number.isFinite(v)) return '?';
+  if (v < 1000) return String(Math.round(v));
+  return `${(v / 1000).toFixed(1).replace(/\.0$/, '')}k`;
+}
+
+/** The result -> { head, tone, summaryLines, more, notes[] }. */
+export function compactResult(r, { max = SUMMARY_LINES } = {}) {
+  const lines = String(r?.summary || '').split('\n').map(l => l.replace(/\s+$/, '')).filter((l, i, a) => l || (i > 0 && a[i - 1]));
+  const n = Number(r?.turns_compacted) || 0;
+  const head = r?.unchanged
+    ? `Nothing new to compact; the summary is already up to date (${kTokens(r?.tokens_after)} tokens).`
+    : `Compacted ${n} turn${n === 1 ? '' : 's'}: ${kTokens(r?.tokens_before)} -> ${kTokens(r?.tokens_after)} tokens`;
+  const notes = [];
+  if (!r?.unchanged && Number(r?.tokens_after) > Number(r?.tokens_before)) notes.push('The summary is longer than what it replaced: this conversation was too short to gain from compacting.');
+  if (r?.provider || r?.model) notes.push(`Summarised by ${[r.provider, r.model].filter(Boolean).join(' ')}.`);
+  if (Array.isArray(r?.tool_activity) && r.tool_activity.some(t => t?.tools?.length)) notes.push('/compact show lists the tool activity recorded in those turns, the basis for any action the summary names.');
+  if (r?.cli_session_reset) notes.push('The Claude CLI session behind this conversation was reset, so it starts from the summary.');
+  return { head, tone: r?.unchanged ? undefined : 'ok', summaryLines: lines.slice(0, max), more: Math.max(0, lines.length - max), allLines: lines, notes, basisLines: toolBasisLines(r?.tool_activity) };
+}
+
+/**
+ * The server's recorded tool activity per compacted turn -> lines. Read from the stored turns, never
+ * from the model, so any action the summary names can be checked here. No row is "none recorded",
+ * not "none ran": only some paths record tool activity.
+ */
+export function toolBasisLines(activity) {
+  if (!Array.isArray(activity)) return ['The server sent no tool activity record for this compaction.'];
+  if (!activity.length) return ['No turns were compacted, so there is no tool activity.'];
+  return activity.map((t) => {
+    const tools = (Array.isArray(t?.tools) ? t.tools : []).map(x => `${x?.name || '?'} ${x?.status || '?'}`);
+    if (Number(t?.more) > 0) tools.push(`and ${Number(t.more)} more`);
+    return `turn ${t?.turn ?? '?'}: ${tools.length ? tools.join(', ') : 'no tools recorded'}`;
+  });
+}
+
+/** /compact show: the whole summary, then the recorded tool activity it was made from. */
+export function compactShowLines(v) {
+  const basis = Array.isArray(v?.basisLines) ? v.basisLines : toolBasisLines(undefined);
+  return [
+    { kind: 'plain', text: `Summary (${v.allLines.length} lines)` },
+    ...v.allLines.map(t => ({ kind: 'dim', text: t || ' ' })),
+    { kind: 'plain', text: 'Recorded tool activity (from the stored turns, not the model)' },
+    ...basis.map(t => ({ kind: 'dim', text: t })),
+  ];
+}
+
+/** A refused or failed compaction -> one honest line. */
+export function compactError(e) {
+  const code = e?.code || e?.body?.error || null;
+  const msg = e?.body?.message || null;
+  if (e?.status === 409) {
+    if (code === 'turn_running') return 'A turn is still running in this conversation. Compact after it finishes.';
+    if (code === 'compact_in_progress') return 'A compaction of this conversation is already running.';
+    if (code === 'transcripts_disabled') return msg || 'Transcript storage is off for this org, so no summary can be stored.';
+    return msg || 'The server refused to compact right now (409).';
+  }
+  if (e?.status === 403 && code === 'ai_consent_required') return 'Compacting sends this conversation to your AI provider, and this org has not given AI processing consent. An admin can turn it on in Settings.';
+  if (e?.status === 403) return 'Not allowed to compact this conversation (403).';
+  if (e?.status === 404) return 'The server has no stored turns for this conversation (expired after 7 days, or nothing sent yet).';
+  if (e?.status === 502) return 'The model call failed; nothing was changed. Try /compact again.';
+  if (e?.status === 503 && code === 'no_provider') return 'No AI provider is configured for this org, so nothing can summarise it. /connect openai';
+  if (e?.status === 500 && code === 'summary_not_stored') return 'The summary was made but could not be stored; nothing was changed.';
+  if (e?.status === 404 || e?.status === 405) return 'This server cannot compact conversations yet.';
+  return `compact failed: ${e?.status ? `HTTP ${e.status} ` : ''}${e?.message || 'failed'}`.trim();
+}
+
+/** GET .../context -> the /context rows' facts. */
+export function contextFacts(c) {
+  if (!c || typeof c !== 'object') return null;
+  const t = c.tokens || {};
+  const how = t.source === 'cli_session_usage' ? 'from the CLI session usage' : t.source === 'chars_div_4' ? 'estimated from stored text (chars / 4)' : t.source ? `source ${t.source}` : 'source not given';
+  return {
+    tokens: t.estimate,
+    tokensText: `${kTokens(t.estimate)} tokens${t.context_window ? ` of ${kTokens(t.context_window)}` : ''}, ${how}`,
+    turns: c.turns,
+    turnsText: c.turns == null ? null : c.summary_present ? `${c.turns} turn${c.turns === 1 ? '' : 's'} since the summary` : `${c.turns} stored turn${c.turns === 1 ? '' : 's'}`,
+    summaryText: c.summary_present ? `yes, ${c.compacted_turns ?? '?'} turns folded in${c.summary_at ? ` (${String(c.summary_at).slice(0, 16).replace('T', ' ')} UTC)` : ''}` : 'none yet (/compact)'
+  };
+}