dexterm-cli 0.1.2 → 0.1.3

package/dist/packages/packs/src/skill-care.js

@@ -0,0 +1,206 @@
+// Skill care (task-1414): the pure decision logic behind the recurring skill backtest that research/skill-care/
+// run.mjs schedules. It never ships anything — it decides whether the newly labelled recorder history is enough,
+// and improves the shipped skills enough, to be worth PROPOSING a tuning (a Kanban card + a parameter diff), or
+// whether to record "no change" and stay silent. Pure over the eval sets + metrics it is given, so the gate is
+// unit-testable with fixtures.
+//
+// Two eval slices matter:
+//   - ROLLING: the full current eval set, re-split so the NEWEST `windowDays` of coins are a held-out TEST
+//     window (never used to tune; the tuning functions already refuse test rows). Rates drift with the market,
+//     so a fresh tune has to beat the shipped rules HERE, beyond Wilson-interval noise.
+//   - FROZEN CANARY: the committed task-1401 eval set and its published numbers. A proposed tuning must also
+//     hold on the frozen canary (an overfitting guard); and if the SHIPPED rules stop reproducing the frozen
+//     numbers (code/data drift), that itself is worth a proposal.
+import { gradeLinks } from '../../data/src/index.js';
+import {} from "./larp-eval.js";
+import { gradeRugRules, splitMetrics, LARP_GRADE_CLAIMS, LARP_GRADE_ORDER, RUG_GRADE_CLAIMS, RUG_GRADE_ORDER, } from "./skill-backtest.js";
+export const SKILL_CARE_SCHEMA = 'dexterm/packs/skill-care/1';
+/** Minimum newly labelled coins since the last accepted tuning before an improvement may be proposed. */
+export const DEFAULT_MIN_NEW_COINS = 150;
+/** Tolerance (absolute MCC) for calling the frozen canary "regressed" or "held". */
+export const DEFAULT_CANARY_NOISE = 0.05;
+/**
+ * Re-split an eval set so the NEWEST coins are a held-out TEST window the tuning never sees. By default (and
+ * whenever `windowDays` is not given) the newest `testFrac` of coins by t0 are TEST (count-based, so TRAIN stays
+ * the majority even when t0 is clustered); with `windowDays` it is a time window instead. Returns a new set
+ * (rows cloned with updated `split`); the original is untouched.
+ */
+export function rollingSplit(set, opts = {}) {
+    let cutoff;
+    let rule;
+    if (opts.windowDays !== undefined) {
+        const anchor = opts.anchor ?? set.rows.reduce((m, r) => Math.max(m, r.t0), 0);
+        cutoff = anchor - opts.windowDays * 86_400_000;
+        rule = `rolling window: coins with t0 in the newest ${opts.windowDays} day(s) (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST window; never tuned on`;
+    }
+    else {
+        const frac = opts.testFrac ?? 0.3;
+        const sorted = [...set.rows].sort((a, b) => a.t0 - b.t0);
+        const idx = Math.min(sorted.length, Math.floor(sorted.length * (1 - frac)));
+        cutoff = sorted[idx]?.t0 ?? Number.MAX_SAFE_INTEGER;
+        rule = `rolling window: the newest ${Math.round(frac * 100)}% of coins by t0 (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST window; never tuned on`;
+    }
+    const rows = set.rows.map((r) => ({ ...r, split: r.t0 >= cutoff ? 'test' : 'train' }));
+    const train = rows.filter((r) => r.split === 'train');
+    const test = rows.filter((r) => r.split === 'test');
+    return {
+        ...set,
+        split_rule: rule,
+        cutoff_t0: cutoff,
+        counts: { ...set.counts, rows: rows.length, train: train.length, test: test.length, bad_train: train.filter((r) => r.bad).length, bad_test: test.filter((r) => r.bad).length },
+        rows,
+    };
+}
+// ---------------------------------------------------------------- new coins since the last tuning
+/** Coins in `current` whose mint is not in `baselineMints` — the newly labelled coins since that baseline. */
+export function newCoinsSince(current, baselineMints) {
+    const newMints = current.rows.filter((r) => !baselineMints.has(r.mint)).map((r) => r.mint);
+    return { newMints, count: newMints.length };
+}
+// ---------------------------------------------------------------- metrics helpers (one split, one subject)
+/** Binary warning→bad metrics for the link rubric on one set of rows. */
+export function larpSplit(rows, rubric) {
+    return splitMetrics(rows.map((r) => ({ grade: gradeLinks(r.link, rubric).grade, bad: r.bad })), LARP_GRADE_CLAIMS, LARP_GRADE_ORDER);
+}
+/** Binary warning→bad metrics for the rug rules on one set of rows. */
+export function rugSplit(rows, rules) {
+    return splitMetrics(rows.map((r) => ({ grade: gradeRugRules(r.rug, rules).grade, bad: r.bad })), RUG_GRADE_CLAIMS, RUG_GRADE_ORDER);
+}
+/** The MCC of "warning grade → bad" on the TEST rows of `set` for each subject (null below the metric's floor). */
+export function canaryMcc(set, params) {
+    const test = set.rows.filter((r) => r.split === 'test');
+    return { larpMcc: larpSplit(test, params.larp).binary.mcc, rugMcc: rugSplit(test, params.rug).binary.mcc };
+}
+/**
+ * Does `after` beat `before` on a held-out split BEYOND interval noise? The test is on the binary warning→bad
+ * classifier: the after precision's Wilson lower bound must clear the before precision's upper bound (a gain
+ * that the intervals do not overlap on), with no interval-exceeding recall loss and a positive MCC delta. When
+ * a precision interval is unavailable (too few flagged rows) the answer is a conservative "no".
+ */
+export function intervalImproves(before, after) {
+    const bp = before.binary.precision, ap = after.binary.precision;
+    const br = before.binary.recall, ar = after.binary.recall;
+    const mccDelta = after.binary.mcc !== null && before.binary.mcc !== null ? after.binary.mcc - before.binary.mcc : null;
+    if (!ap || !bp)
+        return { improves: false, mccDelta, reason: 'precision interval unavailable (too few flagged rows on the held-out window)' };
+    const precisionBeatsNoise = ap.lo > bp.hi;
+    const recallHolds = !ar || !br ? true : ar.hi >= br.lo; // no noise-exceeding recall drop
+    const mccUp = mccDelta !== null && mccDelta > 0;
+    const improves = precisionBeatsNoise && recallHolds && mccUp;
+    const reason = improves
+        ? `precision ${(ap.value * 100).toFixed(0)}% [${(ap.lo * 100).toFixed(0)}-${(ap.hi * 100).toFixed(0)}] clears before ${(bp.value * 100).toFixed(0)}% [${(bp.lo * 100).toFixed(0)}-${(bp.hi * 100).toFixed(0)}], ΔMCC ${mccDelta.toFixed(3)}`
+        : !precisionBeatsNoise ? `precision gain within noise (after [${(ap.lo * 100).toFixed(0)}-${(ap.hi * 100).toFixed(0)}] overlaps before [${(bp.lo * 100).toFixed(0)}-${(bp.hi * 100).toFixed(0)}])`
+            : !recallHolds ? 'recall dropped beyond interval noise' : `ΔMCC ${mccDelta === null ? '—' : mccDelta.toFixed(3)} not positive`;
+    return { improves, mccDelta, reason };
+}
+function rubricChanged(a, b) {
+    return a.threshold !== b.threshold || JSON.stringify(a.weights) !== JSON.stringify(b.weights);
+}
+function rugChanged(a, b) {
+    return a.dev_pct_over !== b.dev_pct_over || a.organic_below !== b.organic_below || a.top10_over !== b.top10_over || a.liq_below !== b.liq_below;
+}
+/** MCC `a` has not regressed below `b` by more than `noise` (nulls treated as not-worse). */
+function holds(a, b, noise) {
+    if (a === null || b === null)
+        return true;
+    return a >= b - noise;
+}
+function regressed(a, b, noise) {
+    return a !== null && b !== null && a < b - noise;
+}
+/**
+ * Decide. Priority: a frozen-canary REGRESSION of the shipped rules (the published numbers no longer reproduce)
+ * is always worth a proposal, even with few new coins. Otherwise an IMPROVEMENT needs all of: at least N new
+ * coins, at least one subject beating the held-out window beyond noise (`intervalImproves`), and the proposed
+ * params holding on the frozen canary. Anything else is 'none' (record it, stay silent).
+ */
+export function proposalGate(input) {
+    const N = input.N ?? DEFAULT_MIN_NEW_COINS;
+    const noise = input.canaryNoise ?? DEFAULT_CANARY_NOISE;
+    const reasons = [];
+    const parameterDrift = { larp: rubricChanged(input.proposed.larp, input.shipped.larp), rug: rugChanged(input.proposed.rug, input.shipped.rug) };
+    // (0) Canary regression of the SHIPPED rules — a canary, not an improvement.
+    const larpReg = regressed(input.canaryShipped.larpMcc, input.canaryBaseline.larpMcc, noise);
+    const rugReg = regressed(input.canaryShipped.rugMcc, input.canaryBaseline.rugMcc, noise);
+    if (larpReg || rugReg) {
+        if (larpReg)
+            reasons.push(`frozen canary regressed: shipped larp MCC ${fmt(input.canaryShipped.larpMcc)} < baseline ${fmt(input.canaryBaseline.larpMcc)} − ${noise}`);
+        if (rugReg)
+            reasons.push(`frozen canary regressed: shipped rug MCC ${fmt(input.canaryShipped.rugMcc)} < baseline ${fmt(input.canaryBaseline.rugMcc)} − ${noise}`);
+        return { propose: true, kind: 'canary-regression', reasons, improved: [], canaryHolds: false, parameterDrift };
+    }
+    // (1) Improvement path.
+    const larpI = intervalImproves(input.larp.before, input.larp.after);
+    const rugI = intervalImproves(input.rug.before, input.rug.after);
+    const improved = [];
+    if (larpI.improves)
+        improved.push('larp');
+    if (rugI.improves)
+        improved.push('rug');
+    const canaryHolds = holds(input.canaryProposed.larpMcc, input.canaryBaseline.larpMcc, noise) && holds(input.canaryProposed.rugMcc, input.canaryBaseline.rugMcc, noise);
+    if (input.newCoins < N)
+        reasons.push(`only ${input.newCoins} new labelled coins since the last accepted tuning (need ${N})`);
+    if (!improved.length)
+        reasons.push(`no subject beats the held-out window beyond noise (larp: ${larpI.reason}; rug: ${rugI.reason})`);
+    else
+        reasons.push(`held-out improvement — larp: ${larpI.improves ? larpI.reason : 'no'}; rug: ${rugI.improves ? rugI.reason : 'no'}`);
+    if (improved.length && !canaryHolds)
+        reasons.push('proposed params would regress the frozen canary (overfit guard) — not proposing');
+    const propose = input.newCoins >= N && improved.length > 0 && canaryHolds;
+    return { propose, kind: propose ? 'improvement' : 'none', reasons, improved, canaryHolds, parameterDrift };
+}
+const fmt = (x) => (x === null ? '—' : x.toFixed(3));
+// ---------------------------------------------------------------- the one-line trend
+const pr = (r) => (r === null ? '—' : `${(r.value * 100).toFixed(0)}%[${(r.lo * 100).toFixed(0)}-${(r.hi * 100).toFixed(0)}]`);
+/** One subject's compact per-grade precision/recall with Wilson intervals, for the trend line. */
+function subjectTrend(label, m) {
+    const grades = m.by_grade.filter((g) => g.claims).map((g) => `${g.grade}=${pr(g.precision)}`).join(' ');
+    return `${label} MCC ${m.binary.mcc === null ? '—' : m.binary.mcc.toFixed(3)} ${grades}`;
+}
+/** The dated one-line trend record (MCC + per-grade precision Wilson intervals + n + the decision). */
+export function trendLine(t) {
+    return `${t.date}  test n=${t.testN} bad=${t.badTest} · train n=${t.trainN} · new=${t.newCoins} · ${subjectTrend('rug', t.rugTest)} · ${subjectTrend('larp', t.larpTest)} · decision=${t.decision}`;
+}
+const cv = (v) => (v === null || v === undefined ? 'off' : String(v));
+const cm = (m) => (m === null || m === undefined ? '—' : m.toFixed(3));
+/**
+ * The Kanban card a proposal creates (priority normal, owner `i.owner`, default 'maintainers': the maintainers'
+ * tooling names the lane). It carries the numbers and the exact tunable-grid parameter change; it NEVER edits app
+ * main and NEVER ships to users — a maintainer opens a scratch branch, applies the diff, it is verified, and the
+ * skills reach users only in a normal release.
+ */
+export function proposalCard(i) {
+    const d = [
+        `Skill care proposes a ${i.kind} tuning for the dexterm analyst skills (task-1414). It never edits app main; a maintainer creates a scratch branch and applies the parameter diff below, it is verified, and it reaches users only in a normal release.`,
+        '',
+        `New labelled coins since the last accepted tuning: ${i.newCoins} (threshold ${i.minNew}).`,
+        `Rolling held-out window: ${i.splitRule}`,
+        `Gate: ${i.reasons.join('; ')}`,
+        '',
+        'Proposed parameters (the existing tunable grid only; keep the AVOID hard rules):',
+        `  rug-check (packages/packs/src/skill-backtest.ts RUG_RULES_V1): dev_pct_over=${cv(i.proposed.rug.dev_pct_over)} organic_below=${cv(i.proposed.rug.organic_below)} top10_over=${cv(i.proposed.rug.top10_over)} liq_below=${cv(i.proposed.rug.liq_below)}`,
+        `    shipped: dev_pct_over=${cv(i.shipped.rug.dev_pct_over)} organic_below=${cv(i.shipped.rug.organic_below)} top10_over=${cv(i.shipped.rug.top10_over)} liq_below=${cv(i.shipped.rug.liq_below)}`,
+        `  larp-check (packages/data/src/larp/link-baseline.ts LINK_RUBRIC_V1): threshold=${i.proposed.larp.threshold} weights=${JSON.stringify(i.proposed.larp.weights)}`,
+        `    shipped: threshold=${i.shipped.larp.threshold} weights=${JSON.stringify(i.shipped.larp.weights)}`,
+        '',
+        `Held-out MCC — rug ${cm(i.heldOut.rug.before)} → ${cm(i.heldOut.rug.after)}; larp ${cm(i.heldOut.larp.before)} → ${cm(i.heldOut.larp.after)}.`,
+        `Frozen canary MCC (must not regress) — baseline rug ${cm(i.canary.baseline.rugMcc)} / larp ${cm(i.canary.baseline.larpMcc)}; proposed rug ${cm(i.canary.proposed.rugMcc)} / larp ${cm(i.canary.proposed.larpMcc)}.`,
+        '',
+        'Also update the skill prose that names these numbers (rug-check/larp-check SKILL.md, token-dossier.md, packages/packs/eval/README.md) and the site docs/larp.md in the release lane — published numbers change only via a release and must keep the weak results. Do NOT auto-ship.',
+    ].join('\n');
+    return {
+        title: `dexterm skill-care: proposed ${i.kind} tuning (${i.date.slice(0, 10)})`,
+        description: d,
+        project: 'dexterm', priority: 'normal', owner: i.owner ?? 'maintainers', delegationTarget: i.owner ?? 'maintainers', actor: 'skill-care',
+        constraints: [
+            'Scratch branch off app main; never commit to main; ship to users only via a release after verification.',
+            'Change the tunable grid only (RUG_RULES_V1 / LINK_RUBRIC_V1); keep the AVOID hard rules.',
+            'Keep the weak results in the published numbers (site docs/larp.md).',
+        ],
+        acceptanceCriteria: [
+            'Parameter diff applied on a scratch branch with the before/after numbers in the handoff',
+            'Frozen canary does not regress; one npm test green',
+            'Site docs/larp.md + skill prose updated in the release lane',
+        ],
+    };
+}

