dexterm-cli 0.1.1 → 0.1.2

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

@@ -192,7 +192,7 @@ export class AgentBus {
             return;
         }
         if (msg.method === 'tools/list') {
-            this.reply(conn, id, { tools: toolsForTierList(conn.session.tier) });
+            this.reply(conn, id, { tools: this.visibleToolDefs(conn.session) });
             return;
         }
         if (msg.method === 'tools/call') {
@@ -245,14 +245,15 @@ export class AgentBus {
         if (rec.paused)
             this.paused.add(rec.id);
         this.gate.setAgentLimits(rec.id, rec.limits);
-        const session = { id: `sess_${(++this.sessionSeq).toString(36)}`, agentId: rec.id, agentName: rec.name, tier, transport: 'bus', openedAt: this.now(), lastActivity: this.now(), closed: false, closedReason: null, client, topics: new Set() };
+        const scope = rec.scope && rec.scope.length ? new Set(rec.scope) : null;
+        const session = { id: `sess_${(++this.sessionSeq).toString(36)}`, agentId: rec.id, agentName: rec.name, tier, transport: 'bus', openedAt: this.now(), lastActivity: this.now(), closed: false, closedReason: null, client, topics: new Set(), scope };
         conn.session = session;
         if (conn.helloTimer) {
             clearTimeout(conn.helloTimer);
             conn.helloTimer = null;
         }
-        this.audit.append({ agentId: rec.id, agentName: rec.name, session: session.id, kind: 'connect', tool: '-', detail: `tier ${tier} · ${client} · ${conn.ws.remote}`, ok: true });
-        this.reply(conn, id, { protocol: BUS_PROTOCOL, agent: rec.name, tier, grantedTier: rec.tier, tools: toolsForTier(tier), paused: rec.paused });
+        this.audit.append({ agentId: rec.id, agentName: rec.name, session: session.id, kind: 'connect', tool: '-', detail: `tier ${tier}${scope ? ` · mandate[${[...scope].join(',')}]` : ''} · ${client} · ${conn.ws.remote}`, ok: true });
+        this.reply(conn, id, { protocol: BUS_PROTOCOL, agent: rec.name, tier, grantedTier: rec.tier, tools: this.visibleTools(session), mandate: scope ? [...scope] : null, paused: rec.paused });
     }
     async onCall(conn, id, params) {
         const session = conn.session;
@@ -309,7 +310,21 @@ export class AgentBus {
         }
     }
     whoami(session) {
-        return { agent: session.agentName, tier: session.tier, tools: toolsForTier(session.tier).map((t) => ({ name: t, tier: agentTool(t)?.tier })), usage: this.gate.usage(session.agentId), subscriptions: [...session.topics], note: 'Your identity and tier come from the server. You cannot change them.' };
+        return { agent: session.agentName, tier: session.tier, mandate: session.scope ? [...session.scope] : null, tools: this.visibleTools(session).map((t) => ({ name: t, tier: agentTool(t)?.tier })), usage: this.gate.usage(session.agentId), subscriptions: [...session.topics], note: 'Your identity, tier and mandate come from the server. You cannot change them.' };
+    }
+    /** Tool names this session may call: its tier surface, narrowed by a mandate (+ agent_whoami, always). */
+    visibleTools(session) {
+        const all = toolsForTier(session.tier);
+        if (!session.scope)
+            return all;
+        return all.filter((t) => t === 'agent_whoami' || session.scope.has(t));
+    }
+    /** The advertised tool DEFINITIONS for tools/list, narrowed the same way. */
+    visibleToolDefs(session) {
+        const defs = toolsForTierList(session.tier);
+        if (!session.scope)
+            return defs;
+        return defs.filter((t) => t.name === 'agent_whoami' || session.scope.has(t.name));
     }
     subscribe(conn, args) {
         const session = conn.session;

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

@@ -116,6 +116,31 @@ export class FixtureExecutor {
                 const [token, rug, trades] = await Promise.all([this.exec(session, 'get_token', { mint: r.mint }), this.exec(session, 'rugcheck', { mint: r.mint }), this.exec(session, 'get_trades', { mint: r.mint, window: 'h1' })]);
                 return { mint: r.mint, interval: args.interval ?? '1h', token, rugcheck: rug, trades, availability: { market: true, security: true, tape: true, canVerdict: true } };
             }
+            case 'analyze_token': {
+                const r = byMint(args.mint) ?? FIXTURE_ROWS.find((x) => x.symbol.toUpperCase() === String(args.symbol ?? '').replace(/^\$/, '').toUpperCase());
+                if (!r)
+                    return { error: 'unknown token (fixtures)' };
+                // A deterministic verdict from the fixture row's audit (mirrors the real pack's rule flags).
+                const flags = [];
+                if (r.freeze)
+                    flags.push('freeze_authority');
+                if (r.mintAuth)
+                    flags.push('mint_authority');
+                if (r.lpLockedPct < 100)
+                    flags.push('lp_unlocked');
+                if (r.top10Pct > 40)
+                    flags.push('top10_concentrated');
+                if (r.organicScore < 40)
+                    flags.push('organic_below_40');
+                if (r.ageSec < 600)
+                    flags.push('under_10_minutes');
+                const verdict = r.rugScore >= 60 ? 'AVOID' : r.rugScore >= 25 ? 'SPECULATIVE' : 'WATCH';
+                return { pack: 'token-dossier', pack_version: 'fixtures', model_output: false, mint: r.mint, symbol: fw(r.symbol), deterministic_verdict: verdict, rug_probability: r.rugScore / 100, rug_model: 'H1-v0.1', flags, injection_suspected: false, note: 'Deterministic code stage (no model) on fixtures.', source: 'fixtures' };
+            }
+            case 'narrative_board':
+                return { pack: 'narrative-board', model_output: false, narratives: [], note: 'No recorded history on fixtures (the board needs a running recorder).' };
+            case 'rug_backtest':
+                return { pack: 'rug-backtest', model_output: false, note: 'No recorded history on fixtures (a backtest needs recorded t0 snapshots with labelled outcomes).' };
             case 'open_token':
             case 'show_in_screener':
             case 'switch_feed':

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

@@ -95,6 +95,9 @@ export class AgentGate {
             return refuse('unknown-tool', `unknown tool ${JSON.stringify(String(name).slice(0, 40))}`);
         if (!tierAtLeast(session.tier, need))
             return refuse('tier', `${name} needs tier ${need}; this agent is ${session.tier}`);
+        // Per-agent mandate (task-1405): a scoped agent may call only its listed tools (+ agent_whoami). Narrow-only.
+        if (session.scope && name !== 'agent_whoami' && !session.scope.has(name))
+            return refuse('mandate', `${name} is outside this agent's mandate (allowed: ${[...session.scope].join(', ')})`);
         // spoofing: identity / capability fields in the arguments are never honoured
         const args = req.args === undefined ? {} : req.args;
         if (typeof args === 'object' && args !== null && !Array.isArray(args)) {

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

@@ -10,11 +10,30 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, chmodSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
-import { isTier } from "./tiers.js";
+import { isTier, TOOL_TIERS } from "./tiers.js";
 export const AGENT_NAME_RE = /^[a-z][a-z0-9-]{0,23}$/;
 export const TOKEN_PREFIX = 'dxa_';
 /** Hard cap on registered agents (a flood of `agent add` is still bounded). */
 export const MAX_AGENTS = 32;
+/** Validate + normalise a mandate scope: known tool names only, deduped; agent_whoami is implicit. Throws on an unknown tool. */
+export function sanitizeScope(tools) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of tools) {
+        const t = String(raw).trim();
+        if (!t || t === 'agent_whoami')
+            continue;
+        if (!Object.hasOwn(TOOL_TIERS, t))
+            throw new Error(`unknown tool "${t.slice(0, 40)}" — a mandate may only list agent tools (${Object.keys(TOOL_TIERS).join(', ')})`);
+        if (!seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+    }
+    if (!out.length)
+        throw new Error('a mandate needs at least one tool (use --clear to remove a mandate)');
+    return out;
+}
 export function dextermHome(env = process.env) {
     return env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
 }
@@ -60,7 +79,16 @@ export class AgentRegistry {
         const list = Array.isArray(f?.agents) ? f.agents : [];
         // Defensive re-validation: a hand-edited file cannot grant a tier outside the three or a bad name.
         this.agents = list.filter((a) => !!a && typeof a === 'object' && typeof a.id === 'string' && typeof a.name === 'string' && AGENT_NAME_RE.test(a.name)
-            && isTier(a.tier) && typeof a.tokenHash === 'string' && typeof a.salt === 'string').map((a) => ({ ...a, paused: a.paused === true, rotatedAt: typeof a.rotatedAt === 'number' ? a.rotatedAt : null }));
+            && isTier(a.tier) && typeof a.tokenHash === 'string' && typeof a.salt === 'string').map((a) => {
+            // A hand-edited scope is re-validated: keep only known tool names; an empty result drops the mandate.
+            const scope = Array.isArray(a.scope) ? a.scope.filter((t) => typeof t === 'string' && Object.hasOwn(TOOL_TIERS, t)) : undefined;
+            const rec = { ...a, paused: a.paused === true, rotatedAt: typeof a.rotatedAt === 'number' ? a.rotatedAt : null };
+            if (scope && scope.length)
+                rec.scope = [...new Set(scope)];
+            else
+                delete rec.scope;
+            return rec;
+        });
     }
     save() {
         if (this.path === ':memory:')
@@ -142,6 +170,17 @@ export class AgentRegistry {
         a.limits = sanitizeLimits(limits);
         this.save();
     }
+    /** Set (or clear, with null) the per-agent tool mandate. Throws on an unknown tool name. */
+    setScope(name, tools) {
+        const a = this.get(name);
+        if (!a)
+            throw new Error(`no agent "${name}"`);
+        if (tools === null)
+            delete a.scope;
+        else
+            a.scope = sanitizeScope(tools);
+        this.save();
+    }
     /**
      * Verify a presented name + token. Constant-time on the hash; the same `null` for an unknown name,
      * a bad token shape and a wrong token (no oracle). Re-reads the file first so a rotate / remove from

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/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

@@ -24,6 +24,7 @@ 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
@@ -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);

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 };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,36 @@
+import { deliveryLine } from "../format.js";
+const nodeFetch = (url, init) => globalThis.fetch(url, init);
+export function createDiscordAdapter(deps) {
+    const creds = deps.creds;
+    const doFetch = deps.fetch ?? nodeFetch;
+    const timeoutMs = deps.timeoutMs ?? 8000;
+    return {
+        name: 'discord',
+        available: () => !!creds?.webhook,
+        deliver: async (d) => {
+            if (!creds)
+                return { ok: false, skipped: true, reason: 'discord not configured (dexterm alerts set-discord)' };
+            const ac = new AbortController();
+            const t = setTimeout(() => ac.abort(), timeoutMs);
+            try {
+                const res = await doFetch(creds.webhook, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    // Content is already firewalled; cap to Discord's 2000-char limit for safety.
+                    body: JSON.stringify({ content: deliveryLine(d).slice(0, 1900) }),
+                    signal: ac.signal,
+                });
+                if (!res.ok)
+                    return { ok: false, reason: `discord ${res.status}` };
+                return { ok: true };
+            }
+            catch (e) {
+                const name = e.name;
+                return { ok: false, reason: name === 'AbortError' ? 'discord timed out' : 'discord unreachable' };
+            }
+            finally {
+                clearTimeout(t);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,43 @@
+import { deliveryLine } from "../format.js";
+const nodeFetch = (url, init) => globalThis.fetch(url, init);
+export function createTelegramAdapter(deps) {
+    const creds = deps.creds;
+    const doFetch = deps.fetch ?? nodeFetch;
+    const timeoutMs = deps.timeoutMs ?? 8000;
+    return {
+        name: 'telegram',
+        available: () => !!creds?.token && !!creds?.chatId,
+        deliver: async (d) => {
+            if (!creds)
+                return { ok: false, skipped: true, reason: 'telegram not configured (dexterm alerts set-telegram)' };
+            const ac = new AbortController();
+            const t = setTimeout(() => ac.abort(), timeoutMs);
+            try {
+                const res = await doFetch(`https://api.telegram.org/bot${creds.token}/sendMessage`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ chat_id: creds.chatId, text: deliveryLine(d), disable_web_page_preview: true }),
+                    signal: ac.signal,
+                });
+                // Never echo the token/url: only the status code and Telegram's own error description.
+                if (!res.ok) {
+                    let desc = '';
+                    try {
+                        const j = JSON.parse(await res.text());
+                        desc = j.description ? `: ${j.description}` : '';
+                    }
+                    catch { /* ignore body */ }
+                    return { ok: false, reason: `telegram ${res.status}${desc}`.slice(0, 160) };
+                }
+                return { ok: true };
+            }
+            catch (e) {
+                const name = e.name;
+                return { ok: false, reason: name === 'AbortError' ? 'telegram timed out' : 'telegram unreachable' };
+            }
+            finally {
+                clearTimeout(t);
+            }
+        },
+    };
+}

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

