quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/slash/compact.js

@@ -65,7 +65,7 @@ export function compactError(e) {
     if (code === 'transcripts_disabled') return msg || 'Transcript storage is off for this org, so no summary can be stored.';
     return msg || 'The server refused to compact right now (409).';
   }
-  if (e?.status === 403 && code === 'ai_consent_required') return 'Compacting sends this conversation to your AI provider, and this org has not given AI processing consent. An admin can turn it on in Settings.';
+  if (e?.status === 403 && code === 'ai_consent_required') return 'Compacting sends this conversation to your AI provider, and you have not given AI processing consent. /consent grant gives it (Settings > Privacy in the dashboard does too).';
   if (e?.status === 403) return 'Not allowed to compact this conversation (403).';
   if (e?.status === 404) return 'The server has no stored turns for this conversation (expired after 7 days, or nothing sent yet).';
   if (e?.status === 502) return 'The model call failed; nothing was changed. Try /compact again.';

package/lib/quoxon/slash/confirm.js

@@ -0,0 +1,30 @@
+/**
+ * One preview card, one y/n. Shared by /watch, /automate and /crystallize: a direct human ask is already the
+ * authorization, so the preview is the only confirmation. The answer is the next composer line (same pattern as the
+ * /approve "y/N" grant); a slash command typed instead drops the preview and runs normally.
+ */
+import { askText } from '../ask.js';
+export function createConfirm({ say, ttlMs = 120000, now = () => Date.now() }) {
+  let p = null;
+  return {
+    pending: () => Boolean(p),
+    /** y/N/c: a chat about the ask keeps it open with a fresh window. */
+    touch() { if (p) p.at = now(); },
+    ask(lines, onYes, { prompt = 'Go ahead?' } = {}) {
+      p = { onYes, at: now() };
+      for (const l of lines) (Array.isArray(l) ? say(l[0], l[1]) : say(l));
+      say(askText(String(prompt).replace(/\s*y\/n$/i, '')), 'ask'); // QUOXON-ASK: one shape
+    },
+    /** -> true when this line was the answer (consumed); false when the caller should treat it as an ordinary line. */
+    answer(text) {
+      if (!p) return false;
+      const q = p; p = null;
+      const t = String(text || '').trim();
+      if (t.startsWith('/')) return false;
+      if (now() - q.at > ttlMs) { say('That preview expired, so nothing was created. Run the command again.', 'dim'); return true; }
+      if (/^y(es)?$/i.test(t)) { Promise.resolve(q.onYes()).catch((e) => say(`Failed: ${e?.message || e}`, 'warn')); return true; }
+      say('Cancelled; nothing was created.', 'dim');
+      return true;
+    }
+  };
+}

package/lib/quoxon/slash/crystallize.js

