dexterm-cli 0.1.3 → 0.1.4

package/dist/packages/cli/src/main.js

@@ -29,6 +29,7 @@ import { makeFixtureState, makeFeedState, syncFeed, renderFrame, isScreenKey, ac
 import { mulberry32, tick, spawnPair, shock } from "./fixtures.js";
 import { createLiveFeed, createReplayFeed } from "./feed.js";
 import { LiveContext, INTERVALS, WATCH_REFRESH_MS, POSITIONS_REFRESH_MS, popupBubbleVM } from "./live/index.js";
+import { McpFollowSession } from "./mcp-follow.js";
 import { TOKEN_REFRESH_MS, CandlePrefetcher } from "./live/token.js";
 import { PRESETS, presetSpec } from "./screener/presets.js";
 import { parseSortArg, SORT_KEYS } from "./screener/sort.js";
@@ -272,6 +273,7 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   dexterm alerts status|enable|disable|set-telegram|set-discord|test  where rule alerts are delivered (desktop / your Telegram / Discord; creds stay local, never logged)
   dexterm watch [--interval S] [--once] [--replay FILE]  run your rules headless and push alerts when the terminal is closed (no signer, proposals only)
   dexterm record run|install|uninstall|status  keep the history recorder fed with no TUI open, as a user-level launchd agent (no network beyond the data layer; 'dexterm record help')
+  dexterm larp-detected --out DIR [--db PATH]  build timestamped high-risk follow-up drafts/cards from recorder history; never posts
   dexterm --fixtures                          interactive demo on seeded fixtures
   dexterm --screen <name>                     one-shot frame to stdout (live)
   dexterm --screen <name> --fixtures          one-shot frame from fixtures
@@ -284,6 +286,8 @@ export const HELP = `dexterm ${VERSION} (live: screener, token, new pairs, watch
   --sort KEY[:asc|desc]     ${SORT_KEYS.map((k) => k.key).join(' | ')}
   --preset NAME             ${PRESETS.map((p) => p.id).join(' | ')}
   --record FILE             save every live response (and the PumpPortal session) to FILE (replay it with --replay)
+  --spectate-mcp            follow an MCP agent's allowed navigation in this terminal; Ctrl+P pauses, Ctrl+K stops,
+                            and any normal user keypress takes control (refused actions never move the UI)
   --max-requests N          hard cap on live requests for this run (default: none)
   --max-credits N           hard cap on Helius credits for this run (default: 5000)
   --mint MINT|LINK          token to open on the token screen (a CA or a dexscreener / pump.fun / solscan / birdeye link)
@@ -392,6 +396,7 @@ export function parseArgs(argv) {
         sound: false,
         trade: [], live: true,
         workspace: null, priceMode: null,
+        spectateMcp: false,
         help: false, version: false, unknown: [],
     };
     for (let i = 0; i < argv.length; i++) {
@@ -573,6 +578,9 @@ export function parseArgs(argv) {
                 throw new Error(`--price-mode expects price|mcap, got ${JSON.stringify(s.slice(0, 20))}`);
             a.priceMode = s;
         }
+        // task-1421: follow an agent driving over MCP (the running terminal moves with it; a read-only stream opens).
+        else if (k === '--spectate-mcp')
+            a.spectateMcp = true;
         else if (k === '--workspace') {
             const s = str();
             if (!/^[a-z][a-z0-9-]{0,39}(\/[a-z][a-z0-9-]{0,39})?$/.test(s))
@@ -790,6 +798,11 @@ export async function main(argv, io = process, proc = process) {
         const { backtestCommand } = await import("./backtest-cmd.js");
         return backtestCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
     }
+    // Local-only marketing evidence pipeline (task-1433): drafts and cards for human review, never posts.
+    if (argv[0] === 'larp-detected') {
+        const { larpDetectedCommand } = await import("./larp-detected.js");
+        return larpDetectedCommand(argv.slice(1), { stdout: io.stdout, stderr: io.stderr, env: io.env });
+    }
     // `dexterm kol …` → KOL lists on the shared DB (task-1330): list/create/add/remove/mute/unmute/enable/disable/import.
     if (argv[0] === 'kol')
         return kolCommand(argv.slice(1), io);
@@ -2895,6 +2908,76 @@ export function applyAnalystAction(state, raw, stack) {
     times.push(now);
     return { ok: true, label: res.label };
 }
+/**
+ * task-1421: move the REAL terminal to mirror an agent's navigation (follow mode, on the owner's own
+ * machine). This is the same VIEW-ONLY navigation the analyst / go-to path uses — open a token, switch
+ * screen/feed, set a filter, highlight a row, open the PAPER ticket editor. It never trades, sizes, confirms
+ * or signs, and the key loop flips control to the user before any of it runs, so the human always wins the
+ * screen. Unlike the analyst boundary it does not re-check the on-screen allow-list: the agent already made
+ * the call on its own server and this only reflects where it went. A no-op when live navigation is off.
+ */
+export function applyFollowNav(state, nav, stack) {
+    const sc = state.screener;
+    const live = state.live && state.screener.source !== 'fixtures' ? state.live : null;
+    const toScreen = (next) => { if (state.screen !== next) {
+        stack.push(state.screen);
+        state.screen = next;
+    } };
+    if (nav.mint && (!nav.screen || nav.screen === 'token')) {
+        if (!live)
+            return;
+        try {
+            live.openToken(seedForMint(state, live, nav.mint));
+            toScreen('token');
+        }
+        catch { /* a stale mint never breaks follow */ }
+        return;
+    }
+    if (nav.screen === 'ticket') {
+        if (!live || !nav.mint)
+            return;
+        try {
+            const seed = seedForMint(state, live, nav.mint);
+            live.openTicket({ mint: seed.mint, symbol: seed.symbol, name: seed.name }, nav.side === 'sell' ? 'sell' : 'buy');
+            toScreen('ticket');
+        }
+        catch { /* ignore */ }
+        return;
+    }
+    if (nav.screen === 'watchlist') {
+        if (live && nav.mint) {
+            try {
+                if (!live.watch.has(nav.mint))
+                    live.watch.add(LiveContext.candidate(seedForMint(state, live, nav.mint)));
+            }
+            catch { /* ignore */ }
+        }
+        toScreen('watchlist');
+        return;
+    }
+    if (nav.feed || nav.filter || nav.highlight || nav.screen === 'screener') {
+        toScreen('screener');
+        if (nav.feed) {
+            if (setPreset(sc, nav.feed) && state.feed)
+                state.feed.setPreset(sc.preset);
+        }
+        if (nav.filter) {
+            try {
+                setFilter(sc, nav.filter);
+            }
+            catch { /* an invalid agent filter is ignored */ }
+        }
+        if (nav.highlight) {
+            const i = screenerView(sc).findIndex((r) => r.mint === nav.highlight);
+            if (i >= 0)
+                state.selected = i;
+        }
+        state.selected = clampSelection(sc, state.selected);
+        return;
+    }
+    if (nav.screen && isScreenKey(nav.screen))
+        toScreen(nav.screen);
+}
 /**
  * task-1413: apply an accepted tier-(b) config proposal through the journaled path as actor `analyst`
  * (so `ctrl+z` undoes it), creating the parent section when absent (exactly like the `$` / `,` handlers),
@@ -3730,6 +3813,9 @@ export function interactive(state, io, depth, args, proc = process) {
         let timer = null;
         let lastRefresh = 0;
         let done = false;
+        // task-1421: the MCP follow session (set below when `--spectate-mcp` is on). Declared here so the quit /
+        // terminal-guard teardown closures can stop it.
+        let followSession = null;
         // Idle economy (task-1303, retuned for task-1319 AC3): between events the ambient rain redraws at
         // IDLE_FPS instead of the full frame cap, cutting idle CPU. A keypress opens a KEY_WAKE_S full-rate
         // window (`wakeUntil`) so input and transitions stay smooth; data landings paint at once on their own
@@ -3759,7 +3845,7 @@ export function interactive(state, io, depth, args, proc = process) {
                 }
             };
         const guard = terminalGuard(io, () => { done = true; prefetcher?.close(); if (timer)
-            clearInterval(timer); state.analyst?.cancel(); if (state.analystByMint)
+            clearInterval(timer); void followSession?.stop(); state.analyst?.cancel(); if (state.analystByMint)
             for (const s of state.analystByMint.values())
                 s.cancel(); state.popups?.shutdown(); voice?.disable(); images?.close(); live?.close(); feed?.close(); }, proc, { beforeLeave: () => layer?.teardown() ?? '' });
         let lastTokenRefresh = 0;
@@ -3930,6 +4016,37 @@ export function interactive(state, io, depth, args, proc = process) {
         // task-1326: an image landing (decoded, or found missing) repaints at most once per macrotask.
         if (images)
             images.onChange = () => scheduleDraw();
+        // task-1421: `--spectate-mcp` → follow an agent driving over MCP. The rendezvous lets a `dexterm mcp`
+        // server the external client spawned emit here; we tail it, move the terminal for navigation calls, and
+        // the owner's controls (ctrl+p pause/resume · ctrl+k stop · any key = take over) are handled in onInput.
+        // A read-only, loopback, token-gated stream opens too (`dexterm spectate --info`). Off (and zero-cost)
+        // unless the flag is set; nothing it folds can arm, sign, confirm, send or raise a cap.
+        if (args.spectateMcp) {
+            followSession = new McpFollowSession({
+                env: io.env,
+                stream: true,
+                onNav: (nav) => {
+                    const before = state.screen;
+                    try {
+                        applyFollowNav(state, nav, stack);
+                    }
+                    catch { /* a stale mint never breaks follow */ }
+                    if (state.screen !== before) {
+                        try {
+                            startTransition();
+                        }
+                        catch {
+                            transition = null;
+                        }
+                    }
+                    scheduleDraw();
+                },
+                onStatus: (line) => { say(line, 'ai', 4); scheduleDraw(); },
+                onEvent: () => scheduleDraw(),
+            });
+            void followSession.start();
+            say('following agents over MCP · ctrl+p pause · ctrl+k stop · any key takes over', 'ai', 6);
+        }
         // Launch a real Claude analyst session when a key asked for one (applyAction cannot spawn). A
         // `question` means start it as a chat turn, not a paid structured skill run (task-1311, QA B3).
         const beginAnalyst = () => {
@@ -4919,6 +5036,7 @@ export function interactive(state, io, depth, args, proc = process) {
             prefetcher?.close();
             if (timer)
                 clearInterval(timer);
+            void followSession?.stop();
             guard.restore();
             guard.uninstall();
             cancelAllAnalysts();
@@ -4973,6 +5091,27 @@ export function interactive(state, io, depth, args, proc = process) {
                     quit();
                     return;
                 }
+                // task-1421 follow-mode controls (only while following an MCP agent). ctrl+p pauses / resumes the
+                // terminal mirroring; ctrl+k stops following (removes the rendezvous so the server stops emitting);
+                // ANY other key while the agent is driving hands control to the user — the human and the agent never
+                // fight over the screen. The control keys are consumed; the take-over key still does its own job.
+                if (followSession) {
+                    if (key.ctrl && key.ch === 'k') {
+                        followSession.kill();
+                        draw();
+                        continue;
+                    }
+                    if (key.ctrl && key.ch === 'p') {
+                        if (followSession.isPaused)
+                            followSession.resume();
+                        else
+                            followSession.pause();
+                        draw();
+                        continue;
+                    }
+                    if (followSession.controlState === 'agent')
+                        followSession.userKey(); // take over, then fall through
+                }
                 // task-1413: a pending analyst config PROPOSAL owns the next key. `y` accepts and journals it as
                 // actor 'analyst' (ctrl+z undoes); any other key dismisses it. A stray key never persists a change.
                 // Two guards (defect c): the proposal does NOT steal a key while a TEXT INPUT is open — the GO-TO

package/dist/packages/cli/src/mcp-follow.js

@@ -0,0 +1,225 @@
+// `dexterm` TUI — follow an agent that is driving over MCP (task-1421, "see what your agent is doing").
+//
+// The running terminal can WATCH and visibly FOLLOW an agent connected through `dexterm mcp` (Claude Code,
+// Cursor, Codex, Claude Desktop, …). That MCP server is a separate process the external client spawned, so
+// the app cannot set its env; instead this session, while it is open, writes the ~/.dexterm rendezvous the
+// server reads (packages/mcp spectator-sink) and tails the JSONL channel the server appends to. Each record
+// is folded into a SpectatorHub → a FollowController (the AGENT ACTIVITY panel + a SCREEN model) and, for
+// navigation calls, moved into the REAL terminal through the caller's onNav hook (open a token, switch
+// screen/feed/filter, highlight). Owner's own machine → follow mode is unredacted; the optional read-only
+// stream (SpectatorServer) redacts every copy that leaves the hub, exactly as in task-1406.
+//
+// It adds NO power. A record only DESCRIBES a read/navigation call the gate already allowed; there is no
+// inbound path from here to anything that can arm, sign, confirm, send or raise a cap. "pause / take over /
+// kill" are local follow controls: pause/take-over stop the terminal mirroring the agent (the external agent
+// keeps running — we simply stop moving the screen), and kill removes the rendezvous so the server stops
+// emitting. Any user keypress during an agent move takes control, so the human and the agent never fight.
+import { writeFileSync, readFileSync, rmSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { SpectatorHub, FollowController, SpectatorServer, } from '../../agents/src/index.js';
+import { rendezvousPath } from '../../mcp/src/index.js';
+function navLabel(agent, nav) {
+    const coin = nav.mint ? ` ${nav.mint.length > 10 ? nav.mint.slice(0, 4) + '…' + nav.mint.slice(-4) : nav.mint}` : '';
+    if (nav.screen === 'token')
+        return `agent ${agent}: opened${coin}`;
+    if (nav.screen === 'ticket')
+        return `agent ${agent}: opened the ${nav.side ?? ''} ticket${coin}`;
+    if (nav.screen === 'watchlist')
+        return `agent ${agent}: watchlisted${coin}`;
+    if (nav.feed)
+        return `agent ${agent}: switched the feed to ${nav.feed}`;
+    if (nav.filter)
+        return `agent ${agent}: filtered ${nav.filter}`;
+    if (nav.highlight)
+        return `agent ${agent}: highlighted ${nav.highlight.length > 10 ? nav.highlight.slice(0, 4) + '…' + nav.highlight.slice(-4) : nav.highlight}`;
+    if (nav.screen)
+        return `agent ${agent}: switched to ${nav.screen}`;
+    return `agent ${agent}: navigated`;
+}
+/**
+ * A follow session for one running terminal. Call start() to arm the rendezvous and begin tailing, pump()
+ * to process new records (the timer does this for you), the controls to pause/take-over/kill, userKey() when
+ * the human presses any key, and stop() to tear everything down. Never throws into the key loop.
+ */
+export class McpFollowSession {
+    hub;
+    follow;
+    opts;
+    rvPath;
+    channelPath;
+    token;
+    agentLabel;
+    currentAgent;
+    offset = 0;
+    timer = null;
+    stream = null;
+    armed = false;
+    paused = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.agentLabel = opts.agentLabel || 'mcp-agent';
+        this.currentAgent = this.agentLabel;
+        this.rvPath = rendezvousPath(opts.env);
+        this.channelPath = this.rvPath.replace(/\.json$/, '.jsonl');
+        this.token = randomBytes(24).toString('hex');
+        this.hub = new SpectatorHub({ cap: Math.max(1, opts.activityCap ?? 200) });
+        const controls = {
+            pauseAgent: () => true,
+            resumeAgent: () => { this.rearm(); return true; },
+            kickAgent: () => { this.disarm(); return 1; },
+        };
+        this.follow = new FollowController({ controls, activityCap: Math.max(1, opts.activityCap ?? 200) });
+        this.hub.on((ev) => this.follow.apply(ev));
+    }
+    /** Arm the rendezvous (so a `dexterm mcp` server starts emitting) and begin tailing. Idempotent. */
+    async start() {
+        this.rearm();
+        if (this.opts.stream) {
+            try {
+                this.stream = new SpectatorServer({ hub: this.hub, env: this.opts.env });
+                await this.stream.start();
+            }
+            catch {
+                this.stream = null;
+            }
+        }
+        if (!this.timer) {
+            this.timer = setInterval(() => this.pump(), Math.max(30, this.opts.pollMs ?? 150));
+            this.timer.unref?.();
+        }
+    }
+    /** Write (or re-write) the channel + rendezvous so the server emits here. */
+    rearm() {
+        try {
+            mkdirSync(dirname(this.rvPath), { recursive: true });
+            if (!this.armed) {
+                writeFileSync(this.channelPath, '', { mode: 0o600 });
+                this.offset = 0;
+            }
+            writeFileSync(this.rvPath, JSON.stringify({ file: this.channelPath, token: this.token, agent: this.agentLabel }) + '\n', { mode: 0o600 });
+            this.armed = true;
+        }
+        catch { /* best-effort local channel */ }
+    }
+    /** Remove the rendezvous so the server stops emitting (the external agent keeps running; we stop seeing it). */
+    disarm() {
+        try {
+            // A second follow surface may have replaced the rendezvous after this session started.  Never remove
+            // another surface's live handle when this one pauses, is killed, or exits.
+            const current = JSON.parse(readFileSync(this.rvPath, 'utf8'));
+            if (current.token === this.token)
+                rmSync(this.rvPath, { force: true });
+        }
+        catch { /* absent/malformed/another surface owns it */ }
+        this.armed = false;
+    }
+    /** Read and fold any records appended since the last pump. Public so tests can drive it without timers. */
+    pump() {
+        let text;
+        try {
+            const st = statSync(this.channelPath);
+            if (st.size <= this.offset) {
+                if (st.size < this.offset)
+                    this.offset = 0;
+                else
+                    return;
+            }
+            text = readFileSync(this.channelPath, 'utf8');
+        }
+        catch {
+            return;
+        }
+        const slice = text.slice(this.offset);
+        const nl = slice.lastIndexOf('\n');
+        if (nl < 0)
+            return; // no complete line yet
+        this.offset += nl + 1;
+        for (const line of slice.slice(0, nl).split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(t);
+            }
+            catch {
+                continue;
+            }
+            this.ingest(rec);
+        }
+    }
+    /** Fold one record: verify its token, strip it, emit into the hub, and move the terminal for a nav call. */
+    ingest(rec) {
+        if (typeof rec.phase !== 'string')
+            return;
+        // Only accept records written by the server we handed our token to (local 0600 file; defence in depth).
+        if (rec.token !== this.token)
+            return;
+        this.currentAgent = typeof rec.agent === 'string' && rec.agent ? rec.agent : this.agentLabel;
+        // The token NEVER enters the hub / activity / stream — fold only the observable fields.
+        const ev = this.hub.emit({
+            phase: rec.phase,
+            agent: this.currentAgent,
+            transport: 'mcp',
+            tool: rec.tool ?? null,
+            summary: rec.summary,
+            ms: rec.ms ?? null,
+            dataAgeSec: rec.dataAgeSec ?? null,
+            nav: rec.nav ?? null,
+            ok: rec.ok ?? true,
+            t: typeof rec.t === 'number' ? rec.t : undefined,
+        });
+        // Move the real terminal ONLY while the agent has control (a user keypress / take-over / kill flips this).
+        if (ev.phase === 'nav' && ev.ok !== false && ev.nav && this.canFollow()) {
+            const label = navLabel(this.currentAgent, ev.nav);
+            try {
+                this.opts.onNav?.(ev.nav, label);
+            }
+            catch { /* a bad hook never breaks the tail */ }
+            try {
+                this.opts.onStatus?.(label);
+            }
+            catch { /* ignore */ }
+        }
+        try {
+            this.opts.onEvent?.();
+        }
+        catch { /* ignore */ }
+    }
+    /** True when the terminal should mirror the agent: the agent still has control and is active. */
+    canFollow() {
+        if (this.follow.controlState !== 'agent')
+            return false;
+        const st = this.follow.view().agents.find((a) => a.name === this.currentAgent);
+        return !st || st.status === 'active';
+    }
+    // ----- the owner's controls. Each returns a short line to toast. -----
+    pause() { const l = this.follow.pause(this.currentAgent); this.paused = l.startsWith('paused '); this.opts.onStatus?.(l); return l; }
+    takeOver() { const l = this.follow.takeOver(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    resume() { const l = this.follow.resume(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    kill() { const l = this.follow.kill(this.currentAgent); this.paused = false; this.opts.onStatus?.(l); return l; }
+    /** Any physical keypress while the agent is driving: the human takes over (no fight over the screen). */
+    userKey() { if (this.follow.controlState === 'agent')
+        this.takeOver(); }
+    get controlState() { return this.follow.controlState; }
+    get isPaused() { return this.paused; }
+    get screenModel() { return this.follow.screenModel; }
+    get streamPort() { return this.stream?.port ?? 0; }
+    view() { return this.follow.view(); }
+    /** Tear down: stop the timer, remove the rendezvous, close the stream. Safe to call more than once. */
+    async stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+        this.disarm();
+        if (this.stream) {
+            try {
+                await this.stream.close();
+            }
+            catch { /* ignore */ }
+            this.stream = null;
+        }
+    }
+}

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

@@ -8,6 +8,7 @@
 // Replay is deterministic and offline. The live stream itself is started by `dexterm agent serve --spectate`;
 // it is read-only, loopback-only and token-gated, and redacts wallet addresses/keys (see SPECTATOR.md).
 import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { FollowController, loadSpectatorRecording } from '../../agents/src/index.js';
 function flag(rest, name) { const i = rest.indexOf(name); return i >= 0 ? rest[i + 1] : undefined; }
@@ -15,7 +16,18 @@ function has(rest, name) { return rest.includes(name); }
 const USAGE = `dexterm spectate <command>
   --replay FILE [--json]   replay a saved session (fold agent actions into the screen + activity panel)
   --info [--json]          show the live stream endpoint from ~/.dexterm/spectator.json (if streaming)
-read-only · redacts wallet addresses/keys · the live stream is started by \`dexterm agent serve --spectate\``;
+read-only · redacts wallet addresses/keys · the live stream is started by \`dexterm agent serve --spectate\`
+or by a running app in follow mode (\`dexterm --spectate-mcp\`, for an agent connected over MCP)
+Full docs: https://dexterm.xyz/docs/spectator/`;
+/**
+ * Where `agent serve --spectate` writes its discovery file: the same rule as the writer (@dexterm/agents
+ * `dextermHome`), so a blank DEXTERM_HOME falls back and a missing HOME (Windows) does not turn into a
+ * relative `.dexterm` under the current directory.
+ */
+export function spectatorInfoPath(env, home = homedir()) {
+    const dir = env.DEXTERM_HOME && env.DEXTERM_HOME.trim() ? env.DEXTERM_HOME : join(home, '.dexterm');
+    return join(dir, 'spectator.json');
+}
 function ago(t) { const s = Math.max(0, Math.round((Date.now() - t) / 1000)); return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : `${Math.floor(s / 3600)}h`; }
 function age(s) { if (s == null)
     return ''; return s < 60 ? ` · ${Math.round(s)}s old` : s < 3600 ? ` · ${Math.floor(s / 60)}m old` : ` · ${Math.floor(s / 3600)}h old`; }
@@ -75,8 +87,7 @@ export async function runSpectate(rest, io) {
         return 0;
     }
     if (has(rest, '--info')) {
-        const home = io.env.DEXTERM_HOME || join(io.env.HOME || '', '.dexterm');
-        const path = join(home, 'spectator.json');
+        const path = spectatorInfoPath(io.env);
         let info;
         try {
             info = JSON.parse(readFileSync(path, 'utf8'));

package/dist/packages/cli/src/version.js

@@ -1,3 +1,3 @@
 // The one place the app's version lives (task-1397). --version, the help banner and `dexterm update` read it;
 // cli.test.ts keeps it equal to packages/cli/package.json (release.yml refuses a tag that differs).
-export const VERSION = '0.1.3';
+export const VERSION = '0.1.4';

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

@@ -52,9 +52,15 @@ function printStatus(io, store, now) {
     else {
         io.stdout.write(`login: ${meta.user ? `@${meta.user.username} (id ${meta.user.id})` : 'logged in (handle unknown)'} · scopes ${meta.scopes.join(' ') || '—'} · access token ${meta.expiresAt !== null ? (meta.expiresAt > now ? `valid ${fmtIn(meta.expiresAt - now)}` : 'expired (refreshes on next use)') : '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no (login again)'}\n`);
     }
-    io.stdout.write(`files: ${store.dir} (mode ${oct(modes.dir)}) · tokens.json ${modes.tokens === null ? 'absent' : `mode ${oct(modes.tokens)}`} · client-id ${modes.clientId === null ? 'absent' : `mode ${oct(modes.clientId)}`}\n`);
-    if ((modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700))
-        io.stderr.write('⚠ permissions are looser than 0600/0700; dexterm will tighten them on the next write (or chmod them now)\n');
+    if (process.platform === 'win32') {
+        io.stdout.write(`files: ${store.dir} · tokens.json ${modes.tokens === null ? 'absent' : 'present'} · client-id ${modes.clientId === null ? 'absent' : 'present'} · Windows ACL isolation is not verified\n`);
+        io.stderr.write('Review the token directory Security permissions in Windows; chmod does not enforce owner-only ACLs.\n');
+    }
+    else {
+        io.stdout.write(`files: ${store.dir} (mode ${oct(modes.dir)}) · tokens.json ${modes.tokens === null ? 'absent' : `mode ${oct(modes.tokens)}`} · client-id ${modes.clientId === null ? 'absent' : `mode ${oct(modes.clientId)}`}\n`);
+        if ((modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700))
+            io.stderr.write('⚠ permissions are looser than 0600/0700; dexterm will tighten them on the next write (or chmod them now)\n');
+    }
     io.stdout.write(`callback: ${callbackUri()} · tokens are never printed, logged, or sent to a model · X reads are user-context only (your rate limits, your bill)\n`);
 }
 /** Run the `x` subcommand. Returns a process exit code. */
@@ -84,7 +90,7 @@ export async function runX(argv, io, over = {}) {
             io.stderr.write(`dexterm x set-client-id: ${e instanceof Error ? e.message : String(e)}\n`);
             return 2;
         }
-        io.stdout.write(`stored (${v.length} chars) at ${store.clientIdPath} (mode 600). Next: dexterm x login\n`);
+        io.stdout.write(`stored (${v.length} chars) at ${store.clientIdPath} (${process.platform === 'win32' ? 'Windows ACL isolation unverified' : 'mode 600'}). Next: dexterm x login\n`);
         return 0;
     }
     if (sub === 'login') {
@@ -101,7 +107,7 @@ export async function runX(argv, io, over = {}) {
             const res = await oauth.login({ env: io.env });
             clearTimeout(t);
             io.stdout.write(`✓ logged in${res.user ? ` as @${res.user.username}` : ''} · scopes ${res.scopes.join(' ')} · access token valid ${fmtIn(res.expiresAt - now())} · refresh ${res.hasRefresh ? 'yes' : 'no'} · browser ${Math.round(res.callbackMs / 100) / 10}s · exchange ${res.exchangeMs}ms\n`);
-            io.stdout.write(`tokens: ${store.tokensPath} (mode 600). The SOCIAL panel and TRENDING board now read X with your own limits.\n`);
+            io.stdout.write(`tokens: ${store.tokensPath} (${process.platform === 'win32' ? 'Windows ACL isolation unverified' : 'mode 600'}). The SOCIAL panel and TRENDING board now read X with your own limits.\n`);
             return 0;
         }
         catch (e) {

package/dist/packages/mcp/assets/kb/app-help/spectate-an-agent.md

@@ -15,10 +15,13 @@ tags:
   - replay
   - stream
   - record
+  - mcp
+  - follow
 commands:
   - spectate
 flags:
   - --replay
+  - --spectate-mcp
 confidence: high
 owner: maintainers
 origin: app-help-generated
@@ -31,6 +34,6 @@ sources:
 date: 2026-10-16
 ---
 
-`dexterm spectate --replay FILE` replays a saved agent session so you can watch what an agent did step by step; `dexterm spectate --info` shows the live read-only, token-gated, loopback spectator stream. The stream is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act.
+Watch an agent work. For an agent on the loopback bus, `dexterm agent serve --spectator-popup` opens the AGENT ACTIVITY window, `--spectate` starts the read-only, token-gated, loopback stream, and `--record FILE` saves a redacted session. For an agent connected over MCP (`dexterm mcp install`), run the app with `dexterm --spectate-mcp`: the running terminal then follows the agent — a navigation call moves the screen, a status line shows `agent <name>: opened <coin>`, ctrl+p pauses, ctrl+k stops and any key you press takes control. `dexterm spectate --replay FILE` replays a saved session step by step and `dexterm spectate --info` shows the live stream endpoint. Every shared copy is redacted — a tool name, refusal, agent line or navigation can never leak a wallet or key — and a spectator can only watch, never act. Full docs: https://dexterm.xyz/docs/spectator/
 
 CLI: `dexterm spectate`.

package/dist/packages/mcp/assets/kb/docs/docs-agents-capability-tiers-enforced-server-side.md

@@ -0,0 +1,38 @@
+---
+id: docs-agents-capability-tiers-enforced-server-side
+title: Bring your own agent › Capability tiers (enforced server-side)
+kind: docs
+page: agents
+page_title: Bring your own agent
+heading: Capability tiers (enforced server-side)
+anchor: capability-tiers-enforced-server-side
+url: https://dexterm.xyz/docs/agents#capability-tiers-enforced-server-side
+tags:
+  - docs
+  - agents
+  - capability
+  - tiers
+  - enforced
+  - server-side
+  - bring
+  - own
+  - agent
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/agents.md
+date: 2026-10-16
+---
+
+The tier comes from your registry at connection time, never from anything the agent sends; a client may only ask to run *below* its grant.
+
+| tier | what it can do |
+| --- | --- |
+| `observe` | read tools (screener, token, dossier, holders, trades, candles, rugcheck, dev history, the analysis packs `analyze_token` / `narrative_board` / `rug_backtest`, KB, cases, LARP checks) and live stream subscriptions |
+| `annotate` | + non-financial UI navigation and the agent's own notes/tags on coins |
+| `propose` | + proposals (alerts, order-plan drafts, watchlist adds) that appear **labelled with the agent** and that **you** confirm with a keypress |
+
+No tier can arm, sign, send, raise or change a cap, change the gate, or reach a wallet/mandate/signer: no such tool exists in the table, and a "never-list" refuses the *shape* of such a request before any lookup.

package/dist/packages/mcp/assets/kb/docs/docs-agents-install-in-one-command.md

@@ -0,0 +1,49 @@
+---
+id: docs-agents-install-in-one-command
+title: Bring your own agent › Install in one command
+kind: docs
+page: agents
+page_title: Bring your own agent
+heading: Install in one command
+anchor: install-in-one-command
+url: https://dexterm.xyz/docs/agents#install-in-one-command
+tags:
+  - docs
+  - agents
+  - install
+  - command
+  - bring
+  - own
+  - agent
+confidence: high
+owner: maintainers
+origin: docs-generated
+reviewed_by: generated@2026-10-16
+generated_from: dexterm/site content/docs (task-1420)
+sources:
+  - site/content/docs/agents.md
+date: 2026-10-16
+---
+
+`dexterm mcp install <client>` writes (or prints) the MCP config for your client. It prints the exact snippet, shows the file it will change, **asks first**, is **idempotent** (re-running changes nothing), and **backs the file up** before editing.
+
+```sh
+$ dexterm mcp install claude-code      # writes ./.mcp.json in this project (asks first)
+$ dexterm mcp install cursor           # writes ~/.cursor/mcp.json
+$ dexterm mcp install claude-desktop   # writes the Claude Desktop config for your OS
+$ dexterm mcp install codex            # appends [mcp_servers.dexterm] to ~/.codex/config.toml
+$ dexterm mcp install generic --print  # just print the snippet to paste anywhere
+$ dexterm mcp doctor                   # spawn the server and list the tools your agent will see
+```
+
+| client | what it writes |
+| --- | --- |
+| `claude-code` | project `.mcp.json` (or run `claude mcp add dexterm -- dexterm mcp`) |
+| `claude-desktop` | `claude_desktop_config.json` for your OS (restart the app after) |
+| `cursor` | `~/.cursor/mcp.json` |
+| `codex` | a `[mcp_servers.dexterm]` table in `~/.codex/config.toml` |
+| `generic` | prints a standard `mcpServers` entry to paste where your agent reads MCP servers (`--config FILE` writes it) |
+
+Flags: `--config FILE` writes to a specific file instead of the client default; `--print` only prints; `--node` emits a `node <path> mcp` command for when `dexterm` is not on your PATH; `--yes` skips the confirmation prompt. On a non-interactive shell the command prints the plan and writes nothing unless you pass `--yes`.
+
+`dexterm mcp doctor` spawns the server over stdio, does the MCP handshake, and lists the tools, prompts and resources the agent sees — proof the connection works before you point an agent at it.