quoxcli 0.0.0-stage → 0.2.0

package/lib/core/governedSession.js

@@ -0,0 +1,402 @@
+/**
+ * Governed sessions: run any interactive program (claude, codex, the Quox TUI)
+ * inside a tmux session `quox-...` that survives sleep and wifi drops and
+ * reattaches with no context reload. argv arrays only; user input never reaches
+ * a shell string.
+ *
+ * Session naming: claude keeps the legacy untagged form `quox-NAME`; other
+ * programs carry a tag: `quox-codex-NAME`, `quox-tui-NAME`. `quox sessions ls`
+ * derives the PROGRAM column from that tag.
+ */
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync as realSpawnSync } from 'node:child_process';
+import { qArt, colorOn } from './banner.js';
+import { startHeartbeat as realStartHeartbeat } from './sessionHeartbeat.js';
+
+const NAME_RE = /^[A-Za-z0-9._-]{1,48}$/;
+export const PREFIX = 'quox-';
+export const HELP_KEY = 'h';
+export const HELP_COMMAND = 'quox sessions help --wait';
+
+export const validateName = (n) => typeof n === 'string' && NAME_RE.test(n);
+
+export function autoName(now = new Date()) {
+  const p = (n) => String(n).padStart(2, '0');
+  return `s-${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}`;
+}
+
+/**
+ * Program registry. One entry per known CLI; adding the next one is one entry.
+ * tag '' means legacy untagged (claude). resumeHint(bare, full) is the plain
+ * words command that gets you back after a reboot. Unknown programs (quox wrap)
+ * use GENERIC: the session carries the tag `run-<program>-` and the hint is
+ * `quox sessions attach FULLNAME`.
+ */
+export const PROGRAMS = {
+  claude: { tag: '', bin: 'claude', resumeHint: (n) => `quox claude --resume ${n}` },
+  codex: { tag: 'codex-', bin: 'codex', resumeHint: (n) => `quox codex resume ${n}` },
+  // gemini resumes by index or "latest" (--resume latest | --resume N), not by name.
+  gemini: { tag: 'gemini-', bin: 'gemini', resumeHint: () => 'quox gemini --resume latest' },
+  tui: { tag: 'tui-', bin: 'quox', resumeHint: (n) => `quox tui --governed --name ${n}` },
+};
+
+export const GENERIC_TAG = 'run-';
+const PROGRAM_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,47}$/;
+export const validateProgram = (p) => typeof p === 'string' && PROGRAM_RE.test(p);
+/** Tag segment for a generic program: no hyphens so the name parses back. */
+export const programSeg = (bin) => String(bin).replace(/-/g, '_');
+
+const TAGGED = Object.entries(PROGRAMS).filter(([, v]) => v.tag);
+
+/** Resume hint for any program name (registry entry or generic). */
+export function resumeHintFor(program, bare, full) {
+  const e = PROGRAMS[program];
+  return e ? e.resumeHint(bare) : `quox sessions attach ${full || bare}`;
+}
+
+/** Find an executable on PATH without a shell. Returns path or null. */
+export function whichSync(bin, envPath = process.env.PATH || '') {
+  if (!validateProgram(bin)) return null;
+  for (const dir of String(envPath).split(path.delimiter)) {
+    if (!dir) continue;
+    const f = path.join(dir, bin);
+    try {
+      if (!fs.statSync(f).isFile()) continue;
+      fs.accessSync(f, fs.constants.X_OK);
+      return f;
+    } catch { /* keep looking */ }
+  }
+  return null;
+}
+
+/** Full session name (without the quox- prefix) for a program + user name. */
+export const taggedName = (program, name, bin) =>
+  (program === 'run' ? `${GENERIC_TAG}${programSeg(bin)}-` : PROGRAMS[program]?.tag || '') + name;
+
+/** Program for a session name (without prefix). Untagged means claude. */
+export function programOf(name) {
+  const n = String(name);
+  for (const [p, v] of TAGGED) if (n.startsWith(v.tag)) return p;
+  const m = /^run-([^-]+)-/.exec(n);
+  if (m) return m[1];
+  return 'claude';
+}
+
+/** Name the user chose, with the program tag stripped. */
+export const bareName = (name) => {
+  const n = String(name);
+  const p = programOf(n);
+  if (PROGRAMS[p]) return PROGRAMS[p].tag ? n.slice(PROGRAMS[p].tag.length) : n;
+  return n.replace(/^run-[^-]+-/, '');
+};
+
+/** argv for the program inside the session. */
+export function programCmd(program, args, bin) {
+  if (program === 'run') return [bin, ...args];
+  const p = PROGRAMS[program];
+  if (program === 'tui') return [p.bin, 'tui', ...args];
+  return [p.bin, ...args];
+}
+
+/** Env vars (QUOX_PREATTACH_*) the SessionStart hook reads to attach/check out a slot. Empty when none requested. */
+export function preattachEnv(pre) {
+  const out = {};
+  if (pre?.agent) out.QUOX_PREATTACH_AGENT = pre.agent;
+  if (pre?.slot) out.QUOX_PREATTACH_SLOT = pre.slot;
+  if ((pre?.agent || pre?.slot) && pre.session) out.QUOX_PREATTACH_SESSION = pre.session;
+  return out;
+}
+
+const tmuxEnvArgs = (penv) => Object.entries(penv).flatMap(([k, v]) => ['-e', `${k}=${v}`]);
+
+export function planLaunch({ name, args = [], env = {}, alive = false, resume = false, noTmux = false, program = 'claude', bin, preattach }) {
+  const penv = preattachEnv(preattach);
+  const tmuxSession = PREFIX + taggedName(program, name, bin);
+  const cmdArgv = programCmd(program, args, bin);
+  if (env.TMUX || noTmux) {
+    return { mode: resume ? 'RESUME' : 'NEW', tmuxSession, cmd: cmdArgv, ...(Object.keys(penv).length ? { env: penv } : {}) };
+  }
+  if (alive) {
+    return { mode: 'REATTACH', tmuxSession, cmd: ['tmux', 'attach-session', '-t', tmuxSession] };
+  }
+  return {
+    mode: resume ? 'RESUME' : 'NEW',
+    tmuxSession,
+    cmd: ['tmux', 'new-session', ...tmuxEnvArgs(penv), '-s', tmuxSession, '--', ...cmdArgv],
+    ...(Object.keys(penv).length ? { env: penv } : {}),
+    ...(resume ? { note: 'A resume reloads the conversation context (costs tokens). Reattach is free.' } : {}),
+  };
+}
+
+export function parseSessions(out) {
+  return String(out || '')
+    .split('\n')
+    .map((l) => l.split('\t'))
+    .filter((c) => c.length >= 4 && c[0].startsWith(PREFIX))
+    .map((c) => {
+      const name = c[0].slice(PREFIX.length);
+      return {
+        name,
+        program: programOf(name),
+        created: new Date(Number(c[1]) * 1000),
+        attached: Number(c[2]) > 0,
+        windows: Number(c[3]),
+      };
+    });
+}
+
+/** The plain-words cheat sheet, shared by the intro and the Ctrl-b h popup. */
+export function howItWorksLines({ name, program = 'claude', bare }) {
+  const b = bare || bareName(name);
+  const full = name;
+  return [
+    ['Leave it running:', 'press Ctrl-b, then d'],
+    ['Come back later:', `quox sessions attach ${name}`],
+    ['See your sessions:', 'quox sessions ls'],
+    ['Scroll back:', 'press Ctrl-b, then [   (q to stop)'],
+    ['After a reboot:', resumeHintFor(program, b, full)],
+    ['End it:', `quox sessions kill ${name}`],
+    ['Help any time:', 'press Ctrl-b, then h'],
+  ];
+}
+
+export function renderIntro({ name, host, mode, tmuxSession, note, program = 'claude', preattach }, { color = false } = {}) {
+  const b = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
+  const d = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
+  const art = qArt(color);
+  const modeText = {
+    NEW: 'NEW',
+    REATTACH: 'REATTACH (same process, no context reload)',
+    RESUME: 'RESUME',
+  }[mode] || mode;
+  const text = [
+    '',
+    b('QUOX GOVERNED SESSION'),
+    '',
+    `${d('session     ')} ${name}`,
+    `${d('program     ')} ${program}`,
+    `${d('host        ')} ${host}`,
+    `${d('mode        ')} ${modeText}`,
+    `${d('tmux session')} ${tmuxSession}`,
+    '',
+    b('How this works'),
+    ...howItWorksLines({ name, program }).map(([k, v]) => `${d(k.padEnd(19))}${v}`),
+  ];
+  const w = art[0] ? 14 : 0;
+  const lines = [];
+  for (let i = 0; i < Math.max(art.length, text.length); i++) {
+    lines.push(`  ${art[i] || ' '.repeat(w)}   ${text[i] || ''}`);
+  }
+  let out = '\n' + lines.join('\n') + '\n';
+  if (note) out += `  ${d(note)}\n`;
+  if (mode !== 'REATTACH' && (preattach?.agent || preattach?.slot)) {
+    const { agent, slot } = preattach;
+    const what = agent ? `Attaching as ${agent}${slot ? ` \u00b7 slot ${slot}` : ''}` : `Holding slot ${slot}`;
+    out += `  ${b(`${what} at session start`)}\n`;
+    if (slot) out += `  ${d(`Talk to it from Discord in #${slot}`)}\n`;
+  }
+  return out + '\n';
+}
+
+/** Plain text for `quox sessions help` (no colour, no art). */
+export function renderHelp({ name, program } = {}) {
+  const n = name || '<name>';
+  const p = program || (name ? programOf(name) : 'claude');
+  const lines = howItWorksLines({ name: n, program: p, bare: name ? bareName(name) : '<name>' });
+  return ['QUOX GOVERNED SESSION: How this works', '', ...lines.map(([k, v]) => `${k.padEnd(19)}${v}`), ''].join('\n');
+}
+
+function defaults(over = {}) {
+  return {
+    spawnSync: realSpawnSync,
+    env: process.env,
+    hostname: () => os.hostname(),
+    now: () => new Date(),
+    color: colorOn(),
+    write: (s) => process.stdout.write(s),
+    // QUOXON J1: register + heartbeat each tmux session the wrapper starts. An
+    // injected spawnSync (tests) means no real child unless startHeartbeat is injected too.
+    startHeartbeat: over.spawnSync ? () => {} : realStartHeartbeat,
+    ...over,
+  };
+}
+
+const tmuxMissing = (r) => r && r.error && r.error.code === 'ENOENT';
+
+/** tmux -V output to [major, minor], or null if unknown. */
+export function parseTmuxVersion(out) {
+  const m = /(\d+)\.(\d+)/.exec(String(out || ''));
+  return m ? [Number(m[1]), Number(m[2])] : null;
+}
+
+export const supportsPopup = (v) => !!v && (v[0] > 3 || (v[0] === 3 && v[1] >= 2));
+
+/** argv (after `tmux`) that binds Ctrl-b h. Contains no user data. */
+export function helpBindArgv(version) {
+  if (supportsPopup(version)) {
+    return ['bind-key', HELP_KEY, 'display-popup', '-E', '-w', '80%', '-h', '60%', HELP_COMMAND];
+  }
+  return ['bind-key', HELP_KEY, 'display-message',
+    'Quox: Ctrl-b d leave it running | Ctrl-b [ scroll back | quox sessions ls | quox sessions help'];
+}
+
+/**
+ * Bind Ctrl-b h idempotently (bind-key is tmux-server wide). Returns
+ * 'cold' when no tmux server is running yet (nothing to bind into),
+ * 'present' when already bound to the quox help, 'bound' otherwise, 'failed'.
+ */
+export function ensureHelpBinding(d) {
+  const keys = d.spawnSync('tmux', ['list-keys', '-T', 'prefix'], { encoding: 'utf8' });
+  if (!keys || keys.error || keys.status !== 0) return 'cold';
+  if (String(keys.stdout || '').includes('quox sessions help')) return 'present';
+  const v = d.spawnSync('tmux', ['-V'], { encoding: 'utf8' });
+  const r = d.spawnSync('tmux', helpBindArgv(parseTmuxVersion(v && v.stdout)), { stdio: 'ignore' });
+  return r && r.status === 0 ? 'bound' : 'failed';
+}
+
+export function runGoverned({ program = 'claude', name, args = [], resume = false, noTmux = false, bin, preattach }, over) {
+  const d = defaults(over);
+  const n = name || autoName(d.now());
+  if (program === 'run') {
+    if (!validateProgram(bin)) {
+      d.write(`Refusing program "${bin}": use a plain command name (letters, digits, dot, underscore, plus, hyphen), no paths or shell characters.\n`);
+      return 2;
+    }
+    const found = (d.which || whichSync)(bin, d.env.PATH);
+    if (!found) {
+      d.write(`${bin} was not found on PATH.\n`);
+      return 1;
+    }
+  }
+  const full = taggedName(program, n, bin);
+  if (!validateName(n) || !validateName(full)) {
+    d.write(`Invalid session name "${n}". Use 1-48 characters: letters, digits, dot, underscore, hyphen.\n`);
+    return 2;
+  }
+  let alive = false;
+  if (!noTmux && !d.env.TMUX) {
+    const r = d.spawnSync('tmux', ['has-session', '-t', '=' + PREFIX + full], { stdio: 'ignore' });
+    if (tmuxMissing(r)) {
+      d.write(`tmux is not installed. Install it (apt install tmux / brew install tmux), or run without it: quox ${program === 'tui' ? 'tui --governed' : program === 'run' ? `wrap ${bin}` : program} --no-tmux\n`);
+      return 1;
+    }
+    alive = r.status === 0;
+  }
+  const plan = planLaunch({ name: n, args, env: d.env, alive, resume, noTmux, program, bin, preattach });
+  const shown = program === 'run' ? bin : program;
+  d.write(renderIntro({ name: full, host: d.hostname(), mode: plan.mode, tmuxSession: plan.tmuxSession, note: plan.note, program: shown, preattach }, { color: d.color }));
+  let cmd = plan.cmd;
+  const viaTmux = cmd[0] === 'tmux';
+  if (viaTmux) {
+    const state = ensureHelpBinding(d);
+    if (state === 'cold' && plan.mode !== 'REATTACH') {
+      // No tmux server yet: create the session detached so a server exists,
+      // bind the help key into it, then attach.
+      const created = d.spawnSync('tmux', ['new-session', '-d', ...tmuxEnvArgs(preattachEnv(preattach)), '-s', plan.tmuxSession, '--', ...programCmd(program, args, bin)], { stdio: 'ignore' });
+      if (created && created.status !== 0) {
+        d.write('Could not start the tmux session.\n');
+        return 1;
+      }
+      ensureHelpBinding(d);
+      cmd = ['tmux', 'attach-session', '-t', plan.tmuxSession];
+    }
+  }
+  if (viaTmux) {
+    try {
+      d.startHeartbeat({
+        tmuxSession: plan.tmuxSession, backend: program === 'run' ? bin : program,
+        agent: (preattach && preattach.agent) || null, slot: (preattach && preattach.slot) || null,
+      });
+    } catch { /* the index is best effort; never block the launch */ }
+  }
+  const [exe, ...exeArgs] = cmd;
+  // Direct run (--no-tmux, or already inside tmux): the env rides the spawn.
+  const r = d.spawnSync(exe, exeArgs, { stdio: 'inherit', ...(exe !== 'tmux' && plan.env ? { env: { ...d.env, ...plan.env } } : {}) });
+  if (r && r.error) {
+    d.write(`Could not run ${exe}: ${r.error.message || r.error.code}\n`);
+    return 1;
+  }
+  return r && typeof r.status === 'number' ? r.status : 0;
+}
+
+function listSessions(d) {
+  const r = d.spawnSync('tmux', ['list-sessions', '-F', '#{session_name}\t#{session_created}\t#{session_attached}\t#{session_windows}'], { encoding: 'utf8' });
+  if (tmuxMissing(r)) return null;
+  return r.status === 0 ? parseSessions(r.stdout) : [];
+}
+
+export function runLs(over) {
+  const d = defaults(over);
+  const s = listSessions(d);
+  if (s === null) {
+    d.write('tmux is not installed (apt install tmux / brew install tmux).\n');
+    return 1;
+  }
+  if (!s.length) {
+    d.write('No Quox sessions running. Start one with: quox claude (or quox codex, quox gemini, quox wrap <program>)\n');
+    return 0;
+  }
+  const pad = (v, n) => String(v).padEnd(n);
+  d.write(`${pad('NAME', 24)}${pad('PROGRAM', 12)}${pad('CREATED', 18)}${pad('ATTACHED', 10)}WINDOWS\n`);
+  for (const x of s) {
+    const c = x.created.toISOString().slice(0, 16).replace('T', ' ');
+    d.write(`${pad(x.name, 24)}${pad(x.program, 12)}${pad(c, 18)}${pad(x.attached ? 'yes' : 'no', 10)}${x.windows}\n`);
+  }
+  return 0;
+}
+
+export function runKill(name, over) {
+  const d = defaults(over);
+  if (!validateName(name)) {
+    d.write(`Invalid session name "${name}".\n`);
+    return 2;
+  }
+  const has = d.spawnSync('tmux', ['has-session', '-t', '=' + PREFIX + name], { stdio: 'ignore' });
+  if (has.status !== 0) {
+    d.write(`No such session: ${name}. See: quox sessions ls\n`);
+    return 1;
+  }
+  const r = d.spawnSync('tmux', ['kill-session', '-t', PREFIX + name], { stdio: 'ignore' });
+  d.write(r.status === 0 ? `Killed ${name}.\n` : `Failed to kill ${name}.\n`);
+  return r.status === 0 ? 0 : 1;
+}
+
+export function runAttach(name, over) {
+  const d = defaults(over);
+  if (!validateName(name)) {
+    d.write(`Invalid session name "${name}".\n`);
+    return 2;
+  }
+  const has = d.spawnSync('tmux', ['has-session', '-t', '=' + PREFIX + name], { stdio: 'ignore' });
+  if (tmuxMissing(has)) {
+    d.write('tmux is not installed (apt install tmux / brew install tmux).\n');
+    return 1;
+  }
+  if (has.status !== 0) {
+    d.write(`No such session: ${name}. See: quox sessions ls\n`);
+    return 1;
+  }
+  const verb = d.env.TMUX ? 'switch-client' : 'attach-session';
+  const r = d.spawnSync('tmux', [verb, '-t', PREFIX + name], { stdio: 'inherit' });
+  return r && typeof r.status === 'number' ? r.status : 0;
+}
+
+/** `quox sessions help`: print the cheat sheet for the current (or given) session. */
+export function runHelp({ wait = false } = {}, over) {
+  const d = defaults(over);
+  let name;
+  if (d.env.TMUX) {
+    const r = d.spawnSync('tmux', ['display-message', '-p', '#{session_name}'], { encoding: 'utf8' });
+    const s = r && r.status === 0 ? String(r.stdout || '').trim() : '';
+    if (s.startsWith(PREFIX) && validateName(s.slice(PREFIX.length))) name = s.slice(PREFIX.length);
+  }
+  d.write(renderHelp({ name }) + '\n');
+  if (wait) {
+    d.write('Press any key to close.\n');
+    if (d.waitKey) d.waitKey();
+    else if (process.stdin.isTTY) d.spawnSync('sh', ['-c', 'stty raw -echo; dd bs=1 count=1 >/dev/null 2>&1; stty sane'], { stdio: 'inherit' });
+  }
+  return 0;
+}

