dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/assets/claude/schemas/larp.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dexterm/claude-layer/larp",
+  "title": "LARP detector verdict (larp-check)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skill", "skill_version", "mint", "verdict", "confidence", "claims", "missing_data", "facts", "flags", "injection_detected", "sources_used", "summary"],
+  "properties": {
+    "skill": { "type": "string", "enum": ["larp-check"] },
+    "skill_version": { "type": "string" },
+    "mint": { "type": "string", "description": "The mint analysed, or empty string when AMBIGUOUS before resolution" },
+    "verdict": { "type": "string", "enum": ["REAL_PRODUCT", "EARLY_BUT_REAL", "LARP", "UNVERIFIABLE", "AMBIGUOUS"] },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "summary": { "type": "string", "maxLength": 600, "description": "Two to four short lines for a 40-column panel: the verdict in plain words and the strongest evidence. Never a disclaimer line" },
+    "claims": {
+      "type": "array",
+      "description": "Each product claim the site/socials make, with the evidence for or against it.",
+      "minItems": 0,
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["claim", "status", "evidence"],
+        "properties": {
+          "claim": { "type": "string", "maxLength": 160, "description": "What the project claims exists (a live app, a demo, a GitHub, a team, docs…)" },
+          "status": { "type": "string", "enum": ["supported", "contradicted", "unverifiable"] },
+          "evidence": { "type": "string", "maxLength": 240, "description": "The tool result that supports/contradicts it (tool + field + value), or why it is unverifiable" }
+        }
+      }
+    },
+    "links_checked": {
+      "type": "array",
+      "maxItems": 24,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["url", "kind", "reachable"],
+        "properties": {
+          "url": { "type": "string" },
+          "kind": { "type": "string" },
+          "reachable": { "type": "boolean" },
+          "status": { "type": ["number", "null"] }
+        }
+      }
+    },
+    "domain": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "domain": { "type": ["string", "null"] },
+        "age_days": { "type": ["number", "null"] },
+        "registrar": { "type": ["string", "null"] },
+        "privacy": { "type": ["boolean", "null"] }
+      }
+    },
+    "github": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "repo": { "type": ["string", "null"] },
+        "days_since_push": { "type": ["number", "null"] },
+        "stars": { "type": ["number", "null"] },
+        "archived": { "type": ["boolean", "null"] }
+      }
+    },
+    "missing_data": {
+      "type": "array",
+      "description": "What could not be fetched keyless (e.g. X is login-walled, site timed out). Be honest here.",
+      "items": { "type": "string", "maxLength": 160 },
+      "maxItems": 20
+    },
+    "facts": {
+      "type": "array",
+      "minItems": 0,
+      "maxItems": 24,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["claim", "tool", "field", "value"],
+        "properties": {
+          "claim": { "type": "string", "maxLength": 160 },
+          "tool": { "type": "string" },
+          "field": { "type": "string" },
+          "value": { "type": ["number", "string", "boolean", "null"] },
+          "age_sec": { "type": ["number", "null"] }
+        }
+      }
+    },
+    "flags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 },
+    "invalidation": { "type": "string", "maxLength": 240 },
+    "proposals": {
+      "type": "array",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "text"],
+        "properties": {
+          "type": { "type": "string", "enum": ["alert", "note", "watchlist"] },
+          "text": { "type": "string", "maxLength": 200 },
+          "condition": { "type": "string", "maxLength": 120 }
+        }
+      }
+    },
+    "injection_detected": { "type": "boolean" },
+    "candidates": {
+      "type": "array",
+      "description": "AMBIGUOUS only: the mints the symbol could mean",
+      "items": { "type": "object", "additionalProperties": false, "required": ["mint"], "properties": { "mint": { "type": "string" }, "launchpad": { "type": "string" }, "mcap": { "type": ["number", "null"] }, "ageSec": { "type": ["number", "null"] } } }
+    },
+    "sources_used": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": false, "required": ["tool"], "properties": { "tool": { "type": "string" }, "source": { "type": "string" }, "age_sec": { "type": ["number", "null"] } } }
+    },
+    "kb_entries_cited": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/dist/packages/cli/assets/claude/schemas/trench-scan.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dexterm/claude-layer/trench-scan",
+  "title": "Trench scan output",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skill", "skill_version", "scanned", "candidates", "skipped", "injection_detected", "sources_used", "summary"],
+  "properties": {
+    "skill": { "type": "string", "enum": ["trench-scan"] },
+    "skill_version": { "type": "string" },
+    "scanned": { "type": "integer", "minimum": 0 },
+    "summary": { "type": "string", "maxLength": 400, "description": "One short line per candidate plus one skipped-count line. No intro, no disclaimer line" },
+    "candidates": {
+      "type": "array",
+      "maxItems": 10,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["mint", "verdict", "confidence", "reasons", "facts"],
+        "properties": {
+          "mint": { "type": "string" },
+          "symbol": { "type": "string" },
+          "verdict": { "type": "string", "enum": ["WATCH", "SPECULATIVE", "AVOID", "INSUFFICIENT_DATA"] },
+          "bias": { "type": "string", "enum": ["long", "short", "avoid", "wait"], "description": "Quick directional lean for this candidate" },
+          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+          "reasons": { "type": "array", "items": { "type": "string", "maxLength": 120 }, "maxItems": 5 },
+          "facts": {
+            "type": "array",
+            "maxItems": 8,
+            "items": { "type": "object", "additionalProperties": false, "required": ["claim", "tool", "field", "value"], "properties": { "claim": { "type": "string", "maxLength": 120 }, "tool": { "type": "string" }, "field": { "type": "string" }, "value": { "type": ["number", "string", "boolean", "null"] } } }
+          }
+        }
+      }
+    },
+    "skipped": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": false, "required": ["mint", "reason"], "properties": { "mint": { "type": "string" }, "reason": { "type": "string", "maxLength": 120 } } }
+    },
+    "proposals": {
+      "type": "array",
+      "maxItems": 5,
+      "items": { "type": "object", "additionalProperties": false, "required": ["type", "text"], "properties": { "type": { "type": "string", "enum": ["alert", "note", "watchlist"] }, "text": { "type": "string", "maxLength": 200 }, "mint": { "type": "string" } } }
+    },
+    "injection_detected": { "type": "boolean" },
+    "results": {
+      "type": "array",
+      "maxItems": 20,
+      "description": "The scan's ranked coins as a list the app renders as a live table (prices/liq/vol from its data layer by mint, never your text). One entry per WATCH/SPECULATIVE candidate, best first; only mints the screener returned.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["mint", "reason"],
+        "properties": {
+          "mint": { "type": "string" },
+          "symbol": { "type": "string", "maxLength": 32 },
+          "reason": { "type": "string", "maxLength": 100 }
+        }
+      }
+    },
+    "filter_applied": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["query"],
+      "properties": {
+        "query": { "type": "string", "maxLength": 120 },
+        "notes": { "type": "string", "maxLength": 160 }
+      }
+    },
+    "sources_used": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["tool"], "properties": { "tool": { "type": "string" }, "source": { "type": "string" }, "age_sec": { "type": ["number", "null"] } } } }
+  }
+}

