pandora-cli-skills 1.1.9 → 1.1.10

package/README_FOR_SHARING.md

@@ -35,13 +35,14 @@ Prerequisite: Node.js `>=18`.
    - `ORACLE`
    - `FACTORY`
    - `USDC`
-   - optional for live mirror hedging:
+   - optional for live mirror hedging and `mirror status --with-live` position diagnostics:
      - `POLYMARKET_PRIVATE_KEY`
-     - `POLYMARKET_FUNDER`
+     - `POLYMARKET_FUNDER` (Polymarket proxy wallet / Gnosis Safe address, not your EOA)
      - `POLYMARKET_API_KEY`
      - `POLYMARKET_API_SECRET`
      - `POLYMARKET_API_PASSPHRASE`
      - `POLYMARKET_HOST`
+   - note: live Polymarket trading settles with Polygon USDC.e collateral on the proxy wallet.
 4. Validate and build:
    - `npm run doctor`
    - `npm run build`
@@ -208,6 +209,8 @@ Prerequisite: Node.js `>=18`.
   - Polymarket resilience: when Polymarket endpoints are unreachable, cached snapshots under `~/.pandora/polymarket` are reused for read paths; live sync blocks execution if source data is cached/stale.
 - `mirror status`:
   - envelope is `ok=true`, `command="mirror.status"`, with `data.stateFile`, `data.strategyHash`, persisted `data.state`, and optional `data.live` when `--with-live` is used.
+  - `data.live` now includes additive position diagnostics: `polymarketPosition.{yesBalance,noBalance,openOrdersCount,estimatedValueUsd,diagnostics[]}` plus `netDeltaApprox` and `pnlApprox`.
+  - if Polymarket credentials/endpoints are unavailable, `--with-live` remains non-fatal and returns diagnostics with null position fields.
 - `mirror close`:
   - envelope is `ok=true`, `command="mirror.close"`, with `data.mode` and unwind `data.steps[]` scaffold.
 - `webhook test`:

package/SKILL.md

@@ -171,9 +171,13 @@ pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --inclu
 - `mirror go`: one-command orchestration for plan → deploy → verify, with optional auto-sync start.
 - `mirror sync`: paper-first delta-neutral loop with strict gates, state persistence, and optional live hedging (`--hedge-ratio <n>`, `--no-hedge`).
   - live hedge env: `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_FUNDER`, `POLYMARKET_API_KEY`, `POLYMARKET_API_SECRET`, `POLYMARKET_API_PASSPHRASE`, `POLYMARKET_HOST`.
+  - `POLYMARKET_FUNDER` must be the Polymarket proxy wallet (Gnosis Safe), not the EOA address.
+  - Polymarket trading collateral is Polygon USDC.e on the proxy wallet.
   - rebalance sizing is pool-aware and bounded by `--max-rebalance-usdc`.
   - endpoint resilience: Polymarket snapshots are cached under `~/.pandora/polymarket`; paper/read flows can reuse cache during outages, while live sync blocks cached sources.
 - `mirror status`: local mirror state inspection with optional live market diagnostics (`--with-live`).
+  - `--with-live` uses the same `POLYMARKET_*` env keys for optional position visibility (YES/NO balances, open orders count, estimated value) and adds `netDeltaApprox` / `pnlApprox`.
+  - missing credentials or unavailable position endpoints do not hard-fail status; diagnostics are returned with null position fields.
 - `mirror close`: deterministic unwind scaffold for LP withdrawal + hedge unwind flow.
 - `webhook test`: channel validation for generic, Telegram, and Discord payload delivery.
 - `leaderboard`: ranked user aggregates by profit/volume/win-rate.

package/cli/lib/mirror_daemon_service.cjs

