quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/slash/settings.js

@@ -0,0 +1,50 @@
+/**
+ * /config settings, saved on the CLI config profile (profile.quoxon = { theme, motion, verbose }), so a
+ * choice survives restarts and follows `-p`. Theme replaces the env-only QUOX_THEME: the saved value is
+ * applied by setting the variable the theme module already reads, unless the user's shell set it, in
+ * which case the shell wins and the card says so.
+ */
+import { PROFILE_IDS } from '../sound/mapping.js';
+
+// Captured at import, before anything here writes it: what the user's shell set.
+const SHELL = { theme: process.env.QUOX_THEME || null, motion: process.env.QUOX_REDUCED_MOTION || null };
+
+
+/** The settings this build can honour. Sound is the /sound controller's own profile (server-side soundProfile). */
+export function settingsList({ sound = true } = {}) {
+  return [
+    { id: 'theme', label: 'Theme', values: ['auto', 'dark', 'light'], def: 'auto', help: 'auto follows your terminal background' },
+    { id: 'motion', label: 'Motion', values: ['full', 'reduced'], def: 'full', help: 'reduced stills the animations' },
+    ...(sound ? [{ id: 'sound', label: 'Sound', values: PROFILE_IDS, def: 'minimal', help: 'same as /sound; saved to your account' }] : []),
+    { id: 'verbose', label: 'Verbose', values: ['off', 'on', 'full'], def: 'on', help: 'protocol lines in turns' },
+    { id: 'model', label: 'Model', action: 'model', help: 'Enter opens /model' }
+  ];
+}
+
+/** Apply saved look settings to this process. -> { themeFromShell, motionFromShell }. */
+export function applySettings(s = {}, env = process.env, shell = SHELL) {
+  if (!shell.theme) {
+    if (s.theme === 'dark' || s.theme === 'light') env.QUOX_THEME = s.theme; else delete env.QUOX_THEME;
+  }
+  if (!shell.motion) {
+    if (s.motion === 'reduced') env.QUOX_REDUCED_MOTION = '1'; else delete env.QUOX_REDUCED_MOTION;
+  }
+  return { themeFromShell: Boolean(shell.theme), motionFromShell: Boolean(shell.motion) };
+}
+
+export const shellOverrides = () => ({ ...SHELL });
+
+/** The card rows. `values` = current settings, `extra` = { model: label, verbose: current }. */
+export function configRows(list, values, { shell = SHELL, model = 'auto' } = {}) {
+  return list.map(it => {
+    if (it.action === 'model') return { key: it.label, text: model, note: it.help };
+    const v = values[it.id] ?? it.def;
+    const forced = (it.id === 'theme' && shell.theme) ? `QUOX_THEME=${shell.theme} in your shell wins` : (it.id === 'motion' && shell.motion) ? 'QUOX_REDUCED_MOTION in your shell wins' : null;
+    return { key: it.label, text: it.values.map(x => (x === v ? `[${x}]` : x)).join('  '), note: forced || it.help };
+  });
+}
+
+export const cycle = (it, cur, dir = 1) => {
+  const i = it.values.indexOf(cur ?? it.def);
+  return it.values[(i + dir + it.values.length) % it.values.length];
+};

package/lib/quoxon/sound/index.js

