dexterm-cli 0.1.3 → 0.1.5

package/dist/packages/mcp/assets/kb/docs/docs-voice-still-unverified.md

@@ -0,0 +1,27 @@
+---
+id: docs-voice-still-unverified
+title: Jarvis voice mode › Still unverified
+kind: docs
+page: voice
+page_title: Jarvis voice mode
+heading: Still unverified
+anchor: still-unverified
+url: https://dexterm.xyz/docs/voice#still-unverified
+tags:
+  - docs
+  - voice
+  - still
+  - unverified
+  - jarvis
+  - mode
+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/voice.md
+date: 2026-10-16
+---
+
+The real-microphone path has been exercised headlessly (scripted speech engines, the real key loop) and the engines have been measured on synthetic audio. A person has not yet run the first-launch Microphone and Speech prompts and spoken to it end to end; see the changelog (https://dexterm.xyz/changelog/).

package/dist/packages/mcp/assets/kb/docs/docs-voice-the-voice-neural-by-default.md

@@ -0,0 +1,48 @@
+---
+id: docs-voice-the-voice-neural-by-default
+title: Jarvis voice mode › The voice: neural by default
+kind: docs
+page: voice
+page_title: Jarvis voice mode
+heading: The voice: neural by default
+anchor: the-voice-neural-by-default
+url: https://dexterm.xyz/docs/voice#the-voice-neural-by-default
+tags:
+  - docs
+  - voice
+  - neural
+  - default
+  - jarvis
+  - mode
+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/voice.md
+date: 2026-10-16
+---
+
+dexterm speaks with a **neural British voice** (Piper, `en_GB-alan-medium`) — the one chosen as the default. It is free, local and keyless, and sounds markedly more natural than the built-in system voices. It is the default speaking voice everywhere it is installed, on macOS as well as Linux, with the system `say` voice as the fallback.
+
+On macOS, run `dexterm voice setup` once to install it. The prebuilt macOS Piper binary from upstream is broken (it needs a system library it does not bundle), so dexterm instead builds its own private Python environment under `~/.dexterm/piper/` and installs Piper into it, then downloads the ~61 MB voice from the official source and checks it against a pinned checksum. It asks before it does any of this, needs Python 3.9+ (the doctor prints the exact install line if it is missing), runs fully offline afterwards, and ships no key. `dexterm voice uninstall` removes the runtime and keeps the downloaded voice model (add `--purge-model` to delete that too); the fallback `say` voice takes over again. Off macOS, install the prebuilt Piper binary and run `dexterm voice download piper-voice`.
+
+```sh
+$ dexterm voice setup                    # macOS: private runtime + checksum-verified voice (asks first)
+$ dexterm voice status                   # which engines and models this machine has
+$ dexterm voice uninstall                # remove the runtime (add --purge-model to drop the voice too)
+```
+
+Once Piper is installed it is used automatically — no config change. The model is kept pre-warmed while voice is on, so the first word of a reply starts in about a fifth of a second. `voice.rate` still maps to its speaking speed; a `voice.pitch` setting does not apply to Piper (its pitch is fixed by the model) and is ignored.
+
+**The fallback chain.** dexterm picks the first engine that can speak on this machine, and never a novelty voice or the machine's own system voice:
+
+| platform | 1st | 2nd | then |
+| --- | --- | --- | --- |
+| macOS | Piper `en_GB-alan-medium` (after `dexterm voice setup`) | `say` with a deep British male voice (Eddy, then Daniel, then the next installed one on that list) | text only: the analyst still answers on screen |
+| Linux (beta) | Piper (prebuilt binary + `dexterm voice download piper-voice`) | `espeak-ng` with a British male voice | text only |
+
+Set `DEXTERM_VOICE_TTS` to `piper`, `say`, `espeak` or `none` to pin one engine. An explicit `say` never switches to Piper.
+
+**Speed and delivery.** `<` slows the spoken reply and `>` speeds it up, 15 words a minute per press between 120 and 320 (the default is 205). The new rate is saved to `voice.rate` in `config.json`. Numbers are read the way a trader says them: a sub-cent price is spoken as the coin's market cap when the line includes one, and otherwise as "a tiny price". Years and SOL amounts are read as written. On the screener, "this one", "this coin" or "it" means the highlighted row.

package/dist/packages/mcp/assets/kb/docs/docs-voice-what-it-can-never-do.md

@@ -0,0 +1,27 @@
+---
+id: docs-voice-what-it-can-never-do
+title: Jarvis voice mode › What it can never do
+kind: docs
+page: voice
+page_title: Jarvis voice mode
+heading: What it can never do
+anchor: what-it-can-never-do
+url: https://dexterm.xyz/docs/voice#what-it-can-never-do
+tags:
+  - docs
+  - voice
+  - can
+  - never
+  - jarvis
+  - mode
+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/voice.md
+date: 2026-10-16
+---
+
+Voice creates proposals only. The ticket it opens is PAPER, in its editing phase, and the keypress gate stands: your `⏎` then `y` (plus the typed-back size above the threshold) is the only way to a fill. Spoken "confirm", "send it", "y", "sign it", "go live", "arm it", "raise my cap", "panic" and "/wallet …" are routed as questions or ignored; they cannot flip the ticket to LIVE, arm a plan, touch the signer's caps, run a wallet command or press anything. The router's output is a closed set of decision kinds, a guard rejects any decision that carries a mode, live, arm, caps, confirm, sign or send field, and an in-app test drives the real key loop with the executor, the confirm paths, the LIVE flip and the wallet commands booby-trapped: twenty-one hostile utterances, zero touches.

package/dist/packages/mcp/assets/kb/docs/docs-voice-what-you-can-say.md

@@ -0,0 +1,38 @@
+---
+id: docs-voice-what-you-can-say
+title: Jarvis voice mode › What you can say
+kind: docs
+page: voice
+page_title: Jarvis voice mode
+heading: What you can say
+anchor: what-you-can-say
+url: https://dexterm.xyz/docs/voice#what-you-can-say
+tags:
+  - docs
+  - voice
+  - can
+  - say
+  - jarvis
+  - mode
+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/voice.md
+date: 2026-10-16
+---
+
+| you say | what happens | path |
+|---|---|---|
+| "show me the runners", "go to new pairs", "open my watchlist", "positions" | switches the screen | instant, no model |
+| "open bonk", "pull up wif" | opens that coin's token screen | instant |
+| "filter liquidity over 50k", "only show age under 10 minutes" | sets the screener filter | instant |
+| "watch this one", "add bonk to my watchlist" | adds to the watchlist | instant |
+| "show the chart", "close the chart" | opens or closes the chart popup for the open coin through the popup host | instant |
+| "buy bonk", "sell half of wif", "ape into this one" | opens a **PAPER ticket in its editing phase** for the spoken coin and says so | instant |
+| "is this a rug?", "what do you think about wif", "tell me about the holders" | asks the analyst; the first two sentences of the answer are read aloud | Claude |
+| "buy this if it dips to 300k, sell half at 600k, and leave a moon bag", "buy bonk if it drops to 250k, stop at 150k" | drafts an **order-plan proposal** (entry trigger, take-profit ladder, moon bag, stop) for the named or highlighted coin; it is inert until you arm it with a held keypress on the `O` screen or `dexterm plan arm` | instant, no model |
+
+`m` mutes the replies, `,` cycles the macOS `say` voice (the fallback; Piper itself has one fixed voice), `<` / `>` make it slower or faster, `esc` stops a reply or cancels the mic. Only the keyboard changes the voice: the analyst can explain these keys but has no action that sets them. Any other key pressed while the mic is live closes it first and then does its normal job, and the mic auto-closes after 15 s if you walk away. On the ticket screen the voice keys are off, so nothing spoken can reach the confirm gate.

package/dist/packages/mcp/assets/kb/docs/docs-voice.md

@@ -0,0 +1,25 @@
+---
+id: docs-voice
+title: Jarvis voice mode
+kind: docs
+page: voice
+page_title: Jarvis voice mode
+url: https://dexterm.xyz/docs/voice
+tags:
+  - docs
+  - voice
+  - jarvis
+  - mode
+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/voice.md
+date: 2026-10-16
+---
+
+Push-to-talk on v, an instant local command path, Claude for analysis, spoken replies, popups. Voice only ever proposes; it can never confirm, sign, flip LIVE or raise a cap.
+
+`v` is push-to-talk. Press it once and the mic opens (a red `● LISTENING` badge sits on the band under the header the whole time it is live); say what you want; press `v` again to send. The first press enables voice for the run and asks macOS for Microphone and Speech permission. Everything is free and local: speech-out is the neural Piper voice once it is set up (otherwise the built-in `say`), speech-in is on-device Apple Speech (compiled once with `swiftc`) or a local whisper.cpp `base.en` model, and the only model in the loop is your own `claude` login, for analysis questions. No paid speech API exists in the code, no key is read, nothing is recorded to disk.

package/dist/packages/mcp/src/app-help.js

@@ -133,3 +133,126 @@ export function searchAppHelp(query, limit = 5, entries = loadAppHelp()) {
 export function getAppHelp(id, entries = loadAppHelp()) {
     return entries.find((e) => e.id === id) ?? null;
 }
+// ---------------------------------------------------------------------------------------- docs (task-1420)
+// A THIRD bundled set: every page of the site docs (dexterm.xyz/docs), chunked by heading. GENERATED from the
+// site by `packages/cli/src/docs-kb-gen.ts` (committed; a regenerate-and-diff test runs when the site checkout
+// is present). The app-help entries stay the authority for an exact key or command; a docs entry carries the
+// explanation and the URL to cite, and NEVER structured keys/commands/flags/tools. Its text is reference DATA:
+// the app_help tool hands it to a model firewalled (`<untrusted kind="docs">`), so an instruction written into
+// a docs page reads as quoted text, never as an order.
+/** The shipped docs KB directory (read-only; generated from the site docs). */
+export const DOCS_KB_DIR = path.resolve(HERE, '..', 'assets', 'kb', 'docs');
+function toDocs(e) {
+    return {
+        id: e.id,
+        title: String(e.meta.title ?? e.id),
+        page: String(e.meta.page ?? ''),
+        pageTitle: String(e.meta.page_title ?? ''),
+        heading: String(e.meta.heading ?? ''),
+        anchor: String(e.meta.anchor ?? ''),
+        url: String(e.meta.url ?? ''),
+        tags: list(e.meta.tags),
+        body: e.body,
+        bytes: e.bytes,
+    };
+}
+/** Load every docs entry (bundled-only; deterministic order by id). */
+export function loadDocsKb(dir = DOCS_KB_DIR) {
+    const entries = loadBundled([{ dir, layout: 'flat' }]).map(toDocs);
+    entries.sort((a, b) => a.id.localeCompare(b.id));
+    return entries;
+}
+/**
+ * A light, deterministic stemmer for the docs set only (prose, unlike the app-help titles): "answers"/"answer",
+ * "cached"/"cache", "clarifies"/"clarify", "streaming"/"stream" meet. Short words are left alone.
+ */
+function stem(w) {
+    if (w.length < 4 || w.includes('-'))
+        return w;
+    let s = w;
+    if (s.endsWith('ies') && s.length > 4)
+        s = s.slice(0, -3) + 'y';
+    else if (s.endsWith('ing') && s.length > 5)
+        s = s.slice(0, -3);
+    else if (s.endsWith('ed') && s.length > 4)
+        s = s.slice(0, -2);
+    else if (/(?:ss|sh|ch|x|z)es$/.test(s))
+        s = s.slice(0, -2);
+    else if (s.endsWith('s') && !s.endsWith('ss'))
+        s = s.slice(0, -1);
+    if (s.endsWith('e') && s.length > 3)
+        s = s.slice(0, -1);
+    return s;
+}
+/**
+ * Deterministic keyword retrieval over the docs set (no model), same word-boundary matching as app-help.
+ * The section heading and tags score strongest, the page title less (every section of a page shares it),
+ * the body is the weak tail.
+ */
+export function searchDocs(query, limit = 5, entries = loadDocsKb()) {
+    const terms = [...new Set(expand(tokenise(query)).map(stem))];
+    const scored = entries.map((e) => {
+        const strong = new Set(words(`${e.heading} ${e.tags.filter((t) => t !== 'docs').join(' ')}`).map(stem));
+        const page = new Set(words(`${e.pageTitle} ${e.page}`).map(stem));
+        const bodyWords = words(e.body).map(stem);
+        let score = 0;
+        for (const t of terms) {
+            if (strong.has(t))
+                score += 4;
+            else if (page.has(t))
+                score += 2;
+            let n = 0;
+            for (const w of bodyWords)
+                if (w === t)
+                    n++;
+            score += Math.min(n, 3);
+        }
+        // A question that names a section's own heading words is about that section: +3 per heading word
+        // matched (+2 more when it names all of them), so "what is redacted in the spectator view" lands on "What is redacted",
+        // not on the page's other sections that merely share the page title.
+        const head = new Set(tokenise(e.heading).map(stem));
+        let hit = 0;
+        for (const w of head)
+            if (terms.includes(w))
+                hit++;
+        if (hit >= 1 && head.size > 0)
+            score += 3 * hit + (hit === head.size ? 2 : 0);
+        return { e, score };
+    }).filter((x) => x.score > 0)
+        .sort((a, b) => (b.score - a.score) || a.e.id.localeCompare(b.e.id))
+        .slice(0, limit);
+    return scored.map(({ e, score }) => ({ ...e, score }));
+}
+/** Fetch one docs entry by id. */
+export function getDocs(id, entries = loadDocsKb()) {
+    return entries.find((e) => e.id === id) ?? null;
+}
+/** Words that make a question about an exact key or command: app-help answers it. */
+const KEY_OR_COMMAND = /\b(?:key|keys|keybind\w*|press|pressing|shortcut|shortcuts|hotkey|hotkeys|command|commands|subcommand|subcommands|flag|flags|cli)\b/i;
+/** "how do I …" / "how to …": a how-to, answered by an app-help topic. */
+const HOW_TO = /^\s*how\s+(?:do|can|could|would|should)\s+(?:i|you|we)\b|^\s*how\s+to\b/i;
+/** A conceptual question opens with a question word ("what is …", "does it …", "how does …", "how long …"). */
+const CONCEPT = /^\s*(?:what|whats|what's|why|is|are|does|do|did|can|could|will|would|should|where|when|which|who|how)\b/i;
+/** About a screen ("what does the token screen show") or the coin on it ("is this coin a rug"): an app-help topic/tool. */
+const APP_SUBJECT = /\b(?:screen|screener)\b|\bthis\s+(?:[a-z-]+\s+){0,2}(?:coin|token|project)\b/i;
+/** The question's shape: 'key' (exact key/command, a how-to, an imperative, a screen/this-coin question) or 'concept'. */
+export function helpIntent(query) {
+    if (KEY_OR_COMMAND.test(query) || HOW_TO.test(query) || APP_SUBJECT.test(query))
+        return 'key';
+    return CONCEPT.test(query) ? 'concept' : 'key';
+}
+/**
+ * The analyst's help search (task-1420): app-help AND the docs, merged by the question's shape.
+ *  - a key/command question, a how-to or an imperative ("export the view", "how do I sort"): app-help ranks
+ *    first (it carries the exact key/command), the docs after it;
+ *  - a conceptual question ("what is redacted in the spectator view", "does voice work on linux"): the docs rank
+ *    first (nothing ranks above them), the app-help after.
+ * Either way the answer keeps both sets in view: up to 3 hits of the leading set, then up to 2 of the other,
+ * then the rest. A set with no hits simply yields to the other (a docs-only answer beats no answer).
+ */
+export function searchHelp(query, limit = 5, sets = {}) {
+    const app = searchAppHelp(query, limit, sets.appHelp ?? loadAppHelp()).map((e) => ({ ...e, origin: 'app-help' }));
+    const docs = searchDocs(query, limit, sets.docs ?? loadDocsKb()).map((e) => ({ ...e, origin: 'docs' }));
+    const [lead, other] = helpIntent(query) === 'concept' ? [docs, app] : [app, docs];
+    return [...lead.slice(0, 3), ...other.slice(0, 2), ...lead.slice(3), ...other.slice(2)].slice(0, limit);
+}

package/dist/packages/mcp/src/firewall.js

@@ -1,7 +1,7 @@
 // Prompt firewall (CL-06), spec'd in SPEC §5.3. Kept tiny and total. Every untrusted string — token text,
 // web pages, RugCheck risks, and (task-1377) user- or pack-edited KB entries and skills — passes through
-// here before a model sees it.
-export const LIMITS = { name: 64, symbol: 16, description: 512, risk: 160, kb: 4000, page: 1600, link: 40, skill: 8000 };
+// here before a model sees it. (task-1420) The generated docs KB sections pass through as kind `docs`.
+export const LIMITS = { name: 64, symbol: 16, description: 512, risk: 160, kb: 4000, page: 1600, link: 40, skill: 8000, docs: 6000 };
 export function firewall(text, source, kind = 'description', opts = {}) {
     if (text === null || text === undefined)
         return null;

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

@@ -1,12 +1,15 @@
 // @dexterm/mcp — read-only MCP server over stdio (SPEC §5, D-09 / task-1302).
 // Every tool is read-only and schema-described; nothing in this package may build,
 // sign or send a transaction (SPEC §5.2, §6.3).
-export { runStdioServer, selfTest, McpTools, TOOLS, READ_ONLY_TOOLS, firewall, listPrompts, getPrompt, resourceList, resourceRead, overlayCounts, userSkillPreamble, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR } from "./server.js";
+export { runStdioServer, selfTest, McpTools, TOOLS, READ_ONLY_TOOLS, PAPER_WRITE_TOOLS, PAPER_READ_TOOLS, appHelpAnswer, firewall, listPrompts, getPrompt, resourceList, resourceRead, overlayCounts, userSkillPreamble, BUNDLED_KB_DIR, BUNDLED_SKILLS_DIR } from "./server.js";
+// task-1443: resolve the paper agent desk from the running app's rendezvous (null when agent paper trading is off).
+export { resolvePaperAgentDesk, paperAgentDeskDb } from "./paper-agent.js";
 export { OverlayStore, mergeOverlay, loadBundled, checkKb, checkSkill, moneyToolMentions, isMoneyToolName, parseFrontmatter, dextermHome, userKbDir, userSkillsDir, userDir, contentJournalPath, journalContent, writeOverlayFile, resetOverlayFile, templateFor, KB_LIMITS, SKILL_LIMITS, KB_ID, SKILL_NAME, KB_RULE, MONEY_TOOLS, } from "./user-content.js";
 export { buildDossier } from "./dossier.js";
-// task-1406: the spectator sink the tool-call path writes to when launched with a spectator channel.
-export { recordForToolCall, maxAgeSec, fileSpectatorSinkFromEnv } from "./spectator-sink.js";
-export { loadAppHelp, searchAppHelp, getAppHelp, APP_HELP_DIR } from "./app-help.js";
+// task-1406 + task-1421: the spectator sink the tool-call path writes to when a spectator surface is open
+// (via DEXTERM_SPECTATOR_FILE, or the ~/.dexterm rendezvous an external `dexterm mcp` client uses).
+export { recordForToolCall, maxAgeSec, fileSpectatorSinkFromEnv, resolveSpectatorSink, rendezvousPath, MCP_SPECTATOR_RENDEZVOUS, MCP_FOLLOW_SCREEN, FOLLOW_NAV_ACTIONS, followScreenPath, readFollowScreen, writeFollowScreen, clearFollowScreen, } from "./spectator-sink.js";
+export { loadAppHelp, searchAppHelp, getAppHelp, APP_HELP_DIR, loadDocsKb, searchDocs, getDocs, searchHelp, DOCS_KB_DIR, helpIntent } from "./app-help.js";
 /** Tool names served in v1 (SPEC §5.2 core + the task-1293 KB/case tools + the task-1314 dossier). */
 export const PLANNED_TOOLS = [
     'screen_state',
@@ -19,6 +22,7 @@ export const PLANNED_TOOLS = [
     'get_candles',
     'rugcheck',
     'get_dev_history',
+    'dev_history',
     'kb_lookup',
     'kb_search',
     'case_lookup',

package/dist/packages/mcp/src/paper-agent.js

@@ -0,0 +1,92 @@
+// task-1443 — the MCP side of agent paper trading. When the running dexterm has the spectator view open and the
+// user named an armed mandate for agent paper trading, it writes a rendezvous under ~/.dexterm; this resolves it
+// into a PaperAgentDesk the paper tools dispatch to. When the rendezvous is absent the resolver returns null and
+// the tools refuse — so agent paper trading is OFF by default and nothing here ever signs, sends or touches a
+// wallet/key.
+//
+// The desk books into the SAME paper wallet SQLite file the app uses (WAL, concurrent-safe). Its caps are
+// REPLAYED from the app's hash-chained plans journal (never read from the rendezvous), re-checked on every call
+// (mtime-cached), so a revoke or panic in the app halts the agent. It prices the mandate's USD caps from a
+// keyless SOL/USD read (fail-closed when older than 60 s), reads the control file on every mutating call
+// (pause / take-over / stop), and journals every call to its own hash chain. The only trade op it can reach is
+// the keyless swap-QUOTE + the PAPER executor (see paper-desk.ts).
+import { PaperAgentDesk, PaperWallet, PaperExecutor, SharedJournal, systemClock, readPaperAgentRendezvous, readDeskControl, rendezvousMtimeMs, fileMtimeMs, loadMandateFromJournal, plansJournalPathFor, paperAgentJournalPath, withPriority, } from '../../data/src/index.js';
+const WSOL = 'So11111111111111111111111111111111111111112';
+/** A SOL/USD read older than this prices no cap (same freshness rule as the signer's resolveSolUsd). */
+export const PAPER_SOL_USD_MAX_AGE_MS = 60_000;
+const SOL_USD_REFRESH_MS = 20_000;
+let cache = null;
+let sol = null;
+let mandateCache = null;
+function teardown() {
+    if (cache) {
+        try {
+            cache.wallet.close();
+        }
+        catch { /* ignore */ }
+        cache = null;
+    }
+    mandateCache = null;
+}
+/** Replay the mandate from the plans journal, re-read whenever the journal changes (revoke / panic / expiry). */
+function currentMandate(env, id) {
+    const path = plansJournalPathFor(env);
+    const mtimeMs = fileMtimeMs(path);
+    if (mandateCache && mandateCache.id === id && mandateCache.mtimeMs === mtimeMs)
+        return mandateCache.m;
+    const r = loadMandateFromJournal(path, id, systemClock);
+    mandateCache = { id, mtimeMs, m: r.mandate };
+    return r.mandate;
+}
+/** Keep the SOL/USD read fresh enough to price the USD caps; a failed read leaves the old one to age out. */
+async function refreshSolUsd(data) {
+    const now = Date.now();
+    if (sol && now - sol.at < SOL_USD_REFRESH_MS)
+        return;
+    try {
+        const p = (await data.jupiter.price([WSOL])).get(WSOL)?.usdPrice;
+        if (typeof p === 'number' && Number.isFinite(p) && p > 0)
+            sol = { price: p, at: Date.now() };
+    }
+    catch { /* keep the last value; it ages out */ }
+}
+/**
+ * Resolve the paper agent desk for this `dexterm mcp` process, or null when agent paper trading is disabled.
+ * Re-reads the rendezvous (mtime-cached) so enabling/disabling in the running app is picked up; the mandate
+ * and the control state are re-read inside the desk on every call, not cached across journal changes.
+ */
+export async function resolvePaperAgentDesk(data, env = process.env) {
+    const mtimeMs = rendezvousMtimeMs(env);
+    if (mtimeMs === 0) {
+        teardown();
+        return null;
+    } // not enabled
+    const rv = readPaperAgentRendezvous(env);
+    if (!rv) {
+        teardown();
+        return null;
+    } // present but unreadable → off (fail closed)
+    await refreshSolUsd(data);
+    if (cache && cache.mtimeMs === mtimeMs && cache.db === rv.db && cache.mandateId === rv.mandateId)
+        return cache.desk;
+    // The rendezvous changed (or first use): rebuild on the current wallet + mandate.
+    teardown();
+    const wallet = new PaperWallet({ path: rv.db, clock: systemClock });
+    const executor = new PaperExecutor(wallet, { clock: systemClock });
+    const desk = new PaperAgentDesk({
+        mandate: () => currentMandate(env, rv.mandateId),
+        wallet,
+        executor,
+        // 'high', like the human ticket (task-1387): a paper exit must not queue behind the agent's own read polling on
+        // the shared keyless `jupiter` bucket (task-1443 live run: a scale-out was refused on a 429 mid-poll).
+        quote: (req, signal) => withPriority('high', () => data.jupiterSwap.quote(req, signal)),
+        solUsd: () => (sol && Date.now() - sol.at <= PAPER_SOL_USD_MAX_AGE_MS ? sol.price : null),
+        control: () => readDeskControl(env),
+        journal: new SharedJournal(paperAgentJournalPath(env), systemClock),
+        agent: rv.agent ?? 'mcp-agent',
+    });
+    cache = { mtimeMs, db: rv.db, mandateId: rv.mandateId, wallet, desk };
+    return desk;
+}
+/** Exported for tests: the current cached rendezvous db, if any. */
+export function paperAgentDeskDb() { return cache?.db ?? null; }