quoxcli 0.0.0-stage → 0.3.1

package/lib/core/output.js

@@ -0,0 +1,239 @@
+/**
+ * Output formatter for QuoxCLI
+ *
+ * All commands pass results through this module.
+ * Supports: table, json, csv, quiet output modes.
+ */
+
+import chalk from 'chalk';
+import Table from 'cli-table3';
+
+/**
+ * Format and print tabular data
+ *
+ * @param {Object} result - { columns, headers, rows } or array of objects
+ * @param {Object} options - { format, title, emptyMessage, full } (full: no 60-char cell truncation in table mode)
+ */
+export function formatOutput(result, options = {}) {
+  const format = options.format || getOutputFormat();
+  const rows = result.rows || result;
+  const columns = result.columns || (rows.length > 0 ? Object.keys(rows[0]) : []);
+  const headers = result.headers || columns;
+
+  // options.raw: the untransformed API records behind the display rows.
+  // --json exists for scripting, and scripts want DATA keys (name, state,
+  // holder_session), not the humanised table cells (NAME, HOLDER, "2d") the
+  // display rows carry -- `quox --json slot list` emitting NAME/STATE bit a
+  // live harness on 2026-08-20. Table/csv/quiet still render the display
+  // rows; json prefers raw when the caller provides it.
+  if (!Array.isArray(rows) || rows.length === 0) {
+    if (format === 'json') {
+      console.log(JSON.stringify(Array.isArray(options.raw) ? options.raw : []));
+    } else if (format === 'csv') {
+      console.log(headers.join(','));
+    } else if (format !== 'quiet') {
+      console.log(chalk.dim(options.emptyMessage || 'No results.'));
+    }
+    return;
+  }
+
+  switch (format) {
+    case 'json':
+      console.log(JSON.stringify(Array.isArray(options.raw) ? options.raw : rows, null, 2));
+      break;
+    case 'csv':
+      formatCsv(rows, columns, headers);
+      break;
+    case 'quiet':
+      formatQuiet(rows, columns);
+      break;
+    default:
+      formatTable(rows, columns, headers, options);
+  }
+}
+
+/**
+ * Format and print a single object (detail view)
+ */
+export function formatDetail(obj, options = {}) {
+  const format = options.format || getOutputFormat();
+
+  if (format === 'json') {
+    console.log(JSON.stringify(obj, null, 2));
+    return;
+  }
+
+  if (format === 'quiet') {
+    console.log(obj.id || obj.name || '');
+    return;
+  }
+
+  // Key-value display
+  const fields = options.fields || Object.keys(obj);
+  const labels = options.labels || {};
+
+  if (options.title) {
+    console.log(chalk.bold(options.title));
+    console.log(chalk.dim('─'.repeat(Math.min(options.title.length + 10, 60))));
+  }
+
+  const maxLabel = Math.max(...fields.map(f => (labels[f] || f).length));
+
+  for (const field of fields) {
+    const label = (labels[field] || field).padEnd(maxLabel + 2);
+    const raw = obj[field];
+    if (raw !== null && typeof raw === 'object') {
+      console.log(`  ${chalk.dim(label)}${formatNestedValue(raw)}`);
+    } else {
+      const value = formatValue(raw);
+      console.log(`  ${chalk.dim(label)} ${value}`);
+    }
+  }
+}
+
+/**
+ * Recursively render a nested object/array value for formatDetail, instead
+ * of falling through to formatValue's String(value) -> "[object Object]".
+ * Kept local to formatDetail (not folded into formatValue) so formatTable /
+ * formatCsv output is unchanged.
+ */
+function formatNestedValue(value, indent = 4) {
+  if (value == null) return ` ${chalk.dim('-')}`;
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return ` ${chalk.dim('[]')}`;
+    const allPrimitive = value.every(v => v === null || typeof v !== 'object');
+    if (allPrimitive) return ` ${value.map(v => formatValue(v)).join(', ')}`;
+    return '\n' + value
+      .map(v => `${' '.repeat(indent)}- ${typeof v === 'object' && v !== null ? formatNestedValue(v, indent + 2).trimStart() : formatValue(v)}`)
+      .join('\n');
+  }
+
+  const keys = Object.keys(value);
+  if (keys.length === 0) return ` ${chalk.dim('{}')}`;
+  return '\n' + keys
+    .map(k => {
+      const v = value[k];
+      if (v !== null && typeof v === 'object') {
+        return `${' '.repeat(indent)}${chalk.dim(k + ':')}${formatNestedValue(v, indent + 2)}`;
+      }
+      return `${' '.repeat(indent)}${chalk.dim(k + ':')} ${formatValue(v)}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Print a success message
+ */
+export function printSuccess(message) {
+  const format = getOutputFormat();
+  if (format === 'json') {
+    console.log(JSON.stringify({ success: true, message }));
+  } else if (format !== 'quiet') {
+    console.log(chalk.green(message));
+  }
+}
+
+/**
+ * Print a warning message
+ */
+export function printWarning(message) {
+  if (getOutputFormat() !== 'quiet') {
+    console.error(chalk.yellow(message));
+  }
+}
+
+/**
+ * Print info message (suppressed in quiet/json mode)
+ */
+export function printInfo(message) {
+  const format = getOutputFormat();
+  if (format !== 'quiet' && format !== 'json') {
+    console.log(chalk.dim(message));
+  }
+}
+
+// -- Internal helpers --
+
+function formatTable(rows, columns, headers, options) {
+  const table = new Table({
+    head: headers.map(h => chalk.bold(h)),
+    style: { head: [], border: [] },
+    chars: {
+      'top': '', 'top-mid': '', 'top-left': '', 'top-right': '',
+      'bottom': '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '',
+      'left': '', 'left-mid': '', 'mid': '', 'mid-mid': '',
+      'right': '', 'right-mid': '', 'middle': '  ',
+    },
+  });
+
+  for (const row of rows) {
+    table.push(columns.map(col => formatValue(row[col], options.full === true)));
+  }
+
+  console.log(table.toString());
+
+  // Show count
+  if (rows.length > 10) {
+    console.log(chalk.dim(`\n${rows.length} items`));
+  }
+}
+
+function formatCsv(rows, columns, headers) {
+  console.log(headers.map(csvEscape).join(','));
+  for (const row of rows) {
+    console.log(columns.map(col => csvEscape(row[col])).join(','));
+  }
+}
+
+function formatQuiet(rows, columns) {
+  // Print first column (usually ID) of each row
+  const idCol = columns[0];
+  for (const row of rows) {
+    console.log(row[idCol] ?? '');
+  }
+}
+
+function csvEscape(value) {
+  const str = String(value ?? '');
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}
+
+function formatValue(value, full = false) {
+  if (value == null) return chalk.dim('-');
+  if (typeof value === 'boolean') return value ? chalk.green('yes') : chalk.dim('no');
+
+  const str = String(value);
+
+  // Color status values
+  const lower = str.toLowerCase();
+  if (['active', 'healthy', 'operational', 'approved', 'online', 'success'].includes(lower)) {
+    return chalk.green(str);
+  }
+  if (['degraded', 'warning', 'pending', 'in_progress', 'draft', 'stale'].includes(lower)) {
+    return chalk.yellow(str);
+  }
+  if (['error', 'down', 'failed', 'rejected', 'retired', 'offline', 'suspended', 'dead'].includes(lower)) {
+    return chalk.red(str);
+  }
+
+  // Truncate long values in table mode
+  if (!full && str.length > 60) return str.slice(0, 57) + '...';
+
+  return str;
+}
+
+export function getOutputFormat() {
+  if (process.argv.includes('--json')) return 'json';
+  if (process.argv.includes('-q') || process.argv.includes('--quiet')) return 'quiet';
+
+  const idx = process.argv.indexOf('-o');
+  if (idx !== -1 && process.argv[idx + 1]) return process.argv[idx + 1];
+  const idx2 = process.argv.indexOf('--output');
+  if (idx2 !== -1 && process.argv[idx2 + 1]) return process.argv[idx2 + 1];
+
+  return 'table';
+}

package/lib/core/peek.js

@@ -0,0 +1,126 @@
+/**
+ * PEEK: look up one id without knowing what it is. `quox peek <id>` and the TUI /peek share this.
+ *
+ * The id's shape picks the kinds worth asking for (an envelope, inbox item, objective and workflow run
+ * are all ULIDs, so a ULID asks all four at once; a WARD receipt is a UUID; an agent is a slug). Every
+ * lookup reuses an existing read endpoint. A 404 means "not this kind"; any other failure is kept and
+ * said, so an unknown id always names exactly what was tried and what each answered.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SLUG = /^[a-z][a-z0-9_-]{0,63}$/i;
+
+export const KIND_LABEL = { envelope: 'envelope', inbox: 'inbox item', objective: 'objective', run: 'workflow run', receipt: 'WARD receipt', agent: 'agent' };
+
+/** -> { id (normalised), kinds: ordered kinds to try, shape: a plain word for the id's shape }. */
+export function idShapes(raw) {
+  const id = String(raw ?? '').trim();
+  if (!id) return { id, kinds: [], shape: 'empty' };
+  if (/^ENV_/i.test(id)) return { id, kinds: ['envelope'], shape: 'envelope id' };
+  const obj = id.match(/^OBJ_([0-9A-HJKMNP-TV-Z]{26})$/i); // an objective's corr id
+  if (obj) return { id: obj[1], kinds: ['objective'], shape: 'objective correlation id' };
+  if (UUID.test(id)) return { id, kinds: ['receipt', 'inbox'], shape: 'UUID' };
+  if (ULID.test(id)) return { id: id.toUpperCase(), kinds: ['envelope', 'inbox', 'objective', 'run'], shape: 'ULID' };
+  if (SLUG.test(id)) return { id, kinds: ['agent', 'inbox'], shape: 'name' };
+  return { id, kinds: [], shape: 'unrecognised' };
+}
+
+const unwrap = (d, ...keys) => { for (const k of keys) if (d && d[k] && typeof d[k] === 'object') return d[k]; return d; };
+
+/**
+ * One fetcher per kind on a CLI client. Each resolves to the object or throws the client's error
+ * (with .status). orgId: a function returning the org the caller is acting in (the window org in the TUI).
+ */
+export function createPeekFetchers({ client, orgId }) {
+  const org = () => { const o = typeof orgId === 'function' ? orgId() : orgId; return typeof o === 'string' && o ? o : null; };
+  const get = (name, params, opts = {}) => { const ep = resolveEndpoint(name, params); return client.get(ep.path, { service: ep.service, retries: 0, timeout: 25000, ...opts }); };
+  const needOrg = () => { const o = org(); if (!o) { const e = new Error('no org on this login'); e.status = 0; throw e; } return o; };
+  return {
+    envelope: async (id) => unwrap(await get('aee.get', { id: encodeURIComponent(id) }), 'envelope'),
+    inbox: async (id) => unwrap(await get('inbox.get', { orgId: needOrg(), itemId: encodeURIComponent(id) }), 'item'),
+    objective: async (id) => unwrap(await get('objectives.get', { id: encodeURIComponent(id) }), 'objective', 'data'),
+    run: async (id) => {
+      try { return unwrap(await get('executions.get', { executionId: encodeURIComponent(id) }), 'data', 'execution'); }
+      catch (e) { if (e?.status !== 404) throw e; }
+      return unwrap(await get('runs.get', { orgId: needOrg(), pollRunId: encodeURIComponent(id) }), 'run', 'data');
+    },
+    receipt: async (id) => unwrap(await get('ward.entries.get', { id: encodeURIComponent(id) }), 'entry'),
+    agent: async (id) => {
+      try { return unwrap(await get('agents.get', { orgId: needOrg(), agentId: encodeURIComponent(id) }), 'agent'); }
+      catch (e) { if (e?.status !== 404) throw e; }
+      const reg = await get('v1.agents.registry', {});
+      const hit = (reg?.agents || []).find(r => r.agent_id === id || String(r.name || '').toLowerCase() === id.toLowerCase());
+      if (!hit) { const e = new Error('Agent not found'); e.status = 404; throw e; }
+      return { ...hit, source: 'registry' };
+    },
+  };
+}
+
+const failText = (e) => {
+  if (e?.status === 404) return 'not found';
+  if (e?.status === 401 || e?.status === 403) return `HTTP ${e.status} (not allowed for this login)`;
+  if (e?.status) return `HTTP ${e.status}${e.message ? `: ${String(e.message).slice(0, 80)}` : ''}`;
+  return String(e?.message || 'failed').slice(0, 80);
+};
+
+/**
+ * Ask every candidate kind at once; the first hit in shape order wins, other hits are named.
+ * -> { id, shape, hit: { kind, data } | null, also: [kind], tried: [{ kind, result }] }
+ */
+export async function peekId(raw, fetchers) {
+  const { id, kinds, shape } = idShapes(raw);
+  const settled = await Promise.all(kinds.map(async (kind) => {
+    try {
+      const data = await fetchers[kind](id);
+      if (data == null || (typeof data === 'object' && !Object.keys(data).length)) return { kind, result: 'empty answer' };
+      return { kind, data };
+    } catch (e) { return { kind, result: failText(e) }; }
+  }));
+  const hits = settled.filter(s => 'data' in s);
+  return {
+    id, shape,
+    hit: hits[0] ? { kind: hits[0].kind, data: hits[0].data } : null,
+    also: hits.slice(1).map(s => s.kind),
+    tried: settled.map(s => ({ kind: s.kind, result: 'data' in s ? 'found' : s.result })),
+  };
+}
+
+const s = (v) => (v == null || v === '' ? null : String(v));
+const short = (v, n = 16) => { const t = s(v); return t && t.length > n ? `${t.slice(0, n)}…` : t; };
+const when = (v) => { const t = s(v); return t ? t.replace('T', ' ').replace(/\.\d+Z$/, 'Z') : null; };
+const parse = (v) => { if (v && typeof v === 'object') return v; try { return JSON.parse(v); } catch { return null; } };
+
+export const MORE = { envelope: (id) => `quox aee get ${id}`, inbox: (id) => `quox inbox get ${id}`, objective: (id) => `quox objective get ${id}`, run: (id) => `quox run get ${id}`, receipt: () => 'quox governance ward entries', agent: (id) => `quox agent get ${id}` };
+
+/** kind -> data -> [[label, value|null]]: the card fields, shared by peekLines and the TUI card. */
+export const ROWS = {
+  envelope: (d) => [['intent', s(d.intent)], ['from', s(d.from) && `${d.from} → ${d.to || '?'}`], ['type', s(d.type)], ['corr', s(d.corr)], ['at', when(d.ts || d.timestamp)]],
+  inbox: (d) => { const p = parse(d.payload_json) || {}; return [['title', s(d.title)], ['kind', s(d.kind)], ['status', [d.status, d.priority && `${d.priority} priority`].filter(Boolean).join(', ') || null], ['from', s(p.agent || p.session || p.source || d.created_by)], ['created', when(d.created_at)]]; },
+  objective: (d) => [['title', s(d.title)], ['status', s(d.status)], ['tasks', d.task_count != null ? `${d.tasks_completed ?? 0} of ${d.task_count} done${d.tasks_failed ? `, ${d.tasks_failed} failed` : ''}` : null], ['team', s(d.team_id)], ['created', when(d.created_at)]],
+  run: (d) => [['workflow', s(d.workflowName || d.workflow_name || d.workflowId || d.workflow_id)], ['status', s(d.status)], ['trigger', s(d.triggerData?.trigger || d.trigger)], ['started', when(d.startedAt || d.started_at || d.createdAt || d.created_at)], ['finished', when(d.finishedAt || d.completedAt || d.completed_at)]],
+  receipt: (d) => [['chain', d.chain_id ? `${d.chain_id} #${d.seq ?? '?'}` : null], ['witnessed', s(d.source_kind) && `${d.source_kind} ${d.source_id || ''}`.trim()], ['at', when(d.witnessed_at)], ['hash', short(d.chain_hash)]],
+  agent: (d) => [['name', s(d.name)], ['role', [d.role, d.level != null && `level ${d.level}`].filter(Boolean).join(', ') || null], ['about', s(d.description)], ['tools', d.tool_count != null ? String(d.tool_count) : null], ['source', s(d.source)]],
+};
+
+/**
+ * Plain lines for a peek result: [{ text, tone }] (tone ok | warn | dim | null). Width-agnostic; the caller clips.
+ */
+export function peekLines(r) {
+  if (!r) return [];
+  if (!r.hit) {
+    if (r.shape === 'empty') return [{ text: 'Usage: peek <id>. An envelope, inbox item, objective, workflow run, WARD receipt or agent id.', tone: 'warn' }];
+    if (!r.tried.length) return [{ text: `"${r.id}" does not look like any id Quox issues (envelope, inbox item, objective, run or agent ULID, WARD receipt UUID, agent name). Nothing was looked up.`, tone: 'warn' }];
+    return [
+      { text: `Nothing found for ${r.id}.`, tone: 'warn' },
+      { text: `Tried (${r.shape}): ${r.tried.map(t => `${KIND_LABEL[t.kind]} ${t.result}`).join(' · ')}`, tone: 'dim' },
+    ];
+  }
+  const { kind, data } = r.hit;
+  const out = [{ text: `◇ ${KIND_LABEL[kind]} ${r.id}`, tone: 'ok' }];
+  for (const [k, v] of ROWS[kind](data || {})) if (v) out.push({ text: `  ${k.padEnd(9)} ${v}`, tone: null });
+  if (r.also.length) out.push({ text: `  ${'also'.padEnd(9)} an id of the same value: ${r.also.map(k => KIND_LABEL[k]).join(', ')}`, tone: 'dim' });
+  out.push({ text: `  ${'more'.padEnd(9)} ${MORE[kind](r.id)}`, tone: 'dim' });
+  return out;
+}

package/lib/core/prodEnv.js

@@ -0,0 +1,7 @@
+/**
+ * Imported FIRST by the shipped bins (bin/quox.js, bin/quoxon.js), before anything that loads React: ES modules
+ * evaluate in import order, and React picks its build from NODE_ENV when it is first loaded. The development
+ * build roughly doubles CPU per animation frame (measured: ~51% vs 12-30% at 12 fps, 100x40). An explicit
+ * NODE_ENV (a developer's, or a test runner's) is always kept.
+ */
+if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production';

package/lib/core/profileUsers.js

@@ -0,0 +1,51 @@
+/**
+ * #1034: which OTHER quox processes on this machine use a given CLI profile. `quox org switch` changes the shared
+ * profile's default org, so it names the sessions that will follow it (a TUI `/org switch` only moves its own window).
+ * Linux /proc only; elsewhere the answer is an empty list. Reads argv and the single QUOX_PROFILE env field, nothing else.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+
+const isQuox = (a) => /(^|\/)quox(\.js|\.mjs)?$/.test(String(a || ''));
+
+/** The profile a process selected: a name, '' for "the config default", or null when it is not quox. */
+export function profileOf({ argv = [], env = {} }) {
+  const at = argv.slice(0, 2).findIndex(isQuox);
+  if (at < 0) return null;
+  const rest = argv.slice(at + 1);
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === '-p' || a === '--profile') return rest[i + 1] || '';
+    if (a.startsWith('--profile=')) return a.slice('--profile='.length);
+  }
+  return env.QUOX_PROFILE || '';
+}
+
+export function otherProfileUsers({ profile, defaultProfile, procs, selfPids = [] }) {
+  const self = new Set(selfPids);
+  return procs.filter(p => {
+    if (self.has(p.pid)) return false;
+    const sel = profileOf(p);
+    if (sel === null) return false;
+    return sel === profile || (sel === '' && profile === defaultProfile);
+  });
+}
+
+/** Live processes of this user: [{ pid, argv, env: { QUOX_PROFILE? } }]. */
+export function listProcs(root = '/proc') {
+  let dirs;
+  try { dirs = readdirSync(root).filter(d => /^\d+$/.test(d)); } catch { return []; }
+  const out = [];
+  for (const d of dirs) {
+    try {
+      const argv = readFileSync(`${root}/${d}/cmdline`, 'utf8').split('\0').filter(Boolean);
+      if (!argv.slice(0, 2).some(isQuox)) continue;
+      let env = {};
+      try {
+        const line = readFileSync(`${root}/${d}/environ`, 'utf8').split('\0').find(l => l.startsWith('QUOX_PROFILE='));
+        if (line) env = { QUOX_PROFILE: line.slice('QUOX_PROFILE='.length) };
+      } catch { /* not ours to read */ }
+      out.push({ pid: Number(d), argv, env });
+    } catch { /* exited */ }
+  }
+  return out;
+}

