quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/objects/replay.js

@@ -0,0 +1,125 @@
+/**
+ * /replay [run | conversation id] [page]: reconstruct a previous agent run from the audit trail, in order:
+ * the decisions (turn messages), each tool with an args summary, its output and its receipt. Read-only:
+ * nothing is re-executed (sandbox re-execution is not available). Default is the last turn of this
+ * conversation. Sources: the conversation's saved turns, this session's tool calls, and AEE envelopes
+ * (GET /aee/:id, GET /aee/query?corr=). A conversation id replays the messages only: the server does not link
+ * tool envelopes to a conversation, so the view says so and points at /replay <envelope id> for a tool run.
+ */
+import { seg, fit, fitRow, short, dur, boxWidth, parseTs } from './model.js';
+
+export const PAGE = 6;
+
+/** '' | '2' | 'abc' | 'abc 3' | 'abc page 3' | 'page 3' -> { ref, page } */
+export function parseReplayArg(arg) {
+  let t = String(arg || '').trim();
+  let page = 1;
+  const m = /(?:^|\s)(?:page\s+)?(\d{1,4})$/i.exec(t);
+  const pm = /(?:^|\s)page\s+(\d{1,4})$/i.exec(t);
+  if (pm) { page = Number(pm[1]); t = t.slice(0, pm.index).trim(); }
+  else if (m && (m.index > 0 || t === m[1]) && !/^\d{5,}$/.test(t)) { page = Number(m[1]); t = t.slice(0, m.index).trim(); }
+  return { ref: t || null, page: Math.max(1, page) };
+}
+
+const receiptOf = (c) => `${c.envelopeId ? `receipt ${c.envelopeId}` : 'no receipt id'}${c.receipt?.verified && c.receipt.ward_seq != null ? ` · WARD seq ${c.receipt.ward_seq}` : ''}`;
+
+/** { messages: [{ role, content }], calls: [tool blocks] } -> steps: the question, each tool, then the answer. */
+export function buildTurnSteps({ messages = [], calls = [] }) {
+  const steps = [];
+  const users = messages.filter(m => m.role === 'user'), agents = messages.filter(m => m.role !== 'user');
+  for (const m of users) steps.push({ kind: 'user', text: String(m.content ?? '') });
+  for (const c of calls) steps.push({ kind: 'tool', tool: c.tool, args: c.summary || '', status: c.status, out: c.resultSummary || '', ms: c.durationMs, receipt: receiptOf(c), id: c.envelopeId || null });
+  for (const m of agents) steps.push({ kind: 'agent', text: String(m.content ?? '') });
+  return steps;
+}
+
+/** AEE envelopes of one correlation id -> steps in time order. */
+export function buildEnvelopeSteps(envs = []) {
+  const sorted = [...envs].sort((a, b) => (parseTs(a.ts) ?? 0) - (parseTs(b.ts) ?? 0));
+  return sorted.map((e) => {
+    const p = e.payload || {};
+    const intent = String(e.intent || '');
+    if (/^ops\.tool\./.test(intent)) {
+      const ok = p.success !== false && !/\.failed$|\.denied$/.test(intent);
+      return { kind: 'tool', id: e.id, tool: p.tool_name || intent, args: p.input_summary || p.summary || '', status: /\.denied$/.test(intent) ? 'denied' : ok ? 'ok' : 'failed', out: ok ? (p.result_summary || '') : (p.error || intent), ms: p.duration_ms, receipt: `receipt ${e.id}` };
+    }
+    if (intent === 'aocl.policy.evaluated') return { kind: 'policy', id: e.id, text: p.allPassed === false ? 'policy blocked' : 'policy passed', receipt: `receipt ${e.id}` };
+    if (intent === 'aocl.identity.verified') return { kind: 'policy', id: e.id, text: 'identity verified', receipt: `receipt ${e.id}` };
+    return { kind: 'event', id: e.id, text: `${intent || 'envelope'}${e.from ? ` from ${e.from}` : ''}`, receipt: `receipt ${e.id}` };
+  });
+}
+
+const MARK = { ok: ['✔', 'ok'], failed: ['✖', 'error'], denied: ['✖', 'error'] };
+
+/** d: { steps, page, size, title, notes } -> view { box, rows } */
+export function replayView(d, cols) {
+  const w = boxWidth(cols, 96), inner = w - 4, nw = w < 60;
+  const size = d.size || PAGE;
+  const steps = d.steps || [];
+  const pages = Math.max(1, Math.ceil(steps.length / size));
+  const page = Math.min(Math.max(1, d.page || 1), pages);
+  const rows = [];
+  if (!steps.length) rows.push([seg('nothing recorded for this run', 'muted')]);
+  const base = (page - 1) * size;
+  steps.slice(base, base + size).forEach((s, i) => {
+    const n = String(base + i + 1).padStart(2);
+    const label = s.kind === 'user' ? 'you' : s.kind === 'agent' ? 'agent' : s.kind === 'tool' ? 'tool' : s.kind === 'policy' ? 'guard' : 'event';
+    const lrole = s.kind === 'user' ? 'sky' : s.kind === 'agent' ? 'violet' : s.kind === 'tool' ? 'indigo' : 'muted';
+    if (s.kind === 'tool') {
+      const [m, mr] = MARK[s.status] || ['○', 'muted'];
+      rows.push([seg(n + ' ', 'muted'), seg(label.padEnd(6), lrole, true), seg(`${s.tool} `, 'value', true), seg(m, mr), seg(` ${s.status || 'unknown'}${s.ms != null ? ` ${dur(s.ms)}` : ''}`, mr)]);
+      if (s.args) rows.push([seg('     args    ', 'muted'), seg(s.args, 'value')]);
+      if (s.out) rows.push([seg('     output  ', 'muted'), seg(s.out, s.status === 'ok' ? 'value' : 'warn')]);
+      rows.push([seg('     ', 'muted'), seg(s.receipt || 'no receipt id', 'muted')]);
+    } else {
+      rows.push([seg(n + ' ', 'muted'), seg(label.padEnd(6), lrole, true), seg(s.text || '', s.kind === 'event' ? 'muted' : 'value')]);
+      if (s.receipt && s.kind !== 'user' && s.kind !== 'agent') rows.push([seg('     ', 'muted'), seg(s.receipt, 'muted')]);
+    }
+  });
+  for (const n of d.notes || []) rows.push([seg(`note: ${n}`, 'warn')]);
+  rows.push([seg(`page ${page} of ${pages}`, 'value', true), seg(page < pages ? `${nw ? '' : ' · '}${nw ? ' ' : ''}/replay${d.ref ? ` ${short(d.ref, 12)}` : ''} ${page + 1} for the next` : '', 'muted')]);
+  rows.push([seg('read-only: rebuilt from the audit trail, nothing is re-run', 'muted')]);
+  return { box: { width: w, title: `Replay · ${d.title || 'last turn'}`, titleRole: 'violet', border: 'violet' }, rows: rows.map(r => fitRow(r, inner)) };
+}
+
+/** Fetchers for createObjectsApi. deps: { get, listOf, why, verifyReceipt, aeeGet } */
+export function replayFetchers({ get, listOf, why, verifyReceipt, aeeGet }) {
+  const turns = async (id) => listOf(await get('collector', `/api/v1/conversations/${encodeURIComponent(id)}/turns`, { limit: 200 }, 12000), 'turns');
+  const corrList = async (corr) => listOf(await get('collector', '/aee/query', { corr, limit: 100 }, 12000), 'envelopes');
+  return {
+    /** a: { ref, page, conversationId, calls } -> { data } | { error, tone } */
+    async replay(a) {
+      const page = a.page || 1;
+      if (!a.ref) {
+        const calls = await Promise.all((a.calls || []).slice(-12).map(async (c) => {
+          if (!c.envelopeId || (c.receipt?.verified && c.receipt.ward_seq != null)) return c;
+          const r = await verifyReceipt(c.envelopeId, 6);
+          const res = r.ok ? r.result : null;
+          return res?.status === 'WITNESSED' ? { ...c, receipt: { verified: true, ward_seq: res.entry?.seq } } : c;
+        }));
+        let messages = [], notes = [];
+        try {
+          const rows = await turns(a.conversationId);
+          let from = 0;
+          for (let i = rows.length - 1; i >= 0; i--) if (rows[i].role === 'user') { from = i; break; }
+          messages = rows.slice(from).filter(r => r.role === 'user' || r.role === 'assistant');
+        } catch (e) { notes.push(`the saved turn messages could not be read (${why(e)}); showing tool calls only`); }
+        return { data: { steps: buildTurnSteps({ messages, calls }), page, title: 'last turn', notes } };
+      }
+      let rows = null;
+      try { rows = await turns(a.ref); } catch (e) { if (e?.status && e.status !== 404 && e.status !== 400) return { error: `replay: ${why(e)}`, tone: 'warn' }; }
+      if (rows && rows.length) {
+        const steps = rows.filter(r => r.role === 'user' || r.role === 'assistant').map(r => ({ kind: r.role === 'user' ? 'user' : 'agent', text: String(r.content ?? '') }));
+        return { data: { steps, page, ref: a.ref, title: `conversation ${short(a.ref, 12)}`, notes: ['tool calls are not linked to a conversation id on the server: /replay <envelope id> replays a tool run'] } };
+      }
+      let corr = a.ref, seen = null;
+      const env = await aeeGet(a.ref);
+      if (env.ok && env.env) { seen = env.env; corr = env.env.corr || a.ref; }
+      let list = [];
+      try { list = await corrList(corr); } catch (e) { return { error: `replay: ${why(e)}`, tone: 'warn' }; }
+      if (seen && !list.some(e => e.id === seen.id)) list = [...list, seen];
+      if (!list.length) return { error: `No run, conversation or envelope called "${a.ref}".`, tone: 'warn' };
+      return { data: { steps: buildEnvelopeSteps(list), page, ref: a.ref, title: `run ${short(corr, 14)}`, notes: [] } };
+    }
+  };
+}

