dexterm-cli 0.1.2 → 0.1.3

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

@@ -13,6 +13,8 @@ import { lowerTier, isTier, toolsForTier } from "./tiers.js";
 import { toolSchema, agentTool, toolsForTierList } from "./tools.js";
 import { isTopic, scrubStrings } from "./executor.js";
 import { TOOL_TO_KIND } from "./proposals.js";
+import { NAVIGATION_TOOLS } from "./tiers.js";
+import { maxDataAgeSec } from "./spectator.js";
 import { firewallText } from '../../data/src/index.js';
 export const BUS_PROTOCOL = 'dexterm-agent-bus/1';
 /** A connection that does not authenticate within this window is closed. */
@@ -27,6 +29,7 @@ export class AgentBus {
     executor;
     proposals;
     feed;
+    spectator;
     gate;
     now;
     paused = new Set();
@@ -39,6 +42,7 @@ export class AgentBus {
         this.executor = opts.executor;
         this.proposals = opts.proposals;
         this.feed = opts.feed ?? null;
+        this.spectator = opts.spectator ?? null;
         this.now = opts.now ?? (() => Date.now());
         this.discoveryPath = opts.discoveryPath === undefined ? join(dextermHome(opts.env), 'agent-bus.json') : opts.discoveryPath;
         this.gate = new AgentGate({
@@ -86,6 +90,7 @@ export class AgentBus {
         this.paused.add(a.id);
         this.registry.setPaused(name, true);
         this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'pause', tool: '-', detail: 'paused by the user', ok: false });
+        this.spectator?.emit({ phase: 'control', agent: name, tool: 'pause', summary: 'paused by the user', ok: true });
         return true;
     }
     resumeAgent(name) {
@@ -96,6 +101,7 @@ export class AgentBus {
         this.registry.setPaused(name, false);
         this.gate.clearFlood(a.id);
         this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'resume', tool: '-', detail: 'resumed by the user', ok: true });
+        this.spectator?.emit({ phase: 'control', agent: name, tool: 'resume', summary: 'resumed by the user', ok: true });
         return true;
     }
     /** Kick: close every live session for an agent now (the token keeps working — use `rotate`/`remove` to revoke it). */
@@ -115,6 +121,7 @@ export class AgentBus {
                 n++;
             }
         this.audit.append({ agentId: a.id, agentName: name, session: null, kind: 'kick', tool: '-', detail: `kicked ${n} session(s)`, ok: true });
+        this.spectator?.emit({ phase: 'control', agent: name, tool: 'kick', summary: `killed — ${n} session(s) closed`, ok: true });
         return n;
     }
     /** For the roster (tier 4): live sessions + usage per connected agent. */
