perp-cli 0.11.0 → 0.12.0

package/dist/jobs.js

@@ -138,7 +138,9 @@ export function removeJob(id) {
  */
 function buildEnvString() {
     const keys = [
-        "LIGHTER_PRIVATE_KEY", "LIGHTER_API_KEY", "LIGHTER_ACCOUNT_INDEX", "LIGHTER_API_KEY_INDEX",
+        // 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",

package/dist/mcp-server.js

@@ -436,15 +436,15 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         else if (g.includes("grid") || g.includes("dca") || g.includes("bot")) {
             const symbol = extractSymbol(g) || "<symbol>";
             if (g.includes("grid")) {
-                steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: "Check current price" }, { step: 2, command: `perp -e ${ex} --json bot quick-grid ${symbol}`, description: "Start grid bot", dangerous: true }, { step: 3, command: "perp --json jobs list", description: "Verify bot is running" });
+                steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: "Check current price" }, { step: 2, command: `perp -e ${ex} --json strategy quick-grid ${symbol}`, description: "Start grid bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
             }
             else if (g.includes("dca")) {
                 const amount = extractNumber(g) || "<amount>";
                 const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-                steps.push({ step: 1, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json bot quick-dca ${symbol} ${side} ${amount} <interval>`, description: "Start DCA bot", dangerous: true }, { step: 3, command: "perp --json jobs list", description: "Verify bot is running" });
+                steps.push({ step: 1, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json strategy quick-dca ${symbol} ${side} ${amount} <interval>`, description: "Start DCA bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
             }
             else {
-                steps.push({ step: 1, command: "perp --json bot preset-list", description: "List available bot presets" }, { step: 2, command: `perp -e ${ex} --json bot quick-arb`, description: "Start arb bot", dangerous: true }, { step: 3, command: "perp --json jobs list", description: "Verify bot is running" });
+                steps.push({ step: 1, command: "perp --json strategy preset-list", description: "List available bot presets" }, { step: 2, command: `perp -e ${ex} --json strategy quick-arb`, description: "Start arb bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
             }
         }
         else if (g.includes("backtest")) {
@@ -486,13 +486,13 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp --json rebalance check", description: "Check balance distribution" }, { step: 2, command: "perp --json rebalance plan", description: "Generate rebalance plan" }, { step: 3, command: "perp --json rebalance execute", description: "Execute rebalance", dangerous: true });
         }
         else if (g.includes("job") || g.includes("running") || g.includes("background")) {
-            steps.push({ step: 1, command: "perp --json jobs list", description: "List running background jobs" });
+            steps.push({ step: 1, command: "perp --json background list", description: "List running background jobs" });
         }
         else if (g.includes("dex") || g.includes("hip-3") || g.includes("hip3")) {
             steps.push({ step: 1, command: "perp --json -e hl market hip3", description: "List HIP-3 deployed dexes" }, { step: 2, command: "perp --json -e hl --dex <name> market list", description: "Show markets on a specific dex" });
         }
         else if (g.includes("plan") || g.includes("composite") || g.includes("multi-step")) {
-            steps.push({ step: 1, command: "perp plan example", description: "Show example execution plan format" }, { step: 2, command: "perp --json plan validate <file>", description: "Validate plan file" }, { step: 3, command: "perp --json plan execute <file> --dry-run", description: "Dry-run the plan", dangerous: true });
+            steps.push({ step: 1, command: "perp strategy plan example", description: "Show example execution plan format" }, { step: 2, command: "perp --json strategy plan validate <file>", description: "Validate plan file" }, { step: 3, command: "perp --json strategy plan execute <file> --dry-run", description: "Dry-run the plan", dangerous: true });
         }
         else if (g.includes("status") || g.includes("check") || g.includes("overview") || g.includes("portfolio")) {
             steps.push({ step: 1, command: `perp -e ${ex} --json status`, description: "Full account overview" }, { step: 2, command: `perp -e ${ex} --json account positions`, description: "Detailed positions" }, { step: 3, command: `perp -e ${ex} --json account orders`, description: "Open orders" }, { step: 4, command: "perp --json portfolio", description: "Cross-exchange portfolio summary" });
@@ -532,7 +532,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp settings show", description: "Show current settings" }, { step: 2, command: "perp settings referrals on", description: "Enable referral codes (no extra fees, just volume tracking)" });
         }
         else {
-            steps.push({ step: 1, command: "perp agent capabilities", description: "List all available CLI capabilities" }, { step: 2, command: `perp -e ${ex} --json status`, description: "Check account status" }, { step: 3, command: "perp --json agent ping", description: "Check exchange connectivity" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json status`, description: "Check account status" }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check exchange connectivity via balance fetch" });
         }
         return {
             content: [{
@@ -831,7 +831,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: sub === "send" || sub === "exchange" ? ["Transfers real funds cross-chain — verify addresses carefully"] : [],
                 category: sub === "send" || sub === "exchange" ? "write" : "read",
-                relatedCommands: ["perp bridge chains", "perp bridge quote"],
+                relatedCommands: ["perp funds bridge chains", "perp funds bridge quote"],
             };
         }
         else if (category === "funds") {
@@ -855,14 +855,14 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 relatedCommands: ["perp account positions", "perp portfolio"],
             };
         }
-        else if (category === "bot" || category === "run") {
+        else if (category === "strategy" || category === "run") {
             explanation = {
                 command,
                 description: `Automated strategy: ${sub}. Runs as a background job.`,
                 parameters: args.slice(2).map((a, i) => ({ name: `arg${i}`, value: a, description: "See --help" })),
-                risks: ["Runs automated trades — monitor with 'perp jobs list'", "Use --dry-run to simulate first"],
+                risks: ["Runs automated trades — monitor with 'perp background list'", "Use --dry-run to simulate first"],
                 category: "write",
-                relatedCommands: ["perp jobs list", "perp jobs stop"],
+                relatedCommands: ["perp background list", "perp background stop"],
             };
         }
         else if (category === "history") {
@@ -878,11 +878,11 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
         else if (category === "wallet") {
             explanation = {
                 command,
-                description: { show: "Show configured wallets with public addresses", list: "List all wallets (OWS vault + legacy)", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new OWS wallet (encrypted, multi-chain)", import: "Import key into OWS vault", migrate: "Migrate legacy wallets to OWS encrypted vault", set: "Set private key for an exchange (legacy)", use: "Set active wallet (OWS or legacy)", remove: "Remove a wallet", rename: "Rename a wallet", ows: "OWS vault management (create, list, info, delete)" }[sub] || `Wallet: ${sub}`,
+                description: { show: "Show configured wallets with public addresses", list: "List all wallets (OWS vault + legacy)", balance: "Check on-chain USDC/SOL/ETH balances", generate: "Generate a new OWS wallet (encrypted, multi-chain)", import: "Import key into OWS vault", migrate: "Migrate legacy wallets to OWS encrypted vault", set: "Set private key for an exchange (legacy)", use: "Set active wallet (OWS or legacy)", remove: "Remove a wallet", rename: "Rename a wallet", policy: "OWS signing policy: create/list/show/delete", key: "OWS API key: create/list/revoke", agent: "DEX-side agent delegation: approve/list/revoke/rotate/verify", deposit: "MoonPay multi-chain deposit (auto-converts to USDC)", setup: "One-click setup: wallet + guardrail policy + agent API key", backup: "Backup encrypted OWS vault", restore: "Restore OWS vault from encrypted backup", rotate: "Rotate wallet keys (new wallet + transfer assets)" }[sub] || `Wallet: ${sub}`,
                 parameters: [],
                 risks: sub === "generate" ? ["Save the mnemonic securely — it cannot be recovered. Keys are stored in ~/.ows/ encrypted vault."] : sub === "remove" ? ["Wallet will be removed — ensure you have backups"] : [],
                 category: "read",
-                relatedCommands: ["perp wallet list", "perp wallet balance", "perp wallet ows list"],
+                relatedCommands: ["perp wallet list", "perp wallet balance", "perp wallet agent list"],
             };
         }
         else if (category === "backtest") {
@@ -906,14 +906,14 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
             };
         }
         else {
-            const writeCommands = new Set(["trade", "funds", "manage", "rebalance"]);
+            const writeCommands = new Set(["trade", "funds", "manage"]);
             explanation = {
                 command,
                 description: `CLI command: ${command}. Run 'perp ${category} --help' for detailed usage.`,
                 parameters: args.slice(1).map((a, i) => ({ name: `arg${i}`, value: a, description: "See --help for details" })),
                 risks: writeCommands.has(category) ? ["This command may modify account state — review carefully"] : [],
                 category: writeCommands.has(category) ? "write" : "read",
-                relatedCommands: ["perp agent capabilities", "perp schema"],
+                relatedCommands: [`perp ${category} --help`],
             };
         }
         return { content: [{ type: "text", text: ok(explanation) }] };
@@ -1096,35 +1096,28 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     check: { usage: "perp risk check --notional <usd> --leverage <n>", description: "Pre-trade risk check" },
                 },
             },
-            bridge: {
-                description: "Cross-chain USDC bridge",
+            strategy: {
+                description: "Trading strategies — long-running bot algorithms + one-shot scripted plans",
                 subcommands: {
-                    chains: { usage: "perp bridge chains", description: "Supported chains" },
-                    quote: { usage: "perp bridge quote --from <chain> --to <chain> --amount <n>", description: "Get quote" },
-                    send: { usage: "perp bridge send --from <chain> --to <chain> --amount <n>", description: "Execute bridge" },
-                    exchange: { usage: "perp bridge exchange --from <ex> --to <ex> --amount <n>", description: "Bridge between exchanges" },
-                    status: { usage: "perp bridge status <orderId>", description: "Track bridge status" },
-                },
-            },
-            bot: {
-                description: "Automated trading bots",
-                subcommands: {
-                    start: { usage: "perp bot start <config>", description: "Start bot from config file" },
-                    twap: { usage: "perp bot twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
-                    grid: { usage: "perp bot grid <symbol> --range <pct> --grids <n> --size <usd>", description: "Grid trading bot" },
-                    dca: { usage: "perp bot dca <symbol> <side> <amount> <interval>", description: "DCA bot" },
-                    "funding-arb": { usage: "perp bot funding-arb", description: "Funding arb bot" },
-                    "trailing-stop": { usage: "perp bot trailing-stop <symbol>", description: "Trailing stop bot" },
-                    "quick-grid": { usage: "perp bot quick-grid <symbol>", description: "Quick grid bot" },
-                    "quick-dca": { usage: "perp bot quick-dca <symbol> <side> <amount> <interval>", description: "Quick DCA bot" },
-                    "quick-arb": { usage: "perp bot quick-arb", description: "Quick arb bot" },
-                    "preset-list": { usage: "perp bot preset-list", description: "List available bot presets" },
-                    preset: { usage: "perp bot preset <name> [symbol]", description: "Run a bot preset" },
-                    example: { usage: "perp bot example", description: "Show example bot config" },
+                    start: { usage: "perp strategy start <config>", description: "Start bot from config file" },
+                    twap: { usage: "perp strategy twap <symbol> <side> <size> <duration>", description: "TWAP execution" },
+                    grid: { usage: "perp strategy grid <symbol> --range <pct> --grids <n> --size <usd>", description: "Grid trading bot" },
+                    dca: { usage: "perp strategy dca <symbol> <side> <amount> <interval>", description: "DCA bot" },
+                    "funding-arb": { usage: "perp strategy funding-arb", description: "Funding arb bot" },
+                    "trailing-stop": { usage: "perp strategy trailing-stop <symbol>", description: "Trailing stop bot" },
+                    "quick-grid": { usage: "perp strategy quick-grid <symbol>", description: "Quick grid bot" },
+                    "quick-dca": { usage: "perp strategy quick-dca <symbol> <side> <amount> <interval>", description: "Quick DCA bot" },
+                    "quick-arb": { usage: "perp strategy quick-arb", description: "Quick arb bot" },
+                    "preset-list": { usage: "perp strategy preset-list", description: "List available bot presets" },
+                    preset: { usage: "perp strategy preset <name> [symbol]", description: "Run a bot preset" },
+                    example: { usage: "perp strategy example", description: "Show example bot config" },
+                    "plan validate": { usage: "perp strategy plan validate <file>", description: "Validate scripted execution plan" },
+                    "plan execute": { usage: "perp strategy plan execute <file>", description: "Execute scripted plan" },
+                    "plan example": { usage: "perp strategy plan example", description: "Show plan format" },
                 },
             },
             wallet: {
-                description: "Wallet management (OWS encrypted vault + legacy)",
+                description: "Wallet management (OWS encrypted vault + legacy + agent delegation + lifecycle)",
                 subcommands: {
                     show: { usage: "perp wallet show", description: "Show configured wallets with public addresses" },
                     list: { usage: "perp wallet list", description: "List all wallets (OWS vault + legacy)" },
@@ -1136,7 +1129,14 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     use: { usage: "perp wallet use <name>", description: "Set active wallet (OWS or legacy)" },
                     remove: { usage: "perp wallet remove <name>", description: "Remove a wallet" },
                     rename: { usage: "perp wallet rename <oldName> <newName>", description: "Rename a wallet" },
-                    ows: { usage: "perp wallet ows <sub>", description: "OWS vault: create, list, info, delete, policy, key, fund, pay, setup" },
+                    policy: { usage: "perp wallet policy <create|list|show|delete>", description: "OWS signing policies (guardrails for agent signing)" },
+                    key: { usage: "perp wallet key <create|list|revoke>", description: "OWS API keys (scoped agent access tokens)" },
+                    agent: { usage: "perp wallet agent <approve|list|revoke|rotate|verify>", description: "DEX-side agent wallet delegation (per-exchange)" },
+                    deposit: { usage: "perp wallet deposit <walletName>", description: "MoonPay multi-chain deposit (auto-converts to USDC)" },
+                    setup: { usage: "perp wallet setup", description: "One-click: wallet + guardrail policy + agent API key" },
+                    backup: { usage: "perp wallet backup", description: "Backup encrypted OWS vault" },
+                    restore: { usage: "perp wallet restore <file>", description: "Restore OWS vault from encrypted backup" },
+                    rotate: { usage: "perp wallet rotate --from <a> --to <b>", description: "Rotate wallet keys (create new + transfer assets)" },
                 },
             },
             history: {
@@ -1162,44 +1162,37 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     grid: { usage: "perp backtest grid", description: "Backtest grid strategy" },
                 },
             },
-            plan: {
-                description: "Composite multi-step execution plans",
-                subcommands: {
-                    validate: { usage: "perp plan validate <file>", description: "Validate plan" },
-                    execute: { usage: "perp plan execute <file>", description: "Execute plan" },
-                    example: { usage: "perp plan example", description: "Show plan format" },
-                },
-            },
-            rebalance: {
-                description: "Cross-exchange balance rebalancing",
-                subcommands: {
-                    check: { usage: "perp rebalance check", description: "Check distribution" },
-                    plan: { usage: "perp rebalance plan", description: "Generate plan" },
-                    execute: { usage: "perp rebalance execute", description: "Execute rebalance" },
-                },
-            },
-            jobs: {
-                description: "Background job management",
+            background: {
+                description: "Background process supervisor (tmux sessions for strategies, alerts, etc.)",
                 subcommands: {
-                    list: { usage: "perp jobs list", description: "List running jobs" },
-                    stop: { usage: "perp jobs stop <id>", description: "Stop a job" },
-                    logs: { usage: "perp jobs logs <id>", description: "View job logs" },
+                    list: { usage: "perp background list", description: "List running jobs" },
+                    stop: { usage: "perp background stop <id>", description: "Stop a job" },
+                    logs: { usage: "perp background logs <id>", description: "View job logs" },
+                    remove: { usage: "perp background remove <id>", description: "Remove a job entry and its logs" },
+                    clean: { usage: "perp background clean", description: "Remove all stopped/done jobs" },
                 },
             },
             funds: {
-                usage: "perp funds <deposit|withdraw|transfer|bridge> ...",
-                description: "Deposit, withdraw, bridge & transfer funds",
+                usage: "perp funds <deposit|withdraw|transfer|bridge|rebalance|info> ...",
+                description: "Fund movement — deposit, withdraw, transfer, cross-chain bridge, inter-exchange rebalance",
                 subcommands: {
-                    "deposit <exchange> <amount>": "Deposit USDC to exchange",
-                    "withdraw <exchange> <amount>": "Withdraw USDC from exchange",
-                    "transfer <amount> <address>": "HL internal transfer",
-                    "bridge --from <chain> --to <chain> --amount <n> --recipient <addr>": "CCTP bridge",
-                    info: "Show all deposit/withdraw routes & limits",
+                    "deposit <exchange> <amount>": "Deposit USDC to exchange (pacifica, hyperliquid, lighter)",
+                    "withdraw <exchange> <amount>": "Withdraw USDC from exchange (pacifica, hyperliquid, lighter)",
+                    "transfer <amount> <address>": "HL internal transfer (instant)",
+                    "bridge chains": "List supported chains and USDC addresses",
+                    "bridge quote --from <chain> --to <chain> --amount <n>": "Get bridge quotes from all providers",
+                    "bridge send --from <chain> --to <chain> --amount <n> [--provider cctp|relay|debridge]": "Execute bridge (auto-cheapest by default)",
+                    "bridge exchange --from <ex> --to <ex> --amount <n>": "Bridge USDC between exchanges (shortcut)",
+                    "bridge status <orderId>": "Check bridge order status",
+                    "rebalance check": "Show balances across exchanges",
+                    "rebalance plan": "Calculate optimal rebalancing moves",
+                    "rebalance execute [--auto-bridge]": "Execute rebalancing (withdraw → bridge → deposit)",
+                    info: "Show all deposit/withdraw/bridge/rebalance routes & limits",
                 },
             },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
             status: { usage: "perp portfolio", description: "Full account overview" },
-            health: { usage: "perp agent ping", description: "Exchange connectivity check" },
+            health: { usage: "perp account balance --json", description: "Exchange connectivity check via balance fetch" },
             settings: {
                 description: "CLI settings",
                 subcommands: {
@@ -1207,16 +1200,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
                     referrals: { usage: "perp settings referrals on|off", description: "Toggle referral codes (no extra fees)" },
                 },
             },
-            agent: {
-                description: "Agent discovery & execution",
-                subcommands: {
-                    schema: { usage: "perp agent schema", description: "Full CLI schema as JSON" },
-                    capabilities: { usage: "perp agent capabilities", description: "Capability list" },
-                    plan: { usage: "perp agent plan '<goal>'", description: "Suggest commands for goal" },
-                    exec: { usage: "perp agent exec <command...>", description: "Execute with JSON output" },
-                    ping: { usage: "perp agent ping", description: "Health check" },
-                },
-            },
+            // `agent` is now `wallet agent ...` — see `wallet.subcommands.agent` above.
         },
         tips: [
             "Always use --json for structured output when automating",
@@ -1255,12 +1239,30 @@ server.tool("trade_preview", "Preview a trade WITHOUT executing. Returns estimat
         const notional = estPrice ? Number(estPrice) * Number(size) : 0;
         const existingPos = positions.find(p => p.symbol.toUpperCase().includes(symbol.toUpperCase()));
         // Run validation
+        // SSOT rule #2: validation failure must surface as a structured invalid
+        // result, NOT be swallowed into a fake `{ valid: true }`. The previous
+        // shape silently green-lit trades when the underlying balance/orderbook
+        // fetches errored out.
         let validation;
+        // For a preview the user has not yet committed leverage, so 1x is the
+        // documented default exposed in the preview shape (no silent fallback —
+        // the caller can override via existingPos.leverage when re-entering an
+        // open position).
+        const previewLeverage = existingPos?.leverage ?? 1;
         try {
-            validation = await validateTrade(adapter, { symbol, side, size: Number(size), leverage: existingPos?.leverage ?? 1 });
-        }
-        catch {
-            validation = { valid: true, checks: [], warnings: ["Validation unavailable — proceed with caution"] };
+            validation = await validateTrade(adapter, { symbol, side, size: Number(size), leverage: previewLeverage });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            validation = {
+                valid: false,
+                checks: [{
+                        check: "symbol_valid",
+                        passed: false,
+                        message: `Validation could not run: ${msg}`,
+                    }],
+                warnings: [],
+            };
         }
         const preview = {
             order: { exchange, symbol, side, size, orderType, price: price ?? estPrice },

package/dist/position-history.js

@@ -13,6 +13,32 @@ function ensureDir() {
 function genId() {
     return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
+/**
+ * Validate position side from a stream event. SSOT rule #2: the stream must
+ * deliver a real side, never silently default to "long" — defaulting can flip
+ * a short into a long in the position history and corrupt P&L analytics.
+ */
+function requireSide(value, eventType, exchange, symbol) {
+    if (value === "long" || value === "short")
+        return value;
+    throw new Error(`position_${eventType} for ${exchange}:${symbol} has missing/invalid side ` +
+        `(received ${JSON.stringify(value)}); refusing to silently default. ` +
+        `Fix the upstream adapter to emit { side: "long" | "short" } on every event.`);
+}
+/**
+ * Validate a stringified numeric field from a stream event. SSOT rule #2: do
+ * NOT silently default missing realizedPnl to "0", because we cannot
+ * distinguish "trade closed flat" from "adapter forgot the field".
+ */
+function requireNumericString(value, fieldName, eventType, exchange, symbol) {
+    if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)))
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    throw new Error(`position_${eventType} for ${exchange}:${symbol} has missing/invalid ${fieldName} ` +
+        `(received ${JSON.stringify(value)}); refusing to silently default. ` +
+        `Fix the upstream adapter to emit a numeric ${fieldName}.`);
+}
 /** Append a position record to the log */
 export function logPosition(record) {
     ensureDir();
@@ -154,7 +180,10 @@ export function attachPositionLogger(onEvent) {
         if (event.type === "position_opened") {
             const id = genId();
             const symbol = String(data.symbol ?? "");
-            const side = String(data.side ?? "long");
+            if (!symbol) {
+                throw new Error(`position_opened on ${exchange} missing symbol; refusing to silently default. Raw data: ${JSON.stringify(data)}`);
+            }
+            const side = requireSide(data.side, "opened", exchange, symbol);
             const key = `${exchange}:${symbol}`;
             openPositions.set(key, { id, openedAt: ts, entryPrice: String(data.entryPrice ?? "") });
             logPosition({
@@ -172,9 +201,15 @@ export function attachPositionLogger(onEvent) {
         }
         else if (event.type === "position_updated") {
             const symbol = String(data.symbol ?? "");
-            const side = String(data.side ?? "long");
+            if (!symbol) {
+                throw new Error(`position_updated on ${exchange} missing symbol; refusing to silently default. Raw data: ${JSON.stringify(data)}`);
+            }
+            const side = requireSide(data.side, "updated", exchange, symbol);
             const key = `${exchange}:${symbol}`;
             const tracked = openPositions.get(key);
+            // tracked?.id ?? genId() is NOT a fallback in the SSOT sense: it covers the
+            // legitimate case where the stream delivers an update for a position the
+            // logger never saw open (out-of-order delivery, mid-session attach).
             logPosition({
                 id: tracked?.id ?? genId(),
                 exchange,
@@ -194,12 +229,20 @@ export function attachPositionLogger(onEvent) {
         }
         else if (event.type === "position_closed") {
             const symbol = String(data.symbol ?? "");
-            const side = String(data.side ?? "long");
+            if (!symbol) {
+                throw new Error(`position_closed on ${exchange} missing symbol; refusing to silently default. Raw data: ${JSON.stringify(data)}`);
+            }
+            const side = requireSide(data.side, "closed", exchange, symbol);
             const key = `${exchange}:${symbol}`;
             const tracked = openPositions.get(key);
             const openedAt = tracked?.openedAt ?? ts;
             const duration = new Date(ts).getTime() - new Date(openedAt).getTime();
-            const realizedPnl = String(data.unrealizedPnl ?? "0");
+            // SSOT rule #2: do NOT alias unrealizedPnl as realizedPnl. They mean
+            // different things: unrealizedPnl is the snapshot before close, and on
+            // a real close event the upstream adapter must emit realizedPnl
+            // explicitly. Aliasing them would have a flat-close (realizedPnl=0)
+            // pretend to be the last unrealized number from the previous tick.
+            const realizedPnl = requireNumericString(data.realizedPnl, "realizedPnl", "closed", exchange, symbol);
             logPosition({
                 id: tracked?.id ?? genId(),
                 exchange,

package/dist/settings.d.ts

@@ -26,14 +26,76 @@ export interface AlertSettings {
     /** Cooldown per symbol in minutes after alert fires (default: 60) */
     cooldownMin: number;
 }
+export interface AgentMeta {
+    agentName: string;
+    agentWalletName: string;
+    /**
+     * EVM address of the agent wallet (required for Aster + Hyperliquid).
+     * For Pacifica (Phase 2c): kept as a sentinel zero-address since the
+     * curve is Solana/Ed25519; the canonical address lives in
+     * `agentSolanaAddress`. For Lighter (Phase 2d): populated with the master
+     * EVM address (since L1 ChangePubKey is signed by the master EVM key); the
+     * canonical agent identity lives in `publicKey + apiKeyIndex`.
+     * The `0x${string}` literal is preserved to avoid disrupting Aster/HL strict typing.
+     */
+    agentEvmAddress: `0x${string}`;
+    /** EVM address of the master/owner wallet — required as `user` field in Aster/HL requests. Populated by `agent approve` (Step 4). */
+    userEvmAddress: `0x${string}`;
+    /**
+     * Solana base58 public key of the agent wallet (Phase 2c — Pacifica only).
+     * Optional for Aster/HL since they live on EVM curves.
+     */
+    agentSolanaAddress?: string;
+    /**
+     * Solana base58 public key of the master/owner wallet (Phase 2c — Pacifica only).
+     * Optional for Aster/HL.
+     */
+    userSolanaAddress?: string;
+    /**
+     * Lighter slot index (Phase 2d — Lighter only).
+     * Range: [4, 254] inclusive. Slots 0-3 are reserved by the Lighter frontend.
+     * Selected at approve time as `max(existing slots) + 1`.
+     */
+    apiKeyIndex?: number;
+    /**
+     * Lighter agent secp256k1 public key (hex, no `0x` prefix) (Phase 2d — Lighter only).
+     * Canonical identity for the Lighter L2 hot-path. Cross-checked against
+     * `GET /api/v1/apikeys?account_index=N` during `wallet agent verify lighter`.
+     */
+    publicKey?: string;
+    /**
+     * Lighter L2 account index (Phase 2d — Lighter only).
+     * Resolved at approve time from L1 EVM address via the Lighter REST API
+     * and cached so subsequent verify/trade calls don't need to re-query.
+     */
+    accountIndex?: number;
+    masterWalletName: string;
+    owsApiKeyId: string;
+    owsPolicyId: string;
+    expiresAt: string;
+    approvedAt: string;
+    permissions: {
+        canPerpTrade: boolean;
+        canSpotTrade: boolean;
+        canWithdraw: boolean;
+    };
+    asterApprovalNonce: string;
+    status?: "active" | "partial";
+}
+export interface AgentsByExchange {
+    aster?: Record<string, AgentMeta>;
+    hyperliquid?: Record<string, AgentMeta>;
+    pacifica?: Record<string, AgentMeta>;
+    lighter?: Record<string, AgentMeta>;
+}
 export interface Settings {
     /** Default exchange when -e flag is omitted */
     defaultExchange: string;
     /** Active OWS wallet name (used when no --ows or --wallet flag) */
     owsActiveWallet: string;
-    /** Enable referral/builder codes (default: false — opt-in only) */
-    referrals: boolean;
-    /** Per-exchange referral codes (used when referrals=true) */
+    /** Per-exchange referral / builder codes (always applied per SSOT Rule #3:
+     *  no opt-out — Pacifica builder code has always been mandatory; HL/LT
+     *  aligned 2026-05-01). */
     referralCodes: {
         pacifica: string;
         hyperliquid: string;
@@ -48,6 +110,8 @@ export interface Settings {
     fees: Record<string, ExchangeFees>;
     /** Alert configuration */
     alerts: AlertSettings;
+    /** OWS-native agent wallets registered per exchange (Phase 2a: Aster only) */
+    agents?: AgentsByExchange;
 }
 export declare function loadSettings(): Settings;
 export declare function saveSettings(settings: Settings): void;

package/dist/settings.js

@@ -5,7 +5,6 @@ const SETTINGS_FILE = resolve(PERP_DIR, "settings.json");
 const DEFAULTS = {
     defaultExchange: "",
     owsActiveWallet: "",
-    referrals: false,
     referralCodes: {
         pacifica: "",
         hyperliquid: "HYPERCASH",
@@ -44,7 +43,6 @@ export function loadSettings() {
         return {
             defaultExchange: stored.defaultExchange ?? DEFAULTS.defaultExchange,
             owsActiveWallet: stored.owsActiveWallet ?? DEFAULTS.owsActiveWallet,
-            referrals: stored.referrals ?? DEFAULTS.referrals,
             referralCodes: {
                 pacifica: stored.referralCodes?.pacifica ?? DEFAULTS.referralCodes.pacifica,
                 hyperliquid: stored.referralCodes?.hyperliquid ?? DEFAULTS.referralCodes.hyperliquid,
@@ -62,6 +60,7 @@ export function loadSettings() {
                 cooldownMin: stored.alerts?.cooldownMin ?? DEFAULTS.alerts.cooldownMin,
             },
             fees,
+            agents: stored.agents && typeof stored.agents === "object" ? stored.agents : undefined,
         };
     }
     catch {

package/dist/signer/ows-evm.d.ts

@@ -16,3 +16,17 @@ export declare class OwsEvmSigner implements EvmSigner {
     }>>, value: Record<string, unknown>): Promise<string>;
     signMessage(message: string | Uint8Array): Promise<string>;
 }
+/**
+ * Normalize OWS signature output to canonical 65-byte hex (0x-prefixed).
+ *
+ * OWS may return the signature in two shapes depending on version:
+ *   (A) 65-byte hex with v already embedded — use as-is
+ *   (B) 64-byte hex (r+s only) + separate recoveryId — append v
+ *
+ * For shape B, recoveryId may be either canonical (27/28) or raw (0/1).
+ * If raw, add 27 to canonicalize.
+ */
+export declare function canonicalizeOwsSignature(result: {
+    signature: string;
+    recoveryId?: number;
+}): string;

package/dist/signer/ows-evm.js

@@ -39,11 +39,8 @@ export class OwsEvmSigner {
             domain,
             message: value,
         });
-        const result = ows.signTypedData(this._walletName, "evm", typedData, this._passphrase);
-        // OWS returns hex signature + recoveryId; combine to 65-byte EIP-712 sig
-        const sig = result.signature.startsWith("0x") ? result.signature : `0x${result.signature}`;
-        const v = result.recoveryId !== undefined ? result.recoveryId + 27 : 27;
-        return `${sig}${v.toString(16).padStart(2, "0")}`;
+        const result = ows.signTypedData(this._walletName, "ethereum", typedData, this._passphrase);
+        return canonicalizeOwsSignature(result);
     }
     async signMessage(message) {
         const ows = loadOws();
@@ -51,12 +48,34 @@ export class OwsEvmSigner {
             ? message
             : Buffer.from(message).toString("hex");
         const encoding = typeof message === "string" ? "utf8" : "hex";
-        const result = ows.signMessage(this._walletName, "evm", msgStr, this._passphrase, encoding);
-        const sig = result.signature.startsWith("0x") ? result.signature : `0x${result.signature}`;
-        const v = result.recoveryId !== undefined ? result.recoveryId + 27 : 27;
-        return `${sig}${v.toString(16).padStart(2, "0")}`;
+        const result = ows.signMessage(this._walletName, "ethereum", msgStr, this._passphrase, encoding);
+        return canonicalizeOwsSignature(result);
     }
 }
+/**
+ * Normalize OWS signature output to canonical 65-byte hex (0x-prefixed).
+ *
+ * OWS may return the signature in two shapes depending on version:
+ *   (A) 65-byte hex with v already embedded — use as-is
+ *   (B) 64-byte hex (r+s only) + separate recoveryId — append v
+ *
+ * For shape B, recoveryId may be either canonical (27/28) or raw (0/1).
+ * If raw, add 27 to canonicalize.
+ */
+export function canonicalizeOwsSignature(result) {
+    const sigHex = result.signature.startsWith("0x") ? result.signature.slice(2) : result.signature;
+    if (sigHex.length === 130) {
+        // Already 65-byte sig with embedded v — trust OWS
+        return `0x${sigHex}`;
+    }
+    if (sigHex.length !== 128) {
+        throw new Error(`Unexpected OWS signature length: ${sigHex.length} hex chars (expected 128 or 130)`);
+    }
+    // 64-byte r+s — append v from recoveryId
+    const rid = result.recoveryId ?? 0;
+    const v = rid >= 27 ? rid : rid + 27; // accept canonical or raw recoveryId
+    return `0x${sigHex}${v.toString(16).padStart(2, "0")}`;
+}
 function inferEip712DomainType(key) {
     switch (key) {
         case "chainId": return "uint256";

package/dist/smart-order.d.ts

@@ -16,13 +16,19 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
- * Fallback: if the IOC limit fails, falls back to market order.
+ * SSOT rule #2: silent fallback is forbidden. The opt-in `fallback: true` flag
+ * is preserved for callers that explicitly want best-effort market substitution
+ * after IOC reject, but the DEFAULT is `false` — failure must surface as a
+ * thrown error, never a silent market sweep.
  */
 import type { ExchangeAdapter } from "./exchanges/index.js";
 export interface SmartOrderOpts {
     /** Extra ticks of tolerance beyond best price. Default: 1 */
     tickTolerance?: number;
-    /** Fall back to market order if IOC limit fails. Default: true */
+    /**
+     * Opt-in: fall back to market order if IOC limit fails.
+     * SSOT rule #2 default: `false` — failure throws unless caller explicitly opts in.
+     */
     fallback?: boolean;
     /** Reduce only flag for closing positions. Default: false */
     reduceOnly?: boolean;