kalshi-trading-bot-cli 2.1.4 → 2.1.5

package/README.md

@@ -28,6 +28,8 @@ That's it — no clone, no install. The setup wizard runs automatically on first
 
 Prefer a global install? `bun add -g kalshi-trading-bot-cli` then run `kalshi`.
 
+> **Scripting and agent use** — for parallel invocations, `--json` consumers, or anything that pipes our output: **install globally and use the `kalshi` binary**, not `bunx`. See [Scripting & Parallel Use](#scripting--parallel-use) below for the gory details.
+
 Or work from a clone:
 
 ```bash
@@ -363,6 +365,37 @@ UNRESOLVED (105 markets)
 
 Set `KALSHI_USE_DEMO=true` in your `.env` to use Kalshi's demo environment. All trades are simulated — no real money at risk.
 
+## Scripting & Parallel Use
+
+The `bunx kalshi-trading-bot-cli@latest …` form is great for one-off interactive use, but it has two gotchas when you script against it:
+
+**1. Install chatter leaks into `--json` output.** Bun prints lines like `Resolving dependencies` and `Saved lockfile` to stdout *before* our CLI runs, which corrupts JSON pipelines.
+
+**2. Parallel invocations race on the install cache.** Running multiple `bunx kalshi-trading-bot-cli@latest …` calls in parallel can fail with `Failed to link …: EEXIST` and `could not determine executable`. See [oven-sh/bun#12917](https://github.com/oven-sh/bun/issues/12917) for current upstream status — `bunx`'s ephemeral install path isn't covered by the `bun install` global-store fix, so the workarounds below are still the recommended path.
+
+**Recommended pattern for scripts and agents:**
+
+```bash
+# Install once globally — this is parallel-safe and emits no install chatter on subsequent runs
+bun add -g kalshi-trading-bot-cli
+
+# Then use the `kalshi` binary directly — fan out as much as you want
+parallel -j 30 'kalshi analyze {} --json > {}.json' ::: KXBTC-26APR-B95000 KXETH-… …
+```
+
+**If you must use `bunx`:**
+
+```bash
+# --silent suppresses Bun's install chatter (keeps your CLI's stdout clean)
+bunx --silent kalshi-trading-bot-cli@latest analyze KXBTC-26APR-B95000 --json
+
+# For parallel bunx, pre-warm the cache serially first to dodge the link race
+bunx --silent kalshi-trading-bot-cli@latest --version    # one-shot, populates cache
+parallel -j 30 'bunx --silent kalshi-trading-bot-cli@latest analyze {} --json' ::: KXBTC-… …
+```
+
+Keep `@latest` if you want auto-update on every invocation; drop it after the first run if you've pinned a version and want speed.
+
 ## Agent Usage
 
 Every command supports `--json` for structured output, making the bot easy to orchestrate from scripts or AI agents.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kalshi-trading-bot-cli",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "Kalshi Trading Bot CLI - AI-powered prediction market terminal.",
   "license": "MIT",
   "author": "Octagon AI, Inc.",

package/src/cli.ts

@@ -371,6 +371,7 @@ export async function runCli(options?: { forceSetup?: boolean }) {
       { value: 'cancel', label: 'cancel', description: 'Cancel an order' },
       { value: 'backtest', label: 'backtest', description: 'Model accuracy & edge scanner' },
       { value: 'help', label: 'help', description: 'Show help' },
+      { value: 'scripting', label: 'scripting', description: 'Tips for agents, pipelines, parallel use' },
       { value: 'setup', label: 'setup', description: 'Re-run setup wizard' },
     ];
     if (!typed) return topics;

package/src/commands/analyze-batch.ts

@@ -0,0 +1,101 @@
+/**
+ * Batch analyze — fan out across multiple tickers in a single Octagon call.
+ *
+ * The full per-ticker `analyze` does deep work (resolve market, run risk gate,
+ * Kelly-size, etc.) and is slow because it makes a fresh Octagon call per
+ * ticker. When the user just wants a model-edge readout across N tickers,
+ * `POST /kalshi/markets/edge` returns them all in one shot — orders of
+ * magnitude faster.
+ *
+ * This is a complement to `analyze <ticker>`, not a replacement. Use it when
+ * you need:
+ *   - quick edge ladder across 5-100 tickers
+ *   - JSON output for downstream scripting
+ *   - refresh without paying per-ticker Octagon round-trips
+ */
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import { getMarketsEdge, type PerTickerEdgeRow } from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+export interface AnalyzeBatchResult {
+  run_id: string;
+  captured_at: string;
+  data: PerTickerEdgeRow[];
+  scored: number;
+  unscored: number;
+}
+
+export async function handleAnalyzeBatch(tickers: string[]): Promise<CLIResponse<AnalyzeBatchResult>> {
+  const cleaned = Array.from(new Set(
+    tickers.map((t) => t.trim().toUpperCase()).filter(Boolean),
+  ));
+  if (cleaned.length === 0) {
+    return wrapError('analyze', 'NO_TICKERS', 'analyze (batch): supply 1+ tickers');
+  }
+  if (cleaned.length > 100) {
+    return wrapError('analyze', 'TOO_MANY_TICKERS', 'analyze (batch): at most 100 tickers per call');
+  }
+  try {
+    const resp = await getMarketsEdge({ tickers: cleaned });
+    const scored = resp.data.filter((r) => r.status === 'scored').length;
+    return wrapSuccess('analyze', {
+      run_id: resp.run_id,
+      captured_at: resp.captured_at,
+      data: resp.data,
+      scored,
+      unscored: resp.data.length - scored,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('analyze', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatAnalyzeBatchHuman(data: AnalyzeBatchResult): string {
+  const lines: string[] = [];
+  lines.push(`Batch analyze — ${data.scored}/${data.data.length} scored in run ${data.run_id.slice(0, 8)} (${data.captured_at.slice(0, 16).replace('T', ' ')})`);
+  lines.push('');
+  if (data.data.length === 0) {
+    lines.push('No tickers returned.');
+    return lines.join('\n');
+  }
+  const rows: string[][] = data.data.map((r) => {
+    const status = r.status === 'scored' ? '✓' : '—';
+    const modelStr = r.model_probability == null ? '-' : `${(r.model_probability * 100).toFixed(1)}%`;
+    const marketStr = r.market_probability == null ? '-' : `${(r.market_probability * 100).toFixed(1)}%`;
+    const edgeStr = r.edge_pp == null ? '-' : `${r.edge_pp > 0 ? '+' : ''}${r.edge_pp.toFixed(1)}pp`;
+    const erStr = r.expected_return == null ? '-' : `${(r.expected_return * 100).toFixed(1)}%`;
+    return [
+      r.input_ticker,
+      status,
+      truncate(r.title ?? '', 32),
+      r.series_category ?? '-',
+      modelStr,
+      marketStr,
+      edgeStr,
+      erStr,
+      fmtVol(r.total_volume),
+    ];
+  });
+  lines.push(formatTable(
+    ['Ticker', '?', 'Title', 'Category', 'Model', 'Market', 'Edge', 'Exp Ret', 'Volume'],
+    rows,
+  ));
+  if (data.unscored > 0) {
+    lines.push('');
+    lines.push(`${data.unscored} ticker(s) not scored in this Octagon run — try \`kalshi analyze <ticker> --refresh\` for a one-off deep call.`);
+  }
+  return lines.join('\n');
+}