@@ -0,0 +1,186 @@
+/**
+ * QuoxSound in the terminal: the controller the app calls from its single
+ * dispatch point. Decides (mapping.js), gates (profile, rate limit, mode) and
+ * plays (synthesised WAV through the OS player, or the terminal bell).
+ *
+ *   const snd = createSound({ api, stdout });
+ *   snd.observe(prevState, nextState, action)   // after every reduce
+ *   snd.focus(true|false)                      // from CSI I / CSI O (keys.js)
+ *   await snd.command(arg, say)                // /sound
+ *
+ * Never throws, never blocks: players are spawned detached with a kill timer.
+ * The setting is the dashboard's server-side `soundProfile` preference
+ * (PATCH /api/auth/me), so dashboard and terminal agree; the active CLI
+ * profile keeps a local copy for offline starts and as the fallback store.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { soundForEvent, createLimiter, normalizeSettings, allowed, PROFILE_IDS, PROFILE_LABELS } from './mapping.js';
+import { soundMode, findPlayer, BEL, BEL_IDS } from './output.js';
+import { earconWav } from './synth.js';
+
+export const FOCUS_ON = '\x1b[?1004h';
+export const FOCUS_OFF = '\x1b[?1004l';
+export const PLAYER_TIMEOUT_MS = 5000;
+
+const cap = (s) => s[0].toUpperCase() + s.slice(1);
+const USAGE = 'Usage: /sound [Silent | Minimal | Operational | Full | test]';
+
+function offReason({ env, stdout, print }) {
+  if (print) return '--print never makes sound';
+  if (!stdout?.isTTY) return 'not a terminal';
+  if (String(env.QUOX_SOUND ?? '').length && soundMode({ env: { QUOX_SOUND: env.QUOX_SOUND }, stdout: { isTTY: true } }) === 'off') return `QUOX_SOUND=${env.QUOX_SOUND}`;
+  return 'CI';
+}
+
+function defaultCacheDir(env) {
+  const base = env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  const dir = join(base, 'quox', 'sound');
+  try { mkdirSync(dir, { recursive: true, mode: 0o700 }); return dir; } catch { return mkdtempSync(join(tmpdir(), 'quox-sound-')); }
+}
+
+export function createSound({
+  api = null, stdout = null, env = process.env, print = false, platform = process.platform,
+  has, spawn = nodeSpawn, now = Date.now, cacheDir = null, exitHook = (fn) => process.once('exit', fn),
+  timeoutMs = PLAYER_TIMEOUT_MS
+} = {}) {
+  const mode = soundMode({ env, stdout, print });
+  const limiter = createLimiter();
+  const localProfile = safe(() => api?.localSoundProfile?.()) || null;
+  let settings = normalizeSettings({ profile: localProfile || undefined });
+  let source = localProfile ? 'local' : 'default';
+  let userSet = false;
+  let focused = null;
+  let player; // undefined = not looked up yet
+  let dir = cacheDir;
+  let focusOn = false;
+  let serverError = null;
+
+  function safe(fn) { try { return fn(); } catch { return null; } }
+  const write = (s) => { try { stdout?.write?.(s); } catch { /* never throw */ } };
+
+  // Server preference (source of truth), loaded in the background; a /sound typed meanwhile wins.
+  const ready = (async () => {
+    if (mode === 'off' || !api?.soundSettings) return;
+    try {
+      const v = await api.soundSettings();
+      if (v && !userSet) { settings = normalizeSettings(v); source = 'account'; safe(() => api.setLocalSoundProfile?.(settings.profile)); }
+    } catch (e) { serverError = e?.message || 'unreachable'; }
+  })();
+
+  if (mode !== 'off') {
+    write(FOCUS_ON);
+    focusOn = true;
+    safe(() => exitHook(dispose));
+  }
+
+  function getPlayer() {
+    if (player === undefined) player = safe(() => findPlayer({ platform, ...(has ? { has } : {}) })) || null;
+    return player;
+  }
+
+  function wavFile(id) {
+    if (!dir) dir = defaultCacheDir(env);
+    const vol = Math.round(settings.volume * 100);
+    const file = join(dir, `quox-${id}-v${vol}.wav`);
+    if (!existsSync(file)) {
+      const tmp = `${file}.${process.pid}.tmp`;
+      writeFileSync(tmp, earconWav(id, { volume: settings.volume }));
+      renameSync(tmp, file);
+    }
+    return file;
+  }
+
+  /** Emit `id` now (gates already passed). Returns how it went out: 'audio' | 'bel' | null. */
+  function emit(id) {
+    if (mode === 'off') return null;
+    const p = mode === 'audio' ? getPlayer() : null;
+    if (!p) {
+      if (!BEL_IDS.has(id)) return null;
+      write(BEL);
+      return 'bel';
+    }
+    try {
+      const file = wavFile(id);
+      const child = spawn(p.cmd, p.args(file), { detached: true, stdio: 'ignore', windowsHide: true });
+      child.on?.('error', () => {});
+      child.unref?.();
+      const t = setTimeout(() => { try { child.kill?.(); } catch { /* gone */ } }, timeoutMs);
+      t.unref?.();
+      return 'audio';
+    } catch {
+      if (BEL_IDS.has(id)) { write(BEL); return 'bel'; }
+      return null;
+    }
+  }
+
+  function observe(prev, next, action) {
+    if (mode === 'off') return null;
+    try {
+      const id = soundForEvent(prev, action, { next, now: action?.now ?? now(), focused });
+      if (!id || !allowed(id, settings) || !limiter.take(id, now())) return null;
+      emit(id);
+      return id;
+    } catch { return null; }
+  }
+
+  function outputLine() {
+    if (mode === 'off') return `Output: off (${offReason({ env, stdout, print })}).`;
+    if (mode === 'bel') return 'Output: terminal bell, approvals and critical alerts only (over SSH the speaker is on your side).';
+    const p = getPlayer();
+    return p ? `Output: speaker via ${p.cmd}.` : 'Output: terminal bell, approvals and critical alerts only (no audio player found).';
+  }
+
+  function whereLine() {
+    if (source === 'account') return 'Saved to your account; the dashboard uses the same setting.';
+    if (source === 'local') return `Saved on this machine only${serverError ? ` (account setting unreachable: ${serverError})` : ''}.`;
+    return `Default${serverError ? ` (account setting unreachable: ${serverError})` : ''}.`;
+  }
+
+  async function command(arg, say) {
+    const a = String(arg || '').trim().toLowerCase();
+    if (!a) {
+      say(`Sound: ${cap(settings.profile)} (${PROFILE_LABELS[settings.profile]}). ${whereLine()}`);
+      say(outputLine());
+      say('Change with /sound silent|minimal|operational|full · /sound test plays the approval chime · QUOX_SOUND=off mutes this terminal.');
+      return;
+    }
+    if (a === 'test') {
+      if (mode === 'off') return say(outputLine(), 'warn');
+      const how = emit('hitl');
+      return say(how === 'audio' ? `Played the approval chime via ${getPlayer().cmd}.` : how === 'bel' ? 'Rang the terminal bell.' : 'Nothing to play on.', how ? undefined : 'warn');
+    }
+    if (!PROFILE_IDS.includes(a)) return say(USAGE, 'warn');
+    userSet = true;
+    settings = normalizeSettings({ ...settings, profile: a });
+    safe(() => api?.setLocalSoundProfile?.(a));
+    try {
+      if (!api?.setSoundSettings) throw new Error('not available in this mode');
+      await api.setSoundSettings(settings);
+      source = 'account';
+      serverError = null;
+    } catch (e) {
+      serverError = e?.message || 'failed';
+      source = api?.setLocalSoundProfile ? 'local' : 'session';
+    }
+    const where = source === 'account' ? 'Saved to your account (the dashboard uses the same setting).'
+      : source === 'local' ? `Saved on this machine only: the account setting could not be written (${serverError}).`
+        : `For this session only: ${serverError}.`;
+    say(`Sound: ${cap(a)} (${PROFILE_LABELS[a]}). ${where}`, source === 'account' ? 'ok' : 'warn');
+  }
+
+  function dispose() {
+    if (!focusOn) return;
+    focusOn = false;
+    write(FOCUS_OFF);
+  }
+
+  return {
+    mode, ready, observe, command, dispose, emit,
+    focus(v) { focused = Boolean(v); },
+    settings: () => ({ ...settings }),
+    get focused() { return focused; }
+  };
+}

