dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/autotrade/src/trade-ledger.js

@@ -0,0 +1,241 @@
+// dexterm autotrade — the run ledgers as UNIFIED TRADE LEDGER drafts (task-1530). Read-only.
+//
+// Every $DEXTERM_HOME/autotrade/runs/<runId>.jsonl is read, its own hash chain verified (the import event records
+// the head and the result), and its fills, reprofiles, closes and session costs become `@dexterm/data/ledger`
+// drafts. A run that traded on the paper desk (the desk executor, `executor: "paper-desk"`) booked its fills there:
+// the desk journal stays their source (SOL, fees, the book before the fill), and this run adds what the desk does
+// not know (the strategy version, whether the agent named the profile, the model, reprofiles, the price extremes
+// and the session costs) through `RunHint` and coin-matched tag / close events.
+//
+// Where each ledger field comes from:
+//   strategy           run_start: strategy id, version and strategyHash
+//   wallet mode        run_start.mode (paper; a live run's executor name says devnet or mainnet)
+//   profile            the entry fill's profile; 'structured' when the agent's DECISION named it, else 'default'
+//                      (the strategy's default profile), 'rule' for a mechanical (auto) entry
+//   entry reason       the agent's DECISION {"action":"enter","reason":…} of the session that entered (structured)
+//   exit reason        the sell fill's rule (tp1, trail, stop, max-hold, thesis-…) or agent-exit / agent-trim with
+//                      the agent's reason; reprofile events become REPROFILE tags
+//   size, prices, mcap USD fills (the desk books in USD); market cap = price × the supply the candidate tick implies
+//                      (tick mcap ÷ tick price), or the fill's own tick mcap (task-1530 runs)
+//   MFE / MAE          trade_closed peakPrice / troughPrice (task-1530 runs; older runs: the fills only)
+//   model              session_start model; session_end costUsd (session ids are scoped by run: s1 of one run is
+//                      not s1 of another)
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { appendTradeLedger, buildLedgerView, cleanLedgerText, collectDataSources, defaultSourcePaths, dextermHomeDir, tagCode, tradeLedgerPath } from '../../data/src/trade/ledger/index.js';
+import { defaultDbPath } from '../../data/src/index.js';
+import { runsDir, verifyChain } from "./ledger.js";
+const RUN_FILE = /^([0-9TZ]+-[a-z][a-z0-9-]{1,31}-[0-9a-f]{4})\.jsonl$/;
+const fin = (x) => (typeof x === 'number' && Number.isFinite(x) ? x : null);
+const str = (x) => (typeof x === 'string' && x ? x : null);
+const MINT = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** Exit codes the agent chose (its reason is its own words); every other code is a mechanical rule. */
+const AGENT_EXITS = new Set(['agent-exit', 'agent-trim']);
+/** Read every run ledger under `home` (missing directory: nothing). */
+export function importRunLedgers(home) {
+    const dir = runsDir(home);
+    const out = { results: [], hints: new Map() };
+    if (!existsSync(dir))
+        return out;
+    for (const name of readdirSync(dir).sort()) {
+        const m = RUN_FILE.exec(name);
+        if (!m)
+            continue;
+        const r = importRunLedger(join(dir, name), m[1]);
+        out.results.push(r);
+        out.hints.set(m[1], r.hint);
+    }
+    return out;
+}
+export function importRunLedger(path, runId) {
+    const declared = new Set();
+    const res = { label: `run ${runId}`, source: 'autotrade', drafts: [], events: 0, note: null, problem: null, hint: { strategy: null, declared, models: new Map() } };
+    const events = [];
+    let cut = false;
+    for (const line of readFileSync(path, 'utf8').split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            cut = true;
+            break;
+        }
+    }
+    res.events = events.length;
+    if (!events.length)
+        return res;
+    const chain = verifyChain(events);
+    const start = events.find((e) => e.kind === 'run_start') ?? null;
+    const strategy = start && str(start.strategy) ? { id: String(start.strategy), version: str(start.version), hash: str(start.strategyHash) } : null;
+    const executor = String(start?.executor ?? '');
+    const walletMode = start?.mode === 'live' ? (/mainnet/.test(executor) ? 'live' : 'devnet') : 'paper';
+    const auto = start?.decide === 'auto';
+    // task-1538: a parallel-run strategy on a shared paper account names it in its first line (and run_start).
+    const memberLine = events.find((e) => e.kind === 'fleet_member') ?? null;
+    const acct = str(memberLine?.account) ?? str(start?.account);
+    const account = acct && /^[a-z][a-z0-9-]{1,31}$/.test(acct) ? acct : null;
+    // A run on the paper desk booked its fills there: the desk journal is their source (SOL, fees, the book), so
+    // this run adds only what the desk does not know: reprofiles, the exit's price extremes and the session costs.
+    const onDesk = executor === 'paper-desk';
+    const looseSource = onDesk ? 'desk' : 'autotrade';
+    const scope = (sid) => (typeof sid === 'string' && sid ? `${runId}:${sid}`.slice(0, 80) : null);
+    const symbolOf = new Map();
+    const supplyOf = new Map();
+    const modelOf = res.hint.models;
+    res.hint.strategy = strategy;
+    const enterOf = new Map();
+    const clampOf = new Map();
+    const posOf = new Map();
+    const supplyFrom = (mcap, price, source) => {
+        const mc = fin(mcap), p = fin(price);
+        return mc && p && mc > 0 && p > 0 && Number.isFinite(mc / p) ? { tokens: mc / p, source } : null;
+    };
+    for (const e of events) {
+        const ref = `run:${runId}:${e.seq}`;
+        switch (e.kind) {
+            case 'candidate': {
+                const mint = str(e.mint);
+                if (!mint)
+                    break;
+                const sym = cleanLedgerText(e.symbol, 24);
+                if (sym)
+                    symbolOf.set(mint, sym);
+                const tick = (e.tick ?? {});
+                const s = supplyFrom(tick.mcap, tick.price, 'tick market cap ÷ price');
+                if (s)
+                    supplyOf.set(mint, s);
+                break;
+            }
+            case 'session_start': {
+                const sid = scope(e.sessionId);
+                const model = cleanLedgerText(e.model, 40);
+                if (sid && model)
+                    modelOf.set(sid, model);
+                break;
+            }
+            case 'reply': {
+                const d = e.decision;
+                const sid = scope(e.sessionId);
+                if (sid && d?.ok && d.decision?.action === 'enter') {
+                    enterOf.set(sid, { reason: cleanLedgerText(d.decision.reason, 200), profile: tagCode(d.decision.profile) });
+                    if (tagCode(d.decision.profile))
+                        declared.add(sid);
+                }
+                break;
+            }
+            case 'clamp': {
+                const mint = str(e.mint);
+                const r = (e.result ?? {});
+                if (mint && r.ok)
+                    clampOf.set(mint, { sessionId: scope(e.sessionId), profile: tagCode(r.profile) });
+                break;
+            }
+            case 'fill': {
+                const mint = str(e.mint), pid = str(e.positionId);
+                if (!mint || !MINT.test(mint) || !pid)
+                    break;
+                const side = e.side === 'sell' ? 'sell' : 'buy';
+                let pos = posOf.get(pid);
+                if (!pos) {
+                    if (side === 'sell')
+                        break; // a sell with no entry on record
+                    const c = clampOf.get(mint);
+                    pos = { key: `run:${runId}:${pid}`, sessionId: c?.sessionId ?? null, mint };
+                    posOf.set(pid, pos);
+                }
+                if (onDesk)
+                    break;
+                const usd = fin(e.usd), tokens = fin(e.tokens);
+                const own = supplyFrom(e.mcap, e.price, 'fill tick market cap ÷ price');
+                if (own)
+                    supplyOf.set(mint, own);
+                let tag = null;
+                const reason = str(e.reason);
+                if (side === 'buy' && reason === 'entry') {
+                    const dec = pos.sessionId ? enterOf.get(pos.sessionId) : undefined;
+                    const profile = tagCode(e.profile) ?? clampOf.get(mint)?.profile ?? null;
+                    const source = dec?.profile ? 'structured' : dec ? 'default' : auto ? 'rule' : 'default';
+                    tag = { profile, reason: dec?.reason ?? (auto ? 'mechanical entry (the strategy\'s entry rules matched)' : null), exitReason: null, line: null, source, ...(dec?.reason && source !== 'structured' ? { reasonSource: 'structured' } : {}) };
+                }
+                else if (side === 'sell' && reason) {
+                    const code = tagCode(reason);
+                    tag = { profile: null, reason: cleanLedgerText(e.detail, 200), exitReason: code, line: null, source: code && AGENT_EXITS.has(code) ? 'structured' : 'rule' };
+                }
+                res.drafts.push({
+                    kind: 'fill', ref, tradeKey: pos.key, t: e.t, source: 'autotrade', walletMode, side, mint, symbol: symbolOf.get(mint) ?? mint.slice(0, 4),
+                    decimals: null, sol: null, usd, tokens, priceSol: null, priceUsd: fin(e.avgPrice) ?? fin(e.price), supply: supplyOf.get(mint) ?? null,
+                    feeSol: null, impactPct: fin(e.impactPct), slippageBps: null, realizedSol: null, realizedUsd: null, bookSol: null, bookUsd: fin(e.bookUsd),
+                    closes: null, txSig: str(e.txSig), runId, agent: auto ? 'auto' : 'agent', strategy, ...(account ? { account } : {}), sessionId: pos.sessionId,
+                    model: pos.sessionId ? modelOf.get(pos.sessionId) ?? null : null, tag,
+                });
+                break;
+            }
+            case 'reprofile': {
+                const pos = posOf.get(String(e.positionId));
+                if (!pos)
+                    break;
+                res.drafts.push({ kind: 'tag', t: e.t, ref, tradeKey: onDesk ? null : pos.key, source: looseSource, mint: pos.mint, tagKind: 'reprofile', from: tagCode(e.from), to: tagCode(e.to), reason: cleanLedgerText(e.reason, 200), line: null, tagSource: 'structured' });
+                break;
+            }
+            case 'trade_closed': {
+                const tr = (e.trade ?? {});
+                const pos = posOf.get(String(tr.id));
+                if (!pos)
+                    break;
+                const sym = cleanLedgerText(tr.symbol, 24);
+                if (sym)
+                    symbolOf.set(pos.mint, sym);
+                res.drafts.push({
+                    kind: 'close', t: e.t, ref, tradeKey: onDesk ? null : pos.key, source: looseSource, mint: pos.mint, reason: tagCode(tr.exitReason), stuck: tr.stuck === true,
+                    peakPrice: fin(e.peakPrice), troughPrice: fin(e.troughPrice), entryPrice: fin(e.entryPrice), priceUnit: 'usd', sessionId: pos.sessionId,
+                });
+                break;
+            }
+            case 'session_end': {
+                const sid = scope(e.sessionId), cost = fin(e.costUsd);
+                if (sid && cost !== null && cost > 0)
+                    res.drafts.push({ kind: 'cost', t: e.t, ref, source: 'autotrade', sessionId: sid, costUsd: cost, model: modelOf.get(sid) ?? null, runId });
+                break;
+            }
+            default: break;
+        }
+    }
+    const last = events[events.length - 1];
+    const head = String(last.hash ?? '');
+    res.drafts.unshift({ kind: 'import', t: last.t, ref: `import:autotrade:${runId}:${head || `n${events.length}`}`, source: 'autotrade', label: res.label, sourceHead: head || null, sourceVerified: chain.ok && !cut, events: events.length, ...(chain.ok ? {} : { note: `the run's chain breaks at event ${chain.at}` }) });
+    if (!chain.ok)
+        res.problem = `${res.label}: its hash chain breaks at event ${chain.at} (${chain.error}); imported as found`;
+    else if (cut)
+        res.problem = `${res.label}: a line is not JSON; imported the ${events.length} events before it`;
+    return res;
+}
+/** The paper wallet db the desk last used (its rendezvous names it), else the app's default db path. */
+export function defaultWalletDb(env = process.env) {
+    try {
+        const rv = JSON.parse(readFileSync(join(dextermHomeDir(env), 'paper-agent.json'), 'utf8'));
+        if (typeof rv.db === 'string' && rv.db && rv.db !== ':memory:')
+            return rv.db;
+    }
+    catch { /* none */ }
+    return defaultDbPath(env);
+}
+/** Every source as drafts: the run ledgers first (their hints feed the desk importer), then the data-layer journals. */
+export function collectAllSources(o = {}) {
+    const env = o.env ?? process.env;
+    const runs = importRunLedgers(dextermHomeDir(env));
+    const data = collectDataSources(defaultSourcePaths(env, o.walletDb === undefined ? defaultWalletDb(env) : o.walletDb), { runs: runs.hints });
+    return [...data, ...runs.results];
+}
+/** The read view (file + pending drafts, folded). Writes nothing. */
+export function loadLedgerView(o = {}) {
+    const env = o.env ?? process.env;
+    return buildLedgerView(o.path ?? tradeLedgerPath(env), collectAllSources(o), o.now ?? Date.now());
+}
+/** `dexterm ledger sync`: append what the sources hold that the file does not (idempotent; refuses a broken file). */
+export function syncLedger(o = {}) {
+    const view = loadLedgerView(o);
+    const r = appendTradeLedger(view.path, view.pending, o.now ?? Date.now());
+    return { view, ...r };
+}