package/dist/packages/popup/src/pages/spectator.css

@@ -0,0 +1,45 @@
+/* dexterm popup — spectator page styles (task-1406, "watch the agent cook"). The palette comes from the
+   theme CSS vars common.js sets (--text, --muted, --accent, --up, --down, --warn, --pump, --ai …). */
+.body { overflow-y: auto; padding: 6px 8px; }
+
+.spec-screen { font: 12px ui-monospace, Menlo, monospace; color: var(--text); margin-bottom: 8px; padding: 4px 6px; border: 1px solid var(--border); border-radius: 6px; background: color-mix(in srgb, var(--panel) 85%, transparent); }
+.spec-screen-k { color: var(--accent); font-weight: 600; }
+.spec-screen-dim { color: var(--dim); }
+.spec-takeover { color: var(--warn); font-weight: 600; }
+
+.spec-agents { display: flex; flex-direction: column; gap: 6px; }
+.spec-agent { display: flex; flex-wrap: wrap; align-items: baseline; gap: 6px; border: 1px solid var(--border); border-radius: 6px; padding: 6px 8px; font: 12px ui-monospace, Menlo, monospace; background: color-mix(in srgb, var(--panel) 85%, transparent); }
+.spec-agent.off { opacity: 0.6; border-color: var(--warn); }
+.spec-badge { font-size: 9px; letter-spacing: 0.06em; text-transform: uppercase; padding: 1px 5px; border-radius: 4px; background: var(--ai, var(--accent)); color: #000; font-weight: 700; }
+.spec-badge.sm { font-size: 8px; padding: 0 4px; }
+.spec-name { color: var(--text); font-weight: 600; }
+.spec-tier { font-size: 10px; padding: 1px 5px; border-radius: 999px; border: 1px solid var(--border); color: var(--muted); }
+.tier-observe { color: var(--muted); }
+.tier-annotate { color: var(--accent); border-color: var(--accent); }
+.tier-propose { color: var(--pump); border-color: var(--pump); }
+.spec-status { font-size: 10px; padding: 1px 5px; border-radius: 4px; border: 1px solid var(--border); color: var(--muted); }
+.status-active { color: var(--up); border-color: color-mix(in srgb, var(--up) 50%, var(--border)); }
+.status-paused { color: var(--warn); border-color: color-mix(in srgb, var(--warn) 50%, var(--border)); }
+.status-killed { color: var(--down); border-color: color-mix(in srgb, var(--down) 50%, var(--border)); }
+.spec-dim { color: var(--dim); }
+
+.spec-ctl { display: flex; gap: 6px; margin-left: auto; }
+.spec-btn { font: 11px ui-monospace, Menlo, monospace; padding: 2px 10px; border-radius: 4px; border: 1px solid var(--border); background: transparent; color: var(--text); cursor: pointer; }
+.spec-btn:hover { border-color: var(--borderFocus); }
+.spec-btn.danger { color: var(--down); border-color: color-mix(in srgb, var(--down) 50%, var(--border)); }
+.spec-btn.danger:hover { border-color: var(--down); }
+
+.spec-activity-head { margin: 10px 0 4px; font: 11px ui-monospace, Menlo, monospace; color: var(--dim); text-transform: uppercase; letter-spacing: 0.08em; }
+.spec-activity { display: flex; flex-direction: column; gap: 1px; font: 11px ui-monospace, Menlo, monospace; }
+.spec-act { display: flex; flex-wrap: wrap; align-items: baseline; gap: 6px; color: var(--muted); }
+.spec-act.bad { color: var(--down); }
+.spec-act.nav .spec-act-phase { color: var(--ai, var(--accent)); font-weight: 600; }
+.spec-act-t { color: var(--dim); min-width: 28px; }
+.spec-act-agent { color: var(--text); }
+.spec-act-phase { color: var(--accent); }
+.spec-act-tool { color: var(--muted); }
+.spec-act-sum { color: var(--text); overflow: hidden; text-overflow: ellipsis; }
+.spec-act-ms { color: var(--dim); }
+.spec-act-age { color: var(--warn); }
+
+.spec-foot-redact { color: var(--up); font-weight: 600; }

package/dist/packages/popup/src/pages/spectator.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="dexterm-ws" content="__WS_TOKEN__">
+<meta name="dexterm-popup" content="__POPUP_ID__">
+<meta name="dexterm-port" content="__PORT__">
+<title>dexterm · watch the agent cook</title>
+<style nonce="__NONCE__">/*__CSS__*/</style>
+</head>
+<body>
+<div id="hud" class="hud">
+  <div id="drag" class="drag"><span class="mark">✦</span><span id="title" class="title">dexterm · WATCH THE AGENT COOK</span><span id="status" class="status">connecting…</span><button id="close" class="close" type="button" aria-label="close">✕</button></div>
+  <div class="stage"><canvas id="rain"></canvas><div class="body">
+    <div id="screen" class="spec-screen"></div>
+    <div id="agents" class="spec-agents"></div>
+    <div class="spec-activity-head">agent activity</div>
+    <div id="activity" class="spec-activity"></div>
+  </div></div>
+  <div id="foot" class="foot"><span id="redact" class="spec-foot-redact">redacted</span><span>read-only · pause / take over / kill</span><span id="fps" class="fps">— fps</span></div>
+</div>
+<script nonce="__NONCE__">/*__COMMON_JS__*/</script>
+<script nonce="__NONCE__">/*__JS__*/</script>
+</body>
+</html>

package/dist/packages/popup/src/pages/spectator.js

@@ -0,0 +1,74 @@
+// dexterm popup — spectator page (task-1406, "watch the agent cook"). Renders the SpectatorPopupVM: the
+// screen the agent moved to, the connected agents with an 'agent' badge and status, and an activity feed
+// with timing and data ages. Every string is already REDACTED TUI-side (wallet addresses/keys masked) and
+// is rendered with textContent only — never innerHTML. The ONLY messages this page sends are the
+// allow-listed spectator.pause / resume / takeover / kill events (by agent name); it can never arm, sign,
+// raise a cap or touch a wallet (no such control exists and the server drops anything off the allow-list).
+(() => {
+  'use strict';
+  const DT = window.DT; DT.page = 'spectator';
+  const $ = (id) => document.getElementById(id);
+  const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = String(text); return e; };
+  const ago = (t) => { if (!t) return '—'; const s = Math.max(0, Math.round((Date.now() - t) / 1000)); return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : `${Math.floor(s / 3600)}h`; };
+  const age = (s) => (s == null ? '' : s < 60 ? `${Math.round(s)}s old` : s < 3600 ? `${Math.floor(s / 60)}m old` : `${Math.floor(s / 3600)}h old`);
+
+  let vm = null;
+
+  function render() {
+    if (!vm) return;
+
+    const scr = $('screen'); scr.textContent = '';
+    const s = vm.screen || {};
+    scr.appendChild(el('span', 'spec-screen-k', `screen: ${s.screen || '—'}`));
+    if (s.selectedMint) scr.appendChild(el('span', 'spec-screen-dim', ` · token ${s.selectedMint}`));
+    if (s.feed) scr.appendChild(el('span', 'spec-screen-dim', ` · feed ${s.feed}`));
+    if (s.filter) scr.appendChild(el('span', 'spec-screen-dim', ` · filter ${s.filter}`));
+    if (s.highlight) scr.appendChild(el('span', 'spec-screen-dim', ` · ★ ${s.highlight}`));
+    if (vm.control === 'user') scr.appendChild(el('span', 'spec-takeover', ' · YOU HAVE TAKEN OVER'));
+
+    const host = $('agents'); host.textContent = '';
+    if (!vm.agents || !vm.agents.length) host.appendChild(el('div', 'spec-dim', 'no agents connected yet'));
+    for (const a of (vm.agents || [])) {
+      const row = el('div', 'spec-agent' + (a.status !== 'active' ? ' off' : ''));
+      row.appendChild(el('span', 'spec-badge', 'agent'));           // the 'agent' badge
+      row.appendChild(el('span', 'spec-name', a.name));             // textContent — redacted/firewalled, safe
+      if (a.tier) row.appendChild(el('span', 'spec-tier tier-' + a.tier, a.tier));
+      row.appendChild(el('span', 'spec-status status-' + a.status, a.status));
+      row.appendChild(el('span', 'spec-dim', ` · ${ago(a.lastAt)}`));
+      const ctl = el('div', 'spec-ctl');
+      const mk = (label, name, danger) => { const b = el('button', 'spec-btn' + (danger ? ' danger' : ''), label); b.type = 'button'; b.addEventListener('click', () => DT.send({ type: 'event', name, payload: { agent: a.name } })); return b; };
+      if (a.status === 'active') { ctl.appendChild(mk('pause', 'spectator.pause')); ctl.appendChild(mk('take over', 'spectator.takeover')); }
+      else ctl.appendChild(mk('resume', 'spectator.resume'));
+      ctl.appendChild(mk('kill', 'spectator.kill', true));          // panic
+      row.appendChild(ctl);
+      host.appendChild(row);
+    }
+
+    const act = $('activity'); act.textContent = '';
+    for (const r of (vm.activity || []).slice().reverse().slice(0, 80)) {
+      const line = el('div', 'spec-act' + (r.ok ? '' : ' bad') + (r.phase === 'nav' ? ' nav' : ''));
+      line.appendChild(el('span', 'spec-act-t', ago(r.t)));
+      line.appendChild(el('span', 'spec-badge sm', 'agent'));
+      line.appendChild(el('span', 'spec-act-agent', r.agent));
+      line.appendChild(el('span', 'spec-act-phase', r.phase));
+      if (r.tool) line.appendChild(el('span', 'spec-act-tool', r.tool));
+      line.appendChild(el('span', 'spec-act-sum', r.summary || ''));  // textContent — redacted upstream
+      if (r.ms != null) line.appendChild(el('span', 'spec-act-ms', `${Math.round(r.ms)}ms`));
+      if (r.dataAgeSec != null) line.appendChild(el('span', 'spec-act-age', age(r.dataAgeSec)));
+      act.appendChild(line);
+    }
+
+    $('redact').textContent = vm.redacted ? 'redacted' : 'local (full)';
+    const live = (vm.agents || []).filter((a) => a.status === 'active').length;
+    DT.status(`${live} cooking`, live ? 'up' : 'muted');
+  }
+
+  DT.onHello(() => { DT.mountRain('rain'); const r = DT.rain(); if (r) { r.setActivity(0.3); r.setMood('rain'); } });
+  DT.onData((payload) => { vm = payload; render(); });
+  DT.onUpdate(() => { /* spectator is pushed as full `data` frames */ });
+  DT.wireChrome();
+  let lastTick = 0;
+  DT.rainEvery = 2; DT.fpsCap = 30;
+  DT.loop((now) => { if (now - lastTick > 1000) { lastTick = now; if (vm) render(); } });
+  DT.connect();
+})();