package/lib/quoxon/sound/mapping.js

@@ -0,0 +1,119 @@
+/**
+ * QuoxSound for the terminal: pure event -> earcon mapping, profiles and the
+ * rate limiter. Mirrors the dashboard's design (src/services/quoxSound.js):
+ * sound is STATE, not personality; the more common the event, the quieter;
+ * `hitl` is reserved for "a human must act". No sound for typing, text,
+ * routine tool rows or anything the human just did themselves.
+ *
+ * Pure: no I/O, no clocks (time comes in on ctx.now / the action).
+ */
+
+export const SOUND_IDS = ['hitl', 'notify', 'success', 'denied', 'critical'];
+
+/** Higher wins when several sounds land in one burst. */
+export const PRIORITY = { critical: 5, hitl: 4, denied: 3, success: 2, notify: 1 };
+
+/** Same layer split as the dashboard, so its per-layer toggles apply here too. */
+export const SOUND_LAYERS = { hitl: 'notifications', notify: 'notifications', success: 'agents', denied: 'security', critical: 'security' };
+export const LAYER_IDS = ['ui', 'agents', 'notifications', 'security'];
+
+/**
+ * Terminal profiles. Same names and setting as the dashboard. Minimal here
+ * also carries failures (owner brief 2026-10-12: "hitl + critical + failure"),
+ * because a failed turn in a terminal you are not watching is otherwise silent.
+ */
+export const PROFILES = {
+  silent: [],
+  minimal: ['hitl', 'critical', 'denied'],
+  operational: ['hitl', 'critical', 'denied', 'success', 'notify'],
+  full: ['hitl', 'critical', 'denied', 'success', 'notify']
+};
+export const PROFILE_IDS = ['silent', 'minimal', 'operational', 'full'];
+export const PROFILE_LABELS = {
+  silent: 'nothing',
+  minimal: 'approvals, critical alerts, failures',
+  operational: 'approvals, critical alerts, failures, long turns finishing',
+  full: 'approvals, critical alerts, failures, long turns finishing'
+};
+export const DEFAULT_PROFILE = 'minimal';
+
+export const LONG_TURN_MS = 20000;
+export const RATE_LIMIT_MS = 2000;
+/** Sounds this close together are one burst: only a more urgent one may follow. */
+export const BURST_MS = 300;
+
+const DEFAULT_LAYERS = Object.freeze({ ui: true, agents: true, notifications: true, security: true });
+
+/** Same shape as the dashboard's soundProfile preference: { profile, volume, layers }. */
+export function normalizeSettings(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const profile = PROFILE_IDS.includes(src.profile) ? src.profile : DEFAULT_PROFILE;
+  const v = Number(src.volume);
+  const volume = Number.isFinite(v) ? Math.min(1, Math.max(0, v)) : 0.6;
+  const layers = { ...DEFAULT_LAYERS };
+  if (src.layers && typeof src.layers === 'object') {
+    for (const id of LAYER_IDS) if (typeof src.layers[id] === 'boolean') layers[id] = src.layers[id];
+  }
+  return { profile, volume, layers };
+}
+
+/** May `id` play under these settings? */
+export function allowed(id, settings) {
+  const s = normalizeSettings(settings);
+  if (!SOUND_IDS.includes(id) || s.volume <= 0) return false;
+  if (!PROFILES[s.profile].includes(id)) return false;
+  return s.layers[SOUND_LAYERS[id]] !== false;
+}
+
+const FAILED_TURN = new Set(['failed', 'unconfirmed']);
+
+/**
+ * prevState + the dispatched action (+ ctx.next, the reduced state) -> sound id or null.
+ * ctx: { next, now, focused } where focused is true | false | null (unknown = treated as looking).
+ * Only state CHANGES the reducer accepted make sound: a duplicate approval or a repeated tool
+ * finish leaves the state alone and stays silent.
+ */
+export function soundForEvent(prev, action, ctx = {}) {
+  const next = ctx.next || prev;
+  const now = ctx.now ?? action?.now ?? 0;
+  if (!prev || !action) return null;
+  // An approval card appeared (stream event or inbox poll).
+  if (next.approvals?.length > (prev.approvals?.length || 0)) return 'hitl';
+  if (action.type === 'approval.result') return action.outcome === 'failed' ? 'denied' : null;
+  if (action.type !== 'event' || !action.ev) return null;
+  const ev = action.ev;
+  switch (ev.type) {
+    case 'alert':
+      return ev.severity === 'critical' ? 'critical' : null;
+    case 'tool.finished': {
+      if (ev.status !== 'failed' && ev.status !== 'denied') return null;
+      return prev.doneCalls?.[ev.call_id] ? null : 'denied';
+    }
+    case 'turn.finished': {
+      if (!prev.turn) return null; // dedupe: no running turn
+      const status = ev.status || 'completed';
+      if (FAILED_TURN.has(status)) return 'denied';
+      if (status !== 'completed') return null; // interrupted: the human pressed Esc
+      const took = prev.turn.startedAt != null ? now - prev.turn.startedAt : 0;
+      return took > LONG_TURN_MS || ctx.focused === false ? 'success' : null;
+    }
+    default:
+      return null;
+  }
+}
+
+/** At most one sound per type per RATE_LIMIT_MS; inside a burst only a more urgent sound plays. */
+export function createLimiter({ windowMs = RATE_LIMIT_MS, burstMs = BURST_MS } = {}) {
+  const last = new Map();
+  let lastAny = null;
+  return {
+    take(id, now) {
+      const t = last.get(id);
+      if (t != null && now - t < windowMs) return false;
+      if (lastAny && now - lastAny.at < burstMs && PRIORITY[id] <= PRIORITY[lastAny.id]) return false;
+      last.set(id, now);
+      lastAny = { id, at: now };
+      return true;
+    }
+  };
+}

