quoxcli 0.0.0-stage → 0.3.1

package/lib/core/selfUpdate.js

@@ -0,0 +1,188 @@
+/**
+ * The one CLI updater (owner 2026-10-16 "we need /update", "or quox --update"): shared by /update in the
+ * conversation client and `quox update` / `quox --update` in the shell.
+ *
+ * It updates THIS quox the way it was installed, and never builds a second path where one already exists:
+ *   npm         <root> is node_modules/quoxcli        -> npm install -g quoxcli@<latest>
+ *   shared-git  the box's shared CLI tree             -> quox-cli-refresh (it refuses a dirty tree itself)
+ *   git         any other git checkout                -> git -C <root> pull --ff-only (clean and on main only)
+ *   server      a self-hosted install, at a v* tag    -> points at `quox server update` (that is its updater)
+ *   bundle      a dev-server bundle (.bundle-sha)     -> points at the server's refresh
+ * It never runs git stash, reset or checkout. Every external call is injectable (deps.run / spawn) for tests.
+ *
+ * Network: `npm view quoxcli ...` (the npm registry) and `git fetch origin main` (the tree's own remote), only
+ * when the user asks for an update. Nothing is sent but those requests.
+ */
+import { spawnSync, execFile } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import os from 'node:os';
+import { RUNNING_ROOT, findOnPath } from '../quoxon/slash/restart.js';
+import { cmpSemver } from '../server/install.js';
+import { askText } from '../quoxon/ask.js';
+
+export const NPM_PACKAGE = 'quoxcli';
+export const NOTES_MAX = 5;
+
+function defaultRun(cmd, args, { timeout = 30000 } = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout });
+  if (r.error) return { code: null, stdout: '', stderr: `${r.error.code || 'failed'}: ${r.error.message}` };
+  return { code: r.status, stdout: String(r.stdout || '').trim(), stderr: String(r.stderr || '').trim() };
+}
+
+/** The same, without blocking: the check runs while the conversation client keeps painting. */
+function asyncRun(cmd, args, { timeout = 30000 } = {}) {
+  return new Promise((done) => {
+    execFile(cmd, args, { encoding: 'utf8', timeout }, (err, stdout, stderr) => {
+      if (err && typeof err.code !== 'number') return done({ code: null, stdout: '', stderr: `${err.code || (err.killed ? 'timed out' : 'failed')}: ${String(stderr || err.message).trim()}` });
+      done({ code: err ? err.code : 0, stdout: String(stdout || '').trim(), stderr: String(stderr || '').trim() });
+    });
+  });
+}
+
+function withDeps(deps = {}, run = defaultRun) {
+  return {
+    run,
+    exists: existsSync,
+    readFile: (p) => readFileSync(p, 'utf8'),
+    realpath: (p) => { try { return realpathSync(p); } catch { return p; } },
+    findOnPath,
+    home: os.homedir(),
+    ...deps,
+  };
+}
+
+const gitOut = (d, dir, args, timeout = 5000) => {
+  const r = d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const gitOutA = async (d, dir, args, timeout = 5000) => {
+  const r = await d.run('git', ['-C', dir, ...args], { timeout });
+  return r.code === 0 ? String(r.stdout || '').trim() : null;
+};
+const lastLine = (s) => String(s || '').trim().split('\n').filter(Boolean).pop() || '';
+
+/** How this quox was installed. -> { kind, root, version, branch?, refresh?, tag? } */
+export function detectInstall({ root = RUNNING_ROOT, env = process.env, deps = {} } = {}) {
+  const d = withDeps(deps);
+  const real = d.realpath(root);
+  let version = null;
+  try { version = JSON.parse(d.readFile(join(root, 'package.json'))).version || null; } catch { /* no package.json */ }
+  if (/[/\\]node_modules[/\\]quoxcli$/.test(real)) return { kind: 'npm', root: real, version };
+  if (d.exists(join(root, '.bundle-sha'))) return { kind: 'bundle', root: real, version };
+  const top = gitOut(d, real, ['rev-parse', '--show-toplevel']);
+  if (top) {
+    const branch = gitOut(d, top, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const refresh = d.findOnPath('quox-cli-refresh', env);
+    const shared = d.realpath(env.QUOX_CLI_DIR || join(d.home, 'quox-dashboard-cli'));
+    if (refresh && d.realpath(top) === shared) return { kind: 'shared-git', root: top, refresh, branch, version };
+    if (branch === 'HEAD') {
+      const tag = gitOut(d, top, ['describe', '--tags', '--exact-match']);
+      if (tag && /^v\d/.test(tag)) return { kind: 'server', root: top, tag, version };
+    }
+    return { kind: 'git', root: top, branch, version };
+  }
+  return { kind: 'unknown', root: real, version };
+}
+
+async function checkNpm(info, d) {
+  const cur = info.version || '0.0.0';
+  const v = await d.run('npm', ['view', NPM_PACKAGE, 'version'], { timeout: 20000 });
+  if (v.code !== 0 || !v.stdout) return { ok: false, kind: 'npm', current: cur, error: `npm view ${NPM_PACKAGE} version failed: ${lastLine(v.stderr) || `exit ${v.code}`}` };
+  const latest = lastLine(v.stdout);
+  const cmd = `npm install -g ${NPM_PACKAGE}@${latest}`;
+  const base = { ok: true, kind: 'npm', current: cur, latest, notes: [], manual: cmd };
+  const c = cmpSemver(latest, cur);
+  if (c !== null && c <= 0) return { ...base, upToDate: true, ahead: c < 0, count: 0 };
+  let count = 1;
+  const all = await d.run('npm', ['view', NPM_PACKAGE, 'versions', '--json'], { timeout: 20000 });
+  try {
+    const list = JSON.parse(all.stdout);
+    const n = (Array.isArray(list) ? list : [list]).filter((x) => cmpSemver(x, cur) === 1 && cmpSemver(x, latest) <= 0).length;
+    if (n > 0) count = n;
+  } catch { /* keep 1 */ }
+  return { ...base, upToDate: false, count, command: { cmd: 'npm', args: ['install', '-g', `${NPM_PACKAGE}@${latest}`], display: cmd } };
+}
+
+async function checkGit(info, d) {
+  const { root, kind } = info;
+  const f = await d.run('git', ['-C', root, 'fetch', 'origin', 'main', '--quiet'], { timeout: 30000 });
+  if (f.code !== 0) return { ok: false, kind, error: `git -C ${root} fetch origin main failed: ${lastLine(f.stderr) || `exit ${f.code}`}` };
+  const current = await gitOutA(d, root, ['rev-parse', '--short', 'HEAD']) || '?';
+  const latest = await gitOutA(d, root, ['rev-parse', '--short', 'origin/main']) || '?';
+  const count = Number(await gitOutA(d, root, ['rev-list', '--count', 'HEAD..origin/main']) || 0) || 0;
+  const pull = `git -C ${root} pull --ff-only`;
+  const shared = kind === 'shared-git';
+  const manual = shared ? 'quox-cli-refresh' : pull;
+  const base = { ok: true, kind, root, current, latest, count, manual };
+  if (count === 0) return { ...base, upToDate: true, notes: [] };
+  const notes = (await gitOutA(d, root, ['log', '--format=%s', '-n', String(NOTES_MAX), 'HEAD..origin/main']) || '').split('\n').filter(Boolean);
+  if (shared) {
+    return { ...base, upToDate: false, notes, scope: `This runs quox-cli-refresh, which updates quox for every session on this box (${root}).`, command: { cmd: info.refresh, args: [], display: 'quox-cli-refresh' } };
+  }
+  let refused = null;
+  if (info.branch !== 'main') refused = `${root} is on branch ${info.branch || '(unknown)'}, not main. Switch to main yourself, then update again. Nothing was changed.`;
+  else {
+    const dirty = (await gitOutA(d, root, ['status', '--porcelain', '--untracked-files=no']) || '').split('\n').filter(Boolean);
+    if (dirty.length) refused = `${root} has ${dirty.length} file${dirty.length === 1 ? '' : 's'} with uncommitted changes. Commit or move them, then update again. Nothing was changed.`;
+  }
+  return { ...base, upToDate: false, notes, refused, command: refused ? null : { cmd: 'git', args: ['-C', root, 'pull', '--ff-only'], display: pull } };
+}
+
+/**
+ * What an update would do. -> { ok, kind, current, latest, count, notes[], upToDate, command?, manual, scope?, refused?, error? }
+ * refused: this install has its own updater (or is not in a state to update): say why and the manual way.
+ */
+export async function checkUpdate(info, { deps = {} } = {}) {
+  const d = withDeps(deps, asyncRun);
+  switch (info?.kind) {
+    case 'npm': return checkNpm(info, d);
+    case 'git': case 'shared-git': return checkGit(info, d);
+    case 'server': return { ok: true, kind: 'server', current: info.tag, manual: 'quox server update', refused: `This quox is part of your self-hosted Quox install (${info.tag} at ${info.root}), so it updates with the server: run quox server update (it shows the latest release and asks first).` };
+    case 'bundle': return { ok: true, kind: 'bundle', manual: null, refused: `This quox is the dev-server bundle in ${info.root}; the Quox server refreshes it while dev mode is on. Ask your admin, or install your own copy with npm install -g ${NPM_PACKAGE}@latest.` };
+    default: return { ok: true, kind: 'unknown', manual: `npm install -g ${NPM_PACKAGE}@latest`, refused: `Could not tell how this quox was installed (${info?.root || 'unknown path'}). To install the published one: npm install -g ${NPM_PACKAGE}@latest` };
+  }
+}
+
+/** Run the update with the terminal handed over (prompts, sudo). -> { ok, code } or { ok:false, error } */
+export function runUpdate(plan, { spawn = spawnSync, env = process.env } = {}) {
+  const r = spawn(plan.command.cmd, plan.command.args, { stdio: 'inherit', env });
+  if (r.error) return { ok: false, error: `${r.error.code || 'failed'}: ${r.error.message}` };
+  const code = r.status ?? (r.signal ? 128 + (os.constants.signals[r.signal] || 0) : 1);
+  return { ok: code === 0, code };
+}
+
+const isGit = (p) => p.kind === 'git' || p.kind === 'shared-git';
+
+/** The lines shown before the ask (or the one line when there is nothing to do). */
+export function updateLines(plan) {
+  if (!plan.ok) return [`Could not check for updates: ${plan.error}`];
+  if (plan.refused && plan.kind !== 'git') return [plan.refused];
+  if (plan.upToDate) return [isGit(plan) ? `quox ${plan.current} is up to date with origin/main.` : plan.ahead ? `quox ${plan.current} is newer than the published ${plan.latest}. Nothing to update.` : `quox ${plan.current} is the latest.`];
+  const out = [];
+  const notes = plan.notes || [];
+  if (notes.length) out.push(`What's new (${isGit(plan) ? 'commits on origin/main' : 'releases'}):`, ...notes.slice(0, NOTES_MAX).map((n) => `  · ${n}`));
+  if (plan.count > notes.length && notes.length) out.push(`  · and ${plan.count - notes.length} more`);
+  if (plan.kind === 'npm') out.push(`Runs: ${plan.command.display}. Release notes show after the restart (/whatsnew).`);
+  if (plan.scope) out.push(plan.scope);
+  if (plan.refused) out.push(`quox ${plan.current} -> ${plan.latest}: ${plan.count} change${plan.count === 1 ? '' : 's'}, not updated. ${plan.refused}`);
+  return out;
+}
+
+/** "▶ quox <cur> -> <latest>: <n> changes. Update now and restart? y/N/c" (the shared ask shape). */
+export function updateAsk(plan, { restart = true } = {}) {
+  const n = plan.count;
+  return askText(`Update now${restart ? ' and restart' : ''}?`, { reason: `quox ${plan.current} -> ${plan.latest}: ${n} change${n === 1 ? '' : 's'}.` });
+}
+
+/** `quox --update [...]` is `quox update [...]` when it comes before any subcommand. */
+export function rewriteUpdateFlag(argv) {
+  const VALUE = new Set(['-p', '--profile', '-o', '--output', '--org']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--update') return [...argv.slice(0, i), 'update', ...argv.slice(i + 1)];
+    if (VALUE.has(a)) { i++; continue; }
+    if (!a.startsWith('-')) return argv; // a subcommand came first: its own flags are its business
+  }
+  return argv;
+}

package/lib/core/sessionHeartbeat.js

@@ -0,0 +1,192 @@
+/**
+ * QUOXON J1: the `quox claude` wrapper's session heartbeat. The wrapper starts
+ * ONE detached `quox sessions heartbeat <tmux-session> --loop` per tmux session
+ * it launches; that child beats POST /api/v1/sessions/heartbeat every interval
+ * while the tmux session exists, then calls /api/v1/sessions/end and exits.
+ * The server expires a row after 3 missed beats, so a killed child or a
+ * powered-off box drops out on its own.
+ *
+ * Loop hygiene (house rule: failure accounting, backoff, retirement):
+ *  - a failed beat is counted and logged, never treated as success;
+ *  - consecutive failures back off exponentially, capped at maxBackoffS;
+ *  - the loop retires after maxFailures consecutive failures, when the tmux
+ *    session ends, or when it never appears within the start grace;
+ *  - a pidfile lock keeps one heartbeat per session across reattaches, and is
+ *    released on every exit path.
+ * Pure parts take injected tmux output / held slots / attach lookup.
+ */
+import { spawn as realSpawn, spawnSync as realSpawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, statSync, appendFileSync, truncateSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { slotsBySession, readAttachSafe, readHeldSlotsSafe } from './liveSessionsReport.js';
+
+export const PROBE_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{session_activity}\t#{pane_pid}\t#{pane_current_command}';
+export const DEFAULT_INTERVAL_S = 60;
+const HB_DIR = () => join(homedir(), '.quox', 'heartbeat');
+const LOG_CAP_BYTES = 256 * 1024;
+
+const isoSec = (v) => {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? new Date(n * 1000).toISOString() : null;
+};
+
+/** One line of PROBE_FORMAT output -> probe record, or null. */
+export function parseProbe(out) {
+  const first = String(out || '').split('\n').find((l) => l.trim());
+  if (!first) return null;
+  const c = first.split('\t');
+  if (c.length < 6 || !c[0]) return null;
+  const pid = Number.parseInt(c[4], 10);
+  return {
+    name: c[0],
+    started_at: isoSec(c[1]),
+    attached: Number(c[2]) > 0,
+    last_active: isoSec(c[3]),
+    pid: Number.isInteger(pid) ? pid : null,
+    command: c[5] || null,
+  };
+}
+
+/** The wrapped tmux session's bare name, as the held-slots ledger records it. */
+const bareOf = (name) => String(name).replace(/^quox-/, '');
+
+export function buildBeat({ probe, backend = null, agent = null, slot = null, held = {}, attachLookup = readAttachSafe, intervalS = DEFAULT_INTERVAL_S }) {
+  const by = slotsBySession(held);
+  const bare = bareOf(probe.name);
+  const hit = by[probe.name] || by[bare] || by[bare.replace(/^(codex-|gemini-|tui-)/, '')] || null;
+  // The pane runs claude directly, so its pid IS the attach-kit pid; the slot entry's pid is the fallback.
+  const att = (probe.pid != null && attachLookup(probe.pid)) || (hit && hit.pid != null && attachLookup(hit.pid)) || null;
+  return {
+    name: probe.name,
+    program: backend || probe.command || null,
+    pid: probe.pid,
+    started_at: probe.started_at,
+    last_active: probe.last_active,
+    attached: probe.attached,
+    slot: (hit && hit.slot) || slot || null,
+    agent: (att && att.agent) || agent || null,
+    interval_s: intervalS,
+  };
+}
+
+/** Live probe of one tmux session (exact match). null when it does not exist. */
+export function probeTmux(name, spawnSync = realSpawnSync) {
+  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}`, PROBE_FORMAT], { encoding: 'utf8' });
+  if (!r || r.error || r.status !== 0) return null;
+  const p = parseProbe(r.stdout);
+  return p && p.name === name ? p : null;
+}
+
+export async function runHeartbeatLoop({
+  tmuxName, backend = null, agent = null, slot = null, intervalS = DEFAULT_INTERVAL_S,
+  probe = (n) => probeTmux(n), post, end, held = () => readHeldSlotsSafe(), attachLookup = readAttachSafe,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), log = () => {},
+  maxFailures = 30, maxBackoffS = 600, graceMs = 30_000, gracePollMs = 2000, maxTicks = Infinity,
+  lock = { acquire: () => true, release: () => {} },
+}) {
+  if (!lock.acquire()) {
+    log(`another heartbeat already holds ${tmuxName}; exiting`);
+    return { exit: 'duplicate', beats: 0, failures: 0 };
+  }
+  let beats = 0;
+  let failures = 0;
+  let consecutive = 0;
+  let ticks = 0;
+  let seen = false;
+  let waited = 0;
+  try {
+    while (ticks < maxTicks) {
+      const p = probe(tmuxName);
+      if (!p) {
+        if (!seen && waited < graceMs) { waited += gracePollMs; await sleep(gracePollMs); continue; }
+        if (!seen) { log(`${tmuxName} never appeared; exiting`); return { exit: 'never_started', beats, failures }; }
+        try { await end(); } catch (e) { log(`end failed: ${e && e.status ? `HTTP ${e.status} ` : ''}${e && e.message}`); }
+        log(`${tmuxName} ended after ${beats} beats (${failures} failed)`);
+        return { exit: 'ended', beats, failures };
+      }
+      seen = true;
+      ticks += 1;
+      let beat;
+      try { beat = buildBeat({ probe: p, backend, agent, slot, held: held(), attachLookup, intervalS }); } catch (e) { beat = null; log(`beat build failed: ${e.message}`); }
+      try {
+        if (!beat) throw new Error('no beat');
+        await post(beat);
+        beats += 1;
+        consecutive = 0;
+      } catch (e) {
+        failures += 1;
+        consecutive += 1;
+        log(`beat failed (${consecutive} in a row, ${failures} total): ${e && e.status ? `HTTP ${e.status} ` : ''}${e && e.message}`);
+        if (consecutive >= maxFailures) {
+          log(`retiring after ${consecutive} consecutive failures`);
+          return { exit: 'retired', beats, failures };
+        }
+      }
+      const delayS = consecutive ? Math.min(intervalS * 2 ** Math.min(consecutive, 10), maxBackoffS) : intervalS;
+      await sleep(delayS * 1000);
+    }
+    return { exit: 'max_ticks', beats, failures };
+  } finally {
+    lock.release();
+  }
+}
+
+const safeFile = (name) => String(name).replace(/[^A-Za-z0-9._-]/g, '_');
+
+/** Pidfile lock under ~/.quox/heartbeat/<session>.pid; a dead holder's file is taken over. */
+export function pidLock(name, { dir = HB_DIR(), pid = process.pid, alive = isAlive } = {}) {
+  const file = join(dir, `${safeFile(name)}.pid`);
+  return {
+    acquire() {
+      try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (existsSync(file)) {
+          const other = Number.parseInt(readFileSync(file, 'utf8'), 10);
+          if (Number.isInteger(other) && other !== pid && alive(other)) return false;
+        }
+        writeFileSync(file, String(pid), { mode: 0o600 });
+        return true;
+      } catch { return false; }
+    },
+    release() {
+      try {
+        if (existsSync(file) && Number.parseInt(readFileSync(file, 'utf8'), 10) === pid) unlinkSync(file);
+      } catch { /* best effort */ }
+    },
+  };
+}
+
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e && e.code === 'EPERM'; }
+}
+
+/** Append-only per-session log, truncated when it passes LOG_CAP_BYTES. */
+export function fileLogger(name, dir = HB_DIR()) {
+  const file = join(dir, `${safeFile(name)}.log`);
+  return (msg) => {
+    try {
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      if (existsSync(file) && statSync(file).size > LOG_CAP_BYTES) truncateSync(file, 0);
+      appendFileSync(file, `${new Date().toISOString()} ${msg}\n`, { mode: 0o600 });
+    } catch { /* logging must never kill the loop */ }
+  };
+}
+
+/**
+ * Start the detached heartbeat child for a tmux session the wrapper launched.
+ * The child is this same quox binary; it survives the wrapper exiting on detach.
+ */
+export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawn = realSpawn, argv = process.argv, execPath = process.execPath } = {}) {
+  if (!argv[1]) return false;
+  const args = [argv[1], 'sessions', 'heartbeat', tmuxSession, '--loop'];
+  if (backend) args.push('--backend', backend);
+  if (agent) args.push('--agent', agent);
+  if (slot) args.push('--slot', slot);
+  try {
+    const child = spawn(execPath, args, { detached: true, stdio: 'ignore' });
+    if (child && child.on) child.on('error', () => {});
+    if (child && child.unref) child.unref();
+    return true;
+  } catch { return false; }
+}

package/lib/core/sessionsOverview.js

@@ -0,0 +1,224 @@
+/**
+ * QUOXON J2: `quox sessions` overview of GET /api/v1/sessions, grouped by
+ * agent, newest activity first. overviewLines() is plain text + a tone per
+ * line, shared by the CLI renderer (ANSI colour) and the quox conversation
+ * client's `/sessions all` (which colours by tone itself).
+ */
+import { hostname as osHostname } from 'node:os';
+import { line } from './quoxglyph.js';
+import { formatAge } from './claudeLs.js';
+import { loadNames } from '../quoxon/session.js';
+
+export const GLYPH = { working: '◐', waiting: '⏸', resting: '○', failing: '✖' };
+const TONE = { working: 'ok', waiting: 'warn', failing: 'warn', resting: 'dim' };
+const ANSI = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', dim: '\x1b[2m', accent: '\x1b[36m', reset: '\x1b[0m' };
+const stripAnsi = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, '');
+
+const clip = (v, n) => {
+  const a = [...String(v ?? '')];
+  return a.length > n ? a.slice(0, n - 1).join('') + '…' : String(v ?? '');
+};
+const pad = (v, n) => clip(v, n).padEnd(n);
+
+function kindLabel(r) {
+  if (r.kind === 'tmux') return r.backend ? `tmux·${r.backend}` : 'tmux';
+  return r.kind;
+}
+
+function hostLabel(r, localHost) {
+  if (!r.host) return r.kind === 'tmux' ? '?' : 'server';
+  return localHost && r.host === localHost ? 'this host' : r.host;
+}
+
+export const RECENT_CONVERSATIONS = 5;
+const KEEP_KINDS = new Set(['tmux', 'slot', 'resident', 'objective', 'loop', 'workflow']);
+
+/** One-line title, clipped on a word boundary when one is near the end, never mid-surrogate. */
+export function clipTitle(raw, max = 34) {
+  const s = String(raw ?? '').replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+  const a = [...s];
+  if (a.length <= max) return s;
+  const cut = a.slice(0, max - 1).join('');
+  const sp = cut.lastIndexOf(' ');
+  return (sp >= Math.floor(max / 2) ? cut.slice(0, sp) : cut).replace(/[\s,.;:-]+$/, '') + '…';
+}
+
+const timeOf = (r) => { const t = Date.parse(r.last_active); return Number.isFinite(t) ? t : -Infinity; };
+
+/**
+ * The default view shows what is useful or eventful: every tmux session, slot,
+ * resident and running piece of work, every working/waiting conversation, and
+ * only the RECENT_CONVERSATIONS most recent other conversations. `all` keeps
+ * everything. Conversation names use the local /rename name when known, else
+ * the server title. Regrouped by each row's own agent; "no agent" goes last.
+ * -> { groups, hiddenConversations, shown }
+ */
+export function prepareIndex(index, { all = false, names = {}, keep = RECENT_CONVERSATIONS } = {}) {
+  const rows = (index.groups || []).flatMap((g) => g.rows).map((r) => (r.kind === 'conversation'
+    // The hint is this client's own command, so set it here too (correct against an older server's --print hint).
+    ? { ...r, name: clipTitle((names && names[r.id] && names[r.id].name) || r.name || '(untitled)'), attach_hint: `quox --conversation ${r.id}` }
+    : r));
+  let hidden = 0;
+  let kept = rows;
+  if (!all) {
+    const quiet = rows.filter((r) => r.kind === 'conversation' && r.state !== 'working' && r.state !== 'waiting').sort((a, b) => timeOf(b) - timeOf(a));
+    const keepIds = new Set(quiet.slice(0, keep));
+    hidden = quiet.length - keepIds.size;
+    kept = rows.filter((r) => KEEP_KINDS.has(r.kind) || r.kind !== 'conversation' || r.state === 'working' || r.state === 'waiting' || keepIds.has(r));
+  }
+  const by = new Map();
+  for (const r of [...kept].sort((a, b) => timeOf(b) - timeOf(a))) {
+    const k = r.agent || null;
+    if (!by.has(k)) by.set(k, []);
+    by.get(k).push(r);
+  }
+  const groups = [...by.entries()].map(([agent, rs]) => ({ agent, rows: rs }))
+    .sort((a, b) => (a.agent === null) - (b.agent === null) || timeOf(b.rows[0]) - timeOf(a.rows[0]));
+  return { groups, hiddenConversations: hidden, shown: kept.length };
+}
+
+/** -> [{ text, tone, state? }] */
+export function overviewLines(index, { now = Date.now(), localHost = null, all = false, names = {} } = {}) {
+  const prepared = prepareIndex(index, { all, names });
+  const counts = index.counts || {};
+  const total = counts.total || 0;
+  const out = [
+    { text: stripAnsi(line('quox', 'sessions', { result: `${total} live` })), tone: 'accent' },
+    { text: `${total} live · ${counts.working || 0} working · ${counts.waiting || 0} waiting · ${counts.resting || 0} resting · ${counts.failing || 0} failing`, tone: 'dim' },
+  ];
+  if (!total) out.push({ text: 'No live sessions in this org.', tone: 'dim' });
+  for (const g of prepared.groups) {
+    out.push({ text: `${g.agent || 'no agent'} (${g.rows.length})`, tone: 'accent' });
+    for (const r of g.rows) {
+      const t = Date.parse(r.last_active);
+      const age = Number.isFinite(t) ? formatAge((now - t) / 1000) : '-';
+      const extra = [r.slot ? `slot ${r.slot}` : null, r.state_reason || null].filter(Boolean).join(', ');
+      const text = `  ${GLYPH[r.state] || '?'} ${pad(r.state, 8)} ${pad(r.name, 34)} ${pad(kindLabel(r), 13)} ${pad(hostLabel(r, localHost), 12)} ${pad(age, 5)} ${r.attach_hint || ''}${extra ? `  (${extra})` : ''}`;
+      out.push({ text, tone: TONE[r.state] || 'dim', state: r.state });
+    }
+  }
+  if (prepared.hiddenConversations > 0) {
+    out.push({ text: `  +${prepared.hiddenConversations} more conversations (last 24 h) · quox sessions --all`, tone: 'dim' });
+  }
+  const bad = (index.sources || []).filter((s) => s.state !== 'connected');
+  if (bad.length) {
+    out.push({ text: `sources: ${bad.map((s) => `${s.id}: ${s.state}${s.note ? ` (${s.note})` : ''}`).join(' · ')}`, tone: 'dim' });
+  }
+  return out;
+}
+
+/**
+ * SESSIONS (owner 2026-10-15): the quox conversation client's bare `/sessions`.
+ * Human first: every row leads with the session NAME and WHERE it runs, then
+ * how long it has been up and when it was last active. Ids and attach commands
+ * only appear with `refs` (one dim line under each row). Sections by what the
+ * thing is (terminal sessions, slots, work, chats), newest activity first.
+ * A row with no host says "host unknown"; nothing is guessed.
+ * -> [{ text, tone, state? }]
+ */
+const SECTIONS = [
+  { title: 'Terminal sessions', test: (r) => r.kind === 'tmux' },
+  { title: 'Slots', test: (r) => r.kind === 'slot' },
+  { title: 'Work', test: (r) => r.kind !== 'tmux' && r.kind !== 'slot' && r.kind !== 'conversation' },
+  { title: 'Chats', test: (r) => r.kind === 'conversation' },
+];
+
+function whereLabel(r, localHost) {
+  if (r.kind === 'conversation') return 'on the Quox server';
+  if (!r.host) return 'host unknown';
+  return localHost && r.host === localHost ? `on ${r.host} (this machine)` : `on ${r.host}`;
+}
+
+function sessionName(r) {
+  if (r.kind === 'slot') return r.holder_session || r.name || '(unnamed slot)';
+  return r.name || '(unnamed)';
+}
+
+export function humanSessionLines(index, { now = Date.now(), localHost = null, all = false, refs = false, names = {} } = {}) {
+  const prepared = prepareIndex(index, { all, names });
+  const rows = prepared.groups.flatMap((g) => g.rows).sort((a, b) => timeOf(b) - timeOf(a));
+  const counts = index.counts || {};
+  const ago = (v) => { const t = Date.parse(v); return Number.isFinite(t) ? formatAge((now - t) / 1000) : null; };
+  const out = [
+    { text: stripAnsi(line('quox', 'sessions', { result: `${counts.total || 0} live` })), tone: 'accent' },
+    { text: `${counts.working || 0} working · ${counts.waiting || 0} waiting · ${counts.resting || 0} resting · ${counts.failing || 0} failing`, tone: 'dim' },
+  ];
+  if (!rows.length) out.push({ text: 'No live sessions in this org.', tone: 'dim' });
+  for (const sec of SECTIONS) {
+    const rs = rows.filter(sec.test);
+    if (!rs.length) continue;
+    out.push({ text: `${sec.title} (${rs.length})`, tone: 'accent' });
+    for (const r of rs) {
+      const bits = [whereLabel(r, localHost)];
+      if (r.kind === 'slot' && r.holder_session && r.name && r.name !== r.holder_session) bits.push(`holds slot ${r.name}`);
+      const up = r.started_at ? ago(r.started_at) : null;
+      if (up) bits.push(`up ${up}`);
+      const act = ago(r.last_active);
+      bits.push(act ? `active ${act} ago` : 'no activity recorded');
+      const who = [r.agent ? `agent ${r.agent}` : null, r.kind === 'tmux' && r.slot ? `slot ${r.slot}` : null, r.backend || null].filter(Boolean);
+      if (who.length) bits.push(who.join(', '));
+      if (r.unread) bits.push(`${r.unread} unread`);
+      if (r.turns) bits.push(`${r.turns} turn${r.turns === 1 ? '' : 's'}`);
+      if (r.state_reason && r.state === 'failing') bits.push(r.state_reason);
+      out.push({ text: `  ${GLYPH[r.state] || '?'} ${sessionName(r)}  ${bits.join(' · ')}`, tone: TONE[r.state] || 'dim', state: r.state });
+      if (refs) out.push({ text: `      ${[r.attach_hint || null, r.id ? `id ${r.id}` : null].filter(Boolean).join(' · ')}`, tone: 'dim' });
+    }
+  }
+  if (prepared.hiddenConversations > 0) out.push({ text: `  +${prepared.hiddenConversations} older chats (last 24 h) · /sessions all`, tone: 'dim' });
+  const bad = (index.sources || []).filter((s) => s.state !== 'connected');
+  if (bad.length) out.push({ text: `could not read: ${bad.map((s) => `${s.id} (${s.state}${s.note ? `: ${s.note}` : ''})`).join(' · ')}`, tone: 'dim' });
+  if (!refs && rows.length) out.push({ text: '/sessions refs adds ids and attach commands · /sessions all includes every chat', tone: 'dim' });
+  return out;
+}
+
+export function renderOverview(index, { now = Date.now(), localHost = osHostname(), color = false, all = false, names = {} } = {}) {
+  return overviewLines(index, { now, localHost, all, names }).map((l) => {
+    if (!color) return l.text;
+    const c = l.state === 'failing' ? ANSI.fail : ANSI[l.tone] || '';
+    return `${c}${l.text}${ANSI.reset}`;
+  }).join('\n');
+}
+
+const errText = (e) => `${e && e.status ? `HTTP ${e.status}: ` : ''}${(e && e.message) || 'request failed'}`;
+
+/**
+ * Bare `quox sessions`. --json prints the raw index; --watch redraws every 2 s
+ * until interrupted. An error is printed with its status (never shown as an
+ * empty list) and exits 1; in --watch it is shown and the next refresh retries.
+ */
+export async function runSessionsOverview({ json = false, watch = false, all = false } = {}, over = {}) {
+  const d = {
+    write: (s) => process.stdout.write(s),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+    now: () => Date.now(),
+    localHost: osHostname(),
+    color: !!process.stdout.isTTY && !process.env.NO_COLOR,
+    iterations: Infinity,
+    names: undefined,
+    ...over,
+  };
+  const names = () => d.names ?? loadNames();
+  if (!d.fetchIndex) throw new Error('fetchIndex required');
+  if (!watch) {
+    try {
+      const idx = await d.fetchIndex();
+      d.write(json ? JSON.stringify(idx, null, 2) + '\n' : renderOverview(idx, { now: d.now(), localHost: d.localHost, color: d.color, all, names: names() }) + '\n');
+      return 0;
+    } catch (e) {
+      d.write(`quox sessions: ${errText(e)}\n`);
+      return 1;
+    }
+  }
+  for (let i = 0; i < d.iterations; i++) {
+    let body;
+    try {
+      const idx = await d.fetchIndex();
+      body = json ? JSON.stringify(idx) : renderOverview(idx, { now: d.now(), localHost: d.localHost, color: d.color, all, names: names() });
+    } catch (e) {
+      body = `quox sessions: ${errText(e)} (retrying)`;
+    }
+    d.write(`\x1b[2J\x1b[H${body}\n\n(refreshing every 2 s, Ctrl-C to stop)\n`);
+    await d.sleep(2000);
+  }
+  return 0;
+}