package/dist/packages/autotrade/src/yolo.js

@@ -0,0 +1,140 @@
+// dexterm autotrade — the yolo (full-port) helpers (task-1532). HIGH RISK, PAPER only (task-1571: dexterm holds no
+// key and places no live order).
+//
+// yoloReplay: the honest numbers for a full-port strategy. The same engine, clamp and monitor as a backtest, on a
+// paper copy sized at 100% of the book (one position at a time), over recorded history: the rugs, the spread of
+// losses, the chronological full-port wallet path, and a seeded bootstrap of entry sequences (how often a run of N
+// entries zeroed the wallet). A replay is not a forecast; DATA_LIMITS print next to the numbers.
+import { SKILL_MIN_N } from '../../packs/src/index.js';
+import { DATA_LIMITS, RUG_PCT, quantile, rng } from "./backtest.js";
+import { writeJsonAtomic } from "./ledger.js";
+import { runAutotrade } from "./runner.js";
+import { round } from "./strategy.js";
+export const YOLO_REPLAY_LIMITS = [
+    'Full port: each entry is measured once at the same stake (the strategy\'s startUsd), then the wallet is compounded through the entries in order with all of it in each one, so one rug takes the wallet down with it.',
+    'The strategy\'s book halts (day loss, drawdown) are lifted while measuring so one early rug does not hide every later entry; a paper run keeps them (and a zeroed book stops it for good).',
+    'A bag that cannot be sold (the pool was pulled) stays open at 0 and blocks every later entry, as it does in a run with one position at a time; on such a tape the replay ends at that rug.',
+    'Bootstrap: entries drawn at random (with replacement) from the replayed ones, as if they were independent; real entries cluster (one bad hour, one bad day), so the true spread is wider.',
+    'The LARP gate and the agent need the live web and a model: this replay enters mechanically on the screen, the safety gates and the triggers only.',
+];
+/** A trade at or below this is a rug (the backtest's RUG_PCT); a full-port wallet at or below ZEROED_FRAC of its start is "zeroed". */
+export const ZEROED_FRAC = 0.1;
+/** The bootstrap horizon: random runs of this many full-port entries (about two days at the preset's entry cap). */
+export const YOLO_SEQUENCE = 10;
+/** The stake-to-book ratio of the measuring copy: every entry is the same stake on a book this many times larger. */
+const MEASURE_BOOK_X = 1000;
+/**
+ * The paper copy the replay measures with: the strategy as written (screen, gates, triggers, exits, one position at a
+ * time, the per-day entry cap, the loss-streak cooldown, one entry per coin), entering mechanically, with every entry
+ * the SAME stake (the strategy's startUsd, so the modelled price impact is the one a full-port entry of that size
+ * would see) on a much larger book, and the book-level halts (day loss, drawdown) lifted. That way one early rug does
+ * not halt the replay and hide every later entry: each entry the rules would take is measured once, and the full-port
+ * wallet is then compounded from those results in order (yoloReplay). Built in code on purpose: no strategy file can
+ * say 100% (the schema's ceiling is 25%).
+ */
+export function measureCopy(s) {
+    const c = structuredClone(s);
+    const stake = c.bankroll.startUsd;
+    c.mode = 'paper';
+    c.bankroll = { ...c.bankroll, startUsd: stake * MEASURE_BOOK_X, source: 'fixed' };
+    c.entry = { ...c.entry, decide: 'auto' };
+    c.sizing = { mode: 'fixed', fixedUsd: stake, maxPctOfBankroll: 25, maxUsd: stake, minUsd: Math.min(c.sizing.minUsd, stake) };
+    c.risk = { ...c.risk, perTrade: { ...c.risk.perTrade, maxLossPctOfBankroll: 100 }, dailyLossHaltPct: 100, drawdown: { ...c.risk.drawdown, sizeDownAtPct: 100, haltAtPct: 100 }, maxExposurePct: 100, maxConcurrent: 1 };
+    return c;
+}
+const BUCKETS = [
+    [`rug (<= ${RUG_PCT}%)`, (p) => p <= RUG_PCT],
+    [`${RUG_PCT}% to -50%`, (p) => p > RUG_PCT && p <= -50],
+    ['-50% to -20%', (p) => p > -50 && p <= -20],
+    ['-20% to 0%', (p) => p > -20 && p <= 0],
+    ['0% to +100%', (p) => p > 0 && p < 100],
+    ['+100% or more (2x+)', (p) => p >= 100],
+];
+export async function yoloReplay(s, tape, o = {}) {
+    const copy = measureCopy(s);
+    const run = await runAutotrade({ strategy: copy, tape, sessions: null, pacing: { mode: 'lockstep' } });
+    // Entries in the order they opened; a position still open at the end counts at its liquidation mark (0 when stuck).
+    const rows = run.trades.map((t) => ({ at: t.openedAt, pct: t.pnlPct, stuck: t.stuck, recovered: t.fills.some((f) => f.reason === 'cost-recovery'), pnl: t.pnlUsd }));
+    for (const p of run.openAtEnd) {
+        const pos = run.book.open.get(p.mint);
+        const pnl = p.markUsd + pos.realizedUsd - pos.costUsd;
+        rows.push({ at: pos.openedAt, pct: round((pnl / pos.costUsd) * 100), stuck: p.stuck, recovered: pos.fills.some((f) => f.reason === 'cost-recovery'), pnl });
+    }
+    rows.sort((a, b) => a.at - b.at);
+    const multiples = rows.map((r) => (r.stuck ? 0 : Math.max(0, 1 + r.pct / 100)));
+    // The full-port wallet, entry after entry: all of it into each entry in order; once zeroed it stays zeroed.
+    let w = 1, low = 1, high = 1, zeroedAt = null;
+    for (const [i, m] of multiples.entries()) {
+        w *= m;
+        low = Math.min(low, w);
+        high = Math.max(high, w);
+        if (w <= ZEROED_FRAC) {
+            zeroedAt = i + 1;
+            break;
+        }
+    }
+    let bootstrap = null;
+    if (multiples.length) {
+        const sequence = o.sequence ?? YOLO_SEQUENCE;
+        const resamples = o.resamples ?? 2000;
+        const r = rng(o.seed ?? 1);
+        const finals = [];
+        let zeroed = 0, halved = 0, doubled = 0;
+        for (let b = 0; b < resamples; b++) {
+            let v = 1, hitZero = false;
+            for (let i = 0; i < sequence && !hitZero; i++) {
+                v *= multiples[Math.floor(r() * multiples.length)];
+                if (v <= ZEROED_FRAC)
+                    hitZero = true;
+            }
+            if (hitZero)
+                zeroed++;
+            if (v <= 0.5)
+                halved++;
+            if (v >= 2)
+                doubled++;
+            finals.push(v);
+        }
+        finals.sort((a, b) => a - b);
+        const pct = (n) => round((n / resamples) * 100, 1);
+        bootstrap = { sequence, resamples, zeroedPct: pct(zeroed), halvedPct: pct(halved), doubledPct: pct(doubled), p10: round(quantile(finals, 0.1), 3), p50: round(quantile(finals, 0.5), 3), p90: round(quantile(finals, 0.9), 3) };
+    }
+    const first = tape.ticks[0]?.t, lastT = tape.ticks[tape.ticks.length - 1]?.t;
+    return {
+        strategy: { id: s.id, version: s.version, hash: s.hash },
+        tape: { source: tape.source, mints: tape.mints.length, ticks: tape.ticks.length, from: first ? new Date(first).toISOString() : null, to: lastT ? new Date(lastT).toISOString() : null },
+        entries: rows.length,
+        wins: rows.filter((x) => x.pnl > 0).length,
+        rugs: rows.filter((x) => x.pct <= RUG_PCT || x.stuck).length,
+        costRecovered: rows.filter((x) => x.recovered).length,
+        spread: BUCKETS.map(([label, f]) => ({ label, n: rows.filter((x) => f(x.stuck ? -100 : x.pct)).length })),
+        path: { final: round(w, 3), low: round(low, 3), high: round(high, 3), zeroed: zeroedAt !== null, zeroedAtEntry: zeroedAt },
+        bootstrap,
+        small: rows.length < SKILL_MIN_N,
+        limits: [...YOLO_REPLAY_LIMITS, ...DATA_LIMITS],
+    };
+}
+export function renderYoloReplay(r) {
+    const x = (m) => `${m.toFixed(2)}x`;
+    const b = r.bootstrap;
+    return [
+        `YOLO REPLAY ${r.strategy.id} v${r.strategy.version} (${r.strategy.hash}) · HIGH RISK · PAPER, full port, recorded data`,
+        `tape: ${r.tape.mints} coins, ${r.tape.ticks} rows, ${r.tape.from ?? '—'} → ${r.tape.to ?? '—'}`,
+        `entries ${r.entries} · won ${r.wins} · RUGS ${r.rugs}${r.entries ? ` (${Math.round((r.rugs / r.entries) * 100)}% of entries)` : ''} · cost taken back ${r.costRecovered}`,
+        '  per entry (% of the stake):',
+        ...r.spread.map((s) => `    ${s.label.padEnd(22)} ${String(s.n).padStart(4)}`),
+        r.path.zeroed
+            ? `  the wallet, all of it into each entry in order: ZEROED at entry ${r.path.zeroedAtEntry} of ${r.entries} (fell to <= ${x(ZEROED_FRAC)}) · highest ${x(r.path.high)} before that`
+            : `  the wallet, all of it into each entry in order: ended at ${x(r.path.final)} of the start · lowest ${x(r.path.low)} · highest ${x(r.path.high)}`,
+        b ? `  ${b.resamples} random runs of ${b.sequence} entries: ZEROED THE WALLET in ${b.zeroedPct}% · halved it or worse in ${b.halvedPct}% · doubled it in ${b.doubledPct}% · end P10 ${x(b.p10)} · median ${x(b.p50)} · P90 ${x(b.p90)}` : '  no entries on this history: nothing to resample (the gates refused every coin, or the tape is too short)',
+        r.small ? `  NOTE: ${r.entries} entries is below n = ${SKILL_MIN_N}: read the counts, not the rates.` : '',
+        '  limits of this replay:', ...r.limits.map((l) => `    - ${l}`),
+        '  HIGH RISK. Paper only; not financial advice. A replay is not a forecast.',
+    ].filter(Boolean).join('\n');
+}
+// ───────────────────────────── built-in tapes ─────────────────────────────
+/** `--replay builtin:<name>`: a tape shipped with the app (assets/tapes); `yolo-rehearsal` is a short fixture tape for a paper yolo run. */
+export function builtinTapePath(arg) {
+    const m = /^builtin:([a-z][a-z0-9-]{1,40})$/.exec(arg);
+    return m ? new URL(`../assets/tapes/${m[1]}.json`, import.meta.url) : arg;
+}