@@ -154,8 +161,10 @@ export class AgentBus {
     onClose(conn) {
         if (conn.helloTimer)
             clearTimeout(conn.helloTimer);
-        if (conn.session)
+        if (conn.session) {
             this.audit.append({ agentId: conn.session.agentId, agentName: conn.session.agentName, session: conn.session.id, kind: 'disconnect', tool: '-', detail: 'socket closed', ok: true });
+            this.spectator?.emit({ phase: 'disconnect', agent: conn.session.agentName, tier: conn.session.tier, transport: 'bus', summary: conn.session.closedReason ? `disconnected (${conn.session.closedReason})` : 'disconnected', ok: true });
+        }
         this.conns.delete(conn);
     }
     reply(conn, id, result) { conn.ws.send({ jsonrpc: '2.0', id, result }); }
@@ -253,6 +262,7 @@ export class AgentBus {
             conn.helloTimer = null;
         }
         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.spectator?.emit({ phase: 'connect', agent: rec.name, tier, transport: 'bus', summary: `connected · ${client}${scope ? ` · mandate[${[...scope].join(',')}]` : ''}`, 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) {
@@ -265,9 +275,12 @@ export class AgentBus {
         const args = (params.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments)) ? params.arguments : {};
         const g = this.gate.check(session, { tool: name, args, schema: toolSchema(name) });
         if (!g.ok) {
+            // The tool name is agent-supplied; cap it (redactSpectatorEvent still masks any address/key in it).
+            this.spectator?.emit({ phase: 'refused', agent: session.agentName, tier: session.tier, transport: 'bus', tool: (name || '?').slice(0, 64), summary: `refused: ${g.error}`, refusal: g.code, ok: false });
             this.fail(conn, id, -32020, g.error, { code: g.code });
             return;
         }
+        const t0 = this.now();
         try {
             // bus-native observe
             if (name === 'agent_whoami') {
@@ -285,6 +298,7 @@ export class AgentBus {
             if (name === 'list_proposals') {
                 const limit = Math.min(Number(args.limit ?? 50), 100);
                 this.gate.record(session, name, `listed proposals`, 'call');
+                this.spectator?.emit({ phase: 'result', agent: session.agentName, tier: session.tier, transport: 'bus', tool: name, summary: 'listed proposals', ms: this.now() - t0, ok: true });
                 this.reply(conn, id, { proposals: this.proposals.list({ agentId: session.agentId, limit }) });
                 return;
             }
@@ -294,6 +308,7 @@ export class AgentBus {
                 if (duplicate)
                     this.gate.refundProposal(session.agentId);
                 this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'proposal', tool: name, detail: `${duplicate ? 'duplicate ' : ''}${proposal.summary}`, ok: true });
+                this.spectator?.emit({ phase: 'proposal', agent: session.agentName, tier: session.tier, transport: 'bus', tool: name, summary: `${duplicate ? 'duplicate ' : ''}${proposal.summary}`, ms: this.now() - t0, nav: navFor(name, args), ok: true });
                 this.reply(conn, id, { proposal, duplicate, note: 'This is a PROPOSAL. The user confirms it with a keypress; you can never arm, confirm or send it.' });
                 return;
             }
@@ -302,6 +317,9 @@ export class AgentBus {
             const result = scrubStrings(await this.executor.exec(session, name, args));
             const isErr = typeof result.error === 'string';
             this.gate.record(session, name, isErr ? `error: ${String(result.error).slice(0, 80)}` : summarise(name, args), name === 'agent_note' ? 'note' : 'call');
+            const nav = navFor(name, args);
+            const phase = nav ? 'nav' : name === 'agent_note' ? 'note' : 'result';
+            this.spectator?.emit({ phase, agent: session.agentName, tier: session.tier, transport: 'bus', tool: name, summary: isErr ? `error: ${String(result.error).slice(0, 80)}` : summarise(name, args), ms: this.now() - t0, dataAgeSec: isErr ? null : maxDataAgeSec(result), nav, ok: !isErr });
             this.reply(conn, id, result);
             return;
         }
@@ -340,6 +358,7 @@ export class AgentBus {
             }
         }
         this.audit.append({ agentId: session.agentId, agentName: session.agentName, session: session.id, kind: 'subscribe', tool: 'subscribe', detail: `+[${added.join(',')}]`, ok: true });
+        this.spectator?.emit({ phase: 'subscribe', agent: session.agentName, tier: session.tier, transport: 'bus', tool: 'subscribe', summary: `subscribed +[${added.join(',')}]`, ok: true });
         // push an immediate snapshot per newly-added topic, if the feed offers one
         if (this.feed?.snapshot)
             for (const t of added) {
@@ -382,6 +401,23 @@ export class AgentBus {
         catch { /* discovery is best-effort; the port can also be passed explicitly */ }
     }
 }
+/** The screen move a navigation / watchlist / ticket tool asks for (task-1406, for follow mode). */
+function navFor(tool, args) {
+    const s = (v) => (typeof v === 'string' ? v : undefined);
+    if (tool === 'open_token')
+        return { screen: 'token', mint: s(args.mint) };
+    if (tool === 'switch_feed')
+        return { screen: 'screener', feed: s(args.feed) };
+    if (tool === 'show_in_screener')
+        return { screen: 'screener', filter: s(args.filter), highlight: s(args.highlight) };
+    if (tool === 'add_to_watchlist')
+        return { screen: 'watchlist', mint: s(args.mint) };
+    if (tool === 'open_ticket')
+        return { screen: 'ticket', mint: s(args.mint), side: s(args.side) };
+    if (NAVIGATION_TOOLS.has(tool))
+        return { screen: 'screener' };
+    return null;
+}
 function summarise(name, args) {
     const mint = typeof args.mint === 'string' ? args.mint.slice(0, 6) + '…' : '';
     if (mint)

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

@@ -0,0 +1,105 @@
+// @dexterm/agents — follow mode (task-1406). The in-terminal, local view of an agent driving dexterm:
+// it folds the spectator event stream into a SCREEN MODEL (what the terminal should be showing) and an
+// ACTIVITY panel (recent calls with agent badge, timing and data ages), and exposes the owner's
+// controls: pause / take over / kill (panic). Controls delegate to an AgentControls interface the bus
+// implements (pauseAgent / resumeAgent / kickAgent) — this module can never arm, sign or raise a cap;
+// it only drives the SAME user-side controls the roster popup already has.
+function emptyScreen() {
+    return { screen: 'screener', selectedMint: null, feed: null, filter: null, highlight: null, ticketSide: null, watchlist: [], lastNavAt: null };
+}
+export class FollowController {
+    controls;
+    activityCap;
+    screen = emptyScreen();
+    activityRing = [];
+    agents = new Map();
+    control = 'agent';
+    lastSeq = 0;
+    constructor(opts = {}) {
+        this.controls = opts.controls ?? null;
+        this.activityCap = Math.max(1, opts.activityCap ?? 50);
+    }
+    /** Fold one spectator event into the screen model + activity + per-agent state. */
+    apply(ev) {
+        this.lastSeq = Math.max(this.lastSeq, ev.seq);
+        this.activityRing.push(ev);
+        if (this.activityRing.length > this.activityCap)
+            this.activityRing.splice(0, this.activityRing.length - this.activityCap);
+        const st = this.agents.get(ev.agent) ?? { name: ev.agent, tier: ev.tier ?? null, status: 'active', lastAt: ev.t };
+        st.lastAt = ev.t;
+        if (ev.tier)
+            st.tier = ev.tier;
+        if (ev.phase === 'connect')
+            st.status = 'active';
+        if (ev.phase === 'disconnect' && st.status !== 'killed')
+            st.status = st.status === 'paused' ? 'paused' : 'active';
+        this.agents.set(ev.agent, st);
+        // The agent driving the screen (navigation tools emit a nav block).
+        if (ev.phase === 'nav' && ev.nav) {
+            const n = ev.nav;
+            this.screen.lastNavAt = ev.t;
+            if (n.screen)
+                this.screen.screen = n.screen;
+            if (n.mint !== undefined)
+                this.screen.selectedMint = n.mint ?? null;
+            if (n.feed !== undefined)
+                this.screen.feed = n.feed ?? null;
+            if (n.filter !== undefined)
+                this.screen.filter = n.filter ?? null;
+            if (n.highlight !== undefined)
+                this.screen.highlight = n.highlight ?? null;
+            if (n.side !== undefined)
+                this.screen.ticketSide = n.side ?? null;
+            if (n.screen === 'watchlist' && n.mint && !this.screen.watchlist.includes(n.mint))
+                this.screen.watchlist.push(n.mint);
+        }
+    }
+    // ----- the owner's controls (pause / take over / kill). Each delegates to the bus. -----
+    /** Pause the agent: its next call is refused; it stays connected and visible. */
+    pause(name) {
+        const ok = this.controls?.pauseAgent(name) ?? false;
+        if (ok)
+            this.setStatus(name, 'paused');
+        return ok ? `paused ${name}` : `no agent ${name}`;
+    }
+    resume(name) {
+        const ok = this.controls?.resumeAgent(name) ?? false;
+        if (ok) {
+            this.setStatus(name, 'active');
+            this.control = 'agent';
+        }
+        return ok ? `resumed ${name}` : `no agent ${name}`;
+    }
+    /** Take over: pause the agent and mark the human as driving. The agent is frozen but still visible. */
+    takeOver(name) {
+        const ok = this.controls?.pauseAgent(name) ?? false;
+        if (ok) {
+            this.setStatus(name, 'paused');
+            this.control = 'user';
+        }
+        return ok ? `took over from ${name} — you are driving (agent frozen)` : `no agent ${name}`;
+    }
+    /** Kill (panic): close every live session for the agent now, and keep it paused so a reconnect is frozen. */
+    kill(name) {
+        const n = this.controls?.kickAgent(name) ?? 0;
+        this.controls?.pauseAgent(name);
+        this.setStatus(name, 'killed');
+        this.control = 'user';
+        return `killed ${name} (${n} session${n === 1 ? '' : 's'} closed; paused)`;
+    }
+    setStatus(name, status) {
+        const st = this.agents.get(name) ?? { name, tier: null, status, lastAt: Date.now() };
+        st.status = status;
+        this.agents.set(name, st);
+    }
+    view() {
+        return {
+            screen: { ...this.screen, watchlist: [...this.screen.watchlist] },
+            activity: [...this.activityRing],
+            agents: [...this.agents.values()].map((a) => ({ ...a })),
+            control: this.control,
+        };
+    }
+    get screenModel() { return { ...this.screen, watchlist: [...this.screen.watchlist] }; }
+    get controlState() { return this.control; }
+}

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

@@ -13,3 +13,8 @@ export * from "./ws.js";
 export * from "./executor.js";
 export * from "./proposals.js";
 export * from "./bus.js";
+// task-1406 "watch the agent cook": the spectator event model + redaction + save/replay, the local
+// follow-mode controller (pause / take over / kill), and the read-only loopback spectator stream.
+export * from "./spectator.js";
+export * from "./follow.js";
+export * from "./spectator-server.js";

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

@@ -0,0 +1,153 @@
+// @dexterm/agents — the read-only spectator STREAM (task-1406). A loopback-only WebSocket a streamer (or
+// a capture tool) can watch the agent's session through. It is OUTBOUND ONLY: the server is constructed
+// with a SpectatorHub and nothing else — no bus, no registry, no executor, no controls — so there is no
+// code path from the socket to anything mutable. The ONLY inbound messages it honors are `hello` (auth
+// with the per-session token) and `ping`; every other inbound frame is counted as `dropped` and ignored.
+// Every event leaving the server is REDACTED (wallet addresses, keys, sensitive fields). This is how the
+// stream "cannot send commands back" — structurally, not by a filter that could be bypassed.
+import { writeFileSync, rmSync, mkdirSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { createWsServer } from "./ws.js";
+import { dextermHome } from "./identity.js";
+import { SPECTATOR_PROTOCOL, redactSpectatorEvent } from "./spectator.js";
+/** A connection that does not authenticate within this window is closed. */
+export const SPECTATOR_HELLO_TIMEOUT_MS = 10_000;
+/** Overall cap on simultaneous spectator sockets. */
+export const SPECTATOR_MAX_CONNS = 32;
+export class SpectatorServer {
+    server = null;
+    conns = new Set();
+    hub;
+    now;
+    backlog;
+    discoveryPath;
+    token;
+    droppedCount = 0;
+    constructor(opts) {
+        this.hub = opts.hub;
+        this.now = opts.now ?? (() => Date.now());
+        this.backlog = Math.max(0, opts.backlog ?? 200);
+        this.token = opts.token ?? randomBytes(32).toString('base64url');
+        this.discoveryPath = opts.discoveryPath === undefined ? join(dextermHome(opts.env), 'spectator.json') : opts.discoveryPath;
+    }
+    get port() { return this.server?.port ?? 0; }
+    get connectionCount() { return this.conns.size; }
+    /** Inbound frames that were ignored because the stream is outbound-only (anything but hello/ping). */
+    get dropped() { return this.droppedCount; }
+    async start() {
+        this.server = await createWsServer({ port: undefined, onConnection: (ws) => this.onConnection(ws) });
+        this.writeDiscovery();
+        return this.server.port;
+    }
+    async close() {
+        for (const c of [...this.conns]) {
+            c.off?.();
+            if (c.helloTimer)
+                clearTimeout(c.helloTimer);
+            try {
+                c.ws.close(1001);
+            }
+            catch { /* ignore */ }
+        }
+        this.conns.clear();
+        if (this.discoveryPath) {
+            try {
+                rmSync(this.discoveryPath);
+            }
+            catch { /* ignore */ }
+        }
+        if (this.server) {
+            await this.server.close();
+            this.server = null;
+        }
+    }
+    onConnection(ws) {
+        if (this.conns.size >= SPECTATOR_MAX_CONNS) {
+            ws.close(1013);
+            return;
+        }
+        const conn = { ws, authed: false, off: null, helloTimer: null };
+        this.conns.add(conn);
+        conn.helloTimer = setTimeout(() => { if (!conn.authed) {
+            try {
+                ws.close(4001);
+            }
+            catch { /* ignore */ }
+        } }, SPECTATOR_HELLO_TIMEOUT_MS);
+        conn.helloTimer.unref?.();
+        ws.onMessage = (text) => this.onMessage(conn, text);
+        ws.onClose = () => this.onClose(conn);
+    }
+    onClose(conn) {
+        if (conn.helloTimer)
+            clearTimeout(conn.helloTimer);
+        conn.off?.();
+        this.conns.delete(conn);
+    }
+    onMessage(conn, text) {
+        if (text.length > 64 * 1024) {
+            conn.ws.close(1009);
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            this.droppedCount++;
+            return;
+        }
+        const method = msg && typeof msg === 'object' ? msg.method : undefined;
+        if (method === 'hello') {
+            this.onHello(conn, msg.token);
+            return;
+        }
+        if (method === 'ping') {
+            conn.ws.send({ type: 'pong', t: this.now() });
+            return;
+        }
+        // Outbound-only: anything else is ignored. There is NO branch that reaches a control.
+        this.droppedCount++;
+    }
+    onHello(conn, token) {
+        if (conn.authed)
+            return;
+        if (typeof token !== 'string' || !this.tokenOk(token)) {
+            try {
+                conn.ws.close(4002);
+            }
+            catch { /* ignore */ }
+            return;
+        }
+        conn.authed = true;
+        if (conn.helloTimer) {
+            clearTimeout(conn.helloTimer);
+            conn.helloTimer = null;
+        }
+        conn.ws.send({ type: 'welcome', protocol: SPECTATOR_PROTOCOL, redacted: true, t: this.now() });
+        for (const ev of this.hub.recent(this.backlog))
+            conn.ws.send(this.frame(ev, true));
+        conn.off = this.hub.on((ev) => conn.ws.send(this.frame(ev, false)));
+    }
+    frame(ev, snapshot) {
+        return { type: 'event', snapshot, event: redactSpectatorEvent(ev) };
+    }
+    tokenOk(given) {
+        const a = Buffer.from(given), b = Buffer.from(this.token);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    writeDiscovery() {
+        if (!this.discoveryPath)
+            return;
+        try {
+            mkdirSync(dirname(this.discoveryPath), { recursive: true, mode: 0o700 });
+            writeFileSync(this.discoveryPath, JSON.stringify({ protocol: SPECTATOR_PROTOCOL, port: this.port, token: this.token, pid: process.pid, startedAt: this.now() }, null, 2) + '\n', { mode: 0o600 });
+            try {
+                chmodSync(this.discoveryPath, 0o600);
+            }
+            catch { /* ignore */ }
+        }
+        catch { /* discovery is best-effort */ }
+    }
+}

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