dexterm-cli 0.2.0 → 0.2.2

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

@@ -0,0 +1,361 @@
+// task-1822: `dexterm classifier …`: pick and manage the classification model (Kev local, hosted Jev with your own
+// key, JEV students, LLM baselines, or the built-in heuristic). Outputs are model estimates, never advice.
+// Nothing downloads without a typed yes (or --yes) for that model; nothing calls the network without a key/consent.
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { CATALOG, COIN_RISK, EXTERNAL_MODELS, PROVIDERS, PROVIDER_IDS, catalogEntry, classify, classifyBatch, coinDossier, describeHardware, describeResult, detectHardware, dextermHome, fits, freeBytes, fromReasonRunner, gb, isInstalled, loadClassifierConfig, modelPath, modelsDir, providerFromConfig, pullModel, readTypesafeKey, recommendTier, removeTypesafeKey, saveClassifierConfig, serveArgv, typesafeKeyRefusal, typesafeKeyState, writeTypesafeKey, } from '../../classifier/src/index.js';
+import { spawnClaudeRunner } from '../../packs/src/index.js';
+export const CLASSIFIER_USAGE = `dexterm classifier [<command>]
+  list                      providers, local models (installed / size / licence / fits this machine) and the current pick
+  pick <provider> [model]   heuristic | kev-local [kev-0.8b-q8|kev-4b-q4|…] | jev-hosted | jev-open | claude | ollama-llm
+  pull <model> [--yes]      download a Kev GGUF (shows size + source, asks first, checks disk, verifies sha256)
+  serve [--model M] [--port P] [--threads N]   run llama-server for the picked Kev model on 127.0.0.1 (foreground)
+  doctor [--json]           hardware (RAM, CPU, GPU/VRAM), the recommended tier, provider readiness
+  bench [--n 20]            time the current provider on N synthetic coins (latency per coin, per 1,000)
+  try                       classify one example coin with the current provider (shows the labelled estimate)
+  key set|clear|status      your own TypeSafe API key for hosted Jev (stored owner-only under ~/.dexterm/keys, never printed)
+Every answer is a model estimate with the model id and a calibration note; never advice. Docs: /docs/classifier/`;
+function flags(argv, bools) {
+    const pos = [];
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const k = a.slice(2);
+            if (bools.includes(k) || i + 1 >= argv.length)
+                opts[k] = true;
+            else
+                opts[k] = argv[++i];
+        }
+        else
+            pos.push(a);
+    }
+    return { pos, opts };
+}
+const keyLine = (s) => s.source === 'refused' ? 'refused (dexterm classifier key status says why; TYPESAFE_API_KEY works instead)' : s.source === 'none' ? 'none (hosted Jev is optional)' : 'configured';
+async function ask(io, question) {
+    if (!io.stdin.isTTY)
+        return '';
+    const rl = readline.createInterface({ input: io.stdin, output: io.stdout });
+    try {
+        return await new Promise((r) => rl.question(question, r));
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Read a secret from the TTY without echoing it. Non-TTY: read one line from stdin (for `… | dexterm classifier key set`). */
+async function readSecret(io, prompt) {
+    if (!io.stdin.isTTY) {
+        let s = '';
+        for await (const c of io.stdin) {
+            s += c.toString();
+            if (s.includes('\n'))
+                break;
+        }
+        return s.split('\n')[0];
+    }
+    io.stdout.write(prompt);
+    const stdin = io.stdin;
+    stdin.setRawMode?.(true);
+    stdin.resume();
+    return await new Promise((resolve) => {
+        let s = '';
+        const on = (b) => {
+            for (const ch of b.toString('utf8')) {
+                if (ch === '\r' || ch === '\n' || ch === '\u0004') {
+                    stdin.off('data', on);
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                    io.stdout.write('\n');
+                    resolve(s);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    stdin.off('data', on);
+                    stdin.setRawMode?.(false);
+                    stdin.pause();
+                    io.stdout.write('\n');
+                    resolve('');
+                    return;
+                }
+                if (ch === '\u007f')
+                    s = s.slice(0, -1);
+                else
+                    s += ch;
+            }
+        };
+        stdin.on('data', on);
+    });
+}
+function deps(c, io) {
+    return { env: io.env, fetch: io.fetch, claudeRunner: fromReasonRunner(spawnClaudeRunner, c.llm.claudeModel) };
+}
+/** Where llama-server is: $DEXTERM_LLAMA_SERVER, else on PATH. */
+export function llamaServerBin(env) {
+    if (env.DEXTERM_LLAMA_SERVER && fs.existsSync(env.DEXTERM_LLAMA_SERVER))
+        return env.DEXTERM_LLAMA_SERVER;
+    for (const dir of (env.PATH ?? '').split(path.delimiter)) {
+        const p = path.join(dir, 'llama-server');
+        try {
+            fs.accessSync(p, fs.constants.X_OK);
+            return p;
+        }
+        catch { /* next */ }
+    }
+    return null;
+}
+/**
+ * Does this llama-server serve decision models (`/v1/systemone`, llama.cpp PR #29818, 2026-10-02)? Older builds (e.g.
+ * Homebrew's 0.4.1) start fine and then 404 every request, so `serve` and `doctor` check the help text first.
+ */
+export async function llamaSupportsDecisions(bin, exec) {
+    const run = exec ?? ((cmd, args) => new Promise((resolve) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        const t = setTimeout(() => child.kill('SIGKILL'), 8000);
+        child.stdout.on('data', (d) => (out += d));
+        child.stderr.on('data', (d) => (out += d));
+        child.on('error', () => { clearTimeout(t); resolve(''); });
+        child.on('close', () => { clearTimeout(t); resolve(out); });
+    }));
+    try {
+        return /decision/i.test(await run(bin, ['--help']));
+    }
+    catch {
+        return false;
+    }
+}
+const LLAMA_TOO_OLD = 'this llama-server has no /v1/systemone (decision models need a llama.cpp build from 2026-10-02 or later): update llama.cpp, or point DEXTERM_LLAMA_SERVER at a newer llama-server';
+export async function classifierCommand(argv, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const err = (s) => io.stderr.write(s + '\n');
+    const loaded = loadClassifierConfig(io.env);
+    for (const e of loaded.errors)
+        err(`classifier.json: ${e}`);
+    const c = loaded.config;
+    const home = dextermHome(io.env);
+    const sub = argv[0] ?? 'list';
+    const { pos, opts } = flags(argv.slice(1), ['yes', 'json']);
+    if (sub === 'help' || sub === '--help' || sub === '-h') {
+        out(CLASSIFIER_USAGE);
+        return 0;
+    }
+    if (sub === 'list') {
+        const hw = await detectHardware({ exec: io.exec });
+        out(`current: ${c.provider}${c.provider === 'kev-local' ? ` (${c.kev.model})` : ''} · shipped default model: ${c.default}`);
+        out('\nproviders:');
+        for (const p of PROVIDERS)
+            out(`  ${p.id.padEnd(11)} ${p.title}  [network: ${p.network}; needs ${p.needs}]`);
+        out('\nlocal models (llama.cpp GGUF, pinned revisions, sha256-verified):');
+        for (const e of CATALOG) {
+            const inst = isInstalled(home, e) ? 'installed' : 'not downloaded';
+            out(`  ${e.id.padEnd(12)} ${gb(e.bytes).padStart(7)}  ${e.license}  ${inst.padEnd(14)} ${fits(e.id, hw) ? 'fits this machine' : 'too big for this machine'}  (${e.authorNote})`);
+        }
+        out('\nlisted, not pulled by dexterm:');
+        for (const x of EXTERNAL_MODELS)
+            out(`  ${x.id.padEnd(12)} ${x.repo} (${x.license}): ${x.note}`);
+        return 0;
+    }
+    if (sub === 'pick') {
+        const id = pos[0];
+        if (!id || !PROVIDER_IDS.includes(id)) {
+            err(`pick one of: ${PROVIDER_IDS.join(', ')}`);
+            return 2;
+        }
+        const next = { ...c, provider: id };
+        if (id === 'kev-local') {
+            const model = pos[1] ?? c.kev.model;
+            try {
+                catalogEntry(model);
+            }
+            catch (e) {
+                err(e.message);
+                return 2;
+            }
+            next.kev = { ...c.kev, model };
+            if (!isInstalled(home, catalogEntry(model)))
+                out(`note: ${model} is not downloaded yet: dexterm classifier pull ${model}. Until it is served, answers fall back to the heuristic.`);
+        }
+        if (id === 'jev-hosted' && !readTypesafeKey(io.env, { platform: io.platform, acl: io.acl }))
+            out('note: no TypeSafe key yet: dexterm classifier key set. Until then answers fall back to the heuristic.');
+        const p = saveClassifierConfig(next, io.env);
+        out(`classifier.provider = ${id}${id === 'kev-local' ? ` (${next.kev.model})` : ''}  (${p})`);
+        return 0;
+    }
+    if (sub === 'pull') {
+        const id = pos[0] ?? c.kev.model;
+        let e;
+        try {
+            e = catalogEntry(id);
+        }
+        catch (x) {
+            err(x.message);
+            return 2;
+        }
+        if (isInstalled(home, e)) {
+            out(`${e.id} is already installed: ${modelPath(home, e)}`);
+            return 0;
+        }
+        const free = (io.free ?? freeBytes)(modelsDir(home));
+        out(`${e.title}: ${gb(e.bytes)} from huggingface.co/${e.repo} (revision ${e.revision.slice(0, 8)}, ${e.license}, base ${e.base})`);
+        out(`to ${modelsDir(home)} · ${gb(free)} free · sha256 ${e.sha256.slice(0, 16)}… checked before use`);
+        let yes = opts.yes === true;
+        if (!yes) {
+            const a = (await ask(io, 'Download it now? Type yes to continue: ')).trim().toLowerCase();
+            yes = a === 'yes';
+        }
+        if (!yes) {
+            out('not downloaded (no consent). Re-run with --yes to skip the question.');
+            return 1;
+        }
+        let lastPct = -1;
+        try {
+            const r = await pullModel(e.id, { home, consent: true, fetch: io.pullFetch, free: io.free, onProgress: (d, t) => { const pct = Math.floor((d / t) * 20) * 5; if (pct !== lastPct) {
+                    lastPct = pct;
+                    io.stdout.write(`\r  ${pct}%`);
+                } } });
+            io.stdout.write('\n');
+            saveClassifierConfig({ ...c, consent: { ...c.consent, [e.id]: new Date().toISOString() } }, io.env);
+            out(`verified ${r.sha256.slice(0, 16)}… → ${r.path}`);
+            out(`next: dexterm classifier pick kev-local ${e.id} && dexterm classifier serve`);
+            return 0;
+        }
+        catch (x) {
+            io.stdout.write('\n');
+            err(`pull failed: ${x.message}`);
+            return 1;
+        }
+    }
+    if (sub === 'serve') {
+        const id = typeof opts.model === 'string' ? opts.model : c.kev.model;
+        let e;
+        try {
+            e = catalogEntry(id);
+        }
+        catch (x) {
+            err(x.message);
+            return 2;
+        }
+        if (!isInstalled(home, e)) {
+            err(`${id} is not downloaded: dexterm classifier pull ${id}`);
+            return 1;
+        }
+        const bin = llamaServerBin(io.env);
+        if (!bin) {
+            err('llama-server not found. Install llama.cpp (a build with /v1/systemone, 2026-10-02 or later) or set DEXTERM_LLAMA_SERVER.');
+            return 1;
+        }
+        if (!(await llamaSupportsDecisions(bin, io.exec))) {
+            err(LLAMA_TOO_OLD);
+            return 1;
+        }
+        const port = Number(typeof opts.port === 'string' ? opts.port : new URL(c.kev.endpoint).port || 8031);
+        const threads = typeof opts.threads === 'string' ? Number(opts.threads) : c.kev.threads ?? undefined;
+        const args = serveArgv(e, modelPath(home, e), port, threads);
+        out(`serving ${e.id} on http://127.0.0.1:${port} (Ctrl+C to stop): ${path.basename(bin)} ${args.join(' ')}`);
+        return await new Promise((resolve) => {
+            const child = spawn(bin, args, { stdio: 'inherit' });
+            child.on('error', (x) => { err(`llama-server: ${x.message}`); resolve(1); });
+            child.on('close', (code) => resolve(code ?? 0));
+        });
+    }
+    if (sub === 'doctor' || sub === 'status') {
+        const hw = await detectHardware({ exec: io.exec });
+        const rec = recommendTier(hw);
+        let provStatus;
+        try {
+            provStatus = await providerFromConfig(c, c.provider, deps(c, io)).status();
+        }
+        catch (x) {
+            provStatus = { ready: false, detail: x.message };
+        }
+        const llama = llamaServerBin(io.env);
+        const llamaOk = llama ? await llamaSupportsDecisions(llama, io.exec) : false;
+        if (opts.json === true) {
+            out(JSON.stringify({ hardware: hw, recommendation: rec, provider: c.provider, model: c.provider === 'kev-local' ? c.kev.model : null, ready: provStatus.ready, detail: provStatus.detail, llamaServer: Boolean(llama), llamaServerDecisions: llamaOk, typesafeKey: Boolean(readTypesafeKey(io.env, { platform: io.platform, acl: io.acl })) }, null, 2));
+            return 0;
+        }
+        out(`hardware: ${describeHardware(hw)}`);
+        out(`recommended: ${rec.model ?? 'the built-in heuristic'}${rec.bestQuality ? ` (best quality here: ${rec.bestQuality})` : ''}: ${rec.why}`);
+        out(`provider: ${c.provider}${c.provider === 'kev-local' ? ` (${c.kev.model})` : ''}: ${provStatus.ready ? 'ready' : 'not ready'}: ${provStatus.detail}`);
+        out(`llama-server: ${!llama ? 'not found (needed for kev-local)' : llamaOk ? 'found, serves decision models' : `found but too old: ${LLAMA_TOO_OLD}`} · TypeSafe key: ${keyLine(typesafeKeyState(io.env, { platform: io.platform, acl: io.acl, fresh: true }))}`);
+        if (c.fallback)
+            out('fallback: the heuristic answers when the provider is unreachable (labelled as a fallback)');
+        return 0;
+    }
+    if (sub === 'bench') {
+        const n = Math.max(1, Math.min(500, Number(opts.n ?? 20) || 20));
+        let provider;
+        try {
+            provider = providerFromConfig(c, c.provider, deps(c, io));
+        }
+        catch (x) {
+            err(x.message);
+            return 1;
+        }
+        const coins = Array.from({ length: n }, (_, i) => coinDossier({ mint: `Bench${String(i).padStart(4, '0')}`.padEnd(32, '1'), symbol: `B${i}`, age_min: 5 + i * 7, liquidity_usd: 2000 + i * 1500, mcap_usd: 9000 + i * 7000, holders: 50 + i * 20, top10_pct: 10 + (i % 40), mint_authority: i % 9 === 0, freeze_authority: i % 13 === 0 }));
+        const r = await classifyBatch(provider, COIN_RISK, coins, { fallback: null });
+        const ok = r.results.filter((x) => !('error' in x));
+        const per = ok.length ? r.ms / ok.length : NaN;
+        out(`${provider.id} ${provider.model()}: ${ok.length}/${n} answered in ${(r.ms / 1000).toFixed(1)} s · ${per.toFixed(0)} ms per coin · ~${((per * 1000) / 60_000).toFixed(1)} min per 1,000 coins (one at a time)`);
+        const failed = r.results.find((x) => 'error' in x);
+        if (failed)
+            err(`first failure: ${failed.error}`);
+        return ok.length ? 0 : 1;
+    }
+    if (sub === 'key') {
+        const action = pos[0] ?? 'status';
+        const keyOpts = { platform: io.platform, acl: io.acl };
+        if (action === 'status') {
+            const s = typesafeKeyState(io.env, { ...keyOpts, fresh: true });
+            if (s.source === 'refused') {
+                out('TypeSafe key: refused');
+                err(typesafeKeyRefusal(s));
+                return 1;
+            }
+            out(s.source === 'env' ? 'TypeSafe key: configured from TYPESAFE_API_KEY (not shown)' : s.source === 'file' ? 'TypeSafe key: configured (not shown)' : 'TypeSafe key: none');
+            return 0;
+        }
+        if (action === 'clear') {
+            out(removeTypesafeKey(io.env) ? 'TypeSafe key removed' : 'no key file to remove');
+            return 0;
+        }
+        if (action === 'set') {
+            const k = await readSecret(io, 'Paste your TypeSafe API key (input hidden): ');
+            if (!k.trim()) {
+                err('no key entered');
+                return 1;
+            }
+            try {
+                const p = writeTypesafeKey(k, io.env, keyOpts);
+                out(`saved to ${p} (${(io.platform ?? process.platform) === 'win32' ? 'owner-only Windows access list' : '0600'}). It is only sent to ${c.jev.endpoint}.`);
+                return 0;
+            }
+            catch (x) {
+                err(x.message);
+                return 1;
+            }
+        }
+        err('key set|clear|status');
+        return 2;
+    }
+    if (sub === 'try') {
+        // A one-off classification of a hand-written coin (no network unless the picked provider is remote).
+        let provider;
+        try {
+            provider = providerFromConfig(c, c.provider, deps(c, io));
+        }
+        catch (x) {
+            err(x.message);
+            return 1;
+        }
+        const r = await classify(provider, COIN_RISK, coinDossier({ mint: 'Example11111111111111111111111111', symbol: 'EXMPL', liquidity_usd: 12000, mcap_usd: 40000, age_min: 20, holders: 300, top10_pct: 35, freeze_authority: false, mint_authority: false }), { fallback: c.fallback ? undefined : null });
+        out(describeResult(r));
+        return 0;
+    }
+    err(`unknown classifier command: ${sub}\n${CLASSIFIER_USAGE}`);
+    return 2;
+}

package/dist/packages/cli/src/classifier-live.js

@@ -0,0 +1,81 @@
+// task-1822: keep `state.classifierByMint` filled for the `rugp` watch-rule field. It does nothing (no model call,
+// no network) unless an ENABLED rule mentions `rugp`. Then, each rules tick:
+//   - provider `heuristic`: every rule row is scored at once (local arithmetic, H1 p(rug)).
+//   - any other provider: one coin at a time in the background, each re-scored at most every RESCORE_MS, the open
+//     token first; a failure falls back to the heuristic (labelled by the provider id stored with the estimate).
+// Estimates are model output for alerts only: nothing here trades, sizes, arms or writes config.
+export const RESCORE_MS = 10 * 60_000;
+const LIVE = new WeakMap();
+export function rulesUseRugp(state) {
+    return !!state.rulesUi?.engine.rules.some((r) => r.enabled && /\brugp\b/i.test(r.whenText));
+}
+/** The dossier fields a rule row carries (the screener row is structurally a RuleRow). */
+export function coinInputFromRuleRow(r) {
+    const n = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+    const b = (v) => (v === 1 ? true : v === 0 ? false : null);
+    return {
+        mint: r.mint, symbol: r.symbol ?? null, age_min: n(r.ageMin), liquidity_usd: n(r.liq), mcap_usd: n(r.mcap),
+        vol5m_usd: n(r.vol5m), vol1h_usd: n(r.vol1h), holders: n(r.holders), top10_pct: n(r.top10), dev_pct: n(r.dev),
+        organic_score: n(r.org), change5m_pct: n(r.chg?.m5), change1h_pct: n(r.chg?.h1), buys1h: n(r.buys), sells1h: n(r.sells),
+        mint_authority: b(r.mintable), freeze_authority: b(r.freezable), launchpad: r.launchpad ?? null,
+    };
+}
+async function load(state, live, env) {
+    const C = await import('../../classifier/src/index.js');
+    const cfg = C.loadClassifierConfig(env).config;
+    live.fallback = cfg.fallback;
+    live.calibration = cfg.calibration;
+    try {
+        live.provider = C.providerFromConfig(cfg, cfg.provider, { env });
+    }
+    catch {
+        live.provider = C.heuristicProvider();
+    }
+    void state;
+}
+/** One step; call from the rules tick with the rows it is about to evaluate. Never throws. */
+export function classifierLiveTick(state, rows, now, env = process.env) {
+    if (!rows.length || !rulesUseRugp(state))
+        return;
+    let live = LIVE.get(state);
+    if (!live) {
+        live = { provider: null, loading: null, inflight: false, fallback: true, calibration: {} };
+        LIVE.set(state, live);
+    }
+    if (!live.provider) {
+        live.loading ??= load(state, live, env).catch(() => { live.loading = null; });
+        return;
+    }
+    const map = (state.classifierByMint ??= new Map());
+    const due = (m) => { const e = map.get(m); return !e || now - e.at >= RESCORE_MS; };
+    const provider = live.provider;
+    if (live.inflight)
+        return;
+    live.inflight = true;
+    const open = state.live?.token?.view.mint ?? null;
+    const queue = rows.filter((r) => due(r.mint)).sort((a, b) => (a.mint === open ? -1 : b.mint === open ? 1 : 0));
+    const batch = provider.id === 'heuristic' ? queue : queue.slice(0, 1);
+    if (!batch.length) {
+        live.inflight = false;
+        return;
+    }
+    void (async () => {
+        try {
+            const C = await import('../../classifier/src/index.js');
+            for (const r of batch) {
+                try {
+                    const res = await C.classify(provider, C.COIN_RISK, C.coinDossier(coinInputFromRuleRow(r)), { calibration: live.calibration, fallback: live.fallback ? undefined : null });
+                    const p = res.answers.drain_6h?.probs.yes;
+                    if (typeof p === 'number')
+                        map.set(r.mint, { p, model: `${res.provider} ${res.model}`, at: now });
+                }
+                catch {
+                    map.set(r.mint, { p: NaN, model: 'error', at: now });
+                }
+            }
+        }
+        finally {
+            live.inflight = false;
+        }
+    })();
+}

package/dist/packages/cli/src/dash/data.js

@@ -0,0 +1,217 @@
+// `dexterm dash` (task-1749): the DATA behind the strategy performance dashboard. Read-only, local, no network:
+//   - every autotrade home given (a DEXTERM_HOME): its run ledgers (autotrade/runs/*.jsonl) through the strategy-stats
+//     definitions (@dexterm/autotrade strategy-stats.ts: the challenge control's math), its service heartbeat and the
+//     fleet status (open positions with the engine's mark, spend, halts)
+//   - the market cache DB (read-only) for the last pool liquidity of an open coin, so an open position shows its
+//     REALIZABLE value next to the engine mark, with the age of that pool read; nothing is fetched
+//   - optional "books" files (dexterm-dash-books/1): other books (e.g. a SOL challenge run by hand or by an agent),
+//     labels, groups, a baseline and status cards, produced by the user's own scripts; their trades go through the
+//     same definitions
+// The output never carries an absolute path, a key, a wallet address or a token: homes are named by their label.
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { readStrategyLedgers, strategyRow, equityCurve, compareToBase, decisionRule, realizableUsd, MIN_CLOSED, RUG_PCT, STUCK_WRITE_OFF_MIN, } from '../../../autotrade/src/strategy-stats.js';
+export const PAPER_LABEL = 'Paper trading, not financial advice.';
+export const DASH_SCHEMA = 'dexterm-dash/1';
+export const BOOKS_SCHEMA = 'dexterm-dash-books/1';
+const readJson = (p) => { try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+}
+catch {
+    return null;
+} };
+const fin = (x) => typeof x === 'number' && Number.isFinite(x);
+const r2 = (x) => Math.round(x * 100) / 100;
+const r1 = (x) => Math.round(x * 10) / 10;
+const alive = (pid) => { if (!fin(pid))
+    return false; try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code === 'EPERM';
+} };
+/** A home's label: the folder that holds `.dexterm` (e.g. c100-control), else the folder's own name. */
+export function homeLabel(dir) { const b = basename(dir); return b === '.dexterm' ? basename(dirname(dir)) || b : b; }
+/** The last cached pool read of each mint (ns ds:token) from the market cache DB, read-only. Missing DB: empty. */
+export function cachedPools(dbPath, mints) {
+    const out = new Map();
+    if (!dbPath || !mints.length || !existsSync(dbPath))
+        return out;
+    let db = null;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+        const q = db.prepare('SELECT json, fetched_at FROM cache WHERE ns = ? AND key = ?');
+        for (const m of new Set(mints)) {
+            const r = q.get('ds:token', m);
+            if (!r)
+                continue;
+            try {
+                const p = JSON.parse(r.json)?.pair;
+                if (fin(p?.liquidityUsd))
+                    out.set(m, { liqUsd: p.liquidityUsd, at: fin(p.fetchedAt) ? p.fetchedAt : r.fetched_at });
+            }
+            catch { /* torn row */ }
+        }
+    }
+    catch { /* locked or not a dexterm cache: no pool reads */ }
+    finally {
+        try {
+            db?.close();
+        }
+        catch { /* closed */ }
+    }
+    return out;
+}
+/** The service heartbeat + fleet status of one home as a status card (no paths, no pids beyond alive/dead). */
+export function homeStatus(h, now) {
+    const at = join(h.dir, 'autotrade');
+    const hb = readJson(join(at, 'service', 'heartbeat.json'));
+    const fl = readJson(join(at, 'fleet-status.json'));
+    const items = [];
+    let state = 'idle';
+    if (hb) {
+        const age = fin(hb.heartbeatAt) ? Math.round((now - hb.heartbeatAt) / 1000) : null;
+        const up = hb.state === 'running' && alive(hb.pid) && age !== null && age < 120;
+        state = up ? 'ok' : hb.state === 'running' ? 'down' : 'idle';
+        items.push(['Service', up ? 'running' : hb.state === 'running' ? 'NOT running (stale heartbeat)' : String(hb.state ?? 'unknown')]);
+        if (age !== null)
+            items.push(['Heartbeat', `${age < 120 ? `${age} s` : `${Math.round(age / 60)} min`} ago`]);
+        if (fin(hb.dataAgeMs))
+            items.push(['Market data age', `${Math.round(hb.dataAgeMs / 1000)} s`]);
+    }
+    else
+        items.push(['Service', 'no service heartbeat (not installed or never run)']);
+    if (fl) {
+        const ms = fl.members ?? [];
+        if (fin(fl.startedAt))
+            items.push(['Fleet started', new Date(fl.startedAt).toISOString()]);
+        if (fl.haltReason) {
+            items.push(['Fleet halt', String(fl.haltReason)]);
+            if (state === 'ok')
+                state = 'warn';
+        }
+        const running = ms.filter((m) => m.state === 'running').length;
+        items.push(['Strategies running', `${running} of ${ms.length}`]);
+        const halted = ms.filter((m) => m.haltReason).map((m) => `${m.id}: ${m.haltReason}`);
+        if (halted.length) {
+            items.push(['Halted', halted.join('; ')]);
+            if (state === 'ok')
+                state = 'warn';
+        }
+        const spend = ms.reduce((s, m) => s + (fin(m.spend?.todayUsd) ? m.spend.todayUsd : 0), 0);
+        items.push(['Model spend today', `$${spend.toFixed(2)}`]);
+    }
+    return { title: `Autotrade · ${h.label}`, state, items, updatedAt: fin(hb?.heartbeatAt) ? hb.heartbeatAt : null };
+}
+function openFromFleet(h, now) {
+    const fl = readJson(join(h.dir, 'autotrade', 'fleet-status.json'));
+    const out = new Map();
+    if (!fl?.members)
+        return out;
+    const mints = fl.members.flatMap((m) => (m.open ?? []).map((o) => o.mint)).filter(Boolean);
+    const pools = cachedPools(h.db, mints);
+    for (const m of fl.members) {
+        out.set(m.id, (m.open ?? []).map((o) => {
+            const cost = fin(o.costUsd) ? o.costUsd : null;
+            const mark = cost !== null ? cost + (fin(o.pnlUsd) ? o.pnlUsd : 0) : null;
+            const pool = o.mint ? pools.get(o.mint) : undefined;
+            // a stuck position has no pool to sell into: realizable 0 whatever the last read said
+            const rv = o.stuck ? 0 : mark !== null ? realizableUsd(mark, pool?.liqUsd) : null;
+            return { symbol: o.symbol ?? null, mint: o.mint ?? null, profile: o.profile ?? null, costUsd: cost, markUsd: mark === null ? null : r2(mark), markPct: fin(o.pnlPct) ? o.pnlPct : null, stuck: !!o.stuck,
+                liqUsd: pool ? Math.round(pool.liqUsd) : null, liqAt: pool?.at ?? null, realizableUsd: rv === null ? null : r2(rv), realizablePct: rv === null || !cost ? null : r1((rv / cost - 1) * 100), openedAt: null };
+        }));
+    }
+    return out;
+}
+const rugsOf = (closed) => closed.filter((c) => c.writtenOff || (fin(c.pnlPct) && c.pnlPct <= RUG_PCT) || (c.stuck && !c.writtenOff));
+function fromLedger(id, m, h, fleetOpen, now) {
+    const row = strategyRow(id, m, { now });
+    // the engine's book is the live truth for what is open; the ledger fold is the fallback when no fleet status exists
+    // a stuck bag the engine still holds but the ledger fold already wrote off is CLOSED here (at its realizable value),
+    // so it is not listed open a second time
+    const heldOff = new Set(m.writtenOff.filter((w) => w.held).map((w) => w.mint));
+    const open = fleetOpen ? fleetOpen.filter((o) => !(o.stuck && heldOff.has(o.mint))) : m.openPositions.map((p) => ({ symbol: p.symbol, mint: p.mint, profile: p.profile, costUsd: p.costUsd, markUsd: null, markPct: null, stuck: p.stuckSince !== null, liqUsd: null, liqAt: null, realizableUsd: p.stuckSince !== null ? r2(p.realizedUsd) : null, realizablePct: null, openedAt: p.openedAt }));
+    return { id, label: m.basedOn?.version ? `v${m.basedOn.version}` : '', group: h.label, source: 'autotrade', home: h.label, unit: 'USD', mode: m.mode, version: m.basedOn?.version ?? null, baseline: false,
+        row, equity: equityCurve(m.closed, m.startUsd), trades: m.closed, open, rugs: rugsOf(m.closed), lastEventAt: m.lastT, firstEventAt: m.firstT };
+}
+function fromBook(b, now) {
+    const closed = (b.trades ?? []).filter((t) => fin(t.t) && fin(t.pnlPct)).map((t) => ({ t: t.t, openedAt: t.openedAt ?? null, mint: t.mint ?? null, symbol: t.symbol ?? null, pnlPct: t.pnlPct, pnlUsd: fin(t.pnl) ? t.pnl : fin(t.pnlUsd) ? t.pnlUsd : null,
+        costUsd: fin(t.cost) ? t.cost : null, exitReason: t.exitReason ?? null, stuck: !!t.writtenOff, writtenOff: !!t.writtenOff, reason: t.reason, profile: t.profile ?? null, entryAgeMin: fin(t.entryAgeMin) ? t.entryAgeMin : null }))
+        .sort((a, b2) => a.t - b2.t);
+    const ts = closed.map((c) => c.openedAt ?? c.t);
+    const firstT = fin(b.firstT) ? b.firstT : ts.length ? Math.min(...ts) : null;
+    const open = (b.open ?? []).map((o) => ({ symbol: o.symbol ?? null, mint: o.mint ?? null, profile: o.profile ?? null, costUsd: fin(o.cost) ? o.cost : null, markUsd: fin(o.mark) ? o.mark : null, markPct: fin(o.markPct) ? o.markPct : null, stuck: !!o.stuck,
+        liqUsd: null, liqAt: null, realizableUsd: fin(o.realizable) ? o.realizable : null, realizablePct: fin(o.realizable) && fin(o.cost) && o.cost ? r1((o.realizable / o.cost - 1) * 100) : null, openedAt: o.openedAt ?? null }));
+    const m = { entries: fin(b.entries) ? b.entries : closed.length + open.length, closed, open: open.length, writtenOff: closed.filter((c) => c.writtenOff), stuckOpen: [], abandoned: [], adopted: 0, firstT };
+    return { id: b.id, label: b.label ?? '', group: b.group ?? 'books', source: 'book', home: b.group ?? 'books', unit: b.unit ?? 'USD', mode: b.mode ?? 'paper', version: b.version ?? null, baseline: false,
+        row: strategyRow(b.id, m, { now }), equity: equityCurve(closed, fin(b.start) ? b.start : null), trades: closed, open, rugs: rugsOf(closed),
+        lastEventAt: closed.length ? closed[closed.length - 1].t : firstT, firstEventAt: firstT };
+}
+export function readBooksFile(p) {
+    const j = readJson(p);
+    return j && j.schema === BOOKS_SCHEMA ? j : null;
+}
+/** Everything the dashboard shows, from the homes and books files given. */
+export function collectDash({ homes, books = [], baseline = null, now = Date.now() }) {
+    const strategies = [];
+    const status = [];
+    const notes = [];
+    const labels = {};
+    const groups = {};
+    let order = [];
+    let base = baseline;
+    for (const h of homes) {
+        const runs = join(h.dir, 'autotrade', 'runs');
+        if (!existsSync(runs)) {
+            notes.push(`${h.label}: no autotrade run ledgers yet`);
+            continue;
+        }
+        const M = readStrategyLedgers(runs, { now });
+        const fo = openFromFleet(h, now);
+        for (const [id, m] of Object.entries(M))
+            strategies.push(fromLedger(id, m, h, fo.get(id), now));
+        status.push(homeStatus(h, now));
+    }
+    for (const f of books) {
+        const b = readBooksFile(f);
+        if (!b) {
+            notes.push(`books file ${basename(f)}: missing or not ${BOOKS_SCHEMA}`);
+            continue;
+        }
+        for (const x of b.books ?? [])
+            strategies.push(fromBook(x, now));
+        Object.assign(labels, b.labels ?? {});
+        Object.assign(groups, b.groups ?? {});
+        if (b.order)
+            order = [...order, ...b.order];
+        base ??= b.baseline ?? null;
+        status.unshift(...(b.status ?? [])); // the books' own cards first (what the user runs by hand)
+        notes.push(...(b.notes ?? []));
+    }
+    for (const s of strategies) {
+        if (labels[s.id])
+            s.label = labels[s.id];
+        if (groups[s.id])
+            s.group = groups[s.id];
+        s.baseline = s.id === base;
+    }
+    const rank = (id) => { const i = order.indexOf(id); return i < 0 ? 1e6 : i; };
+    strategies.sort((a, b) => Number(b.baseline) - Number(a.baseline) || rank(a.id) - rank(b.id) || a.group.localeCompare(b.group) || a.id.localeCompare(b.id));
+    const baseS = strategies.find((s) => s.baseline) ?? null;
+    const pcts = (s) => s.trades.map((c) => c.pnlPct).filter(fin);
+    const comparisons = baseS ? strategies.filter((s) => s !== baseS).map((s) => compareToBase(s.id, pcts(s), baseS.id, pcts(baseS))) : [];
+    return {
+        schema: DASH_SCHEMA, generatedAt: now, paper: PAPER_LABEL,
+        definitions: { minClosed: MIN_CLOSED, rugPct: RUG_PCT, writeOffMin: STUCK_WRITE_OFF_MIN, text: [
+                `Closed = trades the engine closed plus stuck positions written off: no sell for >= ${STUCK_WRITE_OFF_MIN} min (or dropped stuck at a run end) closes at what was actually sold; the unsold rest counts 0.`,
+                `Mean % on cost = the average return per closed trade, with a 95% bootstrap interval (4000 resamples). Wide interval = the data cannot tell yet.`,
+                `Rug = a closed trade at ${RUG_PCT}% or worse on cost. Rug rate interval: Wilson 95%.`,
+                `Under ${MIN_CLOSED} closed trades a strategy is EXPLORATORY: read nothing into it. ETA to ${MIN_CLOSED} = the closed trades still needed / entries per day so far.`,
+                `Realizable = the engine's mark sold into the last pool read from the local cache (impact on half the liquidity, 2.3% fees and slippage); a stuck position is 0.`,
+                `Equity = the starting book plus realized P/L in close order; drawdown is from the running peak.`,
+            ] },
+        baseline: baseS?.id ?? null, decisionRule: baseS ? decisionRule(baseS.id) : null, strategies, comparisons, status, notes,
+    };
+}