quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/slotChat.js

@@ -0,0 +1,300 @@
+/**
+ * QUOXON-MESH: slot chat in the quox TUI. Owner, 2026-10-14: "it would be cool if session to session messaging
+ * was faster, more responsive... instant... like chat". A window holding a slot listens on the collector's slot
+ * stream (GET /api/v1/slots/:name/stream, SSE, pushed from the same notify bus as `quox slot wait`) and renders
+ * each message as a chat line above the composer. `@slot text`, `/say` and `/send` post without a model turn.
+ *
+ * Pure helpers and the listener live here; app.js wires them.
+ */
+import { readFileSync, writeFileSync, mkdirSync, statSync, readdirSync, renameSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, basename, resolve, isAbsolute } from 'node:path';
+import { scrub } from './transcript.js';
+import { looksLikeKey } from './connect.js';
+import { addressLabel } from './session.js';
+
+// ---- outbound ------------------------------------------------------------------------------------
+const AT_RE = /^@([A-Za-z0-9][A-Za-z0-9-]{0,31}):?[ \t]+(\S[\s\S]*)$/;
+// The server's own leading-address forms (devSlotMessagesStore parseAddressedTo) stay message text.
+const RESERVED = /^(all|S\d+|M\d+)$/i;
+
+/** `@quox2 hello` -> { slot: 'quox2', text: 'hello' }; anything else -> null. */
+export function parseAtSend(text) {
+  const m = AT_RE.exec(String(text || ''));
+  if (!m || RESERVED.test(m[1])) return null;
+  const body = m[2].replace(/\s+$/, '');
+  return body ? { slot: m[1].toLowerCase(), text: body } : null;
+}
+
+const labelSafe = (s) => String(s || '').replace(/[^A-Za-z0-9._@:\- ]/g, '').replace(/\s+/g, ' ').trim().slice(0, 24);
+
+/** What a window signs its lines as: "quox1 (Adam)", the slot alone, the name alone, or null (server derives). */
+export function senderLabel({ slot, display }) {
+  const d = labelSafe(display);
+  if (slot) return d ? `${slot} (${d})` : slot;
+  return d || null;
+}
+
+// ---- files ---------------------------------------------------------------------------------------
+export const FILE_CAP = 64 * 1024;
+const FILE_HEAD = '📎 ';
+const FENCE = '~~~~~~'; // a fence a pasted Markdown file is very unlikely to contain
+
+/** The wire form of a file: one header line, then the body inside a long tilde fence (renders as a block in Discord/Matrix too). */
+export function fileMessage({ name, body, size }) {
+  const lines = String(body).split('\n').length;
+  return `${FILE_HEAD}${basename(String(name))} (${fmtSize(size ?? Buffer.byteLength(String(body)))}, ${lines} line${lines === 1 ? '' : 's'})\n${FENCE}\n${body}\n${FENCE}`;
+}
+
+/** -> { name, meta, body } for a file message, else null. */
+export function parseFileMessage(text) {
+  const t = String(text || '');
+  if (!t.startsWith(FILE_HEAD)) return null;
+  const m = /^📎 (.+?) \(([^)\n]*)\)\n~~~~~~\n([\s\S]*)\n~~~~~~$/.exec(t);
+  return m ? { name: m[1], meta: m[2], body: m[3] } : null;
+}
+
+function fmtSize(n) { return n < 1024 ? `${n} B` : `${(n / 1024).toFixed(n < 10240 ? 1 : 0)} KB`; }
+
+const EXTRA_SECRETS = [/\bgsk_[A-Za-z0-9]{20,}/g, /\bhf_[A-Za-z0-9]{20,}/g, /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g];
+
+/** The CLI redactor (transcript.js scrub) plus the paste guard's key shapes. -> { text, hits }. */
+export function redactSecrets(text) {
+  const src = String(text);
+  let out = scrub(src);
+  for (const re of EXTRA_SECRETS) out = out.replace(re, '[redacted-key]');
+  const count = (s) => (s.match(/\[redacted[^\]]*\]/g) || []).length;
+  let hits = count(out) - count(src);
+  if (!hits && looksLikeKey(src)) hits = 1; // a key shape the patterns above missed: never call it clean
+  return { text: out, hits };
+}
+
+/**
+ * Read a local file for /send. Text up to FILE_CAP goes inline; larger or binary files are refused with the cap
+ * (slots have no attachment store). -> { ok, name, path, body, redacted, hits, size } | { ok:false, message }.
+ */
+export function prepareFile(p, { cwd = process.cwd() } = {}) {
+  const raw = String(p || '').trim().replace(/^['"]|['"]$/g, '');
+  if (!raw) return { ok: false, message: 'Usage: /send <slot> <file>' };
+  const full = isAbsolute(raw) ? raw : resolve(cwd, raw.replace(/^~(?=\/)/, homedir()));
+  let st;
+  try { st = statSync(full); } catch { return { ok: false, message: `No such file: ${raw}` }; }
+  if (st.isDirectory()) return { ok: false, message: `${raw} is a directory; /send takes one file.` };
+  if (st.size > FILE_CAP) return { ok: false, message: `${raw} is ${fmtSize(st.size)}; /send sends text files up to 64 KB inline (slots have no attachment store yet).` };
+  const buf = readFileSync(full);
+  if (buf.subarray(0, 8192).includes(0)) return { ok: false, message: `${raw} looks binary; /send sends text files only (up to 64 KB).` };
+  const body = buf.toString('utf8');
+  const { text, hits } = redactSecrets(body);
+  return { ok: true, name: basename(full), path: full, body, redacted: text, hits, size: st.size };
+}
+
+/** Tab completion for /send's path argument: entries of the typed directory, directories with a trailing slash. */
+export function pathItems(partial, { cwd = process.cwd(), max = 200 } = {}) {
+  const p = String(partial || '');
+  const slash = p.lastIndexOf('/');
+  const dirPart = slash >= 0 ? p.slice(0, slash + 1) : '';
+  const base = dirPart.startsWith('~/') ? join(homedir(), dirPart.slice(2)) : isAbsolute(dirPart) ? dirPart : resolve(cwd, dirPart || '.');
+  let names = [];
+  try { names = readdirSync(base, { withFileTypes: true }); } catch { return []; }
+  const showHidden = p.slice(slash + 1).startsWith('.');
+  return names.filter(d => showHidden || !d.name.startsWith('.')).slice(0, max)
+    .map(d => ({ value: dirPart + d.name + (d.isDirectory() ? '/' : ''), desc: d.isDirectory() ? 'dir' : '' }));
+}
+
+// ---- inbound -------------------------------------------------------------------------------------
+const hhmm = (iso) => { const d = new Date(iso || Date.now()); return Number.isNaN(d.getTime()) ? '' : `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`; };
+
+/** Slot text arrives HTML-escaped from the Matrix bridge ("&amp;&amp;"); decode for display. Never renders HTML. */
+export function decodeEntities(t) {
+  return String(t ?? '').replace(/&(amp|lt|gt|quot|apos|#39|#x27);/gi, (_, e) => ({ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", '#39': "'", '#x27': "'" })[e.toLowerCase()]);
+}
+
+/** The slot a session name currently holds (from api.slots() rows), or null. Lets a broadcast show its reply address. */
+export function slotOfHolder(rows, name) {
+  const n = String(name || '').replace(/\s*\(.*\)\s*$/, '').trim().toLowerCase(); if (!n) return null;
+  const r = (Array.isArray(rows) ? rows : []).find(x => x?.name && x.state !== 'free' && String(x.holder_session || '').toLowerCase() === n);
+  return r ? r.name : null;
+}
+
+/** A slot message as a chat line: { glyph, who, time, text, file }. */
+export function slotLine(m) {
+  m = m && typeof m.text === 'string' ? { ...m, text: decodeEntities(m.text) } : m;
+  const f = parseFileMessage(m?.text);
+  const file = f ? { name: f.name, meta: f.meta, body: f.body, lines: f.body.split('\n').length, preview: f.body.split('\n').slice(0, 3) } : null;
+  // SLOTS-REPLY: the slot is the address, so it leads; the session/display name follows in brackets. A sender
+  // with no verified slot keeps its name and is flagged as having no reply address.
+  const from = m?.from || m?.author_identity || 'someone';
+  const who = m?.from_slot ? addressLabel(m.from_slot, m?.from) : from;
+  return { glyph: '◆', who, noReply: !m?.from_slot, time: hhmm(m?.created_at), text: file ? `📎 ${f.name} (${f.meta})` : String(m?.text ?? ''), file };
+}
+
+/**
+ * Keep a slot's stream open: reconnect with the cursor, count failures distinctly, back off on failures (capped),
+ * and fall back to the wait long-poll on a server without the stream route. Never polls while the stream is up.
+ * open(query, signal) -> async iterable of SSE events; wait({ since, signal }) -> { messages, cursor }.
+ */
+// A slot cursor names a message ('<created_at>|<seq>'), not just a time: resuming from a bare timestamp skipped a
+// second message in the same millisecond (collector devSlotMessagesStore parseCursor/cursorOf/isAfterCursor).
+export function slotCursorOf(m) { return m.seq == null ? m.created_at : `${m.created_at}|${m.seq}`; }
+export function isAfterSlotCursor(m, cursor) {
+  if (!cursor) return true;
+  const x = /^(.*)\|(\d+)$/.exec(String(cursor));
+  const ts = x ? (x[1] || null) : String(cursor); const seq = x ? Number(x[2]) : null;
+  if (seq != null && !ts) return m.seq != null && m.seq > seq;
+  if (m.created_at !== ts) return m.created_at > ts;
+  return seq == null ? true : (m.seq != null && m.seq > seq);
+}
+
+export function createSlotListener({ open, wait = null, onMessage, onState = () => {}, delays = [1000, 2000, 5000, 10000, 30000] }) {
+  const st = { running: false, failures: 0, mode: 'stream', cursor: null, connected: false };
+  let ac = null;
+  const seen = new Set();
+  const deliver = (m) => {
+    if (!m) return;
+    if (m.created_at && isAfterSlotCursor(m, st.cursor)) st.cursor = slotCursorOf(m);
+    if (m.id) { if (seen.has(m.id)) return; seen.add(m.id); if (seen.size > 1000) seen.delete(seen.values().next().value); }
+    try { onMessage(m); } catch { /* a render failure never kills the listener */ }
+  };
+  const sleep = (ms, signal) => new Promise((r) => { const t = setTimeout(r, ms); t.unref?.(); signal.addEventListener('abort', () => { clearTimeout(t); r(); }, { once: true }); });
+  const setConn = (v) => { if (st.connected !== v) { st.connected = v; onState({ ...st }); } };
+
+  async function loop(signal, since) {
+    st.cursor = since || null;
+    let streak = 0;
+    while (!signal.aborted) {
+      try {
+        if (st.mode === 'stream') {
+          for await (const ev of open({ since: st.cursor }, signal)) {
+            if (signal.aborted) break;
+            if (ev?.type === 'connected') { streak = 0; if (ev.cursor && !st.cursor) st.cursor = ev.cursor; setConn(true); }
+            else if (ev?.type === 'slot.message') { streak = 0; deliver(ev.message); }
+          }
+          setConn(false);
+          if (signal.aborted) break;
+          await sleep(delays[0], signal); // a clean end (lifetime) reconnects promptly
+          continue;
+        }
+        const r = await wait({ since: st.cursor, signal });
+        if (signal.aborted) break;
+        streak = 0; setConn(true);
+        for (const m of r?.messages || []) deliver(m);
+        if (r?.cursor) st.cursor = r.cursor;
+      } catch (e) {
+        if (signal.aborted) break;
+        setConn(false);
+        if (st.mode === 'stream' && wait && e?.status === 404 && e?.code !== 'unknown slot') { st.mode = 'wait'; onState({ ...st }); continue; }
+        st.failures += 1; streak += 1;
+        onState({ ...st, error: e?.message || 'failed' });
+        await sleep(delays[Math.min(streak - 1, delays.length - 1)], signal);
+      }
+    }
+  }
+  return {
+    start({ since } = {}) {
+      if (st.running) return;
+      st.running = true; ac = new AbortController();
+      const sig = ac.signal;
+      loop(sig, since).finally(() => { st.running = false; st.connected = false; });
+    },
+    stop() { if (ac) ac.abort(); ac = null; st.running = false; st.connected = false; },
+    state: () => ({ ...st }),
+  };
+}
+
+/** SLOTS-REPLY2: is this line in slot X from X's own holder (verified from_slot, else the sender name)? */
+export function isHolderLine(m, slot) {
+  const x = String(slot || '').toLowerCase(); if (!x) return false;
+  if (String(m?.from_slot || '').toLowerCase() === x) return true;
+  const f = String(m?.from || '').toLowerCase();
+  return f === x || f.startsWith(`${x} (`);
+}
+
+/**
+ * SLOTS-REPLY2: after this window sends into slot X it also watches X (not just its own slot) for lines from
+ * X's holder, from the sent message's cursor on, until `ttlMs` after the last send or stop(). A reply posted
+ * in X (a sender with no reply address) is then still shown. onReply(slot, message) fires once per line.
+ * open/wait are api.slotStream / api.slotWait shaped, bound per slot by the caller: open(slot, q, signal).
+ */
+export function createReplyWatches({ open, wait = null, onReply, ttlMs = 30 * 60 * 1000, now = Date.now, isMine = () => false, skipSlot = () => false, setTimer = setTimeout, clearTimer = clearTimeout }) {
+  const watches = new Map();
+  const drop = (slot) => { const w = watches.get(slot); if (!w) return; clearTimer(w.timer); w.l.stop(); watches.delete(slot); };
+  const arm = (slot, sent) => {
+    if (!slot || skipSlot(slot)) return false;
+    const until = now() + ttlMs;
+    const ex = watches.get(slot);
+    if (ex) { clearTimer(ex.timer); ex.timer = setTimer(() => drop(slot), ttlMs); ex.timer.unref?.(); ex.until = until; return true; }
+    const w = { until, timer: null, l: null };
+    w.l = createSlotListener({
+      open: (q, signal) => open(slot, q, signal),
+      wait: wait ? ({ since, signal }) => wait(slot, { since, signal }) : null,
+      onMessage: (m) => {
+        if (now() > w.until) { drop(slot); return; }
+        if (isMine(m) || !isHolderLine(m, slot)) return;
+        onReply(slot, m);
+      },
+    });
+    w.timer = setTimer(() => drop(slot), ttlMs); w.timer.unref?.();
+    watches.set(slot, w);
+    w.l.start({ since: sent && sent.created_at ? slotCursorOf(sent) : undefined });
+    return true;
+  };
+  return { arm, stop: () => { for (const s of [...watches.keys()]) drop(s); }, has: (s) => watches.has(s), size: () => watches.size };
+}
+
+// ---- reattach record -------------------------------------------------------------------------------
+export const lastSlotPath = () => join(homedir(), '.config', 'quox', 'quoxon-slots.json');
+const readAll = (path) => { try { return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) || {} : {}; } catch { return {}; } };
+const keyOf = (profile, cwd) => `${profile || 'default'}|${cwd || ''}`;
+function writeAll(all, path) {
+  try { mkdirSync(dirname(path), { recursive: true }); const tmp = `${path}.${process.pid}.tmp`; writeFileSync(tmp, JSON.stringify(all, null, 2)); renameSync(tmp, path); } catch { /* best effort */ }
+}
+/** The slot this profile last held in this directory, or null. */
+export function loadLastSlot({ profile, cwd, path = lastSlotPath() }) {
+  const e = readAll(path)[keyOf(profile, cwd)];
+  return e && typeof e.slot === 'string' ? e : null;
+}
+export function saveLastSlot({ profile, cwd, slot, session, path = lastSlotPath() }) {
+  const all = readAll(path); all[keyOf(profile, cwd)] = { slot, session: session || null, at: new Date().toISOString() }; writeAll(all, path);
+}
+export function forgetLastSlot({ profile, cwd, path = lastSlotPath() }) {
+  const all = readAll(path); const k = keyOf(profile, cwd);
+  if (k in all) { delete all[k]; writeAll(all, path); }
+}
+
+// ---- QUOXON-ROOMS: a slot as a group room ----------------------------------------------------------
+const ROOM_RE = /^#([A-Za-z0-9][A-Za-z0-9-]{0,31}):?(?:[ \t]+(\S[\s\S]*))?$/;
+/** `#group-chat hello` -> { room, text }; bare `#group-chat` -> { room, text: null }; `# heading` or anything else -> null. */
+export function parseRoomSend(text) {
+  const m = ROOM_RE.exec(String(text || '').replace(/\s+$/, ''));
+  return m ? { room: m[1].toLowerCase(), text: m[2] ? m[2] : null } : null;
+}
+/** `#group-chat` / `group-chat` -> 'group-chat'; junk -> null. */
+export function roomName(arg) {
+  const m = /^#?([A-Za-z0-9][A-Za-z0-9-]{0,31})$/.exec(String(arg || '').trim());
+  return m ? m[1].toLowerCase() : null;
+}
+/** "QUOXON (resident)" -> "QUOXON": the sender as a chat name. */
+export function senderName(from) { return String(from || 'someone').replace(/\s*\(.*$/, '').trim() || 'someone'; }
+const SENDER_ROLES = ['sky', 'teal', 'ok', 'warn', 'indigo', 'violet'];
+/** A stable colour role per sender (same name, same colour, every time and every window). */
+export function senderColor(name) {
+  let h = 0; for (const ch of String(name)) h = (h * 31 + ch.codePointAt(0)) >>> 0;
+  return SENDER_ROLES[h % SENDER_ROLES.length];
+}
+/** A room message as a chat line: `#group-chat  QUOXON: text`. */
+export function roomLine(room, m, { out = false } = {}) {
+  const base = slotLine(m);
+  const who = senderName(m?.from);
+  return { ...base, glyph: '#', room, who, color: senderColor(who), text: base.text, out, roomLine: true };
+}
+/** The text form of a room line, for /rooms backlog tests and plain output. */
+export const roomLineText = (l) => `#${l.room}  ${l.who}: ${l.text}`;
+
+/** QUOXON-MESH: what a send to a slot tells the user about the recipient. null when the server sent no presence. */
+export function presenceLine(slot, presence, agoText) {
+  if (!presence || !presence.state) return null;
+  if (presence.state === 'listening') return { text: `✔ delivered to ${slot} (listening now)`, tone: 'ok', listening: true };
+  if (presence.state === 'nobody_holds') return { text: `✔ delivered to ${slot} · nobody holds this slot`, tone: 'ok', listening: false };
+  const seen = presence.last_checked_in_at ? `last checked in ${agoText(presence.last_checked_in_at)}` : 'no check-in on record';
+  return { text: `✔ delivered to ${slot} · not listening right now (${seen}); it sees this when it next checks`, tone: 'ok', listening: false };
+}

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/mapping.js

@@ -78,8 +78,9 @@ export function soundForEvent(prev, action, ctx = {}) {
   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 (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) {

package/lib/quoxon/stray.js

@@ -0,0 +1,22 @@
+/**
+ * TUI-INPUT: a letter then "/" ("n/help") is a card answer that leaked into the composer ahead of a command.
+ * Pure: -> { letter, command } when the text looks like that and the rest names a known slash command, else null.
+ * (Ordinary "w/o", "b/c" or "and/or" never match: the word after the slash must be a command.)
+ */
+export function strayCardAnswer(text, names = []) {
+  const t = String(text ?? '').trim();
+  const m = /^([a-z])\/([a-z][\w-]*)(?=\s|$)/i.exec(t);
+  if (!m) return null;
+  if (!names.includes(`/${m[2].toLowerCase()}`)) return null;
+  return { letter: m[1].toLowerCase(), command: t.slice(1) };
+}
+
+/** The one-line question (askText adds the y/N/c keys). */
+export const strayQuestion = (s) => `Did you mean ${s.command.split(/\s+/)[0]}? (the '${s.letter}' looks like a stray card answer)`;
+
+/** True when the same message is already queued, steered or waiting for the server. */
+export function alreadyQueued(text, { pending = [], steering = [], waiting = null } = {}) {
+  const t = String(text ?? '').trim();
+  if (!t) return false;
+  return [...pending, ...steering].some(p => String(p.text ?? '').trim() === t) || String(waiting?.text ?? '').trim() === t;
+}