dexterm-cli 0.1.5 → 0.1.7

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

@@ -9,11 +9,12 @@
 // changed, otherwise just the last two bars ("tail"), so a live tick costs the page one `series.update`.
 // When the coin is held (task-1323 PositionSource) the VM carries the position row + entry/stop/target levels
 // and the fills of the current position from the paper ledger. Read-only: nothing here can trade.
-import { createPopupManager, loadConfig, nativeShellAvailable, TerminalDock, CHART_INTERVALS } from '../../popup/src/index.js';
+import { createPopupManager, loadConfig, nativeShellAvailable, TerminalDock, CHART_INTERVALS, CHART_MARKS_MAX } from '../../popup/src/index.js';
 import { fmtPrice, fmtNum } from '../../tui/src/index.js';
 import { positionRow } from "./live/trade.js";
 import { signedUsd, signedPctOf, fmtUsdFine, sol as fmtSol, signedSol } from "./screens/positions.js";
-import { supplyRatio, positionPriceCells } from "./display.js";
+import { supplyRatio, positionPriceCells, levelCell } from "./display.js";
+import { chipSegments } from "./screens/pnl-chip.js";
 /** Map the app's active Theme to the popup protocol's theme-token subset. */
 export function popupThemeFrom(t) {
     return {
@@ -25,6 +26,11 @@ export function popupThemeFrom(t) {
 /** Most bars one VM carries (the 1m base is 1000 bars; this only guards a future bigger base). */
 export const CHART_MAX_BARS = 1500;
 export const DEFAULT_CHART_PREFS = { style: 'candles', scale: 'auto', indicators: ['volume', 'tape', 'ema9', 'ema21'] };
+/** task-1483: the VM's markers layer: the newest CHART_MARKS_MAX fills (oldest first), and how many older ones were left out. */
+export function chartMarksFrom(on, fills) {
+    const keep = fills.length > CHART_MARKS_MAX ? fills.slice(-CHART_MARKS_MAX) : fills;
+    return { on, fills: keep.map((f) => ({ t: f.t, side: f.side, source: f.source, priceUsd: f.priceUsd, tokens: f.tokens, sol: f.sol })), truncated: fills.length - keep.length };
+}
 const finitePos = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
 /** Token amounts up to trillions (same rule as the terminal's position row). */
 function fmtAmt(n) { return n >= 1e12 ? `${(n / 1e12).toFixed(2)}T` : fmtNum(n); }
@@ -56,9 +62,9 @@ export function positionCells(r, mode = 'price', supply = null) {
     if (r.realizedSol !== 0)
         cells.push({ label: 'REALIZED', value: usd && r.realizedUsd !== null ? signedUsd(r.realizedUsd) : `${signedSol(r.realizedSol)} SOL`, tone: tone(r.realizedSol) });
     if (r.stopUsd !== null)
-        cells.push({ label: 'STOP', value: `${fmtPrice(r.stopUsd)}${r.stopDistPct !== null ? ` ${signedPctOf(r.stopDistPct)}` : ''}`, tone: 'down' });
+        cells.push({ label: 'STOP', value: `${levelCell(mode, supply, r.stopUsd)}${r.stopDistPct !== null ? ` ${signedPctOf(r.stopDistPct)}` : ''}`, tone: 'down' });
     if (r.targetUsd !== null)
-        cells.push({ label: 'TARGET', value: `${fmtPrice(r.targetUsd)}${r.targetDistPct !== null ? ` ${signedPctOf(r.targetDistPct)}` : ''}`, tone: 'up' });
+        cells.push({ label: 'TARGET', value: `${levelCell(mode, supply, r.targetUsd)}${r.targetDistPct !== null ? ` ${signedPctOf(r.targetDistPct)}` : ''}`, tone: 'up' });
     return cells;
 }
 /** The chart's position model from the shared task-1323 selector (PositionSource → positionRow). */
@@ -137,7 +143,7 @@ export function chartVMFromView(v, x = {}) {
     vm.feed = x.feed ?? 'POLL';
     vm.livePrice = x.feed === 'LIVE' && finitePos(x.livePrice) ? x.livePrice : null;
     vm.trades = v.trades.map((t) => ({ t: t.t, side: t.side, usd: t.usd, price: t.price })); // no wallet addresses
-    const mode = x.priceMode === 'mcap' ? 'mcap' : 'price';
+    const mode = x.priceMode === 'price' ? 'price' : 'mcap'; // task-1537: market cap unless the host says price
     const supply = mode === 'mcap' ? supplyRatio(v.price, v.mcap) : null;
     vm.position = x.held ? chartPositionFrom(x.held, tick, x.solUsd ?? null, x.positionKind ?? 'paper', x.fills ?? [], mode, supply) : null;
     vm.prefs = x.prefs ?? DEFAULT_CHART_PREFS;
@@ -146,6 +152,8 @@ export function chartVMFromView(v, x = {}) {
     // task-1366: display only — the bars stay USD prices; the page formats the axis as price × supply in mcap mode
     vm.priceMode = mode;
     vm.supply = supply;
+    if (x.marks)
+        vm.marks = chartMarksFrom(x.marks.on, x.marks.fills); // task-1483
     return vm;
 }
 /** Build the token-detail popup view model from the live TokenView (reused by the openPopup interface / Jarvis). */
@@ -160,6 +168,12 @@ export function tokenDetailVMFromView(v, intel = null) {
         flags: v.flags.map((f) => String(f)), holdersSample: v.holdersSample, updatedAt: v.updatedAt,
     };
 }
+/** task-1473 r2: the chip as the chart page draws it (same segments as the terminal). */
+export function chartChipFrom(m) {
+    if (!m)
+        return null;
+    return { kind: m.kind, symbol: m.symbol, tone: m.pnlPct === null ? 'muted' : m.pnlPct >= 0 ? 'up' : 'down', newPeak: m.newPeak, segments: chipSegments(m) };
+}
 /** "docked right of Terminal" / "screen right (unknown terminal)" — for the TUI toast. */
 export function describeDock(p) {
     if (!p)
@@ -432,6 +446,22 @@ export class TokenPopups {
             case 'chart.scale':
                 this.prefs = { ...this.prefs, scale: p.scale };
                 return;
+            case 'chart.axis': { // task-1472: a display preference the terminal saves; nothing else
+                if (p.axis !== 'mcap' && p.axis !== 'price')
+                    return;
+                this.source?.setChartAxis?.(p.axis);
+                if (this.lastView)
+                    this.push(this.lastView);
+                return;
+            }
+            case 'chart.markers': { // task-1483: a display preference the terminal saves; nothing else
+                if (typeof p.on !== 'boolean')
+                    return;
+                this.source?.setChartMarkers?.(p.on);
+                if (this.lastView)
+                    this.push(this.lastView);
+                return;
+            }
             case 'chart.painted': {
                 const ms = Number(p.ms);
                 if (p.kind === 'first' && this.metrics.openedAt !== null && this.metrics.openToFirstPaintMs === null)
@@ -520,8 +550,10 @@ export class TokenPopups {
             prefs: this.prefs,
             now: this.now(),
             image: src.imagePath?.(view) ?? null,
-            priceMode: src.priceMode?.() ?? 'price',
+            priceMode: src.chartAxis?.() ?? src.priceMode?.() ?? 'mcap', // task-1472: the chart axis drives the popup
+            marks: src.markFills ? { on: src.chartMarkers?.() ?? true, fills: src.markFills(view.mint) } : null, // task-1483
         });
+        vm.chip = chartChipFrom(src.pnlChip?.() ?? null); // task-1473 r2
         const key = vm.seriesKey ?? null;
         const n = vm.candles.length;
         const canTail = !full && this.ready && key !== null && key === this.lastKey && this.lastLen > 0 && n >= this.lastLen && n <= this.lastLen + 1;

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

@@ -4,8 +4,9 @@
 // (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 [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]
 //   dexterm record uninstall [--unload]
 //   dexterm record status    [--db PATH]
 //
@@ -15,13 +16,18 @@
 // 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.
+// task-1504 (AUTOTRADE-SPEC §3, §10 Q4), both opt-in so an installed collector behaves as before until it is
+// 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).
 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 { Recorder, recorderEnabled, dbFocus, focusFilePath, readFocusFile, DEFAULT_TICKS } from '../../recorder/src/index.js';
+import { dextermHome } from "./boot-state.js";
 import { createLiveFeed } from "./feed.js";
 import { NewPairsLive } from "./live/index.js";
 /** The LaunchAgent label (reverse-DNS). One collector per user. */
@@ -41,7 +47,17 @@ export function buildLiveEngine(env, opts) {
         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 });
+    // 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));
+    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())] } } : {}),
+    });
     recorder.attach(feed.dl.store);
     let newpairs = null;
     if (!opts.noNewpairs) {
@@ -66,6 +82,8 @@ export function buildLiveEngine(env, opts) {
             recorder.prune();
         }
         catch { /* logged inside; never fatal */ } },