package/src/commands/analyze.ts

@@ -25,7 +25,16 @@ export interface AnalyzeData {
   eventTicker: string;
   title: string;
   expirationTime: string | null;
-  modelLastUpdated: string | null;
+  /** Local timestamp when we last pulled the report from Octagon. */
+  refreshedAt: string | null;
+  /** Upstream Octagon model-run timestamp (Octagon's `analysis_last_updated`). */
+  modelRunAt: string | null;
+  /**
+   * True when --refresh just ran but the upstream `analysis_last_updated`
+   * is unchanged from before the refresh. Tells the user we bumped the
+   * cache time but didn't get a newer underlying report from Octagon.
+   */
+  staleUpstream: boolean;
   modelProb: number;
   marketProb: number;
   edge: number;
@@ -40,6 +49,12 @@ export interface AnalyzeData {
   riskGate: RiskGateResult;
   liquidityGrade: string;
   fromCache: boolean;
+  /**
+   * True when Octagon has no model scoring for this market in the cached report.
+   * When true, model probability + edge fields should be rendered as "--",
+   * not as the 0.5 placeholder.
+   */
+  hasModel: boolean;
   reportAge: string | null;
   reportId: string;
   rawReport: string;
@@ -162,6 +177,15 @@ export async function handleAnalyze(
   const octagonClient = new OctagonClient(invoker, db, auditTrail);
   const edgeComputer = new EdgeComputer(db, auditTrail);
 
+  // Capture the upstream Octagon `analysis_last_updated` BEFORE the refresh
+  // so we can detect when --refresh re-fetches the same stale upstream
+  // report (cache fetch time bumped, but Octagon's underlying model run
+  // didn't move). This catches "stale upstream" cases where the user thinks
+  // they got fresh analysis but actually got the same body Octagon last
+  // generated weeks ago.
+  const preRefreshReport = refresh ? getLatestReport(db, resolvedTicker) : null;
+  const preRefreshAnalysis = preRefreshReport?.analysis_last_updated ?? null;
+
   // Use cache by default; only refresh when explicitly requested
   // Try prefetch first to avoid an individual Octagon API call
   let variant: 'cache' | 'refresh' = refresh ? 'refresh' : 'cache';
@@ -302,17 +326,42 @@ export async function handleAnalyze(
     risk_gate: gate.passed ? 'PASSED' : 'FAILED',
   });
 
-  // Model last-updated timestamp
-  const modelUpdatedAt = latestDbReport
+  // Two distinct timestamps:
+  //   refreshedAt = our local fetched_at (when WE pulled this from Octagon).
+  //                 This is the "Refreshed" date — what bumps when --refresh runs.
+  //   modelRunAt  = Octagon's analysis_last_updated (when their model last
+  //                 scored this event). Independent of our cache.
+  const refreshedAt = latestDbReport
     ? new Date(latestDbReport.fetched_at * 1000).toISOString().replace('T', ' ').slice(0, 16) + ' UTC'
     : null;
+  const modelRunAt = latestDbReport?.analysis_last_updated
+    ? latestDbReport.analysis_last_updated.replace('T', ' ').slice(0, 16) + ' UTC'
+    : null;
+
+  // hasModel = Octagon returned a real probability for this market. A
+  // cache-miss report keeps modelProb at the 0.5 placeholder; we must NOT
+  // render that as if it were a real prediction.
+  const hasModel = !report.cacheMiss && Number.isFinite(snapshot.modelProb)
+    && !(snapshot.modelProb === 0.5 && report.drivers.length === 0 && report.catalysts.length === 0);
+
+  // staleUpstream = user asked for --refresh but Octagon's upstream model run
+  // timestamp didn't move. Cache fetch time bumped, but the underlying report
+  // body is the same one Octagon previously generated. The user wanted fresh
+  // analysis; they got an unchanged stale one.
+  const staleUpstream = refresh
+    && preRefreshAnalysis != null
+    && latestDbReport?.analysis_last_updated != null
+    && preRefreshAnalysis === latestDbReport.analysis_last_updated;
 
   return {
     ticker: resolvedTicker,
     eventTicker,
     title: market.title || market.subtitle || resolvedTicker,
     expirationTime: market.expiration_time || market.expected_expiration_time || market.close_time || null,
-    modelLastUpdated: modelUpdatedAt,
+    refreshedAt,
+    modelRunAt,
+    staleUpstream,
+    hasModel,
     modelProb: snapshot.modelProb,
     marketProb,
     edge: snapshot.edge,
@@ -355,12 +404,23 @@ export function formatAnalyzeHuman(data: AnalyzeData): string {
   }
   lines.push('');
 
-  // Edge & Probabilities
-  lines.push(`  Model Prob:  ${(data.modelProb * 100).toFixed(1)}%`);
-  lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
-  lines.push(`  Edge:        ${data.edgePp} (${(data.edge * 100).toFixed(1)}%)`);
-  lines.push(`  Confidence:  ${data.confidence}`);
-  lines.push(`  Mispricing:  ${data.mispricingSignal}`);
+  // Edge & Probabilities.
+  // When Octagon has no model scoring for this market (hasModel=false), render
+  // the model/edge fields as "--" instead of the 0.5 placeholder — otherwise
+  // downstream consumers (bots, dashboards) think we have a 50/50 prediction.
+  if (data.hasModel) {
+    lines.push(`  Model Prob:  ${(data.modelProb * 100).toFixed(1)}%`);
+    lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
+    lines.push(`  Edge:        ${data.edgePp} (${(data.edge * 100).toFixed(1)}%)`);
+    lines.push(`  Confidence:  ${data.confidence}`);
+    lines.push(`  Mispricing:  ${data.mispricingSignal}`);
+  } else {
+    lines.push(`  Model Prob:  --   (no Octagon model coverage for this market)`);
+    lines.push(`  Market Prob: ${(data.marketProb * 100).toFixed(1)}%`);
+    lines.push(`  Edge:        --`);
+    lines.push(`  Confidence:  --`);
+    lines.push(`  Mispricing:  --`);
+  }
   lines.push('');
 
   // Price Drivers
@@ -428,15 +488,37 @@ export function formatAnalyzeHuman(data: AnalyzeData): string {
     }
   }
 
-  // Cache status & model timestamp
+  // Two distinct timestamps — labeled with the wording users actually use:
+  //
+  //   Cache refreshed at    = when the bot last fetched/re-read the Octagon
+  //                           payload. This is what bumps on --refresh.
+  //   Report body updated at = the upstream Octagon `analysis_last_updated`
+  //                            (matches the "Updated: …" date embedded in the
+  //                            report body text). Doesn't change unless
+  //                            Octagon re-runs their analysis upstream.
+  //
+  // If you're a bot/agent reading this output: use **Report body updated at**
+  // to decide whether the underlying analysis is fresh. The Cache refreshed
+  // at time only tells you when we last re-pulled the same body — it can be
+  // recent while the report itself is weeks old.
   lines.push('');
-  if (data.modelLastUpdated) {
-    lines.push(`  Model Updated: ${data.modelLastUpdated}`);
+  if (data.refreshedAt) {
+    const ageSuffix = data.reportAge ? ` (${data.reportAge})` : '';
+    lines.push(`  Cache refreshed at:    ${data.refreshedAt}${ageSuffix}`);
+    lines.push(`                         ↳ when the bot last fetched the Octagon payload; bumps on --refresh`);
+  }
+  if (data.modelRunAt) {
+    lines.push(`  Report body updated at: ${data.modelRunAt}`);
+    lines.push(`                         ↳ when Octagon last ran the model upstream (the "Updated:" date inside the report)`);
+  }
+  if (data.staleUpstream) {
+    lines.push('');
+    lines.push(`  ⚠ --refresh pulled the same Octagon report body. The cache fetch time bumped,`);
+    lines.push(`    but Octagon's upstream analysis hasn't been re-run since ${data.modelRunAt ?? 'an earlier date'}.`);
+    lines.push(`    Treat this as a stale upstream report — no newer analysis is available.`);
   }
-  if (data.fromCache && data.reportAge) {
-    lines.push(`  Data: cached (${data.reportAge}). Run \`analyze ${data.ticker} --refresh\` for latest (costs 3 credits).`);
-  } else if (data.fromCache) {
-    lines.push(`  Data: cached. Run \`analyze ${data.ticker} --refresh\` for latest (costs 3 credits).`);
+  if (data.fromCache) {
+    lines.push(`  Data: cached. Run \`analyze ${data.ticker} --refresh\` for the latest report (costs 3 credits).`);
   } else {
     lines.push('  Data: freshly generated.');
   }

package/src/commands/basket.ts

@@ -32,6 +32,15 @@ function fmtPct(v: number): string {
   return `${(v * 100).toFixed(1)}%`;
 }
 
+/**
+ * Render a possibly-null numeric value to a fixed-decimal string with an
+ * optional prefix/suffix. Returns "--" for null/undefined or non-finite
+ * (NaN/Infinity) values so we never render "NaNpp" or "Infinity%".
+ */
+function num(v: number | null | undefined, decimals: number, prefix = '', suffix = ''): string {
+  return v == null || !Number.isFinite(v) ? '--' : `${prefix}${v.toFixed(decimals)}${suffix}`;
+}
+
 function parseProbabilities(raw: string | undefined): Record<string, number> | undefined {
   if (!raw) return undefined;
   const map: Record<string, number> = {};
@@ -208,8 +217,6 @@ export function formatBasketBuildHuman(data: BasketBuildResponse): string {
   if (data.legs.length === 0) {
     lines.push('No legs selected.');
   } else {
-    const num = (v: number | null | undefined, decimals: number, prefix = '', suffix = '') =>
-      v == null ? '-' : `${prefix}${v.toFixed(decimals)}${suffix}`;
     const rows: string[][] = data.legs.map((l) => [
       l.market_ticker,
       truncate(l.title, 35),
@@ -430,12 +437,12 @@ export function formatBasketSizeHuman(data: BasketSizeResponse): string {
   const rows: string[][] = data.legs.map((l) => [
     l.market_ticker,
     l.side.toUpperCase(),
-    l.price.toFixed(2),
-    `${(l.model_probability * 100).toFixed(1)}%`,
-    `${l.edge_pp >= 0 ? '+' : ''}${l.edge_pp.toFixed(1)}pp`,
-    l.kelly_fraction.toFixed(3),
-    l.weight.toFixed(3),
-    `$${l.notional_usd.toFixed(2)}`,
+    num(l.price, 2),
+    num(l.model_probability != null ? l.model_probability * 100 : null, 1, '', '%'),
+    !Number.isFinite(l.edge_pp as number) ? '--' : `${(l.edge_pp as number) > 0 ? '+' : ''}${(l.edge_pp as number).toFixed(1)}pp`,
+    num(l.kelly_fraction, 3),
+    num(l.weight, 3),
+    num(l.notional_usd, 2, '$'),
   ]);
   lines.push(formatTable(['Ticker', 'Side', 'Price', 'Model%', 'Edge', 'Kelly', 'Weight', 'Notional'], rows));
   return lines.join('\n');

package/src/commands/dispatch.ts

@@ -91,9 +91,56 @@ function modeFlagsFor(canonical: Subcommand, args: ParsedArgs): Record<string, s
   }
 }
 
+/**
+ * One-time stderr hint when a user pipes `--json` through `bunx` without
+ * `--silent`. Bunx prints install chatter to stdout *before* our process even
+ * starts, which corrupts JSON pipelines — `--silent` fixes it entirely, but
+ * users rarely discover that flag on their own. We can't strip the chatter
+ * (it's not in our stdout), but we can nudge them once.
+ *
+ * Heuristic: --json + non-TTY stdout + BUN_INSTALL_CACHE_DIR set (bunx sets
+ * this; `bun add -g` installs don't). Silenced after first emit by touching
+ * a sentinel file under ~/.kalshi-bot/.
+ */
+async function maybeEmitBunxHint(args: ParsedArgs): Promise<void> {
+  if (!args.json) return;
+  if (process.stdout.isTTY) return;
+  if (!process.env.BUN_INSTALL_CACHE_DIR) return;
+  try {
+    // Dynamic ESM imports to avoid pulling these into the module graph at init.
+    const { appPath } = await import('../utils/paths.js');
+    const { existsSync, writeFileSync, mkdirSync } = await import('fs');
+    const sentinel = appPath('.bunx-hint-shown');
+    if (existsSync(sentinel)) return;
+    process.stderr.write(
+      '[kalshi] Tip: for clean JSON output and parallel-safe scripting, install once with\n' +
+      '[kalshi]   bun add -g kalshi-trading-bot-cli\n' +
+      '[kalshi] then call `kalshi …` directly. Or use `bunx --silent` to suppress install\n' +
+      '[kalshi] chatter from this invocation. See README → Scripting & Parallel Use.\n',
+    );
+    const dir = appPath('.');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(sentinel, String(Date.now()));
+  } catch {
+    // Best-effort hint — never fail the actual command because of it.
+  }
+}
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+
 export async function dispatch(args: ParsedArgs): Promise<void> {
+  // --days-to-close N is ergonomic sugar over --close-before <iso>. Resolve
+  // it once here so every downstream command (search, events, series,
+  // catalysts, basket --theme, similar) gets the same filter without each
+  // handler reimplementing the arithmetic.
+  if (args.daysToClose !== undefined && !args.closeBefore) {
+    const target = new Date(Date.now() + args.daysToClose * MILLISECONDS_PER_DAY);
+    args.closeBefore = target.toISOString();
+  }
+
   const { subcommand, json } = args;
   const resolved = resolveAlias(subcommand, args.positionalArgs);
+  await maybeEmitBunxHint(args);
   trackEvent('cli_command', {
     command: resolved.canonical,
     subview: resolved.subview ?? '',
@@ -307,6 +354,27 @@ export async function dispatch(args: ParsedArgs): Promise<void> {
 
     // ─── analyze ───────────────────────────────────────────────────────
     if (resolved.canonical === 'analyze') {
+      // Batch mode: 2+ positional tickers OR --tickers csv. Routes through
+      // POST /kalshi/markets/edge in a single call (vs. N serial Octagon
+      // round-trips). Use --refresh on a single ticker for the full deep
+      // analysis pipeline.
+      const csvTickers = args.tickers
+        ? args.tickers.split(',').map((s) => s.trim()).filter(Boolean)
+        : [];
+      const tickerList = [...args.positionalArgs, ...csvTickers];
+      if (tickerList.length > 1) {
+        const { handleAnalyzeBatch, formatAnalyzeBatchHuman } = await import('./analyze-batch.js');
+        const resp = await handleAnalyzeBatch(tickerList);
+        if (json) {
+          console.log(JSON.stringify(resp));
+        } else if (resp.ok) {
+          console.log(formatAnalyzeBatchHuman(resp.data));
+        } else {
+          console.error(resp.error?.message ?? 'analyze (batch) failed');
+        }
+        process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+        return;
+      }
       const ticker = args.positionalArgs[0];
       if (!ticker) {
         const errResp = wrapError('analyze', 'MISSING_TICKER', 'Usage: analyze <ticker> [--refresh] [--report]');

package/src/commands/help.ts

@@ -24,9 +24,10 @@ Search flags (server-side path):
   --category <name>     Filter by category
   --series <ticker>     Filter to a series
   --min-volume <n>      Floor on 24h volume
-  --close-before <iso>  Only markets closing before
+  --close-before <iso>  Only markets closing before this timestamp
+  --days-to-close <n>   Shortcut: only markets closing in the next N days
   --limit <n>           Page size (default 30)
-  --sort-by <key>       volume_24h | close_time | last_price (client-side sort)
+  --sort-by <key>       volume_24h | close_time | last_price (server-side sort)
   --aggregate-by series Roll up results by series (calls series rollup)
   --active-only         Drop non-active markets (defensive; the live universe is active by default)
 
@@ -51,12 +52,22 @@ Flags:
 
     analyze: `**${p}analyze** — Deep market analysis
 
-${p}analyze <ticker>             Full analysis: edge, drivers, catalysts, Kelly sizing
-${p}analyze <ticker> ${ctx === 'cli' ? '--' : ''}refresh     Force fresh Octagon report
-${ctx === 'cli' ? `
+${p}analyze <ticker>                       Full analysis: edge, drivers, catalysts, Kelly sizing
+${p}analyze <ticker> ${ctx === 'cli' ? '--' : ''}refresh             Force fresh Octagon report
+
+Batch mode (one Octagon round-trip instead of N):
+${p}analyze KX-A KX-B KX-C                 Edge readout across 2-100 tickers
+${p}analyze --tickers KX-A,KX-B,KX-C       Same, comma-separated
+${p}analyze KX-A KX-B KX-C --json          For pipelines / scripting
+
+The batch mode hits POST /kalshi/markets/edge in one call and returns
+model_probability, market_probability, edge_pp, expected_return per ticker.
+Use single-ticker mode when you need the full deep-analysis pipeline
+(drivers, catalysts, Kelly sizing, risk gate).${ctx === 'cli' ? `
+
 Legacy aliases (still work):
-  ${p}edge [--ticker X]          Edge history / snapshots (default: last 24h)
-  ${p}edge --since <date>        Edges since date (e.g. 2026-03-01)` : ''}`,
+  ${p}edge [--ticker X]                    Edge history / snapshots (default: last 24h)
+  ${p}edge --since <date>                  Edges since date (e.g. 2026-03-01)` : ''}`,
 
     watch: `**${p}watch** — Live monitoring
 
@@ -138,6 +149,34 @@ ${p}init                       Launch the TUI with the setup wizard open
 ${p}help                       Show all commands
 ${p}help <command>             Show detailed help for a command`,
 
+    scripting: `**Scripting & Parallel Use** — for agents, pipelines, and parallel invocations
+
+The \`bunx kalshi-trading-bot-cli@latest …\` form is convenient for one-off use
+but has two gotchas under scripting:
+
+  1. Bun's install chatter ("Resolving dependencies", "Saved lockfile") leaks
+     into stdout before our CLI runs, corrupting JSON pipelines.
+  2. Parallel \`bunx\` invocations race on the install cache and fail with
+     "Failed to link …: EEXIST" / "could not determine executable".
+     See oven-sh/bun#12917 for upstream status.
+
+**Recommended for scripts and agents:**
+
+  bun add -g kalshi-trading-bot-cli           # install once; emits no chatter on subsequent runs
+  parallel -j 30 'kalshi analyze {} --json' ::: TICKER1 TICKER2 …
+
+**If you must use bunx:**
+
+  bunx --silent kalshi-trading-bot-cli@latest analyze KX-A --json
+                ^^^^^^^^ suppresses install chatter; keeps our stdout clean
+
+For parallel bunx, pre-warm the cache serially before fanning out:
+
+  bunx --silent kalshi-trading-bot-cli@latest --version        # one-shot, warms cache
+  parallel -j 30 'bunx --silent kalshi-trading-bot-cli@latest analyze {} --json' ::: …
+
+See README → Scripting & Parallel Use for the full picture.`,
+
     similar: `**${p}similar** — Semantic market search (Octagon-powered)
 
 ${p}similar <ticker>                  Markets near this ticker by embedding distance

package/src/commands/parse-args.ts

@@ -71,6 +71,7 @@ export interface ParsedArgs {
   sides?: string;          // comma-separated yes/no per ticker for correlate
   cells: boolean;          // include_cell_detail for correlate
   autoProbs: boolean;      // basket size: auto-fetch leg probabilities via markets/edge
+  daysToClose?: number;    // ergonomic shortcut: close_before = now + N days
   parseErrors: string[];
 }
 
@@ -129,6 +130,7 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
   let sides: string | undefined;
   let cells = false;
   let autoProbs = false;
+  let daysToClose: number | undefined;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -397,6 +399,13 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
       cells = true;
     } else if (arg === '--auto-probs') {
       autoProbs = true;
+    } else if (arg === '--days-to-close' || arg === '--max-dte') {
+      const raw = argv[++i];
+      if (raw != null) {
+        const numeric = Number(raw);
+        if (Number.isFinite(numeric) && Number.isInteger(numeric) && numeric > 0) { daysToClose = numeric; }
+        else { parseErrors.push(`Invalid ${arg} value: "${raw}" (expected a positive integer)`); }
+      } else { parseErrors.push(`${arg} requires a value`); }
     } else if (arg.startsWith('--')) {
       parseErrors.push(`Unknown flag: ${arg}`);
     } else {
@@ -426,7 +435,7 @@ export function parseArgs(argv: string[] = process.argv.slice(2)): ParsedArgs {
     topK, behavioral, ranked, labelContains, closeBefore, windowDays, correlationInterval, timeframe,
     weights, bankroll, kellyMultiplier, n, maxPerCluster, maxCorrelation, minReturn, seriesTicker,
     sortBy, probabilities, tickers, query, showCluster, aggregateBy, activeOnly,
-    seriesPrefix, sides, cells, autoProbs,
+    seriesPrefix, sides, cells, autoProbs, daysToClose,
     parseErrors,
   };
 }

package/src/db/octagon-cache.ts

@@ -15,8 +15,9 @@ export interface OctagonReport {
   raw_response?: string | null;
   model_accuracy?: number | null;
   variant_used?: string | null;
-  fetched_at: number;
+  fetched_at: number;            // Unix seconds — when WE pulled this report ("Refreshed")
   expires_at: number;
+  analysis_last_updated?: string | null;  // Octagon's upstream model-run timestamp ("Model run")
 }
 
 export function insertReport(db: Database, report: OctagonReport): void {

package/src/db/schema.ts

@@ -237,6 +237,11 @@ export function migrate(db: Database): void {
   if (!reportCols.some((c) => c.name === 'close_time')) {
     db.exec(`ALTER TABLE octagon_reports ADD COLUMN close_time TEXT`);
   }
+  // Upstream model-run timestamp (Octagon `analysis_last_updated`). Distinct
+  // from `fetched_at` (when we pulled the report into our local cache).
+  if (!reportCols.some((c) => c.name === 'analysis_last_updated')) {
+    db.exec(`ALTER TABLE octagon_reports ADD COLUMN analysis_last_updated TEXT`);
+  }
 
   const historyCols = db.query(`PRAGMA table_info(octagon_history)`).all() as Array<{ name: string }>;
   if (!historyCols.some((c) => c.name === 'outcome_probabilities_json')) {

package/src/scan/octagon-kalshi-api.ts

@@ -189,12 +189,12 @@ export interface BasketBacktestResponse extends BasketCandlesResponse {
 export interface BasketSizeLeg {
   market_ticker: string;
   side: 'yes' | 'no';
-  model_probability: number;
-  price: number;
-  edge_pp: number;
-  kelly_fraction: number;
-  weight: number;
-  notional_usd: number;
+  model_probability: number | null;
+  price: number | null;
+  edge_pp: number | null;
+  kelly_fraction: number | null;
+  weight: number | null;
+  notional_usd: number | null;
 }
 
 export interface BasketSizeResponse {

package/src/scan/octagon-prefetch.ts

@@ -49,7 +49,7 @@ function classifyConfidence(absEdge: number): string {
  * Convert an Octagon event entry to local DB records and persist.
  * Returns true if a new record was inserted, false if skipped.
  */
-function persistEvent(db: Database, event: OctagonEventEntry): boolean {
+export function persistEvent(db: Database, event: OctagonEventEntry): boolean {
   const capturedDate = new Date(event.captured_at);
   const closeDate = new Date(event.close_time);
   if (isNaN(capturedDate.getTime()) || isNaN(closeDate.getTime())) return false;
@@ -102,7 +102,8 @@ function persistEvent(db: Database, event: OctagonEventEntry): boolean {
 
     db.prepare(
       `UPDATE octagon_reports SET has_history = $hh, mutually_exclusive = $me, series_category = $sc,
-         confidence_score = $cs, outcome_probabilities_json = $opj, close_time = $ct
+         confidence_score = $cs, outcome_probabilities_json = $opj, close_time = $ct,
+         analysis_last_updated = $alu
        WHERE report_id = $rid`,
     ).run({
       $rid: reportId,
@@ -112,34 +113,54 @@ function persistEvent(db: Database, event: OctagonEventEntry): boolean {
       $cs: event.confidence_score ?? null,
       $opj: event.outcome_probabilities ? JSON.stringify(event.outcome_probabilities) : null,
       $ct: event.close_time ?? null,
+      $alu: event.analysis_last_updated ?? null,
     });
   })();
 
-  // Also persist to edge_history
-  const edge = modelProb - marketProb;
-  try {
-    insertEdge(db, {
-      ticker: event.event_ticker,
-      event_ticker: event.event_ticker,
-      timestamp: capturedAt,
-      model_prob: modelProb,
-      market_prob: marketProb,
-      edge,
-      octagon_report_id: reportId,
-      drivers_json: null,
-      sources_json: null,
-      catalysts_json: null,
-      cache_hit: 1,
-      cache_miss: 0,
-      confidence: classifyConfidence(Math.abs(edge)),
-    });
-  } catch (err) {
-    // Only swallow UNIQUE constraint violations (duplicate ticker+timestamp)
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/UNIQUE constraint failed/i.test(msg)) {
-      // Expected — edge already exists for this ticker+timestamp
-    } else {
-      throw err;
+  // Also persist to edge_history. Two cases:
+  //   - Multi-outcome events (e.g. KXFEDCHAIRNOM-29) ship outcome_probabilities
+  //     with per-market model/market probs. Write one edge_history row per
+  //     outcome with the correct ticker — otherwise downstream consumers see
+  //     the event-level placeholder (typically ~0.5) on every contract.
+  //   - Single-outcome / no-outcome events: fall back to event-level probs on
+  //     a single row keyed by the event ticker, as before.
+  const outcomes = Array.isArray(event.outcome_probabilities) ? event.outcome_probabilities : [];
+  const perOutcomeRows = outcomes.length > 0
+    ? outcomes
+        .filter((o) => o && o.market_ticker && typeof o.model_probability === 'number' && typeof o.market_probability === 'number')
+        .map((o) => ({
+          ticker: o.market_ticker,
+          model_prob: o.model_probability / 100,
+          market_prob: o.market_probability / 100,
+        }))
+    : [{ ticker: event.event_ticker, model_prob: modelProb, market_prob: marketProb }];
+
+  for (const row of perOutcomeRows) {
+    const rowEdge = row.model_prob - row.market_prob;
+    try {
+      insertEdge(db, {
+        ticker: row.ticker,
+        event_ticker: event.event_ticker,
+        timestamp: capturedAt,
+        model_prob: row.model_prob,
+        market_prob: row.market_prob,
+        edge: rowEdge,
+        octagon_report_id: reportId,
+        drivers_json: null,
+        sources_json: null,
+        catalysts_json: null,
+        cache_hit: 1,
+        cache_miss: 0,
+        confidence: classifyConfidence(Math.abs(rowEdge)),
+      });
+    } catch (err) {
+      // Only swallow UNIQUE constraint violations (duplicate ticker+timestamp)
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/UNIQUE constraint failed/i.test(msg)) {
+        // Expected — edge already exists for this ticker+timestamp
+      } else {
+        throw err;
+      }
     }
   }