@@ -0,0 +1,16 @@
+import { deliveryLine } from "../format.js";
+export function createToastAdapter(sink) {
+    return {
+        name: 'toast',
+        available: () => true,
+        deliver: async (d) => {
+            try {
+                sink(deliveryLine(d), d);
+                return { ok: true };
+            }
+            catch (e) {
+                return { ok: false, reason: e.message };
+            }
+        },
+    };
+}

package/dist/packages/cli/src/alerts/creds.js

@@ -0,0 +1,83 @@
+// dexterm — alert-channel credentials (task-1398). Bot tokens and webhook URLs are NEVER in config.json
+// (the config schema has no key-shaped fields, by rule). They live in ~/.dexterm/<channel>.json, mode 0600,
+// outside every repo, read only by the adapters. Nothing here ever prints a secret; `redactCreds()` scrubs
+// a token / webhook out of any string before it could reach a log, a toast, a test fixture or an error.
+import { readFileSync, writeFileSync, mkdirSync, statSync, chmodSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+export const telegramCredsPath = (home) => join(home, 'telegram.json');
+export const discordCredsPath = (home) => join(home, 'discord.json');
+function readJson(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const v = JSON.parse(text);
+        return v && typeof v === 'object' && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeJson(path, home, value) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+    // rename is atomic; chmod again in case an old file had looser bits.
+    try {
+        chmodSync(tmp, 0o600);
+    }
+    catch { /* best effort */ }
+    renameSync(tmp, path);
+}
+export function readTelegramCreds(home) {
+    const j = readJson(telegramCredsPath(home));
+    if (!j)
+        return null;
+    const token = typeof j.token === 'string' ? j.token.trim() : '';
+    const chatId = typeof j.chatId === 'string' ? j.chatId.trim() : (typeof j.chatId === 'number' ? String(j.chatId) : '');
+    if (!token || !chatId)
+        return null;
+    return { token, chatId };
+}
+export function writeTelegramCreds(home, creds) {
+    if (!creds.token.trim())
+        throw new Error('telegram token is empty');
+    if (!/^-?\d{1,19}$/.test(creds.chatId.trim()))
+        throw new Error('telegram chatId must be a numeric id (e.g. 123456789 or -1001234567890)');
+    writeJson(telegramCredsPath(home), home, { token: creds.token.trim(), chatId: creds.chatId.trim() });
+}
+export function readDiscordCreds(home) {
+    const j = readJson(discordCredsPath(home));
+    if (!j)
+        return null;
+    const webhook = typeof j.webhook === 'string' ? j.webhook.trim() : '';
+    if (!webhook)
+        return null;
+    return { webhook };
+}
+export function writeDiscordCreds(home, creds) {
+    const w = creds.webhook.trim();
+    if (!/^https:\/\/(?:[a-z0-9.-]+\.)?discord(?:app)?\.com\/api\/webhooks\/\d+\/[\w-]+$/i.test(w)) {
+        throw new Error('discord webhook must be a https://discord.com/api/webhooks/<id>/<token> URL');
+    }
+    writeJson(discordCredsPath(home), home, { webhook: w });
+}
+/** True when the file exists with 0600-ish perms; a looser mode is reported so the user can tighten it. */
+export function credsMode(path) {
+    try {
+        return statSync(path).mode & 0o777;
+    }
+    catch {
+        return null;
+    }
+}
+const TELEGRAM_TOKEN_RE = /\b\d{6,}:[A-Za-z0-9_-]{20,}\b/g;
+const DISCORD_WEBHOOK_RE = /https:\/\/(?:[a-z0-9.-]+\.)?discord(?:app)?\.com\/api\/webhooks\/\S+/gi;
+/** Scrub any bot token / webhook URL out of a string before it could be logged or shown. Total; never throws. */
+export function redactCreds(s) {
+    return String(s ?? '').replace(TELEGRAM_TOKEN_RE, 'bot[redacted]').replace(DISCORD_WEBHOOK_RE, '[redacted-webhook]');
+}

package/dist/packages/cli/src/alerts/format.js

@@ -0,0 +1,41 @@
+// dexterm — turn a rule-engine alert / proposal into a firewalled AlertDelivery (task-1398). Pure.
+//
+// Untrusted text (a token symbol, and whatever the user put in the rule's alert text) is run through the
+// prompt firewall (control/bidi/ANSI stripped, URLs → [url], foreign base58 → [addr], wide glyphs → ▯,
+// injection-like content neutralised) and the spoken form through the `say` sanitiser (defuses `[[…]]`,
+// shortens addresses). Nothing reaches a channel raw.
+import { firewallText } from '../../../data/src/index.js';
+import { sanitizeSpeech } from '../../../voice/src/index.js';
+const TITLE_MAX = 64;
+const BODY_MAX = 180;
+/** Firewall a string; keep the row's own mint readable, drop URLs, cap length. */
+function fw(s, max, mint) {
+    return firewallText(s, { keepMint: mint ?? null, keepUrls: false, max }).text;
+}
+export function alertToDelivery(a) {
+    const symbol = fw(a.symbol, 24) || '?';
+    const body = fw(a.text, BODY_MAX, a.mint);
+    const title = `${symbol} ⚑`.slice(0, TITLE_MAX);
+    return {
+        kind: 'alert', level: a.level, title, body,
+        spoken: sanitizeSpeech(`${symbol}. ${body}`),
+        symbol, mint: a.mint, source: a.source, rule: a.rule, at: a.at,
+    };
+}
+export function proposalToDelivery(p) {
+    const symbol = fw(p.symbol, 24) || '?';
+    const what = p.type === 'ticket'
+        ? `rule proposes ${p.side} ${p.size} ${p.unit} — confirm in the app (nothing armed)`
+        : `rule asks the analyst: ${p.skill}`;
+    const body = fw(what, BODY_MAX, p.mint);
+    const title = `${symbol} ⚑ proposal`.slice(0, TITLE_MAX);
+    return {
+        kind: 'proposal', level: 'info', title, body,
+        spoken: sanitizeSpeech(`${symbol}. ${body}`),
+        symbol, mint: p.mint, source: p.source, rule: p.rule, at: p.at,
+    };
+}
+/** The one-line form a text channel sends (Telegram / Discord / stdout toast). */
+export function deliveryLine(d) {
+    return d.title === `${d.symbol} ⚑` ? `${d.title} ${d.body}` : `${d.title} — ${d.body}`;
+}