@@ -0,0 +1,69 @@
+/**
+ * /crystallize [what]: turn what was just accomplished into a permanent reusable skill (rules, tools, tests).
+ * Real: one drafting model call (draft.js), a dry-run through the skill firewall for the preview, and creation in
+ * the QSKL store (POST /api/quox-skills). /crystal (is a workflow eligible to become a Crystal) is a different check.
+ */
+import { draftJson, transcriptText } from './draft.js';
+
+const why = (e) => `${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}`;
+const NAME_RE = /^[a-z0-9][a-z0-9-]{1,60}$/;
+
+export const crystallizePrompt = (context) => [
+  'Turn what was just accomplished in the conversation below into a reusable skill. Reply with ONE JSON object and nothing else. Use no tools.',
+  'Shape: {"name":"kebab-case-name","category":str,"description":"one sentence","rules":[str,...],"tools":[tool name,...],',
+  ' "tests":[{"name":str,"input":str,"expect":str}]}.',
+  'Rules are the steps and guardrails to repeat next time. Never include secrets, keys, hostnames or personal data. Tools are only ones actually used above.',
+  '', '--- conversation ---', context, '--- end ---'
+].join('\n');
+
+/** -> { body (POST /api/quox-skills), card[] } or { error } */
+export function buildSkill(d, { orgId, author }) {
+  const name = String(d?.name || '').trim().toLowerCase();
+  if (!NAME_RE.test(name)) return { error: 'the draft has no valid kebab-case name' };
+  const rules = (Array.isArray(d.rules) ? d.rules : []).map((r) => String(r).trim()).filter(Boolean);
+  if (!rules.length) return { error: 'the draft has no rules' };
+  const description = String(d.description || '').trim();
+  if (!description) return { error: 'the draft has no description' };
+  const tools = (Array.isArray(d.tools) ? d.tools : []).map((t) => String(t).trim()).filter(Boolean);
+  const tests = {};
+  for (const [i, t] of (Array.isArray(d.tests) ? d.tests : []).entries()) {
+    if (t && (t.input || t.expect)) tests[String(t.name || `case-${i + 1}`)] = { input: String(t.input || ''), expect: String(t.expect || '') };
+  }
+  const bodyMd = [`# ${name}`, '', description, '', '## Rules', ...rules.map((r, i) => `${i + 1}. ${r}`),
+    ...(tools.length ? ['', '## Tools', ...tools.map((t) => `- ${t}`)] : [])].join('\n');
+  const body = { orgId, scopeId: null, name, category: String(d.category || 'general'), description, bodyMd, author: author || 'quoxon', requiredTools: tools, tests, tags: ['crystallized'] };
+  const card = [
+    ['Skill draft (nothing is saved until you answer):', 'accent'],
+    `  Name       ${name}`,
+    `  About      ${description}`,
+    `  Rules      ${rules.length}   first: ${rules[0]}`,
+    `  Tools      ${tools.length ? tools.join(', ') : 'none'}`,
+    `  Tests      ${Object.keys(tests).length}${Object.keys(tests).length ? '   ' + Object.keys(tests).join(', ') : ''}`
+  ];
+  return { body, card, name };
+}
+
+export function createCrystallizeCmd({ api, say, confirm, getState, getFields }) {
+  return {
+    async handle(arg) {
+      if (!api.skillCreate) return say('Skills are not available in this mode.', 'warn');
+      const ctx = [transcriptText(getState()), String(arg || '').trim() ? `Focus: ${String(arg).trim()}` : ''].filter(Boolean).join('\n');
+      if (!ctx) return say('Nothing to crystallize yet. Do the task with Quox first, or say what: /crystallize how we rotate the API key.');
+      say('Drafting the skill…', 'dim');
+      let d;
+      try { d = await draftJson({ api, prompt: crystallizePrompt(ctx), fields: getFields() }); }
+      catch (e) { return say(`Could not draft a skill: ${e.message}. Nothing was saved.`, 'warn'); }
+      const b = buildSkill(d, { orgId: api.orgId?.(), author: api.userId?.() });
+      if (b.error) return say(`Could not draft a usable skill: ${b.error}. Nothing was saved.`, 'warn');
+      try { await api.skillCreate(b.body, { dryRun: true }); } // the server's skill firewall, before the card
+      catch (e) { return say(`The skill was not saved: ${why(e)}`, 'warn'); }
+      b.card.push('  Firewall   passed the server dry run');
+      confirm.ask(b.card, async () => {
+        try { await api.skillCreate(b.body); } catch (e) { return say(`Could not save the skill: ${why(e)}`, 'warn'); }
+        say(`✔ Saved skill ${b.name}.`, 'ok');
+        say(`  See it: /skills ${b.name}`);
+      }, { prompt: 'Save this skill?' });
+      return undefined;
+    }
+  };
+}

package/lib/quoxon/slash/dashboard.js