package/lib/quoxon/objects/sitrep.js

@@ -0,0 +1,58 @@
+/**
+ * /sitrep: the situation NOW, from persisted data only (no model call): approvals waiting (auth inbox),
+ * what needs you (LUCID needs_you, by urgency), running work (LUCID in_motion), and what Quox cannot see
+ * (LUCID silent / failing / unconnected feeds, plus any source this card could not read). /away is the
+ * "since you were last here" digest; this is the present tense.
+ */
+import { seg, fit, plural, boxWidth, parseTs, ago } from './model.js';
+
+const URG = { now: 0, today: 1, 'this week': 2, whenever: 3, fyi: 4 };
+const hrs = (ms) => { const m = Math.round((ms || 0) / 60000); return m < 60 ? `${m}m` : m < 2880 ? `${Math.round(m / 60)}h` : `${Math.round(m / 1440)}d`; };
+
+/** sit/appr: { ok, v | error } parts. -> { approvals: [..]|null, needs, running, blind } */
+export function sitrepData(sit, appr, now = Date.now()) {
+  const blind = [];
+  let needs = [], running = [];
+  if (sit?.ok) {
+    const s = sit.v?.situation || sit.v || {};
+    needs = (s.needs_you || []).filter(n => n.kind !== 'approval')
+      .map(n => ({ title: n.L0 || n.ref, urgency: n.urgency, ts: n.L1?.when?.since ?? n.status_since ?? null, ref: n.ref }))
+      .sort((a, b) => (URG[a.urgency] ?? 5) - (URG[b.urgency] ?? 5) || (parseTs(b.ts) ?? 0) - (parseTs(a.ts) ?? 0));
+    running = (s.in_motion || []).map(m => ({ title: m.L0 || m.ref, ref: m.ref }));
+    const cs = s.cannot_see || {};
+    for (const x of cs.silent || []) blind.push({ source: `lucid:${x.feed}`, reason: `silent ${hrs(x.silent_ms)}` });
+    for (const x of cs.failing || []) blind.push({ source: `lucid:${x.feed}`, reason: `failing: ${x.error}` });
+    for (const n of cs.unwired || []) blind.push({ source: `lucid:${n}`, reason: 'not connected' });
+  } else blind.push({ source: 'lucid', reason: sit?.error || 'not read' });
+  let approvals = null;
+  if (appr?.ok) approvals = (appr.v || []).map(a => ({ title: a.title || a.summary || a.id, ts: a.created_at, ref: a.id }));
+  else blind.push({ source: 'approvals', reason: appr?.error || 'not read' });
+  return { approvals, needs, running, blind, now };
+}
+
+/** d: sitrepData(...) + now */
+export function sitrepCard(d, cols, { maxNeeds = 5, maxRunning = 3, maxApprovals = 3 } = {}) {
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 96), inner = w - 4;
+  const rows = [];
+  const ap = d.approvals || [], needs = d.needs || [], run = d.running || [];
+  const line = (g, role, title, meta) => {
+    const m = meta ? `  ${meta}` : '';
+    return [seg(g, role), seg(fit(title, Math.max(8, inner - 2 - m.length)), 'value'), seg(m, 'muted')];
+  };
+  for (const a of ap.slice(0, maxApprovals)) rows.push(line('⚠ ', 'warn', `Approval: ${a.title}`, a.ts ? `waiting ${ago(a.ts, now)}` : ''));
+  if (ap.length > maxApprovals) rows.push([seg(`+${ap.length - maxApprovals} more approvals · /approvals`, 'muted')]);
+  for (const n of needs.slice(0, maxNeeds)) rows.push(line(n.urgency === 'now' ? '⚠ ' : '◐ ', n.urgency === 'now' ? 'warn' : 'muted', n.title, n.urgency || ''));
+  if (needs.length > maxNeeds) rows.push([seg(`+${needs.length - maxNeeds} more · quox lucid`, 'muted')]);
+  if (!ap.length && !needs.length) rows.push([seg('Nothing needs you right now.', 'muted')]);
+  if (run.length) {
+    rows.push([seg(' ')]);
+    for (const r of run.slice(0, maxRunning)) rows.push(line('◐ ', 'indigo', r.title, ''));
+    if (run.length > maxRunning) rows.push([seg(`+${run.length - maxRunning} more running · /roster all`, 'muted')]);
+  }
+  if ((d.blind || []).length) rows.push([seg(fit(`Can't see: ${d.blind.map(b => (b.reason ? `${b.source} (${b.reason})` : b.source)).join(', ')}`, inner), 'faint')]);
+  const right = w < 60
+    ? [d.approvals ? `${ap.length} ap` : null, `${needs.length} need`, `${run.length} run`].filter(Boolean).join(' · ')
+    : [d.approvals ? plural(ap.length, 'approval') : null, `${needs.length} need you`, `${run.length} running`].filter(Boolean).join(' · ');
+  return { box: { width: w, title: 'Situation now', titleRole: 'value', right, rightRole: 'muted', border: ap.length || needs.some(n => n.urgency === 'now') ? 'warn' : 'muted' }, rows };
+}

