dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/packs/src/token-dossier.js

@@ -0,0 +1,174 @@
+// token-dossier pack, ASSEMBLE stage (AI-SUITE-DESIGN §2, ported from research/task-1287/packs/token-dossier).
+//
+// Pure, deterministic, zero tokens: it reads the `get_dossier` object the MCP server already assembles
+// (packages/mcp/src/dossier.ts `buildDossier`) and computes the numbers, the named rule flags, the
+// deterministic verdict, the data ages and a cache key. This is what the UI chips, the batch scorer, the
+// rug model and the backtest read; the optional REASON stage (reason.ts) runs one tool-less model call
+// over this object and may only TIGHTEN the verdict.
+//
+// Thresholds are the task-1293 skill rules (owner: maintainers); the model stage may add flags, never remove.
+import { createHash } from 'node:crypto';
+import { scanForInjection } from "./firewall.js";
+export const TOKEN_DOSSIER_PACK = 'token-dossier';
+export const TOKEN_DOSSIER_VERSION = '0.1.0';
+const isObj = (r) => !!r && typeof r === 'object';
+const hasError = (r) => isObj(r) && 'error' in r && !!r.error;
+const present = (r) => isObj(r) && !hasError(r);
+const num = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const boolOrNull = (x) => (x === true || x === false ? x : null);
+const pct = (a, b) => (a === null || b === null || !b ? null : Math.round((a / b) * 1000) / 10);
+const path = (r, ...keys) => keys.reduce((acc, k) => (isObj(acc) ? acc[k] : undefined), r);
+/**
+ * Assemble a token-dossier from a `get_dossier` object (buildDossier output). `now` defaults to the
+ * dossier's `now`. Pass a `rugScorer` to fill `rug_probability` (the deterministic rug model).
+ */
+export function assembleTokenDossier(dossier, opts = {}) {
+    const now = opts.now ?? num(dossier.now) ?? Date.now();
+    const market = dossier.market; // get_token: { token, pair, stats, audit, now }
+    const concentration = dossier.concentration;
+    const security = dossier.security;
+    const candles = dossier.candles;
+    const tape = dossier.tape;
+    const creator = dossier.creator;
+    const mint = String(dossier.mint ?? path(market, 'token', 'mint') ?? '');
+    const tokenObj = path(market, 'token');
+    const pair = path(market, 'pair');
+    const stats = path(market, 'stats');
+    const audit = path(market, 'audit');
+    if (!present(market) || !present(tokenObj)) {
+        return errDossier(mint, 'market section unavailable', dossier, now);
+    }
+    const createdAt = num(path(tokenObj, 'createdAt')) ?? num(path(pair, 'createdAt'));
+    const ageSec = createdAt ? Math.max(0, Math.round((now - createdAt) / 1000)) : num(path(tokenObj, 'ageSec'));
+    const h1 = path(stats, 'perWindow', 'h1');
+    const buysH1 = num(path(pair, 'txns', 'h1', 'buys'));
+    const sellsH1 = num(path(pair, 'txns', 'h1', 'sells'));
+    const volH1 = num(path(pair, 'volume', 'h1'));
+    const liq = num(path(pair, 'liquidityUsd'));
+    const mcap = num(path(pair, 'mcapResolved')) ?? num(path(pair, 'mcap'));
+    const f = {
+        age_sec: ageSec,
+        launchpad: path(tokenObj, 'launchpad') ?? null,
+        price_usd: num(path(pair, 'priceUsd')), mcap, liquidity_usd: liq,
+        liq_to_mcap_pct: pct(liq, mcap),
+        vol_h1: volH1, vol_h24: num(path(pair, 'volume', 'h24')),
+        vol_h1_to_liq: volH1 !== null && liq ? Math.round((volH1 / liq) * 100) / 100 : null,
+        buys_h1: buysH1, sells_h1: sellsH1,
+        buy_share_h1_pct: pct(buysH1, (buysH1 ?? 0) + (sellsH1 ?? 0)),
+        chg_h1_pct: num(path(pair, 'priceChange', 'h1')), chg_h24_pct: num(path(pair, 'priceChange', 'h24')),
+        holder_count: num(path(stats, 'holderCount')), holders_24h_delta: num(path(stats, 'holders24hDelta')),
+        organic_score: num(path(stats, 'organicScore')),
+        num_traders_h1: num(path(h1, 'numTraders')), net_buyers_h1: num(path(h1, 'numNetBuyers')),
+        mint_authority: boolOrNull(path(audit, 'mintAuthority')), freeze_authority: boolOrNull(path(audit, 'freezeAuthority')),
+        top10_pct: num(path(audit, 'top10Pct')), top10_ex_lp_pct: num(path(concentration, 'top10PctExLp')),
+        dev_pct: num(path(audit, 'devPct')), dev_mints: num(path(audit, 'devMints')),
+        lp_locked_pct: num(path(audit, 'lpLockedPct')) ?? num(path(security, 'lpLockedPct')),
+        rug_score: num(path(security, 'scoreNormalised')) ?? num(path(audit, 'rugScore')),
+        rug_risk_count: Array.isArray(path(security, 'risks')) ? path(security, 'risks').length : null,
+        tape_top2_share_pct: num(path(tape, 'top2WalletVolumeSharePct')),
+        tape_buy_usd: num(path(tape, 'buyUsd')), tape_sell_usd: num(path(tape, 'sellUsd')),
+        tape_distinct_wallets: num(path(tape, 'distinctWallets')),
+        drawdown_from_high_pct: num(path(candles, 'summary', 'drawdownFromHighPct')),
+        chg_window_pct: num(path(candles, 'summary', 'changePct')),
+        creator_launches: num(path(creator, 'devHistory', 'launches')),
+        creator_rugged: num(path(creator, 'devHistory', 'rugged')),
+        snipers: num(path(creator, 'snipers')), bundled_pct: num(path(creator, 'bundledPct')),
+    };
+    const tier1 = present(creator) && path(creator, 'tier') === 'tier1';
+    const flags = computeFlags(f);
+    const disqualifier = flags.some((x) => DISQUALIFIERS.has(x));
+    const hasPrice = (f.price_usd ?? 0) > 0;
+    const hasLiquidity = (f.liquidity_usd ?? 0) > 0;
+    const deterministic_verdict = !(hasPrice || hasLiquidity)
+        ? 'INSUFFICIENT_DATA'
+        : disqualifier ? 'AVOID'
+            : flags.some((x) => SOFT_FLAGS.has(x)) ? 'SPECULATIVE'
+                : (f.age_sec !== null && f.age_sec < 600 && !tier1 ? 'INSUFFICIENT_DATA' : 'WATCH');
+    const avail = (isObj(dossier.availability) ? dossier.availability : {});
+    const sections = { market, concentration, security, candles, tape, creator };
+    const inputHash = createHash('sha256').update(stableStringify(sections)).digest('hex').slice(0, 16);
+    const rug = opts.rugScorer ? Math.round(opts.rugScorer.score(f) * 1000) / 1000 : null;
+    return {
+        pack: TOKEN_DOSSIER_PACK, pack_version: TOKEN_DOSSIER_VERSION, status: 'OK', mint,
+        symbol: path(tokenObj, 'symbol') ?? null,
+        assembled_at: new Date(now).toISOString(), input_hash: inputHash,
+        availability: {
+            hasPrice, hasLiquidity, canVerdict: hasPrice || hasLiquidity,
+            present: avail.present ?? [], missing: avail.missing ?? [],
+            knownUnavailable: avail.knownUnavailable ?? [],
+        },
+        features: f, flags, deterministic_verdict,
+        rug_probability: rug, rug_model: opts.rugScorer?.id ?? null,
+        injection_suspected: scanForInjection(sections),
+        data_ages: dataAges(sections),
+        sections,
+    };
+}
+/** The named rule flags (AI-SUITE-DESIGN §2; thresholds are the task-1293 skill rules, owner: maintainers). */
+const DISQUALIFIERS = new Set(['freeze_authority_enabled', 'mint_authority_enabled', 'lp_unlocked_and_concentrated', 'wash_tape']);
+const SOFT_FLAGS = new Set(['bundled_over_15pct', 'dev_holds_over_10pct', 'serial_rugger', 'organic_below_40']);
+export function computeFlags(f) {
+    const flags = [];
+    if (f.freeze_authority === true)
+        flags.push('freeze_authority_enabled');
+    if (f.mint_authority === true)
+        flags.push('mint_authority_enabled');
+    if (f.lp_locked_pct !== null && f.lp_locked_pct < 100 && f.launchpad !== 'pump.fun' && (f.top10_ex_lp_pct ?? 0) > 50)
+        flags.push('lp_unlocked_and_concentrated');
+    if (f.tape_top2_share_pct !== null && f.tape_top2_share_pct > 60 && f.tape_buy_usd && f.tape_sell_usd && Math.abs(f.tape_buy_usd - f.tape_sell_usd) / Math.max(f.tape_buy_usd, f.tape_sell_usd) < 0.15)
+        flags.push('wash_tape');
+    if ((f.bundled_pct ?? 0) > 15)
+        flags.push('bundled_over_15pct');
+    if ((f.dev_pct ?? 0) > 10)
+        flags.push('dev_holds_over_10pct');
+    if ((f.creator_rugged ?? 0) >= 2)
+        flags.push('serial_rugger');
+    if (f.organic_score !== null && f.organic_score < 40)
+        flags.push('organic_below_40');
+    if (f.age_sec !== null && f.age_sec < 600)
+        flags.push('under_10_minutes');
+    return flags;
+}
+/** Data age per section: look for an `ageSec`/`source` at the section root or on its `pair`. */
+function dataAges(sections) {
+    const out = {};
+    for (const [k, v] of Object.entries(sections)) {
+        const root = isObj(v) ? v : undefined;
+        const pr = isObj(path(v, 'pair')) ? path(v, 'pair') : undefined;
+        out[k] = {
+            source: root?.source ?? pr?.source ?? null,
+            age_sec: num(root?.ageSec) ?? num(pr?.ageSec),
+        };
+    }
+    return out;
+}
+function errDossier(mint, error, dossier, now) {
+    return {
+        pack: TOKEN_DOSSIER_PACK, pack_version: TOKEN_DOSSIER_VERSION, status: 'ERROR', mint, symbol: null,
+        assembled_at: new Date(now).toISOString(), input_hash: '',
+        availability: { hasPrice: false, hasLiquidity: false, canVerdict: false, present: [], missing: [error], knownUnavailable: [] },
+        features: emptyFeatures(), flags: [], deterministic_verdict: 'INSUFFICIENT_DATA',
+        rug_probability: null, rug_model: null, injection_suspected: false, data_ages: {},
+        sections: { market: dossier.market ?? null }, error,
+    };
+}
+function emptyFeatures() {
+    return {
+        age_sec: null, launchpad: null, price_usd: null, mcap: null, liquidity_usd: null, liq_to_mcap_pct: null,
+        vol_h1: null, vol_h24: null, vol_h1_to_liq: null, buys_h1: null, sells_h1: null, buy_share_h1_pct: null,
+        chg_h1_pct: null, chg_h24_pct: null, holder_count: null, holders_24h_delta: null, organic_score: null,
+        num_traders_h1: null, net_buyers_h1: null, mint_authority: null, freeze_authority: null, top10_pct: null,
+        top10_ex_lp_pct: null, dev_pct: null, dev_mints: null, lp_locked_pct: null, rug_score: null, rug_risk_count: null,
+        tape_top2_share_pct: null, tape_buy_usd: null, tape_sell_usd: null, tape_distinct_wallets: null,
+        drawdown_from_high_pct: null, chg_window_pct: null, creator_launches: null, creator_rugged: null, snipers: null, bundled_pct: null,
+    };
+}
+/** Deterministic JSON for the input hash: object keys sorted so the cache key is stable across runs. */
+export function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v) ?? 'null';
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const keys = Object.keys(v).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`).join(',')}}`;
+}