+        enforceCap() { return recorder.enforceCap(); },
+        ...(opts.focusTicks ? { pollTicks: () => recorder.pollTicks(dl) } : {}),
         dbBytes() {
             try {
                 const db = recorder.database;
@@ -101,7 +119,7 @@ export function buildLiveEngine(env, opts) {
  * 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 };
+    const res = { ticks: 0, observePasses: 0, rowsWritten: 0, maintainPasses: 0, cappedTicks: 0, evictions: 0 };
     let lastMaintain = -Infinity;
     for (let i = 0; i < opts.ticks && !opts.aborted(); i++) {
         if (i > 0) {
@@ -111,7 +129,19 @@ export async function runCollectorLoop(engine, opts) {
         }
         res.ticks++;
         let over = false;
-        if (opts.maxDbBytes !== null) {
+        if (opts.capMode === 'evict') {
+            try {
+                const c = engine.enforceCap?.() ?? null;
+                if (c?.evicted)
+                    res.evictions++;
+                if (c?.over)
+                    opts.onLog?.(`record: DB still at ${(c.usedAfter / 1e6).toFixed(0)} MB used after evicting all but the newest hour (other tables are large); observation continues\n`);
+            }
+            catch (e) {
+                opts.onLog?.(`record: retention failed: ${redactSecrets(e.message)}\n`);
+            }
+        }
+        else if (opts.maxDbBytes !== null) {
             const b = engine.dbBytes();
             if (b !== null && b >= opts.maxDbBytes) {
                 engine.prune();
@@ -146,6 +176,29 @@ export async function runCollectorLoop(engine, opts) {
     }
     return res;
 }
+/** task-1504: drive the tick lane every `everyMs` until aborted. Never throws (a failed poll is logged). */
+export async function runTickLoop(engine, opts) {
+    const res = { polls: 0, calls: 0, written: 0 };
+    if (!engine.pollTicks)
+        return res;
+    while (!opts.aborted()) {
+        try {
+            const r = await engine.pollTicks();
+            res.polls++;
+            res.calls += r.calls;
+            res.written += r.written;
+            if (r.error)
+                opts.onLog?.(`record: tick poll failed: ${redactSecrets(r.error)}\n`);
+        }
+        catch (e) {
+            opts.onLog?.(`record: tick poll failed: ${redactSecrets(e.message)}\n`);
+        }
+        if (opts.aborted())
+            break;
+        await opts.sleep(opts.everyMs);
+    }
+    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,
@@ -155,7 +208,7 @@ const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g,
  * 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 args = [o.nodePath, o.binPath, 'record', 'run', '--interval', String(Math.round(o.intervalMs / 1000)), '--max-db-mb', String(o.maxDbMb), ...(o.extraArgs ?? [])];
     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">
@@ -202,10 +255,37 @@ function dataDir(env, db) {
 function sourceBin() {
     return fileURLToPath(new URL('../bin/dexterm.mjs', import.meta.url));
 }
+/** task-1504: the shared `--retention-mb` / `--retention-days` / `--focus-ticks` parser (run + install). */
+function parseRetention(t, next, a) {
+    if (t === '--focus-ticks') {
+        a.focusTicks = true;
+        return null;
+    }
+    if (t === '--retention-mb') {
+        const n = Number(next());
+        if (!Number.isFinite(n) || n < 1)
+            return '--retention-mb needs a number ≥ 1';
+        a.retentionBytes = Math.round(n * 1_000_000);
+        return null;
+    }
+    if (t === '--retention-days') {
+        const n = Number(next());
+        if (!Number.isFinite(n) || n < 1)
+            return '--retention-days needs a number of days ≥ 1';
+        a.retentionDays = n;
+        return null;
+    }
+    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 };
+    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 };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
+        const r = parseRetention(t, () => argv[++i], a);
+        if (typeof r === 'string')
+            return { error: r };
+        if (r === null)
+            continue;
         if (t === '--verbose' || t === '-v')
             a.verbose = true;
         else if (t === '--no-newpairs')
@@ -248,15 +328,20 @@ 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] [--no-newpairs] [--db PATH] [--verbose]
-  dexterm record install   [--interval S] [--max-db-mb N] [--load] [--dry-run]
+  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]
   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 + retention keep running. --retention-mb N replaces that pause: the oldest history is evicted
+           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
            (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.
@@ -300,47 +385,77 @@ async function run(argv, io, deps) {
         return 2;
     }
     // SIGINT/SIGTERM-aware cancellable sleeper (launchd sends SIGTERM to stop the agent).
+    // Several loops may sleep at once (the collector + the tick lane), so every sleeper is woken on abort.
     const stop = (() => {
         let aborted = false;
-        let wake = () => { };
+        const wakes = new Set();
         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(); }; }); },
+            abort() { aborted = true; for (const w of [...wakes])
+                w(); },
+            sleep(ms) {
+                return new Promise((r) => {
+                    const done = () => { clearTimeout(t); wakes.delete(done); r(); };
+                    const t = setTimeout(done, ms);
+                    t.unref?.();
+                    wakes.add(done);
+                });
+            },
         };
     })();
     const log = (s) => io.stderr.write(s);
-    const engine = deps.engine ?? buildLiveEngine(io.env, { dbPath, noNewpairs: parsed.noNewpairs, verbose: parsed.verbose, onLog: log });
+    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 });
     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);
     }
