perp-cli 0.12.17 → 0.14.1

package/dist/jobs.d.ts

@@ -1,3 +1,5 @@
+import type { Command } from "commander";
+import type { Network } from "./exchanges/venue-types.js";
 export interface JobEntry {
     id: string;
     strategy: string;
@@ -9,24 +11,86 @@ export interface JobEntry {
     status: "running" | "stopped" | "done" | "error";
     result?: Record<string, unknown>;
 }
+export declare function assertTmuxSessionName(name: string): string;
 export declare function logFile(id: string): string;
+/** Kill a tmux session by (validated) name, without a shell. */
+export declare function killTmuxSession(name: string): void;
 export declare function saveJob(job: JobEntry): void;
 export declare function loadJob(id: string): JobEntry | null;
 export declare function listJobs(): JobEntry[];
 /**
- * Start a job in a tmux background session.
- * Returns the job entry.
+ * Root flags that pick WHICH account / market a command uses. A background child
+ * must run with the same ones as its parent (otherwise it silently trades another
+ * wallet, skips the agent, or another HIP-3 dex). Only non-secret selectors are
+ * forwarded; the child resolves the credentials themselves (OWS vault / agent keystores).
+ */
+export interface JobRootSelectors {
+    /** --ows <name> */
+    ows: string | null;
+    /** -w, --wallet <name> */
+    wallet: string | null;
+    /** --no-agent */
+    noAgent: boolean;
+    /** --dex <name> (Hyperliquid HIP-3) */
+    dex: string | null;
+    /** --no-builder (no builder fee on this run's orders) */
+    noBuilder: boolean;
+}
+/**
+ * The parent's root selectors, read from the root program. Throws INVALID_PARAMS when the
+ * parent was given key material on argv (-k / --passphrase / --ows-key): it cannot be handed
+ * to the child (argv and env are visible in the process list), and the child would otherwise
+ * sign with a different account or fail on the passphrase.
  */
-export declare function startJob(opts: {
+export declare function jobSelectorsOf(cmd: Command): JobRootSelectors;
+/** Options for a background job: `cliArgs` is the child's full command (path + args), e.g. ["strategy", "grid", "BTC"]. */
+export interface StartJobOpts {
     strategy: string;
     exchange: string;
     params: Record<string, unknown>;
+    /** Root `-e` for the child (omit for multi-venue commands). */
+    venue?: string;
+    /** The parent's validated `-n` — the child always runs on the same network. */
+    network: Network;
+    /** The parent's root `--dry-run` — inherited by the child. */
+    dryRun: boolean;
+    /** The parent's account / market selectors (jobSelectorsOf) — inherited by the child. */
+    selectors: JobRootSelectors;
     cliArgs: string[];
-}): JobEntry;
+}
 /**
- * Stop a running job.
+ * The child's argv after `node <cli>`: root flags first (`-n`, `--dry-run`, `-e`,
+ * `--ows`, `-w`, `--no-agent`, `--dex`, `--no-builder`), then the real command path + args, then
+ * `--job-id`. Every target command must exist in buildProgram() and declare
+ * `--job-id` (regression-tested).
  */
-export declare function stopJob(id: string): boolean;
+export declare function jobArgv(opts: StartJobOpts, id: string): string[];
+/**
+ * Start a job in a tmux background session.
+ * Returns the job entry.
+ */
+export declare function startJob(opts: StartJobOpts): JobEntry;
+/** Outcome of stopJob: how the job ended. */
+export interface StopJobResult {
+    /** "notRunning": the session was already gone; "graceful": the job exited after SIGINT within the timeout; "forced": it did not — the session was killed (no cleanup ran). */
+    outcome: "notRunning" | "graceful" | "forced";
+    /** Why a graceful stop could not be attempted / finish (null when graceful / not running). */
+    note: string | null;
+    waitedMs: number;
+}
+/**
+ * Default wait for a job to finish its own cleanup after SIGINT. A daemon that receives SIGINT
+ * mid-entry finishes the verified leg sequence (or its rollback) first — that alone can take
+ * longer than 30s on a slow venue — so the default leaves room for one full verified pair.
+ */
+export declare const JOB_STOP_TIMEOUT_MS = 90000;
+/**
+ * Stop a running job GRACEFULLY: SIGINT to the job's node process (every bot handles it: cancel
+ * its orders, save state), then wait up to `timeoutMs` for the job to exit; only if it is still
+ * running, kill the tmux session ("forced" — the job's own cleanup did not run). Never a silent
+ * kill: the outcome says which happened.
+ */
+export declare function stopJob(id: string, timeoutMs?: number): Promise<StopJobResult | null>;
 /**
  * Update job state file (called from within the running job).
  */
@@ -35,3 +99,17 @@ export declare function updateJobState(id: string, data: Partial<JobEntry>): voi
  * Remove a job entry.
  */
 export declare function removeJob(id: string): boolean;
+/**
+ * The tmux shell command for a child: `env -u <secret>... node cli <argv>`.
+ * `env -u` removes secrets the tmux server's global environment may carry (a server started
+ * earlier from another shell). Only variable NAMES of secrets ever appear on the command line.
+ */
+export declare function childShellCommand(nodeCmd: string, cliPath: string, argv: string[], log: string | null, env: NodeJS.ProcessEnv): string;
+/**
+ * Launch `node <cli> <argv>` in a detached tmux session. The child never receives key
+ * material: every secret var is stripped from the tmux client's env (a fresh tmux server
+ * inherits it) and from the session command (`env -u`). `needsCredentials`: the child
+ * signs, so a shell-only secret env var (one the child cannot re-read from ~/.perp/.env)
+ * is refused with INVALID_PARAMS instead of silently switching the child's account.
+ */
+export declare function launchTmuxChild(session: string, argv: string[], log: string | null, needsCredentials: boolean): void;

package/dist/jobs.js

@@ -1,13 +1,37 @@
-import { execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { execFileSync, execSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
+import { parse as parseDotenv } from "dotenv";
+import { PerpError } from "./errors.js";
+import { QFEX_AUTOMATION_VERIFIED, QFEX_REDUCE_ONLY_WIRE, qfexAutomationGate, qfexReduceOnlyGate } from "./exchanges/qfex/signing.js";
+import { startRefusal } from "./exchanges/trading-v2.js";
+import { scrubSecretEnv, secretEnvNamesIn } from "./secret-env.js";
 const JOBS_DIR = join(homedir(), ".perp", "jobs");
 const LOGS_DIR = join(homedir(), ".perp", "logs");
 function ensureDirs() {
-    mkdirSync(JOBS_DIR, { recursive: true });
-    mkdirSync(LOGS_DIR, { recursive: true });
+    mkdirSync(JOBS_DIR, { recursive: true, mode: 0o700 });
+    mkdirSync(LOGS_DIR, { recursive: true, mode: 0o700 });
+}
+/**
+ * tmux session names we create: "perp-<hex id>" (jobs) / "perp-alerts-<base36>" (alerts).
+ * A name read back from a job file is validated before it reaches tmux (review L6) — tmux is
+ * also invoked without a shell (execFileSync), so a tampered name can never run a command.
+ */
+const TMUX_SESSION_RE = /^perp-[A-Za-z0-9_-]{1,64}$/;
+export function assertTmuxSessionName(name) {
+    if (!TMUX_SESSION_RE.test(name)) {
+        throw new PerpError("INVALID_PARAMS", `Invalid tmux session name ${JSON.stringify(name)}`, {
+            remediation: "Job files under ~/.perp/jobs must hold a perp-<id> session name; remove the corrupted job: perp background remove <id>",
+        });
+    }
+    return name;
+}
+/** Write a job/log file owner-only (0600) — they hold strategy params and order logs. */
+function writePrivate(path, data, flag) {
+    writeFileSync(path, data, { mode: 0o600, flag });
+    chmodSync(path, 0o600);
 }
 function jobFile(id) {
     return join(JOBS_DIR, `${id}.json`);
@@ -20,7 +44,7 @@ function genId() {
 }
 function hasTmux() {
     try {
-        execSync("which tmux", { stdio: "ignore" });
+        execSync("which tmux", { stdio: "ignore", env: scrubSecretEnv(process.env) });
         return true;
     }
     catch {
@@ -28,17 +52,22 @@ function hasTmux() {
     }
 }
 function tmuxSessionExists(name) {
+    const session = assertTmuxSessionName(name);
     try {
-        execSync(`tmux has-session -t ${name} 2>/dev/null`, { stdio: "ignore" });
+        execFileSync("tmux", ["has-session", "-t", session], { stdio: "ignore", env: scrubSecretEnv(process.env) });
         return true;
     }
     catch {
         return false;
     }
 }
+/** Kill a tmux session by (validated) name, without a shell. */
+export function killTmuxSession(name) {
+    execFileSync("tmux", ["kill-session", "-t", assertTmuxSessionName(name)], { stdio: "ignore", env: scrubSecretEnv(process.env) });
+}
 export function saveJob(job) {
     ensureDirs();
-    writeFileSync(jobFile(job.id), JSON.stringify(job, null, 2));
+    writePrivate(jobFile(job.id), JSON.stringify(job, null, 2), "w");
 }
 export function loadJob(id) {
     const path = jobFile(id);
@@ -60,11 +89,83 @@ export function listJobs() {
     });
 }
 import { readdirSync } from "node:fs";
+const SECRET_HANDOFF_REMEDIATION = "Background jobs never receive key material. Import the master key into the OWS vault (perp wallet set <exchange>) " +
+    "and select it with --ows/-w, and register an agent (perp wallet agent approve <venue>) — agent keys sign without the " +
+    "master passphrase. Keys in ~/.perp/.env are re-read by the job itself.";
+/**
+ * The parent's root selectors, read from the root program. Throws INVALID_PARAMS when the
+ * parent was given key material on argv (-k / --passphrase / --ows-key): it cannot be handed
+ * to the child (argv and env are visible in the process list), and the child would otherwise
+ * sign with a different account or fail on the passphrase.
+ */
+export function jobSelectorsOf(cmd) {
+    let root = cmd;
+    while (root.parent)
+        root = root.parent;
+    const o = root.opts();
+    const secretFlags = [
+        ...(o.privateKey !== undefined ? ["-k/--private-key"] : []),
+        ...(o.passphrase !== undefined ? ["--passphrase"] : []),
+        ...(o.owsKey !== undefined ? ["--ows-key"] : []),
+    ];
+    if (secretFlags.length > 0) {
+        throw new PerpError("INVALID_PARAMS", `--background cannot hand ${secretFlags.join(", ")} to the background job`, {
+            remediation: `Drop ${secretFlags.join(", ")}. ${SECRET_HANDOFF_REMEDIATION}`,
+        });
+    }
+    return {
+        ows: o.ows ?? null,
+        wallet: o.wallet ?? null,
+        // Commander's --no-agent sets opts.agent === false.
+        noAgent: o.agent === false,
+        dex: o.dex ?? null,
+        // Commander's --no-builder sets opts.builder === false.
+        noBuilder: o.builder === false,
+    };
+}
+/**
+ * The child's argv after `node <cli>`: root flags first (`-n`, `--dry-run`, `-e`,
+ * `--ows`, `-w`, `--no-agent`, `--dex`, `--no-builder`), then the real command path + args, then
+ * `--job-id`. Every target command must exist in buildProgram() and declare
+ * `--job-id` (regression-tested).
+ */
+export function jobArgv(opts, id) {
+    const sel = opts.selectors;
+    return [
+        "-n", opts.network,
+        ...(opts.dryRun ? ["--dry-run"] : []),
+        ...(opts.venue !== undefined ? ["-e", opts.venue] : []),
+        ...(sel.ows !== null ? ["--ows", sel.ows] : []),
+        ...(sel.wallet !== null ? ["-w", sel.wallet] : []),
+        ...(sel.noAgent ? ["--no-agent"] : []),
+        ...(sel.dex !== null ? ["--dex", sel.dex] : []),
+        ...(sel.noBuilder ? ["--no-builder"] : []),
+        ...opts.cliArgs,
+        "--job-id", id,
+    ];
+}
+const shQuote = (a) => `'${a.replace(/'/g, "'\\''")}'`;
 /**
  * Start a job in a tmux background session.
  * Returns the job entry.
  */
 export function startJob(opts) {
+    // A background job trades unattended: refuse to start one on QFEX while its reduce-only
+    // (closing) orders are gated — it could open a position it cannot close — or while automation
+    // is unverified there (no stop orders: no protective exit). Dry runs send nothing.
+    if (!opts.dryRun) {
+        for (const v of new Set([opts.venue, opts.exchange])) {
+            if (v === undefined || v.toLowerCase() !== "qfex")
+                continue;
+            const what = `Background job "${opts.strategy}"`;
+            const reduceOnly = qfexReduceOnlyGate(QFEX_REDUCE_ONLY_WIRE);
+            if (reduceOnly !== null)
+                throw startRefusal(what, "it could open a position it cannot close", reduceOnly);
+            const automation = qfexAutomationGate(QFEX_AUTOMATION_VERIFIED);
+            if (automation !== null)
+                throw startRefusal(what, "it would trade unattended", automation);
+        }
+    }
     if (!hasTmux()) {
         throw new Error("tmux is required for background jobs. Install with: brew install tmux");
     }
@@ -72,14 +173,8 @@ export function startJob(opts) {
     const id = genId();
     const session = `perp-${id}`;
     const log = logFile(id);
-    // Build the command — re-invoke ourselves with `run` subcommand
-    const nodeCmd = process.argv[0];
-    const cliPath = process.argv[1];
-    const envVars = buildEnvString();
-    const args = opts.cliArgs.join(" ");
-    const cmd = `${envVars} ${nodeCmd} ${cliPath} run ${opts.strategy} ${args} --job-id ${id} 2>&1 | tee -a ${log}`;
-    // Create tmux session
-    execSync(`tmux new-session -d -s ${session} '${cmd.replace(/'/g, "'\\''")}'`);
+    // Re-invoke ourselves with the real command (jobArgv) — no key material on argv or env.
+    launchTmuxChild(session, jobArgv(opts, id), log, true);
     const job = {
         id,
         strategy: opts.strategy,
@@ -93,21 +188,95 @@ export function startJob(opts) {
     return job;
 }
 /**
- * Stop a running job.
+ * Default wait for a job to finish its own cleanup after SIGINT. A daemon that receives SIGINT
+ * mid-entry finishes the verified leg sequence (or its rollback) first — that alone can take
+ * longer than 30s on a slow venue — so the default leaves room for one full verified pair.
+ */
+export const JOB_STOP_TIMEOUT_MS = 90_000;
+/**
+ * The pid of the job's node process inside the tmux pane: the pane runs
+ * `sh -c "env … node <cli> … | tee -a <log>"`, so it is the pane shell's child that is not `tee`
+ * (`env` execs node, keeping its pid). null when it cannot be identified.
  */
-export function stopJob(id) {
+function jobNodePid(session) {
+    const env = scrubSecretEnv(process.env);
+    let panePid;
+    try {
+        panePid = Number(execFileSync("tmux", ["list-panes", "-t", assertTmuxSessionName(session), "-F", "#{pane_pid}"], { env, encoding: "utf8" }).trim().split("\n")[0]);
+    }
+    catch {
+        return null;
+    }
+    if (!Number.isInteger(panePid) || panePid <= 0)
+        return null;
+    let rows;
+    try {
+        rows = execFileSync("ps", ["-o", "pid=,ppid=,comm="], { env, encoding: "utf8" });
+    }
+    catch {
+        return null;
+    }
+    const kids = rows.split("\n").map(l => l.trim().split(/\s+/)).filter(c => c.length >= 3 && Number(c[1]) === panePid);
+    const node = kids.filter(c => !/(^|\/)tee$/.test(c[2]));
+    if (node.length !== 1)
+        return null;
+    const pid = Number(node[0][0]);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+/**
+ * Stop a running job GRACEFULLY: SIGINT to the job's node process (every bot handles it: cancel
+ * its orders, save state), then wait up to `timeoutMs` for the job to exit; only if it is still
+ * running, kill the tmux session ("forced" — the job's own cleanup did not run). Never a silent
+ * kill: the outcome says which happened.
+ */
+export async function stopJob(id, timeoutMs = JOB_STOP_TIMEOUT_MS) {
     const job = loadJob(id);
     if (!job)
-        return false;
-    if (tmuxSessionExists(job.tmuxSession)) {
-        try {
-            execSync(`tmux kill-session -t ${job.tmuxSession}`);
+        return null;
+    const started = Date.now();
+    let result;
+    if (!tmuxSessionExists(job.tmuxSession)) {
+        result = { outcome: "notRunning", note: null, waitedMs: 0 };
+    }
+    else {
+        // Mark the stop BEFORE the SIGINT: the job's own final updateJobState (status "done") must
+        // not overwrite it (updateJobState keeps "stopped").
+        job.status = "stopped";
+        saveJob(job);
+        const pid = jobNodePid(job.tmuxSession);
+        let note = null;
+        if (pid === null)
+            note = "the job's process could not be identified in its tmux pane — no SIGINT was sent";
+        else {
+            try {
+                process.kill(pid, "SIGINT");
+            }
+            catch (e) {
+                note = `SIGINT to pid ${pid} failed: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        if (note === null) {
+            while (tmuxSessionExists(job.tmuxSession) && Date.now() - started < timeoutMs) {
+                await new Promise(r => setTimeout(r, 250));
+            }
+        }
+        if (!tmuxSessionExists(job.tmuxSession)) {
+            result = { outcome: "graceful", note: null, waitedMs: Date.now() - started };
+        }
+        else {
+            try {
+                killTmuxSession(job.tmuxSession);
+            }
+            catch { /* exited between has-session and kill-session */ }
+            result = { outcome: "forced", note: note ?? `the job did not exit within ${Math.round(timeoutMs / 1000)}s of SIGINT`, waitedMs: Date.now() - started };
         }
-        catch { /* already dead */ }
     }
-    job.status = "stopped";
-    saveJob(job);
-    return true;
+    // Re-read: the job wrote its final result while it shut down — keep it, add the stop outcome.
+    const latest = loadJob(id) ?? job;
+    latest.status = "stopped";
+    latest.result = { ...(latest.result ?? {}), stop: result };
+    saveJob(latest);
+    return result;
 }
 /**
  * Update job state file (called from within the running job).
@@ -116,7 +285,10 @@ export function updateJobState(id, data) {
     const job = loadJob(id);
     if (!job)
         return;
-    Object.assign(job, data);
+    // A job stopped by `perp background stop` stays "stopped": its final write (done / error)
+    // only merges the result.
+    const status = job.status === "stopped" ? "stopped" : (data.status ?? job.status);
+    Object.assign(job, data, { status });
     saveJob(job);
 }
 /**
@@ -134,21 +306,47 @@ export function removeJob(id) {
     return true;
 }
 /**
- * Build env string to pass through to tmux session.
+ * Secret env vars the parent holds that the child could NOT re-read itself (i.e. not
+ * from ~/.perp/.env). Handing them over would put key material on the child's env;
+ * dropping them would make the child sign with a different account — so refuse.
  */
-function buildEnvString() {
-    const keys = [
-        // L2 agent key now lives in ~/.perp/lighter-agents/*.json (SSOT Rule #3),
-        // accountIndex/apiKeyIndex live in settings.agents.lighter — none need env passthrough.
-        "LIGHTER_PRIVATE_KEY",
-        "PRIVATE_KEY", "pk",
-        "PACIFICA_BUILDER_CODE", "NEXT_PUBLIC_BUILDER_CODE",
-        "HL_REFERRAL_CODE", "LIGHTER_REFERRAL_CODE",
-    ];
-    const parts = [];
-    for (const k of keys) {
-        if (process.env[k])
-            parts.push(`${k}='${process.env[k].replace(/'/g, "'\"'\"'")}'`);
+function shellOnlySecrets(env) {
+    const envFile = join(process.env.HOME || homedir(), ".perp", ".env");
+    const fromFile = existsSync(envFile) ? parseDotenv(readFileSync(envFile, "utf-8")) : {};
+    return secretEnvNamesIn(env).filter((k) => {
+        const v = env[k];
+        return v !== undefined && v !== "" && fromFile[k] !== v;
+    });
+}
+/**
+ * The tmux shell command for a child: `env -u <secret>... node cli <argv>`.
+ * `env -u` removes secrets the tmux server's global environment may carry (a server started
+ * earlier from another shell). Only variable NAMES of secrets ever appear on the command line.
+ */
+export function childShellCommand(nodeCmd, cliPath, argv, log, env) {
+    const unset = secretEnvNamesIn(env).flatMap((k) => ["-u", k]);
+    // No config env passthrough: builder fees come from settings.json (read by the child) only.
+    const parts = ["env", ...unset, nodeCmd, cliPath, ...argv].map(shQuote).join(" ");
+    return log === null ? parts : `${parts} 2>&1 | tee -a ${shQuote(log)}`;
+}
+/**
+ * Launch `node <cli> <argv>` in a detached tmux session. The child never receives key
+ * material: every secret var is stripped from the tmux client's env (a fresh tmux server
+ * inherits it) and from the session command (`env -u`). `needsCredentials`: the child
+ * signs, so a shell-only secret env var (one the child cannot re-read from ~/.perp/.env)
+ * is refused with INVALID_PARAMS instead of silently switching the child's account.
+ */
+export function launchTmuxChild(session, argv, log, needsCredentials) {
+    const shellOnly = needsCredentials ? shellOnlySecrets(process.env) : [];
+    if (shellOnly.length > 0) {
+        throw new PerpError("INVALID_PARAMS", `--background cannot hand ${shellOnly.join(", ")} (set in the shell environment) to the background job`, {
+            remediation: `Unset ${shellOnly.join(", ")}. ${SECRET_HANDOFF_REMEDIATION}`,
+        });
     }
-    return parts.join(" ");
+    assertTmuxSessionName(session);
+    // The log is created owner-only BEFORE tee appends to it (tee would create it 0644).
+    if (log !== null)
+        writePrivate(log, "", "a");
+    const cmd = childShellCommand(process.argv[0], process.argv[1], argv, log, process.env);
+    execFileSync("tmux", ["new-session", "-d", "-s", session, cmd], { env: scrubSecretEnv(process.env) });
 }

package/dist/landing.d.ts

@@ -1,9 +1,14 @@
-export declare const LANDING_EXCHANGES: readonly ["pacifica", "hyperliquid", "lighter", "aster"];
+import "./exchanges/venues/index.js";
+/** Every registered venue, in registry order (SSOT: the venue registry). */
+export declare const LANDING_EXCHANGES: readonly string[];
 export type LandingExchangeStatus = {
-    exchange: typeof LANDING_EXCHANGES[number];
+    exchange: string;
+    /** Venue has no account API — rendered as market data only. */
+    marketDataOnly?: boolean;
     ok: boolean;
     equity: number;
     positions: number;
+    errorCode?: string;
 };
 export declare function asterAgentMissing(): boolean;
 export declare function renderLandingExchangeLine(status: LandingExchangeStatus, asterAgentMissing: boolean): string;

package/dist/landing.js

@@ -1,16 +1,32 @@
 import chalk from "chalk";
 import { listAgents } from "./agent-wallet/store.js";
-export const LANDING_EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
+import { getVenue, listVenues } from "./exchanges/venue.js";
+import "./exchanges/venues/index.js";
+/** Every registered venue, in registry order (SSOT: the venue registry). */
+export const LANDING_EXCHANGES = listVenues().map(v => v.id);
+const ASTER_AGENT_REQUIRED_CODES = new Set([
+    "NOT_IMPLEMENTED",
+    "NO_SIGNER_AVAILABLE",
+    "AGENT_EXPIRED",
+]);
+/** Single-token label (display name without spaces: "Lighter RH" → "LighterRH") so columns stay one word per venue. */
 function exchangeLabel(exchange) {
-    return exchange === "pacifica" ? "Pacifica" : exchange === "hyperliquid" ? "Hyperliquid" : exchange === "lighter" ? "Lighter" : "Aster";
+    return getVenue(exchange).displayName.replace(/\s+/g, "");
 }
 export function asterAgentMissing() {
     return listAgents("aster").length === 0;
 }
 export function renderLandingExchangeLine(status, asterAgentMissing) {
-    if (!status.ok && status.exchange === "aster" && asterAgentMissing) {
+    if (!status.ok &&
+        status.exchange === "aster" &&
+        asterAgentMissing &&
+        status.errorCode !== undefined &&
+        ASTER_AGENT_REQUIRED_CODES.has(status.errorCode)) {
         return `    ${chalk.yellow("⚙")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.yellow("agent required")} ${chalk.gray("→ perp wallet agent approve aster")}`;
     }
+    if (status.marketDataOnly) {
+        return `    ${chalk.gray("◇")} ${chalk.cyan(exchangeLabel(status.exchange).padEnd(14))} ${chalk.gray("market data only")}`;
+    }
     const icon = status.ok ? chalk.green("●") : chalk.red("○");
     const equity = status.ok
         ? chalk.white(`$${Number(status.equity).toLocaleString("en", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`)

package/dist/mcp-server.d.ts

@@ -2,8 +2,18 @@
 /**
  * MCP (Model Context Protocol) server for perp-cli.
  *
- * Read-only advisor mode: provides market data, account balance, and CLI command suggestions.
- * Does NOT execute trades directly — instead suggests CLI commands for the user to run.
- * Adapters are created lazily from environment variables.
+ * Market data, account reads, CLI command suggestions, and two WRITE tools (`trade_execute`,
+ * `trade_close`) that place real orders through the same safety path as `perp trade`
+ * (local risk gate — no force override over MCP —, quarantine reject, execution log).
+ * Network: PERP_NETWORK (mainnet | testnet, validated like `-n`); unset = mainnet, the
+ * documented default. Every result's meta carries `network`.
+ * Adapters are created lazily from the registered agent / OWS wallet / settings (no CLI flags).
  */
-import "dotenv/config";
+import "./exchanges/venues/index.js";
+/**
+ * Venues with a `perp funds deposit <venue>` command. lighter takes a route (ethereum | cctp <chain>);
+ * qfex takes no amount (it shows the deposit address). Tested against the real command tree.
+ */
+export declare const MCP_DEPOSIT_VENUES: readonly string[];
+/** Venues with a `perp funds withdraw <venue>` command. Tested against the real command tree. */
+export declare const MCP_WITHDRAW_VENUES: readonly string[];