@xerg/cli 0.5.0 → 0.5.2

package/README.md

@@ -1,9 +1,11 @@
 # xerg
 
-Audit OpenClaw and Hermes workflows in dollars, compare fixes, and optionally connect hosted follow-up after the first local result.
+Audit OpenClaw, Hermes, and Cursor spend in dollars, surface provenance-aware waste findings, compare fixes, and optionally connect hosted follow-up after the first local result.
 
 Xerg runs locally by default. Local audits and `--compare` are free. No account is required for local value, and no data leaves your machine unless you explicitly push results to Xerg Cloud.
 
+The `npx @xerg/cli` path fetches and executes the published npm package before running Xerg. If you want to avoid a runtime fetch, install once with `npm install -g @xerg/cli` or run a local build from source.
+
 ## Fastest first run
 
 ```bash
@@ -14,7 +16,7 @@ npx @xerg/cli init
 
 - detects local OpenClaw or Hermes data
 - runs a first audit and stores the local snapshot
-- prints the standard terminal summary
+- prints the provenance-aware terminal summary
 - offers optional hosted follow-up with `connect` and `mcp-setup`
 
 Prefer a global install?
@@ -32,6 +34,7 @@ If you already know what you want, skip `init` and use the direct flows:
 npx @xerg/cli doctor
 npx @xerg/cli audit
 npx @xerg/cli audit --compare
+npx @xerg/cli audit --cursor-usage-csv ./cursor-usage.csv
 npx @xerg/cli audit --json
 npx @xerg/cli audit --markdown
 ```
@@ -54,6 +57,8 @@ node_modules/@xerg/cli/skills/xerg/SKILL.md
 
 For a global install, the same file lives inside the global npm package directory instead. That file is a packaged copy of the canonical repo skill at [`skills/xerg/SKILL.md`](../../skills/xerg/SKILL.md). Use it if your agent platform imports skills from disk; installing the npm package does not automatically register the skill with every agent product.
 
+The bundled skill frontmatter declares the CLI/package surface plus optional Xerg Cloud, SSH, rsync, and Railway requirements so registries can distinguish the default local audit workflow from opt-in hosted sync and remote audit workflows.
+
 ## Supported runtime
 
 `@xerg/cli` supports Node `22` and `24`.
@@ -105,7 +110,7 @@ xerg push
 
 ## Works where your agent data lives
 
-- Local machine: yes
+- Local machine: OpenClaw, Hermes, and explicit Cursor usage CSV exports
 - VPS or remote server: OpenClaw only in this phase
 - If OpenClaw runs remotely, you can audit it from your local machine with `xerg audit --remote user@host`
 - Or point Xerg at exported files directly with flags
@@ -131,6 +136,7 @@ xerg audit --runtime openclaw --log-file /path/to/openclaw.log
 xerg audit --runtime openclaw --sessions-dir /path/to/sessions
 xerg audit --runtime hermes --log-file ~/.hermes/logs/agent.log
 xerg audit --runtime hermes --sessions-dir ~/.hermes/sessions
+xerg audit --cursor-usage-csv ./cursor-usage.csv
 ```
 
 If only one supported local runtime is present, Xerg auto-selects it. If both OpenClaw and Hermes are present locally, rerun with `--runtime openclaw` or `--runtime hermes`.
@@ -152,7 +158,7 @@ xerg mcp-setup
 ```
 
 - `connect` resolves auth from `XERG_API_KEY`, `~/.xerg/config.json`, or stored browser credentials, then offers to push the latest audit
-- `mcp-setup` prints or writes hosted MCP config for Cursor, Claude Code, or another client
+- `mcp-setup` prints or writes hosted MCP config for Cursor, Claude Code, Codex, or another client
 
 You can skip both and keep using local audits and compare.
 
@@ -187,10 +193,13 @@ Example `~/.xerg/config.json`:
 - Total spend by workflow and model, in dollars
 - Daily spend and confirmed waste rollups in UTC
 - Observed vs. estimated cost (always labeled)
-- Confirmed waste: retry, loop, cache carryover where applicable
+- Confirmed waste: retry and loop findings when the required source structure is present
+- Provenance-aware waste rollups by observed, inferred, declared, or unknown signal source
 - Savings opportunities: context bloat, downgrade candidates, idle, max mode concentration where applicable
 - Ranked recommendations with where-to-change guidance and compare validation steps
