dexterm-cli 0.1.7 → 0.2.1

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

@@ -0,0 +1,367 @@
+// `dexterm overlay` — the STREAMER OVERLAY (task-1427): OBS browser-source scenes fed by the spectator stream.
+//
+//   dexterm overlay [--scene activity|coin|pnl|all]… [--theme cyberspace|ice|neon]
+//                   [--replay FILE [--speed N] [--loop]] [--ledger TRADE_ID [--sol-usd N]]
+//                   [--port N] [--ticket-ttl MIN] [--json]
+//
+// Data: the live, read-only, redacted spectator stream (the one `dexterm --spectate-mcp` or `dexterm agent serve
+// --spectate` opens; found through spectator.json, token sent in the hello, loopback only), or a saved recording
+// with --replay (every scene then carries a SAMPLE DATA tag). The PnL scene is the agent's PAPER fills on the coin
+// (stamped PAPER), or with --ledger one round trip of the user's own trade ledger (PAPER or LIVE by wallet mode).
+// Scenes: a loopback page per scene with a single-use ticket → token (overlay/server.ts). No network beyond
+// loopback, no inbound control path: the overlay watches; nothing here can arm, sign, size, trade or raise a cap.
+import { readFileSync } from 'node:fs';
+import { loadSpectatorRecording, sanitizeDetail } from '../../agents/src/index.js';
+import { spectatorInfoPath } from "./spectate-cmd.js";
+import { emptyOverlayState, foldOverlay, activityView, coinView } from "./overlay/model.js";
+import { pnlView, ledgerOverlayInput } from "./overlay/pnl.js";
+import { createOverlayServer, OVERLAY_PAGES, OVERLAY_TICKET_TTL_MS } from "./overlay/server.js";
+import { OVERLAY_THEME_NAMES } from "./overlay/page.js";
+export const OVERLAY_USAGE = `dexterm overlay [options]   streamer overlay: OBS browser-source scenes of the agent's session
+  --scene NAME        activity | coin | pnl | all (repeatable; default: the three scenes)
+  --theme NAME        ${OVERLAY_THEME_NAMES.join(' | ')} (default cyberspace)
+  --replay FILE       play a saved spectator recording instead of the live stream (scenes say SAMPLE DATA)
+  --speed N           replay speed (default 1) · --loop  replay again from the start when it ends
+  --ledger TRADE_ID   PnL scene from your own trade ledger (PAPER or LIVE stamp by wallet mode) instead of the
+                      agent's paper fills · --sol-usd N for a USD-booked trade
+  --port N            fixed loopback port (default random) · --ticket-ttl MIN  minutes a URL stays valid (default 10)
+  --json              print the scene URLs as JSON
+Each URL works ONCE (paste it into an OBS Browser source). Press n for fresh URLs, q to quit.
+Loopback only · read-only · addresses redacted · every scene shows its data age.
+Full docs: https://dexterm.xyz/docs/overlay/`;
+export function parseOverlayArgs(rest) {
+    const o = { scenes: [], theme: 'cyberspace', replay: null, speed: 1, loop: false, ledger: null, solUsd: null, port: undefined, ttlMin: OVERLAY_TICKET_TTL_MS / 60_000, json: false };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        const val = () => { const v = rest[++i]; return v === undefined || v.startsWith('--') ? null : v; };
+        switch (a) {
+            case '--scene': {
+                const v = val();
+                if (!v || !OVERLAY_PAGES.includes(v))
+                    return `--scene is one of ${OVERLAY_PAGES.join(', ')}`;
+                if (!o.scenes.includes(v))
+                    o.scenes.push(v);
+                break;
+            }
+            case '--theme': {
+                const v = val();
+                if (!v || !OVERLAY_THEME_NAMES.includes(v))
+                    return `--theme is one of ${OVERLAY_THEME_NAMES.join(', ')}`;
+                o.theme = v;
+                break;
+            }
+            case '--replay': {
+                const v = val();
+                if (!v)
+                    return '--replay needs a FILE';
+                o.replay = v;
+                break;
+            }
+            case '--speed': {
+                const n = Number(val());
+                if (!(n > 0 && n <= 100))
+                    return '--speed is a number from 0 to 100';
+                o.speed = n;
+                break;
+            }
+            case '--loop':
+                o.loop = true;
+                break;
+            case '--ledger': {
+                const v = val();
+                if (!v)
+                    return '--ledger needs a TRADE_ID (from `dexterm ledger trades`)';
+                o.ledger = v;
+                break;
+            }
+            case '--sol-usd': {
+                const n = Number(val());
+                if (!(n > 0))
+                    return '--sol-usd is a positive number';
+                o.solUsd = n;
+                break;
+            }
+            case '--port': {
+                const n = Number(val());
+                if (!Number.isInteger(n) || n < 1024 || n > 65535)
+                    return '--port is an integer from 1024 to 65535';
+                o.port = n;
+                break;
+            }
+            case '--ticket-ttl': {
+                const n = Number(val());
+                if (!(n >= 1 && n <= 240))
+                    return '--ticket-ttl is minutes from 1 to 240';
+                o.ttlMin = n;
+                break;
+            }
+            case '--json':
+                o.json = true;
+                break;
+            default: return `unknown option ${JSON.stringify(a)}`;
+        }
+    }
+    if (!o.scenes.length)
+        o.scenes = ['activity', 'coin', 'pnl'];
+    if (o.loop && !o.replay)
+        return '--loop only applies to --replay';
+    return o;
+}
+/**
+ * Folds events into the overlay state and pushes the scene views to the server. Public for the tests (they drive it
+ * with fixture events and a fake clock); the command wires it to the stream or a recording.
+ */
+export class OverlayEngine {
+    state;
+    server;
+    now;
+    pnlInput;
+    pnlEveryMs;
+    lastPnlAt = -Infinity;
+    lastPnlKey = '';
+    constructor(o) {
+        this.state = emptyOverlayState(o.sample);
+        this.server = o.server;
+        this.now = o.now ?? (() => Date.now());
+        this.pnlInput = o.pnlInput;
+        this.pnlEveryMs = o.pnlEveryMs ?? 10_000;
+    }
+    /** Start over (a looped replay): the scenes forget every coin, fill and call. */
+    reset() { Object.assign(this.state, emptyOverlayState(this.state.sample)); }
+    /** Fold one event read off the stream or a recording (untrusted data: the detail is re-validated first). */
+    feed(raw) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            return false;
+        const e = raw;
+        if (typeof e.phase !== 'string' || typeof e.t !== 'number' || !Number.isFinite(e.t))
+            return false;
+        // the stream and saved files are redacted (mints are head…tail), so the detail is validated in that shape
+        const ev = { ...e, detail: sanitizeDetail(e.detail, { masked: true }) };
+        foldOverlay(this.state, ev);
+        return true;
+    }
+    /** Push the current views (activity + coin always; the PnL card when its fills changed or it aged). */
+    tick() {
+        const now = this.now();
+        this.server.push('activity', activityView(this.state, now));
+        this.server.push('coin', coinView(this.state, now));
+        const p = this.state.paperCurrent ? this.state.paper.get(this.state.paperCurrent) : undefined;
+        const key = this.pnlInput ? 'ledger' : `${this.state.paperCurrent}:${p?.fills.length ?? 0}:${this.state.coins.get(this.state.paperCurrent ?? '')?.priceUsd?.at ?? 0}`;
+        if (key !== this.lastPnlKey || now - this.lastPnlAt >= this.pnlEveryMs) {
+            this.lastPnlKey = key;
+            this.lastPnlAt = now;
+            let input = null;
+            let note = null;
+            if (this.pnlInput) {
+                try {
+                    input = this.pnlInput();
+                }
+                catch (err) {
+                    note = err.message;
+                }
+            }
+            const view = pnlView(this.state, now, input);
+            this.server.push('pnl', note ? { ...view, note } : view);
+        }
+    }
+}
+function ledgerLoader(io, tradeId, solUsd) {
+    let row = null;
+    let problem = 'reading the trade ledger…';
+    return {
+        async load() {
+            try {
+                const at = await import('../../autotrade/src/index.js');
+                const v = await at.loadLedgerView({ env: io.env, now: Date.now() });
+                const t = v.trades.find((x) => x.tradeId === tradeId);
+                if (!t) {
+                    row = null;
+                    problem = `no trade ${tradeId} in the trade ledger`;
+                    return;
+                }
+                row = t;
+                problem = null;
+            }
+            catch (e) {
+                row = null;
+                problem = `trade ledger: ${e.message}`;
+            }
+        },
+        input() {
+            if (!row)
+                throw new Error(problem ?? 'no ledger trade');
+            return ledgerOverlayInput(row, solUsd ? { usd: solUsd, source: '--sol-usd' } : null);
+        },
+    };
+}
+export async function runOverlay(rest, io) {
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    if (rest.includes('--help') || rest.includes('-h')) {
+        out(OVERLAY_USAGE);
+        return 0;
+    }
+    const o = parseOverlayArgs(rest);
+    if (typeof o === 'string') {
+        errOut(`dexterm overlay: ${o}`);
+        errOut(OVERLAY_USAGE);
+        return 2;
+    }
+    let recording = null;
+    if (o.replay) {
+        try {
+            recording = loadSpectatorRecording(o.replay);
+        }
+        catch (e) {
+            errOut(`dexterm overlay: cannot read ${o.replay}: ${e.message}`);
+            return 1;
+        }
+        if (!recording.events.length) {
+            errOut(`dexterm overlay: ${o.replay} has no events`);
+            return 1;
+        }
+    }
+    let server;
+    try {
+        server = await createOverlayServer({
+            port: o.port, ticketTtlMs: o.ttlMin * 60_000,
+            onEvent: (ev) => { if (ev.ev === 'probe.rejected')
+                errOut(`overlay: refused ${ev.method} ${ev.path} (${ev.reason})`); },
+        });
+    }
+    catch (e) {
+        errOut(`dexterm overlay: cannot listen on 127.0.0.1${o.port ? `:${o.port}` : ''}: ${e.message}`);
+        return 1;
+    }
+    const ledger = o.ledger ? ledgerLoader(io, o.ledger, o.solUsd) : null;
+    if (ledger)
+        await ledger.load();
+    const engine = new OverlayEngine({ sample: !!recording, server, ...(ledger ? { pnlInput: () => ledger.input() } : {}) });
+    const printUrls = () => {
+        const urls = o.scenes.map((s) => ({ scene: s, url: server.issueTicket(s, o.theme) }));
+        if (o.json) {
+            out(JSON.stringify({ theme: o.theme, sample: !!recording, ttlMin: o.ttlMin, scenes: urls }));
+            return;
+        }
+        out(`dexterm overlay · theme ${o.theme}${recording ? ' · SAMPLE DATA (replay)' : ''} · each URL works once, for ${o.ttlMin} min`);
+        for (const u of urls)
+            out(`  ${u.scene.padEnd(9)} ${u.url}`);
+    };
+    printUrls();
+    if (!o.json)
+        out(recording ? `replaying ${recording.events.length} event(s) from ${o.replay}` : 'watching the live spectator stream (start one with `dexterm --spectate-mcp` or `dexterm agent serve --spectate`)');
+    const timers = [];
+    let stopped = false;
+    let ws = null;
+    // ---- data source
+    if (recording) {
+        const evs = recording.events;
+        let i = 0;
+        const step = () => {
+            if (stopped)
+                return;
+            if (i >= evs.length) {
+                if (!o.loop)
+                    return;
+                i = 0;
+                engine.reset();
+            }
+            const ev = evs[i];
+            // replayed events are re-timed to the playback clock (a signal's own `at` shifts with them), so their ages
+            // read as "this long ago in the replay"
+            const shift = Date.now() - ev.t;
+            const flags = ev.detail?.liveFlags;
+            engine.feed({ ...ev, t: ev.t + shift, ...(flags ? { detail: { ...ev.detail, liveFlags: flags.map((f) => ({ ...f, at: (typeof f.at === 'number' ? f.at : ev.t) + shift })) } } : {}) });
+            const next = evs[i + 1];
+            i++;
+            // the end of a looped replay holds its final scenes (the PnL card lands last) before it starts again
+            const gap = next ? Math.min(5000, Math.max(0, next.t - ev.t)) / o.speed : 10_000;
+            timers.push(setTimeout(step, gap));
+        };
+        step();
+    }
+    else {
+        const connect = () => {
+            if (stopped)
+                return;
+            let info;
+            try {
+                info = JSON.parse(readFileSync(spectatorInfoPath(io.env), 'utf8'));
+            }
+            catch {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            if (!Number.isInteger(info.port) || typeof info.token !== 'string') {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            try {
+                ws = new WebSocket(`ws://127.0.0.1:${info.port}`);
+            }
+            catch {
+                timers.push(setTimeout(connect, 3000));
+                return;
+            }
+            const token = info.token;
+            ws.onopen = () => ws?.send(JSON.stringify({ method: 'hello', token }));
+            ws.onmessage = (m) => {
+                let msg;
+                try {
+                    msg = JSON.parse(String(m.data));
+                }
+                catch {
+                    return;
+                }
+                if (msg && msg.type === 'event')
+                    engine.feed(msg.event);
+            };
+            ws.onclose = () => { ws = null; if (!stopped)
+                timers.push(setTimeout(connect, 3000)); };
+            ws.onerror = () => { };
+        };
+        connect();
+    }
+    const ticker = setInterval(() => engine.tick(), 1000);
+    engine.tick();
+    const ledgerTimer = ledger ? setInterval(() => { void ledger.load(); }, 30_000) : null;
+    return new Promise((resolve) => {
+        const stop = () => {
+            if (stopped)
+                return;
+            stopped = true;
+            clearInterval(ticker);
+            if (ledgerTimer)
+                clearInterval(ledgerTimer);
+            for (const t of timers)
+                clearTimeout(t);
+            try {
+                ws?.close();
+            }
+            catch { /* ignore */ }
+            if (io.stdin.isTTY) {
+                try {
+                    io.stdin.setRawMode(false);
+                }
+                catch { /* ignore */ }
+                io.stdin.pause();
+            }
+            process.off('SIGINT', stop);
+            process.off('SIGTERM', stop);
+            void server.close().then(() => resolve(0));
+        };
+        process.on('SIGINT', stop);
+        process.on('SIGTERM', stop);
+        if (io.stdin.isTTY) {
+            io.stdin.setRawMode(true);
+            io.stdin.resume();
+            io.stdin.on('data', (d) => {
+                const k = d.toString();
+                if (k === 'q' || k === '\u0003')
+                    stop();
+                else if (k === 'n')
+                    printUrls();
+            });
+        }
+    });
+}

package/dist/packages/cli/src/pnl-card.js

@@ -138,6 +138,10 @@ export function autotradeCardInput(events, o) {
  * needs `solUsd`; a fill with no token amount refuses the card rather than guess.
  */
 export function ledgerCardInput(row, o = {}) {
+    // task-1655: a real-mode row is dexterm's model of a trade it signalled; the real fill is the executor's receipt.
+    // A card would stamp it PAPER or LIVE, and both are wrong, so there is none.
+    if (row.walletMode === 'real')
+        throw new CardError('a real-mode trade: dexterm only modelled this fill (the signal it sent your executor); your executor\'s receipt is the record, so dexterm makes no card for it');
     const decimals = row.decimals ?? 6;
     const usdDesk = row.fills.some((f) => f.sol === null);
     if (usdDesk && !(o.solUsd && o.solUsd.usd > 0))

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

@@ -1,3 +1,11 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 // 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
@@ -20,13 +28,17 @@
 // re-installed with them: `--retention-mb N` replaces that pause with eviction of the oldest history (observation
 // never pauses), `--retention-days D` is the age rule for snapshot rows, and `--focus-ticks` runs the autotrade
 // tick lane (5–10 s DexScreener samples of watchlist / held / candidate / open coins, plus 1m candles).
+// task-1786 (winner-recall DATA-GAPS items 1-2), opt-in the same way: `--focus-module PATH` loads an ESM module whose
+// `focus(now)` adds focus coins to the tick lane (the challenge / control coins live outside the app; the module that
+// reads them lives with them), and `--exit-probes` adds a keyless Jupiter sell quote for every held focus coin once a
+// minute (exit-probes.ts). Both imply --focus-ticks.
 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 { fileURLToPath, pathToFileURL } from 'node:url';
 import { defaultDbPath, resolveRpcUrl, extraRpcUrls, redactSecrets } from '../../data/src/index.js';
 import { PumpPortalClient } from '../../data/src/index.js';
-import { Recorder, recorderEnabled, dbFocus, focusFilePath, readFocusFile, DEFAULT_TICKS } from '../../recorder/src/index.js';
+import { Recorder, recorderEnabled, dbFocus, focusFilePath, readFocusFile, exitProbeDeps, DEFAULT_TICKS } from '../../recorder/src/index.js';
 import { dextermHome } from "./boot-state.js";
 import { createLiveFeed } from "./feed.js";
 import { NewPairsLive } from "./live/index.js";
@@ -50,13 +62,30 @@ export function buildLiveEngine(env, opts) {
     // Focus coins for the tick lane: the watchlist + paper positions in this DB, and whatever the autotrade runner /
     // the app publish in the focus file. Read on every poll (two indexed reads + one small file).
     const focusFile = focusFilePath(dextermHome(env));
+    // task-1786: the focus module's coins. A throwing module costs its own coins only (logged at most every 10 min).
+    let extraFailedAt = -Infinity;
+    const extra = () => {
+        if (!opts.extraFocus)
+            return [];
+        try {
+            return [...opts.extraFocus()];
+        }
+        catch (e) {
+            if (Date.now() - extraFailedAt > 600_000) {
+                extraFailedAt = Date.now();
+                opts.onLog?.(`record: focus module failed: ${redactSecrets(e.message)}\n`);
+            }
+            return [];
+        }
+    };
     const recorder = new Recorder({
         path: opts.dbPath, onLog: opts.verbose ? opts.onLog : undefined,
         // The cap reclaims the data layer's expired cache entries (its own rule: a day past their TTL) before it evicts
         // any history; `feed` is built above, so the hook can reach it.
         ...(opts.retentionBytes ? { cap: { maxBytes: opts.retentionBytes, reclaim: () => feed.dl.cache.prune() } } : {}),
         ...(opts.retentionDays ? { retention: { columnsDays: opts.retentionDays } } : {}),
-        ...(opts.focusTicks ? { ticks: { focus: () => [...dbFocus(recorder.database), ...readFocusFile(focusFile, Date.now())] } } : {}),
+        ...(opts.focusTicks ? { ticks: { focus: () => [...dbFocus(recorder.database), ...readFocusFile(focusFile, Date.now()), ...extra()] } } : {}),
+        ...(opts.focusTicks && opts.exitProbes ? { exitProbes: {} } : {}),
     });
     recorder.attach(feed.dl.store);
     let newpairs = null;
@@ -71,6 +100,7 @@ export function buildLiveEngine(env, opts) {
         feed.extraMints = () => [...np.rows.keys()];
     }
     const dl = feed.dl;
+    const probeDeps = exitProbeDeps(dl);
     return {
         async observe() {
             const before = recorder.counters.written;
@@ -83,7 +113,14 @@ export function buildLiveEngine(env, opts) {
         }
         catch { /* logged inside; never fatal */ } },
         enforceCap() { return recorder.enforceCap(); },
-        ...(opts.focusTicks ? { pollTicks: () => recorder.pollTicks(dl) } : {}),
+        ...(opts.focusTicks ? { pollTicks: async () => {
+                const r = await recorder.pollTicks(dl);
+                // Detached: a quote waiting on the Jupiter bucket must never delay the next 5 s tick (the lane's own in-flight
+                // guard keeps one probe pass at a time; it never throws).
+                if (opts.exitProbes)
+                    void recorder.probeExits(probeDeps).catch(() => { });
+                return r;
+            } } : {}),
         dbBytes() {
             try {
                 const db = recorder.database;
@@ -261,6 +298,19 @@ function parseRetention(t, next, a) {
         a.focusTicks = true;
         return null;
     }
+    if (t === '--exit-probes') {
+        a.exitProbes = true;
+        a.focusTicks = true;
+        return null;
+    }
+    if (t === '--focus-module') {
+        const v = next();
+        if (!v || v.startsWith('--'))
+            return '--focus-module needs a PATH';
+        a.focusModule = resolve(v);
+        a.focusTicks = true;
+        return null;
+    }
     if (t === '--retention-mb') {
         const n = Number(next());
         if (!Number.isFinite(n) || n < 1)
@@ -278,7 +328,7 @@ function parseRetention(t, next, a) {
     return undefined;
 }
 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, retentionBytes: null, retentionDays: null, focusTicks: false };
+    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, retentionBytes: null, retentionDays: null, focusTicks: false, focusModule: null, exitProbes: false };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
         const r = parseRetention(t, () => argv[++i], a);
@@ -329,8 +379,9 @@ export function parseRun(argv) {
 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] [--retention-mb N] [--retention-days D]
-                       [--focus-ticks] [--no-newpairs] [--db PATH] [--verbose]
-  dexterm record install   [--interval S] [--max-db-mb N] [--retention-mb N] [--retention-days D] [--focus-ticks] [--load] [--dry-run]
+                       [--focus-ticks] [--focus-module PATH] [--exit-probes] [--no-newpairs] [--db PATH] [--verbose]
+  dexterm record install   [--interval S] [--max-db-mb N] [--retention-mb N] [--retention-days D] [--focus-ticks]
+                           [--focus-module PATH] [--exit-probes] [--load] [--dry-run]
   dexterm record uninstall [--unload]
   dexterm record status    [--db PATH]
 
@@ -341,7 +392,10 @@ run        the collector loop: one keyless feed refresh per --interval (default
            to stay under N MB and observation never pauses. --retention-days D drops snapshot rows (sweep rows
            too) older than D days (default 90). --focus-ticks samples watchlist / held / candidate / open coins
            every 5-10 s (DexScreener batches of 30, a daily call ceiling) with 1m candles; autotrade backtests
-           read them. --no-newpairs drops the PumpPortal stream. Ctrl-C stops cleanly
+           read them. --focus-module PATH adds the coins an ESM module's focus(now) returns
+           ([{ mint, role }], role held | open | candidate | watch) to that lane. --exit-probes asks Jupiter for
+           a keyless $50 sell quote of every held focus coin once a minute (exit_probes; quotes only).
+           Both imply --focus-ticks. --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.
@@ -404,7 +458,22 @@ async function run(argv, io, deps) {
         };
     })();
     const log = (s) => io.stderr.write(s);
-    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log, retentionBytes: parsed.retentionBytes, retentionDays: parsed.retentionDays, focusTicks: parsed.focusTicks });
+    // task-1786: the focus module is loaded once, up front; a module that does not load is a startup error (exit 2).
+    let extraFocus;
+    if (parsed.focusModule) {
+        try {
+            const mod = await import(__rewriteRelativeImportExtension(pathToFileURL(parsed.focusModule).href));
+            if (typeof mod.focus !== 'function')
+                throw new Error('it exports no focus(now) function');
+            const fn = mod.focus;
+            extraFocus = () => fn(Date.now());
+        }
+        catch (e) {
+            io.stderr.write(`dexterm record: --focus-module ${parsed.focusModule}: ${redactSecrets(e.message)}\n`);
+            return 2;
+        }
+    }
+    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log, retentionBytes: parsed.retentionBytes, retentionDays: parsed.retentionDays, focusTicks: parsed.focusTicks, extraFocus, exitProbes: parsed.exitProbes });
     const own = !deps.engine;
     const onSig = () => { io.stderr.write('\ndexterm record: stopping…\n'); stop.abort(); };
     if (own) {
@@ -415,7 +484,7 @@ async function run(argv, io, deps) {
     // alive between passes and node would exit mid-run (task-1504 smoke). Hold it open until the loops finish.
     const hold = own ? setInterval(() => { }, 1 << 30) : null;
     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'}${parsed.retentionBytes !== null ? ` · retention ${Math.round(parsed.retentionBytes / 1e6)} MB (evict, never pause)` : ''}${parsed.retentionDays !== null ? ` · rows ${parsed.retentionDays} d` : ''} · focus ticks ${parsed.focusTicks ? 'on' : 'off'}\n`);
+        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'}${parsed.retentionBytes !== null ? ` · retention ${Math.round(parsed.retentionBytes / 1e6)} MB (evict, never pause)` : ''}${parsed.retentionDays !== null ? ` · rows ${parsed.retentionDays} d` : ''} · focus ticks ${parsed.focusTicks ? 'on' : 'off'}${parsed.focusModule ? ` · focus module ${parsed.focusModule}` : ''}${parsed.exitProbes ? ' · exit probes on' : ''}\n`);
     let result;
     let tickRes = { polls: 0, calls: 0, written: 0 };
     try {
@@ -446,7 +515,7 @@ async function run(argv, io, deps) {
 }
 function install(argv, io) {
     let intervalMs = DEFAULT_INTERVAL_MS, maxDbMb = DEFAULT_MAX_DB_MB, load = false, dry = false;
-    const ret = { retentionBytes: null, retentionDays: null, focusTicks: false };
+    const ret = { retentionBytes: null, retentionDays: null, focusTicks: false, focusModule: null, exitProbes: false };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
         const r = parseRetention(t, () => argv[++i], ret);
@@ -488,6 +557,8 @@ function install(argv, io) {
         ...(ret.retentionBytes !== null ? ['--retention-mb', String(Math.round(ret.retentionBytes / 1e6))] : []),
         ...(ret.retentionDays !== null ? ['--retention-days', String(ret.retentionDays)] : []),
         ...(ret.focusTicks ? ['--focus-ticks'] : []),
+        ...(ret.focusModule ? ['--focus-module', ret.focusModule] : []),
+        ...(ret.exitProbes ? ['--exit-probes'] : []),
     ];
     const plist = renderCollectorPlist({ label: COLLECTOR_LABEL, nodePath: process.execPath, binPath: bin, intervalMs, maxDbMb, extraArgs, logPath, workingDir: resolve(dirname(bin), '..', '..', '..') });
     if (dry) {

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

@@ -119,8 +119,9 @@ export async function rulesCommand(argv, io) {
         case 'fields': {
             io.stdout.write(`fields:  ${FIELD_NAMES.join(' ')}\n`);
             io.stdout.write(`aliases: vol volume liquidity cap mc holder organic top locked cluster% clusterpct\n`);
+            io.stdout.write(`narrative (EXPERIMENTAL, measured heat, not advice): narrative_rank narrative_score narrative:spark|ignition|peak|fading|dead|saturated (null until N → n builds the tracker)\n`);
             io.stdout.write(`signals: <field>.velocity (current ÷ mean of earlier samples in the window) · <field>.delta (current − oldest in the window)\n`);
-            io.stdout.write(`tags:    ${TAG_NAMES.map((t) => t + ':').join(' ')}  (e.g. launchpad:pump flag:mint flag:clean verified:yes sus:no; prefix ! to negate)\n`);
+            io.stdout.write(`tags:    ${TAG_NAMES.map((t) => t + ':').join(' ')}  (e.g. launchpad:pump flag:mint flag:clean verified:yes sus:no narrative:ignition narrative:saturated; prefix ! to negate)\n`);
             io.stdout.write(`values:  $1.5M 25K 2B 20% 2h 30m 3d · ops > >= < <= = != · and or not ( )\n`);
             io.stdout.write(`actions: ${ACTIONS.join(' ')}  alert(level, "text") ticket(buy|sell, size ≤ ${TICKET_SIZE_CAP}, sol|usd|pct) ask(skill) popup(${RULE_POPUP_KINDS.join('|')}) tag("label") sound(name) watch\n`);
             io.stdout.write(`limits:  cooldown (default 10m) · max n/h (default 12, cap ${MAX_PER_HOUR_CAP}) · scope ${SCOPES.join('|')}|mint:<addr> · window (default 10m)\n`);

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

@@ -1,4 +1,16 @@
+// dexterm — the rules engine's app adapter (task-1358 Tier 3). Pure helpers over @dexterm/custom's RulesEngine
+// that the key handler, the interactive loop and the Rules screen call: load `config.rules` into an engine on
+// `state.rulesUi`, feed it the screener rows every few seconds (`rulesTick`), turn its outputs into things the
+// app can show (toasts, the screen's log, PROPOSAL cards, pending UI actions the loop performs), and persist edits
+// through the config journal (so `dexterm config undo` / the journal cover rules too).
+//
+// SAFETY: a rule's outputs are alerts, annotations (watch/tag on the user's own watchlist), UI actions (popup /
+// terminal bell) and PROPOSALS. Acting on a ticket proposal opens the PAPER ticket in its editing phase (the user
+// sizes and confirms there, signer caps apply); acting on an ask proposal sends a question to the analyst. Nothing
+// in this module can arm, sign, confirm, open a live ticket or touch a mandate — there is no code path for it.
+import { classifierLiveTick } from "./classifier-live.js";
 import { devBookOf } from "./live/dev-history.js";
+import { narrativeRuleFields } from "./narratives.js";
 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;
@@ -56,6 +68,11 @@ export function larpGrade(verdict) {
  * `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.
  */
+/** task-1822: the classifier's drain estimate for the `rugp` field (null when unscored or the scoring failed). */
+function rugpOf(state, mint) {
+    const p = state.classifierByMint?.get(mint)?.p;
+    return typeof p === 'number' && Number.isFinite(p) ? p : null;
+}
 export function ruleRowsOf(state) {
     const out = [];
     const seen = new Set();
@@ -70,11 +87,13 @@ export function ruleRowsOf(state) {
     // 0.1.5 dev history: the creator's recorded rugs as the `devrugs` field (local recorder only; null = unknown).
     const book = devBookOf(state);
     const devRugsOf = (mint) => book ? book.rugsFor(mint) : null;
+    // task-1818: narrative_rank / narrative_score / narrative:<state> from the ALREADY-built narratives tracker (never builds one)
+    const narr = (mint) => narrativeRuleFields(state, mint);
     for (const r of state.screener.rows) {
         if (!r.mint || r.skeleton || seen.has(r.mint))
             continue;
         seen.add(r.mint);
-        const row = Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict), devRugs: devRugsOf(r.mint) });
+        const row = Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint), larp: larpGrade(state.larpByMint?.get(r.mint)?.verdict), devRugs: devRugsOf(r.mint), rugP: rugpOf(state, r.mint) }, narr(r.mint));
         if (r.mint === openMint)
             overlaySignalFields(row, state, r.mint);
         out.push(row);
@@ -85,9 +104,9 @@ export function ruleRowsOf(state) {
         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), devRugs: devRugsOf(v.mint),
+            cluster: clusterOf(v.mint), larp: larpGrade(state.larpByMint?.get(v.mint)?.verdict), devRugs: devRugsOf(v.mint), rugP: rugpOf(state, v.mint),
             ageMin: v.ageMin, chg: v.chg, launchpad: v.launchpad, flags: v.flags, verified: v.verified, sus: v.sus,
-        });
+        }, narr(v.mint));
         overlaySignalFields(row, state, v.mint);
         out.push(row);
     }
@@ -107,7 +126,7 @@ export function ruleRowsOf(state) {
             out.push(Object.assign(Object.create(null), {
                 mint: p.mint, symbol: p.symbol, mcap: p.mcap, liq: p.liq, holders: p.holders, launchpad: p.launchpad,
                 ageMin: p.createdAt ? Math.max(0, (now - p.createdAt) / 60_000) : null, bonding: p.bonding, devRugs,
-            }));
+            }, narr(p.mint)));
         }
     }
     return out;
@@ -153,6 +172,7 @@ export function rulesTick(state, now) {
     const rows = ruleRowsOf(state);
     if (!rows.length)
         return null;
+    classifierLiveTick(state, rows, now); // task-1822: fills classifierByMint for `rugp` rules (a no-op without one)
     ui.engine.observe(rows, now);
     const watch = state.live?.watch.store ?? null;
     const positions = state.live?.positions ?? null;