package/lib/core/lazyCommands.js

@@ -0,0 +1,119 @@
+/**
+ * Lazy command-group registration (CORTEX-BENCH, CLI startup latency).
+ *
+ * Importing every command module cost ~1s on every `quox` invocation. Here a
+ * cached map (top-level command name -> registrar indexes) lets a normal
+ * invocation import only the module(s) that define or extend its command (a
+ * group can be extended by several modules, e.g. `agent` by agent.js and
+ * agentAttach.js). Correctness rules:
+ *   - no map, stale map, unknown command, help/completion/bare invocation,
+ *     or ANY error in the lazy path  ->  full load (the old behaviour);
+ *   - after a lazy load, the command must actually exist, else full load;
+ *   - every full load rebuilds the map, so it self-heals.
+ * A wrong map can therefore only make a call slower, never break it.
+ */
+import { readFileSync, writeFileSync, mkdirSync, statSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const MAP_VERSION = 1;
+// Global options that consume the next argv token (so it is not the command).
+const VALUE_OPTS = new Set(['-o', '--output', '--org', '-p', '--profile']);
+const FULL_LOAD_TOKENS = new Set(['help', 'completion', 'tui']);
+
+/** First argv token that names a command, or null (help/bare/unknown shape). */
+export function commandToken(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') return null;
+    if (a === '-h' || a === '--help' || a === '-V' || a === '--version') return null;
+    if (a.startsWith('-')) {
+      if (VALUE_OPTS.has(a)) i++;
+      continue;
+    }
+    return a;
+  }
+  return null;
+}
+
+function mapPath() {
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'quox', 'cli-command-map.json');
+}
+
+/** Cache key: the command modules' file set and mtimes, plus the registrar list. */
+export function mapKey(registrars, commandsDir) {
+  let sig = registrars.map(([p, n]) => `${p}#${n}`).join('|');
+  try {
+    for (const f of readdirSync(commandsDir).sort()) {
+      if (!f.endsWith('.js')) continue;
+      sig += `|${f}:${statSync(join(commandsDir, f)).mtimeMs}`;
+    }
+  } catch { return null; }
+  let h = 5381;
+  for (let i = 0; i < sig.length; i++) h = ((h << 5) + h + sig.charCodeAt(i)) | 0;
+  return `v${MAP_VERSION}:${h}`;
+}
+
+// Size of a command subtree (every nested command and option), so a module
+// that only extends a DEEP subcommand of an existing group is still recorded
+// as touching that top-level group.
+function subtreeSize(cmd) {
+  return 1 + cmd.options.length + cmd.commands.reduce((n, c) => n + subtreeSize(c), 0);
+}
+function topLevelSnapshot(program) {
+  return new Map(program.commands.map((c) => [c.name(), subtreeSize(c)]));
+}
+
+async function fullLoad(program, ctx, registrars, baseUrl, key) {
+  const map = {};
+  for (let i = 0; i < registrars.length; i++) {
+    const [path, name] = registrars[i];
+    const before = topLevelSnapshot(program);
+    const mod = await import(new URL(path, baseUrl).href);
+    mod[name](program, ctx);
+    for (const [cmd, size] of topLevelSnapshot(program)) {
+      if (before.get(cmd) !== size) (map[cmd] ||= []).push(i);
+    }
+  }
+  if (key) {
+    try {
+      const file = mapPath();
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({ key, map }));
+    } catch { /* the cache is an optimisation only */ }
+  }
+}
+
+/**
+ * Register command groups lazily when safe, fully otherwise.
+ * @param {import('commander').Command} program
+ * @param {object} ctx
+ * @param {Array<[string, string]>} registrars [modulePath relative to baseUrl, export name], in registration order
+ * @param {string[]} argv process.argv.slice(2)
+ * @param {string} baseUrl import.meta.url of the caller
+ */
+export async function registerCommandGroups(program, ctx, registrars, argv, baseUrl) {
+  const commandsDir = join(dirname(fileURLToPath(baseUrl)), '..', 'lib', 'commands');
+  const key = process.env.QUOX_CLI_EAGER === '1' ? null : mapKey(registrars, commandsDir);
+  const token = commandToken(argv);
+  if (key && token && !FULL_LOAD_TOKENS.has(token)) {
+    try {
+      const cached = JSON.parse(readFileSync(mapPath(), 'utf-8'));
+      const idx = cached && cached.key === key ? cached.map[token] : null;
+      if (Array.isArray(idx) && idx.length > 0) {
+        for (const i of idx) {
+          const [path, name] = registrars[i];
+          const mod = await import(new URL(path, baseUrl).href);
+          mod[name](program, ctx);
+        }
+        if (program.commands.some((c) => c.name() === token || c.aliases().includes(token))) return 'lazy';
+      }
+    } catch { /* fall through to a full load */ }
+    // Partial registration (if any) must not double-register: start clean.
+    program.commands.splice(0, program.commands.length);
+  }
+  await fullLoad(program, ctx, registrars, baseUrl, key);
+  return 'full';
+}

