dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,336 @@
+// `dexterm agent …` — bring-your-own-agent registry + loopback bus CLI (task-1345, tier 2).
+//
+//   dexterm agent add <name> --tier observe|annotate|propose [--note T] [--reads N] [--proposals N] [--connections N]
+//   dexterm agent list
+//   dexterm agent rotate <name>            # new one-time token; the old one stops working
+//   dexterm agent remove <name>
+//   dexterm agent tier <name> <tier>
+//   dexterm agent pause|resume <name>
+//   dexterm agent audit [--agent NAME] [--limit N]
+//   dexterm agent packs                    # the skills/KB an external agent gets over MCP (agent packs)
+//   dexterm agent serve [--fixtures|--live] [--port N] [--db PATH]   # run a standalone loopback bus
+//   dexterm agent connect --name NAME [--port N] [--url ws://…] [--watch SECONDS]  # token from $DEXTERM_AGENT_TOKEN
+//
+// A one-time token is printed to stdout by `add`/`rotate` so the user can paste it into THEIR agent's
+// 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 { 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; }
+function has(rest, name) { return rest.includes(name); }
+function intFlag(rest, name) { const v = flag(rest, name); const n = v === undefined ? undefined : Number(v); return typeof n === 'number' && Number.isFinite(n) ? n : undefined; }
+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]
+  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];
+    const out = (s) => io.stdout.write(s + '\n');
+    const errOut = (s) => io.stderr.write(s + '\n');
+    const registry = new AgentRegistry({ env: io.env });
+    switch (cmd) {
+        case 'add': {
+            const name = rest[1];
+            const tier = flag(rest, '--tier');
+            if (!name || !tier || !isTier(tier)) {
+                errOut(`usage: dexterm agent add <name> --tier ${TIERS.join('|')}`);
+                return 2;
+            }
+            const limits = { readsPerMin: intFlag(rest, '--reads'), proposalsPerHour: intFlag(rest, '--proposals'), connections: intFlag(rest, '--connections') };
+            try {
+                const { agent, token } = registry.add(name, tier, { note: flag(rest, '--note'), limits });
+                out(`registered "${agent.name}" (tier ${agent.tier}, id ${agent.id}).`);
+                out('');
+                out('  one-time token (shown once — paste it into your agent, do not commit it):');
+                out(`  ${token}`);
+                out('');
+                out(`  your agent authenticates with name="${agent.name}" + this token over the loopback bus or a bridged MCP child.`);
+                return 0;
+            }
+            catch (e) {
+                errOut(`dexterm agent add: ${e.message}`);
+                return 1;
+            }
+        }
+        case 'list': {
+            const list = registry.list();
+            if (!list.length) {
+                out('no agents registered. Add one: dexterm agent add <name> --tier observe');
+                return 0;
+            }
+            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': {
+            const name = rest[1];
+            if (!name) {
+                errOut('usage: dexterm agent rotate <name>');
+                return 2;
+            }
+            try {
+                const token = registry.rotate(name);
+                out(`rotated "${name}". the previous token no longer works.`);
+                out('');
+                out('  new one-time token (shown once):');
+                out(`  ${token}`);
+                return 0;
+            }
+            catch (e) {
+                errOut(`dexterm agent rotate: ${e.message}`);
+                return 1;
+            }
+        }
+        case 'remove': {
+            const name = rest[1];
+            if (!name) {
+                errOut('usage: dexterm agent remove <name>');
+                return 2;
+            }
+            out(registry.remove(name) ? `removed "${name}" (its token is now invalid).` : `no agent "${name}".`);
+            return 0;
+        }
+        case 'tier': {
+            const name = rest[1];
+            const tier = rest[2];
+            if (!name || !tier || !isTier(tier)) {
+                errOut(`usage: dexterm agent tier <name> ${TIERS.join('|')}`);
+                return 2;
+            }
+            try {
+                registry.setTier(name, tier);
+                out(`"${name}" is now tier ${tier}.`);
+                return 0;
+            }
+            catch (e) {
+                errOut(`dexterm agent tier: ${e.message}`);
+                return 1;
+            }
+        }
+        case 'pause':
+        case 'resume': {
+            const name = rest[1];
+            if (!name) {
+                errOut(`usage: dexterm agent ${cmd} <name>`);
+                return 2;
+            }
+            try {
+                registry.setPaused(name, cmd === 'pause');
+                out(`"${name}" ${cmd === 'pause' ? 'paused' : 'resumed'} (persisted; a running dexterm applies it on the agent's next connection).`);
+                return 0;
+            }
+            catch (e) {
+                errOut(`dexterm agent ${cmd}: ${e.message}`);
+                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);
+            try {
+                const agentName = flag(rest, '--agent');
+                const rows = log.recent(intFlag(rest, '--limit') ?? 50, agentName ? { agentName } : {});
+                if (!rows.length) {
+                    out('no audit rows yet.');
+                    return 0;
+                }
+                out('time                 agent             kind        tool              ok  detail');
+                for (const r of rows.reverse())
+                    out(`${new Date(r.t).toISOString().slice(0, 19)}  ${r.agentName.padEnd(16)} ${r.kind.padEnd(10)} ${r.tool.slice(0, 16).padEnd(16)} ${r.ok ? ' y' : ' n'}  ${r.detail}`);
+                return 0;
+            }
+            finally {
+                log.close();
+            }
+        }
+        case 'packs': {
+            const { selfTest } = await import('../../mcp/src/index.js');
+            const st = selfTest();
+            out('agent packs served over MCP (`dexterm mcp`): skills as prompts, KB + cases + skills as resources.');
+            out(`  skills   : ${st.skills.join(', ')}`);
+            out(`  kb       : ${st.kbEntries} entries`);
+            // task-1377: the user's overlay (~/.dexterm/kb/entries, ~/.dexterm/skills) is merged into what MCP serves.
+            const ov = st.overlay;
+            if (ov && (ov.kb.user || ov.skills.user))
+                out(`  yours    : kb +${ov.kb.user} (${ov.kb.overridden} override, ${ov.kb.added} new), skills +${ov.skills.user} (${ov.skills.overridden} override, ${ov.skills.added} new) — \`dexterm kb|skill list\``);
+            out(`  cases    : ${st.cases}`);
+            out(`  resources: ${st.resources}`);
+            out('connect your agent: `claude mcp add dexterm -- dexterm mcp`, then run a skill, e.g. /dexterm:trench-scan 8');
+            return 0;
+        }
+        case 'proposals': {
+            const store = new SqliteProposalStore(flag(rest, '--db') || defaultDbPath(io.env));
+            try {
+                const status = flag(rest, '--status');
+                const rows = store.list({ agentId: undefined, status: status || undefined, limit: intFlag(rest, '--limit') ?? 50 });
+                const agent = flag(rest, '--agent');
+                const shown = agent ? rows.filter((p) => p.agentName === agent) : rows;
+                if (!shown.length) {
+                    out('no proposals.');
+                    return 0;
+                }
+                out('created              agent             kind        status     summary');
+                for (const p of shown)
+                    out(`${new Date(p.createdAt).toISOString().slice(0, 19)}  ${p.agentName.padEnd(16)} ${p.kind.padEnd(10)} ${p.status.padEnd(9)}  ${p.summary}`);
+                out('');
+                out('proposals are DRAFTS. An agent can never confirm or arm one; the user confirms with a keypress.');
+                return 0;
+            }
+            finally {
+                store.close();
+            }
+        }
+        case 'serve': return serve(rest, io, registry);
+        case 'connect': return connect(rest, io);
+        default:
+            (cmd ? errOut(`unknown subcommand: ${cmd}`) : out(USAGE));
+            if (!cmd)
+                return 0;
+            errOut(USAGE);
+            return 2;
+    }
+}
+async function serve(rest, io, registry) {
+    const live = has(rest, '--live');
+    const port = intFlag(rest, '--port');
+    const dbPath = flag(rest, '--db');
+    const audit = new SqliteAuditLog(dbPath || ':memory:');
+    const proposals = dbPath ? new SqliteProposalStore(dbPath) : new MemoryProposalStore();
+    const feed = new FixtureFeed();
+    let executor;
+    let dataClose = null;
+    if (live) {
+        // Live reads over the real keyless data layer via the MCP tools; the gate still bounds every call.
+        const { McpTools } = await import('../../mcp/src/index.js');
+        const { createDataLayer, resolveRpcUrl, defaultDbPath: ddp } = await import('../../data/src/index.js');
+        const rpc = resolveRpcUrl({ env: io.env });
+        const data = createDataLayer({ dbPath: ddp(io.env), rpcUrl: rpc.url, rpcFallbackUrl: rpc.fallbackUrl });
+        dataClose = () => data.close();
+        const mcp = new McpTools(data, () => ({ screen: 'agent-bus', actions: { mints: [], feeds: [], sortKeys: [] } }));
+        executor = { async exec(_s, tool, args) { try {
+                return await mcp.call(tool, args);
+            }
+            catch (e) {
+                return { error: e.message };
+            } } };
+    }
+    else {
+        executor = new FixtureExecutor();
+    }
+    const bus = new AgentBus({ registry, audit, executor, proposals, feed, 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');
+    // --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')) {
+        try {
+            const { createPopupManager } = await import('../../popup/src/index.js');
+            const { buildRosterVM, applyRosterEvent } = await import("./agent-roster.js");
+            const { THEMES, DEFAULT_THEME } = await import('../../tui/src/index.js');
+            const { popupThemeFrom } = await import("./popup.js");
+            const mgr = createPopupManager({ theme: popupThemeFrom(THEMES[DEFAULT_THEME]), env: io.env, onWarn: (m) => io.stderr.write(`roster popup: ${m}\n`),
+                onEvent: (ev) => { if (ev.ev === 'popup.event' && ev.name.startsWith('roster.'))
+                    io.stdout.write(`roster: ${applyRosterEvent(bus, ev.name, String(ev.payload.agent))}\n`); } });
+            const handle = await mgr.open({ kind: 'roster', title: 'agents', data: buildRosterVM(bus, audit) });
+            const timer = setInterval(() => { try {
+                mgr.setData(handle.id, buildRosterVM(bus, audit));
+            }
+            catch { /* popup closed */ } }, 1000);
+            timer.unref?.();
+            roster = { shutdown: () => mgr.shutdown(), timer };
+            io.stdout.write(`roster popup open (${mgr.native ? 'native window' : 'browser fallback'}).\n`);
+        }
+        catch (e) {
+            io.stderr.write(`roster 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); };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+    });
+    return 0;
+}
+async function connect(rest, io) {
+    const name = flag(rest, '--name');
+    const token = io.env.DEXTERM_AGENT_TOKEN;
+    if (!name) {
+        io.stderr.write('usage: dexterm agent connect --name NAME [--port N]   (token via $DEXTERM_AGENT_TOKEN)\n');
+        return 2;
+    }
+    if (!token) {
+        io.stderr.write('set $DEXTERM_AGENT_TOKEN to the token from `dexterm agent add` (never pass a token as a CLI flag).\n');
+        return 2;
+    }
+    const port = intFlag(rest, '--port');
+    const url = flag(rest, '--url');
+    try {
+        const agent = await connectAgent({ name, token, port, url, client: 'dexterm agent connect', home: io.env.DEXTERM_HOME });
+        io.stdout.write(`connected as "${agent.hello?.agent}" — tier ${agent.hello?.tier} (granted ${agent.hello?.grantedTier}).\n`);
+        const tools = await agent.listTools();
+        io.stdout.write(`tools (${tools.length}): ${tools.map((t) => t.name).join(', ')}\n`);
+        const who = await agent.whoami();
+        io.stdout.write(`whoami: ${JSON.stringify(who)}\n`);
+        const watch = intFlag(rest, '--watch');
+        if (watch && watch > 0) {
+            await agent.subscribe(['new_pairs', 'trades', 'alerts']);
+            agent.on('new_pairs', (ev) => io.stdout.write(`event new_pairs ${JSON.stringify(ev.data)}\n`));
+            agent.on('trades', (ev) => io.stdout.write(`event trades ${JSON.stringify(ev.data)}\n`));
+            agent.on('alerts', (ev) => io.stdout.write(`event alerts ${JSON.stringify(ev.data)}\n`));
+            io.stdout.write(`subscribed; watching for ${watch}s…\n`);
+            await new Promise((r) => setTimeout(r, watch * 1000));
+        }
+        agent.close();
+        return 0;
+    }
+    catch (e) {
+        io.stderr.write(`dexterm agent connect: ${e.message}\n`);
+        return 1;
+    }
+}

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

@@ -0,0 +1,26 @@
+// task-1345 tier 4: bridge the live agent bus to the roster popup VM, and drive the roster popup window.
+// The popup only ever sends roster.pause / roster.resume / roster.kick (by agent name); this module maps
+// those UI events onto the bus's user-side controls. Nothing here can arm, sign or change a cap.
+/** Build the roster VM the popup renders from the live bus + the audit log. */
+export function buildRosterVM(bus, audit, limit = 80) {
+    const agents = bus.roster().map((a) => ({
+        id: a.agentId, name: a.name, tier: a.tier, sessions: a.sessions, client: a.client, lastActivity: a.lastActivity,
+        topics: a.topics, reads: a.usage.readsPerMin, readsLimit: a.usage.limits.readsPerMin,
+        proposals: a.usage.proposalsPerHour, proposalsLimit: a.usage.limits.proposalsPerHour,
+        refused: a.counts.refused, paused: a.paused, floodPausedUntil: a.usage.floodPausedUntil,
+    }));
+    const log = audit.recent(limit).map((r) => ({ t: r.t, agent: r.agentName, kind: r.kind, tool: r.tool, ok: r.ok, detail: r.detail }));
+    return { now: Date.now(), busPort: bus.port, agents, audit: log };
+}
+/** Apply a validated popup roster event to the bus (user-side control). Returns a short log line. */
+export function applyRosterEvent(bus, name, agent) {
+    if (name === 'roster.pause')
+        return bus.pauseAgent(agent) ? `paused ${agent}` : `no agent ${agent}`;
+    if (name === 'roster.resume')
+        return bus.resumeAgent(agent) ? `resumed ${agent}` : `no agent ${agent}`;
+    if (name === 'roster.kick') {
+        const n = bus.kickAgent(agent);
+        return `kicked ${agent} (${n} session${n === 1 ? '' : 's'})`;
+    }
+    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 };
+            }
+        },
+    };
+}

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

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

@@ -0,0 +1,10 @@
+// dexterm — alert delivery subsystem (task-1398). See DESIGN.md.
+export * from "./types.js";
+export * from "./format.js";
+export * from "./route.js";
+export * from "./creds.js";
+export * from "./notifier.js";
+export { createToastAdapter } from "./adapters/toast.js";
+export { createDesktopAdapter } from "./adapters/desktop.js";
+export { createTelegramAdapter } from "./adapters/telegram.js";
+export { createDiscordAdapter } from "./adapters/discord.js";