package/dist/packages/cli/assets/claude/analyst-system.md

@@ -1,15 +1,15 @@
 You are the dexterm analyst: a Solana token trader's analyst inside a terminal screener. You give a direct trading call: bias, entry, invalidation, size and confidence. That is the whole point of the product. When a named skill is running, follow its tool order and its output contract.
 
 ## How to answer (every free-text answer)
-The user reads you in a narrow panel beside the screener. They can ALREADY SEE the price, % changes, liquidity, volume and every row listed in the CONTEXT block. Write like a desk trader on chat: short, specific, decided.
+The user reads you in a narrow panel beside the screener. They can ALREADY SEE the market cap and price, % changes, liquidity, volume and every row listed in the CONTEXT block. Write like a desk trader on chat: short, specific, decided.
 
 ## Live numbers (every turn)
-Every turn's CONTEXT block opens with a LIVE SNAPSHOT of the selected coin: current price, 5m/1h/6h/24h move, mcap/liq/volume, the TOTAL holder count and recent price history. Those numbers are fresher than anything said earlier in this chat: reason from them, never from a price or holder count you remember from a previous turn. The holder count is the TOTAL; `get_holders` returns only a top-20 sample, so never report its list length as the holder count. When the snapshot says history is not loaded, call `get_dossier` (or `get_candles`) before you state levels, entries or price action, and say plainly when a number is missing instead of estimating it.
+Every turn's CONTEXT block opens with a LIVE SNAPSHOT of the selected coin: current market cap and price, 5m/1h/6h/24h move, mcap/liq/volume, the TOTAL holder count and recent price history. Those numbers are fresher than anything said earlier in this chat: reason from them, never from a price or holder count you remember from a previous turn. The holder count is the TOTAL; `get_holders` returns only a top-20 sample, so never report its list length as the holder count. When the snapshot says history is not loaded, call `get_dossier` (or `get_candles`) before you state levels, entries or price action, and say plainly when a number is missing instead of estimating it.
 
 DEFAULT = 3 to 6 short lines of plain text. Each line is ONE terse clause or two, at most ~90 characters, with `;` or `·` between facts instead of sentences. No blank lines, no headers, no bullets, no tables, no bold. Whole answer under ~450 characters.
 1. Call: `LONG|SHORT|WAIT|AVOID <SYMBOL> · conf <0-100> · setup strong|mixed|weak`
 2. why: the one or two tool facts that decide it and that are NOT already on screen (authorities, LP lock, holder concentration, buy/sell tape, wallet share, dev/sniper data, structure).
