pandora-cli-skills 1.1.42 → 1.1.44

package/README.md

@@ -130,6 +130,25 @@ pandora --output json lifecycle resolve --id <lifecycle-id> --confirm
 - `pandora schema`
 - `pandora mcp`
 
+## Quant ABM Baseline (Module Contract)
+
+- Deterministic ABM engine: `cli/lib/quant/abm_market.cjs`.
+- Simulate-agents handler module: `cli/lib/simulate_handlers/agents.cjs`.
+- Supported handler flags:
+  - `--n-informed` or `--n_informed`
+  - `--n-noise` or `--n_noise`
+  - `--n-mm` or `--n_mm`
+  - `--n-steps` or `--n_steps`
+  - `--seed`
+- ABM payload fields include:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` (`complexity`, `estimatedAgentDecisions`, `estimatedWorkUnits`)
+- Runtime bound metadata is documented as `O(n_steps * (n_informed + n_noise))`.
+- Unit coverage for this baseline is in `tests/unit/abm_market.test.cjs`.
+
 ## Docs
 
 - Full command contract and workflows: [`SKILL.md`](./SKILL.md)

package/README_FOR_SHARING.md

@@ -136,6 +136,27 @@ Prerequisite: Node.js `>=18`.
   - `pandora resolve`
 - `pandora lp add|remove|positions`
 
+## Quant ABM baseline (current implementation)
+- Deterministic ABM engine module:
+  - `cli/lib/quant/abm_market.cjs`
+- Simulate-agents handler module:
+  - `cli/lib/simulate_handlers/agents.cjs`
+- Handler parser accepts:
+  - `--n-informed|--n_informed`
+  - `--n-noise|--n_noise`
+  - `--n-mm|--n_mm`
+  - `--n-steps|--n_steps`
+  - `--seed`
+- ABM output fields include:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` with complexity `O(n_steps * (n_informed + n_noise))`
+- Coverage notes:
+  - `tests/unit/abm_market.test.cjs` validates deterministic seed behavior, required ABM metrics, parser/handler behavior, and runtime-bound calculations.
+  - `package.json` `test:unit` includes the ABM suite in default unit execution.
+
 ## Agent-native expansion details
 
 ### MCP server (`pandora mcp`)

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.44
 ---
 
 # Pandora CLI & Skills
@@ -80,6 +80,29 @@ npm link
   - `max_daily_loss_usd` is enforced as daily live notional (`counters.liveNotionalUsdc`).
   - `max_open_markets` is enforced as daily live operation count (`counters.liveOps`).
 
+## Quant ABM baseline (module contract)
+- Deterministic ABM core:
+  - `cli/lib/quant/abm_market.cjs`
+- Simulate-agents handler:
+  - `cli/lib/simulate_handlers/agents.cjs`
+- Handler flags:
+  - `--n-informed|--n_informed`
+  - `--n-noise|--n_noise`
+  - `--n-mm|--n_mm`
+  - `--n-steps|--n_steps`
+  - `--seed`
+- ABM payload fields:
+  - `convergenceError`
+  - `spreadTrajectory[]`
+  - `volume` (`total`, `averagePerStep`, `byAgentType`)
+  - `pnlByAgentType`
+  - `runtimeBounds` (`complexity`, `estimatedAgentDecisions`, `estimatedWorkUnits`)
+- Runtime complexity metadata: `O(n_steps * (n_informed + n_noise))`.
+- Unit coverage:
+  - `tests/unit/abm_market.test.cjs`
+- Note:
+  - This section documents the current module + handler contract. Top-level simulate namespace routing can consume this handler when wired by command service.
+
 ## Complete command + flag reference (authoritative)
 This section mirrors live CLI help output so agent runs can rely on one source of truth.
 