@@ -0,0 +1,136 @@
+/**
+ * /dashboard [page] and `quox dashboard [page]`: a one-time sign-in link to the web dashboard.
+ *
+ * The link comes from POST /api/auth/login-link (10 minutes, single use, bound to this user and org) and is
+ * joined to the active profile's dashboard URL. It is a credential: callers print it on the visible line only,
+ * never into the dev transcript or any history. Opened in the default browser when running locally; never over
+ * SSH (the browser would open on the wrong machine), where it is only printed.
+ *
+ * `next` asks the consume route to land on the page after sign-in. A server that does not know `next` lands
+ * on the dashboard home instead; nothing breaks.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+
+/** Page name -> real route in src/config/routeRegistry.js (approvals = the HITL /inbox, inbox = InboxQ mail). */
+export const PAGES = {
+  sessions: '/sessions',
+  approvals: '/inbox',
+  agents: '/agents',
+  lucid: '/lucid',
+  inbox: '/inboxq',
+  seo: '/quoxseo',
+  settings: '/settings'
+};
+
+export function resolvePage(arg) {
+  const name = String(arg ?? '').trim().toLowerCase();
+  if (!name) return { ok: true, page: null, path: '/' };
+  if (Object.hasOwn(PAGES, name)) return { ok: true, page: name, path: PAGES[name] };
+  return { ok: false, error: `Unknown page "${name}". Pages: ${Object.keys(PAGES).join(', ')}.` };
+}
+
+export const isRemoteSession = (env = process.env) => Boolean(env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY);
+
+export function openerFor(platform = process.platform) {
+  if (platform === 'linux') return { cmd: 'xdg-open', args: [] };
+  if (platform === 'darwin') return { cmd: 'open', args: [] };
+  if (platform === 'win32') return { cmd: 'rundll32', args: ['url.dll,FileProtocolHandler'] }; // no shell, so & in the URL is safe
+  return null;
+}
+
+/** -> { opened: true } | { opened: false, reason: 'ssh' | 'no-opener' | 'failed' }. Never throws, never uses a shell. */
+export function openInBrowser(url, { env = process.env, platform = process.platform, spawn = nodeSpawn } = {}) {
+  if (isRemoteSession(env)) return Promise.resolve({ opened: false, reason: 'ssh' });
+  const op = openerFor(platform);
+  if (!op) return Promise.resolve({ opened: false, reason: 'no-opener' });
+  return new Promise((resolve) => {
+    let done = false;
+    const fin = (r) => { if (!done) { done = true; resolve(r); } };
+    try {
+      const child = spawn(op.cmd, [...op.args, url], { stdio: 'ignore', detached: true });
+      child.on('error', () => fin({ opened: false, reason: 'failed' }));
+      child.unref?.();
+      setTimeout(() => fin({ opened: true }), 150); // an error (opener missing) arrives well inside this
+    } catch { fin({ opened: false, reason: 'failed' }); }
+  });
+}
+
+const missing = (e) => e?.status === 404 || e?.status === 405 || e?.status === 501;
+const join = (base, path) => new URL(path, base).href;
+const isLoopbackUrl = (u) => /^(localhost|127\.\d+\.\d+\.\d+|\[::1\]|0\.0\.0\.0)$/i.test(new URL(u).hostname);
+
+/**
+ * mint: async () -> { path, expires_at, ttl_seconds } (POST /api/auth/login-link).
+ * -> { kind: 'link' | 'plain' | 'error', url, plainUrl, page, remote, opened, openFailed, ttlSeconds, expiresAt, error }
+ */
+export async function runDashboard({ page, mint, baseUrl, env = process.env, open = (u) => openInBrowser(u, { env }) } = {}) {
+  const p = resolvePage(page);
+  if (!p.ok) return { kind: 'error', error: p.error };
+  const remote = isRemoteSession(env);
+  let plainUrl = null;
+  try { plainUrl = join(baseUrl, p.path); } catch { /* no profile URL: the server may still give one */ }
+  const base = { page: p.page, plainUrl, remote };
+  const noUrl = 'This profile has no dashboard URL. Set one with: quox config set url <https://host:3000>';
+  let r;
+  try { r = await mint(); } catch (e) {
+    if (missing(e)) return plainUrl ? { ...base, kind: 'plain', url: plainUrl } : { kind: 'error', error: noUrl };
+    const why = e?.status ? `${e.message || 'refused'} (HTTP ${e.status})` : (e?.message || 'failed');
+    return { ...base, kind: 'error', url: plainUrl, error: `Could not create a sign-in link: ${why}` };
+  }
+  if (!r?.path || !/^\/api\/auth\/login-link\/consume\?t=[\w-]+$/.test(r.path)) {
+    return { ...base, kind: 'error', url: plainUrl, error: 'Could not create a sign-in link: unexpected answer from the auth service.' };
+  }
+  // The server knows the public address of the instance; the profile URL may be localhost on this box.
+  let origin = null;
+  if (typeof r.url === 'string') {
+    try {
+      const u = new URL(r.url);
+      if (/^https?:$/.test(u.protocol) && r.url === u.origin + r.path) origin = u.origin;
+    } catch { /* ignore a malformed server url */ }
+  }
+  let linkBase = origin || baseUrl;
+  let local = false;
+  if (!origin) {
+    try { local = isLoopbackUrl(join(baseUrl, '/')); } catch { /* handled below */ }
+  }
+  let link;
+  try { link = join(linkBase, r.path); } catch { return { kind: 'error', error: noUrl }; }
+  const url = link + (p.page ? `&next=${encodeURIComponent(p.path)}` : '');
+  if (origin) base.plainUrl = join(origin, p.path);
+  const out = { ...base, kind: 'link', url, localOnly: local, ttlSeconds: r.ttl_seconds ?? 600, expiresAt: r.expires_at, opened: false };
+  if (!remote) {
+    const o = await open(url).catch(() => ({ opened: false, reason: 'failed' }));
+    out.opened = Boolean(o?.opened);
+    out.openFailed = !o?.opened;
+  }
+  return out;
+}
+
+const osc8 = (url, text) => `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+
+/** Result -> [{ text, tone }] for the visible lines. The link line is the only place the credential is printed. */
+export function dashboardLines(r, { hyperlinks = false } = {}) {
+  const where = r.page ? `the ${r.page} page` : 'the dashboard';
+  if (r.kind === 'error') {
+    return [
+      { text: r.error, tone: 'warn' },
+      ...(r.url ? [{ text: `The dashboard is at ${r.url} (you will need to sign in).`, tone: 'dim' }] : [])
+    ];
+  }
+  if (r.kind === 'plain') {
+    return [
+      { text: `This server does not offer one-time sign-in links (an older server). Open ${where} here and sign in:`, tone: 'warn' },
+      { text: r.url }
+    ];
+  }
+  const mins = Math.round((r.ttlSeconds || 600) / 60);
+  return [
+    { text: r.opened ? `Opened ${where} in your browser, already signed in.` : `Sign-in link for ${where}:` },
+    ...(hyperlinks ? [{ text: osc8(r.url, `Open ${where} (signed in)`) }] : []),
+    { text: r.url },
+    { text: `Valid for ${mins} minutes, works once, tied to your account. Anyone holding it can sign in as you until then.`, tone: 'dim' },
+    ...(r.localOnly ? [{ text: 'This address only works on this machine; set the app URL with `quox server config app-url <url>` or in Settings > General > App URL.', tone: 'dim' }] : []),
+    ...(r.remote ? [{ text: 'Over SSH, so it was not opened here: open it in a browser on your own machine.', tone: 'dim' }] : []),
+    ...(r.openFailed ? [{ text: 'Could not open a browser from here: use the link above.', tone: 'warn' }] : [])
+  ];
+}

package/lib/quoxon/slash/draft.js

@@ -0,0 +1,54 @@
+/**
+ * One drafting model call for /automate and /crystallize, through the same governed turn path as chat (api.stream)
+ * but in its own throwaway conversation, so it never lands in the visible transcript. The model is told to answer
+ * with JSON only and use no tools; an approval request or error aborts the draft. The JSON is validated by the
+ * caller before any card is shown.
+ */
+import { textGate } from '../events.js';
+
+const newId = () => `QXN_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+/** The visible conversation as plain text for the drafting prompt (last `max` chars). */
+export function transcriptText(state, max = 12000) {
+  const out = [];
+  for (const it of [...(state?.history || []), ...(state?.blocks || [])]) {
+    if (it.kind === 'user' && !it.echo && it.text && !it.text.startsWith('/')) out.push(`User: ${it.text}`);
+    else if (it.kind === 'text' && it.text) out.push(`Quox: ${it.text}`);
+    else if (it.kind === 'tool' && it.tool) out.push(`Tool used: ${[it.tool, it.target].filter(Boolean).join(' ')}`);
+  }
+  const t = out.join('\n');
+  return t.length > max ? t.slice(t.length - max) : t;
+}
+
+/** First JSON object in a model reply (plain, fenced, or surrounded by prose), or null. */
+export function extractJson(text) {
+  const s = String(text || '');
+  const fence = s.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const cand = fence ? fence[1] : s;
+  const a = cand.indexOf('{'), b = cand.lastIndexOf('}');
+  if (a < 0 || b <= a) return null;
+  try { const v = JSON.parse(cand.slice(a, b + 1)); return v && typeof v === 'object' && !Array.isArray(v) ? v : null; } catch { return null; }
+}
+
+/** -> parsed object, or throws Error(reason). `fields` = streamFields(model choice). */
+export async function draftJson({ api, prompt, fields = {}, timeoutMs = 90000 }) {
+  if (!api.stream) throw new Error('no model connection in this mode');
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  let text = '', gate = null;
+  try {
+    for await (const ev of api.stream({ turnId: newId(), message: prompt, agent: 'quox', ...fields }, ctrl.signal)) {
+      if (ev.type === 'error') throw new Error(String(ev.error || 'the model call failed'));
+      if (ev.type === 'approval.requested') throw new Error('the model tried to use a tool instead of drafting');
+      const g = textGate(gate, ev); gate = g.st;
+      if (g.append) text += ev.content;
+      if (ev.type === 'turn.finished' || ev.type === 'done') break;
+    }
+  } catch (e) {
+    if (ctrl.signal.aborted) throw new Error('the model took too long');
+    throw e;
+  } finally { clearTimeout(timer); }
+  const j = extractJson(text);
+  if (!j) throw new Error('the model did not return a usable draft');
+  return j;
+}

