dexterm-cli 0.1.1 → 0.1.2

package/dist/packages/cli/src/mcp-cmd.js

@@ -0,0 +1,326 @@
+// `dexterm mcp …` — the read-only MCP server plus one-command setup for any agent (task-1405).
+//
+//   dexterm mcp                         run the read-only MCP server on stdio (what the analyst uses and
+//                                       what `claude mcp add dexterm -- dexterm mcp` wires up)
+//   dexterm mcp install <client>        write/print the MCP config for a client (claude-code, claude-desktop,
+//                                       cursor, codex, openclaw, generic). Shows the exact change, asks first,
+//                                       is idempotent, and backs the file up before editing.
+//   dexterm mcp doctor                  spawn the server over stdio, do the MCP handshake, and list the tools,
+//                                       prompts and resources the agent sees — proof the connection works.
+//
+// install writes nothing without consent: it prints the target file and the exact snippet, then (unless
+// --yes) asks on a TTY; a non-TTY run without --yes prints the plan and stops. --print never writes. The
+// config dir is resolved from the environment; --config FILE overrides it (tests point this at a temp dir),
+// so this command NEVER has to touch the real ~/.claude, Cursor or Claude Desktop config to be exercised.
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import readline from 'node:readline';
+function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
+function has(rest, name) { return rest.includes(name); }
+export function defaultCommand(env, useNode) {
+    if (!useNode)
+        return { command: 'dexterm', args: ['mcp'] };
+    // Fallback for when dexterm is not on PATH: run this repo's server bin with the current node.
+    return { command: process.execPath, args: [mcpBinPath(), 'mcp'] };
+}
+/** Where this repo's standalone MCP server bin lives (used by the --node command and by `doctor`). */
+export function mcpBinPath() {
+    const here = dirname(fileURLToPath(import.meta.url)); // packages/cli/src
+    return resolve(here, '..', '..', 'mcp', 'bin', 'dexterm-mcp.mjs');
+}
+function home(env) { return env.HOME || env.USERPROFILE || homedir(); }
+function appSupport(env, platform, app) {
+    if (platform === 'darwin')
+        return join(home(env), 'Library', 'Application Support', app);
+    if (platform === 'win32')
+        return join(env.APPDATA || join(home(env), 'AppData', 'Roaming'), app);
+    return join(env.XDG_CONFIG_HOME || join(home(env), '.config'), app);
+}
+export const CLIENTS = [
+    {
+        id: 'claude-code', label: 'Claude Code', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(env.DEXTERM_CWD || process.cwd(), '.mcp.json'),
+        note: 'project-scoped .mcp.json in the current directory; or run `claude mcp add dexterm -- dexterm mcp`.',
+    },
+    {
+        id: 'claude-desktop', label: 'Claude Desktop', format: 'json', keyPath: 'mcpServers',
+        path: (env, platform) => join(appSupport(env, platform, 'Claude'), 'claude_desktop_config.json'),
+        note: 'restart Claude Desktop after editing so it re-reads the config.',
+    },
+    {
+        id: 'cursor', label: 'Cursor', format: 'json', keyPath: 'mcpServers',
+        path: (env) => join(home(env), '.cursor', 'mcp.json'),
+        note: 'global Cursor MCP config (~/.cursor/mcp.json); a project .cursor/mcp.json works too.',
+    },
+    {
+        id: 'codex', label: 'Codex CLI', format: 'toml', keyPath: 'mcp_servers',
+        path: (env) => join(env.CODEX_HOME || join(home(env), '.codex'), 'config.toml'),
+        note: 'Codex reads MCP servers from the [mcp_servers.*] tables in ~/.codex/config.toml.',
+    },
+    {
+        id: 'openclaw', label: 'OpenClaw / generic agent', format: 'print', keyPath: 'mcpServers',
+        path: () => null,
+        note: 'OpenClaw and most agents take a standard mcpServers entry; paste this where your agent reads MCP servers, or pass --config FILE to write a JSON file.',
+    },
+    {
+        id: 'generic', label: 'Generic (print the snippet)', format: 'print', keyPath: 'mcpServers',
+        path: () => null,
+        note: 'the standard stdio MCP server entry; add it to your client\'s MCP config.',
+    },
+];
+export function clientById(id) { return CLIENTS.find((c) => c.id === id); }
+/** The JSON object a json-format client expects under its server map, for `dexterm`. */
+export function serverEntryJson(cmd) {
+    return { command: cmd.command, args: cmd.args };
+}
+/** The TOML block a codex-style client expects. */
+export function serverEntryToml(cmd) {
+    const args = cmd.args.map((a) => JSON.stringify(a)).join(', ');
+    return `[mcp_servers.dexterm]\ncommand = ${JSON.stringify(cmd.command)}\nargs = [${args}]\n`;
+}
+/** Plan a JSON merge: returns the new file text and whether anything changes. Preserves every other key. */
+export function planJson(existingText, keyPath, entry) {
+    let obj = {};
+    if (existingText && existingText.trim()) {
+        try {
+            const parsed = JSON.parse(existingText);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                obj = parsed;
+        }
+        catch {
+            throw new Error('the existing config is not valid JSON — fix or move it, then re-run');
+        }
+    }
+    const map = (obj[keyPath] && typeof obj[keyPath] === 'object' && !Array.isArray(obj[keyPath])) ? obj[keyPath] : {};
+    const prev = map.dexterm;
+    const was = prev === undefined ? 'absent' : JSON.stringify(prev) === JSON.stringify(entry) ? 'same' : 'different';
+    const next = { ...obj, [keyPath]: { ...map, dexterm: entry } };
+    return { text: JSON.stringify(next, null, 2) + '\n', changed: was !== 'same', was };
+}
+/** Plan a TOML merge: append the dexterm block when there is no [mcp_servers.dexterm] yet; never clobber. */
+export function planToml(existingText, block) {
+    const cur = existingText ?? '';
+    if (cur.includes(block.trim()))
+        return { text: cur, changed: false, was: 'same', conflict: false };
+    if (/\[mcp_servers\.dexterm\]/.test(cur))
+        return { text: cur, changed: false, was: 'different', conflict: true };
+    const sep = cur.length && !cur.endsWith('\n\n') ? (cur.endsWith('\n') ? '\n' : '\n\n') : '';
+    return { text: cur + sep + block, changed: true, was: 'absent', conflict: false };
+}
+function readLineYesNo(io, prompt) {
+    const stdin = io.stdin;
+    if (!stdin || !stdin.isTTY)
+        return Promise.resolve(false);
+    return new Promise((res) => {
+        const rl = readline.createInterface({ input: stdin, output: io.stdout });
+        rl.question(prompt, (ans) => { rl.close(); res(/^y(es)?$/i.test(ans.trim())); });
+    });
+}
+function backupPath(file) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return `${file}.bak-${stamp}`;
+}
+async function install(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    const id = rest.find((a) => !a.startsWith('-'));
+    const spec = id ? clientById(id) : undefined;
+    if (!spec) {
+        errOut(`usage: dexterm mcp install <${CLIENTS.map((c) => c.id).join('|')}> [--config FILE] [--print] [--node] [--yes]`);
+        if (id)
+            errOut(`unknown client "${id}". known: ${CLIENTS.map((c) => c.id).join(', ')}`);
+        return 2;
+    }
+    const printOnly = has(rest, '--print');
+    const useNode = has(rest, '--node');
+    const yes = has(rest, '--yes') || has(rest, '-y');
+    const cmd = defaultCommand(io.env, useNode);
+    const override = flag(rest, '--config');
+    const target = override ? resolve(override) : spec.path(io.env, process.platform);
+    const forcePrint = spec.format === 'print' && !override;
+    // The snippet we would add, always shown.
+    const snippet = spec.format === 'toml' ? serverEntryToml(cmd) : JSON.stringify({ [spec.keyPath]: { dexterm: serverEntryJson(cmd) } }, null, 2);
+    out(`dexterm MCP server for ${spec.label}:`);
+    out('');
+    out(indent(snippet));
+    out('');
+    if (spec.note)
+        out(`note: ${spec.note}`);
+    if (printOnly || forcePrint) {
+        if (forcePrint && !printOnly)
+            out('(this client has no single well-known config file — paste the snippet above, or pass --config FILE to write it.)');
+        return 0;
+    }
+    if (!target) {
+        out('pass --config FILE to write this to a specific file.');
+        return 0;
+    }
+    const existed = existsSync(target);
+    const existingText = existed ? readFileSync(target, 'utf8') : null;
+    let plan;
+    try {
+        plan = spec.format === 'toml'
+            ? planToml(existingText, serverEntryToml(cmd))
+            : planJson(existingText, spec.keyPath, serverEntryJson(cmd));
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: ${e.message} (${target})`);
+        return 1;
+    }
+    out('');
+    out(`target: ${target}${existed ? '' : ' (new file)'}`);
+    if (plan.conflict) {
+        out('a [mcp_servers.dexterm] section already exists and differs; not modifying it. Review it by hand, or edit it to match the snippet above.');
+        return 0;
+    }
+    if (!plan.changed) {
+        out('already configured — nothing to change (idempotent).');
+        return 0;
+    }
+    out(plan.was === 'different' ? 'this UPDATES the existing dexterm entry.' : existed ? 'this ADDS a dexterm entry (your other servers are preserved).' : 'this CREATES the config file with a dexterm entry.');
+    if (!yes) {
+        const ok = await readLineYesNo(io, 'write this change? [y/N] ');
+        if (!ok) {
+            out(io.stdin?.isTTY ? 'cancelled; nothing was written.' : 'not a TTY and --yes was not given; nothing written. Re-run with --yes to write, or --print to just print.');
+            return io.stdin?.isTTY ? 0 : 0;
+        }
+    }
+    try {
+        mkdirSync(dirname(target), { recursive: true });
+        if (existed) {
+            const bak = backupPath(target);
+            copyFileSync(target, bak);
+            out(`backed up: ${bak}`);
+        }
+        writeFileSync(target, plan.text, { mode: 0o600 });
+        out(`wrote ${target}.`);
+        out(`verify it: dexterm mcp doctor`);
+        return 0;
+    }
+    catch (e) {
+        errOut(`dexterm mcp install: could not write ${target}: ${e.message}`);
+        return 1;
+    }
+}
+function indent(s) { return s.split('\n').map((l) => '  ' + l).join('\n'); }
+async function doctor(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    // Prefer the command install writes (`dexterm mcp`); fall back to this repo's node bin when dexterm is
+    // not on PATH (e.g. a dev checkout). Either way this is a real stdio child, not an in-process shortcut.
+    const useNode = has(rest, '--node');
+    const cmd = useNode ? defaultCommand(io.env, true) : { command: 'dexterm', args: ['mcp'] };
+    out(`dexterm mcp doctor — spawning: ${cmd.command} ${cmd.args.join(' ')}`);
+    const result = await probe(cmd, io.env).catch((e) => ({ error: e.message }));
+    if ('error' in result && !useNode && /ENOENT|not found|spawn/i.test(result.error)) {
+        // dexterm not on PATH: retry with the bundled node bin so doctor still verifies the server.
+        out(`(dexterm not on PATH; retrying with this checkout's server)`);
+        const fallback = defaultCommand(io.env, true);
+        out(`dexterm mcp doctor — spawning: ${fallback.command} ${fallback.args.join(' ')}`);
+        const r2 = await probe(fallback, io.env).catch((e) => ({ error: e.message }));
+        return report(r2, out, errOut);
+    }
+    return report(result, out, errOut);
+}
+function report(r, out, errOut) {
+    if ('error' in r) {
+        errOut(`✗ could not reach the MCP server: ${r.error}`);
+        return 1;
+    }
+    const info = r.serverInfo;
+    out(`✓ connected to ${info?.name ?? 'dexterm'} ${info?.version ?? ''} over stdio (MCP initialize ok)`);
+    out(`tools (${r.tools.length}): ${r.tools.join(', ')}`);
+    out(`prompts/skills (${r.prompts.length}): ${r.prompts.join(', ') || '(none)'}`);
+    out(`resources: ${r.resources}`);
+    out('the connection works; add it to your agent with `dexterm mcp install <client>`.');
+    return 0;
+}
+function probe(cmd, env) {
+    return new Promise((res, rej) => {
+        const child = spawn(cmd.command, cmd.args, { stdio: ['pipe', 'pipe', 'pipe'], env: { ...env, DEXTERM_OFFLINE: '1', NO_COLOR: '1' } });
+        const timer = setTimeout(() => { try {
+            child.kill();
+        }
+        catch { /* ignore */ } rej(new Error('timed out waiting for the server (10s)')); }, 10_000);
+        let stderr = '';
+        child.on('error', (e) => { clearTimeout(timer); rej(e); });
+        child.stderr.on('data', (d) => { stderr += String(d); });
+        const rl = readline.createInterface({ input: child.stdout });
+        const pending = new Map();
+        let seq = 0;
+        const send = (method, params) => {
+            const id = ++seq;
+            const msg = { jsonrpc: '2.0', id, method, ...(params ? { params } : {}) };
+            return new Promise((r) => { pending.set(id, r); child.stdin.write(JSON.stringify(msg) + '\n'); });
+        };
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (typeof msg.id === 'number' && pending.has(msg.id)) {
+                const r = pending.get(msg.id);
+                pending.delete(msg.id);
+                r(msg.result ?? {});
+            }
+        });
+        (async () => {
+            try {
+                const init = await send('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'dexterm-doctor', version: '1' } });
+                const toolsRes = await send('tools/list');
+                const promptsRes = await send('prompts/list');
+                const resRes = await send('resources/list');
+                clearTimeout(timer);
+                try {
+                    child.stdin.end();
+                }
+                catch { /* ignore */ }
+                try {
+                    child.kill();
+                }
+                catch { /* ignore */ }
+                const tools = Array.isArray(toolsRes.tools) ? toolsRes.tools.map((t) => String(t.name)) : [];
+                const prompts = Array.isArray(promptsRes.prompts) ? promptsRes.prompts.map((p) => String(p.name)) : [];
+                const resources = Array.isArray(resRes.resources) ? resRes.resources.length : 0;
+                res({ serverInfo: init.serverInfo ?? {}, tools, prompts, resources });
+            }
+            catch (e) {
+                clearTimeout(timer);
+                rej(new Error(`${e.message}${stderr ? ` · server stderr: ${stderr.slice(0, 200)}` : ''}`));
+            }
+        })();
+    });
+}
+const USAGE = `dexterm mcp [<command>]
+  (no command)              run the read-only MCP server on stdio (claude mcp add dexterm -- dexterm mcp)
+  install <client>          write/print the MCP config for a client and verify what changes
+                            clients: ${CLIENTS.map((c) => c.id).join(', ')}
+                            --config FILE  write to a specific file (instead of the client's default)
+                            --print        only print the snippet, never write
+                            --node         emit a "node <path> mcp" command (when dexterm is not on PATH)
+                            --yes          write without the confirmation prompt
+  doctor                    spawn the server, do the MCP handshake, and list the tools/prompts/resources`;
+/** `dexterm mcp …`. With no subcommand (or an arg the server consumes, e.g. --replay) it runs the server. */
+export async function runMcp(rest, io) {
+    const sub = rest[0];
+    if (sub === 'install')
+        return install(rest.slice(1), io);
+    if (sub === 'doctor')
+        return doctor(rest.slice(1), io);
+    if (sub === 'help' || sub === '--help' || sub === '-h') {
+        io.stdout.write(USAGE + '\n');
+        return 0;
+    }
+    // Anything else (no args, or server flags like --replay) → the stdio server, unchanged.
+    const { runStdioServer } = await import('../../mcp/src/index.js');
+    await runStdioServer({ argv: rest });
+    return 0;
+}

