dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/trade/signer/client.js

@@ -0,0 +1,197 @@
+// dexterm T2 — the signer CLIENT (task-1328): the UI's only handle on the signer process. It spawns the
+// signer as a child with piped stdio, hands it the session secret as the first stdin line, and sends
+// authenticated requests with per-call timeouts. Every failure is a REFUSAL (fail closed): a dead or
+// silent signer never becomes a "maybe it signed". The client never respawns a signer that died — LIVE
+// trading stays off for the rest of the run, and the user restarts dexterm.
+//
+// The client forwards exactly the argv the user started dexterm with (caps flags, --mainnet, --rpc).
+// It cannot change caps afterwards: there is no such message.
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { decodeFrame, encodeFrame, encodeHello, isEvent, isResponse, newSecret } from "./protocol.js";
+export class SignerUnavailableError extends Error {
+    /** The signer's refusal/error reason when it sent one (`rate-limited`, `build-failed`, a CapRefusal, …). */
+    reason;
+    /** task-1368: for `rate-limited`, how long to wait before asking the signer again. */
+    retryAfterMs;
+    constructor(message, detail = {}) {
+        super(message);
+        this.name = 'SignerUnavailableError';
+        this.reason = detail.reason ?? null;
+        this.retryAfterMs = typeof detail.retryAfterMs === 'number' && Number.isFinite(detail.retryAfterMs) ? detail.retryAfterMs : null;
+    }
+}
+export const DEFAULT_TIMEOUTS = { status: 8_000, plan: 60_000, probe: 30_000, precheck: 8_000, confirm: 240_000, drop: 8_000, panic: 8_000, fast: 12_000, fill: 30_000, quote: 20_000 };
+export function defaultSignerEntry() {
+    return fileURLToPath(new URL('./main.js', import.meta.url));
+}
+export class SignerClient {
+    child = null;
+    secret = newSecret();
+    outSeq = 0;
+    inSeq = 0;
+    nextId = 1;
+    pending = new Map();
+    ready = null;
+    dead = null;
+    opts;
+    argv;
+    pid = null;
+    constructor(opts = {}) {
+        this.opts = opts;
+        this.argv = [...(opts.argv ?? [])];
+    }
+    /**
+     * Available for LIVE work: not dead. A client that has not started yet IS alive — the signer is
+     * spawned lazily on the first request. task-1337: the old `child !== null && …` made every real run
+     * refuse `L` with "the signer process died" before the signer had ever been started (the ticket
+     * checks `alive` before its first call); only the fake signer in the tests, alive from construction,
+     * ever reached LIVE. `dead` is the fail-closed marker: set once on exit/error/timeout/close, never reset.
+     */
+    get alive() { return this.dead === null; }
+    /** Spawn + handshake (idempotent). Rejects when the signer cannot start; never retries. */
+    start() {
+        if (this.dead)
+            return Promise.reject(new SignerUnavailableError(this.dead));
+        if (this.ready)
+            return this.ready;
+        this.ready = new Promise((resolve, reject) => {
+            const entry = this.opts.entry ?? defaultSignerEntry();
+            let child;
+            try {
+                child = spawn(process.execPath, [entry, ...this.argv], { stdio: ['pipe', 'pipe', 'pipe'], env: this.opts.env ?? process.env });
+            }
+            catch (e) {
+                this.dead = `spawn failed: ${e instanceof Error ? e.message : String(e)}`;
+                reject(new SignerUnavailableError(this.dead));
+                return;
+            }
+            this.child = child;
+            this.pid = child.pid ?? null;
+            let settled = false;
+            const readyTimer = setTimeout(() => { if (!settled) {
+                settled = true;
+                this.kill('signer did not become ready');
+                reject(new SignerUnavailableError('signer did not become ready'));
+            } }, this.opts.readyTimeoutMs ?? 15_000);
+            readyTimer.unref?.();
+            child.on('error', (e) => { this.markDead(`signer error: ${e.message}`); if (!settled) {
+                settled = true;
+                clearTimeout(readyTimer);
+                reject(new SignerUnavailableError(this.dead ?? 'signer error'));
+            } });
+            child.on('exit', (code, signal) => { this.markDead(`signer exited (${code ?? signal ?? '?'})`); if (!settled) {
+                settled = true;
+                clearTimeout(readyTimer);
+                reject(new SignerUnavailableError(this.dead ?? 'signer exited'));
+            } });
+            if (child.stderr)
+                createInterface({ input: child.stderr }).on('line', (l) => this.opts.log?.(l));
+            if (child.stdout) {
+                createInterface({ input: child.stdout, crlfDelay: Infinity }).on('line', (line) => {
+                    const d = decodeFrame(this.secret, line, this.inSeq);
+                    if (!d.ok) {
+                        this.opts.log?.(`signer client: dropped frame (${d.why})`);
+                        return;
+                    }
+                    this.inSeq = d.seq + 1;
+                    this.onMessage(d.message, () => { if (!settled) {
+                        settled = true;
+                        clearTimeout(readyTimer);
+                        resolve();
+                    } });
+                });
+            }
+            child.stdin?.on('error', () => { });
+            child.stdin?.write(encodeHello(this.secret));
+        });
+        return this.ready;
+    }
+    onMessage(m, onReady) {
+        if (isEvent(m)) {
+            if (m.event === 'ready')
+                onReady();
+            return;
+        }
+        if (!isResponse(m))
+            return;
+        const p = this.pending.get(m.id);
+        if (!p)
+            return;
+        this.pending.delete(m.id);
+        clearTimeout(p.timer);
+        if (m.ok)
+            p.resolve(m.result);
+        else
+            p.reject(new SignerUnavailableError(m.error, { reason: m.reason, retryAfterMs: m.retryAfterMs }));
+    }
+    markDead(why) {
+        if (this.dead)
+            return;
+        this.dead = why;
+        for (const [id, p] of this.pending) {
+            clearTimeout(p.timer);
+            this.pending.delete(id);
+            p.reject(new SignerUnavailableError(why));
+        }
+    }
+    kill(why) {
+        this.markDead(why);
+        try {
+            this.child?.kill('SIGTERM');
+        }
+        catch { /* ignore */ }
+    }
+    async request(method, params, timeoutMs = DEFAULT_TIMEOUTS[method] ?? 8_000) {
+        if (this.dead)
+            throw new SignerUnavailableError(this.dead);
+        await this.start();
+        if (this.dead || !this.child?.stdin)
+            throw new SignerUnavailableError(this.dead ?? 'signer has no stdin');
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(new SignerUnavailableError(`signer ${method} timed out after ${Math.round(timeoutMs / 1000)} s`)); }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, { resolve: resolve, reject, timer });
+            try {
+                this.child.stdin.write(encodeFrame(this.secret, this.outSeq++, { id, method, params }));
+            }
+            catch (e) {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                reject(new SignerUnavailableError(`write failed: ${e instanceof Error ? e.message : String(e)}`));
+            }
+        });
+    }
+    status() { return this.request('status', {}); }
+    plan(params) { return this.request('plan', { ...params }); }
+    probe() { return this.request('probe', {}); }
+    precheck(hash) { return this.request('precheck', { hash }); }
+    confirm(hash) { return this.request('confirm', { hash }); }
+    async drop(hash) { await this.request('drop', { hash }); }
+    async panic(reason) { await this.request('panic', { reason }); }
+    fast() { return this.request('fast', {}); }
+    fill(params) { return this.request('fill', { ...params }); }
+    quote(params) { return this.request('quote', { ...params }); }
+    close() {
+        this.markDead('closed');
+        try {
+            this.child?.stdin?.end();
+        }
+        catch { /* ignore */ }
+        const c = this.child;
+        if (c) {
+            const t = setTimeout(() => { try {
+                c.kill('SIGKILL');
+            }
+            catch { /* ignore */ } }, 2_000);
+            t.unref?.();
+            c.on('exit', () => clearTimeout(t));
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/packages/data/src/trade/signer/fast-wallet.js

@@ -0,0 +1,154 @@
+// task-1363 — the capped FAST WALLET (SPEC §6.13.2 `wallet: 'fast'`): the one key dexterm ever holds, and only
+// on DEVNET. Standing-mandate fills must run at machine speed, which a Phantom round-trip per fill cannot do,
+// so an armed mandate fires from this separate hot key instead of the user's main wallet. The main wallet is
+// never named by a mandate (the schema says `fast`), and this signer refuses to sign for any other public key.
+//
+// Boundaries, by construction:
+//   * devnet only — the record carries `network: 'devnet'`; create/load refuse anything else, and the signer
+//     process only loads it when ITS RPC endpoint classifies as devnet (signer/main.ts). There is no mainnet path.
+//   * created only by `dexterm wallet fast create` on a real TTY after a keypress; there is NO channel method
+//     to create, export, import or replace it (the signer protocol has `fast` = status and `fill` = build).
+//   * hard per-fill ceiling: a single fill may move at most FAST_MAX_SOL_PER_FILL SOL out of it (lamports
+//     bound at build and again on the signed bytes), on top of the signer's USD caps which this lane enforces
+//     even on devnet (task-1363: "per-trade and daily caps enforced signer-side").
+//   * the seed lives in ~/.dexterm/fast-wallet.json at mode 600 and never leaves this module: `get()` returns
+//     the public record only; `load()` returns a signer object with a sign method, not the key bytes.
+//
+// Ed25519 via node:crypto only (no wallet library). The signed wire tx is `shortvec(1) + sig + message`, the
+// same shape the executor decodes, compares to the approved message, Ed25519-verifies and re-simulates.
+import { createPrivateKey, createPublicKey, randomBytes, sign as edSign } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { base58 } from "../../sources/solana-rpc.js";
+import { decodeTransaction } from "../tx-decode.js";
+export const FAST_WALLET_NETWORK = 'devnet';
+/** Hard ceiling on the SOL a single mandate fill may move out of the fast wallet (devnet-sized). */
+export const FAST_MAX_SOL_PER_FILL = 0.05;
+export const FAST_MAX_SOL_PER_FILL_LAMPORTS = 50000000n;
+export const FAST_WALLET_PROVIDER = 'fast-wallet';
+const B58 = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+/** PKCS#8 DER prefix for an Ed25519 private key (RFC 8410): the 32-byte seed follows. */
+const PKCS8_ED25519_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+export function defaultFastWalletPath(env = process.env) {
+    const home = env.DEXTERM_HOME && env.DEXTERM_HOME.length ? env.DEXTERM_HOME : join(homedir(), '.dexterm');
+    return join(home, 'fast-wallet.json');
+}
+function privateKeyFromSeed(seed) {
+    if (seed.length !== 32)
+        throw new Error('fast wallet: seed must be 32 bytes');
+    return createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, seed]), format: 'der', type: 'pkcs8' });
+}
+function publicKeyOf(priv) {
+    const der = createPublicKey(priv).export({ format: 'der', type: 'spki' });
+    return base58(der.subarray(der.length - 32));
+}
+function shortvec(n) {
+    const out = [];
+    do {
+        let b = n & 0x7f;
+        n >>= 7;
+        if (n)
+            b |= 0x80;
+        out.push(b);
+    } while (n);
+    return Buffer.from(out);
+}
+/** The thing that signs: holds the key object, exposes only `publicKey` and `signTransaction`. */
+export class FastWalletSigner {
+    publicKey;
+    provider = FAST_WALLET_PROVIDER;
+    key;
+    constructor(seed) {
+        this.key = privateKeyFromSeed(seed);
+        this.publicKey = publicKeyOf(this.key);
+    }
+    /**
+     * Sign ONE transaction for the fast wallet itself (same call shape as the Phantom bridge, so the executor's
+     * pipeline is unchanged). Refuses: a caller expecting any other key, a transaction whose fee payer / sole
+     * required signer is not this wallet, more than one required signature, or undecodable bytes.
+     */
+    async signTransaction(args) {
+        const t0 = Date.now();
+        if (args.expectPublicKey !== undefined && args.expectPublicKey !== this.publicKey)
+            throw new Error('fast wallet: refusing to sign for a different public key');
+        const tx = decodeTransaction(Buffer.from(args.unsignedTxBase64, 'base64')); // throws on malformed bytes
+        if (tx.numRequiredSignatures !== 1)
+            throw new Error(`fast wallet: refusing a transaction with ${tx.numRequiredSignatures} required signatures`);
+        if (tx.staticKeys[0] !== this.publicKey)
+            throw new Error('fast wallet: the transaction fee payer is not the fast wallet');
+        const sig = edSign(null, tx.message, this.key);
+        const wire = Buffer.concat([shortvec(1), sig, tx.message]).toString('base64');
+        return { signedTxBase64: wire, provider: FAST_WALLET_PROVIDER, roundTripMs: Date.now() - t0 };
+    }
+}
+/**
+ * The on-disk record. `create` writes a fresh key (never overwrites), `get` reads the PUBLIC fields only,
+ * `load` returns a signer (or null when there is none / the file is unreadable or not devnet), `remove`
+ * deletes the file. Nothing here talks to the network.
+ */
+export class FastWalletStore {
+    path;
+    constructor(path = defaultFastWalletPath()) { this.path = path; }
+    exists() { return existsSync(this.path); }
+    read() {
+        try {
+            if (!existsSync(this.path))
+                return null;
+            const raw = JSON.parse(readFileSync(this.path, 'utf8'));
+            if (raw.v !== 1 || raw.network !== FAST_WALLET_NETWORK)
+                return null;
+            if (typeof raw.publicKey !== 'string' || !B58.test(raw.publicKey) || typeof raw.seed !== 'string')
+                return null;
+            return { v: 1, network: FAST_WALLET_NETWORK, publicKey: raw.publicKey, seed: raw.seed, createdAt: Number(raw.createdAt) || 0 };
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Public fields only (no seed). Null when absent/malformed. */
+    get() {
+        const r = this.read();
+        return r ? { publicKey: r.publicKey, network: r.network, createdAt: r.createdAt } : null;
+    }
+    /** A signer over the stored seed, or null. The seed is checked against the stored public key. */
+    load() {
+        const r = this.read();
+        if (!r)
+            return null;
+        try {
+            const signer = new FastWalletSigner(Buffer.from(r.seed, 'base64'));
+            return signer.publicKey === r.publicKey ? signer : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Create a NEW devnet fast wallet. Refuses to overwrite an existing one (remove it first, after draining)
+     * and refuses any network but devnet. The caller (the CLI) gates this behind a real TTY keypress.
+     */
+    create(opts) {
+        if (opts.network !== FAST_WALLET_NETWORK)
+            throw new Error('fast wallet: devnet only — there is no mainnet fast wallet');
+        if (this.exists())
+            throw new Error(`fast wallet: ${this.path} already exists; \`dexterm wallet fast remove\` first (after draining it)`);
+        const seed = randomBytes(32);
+        const signer = new FastWalletSigner(seed);
+        const rec = { v: 1, network: FAST_WALLET_NETWORK, publicKey: signer.publicKey, seed: seed.toString('base64'), createdAt: opts.now ?? Date.now() };
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, JSON.stringify(rec, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+        try {
+            chmodSync(this.path, 0o600);
+        }
+        catch { /* best effort on platforms without chmod */ }
+        return { publicKey: rec.publicKey, network: rec.network, createdAt: rec.createdAt };
+    }
+    /** Delete the record. Returns true when one existed. */
+    remove() {
+        if (!existsSync(this.path))
+            return false;
+        rmSync(this.path, { force: true });
+        return true;
+    }
+}

package/dist/packages/data/src/trade/signer/host.js

@@ -0,0 +1,97 @@
+// dexterm T2 — the signer HOST loop (task-1328): runs inside the signer process, reads authenticated
+// frames from `input` (the child's stdin), dispatches to the SignerService, and writes authenticated
+// responses to `output` (the child's stdout). Diagnostics go to `log` (stderr) and never carry bytes,
+// keys or the secret. Fails closed: a bad hello, too many bad frames, or a closed input ends the loop
+// (and the production entry exits the process).
+import { createInterface } from 'node:readline';
+import { decodeFrame, encodeFrame, isRequest, parseHello, MAX_BAD_FRAMES, MAX_FRAME_BYTES, SIGNER_METHODS } from "./protocol.js";
+/** Serve until the input ends. Resolves with the reason the loop stopped. */
+export function serveSigner(opts) {
+    const log = opts.log ?? (() => { });
+    return new Promise((resolve) => {
+        let secret = null;
+        let inSeq = 0;
+        let outSeq = 0;
+        let bad = 0;
+        let ended = false;
+        const rl = createInterface({ input: opts.input, crlfDelay: Infinity });
+        const end = (why) => {
+            if (ended)
+                return;
+            ended = true;
+            try {
+                rl.close();
+            }
+            catch { /* ignore */ }
+            opts.onEnd?.(why);
+            resolve(why);
+        };
+        const send = (m) => {
+            if (!secret)
+                return;
+            try {
+                opts.output.write(encodeFrame(secret, outSeq++, m));
+            }
+            catch (e) {
+                log(`signer: write failed: ${e instanceof Error ? e.message : String(e)}`);
+                end('output closed');
+            }
+        };
+        const strike = (why) => {
+            bad++;
+            log(`signer: dropped frame (${why}) ${bad}/${MAX_BAD_FRAMES}`);
+            if (bad >= MAX_BAD_FRAMES)
+                end('too many bad frames');
+        };
+        rl.on('line', (line) => {
+            if (ended)
+                return;
+            if (line.length > MAX_FRAME_BYTES) {
+                strike('too large');
+                return;
+            }
+            if (!secret) {
+                const h = parseHello(line);
+                if (!h) {
+                    end('bad hello');
+                    return;
+                }
+                secret = h.secret;
+                send({ event: 'ready', detail: { pid: process.pid } });
+                return;
+            }
+            const d = decodeFrame(secret, line, inSeq);
+            if (!d.ok) {
+                strike(d.why);
+                return;
+            }
+            inSeq = d.seq + 1;
+            const m = d.message;
+            if (!isRequest(m)) {
+                strike('not a request');
+                return;
+            }
+            const id = m.id;
+            if (!SIGNER_METHODS.has(m.method)) {
+                send({ id, ok: false, error: `unknown method ${JSON.stringify(String(m.method).slice(0, 32))}` });
+                return;
+            }
+            void opts.service.call(m.method, m.params).then((result) => send({ id, ok: true, result }), (e) => {
+                if (!(e instanceof Error)) {
+                    send({ id, ok: false, error: String(e) });
+                    return;
+                }
+                const reason = e.reason;
+                const retryAfterMs = e.retryAfterMs;
+                send({
+                    id, ok: false,
+                    error: `${typeof reason === 'string' ? `${reason}: ` : ''}${e.message}`,
+                    ...(typeof reason === 'string' ? { reason } : {}),
+                    ...(typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) ? { retryAfterMs } : {}),
+                });
+            });
+        });
+        rl.on('close', () => end('input closed'));
+        opts.input.on('error', () => end('input error'));
+    });
+}

package/dist/packages/data/src/trade/signer/main.js

@@ -0,0 +1,121 @@
+// dexterm T2 — the signer PROCESS entry (task-1328). `node main.ts [caps flags]`. Wires the real
+// dependencies — its OWN HTTP client for Jupiter + RPC, its OWN SOL/USD feed, the wallet bridge (opens
+// the system browser for Phantom), the kill-switch file, the shared daily-cap ledger and the live fill
+// ledger — and serves the authenticated stdio channel until the parent closes it.
+//
+// Caps come from THIS process's argv (what the user typed when starting dexterm), clamped to the hard
+// ceilings and, without --mainnet, only ever DOWN from the defaults. Nothing on the channel can change
+// them. The RPC defaults to DEVNET; `--mainnet` switches to the user's configured mainnet RPC
+// (DEXTERM_RPC_URL / ~/.dexterm/helius.key / public). `--rpc URL` is honoured but the NETWORK the
+// signer reports and caps by is always classified from the URL it will actually talk to.
+import { createDataLayer } from "../../index.js";
+import { JupiterSwapBuild } from "../swap-build.js";
+import { TradeRpc, DEVNET_RPC, rpcNetwork } from "../rpc-exec.js";
+import { WalletBridge } from "../bridge.js";
+import { defaultCaps, capsOnlyDownward, CapLedger, defaultCapLedgerPath, HARD_MAX_PER_TRADE_USD, HARD_MAX_DAILY_USD, HARD_MAX_SOL_OUT, HARD_MAX_SLIPPAGE_BPS } from "../caps.js";
+import { LiveExecutor, LiveLedger, defaultLiveLedgerPath } from "../executor.js";
+import { KillSwitch, defaultPanicPath } from "../kill-switch.js";
+import { WalletLinkStore, defaultLinkPath } from "../link-store.js";
+import { resolveRpcUrl } from "../../rpc-config.js";
+import { DevnetProbeBuilder } from "./probe-builder.js";
+import { SolUsdFeed } from "./sol-usd-feed.js";
+import { FastWalletStore, defaultFastWalletPath } from "./fast-wallet.js";
+import { SignerService } from "./service.js";
+import { serveSigner } from "./host.js";
+/** Parse the signer's argv. Over-ceiling caps are an error (never silently accepted). */
+export function parseSignerArgs(argv, env = process.env) {
+    let mainnet = false;
+    let perTradeUsd, dailyUsd, maxSolOut, maxSlippageBps;
+    let rpcUrl;
+    let ledgerPath = defaultCapLedgerPath(), liveLedgerPath = defaultLiveLedgerPath(), linkPath = defaultLinkPath(), panicPath = defaultPanicPath();
+    let fastWalletPath = defaultFastWalletPath(env);
+    let noBrowser = false;
+    const take = (flag, raw, ceiling) => {
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0)
+            return undefined;
+        if (n > ceiling)
+            throw new Error(`${flag} ${n} exceeds the hard ceiling of ${ceiling}`);
+        return n;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const k = argv[i];
+        if (k === '--mainnet')
+            mainnet = true;
+        else if (k === '--max-usd')
+            perTradeUsd = take(k, argv[++i], HARD_MAX_PER_TRADE_USD);
+        else if (k === '--daily-usd')
+            dailyUsd = take(k, argv[++i], HARD_MAX_DAILY_USD);
+        else if (k === '--max-sol-out')
+            maxSolOut = take(k, argv[++i], HARD_MAX_SOL_OUT);
+        else if (k === '--max-slippage-bps')
+            maxSlippageBps = take(k, argv[++i], HARD_MAX_SLIPPAGE_BPS);
+        else if (k === '--rpc')
+            rpcUrl = argv[++i];
+        else if (k === '--ledger')
+            ledgerPath = argv[++i];
+        else if (k === '--live-ledger')
+            liveLedgerPath = argv[++i];
+        else if (k === '--link')
+            linkPath = argv[++i];
+        else if (k === '--panic-file')
+            panicPath = argv[++i];
+        else if (k === '--fast-wallet')
+            fastWalletPath = argv[++i];
+        else if (k === '--no-browser')
+            noBrowser = true;
+    }
+    const caps = capsOnlyDownward(defaultCaps({ network: mainnet ? 'mainnet' : 'devnet', mainnetEnabled: mainnet, perTradeUsd, dailyUsd, maxSolOut, maxSlippageBps }));
+    // The RPC: explicit --rpc, else devnet; with --mainnet the user's configured mainnet endpoint.
+    const url = rpcUrl ?? (mainnet ? resolveRpcUrl({ env }).url : DEVNET_RPC);
+    // Never let a devnet-labelled signer talk to mainnet by accident: without --mainnet a non-devnet URL is refused.
+    if (!mainnet && rpcNetwork(url) !== 'devnet')
+        throw new Error('without --mainnet the signer RPC must be a devnet endpoint');
+    return { caps, rpcUrl: url, ledgerPath, liveLedgerPath, linkPath, panicPath, fastWalletPath, noBrowser };
+}
+/**
+ * task-1368: the signer's own `jupiter` bucket carries only its quote/build calls (a handful per ticket), so after a
+ * 429 it pauses from this base (doubling per consecutive 429, capped as before) instead of the data layer's 30 s —
+ * which was tuned for the terminal's enrichment flood and made every retry inside the 10 s budget impossible.
+ * Retry-After from the server still wins when it is longer.
+ */
+export const SIGNER_RATE_LIMIT_PAUSE_MS = 3_000;
+export function buildSignerService(a, log) {
+    const dl = createDataLayer({ dbPath: ':memory:', rpcUrl: a.rpcUrl, rpcFallbackUrl: null, rateLimitPauseMs: SIGNER_RATE_LIMIT_PAUSE_MS });
+    const rpc = new TradeRpc(dl.http, { url: a.rpcUrl, clock: dl.clock });
+    const build = new JupiterSwapBuild(dl.http);
+    const bridge = new WalletBridge(a.noBrowser ? { open: (url) => { log(`signer: open this page to approve: ${url}`); } } : {});
+    const ledger = new CapLedger({ path: a.ledgerPath, clock: dl.clock });
+    const liveLedger = new LiveLedger({ path: a.liveLedgerPath, clock: dl.clock });
+    const killSwitch = new KillSwitch(a.panicPath);
+    const linkStore = new WalletLinkStore(a.linkPath);
+    const feed = new SolUsdFeed({ clock: dl.clock });
+    // task-1363: the capped fast wallet is loaded ONLY against a devnet RPC (by classification of the URL the
+    // signer will actually talk to). On mainnet there is no fast signer, so `fill` and fast-lane confirms refuse.
+    const fastStore = new FastWalletStore(a.fastWalletPath);
+    const fastSigner = rpc.network === 'devnet' ? fastStore.load() ?? undefined : undefined;
+    if (fastSigner)
+        log(`signer: fast wallet loaded (devnet) ${fastSigner.publicKey}`);
+    const deps = { build, rpc, bridge, caps: a.caps, ledger, liveLedger, clock: dl.clock, solUsd: () => feed.samples(), killSwitch, probe: new DevnetProbeBuilder(rpc), fastSigner };
+    const executor = new LiveExecutor(deps);
+    return new SignerService({ executor, deps, linkStore, liveLedger, solUsdFeed: feed, clock: dl.clock, fastStore, log });
+}
+export async function main(argv) {
+    const log = (l) => process.stderr.write(`${l}\n`);
+    let args;
+    try {
+        args = parseSignerArgs(argv);
+    }
+    catch (e) {
+        log(`signer: ${e instanceof Error ? e.message : String(e)}`);
+        return 2;
+    }
+    const service = buildSignerService(args, log);
+    const why = await serveSigner({ service, input: process.stdin, output: process.stdout, log });
+    log(`signer: stopped (${why})`);
+    return why === 'input closed' ? 0 : 1;
+}
+// Run when executed directly (never when imported by the client or the tests).
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    main(process.argv.slice(2)).then((code) => { process.exitCode = code; process.stdin.destroy(); }, (e) => { process.stderr.write(`signer: fatal ${e instanceof Error ? e.message : String(e)}\n`); process.exitCode = 1; });
+}

package/dist/packages/data/src/trade/signer/probe-builder.js

@@ -0,0 +1,85 @@
+// dexterm T2 — the DEVNET PROBE transaction builder (task-1328). Jupiter has no devnet, so the way to
+// prove the real signing path end to end on devnet — keypress → Phantom sign → decode/verify →
+// re-simulate → submit → confirm — without any value at risk is a transaction dexterm builds itself:
+// the wrap-and-unwrap shape a Jupiter swap uses around its route, with NO route:
+//
+//   AssociatedToken.CreateIdempotent(wallet's WSOL ATA)  ·  System.Transfer(wallet → WSOL ATA, 0.001 SOL)
+//   Token.SyncNative(WSOL ATA)  ·  Memo("dexterm devnet probe")  ·  Token.CloseAccount(WSOL ATA → wallet)
+//
+// The close returns the lamports (and the ATA rent) to the wallet in the same transaction, so the only
+// SOL that leaves is the network fee. The signer's policy for the probe kind refuses any other shape, and
+// the probe is refused outright unless the RPC endpoint classifies as devnet. No key, no network write:
+// this module only builds bytes; the executor simulates and the wallet signs.
+import { base58Decode } from "../../sources/pda.js";
+import { rpcNetwork } from "../rpc-exec.js";
+import { associatedTokenAddress, ASSOCIATED_TOKEN_PROGRAM, SYSTEM_PROGRAM, TOKEN_PROGRAM, MEMO_PROGRAM, WSOL_MINT } from "../tx-decode.js";
+export const PROBE_LAMPORTS = 1000000n; // 0.001 SOL, wrapped then unwrapped in the same tx
+export const PROBE_MEMO = 'dexterm devnet probe';
+function shortvec(n) {
+    const out = [];
+    do {
+        let b = n & 0x7f;
+        n >>= 7;
+        if (n)
+            b |= 0x80;
+        out.push(b);
+    } while (n);
+    return Buffer.from(out);
+}
+/**
+ * Compile a LEGACY message (no lookup tables needed) with the wallet as the single signer/fee payer.
+ * Key order follows the runtime's rule: writable signers, then writable non-signers, then readonly
+ * non-signers. Exported for the tests (they decode what this builds with the real decoder).
+ */
+export function compileProbeMessage(user, blockhash, lamports = PROBE_LAMPORTS, memo = PROBE_MEMO) {
+    const wsolAta = associatedTokenAddress(user, WSOL_MINT, TOKEN_PROGRAM);
+    const transfer = Buffer.alloc(12);
+    transfer.writeUInt32LE(2, 0);
+    transfer.writeBigUInt64LE(lamports, 4);
+    const ixs = [
+        { program: ASSOCIATED_TOKEN_PROGRAM, accounts: [user, wsolAta, user, WSOL_MINT, SYSTEM_PROGRAM, TOKEN_PROGRAM], data: Buffer.from([1]) },
+        { program: SYSTEM_PROGRAM, accounts: [user, wsolAta], data: transfer },
+        { program: TOKEN_PROGRAM, accounts: [wsolAta], data: Buffer.from([17]) },
+        { program: MEMO_PROGRAM, accounts: [], data: Buffer.from(memo, 'utf8') },
+        { program: TOKEN_PROGRAM, accounts: [wsolAta, user, user], data: Buffer.from([9]) },
+    ];
+    const writable = [user, wsolAta];
+    const readonly = [WSOL_MINT, SYSTEM_PROGRAM, TOKEN_PROGRAM, ASSOCIATED_TOKEN_PROGRAM, MEMO_PROGRAM];
+    const keys = [...writable, ...readonly];
+    const index = (k) => { const i = keys.indexOf(k); if (i < 0)
+        throw new Error(`probe: unknown key ${k}`); return i; };
+    const parts = [Buffer.from([1, 0, readonly.length]), shortvec(keys.length)];
+    for (const k of keys)
+        parts.push(Buffer.from(base58Decode(k)));
+    parts.push(Buffer.from(base58Decode(blockhash)), shortvec(ixs.length));
+    for (const ix of ixs) {
+        const acc = ix.accounts.map(index);
+        parts.push(Buffer.from([index(ix.program)]), shortvec(acc.length), Buffer.from(acc), shortvec(ix.data.length), ix.data);
+    }
+    return Buffer.concat(parts);
+}
+/** The unsigned wire transaction (one zero signature slot + the message), base64. */
+export function probeWire(message) {
+    return Buffer.concat([shortvec(1), Buffer.alloc(64), message]).toString('base64');
+}
+export class DevnetProbeBuilder {
+    rpc;
+    constructor(rpc) { this.rpc = rpc; }
+    /**
+     * The probe (0.001 SOL, the fixed memo) or — task-1363 — a DEVNET FILL for the fast wallet: the same
+     * wrap-and-unwrap shape sized to a plan's SOL leg, with a memo naming the plan leg. Devnet only either way.
+     */
+    async build(userPublicKey, opts = {}) {
+        if (rpcNetwork(this.rpc.url, this.rpc.network ?? null) !== 'devnet')
+            throw new Error('the probe builds only against a devnet RPC endpoint');
+        if (base58Decode(userPublicKey).length !== 32)
+            throw new Error('probe: bad wallet public key');
+        const lamports = opts.lamports ?? PROBE_LAMPORTS;
+        if (!(lamports > 0n))
+            throw new Error('probe: lamports must be positive');
+        const memo = (opts.memo ?? PROBE_MEMO).replace(/[^\x20-\x7e]/g, '?').slice(0, 96);
+        const { blockhash } = await this.rpc.latestBlockhash();
+        const message = compileProbeMessage(userPublicKey, blockhash, lamports, memo);
+        return { txBase64: probeWire(message), lamports };
+    }
+}