package/lib/quoxon/objects/skill.js

@@ -0,0 +1,105 @@
+/**
+ * E1 skill card from a real QSKL skill record (GET /quoxflow/skills/:id) plus, when reachable, its
+ * quoxflow scoreboard row (GET /api/quox-skills/scoreboards). Tests: the record carries test
+ * DEFINITIONS in `tests`; results exist only once run-tests has written `evals.tests`
+ * ({ total, passed, failed, last_run_at, results }). Never shows a pass that was not recorded.
+ */
+import { seg, fit, ago, day, plural, short, boxWidth } from './model.js';
+
+const EDITION_ROLE = { stable: 'ok', experimental: 'warn', archived: 'muted' };
+
+/** -> { word, role } for the review state the record actually states. */
+export function reviewState(s) {
+  if (s?.reviewNeeded) return { word: 'review needed', role: 'warn' };
+  const e = String(s?.edition || s?.status || '').toLowerCase();
+  return e ? { word: e, role: EDITION_ROLE[e] || 'muted' } : { word: 'state unknown', role: 'muted' };
+}
+
+/** -> { dots:[{ch,role}], text, role } or null when the skill has no tests at all. */
+export function testsSummary(s, now) {
+  const run = s?.evals?.tests;
+  if (run && Number.isFinite(Number(run.total))) {
+    const total = Number(run.total), passed = Number(run.passed) || 0, failed = Number(run.failed) || 0;
+    const res = Array.isArray(run.results) ? run.results : null;
+    const dots = res && res.length === total
+      ? res.map(r => ({ ch: '●', role: r.passed === true || r.status === 'passed' || r.ok === true ? 'ok' : 'error' }))
+      : [...Array(passed).fill({ ch: '●', role: 'ok' }), ...Array(Math.max(0, total - passed)).fill({ ch: '●', role: 'error' })];
+    const when = run.last_run_at ? ` · ${ago(run.last_run_at, now)} ago` : '';
+    if (passed === total && total > 0) return { dots, text: `${passed}/${total} pass${when}`, role: 'ok' };
+    return { dots, text: `${passed}/${total} pass · ${failed || total - passed} failing${when}`, role: 'error' };
+  }
+  const defined = s?.tests && typeof s.tests === 'object' ? Object.keys(s.tests).length : 0;
+  if (!defined) return null;
+  return { dots: Array(defined).fill({ ch: '○', role: 'muted' }), text: `${defined} defined · never run`, role: 'muted' };
+}
+
+const sourceOf = (s) => {
+  const parts = [];
+  if (s.category) parts.push(s.category);
+  if (s.createdAt) parts.push(`created ${day(s.createdAt)}`);
+  const tag = (s.tags || []).find(t => /^source:/.test(t));
+  if (tag) parts.push(`from ${tag.split(':')[1] === 'notesq' ? 'NotesQ' : tag.split(':')[1]}`);
+  if (s.authoringEnvelopeId) parts.push(`authored in ${short(s.authoringEnvelopeId, 12)}`);
+  if (s.lastPatchedBy) parts.push('patched since');
+  return parts.join(' · ');
+};
+
+/**
+ * d: { skill, scoreboard: { ok, row } | null, agentName?: (id) => string, now }
+ * -> view { box, rows }
+ */
+export function skillCard(d, cols) {
+  const s = d.skill || {};
+  const now = d.now ?? Date.now();
+  const w = boxWidth(cols, 72), inner = w - 4, nw = w < 50;
+  const rv = reviewState(s);
+  const name = s.name || s.id;
+  const right = s.version ? (nw ? `v${s.version}` : `v${s.version} · ${rv.word}`) : rv.word;
+  const rows = [];
+  if (s.description) rows.push([seg(fit(s.description, inner))]);
+  if (nw) rows.push([seg(rv.word, rv.role)]);
+
+  const agentName = d.agentName || ((id) => id);
+  const agents = (s.bestForAgents || []).map(id => String(agentName(id) || id));
+  const t = testsSummary(s, now);
+  const testRow = [];
+  if (t) {
+    testRow.push(seg('tests ', 'muted'));
+    for (const dt of t.dots.slice(0, 8)) testRow.push(seg(dt.ch, dt.role));
+    testRow.push(seg(` ${t.text}`, t.role));
+  } else testRow.push(seg('tests ', 'muted'), seg('none defined', 'muted'));
+  if (!nw && agents.length) {
+    testRow.push(seg('   agents ', 'muted'));
+    agents.slice(0, 3).forEach((a, i) => { if (i) testRow.push(seg(' ')); testRow.push(seg(a.toUpperCase(), `agent:${a}`)); });
+    if (agents.length > 3) testRow.push(seg(` +${agents.length - 3}`, 'muted'));
+  }
+  rows.push(testRow);
+  if (nw && agents.length) rows.push([seg('agents ', 'muted'), seg(agents.slice(0, 3).map(a => a.toUpperCase()).join(', '), `agent:${agents[0]}`)]);
+
+  const src = sourceOf(s);
+  if (src) rows.push([seg(fit(src, inner), 'muted')]);
+
+  const use = [];
+  const sb = d.scoreboard;
+  if (sb?.ok) {
+    const r = sb.row;
+    const n30 = Number(r?.total_invocations_30d) || 0;
+    if (!r || !n30) use.push(r?.last_used_at ? `no runs in 30d · last ${ago(r.last_used_at, now)} ago` : 'no recorded runs');
+    else {
+      use.push(`used ${plural(n30, 'time')} in 30d`);
+      if (r.last_used_at) use.push(`last ${ago(r.last_used_at, now)} ago`);
+      if (r.success_rate_30d != null) use.push(`${Math.round(Number(r.success_rate_30d) * 100)}% ok`);
+    }
+  }
+  const judge = s.evals?.judge;
+  if (judge && judge.avg_score != null) use.push(`judge ${judge.avg_score}/5${judge.scored_at ? ` (${day(judge.scored_at)})` : ''}`);
+  if (use.length) rows.push([seg(fit(use.join(' · '), inner), 'muted')]);
+
+  if (!nw && Array.isArray(s.policySatisfies) && s.policySatisfies.length) rows.push([seg(fit(`satisfies ${s.policySatisfies.join(', ')}`, inner), 'muted')]);
+
+  // Next possibility: only a capability that exists today. /skill runs a skill through a governed turn.
+  if (String(s.edition).toLowerCase() !== 'archived') rows.push([seg('next ', 'muted'), seg(`/skill ${name}`, 'key'), seg(nw ? ' runs it' : ' [args] runs it (governed turn)', 'muted')]);
+  else rows.push([seg('archived: kept for the record, not offered to agents', 'muted')]);
+
+  return { box: { width: w, title: `Skill · ${name}`, right, rightRole: rv.role, border: 'sky' }, rows };
+}

