pandora-cli-skills 1.1.42 → 1.1.43

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
-version: 1.1.42
+version: 1.1.43
 ---
 
 # Pandora CLI & Skills
@@ -93,7 +93,7 @@ pandora [--output table|json] markets list [--limit <n>] [--after <cursor>] [--b
 pandora [--output table|json] markets get [--id <id> ...] [--stdin]
 pandora [--output table|json] sports books list|events list|events live|odds snapshot|odds bulk|consensus|create plan|create run|sync once|sync run|sync start|sync stop|sync status|resolve plan [flags]
 pandora [--output table|json] lifecycle start --config <path>|status --id <id>|resolve --id <id> --confirm
-pandora arb scan --markets <csv> --output ndjson [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--iterations <n>] [--interval-ms <ms>]
+pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--iterations <n>] [--interval-ms <ms>]
 pandora [--output table|json] odds record --competition <id> --interval <sec> [--max-samples <n>] [--event-id <id>] [--venues pandora_amm,polymarket]
 pandora [--output table|json] odds history --event-id <id> --output csv|json [--limit <n>]
 pandora [--output table|json] polls list [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--status <int>] [--category <int>] [--question-contains <text>] [--where-json <json>]
@@ -443,6 +443,12 @@ Common structured error codes for automation:
 - `INDEXER_HTTP_ERROR` / `INDEXER_TIMEOUT`: indexer transport failure.
 - `MIRROR_*`: mirror pipeline/service failures (plan/deploy/verify/sync/go/status).
 - `POLYMARKET_*`: Polymarket resolution/auth/order/preflight failures.
+- `RISK_*`: risk state/guardrail/panic failures (`RISK_PANIC_ACTIVE`, `RISK_GUARDRAIL_BLOCKED`, etc.).
+- `LIFECYCLE_*`: lifecycle state-machine file operations (`LIFECYCLE_EXISTS`, `LIFECYCLE_NOT_FOUND`).
+- `ODDS_*`: odds record/history storage and connector failures.
+- `ARB_*`: arb scan parsing/execution output-mode failures.
+- `CONFIG_*`: config read/parse failures (for example `CONFIG_FILE_NOT_FOUND`).
+- `MCP_FILE_ACCESS_BLOCKED`: MCP-mode file path denied outside workspace root.
 - `WEBHOOK_DELIVERY_FAILED`: webhook hard-fail when `--fail-on-webhook-error` is set.
 
 Error envelope:

package/cli/lib/arb_command_service.cjs

@@ -14,7 +14,7 @@ const ARB_MARKET_FIELDS = [
 ];
 
 const ARB_USAGE =
