dexterm-cli 0.2.1 → 0.2.2

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

@@ -1,12 +1,14 @@
 // ~/.dexterm/classifier.json (schema dexterm.classifier/1). `provider` is the one switch (`classifier.provider`);
 // `default` is the shipped recommendation (`classifier.default`), chosen by the task-1822 benchmark. Loading never
 // throws: each bad field falls back to its default and is reported. Writing is atomic, 0600 in a 0700 dir.
-// The hosted API key is NOT stored here: it lives in its own 0600 file (or the TYPESAFE_API_KEY env var).
+// The hosted API key is NOT stored here: it lives in its own 0600 file (on Windows an owner-only ACL, see
+// win-acl.ts) or the TYPESAFE_API_KEY env var.
 import fs from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { CATALOG } from "./models.js";
 import { PROVIDER_IDS } from "./types.js";
+import { checkOwnerOnly, currentUserSid, lockOwnerOnly } from "./win-acl.js";
 export const CLASSIFIER_SCHEMA = 'dexterm.classifier/1';
 /**
  * The shipped default (task-1822 benchmark, research/classifier-2026-10/REPORT.md §3, picked on VALID before any
@@ -163,32 +165,108 @@ export function saveClassifierConfig(c, env = process.env) {
     writeAtomic(p, JSON.stringify(c, null, 2) + '\n');
     return p;
 }
-/** The user's TypeSafe key: env TYPESAFE_API_KEY first, then the 0600 key file. Never logged. */
-export function readTypesafeKey(env = process.env) {
+// A Windows ACL probe spawns PowerShell (~0.5 s) and hosted calls read the key per request, so a passing check is
+// remembered for one minute per (path, size, mtime, ctime).
+const aclOk = new Map();
+const ACL_OK_MS = 60_000;
+/** Where the TypeSafe key comes from, or why the key file is refused. The key itself is never logged. */
+export function typesafeKeyState(env = process.env, opts = {}) {
     const e = env.TYPESAFE_API_KEY?.trim();
     if (e)
-        return e;
+        return { source: 'env', key: e };
+    const p = typesafeKeyPath(env);
+    let st;
     try {
-        const p = typesafeKeyPath(env);
-        const st = fs.statSync(p);
-        if ((st.mode & 0o077) !== 0)
-            return null; // refuse a key file other users can read
-        const k = fs.readFileSync(p, 'utf8').trim();
-        return k || null;
+        st = fs.statSync(p);
     }
     catch {
-        return null;
+        return { source: 'none', path: p };
+    }
+    if ((opts.platform ?? process.platform) === 'win32') {
+        // NTFS has no mode bits (stat says 0666 for every file): the access list decides
+        const memo = `${p}|${st.size}|${st.mtimeMs}|${st.ctimeMs}`;
+        if (opts.fresh || opts.acl || !((aclOk.get(memo) ?? 0) > Date.now())) {
+            aclOk.delete(memo);
+            const c = checkOwnerOnly(p, opts.acl);
+            if (!c.ok)
+                return { source: 'refused', path: p, reason: c.reason };
+            if (!opts.acl)
+                aclOk.set(memo, Date.now() + ACL_OK_MS); // injected (test) probes are never remembered
+        }
+    }
+    else if ((st.mode & 0o077) !== 0) {
+        // refuse a key file other users can read
+        return { source: 'refused', path: p, reason: `other users can access it (mode ${(st.mode & 0o777).toString(8)}; chmod 600 it)` };
+    }
+    try {
+        const k = fs.readFileSync(p, 'utf8').trim();
+        return k ? { source: 'file', key: k, path: p } : { source: 'none', path: p };
+    }
+    catch (x) {
+        return { source: 'refused', path: p, reason: `it cannot be read (${x.code ?? 'error'})` };
     }
 }
-export function writeTypesafeKey(key, env = process.env) {
+/** One line on why a key file is refused, naming the env var as the way out. Never contains the key. */
+export const typesafeKeyRefusal = (s) => `the TypeSafe key file ${s.path} is refused: ${s.reason}. Run \`dexterm classifier key set\` again, or set TYPESAFE_API_KEY in your environment instead.`;
+/** The user's TypeSafe key: env TYPESAFE_API_KEY first, then the owner-only key file (0600; on Windows an owner-only ACL). Never logged. */
+export function readTypesafeKey(env = process.env, opts = {}) {
+    const s = typesafeKeyState(env, opts);
+    return s.source === 'env' || s.source === 'file' ? s.key : null;
+}
+export function writeTypesafeKey(key, env = process.env, opts = {}) {
     const k = key.trim();
     if (!/^[\x21-\x7e]{8,512}$/.test(k))
         throw new Error('that does not look like an API key (8-512 printable characters, no spaces)');
     const p = typesafeKeyPath(env);
+    if ((opts.platform ?? process.platform) === 'win32') {
+        writeKeyWindows(p, k + '\n', opts.acl);
+        return p;
+    }
     writeAtomic(p, k + '\n');
     fs.chmodSync(p, 0o600);
     return p;
 }
+/**
+ * Windows: the temp file is created EMPTY, locked to the current user and checked before the key goes into it, then
+ * renamed into place (a same-volume rename keeps its access list) and checked again. Any failure removes what was
+ * written and throws a message naming TYPESAFE_API_KEY.
+ */
+function writeKeyWindows(p, text, acl) {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.${process.pid}.tmp`;
+    const fail = (what) => {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch { /* ignore */ }
+        throw new Error(`could not restrict the key file to your Windows account (${what}). Nothing was saved. Set TYPESAFE_API_KEY in your environment instead.`);
+    };
+    try {
+        fs.writeFileSync(tmp, '');
+    }
+    catch (e) {
+        fail(`create: ${e.code ?? 'error'}`);
+    }
+    try {
+        lockOwnerOnly(tmp, currentUserSid(acl), acl);
+    }
+    catch (e) {
+        fail(`icacls: ${e instanceof Error ? e.message.split(/\r?\n/)[0] : String(e)}`);
+    }
+    const pre = checkOwnerOnly(tmp, acl);
+    if (!pre.ok)
+        fail(pre.reason);
+    fs.writeFileSync(tmp, text);
+    fs.renameSync(tmp, p);
+    const post = checkOwnerOnly(p, acl);
+    if (!post.ok) {
+        try {
+            fs.rmSync(p, { force: true });
+        }
+        catch { /* ignore */ }
+        fail(post.reason);
+    }
+}
 export function removeTypesafeKey(env = process.env) {
     try {
         fs.rmSync(typesafeKeyPath(env));

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

@@ -8,6 +8,7 @@ export * from "./calibrate.js";
 export * from "./classify.js";
 export * from "./models.js";
 export * from "./config.js";
+export { checkOwnerOnly, currentUserSid, lockOwnerOnly, readSddl, sddlOwnerOnly } from "./win-acl.js";
 export * from "./hardware.js";
 export * from "./registry.js";
 export { heuristicProvider, LARP_POINTS_PLATT, WIN_BASE_RATE } from "./providers/heuristic.js";

package/dist/packages/classifier/src/win-acl.js

@@ -0,0 +1,71 @@
+// task-2147: owner-only secret files on Windows. NTFS has no POSIX mode bits (chmod only toggles read-only and
+// stat reports 0666), so the mode cannot say who may read a file; its DACL can. Writes lock the file to the current
+// user with icacls, by SID (account names are localized); reads check the DACL as SDDL (locale-free). Any probe
+// failure refuses the file: the caller names the TYPESAFE_API_KEY env var as the way out.
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+/**
+ * Well-known principals that may hold a key file besides its user (the set Windows OpenSSH accepts). `LA` is the
+ * built-in Administrator (RID 500), always a member of BA: SDDL writes that account's own SID in this alias form.
+ */
+const ALLOWED_WELL_KNOWN = new Set(['SY', 'S-1-5-18', 'BA', 'S-1-5-32-544', 'LA']);
+/** The SDDL aliases that can stand for `sid` itself (task-2155: SDDL never spells RID 500 / 501 as S-1-…). */
+const selfAliases = (sid) => (/-500$/.test(sid) ? ['LA'] : /-501$/.test(sid) ? ['LG'] : []);
+const SID_RE = /^S-1-\d+(-\d+)+$/i;
+const system32 = (...p) => path.win32.join(process.env.SystemRoot || process.env.windir || 'C:\\Windows', 'System32', ...p);
+const defaultRun = (exe, args, env) => execFileSync(exe, args, { env, encoding: 'utf8', windowsHide: true, timeout: 15_000, stdio: ['ignore', 'pipe', 'pipe'] });
+/** The current user's SID (`whoami /user`, CSV: "host\user","S-1-5-21-..."). */
+export function currentUserSid(deps = {}) {
+    const out = (deps.run ?? defaultRun)(system32('whoami.exe'), ['/user', '/fo', 'csv', '/nh'], process.env);
+    const sid = out.trim().split(/\r?\n/).pop()?.split(',').pop()?.replace(/"/g, '').trim() ?? '';
+    if (!SID_RE.test(sid))
+        throw new Error('could not read the current Windows account SID');
+    return sid;
+}
+/** Remove inherited access and grant only `sid` full control (icacls, no shell). */
+export function lockOwnerOnly(p, sid, deps = {}) {
+    if (!SID_RE.test(sid))
+        throw new Error('bad SID');
+    (deps.run ?? defaultRun)(system32('icacls.exe'), [p, '/inheritance:r', '/grant:r', `*${sid}:(F)`], process.env);
+}
+/** The file's security descriptor as SDDL. The path goes through the environment, never into the command text. */
+export function readSddl(p, deps = {}) {
+    const ps = system32('WindowsPowerShell', 'v1.0', 'powershell.exe');
+    return (deps.run ?? defaultRun)(ps, ['-NoProfile', '-NonInteractive', '-Command', '(Get-Acl -LiteralPath $env:DEXTERM_ACL_PATH).Sddl'], { ...process.env, DEXTERM_ACL_PATH: p }).replace(/\s+/g, ''); // SDDL has no whitespace: undo any console wrap
+}
+/**
+ * Is this DACL owner-only? Every ACE that grants anything must name `sid` (as S-1-… or its alias), SYSTEM or
+ * Administrators. A missing or
+ * null DACL (everyone has access) and any ACE kind this parser does not know (e.g. conditional) are refused.
+ */
+export function sddlOwnerOnly(sddl, sid) {
+    const m = /D:([A-Z_]*)((?:\([^()]*\))*)(?:S:|$)/.exec(sddl.trim());
+    if (!m)
+        return { ok: false, reason: 'no readable access list' };
+    if (/NO_ACCESS_CONTROL/.test(m[1]))
+        return { ok: false, reason: 'no access list (everyone has access)' };
+    const others = new Set();
+    const self = new Set([sid.toUpperCase(), ...selfAliases(sid)]);
+    for (const ace of m[2].match(/\(([^()]*)\)/g) ?? []) {
+        const [type, flags = '', , , , who = ''] = ace.slice(1, -1).split(';');
+        if (type === 'D' || type === 'OD')
+            continue; // deny entries only take access away
+        if (type !== 'A' && type !== 'OA')
+            return { ok: false, reason: `unsupported access entry ${type}` };
+        if ((flags.match(/../g) ?? []).some((f) => f === 'IO'))
+            continue; // inherit-only (2-letter flags): not the file itself
+        const w = who.toUpperCase();
+        if (!self.has(w) && !ALLOWED_WELL_KNOWN.has(w))
+            others.add(w);
+    }
+    return others.size ? { ok: false, reason: `other accounts can access it (${[...others].join(', ')})` } : { ok: true };
+}
+/** Check a file's ACL: owner-only or a reason. Never throws. */
+export function checkOwnerOnly(p, deps = {}) {
+    try {
+        return sddlOwnerOnly(readSddl(p, deps), currentUserSid(deps));
+    }
+    catch (e) {
+        return { ok: false, reason: `its Windows access list could not be checked (${e instanceof Error ? e.message.split(/\r?\n/)[0] : String(e)})` };
+    }
+}

package/dist/packages/cli/src/app-help-gen.js

@@ -247,7 +247,7 @@ const TOPICS = [
         body: '`dexterm autotrade run --all --paper` runs every strategy listed in ~/.dexterm/autotrade/autotrade.json at the same time on one data feed, to forward-test several ideas side by side. Each entry has an `id`, a `preset` (a shipped preset or your own strategy) or an absolute `file`, a `bankroll` in USD or SOL, optional `caps` that can only tighten it, and `enabled`. Each strategy gets its own paper book, run file, loss limits and breaker, sessions and model spend budget; a breaker or a stop on one never stops another. The screener fetches once for all of them, and the `global` limits (sessions open at once, model spend and sessions per day, one check of how busy the computer is) count across all of them. `dexterm autotrade status --all` and the runner view on the AUTOTRADE screen (`Q`) compare them: P/L, win rate with the closed count, rug exits and exposure, missed runners, spend per entry. `dexterm autotrade stop|flatten|pause|resume` act on every strategy; add `--strategy ID` to act on one, and `dexterm autotrade start ID` starts a listed one that is not running. An MCP agent can list and compare them and start or stop one listed strategy, never add one or change a size or a cap. Paper only: live is refused. Not financial advice. Full docs: https://dexterm.xyz/docs/autotrade/#several-strategies-at-once' },
     { id: 'autotrade-telegram', title: 'Your own Telegram bot for the autotrade runner: notify, control, one-tap approvals (dexterm telegram)', screen: 'all', tags: ['telegram', 'bot', 'phone', 'mobile', 'notify', 'notifications', 'approve', 'approval', 'approvals', 'pair', 'pairing', 'kill', 'pause', 'remote', 'botfather'],
         commands: ['telegram'], feature: 'autotrade-telegram',
-        body: 'Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/' },
+        body: 'Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. Read-only from chat: `/check <CA>` (one coin\'s LARP score and risk facts: authorities, top-10 holders, dev share, LP lock, liquidity, each with the age of its data), `/top [N]` (the screener\'s trending list, 1 to 10, the runner\'s own coins marked) and `/signals [N]` (the last 1 to 20 signals the runner raised: screen matches, safety refusals, the drain guard, stuck bags, halts, fills); data, not advice, and they cannot reach any write. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/' },
     { id: 'autotrade-real-signal', title: 'Real mode: send a strategy\'s trades to your own executor as LIVE TRADE FIRE signals (dexterm autotrade signal)', screen: 'all', tags: ['real', 'mode', 'live', 'trade', 'fire', 'signal', 'signals', 'executor', 'webhook', 'hook', 'jsonl', 'receipt', 'receipts', 'arm', 'caps', 'kill', 'outbox', 'nonce'],
         commands: ['autotrade'], tools: ['trade_fire_feed'], feature: 'autotrade-real-signal',
         body: 'Real mode runs a strategy exactly like paper (the same clamp, exits, monitor and run file) and sends every buy and sell it fills, first, as a LIVE TRADE FIRE signal (`dexterm-trade-fire/1`: buy or sell, mint, symbol, size in SOL and % of book, the sell fraction and exit reason, strategy, run, account, an always-growing nonce, an idempotency id and an expiry) to YOUR executor: a Telegram trading bot of your choice or any script. dexterm holds no key and signs nothing. Set channels with `dexterm autotrade signal channels --webhook URL | --signal-cmd \'["/abs/path"]\' | --jsonl on | --mcp on | --telegram on` (they live in connectors.json next to the Telegram setup; a bot cannot read another bot, so the Telegram copy alone is not enough), a webhook HMAC secret with `signal secret generate --out FILE`, hard caps with `signal caps set` (raising needs a typed confirmation), then arm on your own terminal with `dexterm autotrade signal arm <id>` (evidence panel + a typed phrase with a one-time code; any later edit disarms; below the evidence floor, a completed forward test with your `minForwardTrades` closed paper trades and a backtest of these exact rules, or past a missing rung of the ladder, it refuses unless you first type a separate OVERRIDE phrase, which is journaled) and run `dexterm autotrade run <id> --real` (live data only, in the foreground: in 0.2.0 the always-on service runs paper strategies only). Delivery is at least once from a restart-safe outbox, in nonce order, retried until acked or expired; the executor dedupes by nonce, ignores expired signals and acts only on its own account. Every run ends with a `halted` signal that lists the positions still open; the run\'s last lines and the Telegram copy name them too. Open positions are carried to the next real run of the same strategy and account, whose exits keep firing; while no real run is running NO signal goes out, sells included, so manage them in your executor. Positions stay unconfirmed until `dexterm autotrade receipt <nonce> executed|rejected|failed` (data only). `signal kill` stops every signal; `signal status`, `signal tail`, `receipt list` and `autotrade audit` show the outbox, receipts and drift; agents can read the MCP feed with trade_fire_feed. No model, tool or chat tap can arm real mode, raise a cap or lift the kill switch. Experimental; not financial advice.' },

package/dist/packages/cli/src/autotrade-cmd/fleet.js

@@ -25,7 +25,7 @@ import { appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { dextermHome } from '../../../custom/src/index.js';
 import { KillSwitch, createDataLayer, defaultDbPath, resolveRpcUrl } from '../../../data/src/index.js';
-import { DrainPoller, RugProbe, chainVets, defaultFetchJson, rugproofVet } from '../../../autotrade/src/index.js';
+import { DrainPoller, RugProbe, chainVets, defaultFetchJson, readOnlyCall, rugproofVet } from '../../../autotrade/src/index.js';
 import { FleetGuard, HEARTBEAT_MS, accountTable, LiveSource, RUNNER_RENDEZVOUS_SCHEMA, RUN_SUMMARY_SCHEMA, RunnerSafety, acquireRunLock, bankrollUsd, claudeSessionFactory, clearControl, clearMemberControls, clearStaleControl, compareRows, compareTable, controlPath, fileLedger, fleetStatusPath, fleetTotals, loadFleetConfig, loadRunnerConfig, loadTape, memberStrategy, newRunId, prepareAccount, releaseRunLock, renderDossierRecord, runFleet, runFiles, runnerRendezvousPath, runnerSystemPrompt, sharedDossier, stubSession, writeJsonAtomic, writeRendezvous, } from '../../../autotrade/src/index.js';
 import { parseArgs, resolveStrategyArg } from "./strategies.js";
 import { larpVet } from "./run.js";
@@ -122,7 +122,8 @@ export async function fleetRunCmd(argv, io, over = {}) {
         const rpc = resolveRpcUrl({ env: io.env });
         data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env), rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
     }
-    const closeData = () => { try {
+    const closeData = () => { if (data)
+        over.onReadTools?.(null); try {
         data?.close();
     }
     catch { /* closing */ } };
@@ -227,6 +228,7 @@ export async function fleetRunCmd(argv, io, over = {}) {
         // One dossier record per coin per 30 s, whichever strategy asks; each strategy renders its own text.
         const { McpTools } = await import('../../../mcp/src/index.js');
         const mcp = new McpTools(data, () => ({ screen: 'autotrade-runner', actions: { mints: [], feeds: [], sortKeys: [] } }));
+        over.onReadTools?.(readOnlyCall(mcp));
         const shared = sharedDossier(async (mint) => {
             try {
                 return await mcp.call('get_dossier', { mint, interval: '5m' });

package/dist/packages/cli/src/autotrade-cmd/run.js

@@ -29,7 +29,7 @@ import { join } from 'node:path';
 import { dextermHome, loadConfig } from '../../../custom/src/index.js';
 import { pickBasis } from '../../../data/src/basis.js';
 import { KillSwitch, createDataLayer, defaultDbPath, resolveRpcUrl } from '../../../data/src/index.js';
-import { DrainPoller, RugProbe, chainVets, defaultFetchJson, rugproofVet } from '../../../autotrade/src/index.js';
+import { DrainPoller, RugProbe, chainVets, defaultFetchJson, readOnlyCall, rugproofVet } from '../../../autotrade/src/index.js';
 import { HEARTBEAT_MS, LiveSource, badgeOf, RUNNER_RENDEZVOUS_SCHEMA, RunnerSafety, SessionGate, acquireRunLock, clearControl, clearStaleControl, controlPath, claudeSessionFactory, effectiveCaps, fileLedger, loadRunnerConfig, loadTape, newRunId, prepareAccount, releaseRunLock, renderDossierRecord, runAutotrade, runnerRendezvousPath, runnerSystemPrompt, simExecutor, stubSession, writeJsonAtomic, writeRendezvous, RUN_SUMMARY_SCHEMA, builtinTapePath, } from '../../../autotrade/src/index.js';
 import { assertAutotradeAllowed, ollamaSessionFactory } from '../../../autotrade/src/ollama-sessions.js';
 import { Outbox, RealSignalExecutor, channelsFromConfig, enabledChannels, loadSignalsConfig, openRealRun, realModeCheck } from '../../../autotrade/src/index.js';
@@ -313,13 +313,15 @@ export async function runCmd(argv, io, over = {}) {
     else {
         const rpc = resolveRpcUrl({ env: io.env });
         const data = createDataLayer({ dbPath: io.env.DEXTERM_DB_PATH || defaultDbPath(io.env), rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
-        closeData = () => data.close();
+        closeData = () => { host?.setReadTools(null); data.close(); };
         liveData = data.dexscreener;
         live = new LiveSource({ store: data.store, dexscreener: data.dexscreener }, { onLog: (l) => log('source_error', { error: l.slice(0, 300) }) });
         source = { name: 'live keyless data layer (Store + DexScreener tokens/v1 fast lane)', ticks: live.ticks(), startT: startedAt };
         // v1 dossier: the MCP get_dossier assembly (market, holders, security, candles, tape, creator) for the mint.
         const { McpTools } = await import('../../../mcp/src/index.js');
         const mcp = new McpTools(data, () => ({ screen: 'autotrade-runner', actions: { mints: [], feeds: [], sortKeys: [] } }));
+        // task-1426: the bot's /check and /top read the same tools (read tools only), while this run's data layer is open.
+        host?.setReadTools(readOnlyCall(mcp));
         dossier = async (k, h, matched, b) => {
             let rec;
             try {

package/dist/packages/cli/src/autotrade-cmd/service.js

@@ -470,6 +470,8 @@ async function runServiceCmd(argv, io, deps) {
     const over = {
         ...deps.fleetOver,
         extraSafety: () => ({ pauseEntries: lastGuard?.pauseEntries ?? null }),
+        // task-1426: the fleet's read tools for the bot's /check and /top (the service opens no data layer of its own).
+        onReadTools: (call) => { tg?.setReadTools(call); deps.fleetOver?.onReadTools?.(call); },
         vetWrap: takenVet,
         adopt: (id) => adopt.get(id),
         onStarted: (id, fl) => {
@@ -587,7 +589,7 @@ async function startTelegram(home, runId, say) {
     } };
     const svc = new TelegramService({ home, connector, port, knownToken: () => token, runId, state, strategy: () => null, alert: (l) => say(`! ${l}`) });
     await svc.start();
-    say('telegram: your bot is on (notifications, /status, /pause, /stop)');
+    say('telegram: your bot is on (notifications, /status, /pause, /stop, /check, /top, /signals)');
     return svc;
 }
 // ───────────────────────────── status / logs ─────────────────────────────

package/dist/packages/cli/src/autotrade-cmd/strategies.js

@@ -73,7 +73,7 @@ export function listCmd(argv, io) {
             io.stdout.write(`${head}  INVALID: ${(r.errors ?? []).slice(0, 2).map(fmtIssue).join('; ')}\n`);
             continue;
         }
-        io.stdout.write(`${head}  v${r.version.padEnd(7)} ${r.hash}  ${r.mode.padEnd(5)}  profiles ${r.profiles.join(',')}  · ${bt}${r.highRisk ? '  · ⚠ HIGH RISK' : ''}\n`);
+        io.stdout.write(`${head}  v${r.version.padEnd(7)} ${r.hash}  ${r.mode.padEnd(5)}  profiles ${r.profiles.join(',')}  · ${bt}${r.highRisk ? '  · ⚠ HIGH RISK' : ''}${r.experimentalTiers ? '  · EXPERIMENTAL tiers (unproven, paper only)' : ''}\n`);
     }
     if (rows.some((r) => r.shadowsPreset))
         io.stdout.write('  * your file shadows the shipped preset of the same id\n');

package/dist/packages/cli/src/autotrade-cmd/telegram-host.js

@@ -47,6 +47,8 @@ export class TelegramHost {
         if (solUsdFor)
             this.solUsdFor = solUsdFor;
     }
+    /** task-1426: the run's read tools for /check and /top (null when its data layer closes, or on a replay). */
+    setReadTools(call) { this.service.setReadTools(call); }
     onLedger = (e) => this.service.onLedger(e);
     onState = (st) => { this.state = st; this.service.onState(st); };
     /** The strategy a confirmed /use asked for, once (null when none). */

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

@@ -5,7 +5,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import { CATALOG, COIN_RISK, EXTERNAL_MODELS, PROVIDERS, PROVIDER_IDS, catalogEntry, classify, classifyBatch, coinDossier, describeHardware, describeResult, detectHardware, dextermHome, fits, freeBytes, fromReasonRunner, gb, isInstalled, loadClassifierConfig, modelPath, modelsDir, providerFromConfig, pullModel, readTypesafeKey, recommendTier, removeTypesafeKey, saveClassifierConfig, serveArgv, writeTypesafeKey, } from '../../classifier/src/index.js';
+import { CATALOG, COIN_RISK, EXTERNAL_MODELS, PROVIDERS, PROVIDER_IDS, catalogEntry, classify, classifyBatch, coinDossier, describeHardware, describeResult, detectHardware, dextermHome, fits, freeBytes, fromReasonRunner, gb, isInstalled, loadClassifierConfig, modelPath, modelsDir, providerFromConfig, pullModel, readTypesafeKey, recommendTier, removeTypesafeKey, saveClassifierConfig, serveArgv, typesafeKeyRefusal, typesafeKeyState, writeTypesafeKey, } from '../../classifier/src/index.js';
 import { spawnClaudeRunner } from '../../packs/src/index.js';
 export const CLASSIFIER_USAGE = `dexterm classifier [<command>]
   list                      providers, local models (installed / size / licence / fits this machine) and the current pick
@@ -15,7 +15,7 @@ export const CLASSIFIER_USAGE = `dexterm classifier [<command>]
   doctor [--json]           hardware (RAM, CPU, GPU/VRAM), the recommended tier, provider readiness
   bench [--n 20]            time the current provider on N synthetic coins (latency per coin, per 1,000)
   try                       classify one example coin with the current provider (shows the labelled estimate)
-  key set|clear|status      your own TypeSafe API key for hosted Jev (stored 0600 under ~/.dexterm/keys, never printed)
+  key set|clear|status      your own TypeSafe API key for hosted Jev (stored owner-only under ~/.dexterm/keys, never printed)
 Every answer is a model estimate with the model id and a calibration note; never advice. Docs: /docs/classifier/`;
 function flags(argv, bools) {
     const pos = [];
@@ -34,6 +34,7 @@ function flags(argv, bools) {
     }
     return { pos, opts };
 }
+const keyLine = (s) => s.source === 'refused' ? 'refused (dexterm classifier key status says why; TYPESAFE_API_KEY works instead)' : s.source === 'none' ? 'none (hosted Jev is optional)' : 'configured';
 async function ask(io, question) {
     if (!io.stdin.isTTY)
         return '';
@@ -178,7 +179,7 @@ export async function classifierCommand(argv, io) {
             if (!isInstalled(home, catalogEntry(model)))
                 out(`note: ${model} is not downloaded yet: dexterm classifier pull ${model}. Until it is served, answers fall back to the heuristic.`);
         }
-        if (id === 'jev-hosted' && !readTypesafeKey(io.env))
+        if (id === 'jev-hosted' && !readTypesafeKey(io.env, { platform: io.platform, acl: io.acl }))
             out('note: no TypeSafe key yet: dexterm classifier key set. Until then answers fall back to the heuristic.');
         const p = saveClassifierConfig(next, io.env);
         out(`classifier.provider = ${id}${id === 'kev-local' ? ` (${next.kev.model})` : ''}  (${p})`);
@@ -274,13 +275,13 @@ export async function classifierCommand(argv, io) {
         const llama = llamaServerBin(io.env);
         const llamaOk = llama ? await llamaSupportsDecisions(llama, io.exec) : false;
         if (opts.json === true) {
-            out(JSON.stringify({ hardware: hw, recommendation: rec, provider: c.provider, model: c.provider === 'kev-local' ? c.kev.model : null, ready: provStatus.ready, detail: provStatus.detail, llamaServer: Boolean(llama), llamaServerDecisions: llamaOk, typesafeKey: Boolean(readTypesafeKey(io.env)) }, null, 2));
+            out(JSON.stringify({ hardware: hw, recommendation: rec, provider: c.provider, model: c.provider === 'kev-local' ? c.kev.model : null, ready: provStatus.ready, detail: provStatus.detail, llamaServer: Boolean(llama), llamaServerDecisions: llamaOk, typesafeKey: Boolean(readTypesafeKey(io.env, { platform: io.platform, acl: io.acl })) }, null, 2));
             return 0;
         }
         out(`hardware: ${describeHardware(hw)}`);
         out(`recommended: ${rec.model ?? 'the built-in heuristic'}${rec.bestQuality ? ` (best quality here: ${rec.bestQuality})` : ''}: ${rec.why}`);
         out(`provider: ${c.provider}${c.provider === 'kev-local' ? ` (${c.kev.model})` : ''}: ${provStatus.ready ? 'ready' : 'not ready'}: ${provStatus.detail}`);
-        out(`llama-server: ${!llama ? 'not found (needed for kev-local)' : llamaOk ? 'found, serves decision models' : `found but too old: ${LLAMA_TOO_OLD}`} · TypeSafe key: ${readTypesafeKey(io.env) ? 'configured' : 'none (hosted Jev is optional)'}`);
+        out(`llama-server: ${!llama ? 'not found (needed for kev-local)' : llamaOk ? 'found, serves decision models' : `found but too old: ${LLAMA_TOO_OLD}`} · TypeSafe key: ${keyLine(typesafeKeyState(io.env, { platform: io.platform, acl: io.acl, fresh: true }))}`);
         if (c.fallback)
             out('fallback: the heuristic answers when the provider is unreachable (labelled as a fallback)');
         return 0;
@@ -307,8 +308,15 @@ export async function classifierCommand(argv, io) {
     }
     if (sub === 'key') {
         const action = pos[0] ?? 'status';
+        const keyOpts = { platform: io.platform, acl: io.acl };
         if (action === 'status') {
-            out(readTypesafeKey(io.env) ? 'TypeSafe key: configured (not shown)' : 'TypeSafe key: none');
+            const s = typesafeKeyState(io.env, { ...keyOpts, fresh: true });
+            if (s.source === 'refused') {
+                out('TypeSafe key: refused');
+                err(typesafeKeyRefusal(s));
+                return 1;
+            }
+            out(s.source === 'env' ? 'TypeSafe key: configured from TYPESAFE_API_KEY (not shown)' : s.source === 'file' ? 'TypeSafe key: configured (not shown)' : 'TypeSafe key: none');
             return 0;
         }
         if (action === 'clear') {
@@ -322,8 +330,8 @@ export async function classifierCommand(argv, io) {
                 return 1;
             }
             try {
-                const p = writeTypesafeKey(k, io.env);
-                out(`saved to ${p} (0600). It is only sent to ${c.jev.endpoint}.`);
+                const p = writeTypesafeKey(k, io.env, keyOpts);
+                out(`saved to ${p} (${(io.platform ?? process.platform) === 'win32' ? 'owner-only Windows access list' : '0600'}). It is only sent to ${c.jev.endpoint}.`);
                 return 0;
             }
             catch (x) {

package/dist/packages/cli/src/skill-eval-build.js

@@ -11,7 +11,7 @@
 // symbol is written (the name and symbol are read only to compute the domain-match boolean).
 import { linkFeatures } from '../../data/src/index.js';
 import { LABELER_VERSION } from '../../recorder/src/index.js';
-import { SKILL_EVAL_SCHEMA } from '../../packs/src/index.js';
+import { SKILL_EVAL_SCHEMA, cutoffIso } from '../../packs/src/index.js';
 function readCache(db, ns, mint) {
     const row = db.prepare('SELECT json, fetched_at FROM cache WHERE ns = ? AND key = ?').get(ns, mint);
     if (!row)
@@ -47,6 +47,11 @@ export function buildSkillEvalSet(db, opts = {}) {
         let picked = null;
         for (const o of outs) {
             const t0 = Number(o.t0);
+            // A t0 that is not a valid time can never anchor point-in-time evidence (and would poison the split). task-1982
+            if (Number.isNaN(new Date(t0).getTime())) {
+                excluded.bad_t0 = (excluded.bad_t0 ?? 0) + 1;
+                continue;
+            }
             const srcs = [['jupiter', jup], ['dexscreener', ds]]
                 .filter((x) => !!x[1] && x[1].fetched_at >= t0 && x[1].fetched_at <= t0 + lagMs);
             if (srcs.length) {
@@ -101,7 +106,7 @@ export function buildSkillEvalSet(db, opts = {}) {
         horizon_sec: horizon,
         label_rule: `recorder outcome at ${horizon}s (keyless proxy, labeler ${LABELER_VERSION}); bad = rug ∪ dead, ok = flat ∪ fade ∪ runner; unobserved dropped`,
         evidence_rule: `link features from the cached DexScreener/Jupiter token record only when it was fetched within ${lagMs / 1000}s after the row's t0 (latest such t0 per coin); rug-check features from that t0 snapshot`,
-        split_rule: `by time: the latest ${Math.round(testFrac * 100)}% of rows by t0 (t0 ≥ ${new Date(cutoff).toISOString()}) are the held-out TEST split, fixed before tuning`,
+        split_rule: `by time: the latest ${Math.round(testFrac * 100)}% of rows by t0 (t0 ≥ ${cutoffIso(cutoff)}) are the held-out TEST split, fixed before tuning`,
         cutoff_t0: cutoff,
         counts: { rows: rows.length, train: train.length, test: test.length, bad_train: train.filter((r) => r.bad).length, bad_test: test.filter((r) => r.bad).length, excluded },
         rows,

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

@@ -1,3 +1,3 @@
 // The one place the app's version lives (task-1397). --version, the help banner and `dexterm update` read it;
 // cli.test.ts keeps it equal to packages/cli/package.json (release.yml refuses a tag that differs).
-export const VERSION = '0.2.1';
+export const VERSION = '0.2.2';

package/dist/packages/mcp/assets/kb/app-help/autotrade-telegram.md

@@ -35,6 +35,6 @@ sources:
 date: 2026-10-16
 ---
 
-Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/
+Create a bot with @BotFather, then run `dexterm telegram setup`: paste the token at the hidden prompt (never as an argument), dexterm checks it and keeps it in your keychain (or the system keyring, or a 0600 file), then shows a 6-digit code; send `/pair <code>` to your bot from your own private chat and confirm the account it shows (@username and id) with `y` on your computer. Pairing is refused while a webhook or another program polls the bot. Only that account in that chat is answered. `dexterm autotrade run <id> --paper` then starts the bot by itself (`--no-telegram` keeps it off): entries, exits, PnL cards, halts and a daily summary reach your phone; `/status`, `/positions`, `/pause`, `/resume` (a pause only), `/kill`, `/flatten` and `/use` (each after a confirm button, `/use` only to an equal-or-tighter strategy; a change it cannot rank counts as looser) and `/approvals on` work from chat, which can make things safer and never less safe. Read-only from chat: `/check <CA>` (one coin's LARP score and risk facts: authorities, top-10 holders, dev share, LP lock, liquidity, each with the age of its data), `/top [N]` (the screener's trending list, 1 to 10, the runner's own coins marked) and `/signals [N]` (the last 1 to 20 signals the runner raised: screen matches, safety refusals, the drain guard, stuck bags, halts, fills); data, not advice, and they cannot reach any write. With `entry.decide: "agent+approve"` or approvals on, every entry is a card with [Approve] [Half size] [Skip]: only a button approves, once, for that proposal, your account and your private chat; the price and your limits are checked again at the tap; no answer is a skip. Typed messages are never trades. `dexterm telegram status|test|audit --verify|revoke`. Nothing is hosted; paper only; never send keys or seed phrases in chat. Not financial advice. Full docs: https://dexterm.xyz/docs/telegram/
 
 CLI: `dexterm telegram`.

package/dist/packages/mcp/assets/kb/docs/docs-autotrade-confidence-tiers-experimental-unproven-paper-only.md

@@ -0,0 +1,56 @@
+---
+id: docs-autotrade-confidence-tiers-experimental-unproven-paper-only
+title: Autotrade (paper) › Confidence tiers (experimental, unproven, paper only)
+kind: docs
+page: autotrade
+page_title: Autotrade (paper)
+heading: Confidence tiers (experimental, unproven, paper only)
+anchor: confidence-tiers-experimental-unproven-paper-only
+url: https://dexterm.xyz/docs/autotrade#confidence-tiers-experimental-unproven-paper-only
+tags:
+  - docs
+  - autotrade
+  - confidence
+  - tiers
+  - experimental
+  - unproven
+  - paper
+  - only
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/autotrade.md
+date: 2026-10-16
+---
+
+**Unproven.** On our held-out data no tier made money, and our November research found no dexterm strategy with a proven edge. This is a way to test a sizing rule on paper; it is not a signal and not a reason to trade real money. Off unless a strategy turns it on, and refused outside paper.
+
+Turn it on per strategy with `sizing.tiers` (paper mode, and the rug-proof block (https://dexterm.xyz/docs/autotrade#rug-proof-entries-experimental) with `minPoolAgeMin` 10 or more):
+
+```json
+"sizing": { "tiers": { "table": "v4-1785", "experimental": "paper-only" } }
+```
+
+The engine, not the agent, then scores every candidate on two figures from that coin's own tick:
+
+- **turnover1h** = 1 h volume / liquidity, a point at **9.878 or less**;
+- **bs5m** = buys / sells over 5 minutes, a point at **3.714 or more**.
+
+Score 0 is **T0, a skip**: no entry. Score 1 is T3, score 2 is T4. **No tier runs above 25% of the book**: the table configures T3 at 75% and T4 at 100%, and both run at 25%. The cap is in the engine's code; no strategy field, table entry or agent answer lifts it, and it also holds across the scale-in tranches of a tiered position. After that every limit you set still applies and the stricter one wins (`maxPctOfBankroll`, `maxUsd`, the profile's max, per-trade loss, exposure, cash, price impact, the drawdown size-down, the rug-proof young-pool cap). The agent can ask for less, never more, and its confidence does not change the tier. One open position at a time unless you add `"oneOpen": false`; an entry still waiting for its fill (the execution latency) or for your approval counts as open, for this and for `maxConcurrent`, and its dollars count against your exposure and cash.
+
+A tier also needs, or it is T0: liquidity of $30,000 or more, a token at least 10 minutes old, not young (under 2 h) and vertical (1 h change of 150% or more), a 1 h change at all for a young coin, and a live tick no older than 5 minutes at the moment of the decision. A missing, negative or non-numeric figure never scores a point.
+
+Paper only, three times over: `dexterm autotrade validate` refuses the block in mode `real` or `live`, the runner refuses it in a real-signal run, and the engine refuses it outside paper.
+
+Where you see it: `dexterm autotrade validate <id>` prints the verdict and every tier with its held-out numbers, `dexterm autotrade list` marks the strategy `EXPERIMENTAL tiers (unproven, paper only)`, every candidate writes a `TIER` line in the run log with its score, size and the verdict, and the ledger's clamp event records the tier.
+
+The table's held-out numbers (frozen before the held-out set was scored once, per entry, 95% interval):
+
+| tier | when | runs at | held-out |
+|---|---|---|---|
+| T0 | score 0 or a failed gate | skip | 19 entries, mean -17.0% (-35.7% … +3.4%) |
+| T3 | score 1 | 25% | 17 entries, mean -7.6% (-31.8% … +16.8%) |
+| T4 | score 2 | 25% | no entries (too few to say anything) |

package/dist/packages/mcp/assets/kb/docs/docs-classifier-hosted-jev-with-your-own-key.md

@@ -27,8 +27,10 @@ date: 2026-10-16
 ---
 
 ```
-dexterm classifier key set          paste your TypeSafe API key (hidden input; stored 0600 under ~/.dexterm/keys)
+dexterm classifier key set          paste your TypeSafe API key (hidden input; stored owner-only under ~/.dexterm/keys)
 dexterm classifier pick jev-hosted
 ```
 
 dexterm never ships or shares a key. The key is sent only to `https://api.typesafe.ai`, never printed, and never stored in `classifier.json`. `TYPESAFE_API_KEY` in the environment works too. Each call counts tokens. Set your price per million input tokens in `~/.dexterm/classifier.json` (`jev.pricePerMTokUsd`) to see a cost in dollars; until you do, the cost shows as *unpriced*, never as $0. A daily call cap (`jev.maxCallsPerDay`, default 1,000) stops calls before they reach the network. A rate limit from the API is reported with its retry time.
+
+The key file must be readable by your account only: on macOS and Linux it is saved with mode 0600, and a file other users can read is refused. On Windows (not supported, see Windows expectations (https://dexterm.xyz/docs/beginners#windows-expectations)) file modes mean nothing, so `key set` locks the file to your Windows account with `icacls` and every read checks its access list; a file other accounts can read, or one whose access list cannot be checked, is refused. `dexterm classifier key status` says why a file is refused. If `icacls` or PowerShell is blocked on your machine, set `TYPESAFE_API_KEY` in your environment instead.

package/dist/packages/mcp/assets/kb/docs/docs-getting-started-install.md

@@ -41,10 +41,10 @@ $ dexterm doctor
 The package is named `dexterm-cli` because npm refuses the name `dexterm` as too similar to `xterm`. The command it installs is `dexterm`. The package ships compiled JavaScript, so it needs no build step. Every GitHub release carries a build-provenance attestation and `SHA256SUMS` you can verify (see the trust page (https://dexterm.xyz/trust/)).
 
 ```sh install from the release
-$ # download dexterm-0.2.1-src.tar.gz and SHA256SUMS from the releases page, then:
+$ # download dexterm-0.2.2-src.tar.gz and SHA256SUMS from the releases page, then:
 $ shasum -a 256 -c SHA256SUMS --ignore-missing
-$ gh attestation verify dexterm-0.2.1-src.tar.gz --repo dexterm-xyz/dexterm
-$ tar -xzf dexterm-0.2.1-src.tar.gz && cd dexterm-0.2.1
+$ gh attestation verify dexterm-0.2.2-src.tar.gz --repo dexterm-xyz/dexterm
+$ tar -xzf dexterm-0.2.2-src.tar.gz && cd dexterm-0.2.2
 $ ./install.sh
 $ dexterm doctor
 ```

package/dist/packages/mcp/assets/kb/docs/docs-getting-started-requirements.md

@@ -32,4 +32,4 @@ date: 2026-10-16
 | optional: a free RPC key | the ranked top-20 holder list and faster chain reads | Helius, Alchemy, QuickNode or Ankr free tier; see configuration (https://dexterm.xyz/docs/configuration). |
 | optional: Rust (`cargo`) | the native docked chart window | without it the chart popup opens in your browser; see popup chart (https://dexterm.xyz/docs/popup-chart). |
 
-> note: dexterm 0.2.1 is out (2026-10-30), open source under AGPL-3.0-only at github.com/dexterm-xyz/dexterm (https://github.com/dexterm-xyz/dexterm). It is early: trading is experimental and has known bugs. The release ships checksums, a build-provenance attestation and an SBOM, and its VirusTotal result (including flags we explain) is on the trust page (https://dexterm.xyz/trust/). It is also on npm as `dexterm-cli` (https://www.npmjs.com/package/dexterm-cli); the command it installs is still `dexterm`.
+> note: dexterm 0.2.2 is out (2026-11-05), open source under AGPL-3.0-only at github.com/dexterm-xyz/dexterm (https://github.com/dexterm-xyz/dexterm). It is early: trading is experimental and has known bugs. The release ships checksums, a build-provenance attestation and an SBOM, and its VirusTotal result (including flags we explain) is on the trust page (https://dexterm.xyz/trust/). It is also on npm as `dexterm-cli` (https://www.npmjs.com/package/dexterm-cli); the command it installs is still `dexterm`.

package/dist/packages/mcp/assets/kb/docs/docs-narratives-where-to-find-it.md

@@ -30,7 +30,7 @@ date: 2026-10-16
   `ZORP · lifecycle: ignition · rank 3 · #2 of 9`.
 - `dexterm narratives` prints the heat table. `dexterm narratives detail ID` shows one narrative, `dexterm narratives of
   MINT` shows the narrative of one coin, and `dexterm narratives export --out FILE` writes the JSON
-  (`dexterm-narratives/1`) that a strategy tracker page reads. `--at ISO` replays up to a past time.
+  (`dexterm-narratives/1`) for your own tools. `--at ISO` replays up to a past time.
 - MCP tools for your analyst or your own agent: `narratives_top`, `narrative_detail`, `narrative_of` (observe tier,
   read-only). Coin names come back wrapped as untrusted data.
 - Watch rules: the field `narrative_rank` and the tags `narrative:ignition` / `narrative:saturated`, so a rule can fire