sigrank-mcp 0.6.3

package/cascade.mjs

@@ -0,0 +1,143 @@
+/**
+ * cascade.mjs — pure SigRank yield cascade (no deps, no transport).
+ * Mirrors sigrank-app/lib/ingest/bridge.ts computeCascadeMetrics() so rank_paste
+ * reproduces the canonical MO§ES Υ 18436.98 from its 4 raw token pillars.
+ * Paper-and-pencil math, open by design; proprietary threshold cuts stay server-side.
+ *
+ * Degenerate-input policy (hardened):
+ *   - Any pillar that collapses a denominator (i=0, o=0, cw=0, cr=0) returns null for
+ *     the affected metrics rather than Infinity/NaN.
+ *   - A `warnings[]` array is attached when any metric is null so callers can surface the
+ *     reason without silently corrupting downstream calculations.
+ *   - The cascade is NEVER thrown away — even partial results are useful for review/storage.
+ *     Callers that require a fully-formed result should check `warnings.length === 0`.
+ */
+
+export const round = (n, d) => (Number.isFinite(n) ? Number(n.toFixed(d)) : null)
+
+/** The four raw token pillars → the cascade. */
+export function cascade({ input, output, cacheCreate, cacheRead }) {
+  const i = Number(input), o = Number(output), cw = Number(cacheCreate), cr = Number(cacheRead)
+  const total = i + o + cw + cr
+  const warnings = []
+
+  // SNR: undefined when both i and o are 0 (empty session)
+  const snrDenom = i + o
+  const snr = snrDenom > 0 ? o / snrDenom : null
+  if (snr === null) warnings.push('snr_undefined: input+output=0')
+
+  // velocity: undefined when i=0 (no fresh input — pure cache-only session)
+  const velocity = i > 0 ? o / i : null
+  if (velocity === null) warnings.push('velocity_undefined: input=0')
+
+  // leverage: undefined when i=0
+  const leverage = i > 0 ? cr / i : null
+  if (leverage === null) warnings.push('leverage_undefined: input=0')
+
+  // Υ = leverage × velocity = (Cr·O)/I² — null when either component is null
+  const yield_ = leverage !== null && velocity !== null ? leverage * velocity : null
+  if (yield_ === null && !warnings.some((w) => w.startsWith('yield')))
+    warnings.push('yield_undefined: requires input>0')
+
+  // dev10x = log10(Cr/I) — collapses when cw=0 (no cache commits) or i=0 or cr=0.
+  // narrate.mjs already has a nonCompounding branch for this case; we return null
+  // explicitly so the branch triggers correctly (vs -Infinity on log10(0)).
+  let dev10x = null
+  if (i > 0 && o > 0 && cw > 0 && cr > 0) {
+    dev10x = Math.log10((o / i) * (cw / o) * (cr / cw)) // = log10(Cr/I)
+  } else {
+    warnings.push('dev10x_undefined: requires all four pillars > 0')
+  }
+
+  const result = {
+    pillars: { input: i, output: o, cacheCreate: cw, cacheRead: cr, total },
+    yield: round(yield_, 2),
+    snr: round(snr, 4),
+    leverage: round(leverage, 1),
+    velocity: round(velocity, 3),
+    dev10x: round(dev10x, 2),
+    class: classify(yield_, dev10x),
+  }
+  if (warnings.length > 0) result.warnings = warnings
+  return result
+}
+
+/** MVP class tiering from Υ + 10xDEV (canon assigns from cascade SNR + 10xDEV; this
+ *  is the open-MVP approximation — proprietary threshold cuts stay server-side). */
+export function classify(yieldVal, dev10x) {
+  if (yieldVal >= 1000 || dev10x >= 3) return 'TRANSMITTER'
+  if (dev10x >= 1.45) return 'ARCH+'
+  if (dev10x >= 1.35) return 'ARCH'
+  if (dev10x >= 1.2) return 'POWER'
+  if (dev10x >= 1.0) return 'BASE'
+  if (dev10x >= 0) return 'SEEKER'
+  if (dev10x >= -0.3) return 'REFINER'
+  return 'IGNITER'
+}
+
+/**
+ * Extract the 4 pillars from pasted text: JSON object OR 4 whitespace numbers.
+ *
+ * Hardened parse policy:
+ *   - JSON path: requires named keys and numeric values. Rejects strings/null.
+ *   - Positional path: requires the input to be ONLY numeric tokens (whitespace/commas
+ *     allowed as separators). If the text contains non-numeric words the positional
+ *     extractor attaches a `_parseWarnings` flag so downstream can route it to a review
+ *     channel instead of treating it as authoritative data.
+ *   - Negative values are accepted (not thrown away) but flagged — could be valid in
+ *     some edge-case accounting or a data error; the server is the authority on validity.
+ *   - We NEVER silently corrupt: if we can't parse 4 pillars we throw. If we parse but
+ *     something looks suspicious we surface it in `_parseWarnings` on the returned object.
+ */
+export function parsePillars(text) {
+  const t = String(text || '').trim()
+  const pw = [] // parse warnings to attach
+
+  // ── JSON path ──────────────────────────────────────────────────────────────
+  try {
+    const j = JSON.parse(t)
+    if (j && typeof j === 'object' && !Array.isArray(j)) {
+      const g = (...keys) => { for (const k of keys) if (j[k] != null) return j[k]; return null }
+      const input      = g('input', 'tokens_input_fresh', 'inputTokens', 'input_tokens')
+      const output     = g('output', 'tokens_output', 'outputTokens', 'output_tokens')
+      const cacheCreate = g('cacheCreate', 'tokens_cache_creation', 'cache_creation_tokens')
+      const cacheRead  = g('cacheRead', 'tokens_cache_read', 'cache_read_tokens')
+      if ([input, output, cacheCreate, cacheRead].every((v) => v != null)) {
+        const pillars = {
+          input: Number(input),
+          output: Number(output),
+          cacheCreate: Number(cacheCreate),
+          cacheRead: Number(cacheRead),
+        }
+        if ([pillars.input, pillars.output, pillars.cacheCreate, pillars.cacheRead].some((v) => !Number.isFinite(v)))
+          throw new Error('Non-numeric pillar value in JSON (got string or non-finite number).')
+        if ([pillars.input, pillars.output, pillars.cacheCreate, pillars.cacheRead].some((v) => v < 0))
+          pw.push('negative_pillar: one or more pillars is negative — may be a data error')
+        if (pw.length > 0) pillars._parseWarnings = pw
+        return pillars
+      }
+    }
+  } catch (e) {
+    // JSON.parse syntax error — fall through to positional. Re-throw parse errors we raised ourselves.
+    if (e.message.startsWith('Non-numeric')) throw e
+  }
+
+  // ── Positional path ────────────────────────────────────────────────────────
+  // Guard: if the text contains alphabetic words, the numeric extraction is unreliable.
+  // We still attempt it (don't throw away the data) but flag it for review.
+  if (/[a-zA-Z]/.test(t))
+    pw.push('positional_from_mixed_text: extracted numbers from text that contains alphabetic characters — verify these are the correct 4 pillars')
+
+  const nums = (t.match(/-?\d[\d,]*\.?\d*/g) || []).map((s) => Number(s.replace(/,/g, '')))
+  if (nums.length >= 4) {
+    const [input, output, cacheCreate, cacheRead] = nums
+    if (nums.length > 4)
+      pw.push(`positional_extra_numbers: found ${nums.length} numbers, using first 4 — inspect for positional order error`)
+    const pillars = { input, output, cacheCreate, cacheRead }
+    if ([input, output, cacheCreate, cacheRead].some((v) => v < 0))
+      pw.push('negative_pillar: one or more pillars is negative — may be a data error')
+    if (pw.length > 0) pillars._parseWarnings = pw
+    return pillars
+  }
+  throw new Error('Could not parse 4 token pillars (input, output, cacheCreate, cacheRead) from the input.')
+}

