quoxcli 0.3.1 → 0.4.0

package/lib/core/offload.js

@@ -192,22 +192,32 @@ export async function connect(deps, w) {
 export function setupScript(nodeMajor, { docker = false } = {}) {
   return [
     'set -e',
+    // set -e does not fire inside an && list or on the left of a pipe, so every install step below ends in || exit
+    'set -o pipefail',
     'SUDO=""; [ "$(id -u)" = 0 ] || SUDO="sudo -n"',
     `NEED=${Number(nodeMajor)}`,
     'export DEBIAN_FRONTEND=noninteractive',
+    // A fresh pool VM runs apt-daily/unattended-upgrades at boot; wait for it (bounded) instead of failing on the dpkg lock
+    'for i in $(seq 1 120); do pgrep -x apt-get >/dev/null || pgrep -f unattended-upgr >/dev/null || pgrep -x dpkg >/dev/null || break; sleep 5; done',
+    'APT="$SUDO apt-get -o DPkg::Lock::Timeout=600"',
     'MISSING=""',
     'for p in git rsync build-essential python3 curl ca-certificates; do dpkg -s $p >/dev/null 2>&1 || MISSING="$MISSING $p"; done',
-    'if [ -n "$MISSING" ]; then $SUDO apt-get update -qq && $SUDO apt-get install -y -qq $MISSING; fi',
+    'if [ -n "$MISSING" ]; then { $APT update -qq && $APT install -y -qq $MISSING; } || { echo "offload setup: apt install of$MISSING failed" >&2; exit 1; }; fi',
     'HAVE=$(node -p "process.versions.node.split(\'.\')[0]" 2>/dev/null || echo none)',
-    'if [ "$HAVE" != "$NEED" ]; then curl -fsSL https://deb.nodesource.com/setup_$NEED.x | $SUDO -E bash - && $SUDO apt-get install -y -qq nodejs; fi',
+    // a worker already on a NEWER major is fine (callers on this box run 20 and 22); never flip it between majors
+    'case "$HAVE" in none|"") HAVE=0;; esac',
+    'if [ "$HAVE" -lt "$NEED" ]; then { curl -fsSL https://deb.nodesource.com/setup_$NEED.x | ${SUDO:+$SUDO -E} bash - && $APT install -y -qq nodejs; } || { echo "offload setup: node $NEED install failed" >&2; exit 1; }; fi',
     ...(docker ? [
       // --docker: the daemon plus buildx (the sandbox Dockerfiles use COPY --chmod, which needs BuildKit)
       'DMISSING=""',
       'for p in docker.io docker-buildx; do dpkg -s $p >/dev/null 2>&1 || DMISSING="$DMISSING $p"; done',
-      'if [ -n "$DMISSING" ]; then $SUDO apt-get update -qq && $SUDO apt-get install -y -qq $DMISSING; fi',
+      'if [ -n "$DMISSING" ]; then { $APT update -qq && $APT install -y -qq $DMISSING; } || { echo "offload setup: docker install failed" >&2; exit 1; }; fi',
       '$SUDO systemctl enable --now docker >/dev/null 2>&1 || true',
       `id -nG ${REMOTE_USER} | grep -qw docker || $SUDO usermod -aG docker ${REMOTE_USER}`,
     ] : []),
+    // Never record a worker as ready unless the toolchain is really there (2026-10-20: workers marked ready with no npm).
+    'command -v npm >/dev/null || { echo "offload setup: npm missing after setup" >&2; exit 1; }',
+    '[ "$(node -p "process.versions.node.split(\'.\')[0]")" -ge "$NEED" ] || { echo "offload setup: node is older than $NEED" >&2; exit 1; }',
     `mkdir -p ${REMOTE_ROOT}`,
   ].join('\n');
 }
@@ -236,18 +246,21 @@ export function sandboxImagesScript(root, sudo = 'sudo -n') {
   ].join('\n');
 }
 
+export const SETUP_REV = 2;
+
 export async function ensureTooling(deps, w, { docker = false } = {}) {
   const st = loadState(deps);
   const major = String(deps.nodeVersion).replace(/^v/, '').split('.')[0];
-  const done = String(st.worker?.setup || '');
+  // SETUP_REV: bumped when the setup script's guarantees change, so a worker recorded under an older script redoes setup.
+  const done = String(st.worker?.setup || '').startsWith(`r${SETUP_REV}:`) ? String(st.worker.setup).slice(`r${SETUP_REV}:`.length) : '';
   // setup is recorded as "<node major>" or "<node major>+docker"; a docker run needs the +docker form
-  if (st.worker?.vmid === w.vmid && done.split('+')[0] === major && (!docker || done.endsWith('+docker'))) return false;
+  if (st.worker?.vmid === w.vmid && Number(done.split('+')[0]) >= Number(major) && (!docker || done.endsWith('+docker'))) return false;
   const withDocker = docker || done.endsWith('+docker');
   deps.log(`preparing the worker (node, git, rsync, build tools${withDocker ? ', docker' : ''})...`);
   const r = await ssh(deps, w.ip, `bash -c ${shq(setupScript(major, { docker: withDocker }))}`);
   if (r.status !== 0) throw new OffloadError(`worker setup failed (exit ${r.status}): ${r.cmdline}\n${(r.stderr || '').trim()}`);
   const st2 = loadState(deps);
-  if (st2.worker) { st2.worker.setup = withDocker ? `${major}+docker` : major; saveState(deps, st2); }
+  if (st2.worker) { st2.worker.setup = `r${SETUP_REV}:` + (withDocker ? `${major}+docker` : major); saveState(deps, st2); }
   return true;
 }
 