package/dist/packages/cli/src/rules.js

@@ -1,4 +1,5 @@
 import { RulesEngine, ruleToJson, ruleToText, slug, applyAndJournal, describeActions, } from '../../custom/src/index.js';
+import { alertToDelivery, proposalToDelivery } from "./alerts/format.js";
 export const RULE_INPUT_MAX = 400;
 /** The engine observes/evaluates at most this often (the feed itself moves every 10 s; fixtures drift every tick). */
 export const RULES_TICK_MS = 2_000;
@@ -8,8 +9,11 @@ export function newRulesUi(engine = new RulesEngine()) {
     return {
         engine, errors: [], pane: 'rules', selected: 0, selectedProposal: 0, input: null, editingId: null, dry: null, notice: null,
         log: [], proposals: [], pending: { popups: [], bells: 0, ask: null, ticket: null }, lastTickAt: 0, nextId: 1, fires: 0,
+        pendingDeliveries: [],
     };
 }
+/** Cap on the push-delivery backlog (a long run with no notifier should never grow unbounded). */
+const MAX_DELIVERIES = 100;
 /**
  * Build the engine from `config.rules` plus the rules of installed packs (task-1358 Tier 4: a pack rule whose id the
  * user already has in config.rules is shadowed by the user's copy). Bad rules are reported, good ones run. Never throws.
@@ -33,7 +37,18 @@ export function rulesUiOf(state) {
         state.rulesUi = initRules(state.custom, state.now.getTime());
     return state.rulesUi;
 }
-/** The rows a rule can see: the screener feed (no skeletons) with the wallet-intel top-cluster share attached when the scan ran. */
+/**
+ * task-1398: LARP-detector grade as a number so a grade change is a rule (`larp.delta`). Higher = more real.
+ * The string verdict is only known here (cli); the engine sees the number. `null` for no verdict (clause false).
+ */
+export const LARP_GRADES = { REAL_PRODUCT: 3, EARLY_BUT_REAL: 2, UNVERIFIABLE: 1, LARP: 0 };
+export function larpGrade(verdict) {
+    if (!verdict)
+        return null;
+    const g = LARP_GRADES[verdict];
+    return g === undefined ? null : g;
+}
+/** The rows a rule can see: the screener feed (no skeletons) with the wallet-intel top-cluster share and the LARP grade attached. */
 export function ruleRowsOf(state) {
     const out = [];
     const seen = new Set();
@@ -48,7 +63,7 @@ export function ruleRowsOf(state) {
         if (!r.mint || r.skeleton || seen.has(r.mint))
             continue;
         seen.add(r.mint);
-        out.push(Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint) }));
+        out.push(Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict) }));
     }
     return out;
 }