-  'pandora arb scan --markets <csv> --output ndjson [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--interval-ms <ms>] [--iterations <n>] [--indexer-url <url>] [--timeout-ms <ms>]';
+  'pandora arb scan --markets <csv> --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--amount-usdc <n>] [--interval-ms <ms>] [--iterations <n>] [--indexer-url <url>] [--timeout-ms <ms>]';
 
 function requireDep(deps, name) {
   if (!deps || typeof deps[name] !== 'function') {
@@ -210,8 +210,8 @@ function parseArbScanFlags(args, deps) {
     throw new CliError('MISSING_REQUIRED_FLAG', 'arb scan requires at least two markets via --markets <csv>.');
   }
 
-  if (options.output !== 'ndjson') {
-    throw new CliError('INVALID_FLAG_VALUE', 'arb scan currently supports only --output ndjson.');
+  if (!['ndjson', 'json'].includes(options.output)) {
+    throw new CliError('INVALID_FLAG_VALUE', 'arb scan supports --output ndjson|json.');
   }
 
   if (options.minNetSpreadPct < 0) {
@@ -291,8 +291,29 @@ function createRunArbCommand(deps) {
       parsePositiveInteger,
     });
 
+    const mcpMode = String(process.env.PANDORA_MCP_MODE || '').trim() === '1';
+    if (mcpMode && options.output !== 'json') {
+      throw new CliError('MCP_LONG_RUNNING_MODE_BLOCKED', 'arb scan via MCP requires --output json and a bounded iteration count.', {
+        toolName: 'arb.scan',
+        hints: ['Use arb.scan with --output json --iterations 1 when calling via MCP.'],
+      });
+    }
+
+    if (options.output === 'json' && !Number.isInteger(options.iterations)) {
+      options.iterations = 1;
+    }
+
+    if (options.output === 'json' && Number.isInteger(options.iterations) && options.iterations > 1) {
+      const code = mcpMode ? 'MCP_LONG_RUNNING_MODE_BLOCKED' : 'INVALID_FLAG_VALUE';
+      throw new CliError(code, 'arb scan --output json supports only --iterations 1.', {
+        toolName: 'arb.scan',
+        hints: ['Use --output ndjson for streaming multi-iteration scans.'],
+      });
+    }
+
     const maxIterations = Number.isInteger(options.iterations) ? options.iterations : Number.POSITIVE_INFINITY;
     let iteration = 0;
+    const snapshots = [];
 
     while (iteration < maxIterations) {
       iteration += 1;
@@ -308,23 +329,58 @@ function createRunArbCommand(deps) {
         amountUsdc: options.amountUsdc,
       });
 
-      for (const opportunity of opportunities) {
-        // eslint-disable-next-line no-console
-        console.log(
-          JSON.stringify({
-            type: 'arb.scan.opportunity',
-            timestamp: new Date().toISOString(),
-            iteration,
-            indexerUrl,
-            ...opportunity,
-          }),
-        );
+      if (options.output === 'ndjson') {
+        for (const opportunity of opportunities) {
+          // eslint-disable-next-line no-console
+          console.log(
+            JSON.stringify({
+              type: 'arb.scan.opportunity',
+              timestamp: new Date().toISOString(),
+              iteration,
+              indexerUrl,
+              ...opportunity,
+            }),
+          );
+        }
+      } else {
+        snapshots.push({
+          iteration,
+          observedAt: new Date().toISOString(),
+          count: opportunities.length,
+          opportunities,
+        });
       }
 
       if (iteration < maxIterations) {
         await sleepMs(options.intervalMs);
       }
     }
+
+    if (options.output === 'json') {
+      const payload = {
+        action: 'scan',
+        indexerUrl,
+        iterationsCompleted: iteration,
+        requestedIterations: options.iterations,
+        intervalMs: options.intervalMs,
+        filters: {
+          markets: options.markets,
+          minNetSpreadPct: options.minNetSpreadPct,
+          feePctPerLeg: options.feePctPerLeg,
+          amountUsdc: options.amountUsdc,
+        },
+        opportunities: snapshots.flatMap((row) => row.opportunities),
+        snapshots,
+        diagnostics: [],
+      };
+
+      if (context.outputMode === 'json') {
+        emitSuccess(context.outputMode, 'arb.scan', payload);
+      } else {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(payload, null, 2));
+      }
+    }
   };
 }
 

package/cli/lib/command_executor_service.cjs

