dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/recorder/src/recorder.js

@@ -7,7 +7,10 @@
 //             day, skipped while the bucket is paused after a 429. The only requests this package makes.
 //   label     code-only outcome labels per (t0 anchor, horizon) from the recorded numbers (labels.ts).
 //   prune     retention: raw JSON 7 d (focus rows only), one row per mint per minute after 24 h,
-//             columns 90 d, outcomes/verdicts forever.
+//             columns 90 d, outcomes/verdicts forever; autotrade ticks 14 d, sampled candles 90 d.
+//   ticks     (task-1504, opt-in) position-grade samples every 5–10 s for held / open / candidate / watch coins
+//             (ticks.ts), and a DB cap enforced by evicting the oldest history (retention.ts) instead of
+//             pausing observation.
 // Everything is synchronous SQLite on the app's own DB file (node:sqlite, WAL), batched in transactions,
 // so a refresh never awaits the recorder and a crash loses at most one batch.
 import { mkdirSync } from 'node:fs';
@@ -18,8 +21,10 @@ import { ALL_HORIZONS_MASK, HORIZONS_SEC, SCHEMA_SQL, SCHEMA_VERSION } from "./s
 import { COLUMN_NAMES, fromDsView, fromEnrichedRow, isMaterialChange } from "./snapshot.js";
 import { LABELER_VERSION, labelAtHorizon } from "./labels.js";
 import { dueBounds, selectDue } from "./sweep.js";
+import { TickLane } from "./ticks.js";
+import { DEFAULT_AGE, enforceCap, pruneTicksByAge } from "./retention.js";
 export const DEFAULT_SWEEP = { everyMs: 60_000, maxCallsPerSweep: 6, maxCallsPerDay: 1500, batch: 30 };
-export const DEFAULT_RETENTION = { rawDays: 7, columnsDays: 90, downsampleAfterHours: 24, everyMs: 3_600_000 };
+export const DEFAULT_RETENTION = { rawDays: 7, columnsDays: 90, downsampleAfterHours: 24, everyMs: 3_600_000, ...DEFAULT_AGE };
 /** Unchanged rows are re-written this often at most; the horizons are ≥ 1 h, so 30 min keeps every window observed. */
 export const DEFAULT_HEARTBEAT_MS = 1_800_000;
 export const DEFAULT_T0_EVERY_MS = 3_600_000;
