pandora-cli-skills 1.1.37 → 1.1.39

package/README.md

@@ -49,6 +49,20 @@ pandora --output json trade --dry-run \
 pandora stream prices --indexer-url https://pandoraindexer.up.railway.app/ --interval-ms 1000
 ```
 
+### Sports Quickstart
+
+```bash
+# list upcoming soccer events
+pandora --output json sports events list --competition <id-or-slug> --limit 5
+
+# compute trimmed-median consensus for one event
+pandora --output json sports consensus --event-id <event-id> --trim-percent 20
+
+# build conservative create + resolve plans
+pandora --output json sports create plan --event-id <event-id> --selection home
+pandora --output json sports resolve plan --event-id <event-id> --poll-address <0x...>
+```
+
 ## Fork Mode Notes
 
 - Runtime marker is included in payloads: `data.runtime.mode = "fork" | "live"`.

package/README_FOR_SHARING.md

@@ -51,6 +51,16 @@ Prerequisite: Node.js `>=18`.
    - `npm run dry-run:clone`
    - `node cli/pandora.cjs help`
 
+## Quickstart (Sports)
+- List soccer events:
+  - `pandora --output json sports events list --competition <id-or-slug> --limit 5`
+- Compute sportsbook consensus:
+  - `pandora --output json sports consensus --event-id <event-id> --trim-percent 20`
+- Build creation plan:
+  - `pandora --output json sports create plan --event-id <event-id> --selection home`
+- Build manual resolve recommendation:
+  - `pandora --output json sports resolve plan --event-id <event-id> --poll-address <0x...>`
+
 ## New CLI capabilities
 - Global machine-readable output:
   - `pandora --output json doctor`

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.36
+version: 1.1.39
 ---
 
 # Pandora CLI & Skills
@@ -83,6 +83,7 @@ pandora [--output table|json] doctor [--dotenv-path <path>] [--skip-dotenv] [--c
 pandora [--output table|json] setup [--force] [--dotenv-path <path>] [--example <path>] [--check-usdc-code] [--check-polymarket] [--rpc-timeout-ms <ms>]
 pandora [--output table|json] markets list [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--poll-address <address>] [--market-type <type>] [--where-json <json>] [--active|--resolved|--expiring-soon] [--expiring-hours <n>] [--expand] [--with-odds]
 pandora [--output table|json] markets get [--id <id> ...] [--stdin]
+pandora [--output table|json] sports books list|events list|events live|odds snapshot|consensus|create plan|create run|sync once|sync run|sync start|sync stop|sync status|resolve plan [flags]
 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>]
 pandora [--output table|json] polls get --id <id>
 pandora [--output table|json] events list [--type all|liquidity|oracle-fee|claim] [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-direction asc|desc] [--chain-id <id>] [--wallet <address>] [--market-address <address>] [--poll-address <address>] [--tx-hash <hash>]
@@ -144,6 +145,81 @@ preflight [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url
 trade --condition-id <id>|--slug <slug>|--token-id <id> --token yes|no --amount-usdc <n> --dry-run|--execute [--side buy|sell] [--polymarket-host <url>] [--polymarket-mock-url <url>] [--timeout-ms <ms>] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>]
 ```
 
