quoxcli 0.3.1 → 0.5.0

package/lib/quoxon/gripeQueue.js

@@ -0,0 +1,135 @@
+/**
+ * GRIPE-QUEUE: a gripe that could not be filed because Quox did not answer (timeout, network, 5xx) is kept on disk and
+ * retried, never lost. Local only (~/.quox/gripe-queue.json, mode 0600). Each entry carries an idempotency key
+ * (sha256 of the normalised text + the UTC day) that rides on the filing request, so the collector can return the
+ * issue it already made when a request that timed out had in fact succeeded.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { redactSecrets } from './secretShape.js';
+
+export const RETRY_MIN_MS = 2 * 60 * 1000;
+export const GIVE_UP_MS = 24 * 60 * 60 * 1000;
+export const RECENT_FILED_CAP = 20;
+export const defaultQueuePath = (home = homedir()) => join(home, '.quox', 'gripe-queue.json');
+
+const normalise = (t) => String(t || '').trim().replace(/\s+/g, ' ').toLowerCase();
+/** sha256(normalised text + UTC day) -> hex. The same gripe retyped the same day maps to one key. */
+export function gripeKey(text, now = Date.now()) {
+  return createHash('sha256').update(`${normalise(text)}|${new Date(now).toISOString().slice(0, 10)}`).digest('hex');
+}
+
+/** A failure worth queueing: no HTTP status (timeout, network, refused) or a 5xx. 4xx is the user's to fix. */
+export function isRetryable(err) {
+  const s = err?.status;
+  if (s == null) return true;
+  return Number(s) >= 500;
+}
+
+export function gripeQueue(path = defaultQueuePath(), { now = () => Date.now() } = {}) {
+  const read = () => {
+    try { const d = JSON.parse(readFileSync(path, 'utf8')); return Array.isArray(d?.items) ? d : { items: [], lastTry: 0 }; }
+    catch { return { items: [], lastTry: 0 }; }
+  };
+  const write = (d) => {
+    try {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      const tmp = `${path}.${process.pid}.tmp`;
+      writeFileSync(tmp, JSON.stringify(d), { mode: 0o600 });
+      renameSync(tmp, path);
+      return true;
+    } catch { return false; }
+  };
+  const trim = (d) => { // keep every open item, and only the most recent filed/expired ones
+    const open = d.items.filter(i => i.status === 'queued');
+    const done = d.items.filter(i => i.status !== 'queued').slice(-RECENT_FILED_CAP);
+    d.items = [...done, ...open];
+    return d;
+  };
+  return {
+    key: (text) => gripeKey(text, now()),
+    list: () => read().items,
+    /** Add (or find) the queued entry for this gripe. -> the entry. */
+    enqueue({ text, repo = null, key }) {
+      const d = read();
+      const k = key || gripeKey(text, now());
+      let it = d.items.find(i => i.key === k);
+      if (!it) { it = { key: k, text: redactSecrets(String(text)), repo, created_at: new Date(now()).toISOString(), status: 'queued', tries: 0 }; d.items.push(it); }
+      else if (it.status === 'expired') { it.status = 'queued'; }
+      write(trim(d));
+      return it;
+    },
+    /** Record a successful filing (from the live path or a retry) so /gripes can show the link. */
+    markFiled({ text, repo = null, key, url }) {
+      const d = read();
+      const k = key || gripeKey(text, now());
+      let it = d.items.find(i => i.key === k);
+      if (!it) { it = { key: k, text: redactSecrets(String(text)), repo, created_at: new Date(now()).toISOString(), tries: 0 }; d.items.push(it); }
+      Object.assign(it, { status: 'filed', url, filed_at: new Date(now()).toISOString() });
+      write(trim(d));
+      return it;
+    },
+    /**
+     * File what is queued, at most once per RETRY_MIN_MS across all callers, expiring entries older than 24 h.
+     * file(item) -> { filed:true, url } | { filed:false, retryable }. -> { ran, filed:[items], expired:[items], pending:n }.
+     */
+    async retry(file, { force = false } = {}) {
+      const d = read();
+      const t = now();
+      const expired = [];
+      for (const it of d.items) if (it.status === 'queued' && t - Date.parse(it.created_at) > GIVE_UP_MS) { it.status = 'expired'; expired.push(it); }
+      const open = d.items.filter(i => i.status === 'queued');
+      if (expired.length) write(d);
+      if (!open.length) return { ran: false, filed: [], expired, pending: 0 };
+      if (!force && t - (d.lastTry || 0) < RETRY_MIN_MS) return { ran: false, filed: [], expired, pending: open.length };
+      d.lastTry = t; write(d);
+      const filed = [];
+      for (const it of open) {
+        let r;
+        try { r = await file(it); } catch (e) { r = { filed: false, retryable: isRetryable(e) }; }
+        it.tries = (it.tries || 0) + 1;
+        if (r?.filed && r.url) { Object.assign(it, { status: 'filed', url: r.url, filed_at: new Date(now()).toISOString() }); filed.push(it); }
+        else if (r && r.retryable === false) { it.status = 'failed'; it.error = r.error || 'refused'; }
+        else break; // Quox still not answering: leave the rest for the next window
+      }
+      const fresh = read(); // another process may have enqueued meanwhile; merge by key
+      for (const it of d.items) { const j = fresh.items.findIndex(x => x.key === it.key); if (j >= 0) fresh.items[j] = it; else fresh.items.push(it); }
+      fresh.lastTry = d.lastTry;
+      write(trim(fresh));
+      return { ran: true, filed, expired, pending: fresh.items.filter(i => i.status === 'queued').length };
+    },
+  };
+}
+
+export const SAVED_LINE = "Saved; I'll file it when Quox answers again (/gripes shows the queue)";
+
+/**
+ * Run one live filing. run(key) -> { response, url, superseded, notes } (throws when Quox does not answer).
+ * A timeout, network or 5xx failure queues the gripe instead of losing it. -> { ok:true, ... } | { ok:false, queued, message }.
+ */
+export async function fileOrQueue({ text, repo = null, queue, run, queueable = true }) {
+  const key = queue.key(text);
+  try {
+    const r = await run(key);
+    if (r?.url) queue.markFiled({ text, repo, key, url: r.url });
+    return { ok: true, ...r };
+  } catch (e) {
+    const message = e?.status ? `HTTP ${e.status}: ${e.message}` : (e?.message || 'failed');
+    if (!queueable || !isRetryable(e)) return { ok: false, message };
+    queue.enqueue({ text, repo, key });
+    return { ok: false, queued: true, message, saved: SAVED_LINE };
+  }
+}
+
+/** The retry filer: straight to the governed proxy (no agent run), carrying the entry's key so a duplicate is impossible. */
+export function makeRetryFiler({ fileDeterministically, client, orgId }) {
+  return async (it) => {
+    const r = await fileDeterministically({
+      client, complaint: it.text, orgId: orgId || null, quiet: true, throwRetryable: true,
+      options: { yes: true, ...(it.repo ? { repo: it.repo } : {}), idempotencyKey: it.key },
+    });
+    return r.filed ? { filed: true, url: r.url } : { filed: false, retryable: false, error: r.error };
+  };
+}