-- Before/after deltas on re-audit
+- Before/after normalized rates on re-audit, including waste per run and waste per 1k calls
+
+Local JSON findings may include `signalSource`, `ruleId`, and evidence references so agents can distinguish observed signals from inferred or legacy unknown provenance. These local provenance fields are not part of the pushed v2 wire payload.
 
 ## Privacy
 

package/dist/index.js

@@ -1165,6 +1165,36 @@ function buildTaxonomyBuckets(findings, classification) {
   }
   return Array.from(buckets.values()).sort((left, right) => right.spendUsd - left.spendUsd);
 }
+function buildWasteBySignalSource(findings) {
+  const rollup = {
+    observedUsd: 0,
+    inferredUsd: 0,
+    declaredUsd: 0,
+    unknownUsd: 0,
+    inferredShare: null
+  };
+  for (const finding of findings) {
+    if (finding.classification !== "waste") {
+      continue;
+    }
+    if (finding.signalSource === "observed") {
+      rollup.observedUsd = round2(rollup.observedUsd + finding.costImpactUsd);
+      continue;
+    }
+    if (finding.signalSource === "inferred") {
+      rollup.inferredUsd = round2(rollup.inferredUsd + finding.costImpactUsd);
+      continue;
+    }
+    if (finding.signalSource === "declared") {
+      rollup.declaredUsd = round2(rollup.declaredUsd + finding.costImpactUsd);
+      continue;
+    }
+    rollup.unknownUsd = round2(rollup.unknownUsd + finding.costImpactUsd);
+  }
+  const knownTotal = rollup.observedUsd + rollup.inferredUsd + rollup.declaredUsd;
+  rollup.inferredShare = rollup.unknownUsd > 0 ? null : Number((knownTotal === 0 ? 0 : rollup.inferredUsd / knownTotal).toFixed(4));
+  return rollup;
+}
 function toSpendMap(rows) {
   return new Map(rows.map((row) => [row.key, row.spendUsd]));
 }
