dexterm-cli 0.1.2 → 0.1.3

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

@@ -0,0 +1,455 @@
+// dexterm — `dexterm record` (task-1414): a HEADLESS collector that keeps the history recorder fed when
+// nobody has the TUI open. The recorder (task-1329) only grows while the interactive app runs; the backtest
+// (task-1401) is only worth re-running on fresh data, so this command runs the exact same recorder jobs
+// (observe snapshots + feed membership, the 1 h/2 h/6 h/24 h/72 h outcome sweeps, labels, retention) with no
+// TUI, to be driven by a user-level launchd LaunchAgent on the Mac mini.
+//
+//   dexterm record [run] [--interval S] [--ticks N | --once] [--maintain S] [--max-db-mb N] [--no-newpairs] [--db PATH] [--verbose]
+//   dexterm record install   [--interval S] [--max-db-mb N] [--load] [--dry-run]
+//   dexterm record uninstall [--unload]
+//   dexterm record status    [--db PATH]
+//
+// SAFETY / BUDGETS: this builds the keyless live feed and the recorder exactly as the live app does, so every
+// request goes through the data layer's rate limiter + health gate and the sweep's own per-sweep / per-day caps
+// (DEFAULT_SWEEP). It never builds a signer, never trades, never prints the Helius key (the URL is built inside
+// the data layer; only the provider name is ever logged). Modest CPU: one feed refresh per `--interval` (60 s
+// default) and recorder maintenance at most every `--maintain` seconds. A soft disk cap pauses OBSERVATION
+// (the growth source) above `--max-db-mb` while labels + retention keep running, so the DB cannot run away.
+import { mkdirSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { defaultDbPath, resolveRpcUrl, extraRpcUrls, redactSecrets } from '../../data/src/index.js';
+import { PumpPortalClient } from '../../data/src/index.js';
+import { Recorder, recorderEnabled } from '../../recorder/src/index.js';
+import { createLiveFeed } from "./feed.js";
+import { NewPairsLive } from "./live/index.js";
+/** The LaunchAgent label (reverse-DNS). One collector per user. */
+export const COLLECTOR_LABEL = 'xyz.dexterm.collector';
+/** Default spacing between feed refreshes (one observation pass). Background work: keep it unhurried. */
+export const DEFAULT_INTERVAL_MS = 60_000;
+/** Default spacing between recorder maintenance passes (sweeps/labels/retention). */
+export const DEFAULT_MAINTAIN_MS = 60_000;
+/** Default soft cap on the whole DB file. Above it, observation pauses; sweeps/labels/retention continue. */
+export const DEFAULT_MAX_DB_MB = 1024;
+/** Build the real collector engine: the keyless live feed, the recorder attached to its store, and (unless
+ *  disabled) the PumpPortal new-pairs stream folded into the feed's candidate pool so fresh launches get
+ *  recorded before the REST feeds index them. */
+export function buildLiveEngine(env, opts) {
+    const rpc = resolveRpcUrl({ env });
+    const feed = createLiveFeed({
+        dbPath: opts.dbPath, rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl, rpcPublicPool: true, rpcExtraUrls: extraRpcUrls(env),
+        onRequest: opts.verbose ? (req, meta, o) => opts.onLog?.(`  ${meta.source.padEnd(14)} ${String(o.status ?? 'ERR').padStart(3)} ${String(o.latencyMs).padStart(5)}ms ${redactSecrets(req.url).slice(0, 110)}\n`) : undefined,
+    });
+    const recorder = new Recorder({ path: opts.dbPath, onLog: opts.verbose ? opts.onLog : undefined });
+    recorder.attach(feed.dl.store);
+    let newpairs = null;
+    if (!opts.noNewpairs) {
+        newpairs = new NewPairsLive(feed.dl, {});
+        const client = new PumpPortalClient({ health: feed.dl.health, clock: feed.dl.clock, onEvent: (ev) => newpairs.handleEvent(ev), onStatus: () => { } });
+        newpairs.attach(client, 'live');
+        newpairs.start();
+        const np = newpairs;
+        feed.extraMints = () => [...np.rows.keys()];
+    }
+    const dl = feed.dl;
+    return {
+        async observe() {
+            const before = recorder.counters.written;
+            await feed.refresh();
+            return recorder.counters.written - before;
+        },
+        async maintain() { await recorder.maintain(dl); },
+        prune() { try {
+            recorder.prune();
+        }
+        catch { /* logged inside; never fatal */ } },
+        dbBytes() {
+            try {
+                const db = recorder.database;
+                const pc = db.prepare('PRAGMA page_count').get().page_count;
+                const ps = db.prepare('PRAGMA page_size').get().page_size;
+                return Number(pc) * Number(ps);
+            }
+            catch {
+                return null;
+            }
+        },
+        newPairs() { return newpairs ? newpairs.rows.size : 0; },
+        close() {
+            try {
+                newpairs?.stop();
+            }
+            catch { /* ignore */ }
+            try {
+                feed.close();
+            }
+            catch { /* ignore */ }
+            try {
+                recorder.close();
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+/**
+ * Drive the engine. Each tick (after the first waits `intervalMs`): if a disk cap is set and the DB is at/over
+ * it, force a retention pass; if it is still over, SKIP observation this tick (so the growth source pauses) but
+ * keep running maintenance. Otherwise observe one pass. Maintenance runs at most every `maintainEveryMs`.
+ * Never throws out of the loop: an engine error is logged and the loop continues to the next tick.
+ */
+export async function runCollectorLoop(engine, opts) {
+    const res = { ticks: 0, observePasses: 0, rowsWritten: 0, maintainPasses: 0, cappedTicks: 0 };
+    let lastMaintain = -Infinity;
+    for (let i = 0; i < opts.ticks && !opts.aborted(); i++) {
+        if (i > 0) {
+            await opts.sleep(opts.intervalMs);
+            if (opts.aborted())
+                break;
+        }
+        res.ticks++;
+        let over = false;
+        if (opts.maxDbBytes !== null) {
+            const b = engine.dbBytes();
+            if (b !== null && b >= opts.maxDbBytes) {
+                engine.prune();
+                const b2 = engine.dbBytes();
+                over = b2 !== null && b2 >= opts.maxDbBytes;
+                if (over) {
+                    res.cappedTicks++;
+                    opts.onLog?.(`record: DB at ${(b2 / 1e6).toFixed(0)} MB ≥ cap ${(opts.maxDbBytes / 1e6).toFixed(0)} MB — observation paused this tick (labels + retention still run)\n`);
+                }
+            }
+        }
+        if (!over) {
+            try {
+                res.rowsWritten += await engine.observe();
+                res.observePasses++;
+            }
+            catch (e) {
+                opts.onLog?.(`record: observe failed: ${redactSecrets(e.message)}\n`);
+            }
+        }
+        const now = opts.now();
+        if (now - lastMaintain >= opts.maintainEveryMs) {
+            lastMaintain = now;
+            try {
+                await engine.maintain();
+                res.maintainPasses++;
+            }
+            catch (e) {
+                opts.onLog?.(`record: maintain failed: ${redactSecrets(e.message)}\n`);
+            }
+        }
+    }
+    return res;
+}
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * A user-level LaunchAgent (no sudo). KeepAlive so a crash or a reboot-after-login brings it back, RunAtLoad,
+ * ProcessType Background + Nice 10 + Low throttling so it never competes with foreground work, and a
+ * ThrottleInterval so a crash-loop cannot spin. It writes to `logPath`. NOTE (documented, and in `install`
+ * output): a LaunchAgent does NOT start before the user logs in — this Mac must be logged in for the
+ * collector to run; a true pre-login daemon would be a LaunchDaemon under sudo, which this task does not use.
+ */
+export function renderCollectorPlist(o) {
+    const args = [o.nodePath, o.binPath, 'record', 'run', '--interval', String(Math.round(o.intervalMs / 1000)), '--max-db-mb', String(o.maxDbMb)];
+    const argXml = args.map((a) => `    <string>${esc(a)}</string>`).join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${esc(o.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${esc(o.workingDir)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>Nice</key>
+  <integer>10</integer>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${esc(o.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${esc(o.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+/** `~/Library/LaunchAgents/<label>.plist` for the invoking user (HOME from env). */
+export function plistPath(env, label = COLLECTOR_LABEL) {
+    const home = env.HOME || env.USERPROFILE || '';
+    return join(home, 'Library', 'LaunchAgents', `${label}.plist`);
+}
+/** The data directory that holds the DB (and the collector log), from the resolved DB path. */
+function dataDir(env, db) {
+    return dirname(db && db !== ':memory:' ? db : defaultDbPath(env));
+}
+/** The source bin shim this file ships next to (…/packages/cli/bin/dexterm.mjs). */
+function sourceBin() {
+    return fileURLToPath(new URL('../bin/dexterm.mjs', import.meta.url));
+}
+export function parseRun(argv) {
+    const a = { intervalMs: DEFAULT_INTERVAL_MS, ticks: Infinity, maintainMs: DEFAULT_MAINTAIN_MS, maxDbBytes: DEFAULT_MAX_DB_MB * 1_000_000, noNewpairs: false, db: null, verbose: false };
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--verbose' || t === '-v')
+            a.verbose = true;
+        else if (t === '--no-newpairs')
+            a.noNewpairs = true;
+        else if (t === '--once')
+            a.ticks = 1;
+        else if (t === '--ticks') {
+            const n = Number(argv[++i]);
+            if (!Number.isInteger(n) || n < 1)
+                return { error: '--ticks needs an integer ≥ 1' };
+            a.ticks = n;
+        }
+        else if (t === '--interval') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1)
+                return { error: '--interval needs seconds ≥ 1' };
+            a.intervalMs = Math.round(n * 1000);
+        }
+        else if (t === '--maintain') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1)
+                return { error: '--maintain needs seconds ≥ 1' };
+            a.maintainMs = Math.round(n * 1000);
+        }
+        else if (t === '--max-db-mb') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 0)
+                return { error: '--max-db-mb needs a number ≥ 0 (0 = no cap)' };
+            a.maxDbBytes = n === 0 ? null : Math.round(n * 1_000_000);
+        }
+        else if (t === '--db') {
+            a.db = argv[++i] ?? null;
+            if (!a.db)
+                return { error: '--db needs a PATH' };
+        }
+        else
+            return { error: `unknown option "${t}"` };
+    }
+    return a;
+}
+export const RECORD_USAGE = `dexterm record: keep the history recorder fed with no TUI open (task-1414).
+
+  dexterm record [run] [--interval S] [--ticks N | --once] [--maintain S] [--max-db-mb N] [--no-newpairs] [--db PATH] [--verbose]
+  dexterm record install   [--interval S] [--max-db-mb N] [--load] [--dry-run]
+  dexterm record uninstall [--unload]
+  dexterm record status    [--db PATH]
+
+run        the collector loop: one keyless feed refresh per --interval (default 60 s) feeds the recorder
+           (snapshots + feed membership + new pairs), recorder maintenance (outcome sweeps, labels, retention)
+           every --maintain seconds. --max-db-mb is a soft cap (default 1024): above it observation pauses while
+           labels + retention keep running. --no-newpairs drops the PumpPortal stream. Ctrl-C stops cleanly
+           (labels whatever is due). Requests honour the data layer's rate limits, health gate and sweep budgets.
+install    write a user-level launchd LaunchAgent (no sudo) that runs \`record run\`; prints the launchctl
+           command. --load also runs launchctl (off by default). --dry-run prints the plist, writes nothing.
+uninstall  remove the LaunchAgent plist; --unload also runs launchctl bootout.
+status     recorder stats + whether the LaunchAgent is installed + DB size vs the cap.
+
+NOTE: a LaunchAgent does not start before the user logs in on this Mac (it is not a pre-login daemon). The
+collector runs only while this user is logged in. Free-tier APIs only; the Helius key is never printed.`;
+export async function recordCommand(argv, io, deps = {}) {
+    const sub = argv[0] && !argv[0].startsWith('--') ? argv[0] : 'run';
+    const rest = argv[0] && !argv[0].startsWith('--') ? argv.slice(1) : argv;
+    if (sub === 'help' || argv.includes('--help') || argv.includes('-h')) {
+        io.stdout.write(RECORD_USAGE + '\n');
+        return 0;
+    }
+    if (sub === 'install')
+        return install(rest, io);
+    if (sub === 'uninstall')
+        return uninstall(rest, io);
+    if (sub === 'status')
+        return status(rest, io);
+    if (sub === 'run')
+        return run(rest, io, deps);
+    io.stderr.write(`dexterm record: unknown subcommand "${sub}"\n\n${RECORD_USAGE}\n`);
+    return 2;
+}
+async function run(argv, io, deps) {
+    const parsed = parseRun(argv);
+    if ('error' in parsed) {
+        io.stderr.write(`dexterm record: ${parsed.error}\n\n${RECORD_USAGE}\n`);
+        return 2;
+    }
+    const now = deps.now ?? (() => Date.now());
+    const dbPath = parsed.db ?? defaultDbPath(io.env);
+    if (!deps.engine && dbPath === ':memory:') {
+        io.stderr.write('dexterm record: an in-memory DB keeps no history; give a --db PATH\n');
+        return 2;
+    }
+    if (!deps.engine && !recorderEnabled(io.env, false)) {
+        io.stderr.write('dexterm record: the recorder is disabled (DEXTERM_RECORDER=0); nothing to collect\n');
+        return 2;
+    }
+    // SIGINT/SIGTERM-aware cancellable sleeper (launchd sends SIGTERM to stop the agent).
+    const stop = (() => {
+        let aborted = false;
+        let wake = () => { };
+        return {
+            get aborted() { return aborted; },
+            abort() { aborted = true; wake(); },
+            sleep(ms) { return new Promise((r) => { const t = setTimeout(r, ms); t.unref?.(); wake = () => { clearTimeout(t); r(); }; }); },
+        };
+    })();
+    const log = (s) => io.stderr.write(s);
+    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log });
+    const own = !deps.engine;
+    const onSig = () => { io.stderr.write('\ndexterm record: stopping…\n'); stop.abort(); };
+    if (own) {
+        process.on('SIGINT', onSig);
+        process.on('SIGTERM', onSig);
+    }
+    if (parsed.verbose || parsed.ticks !== Infinity)
+        io.stderr.write(`dexterm record: db ${dbPath} · interval ${Math.round(parsed.intervalMs / 1000)}s · maintain ${Math.round(parsed.maintainMs / 1000)}s · cap ${parsed.maxDbBytes === null ? 'off' : `${Math.round(parsed.maxDbBytes / 1e6)} MB`} · newpairs ${parsed.noNewpairs ? 'off' : 'on'}\n`);
+    let result;
+    try {
+        result = await runCollectorLoop(engine, {
+            intervalMs: parsed.intervalMs, ticks: parsed.ticks, maintainEveryMs: parsed.maintainMs, maxDbBytes: parsed.maxDbBytes,
+            now, sleep: (ms) => stop.sleep(ms), aborted: () => stop.aborted, onLog: log,
+        });
+    }
+    finally {
+        if (own) {
+            process.removeListener('SIGINT', onSig);
+            process.removeListener('SIGTERM', onSig);
+        }
+        engine.close();
+    }
+    if (parsed.verbose || parsed.ticks !== Infinity)
+        io.stdout.write(`record: ${result.observePasses} observe pass(es), ${result.rowsWritten} snapshot row(s), ${result.maintainPasses} maintenance pass(es)${result.cappedTicks ? `, ${result.cappedTicks} tick(s) paused at the disk cap` : ''}\n`);
+    return 0;
+}
+function install(argv, io) {
+    let intervalMs = DEFAULT_INTERVAL_MS, maxDbMb = DEFAULT_MAX_DB_MB, load = false, dry = false;
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--load')
+            load = true;
+        else if (t === '--dry-run')
+            dry = true;
+        else if (t === '--interval') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1) {
+                io.stderr.write('dexterm record: --interval needs seconds ≥ 1\n');
+                return 2;
+            }
+            intervalMs = Math.round(n * 1000);
+        }
+        else if (t === '--max-db-mb') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1) {
+                io.stderr.write('dexterm record: --max-db-mb needs a number ≥ 1\n');
+                return 2;
+            }
+            maxDbMb = n;
+        }
+        else {
+            io.stderr.write(`dexterm record install: unknown option "${t}"\n`);
+            return 2;
+        }
+    }
+    const path = plistPath(io.env);
+    const logPath = join(dataDir(io.env), 'collector.log');
+    const bin = sourceBin();
+    const plist = renderCollectorPlist({ label: COLLECTOR_LABEL, nodePath: process.execPath, binPath: bin, intervalMs, maxDbMb, logPath, workingDir: resolve(dirname(bin), '..', '..', '..') });
+    if (dry) {
+        io.stdout.write(plist);
+        io.stderr.write(`\ndexterm record: dry run — would write ${path}\n`);
+        return 0;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    mkdirSync(dirname(logPath), { recursive: true });
+    writeFileSync(path, plist);
+    io.stdout.write(`wrote ${path}\nlog     ${logPath}\n\nEnable it (user-level, no sudo):\n  launchctl bootstrap gui/$(id -u) ${path}\n  launchctl kickstart -k gui/$(id -u)/${COLLECTOR_LABEL}\nStop/remove it:  dexterm record uninstall --unload\n\nNOTE: a LaunchAgent does NOT start before you log in on this Mac; the collector runs only while logged in.\n`);
+    if (load)
+        return runLaunchctl(['bootstrap', `gui/${process.getuid?.() ?? 0}`, path], io);
+    io.stderr.write('dexterm record: plist written but NOT loaded (pass --load, or run the launchctl command above) once you have checked it.\n');
+    return 0;
+}
+function uninstall(argv, io) {
+    const unload = argv.includes('--unload');
+    const path = plistPath(io.env);
+    if (unload)
+        runLaunchctl(['bootout', `gui/${process.getuid?.() ?? 0}/${COLLECTOR_LABEL}`], io);
+    if (existsSync(path)) {
+        rmSync(path, { force: true });
+        io.stdout.write(`removed ${path}\n`);
+    }
+    else
+        io.stdout.write(`no LaunchAgent at ${path}\n`);
+    return 0;
+}
+function status(argv, io) {
+    let db = null;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--db') {
+            db = argv[++i] ?? null;
+            if (!db) {
+                io.stderr.write('dexterm record: --db needs a PATH\n');
+                return 2;
+            }
+        }
+    }
+    const path = plistPath(io.env);
+    const installed = existsSync(path);
+    const dbPath = db ?? defaultDbPath(io.env);
+    io.stdout.write(`LaunchAgent     ${installed ? `installed (${path})` : 'not installed (dexterm record install)'}\n`);
+    io.stdout.write(`service note    LaunchAgents do not start before login; the collector runs only while logged in\n`);
+    if (dbPath === ':memory:') {
+        io.stdout.write('recorder        in-memory DB (no history)\n');
+        return 0;
+    }
+    let rec = null;
+    try {
+        rec = new Recorder({ path: dbPath, enabled: false });
+        const s = rec.stats();
+        const when = (t) => (t === null ? '—' : new Date(t).toISOString());
+        io.stdout.write([
+            `db              ${dbPath} (${s.dbBytes === null ? '—' : `${(s.dbBytes / 1e6).toFixed(1)} MB`})`,
+            `snapshots       ${s.snapshots} (live ${s.live}, sweep ${s.sweep}, t0 anchors ${s.t0})`,
+            `outcomes        ${s.outcomes}${s.outcomes ? ` (${Object.entries(s.outcomesByLabel).map(([k, v]) => `${k} ${v}`).join(', ')})` : ''}`,
+            `sweeps          ${s.sweeps} runs · ${s.sweepCallsToday} DexScreener calls today`,
+            `span            ${when(s.oldestT)} → ${when(s.newestT)}`,
+        ].join('\n') + '\n');
+    }
+    catch (e) {
+        io.stderr.write(`dexterm record status: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+    finally {
+        rec?.close();
+    }
+    return 0;
+}
+/** Run launchctl best-effort (only on --load/--unload). Never throws: a failure is reported, the plist stays. */
+function runLaunchctl(args, io) {
+    try {
+        const r = spawnSync('launchctl', args, { stdio: 'inherit' });
+        if (r.status !== 0) {
+            io.stderr.write(`dexterm record: launchctl ${args[0]} exited ${r.status ?? 'null'}\n`);
+            return 1;
+        }
+        io.stdout.write(`launchctl ${args[0]} ok\n`);
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`dexterm record: launchctl failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        return 1;
+    }
+}

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

