dexterm-cli 0.1.1 → 0.1.3

package/dist/packages/agents/src/spectator.js

@@ -0,0 +1,212 @@
+// @dexterm/agents — the spectator event model, redaction, hub and save/replay (task-1406, "watch the
+// agent cook"). One normalized record per observable agent action is emitted by the tool-call path (the
+// bus's onCall, and the MCP tools/call path via a file sink) into a SpectatorHub. The hub keeps the raw
+// events in a ring buffer and fans them out; each consumer redacts for its audience:
+//   * follow mode (local, the owner's own terminal) sees the RAW events;
+//   * the spectator STREAM and the SAVED file redact wallet addresses, keys and sensitive-named fields.
+// Nothing here can arm, sign, confirm or raise a cap — a spectator event only describes a call the gate
+// already allowed; there is no control surface in this module (see spectator-server.ts: read-only).
+import { appendFileSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const SPECTATOR_PROTOCOL = 'dexterm-spectator/1';
+export const SPECTATOR_SCHEMA = 1;
+// ---------------------------------------------------------------------------------------------------
+// Redaction. Addresses are truncated (still watchable); keys are removed entirely; sensitive-named
+// fields are blanked. A full wallet address never appears verbatim in a redacted string.
+/** base58 alphabet (Bitcoin / Solana): no 0 O I l. */
+const BASE58 = '[1-9A-HJ-NP-Za-km-z]';
+/** A base58 run of 32–44 chars is a Solana pubkey (wallet or mint); ≥45 is key material. */
+const ADDR_RE = new RegExp(`${BASE58}{32,44}`, 'g');
+const LONG_B58_RE = new RegExp(`${BASE58}{45,}`, 'g');
+/** A hex run of ≥64 chars is a 32-byte key / signature. */
+const HEX_KEY_RE = /\b[0-9a-fA-F]{64,}\b/g;
+export const SENSITIVE_KEY_RE = /(secret|private|privkey|mnemonic|seed|passphrase|password|signature|sig|apikey|api[_-]?key|keypair|token)/i;
+/** Mask one address the way the product's shortAddr does (head4…tail4). */
+export function maskAddress(s) {
+    return s.length <= 10 ? s : `${s.slice(0, 4)}…${s.slice(-4)}`;
+}
+/** Redact every address / key in a string. Keys (long runs) first so a 45-char run is not truncated as a 44. */
+export function redactString(s) {
+    return s
+        .replace(LONG_B58_RE, '[key]')
+        .replace(HEX_KEY_RE, '[key]')
+        .replace(ADDR_RE, (m) => maskAddress(m));
+}
+/** Deep-redact a JSON value: sensitive-named keys → "[redacted]", strings scrubbed of addresses/keys. */
+export function redactDeep(value, depth = 0) {
+    if (depth > 8)
+        return value;
+    if (typeof value === 'string')
+        return redactString(value);
+    if (Array.isArray(value))
+        return value.map((v) => redactDeep(v, depth + 1));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SENSITIVE_KEY_RE.test(k) ? '[redacted]' : redactDeep(v, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+/** A redacted COPY of an event, safe for a shared stream or a saved file. The original is never mutated.
+ *  EVERY string field is scrubbed — not just the summary — because the producer (bus.ts onCall) copies
+ *  the agent-supplied tool name straight into `tool`/`refusal` on a refused call, so an untrusted agent
+ *  can put a wallet address or key there; `agent` and the nav strings are redacted too so no path can
+ *  leak a full address / key verbatim into a shared stream or a saved file. */
+export function redactSpectatorEvent(ev) {
+    const out = { ...ev, redacted: true };
+    if (ev.sensitive) {
+        out.summary = '[sensitive]';
+    }
+    else if (typeof ev.summary === 'string') {
+        out.summary = redactString(ev.summary);
+    }
+    // Scrub the remaining string fields. Addresses are masked (still watchable), key material → "[key]".
+    if (typeof ev.tool === 'string')
+        out.tool = redactString(ev.tool);
+    if (typeof ev.refusal === 'string')
+        out.refusal = redactString(ev.refusal);
+    if (typeof ev.agent === 'string')
+        out.agent = redactString(ev.agent);
+    if (ev.nav) {
+        out.nav = { ...ev.nav };
+        if (out.nav.screen)
+            out.nav.screen = redactString(out.nav.screen);
+        if (out.nav.mint)
+            out.nav.mint = maskAddress(out.nav.mint);
+        if (out.nav.feed)
+            out.nav.feed = redactString(out.nav.feed);
+        if (out.nav.filter)
+            out.nav.filter = redactString(out.nav.filter);
+        if (out.nav.highlight)
+            out.nav.highlight = maskAddress(out.nav.highlight);
+        if (out.nav.side)
+            out.nav.side = redactString(out.nav.side);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------------------------------
+// Freshness: the oldest/largest `ageSec` anywhere in a tool result, so the activity panel can show a
+// "data age" like the terminal does. Deterministic, bounded depth; returns null when nothing is dated.
+export function maxDataAgeSec(result, depth = 0) {
+    if (depth > 6 || !result || typeof result !== 'object')
+        return null;
+    let max = null;
+    const take = (n) => { if (typeof n === 'number' && Number.isFinite(n) && n >= 0)
+        max = max === null ? n : Math.max(max, n); };
+    for (const [k, v] of Object.entries(result)) {
+        if (k === 'ageSec')
+            take(v);
+        else {
+            const inner = maxDataAgeSec(v, depth + 1);
+            if (inner !== null)
+                take(inner);
+        }
+    }
+    return max;
+}
+export class SpectatorHub {
+    listeners = new Set();
+    ring = [];
+    now;
+    cap;
+    seq = 0;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        this.cap = Math.max(1, opts.cap ?? 500);
+    }
+    /** Emit one event. Assigns v/seq/t and defaults ok:true. Returns the stored (raw) event. */
+    emit(input) {
+        const ev = { v: SPECTATOR_SCHEMA, seq: ++this.seq, t: input.t ?? this.now(), ok: input.ok ?? true, ...stripUndef(input) };
+        ev.v = SPECTATOR_SCHEMA;
+        ev.seq = this.seq; // keep after spread in case input carried stray keys
+        this.ring.push(ev);
+        if (this.ring.length > this.cap)
+            this.ring.splice(0, this.ring.length - this.cap);
+        for (const l of this.listeners) {
+            try {
+                l(ev);
+            }
+            catch { /* one bad listener never stops the fan-out */ }
+        }
+        return ev;
+    }
+    /** Subscribe; returns an unsubscribe fn. */
+    on(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+    /** The most recent events, oldest-first (for replay-on-connect / the activity panel). */
+    recent(limit = this.cap) { return this.ring.slice(Math.max(0, this.ring.length - limit)); }
+    clear() { this.ring.length = 0; }
+    get size() { return this.ring.length; }
+}
+function stripUndef(o) {
+    const out = {};
+    for (const [k, v] of Object.entries(o))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Attach to a hub and append each event to a sink (default: a file, 0600). Redacts unless redact:false. */
+export class SpectatorRecorder {
+    off = null;
+    redact;
+    write;
+    count = 0;
+    constructor(opts) {
+        this.redact = opts.redact ?? true;
+        const now = opts.now ?? (() => Date.now());
+        if (opts.write) {
+            this.write = opts.write;
+        }
+        else if (opts.path) {
+            const p = opts.path;
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, '', { mode: 0o600 });
+            this.write = (line) => appendFileSync(p, line + '\n', { mode: 0o600 });
+        }
+        else {
+            throw new Error('SpectatorRecorder needs a path or a write sink');
+        }
+        const meta = { protocol: SPECTATOR_PROTOCOL, schema: SPECTATOR_SCHEMA, savedAt: now(), redacted: this.redact, note: opts.note };
+        this.write(JSON.stringify({ meta }));
+    }
+    /** Record one event (redacting a copy when redact is on). */
+    record(ev) { this.write(JSON.stringify(this.redact ? redactSpectatorEvent(ev) : ev)); this.count++; }
+    /** Start recording every event a hub emits from now on. */
+    attach(hub) { this.off = hub.on((ev) => this.record(ev)); return this; }
+    stop() { this.off?.(); this.off = null; return this.count; }
+    get written() { return this.count; }
+}
+/** Parse a JSONL recording (header line + events). Tolerant: bad lines are skipped. */
+export function parseSpectatorRecording(text) {
+    const lines = text.split('\n').map((l) => l.trim()).filter(Boolean);
+    let meta = null;
+    const events = [];
+    for (const line of lines) {
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!meta && obj.meta && typeof obj.meta === 'object') {
+            meta = obj.meta;
+            continue;
+        }
+        if (typeof obj.seq === 'number' && typeof obj.phase === 'string')
+            events.push(obj);
+    }
+    events.sort((a, b) => a.seq - b.seq);
+    return { meta: meta ?? { protocol: SPECTATOR_PROTOCOL, schema: SPECTATOR_SCHEMA, savedAt: 0, redacted: false }, events };
+}
+/** Load a recording from a file. */
+export function loadSpectatorRecording(path) {
+    return parseSpectatorRecording(readFileSync(path, 'utf8'));
+}
+/** Replay a recording's events into a handler (a FollowController.apply, a hub.emit, or a sink), in order. */
+export function replaySpectator(recording, handle) {
+    for (const ev of recording.events)
+        handle(ev);
+    return recording.events.length;
+}

package/dist/packages/agents/src/tiers.js

@@ -42,6 +42,11 @@ export const TOOL_TIERS = Object.freeze({
     get_candles: 'observe',
     rugcheck: 'observe',
     get_dev_history: 'observe',
+    // deterministic analysis packs (task-1356): read-only, no model, no token cost. Exposed to external
+    // agents in task-1405 so a bring-your-own-agent gets the same code-stage analysis the built-in analyst does.
+    analyze_token: 'observe',
+    narrative_board: 'observe',
+    rug_backtest: 'observe',
     kb_lookup: 'observe',
     kb_search: 'observe',
     case_lookup: 'observe',

package/dist/packages/agents/src/tools.js

@@ -26,6 +26,9 @@ const TOOLS_DEF = [
     { name: 'get_candles', tier: 'observe', description: 'Candles plus computed summaries (range, drawdown, VWAP, change%).', inputSchema: { type: 'object', properties: { mint: MINT, interval: { type: 'string', enum: ['1m', '5m', '15m', '1h', '4h', '1d'] }, limit: { type: 'integer', minimum: 1, maximum: 300 } }, required: ['mint'], additionalProperties: false } },
     { name: 'rugcheck', tier: 'observe', description: 'RugCheck-style summary: risks[] (firewalled), normalised score, lpLockedPct, tokenProgram.', inputSchema: { type: 'object', properties: { mint: MINT }, required: ['mint'], additionalProperties: false } },
     { name: 'get_dev_history', tier: 'observe', description: 'Creator address and prior-launch forensics. Tier-1 fields need a key and are null on the keyless tier.', inputSchema: { type: 'object', properties: { mint: MINT }, required: ['mint'], additionalProperties: false } },
+    { name: 'analyze_token', tier: 'observe', description: 'Deterministic token-dossier analysis pack: numeric features, named rule flags, a WATCH/SPECULATIVE/AVOID verdict, a p(rug) heuristic and data ages. No model, no token cost; a reasoning stage may only tighten the verdict, never loosen it.', inputSchema: { type: 'object', properties: { mint: MINT, symbol: SYMBOL, interval: { type: 'string', enum: ['1m', '5m', '15m', '1h', '4h', '1d'] } }, additionalProperties: false } },
+    { name: 'narrative_board', tier: 'observe', description: 'The narrative board over recorded + trending tokens: per-narrative volume, new launches, runners and a "what is working" score. No model; returns a note when there is no recorded history yet.', inputSchema: { type: 'object', properties: { window: { type: 'string', enum: ['1h', '24h'] }, limit: { type: 'integer', minimum: 1, maximum: 50 }, summary: { type: 'boolean' } }, additionalProperties: false } },
+    { name: 'rug_backtest', tier: 'observe', description: 'Backtest the rug model or recorded pack verdicts against RECORDED outcomes: honest precision/recall, Brier, AUC and calibration. Leakage-free by construction; returns a note when there is not enough history. Read-only.', inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['heuristic', 'pack_verdicts'] }, horizon_sec: { type: 'integer', enum: [3600, 7200, 21600, 86400, 259200] }, positive_labels: { type: 'array', items: { type: 'string', enum: ['rug', 'dead', 'fade', 'flat', 'runner'] }, maxItems: 5 } }, additionalProperties: false } },
     { name: 'kb_lookup', tier: 'observe', description: 'One knowledge-base entry by id (mechanics / patterns / glossary). KB never holds facts about a live token.', inputSchema: { type: 'object', properties: { id: { type: 'string', maxLength: 64 } }, required: ['id'], additionalProperties: false } },
     { name: 'kb_search', tier: 'observe', description: 'Search the knowledge base; returns ids, titles and an excerpt.', inputSchema: { type: 'object', properties: { query: { type: 'string', maxLength: 200 }, limit: { type: 'integer', minimum: 1, maximum: 10 } }, required: ['query'], additionalProperties: false } },
     { name: 'case_lookup', tier: 'observe', description: 'Historical case files (verified on-chain references + outcome). By id, or list all with no id.', inputSchema: { type: 'object', properties: { id: { type: 'string', maxLength: 64 } }, additionalProperties: false } },

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

@@ -51,9 +51,14 @@ Write long form (short sections or bullets, a table if it helps, at most ~25 lin
 - When levels or risks come from young or missing data, lower conf rather than inventing precision.
 - A symbol can mean several tokens. Use the SELECTED/HOVERED coin from the CONTEXT block for "this coin" / "it" / "the highlighted one" without asking. Only ask the user to choose when the question genuinely names an ambiguous symbol and nothing in context resolves it.
 
+## Helping the user use the app ("how do I …")
+- For ANY question about how dexterm itself works — "how do I X", "what key does Y", "what does this screen show", "where is Z" — call `app_help` FIRST (it searches a knowledge base generated from the app's own keymap, help overlay, MCP tools and CLI). Answer with the EXACT key or command from the result (its `keys`, `commands`, `flags` fields). Never invent or guess a key, flag or command. If nothing matches, say plainly "I don't see that in the app" rather than making one up.
+- Call `app_state` (read-only) to fit the answer to what the user currently sees: the screen, selected coin, theme, price mode, voice, whether scan/calm are on, and which alert channels are configured (yes/no). It never exposes any secret.
+
 ## You cannot trade, only analyse and navigate
 - You cannot sign, send, or confirm a transaction. Trading in dexterm is PAPER only and every ticket needs the user's own confirmation. If asked to buy/sell, open the PAPER ticket with `open_ticket` (pre-filled, side set) and tell the user in a few words to confirm it themselves. Never claim you executed a trade.
-- You may drive non-financial navigation with the UI-action tools to help the user see what you mean: `open_token` (put a coin on their screen), `show_in_screener` (filter/sort/highlight), `add_to_watchlist`, `switch_feed`, `open_ticket` (opens, never confirms). These act only on tokens already on screen (see the CONTEXT block) and the app shows "analyst did X".
+- You may drive non-financial navigation with the UI-action tools to help the user see what you mean: `open_token` (put a coin on their screen), `show_in_screener` (filter/sort/highlight/preset), `add_to_watchlist`, `switch_feed`, `switch_screen`, `switch_workspace`, `chart_popup`, `toggle_calm`, `set_scan`, `export_view`, `open_ticket` (opens, never confirms). These apply immediately and the app shows "analyst did X"; they act only on screens/tokens/presets already available (see the CONTEXT block).
+- A few settings are PERSISTED and need the user's go-ahead: `set_theme`, `set_price_mode`, `set_intensity` do NOT change anything by themselves — they put a one-line proposal on screen that the user accepts with a keypress (and `ctrl+z` undoes). Nothing you can call touches wallets, keys, credentials, alert channels, signing, caps, mandates, network/RPC settings, the VOICE speed or name (only the keyboard — `<`/`>` and the voice picker — sets that), or installing/updating software; those are not actions you have.
 
 ## Plain-language filtering (turn a request into a screener filter)
 When the user describes the coins they want in words ("show me coins under 5M mcap with over 100k liquidity that are up on the day and not rugs"), translate it into dexterm's screener filter grammar and apply it with `show_in_screener` (the `filter` field). The app re-parses your string with the real grammar and rejects anything malformed, so use ONLY the fields and syntax below — never invent a field name.

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

@@ -1,7 +1,7 @@
 ---
 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.1.0
+version: 0.2.0
 argument-hint: <mint or symbol>
 kind: skill
 output_schema: schemas/larp.schema.json
@@ -30,7 +30,7 @@ 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`.
+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`.
    - 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.
@@ -45,6 +45,14 @@ Do not call X/Twitter or Telegram through `fetch_page` expecting profile data: t
 - **LARP signals:** a near-empty or default/parked/site-builder placeholder page; the site never mentions the token symbol or name; broken/unreachable advertised links; a domain registered the same day as the token behind privacy; a GitHub that is empty, archived, a fork, or has no commits since launch; claims of an app with no reachable app; advertised links that mismatch across sources.
 - **Drainer/scam signals:** `drainerFlags` set, EVM wallet calls on a Solana token, wallet-connect as the only content. These make it worse than a LARP — flag `wallet_drainer_risk`.
 
+## The links-only baseline (backtested, task-1401)
+
+`get_links.baseline` grades the three primary links with a rubric tuned on recorded history (`grade`, `signals`, and the held-out rate in `measured`). It is a weak prior, not evidence about the product:
+- On held-out coins its `LARP` grade was rare (14 of 328) and not reliably better than average; its `EARLY_BUT_REAL` coins went bad less often than average (10 % against 19 %). Never return `LARP` from the baseline alone: a `LARP` verdict needs a fetched-page, domain or GitHub fact that contradicts a claim. If nothing could be fetched, the verdict is `UNVERIFIABLE`.
+- The link signals that went with bad outcomes in the backtest: an X link to a single post or a community instead of an account, no X at all, no Telegram. A social or launchpad page posted as the website did not, so fetch it before reading anything into it.
+- 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.
+
 ## 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.
@@ -64,4 +72,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.1.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.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.

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

@@ -1,7 +1,7 @@
 ---
 name: rug-check
 description: Rug and honeypot forensics on one token - authorities, token program, LP, concentration, creator history, tape - with a rug probability. Use for "is this a rug", "safe?", "check it".
-version: 0.2.0
+version: 0.3.0
 argument-hint: <mint or symbol>
 kind: skill
 output_schema: schemas/verdict.schema.json
@@ -32,7 +32,17 @@ Authorities → token program and extensions → LP → concentration and cluste
 - Freeze authority enabled, mint authority enabled, or a Token-2022 program with a dangerous extension named in `security.risks[]`: verdict `AVOID`, `rug_probability ≥ 0.8`. The verdict is settled.
 - A tape with almost no sells on a token hours old and many buyers (`tape.sells` under 5 % of `tape.buys` with `count` above 50) is a honeypot signal even when the freeze field is null: flag `sells_suppressed`.
 - LP below 100 % locked on a Raydium/Meteora pair: flag `lp_unlocked`; combined with `concentration.top10PctExLp` above 50 % it is `AVOID`.
-- Dev above 10 %, or a concentration/creator red flag: `SPECULATIVE` at best; raise `rug_probability` accordingly.
+- Liquidity under $5,000 (`market.pair.liquidityUsd`): `SPECULATIVE` at best. This was the strongest signal in the backtest (task-1401, train split: 80 % of such coins went rug or dead within 72 h, against 40 % overall).
+- Dev above 10 %, organic score below 40 and top-10 above 30 % did not go with a worse 72 h outcome in the backtest. Report them in `flags` and lower `confidence`, but on their own they do not make a coin `SPECULATIVE`. A serial-rugger creator still does (the backtest has no creator history, so that rule is untested).
+
+## Anchoring `rug_probability` (backtest, task-1401)
+
+Start from the train-split 72 h bad-outcome rate of the rule that decided the verdict, then move it with the tape and creator facts you can cite:
+- liquidity under $5,000: anchor 0.8.
+- no disqualifier and liquidity at or above $5,000: anchor 0.27.
+- the authority disqualifiers keep `AVOID` and their floor. The backtest cannot score them: its labels are price outcomes, which miss honeypots and frozen holders, and the coins with an authority still enabled were almost all older tokens off pump.fun (median age 259 days).
+
+On the later, held-out coins both anchored rates ran lower (55 % and 14 %) because fewer coins went bad overall: the ranking held, the level did not. These rates come from one machine's recorder over a few days and drift with the market; never round up toward certainty.
 
 ## Grounding rules (hard)
 
@@ -57,7 +67,7 @@ Authorities → token program and extensions → LP → concentration and cluste
 
 ## Output
 
-Only the JSON object required by the schema (`skill: "rug-check"`, `skill_version: "0.2.0"`, include `rug_probability`). Fill every structured field completely (`bias`, `key_levels`, `invalidation`, `size_hint`, `facts`, `missing_data`). Brevity applies to the prose only:
+Only the JSON object required by the schema (`skill: "rug-check"`, `skill_version: "0.3.0"`, include `rug_probability`). Fill every structured field completely (`bias`, `key_levels`, `invalidation`, `size_hint`, `facts`, `missing_data`). Brevity applies to the prose only:
 
 - `summary` is two to four short lines for a 40-column panel: line 1 answers "is it a rug" in plain words (the disqualifier if there is one, otherwise the main risk or "no disqualifier"), line 2 is the one or two strongest facts with their source fields. Add a short `missing:` line only when a gap changes the call.
 - Do not repeat the verdict, rug probability, bias, key levels, invalidation or size in `summary`. The app renders those fields right beside it. Do not restate numbers the user already sees on the screener row.

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

@@ -1,7 +1,7 @@
 ---
 name: token-dossier
 description: Full read-only dossier on one Solana token (market, holders, creator, risk, tape) with a WATCH/SPECULATIVE/AVOID verdict. Use when the user asks "what is this", "dossier", "look at $X".
-version: 0.2.0
+version: 0.3.0
 argument-hint: <mint or symbol>
 kind: skill
 output_schema: schemas/verdict.schema.json
@@ -39,7 +39,7 @@ Read `availability` first: `present` lists the sections you have, `missing` the
 Judge with what you have. Missing sections lower `confidence`; they do not block a verdict.
 
 - `AVOID` when any disqualifier is present: freeze authority enabled, mint authority enabled, Token-2022 honeypot extension, LP locked below 100 % on a non-pump pair with top-10 ex-LP above 50 %, or wash tape (`tape.top2WalletVolumeSharePct` above 60 with `buyUsd ≈ sellUsd`).
-- `SPECULATIVE` when there is no disqualifier but a material risk (dev above 10 %, serial creator, organic score below 40, top-10 ex-LP above 50 %, or a thin/young market).
+- `SPECULATIVE` when there is no disqualifier but a material risk: liquidity under $5,000 (the strongest signal in the task-1401 backtest), a serial creator, or top-10 ex-LP above 50 %. Dev above 10 % and organic score below 40 did not go with a worse 72 h outcome in that backtest: name them as risks and lower `confidence`, but they alone do not make a coin `SPECULATIVE`.
 - `WATCH` otherwise.
 - `INSUFFICIENT_DATA` **only** when `availability.canVerdict` is false — i.e. no price and no liquidity from any source. A null creator history, missing holders, no candles or no tape is NOT insufficient data on its own: produce a verdict from the rest and note what was missing.
 - `missing_data`: copy every entry of `availability.missing` and `availability.knownUnavailable` here. The keyless creator-history Tier-1 gap belongs here every time, not in the verdict.
@@ -56,7 +56,7 @@ Judge with what you have. Missing sections lower `confidence`; they do not block
 
 ## Output
 
-Return only the JSON object required by the schema (`skill: "token-dossier"`, `skill_version: "0.2.0"`). Fill every structured field completely (`bias`, `setup_quality`, `key_levels`, `invalidation`, `size_hint`, `facts`, `missing_data`). Brevity applies to the prose only:
+Return only the JSON object required by the schema (`skill: "token-dossier"`, `skill_version: "0.3.0"`). Fill every structured field completely (`bias`, `setup_quality`, `key_levels`, `invalidation`, `size_hint`, `facts`, `missing_data`). Brevity applies to the prose only:
 
 - `summary` is two to four short lines for a 40-column panel: line 1 is the call in plain words (bias plus the one-clause reason), line 2 is the one or two facts that decide it, each with its source field. Add a short `missing:` line only when a gap changes the call.
 - Do not repeat the verdict, bias, setup, key levels, invalidation or size in `summary`. The app renders those fields right beside it. Do not restate numbers the user already sees on the screener row (price, % change, liquidity, volume).

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, TIERS, isTier, } from '../../agents/src/index.js';
+import { AgentRegistry, SqliteAuditLog, MemoryProposalStore, SqliteProposalStore, AgentBus, FixtureExecutor, FixtureFeed, SpectatorHub, SpectatorServer, SpectatorRecorder, FollowController, 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; }
@@ -24,10 +24,11 @@ function intFlag(rest, name) { const v = flag(rest, name); const n = v === undef
 const USAGE = `dexterm agent <command>
   add <name> --tier observe|annotate|propose [--note T] [--reads N] [--proposals N] [--connections N]
   list | rotate <name> | remove <name> | tier <name> <tier> | pause <name> | resume <name>
+  mandate <name> --tools a,b,c | mandate <name> --clear   (narrow an agent to a named set of tools)
   audit [--agent NAME] [--limit N]
   proposals [--agent NAME] [--status pending|confirmed|dismissed] [--limit N] [--db PATH]
   packs
-  serve [--fixtures|--live] [--roster] [--port N] [--db PATH]
+  serve [--fixtures|--live] [--roster] [--spectate] [--spectator-popup] [--record FILE] [--port N] [--db PATH]
   connect --name NAME [--port N] [--url ws://127.0.0.1:PORT] [--watch SECONDS]   (token via $DEXTERM_AGENT_TOKEN)`;
 export async function runAgent(rest, io) {
     const cmd = rest[0];
@@ -64,9 +65,12 @@ export async function runAgent(rest, io) {
                 out('no agents registered. Add one: dexterm agent add <name> --tier observe');
                 return 0;
             }
-            out('name                     tier      paused  created              note');
-            for (const a of list)
-                out(`${a.name.padEnd(24)} ${a.tier.padEnd(9)} ${(a.paused ? 'yes' : 'no').padEnd(7)} ${new Date(a.createdAt).toISOString().slice(0, 19)}  ${a.note ?? ''}`);
+            out('name                     tier      paused  created              mandate / note');
+            for (const a of list) {
+                const mandate = a.scope && a.scope.length ? `mandate: ${a.scope.join(',')}` : '';
+                const tail = [mandate, a.note ?? ''].filter(Boolean).join(' · ');
+                out(`${a.name.padEnd(24)} ${a.tier.padEnd(9)} ${(a.paused ? 'yes' : 'no').padEnd(7)} ${new Date(a.createdAt).toISOString().slice(0, 19)}  ${tail}`);
+            }
             return 0;
         }
         case 'rotate': {
@@ -131,6 +135,35 @@ export async function runAgent(rest, io) {
                 return 1;
             }
         }
+        case 'mandate': {
+            const name = rest[1];
+            if (!name) {
+                errOut('usage: dexterm agent mandate <name> --tools a,b,c | --clear');
+                return 2;
+            }
+            try {
+                if (has(rest, '--clear')) {
+                    registry.setScope(name, null);
+                    out(`cleared the mandate for "${name}" (it may now use its full tier surface).`);
+                    return 0;
+                }
+                const tools = flag(rest, '--tools');
+                if (!tools) {
+                    errOut('usage: dexterm agent mandate <name> --tools a,b,c | --clear');
+                    return 2;
+                }
+                const list = tools.split(',').map((t) => t.trim()).filter(Boolean);
+                registry.setScope(name, list);
+                const rec = registry.get(name);
+                out(`"${name}" is now mandated to: ${rec.scope.join(', ')}.`);
+                out('the agent can call only these tools (plus agent_whoami); a mandate only narrows the tier, never widens it.');
+                return 0;
+            }
+            catch (e) {
+                errOut(`dexterm agent mandate: ${e.message}`);
+                return 1;
+            }
+        }
         case 'audit': {
             const dbPath = flag(rest, '--db') || defaultDbPath(io.env);
             const log = new SqliteAuditLog(dbPath);
@@ -224,12 +257,36 @@ async function serve(rest, io, registry) {
     else {
         executor = new FixtureExecutor();
     }
-    const bus = new AgentBus({ registry, audit, executor, proposals, feed, port, env: io.env });
+    // task-1406: the spectator hub observes every agent action; it feeds follow mode, the read-only stream
+    // and the save file. Created whenever any spectator surface is asked for (cheap; off otherwise).
+    const wantSpectate = has(rest, '--spectate');
+    const wantRecord = flag(rest, '--record');
+    const wantSpectatorPopup = has(rest, '--spectator-popup');
+    const hub = (wantSpectate || wantRecord || wantSpectatorPopup) ? new SpectatorHub() : undefined;
+    const bus = new AgentBus({ registry, audit, executor, proposals, feed, spectator: hub, port, env: io.env });
     const boundPort = await bus.start();
     feed.start(1500);
     io.stdout.write(`dexterm agent bus listening on ws://127.0.0.1:${boundPort} (${live ? 'live keyless reads' : 'fixtures'})\n`);
     io.stdout.write(`discovery: ${process.env.DEXTERM_HOME ?? '~/.dexterm'}/agent-bus.json · ${registry.list().length} registered agent(s)\n`);
     io.stdout.write('agents connect with their name + $DEXTERM_AGENT_TOKEN. Ctrl-C to stop.\n');
+    // --record FILE: save the session (redacted) for demos / bug reports; replay with `dexterm spectate --replay`.
+    let recorder = null;
+    if (hub && wantRecord) {
+        try {
+            recorder = new SpectatorRecorder({ path: wantRecord, note: 'dexterm agent serve' }).attach(hub);
+            io.stdout.write(`recording the session to ${wantRecord} (redacted).\n`);
+        }
+        catch (e) {
+            io.stderr.write(`could not record: ${e.message}\n`);
+        }
+    }
+    // --spectate: start the read-only, loopback, token-gated spectator stream (SPECTATOR.md).
+    let stream = null;
+    if (hub && wantSpectate) {
+        stream = new SpectatorServer({ hub, env: io.env });
+        const sp = await stream.start();
+        io.stdout.write(`spectator stream (read-only) on ws://127.0.0.1:${sp} · token in ${process.env.DEXTERM_HOME ?? '~/.dexterm'}/spectator.json (0600) · redacts addresses/keys\n`);
+    }
     // --roster: open the agent roster popup and keep it live. The popup can only send pause/resume/kick.
     let roster = null;
     if (has(rest, '--roster')) {
@@ -254,11 +311,51 @@ async function serve(rest, io, registry) {
             io.stderr.write(`roster popup unavailable: ${e.message}\n`);
         }
     }
+    // --spectator-popup: open the spectator popup ("watch the agent cook"), fed by a follow controller that
+    // folds the hub's events into the screen model + activity. It sends only spectator.* (pause/takeover/kill).
+    let spectatorPopup = null;
+    if (hub && wantSpectatorPopup) {
+        try {
+            const { createPopupManager } = await import('../../popup/src/index.js');
+            const { buildSpectatorVM, applySpectatorEvent } = await import("./agent-spectator.js");
+            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));
+            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 timer = setInterval(() => { try {
+                mgr.setData(handle.id, buildSpectatorVM(follow));
+            }
+            catch { /* popup closed */ } }, 1000);
+            timer.unref?.();
+            spectatorPopup = { shutdown: () => mgr.shutdown(), timer, off };
+            io.stdout.write(`spectator popup open (${mgr.native ? 'native window' : 'browser fallback'}).\n`);
+        }
+        catch (e) {
+            io.stderr.write(`spectator popup unavailable: ${e.message}\n`);
+        }
+    }
     await new Promise((resolve) => {
-        const stop = () => { if (roster) {
-            clearInterval(roster.timer);
-            void roster.shutdown();
-        } feed.stop(); audit.close(); proposals.close(); dataClose?.(); void bus.close().then(resolve); };
+        const stop = () => {
+            if (roster) {
+                clearInterval(roster.timer);
+                void roster.shutdown();
+            }
+            if (spectatorPopup) {
+                clearInterval(spectatorPopup.timer);
+                spectatorPopup.off();
+                void spectatorPopup.shutdown();
+            }
+            recorder?.stop();
+            feed.stop();
+            audit.close();
+            proposals.close();
+            dataClose?.();
+            void (stream ? stream.close() : Promise.resolve()).then(() => bus.close().then(resolve));
+        };
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
     });

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

@@ -0,0 +1,37 @@
+// 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';
+function activityVM(ev) {
+    return {
+        seq: ev.seq, t: ev.t, phase: ev.phase, agent: ev.agent, tier: ev.tier ?? null,
+        tool: ev.tool ?? null, summary: ev.summary ?? '', ms: ev.ms ?? null, dataAgeSec: ev.dataAgeSec ?? null,
+        ok: ev.ok, refusal: ev.refusal ?? null,
+    };
+}
+/** Build the spectator popup VM from the follow controller. Redacts addresses/keys unless redact:false. */
+export function buildSpectatorVM(follow, opts = {}) {
+    const redact = opts.redact ?? true;
+    const v = follow.view();
+    const s = v.screen;
+    const mask = (x) => (x && redact ? maskAddress(x) : x);
+    return {
+        title: opts.title ?? 'watch the agent cook',
+        now: Date.now(),
+        redacted: redact,
+        control: v.control,
+        screen: { screen: s.screen, selectedMint: mask(s.selectedMint), feed: s.feed, filter: s.filter, highlight: mask(s.highlight) },
+        agents: v.agents.map((a) => ({ name: a.name, tier: a.tier, status: a.status, lastAt: a.lastAt })),
+        activity: v.activity.map((ev) => activityVM(redact ? redactSpectatorEvent(ev) : ev)),
+    };
+}
+/** Apply a validated spectator popup event to the follow controller. Returns a short log line. */
+export function applySpectatorEvent(follow, name, agent) {
+    switch (name) {
+        case 'spectator.pause': return follow.pause(agent);
+        case 'spectator.resume': return follow.resume(agent);
+        case 'spectator.takeover': return follow.takeOver(agent);
+        case 'spectator.kill': return follow.kill(agent);
+        default: return `ignored ${name}`;
+    }
+}

package/dist/packages/cli/src/alerts/adapters/desktop.js

@@ -0,0 +1,40 @@
+// dexterm — the `desktop` adapter (task-1398). macOS `osascript -e 'display notification …'`, Linux
+// `notify-send`. The command is run via execFile with an argv array (NO shell), so a crafted title/body
+// cannot inject a command. macOS osascript takes one AppleScript string on argv; the already-firewalled
+// title/body are additionally AppleScript-escaped (\\, ") and newline-stripped there. The runner is
+// injectable so tests assert the command without spawning anything.
+import { execFile } from 'node:child_process';
+import { deliveryLine } from "../format.js";
+const defaultRunner = (cmd, args) => new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 5000 }, (err) => (err ? reject(new Error(err.code === 'ENOENT' ? `${cmd} not found` : err.message)) : resolve()));
+});
+/** AppleScript string literal body: escape backslash and quote, drop any residual control chars. */
+function osaString(s) {
+    return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/[\u0000-\u001f\u007f]/g, ' ') + '"';
+}
+export function createDesktopAdapter(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const run = deps.run ?? defaultRunner;
+    return {
+        name: 'desktop',
+        available: () => platform === 'darwin' || platform === 'linux',
+        deliver: async (d) => {
+            try {
+                if (platform === 'darwin') {
+                    const script = `display notification ${osaString(d.body)} with title ${osaString(d.title)}`;
+                    await run('osascript', ['-e', script]);
+                }
+                else if (platform === 'linux') {
+                    await run('notify-send', ['--app-name=dexterm', d.title, d.body || deliveryLine(d)]);
+                }
+                else {
+                    return { ok: false, skipped: true, reason: `desktop notifications unsupported on ${platform}` };
+                }
+                return { ok: true };
+            }
+            catch (e) {
+                return { ok: false, reason: e.message };
+            }
+        },
+    };
+}