package/index.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/**
+ * SigRank MCP server — exposes the SigRank yield cascade + live board as MCP tools
+ * any client (Claude Code, Cursor, …) can call. Token-only, Claude/ccusage-first.
+ *
+ * Tools (see ./tools.mjs):
+ *   - rank_paste(text)              paste ccusage token counts → Υ/SNR/Leverage/…+class +card
+ *   - get_leaderboard()             the live public board (signalaf.com)
+ *   - get_operator(codename)        one operator's live profile
+ *   - submit_paste(text, codename)  rank AND publish to the board in one call
+ *
+ * Pure cascade math lives in ./cascade.mjs (mirrors lib/ingest/bridge.ts); the
+ * deterministic card in ./narrate.mjs; the tool table + dispatcher in ./tools.mjs.
+ * No transcript content, no auth. Reuses the live read/write endpoints over HTTP.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { TOOLS, callTool } from './tools.mjs'
+
+// Prevent silent crashes — log to stderr (MCP clients read stdout; stderr is safe for
+// diagnostics). The process exits so the client can respawn with a clean slate rather
+// than hanging on a broken connection.
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[sigrank-mcp] uncaughtException: ${err?.stack || err}\n`)
+  process.exit(1)
+})
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[sigrank-mcp] unhandledRejection: ${reason?.stack || reason}\n`)
+  process.exit(1)
+})
+
+async function main() {
+  const server = new Server({ name: 'sigrank', version: '0.6.2' }, { capabilities: { tools: {} } })
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    try {
+      const out = await callTool(req.params.name, req.params.arguments)
+      return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] }
+    } catch (e) {
+      return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true }
+    }
+  })
+  await server.connect(new StdioServerTransport())
+}
+
+main()

package/narrate.mjs

@@ -0,0 +1,65 @@
+/**
+ * narrate.mjs — deterministic prose "card" for a cascade result.
+ *
+ * Port of _template() from ~/Desktop/moses-sigrank/narrate.py. The model path
+ * (MiniCPM4-0.5B) is intentionally SKIPPED: the template is the trustworthy,
+ * instant, auditable fallback — same numbers in → same card out, and it can never
+ * emit a metric the cascade didn't produce. A model hook can layer behind this same
+ * narrate() interface later without a rewrite.
+ *
+ * Token-only. No network, no randomness.
+ */
+
+// Safe formatters: never emit NaN/Infinity/undefined into the card.
+const safeNum = (n) => (Number.isFinite(Number(n)) ? Number(n) : null)
+const comma = (n, dec) => {
+  const v = safeNum(n)
+  return v !== null ? v.toLocaleString('en-US', { minimumFractionDigits: dec, maximumFractionDigits: dec }) : '—'
+}
+const plain = (n, dec) => {
+  const v = safeNum(n)
+  return v !== null ? v.toFixed(dec) : '—'
+}
+
+/**
+ * Given a cascade result ({ velocity, leverage, dev10x, pillars, class }) and an
+ * optional subject name, return "**CLASS.** <one or two sentences>". Deterministic.
+ */
+export function narrate(cascade, name = 'This operator') {
+  const klass = cascade.class || cascade.klass || 'UNCLASSED'
+  const v = safeNum(cascade.velocity)
+  const l = safeNum(cascade.leverage)
+
+  // "non-compounding" = a stateless pipe: no cache commits, so the cascade can't
+  // form. cascade.mjs leaves dev10x null when cacheCreate is 0 (the cw/o term
+  // collapses), which is exactly metrics.py's non_compounding flag.
+  // Also catches zero-input sessions where velocity/leverage are null.
+  const cw = cascade.pillars ? Number(cascade.pillars.cacheCreate) : NaN
+  const nonCompounding = cascade.dev10x == null || !(cw > 0) || v === null || l === null
+
+  let body
+  if (nonCompounding) {
+    const leverageStr = l !== null ? `Leverage ${comma(l, 1)}x comes from reuse alone.` : 'Leverage is undefined (no fresh input recorded).'
+    const dev10xNote = cascade.dev10x == null ? ' 10xDEV is undefined — the compounding loop has not formed yet.' : ''
+    body =
+      `${name} runs a stateless pipe — no cache commits, so the cascade can't form. ` +
+      `High read volume, but nothing is being built forward. ${leverageStr}${dev10xNote}`
+  } else if (v >= 1 && l >= 100) {
+    body =
+      `${name} holds both axes at once: ${plain(v, 1)}x generation AND ${comma(l, 0)}x memory leverage. ` +
+      `A closed kinetic loop — the rare operator the leverage/generation tradeoff says shouldn't exist.`
+  } else if (l >= 10 && v < 1) {
+    body =
+      `${name} is an archival sponge — ${comma(l, 0)}x reuse but only ${plain(v, 2)}x generation. ` +
+      `Holds context beautifully, executes little with it. The reuse number is inflated by a weak commitment stage.`
+  } else if (v >= 0.8 && l < 2) {
+    body =
+      `${name} is a volatile ingestor — ${plain(v, 2)}x generation but ${plain(l, 1)}x leverage. ` +
+      `Fast on single shots, resets between turns. Memory doesn't persist into a compounding loop.`
+  } else {
+    body =
+      `${name} sits low on both axes: ${plain(v, 2)}x generation, ${plain(l, 1)}x leverage. ` +
+      `A transient profile — neither building state nor converting input to output efficiently.`
+  }
+  return `**${klass}.** ${body}`
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "sigrank-mcp",
+  "version": "0.6.3",
+  "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
+  "type": "module",
+  "bin": { "sigrank-mcp": "./index.mjs" },
+  "main": "index.mjs",
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node test.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "tools.mjs",
+    "cascade.mjs",
+    "narrate.mjs",
+    "tokenpull.mjs",
+    "adapters.mjs",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/tokenpull.mjs

@@ -0,0 +1,274 @@
+/**
+ * tokenpull.mjs — SigRank's in-house local usage reader.
+ *
+ * Reads token telemetry straight from the platform's local session logs (Claude Code
+ * first: ~/.claude/projects/<project>/<session>.jsonl) and slices it into the four
+ * windows (7d / 30d / 90d / all) of raw pillars — the WINDOWED_PROFILES payload, pulled
+ * with zero paste. No ccusage, no tokscale: our own reader, our own numbers.
+ *
+ * Token-only: we read usage counts (input/output/cache), message id, and timestamp —
+ * never message text. Billing-accurate: messages are deduped by `message.id` so the
+ * tally matches what the API actually billed (the one trick token-dashboard gets right
+ * and sigrank-agent's line-index keying does not).
+ *
+ * Adapter-shaped for multi-system: add a Codex / Cursor / Gemini reader by implementing
+ * the same { platform, defaultRoot(), messages(root) } contract — Claude is just the first.
+ */
+
+import { readdir, readFile, lstat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { ADAPTERS } from './adapters.mjs'
+
+const DAY_MS = 86_400_000
+
+// Background tooling that runs under your account but is NOT your work — memory plugins,
+// observers, summarizers, sub-agent fleets. They pad output/Υ (claude-mem did ~27%).
+// Excluded so pillars reflect the operator, not their tools. EXTENSIBLE — add tool
+// dir-name patterns here. Strategic note: others' tools inflate the PUBLIC
+// token-dashboard / tokscale boards; SigRank filters them, so SigRank stays honest.
+// subagents/ are KEPT (real work). Future-robust signal: also drop entrypoint=sdk-cli.
+export const EXCLUDE_TOOLING =
+  /(^|[/-])(claude-mem|mem0|claude-self-reflect|basic-memory|memento|cipher-mem|memory-keeper)\b|observer-(sessions|archive)/i
+
+/** The four windows, in days. `all` = unbounded. */
+export const WINDOWS = [
+  { key: '7d', days: 7 },
+  { key: '30d', days: 30 },
+  { key: '90d', days: 90 },
+  { key: 'all', days: Infinity },
+]
+
+/** Hard cap: stop walking after this many .jsonl files to prevent OOM on
+ *  accidentally huge or circularly-symlinked directory trees.
+ *  Override via SIGRANK_MAX_JSONL_FILES env var. */
+const MAX_JSONL_FILES = Number(process.env.SIGRANK_MAX_JSONL_FILES) || 10_000
+
+/** Recursively yield every *.jsonl path under dir (any depth), sorted. Must be
+ *  recursive: Claude Code stores sub-agent transcripts in `<project>/subagents/`
+ *  (and other nested logs) — a 2-level readdir silently drops them, which badly
+ *  under-counts input (sub-agent runs are input-heavy). token-dashboard's rglob.
+ *
+ *  Hardened: skips symlinked directories (prevents circular traversal) and stops
+ *  after MAX_JSONL_FILES files (prevents OOM on pathological trees). */
+async function* _walkJsonl(dir, _counter = { n: 0 }) {
+  if (_counter.n >= MAX_JSONL_FILES) return
+  let entries
+  try { entries = await readdir(dir, { withFileTypes: true }) } catch { return }
+  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+    if (_counter.n >= MAX_JSONL_FILES) return
+    const full = join(dir, e.name)
+    if (e.isDirectory()) {
+      // Skip symlinked directories — prevents circular traversal on machines where
+      // ~/.claude/projects/ contains a symlink to a large or self-referential tree.
+      let stat
+      try { stat = await lstat(full) } catch { continue }
+      if (stat.isSymbolicLink()) continue
+      yield* _walkJsonl(full, _counter)
+    } else if (e.isFile() && e.name.endsWith('.jsonl')) {
+      _counter.n++
+      yield full
+    }
+  }
+}
+
+/**
+ * Claude Code adapter. Yields one record per billed assistant message:
+ * { id, sid, ts, input, output, cacheCreate, cacheRead, file }. Walks
+ * ~/.claude/projects RECURSIVELY (incl. subagents/) and carries sessionId so the
+ * caller can dedup by (session_id, message_id) like token-dashboard.
+ */
+export const claudeAdapter = {
+  platform: 'claude',
+  defaultRoot: () => join(homedir(), '.claude', 'projects'),
+  async *messages(root) {
+    for await (const path of _walkJsonl(root)) {
+      let text
+      try { text = await readFile(path, 'utf8') } catch { continue }
+      const rel = path.startsWith(root) ? path.slice(root.length + 1) : path
+      if (EXCLUDE_TOOLING.test(rel)) continue // skip claude-mem observer & other background tooling
+      for (const line of text.split('\n')) {
+        const s = line.trim()
+        if (!s) continue
+        let ev
+        try { ev = JSON.parse(s) } catch { continue }
+        const m = ev && ev.message
+        if (!m || typeof m !== 'object') continue
+        const u = m.usage
+        if (!u || typeof u !== 'object') continue
+        yield {
+          id: m.id || null,
+          sid: ev.sessionId || null,
+          ts: ev.timestamp || ev.ts || null,
+          input: Number(u.input_tokens) || 0,
+          output: Number(u.output_tokens) || 0,
+          cacheCreate: Number(u.cache_creation_input_tokens) || 0,
+          cacheRead: Number(u.cache_read_input_tokens) || 0,
+          file: rel,
+        }
+      }
+    }
+  },
+}
+
+/**
+ * Pull local usage and slice it into the four windows of raw pillars.
+ * Deterministic given (adapter output, now). Inject `now`/`root`/`adapter` for tests.
+ * Returns { platform, root, generatedAt, files, totalMessages, windows:[{window,pillars,messages}] }.
+ */
+export async function tokenpull({ adapter = claudeAdapter, root, now } = {}) {
+  const r = root || adapter.defaultRoot()
+  const nowMs = now == null ? Date.now() : (typeof now === 'number' ? now : Date.parse(now))
+
+  // Dedup by (session_id, message_id), keeping the FINAL snapshot — matches
+  // token-dashboard: Claude Code writes 2-3 partial→final lines per response with
+  // the same message.id; only the final tally matches billing. No-id records each
+  // get a unique synthetic key so they always count.
+  const seen = new Map()
+  const files = new Set()
+  let noId = 0
+  for await (const msg of adapter.messages(r)) {
+    const key = msg.sid && msg.id ? `${msg.sid}|${msg.id}` : (msg.id || `__noid_${noId++}`)
+    seen.set(key, msg) // keep-last (final snapshot wins)
+    if (msg.file) files.add(msg.file)
+  }
+  const msgs = [...seen.values()]
+
+  const windows = WINDOWS.map((w) => {
+    const cutoff = w.days === Infinity ? -Infinity : nowMs - w.days * DAY_MS
+    const inWin = msgs.filter((m) => {
+      if (w.days === Infinity) return true
+      const t = m.ts ? Date.parse(m.ts) : NaN
+      return Number.isFinite(t) && t >= cutoff && t <= nowMs
+    })
+    const pillars = inWin.reduce(
+      (a, m) => ({ input: a.input + m.input, output: a.output + m.output, cacheCreate: a.cacheCreate + m.cacheCreate, cacheRead: a.cacheRead + m.cacheRead }),
+      { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 },
+    )
+    return { window: w.key, pillars, messages: inWin.length }
+  })
+
+  // Auto-detect background tooling we excluded → report it (the MCP "asks" by telling).
+  let excludedTooling = []
+  try {
+    const top = await readdir(r, { withFileTypes: true })
+    excludedTooling = top.filter((d) => d.isDirectory() && EXCLUDE_TOOLING.test(d.name)).map((d) => d.name)
+  } catch { /* ignore */ }
+
+  return {
+    platform: adapter.platform,
+    root: r,
+    generatedAt: new Date(nowMs).toISOString(),
+    files: files.size,
+    totalMessages: msgs.length,
+    excludedTooling,
+    windows,
+  }
+}
+
+// ── Codex ──────────────────────────────────────────────────────────────────
+// Logs at ~/.codex/sessions/**/rollout-*.jsonl (+ archived_sessions). Token usage is
+// on `payload.type=='token_count'` lines; `payload.info.last_token_usage` is the
+// per-turn delta. Codex `input_tokens` is INCLUSIVE of cached, so the combined input to
+// split = input_tokens − cached_input_tokens (= ccusage's inputTokens, verified ~1%).
+// The input/cacheCreate split is WINDOW-level (estInput = output × io_ratio), so Codex
+// has its own pull (tokenpullCodex) instead of the per-message claude pipeline.
+export const codexAdapter = {
+  platform: 'codex',
+  defaultRoot: () => join(homedir(), '.codex'),
+  async *records(root) {
+    for (const sub of ['sessions', 'archived_sessions']) {
+      for await (const path of _walkJsonl(join(root, sub))) {
+        let text
+        try { text = await readFile(path, 'utf8') } catch { continue }
+        const rel = path.startsWith(root) ? path.slice(root.length + 1) : path
+        // Apply the same background-tooling exclusion as the Claude adapter — skips
+        // memory plugins / observers running under the Codex account.
+        if (EXCLUDE_TOOLING.test(rel)) continue
+        for (const line of text.split('\n')) {
+          if (!line.includes('"token_count"')) continue
+          let ev
+          try { ev = JSON.parse(line) } catch { continue }
+          const p = ev && ev.payload
+          if (!p || p.type !== 'token_count') continue
+          const u = (p.info || {}).last_token_usage || {}
+          const inputIncl = Number(u.input_tokens) || 0
+          const cached = Number(u.cached_input_tokens) || 0
+          yield {
+            ts: ev.timestamp || null,
+            output: (Number(u.output_tokens) || 0) + (Number(u.reasoning_output_tokens) || 0),
+            cacheRead: cached,
+            uncached: Math.max(0, inputIncl - cached), // (true input + cache-write), split window-level
+            file: rel,
+          }
+        }
+      }
+    }
+  },
+}
+
+/**
+ * Pull local Codex usage → the 4 windows of CANONICAL pillars (always estimated).
+ * Window-level conversion: input = floor(output × ioRatio) (Beta = operator's Claude
+ * input/output ratio; Alpha = 2.0 default), cacheCreate = max(0, uncached − input).
+ * Inject ioRatio/root/now/adapter for tests.
+ */
+export async function tokenpullCodex({ adapter = codexAdapter, root, now, ioRatio = 2.0 } = {}) {
+  const r = root || adapter.defaultRoot()
+  const nowMs = now == null ? Date.now() : (typeof now === 'number' ? now : Date.parse(now))
+  const recs = []
+  const files = new Set()
+  for await (const m of adapter.records(r)) { recs.push(m); if (m.file) files.add(m.file) }
+
+  const windows = WINDOWS.map((w) => {
+    const cutoff = w.days === Infinity ? -Infinity : nowMs - w.days * DAY_MS
+    const inWin = recs.filter((m) => {
+      if (w.days === Infinity) return true
+      const t = m.ts ? Date.parse(m.ts) : NaN
+      return Number.isFinite(t) && t >= cutoff && t <= nowMs
+    })
+    const sum = inWin.reduce(
+      (a, m) => ({ output: a.output + m.output, cacheRead: a.cacheRead + m.cacheRead, uncached: a.uncached + m.uncached }),
+      { output: 0, cacheRead: 0, uncached: 0 },
+    )
+    const input = Math.floor(sum.output * ioRatio) // estimated true input
+    const cacheCreate = Math.max(0, sum.uncached - input) // split cache-write out of the combined input
+    return { window: w.key, messages: inWin.length, pillars: { input, output: sum.output, cacheCreate, cacheRead: sum.cacheRead } }
+  })
+
+  return { platform: 'codex', root: r, generatedAt: new Date(nowMs).toISOString(), files: files.size, totalMessages: recs.length, estimated: true, ioRatio, windows }
+}
+
+/**
+ * Unified pull for ANY platform by name. Routes to the right adapter:
+ *   - 'claude' → tokenpull()
+ *   - 'codex'  → tokenpullCodex()  (requires ioRatio via opts; auto-derives from Claude if available)
+ *   - other    → tokenpull() with the adapter from ADAPTERS registry
+ *
+ * Returns the same shape as tokenpull() with an added `estimated` flag when the
+ * adapter cannot provide full cacheCreate data, and a `dataGap` string when the
+ * source's log format doesn't expose token counts at all.
+ */
+export async function tokenpullAny(platform, opts = {}) {
+  if (!platform || platform === 'claude') return tokenpull({ adapter: claudeAdapter, ...opts })
+  if (platform === 'codex') {
+    // Auto-derive io_ratio from the operator's Claude data when not explicitly provided.
+    let ioRatio = opts.ioRatio || 2.0
+    if (!opts.ioRatio) {
+      try {
+        const c = await tokenpull({ adapter: claudeAdapter })
+        const all = c.windows.find((w) => w.window === 'all')
+        if (all && all.pillars.output > 0) ioRatio = all.pillars.input / all.pillars.output
+      } catch { /* no Claude data → Alpha 2.0 */ }
+    }
+    return tokenpullCodex({ ioRatio, ...opts })
+  }
+  const adapter = ADAPTERS[platform]
+  if (!adapter) throw new Error(`Unknown platform "${platform}". Valid platforms: claude, codex, ${Object.keys(ADAPTERS).join(', ')}`)
+  const result = await tokenpull({ adapter, ...opts })
+  // Surface adapter-level flags
+  if (adapter.estimated) result.estimated = true
+  if (adapter.dataGap)   result.dataGap   = adapter.dataGap
+  if (adapter.setupNote) result.setupNote = adapter.setupNote
+  return result
+}