package/lib/quoxon/inboxView.js

@@ -0,0 +1,182 @@
+/**
+ * HITL-INBOX-BAR (owner 2026-10-26): the owner's Quox inbox in the chat. Pure helpers: the status-area bar text,
+ * the arrival line, the /inbox table and the one-item view. No I/O here; app.js owns the calls.
+ */
+import { bursts, burstLine } from './approvalBatch.js';
+const clip = (s, n) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, Math.max(0, n - 1))}…` : t; };
+const pad = (s, n) => { const t = clip(s, n); return t + ' '.repeat(Math.max(0, n - [...t].length)); };
+const ms = (v) => { const t = Date.parse(String(v ?? '').includes('T') || !v ? v : `${String(v).replace(' ', 'T')}Z`); return Number.isFinite(t) ? t : 0; };
+const CLOSED = new Set(['resolved', 'cancelled', 'expired', 'withdrawn', 'deleted', 'archived']);
+
+/** Newest first. */
+export const newestFirst = (items) => [...(Array.isArray(items) ? items : [])].filter((i) => i && i.id).sort((a, b) => ms(b.created_at ?? b.createdAt) - ms(a.created_at ?? a.createdAt));
+/** Unread = the server's per-user is_read flag is not set, and the item is not closed or archived. */
+export const isUnread = (it) => !it.is_read && !it.archived_at && !CLOSED.has(String(it.status || '').toLowerCase());
+/** Read but still open: what `/inbox unread all` flips back. */
+export const readItems = (items) => newestFirst(items).filter((i) => i.is_read && !i.archived_at && !CLOSED.has(String(i.status || '').toLowerCase()));
+export const unreadItems = (items) => newestFirst(items).filter(isUnread);
+
+const titleOf = (it) => String(it.title || it.kind || 'untitled');
+const sameTitle = (a, b) => titleOf(a) === titleOf(b);
+
+/** Inbox noise (owner 2026-10-27). Mutes are { [source lowercase]: expiryEpochMs }, stored per profile in the CLI settings. */
+export const REPEAT_WINDOW_MS = 12 * 3600000;
+export const MUTE_DEFAULT_MS = 8 * 3600000;
+/** '30m' | '8h' | '1d' -> ms, or null when it is not a duration. */
+export function muteDuration(text) {
+  const m = /^(\d+)\s*(m|h|d)$/i.exec(String(text || '').trim());
+  if (!m || !Number(m[1])) return null;
+  return Number(m[1]) * { m: 60000, h: 3600000, d: 86400000 }[m[2].toLowerCase()];
+}
+/** The mutes that have not expired. */
+export function activeMutes(mutes, now = Date.now()) {
+  const out = {};
+  for (const [k, v] of Object.entries(mutes && typeof mutes === 'object' ? mutes : {})) if (Number(v) > now) out[String(k).toLowerCase()] = Number(v);
+  return out;
+}
+/** An approval is NEVER muted: approvals always announce. */
+export const isMuted = (it, mutes, now = Date.now()) => !isApprovalItem(it) && Boolean(activeMutes(mutes, now)[fromOf(it).toLowerCase()]);
+/** Decide which fresh arrivals print. `announced` is a Map(title -> { at, n }) kept for the window session and updated here. -> { print, collapsed, muted } */
+export function announceFresh(fresh, announced, { mutes = {}, now = Date.now() } = {}) {
+  const print = []; let collapsed = 0; let muted = 0;
+  for (const it of fresh) {
+    if (isMuted(it, mutes, now)) { muted++; continue; }
+    const key = titleOf(it); const prev = announced.get(key);
+    if (!isApprovalItem(it) && prev && now - prev.at < REPEAT_WINDOW_MS) { prev.n++; collapsed++; continue; }
+    announced.set(key, { at: now, n: 1 }); print.push(it);
+  }
+  return { print, collapsed, muted };
+}
+
+/** The status-area line, or '' when nothing is unread: `📨 2 new · <newest title> (×3)`. Muted sources are left out of the count. */
+export function inboxBarText(items, cols = 80, { mutes = {}, now = Date.now(), announced = null } = {}) {
+  const un = unreadItems(items).filter((i) => !isMuted(i, mutes, now));
+  if (!un.length) return '';
+  const head = `📨 ${un.length} new · `;
+  const burst = bursts(un).find((b) => b.items.includes(un[0])); // APPROVAL-BURST: a burst of one agent's same-tool approvals reads as one line
+  if (burst) return head + clip(burstLine(burst).replace(/^📨 /, '').replace(/ · \/approvals$/, ''), Math.max(8, cols - 4 - [...head].length));
+  const reps = Math.max(un.filter((i) => sameTitle(i, un[0])).length, announced?.get(titleOf(un[0]))?.n || 0);
+  const tail = reps > 1 ? ` (×${reps})` : '';
+  return head + clip(titleOf(un[0]), Math.max(8, cols - 4 - [...head].length - [...tail].length)) + tail;
+}
+
+/** Unread items not seen on an earlier poll. `seen` is a Set of ids; the first poll seeds it and announces nothing. */
+export function arrivals(items, seen) {
+  const un = unreadItems(items);
+  const fresh = seen ? un.filter((i) => !seen.has(i.id)) : [];
+  // Cumulative: a short or empty read (collector restarting) or an item rolling out of the latest 10 must not make it "new" on return.
+  const ids = new Set(seen || []);
+  for (const i of Array.isArray(items) ? items : []) if (i?.id) ids.add(i.id);
+  return { fresh, ids };
+}
+export const SEEN_KEEP = 300;
+/** The persisted seen ids for one org (profile settings `inboxSeenByOrg`), or null when none were saved. */
+export const loadSeen = (settings, orgId) => { const v = settings?.inboxSeenByOrg?.[orgId || '_']; return Array.isArray(v) && v.length ? new Set(v) : null; };
+/** The settings value with this org's seen ids (newest kept, capped) stored. */
+export const withSeen = (settings, orgId, ids) => ({ ...(settings?.inboxSeenByOrg || {}), [orgId || '_']: [...ids].slice(-SEEN_KEEP) });
+/** One arrival line; `n` is the item's own number in the /inbox list (0 when it is not in the latest 10; defaults to 1). */
+export const arrivalLine = (it, n = 1) => `📨 ${clip(it.title || it.kind || 'untitled', 70)} · /inbox${n ? ` ${n}` : ''}`;
+
+export const fromOf = (it) => String(it.created_by_name || it.payload?.source || it.payload?.approval_context?.source_label || it.source || it.inbox_type || it.kind || 'system');
+export function ageOf(v, now = Date.now()) {
+  const t = ms(v); if (!t) return '?';
+  const s = Math.max(0, Math.round((now - t) / 1000));
+  if (s < 90) return 'now';
+  if (s < 5400) return `${Math.round(s / 60)}m`;
+  if (s < 129600) return `${Math.round(s / 3600)}h`;
+  return `${Math.round(s / 86400)}d`;
+}
+
+/** The latest 10 as a compact table; unread rows carry a dot. -> [{ text, tone }] */
+export function inboxTable(items, now = Date.now(), cols = 100, max = 10, mutes = {}) {
+  const rows = newestFirst(items).slice(0, max);
+  if (!rows.length) return [{ text: 'Your inbox is empty. (email is /mail)', tone: 'dim' }];
+  const tw = Math.max(16, Math.min(60, cols - 40));
+  const out = [{ text: `  ${pad('#', 3)}${pad('when', 6)}${pad('from', 14)}${pad('title', tw)} state`, tone: 'dim' }];
+  rows.forEach((it, i) => {
+    const un = isUnread(it); const mu = isMuted(it, mutes, now);
+    const reps = un ? unreadItems(items).filter((x) => sameTitle(x, it)).length : 0;
+    const title = titleOf(it); const shown = reps > 1 ? `${clip(title, Math.max(8, tw - 6))} (×${reps})` : title;
+    out.push({ text: `${un ? '●' : ' '} ${pad(i + 1, 3)}${pad(ageOf(it.created_at ?? it.createdAt, now), 6)}${pad(fromOf(it), 14)}${pad(shown, tw)} ${un ? 'unread' : (it.status || 'read')}${mu ? ' (muted)' : ''}`, tone: un && !mu ? 'accent' : 'dim' });
+  });
+  const un = unreadItems(items).filter((i) => !isMuted(i, mutes, now)).length;
+  out.push({ text: `${un} unread · /inbox N open one · /inbox read N|all · /inbox unread N|all · /inbox open N (approvals) · /inbox mute <from> [1h|8h|1d] · email is /mail`, tone: 'dim' });
+  return out;
+}
+
+/** '5 6', '5-8', '1,3', '#2 4-5' -> sorted unique numbers, or null when any token is not a number or range. */
+export function parseNumbers(text) {
+  const toks = String(text || '').trim().split(/[\s,]+/).filter(Boolean);
+  if (!toks.length) return null;
+  const out = new Set();
+  for (const t of toks) {
+    const m = /^#?(\d+)(?:-#?(\d+))?$/.exec(t); if (!m) return null;
+    const a = Number(m[1]), b = m[2] === undefined ? a : Number(m[2]);
+    if (a < 1 || b < 1 || b - a > 200) return null;
+    for (let k = Math.min(a, b); k <= Math.max(a, b); k++) out.add(k);
+  }
+  return [...out].sort((x, y) => x - y);
+}
+const one = (kind, ns) => (ns.length === 1 ? { kind, n: ns[0] } : { kind, ns });
+
+/** Arg grammar: '' | N | N open|read | read N..|all | open N. Several numbers and ranges (5 6, 5-8) are fine for read. -> { kind, n? | ns? | all? } | { kind:'usage' } */
+export function parseInbox(arg) {
+  const a = String(arg || '').trim().toLowerCase();
+  if (!a || a === 'list' || a === 'latest') return { kind: 'list' };
+  if (a === 'mutes') return { kind: 'mutes' };
+  let m = /^(mute|unmute)\s+(\S+)(?:\s+(\S+))?$/.exec(a);
+  if (m) {
+    if (m[1] === 'unmute') return m[3] ? { kind: 'usage' } : { kind: 'unmute', source: m[2] };
+    const dur = m[3] === undefined ? MUTE_DEFAULT_MS : muteDuration(m[3]);
+    return dur ? { kind: 'mute', source: m[2], ms: dur } : { kind: 'usage' };
+  }
+  m = /^(?:show\s+)?#?(\d+)$/.exec(a); if (m) return { kind: 'show', n: Number(m[1]) };
+  m = /^(open|read|unread)\s+(.+)$/.exec(a);
+  if (m) {
+    if ((m[1] === 'read' || m[1] === 'unread') && m[2] === 'all') return { kind: m[1], all: true };
+    const ns = parseNumbers(m[2]); if (!ns) return { kind: 'usage' };
+    if (m[1] === 'open') return ns.length === 1 ? { kind: 'open', n: ns[0] } : { kind: 'usage' };
+    return one(m[1], ns);
+  }
+  m = /^(.+?)\s+(open|read|unread|show)$/.exec(a); // word order: /inbox 1 open, /inbox 5-8 read
+  if (m) {
+    const ns = parseNumbers(m[1]); if (!ns) return { kind: 'usage' };
+    if (m[2] === 'open') return ns.length === 1 ? { kind: 'open', n: ns[0] } : { kind: 'usage' };
+    if (m[2] === 'show') return ns.length === 1 ? { kind: 'show', n: ns[0] } : { kind: 'usage' };
+    return one(m[2], ns);
+  }
+  return { kind: 'usage' };
+}
+export const INBOX_USAGE = 'Usage: /inbox | /inbox N | /inbox read N|N-M|all | /inbox unread N|N-M|all (undo a read) | /inbox open N (or /inbox 1 open, /inbox 1 read, /inbox 1 unread) | /inbox mute <from> [1h|8h|1d] | /inbox unmute <from> | /inbox mutes (email is /mail)';
+
+/** The first non-empty string among the item's own body fields and the payload's (body_md is the stored column every task/info item uses). */
+const bodyOf = (it) => {
+  const p = it.payload || {};
+  for (const v of [it.body_md, it.body, it.message, p.body_md, p.body, p.body_text, p.text, p.message, p.summary, p.description]) if (typeof v === 'string' && v.trim()) return v;
+  return '';
+};
+/** One item in full: sender, subject, the whole body (every line, nothing cut), then the actions that apply. `n` is its /inbox number. -> [{ text, tone }] */
+export function inboxDetail(it, now = Date.now(), n = 0) {
+  const p = it.payload || {};
+  const body = bodyOf(it);
+  const subject = p.subject || p.email_subject || '';
+  const out = [{ text: `${it.title || it.kind || 'untitled'}`, tone: 'accent' },
+    { text: `from ${p.from || p.sender || p.from_email || fromOf(it)} · ${ageOf(it.created_at ?? it.createdAt, now)} ago · ${it.kind || 'item'} · ${it.priority || 'normal'} · ${it.status || '?'}`, tone: 'dim' }];
+  if (subject && subject !== it.title) out.push({ text: `subject: ${subject}`, tone: 'dim' });
+  if (body) for (const l of String(body).split('\n')) out.push({ text: l, tone: 'text' });
+  else out.push({ text: '(no body: this item carries only a title)', tone: 'dim' });
+  if (it.dashboard_url) out.push({ text: it.dashboard_url, tone: 'dim' });
+  const at = n ? ` ${n}` : ' N';
+  out.push({ text: `actions: /inbox unread${at} (keep it unread) · /inbox read${at} · /inbox${isApprovalItem(it) ? ` open${at} (decide it in /approvals)` : ''}`, tone: 'dim' });
+  return out;
+}
+/** Approval-type items route to /approvals (the existing view). */
+export const isApprovalItem = (it) => String(it.kind || '').toLowerCase() === 'approval' || Boolean(it.payload?.approval_context) || it.payload?.type === 'decision';
+
+/** /inbox mutes -> [{ text, tone }] with each expiry. */
+export function mutesLines(mutes, now = Date.now()) {
+  const act = Object.entries(activeMutes(mutes, now));
+  if (!act.length) return [{ text: 'No sources muted. /inbox mute <from> [1h|8h|1d] (default 8h). Approvals are never muted.', tone: 'dim' }];
+  const left = (v) => { const m = Math.ceil((v - now) / 60000); return m < 90 ? `${m}m` : m < 2880 ? `${Math.round(m / 60)}h` : `${Math.round(m / 1440)}d`; };
+  return act.map(([k, v]) => ({ text: `${k} muted until ${new Date(v).toISOString().slice(0, 16).replace('T', ' ')} UTC (${left(v)} left)`, tone: 'dim' }));
+}

package/lib/quoxon/installCli.js

@@ -0,0 +1,79 @@
+/**
+ * LAZY-AI-CLI (owner 2026-10-19): "Quox can depend heavily on your choice or blend of Claude and OpenAI models.
+ * We advise installing both Claude Code and Codex." Draw people in step by step: when something needs a vendor CLI
+ * that is missing, offer to install it THEN, as a y/N.
+ *
+ * ONE flow behind `quox provider install` and the TUI offer cards (first-run suggestion + just-in-time), so they
+ * cannot drift. The server downloads the vendor's own npm package (never a binary Quox ships), as the Quox service
+ * user, into a volume that survives updates, audited start and finish (services/collector/routes/providerCli.js).
+ */
+import { detectCallerSource } from '../core/callerSource.js';
+
+export const INSTALL_TOOLS = {
+  'claude-code': { id: 'claude-code', name: 'Claude Code', vendor: 'Anthropic', bin: 'claude', after: 'Claude sign-in is available now: sign in from the dashboard Terminal, then pick Claude in /model.' },
+  codex: { id: 'codex', name: 'Codex', vendor: 'OpenAI', bin: 'codex', after: 'Codex is ready: sign in to ChatGPT from the dashboard Terminal (Codex), then pick it in /model.' },
+};
+
+export const SUGGEST_LINE = 'Quox works best with both Claude and OpenAI models. We suggest installing Claude Code and Codex.';
+
+const ALIASES = { claude: 'claude-code', 'claude-code': 'claude-code', claudecode: 'claude-code', codex: 'codex', 'openai-codex': 'codex' };
+export const toolFor = (s) => ALIASES[String(s || '').trim().toLowerCase()] || null;
+
+const sizeText = (p) => (p?.downloadMb ? `about ${p.downloadMb} MB` : null);
+
+export function planLine(p) {
+  const t = INSTALL_TOOLS[p?.id] || { name: p?.name || p?.id };
+  const size = sizeText(p);
+  return `${t.name} ${p?.version || ''} (${t.vendor ? `${t.vendor}'s ` : ''}${p?.package || ''}) from ${p?.source || 'registry.npmjs.org'}${size ? `, ${size} download` : ''}${p?.installedMb ? `, ${p.installedMb} MB on disk` : ''}. It installs on this server as the Quox service user and stays across updates.`.replace(/\s+/g, ' ');
+}
+
+export function offerQuestion(tool, plan) {
+  const t = INSTALL_TOOLS[tool];
+  const size = sizeText(plan);
+  return `${t.name} isn't installed on this server. Install it now? (${size ? `${size} from npm` : 'from npm'})`;
+}
+
+/** The CLIs the server says are missing, in a stable order. */
+export function missingTools(status) {
+  if (!status?.ok || !Array.isArray(status.tools)) return [];
+  return Object.keys(INSTALL_TOOLS).filter((id) => status.tools.some((t) => t.id === id && t.installed === false));
+}
+
+/** An agent (a session, an attached agent, a Claude process) never self-approves an install: it files a card. */
+export function isAgentCaller(env = process.env, detect = detectCallerSource) {
+  if (env.QUOX_AGENT_ID || env.QUOX_SESSION_ID || env.QUOX_SESSION) return true;
+  let src = null;
+  try { src = detect(env); } catch { src = null; }
+  if (!src) return false;
+  if (['attached_agent', 'held_slot', 'QUOX_STREAM'].includes(src.via)) return true;
+  return src.via === 'process' && /^claude\b/i.test(String(src.label || ''));
+}
+
+const POLL_MS = 3000;
+
+/**
+ * Start the server install and wait for it. Never throws.
+ * @returns {Promise<{ok:boolean, version?:string|null, lines:string[]}>}
+ */
+export async function runInstall(api, tool, { approvalId = null, onProgress = () => {}, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, timeoutMs = 15 * 60 * 1000 } = {}) {
+  const t = INSTALL_TOOLS[tool];
+  if (!t) return { ok: false, lines: [`No installable CLI called "${tool}". Use one of: ${Object.keys(INSTALL_TOOLS).join(', ')}`] };
+  const start = await api.providerCliInstall(tool, { approvalId });
+  if (!start?.ok || !start.job_id) {
+    if (start?.status === 404 || start?.status === 405) return { ok: false, lines: [`This Quox server is too old to install ${t.name} for you. Update it first: quox server update`] };
+    if (start?.status === 403) return { ok: false, lines: [`✖ ${start.error || 'Only an instance admin can install software on this server.'} Nothing was installed.`] };
+    return { ok: false, lines: [`✖ ${t.name} was not installed: ${start?.error || 'the server did not start the install'}`] };
+  }
+  const began = now();
+  let last = began;
+  for (;;) {
+    await sleep(POLL_MS);
+    const j = await api.providerCliJob(start.job_id);
+    if (j?.state === 'done' && j.ok) {
+      return { ok: true, version: j.version || null, lines: [`✔ ${t.name} ${j.version || ''} is installed on this server.`.replace(/\s+/g, ' ').replace(' .', '.'), t.after] };
+    }
+    if (j?.state === 'failed') return { ok: false, lines: [`✖ ${t.name} was not installed: ${j.error || 'the install failed'}`] };
+    if (now() - began >= timeoutMs) return { ok: false, lines: [`◐ ${t.name} is still running its install on the server. Check again shortly: quox provider list`] };
+    if (now() - last >= 15000) { last = now(); onProgress(`◐ installing ${t.name} (${Math.round((now() - began) / 1000)}s)`); }
+  }
+}