@@ -149,11 +149,16 @@ function createCommandExecutorService(options = {}) {
       ? Math.max(1_000, Math.trunc(runtime.timeoutMs))
       : defaultTimeoutMs;
     const env = runtime.env && typeof runtime.env === 'object' ? runtime.env : baseEnv;
+    const childEnv = {
+      ...env,
+      // Mark child CLI invocations as MCP-controlled to enable stricter file/path safety guards.
+      PANDORA_MCP_MODE: '1',
+    };
     const argv = ['--output', 'json', ...commandArgs];
 
     const result = spawnSync(process.execPath, [cliPath, ...argv], {
       encoding: 'utf8',
-      env,
+      env: childEnv,
       timeout: timeoutMs,
       killSignal: 'SIGKILL',
       maxBuffer: 10 * 1024 * 1024,

package/cli/lib/error_recovery_service.cjs

@@ -99,6 +99,30 @@ function buildSportsResolvePlanRetryCommand(cliName, details) {
   return `${cliName} sports resolve plan --event-id ${eventId}`;
 }
 
+function buildLifecycleStatusCommand(cliName, details) {
+  const id = cleanToken(details && details.id, '<lifecycle-id>');
+  return `${cliName} lifecycle status --id ${id}`;
+}
+
+function buildLifecycleStartCommand(cliName, details) {
+  const configPath = cleanToken(details && details.configPath, '<config-file>');
+  return `${cliName} lifecycle start --config ${configPath}`;
+}
+
+function buildOddsRecordCommand(cliName, details) {
+  const competition = cleanToken(details && details.competition, '<competition>');
+  return `${cliName} odds record --competition ${competition} --interval 60 --max-samples 1`;
+}
+
+function buildOddsHistoryCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} odds history --event-id ${eventId} --output json`;
+}
+
+function buildArbScanCommand(cliName) {
+  return `${cliName} arb scan --markets <market-a>,<market-b> --output json --iterations 1`;
+}
+
 /**
  * Build deterministic Next-Best-Action recovery hints for JSON errors.
  * @param {{cliName?: string}} [options]
@@ -264,6 +288,52 @@ function createErrorRecoveryService(options = {}) {
           command: buildSportsResolvePlanRetryCommand(cliName, details),
           retryable: true,
         };
+      case 'LIFECYCLE_EXISTS':
+        return {
+          action: 'Inspect existing lifecycle state before creating another run',
+          command: buildLifecycleStatusCommand(cliName, details),
+          retryable: true,
+        };
+      case 'CONFIG_FILE_NOT_FOUND':
+        return {
+          action: 'Create/fix lifecycle config file and retry start',
+          command: buildLifecycleStartCommand(cliName, details),
+          retryable: true,
+        };
+      case 'LIFECYCLE_NOT_FOUND':
+        return {
+          action: 'Verify lifecycle id and inspect currently tracked runs',
+          command: `${cliName} lifecycle status --id <lifecycle-id>`,
+          retryable: true,
+        };
+      case 'ODDS_RECORD_CONNECTOR_FAILED':
+      case 'ODDS_RECORD_FAILED':
+      case 'ODDS_RECORD_WRITE_FAILED':
+        return {
+          action: 'Run one bounded odds capture sample to isolate connector/storage errors',
+          command: buildOddsRecordCommand(cliName, details),
+          retryable: true,
+        };
+      case 'ODDS_HISTORY_READ_FAILED':
+      case 'ODDS_HISTORY_FAILED':
+        return {
+          action: 'Retry odds history read with explicit event id and JSON output',
+          command: buildOddsHistoryCommand(cliName, details),
+          retryable: true,
+        };
+      case 'ARB_SCAN_FAILED':
+      case 'ARB_SCAN_INVALID_OUTPUT':
+        return {
+          action: 'Run a bounded arb scan iteration for deterministic diagnostics',
+          command: buildArbScanCommand(cliName),
+          retryable: true,
+        };
+      case 'MCP_FILE_ACCESS_BLOCKED':
+        return {
+          action: 'Use a workspace-relative file path when invoking tools via MCP',
+          command: `${cliName} help`,
+          retryable: true,
+        };
       case 'MISSING_REQUIRED_FLAG':
       case 'MISSING_FLAG_VALUE':
       case 'INVALID_FLAG_VALUE':

package/cli/lib/lifecycle_command_service.cjs

@@ -59,7 +59,10 @@ function readJsonFile(filePath, CliError) {
     raw = fs.readFileSync(filePath, 'utf8');
   } catch (err) {
     if (err && err.code === 'ENOENT') {
-      throw new CliError('NOT_FOUND', `Lifecycle not found for id: ${path.basename(filePath, '.json')}`);
+      throw new CliError('LIFECYCLE_NOT_FOUND', `Lifecycle not found for id: ${path.basename(filePath, '.json')}`, {
+        id: path.basename(filePath, '.json'),
+        filePath,
+      });
     }
     throw err;
   }
@@ -84,6 +87,15 @@ function writeJsonFileAtomic(filePath, payload) {
   }
 }
 
+function isMcpMode() {
+  return String(process.env.PANDORA_MCP_MODE || '').trim() === '1';
+}
+
+function isPathInside(baseDir, candidatePath) {
+  const relative = path.relative(baseDir, candidatePath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
 function renderLifecycleTable(payload) {
   // eslint-disable-next-line no-console
   console.log(`Lifecycle: ${payload.id}`);
@@ -111,6 +123,24 @@ function createRunLifecycleCommand(deps) {
   const commandHelpPayload = requireDep(deps, 'commandHelpPayload');
   const parseLifecycleFlags = requireDep(deps, 'parseLifecycleFlags');
 
+  function assertMcpReadablePathAllowed(targetPath, flagName) {
+    if (!isMcpMode()) return;
+    const workspaceRoot = path.resolve(process.cwd());
+    const resolvedPath = path.resolve(targetPath);
+    if (!isPathInside(workspaceRoot, resolvedPath)) {
+      throw new CliError(
+        'MCP_FILE_ACCESS_BLOCKED',
+        `${flagName} must point to a file within the current workspace when running via MCP.`,
+        {
+          flag: flagName,
+          requestedPath: targetPath,
+          resolvedPath,
+          workspaceRoot,
+        },
+      );
+    }
+  }
+
   return async function runLifecycleCommand(args, context) {
     const action = args[0];
     const actionArgs = args.slice(1);
@@ -165,12 +195,15 @@ function createRunLifecycleCommand(deps) {
 
     if (options.action === 'start') {
       const configPath = path.resolve(process.cwd(), options.configPath);
+      assertMcpReadablePathAllowed(configPath, '--config');
       let configRaw;
       try {
         configRaw = fs.readFileSync(configPath, 'utf8');
       } catch (err) {
         if (err && err.code === 'ENOENT') {
-          throw new CliError('CONFIG_FILE_NOT_FOUND', `Lifecycle config file not found: ${configPath}`);
+          throw new CliError('CONFIG_FILE_NOT_FOUND', `Lifecycle config file not found: ${configPath}`, {
+            configPath,
+          });
         }
         throw err;
       }
@@ -179,7 +212,9 @@ function createRunLifecycleCommand(deps) {
       try {
         config = JSON.parse(configRaw);
       } catch {
-        throw new CliError('INVALID_JSON', `Lifecycle config must be valid JSON: ${configPath}`);
+        throw new CliError('INVALID_JSON', `Lifecycle config must be valid JSON: ${configPath}`, {
+          configPath,
+        });
       }
 
       if (!config || typeof config !== 'object' || Array.isArray(config)) {
@@ -197,7 +232,10 @@ function createRunLifecycleCommand(deps) {
 
       const filePath = lifecycleFilePath(lifecycleDir, id);
       if (fs.existsSync(filePath)) {
-        throw new CliError('LIFECYCLE_EXISTS', `Lifecycle already exists for id: ${id}`);
+        throw new CliError('LIFECYCLE_EXISTS', `Lifecycle already exists for id: ${id}`, {
+          id,
+          filePath,
+        });
       }
 
       const nowIso = new Date().toISOString();

package/cli/lib/mcp_tool_registry.cjs

@@ -243,8 +243,14 @@ const TOOL_DEFINITIONS = [
     name: 'odds.record',
     command: ['odds', 'record'],
     description: 'Record venue odds snapshots into local history storage.',
+    longRunningBlocked: true,
     mutating: true,
   },
+  {
+    name: 'arb.scan',
+    command: ['arb', 'scan', '--output', 'json', '--iterations', '1'],
+    description: 'Run one bounded arb scan iteration and return a structured payload.',
+  },
   { name: 'lifecycle.status', command: ['lifecycle', 'status'], description: 'Inspect lifecycle state by id.' },
   {
     name: 'lifecycle.start',

package/cli/lib/odds_command_service.cjs

@@ -0,0 +1,168 @@
+function requireDep(deps, name) {
+  if (!deps || typeof deps[name] !== 'function') {
+    throw new Error(`createRunOddsCommand requires deps.${name}()`);
+  }
+  return deps[name];
+}
+
+const ODDS_RECORD_USAGE =
+  'pandora [--output table|json] odds record --competition <id> --interval <sec> [--max-samples <n>] [--event-id <id>] [--venues pandora_amm,polymarket] [--indexer-url <url>] [--polymarket-host <url>] [--polymarket-mock-url <url>] [--timeout-ms <ms>]';
+const ODDS_HISTORY_USAGE =
+  'pandora [--output table|json] odds history --event-id <id> --output csv|json [--limit <n>]';
+
+/**
+ * Create runner for `pandora odds` commands.
+ * @param {object} deps
+ * @returns {(args: string[], context: {outputMode: 'table'|'json'}) => Promise<void>}
+ */
+function createRunOddsCommand(deps) {
+  const parseIndexerSharedFlags = requireDep(deps, 'parseIndexerSharedFlags');
+  const includesHelpFlag = requireDep(deps, 'includesHelpFlag');
+  const maybeLoadIndexerEnv = requireDep(deps, 'maybeLoadIndexerEnv');
+  const resolveIndexerUrl = requireDep(deps, 'resolveIndexerUrl');
+  const parseOddsFlags = requireDep(deps, 'parseOddsFlags');
+  const createOddsHistoryService = requireDep(deps, 'createOddsHistoryService');
+  const createVenueConnectorFactory = requireDep(deps, 'createVenueConnectorFactory');
+  const sleepMs = requireDep(deps, 'sleepMs');
+  const emitSuccess = requireDep(deps, 'emitSuccess');
+  const renderSingleEntityTable = requireDep(deps, 'renderSingleEntityTable');
+
+  return async function runOddsCommand(args, context) {
+    const shared = parseIndexerSharedFlags(args);
+    if (!shared.rest.length || includesHelpFlag(shared.rest)) {
+      if (context.outputMode === 'json') {
+        emitSuccess(context.outputMode, 'odds.help', {
+          usage: ODDS_RECORD_USAGE,
+          historyUsage: ODDS_HISTORY_USAGE,
+        });
+      } else {
+        // eslint-disable-next-line no-console
+        console.log(`Usage: ${ODDS_RECORD_USAGE}`);
+        // eslint-disable-next-line no-console
+        console.log(`       ${ODDS_HISTORY_USAGE}`);
+      }
+      return;
+    }
+
+    maybeLoadIndexerEnv(shared);
+    const indexerUrl = resolveIndexerUrl(shared.indexerUrl);
+    const parsed = parseOddsFlags(shared.rest);
+    const options = parsed.options || {};
+
+    const historyService = createOddsHistoryService();
+    const connectorFactory = createVenueConnectorFactory();
+
+    if (parsed.action === 'record') {
+      const intervalMs = Number(options.intervalSec) * 1000;
+      const maxSamples = Number.isInteger(options.maxSamples) && options.maxSamples > 0 ? options.maxSamples : 1;
+      const sampleResults = [];
+      let insertedTotal = 0;
+
+      for (let sample = 1; sample <= maxSamples; sample += 1) {
+        const rows = [];
+        const diagnostics = [];
+        for (const venue of options.venues) {
+          try {
+            const connector = connectorFactory.createConnector(venue, {
+              indexerUrl,
+              host: options.polymarketHost || null,
+              mockUrl: options.polymarketMockUrl || null,
+              timeoutMs: options.timeoutMs || shared.timeoutMs,
+            });
+            const pricePayload = await connector.getPrice({
+              competition: options.competition,
+              eventId: options.eventId,
+              indexerUrl,
+              host: options.polymarketHost || null,
+              mockUrl: options.polymarketMockUrl || null,
+              timeoutMs: options.timeoutMs || shared.timeoutMs,
+            });
+            if (pricePayload && Array.isArray(pricePayload.items)) {
+              rows.push(...pricePayload.items);
+            }
+          } catch (err) {
+            diagnostics.push({
+              venue,
+              code: err && err.code ? String(err.code) : 'ODDS_RECORD_CONNECTOR_FAILED',
+              message: err && err.message ? err.message : String(err),
+            });
+          }
+        }
+
+        const writeResult = historyService.recordEntries(rows);
+        insertedTotal += writeResult.inserted;
+        sampleResults.push({
+          sample,
+          observedAt: new Date().toISOString(),
+          inserted: writeResult.inserted,
+          diagnostics,
+        });
+
+        if (sample < maxSamples) {
+          await sleepMs(intervalMs);
+        }
+      }
+
+      emitSuccess(context.outputMode, 'odds.record', {
+        schemaVersion: '1.0.0',
+        generatedAt: new Date().toISOString(),
+        action: 'record',
+        competition: options.competition,
+        eventId: options.eventId || null,
+        intervalSec: options.intervalSec,
+        maxSamples,
+        venues: options.venues,
+        backend: historyService.backend,
+        storage: historyService.paths,
+        insertedTotal,
+        samples: sampleResults,
+      }, renderSingleEntityTable);
+      return;
+    }
+
+    const rows = historyService.queryByEventId(options.eventId, {
+      limit: options.limit,
+    });
+    const basePayload = {
+      schemaVersion: '1.0.0',
+      generatedAt: new Date().toISOString(),
+      action: 'history',
+      eventId: options.eventId,
+      backend: historyService.backend,
+      storage: historyService.paths,
+      count: rows.length,
+      items: rows,
+    };
+
+    if (options.output === 'csv') {
+      const csv = historyService.formatRows(rows, 'csv');
+      if (context.outputMode === 'json') {
+        emitSuccess(context.outputMode, 'odds.history', {
+          ...basePayload,
+          output: 'csv',
+          csv,
+        });
+      } else {
+        // eslint-disable-next-line no-console
+        console.log(csv);
+      }
+      return;
+    }
+
+    if (context.outputMode === 'json') {
+      emitSuccess(context.outputMode, 'odds.history', {
+        ...basePayload,
+        output: 'json',
+      });
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(JSON.stringify(basePayload, null, 2));
+    }
+  };
+}
+
+module.exports = {
+  createRunOddsCommand,
+  ODDS_RECORD_USAGE,
+  ODDS_HISTORY_USAGE,
+};

package/cli/lib/parsers/odds_flags.cjs

@@ -29,6 +29,7 @@ function createParseOddsFlags(deps) {
   const requireFlagValue = requireDep(deps, 'requireFlagValue');
   const parsePositiveInteger = requireDep(deps, 'parsePositiveInteger');
   const parseCsvList = requireDep(deps, 'parseCsvList');
+  const isSecureHttpUrlOrLocal = requireDep(deps, 'isSecureHttpUrlOrLocal');
 
   return function parseOddsFlags(args) {
     const action = String((args && args[0]) || '').trim().toLowerCase();
@@ -79,16 +80,34 @@ function createParseOddsFlags(deps) {
         }
         if (token === '--indexer-url') {
           options.indexerUrl = requireFlagValue(rest, i, '--indexer-url');
+          if (!isSecureHttpUrlOrLocal(options.indexerUrl)) {
+            throw new CliError(
+              'INVALID_FLAG_VALUE',
+              `--indexer-url must use https:// (or http://localhost/127.0.0.1). Received: "${options.indexerUrl}"`,
+            );
+          }
           i += 1;
           continue;
         }
         if (token === '--polymarket-host') {
           options.polymarketHost = requireFlagValue(rest, i, '--polymarket-host');
+          if (!isSecureHttpUrlOrLocal(options.polymarketHost)) {
+            throw new CliError(
+              'INVALID_FLAG_VALUE',
+              `--polymarket-host must use https:// (or http://localhost/127.0.0.1). Received: "${options.polymarketHost}"`,
+            );
+          }
           i += 1;
           continue;
         }
         if (token === '--polymarket-mock-url') {
           options.polymarketMockUrl = requireFlagValue(rest, i, '--polymarket-mock-url');
+          if (!isSecureHttpUrlOrLocal(options.polymarketMockUrl)) {
+            throw new CliError(
+              'INVALID_FLAG_VALUE',
+              `--polymarket-mock-url must use https:// (or http://localhost/127.0.0.1). Received: "${options.polymarketMockUrl}"`,
+            );
+          }
           i += 1;
           continue;
         }