quoxcli 0.0.0-stage → 0.3.1

package/lib/commands/chat.js

@@ -0,0 +1,295 @@
+/**
+ * Chat commands: send, stream, status
+ */
+
+import chalk from 'chalk';
+import { formatDetail } from '../core/output.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+/**
+ * Build the POST body for /chat/stream (quox#782). The prompt and context
+ * travel in the JSON body, never in the URL. The name is kept for callers;
+ * the collector reads `assistant` (not `selected_agent`, the POST /chat key).
+ */
+export function buildStreamQuery({ queryId, message, agent, sessionId, context }) {
+  const body = {
+    query_id: queryId,
+    prompt: message,
+    assistant: agent || 'quox',
+  };
+  if (sessionId) body.session_id = sessionId;
+  try {
+    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    if (tz) body.timezone = tz;
+  } catch { /* best-effort */ }
+  if (context) body.context = context;
+  return body;
+}
+
+/**
+ * TUI-DIVIDER: `quox chat --trace` prints the turn's protocol events as they arrive, so the
+ * per-layer AOCL record (`aocl.layer`: id, name, result, ms) is visible in the CLI before any
+ * UI animates it. Returns { text, tone } or null for an event --trace does not show.
+ * tone: ok | warn | fail | accent (no grey: every tone is a real colour).
+ */
+const RESULT_TONE = { pass: 'ok', gated: 'warn', blocked: 'fail', bypass: 'accent' };
+const fmtTraceMs = (ms) => {
+  const n = Number(ms);
+  if (!Number.isFinite(n)) return '';
+  return n < 10 ? `${Math.round(n * 10) / 10} ms` : `${Math.round(n)} ms`;
+};
+export function formatTraceEvent(ev) {
+  if (!ev || typeof ev !== 'object') return null;
+  switch (ev.type) {
+    case 'turn.started':
+      return { text: `▸ turn.started  ${[ev.provider, ev.model].filter(Boolean).join(' ')}`, tone: 'accent' };
+    case 'aocl.layer': {
+      const result = String(ev.result || 'pass');
+      const line = `▤ aocl.layer  ${String(ev.id || '?').padEnd(4)}${String(ev.name || '').padEnd(10)}${result.padEnd(8)}${fmtTraceMs(ev.ms).padStart(8)}  ${ev.phase || ''}${ev.reason ? `  ${ev.reason}` : ''}`;
+      return { text: line, tone: RESULT_TONE[result] || 'accent' };
+    }
+    case 'aocl.summary':
+      return { text: `▤ aocl.summary ${ev.accounted ?? '?'}/${ev.total ?? '?'} accounted · ${ev.passed ?? 0} passed · ${ev.bypassed ?? 0} bypassed · ${ev.rejected ?? 0} rejected${ev.ms != null ? ` · ${fmtTraceMs(ev.ms)}` : ''}`, tone: ev.rejected ? 'fail' : 'ok' };
+    case 'aocl.verdict':
+      return { text: `▤ aocl.verdict ${ev.layer || 'L8'} ${ev.verdict}${ev.reason ? `: ${ev.reason}` : ''}`, tone: ev.verdict === 'blocked' ? 'fail' : 'warn' };
+    case 'trace':
+      return { text: `· trace ${ev.protocol || ''} ${ev.label || ''}${ev.detail ? `  ${ev.detail}` : ''}`, tone: 'accent' };
+    case 'turn.finished':
+      return { text: `▸ turn.finished ${ev.status || ''}${ev.usage?.elapsed_ms != null ? ` · ${ev.usage.elapsed_ms} ms` : ''}`, tone: ev.status === 'completed' ? 'ok' : 'fail' };
+    default:
+      return null;
+  }
+}
+const TONE_PAINT = { ok: chalk.green, warn: chalk.yellow, fail: chalk.red, accent: chalk.cyan };
+function printTrace(ev) {
+  const f = formatTraceEvent(ev);
+  if (f) process.stderr.write((TONE_PAINT[f.tone] || chalk.cyan)(f.text) + '\n');
+}
+
+function generateQueryId() {
+  return `CLI_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Consume a chat SSE stream, printing chunks as they arrive.
+ * Returns { text, sessionId, agentUsed } once the stream completes.
+ */
+export async function consumeStream(client, { message, agent, sessionId, context }, { onAgentLabel, trace = false } = {}) {
+  const queryId = generateQueryId();
+  const body = buildStreamQuery({ queryId, message, agent, sessionId, context });
+
+  let text = '';
+  let resultSessionId = sessionId;
+  let agentUsed = agent;
+  let labelPrinted = false;
+  let sawChunk = false;
+
+  const printLabel = () => {
+    if (labelPrinted) return;
+    labelPrinted = true;
+    onAgentLabel?.(agentUsed);
+  };
+
+  const iter = client.stream(resolveEndpoint('chat.stream').path, { service: resolveEndpoint('chat.stream').service, body, untilClose: Boolean(trace) })[Symbol.asyncIterator]();
+  while (true) {
+    let step;
+    try {
+      step = await iter.next();
+    } catch (err) {
+      // A refusal before the stream opened carries the layers it really evaluated.
+      if (trace && Array.isArray(err?.body?.aocl_layers)) for (const l of err.body.aocl_layers) printTrace({ type: 'aocl.layer', ...l });
+      throw err;
+    }
+    if (step.done) break;
+    const event = step.value;
+    if (trace) printTrace(event);
+    switch (event.type) {
+      case 'connected':
+        break;
+
+      case 'thinking': {
+        const stage = event.stage || '';
+        if (stage === 'tool_call' || stage.includes('tool')) {
+          console.log(chalk.dim(`  ⚙ using tool: ${event.message}`));
+        } else if (process.argv.includes('--verbose') || process.argv.includes('-v')) {
+          console.log(chalk.dim(`  … ${event.message}`));
+        }
+        break;
+      }
+
+      case 'chunk':
+        printLabel();
+        sawChunk = true;
+        process.stdout.write(event.content || '');
+        text += event.content || '';
+        break;
+
+      case 'done':
+        if (!sawChunk && event.full_response) {
+          printLabel();
+          process.stdout.write(event.full_response);
+          text = event.full_response;
+        }
+        if (event.session_id) resultSessionId = event.session_id;
+        if (event.agent_used) agentUsed = event.agent_used;
+        console.log();
+        break;
+
+      case 'error':
+        throw new Error(event.error || 'Stream error');
+
+      default:
+        break;
+    }
+  }
+
+  return { text, sessionId: resultSessionId, agentUsed };
+}
+
+/** One-shot (non-streaming) chat via POST /chat/claude. */
+async function sendOneShot(client, { message, agent, sessionId }) {
+  const body = { prompt: message };
+  if (agent) body.selected_agent = agent;
+  if (sessionId) body.session_id = sessionId;
+
+  const data = await client.post(resolveEndpoint('chat.claude').path, {
+    service: resolveEndpoint('chat.claude').service,
+    body,
+    timeout: 120000,
+  });
+
+  const response = data.result || data.response || data.text || JSON.stringify(data);
+  return { data, response, sessionId: data.session_id || sessionId };
+}
+
+export function registerChatCommands(program, ctx) {
+  const { client, auth } = ctx;
+
+  const chat = program
+    .command('chat')
+    .description('Chat with CommanderQ or any agent, streaming by default')
+    .argument('[message]', 'message to send (omit for interactive mode)')
+    .option('--agent <name>', 'route to a specific agent (e.g. sentinel, cipher, nova)')
+    .option('--no-stream', 'disable streaming output (one-shot request/response)')
+    .option('--conversation <id>', 'continue a conversation (session id)')
+    .option('--trace', 'print the turn\'s protocol events (per-layer AOCL, traces, summary) to stderr as they arrive')
+    .action(async (message, options) => {
+      auth.requireAuth();
+      const streaming = options.stream !== false;
+
+      // Interactive mode if no message
+      if (!message) {
+        const { default: inquirer } = await import('inquirer');
+        let currentAgent = options.agent || 'quox';
+        let sessionId = options.conversation;
+
+        console.log(chalk.bold(currentAgent.toUpperCase()) + chalk.dim(' | Type /exit to quit, /agent <name> to switch agent\n'));
+
+        while (true) {
+          const ans = await inquirer.prompt([{
+            type: 'input',
+            name: 'message',
+            message: chalk.cyan('You:'),
+          }]);
+
+          const input = (ans.message || '').trim();
+          if (!input || input === '/exit') break;
+
+          if (input.startsWith('/agent')) {
+            const next = input.slice('/agent'.length).trim();
+            if (next) {
+              currentAgent = next.toLowerCase();
+              console.log(chalk.dim(`Switched to agent: ${currentAgent}\n`));
+            } else {
+              console.log(chalk.dim(`Current agent: ${currentAgent}\n`));
+            }
+            continue;
+          }
+
+          try {
+            if (streaming) {
+              const result = await consumeStream(client, {
+                message: input,
+                agent: currentAgent,
+                sessionId,
+              }, {
+                onAgentLabel: (agentUsed) => process.stdout.write(chalk.green(`${(agentUsed || currentAgent).toUpperCase()}: `)),
+                trace: Boolean(options.trace),
+              });
+              if (result.sessionId) sessionId = result.sessionId;
+              console.log();
+            } else {
+              const { response, sessionId: newSessionId } = await sendOneShot(client, {
+                message: input,
+                agent: currentAgent,
+                sessionId,
+              });
+              if (newSessionId) sessionId = newSessionId;
+              console.log(chalk.green(`${currentAgent.toUpperCase()}:`), response);
+              console.log();
+            }
+          } catch (err) {
+            console.error(chalk.red(`Error: ${err.message}`));
+          }
+        }
+        return;
+      }
+
+      // Single message mode
+      if (streaming) {
+        try {
+          await consumeStream(client, {
+            message,
+            agent: options.agent,
+            sessionId: options.conversation,
+          }, {
+            onAgentLabel: () => {}, // no label prefix in single-shot streaming; just print tokens
+            trace: Boolean(options.trace),
+          });
+        } catch (err) {
+          console.error(chalk.red(`Error: ${err.message}`));
+          process.exitCode = 1;
+        }
+        return;
+      }
+
+      const ora = (await import('ora')).default;
+      const spinner = ora('Thinking...').start();
+
+      try {
+        const { data, response } = await sendOneShot(client, {
+          message,
+          agent: options.agent,
+          sessionId: options.conversation,
+        });
+        spinner.stop();
+
+        if (program.opts().output === 'json') {
+          console.log(JSON.stringify(data, null, 2));
+        } else {
+          console.log(response);
+
+          if (data.tools_used?.length) {
+            console.log(chalk.dim(`\nTools used: ${data.tools_used.join(', ')}`));
+          }
+        }
+      } catch (err) {
+        spinner.fail('Failed');
+        throw err;
+      }
+    });
+
+  // quox chat status
+  program
+    .command('chat-status')
+    .description('Check chat service status')
+    .action(async () => {
+      // Token attached when logged in: the collector auth gate 401s this
+      // route without a JWT (noAuth previously made it fail even when logged in).
+      const data = await client.get(resolveEndpoint('chat.status.list').path, { service: resolveEndpoint('chat.status.list').service });
+      formatDetail(data, {
+        format: program.opts().output,
+        title: 'Chat Status',
+      });
+    });
+}

package/lib/commands/claude.js

@@ -0,0 +1,380 @@
+/**
+ * quox claude / codex / gemini / run / sessions: governed tmux sessions. The runner
+ * lives in core/governedSession.js; this file holds argument parsing and the
+ * commander wiring. argv arrays only; user input never reaches a shell string.
+ */
+import { markForwardsRawArgs } from '../core/global-flags.js';
+import * as gs from '../core/governedSession.js';
+import { validateName, PROGRAMS } from '../core/governedSession.js';
+import { runClaudeLs } from '../core/claudeLs.js';
+import { gatherReport } from '../core/liveSessionsReport.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+import { formatOutput } from '../core/output.js';
+import { resolveOrgId } from './helpers.js';
+import { hostname as osHostname } from 'node:os';
+import { runSessionsOverview } from '../core/sessionsOverview.js';
+import {
+  buildBeat, probeTmux, runHeartbeatLoop, pidLock, fileLogger, DEFAULT_INTERVAL_S,
+} from '../core/sessionHeartbeat.js';
+
+export {
+  validateName, autoName, planLaunch, parseSessions, renderIntro, runKill, runLs, runAttach,
+} from '../core/governedSession.js';
+
+/**
+ * Split raw args after `quox claude`: strip quox's own --no-tmux, --as <agent>
+ * and --slot <name> (also --as=x / --slot=x; consumed only before a bare `--`),
+ * find --resume <name> (else -n/--name). Claude's own --agent is NOT ours and
+ * passes through verbatim, as does everything else, in order.
+ */
+export function parseClaudeArgs(raw) {
+  let noTmux = false;
+  let as;
+  let slot;
+  const args = [];
+  let past = false;
+  for (let i = 0; i < raw.length; i++) {
+    const a = raw[i];
+    if (past) { args.push(a); continue; }
+    if (a === '--') { past = true; args.push(a); continue; }
+    if (a === '--no-tmux') noTmux = true;
+    else if ((a === '--as' || a === '--slot') && raw[i + 1] && !raw[i + 1].startsWith('-')) {
+      if (a === '--as') as = raw[i + 1]; else slot = raw[i + 1];
+      i++;
+    } else if (a.startsWith('--as=') && a.length > 5) as = a.slice(5);
+    else if (a.startsWith('--slot=') && a.length > 7) slot = a.slice(7);
+    else args.push(a);
+  }
+  let name;
+  let resume = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--') break;
+    if (a === '--resume' || a === '-r') {
+      resume = true;
+      if (args[i + 1] && !args[i + 1].startsWith('-')) name = args[i + 1];
+      break;
+    }
+    if (a.startsWith('--resume=')) {
+      resume = true;
+      name = a.slice('--resume='.length) || undefined;
+      break;
+    }
+  }
+  // Claude's own -n/--name also names the tmux session, so a session started
+  // as `quox claude -n VULCAN` comes back with `quox claude --resume VULCAN`.
+  if (!resume) {
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a === '--') break;
+      if ((a === '-n' || a === '--name') && args[i + 1] && !args[i + 1].startsWith('-')) { name = args[i + 1]; break; }
+      if (a.startsWith('--name=')) { name = a.slice('--name='.length) || undefined; break; }
+    }
+  }
+  if (name !== undefined && !validateName(name)) name = undefined;
+  return { args, name, resume, noTmux, as, slot };
+}
+
+/**
+ * quox codex <args>: verbatim to `codex`. Codex has no --resume flag; it
+ * resumes with the subcommand `codex resume [SESSION_ID|NAME]`, so
+ * `quox codex resume NAME` names the tmux session after NAME.
+ */
+export function parseCodexArgs(raw) {
+  let noTmux = false;
+  const args = [];
+  for (const a of raw) {
+    if (a === '--no-tmux') noTmux = true;
+    else args.push(a);
+  }
+  let name;
+  let resume = false;
+  if (args[0] === 'resume') {
+    resume = true;
+    if (args[1] && !args[1].startsWith('-') && validateName(args[1])) name = args[1];
+  }
+  return { args, name, resume, noTmux };
+}
+
+/** `--as` / `--slot` become the preattach request that runGoverned exports as QUOX_PREATTACH_*. */
+export const runClaude = ({ as, slot, ...opts } = {}, over) => gs.runGoverned({
+  ...opts,
+  program: 'claude',
+  ...(as || slot ? { preattach: { agent: as, slot, session: opts.name } } : {}),
+}, over);
+/**
+ * quox gemini <args>: verbatim to `gemini`. Gemini resumes by index or
+ * "latest" (`--resume latest`, `-r 5`), not by name, so the tmux session is
+ * auto-named; reattach with `quox sessions attach NAME`.
+ */
+export function parseGeminiArgs(raw) {
+  let noTmux = false;
+  const args = [];
+  for (const a of raw) {
+    if (a === '--no-tmux') noTmux = true;
+    else args.push(a);
+  }
+  const resume = args.some((a) => a === '--resume' || a === '-r' || a.startsWith('--resume='));
+  return { args, name: undefined, resume, noTmux };
+}
+
+/**
+ * quox wrap <program> [args...]: wrap ANY command. Known programs use their
+ * registry entry (so `quox wrap codex` == `quox codex`); unknown ones get the
+ * generic tag and attach-based resume hint. Args are passed verbatim.
+ */
+export function parseRunArgs(raw) {
+  let noTmux = false;
+  const rest = [];
+  for (const a of raw) {
+    if (a === '--no-tmux' && rest.length === 0) noTmux = true;
+    else rest.push(a);
+  }
+  const [bin, ...args] = rest;
+  return { bin, args, noTmux };
+}
+
+export function runRun({ bin, args = [], noTmux = false } = {}, over) {
+  const known = ['claude', 'codex', 'gemini'].find((k) => PROGRAMS[k].bin === bin);
+  if (known) return gs.runGoverned({ program: known, args, noTmux }, over);
+  return gs.runGoverned({ program: 'run', bin, args, noTmux }, over);
+}
+
+export const runGemini = (opts, over) => gs.runGoverned({ ...opts, program: 'gemini' }, over);
+export const runCodex = (opts, over) => gs.runGoverned({ ...opts, program: 'codex' }, over);
+export const runTui = (opts, over) => gs.runGoverned({ ...opts, program: 'tui' }, over);
+export const runHelp = gs.runHelp;
+
+/** `quox tui --governed [screen] [--name N]`: the inner command is plain `quox tui [screen]`. */
+export function runTuiGoverned({ screen, name, noTmux = false } = {}, over) {
+  return runTui({ args: screen ? [screen] : [], name, resume: !!name, noTmux }, over);
+}
+
+/** True when --help/-h appears before a bare `--` (after it, flags belong to claude). */
+export function wantsWrapperHelp(args) {
+  for (const a of args) {
+    if (a === '--') return false;
+    if (a === '--help' || a === '-h') return true;
+  }
+  return false;
+}
+
+export const CLAUDE_WRAPPER_HELP = `Usage: quox claude [options] [-- claude-args...]
+
+Run Claude Code in a governed tmux session that survives sleep and drops.
+All other arguments are passed to claude exactly as given.
+
+quox's own flags (consumed here, not passed to claude):
+  --as <agent>    start already attached to a Quox agent
+  --slot <name>   start already holding a dev slot
+  --no-tmux       run claude directly, without tmux
+  -n, --name <n>  name the session (also names the tmux session; claude's own flag)
+  --resume <n>    resume the named session (claude's own flag)
+  -h, --help      show this help
+
+To pass --help (or any flag) through to claude itself:
+  quox claude -- --help`;
+
+export function registerClaudeCommands(program, ctx, over) {
+  // `quox claude <args>` behaves exactly like `claude <args>`: every arg is
+  // forwarded verbatim. Only --no-tmux is quox's own. Management lives in
+  // `quox sessions` so it can never collide with claude's own arguments.
+  markForwardsRawArgs(program
+    .command('claude'), 'forwards argv after the verb verbatim')
+    .description('Run Claude Code (same arguments as claude) in a tmux session that survives sleep and drops')
+    .argument('[args...]', 'passed to claude exactly as given (quox adds only --no-tmux, --as, --slot)')
+    .addHelpText('after', `
+quox's own flags (consumed here, not passed to claude):
+  --as <agent>    start already attached to a Quox agent (quox agent attach <agent> at session start)
+  --slot <name>   start already holding a dev slot (talk to it from Discord)
+  --no-tmux       run claude directly, without tmux
+Subcommand: quox claude ls [--json] lists running quox-* tmux sessions.
+Claude's own --agent is untouched and passes through to claude.`)
+    .helpOption(false)
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action((_a, _o, cmd) => {
+      const raw = (cmd.parent && cmd.parent.rawArgs) || process.argv;
+      const i = raw.indexOf('claude', 2);
+      const rest = i >= 0 ? raw.slice(i + 1) : [];
+      if (wantsWrapperHelp(rest)) { console.log(CLAUDE_WRAPPER_HELP); process.exitCode = 0; return; }
+      // `quox claude ls [--json]` lists sessions instead of launching claude.
+      if (rest[0] === 'ls' && rest.slice(1).every((a) => a === '--json')) {
+        process.exitCode = runClaudeLs({ json: rest.includes('--json') }, over);
+        return;
+      }
+      const parsed = parseClaudeArgs(rest);
+      process.exitCode = runClaude(parsed, over);
+    });
+  markForwardsRawArgs(program
+    .command('codex'), 'forwards argv after the verb verbatim')
+    .description('Run Codex (same arguments as codex) in a tmux session that survives sleep and drops')
+    .argument('[args...]', 'passed to codex exactly as given (quox adds only --no-tmux)')
+    .helpOption(false)
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action((_a, _o, cmd) => {
+      const raw = (cmd.parent && cmd.parent.rawArgs) || process.argv;
+      const i = raw.indexOf('codex', 2);
+      const parsed = parseCodexArgs(i >= 0 ? raw.slice(i + 1) : []);
+      process.exitCode = runCodex(parsed, over);
+    });
+  markForwardsRawArgs(program
+    .command('gemini'), 'forwards argv after the verb verbatim')
+    .description('Run Gemini CLI (same arguments as gemini) in a tmux session that survives sleep and drops')
+    .argument('[args...]', 'passed to gemini exactly as given (quox adds only --no-tmux)')
+    .helpOption(false)
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action((_a, _o, cmd) => {
+      const raw = (cmd.parent && cmd.parent.rawArgs) || process.argv;
+      const i = raw.indexOf('gemini', 2);
+      process.exitCode = runGemini(parseGeminiArgs(i >= 0 ? raw.slice(i + 1) : []), over);
+    });
+  markForwardsRawArgs(program
+    .command('wrap'), 'forwards argv after the verb verbatim')
+    .description('Run any program in a governed tmux session: quox wrap <program> [args...]')
+    .argument('<program>', 'command name on PATH')
+    .argument('[args...]', 'passed to the program exactly as given')
+    .helpOption(false)
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .action((_prog, _args, _opts, cmd) => {
+      // Two declared arguments => commander passes (program, args, opts, command).
+      const raw = (cmd && cmd.parent && cmd.parent.rawArgs) || process.argv;
+      const i = raw.indexOf('wrap', 2);
+      const rest = i >= 0 ? raw.slice(i + 1) : [];
+      // `quox wrap --help` / `-h` (program position only) shows usage instead
+      // of being refused as a program name.
+      if (rest.length === 0 || rest[0] === '--help' || rest[0] === '-h') {
+        cmd.outputHelp();
+        return;
+      }
+      process.exitCode = runRun(parseRunArgs(rest), over);
+    });
+  const orgOrNull = (auth) => { try { return resolveOrgId(auth, program) || null; } catch { return null; } };
+  // Bare `quox sessions`: the org-wide live index (QUOXON J2). Subcommands keep working.
+  const sessions = program.command('sessions')
+    .description('Everything live in your org, grouped by agent (bare); ls, attach, kill, report manage tmux sessions')
+    .option('--json', 'print the raw index as JSON')
+    .option('--watch', 'refresh every 2 s until Ctrl-C')
+    .option('--all', 'show every conversation (default: the 5 most recent plus any working or waiting)')
+    .action(async (o) => {
+      const so = (over && over.sessionsOverview) || {};
+      const fetchIndex = so.fetchIndex || (async () => {
+        const { client, auth } = ctx;
+        auth.requireAuth();
+        const ep = resolveEndpoint('v1.sessions.index');
+        const org = orgOrNull(auth);
+        return client.get(ep.path, { service: ep.service, retries: 0, ...(org ? { query: { org_id: org } } : {}) });
+      });
+      const json = !!o.json || program.opts().output === 'json';
+      process.exitCode = await runSessionsOverview({ json, watch: !!o.watch, all: !!o.all }, { ...so, fetchIndex });
+    });
+  // `quox active [sessions|slots|agents]`: one short summary of who is doing what (QUOXON-1208).
+  program.command('active [filter]')
+    .description('Who is doing what: one line per active worker, grouped working / waiting on you / idle; filter: sessions, slots, agents')
+    .option('--json', 'print the summary as JSON')
+    .option('--all', 'show every worker (default: top 10 per group)')
+    .option('--lines', 'the older one-line-per-worker layout with state and age columns')
+    .action(async (filter, o) => {
+      const so = (over && over.sessionsOverview) || {};
+      const fetchIndex = so.fetchIndex || (async () => {
+        const { client, auth } = ctx;
+        auth.requireAuth();
+        const ep = resolveEndpoint('v1.sessions.index');
+        const org = orgOrNull(auth);
+        return client.get(ep.path, { service: ep.service, retries: 0, ...(org ? { query: { org_id: org } } : {}) });
+      });
+      const json = !!o.json || program.opts().output === 'json';
+      const { runActive } = await import('../core/activeSummary.js');
+      const fetchSlots = so.fetchSlots || (async () => {
+        const { client, auth } = ctx;
+        const ep = resolveEndpoint('v1.slots.list');
+        const r = await client.get(ep.path, { service: ep.service, retries: 0 });
+        return Array.isArray(r) ? r : (r?.slots || r?.data || []);
+      });
+      process.exitCode = await runActive({ filter: filter || null, json, all: !!o.all, lines: !!o.lines }, { ...so, fetchIndex, fetchSlots });
+    });
+  sessions.command('heartbeat <tmuxSession>', { hidden: true })
+    .description('Heartbeat one wrapped tmux session to the org session index (started by quox claude)')
+    .option('--loop', 'keep beating until the tmux session ends')
+    .option('--backend <program>', 'claude, codex, gemini, ...')
+    .option('--agent <agent>', 'agent the session started attached to (--as)')
+    .option('--slot <slot>', 'slot the session started holding (--slot)')
+    .action(async (name, o) => {
+      const { client, auth } = ctx;
+      auth.requireAuth();
+      const org = orgOrNull(auth);
+      const host = osHostname();
+      const hb = resolveEndpoint('v1.sessions.heartbeat');
+      const en = resolveEndpoint('v1.sessions.end');
+      const withOrg = (b) => (org ? { ...b, org_id: org } : b);
+      const post = (session) => client.post(hb.path, { service: hb.service, retries: 0, body: withOrg({ host, session }) });
+      const end = () => client.post(en.path, { service: en.service, retries: 0, body: withOrg({ host, name }) });
+      if (!o.loop) {
+        const p = probeTmux(name);
+        if (!p) { process.stderr.write(`No tmux session named ${name}.\n`); process.exitCode = 1; return; }
+        const r = await post(buildBeat({ probe: p, backend: o.backend, agent: o.agent, slot: o.slot }));
+        process.stdout.write(`Registered ${name} (expires after ${r && r.expires_after_s ? r.expires_after_s : 3 * DEFAULT_INTERVAL_S}s without a beat).\n`);
+        return;
+      }
+      const r = await runHeartbeatLoop({
+        tmuxName: name, backend: o.backend || null, agent: o.agent || null, slot: o.slot || null,
+        post, end, log: fileLogger(name), lock: pidLock(name),
+      });
+      process.exitCode = r.exit === 'retired' ? 1 : 0;
+    });
+  sessions.command('help').description('Show how governed sessions work (also Ctrl-b then h)')
+    .option('--wait', 'wait for a key before exiting (used by the popup)')
+    .action((o) => {
+      process.exitCode = runHelp({ wait: !!o.wait }, over);
+    });
+  sessions.command('ls').description('List Quox sessions (--all: the org-wide live register)')
+    .option('--all', 'list the org-wide register of live sessions from the collector')
+    .action(async (o) => {
+      // The bare overview also has --all, and commander hands `sessions ls --all` to the parent;
+      // either spelling means the org-wide register here.
+      if (!o.all && !sessions.opts().all) {
+        process.exitCode = gs.runLs(over);
+        return;
+      }
+      const { client, auth } = ctx;
+      auth.requireAuth();
+      const ep = resolveEndpoint('v1.liveSessions.list');
+      const data = await client.get(ep.path, { service: ep.service, query: { org_id: resolveOrgId(auth, program) } });
+      const rows = (data.sessions || []).map((s) => ({
+        NAME: s.name, HOST: s.host, PROGRAM: s.program || '-', TMUX: s.tmux ? 'yes' : 'no',
+        SLOT: s.slot || '-', AGENT: s.agent || '-', STREAM: s.stream || '-',
+        'LAST-SEEN': s.last_seen_at, LIVE: s.live ? 'yes' : 'no',
+      }));
+      formatOutput(rows, {
+        format: program.opts().output,
+        columns: ['NAME', 'HOST', 'PROGRAM', 'TMUX', 'SLOT', 'AGENT', 'STREAM', 'LAST-SEEN', 'LIVE'],
+        emptyMessage: 'No sessions registered. Run `quox sessions report` on a dev host.',
+        raw: data.sessions || [],
+      });
+    });
+  sessions.command('report').description('Report this host\'s tmux sessions to the org live-session register').action(async () => {
+    const { client, auth } = ctx;
+    auth.requireAuth();
+    const payload = gatherReport();
+    if (!payload) {
+      process.stderr.write('tmux is not installed; nothing to report.\n');
+      process.exitCode = 1;
+      return;
+    }
+    const ep = resolveEndpoint('v1.liveSessions.report');
+    const data = await client.post(ep.path, {
+      service: ep.service,
+      body: { ...payload, org_id: resolveOrgId(auth, program) },
+    });
+    process.stdout.write(`Reported ${payload.sessions.length} session(s) from ${payload.host} (ended ${data.ended ?? 0}).\n`);
+  });
+  sessions.command('attach <name>').description('Reattach to a running Quox session').action((name) => {
+    process.exitCode = gs.runAttach(name, over);
+  });
+  sessions.command('kill <name>').description('Kill a Quox session').action((name) => {
+    process.exitCode = gs.runKill(name, over);
+  });
+}