-3. levels: `entry <zone> · invalid <level> (<why>) · target <level>` with real numbers from tool results.
+3. levels: `entry <zone> · invalid <level> (<why>) · target <level>` with real numbers from tool results, in the turn's PRICE BASIS (the last section of this prompt; market cap by default: `entry $380K–$400K`).
 4. size: `risk <x–y>% of account, stop at invalid`. Only when the user states their account size, add the math in the same line: `$<account> × <risk%> = $<risk> risk; <stop%> stop → ~$<position> position`. Never invent an account size.
 5. risk (optional, at most ONE line): only a risk that changes the trade.
 You may end the size line with a short PAPER-ticket offer (`say "ticket" to stage it`).
@@ -18,7 +18,7 @@ Format example (shape only; the symbol and numbers are invented, never reuse the
 ```
 WAIT XYZ · conf 55 · setup mixed
 why: 1h tape 35 sells vs 13 buys; 2 wallets = 49% of volume; mint/freeze off
-levels: entry 0.0038–0.0040 if it holds · invalid < 0.0036 (VWAP) · target 0.0046
+levels: entry $380K–$400K mcap if it holds · invalid < $360K (VWAP) · target $460K (1.2x)
 size: risk 0.5% of account, stop at invalid · say "ticket" to stage it
 risk: 59% of LP unlocked; exit on any LP pull
 ```

package/dist/packages/cli/assets/claude/plugin/skills/REGISTRY.json

@@ -5,7 +5,7 @@
     { "name": "token-dossier", "status": "proven", "schema": "schemas/verdict.schema.json", "tools": ["screen_state", "get_dossier", "kb_lookup"], "owner": "maintainers" },
     { "name": "rug-check", "status": "proven", "schema": "schemas/verdict.schema.json", "tools": ["screen_state", "get_dossier", "kb_lookup"], "owner": "maintainers" },
     { "name": "trench-scan", "status": "proven", "schema": "schemas/trench-scan.schema.json", "tools": ["screener_query", "get_token", "rugcheck", "get_dev_history"], "owner": "maintainers" },
-    { "name": "larp-check", "status": "proven", "schema": "schemas/larp.schema.json", "tools": ["screen_state", "get_token", "get_links", "fetch_page", "check_domain", "check_github", "kb_lookup"], "owner": "maintainers", "note": "Vets the website/socials behind a coin for a real product vs a LARP via SSRF-safe read-only fetch; fetched page text is firewalled <untrusted>." },
+    { "name": "larp-check", "status": "proven", "schema": "schemas/larp.schema.json", "tools": ["screen_state", "get_token", "larp_check", "get_links", "fetch_page", "check_domain", "check_github", "check_x", "kb_lookup"], "owner": "maintainers", "note": "Vets the website/socials behind a coin for a real product vs a LARP via SSRF-safe read-only fetch and a keyless X account lookup, with a 0-100 LARP score (a sum of named flags); fetched page text and bios are firewalled <untrusted>." },
     { "name": "launch-forensics", "status": "defined", "schema": "schemas/verdict.schema.json", "tools": ["get_token", "get_dev_history", "get_holders", "get_trades", "kb_lookup"], "owner": "maintainers", "needs": "Tier-1 first-N-slot buys and funding-source clusters from the Helius history adapter (data lane item 1); until then bundledPct/snipers are null and the skill returns INSUFFICIENT_DATA" },
     { "name": "narrative-scan", "status": "defined", "schema": "schemas/narrative.schema.json", "tools": ["screener_query", "get_token", "kb_lookup"], "owner": "maintainers", "needs": "theme matcher over firewalled names/descriptions; KB entry narrative-lifecycle reviewed by the maintainers; X feed (1289) optional" },
     { "name": "wallet-dossier", "status": "defined", "schema": "schemas/wallet.schema.json", "tools": ["get_wallet", "get_wallet_trades", "get_labels", "kb_lookup"], "owner": "maintainers", "needs": "wallet tools (task-1286): history, PnL, early-entry score, labels with evidence" },

package/dist/packages/cli/assets/claude/plugin/skills/larp-check/SKILL.md

@@ -1,17 +1,19 @@
 ---
 name: larp-check
 description: Vet the website and socials behind a Solana token to judge whether there is a real product or it is a LARP (claims a product that does not exist). Use when the user asks "is this real", "larp check", "is the product real", "check the website/socials".
-version: 0.2.0
+version: 0.3.0
 argument-hint: <mint or symbol>
 kind: skill
 output_schema: schemas/larp.schema.json
 tools:
   - screen_state
   - get_token
+  - larp_check
   - get_links
   - fetch_page
   - check_domain
   - check_github
+  - check_x
   - kb_lookup
 arguments:
   - target
@@ -30,14 +32,12 @@ You are judging one thing: **does a real product exist behind this coin, or is t
 2. `get_token` with `{mint}` for a base58 address (32–44 chars), else `{symbol}`.
    - If the result has `candidates`: stop. Verdict `AMBIGUOUS`, `mint` = "", list the candidates, ask the user to pick a mint. Analyse none of them.
    - If the result has `error`: stop with `UNVERIFIABLE` and say why.
-3. `get_links` `{mint}` — the website and socials the coin advertises. Note any `mismatch` and read `baseline` (below).
-4. `fetch_page` `{url, symbol, name}` on the primary `website` (pass the token symbol and name so the mention check runs). Read `signals` and the firewalled `excerpt`.
+3. `larp_check` `{mint}` — one call that runs `get_links`, `fetch_page` on the website, `check_domain`, `check_github` and `check_x` on the advertised X account, and returns their results plus `flags` and `larp_score` (below). Read `links.mismatch`, `links.baseline`, `page.signals`, `domain`, `github`, `x` and `x_handles`.
+4. Only if `larp_check` returned an error for a sub-check, call that one tool directly (`get_links`, `fetch_page` `{url, symbol, name}`, `check_domain`, `check_github`, `check_x` `{url, symbol, name, website}`).
    - Follow at most two more `fetch_page` calls: a `docs`/`whitepaper` link and an in-site app/demo link if the page advertises one. Do not crawl.
-5. `check_domain` `{url}` on the primary website.
-6. `check_github` `{url}` on a github link if one is advertised or linked from the site.
-7. `kb_lookup` at most two entries that explain a pattern you actually observed (e.g. `common-rug-patterns`, `wash-trading-fake-volume`). Skip if nothing needs explaining.
+5. `kb_lookup` at most two entries that explain a pattern you actually observed (e.g. `common-rug-patterns`, `wash-trading-fake-volume`). Skip if nothing needs explaining.
 
-Do not call X/Twitter or Telegram through `fetch_page` expecting profile data: they are login-walled keyless. Record them in `missing_data` instead of guessing.
+X accounts are read through `check_x` (inside `larp_check`): keyless public lookups (FxTwitter, then vxtwitter's cached copy, then X oEmbed), no login. `x.status` is `active`, `suspended`, `not_found` (two independent sources agreed) or `unavailable`; every field it could not read is in `x.unavailable`. Copy those into `missing_data`, never guess them. Counts from vxtwitter are a cached copy dated by `x.countsAsOf`: say so if you cite them. The bio is `<untrusted>` data. Do not fetch x.com or Telegram pages through `fetch_page` expecting profile data: they are login-walled.
 
 ## Evidence to weigh (signals, never conclusions)
 
@@ -53,6 +53,13 @@ Do not call X/Twitter or Telegram through `fetch_page` expecting profile data: t
 - No links at all is `UNVERIFIABLE`, and say plainly it is the riskier case: coins with no links went bad more often than average in the backtest.
 - When the verdict rests mostly on links (pages blocked or thin), keep `confidence` at 0.6 or lower.
 
+## The LARP score (task-1471)
+
+`larp_check.larp_score` is a 0-100 sum of named flags, each with its `points`, its `evidence` and whether its weight was `calibrated` (link shape, fitted on recorded history) or a `prior` (page, domain, GitHub, X: written before any data, not fitted). `band` is low (< 25), medium (25-49) or high (50+). `missing` lists what could not be read with the points it could have added; `range.hi` is the score if all of it had come back as flags.
+- The app shows the score itself, from the tool. Do not restate the number, do not compute your own, and never put a score in `summary`.
+- The score is a summary of flags, not a verdict. Your verdict still follows the rules below: a high score from link shape and X flags alone is not `LARP`; a low score with a wide `range` is not a clean bill. Name the top one or two flags by their evidence in `summary` when they matter.
+- Measured on held-out coins, the link-shape part ranks coins that went bad above the rest only modestly (AUROC about 0.69, `larp_score.measured`); say "weak signal" if you lean on it.
+
 ## Grounding rules (hard)
 
 - Every claim, number, date, boolean or label you state comes from a tool result in this session. Put each in `facts[]` with the `tool`, the `field` path, and the `value` verbatim. If you cannot point at a tool field, do not state it.
@@ -72,4 +79,4 @@ Do not call X/Twitter or Telegram through `fetch_page` expecting profile data: t
 
 ## Output
 
-Return only the JSON object required by the schema (`skill: "larp-check"`, `skill_version: "0.2.0"`). Fill `claims[]`, `facts[]` and `missing_data[]` completely. `summary` is two to four short lines for a 40-column panel: the verdict in plain words, the one or two strongest pieces of evidence (each with its source), and what was missing only if it matters. Do not repeat the confidence number (the app renders it), and add no disclaimer or boilerplate line.
+Return only the JSON object required by the schema (`skill: "larp-check"`, `skill_version: "0.3.0"`). Fill `claims[]`, `facts[]` and `missing_data[]` completely. `summary` is two to four short lines for a 40-column panel: the verdict in plain words, the one or two strongest pieces of evidence (each with its source), and what was missing only if it matters. Do not repeat the confidence number (the app renders it), and add no disclaimer or boilerplate line.

package/dist/packages/cli/assets/claude/plugin/skills/token-dossier/SKILL.md

@@ -49,7 +49,7 @@ Judge with what you have. Missing sections lower `confidence`; they do not block
 
 - `bias`: `long`, `short`, `avoid`, or `wait`. A disqualifier means `avoid`; young/thin data usually means `wait`; otherwise take a directional side from the structure and tape. (`avoid`/`wait` when `verdict` is INSUFFICIENT_DATA/AMBIGUOUS; omit `bias` only then.)
 - `setup_quality`: `strong`, `mixed`, or `weak` from liquidity depth, holder spread, tape quality and the chart.
-- `key_levels[]`: pull concrete numbers from `get_candles` (`summary.high`, `summary.low`, `summary.vwap`, range) and from liquidity — support, resistance, VWAP, and the level whose break invalidates the idea. Label each; copy the value.
+- `key_levels[]`: pull concrete numbers from `get_candles` (`summary.high`, `summary.low`, `summary.vwap`, range) and from liquidity — support, resistance, VWAP, and the level whose break invalidates the idea. Label each; copy the value. Write levels in the turn's PRICE BASIS (the system prompt's last section): by default the market-cap twins (`summary.highMcap`, `lowMcap`, `vwapMcap`) as strings like `"$380K"`; in price basis the price fields. When a cap twin is null the supply is unknown: copy the price and say `price; supply unknown` in the note.
 - `invalidation`: the specific level/condition that makes the view wrong (a level breaking, LP pulled, dev selling, authority flip).
 - `size_hint`: frame size as a fraction of risk capital with the stop at the invalidation (e.g. "0.5–1% risk, stop below the range low"). Never a dollar amount or a token count.
 - You may offer to open a PAPER ticket (the ticket action in the system prompt); it only opens, the user confirms. You never execute a trade. `proposals[]` may still suggest an alert, a note or a watch-list add.

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

@@ -15,7 +15,7 @@
 // config; it is never stored in plaintext and never echoed again. The token for `serve`/`connect` auth is
 // read ONLY from the $DEXTERM_AGENT_TOKEN environment variable — never a command-line flag — so it cannot
 // leak through a process list. No agent path can arm, sign, send, raise a cap or touch a wallet/mandate.
-import { AgentRegistry, SqliteAuditLog, MemoryProposalStore, SqliteProposalStore, AgentBus, FixtureExecutor, FixtureFeed, SpectatorHub, SpectatorServer, SpectatorRecorder, FollowController, TIERS, isTier, } from '../../agents/src/index.js';
+import { AgentRegistry, SqliteAuditLog, MemoryProposalStore, SqliteProposalStore, AgentBus, FixtureExecutor, FixtureFeed, SpectatorHub, SpectatorServer, SpectatorRecorder, FollowController, AgentStory, TIERS, isTier, } from '../../agents/src/index.js';
 import { connectAgent } from '../../agents/src/sdk.js';
 import { defaultDbPath } from '../../data/src/index.js';
 function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
@@ -321,13 +321,15 @@ async function serve(rest, io, registry) {
             const { THEMES, DEFAULT_THEME } = await import('../../tui/src/index.js');
             const { popupThemeFrom } = await import("./popup.js");
             const follow = new FollowController({ controls: bus, activityCap: 200 });
-            const off = hub.on((ev) => follow.apply(ev));
+            // task-1466: the agent story (phase rail, heartbeat, timeline, thoughts) the popup draws above the activity.
+            const story = new AgentStory();
+            const off = hub.on((ev) => { follow.apply(ev); story.apply(ev); });
             const mgr = createPopupManager({ theme: popupThemeFrom(THEMES[DEFAULT_THEME]), env: io.env, onWarn: (m) => io.stderr.write(`spectator popup: ${m}\n`),
                 onEvent: (ev) => { if (ev.ev === 'popup.event' && ev.name.startsWith('spectator.'))
                     io.stdout.write(`spectator: ${applySpectatorEvent(follow, ev.name, String(ev.payload.agent))}\n`); } });
-            const handle = await mgr.open({ kind: 'spectator', title: 'watch the agent cook', data: buildSpectatorVM(follow) });
+            const handle = await mgr.open({ kind: 'spectator', title: 'watch the agent cook', data: buildSpectatorVM(follow, { story: story.view(Date.now()) }) });
             const timer = setInterval(() => { try {
-                mgr.setData(handle.id, buildSpectatorVM(follow));
+                mgr.setData(handle.id, buildSpectatorVM(follow, { story: story.view(Date.now()) }));
             }
             catch { /* popup closed */ } }, 1000);
             timer.unref?.();

package/dist/packages/cli/src/agent-spectator.js

@@ -1,7 +1,22 @@
 // task-1406 "watch the agent cook": bridge the follow-mode controller to the spectator popup VM, and map
 // the popup's spectator.* UI events onto the controller's user-side controls. Nothing here can arm, sign
 // or raise a cap — the controls are exactly the bus's pause/resume/kick, the same as the roster popup.
-import { redactSpectatorEvent, maskAddress } from '../../agents/src/index.js';
+import { redactSpectatorEvent, redactString, maskAddress, STORY_RAIL } from '../../agents/src/index.js';
+/** task-1466: the story for the popup, every string redacted (addresses masked, keys removed). */
+export function storyVM(v, redact = true) {
+    const r = (s) => (redact ? redactString(s) : s);
+    const a = v.arc?.stage === 'closed' || !v.arc ? (v.arc ?? v.lastResult) : v.arc;
+    return {
+        phase: v.phase, rail: [...STORY_RAIL], sub: v.sub, bpm: v.bpm, control: v.control, calls: v.calls,
+        thoughts: v.thoughts.slice(-4).map((x) => ({ t: x.t, text: r(x.text), source: x.source })),
+        nodes: v.nodes.slice(-24).map((n) => ({ t: n.t, label: r(n.label), ms: n.ms, status: n.status, paper: n.paper, phase: n.phase, count: n.count })),
+        focus: v.focus ? { symbol: r(v.focus.symbol), checks: [...v.focus.checks], verdict: v.focus.verdict?.label ?? null, rug: v.focus.verdict?.rug ?? null, larpFlags: v.focus.larp?.flags ?? null } : null,
+        arc: a ? {
+            symbol: r(a.symbol), stage: a.stage, sizeUsd: a.sizeUsd, entryUsd: a.entryUsd, markUsd: a.mark?.priceUsd ?? null, pnlPct: a.pnlPct, peakPct: a.peakPct,
+            exits: a.fills.filter((f) => f.side === 'sell').length, realizedSol: a.result?.realizedSol ?? null, resultPct: a.result?.pct ?? null, refusal: a.refusal ? r(a.refusal) : null,
+        } : null,
+    };
+}
 function activityVM(ev) {
     return {
         seq: ev.seq, t: ev.t, phase: ev.phase, agent: ev.agent, tier: ev.tier ?? null,
@@ -16,6 +31,7 @@ export function buildSpectatorVM(follow, opts = {}) {
     const s = v.screen;
     const mask = (x) => (x && redact ? maskAddress(x) : x);
     return {
+        ...(opts.story ? { story: storyVM(opts.story, redact) } : {}),
         title: opts.title ?? 'watch the agent cook',
         now: Date.now(),
         redacted: redact,