+## Sports command matrix
+| Command | Purpose | Primary flags |
+| --- | --- | --- |
+| `sports books list` | Show sportsbook provider health and active book preference list. | `--provider`, `--book-priority`, `--timeout-ms` |
+| `sports events list` | List normalized soccer events. | `--competition`, `--kickoff-after`, `--kickoff-before`, `--limit` |
+| `sports events live` | List only live/in-play events. | `--competition`, `--limit`, `--provider` |
+| `sports odds snapshot` | Fetch event odds snapshot plus consensus context. | `--event-id`, `--trim-percent`, `--min-tier1-books`, `--min-total-books` |
+| `sports consensus` | Compute trimmed-median consensus from live or offline checks. | `--event-id` or `--checks-json`, `--trim-percent`, `--book-priority` |
+| `sports create plan` | Build conservative creation plan and safety gates. | `--event-id`, `--selection`, `--market-type`, `--creation-window-open-min`, `--creation-window-close-min` |
+| `sports create run` | Dry-run or execute creation path. | `--event-id`, `--dry-run/--execute`, `--liquidity-usdc`, `--chain-id`, `--rpc-url` |
+| `sports sync once|run|start|stop|status` | Evaluate and operate sports sync runtime state. | `--event-id` (required for `once|run|start`), `--risk-profile`, `--state-file`, `--paper/--execute-live` |
+| `sports resolve plan` | Build manual-final resolution recommendation. | `--event-id` or `--checks-json/--checks-file`, `--poll-address`, `--settle-delay-ms`, `--consecutive-checks-required` |
+
+## Sports consensus policy
+- Odds are normalized to implied probability from decimal/American/fractional inputs.
+- Consensus method is `trimmed-median` (v1), with default `--trim-percent 20`.
+- Conservative coverage inputs default to `--min-tier1-books 3` and `--min-total-books 6`.
+- Confidence can degrade when coverage policy is not satisfied.
+- Consensus payload includes:
+  - `method`
+  - `tier1Coverage`
+  - `totalBooks`
+  - `includedBooks`
+  - `excludedBooks`
+  - `outliers`
+  - `consensusYesPct`
+  - `consensusNoPct`
+
+## Sports timing policy
+- Creation planning defaults:
+  - `--creation-window-open-min 1440` (24h before kickoff)
+  - `--creation-window-close-min 90` (90m before kickoff)
+- Core timing module defaults (spec-level fallbacks):
+  - creation open lead `7d`, creation close lead `15m`
+  - assumed event duration `3h`
+  - resolve open delay `30m`, resolve target delay `2h`, resolve close delay `48h`
+- Resolve plan safety defaults:
+  - `--settle-delay-ms 600000` (10m)
+  - `--consecutive-checks-required 2`
+
+## Manual resolve workflow (sports)
+1. Build resolve plan:
+   - `pandora --output json sports resolve plan --event-id <id> --poll-address <0x...>`
+2. Confirm plan safety:
+   - require `safeToResolve=true`
+   - read `recommendedAnswer`, `stableWindowStartAt`, and diagnostics
+3. Execute resolution:
+   - run `recommendedCommand` when present
+   - or run manual command: `pandora resolve --poll-address <0x...> --answer yes|no|invalid --reason "<text>" --execute`
+4. If unsafe:
+   - continue collecting checks (`--checks-json`/`--checks-file`) and rerun until safety gates pass.
+
+## Sports sync risk defaults
+- Conservative (`--risk-profile conservative`):
+  - `maxDataAgeMs=120000`
+  - `minCoverageRatio=0.70`
+  - `maxCoverageDropRatio=0.25`
+  - `maxSpreadJumpBps=150`
+  - `maxConsecutiveFailures=3`
+  - `maxConsecutiveGateFailures=2`
+- Balanced:
+  - `maxDataAgeMs=150000`
+  - `minCoverageRatio=0.60`
+  - `maxCoverageDropRatio=0.30`
+  - `maxSpreadJumpBps=200`
+  - `maxConsecutiveFailures=4`
+  - `maxConsecutiveGateFailures=3`
+- Aggressive:
+  - `maxDataAgeMs=180000`
+  - `minCoverageRatio=0.50`
+  - `maxCoverageDropRatio=0.40`
+  - `maxSpreadJumpBps=250`
+  - `maxConsecutiveFailures=5`
+  - `maxConsecutiveGateFailures=4`
+
 ## Read-only indexer commands
 Indexer URL resolution order:
 1. `--indexer-url`

package/cli/lib/command_executor_service.cjs

@@ -1,6 +1,11 @@
 const path = require('path');
 const { spawnSync } = require('child_process');
 
+/**
+ * Normalize unknown error-ish values into a loggable message string.
+ * @param {*} value
+ * @returns {string}
+ */
 function coerceErrorMessage(value) {
   if (typeof value === 'string') return value;
   if (value && typeof value.message === 'string') return value.message;
@@ -11,6 +16,12 @@ function coerceErrorMessage(value) {
   }
 }
 