@@ -48,7 +48,13 @@ export function larpGrade(verdict) {
     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. */
+/**
+ * The rows a rule can see: the screener feed (no skeletons) with the wallet-intel top-cluster share and the LARP
+ * grade attached. task-1404: the OPEN token also carries its LIVE holder/rug signal fields (top10 / dev / bundled /
+ * snipers / fresh / cluster / lpLocked / bonding / mintable / freezable), so a rule like `dev.delta < 0` or
+ * `mintable > 0` fires on the real streaming values, not the on-open snapshot. A token opened by `--mint` that is
+ * not in the screener feed is appended as its own row so rules still see it.
+ */
 export function ruleRowsOf(state) {
     const out = [];
     const seen = new Set();
@@ -59,14 +65,56 @@ export function ruleRowsOf(state) {
         const c = res.analysis.clusters[0];
         return c ? c.pct : null;
     };
+    const openMint = state.live?.token?.view.mint ?? null;
     for (const r of state.screener.rows) {
         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), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict) }));
+        const row = Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict) });
+        if (r.mint === openMint)
+            overlaySignalFields(row, state, r.mint);
+        out.push(row);
+    }
+    // A token opened by mint (not in the screener feed): synthesize a row from its live view so rules see it too.
+    if (openMint && !seen.has(openMint) && state.live?.token) {
+        const v = state.live.token.view;
+        const row = Object.assign(Object.create(null), {
+            mint: v.mint, symbol: v.symbol, price: v.price, mcap: v.mcap, fdv: v.fdv, liq: v.liq, vol24: v.vol24,
+            holders: v.holders, org: v.org, top10: v.top10, dev: v.dev, lpLocked: v.lpLocked,
+            cluster: clusterOf(v.mint), larp: larpGrade(state.larpByMint?.get(v.mint)?.verdict),
+            ageMin: v.ageMin, chg: v.chg, launchpad: v.launchpad, flags: v.flags, verified: v.verified, sus: v.sus,
+        });
+        overlaySignalFields(row, state, v.mint);
+        out.push(row);
     }
     return out;
 }
