quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/slotFormat.js

@@ -0,0 +1,195 @@
+/**
+ * SLOT-RUN A (owner 2026-10-16, about a slot message that arrived as a wrapped wall of text around a long
+ * shell command: "messy needs a format, structure, styling"). Incoming slot message bodies render light
+ * markdown: paragraphs, - bullets, **bold**, `inline code` and fenced blocks.
+ *
+ * Code is never wrapped mid-token. A long inline command is lifted into its own block; a block line that does
+ * not fit breaks ONLY at unquoted whitespace and ends in " \" (shell line continuation), so a copied block is
+ * still the same command. A single token longer than the row hard-breaks with a visible " ↩".
+ *
+ * Pure layout: rows of segments { t, role, bold? }. render.js paints them; no grey roles (owner rule).
+ */
+import { graphemes } from './textBuffer.js';
+
+export const CONT = ' \\';
+export const HARD = ' ↩';
+export const GUTTER = '│ ';
+export const LONG_INLINE = 32; // an inline code span longer than this gets its own block
+
+const len = (s) => graphemes(String(s)).length;
+
+/** Where a line may break: unquoted, unescaped whitespace before any unquoted # comment. */
+function safeBreaks(chars) {
+  const safe = new Array(chars.length).fill(false);
+  let q = null; let comment = false;
+  for (let i = 0; i < chars.length; i++) {
+    const ch = chars[i];
+    if (comment) continue;
+    if (q === "'") { if (ch === "'") q = null; continue; }
+    if (q === '"') { if (ch === '\\') i++; else if (ch === '"') q = null; continue; }
+    if (ch === '\\') { i++; continue; }
+    if (ch === "'" || ch === '"') { q = ch; continue; }
+    if (ch === '#' && (i === 0 || /\s/.test(chars[i - 1]))) { comment = true; continue; }
+    if (/\s/.test(ch)) safe[i] = true;
+  }
+  return safe;
+}
+
+/** One command line as rows of at most `width` columns. Continuation rows are indented two spaces. */
+export function wrapShell(line, width) {
+  const w = Math.max(12, width);
+  const chars = [...String(line)];
+  if (chars.length <= w) return [chars.join('')];
+  const safe = safeBreaks(chars);
+  const out = [];
+  let start = 0;
+  for (;;) {
+    const indent = out.length ? '  ' : '';
+    const avail = w - indent.length;
+    if (chars.length - start <= avail) { out.push(indent + chars.slice(start).join('')); break; }
+    const lim = avail - CONT.length;
+    let cut = -1;
+    for (let i = start + lim; i > start; i--) if (safe[i]) { cut = i; break; }
+    if (cut > start) {
+      out.push(indent + chars.slice(start, cut).join('').replace(/\s+$/, '') + CONT);
+      start = cut;
+      while (start < chars.length && safe[start]) start++;
+    } else {
+      const n = avail - HARD.length;
+      out.push(indent + chars.slice(start, start + n).join('') + HARD);
+      start += n;
+    }
+  }
+  return out;
+}
+
+/** Inline runs of one line: plain text, **bold**, `code`. */
+function inlineRuns(text) {
+  const out = [];
+  const re = /(`+)([^`]+?)\1|\*\*([^*]+?)\*\*/g;
+  let last = 0; let m;
+  const s = String(text);
+  while ((m = re.exec(s))) {
+    if (m.index > last) out.push({ kind: 'text', t: s.slice(last, m.index) });
+    if (m[1]) out.push({ kind: 'code', t: m[2].trim() });
+    else out.push({ kind: 'bold', t: m[3] });
+    last = m.index + m[0].length;
+  }
+  if (last < s.length) out.push({ kind: 'text', t: s.slice(last) });
+  return out;
+}
+
+/** Block structure: code (fenced, `$ ` lines, long inline spans), bullets, paragraphs, gaps. */
+function blocks(text) {
+  const src = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const out = [];
+  const push = (b) => {
+    if (b.type === 'gap' && (!out.length || out[out.length - 1].type === 'gap')) return;
+    out.push(b);
+  };
+  for (let i = 0; i < src.length; i++) {
+    const line = src[i];
+    const fence = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      const lines = [];
+      for (i++; i < src.length && !src[i].trim().startsWith(fence[1]); i++) lines.push(src[i]);
+      push({ type: 'code', lines });
+      continue;
+    }
+    if (/^\s*\$ \S/.test(line)) {
+      const prev = out[out.length - 1];
+      if (prev?.type === 'code' && prev.dollar) prev.lines.push(line.trim()); else push({ type: 'code', lines: [line.trim()], dollar: true });
+      continue;
+    }
+    if (!line.trim()) { push({ type: 'gap' }); continue; }
+    const bullet = /^\s*(?:[-*•]|(\d+[.)]))\s+(.*)$/.exec(line);
+    const heading = /^\s*#{1,6}\s+(.*)$/.exec(line);
+    const kind = bullet ? 'bullet' : 'para';
+    const body = bullet ? bullet[2] : heading ? `**${heading[1]}**` : line;
+    const mark = bullet ? (bullet[1] ? `${bullet[1]} ` : '• ') : '';
+    // A long inline command is lifted out into its own block between the prose around it.
+    let pending = [];
+    let first = true;
+    const flush = () => {
+      if (!pending.length) return;
+      if (pending.some(r => r.kind !== 'text' || r.t.trim())) push({ type: kind, runs: pending, mark: first ? mark : (mark ? '  ' : '') });
+      first = false; pending = [];
+    };
+    for (const r of inlineRuns(body)) {
+      if (r.kind === 'code' && len(r.t) > LONG_INLINE) { flush(); push({ type: 'code', lines: [r.t] }); first = false; }
+      else pending.push(r);
+    }
+    flush();
+  }
+  while (out.length && out[out.length - 1].type === 'gap') out.pop();
+  return out;
+}
+
+/** Word-wrap inline runs to `width`; code spans are unbreakable atoms (hard-split only if wider than the row). */
+function wrapRuns(runs, width, role, prefix) {
+  const atoms = [];
+  for (const r of runs) {
+    if (r.kind === 'code') { atoms.push({ t: r.t, role: 'code', sp: /^\s/.test(r.t) }); continue; }
+    const parts = r.t.split(/(\s+)/);
+    for (const p of parts) {
+      if (!p) continue;
+      if (/^\s+$/.test(p)) { atoms.push({ space: true }); continue; }
+      atoms.push({ t: p, role, bold: r.kind === 'bold' || undefined });
+    }
+  }
+  const rows = [];
+  let cur = []; let w = 0; let gap = false;
+  const ind = len(prefix);
+  const room = Math.max(8, width - ind);
+  const add = (seg) => {
+    const last = cur[cur.length - 1];
+    if (last && last.role === seg.role && last.bold === seg.bold) last.t += seg.t; else cur.push({ ...seg });
+  };
+  const newRow = () => { rows.push(cur); cur = []; w = 0; };
+  for (const a of atoms) {
+    if (a.space) { gap = true; continue; }
+    const sep = cur.length && gap ? 1 : 0; // runs that touch (`a`**b**) stay touching
+
+    let t = a.t;
+    if (w + sep + len(t) > room && cur.length) newRow();
+    else if (sep) { add({ t: ' ', role, bold: undefined }); w += 1; }
+    while (len(t) > room) { const g = graphemes(t); add({ t: g.slice(0, room - w).join(''), role: a.role, bold: a.bold }); t = g.slice(room - w).join(''); newRow(); }
+    add({ t, role: a.role, bold: a.bold }); w += len(t);
+    gap = false;
+  }
+  if (cur.length) rows.push(cur);
+  return rows.map((r, i) => (prefix ? [{ t: i === 0 ? prefix : ' '.repeat(ind), role: 'bullet1' }, ...r] : r));
+}
+
+/** A code block's rows: gutter, the code, and the continuation marker in the label colour. */
+export function codeRows(lines, width) {
+  const rows = [];
+  for (const line of lines) {
+    for (const piece of wrapShell(line, Math.max(12, width - len(GUTTER)))) {
+      const mk = piece.endsWith(CONT) ? CONT : piece.endsWith(HARD) ? HARD : '';
+      const body = mk ? piece.slice(0, -mk.length) : piece;
+      rows.push([{ t: GUTTER, role: 'label' }, { t: body || ' ', role: 'code' }, ...(mk ? [{ t: mk, role: 'label' }] : [])]);
+    }
+  }
+  return rows;
+}
+
+/** The body of a slot message as rows of segments, at most `width` columns each. */
+export function formatSlotBody(text, width, { role = 'text' } = {}) {
+  const rows = [];
+  for (const b of blocks(text)) {
+    if (b.type === 'gap') rows.push([]);
+    else if (b.type === 'code') rows.push(...codeRows(b.lines, width));
+    else rows.push(...wrapRuns(b.runs, width, role, b.mark));
+  }
+  return rows;
+}
+
+/** Plain text of each row (tests, NO_COLOR). */
+export const rowsText = (rows) => rows.map(r => r.map(s => s.t).join(''));
+
+/** A short plain one-liner keeps the chat shape: on the header line after the time. */
+export function inlineable(text, room) {
+  const t = String(text ?? '');
+  return !/[\n`]|\*\*/.test(t) && !/^\s*(?:[-*•]\s|\d+[.)]\s|\$ |#{1,6}\s)/.test(t) && len(t) <= room;
+}

package/lib/quoxon/slotRun.js

@@ -0,0 +1,131 @@
+/**
+ * SLOT-RUN B (owner 2026-10-16: "if its a request to run the command, let me just say yes"). A slot message may
+ * carry ONE command for the human to run here (`quox slot say <slot> --run '<command>' "<why>"`, stored by the
+ * collector as the message's `run` field, never executed server-side).
+ *
+ * The TUI shows it with the shared ask: "▶ SENDER asks you to run this here: why", the FULL command in a code
+ * block (wrapped, never truncated: this is a confirm-what-you-see boundary), then "Run it? y/N/c". y hands the
+ * terminal over (like /restart: the user's own shell, stdio inherited, so OTP and login prompts work), then
+ * the TUI resumes and prints the exit code.
+ *
+ * Rules (non-negotiable): never auto-run; only from a verified sender (author_identity) in this org, otherwise
+ * shown but refused; one command; the ask expires after RUN_TTL_MS; never through the model (no turn, never a
+ * terminal_suggest_command offer); secret-shaped or destructive commands need "run" typed instead of y.
+ */
+import { spawnSync } from 'node:child_process';
+import { askText, askAnswer } from './ask.js';
+import { looksLikeKey } from './connect.js';
+import { resolveCliSlash } from './slash/cliCommand.js';
+import { tokenize } from './bang.js';
+import { codeRows } from './slotFormat.js';
+import { graphemes } from './textBuffer.js';
+import { TERMINAL_RESTORE } from './slash/restart.js';
+import { PASTE_ON } from './keys.js';
+
+export const RUN_TTL_MS = 10 * 60 * 1000;
+export const RUN_MAX_LEN = 2000;
+// Same rule as the collector (devSlotMessagesStore validateRunCommand): one line, nothing that can make the
+// screen differ from what runs (control/ESC/CR, bidi overrides, zero-width, line separators).
+const RUN_BAD_RE = /[\u0000-\u001f\u007f\u0080-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/;
+
+/** -> null (no run request) | { id, cmd, why, who, runnable, refuse, danger, expiresAt }. */
+export function runRequest(m, { orgId = null, now = Date.now() } = {}) {
+  if (!m || m.run === undefined || m.run === null || m.run === '') return null;
+  const cmd = String(m.run);
+  const who = String(m.from || m.author_identity || 'someone').replace(/\s*\(.*$/, '').trim() || 'someone';
+  let refuse = null;
+  if (!m.author_identity) refuse = `${who} is not a verified sender, so this window will not run it`;
+  else if (orgId && m.org_id && m.org_id !== orgId) refuse = `it came from another org, so this window will not run it`;
+  else if (cmd.length > RUN_MAX_LEN || !cmd.trim() || RUN_BAD_RE.test(cmd)) refuse = 'it is not one plain command on one line, so this window will not run it';
+  return { id: m.id || null, cmd, why: String(m.text ?? '').trim(), who, runnable: !refuse, refuse, danger: refuse ? null : runDanger(cmd), expiresAt: now + RUN_TTL_MS };
+}
+
+// Destructive shell shapes (the bang runner has no shell danger list of its own; these are the ones that cost
+// real work to undo). Matching one means "type run", never a refusal: it is the human's machine.
+const DESTRUCTIVE = [
+  /(^|[\s;&|(])rm\s+(-[a-zA-Z]*[rf][a-zA-Z]*\s+)*-[a-zA-Z]*[rRf]/, /(^|[\s;&|(])sudo\s/, /(^|[\s;&|(])doas\s/,
+  /(^|[\s;&|(])mkfs(\.\w+)?\s/, /(^|[\s;&|(])dd\s+[^|;&]*\bof=/, />\s*\/dev\/(sd|nvme|hd|vd|disk)/,
+  /\|\s*(sudo\s+)?(ba|z|da|k)?sh\b/, /\bgit\s+push\b[^|;&]*\s(--force\b|-f\b|--force-with-lease\b|--delete\b)/,
+  /\bgit\s+reset\s+--hard\b/, /\bgit\s+clean\s+-[a-zA-Z]*f/, /\bchmod\s+-R\b/, /\bchown\s+-R\b/,
+  /:\(\)\s*\{/, /(^|[\s;&|(])(shutdown|reboot|halt|poweroff)\b/, /\bdrop\s+(table|database)\b/i, /\bdocker\s+(system\s+prune|volume\s+rm)\b/,
+];
+
+/** null when y is enough; otherwise the reason "run" must be typed. Reuses the bang secret check and the quox CLI leaf policy. */
+export function runDanger(cmd) {
+  const c = String(cmd || '');
+  if (looksLikeKey(c)) return 'It contains something that looks like a key or token';
+  const words = tokenize(c);
+  if (words[0] === 'quox' || words[0] === 'q') {
+    const hit = resolveCliSlash(`/${words[1] || ''}`, words.slice(2).map(w => (/[\s"']/.test(w) ? JSON.stringify(w) : w)).join(' '));
+    if (hit?.cls === 'never') return `${hit.display} is a never-from-chat quox command`;
+  }
+  if (DESTRUCTIVE.some(re => re.test(c))) return /(^|[\s;&|(])(sudo|doas)\s/.test(c) ? 'It runs as root' : 'It looks destructive';
+  return null;
+}
+
+/** 'run' | 'needs-run' (y on a dangerous one) | 'no' | 'chat' | 'command'. */
+export function runAnswer(text, req) {
+  const t = String(text ?? '').trim();
+  if (/^run$/i.test(t)) return 'run';
+  const a = askAnswer(t);
+  if (a === 'yes') return req?.danger ? 'needs-run' : 'run';
+  return a;
+}
+
+const len = (s) => graphemes(String(s)).length;
+function wrapWords(text, width) {
+  const out = []; let line = '';
+  for (const w of String(text).split(/\s+/).filter(Boolean)) {
+    if (line && len(line) + 1 + len(w) > width) { out.push(line); line = w; } else line = line ? `${line} ${w}` : w;
+  }
+  if (line) out.push(line);
+  return out;
+}
+
+/** The ask as rows of segments (render.js paints them; slotFormat rows shape). */
+export function runAskRows(req, width) {
+  const w = Math.max(20, width);
+  const head = askText(`${req.who} asks you to run this here:`, { keys: '' }) + (req.why ? ` ${req.why}` : '');
+  const rows = wrapWords(head, w).map((l, i) => [{ t: i ? `  ${l}` : l, role: 'ask', bold: true }]);
+  // wrapWords may push an indented continuation over the width: re-wrap continuations at w - 2
+  const fixed = [];
+  for (const r of rows) { if (len(r[0].t) <= w) fixed.push(r); else for (const p of wrapWords(r[0].t, w - 2)) fixed.push([{ t: `  ${p}`, role: 'ask', bold: true }]); }
+  fixed.push(...codeRows([req.cmd], w));
+  let last;
+  if (!req.runnable) last = { t: `✖ Not offered: ${req.refuse}. Copy it yourself only if you trust it.`, role: 'warn' };
+  else if (req.danger) last = { t: askText('Type run to run it, n to skip?', { keys: 'run/N/c', reason: req.danger }), role: 'ask', bold: true };
+  else last = { t: askText('Run it?'), role: 'ask', bold: true };
+  for (const l of wrapWords(last.t, w)) fixed.push([{ ...last, t: l }]);
+  return fixed;
+}
+
+/**
+ * Run the command in the user's own shell with the terminal handed over (stdio inherited), then take it back.
+ * The live frame is cleared first and padded after, so the TUI redraws below the command's output instead of
+ * over it. -> { code, signal, ms } | { error, ms }.
+ */
+export function handOverRun({ cmd, file = null, args = null, env = process.env, cwd = process.cwd(), stdout = null, setRawMode = null, spawn = spawnSync, shell, now = Date.now, resume = '' }) {
+  const tty = Boolean(stdout?.isTTY);
+  const rows = tty ? Math.max(0, Number(stdout.frameRows) || 0) : 0;
+  const put = (s) => { try { stdout.write(Buffer.from(s)); } catch { /* closed */ } };
+  if (tty) put(`\r${rows ? `\x1b[${rows}A` : ''}\x1b[J${TERMINAL_RESTORE}`);
+  try { setRawMode?.(false); } catch { /* not a tty */ }
+  const t0 = now();
+  let r;
+  try { // file + args (BANG-TTY: !quox runs this binary's argv) or a shell command line
+    r = file ? spawn(file, args || [], { stdio: 'inherit', cwd, env }) : spawn(shell || env.SHELL || '/bin/sh', ['-lc', cmd], { stdio: 'inherit', cwd, env });
+  } catch (e) { r = { error: e }; }
+  const ms = now() - t0;
+  try { setRawMode?.(true); } catch { /* not a tty */ }
+  if (tty) put(`\n${'\n'.repeat(rows)}${PASTE_ON}${resume}`); // resume: mouse tracking back on when /mouse on (QUOXON-MOUSE)
+  if (r?.error) return { error: `${r.error.code || 'failed'}: ${r.error.message}`, ms };
+  return { code: r?.status ?? null, signal: r?.signal || null, ms };
+}
+
+/** The footer after a hand-over run. */
+export function runFooter(r) {
+  const secs = `${(r.ms / 1000).toFixed(1)}s`;
+  if (r.error) return `Could not start it: ${r.error}`;
+  if (r.signal) return `killed by ${r.signal} · ${secs}`;
+  return `exit ${r.code} · ${secs}`;
+}

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,120 @@
+/**
+ * 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) || next.waiting?.length > (prev.waiting?.length || 0)) return 'hitl'; // a card, or another session's notice
+  if (action.type === 'approval.result') return action.outcome === 'failed' ? 'denied' : null;
+  if (action.type === 'stepup.result') return action.ok ? 'success' : 'denied'; // QUOXON-STEPUP: reuse the existing cues
+  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;
+    }
+  };
+}