package/dist/packages/cli/assets/claude/schemas/verdict.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dexterm/claude-layer/verdict",
+  "title": "Analyst verdict (token-dossier, rug-check)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skill", "skill_version", "mint", "verdict", "confidence", "facts", "flags", "invalidation", "proposals", "injection_detected", "sources_used", "summary", "missing_data"],
+  "properties": {
+    "product_assessment": {
+      "type": "object", "additionalProperties": false,
+      "required": ["verdict", "confidence", "claims", "missing_data"],
+      "properties": {
+        "verdict": { "type": "string", "enum": ["REAL_PRODUCT", "EARLY_BUT_REAL", "LARP", "UNVERIFIABLE"] },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "claims": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["claim", "evidence"], "properties": { "claim": { "type": "string" }, "evidence": { "type": "string" } } } },
+        "missing_data": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "skill": { "type": "string", "enum": ["token-dossier", "rug-check"] },
+    "skill_version": { "type": "string" },
+    "mint": { "type": "string", "description": "The mint analysed, or empty string when AMBIGUOUS/INSUFFICIENT_DATA before resolution" },
+    "verdict": { "type": "string", "enum": ["WATCH", "SPECULATIVE", "AVOID", "INSUFFICIENT_DATA", "AMBIGUOUS"] },
+    "bias": { "type": "string", "enum": ["long", "short", "avoid", "wait"], "description": "The directional trading view; give one unless AMBIGUOUS/INSUFFICIENT_DATA" },
+    "setup_quality": { "type": "string", "enum": ["strong", "mixed", "weak"], "description": "How clean the setup is given liquidity, holders, tape and structure" },
+    "key_levels": {
+      "type": "array",
+      "maxItems": 8,
+      "description": "Concrete levels from the candles and liquidity (support, resistance, VWAP, range high/low, invalidation level)",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string", "maxLength": 40 },
+          "value": { "type": ["number", "string", "null"] },
+          "note": { "type": "string", "maxLength": 80 }
+        }
+      }
+    },
+    "size_hint": { "type": "string", "maxLength": 160, "description": "Size framed as a fraction of risk capital with the stop (e.g. '0.5-1% risk, stop below the range low'); never a dollar amount or a token count" },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "missing_data": { "type": "array", "items": { "type": "string", "maxLength": 160 }, "maxItems": 20, "description": "Sections or fields that were unavailable/null (copied from the dossier `availability.missing` and `knownUnavailable`). Empty array when everything was present. A non-empty list lowers confidence but — as long as price or liquidity exists — never forces INSUFFICIENT_DATA." },
+    "rug_probability": { "type": "number", "minimum": 0, "maximum": 1, "description": "rug-check only: model's probability that this token rugs within 72 h" },
+    "summary": { "type": "string", "maxLength": 600, "description": "Two to four short lines for a 40-column panel: the call in plain words and the deciding facts. Never repeats bias/levels/invalidation/size (rendered from their own fields), never a disclaimer line" },
+    "facts": {
+      "type": "array",
+      "minItems": 0,
+      "maxItems": 20,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["claim", "tool", "field", "value"],
+        "properties": {
+          "claim": { "type": "string", "maxLength": 160 },
+          "tool": { "type": "string" },
+          "field": { "type": "string" },
+          "value": { "type": ["number", "string", "boolean", "null"] },
+          "age_sec": { "type": ["number", "null"] }
+        }
+      }
+    },
+    "flags": { "type": "array", "items": { "type": "string" }, "maxItems": 20 },
+    "invalidation": { "type": "string", "maxLength": 240 },
+    "proposals": {
+      "type": "array",
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "text"],
+        "properties": {
+          "type": { "type": "string", "enum": ["alert", "note", "watchlist"] },
+          "text": { "type": "string", "maxLength": 200 },
+          "condition": { "type": "string", "maxLength": 120 }
+        }
+      }
+    },
+    "injection_detected": { "type": "boolean" },
+    "candidates": {
+      "type": "array",
+      "description": "AMBIGUOUS only: the mints the symbol could mean",
+      "items": { "type": "object", "additionalProperties": false, "required": ["mint"], "properties": { "mint": { "type": "string" }, "launchpad": { "type": "string" }, "mcap": { "type": ["number", "null"] }, "ageSec": { "type": ["number", "null"] } } }
+    },
+    "results": {
+      "type": "array",
+      "maxItems": 20,
+      "description": "When the answer is a LIST of coins (e.g. after a filter, or 'best setups right now'), put one entry per coin here by mint. The app renders a live table from these mints (prices/liq/vol come from its data layer, never your text); only mints already on screen or fetched via tools are shown. Give a one-line reason per row.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["mint", "reason"],
+        "properties": {
+          "mint": { "type": "string", "description": "base58 mint of a coin that is on screen or that a tool returned" },
+          "symbol": { "type": "string", "maxLength": 32 },
+          "reason": { "type": "string", "maxLength": 100, "description": "one short line on why this coin is in the list" }
+        }
+      }
+    },
+    "filter_applied": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "When you called show_in_screener for a plain-language request, echo the structured filter you applied here so the user sees (and can correct) the numbers you chose.",
+      "required": ["query"],
+      "properties": {
+        "query": { "type": "string", "maxLength": 120, "description": "the exact filter string you passed to show_in_screener, in dexterm grammar (e.g. 'mcap < 5M liq > 50K h24 > 0 flag:clean')" },
+        "notes": { "type": "string", "maxLength": 160, "description": "the numbers you chose for vague words, in words (e.g. 'low cap = mcap < 5M; liquid = liq > 50K; up on the day = h24 > 0; not a rug = flag:clean')" }
+      }
+    },
+    "sources_used": {
+      "type": "array",
+      "items": { "type": "object", "additionalProperties": false, "required": ["tool"], "properties": { "tool": { "type": "string" }, "source": { "type": "string" }, "age_sec": { "type": ["number", "null"] } } }
+    },
+    "kb_entries_cited": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/dist/packages/cli/bin/dexterm.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// dexterm bin shim. Runs the TypeScript sources directly via Node's built-in type stripping
+// (Node >= 22.18 / 23.6+ / 24). This is the checkout/source-tarball entry; the npm package's bin is
+// the compiled copy at dist/packages/cli/bin/dexterm.mjs, built by scripts/build-dist.mjs (task-1346).
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 22 || (major === 22 && minor < 18)) {
+  process.stderr.write(`dexterm needs Node 22.18 or newer (found ${process.versions.node})\n`);
+  process.exit(1);
+}
+const { main } = await import('../src/main.js');
+process.exitCode = await main(process.argv.slice(2));

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

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

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

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