+/** Overlay the live-signals engine's latest values (non-null wins) onto a rule row (task-1404). */
+function overlaySignalFields(row, state, mint) {
+    const f = state.live?.signals?.fields(mint);
+    if (!f)
+        return;
+    if (f.top10 !== null)
+        row.top10 = f.top10;
+    if (f.dev !== null)
+        row.dev = f.dev;
+    if (f.bundled !== null)
+        row.bundled = f.bundled;
+    if (f.snipers !== null)
+        row.snipers = f.snipers;
+    if (f.cluster !== null)
+        row.cluster = f.cluster;
+    if (f.lpLocked !== null)
+        row.lpLocked = f.lpLocked;
+    if (f.bonding !== null)
+        row.bonding = f.bonding;
+    if (f.fresh !== null)
+        row.fresh = f.fresh;
+    if (f.mintable !== null)
+        row.mintable = f.mintable;
+    if (f.freezable !== null)
+        row.freezable = f.freezable;
+}
 /**
  * One engine tick: observe the rows, evaluate, and turn the outputs into app state. Self-throttled to RULES_TICK_MS.
  * Alerts become the first pending toast + log lines; ticket/ask become PROPOSAL cards; watch/tag touch the user's

package/dist/packages/cli/src/screens/follows.js

@@ -6,7 +6,7 @@
 // mirror PROPOSAL and Tier 3 the capped auto-mirror, both behind the plan engine's own keypress gates.
 import { Canvas, header, footer, breakpoint, fmtAgeSec } from '../../../tui/src/index.js';
 import { headerModel } from "../state.js";
-import { shortAddr, autoSizeCap } from '../../../data/src/trade/copy/index.js';
+import { shortAddr, autoSizeCap, fmtHoldMs } from '../../../data/src/trade/copy/index.js';
 function fmtSol(n) { const s = n >= 0 ? '+' : '−'; return `${s}${Math.abs(n).toFixed(Math.abs(n) >= 10 ? 1 : 3)} SOL`; }
 function fmtUsdSigned(n) { const s = n >= 0 ? '+' : '−'; const a = Math.abs(n); return `${s}$${a >= 1000 ? (a / 1000).toFixed(1) + 'k' : a.toFixed(a >= 100 ? 0 : 2)}`; }
 function fmtUsdAbs(n) { if (n === null)
@@ -196,6 +196,95 @@ export function renderFollows(c, state) {
         y += 2;
         c.text(mbox.x + 1, y, gateOk ? 'Hold and release [enter] or [y] to turn auto ON (physical keypress) · [esc] leaves it OFF · a pipe/agent cannot' : '[esc] closes · accept the popup, then A again', { fg: t.accent, bg: mbg }, mbox.w - 2);
     }
+    // task-1399: the per-wallet DETAIL view (its own trades + positions + metrics, each with source + data age).
+    if (ui?.detail)
+        renderWalletDetail(c, state, now);
     const autoHint = (() => { const f = follows[Math.max(0, Math.min(follows.length - 1, ui?.selected ?? 0))]; const p = f ? svc?.auto?.policy(f.addr) : null; return p?.enabled ? 'auto OFF' : 'auto-mirror'; })();
-    footer(c, [['↑↓', 'move'], ['i', 'follow a wallet'], ['d', 'unfollow'], ['m', ui?.mirror ? (ui.mirror.result?.ok ? 'PROPOSE mirror' : 'close') : 'mirror ticket'], ['A', autoHint], ['r', 'poll now'], ['esc', 'back'], ['q', 'quit']], t.name);
+    const foot = ui?.detail
+        ? [['↑↓', 'scroll'], ['enter/esc', 'close'], ['q', 'quit']]
+        : [['↑↓', 'move'], ['enter', 'wallet view'], ['i', 'follow a wallet'], ['d', 'unfollow'], ['m', ui?.mirror ? (ui.mirror.result?.ok ? 'PROPOSE mirror' : 'close') : 'mirror ticket'], ['A', autoHint], ['r', 'poll now'], ['esc', 'back'], ['q', 'quit']];
+    footer(c, foot, t.name);
+}
+/**
+ * task-1399 — one followed wallet's DETAIL view: its own recent decoded trades and positions, plus the full metric
+ * set (realised PnL, win rate with n, median hold time, early-entry score, open), each labelled with its source
+ * (Helius history) and data age (time since the last poll). Read-only: nothing here trades, arms, proposes or signs.
+ */
+function renderWalletDetail(c, state, now) {
+    const t = c.theme;
+    const ui = state.copyUi;
+    const svc = state.copy;
+    if (!ui?.detail || !svc)
+        return;
+    const addr = ui.detail.wallet;
+    const f = svc.follows().find((x) => x.addr === addr);
+    const s = svc.stats(addr);
+    const trades = svc.trades(addr); // newest first
+    const top = 2, bottom = c.h - 1;
+    const mw = Math.min(c.w - 2, 104);
+    const mh = Math.max(10, bottom - top - 1);
+    const mx = Math.floor((c.w - mw) / 2), my = top + 1;
+    c.noRain(mx, my, mw, mh);
+    const label = f?.name ? ` · ${f.name}` : '';
+    const box = c.box(mx, my, mw, mh, { title: `WALLET${label} — read-only`, caption: 'its own trades + positions · every number: source + data age · not a recommendation', focus: true, bg: t.panelAlt });
+    const bg = box.bg;
+    let y = box.y;
+    c.text(box.x + 1, y, addr, { fg: t.text, bg }, box.w - 2);
+    y += 1;
+    const age = s.sample.asOf ? `${Math.max(0, Math.round((now - s.sample.asOf) / 1000))}s ago` : 'not fetched yet';
+    c.text(box.x + 1, y, `source ${s.sample.source} · ${age} · ${s.sample.note}`, { fg: t.dim, bg }, box.w - 2);
+    y += 1;
+    const pnl = `${fmtSol(s.realisedSol)}${s.realisedUsd !== null ? ` ${fmtUsdSigned(s.realisedUsd)}` : ''}`;
+    const wr = s.winRate === null ? `win rate n<10 (${s.wins}/${s.closed})` : `win rate ${Math.round(s.winRate * 100)}% (${s.wins}/${s.closed})`;
+    c.text(box.x + 1, y, `realised ${pnl} · ${wr} · hold ${fmtHoldMs(s.holdMedianMs)} · EES ${s.earlyEntry.score === null ? '—' : s.earlyEntry.score.toFixed(2)} · open ${s.open} · ${s.buys}b/${s.sells}s`, { fg: t.text, bg }, box.w - 2);
+    y += 1;
+    c.text(box.x + 1, y, `hold: ${s.holdNote} · EES: ${s.earlyEntry.note}`, { fg: t.dim, bg }, box.w - 2);
+    y += 2;
+    const footerY = box.y + box.h - 1;
+    const posCount = Math.min(s.positions.length, 6);
+    const posHeaderY = posCount ? footerY - posCount - 1 : footerY;
+    // RECENT TRADES (scrollable) fill the space above the positions block.
+    c.text(box.x + 1, y, 'RECENT TRADES', { fg: t.dim, bg });
+    y += 1;
+    if (!trades.length) {
+        c.text(box.x + 1, y, svc.status().state === 'unavailable' ? 'needs a free Helius key' : 'no swaps in fetched history', { fg: t.dim, bg, i: true });
+        y += 1;
+    }
+    else {
+        const roomRows = Math.max(1, posHeaderY - 1 - y);
+        const scroll = Math.max(0, Math.min(Math.max(0, trades.length - roomRows), ui.detail.scroll));
+        for (let i = scroll; i < trades.length && y < posHeaderY - 1; i++) {
+            const tr = trades[i];
+            const sideFg = tr.side === 'buy' ? t.up : tr.side === 'sell' ? t.down : t.muted;
+            let cx = c.text(box.x + 1, y, (tr.tKnown ? new Date(tr.t).toISOString().replace('T', ' ').slice(5, 19) : 'time unknown ').padEnd(15), { fg: t.dim, bg });
+            cx = c.text(cx + 1, y, tr.side.toUpperCase().padEnd(9), { fg: sideFg, bg, b: true });
+            cx = c.text(cx + 1, y, shortAddr(tr.mint).padEnd(11), { fg: t.text, bg });
+            cx = c.text(cx + 1, y, (tr.solDelta !== null ? `${Math.abs(tr.solDelta).toFixed(3)} SOL` : 'unpriced').padStart(11), { fg: t.muted, bg });
+            cx = c.text(cx + 1, y, fmtUsdAbs(tr.usd).padStart(8), { fg: t.text, bg });
+            if (tr.note)
+                c.text(cx + 1, y, `(${tr.note})`, { fg: t.dim, bg }, box.w - (cx + 1 - box.x) - 1);
+            y += 1;
+        }
+        const older = trades.length - scroll - roomRows;
+        if (older > 0)
+            c.textR(box.x + 1, posHeaderY - 1, box.w - 2, `… ${older} older (↑↓)`, { fg: t.dim, bg, i: true });
+    }
+    // POSITIONS block (fixed, bottom).
+    if (posCount) {
+        c.text(box.x + 1, posHeaderY, `POSITIONS · ${s.positions.length}`, { fg: t.dim, bg });
+        let py = posHeaderY + 1;
+        for (const p of s.positions.slice(0, posCount)) {
+            if (py >= footerY)
+                break;
+            let cx = c.text(box.x + 1, py, shortAddr(p.mint).padEnd(11), { fg: t.text, bg });
+            cx = c.text(cx + 1, py, (p.closed ? 'closed' : 'open').padEnd(7), { fg: p.closed ? t.muted : t.accent, bg });
+            cx = c.text(cx + 1, py, fmtSol(p.realisedSol).padStart(11), { fg: p.realisedSol > 0 ? t.up : p.realisedSol < 0 ? t.down : t.muted, bg });
+            cx = c.text(cx + 1, py, `${p.buys}b/${p.sells}s`.padEnd(8), { fg: t.dim, bg });
+            cx = c.text(cx + 1, py, `hold ${fmtHoldMs(p.holdMs)}`.padEnd(12), { fg: t.dim, bg });
+            if (p.flagged)
+                c.text(cx + 1, py, '(cost-0 lot: airdrop/transfer/unpriced)', { fg: t.dim, bg }, box.w - (cx + 1 - box.x) - 1);
+            py += 1;
+        }
+    }
+    c.textR(box.x + 1, footerY, box.w - 2, 'not a recommendation · a wallet\'s past fills say nothing about its next one', { fg: t.dim, bg, i: true });
 }