package/lib/core/promptCancel.js

@@ -0,0 +1,18 @@
+/**
+ * #1101: Ctrl-C (or a closed stdin) at an inquirer prompt rejects with ExitPromptError
+ * ("User force closed the prompt with SIGINT"). That is the user leaving, not a crash: say so in one word,
+ * put the cursor back, and exit 130 instead of printing a raw Error line.
+ */
+export const PROMPT_CANCELLED = 'Cancelled.';
+
+export function isPromptCancel(err) {
+  if (!err) return false;
+  return err.name === 'ExitPromptError' || /User force closed the prompt/.test(String(err.message || ''));
+}
+
+export function exitOnPromptCancel(err, { stderr = process.stderr, exit = process.exit } = {}) {
+  if (!isPromptCancel(err)) return false;
+  try { stderr.write(`\x1b[?25h\n${PROMPT_CANCELLED}\n`); } catch { /* the exit still happens */ }
+  exit(130);
+  return true;
+}

package/lib/core/quoxglyph.js

@@ -0,0 +1,158 @@
+/**
+ * @quox/glyph — the canonical JS implementation of the QuoxGlyph terminal
+ * output language (DEVSUITE-GLYPH). Spec: quox-skills
+ * quoxify/references/quoxglyph-spec.md. This package IS the spec's constants:
+ * ports must consume it (or test against it), never re-type the values.
+ *
+ * Grammar:  <icon> NAME │ <verb object> │ <result> · <duration> [status]
+ * Colour:   truecolor, degrades to plain when !isTTY or NO_COLOR.
+ *           Brand gradient #38bdf8 -> #a855f7; rainbow RESERVED for completed.
+ */
+
+export const GRAD = [[56, 189, 248], [168, 85, 247]];
+export const RAINBOW = [
+  [255, 59, 48], [255, 149, 0], [255, 204, 0], [52, 199, 89],
+  [0, 199, 190], [10, 132, 255], [94, 92, 230], [191, 90, 242]
+];
+export const STATUS = {
+  ok: { glyph: '✔', rgb: [48, 209, 88] },
+  fail: { glyph: '✖', rgb: [255, 69, 58] },
+  busy: { glyph: '◐', rgb: [56, 189, 248] },
+  warn: { glyph: '⚠', rgb: [255, 214, 10] },
+  block: { glyph: '⛔', rgb: null }
+};
+export const ICONS = {
+  repobrain: '🧠 REPOBRAIN', clarify: '🔍 CLARIFY', qlarity: '🔍 QLARITY',
+  quoxplan: '🧭 QUOXPLAN', doneengine: '🏁 DONEENGINE', quoxbuild: '🔨 QUOXBUILD',
+  quoxsignal: '📡 QUOXSIGNAL', bastion: '🛰️ BASTION', precompact: '🧿 PRECOMPACT',
+  brain2: '🌌 QORTEX',
+  watchtower: '📨 WATCHTOWER', metron: '⏳ METRON',
+  quoxseo: '📈 QUOXSEO', reach: '💥 REACH', vulcan: '🌋 VULCAN',
+  quoxvoice: '📞 QUOXVOICE', quoxsecurity: '🛡️ QUOXSECURITY', quoxpert: '🎓 QUOXPERT',
+  quoxslots: '📍 QUOXSLOTS',
+  quox: 'Ⓠ QUOX'
+};
+export const BUDGETS = { VERB_MAX: 48, RESULT_MAX: 40, LINE_MAX: 120, TREE_MAX: 6, TABLE_MAX: 6 };
+export const PUA_Q = ''; // real horned Q, served by QuoxSymbols font
+
+const R = '\x1b[0m', DIM = '\x1b[2m', BOLD = '\x1b[1m';
+const fg = ([r, g, b]) => `\x1b[38;2;${r};${g};${b}m`;
+
+let forced = null;
+/** Force colour on/off (null = auto: isTTY && !NO_COLOR). */
+export function setColor(v) { forced = v; }
+function on() {
+  if (forced !== null) return forced;
+  const env = process.env.QUOX_COLOR;
+  if (env === '0') return false;
+  if (env === '1' || env === '2') return true;
+  return Boolean(process.stdout && process.stdout.isTTY) && !process.env.NO_COLOR;
+}
+
+function iconFor(surface) {
+  let name = ICONS[surface] || `Ⓠ ${String(surface).toUpperCase()}`;
+  if (process.env.QUOX_BRAND_FONT === '1') name = name.replace('Ⓠ', PUA_Q);
+  return name;
+}
+
+/** "<icon> NAME" with NAME painted in the brand gradient, bold, so a Quox
+ *  line stands out in tool output (owner 2026-10-05). Plain when colour is off. */
+export function brandName(label, col = on()) {
+  if (!col) return label;
+  const i = label.indexOf(' ');
+  const icon = i > 0 ? label.slice(0, i) : '';
+  const chars = [...(i > 0 ? label.slice(i + 1) : label)];
+  const last = Math.max(chars.length - 1, 1);
+  const painted = chars.map((c, k) => fg(GRAD[0].map((v, j) => Math.round(v + (GRAD[1][j] - v) * k / last))) + c).join('');
+  return `${icon ? icon + ' ' : ''}${BOLD}${painted}${R}`;
+}
+
+const trunc = (s, max) => ([...s].length > max ? [...s].slice(0, max - 1).join('') + '…' : s);
+
+/** The grammar event line. opts: {result, ms, status} */
+export function line(surface, verb, opts = {}) {
+  const col = on();
+  const name = brandName(iconFor(surface), col);
+  const sep = col ? `${DIM}│${R}` : '│';
+  let tail = opts.result ? trunc(opts.result, BUDGETS.RESULT_MAX) : '';
+  if (opts.ms !== undefined) {
+    const d = col ? `${DIM}${opts.ms}ms${R}` : `${opts.ms}ms`;
+    tail = tail ? `${tail} ${col ? DIM + '·' + R : '·'} ${d}` : d;
+  }
+  const s = opts.status && STATUS[opts.status];
+  if (s) tail += ' ' + (col && s.rgb ? `${fg(s.rgb)}${s.glyph}${R}` : s.glyph);
+  const v = trunc(verb, BUDGETS.VERB_MAX);
+  return tail ? `${name} ${sep} ${v} ${sep} ${tail}` : `${name} ${sep} ${v}`;
+}
+
+/** Gradient progress meter: ▰▰▰▱ done/total (or pct when total omitted). */
+export function meter(done, total, width = 8) {
+  const col = on();
+  const pct = total === undefined || total === null;
+  const ratio = pct ? Math.min(100, Math.max(0, done)) / 100 : (total > 0 ? done / total : 0);
+  const filled = Math.round(ratio * width);
+  const last = Math.max(1, width - 1);
+  let bar = '';
+  for (let i = 0; i < filled; i++) {
+    if (col) {
+      const t = i / last;
+      bar += fg(GRAD[0].map((v, k) => Math.round(v + (GRAD[1][k] - v) * t)));
+    }
+    bar += '▰';
+  }
+  if (col && filled) bar += R;
+  bar += (col ? DIM : '') + '▱'.repeat(Math.max(0, width - filled)) + (col ? R : '');
+  return pct ? `${bar} ${done}%` : `${bar} ${done}/${total}`;
+}
+
+/** Rainbow text. RESERVED for the `completed` lifecycle event. */
+export function celebrate(text) {
+  if (!on()) return text;
+  const chars = [...text];
+  const last = Math.max(1, chars.length - 1);
+  return chars.map((ch, i) => {
+    const t = (i / last) * (RAINBOW.length - 1);
+    const seg = Math.min(RAINBOW.length - 2, Math.floor(t));
+    const local = t - seg;
+    return fg(RAINBOW[seg].map((v, k) => Math.round(v + (RAINBOW[seg + 1][k] - v) * local))) + ch;
+  }).join('') + R;
+}
+
+/** WARD receipt footer. */
+export function receipt(hash, ts) {
+  const col = on();
+  const chain = col ? `${fg([168, 85, 247])}⛓${R}` : '⛓';
+  const label = col ? `${DIM}ward:${R}` : 'ward:';
+  const t = ts ? (col ? ` ${DIM}· witnessed ${ts}${R}` : ` · witnessed ${ts}`) : '';
+  return `${chain} ${label}${String(hash).slice(0, 12)}${t}`;
+}
+
+/**
+ * Lifecycle events (spec section 4b): the contract every product emits.
+ * Each returns a rendered line; the caller prints it.
+ */
+export const events = {
+  created: (surface, thing, id) => line(surface, `${thing} created`, { result: id, status: 'ok' }),
+  updated: (surface, thing, id, delta) =>
+    line(surface, `${thing} updated`, { result: delta ? `${id} ${delta}` : id, status: 'ok' }),
+  progressed: (surface, step, id, done, total) =>
+    line(surface, step, { result: `${id} ${meter(done, total)}` }),
+  completed: (surface, thing, text) => line(surface, thing, { result: celebrate(text) }),
+  assigned: (surface, thing, holder) => line(surface, `${thing} assigned`, { result: holder, status: 'busy' }),
+  released: (surface, thing, id) => line(surface, `${thing} released`, { result: id, status: 'ok' }),
+  failed: (surface, thing, why) => line(surface, `${thing} failed`, { result: why, status: 'fail' }),
+  warned: (surface, thing, risk) => line(surface, thing, { result: risk, status: 'warn' })
+};
+
+// ---- quoxcli integration (not part of the @quox/glyph copy above) ----
+// VENDORED from quox-plugin-sdk packages/quox-glyph/index.js until the
+// owner-gated npm publish lands; the lockstep test in quoxglyph.test.js
+// fails if this copy drifts from the package.
+import { getOutputFormat } from './output.js';
+
+/** Print a rendered glyph line, respecting --output json/quiet. */
+export function printEvent(rendered) {
+  const format = getOutputFormat();
+  if (format === 'json' || format === 'quiet') return;
+  console.log(`  ${rendered}`);
+}

package/lib/core/repoPath.js

@@ -0,0 +1,11 @@
+// Repo-relative path normaliser for loosening asks. Keep in step with services/auth/lib/repoPath.js and
+// scripts/guards/check-test-loosening.mjs (cli/test/core/repoPath.test.js asserts all three agree).
+// "<anywhere>/quox-dashboard-wt-x/cli/a.test.js" -> "cli/a.test.js"; "./cli/a.test.js" -> "cli/a.test.js".
+export function toRepoRelative(p) {
+  let s = String(p ?? '').trim().replace(/\\/g, '/');
+  s = s.replace(/^(?:.*?\/)?quox-dashboard(?:-wt-[^/]+)?\//, '');
+  s = s.replace(/^(?:\.\/)+/, '').replace(/^\/+/, '');
+  return s;
+}
+
+export const LOOSENING_HINT = 'quox ask loosening --paths <repo-relative test files...> --justify "<why it is safe, plain words>"';