package/lib/quoxon/slash/evidenceCmd.js

@@ -0,0 +1,34 @@
+/**
+ * /evidence: export this conversation's signed evidence bundle (the same call as `quox evidence bundle`) to
+ * ~/quox-evidence/<conversation>-<timestamp>.zip and say what is in it. /ward lists the WARD receipts the export found
+ * (newest ten, then N more). /envelope, /envelopes and /aee are pointers to /proof (the envelope ids); /volt is the
+ * VOLT run, which travels inside the bundle. Pure formatting plus one api call; the lines are { text, tone }.
+ */
+import { wrapHang } from '../objects/model.js';
+export const EVIDENCE_ALIASES = ['envelope', 'envelopes', 'aee', 'volt', 'ward'];
+const SHOWN = 10;
+
+export async function runEvidenceCommand({ cmd, api, conversationId, cols = Infinity }) {
+  const W = Number.isFinite(cols) ? Math.max(20, cols - 4) : 1e9;
+  const wrapT = (l) => wrapHang(l.text, W, 4).map(text => ({ ...l, text }));
+  if (!api || typeof api.evidenceExport !== 'function') return [{ text: 'Evidence export is not available in this mode. In a terminal: quox evidence bundle', tone: 'warn' }].flatMap(wrapT);
+  if (!conversationId) return [{ text: 'No conversation to export yet: send a message first, or in a terminal run quox evidence bundle <conversation id>.', tone: 'warn' }].flatMap(wrapT);
+  let r;
+  try { r = await api.evidenceExport(conversationId); } catch (e) {
+    return [{ text: `Evidence export failed: ${e?.message || 'failed'}. Nothing was written.`, tone: 'warn' }].flatMap(wrapT);
+  }
+  const out = [];
+  const ok = r.verify && r.verify.ok;
+  out.push({ text: `${ok ? '✔' : '✖'} evidence bundle ${ok ? 'written and verified' : 'written but FAILED verification'}: ${r.path}`, tone: ok ? 'ok' : 'warn' });
+  out.push({ text: `  ${r.envelopes} envelopes, ${r.receipts} WARD receipts, conversation ${r.corr}`, tone: 'dim' });
+  if (cmd === '/ward') {
+    out.push({ text: '  WARD receipts for this conversation (the same bundle /evidence writes):', tone: 'dim' });
+    const rows = [...(r.receiptRows || [])].sort((a, b) => (b.seq || 0) - (a.seq || 0));
+    for (const x of rows.slice(0, SHOWN)) out.push({ text: `  WARD seq ${x.seq}  envelope ${x.envelope_id}`, tone: 'dim' });
+    if (rows.length > SHOWN) out.push({ text: `  ${rows.length - SHOWN} more in the bundle`, tone: 'dim' });
+    if (!rows.length) out.push({ text: '  No WARD receipt was found for this conversation\'s envelopes yet (witnessing can lag a few seconds).', tone: 'warn' });
+  }
+  if (cmd === '/volt') out.push({ text: '  The VOLT run (if this conversation has one) is volt.json inside the bundle.', tone: 'dim' });
+  out.push({ text: `  check it offline: quox evidence verify ${r.path}`, tone: 'dim' });
+  return out.flatMap(wrapT);
+}