package/dist/packages/cli/src/screens/overlay.js

@@ -3,6 +3,7 @@
 // after the effects pass, so the card is crisp and no rain/scanline crosses it. Any key closes the
 // overlay; `?` toggles help.
 import { Canvas, DEFAULT_KEYMAP, mix } from '../../../tui/src/index.js';
+import { renderPnlOverlay } from "../pnl-app.js";
 /** Pretty single-key display for a keymap id ('enter' → '⏎', 'pagedown' → 'PgDn', 'ctrl+f' → '^F'). */
 function prettyKey(id) {
     switch (id) {
@@ -241,6 +242,8 @@ export function renderOverlay(c, state) {
         renderHelp(c, state);
     else if (state.overlay === 'workspaces')
         renderWorkspaces(c, state);
+    else if (state.overlay === 'pnl')
+        renderPnlOverlay(c, state);
     else if (state.overlay === 'links' && state.linkMenu) {
         const menu = state.linkMenu;
         const box = card(c, { w: 100, h: Math.min(24, menu.items.length * 2 + 6) }, 'ADVERTISED LINKS (UNTRUSTED)', 'j/k select · enter open · esc close');

package/dist/packages/cli/src/screens/positions.js

@@ -172,5 +172,5 @@ export function renderPositions(c, state) {
     }
     if (v.history.length === 0)
         c.text(hb.x + 1, hb.y, 'no paper trades yet', { fg: t.dim, bg: hb.bg });
-    footer(c, [['esc', 'back'], ['r', 'refresh'], ['1-4', 'screens'], ['q', 'quit']], t.name, isCalm(state.vfx));
+    footer(c, [['esc', 'back'], ['r', 'refresh'], ['H', 'PnL card'], ['1-4', 'screens'], ['q', 'quit']], t.name, isCalm(state.vfx));
 }

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

@@ -39,7 +39,7 @@ export function renderRules(c, state) {
         cy += 1;
         c.text(box.x + 1, cy, 'dexterm rules add "<rule>"         the same from a shell · rules list | check | dry-run | remove | enable | disable', { fg: t.dim, bg }, box.w - 2);
         cy += 1;
-        c.text(box.x + 1, cy, 'fields: price mcap fdv liq vol5m vol1h vol24 holders org top10 dev lplocked bundled snipers cluster age m5 h1 h6 h24 buys sells bonding', { fg: t.dim, bg }, box.w - 2);
+        c.text(box.x + 1, cy, 'fields: price mcap fdv liq vol5m vol1h vol24 holders org top10 dev lplocked bundled snipers cluster fresh mintable freezable age m5 h1 h6 h24 buys sells bonding', { fg: t.dim, bg }, box.w - 2);
         cy += 1;
         c.text(box.x + 1, cy, 'signals: <field>.velocity (× its own pace) · <field>.delta (change in the window) · tags: launchpad: flag: verified: sus:', { fg: t.dim, bg }, box.w - 2);
         cy += 2;