+    // The sleeps are unref'd; without the PumpPortal socket (--no-newpairs) nothing else would keep the event loop
+    // 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'}\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'}\n`);
     let result;
+    let tickRes = { polls: 0, calls: 0, written: 0 };
     try {
-        result = await runCollectorLoop(engine, {
+        let mainDone = false;
+        const main = runCollectorLoop(engine, {
             intervalMs: parsed.intervalMs, ticks: parsed.ticks, maintainEveryMs: parsed.maintainMs, maxDbBytes: parsed.maxDbBytes,
+            capMode: parsed.retentionBytes !== null ? 'evict' : 'pause',
             now, sleep: (ms) => stop.sleep(ms), aborted: () => stop.aborted, onLog: log,
-        });
+        }).finally(() => { mainDone = true; if (parsed.ticks !== Infinity)
+            stop.abort(); });
+        const lane = parsed.focusTicks && engine.pollTicks
+            ? runTickLoop(engine, { everyMs: DEFAULT_TICKS.fastEveryMs, sleep: (ms) => stop.sleep(ms), aborted: () => stop.aborted || mainDone, onLog: log })
+            : Promise.resolve(tickRes);
+        [result, tickRes] = await Promise.all([main, lane]);
     }
     finally {
         if (own) {
             process.removeListener('SIGINT', onSig);
             process.removeListener('SIGTERM', onSig);
         }
+        if (hold)
+            clearInterval(hold);
         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`);
+        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` : ''}${result.evictions ? `, ${result.evictions} retention eviction(s)` : ''}${tickRes.polls ? `, ${tickRes.polls} focus-tick poll(s) (${tickRes.calls} call(s), ${tickRes.written} tick row(s))` : ''}\n`);
     return 0;
 }
 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 };
     for (let i = 0; i < argv.length; i++) {
         const t = argv[i];
+        const r = parseRetention(t, () => argv[++i], ret);
+        if (typeof r === 'string') {
+            io.stderr.write(`dexterm record: ${r}\n`);
+            return 2;
+        }
+        if (r === null)
+            continue;
         if (t === '--load')
             load = true;
         else if (t === '--dry-run')
@@ -369,7 +484,12 @@ function install(argv, io) {
     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), '..', '..', '..') });
+    const extraArgs = [
+        ...(ret.retentionBytes !== null ? ['--retention-mb', String(Math.round(ret.retentionBytes / 1e6))] : []),
+        ...(ret.retentionDays !== null ? ['--retention-days', String(ret.retentionDays)] : []),
+        ...(ret.focusTicks ? ['--focus-ticks'] : []),
+    ];
+    const plist = renderCollectorPlist({ label: COLLECTOR_LABEL, nodePath: process.execPath, binPath: bin, intervalMs, maxDbMb, extraArgs, logPath, workingDir: resolve(dirname(bin), '..', '..', '..') });
     if (dry) {
         io.stdout.write(plist);
         io.stderr.write(`\ndexterm record: dry run — would write ${path}\n`);
@@ -427,6 +547,7 @@ function status(argv, io) {
             `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`,
+            `focus ticks     ${s.ticks} rows · ${s.candles} 1m candles · ${s.tickCallsToday} calls today`,
             `span            ${when(s.oldestT)} → ${when(s.newestT)}`,
         ].join('\n') + '\n');
     }

package/dist/packages/cli/src/scan/ui.js

@@ -11,8 +11,14 @@ export const SCAN_TICK_MS = 2_000;
 export const SCAN_RECOMPUTE_MS = 10_000;
 /** The analyst UI actions a scan session may request: NONE (observe-only). */
 export const SCAN_ACTION_TYPES = Object.freeze([]);
+/** task-1473: append one line to the scan's session log (the analyst panel's brain view shows it). */
+export function scanLog(scan, t, kind, symbol, text) {
+    scan.log.push({ t, kind, symbol: cleanText(symbol, 12), text });
+    if (scan.log.length > 40)
+        scan.log.splice(0, scan.log.length - 40);
+}
 export function makeScanUi(cfg = {}) {
-    return { engine: new ScanEngine(cfg), sig: '', lastTickAt: 0, lastComputeAt: 0, session: null, blocked: [], returnTo: null };
+    return { engine: new ScanEngine(cfg), sig: '', lastTickAt: 0, lastComputeAt: 0, session: null, blocked: [], returnTo: null, log: [] };
 }
 export const MODE_LABEL = { off: 'OFF', scanning: 'SCANNING', locked: 'LOCKED', paused: 'PAUSED' };
 const SHORT = { vol: 'vol', flow: 'flow', fresh: 'fresh', breakout: 'brk', liq: 'liq', holders: 'hold' };