@@ -43,6 +48,9 @@ export class Recorder {
     membersEveryMs;
     sweepPolicy;
     retention;
+    /** task-1504: the tick lane (null when not configured) and the cap policy (null = no cap). */
+    tickLane;
+    cap;
     onLog;
     /**
      * Per mint: the last WRITTEN row (columns + hash + time) and the newest observation time this process
@@ -92,6 +100,8 @@ export class Recorder {
             lastLive: this.db.prepare(`SELECT t, hash, sources, ${cols} FROM token_snapshots WHERE mint = ? AND kind = 'live' ORDER BY t DESC LIMIT 1`),
             insertCreator: this.db.prepare('INSERT OR IGNORE INTO creators (mint, creator, source, first_t, created_at) VALUES (?, ?, ?, ?, ?)'),
         };
+        this.tickLane = opts.ticks ? new TickLane(this.db, { focus: opts.ticks.focus, policy: opts.ticks.policy, clock: this.clock, onLog: this.onLog }) : null;
+        this.cap = opts.cap && opts.cap.maxBytes ? opts.cap : null;
     }
     /** Attach as the data layer's store listener (and detach any previous one). */
     attach(store) {
@@ -298,8 +308,38 @@ export class Recorder {
         catch (err) {
             this.log(`prune failed: ${msg(err)}`);
         }
+        try {
+            this.enforceCap(now);
+        }
+        catch (err) {
+            this.log(`cap failed: ${msg(err)}`);
+        }
         return out;
     }
+    /**
+     * task-1504: one tick-lane poll (ticks.ts). The host calls it every `fastEveryMs` (5 s); 'disabled' when the
+     * recorder is off or no tick lane was configured. The only other requests this package makes besides sweeps.
+     */
+    async pollTicks(deps, now = this.clock.now()) {
+        if (!this.enabled || this.closed || !this.tickLane)
+            return { coins: 0, calls: 0, answered: 0, written: 0, overCap: 0, skipped: 'disabled' };
+        return this.tickLane.poll(deps, now);
+    }
+    /**
+     * task-1504: keep the DB under the configured cap by evicting the oldest history (retention.ts). A no-op without
+     * a cap or below its high-water mark. Observation never pauses; the collector calls this before each pass.
+     */
+    enforceCap(now = this.clock.now()) {
+        if (!this.cap || this.closed)
+            return null;
+        const r = enforceCap(this.db, this.cap, now);
+        if (r.evicted) {
+            this.log(`cap: used ${(r.usedBefore / 1e6).toFixed(1)} → ${(r.usedAfter / 1e6).toFixed(1)} MB (${r.reclaimed} reclaimed, ${r.slices} slice(s) of history), history now from ${r.cutoff === null ? '—' : new Date(r.cutoff).toISOString()}${r.over ? ' (still over: only the newest hour is left)' : ''}`);
+            // Forget cached last rows: an evicted mint is re-seeded from the DB (or written fresh) next time.
+            this.seen.clear();
+        }
+        return r;
+    }
     /** Mints whose horizon window is open and unobserved (sweep.ts), soonest-closing first. */
     due(now = this.clock.now(), max = this.sweepPolicy.maxCallsPerSweep * this.sweepPolicy.batch) {
         const b = dueBounds(now);
@@ -455,7 +495,7 @@ export class Recorder {
      * watermark in recorder_meta means each pass only looks at the hours that newly crossed the line.
      */
     prune(now = this.clock.now()) {
-        const res = { rawCleared: 0, downsampled: 0, expired: 0, membersExpired: 0 };
+        const res = { rawCleared: 0, downsampled: 0, expired: 0, membersExpired: 0, ticksExpired: 0, candlesExpired: 0 };
         if (this.closed)
             return res;
         const day = 86_400_000;
@@ -480,14 +520,17 @@ export class Recorder {
             res.membersExpired = Number(this.db.prepare('DELETE FROM feed_members WHERE t < ?').run(colsBefore).changes);
             this.db.prepare('DELETE FROM mints WHERE last_any_t < ?').run(colsBefore);
             this.db.prepare('DELETE FROM sweeps WHERE started_at < ?').run(colsBefore);
+            const tk = pruneTicksByAge(this.db, { ticksDays: this.retention.ticksDays, candlesDays: this.retention.candlesDays }, now);
+            res.ticksExpired = tk.ticks;
+            res.candlesExpired = tk.candles;
             this.db.exec('COMMIT');
         }
         catch (err) {
             this.db.exec('ROLLBACK');
             throw err;
         }
-        if (res.rawCleared || res.downsampled || res.expired)
-            this.log(`prune: raw ${res.rawCleared}, downsampled ${res.downsampled}, expired ${res.expired} rows`);
+        if (res.rawCleared || res.downsampled || res.expired || res.ticksExpired)
+            this.log(`prune: raw ${res.rawCleared}, downsampled ${res.downsampled}, expired ${res.expired} rows, ${res.ticksExpired} ticks`);
         return res;
     }
     // ---------------------------------------------------------------- read side
@@ -512,7 +555,7 @@ export class Recorder {
             const d = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending')");
             if (d.b !== null && Number(s.n) > 0)
                 bytesPerSnapshot = Number(d.b) / Number(s.n);
-            const all = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('recorder_meta', 'feed_members', 'feed_members_mint_t', 'token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending', 'mints', 'mints_last_live', 'sweeps', 'chain_events', 'chain_events_mint_t', 'outcomes', 'outcomes_label', 'verdicts', 'verdicts_mint_t')");
+            const all = one("SELECT SUM(pgsize) AS b FROM dbstat WHERE name IN ('recorder_meta', 'feed_members', 'feed_members_mint_t', 'token_snapshots', 'token_snapshots_mint_t', 'token_snapshots_t', 'token_snapshots_t0_pending', 'mints', 'mints_last_live', 'sweeps', 'chain_events', 'chain_events_mint_t', 'outcomes', 'outcomes_label', 'verdicts', 'verdicts_mint_t', 'creators', 'creators_creator', 'autotrade_ticks', 'autotrade_ticks_t', 'autotrade_candles_1m', 'autotrade_candles_1m_t')");
             recorderBytes = all.b === null ? null : Number(all.b);
         }
         catch {
@@ -533,6 +576,9 @@ export class Recorder {
             outcomesByLabel: byLabel,
             sweeps: Number(one('SELECT COUNT(*) AS n FROM sweeps').n),
             sweepCallsToday: this.sweepCallsToday(now),
+            ticks: Number(one('SELECT COUNT(*) AS n FROM autotrade_ticks').n),
+            candles: Number(one('SELECT COUNT(*) AS n FROM autotrade_candles_1m').n),
+            tickCallsToday: this.tickLane ? this.tickLane.callsToday(now) : tickCallsOn(this.db, now),
             dbBytes, recorderBytes, bytesPerSnapshot,
             oldestT: s.oldest === null ? null : Number(s.oldest),
             newestT: s.newest === null ? null : Number(s.newest),
@@ -571,6 +617,17 @@ export class Recorder {
         this.onLog?.(`recorder: ${line}\n`);
     }
 }
+/** Tick calls the lane recorded for `now`'s UTC day (recorder_meta), for a reader with no lane of its own. */
+function tickCallsOn(db, now) {
+    const r = db.prepare("SELECT value FROM recorder_meta WHERE key = 'tick_calls'").get();
+    try {
+        const v = r ? JSON.parse(r.value) : null;
+        return v && v.day === new Date(now).toISOString().slice(0, 10) ? Number(v.calls) || 0 : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 function msg(err) {
     return err instanceof Error ? err.message : String(err);
 }

package/dist/packages/recorder/src/retention.js

@@ -0,0 +1,100 @@
+// dexterm history recorder: retention under a DB cap (task-1504, AUTOTRADE-SPEC §3 + §10 Q4).
+//
+// Before this, the collector's only answer to a full disk was to PAUSE observation above `--max-db-mb`, while the
+// outcome sweeps kept writing: the cap stopped exactly the rows autotrade needs and the DB still grew past it.
+// This module keeps the DB under the cap by EVICTING the oldest recorder history instead, so observation never
+// pauses:
+//
+//   age       ticks after `ticksDays` (14), sampled candles after `candlesDays` (90). Snapshot / feed-member /
+//             sweep rows keep the recorder's existing `columnsDays` rule (recorder.ts prune; Q4's "prune raw rows
+//             older than 14 days" is `columnsDays: 14`).
+//   reclaim   (optional) once the cap is reached, the host's cheap space goes first: the collector passes the data
+//             layer's own expired-cache prune (`Cache.prune()`, entries a day past their TTL), measured on
+//             2026-10-21 at ~470 MB of a 1,173 MB file that only held ~430 MB of recorder history.
+//   cap       once the DB's USED bytes (pages minus the freelist) reach `highWater` × `maxBytes`, delete the
+//             oldest slice of history (`sliceMs`, all recorder tables: ticks, candles, snapshots incl. sweep rows,
+//             feed members; the small sweep ledger keeps its age rule) and repeat until used ≤ `lowWater` × `maxBytes`. Rows newer than
+//             `keepMs` are never evicted. Outcomes, verdicts and creators are tiny and stay forever.
+//
+// SQLite does not shrink the file on DELETE: freed pages go to the freelist and new rows reuse them. So the file
+// stops growing at about the high-water mark; a file that is ALREADY above the cap stays that size (only
+// `VACUUM`, with the collector stopped, gives the space back) but no longer grows.
+export const DEFAULT_CAP = { maxBytes: null, highWater: 0.95, lowWater: 0.85, sliceMs: 3_600_000, keepMs: 3_600_000, maxSlices: 500 };
+export const DEFAULT_AGE = { ticksDays: 14, candlesDays: 90 };
+/** The Q4 default cap when retention-by-cap is switched on (3 GB). */
+export const DEFAULT_CAP_BYTES = 3_000_000_000;
+/** Tables the cap may evict from, each with its time column. */
+const EVICTABLE = [
+    { table: 'autotrade_ticks', col: 't' },
+    { table: 'autotrade_candles_1m', col: 't' },
+    { table: 'token_snapshots', col: 't' },
+    { table: 'feed_members', col: 't' },
+];
+export function dbSize(db) {
+    const one = (sql) => Number(Object.values(db.prepare(sql).get())[0]);
+    const ps = one('PRAGMA page_size');
+    const pc = one('PRAGMA page_count');
+    const fl = one('PRAGMA freelist_count');
+    return { fileBytes: pc * ps, usedBytes: (pc - fl) * ps };
+}
+/**
+ * Enforce the cap: a no-op below the high-water mark; above it, delete the oldest `sliceMs` of history across every
+ * evictable table, one transaction per slice, until used ≤ the low-water mark. Never deletes rows newer than
+ * `now - keepMs`. Outcome / verdict / creator rows are never touched.
+ */
+export function enforceCap(db, policy, now) {
+    const p = { ...DEFAULT_CAP, ...policy };
+    const size0 = dbSize(db);
+    const res = { evicted: false, usedBefore: size0.usedBytes, usedAfter: size0.usedBytes, fileBytes: size0.fileBytes, slices: 0, reclaimed: 0, deleted: {}, cutoff: null, over: false };
+    if (p.maxBytes === null || p.maxBytes <= 0 || size0.usedBytes < p.highWater * p.maxBytes)
+        return res;
+    res.evicted = true;
+    const target = p.lowWater * p.maxBytes;
+    const floor = now - p.keepMs;
+    const tables = EVICTABLE.filter((e) => !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(e.table));
+    const oldestQ = tables.map((e) => ({ ...e, q: db.prepare(`SELECT MIN(${e.col}) AS m FROM ${e.table}`), del: db.prepare(`DELETE FROM ${e.table} WHERE ${e.col} < ?`) }));
+    const delMints = db.prepare('DELETE FROM mints WHERE last_any_t < ?');
+    let used = size0.usedBytes;
+    if (p.reclaim) {
+        res.reclaimed = p.reclaim();
+        used = dbSize(db).usedBytes;
+    }
+    while (used > target && res.slices < p.maxSlices) {
+        let oldest = Infinity;
+        for (const e of oldestQ) {
+            const m = e.q.get().m;
+            if (m !== null && Number(m) < oldest)
+                oldest = Number(m);
+        }
+        if (!Number.isFinite(oldest) || oldest >= floor)
+            break;
+        const cutoff = Math.min(oldest + p.sliceMs, floor);
+        db.exec('BEGIN');
+        try {
+            for (const e of oldestQ)
+                res.deleted[e.table] = (res.deleted[e.table] ?? 0) + Number(e.del.run(cutoff).changes);
+            res.deleted.mints = (res.deleted.mints ?? 0) + Number(delMints.run(cutoff).changes);
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            db.exec('ROLLBACK');
+            throw err;
+        }
+        res.slices++;
+        res.cutoff = cutoff;
+        used = dbSize(db).usedBytes;
+    }
+    const size1 = dbSize(db);
+    res.usedAfter = size1.usedBytes;
+    res.fileBytes = size1.fileBytes;
+    res.over = size1.usedBytes >= p.highWater * p.maxBytes;
+    return res;
+}
+/** Age rules for the autotrade tables (the recorder's prune() calls this next to its own snapshot rules). */
+export function pruneTicksByAge(db, policy, now) {
+    const p = { ...DEFAULT_AGE, ...policy };
+    const day = 86_400_000;
+    const ticks = Number(db.prepare('DELETE FROM autotrade_ticks WHERE t < ?').run(now - p.ticksDays * day).changes);
+    const candles = Number(db.prepare('DELETE FROM autotrade_candles_1m WHERE t < ?').run(now - p.candlesDays * day).changes);
+    return { ticks, candles };
+}

package/dist/packages/recorder/src/schema.js

@@ -12,7 +12,11 @@
 //   - `mints` is a per-mint summary the sweep scheduler reads instead of scanning snapshots.
 //   - feed_members is keyed on (t, feed, rank): the refresh tick is the run.
 //   - chain_events and verdicts are created here (one schema owner) but written by R-02 / L-01.
-export const SCHEMA_VERSION = 1;
+//
+// v2 (task-1504, AUTOTRADE-SPEC §3): `autotrade_ticks` (position-grade samples every 5–10 s for the few coins
+// that are watched, open, a candidate or held; written by the tick lane in ticks.ts) and `autotrade_candles_1m`
+// (1-minute OHLC built from those samples). Both are additive: a v1 file gains the two tables on open.
+export const SCHEMA_VERSION = 2;
 export const HORIZONS_SEC = [3600, 7200, 21600, 86400, 259200];
 /** Every horizon labelled: the bitmask value of `horizons_done` for a finished t0 row. */
 export const ALL_HORIZONS_MASK = (1 << HORIZONS_SEC.length) - 1;
@@ -143,4 +147,33 @@ CREATE TABLE IF NOT EXISTS creators (
   created_at  INTEGER                    -- the coin's creation time when the source gave one
 ) WITHOUT ROWID;
 CREATE INDEX IF NOT EXISTS creators_creator ON creators (creator, first_t);
+
+-- task-1504 (AUTOTRADE-SPEC §3): position-grade ticks. One row per (mint, poll) for focus coins, written
+-- every sample (no change detection), from DexScreener tokens/v1 batches. price_usd NULL = the poll got no
+-- pair back for the mint (pool gone or not indexed): a held coin's rug shows up here as NULL rows.
+CREATE TABLE IF NOT EXISTS autotrade_ticks (
+  mint            TEXT NOT NULL,
+  t               INTEGER NOT NULL,          -- unix ms the answer was fetched
+  role            TEXT NOT NULL,             -- why it was polled: 'held' | 'open' | 'candidate' | 'watch'
+  price_usd REAL, liquidity_usd REAL, mcap REAL, fdv REAL,
+  vol_m5 REAL, vol_h1 REAL,
+  buys_m5 INTEGER, sells_m5 INTEGER,
+  chg_m5 REAL, chg_h1 REAL,
+  pair_address    TEXT,
+  pair_created_at INTEGER,
+  PRIMARY KEY (mint, t)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS autotrade_ticks_t ON autotrade_ticks (t);
+
+-- 1-minute candles for the same coins, built from the ticks (sampled: high/low are of the 5–10 s samples,
+-- not of every trade). t = the minute's start; n = samples in the minute.
+CREATE TABLE IF NOT EXISTS autotrade_candles_1m (
+  mint  TEXT NOT NULL,
+  t     INTEGER NOT NULL,
+  o REAL NOT NULL, h REAL NOT NULL, l REAL NOT NULL, c REAL NOT NULL,
+  liq_c REAL, mcap_c REAL,
+  n     INTEGER NOT NULL,
+  PRIMARY KEY (mint, t)
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS autotrade_candles_1m_t ON autotrade_candles_1m (t);
 `;

package/dist/packages/recorder/src/ticks.js

@@ -0,0 +1,237 @@
+// dexterm history recorder: position-grade ticks for autotrade (task-1504, AUTOTRADE-SPEC §3 "Data today vs what
+// must be recorded"). The change-driven `token_snapshots` rows land every ~2 min at best and only on a ≥ 5 % move,
+// which hides the intrabar path a stop or a take-profit lives on. This lane samples the FEW coins that matter to a
+// position every 5–10 s and writes every sample:
+//
+//   focus      held > open > candidate > watch, one role per mint (the highest wins), at most `maxCoins`
+//              (default 60 = two calls). Sources are injected: the collector reads the watchlist and the paper
+//              wallet from the DB and the autotrade focus file (`focus.json`, written by the runner / the app).
+//   cadence    held + open coins every `fastEveryMs` (5 s), candidate + watch every `slowEveryMs` (10 s). A call
+//              that goes out anyway is topped up with coins not yet due (oldest sample first): a batch of 30
+//              costs the same one request.
+//   budget     DexScreener `tokens/v1` batches of 30 only (never a per-coin keyless Jupiter call), through the
+//              data layer's limiter and health gate; 'normal' priority when a held/open coin is in the call,
+//              'low' otherwise; skipped while the bucket is paused after a 429; a per-UTC-day call ceiling.
+//   candles    every sample with a price folds into `autotrade_candles_1m` (sampled OHLC: high/low are of the
+//              samples, not of every trade).
+//
+// No change detection and no raw JSON: a tick row is ~100 bytes. Retention (retention.ts) keeps ticks 14 days.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { withPriority, systemClock } from '../../data/src/index.js';
+/** Priority order: earlier roles are sampled first and faster. */
+export const FOCUS_ROLES = ['held', 'open', 'candidate', 'watch'];
+export const DEFAULT_TICKS = { fastEveryMs: 5_000, slowEveryMs: 10_000, maxCoins: 60, batch: 30, maxCallsPerDay: 36_000 };
+const BASE58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+const MIN = 60_000;
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const isFast = (r) => r === 'held' || r === 'open';
+/** One role per mint (the highest-priority role wins), invalid mints dropped, in priority order. */
+export function mergeFocus(entries) {
+    const best = new Map();
+    for (const e of entries) {
+        if (!e || typeof e.mint !== 'string' || !BASE58.test(e.mint) || !FOCUS_ROLES.includes(e.role))
+            continue;
+        const cur = best.get(e.mint);
+        if (!cur || FOCUS_ROLES.indexOf(e.role) < FOCUS_ROLES.indexOf(cur))
+            best.set(e.mint, e.role);
+    }
+    return [...best].map(([mint, role]) => ({ mint, role })).sort((a, b) => FOCUS_ROLES.indexOf(a.role) - FOCUS_ROLES.indexOf(b.role));
+}
+/** The sampler. Owns no connection: it writes through the recorder's DB handle (same file, same thread). */
+export class TickLane {
+    policy;
+    db;
+    focus;
+    clock;
+    onLog;
+    /** mint -> time of its last sample this process took. */
+    last = new Map();
+    polling = false;
+    day = '';
+    dayCalls = 0;
+    counters = { polls: 0, calls: 0, written: 0 };
+    stmts;
+    constructor(db, opts) {
+        this.db = db;
+        this.focus = opts.focus;
+        this.policy = { ...DEFAULT_TICKS, ...opts.policy };
+        this.clock = opts.clock ?? systemClock;
+        this.onLog = opts.onLog;
+        this.stmts = {
+            tick: db.prepare(`INSERT OR IGNORE INTO autotrade_ticks (mint, t, role, price_usd, liquidity_usd, mcap, fdv, vol_m5, vol_h1, buys_m5, sells_m5, chg_m5, chg_h1, pair_address, pair_created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+            candle: db.prepare(`INSERT INTO autotrade_candles_1m (mint, t, o, h, l, c, liq_c, mcap_c, n) VALUES (?, ?, ?, ?, ?, ?, ?, ?, 1)
+        ON CONFLICT(mint, t) DO UPDATE SET h = MAX(h, excluded.h), l = MIN(l, excluded.l), c = excluded.c, liq_c = excluded.liq_c, mcap_c = excluded.mcap_c, n = n + 1`),
+            meta: db.prepare("INSERT OR REPLACE INTO recorder_meta (key, value) VALUES ('tick_calls', ?)"),
+        };
+    }
+    /** Tick calls issued in the current UTC day (persisted in recorder_meta, so a restart keeps the count). */
+    callsToday(now = this.clock.now()) {
+        const day = new Date(now).toISOString().slice(0, 10);
+        if (day !== this.day) {
+            this.day = day;
+            this.dayCalls = 0;
+            const r = this.db.prepare("SELECT value FROM recorder_meta WHERE key = 'tick_calls'").get();
+            try {
+                const v = r ? JSON.parse(r.value) : null;
+                if (v && v.day === day)
+                    this.dayCalls = Number(v.calls) || 0;
+            }
+            catch { /* reset */ }
+        }
+        return this.dayCalls;
+    }
+    /**
+     * Which coins this poll samples: every due coin in priority order up to `maxCoins`, then the last batch topped
+     * up with coins not yet due (oldest sample first). `overCap` counts focus coins past `maxCoins`.
+     */
+    plan(now = this.clock.now(), maxCalls = Math.ceil(this.policy.maxCoins / this.policy.batch)) {
+        const focus = mergeFocus(this.focus());
+        const cap = Math.min(this.policy.maxCoins, maxCalls * this.policy.batch);
+        const inCap = focus.slice(0, cap);
+        const overCap = focus.length - inCap.length;
+        const isDue = (e) => now - (this.last.get(e.mint) ?? -Infinity) >= (isFast(e.role) ? this.policy.fastEveryMs : this.policy.slowEveryMs);
+        const due = inCap.filter(isDue);
+        if (!due.length)
+            return { coins: [], due: 0, overCap, focus: focus.length };
+        const room = Math.ceil(due.length / this.policy.batch) * this.policy.batch - due.length;
+        const ride = inCap.filter((e) => !isDue(e)).sort((a, b) => (this.last.get(a.mint) ?? 0) - (this.last.get(b.mint) ?? 0)).slice(0, room);
+        return { coins: [...due, ...ride], due: due.length, overCap, focus: focus.length };
+    }
+    /** One poll. The host calls this every `fastEveryMs` (the collector's tick loop). Never throws. */
+    async poll(deps, now = this.clock.now()) {
+        const none = (skipped, overCap = 0) => ({ coins: 0, calls: 0, answered: 0, written: 0, overCap, skipped });
+        if (this.polling)
+            return none('in-flight');
+        let budget = this.policy.maxCallsPerDay - this.callsToday(now);
+        if (budget <= 0)
+            return none('day-cap');
+        let planned;
+        try {
+            planned = this.plan(now, Math.min(budget, Math.ceil(this.policy.maxCoins / this.policy.batch)));
+        }
+        catch (err) {
+            this.log(`focus failed: ${msg(err)}`);
+            return none('no-focus');
+        }
+        if (!planned.coins.length)
+            return none(planned.focus ? 'not-due' : 'no-focus', planned.overCap);
+        if (deps.limiter.bucket('dexscreener').stats().pausedUntil > now)
+            return none('paused', planned.overCap);
+        this.polling = true;
+        this.counters.polls++;
+        const res = { coins: planned.coins.length, calls: 0, answered: 0, written: 0, overCap: planned.overCap, skipped: null };
+        try {
+            for (let i = 0; i < planned.coins.length && budget > 0; i += this.policy.batch) {
+                const chunk = planned.coins.slice(i, i + this.policy.batch);
+                const priority = chunk.some((e) => isFast(e.role)) ? 'normal' : 'low';
+                res.calls++;
+                budget--;
+                this.dayCalls++;
+                this.stmts.meta.run(JSON.stringify({ day: this.day, calls: this.dayCalls }));
+                const views = await withPriority(priority, () => deps.dexscreener.tokens(chunk.map((e) => e.mint)));
+                const t = this.clock.now();
+                const w = this.write(chunk, views, t);
+                res.answered += w.answered;
+                res.written += w.written;
+            }
+        }
+        catch (err) {
+            res.error = msg(err);
+            this.log(`tick poll failed: ${res.error}`);
+        }
+        finally {
+            this.polling = false;
+            this.counters.calls += res.calls;
+            this.counters.written += res.written;
+        }
+        return res;
+    }
+    /** Write one answered batch (one transaction): a tick per coin (NULL price when no pair came back) + candles. */
+    write(chunk, views, t) {
+        let answered = 0, written = 0;
+        this.db.exec('BEGIN');
+        try {
+            for (const e of chunk) {
+                this.last.set(e.mint, t);
+                const p = views.get(e.mint)?.pair;
+                if (p)
+                    answered++;
+                const price = p ? fin(p.priceUsd) : null;
+                const liq = p ? fin(p.liquidityUsd) : null;
+                const mcap = p ? fin(p.mcap) : null;
+                const r = this.stmts.tick.run(e.mint, t, e.role, price, liq, mcap, p ? fin(p.fdv) : null, p ? fin(p.volume.m5) : null, p ? fin(p.volume.h1) : null, p ? fin(p.txns.m5?.buys) : null, p ? fin(p.txns.m5?.sells) : null, p ? fin(p.priceChange.m5) : null, p ? fin(p.priceChange.h1) : null, p?.pairAddress || null, p ? fin(p.createdAt) : null);
+                if (Number(r.changes) > 0)
+                    written++;
+                if (price !== null && price > 0 && Number(r.changes) > 0)
+                    this.stmts.candle.run(e.mint, Math.floor(t / MIN) * MIN, price, price, price, price, liq, mcap);
+            }
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+        // Forget coins that left the focus long ago (bounded memory over a long run).
+        if (this.last.size > 4 * this.policy.maxCoins)
+            for (const [m, lt] of this.last)
+                if (t - lt > 3_600_000)
+                    this.last.delete(m);
+        return { answered, written };
+    }
+    log(line) {
+        this.onLog?.(`recorder: ${line}\n`);
+    }
+}
+// ---------------------------------------------------------------- focus sources
+/**
+ * Focus coins the app's own DB already knows: every watchlist mint ('watch') and every paper position with a
+ * token balance ('held'). Tables that do not exist yet (a fresh DB) contribute nothing.
+ */
+export function dbFocus(db) {
+    const has = (name) => !!db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(name);
+    const out = [];
+    if (has('watchlist'))
+        for (const r of db.prepare('SELECT mint FROM watchlist').all())
+            out.push({ mint: r.mint, role: 'watch' });
+    if (has('paper_positions'))
+        for (const r of db.prepare("SELECT mint FROM paper_positions WHERE tokens_raw NOT IN ('0', '')").all())
+            out.push({ mint: r.mint, role: 'held' });
+    return out;
+}
+/** The rendezvous file other processes (the autotrade runner, the app) publish focus coins in. */
+export const FOCUS_FILE_SCHEMA = 'dexterm-autotrade-focus/1';
+/** A focus file not rewritten for this long is ignored (a dead writer must not pin coins to the fast lane). */
+export const FOCUS_FILE_STALE_MS = 30 * MIN;
+/** `<dexterm home>/autotrade/focus.json`. */
+export const focusFilePath = (home) => join(home, 'autotrade', 'focus.json');
+/** Read a focus file: missing, garbled, stale or expired entries contribute nothing. Never throws. */
+export function readFocusFile(path, now) {
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return [];
+    }
+    if (!doc || doc.schema !== FOCUS_FILE_SCHEMA || !Array.isArray(doc.entries) || !(now - Number(doc.updatedAt) <= FOCUS_FILE_STALE_MS))
+        return [];
+    return mergeFocus(doc.entries.filter((e) => e && (e.until === undefined || Number(e.until) >= now)).map((e) => ({ mint: e.mint, role: e.role })));
+}
+/** Write a focus file atomically (tmp + rename, mode 0600). */
+export function writeFocusFile(path, entries, now) {
+    mkdirSync(dirname(path), { recursive: true });
+    const doc = { schema: FOCUS_FILE_SCHEMA, updatedAt: now, entries: [...entries] };
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+}
+/** Sampled 1m candles for one mint, oldest first (read-only use). */
+export function candlesFromDb(db, mint, from = 0, to = Number.MAX_SAFE_INTEGER) {
+    return db.prepare('SELECT t, o, h, l, c, liq_c, mcap_c, n FROM autotrade_candles_1m WHERE mint = ? AND t >= ? AND t <= ? ORDER BY t').all(mint, from, to)
+        .map((r) => ({ t: Number(r.t), o: Number(r.o), h: Number(r.h), l: Number(r.l), c: Number(r.c), liq: r.liq_c ?? null, mcap: r.mcap_c ?? null, n: Number(r.n) }));
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/packages/tui/src/canvas.js

@@ -66,6 +66,11 @@ export class Canvas {
      */
     images;
     imageMode;
+    /**
+     * task-1466: where each keyed list row was drawn (a table with `rowKey`, e.g. a screener row by mint), so an
+     * overlay drawn later (the agent HUD's row glow / cursor) can find the row on screen. Not emitted anywhere.
+     */
+    rowMarks;
     constructor(w, h, theme) {
         this.w = w;
         this.h = h;
@@ -82,6 +87,7 @@ export class Canvas {
         this.shields = [];
         this.images = [];
         this.imageMode = 'cells';
+        this.rowMarks = [];
     }
     idx(x, y) { return y * this.w + x; }
     /** Copy every buffer of `src` (same size) into this canvas. */
@@ -97,6 +103,7 @@ export class Canvas {
         this.shields = src.shields.slice();
         this.images = src.images.slice();
         this.imageMode = src.imageMode;
+        this.rowMarks = src.rowMarks.slice();
     }
     put(x, y, ch, st = {}) {
         if (x < 0 || y < 0 || x >= this.w || y >= this.h)

package/dist/packages/tui/src/fmt.js

@@ -119,6 +119,59 @@ export function fmtMcap(n) {
         return bare;
     return bare.startsWith('-') ? `-$${bare.slice(1)}` : `$${bare}`;
 }
+/**
+ * task-1472: THE chart number formatter (Y axis, crosshair/legend, last-value tag, volume): compact with a LOWERCASE k
+ * for thousands, then M, B, T. One decimal while the value is below 10 of its unit, none after, trailing `.0` dropped:
+ * 4930 → 4.9k, 42100 → 42k, 487000 → 487k, 1.23e6 → 1.2M, 4.8e7 → 48M, 1.3e9 → 1.3B, 999 → 999. The unit is promoted
+ * AFTER rounding, so 999 900 reads 1M (never 1000k). Below 1 it is the subscript price form (0.0000123 → 0.0₄123):
+ * never scientific notation, never a long run of zeros. `extra` (0..3) adds decimals when an axis needs them to keep
+ * two neighbouring ticks apart (see compactDecimalsFor). No currency symbol; fmtCompactUsd adds the `$`.
+ */
+export function fmtCompact(n, extra = 0) {
+    if (n == null || !Number.isFinite(n))
+        return '—';
+    if (n === 0)
+        return '0';
+    const sign = n < 0 ? '-' : '';
+    const a = Math.abs(n);
+    if (a < 1)
+        return sign + trimZeros(fmtPriceBare(a));
+    const units = ['', 'k', 'M', 'B', 'T'];
+    const x = Math.max(0, Math.min(3, Math.floor(extra)));
+    const round = (q) => Number(q.toFixed((q < 10 ? 1 : 0) + x));
+    let u = 0, v = a;
+    while (u < units.length - 1 && v >= 1000) {
+        v /= 1000;
+        u++;
+    }
+    let r = round(v);
+    if (r >= 1000 && u < units.length - 1) {
+        u++;
+        r = round(r / 1000);
+    }
+    return `${sign}${trimZeros(r.toFixed((r < 10 ? 1 : 0) + x))}${units[u]}`;
+}
+/** USD form of fmtCompact: `$4.9k`, `$48M`, `-$1.2k`. */
+export function fmtCompactUsd(n, extra = 0) {
+    const bare = fmtCompact(n, extra);
+    if (bare === '—')
+        return bare;
+    return bare.startsWith('-') ? `-$${bare.slice(1)}` : `$${bare}`;
+}
+/**
+ * task-1472: the extra decimals (0..3) fmtCompact needs so that axis ticks `step` apart around `around` never print
+ * the same label (a 48.1M–48.6M range would otherwise read 48M on every tick). 0 for a normal memecoin range.
+ */
+export function compactDecimalsFor(around, step) {
+    if (!Number.isFinite(around) || !Number.isFinite(step) || step <= 0 || Math.abs(around) < 1)
+        return 0;
+    for (let x = 0; x < 3; x++) {
+        const a = fmtCompact(around, x);
+        if (a !== fmtCompact(around + step, x) && a !== fmtCompact(around - step, x))
+            return x;
+    }
+    return 3;
+}
 export function fmtPct(n, { sign = true, digits = 1 } = {}) {
     if (n == null || Number.isNaN(n))
         return '—';

package/dist/packages/tui/src/index.js

@@ -7,6 +7,7 @@ export * from "./flush.js";
 export * from "./layout.js";
 export * from "./keymap.js";
 export * from "./widgets.js";
+export * from "./markers.js";
 export * from "./fx.js";
 export * from "./fx-trade.js";
 export * from "./sound.js";