@@ -91,6 +106,8 @@ function applyOutputs(state, ui, res, rows, now) {
             if (a.kind === 'alert') {
                 push({ ...base, kind: 'alert', level: a.level, text: a.text });
                 summary.alerts.push(`${f.symbol}: ${a.text}`);
+                if (ui.pendingDeliveries.length < MAX_DELIVERIES)
+                    ui.pendingDeliveries.push(alertToDelivery(a));
             }
             else if (a.kind === 'proposal') {
                 const card = a.type === 'ticket'
@@ -99,6 +116,8 @@ function applyOutputs(state, ui, res, rows, now) {
                 ui.proposals.unshift(card);
                 if (ui.proposals.length > MAX_PROPOSALS)
                     ui.proposals.length = MAX_PROPOSALS;
+                if (ui.pendingDeliveries.length < MAX_DELIVERIES)
+                    ui.pendingDeliveries.push(proposalToDelivery(a));
                 summary.proposals += 1;
                 push({ ...base, kind: 'proposal', level: 'info', text: `PROPOSAL ${describeCard(card)} — ctrl+r, tab, ⏎ to act (you confirm there)` });
             }

package/dist/packages/cli/src/skill-eval-build.js

@@ -0,0 +1,109 @@
+// Build the skill backtest eval set from a recorder DB (task-1401). Read-only on the DB, no network.
+//
+// One row per coin. The label is the recorder's own outcome at the horizon (keyless proxy). The link evidence is
+// the DexScreener / Jupiter token record the app's cache already holds (ns `ds:token` / `jup:token`), used ONLY
+// when that record was fetched within `maxLagSec` AFTER the row's t0 anchor: the cache keeps the newest fetch per
+// coin, and a coin that kept trading was re-fetched long after t0 (when it may have bought a DexScreener profile),
+// while a coin that died stopped being fetched near t0. Taking a late record would leak the outcome into the
+// evidence, so a coin with no record inside the window is excluded and counted, never back-filled.
+//
+// The rows keep the mint, t0, the label, URL-free link features and the t0 snapshot numbers. No URL, name or
+// symbol is written (the name and symbol are read only to compute the domain-match boolean).
+import { linkFeatures } from '../../data/src/index.js';
+import { LABELER_VERSION } from '../../recorder/src/index.js';
+import { SKILL_EVAL_SCHEMA } from '../../packs/src/index.js';
+function readCache(db, ns, mint) {
+    const row = db.prepare('SELECT json, fetched_at FROM cache WHERE ns = ? AND key = ?').get(ns, mint);
+    if (!row)
+        return null;
+    try {
+        const j = JSON.parse(row.json);
+        const s = j.token?.socials ?? {};
+        return { fetched_at: Number(row.fetched_at), socials: { web: s.web ?? null, x: s.x ?? null, tg: s.tg ?? null }, symbol: j.token?.symbol ?? null, name: j.token?.name ?? null };
+    }
+    catch {
+        return null;
+    }
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const bool = (v) => (v === null || v === undefined ? null : Number(v) !== 0);
+export function buildSkillEvalSet(db, opts = {}) {
+    const horizon = opts.horizonSec ?? 259_200;
+    const lagMs = (opts.maxLagSec ?? 3_600) * 1000;
+    const testFrac = opts.testFrac ?? 0.3;
+    const excluded = { no_cached_link_record: 0, no_point_in_time_link_record: 0, no_t0_snapshot: 0, chain_verified_label: 0 };
+    const mints = db.prepare("SELECT DISTINCT mint FROM outcomes WHERE horizon_sec = ? AND label != 'unobserved'").all(horizon).map((r) => r.mint);
+    const outStmt = db.prepare("SELECT t0, label, label_tier FROM outcomes WHERE mint = ? AND horizon_sec = ? AND label != 'unobserved' ORDER BY t0 DESC");
+    const snapStmt = db.prepare('SELECT * FROM token_snapshots WHERE mint = ? AND t = ? AND is_t0 = 1 LIMIT 1');
+    const rows = [];
+    for (const mint of mints) {
+        const ds = readCache(db, 'ds:token', mint);
+        const jup = readCache(db, 'jup:token', mint);
+        if (!ds && !jup) {
+            excluded.no_cached_link_record++;
+            continue;
+        }
+        const outs = outStmt.all(mint, horizon);
+        let picked = null;
+        for (const o of outs) {
+            const t0 = Number(o.t0);
+            const srcs = [['jupiter', jup], ['dexscreener', ds]]
+                .filter((x) => !!x[1] && x[1].fetched_at >= t0 && x[1].fetched_at <= t0 + lagMs);
+            if (srcs.length) {
+                picked = { t0, label: o.label, label_tier: o.label_tier, srcs };
+                break;
+            }
+        }
+        if (!picked) {
+            excluded.no_point_in_time_link_record++;
+            continue;
+        }
+        if (picked.label_tier !== 'keyless-proxy') {
+            excluded.chain_verified_label++;
+            continue;
+        }
+        const snap = snapStmt.get(mint, picked.t0);
+        if (!snap) {
+            excluded.no_t0_snapshot++;
+            continue;
+        }
+        // The store's merge order: Jupiter first, then DexScreener (packages/data/src/store.ts).
+        const pick = (k) => picked.srcs.map(([, r]) => r.socials[k]).find((v) => v) ?? null;
+        const symbol = picked.srcs.map(([, r]) => r.symbol).find((v) => v) ?? snap.symbol;
+        const name = picked.srcs.map(([, r]) => r.name).find((v) => v) ?? snap.name;
+        const createdAt = num(snap.created_at);
+        rows.push({
+            mint, t0: picked.t0, split: 'train',
+            outcome: picked.label, bad: picked.label === 'rug' || picked.label === 'dead',
+            link: linkFeatures({ web: pick('web'), x: pick('x'), tg: pick('tg'), symbol, name }),
+            link_sources: picked.srcs.map(([s]) => s),
+            link_lag_sec: Math.round((Math.max(...picked.srcs.map(([, r]) => r.fetched_at)) - picked.t0) / 1000),
+            rug: {
+                freeze_auth: bool(snap.freeze_auth_enabled), mint_auth: bool(snap.mint_auth_enabled),
+                dev_pct: num(snap.dev_pct), top10_pct: num(snap.top_holders_pct), organic_score: num(snap.organic_score),
+                liquidity_usd: num(snap.liquidity_usd), price_usd: num(snap.price_usd), lp_locked_pct: num(snap.lp_locked_pct),
+                launchpad: snap.launchpad ?? null,
+                age_sec: createdAt ? Math.max(0, Math.round((picked.t0 - createdAt) / 1000)) : null,
+            },
+        });
+    }
+    rows.sort((a, b) => a.t0 - b.t0 || a.mint.localeCompare(b.mint));
+    const cutIdx = Math.min(rows.length, Math.floor(rows.length * (1 - testFrac)));
+    const cutoff = rows[cutIdx]?.t0 ?? Number.MAX_SAFE_INTEGER;
+    for (const r of rows)
+        r.split = r.t0 >= cutoff ? 'test' : 'train';
+    const train = rows.filter((r) => r.split === 'train');
+    const test = rows.filter((r) => r.split === 'test');
+    return {
+        schema: SKILL_EVAL_SCHEMA,
+        built_at: new Date(opts.now ?? Date.now()).toISOString(),
+        source: { kind: 'recorder', labeler_version: LABELER_VERSION, db_note: 'the app history DB on the machine that built it (outcomes + cache + token_snapshots); not shipped' },
+        horizon_sec: horizon,
+        label_rule: `recorder outcome at ${horizon}s (keyless proxy, labeler ${LABELER_VERSION}); bad = rug ∪ dead, ok = flat ∪ fade ∪ runner; unobserved dropped`,
+        evidence_rule: `link features from the cached DexScreener/Jupiter token record only when it was fetched within ${lagMs / 1000}s after the row's t0 (latest such t0 per coin); rug-check features from that t0 snapshot`,
+        split_rule: `by time: the latest ${Math.round(testFrac * 100)}% of rows by t0 (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST split, fixed before tuning`,
+        cutoff_t0: cutoff,
+        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, excluded },
+        rows,
+    };
+}