package/lib/quoxon/slash/hatWalk.js

@@ -0,0 +1,206 @@
+/**
+ * CUSTOM-HATS (owner 2026-10-17): /hat new | edit <hat> | delete <hat> in the quox window. One small step machine:
+ * every question is either a y/N/c card (askText, the same shape as every other ask) or a one-line text capture
+ * (a name, a pick by number or name, a list of agents). Esc, or any other slash command, ends the walk and
+ * nothing is sent. Nothing reaches the server until the final summary card is answered y.
+ * The definition maths is shared with `quox hat create|edit` (core/customHats.js); this file has no I/O of its own
+ * beyond the api it is given.
+ */
+import { buildCustomDefinition, applyHatEdits } from '../../core/customHats.js';
+import { matchHat, hatChoices } from '../hatSwitch.js';
+import { askText } from '../ask.js';
+
+export const slugify = (name) => String(name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const isCustom = (hat) => hat?.template_key == null;
+const nameOf = (hat) => hat?.name || hat?.key || 'hat';
+const joinNice = (xs) => xs.join(', ');
+
+/** "1, 3 sec" -> picks resolved against rows [{ id }] -> { ids, unknown } (numbers are 1-based positions). */
+export function pickAgents(line, rows) {
+  const ids = []; const unknown = [];
+  for (const raw of String(line ?? '').split(/[\s,]+/).map(s => s.trim()).filter(Boolean)) {
+    let id = null;
+    if (/^\d+$/.test(raw)) id = rows[Number(raw) - 1]?.id ?? null;
+    else id = rows.find(r => r.id.toLowerCase() === raw.toLowerCase())?.id ?? null;
+    if (!id) unknown.push(raw); else if (!ids.includes(id)) ids.push(id);
+  }
+  return { ids, unknown };
+}
+
+export function createHatWalk({ api, say, bump = () => {} }) {
+  let W = null; // the walk in progress, or null
+
+  const ask = (question, reason = '') => { const st = { at: Date.now() }; W.card = st; W.wait = { ...W.wait, kind: 'yn' }; say(askText(question, { reason }), 'ask'); return st; };
+  const yn = (question, on, reason) => { W.wait = { kind: 'yn', on }; ask(question, reason); bump(); };
+  const text = (prompt, on) => { W.wait = { kind: 'text', on }; W.card = null; say(prompt); bump(); };
+  const end = () => { W = null; bump(); };
+  const fail = (what, e) => { say(`${what}: ${e?.message || 'the server refused'}.`, 'warn'); end(); };
+
+  async function loadAgents() {
+    if (W.agents) return W.agents;
+    try {
+      const rows = await api.agents();
+      W.agents = (Array.isArray(rows) ? rows : []).map(a => ({ id: String(a.agent_id ?? a.id ?? ''), name: a.name || a.agent_id || a.id })).filter(a => a.id);
+    } catch { W.agents = null; }
+    return W.agents;
+  }
+  const agentLabel = (id) => { const a = W.agents?.find(x => x.id === id); return a && a.name && a.name !== id ? `${id} (${a.name})` : id; };
+
+  // Shared tail: keep cards for each current specialist, then "Add agents?". done(kept, added).
+  async function agentSteps(current, done) {
+    await loadAgents();
+    const kept = []; const queue = [...current];
+    const nextKeep = () => {
+      if (!queue.length) return askAdd();
+      const id = queue.shift();
+      yn(`Keep ${agentLabel(id)}?`, (yes) => { if (yes) kept.push(id); nextKeep(); }, 'This hat lists it as a specialist');
+    };
+    const askAdd = () => yn('Add agents?', async (yes) => {
+      if (!yes) return done(kept, []);
+      if (!W.agents?.length) { say('Could not list the org agents, so none were added.', 'warn'); return done(kept, []); }
+      const rows = W.agents.filter(a => !kept.includes(a.id));
+      if (!rows.length) { say('Every agent in this org is already in the hat.'); return done(kept, []); }
+      rows.forEach((a, i) => say(`  ${i + 1}. ${a.id}${a.name && a.name !== a.id ? `  ${a.name}` : ''}`));
+      const pick = () => text('Which agents? Numbers and/or ids, separated by commas or spaces.', (line) => {
+        const { ids, unknown } = pickAgents(line, rows);
+        if (unknown.length) { say(`Not in the list above: ${unknown.join(', ')}.`, 'warn'); return pick(); }
+        if (!ids.length) { say('No agent picked.', 'warn'); return pick(); }
+        done(kept, ids);
+      });
+      pick();
+    });
+    nextKeep();
+  }
+
+  async function startNew() {
+    let hats;
+    try { hats = await api.hats(); } catch (e) { return fail("Couldn't list hats", e); }
+    W = { mode: 'new', hats };
+    const askName = () => text('What should the new hat be called?', (line) => {
+      const name = line.trim(); const key = slugify(name);
+      if (key.length < 2 || key.length > 41) { say('A hat name needs 2 to 41 letters or digits. Try another.', 'warn'); return askName(); }
+      if (hats.some(h => h.key === key)) { say(`A hat with the key "${key}" already exists. Try another name.`, 'warn'); return askName(); }
+      W.name = name; W.key = key; askBase();
+    });
+    const askBase = () => yn('Start from an empty hat?', (yes) => {
+      if (yes) { W.base = null; return agents(); }
+      hats.forEach((h, i) => say(`  ${i + 1}. ${nameOf(h)}  ${h.key}`));
+      const pick = () => text('Which hat should it start from? A number or a name.', (line) => {
+        const t = line.trim();
+        const m = /^\d+$/.test(t) ? { hat: hats[Number(t) - 1] } : matchHat(t, hats);
+        if (m.ambiguous) { say(`"${t}" matches more than one hat: ${hatChoices(m.ambiguous)}. Be more specific.`, 'warn'); return pick(); }
+        if (!m.hat) { say(`No hat matches "${t}".`, 'warn'); return pick(); }
+        W.base = m.hat; agents();
+      });
+      pick();
+    });
+    const agents = () => agentSteps(W.base?.definition?.agents?.specialists || [], (kept, added) => {
+      const list = [...kept, ...added];
+      let built;
+      try { built = buildCustomDefinition({ base: W.base?.definition || null, name: W.name, agents: list }); } catch (e) { return fail('Could not build the hat', e); }
+      yn(`Create the ${W.name} hat with ${list.length ? joinNice(list) : 'no agents'}? It offers only its own tools and agents.`, async (yes) => {
+        if (!yes) { say('Nothing created.', 'dim'); return end(); }
+        const { key, name } = W;
+        try {
+          const r = await api.createHat({ key, name, definition: built.definition, visibility: 'org' });
+          say(`Hat ${name} created (rev ${r?.hat?.current_revision ?? 1}). It is in your hat list now, ready to wear.`, 'ok');
+          for (const w of Array.isArray(r?.warnings) ? r.warnings : []) say(`Note: ${typeof w === 'string' ? w : w?.message || JSON.stringify(w)}`, 'warn');
+        } catch (e) { say(`Hat not created: ${e?.message || 'the server refused'}.`, 'warn'); }
+        end();
+      });
+    });
+    askName();
+  }
+
+  async function findCustom(arg, verb) {
+    let hats;
+    try { hats = await api.hats(); } catch (e) { say(`Couldn't list hats: ${e?.message || 'failed'}.`, 'warn'); return null; }
+    const mine = hats.filter(isCustom);
+    if (!arg) { say(`Which hat? ${mine.length ? `Your own hats: ${hatChoices(mine)}.` : 'You have no hats of your own yet. /hat new makes one.'}`, 'warn'); return null; }
+    const m = matchHat(arg, hats);
+    if (m.ambiguous) { say(`"${arg}" matches more than one hat: ${hatChoices(m.ambiguous)}. Be more specific.`, 'warn'); return null; }
+    if (!m.hat) { say(`No hat matches "${arg}". Your own hats: ${hatChoices(mine) || 'none yet'}.`, 'warn'); return null; }
+    if (!isCustom(m.hat)) {
+      say(verb === 'edit'
+        ? `${nameOf(m.hat)} is a built-in hat, so it is not edited here. It can be reset, or used as a starting point with /hat new.`
+        : `${nameOf(m.hat)} is a built-in hat and cannot be deleted. It can be reset, or used as a starting point with /hat new.`, 'warn');
+      return null;
+    }
+    return m.hat;
+  }
+
+  async function startEdit(arg) {
+    const hat = await findCustom(arg, 'edit'); if (!hat) return;
+    W = { mode: 'edit', hat };
+    const def = hat.definition || {};
+    agentSteps(def.agents?.specialists || [], (kept, added) => {
+      const current = def.agents?.specialists || [];
+      const removeAgents = current.filter(a => !kept.includes(a));
+      const rename = () => yn('Rename it?', (yes) => {
+        if (!yes) return summary(null);
+        const ask2 = () => text('What is the new name?', (line) => { const n = line.trim(); if (!n) { say('A name cannot be empty.', 'warn'); return ask2(); } summary(n); });
+        ask2();
+      });
+      const summary = (newName) => {
+        let ed;
+        try { ed = applyHatEdits(def, { addAgents: added, removeAgents }); } catch (e) { return fail('Could not apply the edit', e); }
+        const changes = [...ed.changes];
+        if (newName && newName !== hat.name) changes.push(`name ${newName}`); else newName = null;
+        if (!changes.length) { say(`Nothing changed on the ${nameOf(hat)} hat. Nothing was sent.`); return end(); }
+        yn(`Update the ${nameOf(hat)} hat: ${changes.join('; ')}?`, async (yes) => {
+          if (!yes) { say('Nothing changed.', 'dim'); return end(); }
+          try {
+            const r = await api.updateHat(hat.id, { definition: ed.definition, ...(newName ? { name: newName } : {}), change_reason: 'Edited from the quox window' });
+            say(`Hat ${newName || nameOf(hat)} updated (rev ${r?.hat?.current_revision ?? 'next'}).`, 'ok');
+            for (const w of Array.isArray(r?.warnings) ? r.warnings : []) say(`Note: ${typeof w === 'string' ? w : w?.message || JSON.stringify(w)}`, 'warn');
+          } catch (e) { say(`Hat not updated: ${e?.message || 'the server refused'}.`, 'warn'); }
+          end();
+        });
+      };
+      rename();
+    });
+  }
+
+  async function startDelete(arg) {
+    const hat = await findCustom(arg, 'delete'); if (!hat) return;
+    W = { mode: 'delete', hat };
+    yn(`Delete the ${nameOf(hat)} hat? Conversations wearing it go back to the default hat.`, async (yes) => {
+      if (!yes) { say('Nothing deleted.', 'dim'); return end(); }
+      try {
+        const r = await api.deleteHat(hat.id);
+        const d = r?.deleted || {};
+        say(`Hat ${nameOf(hat)} deleted. Conversations moved off it: ${d.bindings_cleared ?? 0}. Personal choices cleared: ${d.user_prefs_cleared ?? 0}.`, 'ok');
+      } catch (e) { say(`Hat not deleted: ${e?.message || 'the server refused'}.`, 'warn'); }
+      end();
+    }, 'It cannot be undone');
+  }
+
+  return {
+    active: () => Boolean(W),
+    /** the y/N/c card currently on screen (for the ask machinery), or null */
+    card: () => (W?.wait?.kind === 'yn' ? W.card : null),
+    start(kind, arg = '') {
+      if (W) { say('A hat walk is already open. Esc cancels it.', 'warn'); return; }
+      if (kind === 'new') return startNew();
+      if (kind === 'edit') return startEdit(arg);
+      return startDelete(arg);
+    },
+    /** One typed line. true = consumed. A slash command ends the walk and is left to run. */
+    answer(line) {
+      if (!W?.wait) return false;
+      const t = String(line ?? '').trim();
+      if (t.startsWith('/')) { W = null; say('Hat walk ended. Nothing was sent.', 'dim'); bump(); return false; }
+      const w = W.wait;
+      if (w.kind === 'yn') {
+        const yes = /^y(es)?$/i.test(t);
+        if (!yes && t && !/^no?$/i.test(t)) return false; // c or free text: the card's normal chat behaviour
+        W.wait = null; Promise.resolve(w.on(yes)).catch((e) => fail('Hat walk failed', e));
+        return true;
+      }
+      if (!t) return true;
+      W.wait = null; Promise.resolve(w.on(t)).catch((e) => fail('Hat walk failed', e));
+      return true;
+    },
+    cancel() { if (!W) return false; W = null; say('Hat walk cancelled. Nothing was sent.', 'dim'); bump(); return true; },
+  };
+}

package/lib/quoxon/slash/inverses.js

@@ -0,0 +1,77 @@
+/**
+ * /undo: which tool calls count as state changes, and the small registry of KNOWN inverses.
+ *
+ * Receipts are content-free on purpose (the AEE envelope commits to the action by digest, never plaintext
+ * args) and the stream summary only echoes a few safe keys. So an inverse is never built from "what the
+ * receipt said the args were". Each entry binds its target from something that is really there: a safe key
+ * in the call's own summary (slot name), or the server's own record of what the call produced, matched by
+ * time window and accepted only when EXACTLY ONE record fits. Zero or several = not bound = nothing runs,
+ * and the user gets the by-hand route. Nothing here guesses an inverse.
+ */
+
+const READ_ONLY = /(^|_)(list|get|read|search|status|view|history|health|query|check|show|stats|find|lookup|related|suggest|research|describe|info|accounts|folders|pending|proposals|blocked|report|transcript|doctor|ping|whoami|verify)(_|$)/;
+
+/** A settled, successful, receipt-backed call that is not a read. */
+export function isStateChanging(b) {
+  return Boolean(b) && b.kind === 'tool' && b.status === 'ok' && Boolean(b.envelopeId) && Boolean(b.tool) && !READ_ONLY.test(String(b.tool));
+}
+
+export function lastStateChange(items) {
+  const all = (items || []).filter(isStateChanging);
+  return all.length ? all[all.length - 1] : null;
+}
+
+const WIN_BEFORE = 10_000;
+const WIN_AFTER = 20_000;
+const toMs = (v) => (typeof v === 'number' ? v : Number.isFinite(Date.parse(v)) ? Date.parse(v) : null);
+function inWindow(call, ts) {
+  const t = toMs(ts);
+  if (t == null || !Number.isFinite(call.startedAt)) return false;
+  return t >= call.startedAt - WIN_BEFORE && t <= call.startedAt + (call.durationMs || 0) + WIN_AFTER;
+}
+const summaryKey = (call, key) => new RegExp(`(?:^|\\s)${key}=(\\S+)`).exec(String(call.summary || ''))?.[1] || null;
+
+/** Each bind -> { ok: true, label, run(ops) -> { receipt } } | { ok: false, why, byHand } */
+export const INVERSES = {
+  slot_checkout: {
+    did: 'checked a slot out for this conversation',
+    async bind(call) {
+      const name = summaryKey(call, 'name');
+      if (!name) return { ok: false, why: 'the call summary does not name the slot', byHand: 'quox slot list, then quox slot release <name>' };
+      return { ok: true, reverse: `release slot ${name} (the hold ends; the slot itself stays)`, run: (ops) => ops.releaseSlot(name) };
+    }
+  },
+  inbox_move: {
+    did: 'moved mail between folders',
+    async bind(call, ops) {
+      const moves = (await ops.recentMoves()).filter(m => inWindow(call, m.movedAt ?? m.moved_at));
+      if (moves.length === 1) {
+        const m = moves[0];
+        return { ok: true, reverse: `move the message back from ${m.toFolder || m.to_folder || 'its new folder'} to ${m.fromFolder || m.from_folder || 'its source folder'} (move ${m.id})`, run: (o) => o.undoMove(m.id) };
+      }
+      return { ok: false, why: moves.length ? `more than one move fits that call (${moves.map(m => m.id).join(', ')}), so Quox can't tell which one it made` : 'no recorded move fits that call', byHand: 'quox mail moves, then quox mail undo <moveId>' };
+    }
+  },
+  notesq_create: {
+    did: 'created a note',
+    async bind(call, ops) {
+      const notes = (await ops.listNotes()).filter(n => inWindow(call, n.createdAt ?? n.created_at));
+      if (notes.length === 1) {
+        const n = notes[0];
+        return { ok: true, reverse: `delete the note "${n.title || n.id}" (${n.id})`, run: (o) => o.deleteNote(n.id) };
+      }
+      return { ok: false, why: notes.length ? `more than one note fits that call (${notes.map(n => n.id).join(', ')})` : 'no recorded note fits that call', byHand: 'quox notes list, then delete the one you mean from NotesQ' };
+    }
+  }
+};
+
+/** Tools that change state but have no automatic inverse here: the by-hand route, stated plainly. */
+export const BY_HAND = {
+  activate_workflow: 'quox workflow list, then deactivate it from the dashboard or ask Quox to deactivate_workflow with the id',
+  deactivate_workflow: 'reactivate it with activate_workflow, or from the dashboard',
+  skill_manage: 'a created skill sits in the review queue: reject it there, or leave it unapproved',
+  notesq_delete: 'ask Quox to notesq_restore the note, or use quox notes restore <id>',
+  email_send: 'a sent email cannot be recalled',
+  email: 'a sent email cannot be recalled',
+  slot_say: 'a message already posted in a slot room stays there'
+};

package/lib/quoxon/slash/killer.js

@@ -0,0 +1,24 @@
+/**
+ * /watch, /automate, /crystallize: the shared factory app.js wires (switch cases + one answer hook).
+ * Each command makes ONE preview card; the next line y/n creates through an existing backend path.
+ */
+import { createConfirm } from './confirm.js';
+import { createWatchCmd } from './watch.js';
+import { createAutomateCmd } from './automate.js';
+import { createCrystallizeCmd } from './crystallize.js';
+
+export function createKillerCmds({ api, say, getState, getFields }) {
+  const confirm = createConfirm({ say });
+  const watch = createWatchCmd({ api, say, confirm });
+  const automate = createAutomateCmd({ api, say, confirm, getState, getFields });
+  const crystallize = createCrystallizeCmd({ api, say, confirm, getState, getFields });
+  return {
+    crystallize: (arg) => crystallize.handle(arg),
+    automate: (arg) => automate.handle(arg),
+    watch: (arg) => watch.handle(arg),
+    /** The composer line after a preview card: true when consumed as the y/n answer. */
+    answer: (text) => confirm.answer(text),
+    pending: () => confirm.pending(),
+    touch: () => confirm.touch()
+  };
+}