package/dist/packages/popup/src/selftest.js

@@ -62,6 +62,25 @@ export function fixtureNarrativeVM() {
         limits: 'model output: none (deterministic lexicon v0.1.0). Name-based: X/Telegram-only narratives are missed; 6 copycat symbols.',
     };
 }
+/** A deterministic, network-free spectator view for the popup self-test / demo (task-1406). Not real agents. */
+export function fixtureSpectatorVM() {
+    const now = Date.now();
+    return {
+        title: 'watch the agent cook', now, redacted: true, control: 'agent',
+        screen: { screen: 'token', selectedMint: 'Fixt…AAAA', feed: 'new', filter: null, highlight: null },
+        agents: [
+            { name: 'claude-code', tier: 'propose', status: 'active', lastAt: now - 1200 },
+            { name: 'scanbot', tier: 'observe', status: 'paused', lastAt: now - 8000 },
+        ],
+        activity: [
+            { seq: 1, t: now - 8000, phase: 'connect', agent: 'claude-code', tier: 'propose', tool: null, summary: 'connected · claude-code 2.1', ms: null, dataAgeSec: null, ok: true, refusal: null },
+            { seq: 2, t: now - 5000, phase: 'nav', agent: 'claude-code', tier: 'propose', tool: 'open_token', summary: 'open Fixt…AAAA', ms: 6, dataAgeSec: null, ok: true, refusal: null },
+            { seq: 3, t: now - 4200, phase: 'result', agent: 'claude-code', tier: 'propose', tool: 'rugcheck', summary: 'rugcheck Fixt…', ms: 42, dataAgeSec: 3, ok: true, refusal: null },
+            { seq: 4, t: now - 2000, phase: 'proposal', agent: 'claude-code', tier: 'propose', tool: 'propose_alert', summary: 'alert when mcap crosses 1M', ms: 2, dataAgeSec: null, ok: true, refusal: null },
+            { seq: 5, t: now - 1000, phase: 'refused', agent: 'scanbot', tier: 'observe', tool: 'arm_plan', summary: 'refused: no agent may do that at any tier', ms: null, dataAgeSec: null, ok: false, refusal: 'never' },
+        ],
+    };
+}
 /** Run the self-test and resolve with the measured result. Always cleans up the window host and server. */
 export async function runSelfTest(opts = {}) {
     const seconds = Math.max(2, Math.min(30, opts.seconds ?? 6));

package/dist/packages/popup/src/server.js

@@ -52,6 +52,8 @@ export const POPUP_EVENTS = new Set([
     'event:roster.pause', 'event:roster.resume', 'event:roster.kick',
     // task-1355 order plans: cancel a plan by id (the ONLY write the plans popup can send — never arm/cap/sign)
     'event:plan.cancel',
+    // task-1406 spectator: pause / resume / take over / kill an agent by name (the only writes this popup sends)
+    'event:spectator.pause', 'event:spectator.resume', 'event:spectator.takeover', 'event:spectator.kill',
 ]);
 /**
  * task-1358 r3: the ONLY messages a pack widget's socket may send — the generic set every popup has. A widget socket
@@ -104,6 +106,10 @@ export function validateEventPayload(name, payload) {
         case 'roster.pause':
         case 'roster.resume':
         case 'roster.kick':
+        case 'spectator.pause':
+        case 'spectator.resume':
+        case 'spectator.takeover':
+        case 'spectator.kill':
             return typeof p.agent === 'string' && ROSTER_AGENT_RE.test(p.agent) ? { agent: p.agent } : null;
         case 'plan.cancel':
             return typeof p.id === 'string' && PLAN_ID_RE.test(p.id) ? { id: p.id } : null;
@@ -117,7 +123,7 @@ export function lwcLogoStyleHash(lwcSource) {
     return m ? `'sha256-${createHash('sha256').update(m[1], 'utf8').digest('base64')}'` : null;
 }
 // (r3) 'widget' is the WRAPPER page — ours, nonce-rendered like the rest; the pack html goes in its iframe
-const PAGE_KINDS = ['chart', 'token', 'feeds', 'bubbles', 'roster', 'narrative', 'plans', 'widget'];
+const PAGE_KINDS = ['chart', 'token', 'feeds', 'bubbles', 'roster', 'narrative', 'plans', 'widget', 'spectator'];
 function b64url(buf) { return buf.toString('base64url'); }
 function safeEq(a, b) {
     const ba = Buffer.from(a), bb = Buffer.from(b);

package/dist/packages/tui/src/keymap.js

@@ -206,6 +206,12 @@ export const DEFAULT_KEYMAP = new Keymap([
     // task-1282 JARVIS voice: push-to-talk toggle (hold not possible in a terminal). Lowercase v is free
     // on every screen; the loop auto-enables voice mode on first use and shows a live mic indicator.
     { keys: ['v'], action: 'voice.talk', label: 'voice' },
+    // task-1411: in-voice controls (loop-handled; only act while voice is on). `m` mute, `,` change voice,
+    // `<`/`>` slow down / speed up the spoken reply (saved to config.voice.rate). Per-screen `m` bindings
+    // (kol/bubbles/follows) override this global one on those screens, exactly like `voice.talk`.
+    { keys: ['m'], action: 'voice.mute', label: 'mute voice' },
+    { keys: [','], action: 'voice.cycle', label: 'change voice' },
+    { keys: ['<', '>'], action: 'voice.rate', label: 'slower / faster voice' },
     // task-1311: `i` focuses the chat input on the token / analyst screens (QA B1–B3); the loop only
     // captures keystrokes into the input while it is focused, so the number keys and `q` never type.
     { keys: ['i'], action: 'input.focus', label: 'ask', screen: 'token' },
@@ -217,6 +223,10 @@ export const DEFAULT_KEYMAP = new Keymap([
     { keys: ['$'], action: 'display.priceMode', label: 'price ⇄ mcap' },
     // task-1401: `E` exports the current view (PNG + text report, local only). Free on every screen.
     { keys: ['E'], action: 'export.view', label: 'export PNG + report' },
+    // task-1407: `H` (free capital everywhere) opens the PnL card preview on the screens that have fills to card.
+    { keys: ['H'], action: 'pnl.card', label: 'PnL card (share)', screen: 'token' },
+    { keys: ['H'], action: 'pnl.card', label: 'PnL card (share)', screen: 'positions' },
+    { keys: ['H'], action: 'pnl.card', label: 'PnL card (share)', screen: 'follows' },
     { keys: ['/'], action: 'filter.edit', label: 'filter', screen: 'screener' },
     { keys: ['\\'], action: 'filter.clear', label: 'clear filter', screen: 'screener' },
     { keys: ['s'], action: 'sort.menu', label: 'sort', screen: 'screener' },

package/dist/packages/voice/src/controller.js

@@ -5,7 +5,13 @@
 // listen() is called — so the on-screen indicator and the real mic state can never disagree.
 import { route, isSafe } from "./router.js";
 import { spokenSummary } from "./summary.js";
+import { speakable } from "./speakable.js";
 import { isBannedVoice } from "./tts/voices.js";
+import { DEFAULT_RATE } from "./tts/say.js";
+/** Live rate-nudge bounds and step (task-1411, the < / > keys). Clamped so a voice stays intelligible. */
+export const RATE_MIN = 120;
+export const RATE_MAX = 320;
+export const RATE_STEP = 15;
 export class VoiceController {
     stt;
     tts;
@@ -44,7 +50,7 @@ export class VoiceController {
         this.tts = opts.tts;
         this.muted = opts.muted ?? false;
         this.voice = opts.voice ?? null;
-        this.rate = opts.rate ?? 190;
+        this.rate = opts.rate ?? DEFAULT_RATE;
         this.pitch = opts.pitch;
         this.now = opts.now ?? (() => Date.now());
         this.maxListenMs = opts.maxListenMs ?? 15_000;
@@ -99,6 +105,12 @@ export class VoiceController {
         this.message = this.stt ? null : 'voice-in unavailable on this machine — type questions; replies are still spoken';
         this.setMode('idle');
         void this.loadVoices();
+        // task-1416: pre-load the TTS engine (Piper loads its model into a standby process) so the first
+        // reply starts speaking quickly. A no-op for engines that stream from spawn (`say`).
+        try {
+            this.tts?.warmup?.(this.rate);
+        }
+        catch { /* warm-up is best-effort; never break enabling voice */ }
     }
     disable() {
         if (!this.enabled)
@@ -107,6 +119,10 @@ export class VoiceController {
         this.stopSpeaking();
         this.enabled = false;
         this.pendingLatency = null;
+        try {
+            this.tts?.dispose?.();
+        }
+        catch { /* best-effort cleanup */ }
         this.setMode('off');
     }
     toggle() { this.enabled ? this.disable() : this.enable(); }
@@ -279,6 +295,9 @@ export class VoiceController {
     }
     /** Low-level speak: stops any current reply, then reads `text`. Muted → skip audio but update state. */
     speak(text) {
+        // Speak like a trader (task-1411): no digit-by-digit tiny prices, big numbers in human words,
+        // natural percents. Applied to EVERY spoken line so an ack or an analyst answer never reads raw.
+        text = speakable(text);
         this.lastSay = text;
         if (!this.tts || this.muted) {
             // Still resolve the latency sample (the "spoken word" is just suppressed) so the table is complete.
@@ -386,6 +405,28 @@ export class VoiceController {
     }
     currentVoice() { return this.voice; }
     availableVoices() { return this.voices.slice(); }
+    /** The current speaking rate (words-per-minute-ish), for the status line / help. */
+    currentRate() { return this.rate; }
+    /**
+     * Nudge the speaking rate by `steps` × RATE_STEP (— for slower, + for faster), clamp it, persist it,
+     * and surface it on the status line (task-1411: the < / > keys). Takes effect on the next reply; it
+     * does not restart a line already in flight. A no-op when the rate is already at the clamp.
+     */
+    nudgeRate(steps) {
+        const next = Math.max(RATE_MIN, Math.min(RATE_MAX, this.rate + steps * RATE_STEP));
+        if (next === this.rate) {
+            this.message = `voice rate ${this.rate} wpm (${next <= RATE_MIN ? 'slowest' : 'fastest'})`;
+            this.notify();
+            return;
+        }
+        this.rate = next;
+        this.message = `voice rate ${this.rate} wpm`;
+        try {
+            this.opts.onRateChange?.(this.rate);
+        }
+        catch { /* persistence is best-effort; never break the UI */ }
+        this.notify();
+    }
     /** A compact latency report for the handoff / `--latency` demo. */
     report() {
         const paths = ['instant', 'analyst'];

package/dist/packages/voice/src/doctor.js

@@ -71,26 +71,43 @@ export function voiceDoctor(deps) {
         }
         return checks;
     }
-    // Speech OUT — macOS say.
+    // Speech OUT — Piper neural (the default when set up, task-1416) → macOS `say` (fallback) → text.
+    const macPiperReady = !!deps.piperPresent && !!deps.piperVoicePresent && !!deps.playerName;
+    if (macPiperReady) {
+        checks.push({
+            name: 'Voice out (Piper)', status: 'pass',
+            detail: `neural British voice is the default — en_GB-alan-medium, plays via ${deps.playerName} (local, no key); fallback: macOS \`say\``,
+        });
+    }
     if (deps.sayAvailable) {
-        checks.push({ name: 'Voice out (say)', status: 'pass', detail: `macOS \`say\` ready · ${deps.voiceCount} voice${deps.voiceCount === 1 ? '' : 's'} (press the voice key, then cycle the voice)` });
-        // Which voice speaks, and why — so a machine can never silently use a novelty/odd system voice (task-1393).
+        const role = macPiperReady ? 'the fallback if Piper is removed' : 'the default — press the voice key, then cycle the voice';
+        checks.push({ name: macPiperReady ? 'Voice out (say, fallback)' : 'Voice out (say)', status: 'pass', detail: `macOS \`say\` ready · ${deps.voiceCount} voice${deps.voiceCount === 1 ? '' : 's'} · ${role}` });
+        // Which `say` voice speaks, and why — so a machine can never silently use a novelty/odd system voice (task-1393).
+        const voiceLabel = macPiperReady ? 'Fallback voice' : 'Default voice';
         if (deps.resolvedVoice) {
-            checks.push({ name: 'Default voice', status: 'pass', detail: `${deps.resolvedVoiceReason ?? deps.resolvedVoice} · , changes it` });
+            checks.push({ name: voiceLabel, status: 'pass', detail: `${deps.resolvedVoiceReason ?? deps.resolvedVoice} · , changes it` });
         }
         else if (deps.resolvedVoice === null) {
             checks.push({
-                name: 'Default voice', status: 'warn',
+                name: voiceLabel, status: 'warn',
                 detail: deps.resolvedVoiceReason ?? 'no safe voice installed — spoken replies are off (text still works)',
                 fix: 'Install a British male voice in System Settings → Accessibility → Spoken Content → System Voice → Manage Voices (Daniel, English (UK)); the Enhanced/Premium download sounds best.',
             });
         }
+        // Offer the higher-quality neural voice when it is not set up yet (never silent; the user decides).
+        if (!macPiperReady) {
+            checks.push({
+                name: 'Neural voice (Piper)', status: 'warn',
+                detail: 'a higher-quality neural British voice is available but not set up; `say` is speaking for now',
+                fix: 'Run `dexterm voice setup` to install it (asks first; a private Python runtime + a ~61 MB checksum-verified model; runs offline after, `dexterm voice uninstall` removes it).',
+            });
+        }
     }
-    else {
+    else if (!macPiperReady) {
         checks.push({
-            name: 'Voice out (say)', status: 'warn',
+            name: 'Voice out', status: 'warn',
             detail: 'macOS `say` not found; spoken replies are off, the analyst still answers in text',
-            fix: '`say` ships with macOS — if it is missing, reinstall the Command Line Tools (`xcode-select --install`).',
+            fix: '`say` ships with macOS — if it is missing, reinstall the Command Line Tools (`xcode-select --install`). Or set up the neural voice: `dexterm voice setup`.',
         });
     }
     // Speech IN — Apple Speech (preferred) or whisper (fallback).

package/dist/packages/voice/src/engines.js

@@ -62,8 +62,15 @@ export async function selectTts(choice = process.env.DEXTERM_VOICE_TTS || 'auto'
         const e = new EspeakTts(espeakVoiceFor(configuredVoice) ?? undefined);
         return (await e.available()) ? e : null;
     }
-    // On macOS, prefer `say`. Off macOS, `say` does not exist — use the portable engines below.
+    // On macOS, prefer Piper alan (neural) when the managed runtime is installed (task-1416:
+    // `dexterm voice setup` → venv + model + afplay), else the built-in `say`. Off macOS, `say` does not
+    // exist — use the portable engines below. An explicit `choice==='say'` always skips Piper.
     if (choice === 'say' || (choice === 'auto' && process.platform === 'darwin')) {
+        if (choice === 'auto') {
+            const piperMac = new PiperTts();
+            if (await piperMac.available())
+                return piperMac;
+        }
         const probe = new SayTts();
         if (choice === 'auto' && !(await probe.available()))
             return null;

package/dist/packages/voice/src/index.js

@@ -6,13 +6,15 @@
 export * from "./types.js";
 export { route, isSafe } from "./router.js";
 export { spokenSummary, splitSentences } from "./summary.js";
+export { speakable, humanizeNumber } from "./speakable.js";
 export { VoiceController } from "./controller.js";
 export { selectStt, selectTts, resolveSayVoice } from "./engines.js";
 export { voiceDoctor } from "./doctor.js";
 export { resolveVoice, isBannedVoice, normalizeVoiceName, parseSayVoices, sanitizeSpeech, BANNED_VOICE_NAMES, BRITISH_MALE_PREFERENCE, MAX_SPEAK_CHARS, VOICE_STYLE_DEFAULTS, voiceStyleDefaults, } from "./tts/voices.js";
 export { SayTts, DEFAULT_RATE } from "./tts/say.js";
 export { EspeakTts, DEFAULT_ESPEAK_VOICE, resolveEspeakBin, espeakVoiceFor } from "./tts/espeak.js";
-export { PiperTts, DEFAULT_PIPER_VOICE, PIPER_MODEL, PIPER_PLAYERS, resolvePiperBin, pickPlayer } from "./tts/piper.js";
+export { PiperTts, DEFAULT_PIPER_VOICE, PIPER_MODEL, PIPER_PLAYERS, resolvePiperBin, resolvePiperRuntime, managedVenvPython, pickPlayer, } from "./tts/piper.js";
+export { setupPiperRuntime, uninstallPiperRuntime, piperRuntimeStatus, piperRuntimePaths, readRuntimeRecord, detectPython, parsePythonVersion, pythonVersionOk, pythonFixLine, PIPER_PYPI_VERSION, MIN_PYTHON, DEFAULT_PYTHON_CANDIDATES, } from "./tts/piper-setup.js";
 export { FakeTts } from "./tts/fake.js";
 export { WhisperStt, WHISPER_MODEL, WHISPER_MODEL_DIR, pickRecorder } from "./stt/whisper.js";
 export { modelRegistry, downloadModel, modelStatus, specSizeMB, } from "./download.js";