package/lib/quoxon/sound/output.js

@@ -0,0 +1,52 @@
+/**
+ * Where a terminal earcon goes: a local OS player, the terminal bell, or
+ * nowhere. Pure decisions here; the controller (index.js) does the I/O.
+ */
+import { spawnSync } from 'node:child_process';
+
+const OFF_VALUES = new Set(['off', '0', 'false', 'no', 'silent']);
+
+/**
+ * 'off'   : --print, non-TTY, CI, or QUOX_SOUND=off. Never a sound, never an escape write.
+ * 'bel'   : over SSH the speaker is on the other end, so only the terminal bell can reach it.
+ * 'audio' : a local desktop; play the WAV (falls back to the bell when no player exists).
+ */
+export function soundMode({ env = {}, stdout, print = false } = {}) {
+  if (print || !stdout?.isTTY) return 'off';
+  if (env.CI && !OFF_VALUES.has(String(env.CI).toLowerCase())) return 'off';
+  if (OFF_VALUES.has(String(env.QUOX_SOUND ?? '').toLowerCase())) return 'off';
+  if (env.SSH_CONNECTION || env.SSH_TTY) return 'bel';
+  return 'audio';
+}
+
+const psQuote = (s) => `'${String(s).replace(/'/g, "''")}'`;
+
+const PLAYERS = {
+  linux: [
+    { cmd: 'pw-play', args: (f) => [f] },
+    { cmd: 'paplay', args: (f) => [f] },
+    { cmd: 'aplay', args: (f) => ['-q', f] }
+  ],
+  darwin: [{ cmd: 'afplay', args: (f) => [f] }],
+  win32: [{ cmd: 'powershell', args: (f) => ['-NoProfile', '-NonInteractive', '-Command', `(New-Object Media.SoundPlayer(${psQuote(f)})).PlaySync()`] }]
+};
+
+/** Is `cmd` on PATH? (one lookup per player, cached by the controller) */
+export function onPath(cmd, platform = process.platform) {
+  try {
+    const r = platform === 'win32'
+      ? spawnSync('where', [cmd], { stdio: 'ignore', timeout: 2000 })
+      : spawnSync('sh', ['-c', `command -v ${cmd}`], { stdio: 'ignore', timeout: 2000 });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+/** First available player for this platform, or null. */
+export function findPlayer({ platform = process.platform, has = (c) => onPath(c, platform) } = {}) {
+  const list = PLAYERS[platform] || PLAYERS.linux;
+  return list.find(p => has(p.cmd)) || null;
+}
+
+/** Only these may ring the bell: the bell is for a human, not for feedback. */
+export const BEL_IDS = new Set(['hitl', 'critical']);
+export const BEL = '\x07';

package/lib/quoxon/sound/synth.js

@@ -0,0 +1,122 @@
+/**
+ * Offline renderer for the QuoxSound earcons: the dashboard's Web Audio
+ * recipes (src/services/quoxSound.js RECIPES) rendered sample by sample into
+ * 16-bit mono PCM WAV. No assets, no dependencies.
+ *
+ * Timbre: fundamental + octave (0.18) + twelfth (0.07), linear attack then an
+ * exponential decay to near-silence, same as the phone earcons. `success`
+ * reuses the granted interval (587 -> 880 Hz), `denied` the denied floor
+ * (233 Hz gliding down through a 600 Hz lowpass).
+ */
+
+export const SAMPLE_RATE = 44100;
+const HARMONICS = [[1, 1], [2, 0.18], [3, 0.07]];
+const FLOOR = 0.0001;
+
+/** The recipes as data: the same notes, times and envelopes as the dashboard. */
+export const RECIPES = {
+  hitl: { notes: [
+    { freq: 523.25, at: 0, decay: 0.30, peak: 0.20 },
+    { freq: 659.25, at: 0.15, decay: 0.30, peak: 0.19 },
+    { freq: 880.0, at: 0.30, decay: 0.32, peak: 0.18 }
+  ] },
+  notify: { notes: [
+    { freq: 698.46, at: 0, attack: 0.01, decay: 0.10, peak: 0.11 },
+    { freq: 932.33, at: 0.10, attack: 0.01, decay: 0.14, peak: 0.10 }
+  ] },
+  success: { notes: [
+    { freq: 587.33, at: 0, attack: 0.003, decay: 0.04, peak: 0.09 },
+    { freq: 880.0, at: 0.045, attack: 0.003, decay: 0.07, peak: 0.09 }
+  ] },
+  denied: { lowpass: 600, notes: [
+    { freq: 233.08, glideTo: 150, at: 0, attack: 0.004, decay: 0.16, peak: 0.28, harmonics: [[1, 1]] }
+  ] },
+  critical: { lowpass: 2400, notes: [0, 1, 2].map(i => (
+    { freq: 622.25, at: i * 0.12, type: 'square', attack: 0.003, decay: 0.07, peak: 0.12, harmonics: [[1, 1]] }
+  )) }
+};
+
+function envelope(t, attack, decay, peak) {
+  if (t < 0) return 0;
+  if (t < attack) return FLOOR + (peak - FLOOR) * (t / attack);
+  const d = t - attack;
+  if (d < decay) return peak * Math.pow(FLOOR / peak, d / decay);
+  return 0;
+}
+
+function renderNote(out, sr, n) {
+  const attack = n.attack ?? 0.008;
+  const decay = n.decay ?? 0.2;
+  const peak = n.peak ?? 0.2;
+  const harmonics = n.harmonics || HARMONICS;
+  const len = attack + decay + 0.02;
+  const start = Math.round(n.at * sr);
+  const count = Math.min(out.length - start, Math.round(len * sr));
+  for (const [mult, level] of harmonics) {
+    let phase = 0;
+    for (let i = 0; i < count; i++) {
+      const t = i / sr;
+      // exponential glide over attack + decay, then held (as exponentialRampToValueAtTime)
+      const f = n.glideTo ? n.freq * Math.pow(n.glideTo / n.freq, Math.min(1, t / (attack + decay))) : n.freq;
+      phase += (2 * Math.PI * f * mult) / sr;
+      const osc = n.type === 'square' ? (Math.sin(phase) >= 0 ? 1 : -1) : Math.sin(phase);
+      out[start + i] += osc * level * envelope(t, attack, decay, peak);
+    }
+  }
+}
+
+/** RBJ biquad lowpass, in place. */
+function lowpass(buf, sr, cutoff, q = Math.SQRT1_2) {
+  const w0 = (2 * Math.PI * cutoff) / sr;
+  const alpha = Math.sin(w0) / (2 * q);
+  const cos = Math.cos(w0);
+  const a0 = 1 + alpha;
+  const b0 = (1 - cos) / 2 / a0, b1 = (1 - cos) / a0, b2 = (1 - cos) / 2 / a0;
+  const a1 = (-2 * cos) / a0, a2 = (1 - alpha) / a0;
+  let x1 = 0, x2 = 0, y1 = 0, y2 = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const x = buf[i];
+    const y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2;
+    x2 = x1; x1 = x; y2 = y1; y1 = y;
+    buf[i] = y;
+  }
+}
+
+/** Render one earcon to float samples in [-1, 1]. */
+export function renderEarcon(id, { volume = 0.6, sampleRate = SAMPLE_RATE } = {}) {
+  const r = RECIPES[id];
+  if (!r) throw new Error(`unknown earcon ${id}`);
+  const secs = Math.max(...r.notes.map(n => n.at + (n.attack ?? 0.008) + (n.decay ?? 0.2) + 0.02));
+  const out = new Float32Array(Math.ceil(secs * sampleRate));
+  for (const n of r.notes) renderNote(out, sampleRate, n);
+  if (r.lowpass) lowpass(out, sampleRate, r.lowpass);
+  const g = Math.min(1, Math.max(0, volume));
+  for (let i = 0; i < out.length; i++) out[i] = Math.max(-1, Math.min(1, out[i] * g));
+  return out;
+}
+
+/** Float samples -> 16-bit mono PCM WAV (44-byte RIFF header). */
+export function toWav(samples, sampleRate = SAMPLE_RATE) {
+  const data = samples.length * 2;
+  const buf = Buffer.alloc(44 + data);
+  buf.write('RIFF', 0, 'ascii');
+  buf.writeUInt32LE(36 + data, 4);
+  buf.write('WAVE', 8, 'ascii');
+  buf.write('fmt ', 12, 'ascii');
+  buf.writeUInt32LE(16, 16);        // fmt chunk size
+  buf.writeUInt16LE(1, 20);         // PCM
+  buf.writeUInt16LE(1, 22);         // mono
+  buf.writeUInt32LE(sampleRate, 24);
+  buf.writeUInt32LE(sampleRate * 2, 28); // byte rate
+  buf.writeUInt16LE(2, 32);         // block align
+  buf.writeUInt16LE(16, 34);        // bits per sample
+  buf.write('data', 36, 'ascii');
+  buf.writeUInt32LE(data, 40);
+  for (let i = 0; i < samples.length; i++) {
+    const v = Math.max(-1, Math.min(1, samples[i]));
+    buf.writeInt16LE(Math.round(v < 0 ? v * 0x8000 : v * 0x7fff), 44 + i * 2);
+  }
+  return buf;
+}
+
+export const earconWav = (id, opts = {}) => toWav(renderEarcon(id, opts), opts.sampleRate ?? SAMPLE_RATE);

package/lib/quoxon/term.js

@@ -0,0 +1,106 @@
+/**
+ * The terminal as Ink sees it.
+ *
+ * Ink 6.8 has a bookkeeping defect on its "frame was as tall as the screen" path (ink.js onRender): it
+ * repaints with clearTerminal + all static output + the frame WITHOUT a trailing newline, then records the
+ * frame WITH one (log.sync(outputToRender)). log-update then believes the cursor is one row lower than it
+ * is, so its next erase removes one extra row: the last line of whatever <Static> printed last. On
+ * 2026-10-12 that silently deleted "status writeup that's supposed to accompany completion." from a LUCID
+ * answer at 64x34 (test/quoxon/dropped.test.jsx replays it).
+ *
+ * Fix: Ink is told the screen has unlimited rows, so it never takes that path (only the fullscreen and
+ * repaint checks read stdout.rows). The app reads the real height from termRows() and keeps its live
+ * region shorter than the screen itself (app.js), so log-update can always erase it.
+ */
+export function inkStdout(out) {
+  if (!out || out.__quoxInk) return out;
+  const diff = out.isTTY ? createLineDiff() : null;
+  // One frame = one write: Ink brackets each frame in separate synchronized-update writes (?2026h ... ?2026l);
+  // they are held and sent together with the (diffed) frame, and a frame that changed nothing sends nothing.
+  // A write that sends nothing (or is held for the frame) must still call its callback: Ink's unmount waits
+  // on write('', cb) before waitUntilExit() resolves, and a dropped callback let the event loop drain, so
+  // the process exited without running anything after the app (/restart never started the new client).
+  let held = null;
+  let waiting = [];
+  const settle = () => { const cbs = waiting; waiting = []; for (const cb of cbs) cb(); };
+  const flush = () => {
+    if (held == null) return;
+    const body = held; held = null;
+    if (body) out.write(SYNC_ON + body + SYNC_OFF, settle); else if (waiting.length) out.write('', settle);
+  };
+  const write = diff ? (chunk, ...rest) => {
+    if (typeof chunk !== 'string') { flush(); diff.reset(); return out.write(chunk, ...rest); }
+    const cb = rest.find(a => typeof a === 'function');
+    if (chunk === SYNC_ON) { flush(); held = ''; setImmediate(flush); if (cb) waiting.push(cb); return true; }
+    if (chunk === SYNC_OFF && held != null) { if (cb) waiting.push(cb); flush(); return true; }
+    const d = diff(chunk);
+    if (held != null) { held += d; if (cb) waiting.push(cb); return true; }
+    if (d) return out.write(d, ...rest);
+    if (cb) out.write('', cb); // nothing to send: still a barrier behind the earlier writes
+    return true;
+  } : null;
+  return new Proxy(out, {
+    get(target, prop) {
+      if (prop === 'write' && write) return write;
+      if (prop === 'rows') return Infinity;
+      if (prop === 'termRows') return target.rows;
+      if (prop === '__quoxInk') return true;
+      const v = Reflect.get(target, prop, target);
+      return typeof v === 'function' ? v.bind(target) : v;
+    },
+    set(target, prop, value) { return Reflect.set(target, prop, value, target); }
+  });
+}
+
+/** Real terminal height, or null when unknown (not a TTY, tests). */
+export function termRows(stdout) {
+  const r = stdout?.__quoxInk ? stdout.termRows : stdout?.rows;
+  return Number.isFinite(r) && r > 0 ? r : null;
+}
+
+/**
+ * Line-diffed live frames (so native text selection survives animation).
+ *
+ * Ink repaints its live region as ONE write: eraseLines(previous line count) followed by the whole frame. A 12 fps
+ * ring or activity word would then rewrite the input line, and the user's selection on it, every frame. This
+ * transform recognises exactly that shape; when the new frame has the same height as the last one it moves up
+ * and rewrites only the lines that changed, leaving the cursor where Ink expects it (start of the line after the
+ * frame). Anything else (static history, clears, a height change, a resize, a write it did not see) passes
+ * through untouched and resets the diff, so the next frame is drawn in full. Cursor moves never scroll.
+ * (Ink's own incrementalRendering was tried first and duplicates lines on the dropped-text replay.)
+ */
+const FRAME_RE = /^((?:\x1b\[2K\x1b\[1A)*\x1b\[2K\x1b\[G)([\s\S]*)$/;
+const SYNC_ON = '\x1b[?2026h', SYNC_OFF = '\x1b[?2026l';
+const TRANSPARENT = new Set(['\x1b[?2026h', '\x1b[?2026l', '\x1b[?25l', '\x1b[?25h', '']);
+export function createLineDiff() {
+  let prev = null; // lines of the last frame, trailing '' included
+  const diff = (chunk) => {
+    if (TRANSPARENT.has(chunk)) return chunk; // synchronized-update brackets and cursor hide/show around a frame
+    const m = FRAME_RE.exec(chunk);
+    if (!m || !m[2].endsWith('\n') || m[2].includes('\x1b[2J')) { prev = null; return chunk; }
+    const erased = (m[1].match(/\x1b\[2K/g) || []).length;
+    const next = m[2].split('\n');
+    if (!prev || erased !== prev.length || next.length !== prev.length || next.length < 2) { prev = next; return chunk; }
+    const body = next.length - 1;
+    let out = body > 1 ? `\x1b[${body}A` : (body === 1 ? '\x1b[1A' : '');
+    let changed = 0;
+    for (let i = 0; i < body; i++) {
+      if (next[i] !== prev[i]) { out += `\r${next[i]}\x1b[K`; changed++; }
+      out += '\x1b[1B';
+    }
+    out += '\r';
+    prev = next;
+    return changed ? out : '';
+  };
+  diff.reset = () => { prev = null; };
+  return diff;
+}
+
+/**
+ * Ink render options for the interactive client. Standard rendering (Ink's incrementalRendering duplicated lines on
+ * the dropped-text replay); the stdout proxy line-diffs same-height frames instead. Never mouse tracking, never the
+ * alternate screen: native selection keeps working.
+ */
+export function inkRenderOptions(stdout) {
+  return { exitOnCtrlC: false, stdout: inkStdout(stdout) };
+}