package/dist/packages/packs/src/verdicts.js

@@ -0,0 +1,17 @@
+// Record a pack verdict into the recorder's `verdicts` table (schema owner: @dexterm/recorder, lane
+// L-01 reserved this table). A verdict row lets the eval/backtest score a model's output against the
+// outcomes the labeler later writes (the non-circular golden set, AI-SUITE-DESIGN §4). Deterministic
+// stages are recorded with model = null; reason stages with the model id and cost.
+//
+// Takes a `node:sqlite` DatabaseSync (Recorder.database) so the pack engine never imports the Recorder
+// class and tests can pass an in-memory DB.
+/** Insert one verdict row. The `verdicts` table is created by the recorder's SCHEMA_SQL. No-op guard if the table is absent. */
+export function recordVerdict(db, row) {
+    db.prepare(`INSERT INTO verdicts (mint, t, pack, pack_version, model, verdict, rug_p, confidence, score, cost_usd, wall_ms, input_hash, run_file)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(row.mint, row.t, row.pack, row.pack_version, row.model, row.verdict, row.rug_p, row.confidence, row.score, row.cost_usd, row.wall_ms, row.input_hash, row.run_file);
+}
+/** The most recent verdict for a mint+pack (for the cache: don't re-spend on an unchanged input_hash). */
+export function latestVerdict(db, mint, pack) {
+    const r = db.prepare('SELECT mint, t, pack, pack_version, model, verdict, rug_p, confidence, score, cost_usd, wall_ms, input_hash, run_file FROM verdicts WHERE mint = ? AND pack = ? ORDER BY t DESC LIMIT 1').get(mint, pack);
+    return r ?? null;
+}

package/dist/packages/packs/src/wallet-dossier.js

@@ -0,0 +1,105 @@
+// wallet-dossier pack, ASSEMBLE stage (AI-SUITE-DESIGN §2). "Who is this wallet?" grounded in what the
+// merged, keyless code can actually prove: the wallet's role inside a scanned token's holder intelligence
+// (@dexterm/data WalletIntel / IntelAnalysis) — its labels (each a rule id + confidence), cluster
+// membership and kind, funder / self-funded, sniper / fresh-at-buy / created-before-launch, and holding
+// share.
+//
+// HONEST SCOPE (design §2 + §14.4): cross-token PnL, win rate and the smart-money gate need the wallet
+// tracker (task-1286 W6), which is NOT built. So the `SMART` verdict can never fire on keyless data; the
+// assembled dossier records that in `availability.knownUnavailable` and the deterministic verdict is
+// NEUTRAL / SUSPECT / INSUFFICIENT_DATA from the available signals. No number here comes from model
+// memory; every fact is a field of the IntelAnalysis the tools returned.
+import { createHash } from 'node:crypto';
+import { HIDDEN_LABELS } from '../../data/src/index.js';
+import { stableStringify } from "./token-dossier.js";
+export const WALLET_DOSSIER_PACK = 'wallet-dossier';
+export const WALLET_DOSSIER_VERSION = '0.1.0';
+const num = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+/** The cross-token facts that need the wallet tracker (task-1286 W6), not available keyless. */
+const KNOWN_UNAVAILABLE = [
+    'PnL and realised/unrealised profit across tokens: needs the wallet tracker (task-1286 W6, not built)',
+    'win rate and trade count (n>=10 gate): needs the wallet tracker',
+    'smart-money gate (not exchange/MM, not self-funded, positive PnL over n>=10): not computable keyless, so SMART never fires',
+];
+/**
+ * Assemble a wallet-dossier for `wallet` from one token's `IntelAnalysis` (WalletIntel.scan output).
+ * The verdict is grounded only in that scan: a wallet not in the scanned token's holder sample is
+ * NOT_IN_SCAN with INSUFFICIENT_DATA.
+ */
+export function assembleWalletDossier(wallet, analysis, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const holder = analysis.holders.find((h) => h.owner === wallet);
+    const cluster = analysis.clusters.find((c) => c.members.includes(wallet));
+    const present = [];
+    const missing = [];
+    if (!holder) {
+        return {
+            pack: WALLET_DOSSIER_PACK, pack_version: WALLET_DOSSIER_VERSION, status: 'NOT_IN_SCAN',
+            wallet, token: analysis.mint, assembled_at: new Date(now).toISOString(),
+            input_hash: createHash('sha256').update(`${wallet}:${analysis.mint}:not-in-scan`).digest('hex').slice(0, 16),
+            availability: { canVerdict: false, present: [], missing: ['wallet not in this token\'s top-holder sample'], knownUnavailable: KNOWN_UNAVAILABLE },
+            features: emptyWalletFeatures(), flags: [], labels_restated: [], deterministic_verdict: 'INSUFFICIENT_DATA',
+            injection_suspected: false, sections: { analysis_mint: analysis.mint, holder: null, cluster: null },
+        };
+    }
+    present.push('holder-sample', 'labels');
+    if (holder.funder)
+        present.push('funder');
+    if (cluster)
+        present.push('cluster');
+    if (holder.freshAtBuy === null)
+        missing.push('fresh-at-buy: launch window needs a Helius key (keyless tier)');
+    if (holder.funder === null)
+        missing.push('funder: funding lookup needs a Helius key');
+    // Self-funded = the funder is the wallet itself, or no distinct funder was found (design: self-funded
+    // wallets are never SMART).
+    const selfFunded = holder.funder ? holder.funder.address === wallet : null;
+    const labels = holder.labels ?? [];
+    const visibleLabels = labels.filter((l) => !HIDDEN_LABELS.has(l.label));
+    const labelSet = new Set(visibleLabels.map((l) => l.label));
+    const f = {
+        in_token: true,
+        holding_pct: num(holder.pct),
+        owner_kind: holder.ownerKind ?? null,
+        cluster: cluster?.name ?? null,
+        cluster_kind: cluster?.kind ?? null,
+        cluster_pct: cluster ? num(cluster.pct) : null,
+        self_funded: selfFunded,
+        funder: holder.funder?.address ?? null,
+        funder_label: holder.funder?.label ?? null,
+        sniper: labelSet.has('sniper'),
+        fresh_at_buy: holder.freshAtBuy,
+        created_before_launch: holder.createdBeforeLaunch,
+        label_count: visibleLabels.length,
+    };
+    const flags = [];
+    if (f.sniper)
+        flags.push('sniper_window_buy');
+    if (f.cluster_kind === 'bundle')
+        flags.push('in_bundle_cluster');
+    if (f.cluster_kind === 'dev-linked')
+        flags.push('dev_linked_cluster');
+    if (f.fresh_at_buy === true)
+        flags.push('fresh_wallet_at_buy');
+    if (f.owner_kind === 'program-owned')
+        flags.push('program_owned_account');
+    // SMART is unreachable keyless (no PnL). SUSPECT when a sniper / bundle / dev-linked / fresh signal
+    // fired; NEUTRAL otherwise; an LP / CEX / contract address is INSUFFICIENT_DATA as a "trader".
+    const infra = labelSet.has('LP') || labelSet.has('cex') || labelSet.has('contract') || labelSet.has('pool');
+    const deterministic_verdict = infra ? 'INSUFFICIENT_DATA' : flags.length ? 'SUSPECT' : 'NEUTRAL';
+    const labels_restated = visibleLabels.map((l) => ({ label: l.label, rule: l.rule, confidence: l.confidence }));
+    const sections = { analysis_mint: analysis.mint, holder, cluster: cluster ?? null };
+    return {
+        pack: WALLET_DOSSIER_PACK, pack_version: WALLET_DOSSIER_VERSION, status: 'OK',
+        wallet, token: analysis.mint, assembled_at: new Date(now).toISOString(),
+        input_hash: createHash('sha256').update(stableStringify(sections)).digest('hex').slice(0, 16),
+        availability: { canVerdict: true, present, missing, knownUnavailable: KNOWN_UNAVAILABLE },
+        features: f, flags, labels_restated, deterministic_verdict, injection_suspected: false, sections,
+    };
+}
+function emptyWalletFeatures() {
+    return {
+        in_token: false, holding_pct: null, owner_kind: null, cluster: null, cluster_kind: null, cluster_pct: null,
+        self_funded: null, funder: null, funder_label: null, sniper: false, fresh_at_buy: null, created_before_launch: null, label_count: 0,
+    };
+}

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

@@ -0,0 +1,71 @@
+// Popup host configuration (task-1290). decision: keep the spike's hotkey chord and rain cadence
+// defaults, but make both configurable in a config file. The file is ~/.dexterm/popup.json (DEXTERM_HOME
+// overrides the directory, same convention as state.json / helius.key). Everything is optional; a missing
+// or malformed file degrades to the defaults and never throws — a popup must open even with a bad config.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** The spike's global-hotkey chord (⌃⌥⌘⇧B). Accelerator syntax: `Mod+Mod+Code`, matched by the shell. */
+export const DEFAULT_HOTKEY = 'Control+Alt+Super+Shift+KeyB';
+/** task-1325: the global chord that closes every popup window (⌃⌥⌘⇧W). */
+export const DEFAULT_HOTKEY_CLOSE = 'Control+Alt+Super+Shift+KeyW';
+export const DEFAULT_DOCK = { enabled: true, width: 560, follow: true, followEvery: 0.5 };
+/** The rain cadence approved in the spike. speedScale 1 = the bubble-map default fall speed. */
+export const DEFAULT_RAIN = { enabled: true, speedScale: 1, density: 0.55 };
+export const DEFAULT_CONFIG = { hotkey: DEFAULT_HOTKEY, hotkeyClose: DEFAULT_HOTKEY_CLOSE, dock: { ...DEFAULT_DOCK }, rain: { ...DEFAULT_RAIN }, fpsCap: 60, source: 'defaults' };
+/** `DEXTERM_HOME` overrides `~/.dexterm` (tests point it at a temp dir). */
+export function dexHome(env = process.env) {
+    return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+}
+export function configPath(env = process.env) {
+    return join(dexHome(env), 'popup.json');
+}
+function num(v, lo, hi, dflt) {
+    const n = typeof v === 'number' ? v : NaN;
+    return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : dflt;
+}
+/**
+ * Validate a parsed config object into a PopupConfig, clamping every field and keeping the defaults for
+ * anything missing or out of range. The hotkey must be a short printable accelerator; an unexpected value
+ * is ignored so a bad file can never register a nonsense chord or an oversized string.
+ */
+export function normalizeConfig(raw, source = 'file') {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    const rrain = (o.rain && typeof o.rain === 'object' ? o.rain : {});
+    // empty = disabled; otherwise a short accelerator of letters/digits/+ only (no shell metacharacters)
+    const chord = (v, dflt) => {
+        if (typeof v !== 'string')
+            return dflt;
+        const h = v.trim();
+        return h === '' ? '' : (/^[A-Za-z0-9+]{1,64}$/.test(h) ? h : dflt);
+    };
+    const hotkey = chord(o.hotkey, DEFAULT_HOTKEY);
+    const rdock = (o.dock && typeof o.dock === 'object' ? o.dock : {});
+    return {
+        hotkey,
+        hotkeyClose: chord(o.hotkeyClose, DEFAULT_HOTKEY_CLOSE),
+        dock: {
+            enabled: typeof rdock.enabled === 'boolean' ? rdock.enabled : DEFAULT_DOCK.enabled,
+            width: Math.round(num(rdock.width, 360, 1600, DEFAULT_DOCK.width)),
+            follow: typeof rdock.follow === 'boolean' ? rdock.follow : DEFAULT_DOCK.follow,
+            followEvery: num(rdock.followEvery, 0.25, 5, DEFAULT_DOCK.followEvery),
+        },
+        rain: {
+            enabled: typeof rrain.enabled === 'boolean' ? rrain.enabled : DEFAULT_RAIN.enabled,
+            speedScale: num(rrain.speedScale, 0.1, 5, DEFAULT_RAIN.speedScale),
+            density: num(rrain.density, 0, 1, DEFAULT_RAIN.density),
+        },
+        fpsCap: Math.round(num(o.fpsCap, 15, 120, DEFAULT_CONFIG.fpsCap)),
+        source,
+    };
+}
+/** Load ~/.dexterm/popup.json, or the defaults when it is missing/unreadable/malformed. Never throws. */
+export function loadConfig(env = process.env) {
+    try {
+        const text = readFileSync(configPath(env), 'utf8');
+        return normalizeConfig(JSON.parse(text), 'file');
+    }
+    catch {
+        return { ...DEFAULT_CONFIG, dock: { ...DEFAULT_DOCK }, rain: { ...DEFAULT_RAIN } };
+    }
+}

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

@@ -0,0 +1,271 @@
+// dexterm popup — dock the chart window beside the terminal (task-1325).
+//
+// macOS only (elsewhere every function degrades to "no docking": the shell's default geometry is used).
+//
+//   * Which terminal: TERM_PROGRAM (Apple_Terminal | iTerm.app), else LC_TERMINAL=iTerm2 (survives tmux/ssh).
+//   * Which WINDOW: the one whose tab (Terminal.app) / session (iTerm2) has OUR controlling tty, found once and
+//     then addressed by window id; the front window if no tty matches (e.g. inside tmux).
+//   * One `osascript -l JavaScript` process does the work. It prints the screens first (AppKit, no Apple Events,
+//     no permission), then the terminal window's bounds (Apple Events to the terminal app: from inside that
+//     terminal this is the app talking to itself). With follow on it stays alive, re-checks every ~0.5 s, prints
+//     only when something changed, and exits by itself when its parent (the TUI) is gone.
+//   * Placement: right edge of the terminal, same top and height; left edge when the right side has no room;
+//     overlapping the screen's right edge (always-on-top) when neither side has room; and for an unknown
+//     terminal, the right edge of the main screen (always-on-top), full visible height.
+//
+// Nothing here reads keys, URLs or tickets: the script only carries our tty name and the terminal kind.
+import { spawn, spawnSync } from 'node:child_process';
+/** The terminal app we run in, from the environment it sets. */
+export function detectTerminal(env = process.env) {
+    const tp = env.TERM_PROGRAM ?? '';
+    if (tp === 'Apple_Terminal')
+        return 'terminal';
+    if (tp === 'iTerm.app' || env.LC_TERMINAL === 'iTerm2')
+        return 'iterm';
+    return 'unknown';
+}
+/** Our controlling tty as the terminal apps report it (`/dev/ttys003`), or null. */
+export function controllingTty(pid = process.pid, run = spawnSync) {
+    try {
+        const r = run('ps', ['-o', 'tty=', '-p', String(pid)], { encoding: 'utf8', timeout: 1500 });
+        const t = String(r.stdout ?? '').trim();
+        return /^ttys?\d+$/.test(t) ? `/dev/${t}` : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The JXA probe. `tty`/`kind` are JSON-encoded into the script (never interpolated raw). */
+export function dockScript(kind, tty, follow, everyS = 0.5) {
+    const every = Math.max(0.25, Math.min(5, Number.isFinite(everyS) ? everyS : 0.5));
+    return `ObjC.import('AppKit');
+ObjC.bindFunction('getppid', ['int', []]);
+var KIND = ${JSON.stringify(kind)}, TTY = ${JSON.stringify(tty)}, FOLLOW = ${follow ? 'true' : 'false'}, EVERY = ${every};
+var PARENT = $.getppid(), winId = null;
+function rect(b) {
+  if (!b) return null;
+  if (Array.isArray(b) && b.length === 4) return [b[0], b[1], b[2] - b[0], b[3] - b[1]];
+  if (typeof b.width === 'number') return [b.x, b.y, b.width, b.height];
+  return null;
+}
+function screens() {
+  var out = [], all = $.NSScreen.screens, mainH = all.objectAtIndex(0).frame.size.height;
+  for (var i = 0; i < all.count; i++) {
+    var s = all.objectAtIndex(i), f = s.frame, v = s.visibleFrame;
+    out.push({ frame: [f.origin.x, mainH - f.origin.y - f.size.height, f.size.width, f.size.height],
+               visible: [v.origin.x, mainH - v.origin.y - v.size.height, v.size.width, v.size.height], scale: s.backingScaleFactor });
+  }
+  return out;
+}
+function find(app, tabsOf) {
+  if (!app.running()) return null;
+  if (winId !== null) { try { return rect(app.windows.byId(winId).bounds()); } catch (e) { winId = null; } }
+  var ws = app.windows();
+  for (var i = 0; i < ws.length; i++) { if (TTY && tabsOf(ws[i])) { winId = ws[i].id(); return rect(ws[i].bounds()); } }
+  return ws.length ? rect(ws[0].bounds()) : null;
+}
+function term() {
+  try {
+    if (KIND === 'terminal') return find(Application('com.apple.Terminal'), function (w) {
+      var t = w.tabs(); for (var j = 0; j < t.length; j++) if (t[j].tty() === TTY) return true; return false; });
+    if (KIND === 'iterm') return find(Application('com.googlecode.iterm2'), function (w) {
+      var t = w.tabs(); for (var j = 0; j < t.length; j++) { var s = t[j].sessions(); for (var k = 0; k < s.length; k++) if (s[k].tty() === TTY) return true; } return false; });
+  } catch (e) { return null; }
+  return null;
+}
+function out(s) { $.NSFileHandle.fileHandleWithStandardOutput.writeData($(s + '\\n').dataUsingEncoding($.NSUTF8StringEncoding)); }
+function run() {
+  var sc = screens(), last = '';
+  out(JSON.stringify({ screens: sc, term: null, pending: KIND !== 'unknown' }));
+  for (;;) {
+    var s = JSON.stringify({ screens: screens(), term: term(), pending: false });
+    if (s !== last) { out(s); last = s; }
+    if (!FOLLOW) return '';
+    var pp = $.getppid(); if (pp !== PARENT || pp === 1) return '';
+    delay(EVERY);
+  }
+}
+`;
+}
+const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+const toRect = (a) => Array.isArray(a) && a.length === 4 && a.every(finite) && a[2] > 0 && a[3] > 0 ? { x: a[0], y: a[1], w: a[2], h: a[3] } : null;
+/** Validate one probe line. Anything malformed → null (the caller keeps its last placement). */
+export function parseDockProbe(line) {
+    let o;
+    try {
+        o = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!o || typeof o !== 'object')
+        return null;
+    const r = o;
+    if (!Array.isArray(r.screens) || r.screens.length === 0 || r.screens.length > 16)
+        return null;
+    const screens = [];
+    for (const s of r.screens) {
+        const so = (s ?? {});
+        const frame = toRect(so.frame), visible = toRect(so.visible);
+        if (!frame || !visible)
+            return null;
+        screens.push({ frame, visible, scale: finite(so.scale) ? so.scale : 1 });
+    }
+    return { screens, term: toRect(r.term), pending: r.pending === true };
+}
+const contains = (r, x, y) => x >= r.x && x < r.x + r.w && y >= r.y && y < r.y + r.h;
+/**
+ * Where the popup goes. Pure: unit-tested with synthetic screens/terminals.
+ *   right   — the terminal's right edge, same top + height (a narrower window if 360–width pt fit)
+ *   left    — mirrored, when the right side has no room
+ *   overlap — neither side fits: the screen's right edge, always-on-top, over part of the terminal
+ *   screen-right — unknown terminal: the main screen's right edge, full visible height, always-on-top
+ */
+export function dockRect(term, screens, kind, opts = {}) {
+    const want = Math.max(360, Math.round(opts.width ?? 560));
+    const gap = Math.max(0, Math.round(opts.gap ?? 4));
+    const main = screens[0]?.visible ?? { x: 0, y: 25, w: 1440, h: 875 };
+    if (!term) {
+        const w = Math.min(want, Math.round(main.w * 0.5));
+        return { rect: { x: main.x + main.w - w, y: main.y, w, h: main.h }, mode: 'screen-right', ontop: true, kind };
+    }
+    const cx = term.x + term.w / 2, cy = term.y + Math.min(term.h / 2, 40);
+    const V = (screens.find((s) => contains(s.frame, cx, cy)) ?? screens[0])?.visible ?? main;
+    const h = Math.max(200, Math.min(term.h, V.h));
+    const y = Math.max(V.y, Math.min(term.y, V.y + V.h - h));
+    const right = V.x + V.w - (term.x + term.w) - gap;
+    const left = term.x - V.x - gap;
+    if (right >= want)
+        return { rect: { x: term.x + term.w + gap, y, w: want, h }, mode: 'right', ontop: false, kind };
+    if (right >= 360)
+        return { rect: { x: term.x + term.w + gap, y, w: right, h }, mode: 'right', ontop: false, kind };
+    if (left >= want)
+        return { rect: { x: term.x - gap - want, y, w: want, h }, mode: 'left', ontop: false, kind };
+    const w = Math.min(want, V.w);
+    return { rect: { x: V.x + V.w - w, y, w, h }, mode: 'overlap', ontop: true, kind };
+}
+const same = (a, b) => !!a && a.mode === b.mode && Math.abs(a.rect.x - b.rect.x) < 1 && Math.abs(a.rect.y - b.rect.y) < 1 && Math.abs(a.rect.w - b.rect.w) < 1 && Math.abs(a.rect.h - b.rect.h) < 1;
+/** Probes and follows the terminal window. Every failure degrades to "no docking"; it never throws. */
+export class TerminalDock {
+    kind;
+    enabled;
+    tty;
+    opts;
+    child = null;
+    last = null;
+    onExit = () => this.stop();
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.kind = detectTerminal(opts.env ?? process.env);
+        this.enabled = (opts.platform ?? process.platform) === 'darwin';
+        this.tty = opts.tty !== undefined ? opts.tty : (this.enabled && this.kind !== 'unknown' ? controllingTty() : null);
+    }
+    get following() { return this.child !== null; }
+    run(follow) {
+        const args = ['-l', 'JavaScript', '-e', dockScript(this.kind, this.tty, follow, this.opts.followEvery)];
+        return this.opts.spawnImpl ? this.opts.spawnImpl('osascript', args) : spawn('osascript', args, { stdio: ['ignore', 'pipe', 'ignore'] });
+    }
+    place1(p) {
+        return dockRect(p.term, p.screens, p.term ? this.kind : (this.kind === 'unknown' ? 'unknown' : this.kind), { width: this.opts.width, gap: this.opts.gap });
+    }
+    /**
+     * One probe, at most `timeoutMs`. Resolves with the terminal-docked placement, or — when the terminal did
+     * not answer in time (first-run Automation prompt, app busy) — the screen-right placement from the screens
+     * line, or null off macOS / when even that failed.
+     */
+    place(timeoutMs = 1500) {
+        if (!this.enabled)
+            return Promise.resolve(null);
+        return new Promise((resolve) => {
+            let best = null, buf = '', done = false;
+            let child;
+            try {
+                child = this.run(false);
+            }
+            catch {
+                resolve(null);
+                return;
+            }
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(t);
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch { /* gone */ }
+                const p = best ? this.place1(best) : null;
+                if (p)
+                    this.last = p;
+                resolve(p);
+            };
+            const t = setTimeout(finish, timeoutMs);
+            child.on('error', finish);
+            child.on('exit', finish);
+            child.stdout?.on('data', (d) => {
+                buf += d.toString();
+                let i;
+                while ((i = buf.indexOf('\n')) >= 0) {
+                    const p = parseDockProbe(buf.slice(0, i));
+                    buf = buf.slice(i + 1);
+                    if (p) {
+                        best = p;
+                        if (!p.pending)
+                            finish();
+                    }
+                }
+            });
+        });
+    }
+    /** Follow the terminal: `onPlace` fires on every changed placement. Idempotent; stop() ends it. */
+    follow(onPlace) {
+        if (!this.enabled || this.child || this.kind === 'unknown')
+            return;
+        let buf = '';
+        try {
+            this.child = this.run(true);
+        }
+        catch {
+            this.child = null;
+            return;
+        }
+        const child = this.child;
+        child.on('error', () => { if (this.child === child)
+            this.child = null; });
+        child.on('exit', () => { if (this.child === child)
+            this.child = null; });
+        child.stdout?.on('data', (d) => {
+            buf += d.toString();
+            let i;
+            while ((i = buf.indexOf('\n')) >= 0) {
+                const p = parseDockProbe(buf.slice(0, i));
+                buf = buf.slice(i + 1);
+                if (!p || p.pending || !p.term)
+                    continue; // never jump to screen-right while following
+                const pl = this.place1(p);
+                if (!same(this.last, pl)) {
+                    this.last = pl;
+                    try {
+                        onPlace(pl);
+                    }
+                    catch { /* the window may be gone */ }
+                }
+            }
+        });
+        process.once('exit', this.onExit);
+    }
+    stop() {
+        const c = this.child;
+        this.child = null;
+        process.removeListener('exit', this.onExit);
+        if (c) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* gone */ }
+        }
+    }
+    /** The child's pid while following (for the CPU measurement). */
+    get pid() { return this.child?.pid; }
+}