+/**
+ * Parse a candidate JSON envelope from raw process output.
+ * Accepts only objects that include a boolean `ok` field.
+ * @param {string} text
+ * @returns {object|null}
+ */
 function parseEnvelopeCandidate(text) {
   const candidate = String(text || '').trim();
   if (!candidate) return null;
@@ -25,6 +36,12 @@ function parseEnvelopeCandidate(text) {
   return null;
 }
 
+/**
+ * Extract the last syntactically valid top-level JSON object from text.
+ * Useful when diagnostics/noise precede the structured CLI envelope.
+ * @param {string} text
+ * @returns {object|null}
+ */
 function extractLastJsonObject(text) {
   const source = String(text || '');
   if (!source) return null;
@@ -70,6 +87,12 @@ function extractLastJsonObject(text) {
   return parseEnvelopeCandidate(last);
 }
 
+/**
+ * Parse a CLI JSON envelope from stdout/stderr with robust fallbacks.
+ * @param {string} stdout
+ * @param {string} stderr
+ * @returns {object|null}
+ */
 function parseEnvelopeFromOutput(stdout, stderr) {
   const candidates = [stdout, stderr, `${stdout || ''}\n${stderr || ''}`];
   for (const candidate of candidates) {
@@ -81,10 +104,31 @@ function parseEnvelopeFromOutput(stdout, stderr) {
   return null;
 }
 
+/**
+ * @typedef {object} ExecutorEnvelope
+ * @property {boolean} ok
+ * @property {string} [command]
+ * @property {object} [data]
+ * @property {{code: string, message: string, details?: object}} [error]
+ */
+
+/**
+ * @typedef {object} ExecuteJsonCommandResult
+ * @property {boolean} ok
+ * @property {number} exitCode
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {ExecutorEnvelope} envelope
+ */
+
 /**
  * Build a child-process command executor for JSON-mode CLI invocations.
+ * The executor always prepends `--output json` and normalizes failures into an envelope shape.
  * @param {{cliPath?: string, defaultTimeoutMs?: number, env?: object}} [options]
- * @returns {{executeJsonCommand: (commandArgs: string[], runtime?: {timeoutMs?: number, env?: object}) => {ok: boolean, envelope: object, exitCode: number, stdout: string, stderr: string}}}
+ * @returns {{
+ *   executeJsonCommand: (commandArgs: string[], runtime?: {timeoutMs?: number, env?: object}) => ExecuteJsonCommandResult,
+ *   coerceErrorMessage: (value: *) => string
+ * }}
  */
 function createCommandExecutorService(options = {}) {
   const cliPath =
@@ -94,6 +138,12 @@ function createCommandExecutorService(options = {}) {
   const defaultTimeoutMs = Number.isFinite(options.defaultTimeoutMs) ? Math.max(1_000, Math.trunc(options.defaultTimeoutMs)) : 60_000;
   const baseEnv = options.env && typeof options.env === 'object' ? options.env : process.env;
 
+  /**
+   * Execute the CLI synchronously and parse the envelope from process output.
+   * @param {string[]} commandArgs
+   * @param {{timeoutMs?: number, env?: object}} [runtime]
+   * @returns {ExecuteJsonCommandResult}
+   */
   function executeJsonCommand(commandArgs, runtime = {}) {
     const timeoutMs = Number.isFinite(runtime.timeoutMs)
       ? Math.max(1_000, Math.trunc(runtime.timeoutMs))

package/cli/lib/command_router.cjs

@@ -18,6 +18,7 @@ function createCommandRouter(deps = {}) {
     runSetup,
     runMarketsCommand,
     runScanCommand,
+    runSportsCommand,
     runQuoteCommand,
     runTradeCommand,
     runPollsCommand,
@@ -65,6 +66,7 @@ function createCommandRouter(deps = {}) {
   requireFn('runSetup', runSetup);
   requireFn('runMarketsCommand', runMarketsCommand);
   requireFn('runScanCommand', runScanCommand);
+  requireFn('runSportsCommand', runSportsCommand);
   requireFn('runQuoteCommand', runQuoteCommand);
   requireFn('runTradeCommand', runTradeCommand);
   requireFn('runPollsCommand', runPollsCommand);
@@ -153,6 +155,7 @@ function createCommandRouter(deps = {}) {
       },
       markets: async (handlerArgs, handlerContext) => runMarketsCommand(handlerArgs, handlerContext),
       scan: async (handlerArgs, handlerContext) => runScanCommand(handlerArgs, handlerContext),
+      sports: async (handlerArgs, handlerContext) => runSportsCommand(handlerArgs, handlerContext),
       quote: async (handlerArgs, handlerContext) => runQuoteCommand(handlerArgs, handlerContext),
       trade: async (handlerArgs, handlerContext) => runTradeCommand(handlerArgs, handlerContext),
       polls: async (handlerArgs, handlerContext) => runPollsCommand(handlerArgs, handlerContext),

package/cli/lib/error_recovery_service.cjs

@@ -51,6 +51,38 @@ function buildMcpRestartCommand(cliName) {
   return `${cliName} mcp`;
 }
 
+function buildMcpBoundedCommand(cliName, details) {
+  const toolName = cleanToken(details && details.toolName, '');
+  if (toolName.startsWith('sports.sync.')) {
+    return `${cliName} sports sync once --help`;
+  }
+  if (toolName.startsWith('mirror.sync.')) {
+    return `${cliName} mirror sync once --help`;
+  }
+  if (toolName.startsWith('autopilot.')) {
+    return `${cliName} autopilot once --help`;
+  }
+  if (toolName.startsWith('watch')) {
+    return `${cliName} watch --help`;
+  }
+  return `${cliName} help`;
+}
+
+function buildSportsConsensusRetryCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports consensus --event-id ${eventId}`;
+}
+
+function buildSportsCreatePlanCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports create plan --event-id ${eventId}`;
+}
+
+function buildSportsResolvePlanRetryCommand(cliName, details) {
+  const eventId = cleanToken(details && details.eventId, '<event-id>');
+  return `${cliName} sports resolve plan --event-id ${eventId}`;
+}
+
 /**
  * Build deterministic Next-Best-Action recovery hints for JSON errors.
  * @param {{cliName?: string}} [options]
@@ -124,7 +156,7 @@ function createErrorRecoveryService(options = {}) {
       case 'MCP_LONG_RUNNING_MODE_BLOCKED':
         return {
           action: 'Switch to a bounded command variant for MCP',
-          command: `${cliName} mirror sync once --help`,
+          command: buildMcpBoundedCommand(cliName, details),
           retryable: true,
         };
       case 'MCP_TOOL_FAILED':
@@ -134,6 +166,46 @@ function createErrorRecoveryService(options = {}) {
           command: `${cliName} --output json schema`,
           retryable: true,
         };
+      case 'SPORTS_PROVIDER_NOT_CONFIGURED':
+      case 'SPORTS_PROVIDER_FETCH_MISSING':
+      case 'SPORTS_LIST_COMPETITIONS_FAILED':
+      case 'SPORTS_LIST_EVENTS_FAILED':
+      case 'SPORTS_GET_EVENT_ODDS_FAILED':
+      case 'SPORTS_GET_EVENT_STATUS_FAILED':
+        return {
+          action: 'Retry sportsbook query with explicit provider settings',
+          command: `${cliName} sports books list --provider auto`,
+          retryable: true,
+        };
+      case 'SPORTS_PROVIDER_TIMEOUT':
+      case 'SPORTS_PROVIDER_REQUEST_FAILED':
+      case 'SPORTS_PROVIDER_HTTP_ERROR':
+      case 'SPORTS_PROVIDER_INVALID_JSON':
+        return {
+          action: 'Retry sportsbook read path with backup provider',
+          command: `${cliName} sports events list --provider backup --limit 10`,
+          retryable: true,
+        };
+      case 'SPORTS_CONSENSUS_FAILED':
+      case 'SPORTS_CONSENSUS_UNAVAILABLE':
+        return {
+          action: 'Re-run consensus for the target event',
+          command: buildSportsConsensusRetryCommand(cliName, details),
+          retryable: true,
+        };
+      case 'SPORTS_CREATE_BLOCKED':
+      case 'SPORTS_CREATE_FAILED':
+        return {
+          action: 'Rebuild creation plan and adjust timing/coverage inputs',
+          command: buildSportsCreatePlanCommand(cliName, details),
+          retryable: true,
+        };
+      case 'SPORTS_RESOLVE_PLAN_UNSAFE':
+        return {
+          action: 'Wait for stable final status and retry resolve plan',
+          command: buildSportsResolvePlanRetryCommand(cliName, details),
+          retryable: true,
+        };
       case 'MISSING_REQUIRED_FLAG':
       case 'MISSING_FLAG_VALUE':
       case 'INVALID_FLAG_VALUE':

package/cli/lib/mcp_tool_registry.cjs

@@ -1,3 +1,38 @@
+/**
+ * @typedef {string|number|boolean|null|undefined|Array<string|number|boolean>} FlagInputValue
+ */
+
+/**
+ * @typedef {{[flagName: string]: FlagInputValue}} ToolFlags
+ */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   command: string[],
+ *   description: string,
+ *   mutating?: boolean,
+ *   safeFlags?: string[],
+ *   executeFlags?: string[],
+ *   longRunningBlocked?: boolean
+ * }} ToolDefinition
+ */
+
+/**
+ * @typedef {{
+ *   positionals?: Array<string|number|boolean>,
+ *   flags?: ToolFlags,
+ *   intent?: { execute?: boolean }
+ * }} ToolInvocationArgs
+ */
+
+/**
+ * Normalize a flag token to a CLI-prefixed name.
+ * Leaves existing `--foo`/`-f` tokens unchanged and prefixes bare names.
+ *
+ * @param {string} name Raw flag key.
+ * @returns {string} Normalized CLI flag token or empty string.
+ */
 function normalizeFlagName(name) {
   const normalized = String(name || '').trim();
   if (!normalized) return '';
@@ -6,6 +41,13 @@ function normalizeFlagName(name) {
   return `--${normalized}`;
 }
 
+/**
+ * Convert a flag value (including nested arrays) into scalar CLI values.
+ * Booleans are preserved so callers can emit bare switch flags.
+ *
+ * @param {FlagInputValue} value Flag value candidate.
+ * @returns {Array<string|boolean>} Flattened scalar values.
+ */
 function flagValueToStrings(value) {
   if (value === null || value === undefined) return [];
   if (Array.isArray(value)) {
@@ -17,6 +59,13 @@ function flagValueToStrings(value) {
   return [String(value)];
 }
 
+/**
+ * Build argv segments from a JSON-style flags map.
+ * Truthy booleans produce bare switch flags; scalar values produce pairs.
+ *
+ * @param {ToolFlags} flags Flag map where keys may be with/without `--`.
+ * @returns {string[]} CLI argv segment for flags.
+ */
 function buildFlagArgv(flags) {
   if (!flags || typeof flags !== 'object') return [];
   const argv = [];
@@ -37,6 +86,13 @@ function buildFlagArgv(flags) {
   return argv;
 }
 
+/**
+ * Collect normalized flags that are meaningfully provided by the caller.
+ * Used by execution guardrails to detect safe/live mode intent flags.
+ *
+ * @param {ToolFlags} flags Candidate flags object.
+ * @returns {Set<string>} Set of normalized provided flag names.
+ */
 function providedFlagSet(flags) {
   const set = new Set();
   if (!flags || typeof flags !== 'object' || Array.isArray(flags)) return set;
@@ -53,6 +109,12 @@ function providedFlagSet(flags) {
   return set;
 }
 
+/**
+ * Convert a tool definition to MCP descriptor format.
+ *
+ * @param {ToolDefinition} definition Tool registration definition.
+ * @returns {{name: string, description: string, inputSchema: object}} MCP tool descriptor.
+ */
 function toToolDescriptor(definition) {
   return {
     name: definition.name,
@@ -104,6 +166,7 @@ function toToolDescriptor(definition) {
   };
 }
 
+/** @type {ToolDefinition[]} */
 const TOOL_DEFINITIONS = [
   { name: 'help', command: ['help'], description: 'Show top-level command help.' },
   { name: 'version', command: ['version'], description: 'Return the installed CLI version.' },
@@ -112,6 +175,54 @@ const TOOL_DEFINITIONS = [
   { name: 'markets.list', command: ['markets', 'list'], description: 'List Pandora markets with filters.' },
   { name: 'markets.get', command: ['markets', 'get'], description: 'Get one or more markets by id.' },
   { name: 'scan', command: ['scan'], description: 'Scan markets with lifecycle filters.' },
+  { name: 'sports.books.list', command: ['sports', 'books', 'list'], description: 'List sportsbook provider health and configured book priorities.' },
+  { name: 'sports.events.list', command: ['sports', 'events', 'list'], description: 'List normalized soccer events from sportsbook providers.' },
+  { name: 'sports.events.live', command: ['sports', 'events', 'live'], description: 'List currently-live soccer events from sportsbook providers.' },
+  { name: 'sports.odds.snapshot', command: ['sports', 'odds', 'snapshot'], description: 'Get normalized event odds snapshot and consensus.' },
+  { name: 'sports.consensus', command: ['sports', 'consensus'], description: 'Compute majority-book trimmed-median consensus for one event.' },
+  { name: 'sports.create.plan', command: ['sports', 'create', 'plan'], description: 'Build conservative market creation plan from sportsbook consensus.' },
+  {
+    name: 'sports.create.run',
+    command: ['sports', 'create', 'run'],
+    description: 'Execute or dry-run sports market creation.',
+    mutating: true,
+    safeFlags: ['--dry-run', '--paper'],
+    executeFlags: ['--execute'],
+  },
+  {
+    name: 'sports.sync.once',
+    command: ['sports', 'sync', 'once'],
+    description: 'Run one sports sync evaluation tick.',
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.run',
+    command: ['sports', 'sync', 'run'],
+    description: 'Continuous sports sync loop (blocked in MCP v1).',
+    longRunningBlocked: true,
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.start',
+    command: ['sports', 'sync', 'start'],
+    description: 'Start detached sports sync runtime (blocked in MCP v1).',
+    longRunningBlocked: true,
+    mutating: true,
+    safeFlags: ['--paper', '--dry-run'],
+    executeFlags: ['--execute-live', '--execute'],
+  },
+  {
+    name: 'sports.sync.stop',
+    command: ['sports', 'sync', 'stop'],
+    description: 'Stop sports sync runtime.',
+    mutating: true,
+  },
+  { name: 'sports.sync.status', command: ['sports', 'sync', 'status'], description: 'Inspect sports sync runtime status.' },
+  { name: 'sports.resolve.plan', command: ['sports', 'resolve', 'plan'], description: 'Build manual-final resolution recommendation.' },
   { name: 'quote', command: ['quote'], description: 'Build YES/NO quote estimates.' },
   {
     name: 'trade',
@@ -276,15 +387,33 @@ const TOOL_DEFINITIONS = [
 
 /**
  * Registry for MCP-exposed Pandora tools with execution guardrails.
- * @returns {{listTools: () => object[], prepareInvocation: (toolName: string, args?: object) => {argv: string[]}, hasTool: (toolName: string) => boolean}}
+ *
+ * @returns {{
+ *   listTools: () => object[],
+ *   prepareInvocation: (toolName: string, args?: ToolInvocationArgs) => {argv: string[]},
+ *   hasTool: (toolName: string) => boolean
+ * }} MCP tool registry API.
  */
 function createMcpToolRegistry() {
   const byName = new Map(TOOL_DEFINITIONS.map((definition) => [definition.name, definition]));
 
+  /**
+   * List all MCP-exposed Pandora tools and their shared JSON contract.
+   *
+   * @returns {object[]} Tool descriptors.
+   */
   function listTools() {
     return TOOL_DEFINITIONS.map((definition) => toToolDescriptor(definition));
   }
 
+  /**
+   * Validate and convert a tool invocation request into Pandora CLI argv.
+   * Applies guardrails for unknown/blocked tools and mutating intent rules.
+   *
+   * @param {string} toolName Registered MCP tool name.
+   * @param {ToolInvocationArgs} [args={}] Invocation payload from MCP client.
+   * @returns {{argv: string[]}} Prepared command argv (without binary prefix).
+   */
   function prepareInvocation(toolName, args = {}) {
     if (toolName === 'launch' || toolName === 'clone-bet') {
       const unsupported = new Error(
@@ -310,6 +439,7 @@ function createMcpToolRegistry() {
       );
       blocked.code = 'MCP_LONG_RUNNING_MODE_BLOCKED';
       blocked.details = {
+        toolName: definition.name,
         hints: ['Use the non-long-running variant (for example, *.once) or call the CLI directly outside MCP.'],
       };
       throw blocked;