dexterm-cli 0.1.1 → 0.1.3

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

@@ -0,0 +1,300 @@
+// Skill backtest harness (task-1401). Runs the replayable part of the default analyst skills over a recorded,
+// outcome-labelled eval set and reports per-grade precision/recall with 95 % Wilson intervals, on a TRAIN and a
+// held-out TEST split. Pure: input is the eval set JSON (built from a recorder DB by `dexterm backtest
+// --build-eval`), so every number is re-runnable offline.
+//
+// Which skills, and what is actually replayed:
+//   - larp-check: the links-only baseline grade (@dexterm/data link-baseline.ts) the skill starts from. The model
+//     stage (fetched pages, RDAP, GitHub) cannot be replayed on history and is NOT measured here.
+//   - rug-check (and token-dossier, which shares its verdict rules): the skill's stated verdict rules over the t0
+//     snapshot columns the recorder keeps (authorities, dev %, organic score, top-10 %, liquidity). The model's
+//     own rug_probability is not replayed either; the recorded-verdict path (`--subject pack_verdicts|larp`)
+//     measures that going forward.
+// The other default skills (trench-scan) have no per-token labelled outcome.
+//
+// Labels: the recorder's keyless-proxy outcome at the eval horizon; bad = rug ∪ dead, ok = flat ∪ fade ∪ runner.
+// That is a PRICE outcome, not ground truth about a product: a LARP grade "agrees" when the coin went bad.
+//
+// Honesty rules enforced in code: tuning functions refuse any TEST row (throw), the split is by time and fixed
+// in the eval file before tuning, and rates under MIN_N rows print as counts only.
+import { gradeLinks, LINK_SIGNALS, linkSignals, } from '../../data/src/index.js';
+import { wilson } from "./larp-eval.js";
+export const SKILL_EVAL_SCHEMA = 'dexterm/packs/skill-eval/1';
+export const SKILL_BACKTEST_SCHEMA = 'dexterm/packs/skill-backtest/1';
+/** Below this many rows in a grade, its rates are printed as counts only (same spirit as the n ≥ 50 gate). */
+export const SKILL_MIN_N = 20;
+/** v0: the rug-check skill's own rules as written before the backtest (dev > 10 %, organic < 40 = soft flags). */
+export const RUG_RULES_V0 = {
+    id: 'rug-rules-v0', dev_pct_over: 10, organic_below: 40, top10_over: null, liq_below: null,
+    provenance: 'the rug-check skill 0.2.0 / token-dossier computeFlags thresholds before the backtest',
+};
+/** v1: tuned on the TRAIN split (grid search, objective MCC of AVOID ∪ SPECULATIVE → bad). */
+export const RUG_RULES_V1 = {
+    id: 'rug-rules-v1', dev_pct_over: null, organic_below: null, top10_over: null, liq_below: 5_000,
+    provenance: 'tuned on the train split of the task-1401 eval set (see packages/packs/eval/README.md)',
+};
+/**
+ * The rug-check verdict rules on recorder t0 columns. AVOID rules are the skill's hard disqualifiers and are never
+ * tuned (authorities; LP unlocked off pump.fun with top-10 above 50 %). INSUFFICIENT_DATA only when there is no
+ * price and no liquidity (skill rule). Everything tunable only moves a coin between SPECULATIVE and WATCH.
+ */
+export function gradeRugRules(f, rules = RUG_RULES_V1) {
+    if (!((f.price_usd ?? 0) > 0) && !((f.liquidity_usd ?? 0) > 0))
+        return { grade: 'INSUFFICIENT_DATA', reasons: ['no price and no liquidity'] };
+    const avoid = [];
+    if (f.freeze_auth === true)
+        avoid.push('freeze_authority_enabled');
+    if (f.mint_auth === true)
+        avoid.push('mint_authority_enabled');
+    if (f.lp_locked_pct !== null && f.lp_locked_pct < 100 && f.launchpad !== 'pump.fun' && (f.top10_pct ?? 0) > 50)
+        avoid.push('lp_unlocked_and_concentrated');
+    if (avoid.length)
+        return { grade: 'AVOID', reasons: avoid };
+    const soft = [];
+    if (rules.dev_pct_over !== null && (f.dev_pct ?? 0) > rules.dev_pct_over)
+        soft.push(`dev_over_${rules.dev_pct_over}pct`);
+    if (rules.organic_below !== null && f.organic_score !== null && f.organic_score < rules.organic_below)
+        soft.push(`organic_below_${rules.organic_below}`);
+    if (rules.top10_over !== null && f.top10_pct !== null && f.top10_pct > rules.top10_over)
+        soft.push(`top10_over_${rules.top10_over}pct`);
+    if (rules.liq_below !== null && (f.liquidity_usd ?? 0) < rules.liq_below)
+        soft.push(`liquidity_below_${rules.liq_below}`);
+    return soft.length ? { grade: 'SPECULATIVE', reasons: soft } : { grade: 'WATCH', reasons: [] };
+}
+export const LARP_GRADE_CLAIMS = { LARP: 'bad', EARLY_BUT_REAL: 'ok', UNVERIFIABLE: null };
+export const RUG_GRADE_CLAIMS = { AVOID: 'bad', SPECULATIVE: 'bad', WATCH: 'ok', INSUFFICIENT_DATA: null };
+export function mcc(tp, fp, fn, tn) {
+    const d = Math.sqrt((tp + fp) * (tp + fn) * (tn + fp) * (tn + fn));
+    return d === 0 ? null : (tp * tn - fp * fn) / d;
+}
+export function splitMetrics(rows, claims, order) {
+    const n = rows.length;
+    const bad = rows.filter((r) => r.bad).length;
+    const ok = n - bad;
+    const by_grade = order.map((g) => {
+        const gr = rows.filter((r) => r.grade === g);
+        const gb = gr.filter((r) => r.bad).length;
+        const claim = claims[g] ?? null;
+        const enough = gr.length >= SKILL_MIN_N;
+        const right = claim === 'bad' ? gb : claim === 'ok' ? gr.length - gb : 0;
+        const classN = claim === 'bad' ? bad : claim === 'ok' ? ok : 0;
+        return {
+            grade: g, claims: claim, n: gr.length, bad: gb,
+            bad_rate: enough ? wilson(gb, gr.length) : null,
+            precision: claim && enough ? wilson(right, gr.length) : null,
+            recall: claim && enough && classN > 0 ? wilson(right, classN) : null,
+        };
+    });
+    let tp = 0, fp = 0, fn = 0, tn = 0;
+    for (const r of rows) {
+        const warn = claims[r.grade] === 'bad';
+        if (warn && r.bad)
+            tp++;
+        else if (warn)
+            fp++;
+        else if (r.bad)
+            fn++;
+        else
+            tn++;
+    }
+    return {
+        n, bad, base_rate: wilson(bad, n), by_grade,
+        binary: { tp, fp, fn, tn, precision: tp + fp >= SKILL_MIN_N ? wilson(tp, tp + fp) : null, recall: bad >= SKILL_MIN_N ? wilson(tp, tp + fn) : null, mcc: mcc(tp, fp, fn, tn) },
+    };
+}
+export const LARP_GRADE_ORDER = ['LARP', 'UNVERIFIABLE', 'EARLY_BUT_REAL'];
+export const RUG_GRADE_ORDER = ['AVOID', 'SPECULATIVE', 'WATCH', 'INSUFFICIENT_DATA'];
+function evalSplit(rows, grade, p, claims, order) {
+    return splitMetrics(rows.map((r) => ({ grade: grade(r, p), bad: r.bad })), claims, order);
+}
+const larpGradeOf = (r, rubric) => gradeLinks(r.link, rubric).grade;
+const rugGradeOf = (r, rules) => gradeRugRules(r.rug, rules).grade;
+export function runLarpSubject(set, rubric) {
+    const train = set.rows.filter((r) => r.split === 'train');
+    const test = set.rows.filter((r) => r.split === 'test');
+    return {
+        params: rubric.id,
+        train: evalSplit(train, larpGradeOf, rubric, LARP_GRADE_CLAIMS, LARP_GRADE_ORDER),
+        test: evalSplit(test, larpGradeOf, rubric, LARP_GRADE_CLAIMS, LARP_GRADE_ORDER),
+    };
+}
+export function runRugSubject(set, rules) {
+    const train = set.rows.filter((r) => r.split === 'train');
+    const test = set.rows.filter((r) => r.split === 'test');
+    return {
+        params: rules.id,
+        train: evalSplit(train, rugGradeOf, rules, RUG_GRADE_CLAIMS, RUG_GRADE_ORDER),
+        test: evalSplit(test, rugGradeOf, rules, RUG_GRADE_CLAIMS, RUG_GRADE_ORDER),
+    };
+}
+// ------------------------------------------------------------------------------------------ tuning (train only)
+function assertTrainOnly(rows) {
+    const bad = rows.find((r) => r.split !== 'train');
+    if (bad)
+        throw new Error(`tuning refused: row ${bad.mint.slice(0, 6)}… is in the ${bad.split} split (tune on the train split only)`);
+}
+/** Better = higher MCC; ties go to the simpler parameter set (smaller `cost`). Null MCC never wins. */
+function better(m, cost, best) {
+    if (m === null)
+        return false;
+    if (!best || best.m === null)
+        return true;
+    if (m > best.m + 1e-12)
+        return true;
+    return Math.abs(m - best.m) <= 1e-12 && cost < best.cost;
+}
+/**
+ * Grid-search the link rubric on TRAIN rows: weights 0..2 per signal, threshold 1..5, objective MCC of
+ * LARP → bad. Rows are bucketed by signal mask first, so the 98 k candidates evaluate in well under a second.
+ */
+export function tuneLinkRubric(rows, id = 'larp-links-v1') {
+    assertTrainOnly(rows);
+    const buckets = new Map();
+    for (const r of rows) {
+        const sig = linkSignals(r.link);
+        const key = `${r.link.web === 'none' ? 0 : 1}|${sig.join(',')}`;
+        const b = buckets.get(key) ?? { sig, hasWeb: r.link.web !== 'none', bad: 0, ok: 0 };
+        if (r.bad)
+            b.bad++;
+        else
+            b.ok++;
+        buckets.set(key, b);
+    }
+    const list = [...buckets.values()].map((b) => ({ ...b, idx: b.sig.map((s) => LINK_SIGNALS.indexOf(s)) }));
+    const totalBad = rows.filter((r) => r.bad).length;
+    const totalOk = rows.length - totalBad;
+    const K = LINK_SIGNALS.length;
+    const w = new Array(K).fill(0);
+    let best = null;
+    let candidates = 0;
+    const combos = 3 ** K;
+    for (let c = 0; c < combos; c++) {
+        let x = c;
+        let sum = 0;
+        for (let k = 0; k < K; k++) {
+            w[k] = x % 3;
+            x = Math.floor(x / 3);
+            sum += w[k];
+        }
+        if (sum === 0)
+            continue;
+        for (let t = 1; t <= 5; t++) {
+            candidates++;
+            let tp = 0, fp = 0;
+            for (const b of list) {
+                if (!b.hasWeb)
+                    continue;
+                let s = 0;
+                for (const i of b.idx)
+                    s += w[i];
+                if (s >= t) {
+                    tp += b.bad;
+                    fp += b.ok;
+                }
+            }
+            const m = mcc(tp, fp, totalBad - tp, totalOk - fp);
+            if (better(m, sum * 10 + t, best))
+                best = { m, cost: sum * 10 + t, w: w.slice(), t };
+        }
+    }
+    const weights = Object.fromEntries(LINK_SIGNALS.map((s, i) => [s, best ? best.w[i] : 0]));
+    return {
+        rubric: { id, weights, threshold: best?.t ?? 99, provenance: `tuned on ${rows.length} train rows (MCC ${best?.m?.toFixed(3) ?? '—'})` },
+        train_mcc: best?.m ?? null, candidates,
+    };
+}
+export const RUG_GRID = {
+    dev_pct_over: [null, 5, 10, 15, 20, 30],
+    organic_below: [null, 10, 20, 30, 40, 50, 60, 70],
+    top10_over: [null, 20, 30, 40, 50, 60],
+    liq_below: [null, 2_000, 5_000, 10_000, 20_000, 50_000],
+};
+/** Grid-search the tunable rug-check thresholds on TRAIN rows; objective MCC of AVOID ∪ SPECULATIVE → bad. */
+export function tuneRugRules(rows, id = 'rug-rules-v1') {
+    assertTrainOnly(rows);
+    let best = null;
+    let candidates = 0;
+    for (const dev of RUG_GRID.dev_pct_over)
+        for (const org of RUG_GRID.organic_below)
+            for (const top of RUG_GRID.top10_over)
+                for (const liq of RUG_GRID.liq_below) {
+                    candidates++;
+                    const r = { id, dev_pct_over: dev, organic_below: org, top10_over: top, liq_below: liq, provenance: '' };
+                    let tp = 0, fp = 0, fn = 0, tn = 0;
+                    for (const row of rows) {
+                        const warn = RUG_GRADE_CLAIMS[gradeRugRules(row.rug, r).grade] === 'bad';
+                        if (warn && row.bad)
+                            tp++;
+                        else if (warn)
+                            fp++;
+                        else if (row.bad)
+                            fn++;
+                        else
+                            tn++;
+                    }
+                    const cost = [dev, org, top, liq].filter((v) => v !== null).length;
+                    const m = mcc(tp, fp, fn, tn);
+                    if (better(m, cost, best))
+                        best = { m, cost, r };
+                }
+    const rules = best?.r ?? { ...RUG_RULES_V0, id };
+    return { rules: { ...rules, provenance: `tuned on ${rows.length} train rows (MCC ${best?.m?.toFixed(3) ?? '—'})` }, train_mcc: best?.m ?? null, candidates };
+}
+export function skillBacktest(set, opts) {
+    return {
+        schema: SKILL_BACKTEST_SCHEMA,
+        eval: { built_at: set.built_at, horizon_sec: set.horizon_sec, cutoff_t0: set.cutoff_t0, counts: set.counts, label_rule: set.label_rule, evidence_rule: set.evidence_rule, split_rule: set.split_rule },
+        larp: { before: runLarpSubject(set, opts.larpBefore), after: runLarpSubject(set, opts.larpAfter), rubric_before: opts.larpBefore, rubric_after: opts.larpAfter, tuned: opts.tuned?.larp ?? null },
+        rug: { before: runRugSubject(set, opts.rugBefore), after: runRugSubject(set, opts.rugAfter), rules_before: opts.rugBefore, rules_after: opts.rugAfter, tuned: opts.tuned?.rug ?? null },
+        not_measured: [
+            'larp-check model stage (fetch_page / check_domain / check_github and the model\'s judgement): pages from the past cannot be re-fetched as they were; measured forward only via `dexterm backtest --subject larp` once ≥ 50 recorded verdicts match an outcome',
+            'rug-check model output (rug_probability, bias): measured forward via `--subject pack_verdicts` from recorded verdicts',
+            'trench-scan: no per-token labelled outcome',
+        ],
+        method: [
+            `eval set: ${set.counts.rows} coins from this machine's recorder (${set.counts.train} train / ${set.counts.test} test), one row per coin`,
+            `labels: ${set.label_rule}`,
+            `evidence: ${set.evidence_rule}`,
+            `split: ${set.split_rule}`,
+            'tuning: grid search on the train split only (the code refuses test rows); objective MCC of warning grade → bad; ties go to the simpler setting',
+            `rates: 95% Wilson intervals; a grade with fewer than ${SKILL_MIN_N} rows prints counts only`,
+            'meaning: agreement between a grade and a bad price outcome; a risk flag, not a certificate, and not a measure of whether a product is real',
+        ],
+    };
+}
+const pct = (r) => (r === null ? '—' : `${(r.value * 100).toFixed(1)}% [${(r.lo * 100).toFixed(0)}–${(r.hi * 100).toFixed(0)}]`);
+function splitLines(name, m) {
+    const L = [`    ${name}: n=${m.n}  bad=${m.bad}  base rate ${pct(m.base_rate)}  MCC ${m.binary.mcc === null ? '—' : m.binary.mcc.toFixed(3)}  (tp ${m.binary.tp} fp ${m.binary.fp} fn ${m.binary.fn} tn ${m.binary.tn})`];
+    for (const g of m.by_grade) {
+        L.push(`      ${g.grade.padEnd(17)} n=${String(g.n).padEnd(4)} bad=${String(g.bad).padEnd(4)} P(bad)=${pct(g.bad_rate).padEnd(18)} ${g.claims ? `claims ${g.claims.padEnd(3)} precision=${pct(g.precision).padEnd(18)} recall=${pct(g.recall)}` : 'claims nothing'}`);
+    }
+    return L;
+}
+export function renderSkillBacktestText(r) {
+    const L = [];
+    L.push(`SKILL BACKTEST  horizon=${r.eval.horizon_sec}s  eval built ${r.eval.built_at}  rows ${r.eval.counts.rows} (train ${r.eval.counts.train} · test ${r.eval.counts.test})`);
+    L.push('');
+    L.push(`larp-check · links-only baseline  before=${r.larp.rubric_before.id}  after=${r.larp.rubric_after.id}${r.larp.tuned ? `  (tuned: train MCC ${r.larp.tuned.train_mcc?.toFixed(3) ?? '—'}, ${r.larp.tuned.candidates} candidates)` : ''}`);
+    L.push('  before');
+    L.push(...splitLines('train', r.larp.before.train));
+    L.push(...splitLines('TEST ', r.larp.before.test));
+    L.push('  after');
+    L.push(...splitLines('train', r.larp.after.train));
+    L.push(...splitLines('TEST ', r.larp.after.test));
+    L.push('');
+    L.push(`rug-check · verdict rules  before=${r.rug.rules_before.id}  after=${r.rug.rules_after.id}${r.rug.tuned ? `  (tuned: train MCC ${r.rug.tuned.train_mcc?.toFixed(3) ?? '—'}, ${r.rug.tuned.candidates} candidates)` : ''}`);
+    L.push('  before');
+    L.push(...splitLines('train', r.rug.before.train));
+    L.push(...splitLines('TEST ', r.rug.before.test));
+    L.push('  after');
+    L.push(...splitLines('train', r.rug.after.train));
+    L.push(...splitLines('TEST ', r.rug.after.test));
+    L.push('');
+    L.push('not measured:');
+    for (const m of r.not_measured)
+        L.push(`  - ${m}`);
+    L.push('method:');
+    for (const m of r.method)
+        L.push(`  - ${m}`);
+    return L.join('\n') + '\n';
+}

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>