package/lib/quoxon/objects/view.js

@@ -0,0 +1,87 @@
+/**
+ * <ObjectView/>: the one Ink component for the inline object views. It maps a pure view (rows of
+ * { text, role } segments, optional box) to <Text> runs. `t` is seconds since arrival for the lab's
+ * decode-in (rows start 0.1 s apart); the default Infinity is the settled card, which is what history
+ * shows while there is no shared motion clock on main. Quiet (NO_COLOR or reduced motion) is always
+ * settled; NO_COLOR also drops every colour (c() returns undefined).
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { c, agentColor, mono } from '../theme.js';
+import { reducedMotion } from '../motion/clock.js';
+import { buildObject } from './index.js';
+import { decodeRow, padRow, fit, len } from './model.js';
+
+const h = React.createElement;
+
+/** Role -> Ink colour. agent:<name> uses the stable agent shade. */
+export function roleColor(role) {
+  if (mono()) return undefined;
+  if (typeof role === 'string' && role.startsWith('agent:')) return agentColor(role.slice(6));
+  return c(role || 'value');
+}
+
+function runsOf(cells, key) {
+  const out = [];
+  let run = '', role, bold = false, glyph = false, k = 0;
+  const flush = () => { if (run) out.push(h(Text, { key: `${key}-${k++}`, color: glyph ? roleColor('faint') : roleColor(role), bold }, run)); run = ''; };
+  for (const cl of cells) {
+    if (cl.role !== role || cl.bold !== bold || cl.glyph !== glyph) { flush(); role = cl.role; bold = cl.bold; glyph = cl.glyph; }
+    run += cl.ch;
+  }
+  flush();
+  return out;
+}
+
+/** Rows start this far apart (at most 0.1 s, the lab) so the last one lands inside the 0.65 s reveal window. */
+export const STAGGER_SPAN = 0.3;
+export const rowStart = (i, n) => i * Math.min(0.1, STAGGER_SPAN / Math.max(1, n - 1));
+const rowNode = (row, i, n, t, key) => h(Text, { key, wrap: 'truncate' }, ...runsOf(decodeRow(row, t, rowStart(i, n), 0.25, 70 + i), key));
+
+export function ObjectView({ item, cols, fx = null, t = fx && fx.e != null ? fx.e : Infinity, now }) {
+  const view = buildObject(item.obj || item, cols, now);
+  const tt = reducedMotion() ? Infinity : t;
+  const rows = view.rows || [];
+  if (!view.box) {
+    return h(Box, { flexDirection: 'column', marginTop: 1, paddingLeft: 2 }, ...rows.map((r, i) => rowNode(r, i, rows.length, tt, `r${i}`)));
+  }
+  const b = view.box, w = b.width, inner = w - 4;
+  const bc = roleColor(b.border || 'muted');
+  const right = b.right ? ` ${b.right} ` : '';
+  const title = b.title ? ` ${fit(b.title, Math.max(4, w - 6 - (right ? len(right) + 1 : 0)))} ` : '';
+  const fill = Math.max(0, w - 3 - len(title) - len(right) - 1);
+  const top = h(Text, { key: 'top', wrap: 'truncate' },
+    h(Text, { color: bc }, '╭─'),
+    h(Text, { color: roleColor(b.titleRole || 'value'), bold: true }, title),
+    h(Text, { color: bc }, '─'.repeat(fill)),
+    h(Text, { color: roleColor(b.rightRole || 'muted') }, right),
+    h(Text, { color: bc }, '─╮'));
+  const body = rows.map((r, i) => h(Text, { key: `b${i}`, wrap: 'truncate' },
+    h(Text, { color: bc }, '│ '), ...runsOf(decodeRow(padRow(r, inner), tt, rowStart(i, rows.length), 0.25, 70 + i), `b${i}`), h(Text, { color: bc }, ' │')));
+  const bottom = h(Text, { key: 'bot', color: bc }, '╰' + '─'.repeat(w - 2) + '╯');
+  return h(Box, { flexDirection: 'column', marginTop: 1, paddingLeft: 1 }, top, ...body, bottom);
+}
+
+/**
+ * TUI-UX #5: would this card (rows + border + margin) be taller than the terminal? Ink cannot erase rows that already scrolled
+ * off the top of a live region, so a decode-in on such a card leaves a half-decoded copy in scrollback. Callers skip the
+ * animation for it and commit it settled.
+ */
+export function cardTallerThanScreen(item, cols, termRows, now) {
+  if (!Number.isFinite(termRows) || termRows <= 0) return false;
+  const view = buildObject(item.obj || item, cols, now);
+  return (view.rows || []).length + (view.box ? 3 : 1) + 2 >= termRows; // top + bottom border, marginTop, plus the composer line
+}
+
+/** Plain text of a view at a width (tests, transcripts, --print): the box drawn with the same geometry. */
+export function objectText(item, cols, now) {
+  const view = buildObject(item.obj || item, cols, now);
+  const rt = (r) => r.map(s => s.text).join('');
+  if (!view.box) return view.rows.map(r => '  ' + rt(fitRowText(r, cols - 2))).join('\n');
+  const b = view.box, w = b.width, inner = w - 4;
+  const right = b.right ? ` ${b.right} ` : '';
+  const title = b.title ? ` ${fit(b.title, Math.max(4, w - 6 - (right ? len(right) + 1 : 0)))} ` : '';
+  const fill = Math.max(0, w - 3 - len(title) - len(right) - 1);
+  return [` ╭─${title}${'─'.repeat(fill)}${right}─╮`, ...view.rows.map(r => ` │ ${rt(padRow(r, inner))} │`), ` ╰${'─'.repeat(w - 2)}╯`].join('\n');
+}
+const fitRowText = (r, n) => padRow(r, n).filter((s, i, a) => !(i === a.length - 1 && /^ +$/.test(s.text)));