package/lib/quoxon/keys.js

@@ -53,7 +53,7 @@ const CSI_KEYS = {
   '\x1bOA': 'up', '\x1bOB': 'down', '\x1bOC': 'right', '\x1bOD': 'left',
   '\x1b[H': 'home', '\x1b[F': 'end', '\x1bOH': 'home', '\x1bOF': 'end',
   '\x1b[1~': 'home', '\x1b[4~': 'end', '\x1b[7~': 'home', '\x1b[8~': 'end',
-  '\x1b[3~': 'delete', '\x1b[Z': 'shift-tab',
+  '\x1b[3~': 'delete', '\x1b[5~': 'pageup', '\x1b[6~': 'pagedown', '\x1b[Z': 'shift-tab',
   '\x1b[13;2u': 'shift-enter', '\x1b[27;2;13~': 'shift-enter', '\x1b\r': 'shift-enter', '\x1b\n': 'shift-enter',
   '\x1b[1;5D': 'word-left', '\x1b[1;5C': 'word-right', '\x1b[1;3D': 'word-left', '\x1b[1;3C': 'word-right',
   // COMPOSER-EDIT (owner 2026-10-17: edit like Claude Code's prompt box). Alt+B/F (macOS Option+Left/Right), iTerm2 Alt+arrows,
@@ -68,8 +68,8 @@ const CSI_KEYS = {
 const CSI_LIST = Object.keys(CSI_KEYS).sort((a, b) => b.length - a.length);
 
 const CTRL = {
-  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g',
-  '\x0b': 'kill-line-forward', '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x15': 'kill-line', '\x17': 'delete-word',
+  '\x01': 'home', '\x05': 'end', '\x03': 'ctrl-c', '\x04': 'ctrl-d', '\x07': 'ctrl-g', '\x12': 'ctrl-r',
+  '\x0b': 'kill-line-forward', '\x0f': 'ctrl-o', '\x13': 'ctrl-s', '\x1d': 'ctrl-]', '\x15': 'kill-line', '\x17': 'delete-word',
   '\x1f': 'undo', '\x19': 'redo', '\x0a': 'newline', '\x7f': 'backspace', '\x08': 'backspace',
   '\r': 'enter', '\t': 'tab', '\x02': 'left', '\x06': 'right'
 };
@@ -118,7 +118,7 @@ export function parseChunk(chunk, state = initialKeyState(), draft = '') {
     const run = /^[^\x00-\x1f\x7f]+/.exec(s);
     if (run) { events.push({ type: 'text', text: run[0] }); s = s.slice(run[0].length); continue; }
     const c = s[0];
-    if (CTRL[c]) { events.push({ type: 'key', name: CTRL[c] }); }
+    if (CTRL[c]) { events.push(c === '\x01' ? { type: 'key', name: CTRL[c], via: 'ctrl-a' } : { type: 'key', name: CTRL[c] }); } // via: a double Ctrl+A selects all (app.js)
     s = s.slice(1);
   }
   return { events: coalesceBurst(events, draft), state: st };