pandora-cli-skills 1.1.29 → 1.1.31

package/SKILL.md

@@ -110,7 +110,7 @@ lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <
 hedge-calc [--reserve-yes-usdc <n> --reserve-no-usdc <n>] [--excess-yes-usdc <n>] [--excess-no-usdc <n>] [--polymarket-yes-pct <0-100>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--volume-scenarios <csv>] [--pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>] [--trust-deploy] [--manifest-file <path>]
 simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier 500|3000|10000] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--polymarket-yes-pct <0-100>]
 go     --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
-sync run|once|start|stop|status --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--discord-webhook-url <url>]
+sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
 status --state-file <path>|--strategy-hash <hash> [--with-live] [--pandora-market-address <address>|--market-address <address>] [--polymarket-market-id <id>|--polymarket-slug <slug>]
 close  --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute
 ```
@@ -257,6 +257,7 @@ pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --inclu
   - Polymarket trading collateral is Polygon USDC.e on the proxy wallet.
   - rebalance sizing is pool-aware and bounded by `--max-rebalance-usdc`.
   - endpoint resilience: Polymarket snapshots are cached under `~/.pandora/polymarket`; paper/read flows can reuse cache during outages, while live sync blocks cached sources.
+  - daemon verification note: `mirror sync start` launches a child process that executes `cli/pandora.cjs` and enters the same CLI `main()` handlers, so crash/error handling remains covered by the normal command dispatcher + structured error envelopes.
 - `mirror status`: local mirror state inspection with optional live market diagnostics (`--with-live`).
   - `--with-live` uses the same `POLYMARKET_*` env keys for optional position visibility (YES/NO balances, open orders count, estimated value) and adds `netDeltaApprox` / `pnlApprox`.
   - missing credentials or unavailable position endpoints do not hard-fail status; diagnostics are returned with null position fields.
@@ -346,6 +347,25 @@ Error envelope:
 ## Additional JSON response shapes
 - `doctor`:
   - `{ ok: true, command: "doctor", data: { schemaVersion, generatedAt, env, rpc, codeChecks, polymarket, summary } }`
+- `history`:
+  - `{ ok: true, command: "history", data: { schemaVersion, generatedAt, indexerUrl, wallet, chainId, filters, pagination, pageInfo, summary, count, items[] } }`
+  - each `items[]` row includes `entryPriceUsdcPerToken`, `markPriceUsdcPerToken`, `currentValueUsdc`, `pnlUnrealizedApproxUsdc`, `pnlRealizedApproxUsdc`, `status`, and `diagnostics[]`.
+- `export`:
+  - `{ ok: true, command: "export", data: { schemaVersion, generatedAt, format: "csv"|"json", wallet, chainId, count, filters, columns[], outPath, rows[], content } }`
+  - `content` is the deterministic serialized payload written to `outPath` when `--out` is provided.
+- `arbitrage`:
+  - `{ ok: true, command: "arbitrage", data: { schemaVersion, generatedAt, indexerUrl, venues, filters, count, opportunities[], diagnostics[] } }`
+- `autopilot`:
+  - `{ ok: true, command: "autopilot", data: { schemaVersion, generatedAt, strategyHash, mode, executeLive, stateFile, killSwitchFile, iterationsRequested, iterationsCompleted, stoppedReason?, parameters: { marketAddress, side, amountUsdc, triggerYesBelow?, triggerYesAbove?, intervalMs, cooldownMs, maxAmountUsdc?, maxOpenExposureUsdc, dailySpendCapUsdc, maxTradesPerDay }, state, actionCount, actions[], snapshots[], webhookReports[] } }`
+- `mirror browse`:
+  - `{ ok: true, command: "mirror.browse", data: { schemaVersion, generatedAt, source, gammaApiError, filters, count, items[], diagnostics[] } }`
+  - each candidate row can include `existingMirror: { marketAddress, similarity } | null`.
+- `mirror go`:
+  - `{ ok: true, command: "mirror.go", data: { schemaVersion, generatedAt, mode, plan, deploy, verify, sync, polymarketPreflight, suggestedSyncCommand, trustManifest, diagnostics[] } }`
+  - `plan` is the same payload shape as `mirror.plan`; `deploy` is the same payload shape as `mirror.deploy`; `sync` is null unless `--auto-sync` is used.
+- close peers:
+  - `mirror close`: `{ ok: true, command: "mirror.close", data: { schemaVersion, generatedAt, mode, pandoraMarketAddress, polymarketMarketId?, polymarketSlug?, steps[], diagnostics[] } }`
+  - `mirror sync start|status|stop`: `{ ok: true, command: "mirror.sync.start|mirror.sync.status|mirror.sync.stop", data: { strategyHash, pid?, pidFile, logFile?, alive, status, metadata? } }`
 - `resolve`:
   - dry-run: `{ ok: true, command: "resolve", data: { schemaVersion, generatedAt, mode: "dry-run", txPlan } }`
   - execute: `{ ok: true, command: "resolve", data: { schemaVersion, generatedAt, mode: "execute", tx } }`
@@ -354,6 +374,12 @@ Error envelope:
   - `lp positions`: `{ ok: true, command: "lp", data: { schemaVersion, generatedAt, action: "positions", mode: "read", wallet, count, items[] } }`
 - `polymarket`:
   - `check|preflight|approve|trade` all return `{ ok: true, command, data }` with `schemaVersion` and `generatedAt`; execute paths include `result`/`tx` blocks.
+- `leaderboard`:
+  - `{ ok: true, command: "leaderboard", data: { schemaVersion, generatedAt, indexerUrl, metric, limit, minTrades, count, items[], diagnostics[] } }`
+- `analyze`:
+  - `{ ok: true, command: "analyze", data: { schemaVersion, generatedAt, indexerUrl, marketAddress, provider, model, market, quote, result } }`
+- `suggest`:
+  - `{ ok: true, command: "suggest", data: { schemaVersion, generatedAt, wallet, risk, budget, count, items[], indexerUrl, includeVenues, historySummary, arbitrageCount } }`
 
 ## Pandora mainnet deployment reference
 - PredictionOracle (Factory): `0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442`

package/cli/lib/arbitrage_service.cjs

@@ -5,21 +5,10 @@ const {
   questionSimilarityBreakdown,
   questionSimilarity,
 } = require('./similarity_service.cjs');
+const { toNumber, round } = require('./shared/utils.cjs');
 
 const ARBITRAGE_SCHEMA_VERSION = '1.1.0';
 
-function toNumber(value) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
-function round(value, decimals = 6) {
-  if (!Number.isFinite(value)) return null;
-  const factor = 10 ** decimals;
-  return Math.round(value * factor) / factor;
-}
-
 function toUsdc(raw) {
   const numeric = toNumber(raw);
   if (numeric === null) return null;

package/cli/lib/autopilot_service.cjs

@@ -9,17 +9,7 @@ const {
   pruneIdempotencyKeys,
   resetDailyCountersIfNeeded,
 } = require('./autopilot_state_store.cjs');
-
-function toNumber(value) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
-function sleepMs(ms) {
-  if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve();
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+const { toNumber, sleepMs } = require('./shared/utils.cjs');
 
 function buildIdempotencyKey(options, quote, nowMs) {
   const yesPct = toNumber(quote && quote.odds && quote.odds.yesPct);

package/cli/lib/cli_output_service.cjs

@@ -1,3 +1,8 @@
+/**
+ * Create CLI output helpers for success/error envelopes and table output.
+ * @param {{defaultSchemaVersion?: string, CliError: Function}} [options]
+ * @returns {{emitFailure: (outputMode: 'table'|'json', error: any) => void, emitSuccess: (outputMode: 'table'|'json', command: string, data: any, tableRenderer?: Function) => void}}
+ */
 function createCliOutputService(options = {}) {
   const defaultSchemaVersion =
     typeof options.defaultSchemaVersion === 'string' && options.defaultSchemaVersion.trim()
@@ -120,6 +125,7 @@ function createCliOutputService(options = {}) {
   };
 }
 
+/** Public CLI output service factory export. */
 module.exports = {
   createCliOutputService,
 };

package/cli/lib/command_router.cjs

@@ -1,3 +1,9 @@
+/**
+ * Build the top-level command dispatcher for `pandora`.
+ * The returned function routes parsed command/args/context to subcommand handlers.
+ * @param {object} deps
+ * @returns {(command: string|undefined, args: string[], context: {outputMode: 'table'|'json'}) => Promise<void>}
+ */
 function createCommandRouter(deps = {}) {
   const {
     CliError,
@@ -156,7 +162,7 @@ function createCommandRouter(deps = {}) {
   };
 }
 
+/** Public command-router factory export. */
 module.exports = {
   createCommandRouter,
 };
-

package/cli/lib/history_service.cjs

@@ -1,29 +1,17 @@
 const { createIndexerClient } = require('./indexer_client.cjs');
+const { round, toOptionalNumber } = require('./shared/utils.cjs');
 
 const USDC_DECIMALS = 6;
 const HISTORY_SCHEMA_VERSION = '1.0.0';
 
-function toNumber(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
-function round(value, decimals = 6) {
-  if (!Number.isFinite(value)) return null;
-  const factor = 10 ** decimals;
-  return Math.round(value * factor) / factor;
-}
-
 function toUsdc(raw) {
-  const numeric = toNumber(raw);
+  const numeric = toOptionalNumber(raw);
   if (numeric === null) return null;
   return round(numeric / 10 ** USDC_DECIMALS, 6);
 }
 
 function normalizeProbabilityFromYesChance(rawYesChance) {
-  const raw = toNumber(rawYesChance);
+  const raw = toOptionalNumber(rawYesChance);
   if (raw === null) return null;
   if (raw >= 0 && raw <= 1) return raw;
   if (raw > 1 && raw <= 100) return raw / 100;
@@ -34,8 +22,8 @@ function computeYesProbabilityFromMarket(market) {
   const yesChanceProb = normalizeProbabilityFromYesChance(market && market.yesChance);
   if (yesChanceProb !== null && yesChanceProb >= 0 && yesChanceProb <= 1) return yesChanceProb;
 
-  const reserveYes = toNumber(market && market.reserveYes);
-  const reserveNo = toNumber(market && market.reserveNo);
+  const reserveYes = toOptionalNumber(market && market.reserveYes);
+  const reserveNo = toOptionalNumber(market && market.reserveNo);
   if (reserveYes === null || reserveNo === null) return null;
   const total = reserveYes + reserveNo;
   if (!Number.isFinite(total) || total <= 0) return null;
@@ -117,21 +105,21 @@ function buildSummary(items) {
   };
 
   for (const item of items) {
-    const collateral = toNumber(item.collateralAmountUsdc) || 0;
+    const collateral = toOptionalNumber(item.collateralAmountUsdc) || 0;
     summary.grossVolumeUsdc += collateral;
 
     if (item.status === 'open') {
       summary.openCount += 1;
-      summary.unrealizedPnlApproxUsdc += toNumber(item.pnlUnrealizedApproxUsdc) || 0;
+      summary.unrealizedPnlApproxUsdc += toOptionalNumber(item.pnlUnrealizedApproxUsdc) || 0;
     } else if (item.status === 'won') {
       summary.wonCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     } else if (item.status === 'lost') {
       summary.lostCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     } else {
       summary.closedOtherCount += 1;
-      summary.realizedPnlApproxUsdc += toNumber(item.pnlRealizedApproxUsdc) || 0;
+      summary.realizedPnlApproxUsdc += toOptionalNumber(item.pnlRealizedApproxUsdc) || 0;
     }
   }
 
@@ -146,15 +134,15 @@ function sortHistoryItems(items, orderBy, orderDirection) {
   const dir = String(orderDirection || 'desc').toLowerCase() === 'asc' ? 1 : -1;
   const pick = (item) => {
     if (orderBy === 'pnl') {
-      return toNumber(item.pnlRealizedApproxUsdc) ?? toNumber(item.pnlUnrealizedApproxUsdc) ?? -Infinity;
+      return toOptionalNumber(item.pnlRealizedApproxUsdc) ?? toOptionalNumber(item.pnlUnrealizedApproxUsdc) ?? -Infinity;
     }
     if (orderBy === 'entry-price') {
-      return toNumber(item.entryPriceUsdcPerToken) ?? -Infinity;
+      return toOptionalNumber(item.entryPriceUsdcPerToken) ?? -Infinity;
     }
     if (orderBy === 'mark-price') {
-      return toNumber(item.markPriceUsdcPerToken) ?? -Infinity;
+      return toOptionalNumber(item.markPriceUsdcPerToken) ?? -Infinity;
     }
-    return toNumber(item.timestamp) ?? 0;
+    return toOptionalNumber(item.timestamp) ?? 0;
   };
 
   items.sort((a, b) => {

package/cli/lib/leaderboard_service.cjs

@@ -1,13 +1,8 @@
 const { createIndexerClient } = require('./indexer_client.cjs');
+const { toNumber } = require('./shared/utils.cjs');
 
 const LEADERBOARD_SCHEMA_VERSION = '1.0.0';
 
-function toNumber(value) {
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
 function toCount(value) {
   const numeric = toNumber(value);
   if (numeric === null || numeric < 0) return 0;

package/cli/lib/market_admin_service.cjs

@@ -1,8 +1,4 @@
-const DEFAULT_INDEXER_URL = 'https://pandoraindexer.up.railway.app/';
-const DEFAULT_RPC_BY_CHAIN_ID = {
-  1: 'https://ethereum.publicnode.com',
-  146: 'https://rpc.soniclabs.com',
-};
+const { DEFAULT_INDEXER_URL, DEFAULT_RPC_BY_CHAIN_ID } = require('./shared/constants.cjs');
 
 const ERC20_ABI = [
   {
@@ -180,6 +176,12 @@ function normalizeTimeoutMs(value) {
   return Math.trunc(numeric);
 }
 
+/**
+ * Convert numeric-like input into a finite number.
+ * Used by LP/resolve input normalization paths.
+ * @param {*} value
+ * @returns {number|null}
+ */
 function toFiniteNumber(value) {
   const numeric = Number(value);
   if (!Number.isFinite(numeric)) return null;
@@ -313,6 +315,14 @@ async function readDecimals(publicClient, address, fallback = 18) {
   }
 }
 
+/**
+ * Read optional `calcRemoveLiquidity` preview outputs.
+ * Returned values are raw on-chain integers as decimal strings.
+ * @param {object} publicClient
+ * @param {string} marketAddress
+ * @param {bigint} sharesRaw
+ * @returns {Promise<{collateralOutRaw: string|null, yesOutRaw: string|null, noOutRaw: string|null}|null>}
+ */
 async function readCalcRemoveLiquidity(publicClient, marketAddress, sharesRaw) {
   for (const abi of CALC_REMOVE_LIQUIDITY_ABI_CANDIDATES) {
     try {
@@ -395,6 +405,11 @@ async function discoverLiquidityMarkets(indexerUrl, wallet, chainId, timeoutMs)
   return Array.from(new Set(addresses));
 }
 
+/**
+ * Resolve a market outcome by calling `resolveMarket(bool)`.
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
 async function runResolve(options = {}) {
   const schemaVersion = '1.0.0';
   const generatedAt = new Date().toISOString();
@@ -468,6 +483,13 @@ async function runResolve(options = {}) {
   }
 }
 
+/**
+ * Read LP balances and remove-liquidity previews for a wallet.
+ * LP/share values are raw and human-readable decimal strings in the payload.
+ * `collateralOutUsdc` is decimal USDC (6 decimals).
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
 async function runLpPositions(options = {}) {
   const schemaVersion = '1.0.0';
   const generatedAt = new Date().toISOString();
@@ -570,6 +592,12 @@ async function runLpPositions(options = {}) {
   };
 }
 
+/**
+ * Build or execute `addLiquidity`.
+ * `amountUsdc` is decimal USDC input; `collateralAmountRaw` is 6-decimal raw units.
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
 async function runLpAdd(options = {}) {
   const schemaVersion = '1.0.0';
   const generatedAt = new Date().toISOString();
@@ -719,6 +747,12 @@ async function runLpAdd(options = {}) {
   }
 }
 
+/**
+ * Build or execute `removeLiquidity`.
+ * `lpTokens` is decimal LP token amount; `sharesToBurnRaw` is on-chain raw units.
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
 async function runLpRemove(options = {}) {
   const schemaVersion = '1.0.0';
   const generatedAt = new Date().toISOString();
@@ -825,6 +859,11 @@ async function runLpRemove(options = {}) {
   }
 }
 
+/**
+ * Dispatch LP admin action (`positions`, `add`, `remove`).
+ * @param {object} [options]
+ * @returns {Promise<object>}
+ */
 async function runLp(options = {}) {
   if (options.action === 'positions') {
     return runLpPositions(options);
@@ -838,6 +877,7 @@ async function runLp(options = {}) {
   throw createServiceError('INVALID_ARGS', 'lp requires action add|remove|positions.');
 }
 
+/** Public market admin API consumed by CLI `resolve` and `lp` commands. */
 module.exports = {
   runResolve,
   runLp,

package/cli/lib/mirror_command_service.cjs

@@ -0,0 +1,149 @@
+/**
+ * Canonical usage string for `mirror go`.
+ * Exported for CLI help rendering and integration tests.
+ * @type {string}
+ */
+const MIRROR_GO_USAGE =
+  'pandora [--output table|json] mirror go --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]';
+
+/**
+ * Canonical usage string for `mirror sync`.
+ * Exported for CLI help rendering and integration tests.
+ * @type {string}
+ */
+const MIRROR_SYNC_USAGE =
+  'pandora [--output table|json] mirror sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]';
+
+const INVALID_SUBCOMMAND_MESSAGE =
+  'mirror requires subcommand: browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close';
+
+/**
+ * Build the `mirror` subcommand dispatcher with lazy-loaded action handlers.
+ * @param {object} deps
+ * @returns {(args: string[], context: {outputMode: 'table'|'json'}) => Promise<any>}
+ */
+function createRunMirrorCommand(deps) {
+  const {
+    CliError,
+    emitSuccess,
+    commandHelpPayload,
+    parseIndexerSharedFlags,
+  } = deps;
+
+  const handlerLoaders = {
+    browse: () => require('./mirror_handlers/browse.cjs'),
+    plan: () => require('./mirror_handlers/plan.cjs'),
+    deploy: () => require('./mirror_handlers/deploy.cjs'),
+    verify: () => require('./mirror_handlers/verify.cjs'),
+    'lp-explain': () => require('./mirror_handlers/lp_explain.cjs'),
+    'hedge-calc': () => require('./mirror_handlers/hedge_calc.cjs'),
+    simulate: () => require('./mirror_handlers/simulate.cjs'),
+    go: () => require('./mirror_handlers/go.cjs'),
+    sync: () => require('./mirror_handlers/sync.cjs'),
+    status: () => require('./mirror_handlers/status.cjs'),
+    close: () => require('./mirror_handlers/close.cjs'),
+  };
+  const handlerCache = new Map();
+
+  function getHandler(action) {
+    if (handlerCache.has(action)) {
+      return handlerCache.get(action);
+    }
+
+    const load = handlerLoaders[action];
+    if (!load) {
+      return null;
+    }
+
+    const loaded = load();
+    const handler =
+      typeof loaded === 'function'
+        ? loaded
+        : loaded && typeof loaded.handle === 'function'
+          ? loaded.handle
+          : null;
+
+    if (!handler) {
+      throw new Error(`Invalid mirror handler module for action: ${action}`);
+    }
+
+    handlerCache.set(action, handler);
+    return handler;
+  }
+
+  return async function runMirrorCommand(args, context) {
+    const action = args[0];
+    const actionArgs = args.slice(1);
+
+    if (!action || action === '--help' || action === '-h') {
+      if (context.outputMode === 'json') {
+        emitSuccess(
+          context.outputMode,
+          'mirror.help',
+          commandHelpPayload(
+            'pandora [--output table|json] mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...',
+          ),
+        );
+      } else {
+        console.log(
+          'Usage: pandora [--output table|json] mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...',
+        );
+        console.log('');
+        console.log('Subcommands:');
+        console.log(
+          '  browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
+        );
+        console.log(
+          '  plan   --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
+        );
+        console.log(
+          '  deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier 500|3000|10000] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--min-close-lead-seconds <n>]',
+        );
+        console.log(
+          '  verify --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--trust-deploy] [--manifest-file <path>] [--include-similarity] [--with-rules] [--allow-rule-mismatch] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
+        );
+        console.log(
+          '  lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>]',
+        );
+        console.log(
+          '  hedge-calc [--reserve-yes-usdc <n> --reserve-no-usdc <n>] [--excess-yes-usdc <n>] [--excess-no-usdc <n>] [--polymarket-yes-pct <0-100>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--volume-scenarios <csv>] [--pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>]',
+        );
+        console.log(
+          '  simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier 500|3000|10000] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--polymarket-yes-pct <0-100>]',
+        );
+        console.log(
+          `  go     ${MIRROR_GO_USAGE.replace('pandora [--output table|json] mirror go ', '')}`,
+        );
+        console.log(
+          `  sync ${MIRROR_SYNC_USAGE.replace('pandora [--output table|json] mirror sync ', '')}`,
+        );
+        console.log('         stop|status selector: --pid-file <path>|--strategy-hash <hash>');
+        console.log('  status --state-file <path>|--strategy-hash <hash> [--with-live] [--trust-deploy]');
+        console.log('  close  --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute');
+      }
+      return;
+    }
+
+    const handler = getHandler(action);
+    if (!handler) {
+      throw new CliError('INVALID_ARGS', INVALID_SUBCOMMAND_MESSAGE);
+    }
+    const shared = parseIndexerSharedFlags(actionArgs);
+
+    return handler({
+      actionArgs: shared.rest,
+      shared,
+      context,
+      deps,
+      mirrorGoUsage: MIRROR_GO_USAGE,
+      mirrorSyncUsage: MIRROR_SYNC_USAGE,
+    });
+  };
+}
+
+/** Public mirror command service exports. */
+module.exports = {
+  MIRROR_GO_USAGE,
+  MIRROR_SYNC_USAGE,
+  createRunMirrorCommand,
+};

package/cli/lib/mirror_econ_service.cjs

@@ -1,4 +1,5 @@
 const { computeDistributionHint, normalizeProbability } = require('./mirror_sizing_service.cjs');
+const { round, clamp, toOptionalNumber } = require('./shared/utils.cjs');
 
 const MIRROR_LP_EXPLAIN_SCHEMA_VERSION = '1.0.0';
 const MIRROR_HEDGE_CALC_SCHEMA_VERSION = '1.0.0';
@@ -6,25 +7,8 @@ const MIRROR_SIMULATE_SCHEMA_VERSION = '1.0.0';
 const USDC_DECIMALS = 6;
 const USDC_SCALE = 10 ** USDC_DECIMALS;
 
-function toNumber(value) {
-  if (value === null || value === undefined || value === '') return null;
-  const numeric = Number(value);
-  if (!Number.isFinite(numeric)) return null;
-  return numeric;
-}
-
-function round(value, decimals = 6) {
-  if (!Number.isFinite(value)) return null;
-  const factor = 10 ** decimals;
-  return Math.round(value * factor) / factor;
-}
-
-function clamp(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-}
-
 function toRawUsdc(usdc) {
-  const numeric = toNumber(usdc);
+  const numeric = toOptionalNumber(usdc);
   if (numeric === null) return null;
   return BigInt(Math.round(numeric * USDC_SCALE));
 }
@@ -35,7 +19,7 @@ function rawUsdcToNumber(rawValue) {
 }
 
 function toPercent(value) {
-  const numeric = toNumber(value);
+  const numeric = toOptionalNumber(value);
   if (numeric === null) return null;
   if (numeric >= 0 && numeric <= 100) return round(numeric, 6);
   return null;
@@ -51,8 +35,8 @@ function resolveDistribution(options = {}) {
   const diagnostics = [];
   const sourceYesPct = toPercent(options.sourceYesPct);
 
-  const explicitYes = toNumber(options.distributionYes);
-  const explicitNo = toNumber(options.distributionNo);
+  const explicitYes = toOptionalNumber(options.distributionYes);
+  const explicitNo = toOptionalNumber(options.distributionNo);
   if (explicitYes !== null || explicitNo !== null) {
     if (explicitYes === null || explicitNo === null) {
       throw new Error('distributionYes and distributionNo must both be provided together.');
@@ -94,8 +78,8 @@ function resolveDistribution(options = {}) {
 }
 
 function deriveYesPctFromReserves(reserveYesUsdc, reserveNoUsdc) {
-  const yesReserve = toNumber(reserveYesUsdc);
-  const noReserve = toNumber(reserveNoUsdc);
+  const yesReserve = toOptionalNumber(reserveYesUsdc);
+  const noReserve = toOptionalNumber(reserveNoUsdc);
   if (yesReserve === null || noReserve === null) return null;
   const total = yesReserve + noReserve;
   if (!Number.isFinite(total) || total <= 0) return null;
@@ -108,8 +92,8 @@ function computeCompleteSetAllocation(options = {}) {
     throw new Error('liquidityUsdc must be a positive number.');
   }
 
-  const distributionYes = toNumber(options.distributionYes);
-  const distributionNo = toNumber(options.distributionNo);
+  const distributionYes = toOptionalNumber(options.distributionYes);
+  const distributionNo = toOptionalNumber(options.distributionNo);
   if (!Number.isInteger(distributionYes) || !Number.isInteger(distributionNo)) {
     throw new Error('distributionYes and distributionNo must be integers.');
   }
@@ -163,9 +147,9 @@ function computeCompleteSetAllocation(options = {}) {
 }
 
 function simulateDirectionalSwap(options = {}) {
-  const reserveYes = Math.max(0, toNumber(options.reserveYesUsdc) || 0);
-  const reserveNo = Math.max(0, toNumber(options.reserveNoUsdc) || 0);
-  const volumeUsdc = Math.max(0, toNumber(options.volumeUsdc) || 0);
+  const reserveYes = Math.max(0, toOptionalNumber(options.reserveYesUsdc) || 0);
+  const reserveNo = Math.max(0, toOptionalNumber(options.reserveNoUsdc) || 0);
+  const volumeUsdc = Math.max(0, toOptionalNumber(options.volumeUsdc) || 0);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
   const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
   const side = String(options.side || 'none').toLowerCase();
@@ -224,8 +208,8 @@ function simulateDirectionalSwap(options = {}) {
 
 function solveVolumeForTargetYesPct(options = {}) {
   const targetYesPct = toPercent(options.targetYesPct);
-  const reserveYesUsdc = toNumber(options.reserveYesUsdc);
-  const reserveNoUsdc = toNumber(options.reserveNoUsdc);
+  const reserveYesUsdc = toOptionalNumber(options.reserveYesUsdc);
+  const reserveNoUsdc = toOptionalNumber(options.reserveNoUsdc);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
 
   if (targetYesPct === null || reserveYesUsdc === null || reserveNoUsdc === null) {
@@ -276,7 +260,7 @@ function solveVolumeForTargetYesPct(options = {}) {
 
 function normalizeVolumeScenarios(value, liquidityUsdc) {
   const fallback = () => {
-    const liq = Math.max(1, toNumber(liquidityUsdc) || 0);
+    const liq = Math.max(1, toOptionalNumber(liquidityUsdc) || 0);
     return [
       round(liq * 0.25, 6),
       round(liq * 0.5, 6),
@@ -286,7 +270,7 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
   };
 
   if (Array.isArray(value)) {
-    const parsed = value.map((item) => toNumber(item)).filter((item) => Number.isFinite(item) && item >= 0).map((item) => round(item, 6));
+    const parsed = value.map((item) => toOptionalNumber(item)).filter((item) => Number.isFinite(item) && item >= 0).map((item) => round(item, 6));
     return parsed.length ? parsed : fallback();
   }
 
@@ -294,7 +278,7 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
   if (raw) {
     const parsed = raw
       .split(',')
-      .map((entry) => toNumber(entry.trim()))
+      .map((entry) => toOptionalNumber(entry.trim()))
       .filter((entry) => Number.isFinite(entry) && entry >= 0)
       .map((entry) => round(entry, 6));
     return parsed.length ? parsed : fallback();
@@ -304,13 +288,13 @@ function normalizeVolumeScenarios(value, liquidityUsdc) {
 }
 
 function computeHedgeMetrics(options = {}) {
-  const reserveYesUsdc = toNumber(options.reserveYesUsdc) || 0;
-  const reserveNoUsdc = toNumber(options.reserveNoUsdc) || 0;
-  const excessYesUsdc = toNumber(options.excessYesUsdc) || 0;
-  const excessNoUsdc = toNumber(options.excessNoUsdc) || 0;
-  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
+  const reserveYesUsdc = toOptionalNumber(options.reserveYesUsdc) || 0;
+  const reserveNoUsdc = toOptionalNumber(options.reserveNoUsdc) || 0;
+  const excessYesUsdc = toOptionalNumber(options.excessYesUsdc) || 0;
+  const excessNoUsdc = toOptionalNumber(options.excessNoUsdc) || 0;
+  const hedgeRatio = clamp(toOptionalNumber(options.hedgeRatio) || 1, 0, 5);
   const polymarketYesPct = toPercent(options.polymarketYesPct);
-  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const hedgeCostBps = Math.max(0, toOptionalNumber(options.hedgeCostBps) || 35);
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
   const feeRate = clamp(feeTier / 1_000_000, 0, 0.1);
 
@@ -453,8 +437,8 @@ function buildMirrorSimulate(options = {}) {
           : 'none';
 
   const feeTier = Number.isFinite(Number(options.feeTier)) ? Number(options.feeTier) : 3000;
-  const hedgeRatio = clamp(toNumber(options.hedgeRatio) || 1, 0, 5);
-  const hedgeCostBps = Math.max(0, toNumber(options.hedgeCostBps) || 35);
+  const hedgeRatio = clamp(toOptionalNumber(options.hedgeRatio) || 1, 0, 5);
+  const hedgeCostBps = Math.max(0, toOptionalNumber(options.hedgeCostBps) || 35);
   const polymarketYesPct = toPercent(
     options.polymarketYesPct !== undefined ? options.polymarketYesPct : (targetYesPct !== null ? targetYesPct : 50),
   );