sigrank 0.0.181 → 0.0.183

package/README.md

@@ -332,28 +332,29 @@ Verifier numbers (ccusage/tokscale for codex) show **raw uncached input** (`inpu
 
 ## Platform adapters
 
-All adapters are token-only (no message content, no cost fields, no credentials).
-
-| Platform           | Path                                           | Notes                                                           |
-| ------------------ | ---------------------------------------------- | --------------------------------------------------------------- |
-| Claude Code        | ✅ `~/.claude/projects`                        | Native; dedup by `(session_id, message_id)`; subagents included |
-| Codex              | ✅ `~/.codex/sessions`                         | Estimated input via `io_ratio`; verified vs ccusage             |
-| Devin CLI          | ✅ `~/.local/share/devin/cli/sessions.db`      | Estimated input via `io_ratio`; SQLite; same split as Codex     |
-| Amp                | ✅ `~/.local/share/amp/threads`                | Full 4-pillar; per-message                                      |
-| Kimi               | ✅ `~/.kimi/sessions`                          | Full 4-pillar; `StatusUpdate` lines only                        |
-| pi-agent           | ✅ `~/.pi/agent/sessions`                      | Full 4-pillar; per-message JSONL                                |
-| OpenClaw           | ✅ `~/.openclaw`                               | Full 4-pillar; per-message JSONL                                |
-| Droid              | ✅ `~/.factory/sessions/*.settings.json`       | Full 4-pillar; thinking→output                                  |
-| Codebuff           | ✅ `~/.config/manicode`                        | Full 4-pillar; `chat-messages.json`                             |
-| Hermes             | ✅ `~/.hermes/state.db`                        | Full 4-pillar; SQLite; reasoning→output                         |
-| Kilo               | ✅ `~/.local/share/kilo/kilo.db`               | Full 4-pillar; SQLite                                           |
-| Qwen               | ✅ `~/.qwen/projects`                          | `cacheCreate=0` estimated; thought→output                       |
-| Goose              | ✅ `~/.local/share/goose/sessions/sessions.db` | `cacheCreate=cacheRead=0` estimated; SQLite                     |
-| Gemini CLI         | ✅ `~/.gemini/tmp`                             | `cacheCreate=0` estimated; cache extracted from input field     |
-| GitHub Copilot CLI | ✅ `~/.copilot/otel`                           | OTel JSONL; requires `COPILOT_OTEL_ENABLED=true`                |
-| OpenCode           | ⚠️ `~/.local/share/opencode`                   | Raw token counts not persisted in log format                    |
-| Cursor             | 🔜                                             | Chat log path TBD                                               |
-| Windsurf           | 🔜                                             | Session logs at `~/.codeium/windsurf/`                          |
+All adapters are token-only (no message content, no cost fields, no credentials). The table below is regenerated from the adapter file headers in `adapters/index.mjs` + `adapters/tokenpull.mjs` so the path, pillar shape, and notes match the actual code (a prior revision had drifted on Qwen/Codex/Copilot).
+
+| Platform           | Path                                           | Pillar shape & notes                                                                                              |
+| ------------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| Claude Code        | ✅ `~/.claude/projects` (recursive, incl. `subagents/`) | Native 4-pillar; dedup by `(session_id, message_id)` — final snapshot wins                                  |
+| Codex              | ✅ `~/.codex/sessions` (+ `archived_sessions`) | `input_tokens` incl. cached → `input` + `cacheCreate` split window-level via `io_ratio`; `cacheRead` native (`cached_input_tokens`); `reasoning_output`→output; verified vs ccusage (~1%) |
+| Devin CLI          | ✅ `~/.local/share/devin/cli/sessions.db`      | SQLite; same `io_ratio` split as Codex (Alpha 2.0 default); `cacheRead` native                                   |
+| Amp                | ✅ `~/.local/share/amp/threads`                | Native 4-pillar; per-message                                                                                      |
+| Kimi               | ✅ `~/.kimi/sessions`                          | Native 4-pillar; `StatusUpdate` lines only                                                                        |
+| pi-agent           | ✅ `~/.pi/agent/sessions`                      | Native 4-pillar; per-message JSONL                                                                                |
+| OpenClaw           | ✅ `~/.openclaw`                               | Native 4-pillar; per-message JSONL                                                                                |
+| Droid              | ✅ `~/.factory/sessions/*.settings.json`       | Native 4-pillar; `thinking_tokens`→output                                                                         |
+| Codebuff           | ✅ `~/.config/manicode`                        | Native 4-pillar; `chat-messages.json`                                                                             |
+| Hermes             | ✅ `~/.hermes/state.db`                        | Native 4-pillar; SQLite; `reasoning_tokens`→output                                                                |
+| Kilo               | ✅ `~/.local/share/kilo/kilo.db`               | Native 4-pillar; SQLite                                                                                            |
+| Qwen               | ✅ `~/.qwen/projects`                          | Estimated (`cacheCreate=0` — no field in logs); `cacheRead` from `cachedContentTokenCount`; `thoughtsTokenCount`→output |
+| Goose              | ✅ `~/.local/share/goose/sessions/sessions.db` (or `$GOOSE_PATH_ROOT/data/sessions/sessions.db`) | Estimated (`cacheCreate=cacheRead=0` — no cache fields); reasoning = `total−input−output`→output; cumulative-column dedup by session id |
+| Gemini CLI         | ✅ `~/.gemini/tmp`                             | Estimated (`cacheCreate=0`); `cacheRead` from `cached` field; `thought`→output; `input` = `input−cached` (fresh)  |
+| GitHub Copilot CLI | ✅ `~/.copilot/otel`                           | Native 4-pillar (OTel spans: `llm.token_count.{prompt,completion,cache_creation,cache_read}`); requires `COPILOT_OTEL_ENABLED=true` + `COPILOT_OTEL_EXPORTER_TYPE=file` set **before** session start |
+| OpenCode           | ⚠️ `~/.local/share/opencode`                   | Data gap — logs store `cost:0` and derive tokens via LiteLLM at runtime; raw token counts not persisted. No pillars readable with current format |
+| Other (user JSON)  | ✅ `$SIGRANK_OTHER_PATH`                       | User-supplied JSON `{ "windows": { "all": {input,output,cacheCreate,cacheRead} } }`; all-time only (no timestamps) |
+| Cursor             | 🔜                                             | Chat log path TBD                                                                                                 |
+| Windsurf           | 🔜                                             | Session logs at `~/.codeium/windsurf/`                                                                            |
 
 `estimated=true` means one or more pillars are derived, not native. The server re-scores all submitted pillars authoritatively; local preview Υ is indicative only.
 

package/adapters/index.mjs

@@ -51,8 +51,11 @@ const DAY_MS = 86_400_000; // shared with tokenpull.mjs but kept local to avoid
 
 // ── File-system helpers ───────────────────────────────────────────────────────
 
-/** Recursively yield every file whose name matches `pred` under dir (skips symlink dirs). */
-async function* walkFiles(dir, pred, counter = { n: 0 }, max = 10_000) {
+/** Recursively yield every file whose name matches `pred` under dir (skips
+ *  symlink dirs, stops after `max` files). Exported so adapters/tokenpull.mjs
+ *  can reuse it instead of maintaining a second near-identical walker
+ *  (_walkJsonl) — the two had drifted on the symlink-skip + max-files guards. */
+export async function* walkFiles(dir, pred, counter = { n: 0 }, max = 10_000) {
   if (counter.n >= max) return;
   let entries;
   try {
@@ -743,7 +746,9 @@ export const hermesAdapter = {
 // Same combined-input problem as Codex: input_tokens INCLUDES cache write, so we
 // yield { ts, output, cacheRead, uncached } and let tokenpullCodex() do the
 // ioRatio split (input = output × ioRatio, cacheCreate = uncached − input).
-// ioRatio comes from Claude (Beta) or the 7:1:2 average (Alpha = 0.5).
+// ioRatio comes from Claude (Beta = operator's Claude input/output ratio) or
+// the Alpha 2.0 default (matches Codex; the "7:1:2 average → 0.5" note in a
+// prior revision was wrong — tokenpullAny defaults ioRatio to 2.0 for both).
 export const devinAdapter = {
   platform: "devin",
   defaultRoot: () => join(homedir(), ".local", "share", "devin", "cli"),
@@ -795,9 +800,22 @@ export const devinAdapter = {
 //   }
 // }
 //
-// The adapter yields one "message" per window with the summed pillars. Since
-// there's no per-message timestamp, all data lands in the "all" window only
-// (same as null-timestamp records in other adapters).
+// The adapter yields ONE message carrying the all-time pillars. The generic
+// tokenpull aggregator buckets by timestamp, and these records carry no
+// timestamp (ts: null → "all" window only, same as null-ts records in other
+// adapters). Yielding one message PER window key — as a prior version did —
+// caused the "all" total to be the SUM of every window entry (all + 30d + 7d
+// …), i.e. a multi-count. This is the only user-facing wrong-number bug in
+// ingestion: an operator who filled in all four windows saw an "all" Υ
+// computed from 2–4× the real pillars.
+//
+// Fix: yield exactly one record. If the JSON has an "all" entry, use it
+// verbatim; otherwise sum the provided windows into a synthetic all-time
+// total. The 7d/30d/90d entries are accepted (so the file format stays
+// forward-compatible) but are NOT yielded as separate records — the generic
+// aggregator has no way to route a timestamp-less record into a bounded
+// window, so emitting them would only re-introduce the overcount. An operator
+// who wants windowed data must use a real adapter that carries timestamps.
 export const otherAdapter = {
   platform: "other",
   defaultRoot: () => process.env.SIGRANK_OTHER_PATH || "",
@@ -822,23 +840,38 @@ export const otherAdapter = {
       throw new Error(`other adapter: invalid JSON in ${filePath}`);
     }
     const windows = data.windows || {};
-    for (const [win, pillars] of Object.entries(windows)) {
-      const input = Number(pillars.input || 0);
-      const output = Number(pillars.output || 0);
-      const cacheCreate = Number(pillars.cacheCreate || pillars.cache_create || 0);
-      const cacheRead = Number(pillars.cacheRead || pillars.cache_read || 0);
-      if (input + output + cacheCreate + cacheRead === 0) continue;
-      yield {
-        id: `other:${win}`,
-        sid: `other-${win}`,
-        ts: null, // no timestamp → lands in "all" window only
-        input,
-        output,
-        cacheCreate,
-        cacheRead,
-        file: filePath,
-      };
+    const norm = (p) => ({
+      input: Number(p?.input || 0),
+      output: Number(p?.output || 0),
+      cacheCreate: Number(p?.cacheCreate || p?.cache_create || 0),
+      cacheRead: Number(p?.cacheRead || p?.cache_read || 0),
+    });
+    let all;
+    if (windows.all) {
+      // Explicit all-time entry → use verbatim (do NOT add 7d/30d/90d on top).
+      all = norm(windows.all);
+    } else {
+      // No "all" key → fold the provided windows into a synthetic all-time.
+      all = { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+      for (const pillars of Object.values(windows)) {
+        const n = norm(pillars);
+        all.input += n.input;
+        all.output += n.output;
+        all.cacheCreate += n.cacheCreate;
+        all.cacheRead += n.cacheRead;
+      }
     }
+    if (all.input + all.output + all.cacheCreate + all.cacheRead === 0) return;
+    yield {
+      id: `other:all`,
+      sid: `other-all`,
+      ts: null, // no timestamp → lands in "all" window only
+      input: all.input,
+      output: all.output,
+      cacheCreate: all.cacheCreate,
+      cacheRead: all.cacheRead,
+      file: filePath,
+    };
   },
 };
 

package/adapters/tokenpull.mjs

@@ -15,13 +15,13 @@
  * the same { platform, defaultRoot(), messages(root) } contract — Claude is just the first.
  */
 
-import { readdir, readFile, lstat } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { execFile } from "node:child_process";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { ADAPTERS } from "./index.mjs";
+import { ADAPTERS, walkFiles } from "./index.mjs";
 
 const DAY_MS = 86_400_000;
 
@@ -87,34 +87,26 @@ const MAX_JSONL_FILES = Number(process.env.SIGRANK_MAX_JSONL_FILES) || 10_000;
  *  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). */
+ *  after MAX_JSONL_FILES files (prevents OOM on pathological trees).
+ *
+ *  Pass 2: now a thin sorted wrapper over the shared walkFiles() from
+ *  adapters/index.mjs so the two walkers can't drift on the symlink-skip +
+ *  max-files guards again. The sort (entries within each directory) is preserved
+ *  by sorting the yielded paths; walkFiles already recurses in readdir order. */
 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;
-    }
+  // walkFiles yields in readdir order; we collect + sort to keep the
+  // deterministic ordering the previous implementation guaranteed.
+  const paths = [];
+  for await (const p of walkFiles(
+    dir,
+    (n) => n.endsWith(".jsonl"),
+    _counter,
+    MAX_JSONL_FILES,
+  )) {
+    paths.push(p);
   }
+  paths.sort((a, b) => (a < b ? -1 : 1));
+  for (const p of paths) yield p;
 }
 
 /**

package/analytics/cascade.mjs

@@ -61,24 +61,129 @@ export function cascade({ input, output, cacheCreate, cacheRead }) {
     leverage: round(leverage, 1),
     velocity: round(velocity, 3),
     dev10x: round(dev10x, 2),
-    class: classify(yield_, dev10x),
+    class: classify(total),
     mode: detectMode({ input: i, output: o, cacheCreate: cw, cacheRead: cr }),
   };
   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";
+/**
+ * CLASS_TIERS — the 8 base tier names (K.01–K.08) for display: glyph, color,
+ * meaning. SINGLE SOURCE OF TRUTH for tier-level display info.
+ *
+ * The permanent class is an EXPERIENCE ladder keyed on TOTAL TOKENS. Each tier
+ * has 3 sub-stages (I/II/III) — 24 stages total. The 24 thresholds live in
+ * RS05_CLASS_THRESHOLDS below. classify() returns the full sub-stage string
+ * (e.g. "REFINER II"). Use tierOf() to extract the base tier name.
+ *
+ * TRANSMITTER is NOT on this ladder — it is a temporary peak badge (RS.08).
+ * The client does not evaluate the badge (owner is still calibrating it);
+ * the server does it on read.
+ *
+ * Mirrors the server's canon-ids.ts CLASS_TIERS (display) + ruleset.ts
+ * RS05_CLASS_THRESHOLDS (thresholds). Order is descending (ARCH+ → IGNITER).
+ */
+export const CLASS_TIERS = [
+  "ARCH+",
+  "ARCH",
+  "POWER",
+  "BASE",
+  "SEEKER",
+  "REFINER",
+  "BEARER",
+  "IGNITER",
+];
+
+/**
+ * SIGNAL_CLASSES — the full 24 sub-stage names (8 tiers × 3 sub-stages I/II/III).
+ * Mirrors the server's SIGNAL_CLASSES set in lib/board/mappers.ts. The API
+ * returns class_tier as one of these 24 values. classify() returns one of these
+ * (or UNCLASSED). Use this for schema enums and validation.
+ */
+export const SIGNAL_CLASSES = [
+  "ARCH+ I", "ARCH+ II", "ARCH+ III",
+  "ARCH I", "ARCH II", "ARCH III",
+  "POWER I", "POWER II", "POWER III",
+  "BASE I", "BASE II", "BASE III",
+  "SEEKER I", "SEEKER II", "SEEKER III",
+  "REFINER I", "REFINER II", "REFINER III",
+  "BEARER I", "BEARER II", "BEARER III",
+  "IGNITER I", "IGNITER II", "IGNITER III",
+];
+
+/**
+ * RS05_CLASS_THRESHOLDS — 24 total-token breakpoints (8 tiers × 3 sub-stages).
+ * Mirrors the server's lib/analytics/ruleset.ts RS05_CLASS_THRESHOLDS exactly.
+ * Calibrated from the HCM cut (1,626 operators) using target distribution
+ * (Option C): IGNITER 10%, BEARER 12.5%, REFINER 15%, SEEKER 22.5%, BASE 20%,
+ * POWER 15%, ARCH 5%, ARCH+ 0% (aspirational). Each tier split into 3
+ * equal-population sub-stages. Update this one constant to stay in parity
+ * when the owner tweaks server-side.
+ */
+export const RS05_CLASS_THRESHOLDS = [
+  { class: "ARCH+ I", totalMin: 7068201104627 },
+  { class: "ARCH+ II", totalMin: 7068201104627 },
+  { class: "ARCH+ III", totalMin: 7068201104627 },
+  { class: "ARCH I", totalMin: 186207267611 },
+  { class: "ARCH II", totalMin: 98543134083 },
+  { class: "ARCH III", totalMin: 68766193943 },
+  { class: "POWER I", totalMin: 39958782379 },
+  { class: "POWER II", totalMin: 26955905621 },
+  { class: "POWER III", totalMin: 19141226889 },
+  { class: "BASE I", totalMin: 13960345961 },
+  { class: "BASE II", totalMin: 10189224970 },
+  { class: "BASE III", totalMin: 7747041813 },
+  { class: "SEEKER I", totalMin: 5446673659 },
+  { class: "SEEKER II", totalMin: 4014577247 },
+  { class: "SEEKER III", totalMin: 2961798768 },
+  { class: "REFINER I", totalMin: 2358346840 },
+  { class: "REFINER II", totalMin: 1845750357 },
+  { class: "REFINER III", totalMin: 1334876308 },
+  { class: "BEARER I", totalMin: 984078167 },
+  { class: "BEARER II", totalMin: 714619043 },
+  { class: "BEARER III", totalMin: 431702990 },
+  { class: "IGNITER I", totalMin: 216393332 },
+  { class: "IGNITER II", totalMin: 88999166 },
+  { class: "IGNITER III", totalMin: 0 },
+];
+
+/** The degenerate-case class returned when totalTokens is null/undefined
+ *  (all-zero / empty session). Distinct from IGNITER III (which is a real
+ *  low-experience tier) so callers can tell "no data" from "bottom tier". */
+export const UNCLASSED = "UNCLASSED";
+
+/** Extract the base tier name from a sub-stage string (e.g. "ARCH+ I" → "ARCH+").
+ *  Mirrors the server's tierOf() in components/sigrank/types.ts. Returns the
+ *  input as-is if it's not a sub-stage string (e.g. UNCLASSED). */
+export function tierOf(cls) {
+  if (cls === UNCLASSED || cls == null) return cls;
+  const parts = String(cls).split(" ");
+  if (parts.length >= 2 && ["I", "II", "III"].includes(parts[parts.length - 1])) {
+    return parts.slice(0, -1).join(" ");
+  }
+  return cls;
+}
+
+/** Extract the sub-stage from a sub-stage string (e.g. "ARCH+ I" → "I").
+ *  Mirrors the server's stageOf(). Returns null for non-sub-stage strings. */
+export function stageOf(cls) {
+  if (cls === UNCLASSED || cls == null) return null;
+  const parts = String(cls).split(" ");
+  const stage = parts[parts.length - 1];
+  return stage === "I" || stage === "II" || stage === "III" ? stage : null;
+}
+
+/** Classify an operator's experience stage from total tokens (input + output +
+ *  cacheCreate + cacheRead). Descending first-match-wins scan over
+ *  RS05_CLASS_THRESHOLDS — mirrors the server's assignClass(totalTokens).
+ *  Returns a full sub-stage string (e.g. "REFINER II") or UNCLASSED. */
+export function classify(totalTokens) {
+  if (totalTokens == null || !Number.isFinite(totalTokens)) return UNCLASSED;
+  for (const t of RS05_CLASS_THRESHOLDS) {
+    if (totalTokens >= t.totalMin) return t.class;
+  }
+  return "IGNITER III";
 }
 
 /**

package/identity/keystore.mjs

@@ -23,6 +23,7 @@ import {
   copyFileSync,
 } from "node:fs";
 import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { agentVersion } from "../lib/pkg-version.mjs";
 
 const DIR = join(homedir(), ".sigrank-mcp");
 const PATH = join(DIR, "identity.json");
@@ -32,18 +33,6 @@ const MAX_BACKUPS = 5;
 /** SPKI DER prefix length for an ed25519 public key (12 bytes before the raw 32). */
 const SPKI_PREFIX_LEN = 12;
 
-/** Resolve this package's version for the agent_version stamp (best-effort). */
-function agentVersion() {
-  try {
-    const pkg = JSON.parse(
-      readFileSync(new URL("./package.json", import.meta.url), "utf-8"),
-    );
-    return `sigrank-mcp/${pkg.version}`;
-  } catch {
-    return "sigrank-mcp";
-  }
-}
-
 export function keystorePath() {
   return PATH;
 }

package/lib/constants.mjs

@@ -0,0 +1,111 @@
+// lib/constants.mjs — repo-wide constants that were previously inlined as
+// literals across multiple files. Centralizing them here means a version bump
+// or a client-map update lands in exactly one place.
+//
+//   TERMS_VERSION / PRIVACY_VERSION — embedded in every enroll + submit
+//     payload (tools/enroll.mjs, tools/submit-paste.mjs,
+//     tools/tokenpull-submit.mjs, submit/index.mjs). They were inlined as
+//     "2026-07-21" in four files; a terms rev would have required finding
+//     and editing all four. Now: one export, imported everywhere.
+//
+//   TOKSCALE_CLIENT_MAP — maps tokscale's raw client names to our platform
+//     IDs. Was duplicated verbatim in tools/index.mjs and
+//     tools/tokscale-breakdown.mjs (and again in tokscale_analytics.mjs);
+//     the three copies had already started to drift. One export here.
+//
+//   isRankedAck — the "actually on the board" predicate (verified + persisted).
+//     Was inlined as `ack.verification_tier === "verified" && ack.persisted
+//     === true` in submit-paste, tokenpull-submit, and submit/index.mjs, with
+//     tokenpull-submit's multi-platform branch using a DIFFERENT looser
+//     predicate (`ack?.ranked ?? ack?.accepted ?? false`). One predicate here
+//     closes that loophole so every submit path agrees on what "ranked" means.
+
+/** Current Terms of Service version the client attests to. */
+export const TERMS_VERSION = "2026-07-21";
+
+/** Current Privacy Policy version the client attests to. */
+export const PRIVACY_VERSION = "2026-07-21";
+
+/**
+ * The leaderboard sort metric the client requests from the server. Every
+ * leaderboard fetch site (tools/get-leaderboard.mjs, presentation/cli.mjs
+ * fetchBoard, presentation/tui.mjs, compare-self / optimize-efficiency /
+ * get-best-operator / compare-operators) MUST use this value — the server
+ * ranks by `yield_` and a different metric string would either 400 or return
+ * an unsorted board. Centralized here so a future metric rename lands in one
+ * place; the contract test in __tests__/contract/leaderboard-metric-contract.test.mjs
+ * guards against intra-repo drift and (in CI) cross-repo drift vs sigrank-app.
+ */
+export const LEADERBOARD_METRIC = "yield_";
+
+/**
+ * Map a raw tokscale `client` string to our canonical platform ID.
+ * Values mapped to `null` are skipped (synthetic / non-attributable).
+ * Values mapped to `"other"` have no native adapter and bucket together.
+ */
+export const TOKSCALE_CLIENT_MAP = {
+  claude: "claude",
+  codex: "codex",
+  "devin-cli": "devin",
+  "devin-desktop": "devin",
+  gemini: "gemini",
+  amp: "amp",
+  kimi: "kimi",
+  qwen: "qwen",
+  goose: "goose",
+  kilo: "kilo",
+  kilocode: "kilo",
+  hermes: "hermes",
+  droid: "droid",
+  codebuff: "codebuff",
+  copilot: "copilot",
+  opencode: "opencode",
+  openclaw: "openclaw",
+  pi: "pi",
+  cursor: "other",
+  roocode: "other",
+  mux: "other",
+  crush: "other",
+  antigravity: "other",
+  "antigravity-cli": "other",
+  zed: "other",
+  kiro: "other",
+  trae: "other",
+  warp: "other",
+  cline: "other",
+  gjc: "other",
+  grok: "other",
+  jcode: "other",
+  commandcode: "other",
+  micode: "other",
+  junie: "other",
+  zcode: "other",
+  opencodereview: "other",
+  codebuddy: "other",
+  workbuddy: "other",
+  synthetic: null,
+};
+
+/**
+ * The "actually on the board" predicate. A submission is ranked only when the
+ * server returns HTTP ok AND verification_tier === "verified" AND persisted
+ * === true. An unenrolled/revoked device gets 202 but is NEVER ranked.
+ *
+ * Use this everywhere a submit path decides whether to surface `ranked: true`.
+ * The previous tokenpull-submit multi-platform branch used a looser
+ * `ack?.ranked ?? ack?.accepted ?? false` which would mark a non-persisted
+ * 202 as ranked — this predicate closes that loophole.
+ *
+ * @param {{ ok: boolean }} res  the fetch Response (or { ok } shim)
+ * @param {Record<string, unknown>} ack  the parsed JSON ack body
+ * @returns {boolean}
+ */
+export function isRankedAck(res, ack) {
+  return !!(
+    res &&
+    res.ok &&
+    ack &&
+    ack.verification_tier === "verified" &&
+    ack.persisted === true
+  );
+}

package/lib/pkg-version.mjs

@@ -0,0 +1,59 @@
+// lib/pkg-version.mjs — single source of truth for the package version.
+//
+// Resolves the repo-root package.json by walking up from this module until it
+// finds the package named "sigrank". This is robust to callers in any
+// subdirectory (identity/, submit/, presentation/, tools/, scripts/) — the
+// previous per-caller `new URL("./package.json", import.meta.url)` lookups
+// resolved relative to the CALLER's own directory and hit non-existent files,
+// falling back to a bare string. The agent_version stamp rides inside the
+// SIGNED submit payload (agent.agent_version), so a wrong/missing version
+// there is a high-priority bug — it survived because no test guarded it.
+//
+// One implementation, imported everywhere. Never throws: returns "unknown" on
+// any failure so a missing/renamed package.json never breaks a submit.
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** The published package name (package.json "name"). Used to identify the
+ *  repo-root package.json unambiguously past any nested package.json. */
+const REPO_PKG_NAME = "sigrank";
+
+/** Resolve the repo-root package version (best-effort).
+ *  Returns the version string (e.g. "0.0.181") or "unknown" on any failure. */
+export function pkgVersion() {
+  try {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 20; i++) {
+      const pkgPath = join(dir, "package.json");
+      let pkg;
+      try {
+        pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      } catch {
+        // no package.json here — walk up
+        const parent = dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+        continue;
+      }
+      if (pkg.name === REPO_PKG_NAME) return pkg.version || "unknown";
+      // Found a package.json but it isn't ours (e.g. a nested dep) — keep walking.
+      const parent = dirname(dir);
+      if (parent === dir) {
+        // Reached the filesystem root without matching; use whatever we found.
+        return pkg.version || "unknown";
+      }
+      dir = parent;
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** The full agent-version stamp, e.g. "sigrank-mcp/0.0.181".
+ *  This is the value embedded in the signed payload's agent.agent_version. */
+export function agentVersion() {
+  return `sigrank-mcp/${pkgVersion()}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "0.0.181",
+  "version": "0.0.183",
   "author": "SunrisesIllNeverSee (https://github.com/SunrisesIllNeverSee)",
   "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
   "mcpName": "io.github.SunrisesIllNeverSee/sigrank-mcp",
@@ -32,6 +32,7 @@
   },
   "files": [
     "index.mjs",
+    "lib/",
     "tools/",
     "analytics/",
     "identity/",