package/lib/quoxon/objects/workflow.js

@@ -0,0 +1,119 @@
+/**
+ * E2 workflow step flow from ONE real execution: the step list comes from the workflow definition
+ * (GET /api/workflows/:id on quoxflow) in edge order, and each step's state and timing from that
+ * execution's AEE envelopes (GET /api/executions/:id/envelopes: quox.flow.node.started | completed |
+ * failed | skipped, keyed by payload.nodeId). Only the running step moves; a human gate
+ * (approval:gate, human:task) that is reached shows amber. A step with no envelope is shown as
+ * not reached, and when no envelopes could be read every state is '?', never guessed.
+ */
+import { seg, fit, dur, hhmm, short, parseTs } from './model.js';
+
+export const isGateType = (type) => /^(approval|human|hitl)[:_-]|(^|:)(approval|hitl|human)(gate|task)?$/i.test(String(type || ''));
+
+/** Definition nodes in execution order (Kahn over edges; definition order breaks ties). */
+export function orderNodes(def) {
+  const nodes = Array.isArray(def?.nodes) ? def.nodes : [];
+  const edges = Array.isArray(def?.edges) ? def.edges : [];
+  const ids = nodes.map(n => n.id);
+  const indeg = new Map(ids.map(id => [id, 0]));
+  for (const e of edges) if (indeg.has(e.target) && indeg.has(e.source)) indeg.set(e.target, indeg.get(e.target) + 1);
+  const out = [], seen = new Set();
+  const queue = ids.filter(id => indeg.get(id) === 0);
+  while (queue.length) {
+    const id = queue.shift();
+    if (seen.has(id)) continue;
+    seen.add(id); out.push(id);
+    for (const e of edges) if (e.source === id && indeg.has(e.target)) { indeg.set(e.target, indeg.get(e.target) - 1); if (indeg.get(e.target) === 0) queue.push(e.target); }
+  }
+  for (const id of ids) if (!seen.has(id)) out.push(id); // a cycle or dangling edge: keep definition order
+  const byId = new Map(nodes.map(n => [n.id, n]));
+  return out.map(id => byId.get(id));
+}
+
+/** nodeId -> { started, completed, failed, skipped, payload, nodeName, nodeType } from envelopes. */
+export function nodeStates(envelopes) {
+  const st = new Map();
+  for (const e of envelopes || []) {
+    const p = e?.payload || {};
+    const id = p.nodeId;
+    if (!id || !/^quox\.flow\.node\./.test(String(e.intent || ''))) continue;
+    const s = st.get(id) || { id };
+    const ts = parseTs(e.ts);
+    const kind = String(e.intent).slice('quox.flow.node.'.length);
+    if (kind === 'started') { if (s.started == null || ts < s.started) s.started = ts; s.nodeName ??= p.nodeName; s.nodeType ??= p.nodeType; }
+    else if (kind === 'completed') { s.completed = ts; s.result = p; }
+    else if (kind === 'failed') { s.failed = ts; s.error = p.error || p.message || null; }
+    else if (kind === 'skipped') s.skipped = ts;
+    st.set(id, s);
+  }
+  return st;
+}
+
+const triggerDetail = (n) => {
+  const c = n?.config || {};
+  return c.label || c.expression || c.event || c.path || '';
+};
+
+/**
+ * d: { execution, envelopes: [] | null, def: { nodes, edges } | null, now }
+ * -> view { rows } (no box: the lab draws this as an indented flow)
+ */
+export function stepFlow(d, cols) {
+  const ex = d.execution || {};
+  const now = d.now ?? Date.now();
+  const nw = cols < 60;
+  const rows = [];
+  const status = String(ex.status || 'unknown');
+  const head = [seg(ex.workflowName || ex.workflowId || 'workflow', 'value', true), seg('  ')];
+  const meta = [`run ${short(ex.id, 10)}`, status];
+  if (!nw && ex.startedAt) meta.push(`started ${hhmm(ex.startedAt)}`);
+  head.push(seg(meta.join(' · '), status === 'failed' ? 'error' : 'muted'));
+  rows.push(head);
+
+  const states = d.envelopes ? nodeStates(d.envelopes) : null;
+  let nodes = d.def ? orderNodes(d.def) : [];
+  if (!nodes.length && states) nodes = [...states.values()].filter(s => !/_replay_\d+$/.test(s.id)).map(s => ({ id: s.id, name: s.nodeName, type: s.nodeType }));
+  if (!nodes.length) {
+    rows.push([seg(d.envelopes ? 'No step records for this run.' : 'Steps could not be read for this run (no definition or envelopes).', 'muted')]);
+    return { rows };
+  }
+  const running = status === 'running' || status === 'paused';
+  const nameW = Math.min(Math.max(12, Math.floor((cols - 8) * 0.45)), Math.max(8, ...nodes.map(n => [...String(n.name || n.id)].length)));
+  for (const n of nodes) {
+    const s = states?.get(n.id);
+    const type = n.type || s?.nodeType || '';
+    const gate = isGateType(type);
+    let mark = '?', mrole = 'muted', nrole = 'value', det = '', drole = 'muted', bold = false;
+    if (!states) { det = 'state not readable'; }
+    else if (/^trigger/.test(type)) { mark = '●'; mrole = 'sky'; det = triggerDetail(n); }
+    else if (s?.failed != null) { mark = '✖'; mrole = 'error'; det = fit(s.error ? `failed: ${s.error}` : 'failed', 60); drole = 'error'; }
+    else if (s?.completed != null) {
+      mark = '✓'; mrole = 'ok';
+      const r = s.result || {};
+      const bits = [];
+      if (r.actions_taken != null) bits.push(`${r.actions_taken} action${r.actions_taken === 1 ? '' : 's'}`);
+      if (s.started != null) bits.push(dur(s.completed - s.started));
+      det = bits.join(' · ');
+    } else if (s?.skipped != null) { mark = '○'; mrole = 'faint'; nrole = 'muted'; det = 'skipped'; }
+    else if (s?.started != null && running) {
+      if (gate) { mark = '◐'; mrole = 'warn'; det = 'waiting for approval'; drole = 'warn'; }
+      else { mark = '◐'; mrole = 'sky'; bold = true; det = `running · ${dur(now - s.started)}`; }
+    } else if (s?.started != null) { mark = '?'; det = `started, no end recorded (run ${status})`; drole = 'warn'; }
+    else { mark = '○'; mrole = 'faint'; nrole = 'muted'; if (gate && running) { det = 'human gate'; drole = 'warn'; } }
+    rows.push([seg(' │', 'faint')]);
+    const nm = fit(n.name || n.id, nameW);
+    const row = [seg(' '), seg(mark, mrole, bold), seg(' '), seg(nm, nrole, bold)];
+    if (det) {
+      const pad = nw ? '  ' : ' '.repeat(Math.max(2, nameW + 2 - [...nm].length));
+      row.push(seg(pad), seg(fit(det, Math.max(6, cols - 6 - (nw ? [...nm].length + 2 : nameW + 2))), drole));
+    }
+    rows.push(row);
+  }
+  if (!running && (ex.duration != null || ex.completedAt)) {
+    const total = ex.duration != null ? dur(ex.duration) : dur(parseTs(ex.completedAt) - parseTs(ex.startedAt));
+    rows.push([seg(' ')]);
+    if (status === 'failed') rows.push([seg('✖ ', 'error'), seg(fit(`failed${total ? ` after ${total}` : ''}${ex.error ? `: ${typeof ex.error === 'string' ? ex.error : ex.error.message || ''}` : ''}`, cols - 6), 'error')]);
+    else rows.push([seg(status === 'completed' ? '✔ ' : '· ', status === 'completed' ? 'ok' : 'muted'), seg(`${status}${total ? ` in ${total}` : ''}${ex.envelopeCount != null ? ` · ${ex.envelopeCount} envelopes` : ''}`, 'muted')]);
+  }
+  return { rows };
+}