@@ -93,7 +116,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>]
@@ -131,12 +154,12 @@ Mirror subcommand detail:
 ```text
 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>]
 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>]
-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...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
+deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--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...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 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>]
 lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>]
 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>]
+simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier <500-50000>] [--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-50000>] [--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 --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
@@ -443,6 +466,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>] [--slippage-pct-per-leg <n>] [--amount-usdc <n>] [--combinatorial] [--max-bundle-size <n>] [--interval-ms <ms>] [--iterations <n>] [--indexer-url <url>] [--timeout-ms <ms>]';
 
 function requireDep(deps, name) {
   if (!deps || typeof deps[name] !== 'function') {
@@ -139,6 +139,114 @@ function buildArbOpportunities(options) {
   return opportunities;
 }
 
+function enumerateCombinations(items, size, onCombination) {
+  if (!Array.isArray(items) || !Number.isInteger(size) || size < 1 || size > items.length) return;
+  if (typeof onCombination !== 'function') return;
+
+  const selected = [];
+  function walk(startIndex) {
+    if (selected.length === size) {
+      onCombination(selected.slice());
+      return;
+    }
+    const remaining = size - selected.length;
+    const maxStart = items.length - remaining;
+    for (let index = startIndex; index <= maxStart; index += 1) {
+      selected.push(items[index]);
+      walk(index + 1);
+      selected.pop();
+    }
+  }
+  walk(0);
+}
+
+/**
+ * Build bundle-level combinatorial opportunities across provided markets.
+ * @param {object} options
+ * @returns {object[]}
+ */
+function buildCombinatorialArbOpportunities(options) {
+  const marketSnapshots = Array.isArray(options.marketSnapshots)
+    ? options.marketSnapshots.filter((item) => item && Number.isFinite(item.yesPct))
+    : [];
+  if (marketSnapshots.length < 3) return [];
+
+  const minNetSpreadPct = Number.isFinite(options.minNetSpreadPct) ? Number(options.minNetSpreadPct) : 0;
+  const feePctPerLeg = Number.isFinite(options.feePctPerLeg) ? Number(options.feePctPerLeg) : 0;
+  const slippagePctPerLeg = Number.isFinite(options.slippagePctPerLeg) ? Number(options.slippagePctPerLeg) : 0;
+  const amountUsdc = Number.isFinite(options.amountUsdc) ? Number(options.amountUsdc) : 0;
+  const requestedMaxBundleSize = Number.isInteger(options.maxBundleSize) ? options.maxBundleSize : 4;
+  const maxBundleSize = Math.max(3, Math.min(requestedMaxBundleSize, marketSnapshots.length));
+
+  const opportunities = [];
+  for (let bundleSize = 3; bundleSize <= maxBundleSize; bundleSize += 1) {
+    enumerateCombinations(marketSnapshots, bundleSize, (bundle) => {
+      const bundleMarketIds = bundle.map((item) => item.id);
+      const sumYesPct = roundNumber(bundle.reduce((total, item) => total + Number(item.yesPct), 0), 6);
+      const sumNoPct = roundNumber(bundle.reduce((total, item) => total + (100 - Number(item.yesPct)), 0), 6);
+      const feeImpactPct = roundNumber(bundleSize * feePctPerLeg, 6);
+      const slippageImpactPct = roundNumber(bundleSize * slippagePctPerLeg, 6);
+
+      const evaluate = (strategy) => {
+        const grossEdgePct = strategy === 'buy_yes_bundle' ? roundNumber(100 - sumYesPct, 6) : roundNumber(sumYesPct - 100, 6);
+        if (grossEdgePct <= 0) return;
+
+        const netSpreadPct = roundNumber(grossEdgePct - feeImpactPct - slippageImpactPct, 6);
+        if (netSpreadPct <= 0 || netSpreadPct < minNetSpreadPct) return;
+
+        const payoutPct = strategy === 'buy_yes_bundle' ? 100 : roundNumber((bundleSize - 1) * 100, 6);
+        const totalEntryPct = strategy === 'buy_yes_bundle' ? sumYesPct : sumNoPct;
+        const grossProfitUsdc = roundNumber((amountUsdc * grossEdgePct) / 100, 6);
+        const profitUsdc = roundNumber((amountUsdc * netSpreadPct) / 100, 6);
+
+        opportunities.push({
+          opportunityType: 'combinatorial',
+          strategy,
+          pair: `bundle:${bundleMarketIds.join('|')}:${strategy}`,
+          bundleMarketIds,
+          bundleSize,
+          legs: bundle.map((item) => ({
+            marketId: item.id,
+            yesPct: roundNumber(item.yesPct, 6),
+            noPct: roundNumber(100 - item.yesPct, 6),
+          })),
+          sumYesPct,
+          sumNoPct,
+          totalEntryPct,
+          payoutPct,
+          grossSpreadPct: grossEdgePct,
+          grossEdgePct,
+          feePctPerLeg: roundNumber(feePctPerLeg, 6),
+          slippagePctPerLeg: roundNumber(slippagePctPerLeg, 6),
+          feeImpactPct,
+          slippageImpactPct,
+          netSpreadPct,
+          netSpread: roundNumber(netSpreadPct / 100, 8),
+          amountUsdc: roundNumber(amountUsdc, 6),
+          grossProfitUsdc,
+          profitUsdc,
+          profit: profitUsdc,
+        });
+      };
+
+      evaluate('buy_yes_bundle');
+      evaluate('buy_no_bundle');
+    });
+  }
+
+  opportunities.sort((left, right) => {
+    if (right.netSpreadPct !== left.netSpreadPct) {
+      return right.netSpreadPct - left.netSpreadPct;
+    }
+    if (right.bundleSize !== left.bundleSize) {
+      return right.bundleSize - left.bundleSize;
+    }
+    return left.pair.localeCompare(right.pair);
+  });
+
+  return opportunities;
+}
+
 /**
  * Parse `arb scan` command flags.
  * @param {string[]} args
@@ -159,7 +267,10 @@ function parseArbScanFlags(args, deps) {
     output: 'ndjson',
     minNetSpreadPct: 0,
     feePctPerLeg: 0,
+    slippagePctPerLeg: 0,
     amountUsdc: 100,
+    combinatorial: false,
+    maxBundleSize: 4,
     intervalMs: 5_000,
     iterations: null,
   };
@@ -187,11 +298,25 @@ function parseArbScanFlags(args, deps) {
       i += 1;
       continue;
     }
+    if (token === '--slippage-pct-per-leg') {
+      options.slippagePctPerLeg = parseNumber(requireFlagValue(rest, i, '--slippage-pct-per-leg'), '--slippage-pct-per-leg');
+      i += 1;
+      continue;
+    }
     if (token === '--amount-usdc') {
       options.amountUsdc = parsePositiveNumber(requireFlagValue(rest, i, '--amount-usdc'), '--amount-usdc');
       i += 1;
       continue;
     }
+    if (token === '--combinatorial') {
+      options.combinatorial = true;
+      continue;
+    }
+    if (token === '--max-bundle-size') {
+      options.maxBundleSize = parsePositiveInteger(requireFlagValue(rest, i, '--max-bundle-size'), '--max-bundle-size');
+      i += 1;
+      continue;
+    }
     if (token === '--interval-ms') {
       options.intervalMs = parsePositiveInteger(requireFlagValue(rest, i, '--interval-ms'), '--interval-ms');
       i += 1;
@@ -210,8 +335,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) {
@@ -222,6 +347,14 @@ function parseArbScanFlags(args, deps) {
     throw new CliError('INVALID_FLAG_VALUE', '--fee-pct-per-leg must be >= 0.');
   }
 
+  if (options.slippagePctPerLeg < 0) {
+    throw new CliError('INVALID_FLAG_VALUE', '--slippage-pct-per-leg must be >= 0.');
+  }
+
+  if (!Number.isInteger(options.maxBundleSize) || options.maxBundleSize < 3) {
+    throw new CliError('INVALID_FLAG_VALUE', '--max-bundle-size must be an integer >= 3.');
+  }
+
   options.markets = Array.from(
     new Set(
       options.markets
@@ -234,6 +367,10 @@ function parseArbScanFlags(args, deps) {
     throw new CliError('INVALID_ARGS', 'arb scan requires at least two distinct market ids.');
   }
 
+  if (options.combinatorial && options.markets.length < 3) {
+    throw new CliError('INVALID_ARGS', 'arb scan --combinatorial requires at least three distinct market ids.');
+  }
+
   return options;
 }
 
@@ -291,8 +428,30 @@ 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 iterationSnapshots = [];
+    let emittedCombinatorialCount = 0;
 
     while (iteration < maxIterations) {
       iteration += 1;
@@ -300,37 +459,100 @@ function createRunArbCommand(deps) {
         buildGraphqlGetQuery,
         graphqlRequest,
       });
-      const snapshots = buildMarketSnapshots(markets, options.markets);
-      const opportunities = buildArbOpportunities({
-        marketSnapshots: snapshots,
+      const marketSnapshots = buildMarketSnapshots(markets, options.markets);
+      const pairwiseOpportunities = buildArbOpportunities({
+        marketSnapshots,
         minNetSpreadPct: options.minNetSpreadPct,
         feePctPerLeg: options.feePctPerLeg,
         amountUsdc: options.amountUsdc,
       });
+      const combinatorialOpportunities = options.combinatorial
+        ? buildCombinatorialArbOpportunities({
+            marketSnapshots,
+            minNetSpreadPct: options.minNetSpreadPct,
+            feePctPerLeg: options.feePctPerLeg,
+            slippagePctPerLeg: options.slippagePctPerLeg,
+            amountUsdc: options.amountUsdc,
+            maxBundleSize: options.maxBundleSize,
+          })
+        : [];
+      emittedCombinatorialCount += combinatorialOpportunities.length;
+      const opportunities = [...pairwiseOpportunities, ...combinatorialOpportunities].sort((left, right) => {
+        if (right.netSpreadPct !== left.netSpreadPct) {
+          return right.netSpreadPct - left.netSpreadPct;
+        }
+        return String(left.pair || '').localeCompare(String(right.pair || ''));
+      });
 
-      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 {
+        iterationSnapshots.push({
+          iteration,
+          observedAt: new Date().toISOString(),
+          count: opportunities.length,
+          pairwiseCount: pairwiseOpportunities.length,
+          combinatorialCount: combinatorialOpportunities.length,
+          opportunities,
+        });
       }
 
       if (iteration < maxIterations) {
         await sleepMs(options.intervalMs);
       }
     }
+
+    if (options.output === 'json') {
+      const diagnostics = [];
+      if (options.combinatorial && emittedCombinatorialCount === 0) {
+        diagnostics.push('No combinatorial bundles cleared net spread thresholds for this run.');
+      }
+
+      const payload = {
+        action: 'scan',
+        indexerUrl,
+        iterationsCompleted: iteration,
+        requestedIterations: options.iterations,
+        intervalMs: options.intervalMs,
+        filters: {
+          markets: options.markets,
+          minNetSpreadPct: options.minNetSpreadPct,
+          feePctPerLeg: options.feePctPerLeg,
+          slippagePctPerLeg: options.slippagePctPerLeg,
+          amountUsdc: options.amountUsdc,
+          combinatorial: options.combinatorial,
+          maxBundleSize: options.maxBundleSize,
+        },
+        opportunities: iterationSnapshots.flatMap((row) => row.opportunities),
+        snapshots: iterationSnapshots,
+        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));
+      }
+    }
   };
 }
 
 module.exports = {
   ARB_USAGE,
   buildArbOpportunities,
+  buildCombinatorialArbOpportunities,
   createRunArbCommand,
   parseArbScanFlags,
 };