@@ -1280,6 +1310,7 @@ function hydrateAuditSummary(summary) {
     opportunityByKind: summary.opportunityByKind?.length > 0 ? summary.opportunityByKind : buildTaxonomyBuckets(summary.findings, "opportunity"),
     spendByDay: summary.spendByDay ?? [],
     wasteByDay: summary.wasteByDay ?? [],
+    wasteBySignalSource: summary.wasteBySignalSource ?? buildWasteBySignalSource(summary.findings),
     recommendations: summary.recommendations ?? [],
     notes: summary.notes ?? [],
     pricingCoverage: summary.pricingCoverage ?? null,
@@ -1300,6 +1331,7 @@ function buildAuditComparison(current, baseline) {
     baselineWasteSpendUsd: baseline.wasteSpendUsd,
     baselineOpportunitySpendUsd: baseline.opportunitySpendUsd,
     baselineStructuralWasteRate: baseline.structuralWasteRate,
+    baselineWasteBySignalSource: baseline.wasteBySignalSource ?? buildWasteBySignalSource(baseline.findings),
     deltaTotalSpendUsd: round2(current.totalSpendUsd - baseline.totalSpendUsd),
     deltaObservedSpendUsd: round2(current.observedSpendUsd - baseline.observedSpendUsd),
     deltaEstimatedSpendUsd: round2(current.estimatedSpendUsd - baseline.estimatedSpendUsd),
@@ -1350,6 +1382,8 @@ function readLatestComparableAuditSummary(input) {
 }
 
 // ../core/src/findings/cursor.ts
+var CACHE_CARRYOVER_RULE_ID = "cursor_cache_ratio_v1";
+var MAX_MODE_CONCENTRATION_RULE_ID = "cursor_max_mode_concentration_v1";
 function round3(value) {
   return Number(value.toFixed(6));
 }
@@ -1419,6 +1453,13 @@ function buildCursorUsageFindings(runs) {
       scopeId: "all",
       scopeLabel: "Cursor usage",
       costImpactUsd: cacheImpactUsd,
+      signalSource: "observed",
+      ruleId: CACHE_CARRYOVER_RULE_ID,
+      evidence: {
+        callIds: cacheAwareCalls.map((call) => call.id).sort(),
+        runIds: Array.from(new Set(cacheAwareCalls.map((call) => call.runId))).sort(),
+        sourceKinds: ["cursor-usage-csv"]
+      },
       details: {
         cacheReadShare: round3(cacheReadShare),
         cacheCoverageShare: round3(cacheCoverageShare),
@@ -1447,6 +1488,13 @@ function buildCursorUsageFindings(runs) {
         scopeId: "all",
         scopeLabel: "Cursor usage",
         costImpactUsd: round3(maxModeSpendUsd * 0.2),
+        signalSource: "observed",
+        ruleId: MAX_MODE_CONCENTRATION_RULE_ID,
+        evidence: {
+          callIds: maxModeCalls.map((call) => call.id).sort(),
+          runIds: Array.from(new Set(maxModeCalls.map((call) => call.runId))).sort(),
+          sourceKinds: ["cursor-usage-csv"]
+        },
         details: {
           maxModeSpendUsd: round3(maxModeSpendUsd),
           maxModeSpendShare: round3(maxModeSpendShare),
@@ -1468,55 +1516,178 @@ function buildCursorUsageFindings(runs) {
 }
 
 // ../core/src/findings/engine.ts
+var RETRY_OBSERVED_RULE_ID = "retry_explicit_failed_attempt_v1";
+var RETRY_INFERRED_RULE_ID = "retry_later_attempt_proxy_v1";
+var LOOP_RULE_ID = "loop_iteration_threshold_v1";
+var CONTEXT_OUTLIER_RULE_ID = "context_outlier_tokens_v1";
+var IDLE_SPEND_RULE_ID = "idle_workflow_name_v1";
+var CANDIDATE_DOWNGRADE_RULE_ID = "candidate_downgrade_task_model_v1";
+var LOOP_WASTE_START_ITERATION = 6;
+var LOOP_FINDING_MIN_ITERATION = 7;
 function createFinding2(input) {
   return {
     ...input,
     id: sha1(
-      `${input.kind}:${input.scope}:${input.scopeId}:${input.title}:${input.costImpactUsd}:${input.summary}`
+      `${input.kind}:${input.scope}:${input.scopeId}:${input.title}:${input.costImpactUsd}:${input.summary}:${input.signalSource ?? "unknown"}:${input.ruleId ?? "none"}`
     )
   };
 }
 function round4(value) {
   return Number(value.toFixed(6));
 }
+function isFailedOrAborted(call) {
+  const status = (call.status ?? "").toLowerCase();
+  return status.includes("error") || status.includes("fail") || status.includes("abort");
+}
+function hasExplicitRetrySignal(call) {
+  return (call.attempt ?? 1) > 1 || call.retries > 0;
+}
+function toTimestampMs(call) {
+  const timestamp = new Date(call.timestamp).getTime();
+  return Number.isFinite(timestamp) ? timestamp : Number.POSITIVE_INFINITY;
+}
+function sortCallsByTime(calls) {
+  return calls.map((call, index) => ({ call, index })).sort((left, right) => {
+    const delta = toTimestampMs(left.call) - toTimestampMs(right.call);
+    return delta === 0 ? left.index - right.index : delta;
+  });
+}
+function canUseStructuralSignals(sourceKind) {
+  return sourceKind === "gateway";
+}
+function hasLaterExplicitRetryAttempt(sortedCalls, currentIndex) {
+  const current = sortedCalls[currentIndex]?.call;
+  if (!current) {
+    return false;
+  }
+  return sortedCalls.slice(currentIndex + 1).some(({ call }) => {
+    if (!hasExplicitRetrySignal(call)) {
+      return false;
+    }
+    if (current.attempt !== null && call.attempt !== null) {
+      return call.attempt > current.attempt;
+    }
+    return true;
+  });
+}
+function uniqueSourceKinds(calls, runs) {
+  const runById = new Map(runs.map((run2) => [run2.id, run2]));
+  return Array.from(
+    new Set(
+      calls.map((call) => runById.get(call.runId)?.sourceKind).filter((sourceKind) => Boolean(sourceKind))
+    )
+  ).sort();
+}
+function buildRetryFinding(input) {
+  const retryCost = input.calls.reduce((sum, call) => sum + call.costUsd, 0);
+  const observed = input.signalSource === "observed";
+  return createFinding2({
+    classification: "waste",
+    confidence: observed ? "high" : "medium",
+    kind: "retry-waste",
+    title: observed ? "Retry waste is consuming measurable spend" : "Retry waste is likely present from later retry attempts",
+    summary: observed ? `${input.calls.length} failed or aborted call${input.calls.length === 1 ? "" : "s"} were followed by explicit retry attempts, making their spend retry overhead.` : `${input.calls.length} later retry attempt${input.calls.length === 1 ? "" : "s"} were counted as proxy retry overhead because the earlier failed attempt was not separately countable.`,
+    scope: "global",
+    scopeId: "all",
+    scopeLabel: "workspace",
+    costImpactUsd: round4(retryCost),
+    signalSource: input.signalSource,
+    ruleId: input.ruleId,
+    evidence: {
+      callIds: input.calls.map((call) => call.id).sort(),
+      runIds: Array.from(new Set(input.calls.map((call) => call.runId))).sort(),
+      sourceKinds: uniqueSourceKinds(input.calls, input.runs)
+    },
+    details: {
+      retryCallCount: input.calls.length
+    }
+  });
+}
 function buildFindings(runs) {
   const findings = [];
   const wasteAttributions = [];
-  const allCalls = runs.flatMap((run2) => run2.calls.map((call) => ({ run: run2, call })));
-  const retryCandidates = allCalls.filter(({ call }) => {
-    const status = (call.status ?? "").toLowerCase();
-    return status.includes("error") || status.includes("fail");
-  });
-  const retryCost = retryCandidates.reduce((sum, item) => sum + item.call.costUsd, 0);
-  if (retryCost > 0) {
+  const observedRetryCalls = [];
+  const inferredRetryCalls = [];
+  const retryCoveredCallIds = /* @__PURE__ */ new Set();
+  for (const run2 of runs.filter((candidate) => canUseStructuralSignals(candidate.sourceKind))) {
+    const sortedCalls = sortCallsByTime(run2.calls);
+    sortedCalls.forEach(({ call }, index) => {
+      if (!isFailedOrAborted(call)) {
+        return;
+      }
+      if (!hasExplicitRetrySignal(call) && !hasLaterExplicitRetryAttempt(sortedCalls, index)) {
+        return;
+      }
+      if (!hasLaterExplicitRetryAttempt(sortedCalls, index)) {
+        return;
+      }
+      observedRetryCalls.push(call);
+      retryCoveredCallIds.add(call.id);
+      const later = sortedCalls.slice(index + 1).find(({ call: laterCall }) => hasExplicitRetrySignal(laterCall));
+      if (later) {
+        retryCoveredCallIds.add(later.call.id);
+      }
+    });
+    for (const { call } of sortedCalls) {
+      if (!hasExplicitRetrySignal(call) || retryCoveredCallIds.has(call.id)) {
+        continue;
+      }
+      const hasEarlierCountableFailure = sortedCalls.some(({ call: earlier }) => {
+        if (earlier.id === call.id) {
+          return false;
+        }
+        return toTimestampMs(earlier) < toTimestampMs(call) && isFailedOrAborted(earlier);
+      });
+      if (!hasEarlierCountableFailure) {
+        inferredRetryCalls.push(call);
+        retryCoveredCallIds.add(call.id);
+      }
+    }
+  }
+  if (observedRetryCalls.length > 0) {
     wasteAttributions.push(
-      ...retryCandidates.map(({ call }) => ({
+      ...observedRetryCalls.map((call) => ({
         kind: "retry-waste",
         timestamp: call.timestamp,
         wasteUsd: call.costUsd
       }))
     );
     findings.push(
-      createFinding2({
-        classification: "waste",
-        confidence: "high",
+      buildRetryFinding({
+        calls: observedRetryCalls,
+        runs,
+        signalSource: "observed",
+        ruleId: RETRY_OBSERVED_RULE_ID
+      })
+    );
+  }
+  if (inferredRetryCalls.length > 0) {
+    wasteAttributions.push(
+      ...inferredRetryCalls.map((call) => ({
         kind: "retry-waste",
-        title: "Retry waste is consuming measurable spend",
-        summary: `${retryCandidates.length} failed call${retryCandidates.length === 1 ? "" : "s"} were followed by additional work, making their spend pure retry overhead.`,
-        scope: "global",
-        scopeId: "all",
-        scopeLabel: "workspace",
-        costImpactUsd: round4(retryCost),
-        details: {
-          failedCallCount: retryCandidates.length
-        }
+        timestamp: call.timestamp,
+        wasteUsd: call.costUsd
+      }))
+    );
+    findings.push(
+      buildRetryFinding({
+        calls: inferredRetryCalls,
+        runs,
+        signalSource: "inferred",
+        ruleId: RETRY_INFERRED_RULE_ID
       })
     );
   }
-  for (const run2 of runs) {
-    const maxIteration = Math.max(...run2.calls.map((call) => call.iteration ?? 0));
-    if (maxIteration >= 7) {
-      const loopCalls = run2.calls.filter((call) => (call.iteration ?? 0) > 5);
+  for (const run2 of runs.filter((candidate) => canUseStructuralSignals(candidate.sourceKind))) {
+    const iterations = run2.calls.map((call) => call.iteration).filter((iteration) => iteration !== null);
+    if (iterations.length === 0) {
+      continue;
+    }
+    const maxIteration = Math.max(...iterations);
+    if (maxIteration >= LOOP_FINDING_MIN_ITERATION) {
+      const loopCalls = run2.calls.filter(
+        (call) => (call.iteration ?? 0) >= LOOP_WASTE_START_ITERATION
+      );
       const loopCost = loopCalls.reduce((sum, call) => sum + call.costUsd, 0);
       wasteAttributions.push(
         ...loopCalls.map((call) => ({
@@ -1531,14 +1702,22 @@ function buildFindings(runs) {
           confidence: "high",
           kind: "loop-waste",
           title: `Workflow "${run2.workflow}" ran beyond efficient loop bounds`,
-          summary: `This run reached ${maxIteration} iterations. Xerg treats the spend after iteration 5 as likely loop waste.`,
+          summary: `This run reached ${maxIteration} iterations. Xerg treats spend from iteration ${LOOP_WASTE_START_ITERATION} onward as loop waste.`,
           scope: "run",
           scopeId: run2.workflow,
           scopeLabel: run2.workflow,
           costImpactUsd: round4(loopCost),
+          signalSource: "observed",
+          ruleId: LOOP_RULE_ID,
+          evidence: {
+            callIds: loopCalls.map((call) => call.id).sort(),
+            runIds: [run2.id],
+            sourceKinds: [run2.sourceKind]
+          },
           details: {
             workflow: run2.workflow,
-            maxIteration
+            maxIteration,
+            thresholdIteration: LOOP_WASTE_START_ITERATION
           }
         })
       );
@@ -1573,6 +1752,12 @@ function buildFindings(runs) {
             scopeId: workflow,
             scopeLabel: workflow,
             costImpactUsd: round4(outlierCost),
+            signalSource: "observed",
+            ruleId: CONTEXT_OUTLIER_RULE_ID,
+            evidence: {
+              runIds: outlierRuns.map((run2) => run2.id).sort(),
+              sourceKinds: Array.from(new Set(outlierRuns.map((run2) => run2.sourceKind))).sort()
+            },
             details: {
               workflow,
               averageInputTokens: round4(average),
@@ -1598,6 +1783,12 @@ function buildFindings(runs) {
           scopeId: workflow,
           scopeLabel: workflow,
           costImpactUsd: round4(idleCost),
+          signalSource: "observed",
+          ruleId: IDLE_SPEND_RULE_ID,
+          evidence: {
+            runIds: idleRuns.map((run2) => run2.id).sort(),
+            sourceKinds: Array.from(new Set(idleRuns.map((run2) => run2.sourceKind))).sort()
+          },
           details: {
             workflow
           }
@@ -1620,6 +1811,13 @@ function buildFindings(runs) {
           scopeId: workflow,
           scopeLabel: workflow,
           costImpactUsd: round4(spend * 0.3),
+          signalSource: "observed",
+          ruleId: CANDIDATE_DOWNGRADE_RULE_ID,
+          evidence: {
+            callIds: downgradeCalls.map((call) => call.id).sort(),
+            runIds: Array.from(new Set(downgradeCalls.map((call) => call.runId))).sort(),
+            sourceKinds: uniqueSourceKinds(downgradeCalls, runs)
+          },
           details: {
             workflow,
             expensiveCallCount: downgradeCalls.length,
@@ -1781,7 +1979,7 @@ var templatesByKind = {
     severity: "high",
     effort: "low",
     titleFn: (finding) => `Reduce retry waste in ${formatScopeLabel(finding)}`,
-    summaryFn: (finding) => `${finding.summary} This is confirmed retry overhead, so it is a fix-now issue rather than an experiment.`,
+    summaryFn: (finding) => finding.signalSource === "observed" ? `${finding.summary} This is confirmed retry overhead, so it is a fix-now issue rather than an experiment.` : `${finding.summary} Treat this as likely retry overhead and inspect the retry wrapper before classifying the full amount as proven waste.`,
     whereToChangeFn: (finding) => `Reduce retries or add exponential backoff in the retry wrapper for ${formatScopeLabel(finding)}.`,
     validationPlanFn: () => "Ship the change, then rerun `xerg audit --compare --push` against the same source. Retry waste should drop materially on the next audit.",
     actionsFn: () => [
@@ -2128,6 +2326,7 @@ function buildAuditSummary(input) {
     structuralWasteRate: Number(
       (totalSpendUsd === 0 ? 0 : wasteSpendUsd / totalSpendUsd).toFixed(4)
     ),
+    wasteBySignalSource: buildWasteBySignalSource(input.findings),
     wasteByKind: buildTaxonomyBuckets(input.findings, "waste"),
     opportunityByKind: buildTaxonomyBuckets(input.findings, "opportunity"),
     spendByWorkflow: buildBreakdown(
@@ -3445,9 +3644,18 @@ function formatUsdDelta(value) {
   const sign = value > 0 ? "+" : "";
   return `${sign}${formatUsd(value)}`;
 }
+function formatUsdRate(value) {
+  return formatUsd(value);
+}
 function isCursorUsageSummary(summary) {
   return summary.sourceFiles.some((source) => source.kind === "cursor-usage-csv");
 }
+function divideOrZero(numerator, denominator) {
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+function formatInferredShare(value) {
+  return value === null || value === void 0 ? "unavailable" : formatPercent(value);
+}
 function topRows(rows, limit = 5) {
   return rows.slice(0, limit).map((row) => {
     return `- ${row.key}: ${formatUsd(row.spendUsd)} (${formatPercent(row.observedShare)} observed)`;
@@ -3532,6 +3740,35 @@ function renderFindingChange(change, state) {
   }
   return `- New: ${change.title} (${formatUsd(change.currentCostImpactUsd ?? 0)})`;
 }
+function renderCompareCoreRows(summary) {
+  if (!summary.comparison) {
+    return [];
+  }
+  const comparison = summary.comparison;
+  const baselineWastePerRun = divideOrZero(
+    comparison.baselineWasteSpendUsd,
+    comparison.baselineRunCount
+  );
+  const currentWastePerRun = divideOrZero(summary.wasteSpendUsd, summary.runCount);
+  const baselineWastePer1kCalls = divideOrZero(
+    comparison.baselineWasteSpendUsd,
+    comparison.baselineCallCount / 1e3
+  );
+  const currentWastePer1kCalls = divideOrZero(summary.wasteSpendUsd, summary.callCount / 1e3);
+  return [
+    "## Before / after",
+    `Compared against ${comparison.baselineGeneratedAt}`,
+    `- Waste rate: ${formatPercent(comparison.baselineStructuralWasteRate)} -> ${formatPercent(summary.structuralWasteRate)} (${formatPercentDelta(comparison.deltaStructuralWasteRate)})`,
+    `- Waste per run: ${formatUsdRate(baselineWastePerRun)} -> ${formatUsdRate(currentWastePerRun)} (${formatUsdDelta(currentWastePerRun - baselineWastePerRun)})`,
+    `- Waste per 1k calls: ${formatUsdRate(baselineWastePer1kCalls)} -> ${formatUsdRate(currentWastePer1kCalls)} (${formatUsdDelta(currentWastePer1kCalls - baselineWastePer1kCalls)})`,
+    `- Inferred waste share: ${formatInferredShare(comparison.baselineWasteBySignalSource?.inferredShare)} -> ${formatInferredShare(summary.wasteBySignalSource?.inferredShare)}`,
+    "- CPO: unavailable (no outcome signal)",
+    `- Total spend (workload-dependent): ${formatUsd(comparison.baselineTotalSpendUsd)} -> ${formatUsd(summary.totalSpendUsd)} (${formatUsdDelta(comparison.deltaTotalSpendUsd)})`,
+    `- Structural waste (workload-dependent): ${formatUsd(comparison.baselineWasteSpendUsd)} -> ${formatUsd(summary.wasteSpendUsd)} (${formatUsdDelta(comparison.deltaWasteSpendUsd)})`,
+    `- Runs analyzed: ${comparison.baselineRunCount} -> ${summary.runCount} (${comparison.deltaRunCount > 0 ? "+" : ""}${comparison.deltaRunCount})`,
+    `- Model calls: ${comparison.baselineCallCount} -> ${summary.callCount} (${comparison.deltaCallCount > 0 ? "+" : ""}${comparison.deltaCallCount})`
+  ];
+}
 function renderCompareBlock(summary) {
   if (!summary.comparison) {
     return [];
@@ -3552,13 +3789,7 @@ function renderCompareBlock(summary) {
     )
   ].slice(0, 5);
   return [
-    "## Before / after",
-    `Compared against ${comparison.baselineGeneratedAt}`,
-    `- Total spend: ${formatUsd(comparison.baselineTotalSpendUsd)} -> ${formatUsd(summary.totalSpendUsd)} (${formatUsdDelta(comparison.deltaTotalSpendUsd)})`,
-    `- Structural waste: ${formatUsd(comparison.baselineWasteSpendUsd)} -> ${formatUsd(summary.wasteSpendUsd)} (${formatUsdDelta(comparison.deltaWasteSpendUsd)})`,
-    `- Waste rate: ${formatPercent(comparison.baselineStructuralWasteRate)} -> ${formatPercent(summary.structuralWasteRate)} (${formatPercentDelta(comparison.deltaStructuralWasteRate)})`,
-    `- Runs analyzed: ${comparison.baselineRunCount} -> ${summary.runCount} (${comparison.deltaRunCount > 0 ? "+" : ""}${comparison.deltaRunCount})`,
-    `- Model calls: ${comparison.baselineCallCount} -> ${summary.callCount} (${comparison.deltaCallCount > 0 ? "+" : ""}${comparison.deltaCallCount})`,
+    ...renderCompareCoreRows(summary),
     biggestImprovement ? `- Biggest improvement: ${describeSpendDelta(biggestImprovement)}` : "- Biggest improvement: none detected",
     biggestRegression ? `- Biggest regression: ${describeSpendDelta(biggestRegression)}` : "- Biggest regression: none detected",
     firstWorkflowToInspect ? `- First workflow to inspect now: ${firstWorkflowToInspect}` : "- First workflow to inspect now: no workflow delta available",
@@ -3682,10 +3913,7 @@ function renderCursorCompareBlock(summary) {
   const modeSwing = comparison.workflowDeltas[0];
   const modelSwing = comparison.modelDeltas[0];
   return [
-    "## Before / after",
-    `Compared against ${comparison.baselineGeneratedAt}`,
-    `- Total spend: ${formatUsd(comparison.baselineTotalSpendUsd)} -> ${formatUsd(summary.totalSpendUsd)} (${formatUsdDelta(comparison.deltaTotalSpendUsd)})`,
-    `- Rows analyzed: ${formatCount(comparison.baselineRunCount)} -> ${formatCount(summary.runCount)} (${comparison.deltaRunCount > 0 ? "+" : ""}${comparison.deltaRunCount})`,
+    ...renderCompareCoreRows(summary),
     `- Usage rows with pricing: ${formatCount(summary.pricingCoverage?.pricedCallCount ?? 0)}`,
     modeSwing ? `- Mode swing to inspect: ${describeSpendDelta(modeSwing)}` : "- Mode swing to inspect: none",
     modelSwing ? `- Model swing to inspect: ${describeSpendDelta(modelSwing)}` : "- Model swing to inspect: none"
@@ -3779,7 +4007,7 @@ function renderCursorMarkdownSummary(summary) {
     "",
     "## Findings",
     ...summary.findings.slice(0, 10).map((finding) => {
-      return `- **${finding.title}** (${finding.classification}, ${finding.confidence}) \u2014 ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
+      return `- **${finding.title}** (${finding.classification}, ${finding.confidence}). ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
     }),
     "",
     ...renderActionQueue(summary),
@@ -3862,21 +4090,13 @@ function renderMarkdownSummary(summary) {
     "",
     "## Findings",
     ...summary.findings.slice(0, 10).map((finding) => {
-      return `- **${finding.title}** (${finding.classification}, ${finding.confidence}) \u2014 ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
+      return `- **${finding.title}** (${finding.classification}, ${finding.confidence}). ${finding.summary} Estimated impact: ${formatUsd(finding.costImpactUsd)}.`;
     }),
     "",
     ...renderActionQueue(summary)
   ];
   if (summary.comparison) {
-    const comparison = summary.comparison;
-    lines.push(
-      "",
-      "## Before / after",
-      `- Compared against: ${comparison.baselineGeneratedAt}`,
-      `- Total spend: ${formatUsd(comparison.baselineTotalSpendUsd)} -> ${formatUsd(summary.totalSpendUsd)} (${formatUsdDelta(comparison.deltaTotalSpendUsd)})`,
-      `- Structural waste: ${formatUsd(comparison.baselineWasteSpendUsd)} -> ${formatUsd(summary.wasteSpendUsd)} (${formatUsdDelta(comparison.deltaWasteSpendUsd)})`,
-      `- Waste rate: ${formatPercent(comparison.baselineStructuralWasteRate)} -> ${formatPercent(summary.structuralWasteRate)} (${formatPercentDelta(comparison.deltaStructuralWasteRate)})`
-    );
+    lines.push("", ...renderCompareBlock(summary));
   }
   return lines.join("\n");
 }
@@ -5989,6 +6209,7 @@ function renderRailwayDoctorReport(report) {
 import { existsSync as existsSync2, mkdirSync as mkdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync2 } from "fs";
 import { dirname as dirname3, join as join8 } from "path";
 var HOSTED_MCP_URL = "https://mcp.xerg.ai/mcp";
+var MCP_SERVER_NAME = "xerg";
 async function runMcpSetupCommand() {
   await runMcpSetupFlow();
 }
@@ -6031,6 +6252,11 @@ async function runMcpSetupFlow() {
       value: "claude-code",
       description: "Project-scoped Claude Code MCP config"
     },
+    {
+      name: "Codex",
+      value: "codex",
+      description: "Codex config.toml snippet"
+    },
     {
       name: "Other",
       value: "other",
@@ -6042,6 +6268,14 @@ async function runMcpSetupFlow() {
     await handleCursorSetup(snippet, config);
     return;
   }
+  if (client === "codex") {
+    process.stdout.write(`${buildCodexMcpConfig(config)}
+`);
+    process.stderr.write(
+      "Add this to `~/.codex/config.toml`, then restart Codex so it loads the Xerg MCP tools.\n"
+    );
+    return;
+  }
   process.stdout.write(`${snippet}
 `);
   if (client === "claude-code") {
@@ -6079,7 +6313,7 @@ async function handleCursorSetup(snippet, config) {
 function buildHostedMcpConfig(config) {
   return {
     mcpServers: {
-      xerg: {
+      [MCP_SERVER_NAME]: {
         type: "http",
         url: HOSTED_MCP_URL,
         headers: {
@@ -6089,6 +6323,19 @@ function buildHostedMcpConfig(config) {
     }
   };
 }
+function buildCodexMcpConfig(config) {
+  return [
+    `[mcp_servers.${MCP_SERVER_NAME}]`,
+    "enabled = true",
+    `url = ${tomlString(HOSTED_MCP_URL)}`,
+    "",
+    `[mcp_servers.${MCP_SERVER_NAME}.http_headers]`,
+    `Authorization = ${tomlString(`Bearer ${config.apiKey}`)}`
+  ].join("\n");
+}
+function tomlString(value) {
+  return JSON.stringify(value);
+}
 function writeCursorConfig(filePath, config) {
   mkdirSync6(dirname3(filePath), { recursive: true });
   let parsed = {};
@@ -6425,7 +6672,7 @@ Notes:
 function renderMcpSetupHelp(commandPrefix) {
   return `${formatCommand("mcp-setup", commandPrefix)}
 
-Generate hosted MCP client configuration for Cursor, Claude Code, or another MCP client.
+Generate hosted MCP client configuration for Cursor, Claude Code, Codex, or another MCP client.
 
 Usage:
   ${formatCommand("mcp-setup", commandPrefix)}
@@ -6434,6 +6681,7 @@ Notes:
   - Interactive in v1 because client selection is prompt-driven
   - Uses the hosted MCP endpoint at https://mcp.xerg.ai/mcp
   - Can write a project-scoped Cursor config when .cursor/ already exists
+  - Prints a Codex config.toml snippet when Codex is selected
   - Local audits and compare stay available even if you skip hosted MCP setup
 
   -h, --help                  Show help