@@ -0,0 +1,268 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+const { expandHome } = require('./mirror_state_store.cjs');
+
+const MIRROR_DAEMON_SCHEMA_VERSION = '1.0.0';
+const STOP_TIMEOUT_MS = 5_000;
+const STOP_POLL_MS = 100;
+
+function createServiceError(code, message, details = undefined) {
+  const err = new Error(message);
+  err.code = code;
+  if (details !== undefined) {
+    err.details = details;
+  }
+  return err;
+}
+
+function normalizeStrategyHash(strategyHash) {
+  const value = String(strategyHash || '').trim().toLowerCase();
+  if (!/^[a-f0-9]{16}$/.test(value)) {
+    throw createServiceError('INVALID_FLAG_VALUE', '--strategy-hash must be a 16-character hex value.');
+  }
+  return value;
+}
+
+function resolvePath(filePath) {
+  return path.resolve(expandHome(String(filePath || '').trim()));
+}
+
+function defaultPidFile(strategyHash) {
+  const hash = normalizeStrategyHash(strategyHash);
+  return path.join(os.homedir(), '.pandora', 'mirror', 'daemon', `${hash}.json`);
+}
+
+function defaultLogFile(strategyHash) {
+  const hash = normalizeStrategyHash(strategyHash);
+  return path.join(os.homedir(), '.pandora', 'mirror', 'logs', `${hash}.log`);
+}
+
+function writeJsonFile(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+  const serialized = JSON.stringify(payload, null, 2);
+  fs.writeFileSync(tmpPath, serialized);
+  fs.renameSync(tmpPath, filePath);
+}
+
+function readJsonFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw createServiceError('MIRROR_DAEMON_PIDFILE_INVALID', `Failed to parse daemon pid file at ${filePath}.`, {
+      cause: err && err.message ? err.message : String(err),
+    });
+  }
+}
+
+function isPidAlive(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) return false;
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch (err) {
+    if (err && (err.code === 'ESRCH' || err.code === 'ENOENT')) return false;
+    if (err && err.code === 'EPERM') return true;
+    throw err;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForProcessExit(pid, timeoutMs = STOP_TIMEOUT_MS) {
+  const startedAt = Date.now();
+  while (Date.now() - startedAt < timeoutMs) {
+    if (!isPidAlive(pid)) return true;
+    await sleep(STOP_POLL_MS);
+  }
+  return !isPidAlive(pid);
+}
+
+function resolvePidFile(options = {}) {
+  if (options.pidFile) {
+    return resolvePath(options.pidFile);
+  }
+  if (options.strategyHash) {
+    return defaultPidFile(options.strategyHash);
+  }
+  throw createServiceError(
+    'MISSING_REQUIRED_FLAG',
+    'mirror sync daemon lifecycle requires --pid-file <path> or --strategy-hash <hash>.',
+  );
+}
+
+function startDaemon(options = {}) {
+  const strategyHash = normalizeStrategyHash(options.strategyHash);
+  const pidFile = defaultPidFile(strategyHash);
+  const logFile = options.logFile ? resolvePath(options.logFile) : defaultLogFile(strategyHash);
+  const cliPath = options.cliPath ? resolvePath(options.cliPath) : null;
+  const cliArgs = Array.isArray(options.cliArgs) ? options.cliArgs.map((item) => String(item)) : [];
+
+  if (!cliPath) {
+    throw createServiceError('MIRROR_DAEMON_CLI_PATH_REQUIRED', 'Daemon start requires the CLI path.');
+  }
+  if (!cliArgs.length) {
+    throw createServiceError('MIRROR_DAEMON_CLI_ARGS_REQUIRED', 'Daemon start requires sync run CLI arguments.');
+  }
+
+  const existing = readJsonFile(pidFile);
+  if (existing && isPidAlive(existing.pid)) {
+    throw createServiceError('MIRROR_DAEMON_ALREADY_RUNNING', 'Mirror sync daemon is already running for this strategy.', {
+      pidFile,
+      pid: existing.pid,
+      strategyHash,
+    });
+  }
+
+  fs.mkdirSync(path.dirname(logFile), { recursive: true });
+  const logFd = fs.openSync(logFile, 'a');
+  const child = spawn(process.execPath, [cliPath, ...cliArgs], {
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+  });
+  child.unref();
+  fs.closeSync(logFd);
+
+  const metadata = {
+    schemaVersion: MIRROR_DAEMON_SCHEMA_VERSION,
+    strategyHash,
+    pid: child.pid,
+    pidAlive: isPidAlive(child.pid),
+    startedAt: new Date().toISOString(),
+    checkedAt: new Date().toISOString(),
+    status: isPidAlive(child.pid) ? 'running' : 'unknown',
+    pidFile,
+    logFile,
+    cliPath,
+    cliArgs,
+    stateFile: options.stateFile || null,
+    killSwitchFile: options.killSwitchFile || null,
+    mode: options.mode || 'run',
+    executeLive: Boolean(options.executeLive),
+    pandoraMarketAddress: options.pandoraMarketAddress || null,
+    polymarketMarketId: options.polymarketMarketId || null,
+    polymarketSlug: options.polymarketSlug || null,
+    launchCommand: [process.execPath, cliPath, ...cliArgs].join(' '),
+  };
+  writeJsonFile(pidFile, metadata);
+
+  return metadata;
+}
+
+async function stopDaemon(options = {}) {
+  const pidFile = resolvePidFile(options);
+  const metadata = readJsonFile(pidFile);
+  if (!metadata) {
+    throw createServiceError('MIRROR_DAEMON_NOT_FOUND', `No daemon metadata found at ${pidFile}.`, { pidFile });
+  }
+
+  const pid = Number(metadata.pid);
+  const wasAlive = isPidAlive(pid);
+  let signalSent = false;
+  if (wasAlive) {
+    process.kill(pid, 'SIGTERM');
+    signalSent = true;
+  }
+
+  let exited = wasAlive ? await waitForProcessExit(pid, options.stopTimeoutMs || STOP_TIMEOUT_MS) : true;
+  let alive = isPidAlive(pid);
+  let forceKilled = false;
+  if (wasAlive && alive) {
+    try {
+      process.kill(pid, 'SIGKILL');
+      forceKilled = true;
+      exited = await waitForProcessExit(pid, 2_000);
+      alive = isPidAlive(pid);
+    } catch (err) {
+      if (!(err && (err.code === 'ESRCH' || err.code === 'ENOENT'))) {
+        throw err;
+      }
+      exited = true;
+      alive = false;
+    }
+  }
+
+  const updated = {
+    ...metadata,
+    checkedAt: new Date().toISOString(),
+    pidAlive: alive,
+    status: alive ? 'running' : 'stopped',
+    stopAttemptedAt: new Date().toISOString(),
+    stopSignal: signalSent ? 'SIGTERM' : null,
+    stopForceSignal: forceKilled ? 'SIGKILL' : null,
+    stopSignalSent: signalSent,
+    stopExitObserved: exited,
+    stopForceKilled: forceKilled,
+  };
+  writeJsonFile(pidFile, updated);
+
+  return {
+    schemaVersion: MIRROR_DAEMON_SCHEMA_VERSION,
+    strategyHash: updated.strategyHash || null,
+    pidFile,
+    pid,
+    wasAlive,
+    signalSent,
+    forceKilled,
+    exitObserved: exited,
+    alive,
+    status: updated.status,
+    metadata: updated,
+  };
+}
+
+function daemonStatus(options = {}) {
+  const pidFile = resolvePidFile(options);
+  const metadata = readJsonFile(pidFile);
+
+  if (!metadata) {
+    return {
+      schemaVersion: MIRROR_DAEMON_SCHEMA_VERSION,
+      found: false,
+      pidFile,
+      strategyHash: options.strategyHash ? normalizeStrategyHash(options.strategyHash) : null,
+      pid: null,
+      alive: false,
+      status: 'not-found',
+      metadata: null,
+    };
+  }
+
+  const pid = Number(metadata.pid);
+  const alive = isPidAlive(pid);
+  const updated = {
+    ...metadata,
+    checkedAt: new Date().toISOString(),
+    pidAlive: alive,
+    status: alive ? 'running' : 'stopped',
+  };
+  writeJsonFile(pidFile, updated);
+
+  return {
+    schemaVersion: MIRROR_DAEMON_SCHEMA_VERSION,
+    found: true,
+    pidFile,
+    strategyHash: updated.strategyHash || null,
+    pid,
+    alive,
+    status: updated.status,
+    metadata: updated,
+  };
+}
+
+module.exports = {
+  MIRROR_DAEMON_SCHEMA_VERSION,
+  defaultPidFile,
+  startDaemon,
+  stopDaemon,
+  daemonStatus,
+};

package/cli/lib/mirror_sync_service.cjs

@@ -410,6 +410,8 @@ async function runMirrorSync(options, deps = {}) {
             rebalance: null,
             hedge: null,
           };
+          let actualRebalanceUsdc = 0;
+          let actualHedgeUsdc = 0;
           state.idempotencyKeys.push(idempotencyKey);
           pruneIdempotencyKeys(state);
           state.lastExecution = {
@@ -439,6 +441,7 @@ async function runMirrorSync(options, deps = {}) {
                 result: { status: 'simulated' },
               };
             }
+            actualRebalanceUsdc = plannedRebalanceUsdc;
 
             state.cumulativeLpFeesApproxUsdc =
               round((toNumber(state.cumulativeLpFeesApproxUsdc) || 0) + plannedRebalanceUsdc * 0.003, 6) || 0;
@@ -450,18 +453,18 @@ async function runMirrorSync(options, deps = {}) {
             const hedgeDepth = gapUsdc >= 0 ? depth.yesDepth : depth.noDepth;
 
             if (options.executeLive) {
-              const creds = readTradingCredsFromEnv();
+              const envCreds = readTradingCredsFromEnv();
               const hedgeResult = await hedgeFn({
                 host: options.polymarketHost,
                 mockUrl: options.polymarketMockUrl,
                 tokenId,
                 side: hedgeSide,
                 amountUsd: plannedHedgeUsdc,
-                privateKey: creds.privateKey,
-                funder: creds.funder,
-                apiKey: creds.apiKey,
-                apiSecret: creds.apiSecret,
-                apiPassphrase: creds.apiPassphrase,
+                privateKey: options.privateKey || envCreds.privateKey,
+                funder: options.funder || envCreds.funder,
+                apiKey: envCreds.apiKey,
+                apiSecret: envCreds.apiSecret,
+                apiPassphrase: envCreds.apiPassphrase,
               });
               action.hedge = {
                 tokenId,
@@ -477,21 +480,39 @@ async function runMirrorSync(options, deps = {}) {
                 result: { status: 'simulated' },
               };
             }
-
-            const direction = gapUsdc >= 0 ? 1 : -1;
-            state.currentHedgeUsdc = round((toNumber(state.currentHedgeUsdc) || 0) + direction * plannedHedgeUsdc, 6) || 0;
-            state.cumulativeHedgeNotionalUsdc =
-              round((toNumber(state.cumulativeHedgeNotionalUsdc) || 0) + plannedHedgeUsdc, 6) || 0;
-            const slippageRatio =
-              hedgeDepth && hedgeDepth.midPrice !== null && hedgeDepth.worstPrice !== null && hedgeDepth.midPrice > 0
-                ? Math.max(0, Math.abs(hedgeDepth.worstPrice - hedgeDepth.midPrice) / hedgeDepth.midPrice)
-                : 0;
-            const hedgeCostApprox = plannedHedgeUsdc * slippageRatio;
-            state.cumulativeHedgeCostApproxUsdc =
-              round((toNumber(state.cumulativeHedgeCostApproxUsdc) || 0) + hedgeCostApprox, 6) || 0;
+            const hedgeResultOk = !options.executeLive || (action.hedge && action.hedge.result && action.hedge.result.ok !== false);
+            if (hedgeResultOk) {
+              actualHedgeUsdc = plannedHedgeUsdc;
+              const direction = gapUsdc >= 0 ? 1 : -1;
+              state.currentHedgeUsdc =
+                round((toNumber(state.currentHedgeUsdc) || 0) + direction * plannedHedgeUsdc, 6) || 0;
+              state.cumulativeHedgeNotionalUsdc =
+                round((toNumber(state.cumulativeHedgeNotionalUsdc) || 0) + plannedHedgeUsdc, 6) || 0;
+              const slippageRatio =
+                hedgeDepth && hedgeDepth.midPrice !== null && hedgeDepth.worstPrice !== null && hedgeDepth.midPrice > 0
+                  ? Math.max(0, Math.abs(hedgeDepth.worstPrice - hedgeDepth.midPrice) / hedgeDepth.midPrice)
+                  : 0;
+              const hedgeCostApprox = plannedHedgeUsdc * slippageRatio;
+              state.cumulativeHedgeCostApproxUsdc =
+                round((toNumber(state.cumulativeHedgeCostApproxUsdc) || 0) + hedgeCostApprox, 6) || 0;
+            } else {
+              action.status = 'failed';
+              const hedgeError =
+                action.hedge && action.hedge.result && action.hedge.result.error
+                  ? action.hedge.result.error
+                  : action.hedge && action.hedge.result && action.hedge.result.response && action.hedge.result.response.error
+                    ? { message: String(action.hedge.result.response.error) }
+                    : { message: 'Polymarket hedge execution failed.' };
+              action.error = {
+                code: 'HEDGE_EXECUTION_FAILED',
+                message: hedgeError.message || 'Polymarket hedge execution failed.',
+                details: hedgeError,
+              };
+            }
           }
 
-          state.dailySpendUsdc = round((toNumber(state.dailySpendUsdc) || 0) + plannedSpendUsdc, 6) || 0;
+          const actualSpendUsdc = round(actualRebalanceUsdc + actualHedgeUsdc, 6) || 0;
+          state.dailySpendUsdc = round((toNumber(state.dailySpendUsdc) || 0) + actualSpendUsdc, 6) || 0;
           const executedLegCount = (action.rebalance ? 1 : 0) + (action.hedge ? 1 : 0);
           state.tradesToday += executedLegCount || 1;
           state.lastExecution = action;