package/lib/core/liveSessionsReport.js

@@ -0,0 +1,112 @@
+/**
+ * DEVSUITE phase 19: gather this host's tmux sessions into the payload for
+ * POST /api/v1/live-sessions/report. Pure parse/map functions take injected
+ * tmux output and held-slots JSON so they unit-test without tmux.
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const TMUX_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{pane_current_command}\t#{pane_pid}\t#{session_activity}';
+
+const AGENT_PROGRAMS = new Set(['claude', 'codex', 'gemini']);
+
+/** Parse `tmux list-panes -a -F TMUX_FORMAT` output; one entry per session (first pane wins). */
+export function parseTmuxPanes(out) {
+  const seen = new Map();
+  for (const line of String(out || '').split('\n')) {
+    const c = line.split('\t');
+    if (c.length < 5 || !c[0]) continue;
+    if (seen.has(c[0])) continue;
+    const created = Number(c[1]);
+    const pid = Number.parseInt(c[4], 10);
+    const activity = Number(c[5]);
+    seen.set(c[0], {
+      name: c[0],
+      tmux: true,
+      attached: Number(c[2]) > 0,
+      program: c[3] || null,
+      pid: Number.isInteger(pid) ? pid : null,
+      started_at: Number.isFinite(created) && created > 0 ? new Date(created * 1000).toISOString() : null,
+      last_active: Number.isFinite(activity) && activity > 0 ? new Date(activity * 1000).toISOString() : null,
+    });
+  }
+  return [...seen.values()];
+}
+
+/** held-slots.json is { slotName: { session, pid, ... } }; return { holderSession: { slot, pid } }. */
+export function slotsBySession(held) {
+  const map = {};
+  if (!held || typeof held !== 'object') return map;
+  for (const [slot, e] of Object.entries(held)) {
+    if (e && typeof e.session === 'string' && e.session && !(e.session in map)) {
+      map[e.session] = { slot, pid: Number.isInteger(e.pid) ? e.pid : null };
+    }
+  }
+  return map;
+}
+
+/**
+ * Attach kits live at ~/.quox/attach/sessions/claude-<pid>/<agentId>/, where
+ * <pid> is the claude process the slot entry records. Read ONLY the agent dir
+ * name and the plain `splinter` label file (e.g. "S2 1"); never the token.
+ */
+export function readAttachSafe(pid, base = join(homedir(), '.quox', 'attach', 'sessions')) {
+  if (!Number.isInteger(pid)) return null;
+  try {
+    const dir = join(base, `claude-${pid}`);
+    if (!existsSync(dir)) return null;
+    const agent = readdirSync(dir).find((d) => /^[a-z0-9_-]{1,40}$/.test(d));
+    if (!agent) return null;
+    let splinter = null;
+    const sp = join(dir, agent, 'splinter');
+    if (existsSync(sp)) {
+      const m = /^(S\d{1,3})\b/.exec(readFileSync(sp, 'utf-8').trim());
+      if (m) splinter = m[1];
+    }
+    return { agent, splinter };
+  } catch {
+    return null;
+  }
+}
+
+export function buildReport({ tmuxOut, held, env = {}, host, attachLookup = readAttachSafe }) {
+  const bySession = slotsBySession(held);
+  const sessions = parseTmuxPanes(tmuxOut).slice(0, 50).map((s) => {
+    // `quox claude --resume NAME` runs NAME in tmux session quox-NAME, while
+    // the slot entry records the bare NAME.
+    const bare = s.name.replace(/^quox-/, '');
+    const hit = bySession[s.name] || bySession[bare] || null;
+    const { last_active: lastActive, ...rest } = s;
+    const out = { ...rest, slot: hit ? hit.slot : null };
+    const att = hit ? attachLookup(hit.pid) : null;
+    if (att) {
+      out.agent = att.agent;
+      if (att.splinter) out.splinter = att.splinter;
+    }
+    // No stream from env: QUOX_STREAM goes stale in inherited shells (house
+    // rule, and it mislabelled VULCAN as QUOX-SECURITY on the first live run).
+    // The column stays for a reliable source later (slot or attach metadata).
+    // last_active (tmux session_activity) feeds the J1 index's working/resting state.
+    out.meta = { agent_program: AGENT_PROGRAMS.has(s.program), ...(lastActive ? { last_active: lastActive } : {}) };
+    return out;
+  });
+  return { host: host || hostname(), sessions };
+}
+
+export function readHeldSlotsSafe(path = join(homedir(), '.quox', 'held-slots.json')) {
+  try {
+    if (!existsSync(path)) return {};
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Live gather. Returns null when tmux is missing; an empty server yields an empty list. */
+export function gatherReport({ spawn = spawnSync, env = process.env, held = readHeldSlotsSafe() } = {}) {
+  const r = spawn('tmux', ['list-panes', '-a', '-F', TMUX_FORMAT], { encoding: 'utf8' });
+  if (r.error) return null;
+  return buildReport({ tmuxOut: r.status === 0 ? r.stdout : '', held, env });
+}

package/lib/core/org-override.js

@@ -0,0 +1,52 @@
+/**
+ * org-override.js — what `--org` is allowed to mean (GRIPE-709).
+ *
+ * A user access token is bound to ONE org (its org_id claim). `--org` used to
+ * be read only by verbs that build /api/orgs/<id>/... paths; every other verb
+ * (notes, whoami, ...) ignored it and answered from the session org, so
+ * `quox --org B notes ls` silently returned org A's data. The server offers no
+ * per-request org header, only a governed switch (`quox org switch`), so the
+ * safe contract is:
+ *
+ *   - flag absent                      -> fine
+ *   - flag names the session org       -> fine (id, slug or name)
+ *   - flag names ANY OTHER org while a
+ *     user session is active           -> REFUSE, never fall back
+ *   - service-key-only invocation      -> allowed (no session org to disagree
+ *     with; the key's verbs take the org explicitly)
+ */
+import { QuoxValidationError } from './errors.js';
+
+// Commands where --org legitimately means something other than "act in".
+const EXEMPT = new Set(['login', 'logout', 'signup', 'org switch', 'invites list', 'invites accept']);
+
+export function commandPath(cmd) {
+  const parts = [];
+  for (let c = cmd; c && c.parent; c = c.parent) parts.unshift(c.name());
+  return parts.join(' ');
+}
+
+/**
+ * @param {object} args
+ * @param {string|undefined} args.override  value of --org
+ * @param {object|null} args.authData       stored auth (org_id/org_slug/org_name)
+ * @param {boolean} args.hasUserToken
+ * @param {string} [args.command]           e.g. 'notes ls'
+ * @throws {QuoxValidationError} when the override differs from the session org
+ */
+export function assertOrgOverrideSafe({ override, authData, hasUserToken, command = '' }) {
+  if (!override || !hasUserToken || EXEMPT.has(command)) return;
+  const want = String(override).toLowerCase();
+  const sid = authData?.org_id || null;
+  const known = [sid, authData?.org_slug, authData?.org_name]
+    .filter(Boolean).map(v => String(v).toLowerCase());
+  if (known.includes(want)) return;
+  const current = sid
+    ? `${authData.org_slug || authData.org_name || sid}${authData.org_slug || authData.org_name ? ` (${sid})` : ''}`
+    : 'none';
+  throw new QuoxValidationError(
+    `--org ${override} differs from your session org ${current}; `
+    + `run \`quox org switch ${override}\` or use a profile for that org. `
+    + 'Refusing to act in a different org than the one named.'
+  );
+}