dexterm-cli 0.1.1 → 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 }); }
@@ -192,7 +201,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 +254,16 @@ 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.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) {
         const session = conn.session;
@@ -264,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') {
@@ -284,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;
             }
@@ -293,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;
             }
@@ -301,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;
         }
@@ -309,7 +328,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;
@@ -325,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) {
@@ -367,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/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/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/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/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 */ }
+    }
+}