@@ -255,7 +268,13 @@ export async function ensureTooling(deps, w, { docker = false } = {}) {
 // Before a sync, drop synced dirs idle longer than the limit (dir mtime = last use, touched at every sync), never the
 // one being synced and never one a run is busy in (.offload-busy younger than 6h; an older one is a crashed run).
 export const PRUNE_IDLE_MIN = 120;
-export function pruneScript(root, keep, maxIdleMin = PRUNE_IDLE_MIN) {
+// Under disk pressure (free below minFreePct) the least recently used synced dirs go too, oldest first, never the
+// current one or a busy one, until free space reaches targetFreePct (2026-10-20: ~30 dirs all used within the hour
+// filled the shared worker and the idle rule freed nothing).
+export const PRUNE_MIN_FREE_PCT = 20;
+export const PRUNE_TARGET_FREE_PCT = 35;
+const DF_FREE_PCT = 'df -P . | awk \'NR==2 { gsub("%", "", $5); print 100 - $5 }\'';
+export function pruneScript(root, keep, maxIdleMin = PRUNE_IDLE_MIN, { minFreePct = PRUNE_MIN_FREE_PCT, targetFreePct = PRUNE_TARGET_FREE_PCT, freePctCmd = DF_FREE_PCT } = {}) {
   return [
     `cd ${shq(root)} 2>/dev/null || exit 0`,
     'for d in */; do d=${d%/}; [ -d "$d" ] || continue',
@@ -265,6 +284,16 @@ export function pruneScript(root, keep, maxIdleMin = PRUNE_IDLE_MIN) {
     'done',
     // cache entries nobody has used for a day go too (each worktree's copy is only hard links into these)
     `find ${shq(`${root}/.nm-cache`)} -mindepth 1 -maxdepth 1 -mmin +1440 -exec rm -rf {} + 2>/dev/null; true`,
+    `free_pct() { ${freePctCmd}; }`,
+    `if [ "$(free_pct)" -lt ${Number(minFreePct)} ]; then`,
+    '  for d in $(ls -1tr); do [ -d "$d" ] || continue',
+    `    [ "$(free_pct)" -ge ${Number(targetFreePct)} ] && break`,
+    `    [ "$d" = ${shq(keep)} ] && continue`,
+    '    [ -e "$d/.offload-busy" ] && [ -n "$(find "$d/.offload-busy" -mmin -360 2>/dev/null)" ] && continue',
+    '    rm -rf -- "$d"',
+    '  done',
+    'fi',
+    'true',
   ].join('\n');
 }
 

package/lib/core/output.js

@@ -83,9 +83,9 @@ export function formatDetail(obj, options = {}) {
     const label = (labels[field] || field).padEnd(maxLabel + 2);
     const raw = obj[field];
     if (raw !== null && typeof raw === 'object') {
-      console.log(`  ${chalk.dim(label)}${formatNestedValue(raw)}`);
+      console.log(`  ${chalk.dim(label)}${formatNestedValue(raw, 4, options.full === true)}`);
     } else {
-      const value = formatValue(raw);
+      const value = formatValue(raw, options.full === true);
       console.log(`  ${chalk.dim(label)} ${value}`);
     }
   }
@@ -97,15 +97,15 @@ export function formatDetail(obj, options = {}) {
  * Kept local to formatDetail (not folded into formatValue) so formatTable /
  * formatCsv output is unchanged.
  */
-function formatNestedValue(value, indent = 4) {
+function formatNestedValue(value, indent = 4, full = false) {
   if (value == null) return ` ${chalk.dim('-')}`;
 
   if (Array.isArray(value)) {
     if (value.length === 0) return ` ${chalk.dim('[]')}`;
     const allPrimitive = value.every(v => v === null || typeof v !== 'object');
-    if (allPrimitive) return ` ${value.map(v => formatValue(v)).join(', ')}`;
+    if (allPrimitive) return ` ${value.map(v => formatValue(v, full)).join(', ')}`;
     return '\n' + value
-      .map(v => `${' '.repeat(indent)}- ${typeof v === 'object' && v !== null ? formatNestedValue(v, indent + 2).trimStart() : formatValue(v)}`)
+      .map(v => `${' '.repeat(indent)}- ${typeof v === 'object' && v !== null ? formatNestedValue(v, indent + 2, full).trimStart() : formatValue(v, full)}`)
       .join('\n');
   }
 
@@ -115,9 +115,9 @@ function formatNestedValue(value, indent = 4) {
     .map(k => {
       const v = value[k];
       if (v !== null && typeof v === 'object') {
-        return `${' '.repeat(indent)}${chalk.dim(k + ':')}${formatNestedValue(v, indent + 2)}`;
+        return `${' '.repeat(indent)}${chalk.dim(k + ':')}${formatNestedValue(v, indent + 2, full)}`;
       }
-      return `${' '.repeat(indent)}${chalk.dim(k + ':')} ${formatValue(v)}`;
+      return `${' '.repeat(indent)}${chalk.dim(k + ':')} ${formatValue(v, full)}`;
     })
     .join('\n');
 }

package/lib/core/sessionHeartbeat.js

@@ -15,7 +15,7 @@
  *    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 { 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';
@@ -70,9 +70,10 @@ export function buildBeat({ probe, backend = null, agent = null, slot = null, he
   };
 }
 
-/** Live probe of one tmux session (exact match). null when it does not exist. */
+/** Live probe of one tmux session (exact match). null when it does not exist.
+ *  `=name:` (session form): tmux 3.4 answers a bare `=name` with an empty line. */
 export function probeTmux(name, spawnSync = realSpawnSync) {
-  const r = spawnSync('tmux', ['display-message', '-p', '-t', `=${name}`, PROBE_FORMAT], { encoding: 'utf8' });
+  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;
@@ -177,16 +178,19 @@ export function fileLogger(name, dir = HB_DIR()) {
  * 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 } = {}) {
+// Spawned by a short-lived node that exits at once, so the heartbeat is never
+// the wrapper's child: the wrapper blocks in spawnSync(tmux) for the session's
+// life and could not reap it (ZOMBIES 2026-10-24, one defunct per wrapper).
+const DETACH_LAUNCHER = "const{spawn}=require('node:child_process');const c=spawn(process.argv[1],process.argv.slice(2),{detached:true,stdio:'ignore'});c.on('error',()=>{});c.unref();";
+
+export function startHeartbeat({ tmuxSession, backend, agent, slot }, { spawnSync = realSpawnSync, 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;
+    const r = spawnSync(execPath, ['-e', DETACH_LAUNCHER, execPath, ...args], { stdio: 'ignore', timeout: 10_000 });
+    return !!r && !r.error && r.status === 0;
   } catch { return false; }
 }

package/lib/core/shortcut.js

@@ -0,0 +1,83 @@
+/**
+ * `quox shortcut add|remove` (QUOXON-Q): a short command (default `q`) that is a symlink to this quox.
+ *
+ * Rules: never shadow an existing command (a `q` already on PATH that is not ours is refused and named);
+ * a user-writable directory only (the one quox lives in, else ~/.local/bin); no sudo; no shell rc edits (a symlink
+ * works in every shell and script); idempotent; remove only ever removes a link that points at this quox.
+ * Local only: nothing is sent anywhere.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const DEFAULT_NAME = 'q';
+export const NAME_OK = /^[A-Za-z][A-Za-z0-9_.-]{0,30}$/;
+export const QUOX_ENTRY = fileURLToPath(new URL('../../bin/quox.js', import.meta.url));
+
+const real = (p) => { try { return fs.realpathSync(p); } catch { return null; } };
+const isExec = (p) => { try { fs.accessSync(p, fs.constants.X_OK); return fs.statSync(p).isFile(); } catch { return false; } };
+const writable = (d) => { try { fs.accessSync(d, fs.constants.W_OK); return fs.statSync(d).isDirectory(); } catch { return false; } };
+const pathDirs = (env) => String(env.PATH || '').split(path.delimiter).filter(Boolean);
+
+/** `command -v name` over PATH -> the first executable path, or null. */
+export function whichOnPath(name, env = process.env) {
+  for (const d of pathDirs(env)) { const p = path.join(d, name); if (isExec(p)) return p; }
+  return null;
+}
+
+/** Where the link goes: { dir, onPath, target }. target is what `q` will point at. */
+export function planShortcut({ env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  const realEntry = real(entry) || entry;
+  const quoxOnPath = whichOnPath('quox', env);
+  // The `quox` on PATH may be a wrapper script rather than a link to this entry: it is still "this quox".
+  const onPathReal = quoxOnPath;
+  const target = onPathReal || realEntry;
+  const reals = new Set([realEntry, quoxOnPath && real(quoxOnPath)].filter(Boolean));
+  const dirs = pathDirs(env).map(d => path.resolve(d));
+  const local = path.join(home, '.local', 'bin');
+  const cands = [];
+  if (onPathReal) cands.push(path.dirname(onPathReal));
+  cands.push(local);
+  const dir = cands.find(writable) || (fs.existsSync(local) ? null : local);
+  return { dir, onPath: dir ? dirs.includes(path.resolve(dir)) : false, target, realEntry, reals };
+}
+
+const ours = (p, reals) => { try { return fs.lstatSync(p).isSymbolicLink() && reals.has(real(p)); } catch { return false; } };
+
+/** -> { ok, status: 'created'|'exists'|'refused'|'error', message, link?, onPath? } */
+export function addShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name (letters, digits, _ . -, starting with a letter).` };
+  const plan = planShortcut({ env, home, entry });
+  const found = whichOnPath(name, env);
+  if (found && plan.reals.has(real(found))) return { ok: true, status: 'exists', link: found, message: `${name} already runs quox (${found}). Nothing changed.` };
+  if (found) return { ok: false, status: 'refused', message: `Not created: "${name}" already runs ${found}. Quox never shadows an existing command. Pick another name with: quox shortcut add --name <name>` };
+  if (!plan.dir) return { ok: false, status: 'error', message: 'No writable directory for the link (tried the one quox lives in and ~/.local/bin). Nothing changed.' };
+  const link = path.join(plan.dir, name);
+  if (ours(link, plan.reals)) return { ok: true, status: 'exists', link, onPath: plan.onPath, message: `${name} already points at quox (${link}).${plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run yet.`}` };
+  let present = false;
+  try { fs.lstatSync(link); present = true; } catch { /* free */ }
+  if (present) return { ok: false, status: 'refused', message: `Not created: ${link} already exists and is not a link to quox. Left alone.` };
+  try {
+    fs.mkdirSync(plan.dir, { recursive: true });
+    fs.symlinkSync(plan.target, link);
+  } catch (e) { return { ok: false, status: 'error', message: `Could not create ${link}: ${e.message}` }; }
+  const warn = plan.onPath ? '' : ` ${plan.dir} is not on your PATH, so ${name} will not run until you add it.`;
+  return { ok: true, status: 'created', link, onPath: plan.onPath, message: `Created ${link} -> ${plan.target}.${warn}` };
+}
+
+/** Removes the link only if it points at this quox. */
+export function removeShortcut({ name = DEFAULT_NAME, env = process.env, home = os.homedir(), entry = QUOX_ENTRY } = {}) {
+  if (!NAME_OK.test(name)) return { ok: false, status: 'error', message: `"${name}" is not a usable command name.` };
+  const plan = planShortcut({ env, home, entry });
+  const dirs = [...new Set([...(plan.dir ? [plan.dir] : []), ...pathDirs(env), path.join(home, '.local', 'bin')])];
+  for (const d of dirs) {
+    const link = path.join(d, name);
+    if (ours(link, plan.reals)) {
+      try { fs.unlinkSync(link); } catch (e) { return { ok: false, status: 'error', message: `Could not remove ${link}: ${e.message}` }; }
+      return { ok: true, status: 'removed', link, message: `Removed ${link}.` };
+    }
+  }
+  const other = whichOnPath(name, env);
+  return { ok: true, status: 'none', message: other ? `Nothing removed: ${name} (${other}) is not a link to quox, so it is left alone.` : `Nothing to remove: no ${name} link to quox found.` };
+}

package/lib/core/version.js

@@ -18,7 +18,7 @@ import { execFileSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 
-export const BASE_VERSION = '0.3.1';
+export const BASE_VERSION = '0.4.0';
 
 // The CLI source root (…/cli). version.js lives at cli/lib/core/, so two
 // levels up is the tree whose HEAD identifies the running build.

package/lib/core/vm.js

@@ -134,6 +134,11 @@ export async function listVms(exec, { node, type } = {}) {
  * does not know it, fall back to client-side exact match over proxmox_vms + proxmox_containers.
  * Ambiguity is an error listing candidates; never a guess.
  */
+/** DEVFLEET INV-1: list rows for `quox vm list`, with each VM's Proxmox tags as one cell ('' when untagged). */
+export function vmListRows(vms) {
+  return vms.map(({ raw, ...r }) => ({ ...r, tags: Array.isArray(raw && raw.tags) ? raw.tags.join(', ') : '' }));
+}
+
 export async function resolveTarget(exec, target) {
   const t = String(target ?? '').trim();
   if (!t) throw new Error('a VM name or vmid is required');

package/lib/dragon/companionView.js

@@ -0,0 +1,34 @@
+/**
+ * The companion view Quoxon actually uses: same contract as dragonlab's integration/companions-v1/view.mjs
+ * (initial / reduce / view -> {frame, caption, hidden, name, scene}), same reducer, same character, same scene and caption
+ * logic, but sized to the classic dragon's footprint and played from a frame cache filled by a worker (frames.js).
+ * view() never renders; it reads. `ready` resolves once the worker has loaded the art.
+ */
+import { pathToFileURL } from 'node:url';
+import { createPlayhead, createWorkerBackend, companionSlot, quantise } from './frames.js';
+
+export async function loadCompanionView(root, id, { still = false, arrival = true, mono = false, persist = true, makeBackend = createWorkerBackend, onFrame = () => {} } = {}) {
+  const url = (p) => pathToFileURL(`${root}/integration/${p}`).href;
+  const [chars, act] = await Promise.all([import(url('companions-v1/characters.mjs')), import(url('hyperion-v3/activity.mjs'))]);
+  const spec = chars.character(id);
+  const backend = await makeBackend({ root, id, still, mono });
+  const play = createPlayhead(backend, { onFirst: onFrame });
+  return {
+    id, name: spec.name, arrivalMs: spec.arrival.duration,
+    initial: act.initialActivity,
+    reduce: act.activityEvent,
+    playhead: play,
+    view(state, now, { cols = 80, rows = 24, mood = null } = {}) {
+      if (!persist && !still && now - state.started >= spec.arrival.duration && !state.approvals.length) return { frame: null, caption: null, hidden: true, name: spec.name, scene: null };
+      const slot = companionSlot(cols, Math.max(1, rows));
+      let v = chars.activityView(id, state, now, { arrival: arrival && !still });
+      // The dragon's job read found something wrong (a down route, an unhealthy host, a failed check): it acts concerned, the same scene
+      // a recorded issue gets. Never the other way round: a good read does not pick a happier scene than the activity allows.
+      if (mood === 'concerned' && !state.approvals.length && !state.issue) { const c = chars.activityView(id, { ...state, issue: true }, now, { arrival: false }); v = { ...v, scene: c.scene, time: c.time, motionTime: c.motionTime }; }
+      const frame = slot.showArt ? play.frame({ scene: v.scene, time: v.time, motionTime: v.motionTime, cols: slot.cols, rows: slot.rows }, { still }) : null;
+      return { frame, caption: v.caption, slot, name: spec.name, scene: v.scene };
+    },
+    dispose() { play.dispose(); },
+  };
+}
+export { companionSlot, quantise };

package/lib/dragon/frames.js

@@ -0,0 +1,118 @@
+/**
+ * Smooth companion playback. Rendering a dragonlab frame costs 100 ms to over a second (Hyperion), and the old path did it
+ * synchronously inside every Ink render, so the whole TUI hitched and the dragon juddered. The classic Q dragon is smooth
+ * because its frames are cheap and the shared clock paces them. This does the same for companions: time is quantised to
+ * the clock's frame step, frames are rendered OFF the main thread (a worker, see renderWorker.js) a few steps ahead of the
+ * playhead into a cache, and the renderer only ever READS the cache. A frame that is not ready yet is held (the last one
+ * shown stays), never rendered inline. The same quantised time returns the same frame object, so an unchanged frame costs
+ * Ink no output at all.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** One animation step, the shared clock's FRAME_MS (about 12 fps). */
+export const STEP_MS = 83;
+/** How many steps ahead of the playhead the worker is asked to fill. */
+export const LOOKAHEAD = 3;
+const CACHE_MAX = 240;
+
+export const quantise = (ms) => Math.max(0, Math.round((Number(ms) || 0) / STEP_MS) * STEP_MS);
+
+/**
+ * Where the art goes. Sized to the classic dragon's footprint (15 rows when the terminal is short, 22 when it is tall
+ * enough that the live region still fits), not the old 39x11 cap. Below ART_MIN a one-line label is used instead.
+ */
+export const ART_MIN_COLS = 64, ART_MIN_ROWS = 30;
+export function companionSlot(cols, rows) {
+  const big = cols >= ART_MIN_COLS && rows >= ART_MIN_ROWS;
+  if (!big) return { showArt: false, cols: 0, rows: 0 };
+  const tall = rows >= 40;
+  return { showArt: true, cols: Math.max(28, Math.min(tall ? 66 : 52, cols - 26)), rows: tall ? 22 : 15 };
+}
+
+/**
+ * Cache + playhead. `backend.render(req) -> Promise<frame>` does the real work somewhere else; at most one request is in
+ * flight, and the next one asked for is always the soonest frame not cached yet (current step first, then lookahead).
+ */
+export function createPlayhead(backend, { onFirst = () => {}, lookahead = LOOKAHEAD, clock = () => Date.now() } = {}) {
+  const cache = new Map(), pending = new Set();
+  const conc = Math.max(1, backend.size || 1); // the backend may be a pool: keep every worker busy
+  let last = null, disposed = false, failed = null, renders = 0, ema = 100;
+  const keyOf = (r) => `${r.scene}|${r.time}|${r.motionTime}|${r.cols}x${r.rows}`;
+  const put = (k, f) => { cache.set(k, f); if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value); };
+  function pump(wants) {
+    for (const next of wants) {
+      if (pending.size >= conc || disposed || failed) return;
+      const k = keyOf(next);
+      if (cache.has(k) || pending.has(k)) continue;
+      pending.add(k); renders++;
+      const began = clock();
+      Promise.resolve().then(() => backend.render(next)).then((f) => {
+        ema = ema * 0.7 + (clock() - began) * 0.3;
+        if (f) { put(k, f); const first = !last; last = f; if (first) onFirst(); }
+      }, (e) => { failed = e; }).finally(() => { pending.delete(k); });
+    }
+  }
+  return {
+    /**
+     * The frame to draw for this scene/time: the cached one for this step, else the newest earlier one (held), else the last
+     * one shown. null before the first ever arrives. The worker is asked for the step the playhead will be at when the
+     * render lands (now + the measured render time), so a slow character still plays at the rate it can render, never stalls the TUI.
+     */
+    frame(req, { still = false } = {}) {
+      const base = (i) => ({ ...req, time: quantise(req.time) + i * STEP_MS, motionTime: quantise(req.motionTime) + i * STEP_MS });
+      const lead = still ? 0 : Math.min(6, Math.ceil(ema / STEP_MS));
+      pump(still ? [base(0)] : Array.from({ length: Math.max(lookahead, conc * 2) + 1 }, (_, i) => base(lead + i)));
+      for (let back = 0; back <= 4; back++) {
+        const hit = cache.get(keyOf(base(-back)));
+        if (hit) { last = hit; return hit; }
+      }
+      return last;
+    },
+    get error() { return failed; },
+    get renders() { return renders; },
+    get size() { return cache.size; },
+    get busy() { return pending.size; },
+    get lead() { return Math.min(6, Math.ceil(ema / STEP_MS)); },
+    dispose() { disposed = true; cache.clear(); backend.dispose?.(); },
+  };
+}
+
+/**
+ * The real backend: worker threads that load the character once and render on request (a small pool, because the heavier
+ * characters take several frame steps to render and the pool renders upcoming steps in parallel). Rejects if no worker can start.
+ */
+export async function createWorkerBackend({ root, id, still = false, mono = false, size = null }, { Worker, cpus = null } = {}) {
+  const W = Worker || (await import('node:worker_threads')).Worker;
+  const avail = cpus ?? (await import('node:os')).availableParallelism?.() ?? 2;
+  const n = Math.max(1, Math.min(size ?? 3, avail - 1));
+  const file = fileURLToPath(new URL('./renderWorker.js', import.meta.url));
+  const waiting = new Map();
+  let seq = 0, dead = null;
+  const fail = (e) => { dead = e; for (const w of waiting.values()) w.reject(e); waiting.clear(); };
+  const spawn = () => new Promise((resolve, reject) => {
+    const worker = new W(file, { workerData: { root, id } });
+    worker.unref?.();
+    worker.once('error', (e) => { fail(e); reject(e); });
+    worker.on('message', (m) => {
+      if (m.type === 'ready') return resolve({ worker, load: 0 });
+      const w = waiting.get(m.seq); if (!w) return;
+      waiting.delete(m.seq); w.slot.load--;
+      if (m.type === 'frame') w.resolve(m.frame); else w.reject(new Error(m.code || 'render failed'));
+    });
+    worker.once('exit', (c) => { fail(new Error(`render worker exited (${c})`)); reject(dead); });
+  });
+  const slots = await Promise.all(Array.from({ length: n }, spawn));
+  return {
+    size: n,
+    render: (req) => new Promise((resolve, reject) => {
+      if (dead) return reject(dead);
+      const slot = slots.reduce((a, b) => (b.load < a.load ? b : a));
+      const s = ++seq; slot.load++; waiting.set(s, { resolve, reject, slot });
+      slot.worker.postMessage({ seq: s, req: { ...req, still, mono } });
+    }),
+    dispose() { fail(new Error('disposed')); for (const s of slots) s.worker.terminate(); },
+  };
+}
+
+/** Test/fallback helper: path-to-URL for a dragonlab module. */
+export const labModule = (root, ...p) => pathToFileURL([root, 'integration', 'companions-v1', ...p].join('/')).href;

package/lib/dragon/jobs.js

@@ -0,0 +1,123 @@
+/**
+ * Dragon jobs: each companion dragon has ONE truthful job, and its caption comes from a real read.
+ *   sentinel  WARD state of the last answer's envelope (POST /ward/verify-receipt, the route /proof uses)
+ *   cipher    route health: kuma monitors up/down (the `quox kuma` read)
+ *   seer      the plan: QuoxPlan focus stream and x of y phases
+ *   hyperion  fleet: hosts up of total (the Bastion host read)
+ *   drago     open security findings (the engagement store)
+ *   lucid     recovery: the last failure this session saw, and whether a later turn completed (no network read)
+ * Rules: every read is bounded (timeoutMs); a failed or silent read says "Couldn't check <thing> (<why>)" and never a number;
+ * results (failures too) are cached for JOB_TTL_MS so a dragon that appears often does not hammer the server; nothing here
+ * polls, run() is only called when the dragon is about to be shown; read-only. Pure apart from the injected reads.
+ * A result is { caption, mood } where mood is 'ok' | 'concerned' | null (null = unknown or neutral). The host may pick a
+ * concerned scene for 'concerned'; it never celebrates on null.
+ */
+export const JOB_FOR = Object.freeze({ sentinel: 'ward', cipher: 'routes', seer: 'plan', hyperion: 'fleet', drago: 'findings', lucid: 'recovery' });
+export const JOB_TTL_MS = 30000;
+export const JOB_TIMEOUT_MS = 6000;
+const LABEL = { ward: 'WARD', routes: 'routes', plan: 'plan', fleet: 'fleet', findings: 'findings' };
+const READ_FOR = { ward: 'verifyReceipt', routes: 'routes', plan: 'plan', fleet: 'fleet', findings: 'findings' };
+
+const why = (e) => (e?.status ? `HTTP ${e.status}` : /timed out/i.test(e?.message || '') ? 'timed out' : String(e?.message || 'failed').slice(0, 60));
+const ago = (ms) => { const m = Math.floor(ms / 60000); return m < 1 ? 'under a minute ago' : m < 60 ? `${m} min ago` : m < 1440 ? `${Math.floor(m / 60)} h ago` : `${Math.floor(m / 1440)} d ago`; };
+const failed = (job, reason) => ({ caption: `Couldn't check ${LABEL[job]} (${reason}).`, mood: null });
+
+/** Pure: a read's data -> { caption, mood }. */
+export function captionFor(job, d) {
+  if (job === 'ward') {
+    const r = d?.result || {}, seq = r.entry?.seq;
+    if (r.status === 'WITNESSED') return { caption: `Last answer witnessed by WARD (seq ${seq}, signed tip).`, mood: 'ok' };
+    if (r.status === 'UNTIPPED') return { caption: `Last answer recorded (seq ${seq}) but no signed tip yet.`, mood: null };
+    if (r.status === 'NOT_WITNESSED') return { caption: 'Last answer not witnessed yet.', mood: null };
+    if (r.status) return { caption: `WARD check failed: ${r.status}${r.reason ? ` ${r.reason}` : ''}.`, mood: 'concerned' };
+    return failed('ward', 'no status in the answer');
+  }
+  if (job === 'routes') {
+    if (!d.total) return { caption: 'No monitors to read.', mood: null };
+    const stale = d.ageSeconds > 600 ? ` (snapshot ${Math.round(d.ageSeconds / 60)} min old)` : '';
+    if (d.down > 0) return { caption: `Routes: ${d.up} of ${d.total} up. Down: ${d.downNames.slice(0, 3).join(', ')}${d.downNames.length > 3 ? ` and ${d.downNames.length - 3} more` : ''}.`, mood: 'concerned' };
+    if (d.up < d.total) return { caption: `Routes: ${d.up} of ${d.total} up${stale}.`, mood: null }; // pending, maintenance, unknown: not counted up
+    const ping = Number.isFinite(d.avgPing) && !stale ? `, average ${Math.round(d.avgPing)} ms` : '';
+    return { caption: `Routes: ${d.up} of ${d.total} up${stale || ping}.`, mood: stale ? null : 'ok' };
+  }
+  if (job === 'plan') {
+    if (!d) return { caption: 'Nothing in focus on the plan.', mood: null };
+    if (d.total === 0) return { caption: `Plan: ${d.id} (no phases listed).`, mood: null };
+    return { caption: Number.isFinite(d.total) ? `Plan: ${d.id}, ${d.done} of ${d.total} phases.` : `Plan: ${d.id} (phases not read).`, mood: null };
+  }
+  if (job === 'fleet') {
+    if (!d.total) return { caption: 'No hosts to read.', mood: null };
+    const bits = ['degraded', 'unhealthy', 'offline', 'unknown'].filter(k => d[k]).map(k => `${d[k]} ${k}`);
+    return { caption: `Fleet: ${d.healthy} of ${d.total} hosts up${bits.length ? ` (${bits.join(', ')})` : ''}.`, mood: d.healthy === d.total ? 'ok' : 'concerned' };
+  }
+  if (job === 'findings') {
+    if (!d.open) return { caption: 'No open security findings recorded.', mood: 'ok' };
+    return { caption: `Open findings: ${d.open}${d.severe ? ` (${d.severe} critical or high)` : ''}.`, mood: d.severe ? 'concerned' : null };
+  }
+  return null;
+}
+
+/**
+ * reads: { verifyReceipt(envelopeId), routes(), plan(), fleet(), findings() }, each resolving to data or throwing (verifyReceipt may
+ * resolve { ok:false, error }). context(): { envelopeId } of the last answer. observe(event): the session's own events (lucid).
+ */
+export function createDragonJobs({ reads = {}, context = () => ({}), now = Date.now, ttlMs = JOB_TTL_MS, timeoutMs = JOB_TIMEOUT_MS } = {}) {
+  const cache = new Map(), inflight = new Map();
+  let lastFailure = null, recoveredAt = null;
+  const keyOf = (job) => (job === 'ward' ? `ward:${context()?.envelopeId || ''}` : job);
+
+  function recovery() {
+    if (!lastFailure) return { caption: 'No failures seen in this session.', mood: null };
+    const when = ago(now() - lastFailure.at);
+    return recoveredAt != null
+      ? { caption: `Recovered: ${lastFailure.what} ${when}, a later turn completed.`, mood: 'ok' }
+      : { caption: `Last failure: ${lastFailure.what} ${when}, not recovered yet.`, mood: 'concerned' };
+  }
+  async function fetchOne(job) {
+    const read = reads[READ_FOR[job]];
+    if (typeof read !== 'function') return null;
+    let timer;
+    try {
+      const arg = job === 'ward' ? context()?.envelopeId : undefined;
+      const data = await Promise.race([
+        Promise.resolve().then(() => read(arg)),
+        new Promise((_, rej) => { timer = setTimeout(() => rej(new Error('timed out')), timeoutMs); timer.unref?.(); }),
+      ]);
+      if (job === 'ward' && data && data.ok === false) return failed(job, data.error || 'failed');
+      return captionFor(job, data);
+    } catch (e) { return failed(job, why(e)); }
+    finally { clearTimeout(timer); }
+  }
+
+  return {
+    /** Feed the session's events (turn.finished, error): the only input lucid's job has. */
+    observe(ev) {
+      if (!ev) return;
+      if (ev.type === 'error') { lastFailure = { at: now(), what: 'stream error' }; recoveredAt = null; }
+      else if (ev.type === 'turn.finished') {
+        if (ev.status === 'failed' || ev.status === 'unconfirmed') { lastFailure = { at: now(), what: `turn ${ev.status}` }; recoveredAt = null; }
+        else if (ev.status === 'completed' && lastFailure && recoveredAt == null) recoveredAt = now();
+      }
+    },
+    peek(dragonId) {
+      const job = JOB_FOR[dragonId];
+      if (!job) return null;
+      if (job === 'recovery') return recovery();
+      const hit = cache.get(keyOf(job));
+      return hit && now() - hit.at < ttlMs ? hit.value : null;
+    },
+    /** The dragon's job result, from cache (30 s) or one bounded read. null = this dragon has no job here. */
+    async run(dragonId) {
+      const job = JOB_FOR[dragonId];
+      if (!job) return null;
+      if (job === 'recovery') return recovery();
+      if (job === 'ward' && !context()?.envelopeId) return { caption: 'No receipt to check yet: nothing from this session is witnessed.', mood: null };
+      const key = keyOf(job), hit = cache.get(key);
+      if (hit && now() - hit.at < ttlMs) return hit.value;
+      if (inflight.has(key)) return inflight.get(key);
+      const p = fetchOne(job).then((value) => { if (value) cache.set(key, { at: now(), value }); return value; }).finally(() => inflight.delete(key));
+      inflight.set(key, p);
+      return p;
+    },
+  };
+}

package/lib/dragon/renderWorker.js

@@ -0,0 +1,15 @@
+/** Worker thread: loads one dragonlab character and renders frames on request, so the TUI thread never does. See frames.js. */
+import { parentPort, workerData } from 'node:worker_threads';
+import { pathToFileURL } from 'node:url';
+
+const { root, id } = workerData;
+const mod = await import(pathToFileURL(`${root}/integration/companions-v1/characters.mjs`).href);
+const actor = await mod.loadCharacter(id);
+parentPort.on('message', ({ seq, req }) => {
+  try {
+    const r = actor.render(req.scene, req.time, { cols: req.cols, rows: req.rows, still: req.still, mono: req.mono, motionTime: req.motionTime });
+    if (!r || !r.ok) parentPort.postMessage({ type: 'error', seq, code: r?.code || 'render failed' });
+    else parentPort.postMessage({ type: 'frame', seq, frame: r.frame });
+  } catch (e) { parentPort.postMessage({ type: 'error', seq, code: e.message }); }
+});
+parentPort.postMessage({ type: 'ready' });