package/lib/quoxon/observers.js

@@ -0,0 +1,42 @@
+/**
+ * /observers: facts from persisted data only (LUCID situation, LUCID changes, lessons taught,
+ * reflect / learn / insight counters). No model-generated text: every line is a stored field
+ * or a count of them. Pure: takes api.observers() output, returns [[text, tone]].
+ */
+import { clip } from './theme.js';
+
+const why = (p) => (p.unavailable ? 'no endpoint on this server' : `unreadable (${p.error})`);
+
+export function observerLines(o, cols = 80) {
+  const out = [];
+  const add = (t, tone) => out.push([clip(t, cols - 4), tone]);
+  const sit = o.situation;
+  if (!sit?.ok) add(`◉ LUCID situation: ${why(sit || { error: 'no answer' })}`, 'warn');
+  else {
+    const s = sit.v?.situation || {};
+    add(`◉ LUCID: ${s.L0 || 'no summary recorded'}`);
+    const needs = s.needs_you || [];
+    needs.slice(0, 3).forEach(n => add(`  needs you: ${n.L0 || n.ref}`, 'warn'));
+    if (needs.length > 3) add(`  +${needs.length - 3} more needing you (quox lucid)`);
+    const cs = s.cannot_see || {};
+    const blind = [...(cs.unwired || []).map(x => `${x} not wired`), ...(cs.silent || []).map(x => `${x.feed} silent`), ...(cs.failing || []).map(x => `${x.feed || x} failing`)];
+    if (cs.coverage) add(`  sees ${cs.coverage.live} of ${cs.coverage.expected} sources${blind.length ? `; ${blind.join(', ')}` : ''}`);
+    const total = s.changed_total ?? (s.changed || []).length;
+    const range = s.cursor ? ` (journal ${s.cursor.from} to ${s.cursor.to})` : '';
+    add(`◉ Changed since you last looked: ${total}${range}`);
+    (s.changed || []).slice(0, 5).forEach(c => add(`  ${c.L0 || c.ref}${c.from && c.to ? ` (${c.from} to ${c.to})` : ''}`));
+    if (total > 5) add(`  +${total - 5} more (quox lucid since-last)`);
+  }
+  out.push(['', undefined]);
+  add('Self-learning records');
+  const les = o.lessons;
+  add(les?.ok ? `  LUCID lessons taught: ${(les.v?.lessons || []).length}` : `  LUCID lessons: ${why(les || { error: 'no answer' })}`);
+  for (const p of o.learning || []) {
+    if (!p.ok) { add(`  ${p.label || 'stat'}: ${why(p)}`); continue; }
+    const f = p.v.fields || {};
+    const last = f.lastOutcomeAt || f.lastObservationAt || f.lastSignalAt || f.lastClusterAt;
+    add(`  ${p.v.label}: ${p.v.text || 'no data'}${last ? ` · last ${last}` : ''}`);
+  }
+  add('  Memory consolidation: no read API found, not shown.');
+  return out;
+}