sigrank 0.0.177 → 0.0.179

package/tools/index.mjs

@@ -0,0 +1,257 @@
+/**
+ * tools/index.mjs — the SigRank MCP tool table + dispatcher, transport-free so it can be
+ * unit-tested without spawning the stdio server.
+ *
+ * Imports individual tool modules from ./ and re-exports the TOOLS array + callTool
+ * dispatcher. Backward-compatible root import via ../tools.mjs (shim).
+ */
+
+import { ALL_PLATFORMS } from "../adapters/index.mjs";
+import { execFileAsync } from "./_helpers.mjs";
+import { buildFetch, DEFAULT_API_BASE, DEFAULT_FETCH_TIMEOUT } from "./_helpers.mjs";
+
+import { TOOL_DEF as rankPasteTool, handleRankPaste } from "./rank-paste.mjs";
+import { TOOL_DEF as getLeaderboardTool, handleGetLeaderboard } from "./get-leaderboard.mjs";
+import { TOOL_DEF as getOperatorTool, handleGetOperator } from "./get-operator.mjs";
+import { TOOL_DEF as submitPasteTool, handleSubmitPaste } from "./submit-paste.mjs";
+import { TOOL_DEF as tokenpullTool, handleTokenpull } from "./tokenpull.mjs";
+import { TOOL_DEF as tokenpullSubmitTool, handleTokenpullSubmit } from "./tokenpull-submit.mjs";
+import { TOOL_DEF as rankWindowsTool, handleRankWindows } from "./rank-windows.mjs";
+import { TOOL_DEF as watchTokenpullTool, handleWatchTokenpull } from "./watch-tokenpull.mjs";
+import { TOOL_DEF as tokenpullCompareTool, handleTokenpullCompare } from "./tokenpull-compare.mjs";
+import { TOOL_DEF as enrollTool, handleEnroll } from "./enroll.mjs";
+import { TOOL_DEF as submitVerifiedTool, handleSubmitVerified } from "./submit-verified.mjs";
+import { TOOL_DEF as simulateChangeTool, handleSimulateChange } from "./simulate-change.mjs";
+import { TOOL_DEF as diagnoseCascadeTool, handleDiagnoseCascade } from "./diagnose-cascade.mjs";
+import { TOOL_DEF as suggestImprovementsTool, handleSuggestImprovements } from "./suggest-improvements.mjs";
+import { TOOL_DEF as selfImproveTool, handleSelfImprove } from "./self-improve.mjs";
+import { TOOL_DEF as getBestOperatorTool, handleGetBestOperator } from "./get-best-operator.mjs";
+import { TOOL_DEF as compareSelfTool, handleCompareSelf } from "./compare-self.mjs";
+import { TOOL_DEF as compareOperatorsTool, handleCompareOperators } from "./compare-operators.mjs";
+import { TOOL_DEF as describePowerUserTool, handleDescribePowerUser } from "./describe-power-user.mjs";
+import { TOOL_DEF as optimizeEfficiencyTool, handleOptimizeEfficiency } from "./optimize-efficiency.mjs";
+import { TOOL_DEF as tokscaleBreakdownTool, handleTokscaleBreakdown } from "./tokscale-breakdown.mjs";
+import { TOOL_DEF as tokscaleMarketShareTool, handleTokscaleMarketShare } from "./tokscale-market-share.mjs";
+import { TOOL_DEF as tokscaleDeveloperProfileTool, handleTokscaleDeveloperProfile } from "./tokscale-developer-profile.mjs";
+import { TOOL_DEF as tokscaleModelTrendsTool, handleTokscaleModelTrends } from "./tokscale-model-trends.mjs";
+import { TOOL_DEF as tokscaleCostAnalysisTool, handleTokscaleCostAnalysis } from "./tokscale-cost-analysis.mjs";
+import { TOOL_DEF as tokscaleDeviceProfileTool, handleTokscaleDeviceProfile } from "./tokscale-device-profile.mjs";
+import { TOOL_DEF as tokscaleMcpUsageTool, handleTokscaleMcpUsage } from "./tokscale-mcp-usage.mjs";
+import { TOOL_DEF as tokscaleCompetitiveIntelTool, handleTokscaleCompetitiveIntel } from "./tokscale-competitive-intel.mjs";
+
+export { DEFAULT_API_BASE, DEFAULT_FETCH_TIMEOUT };
+
+export const TOOLS = [
+  rankPasteTool,
+  getLeaderboardTool,
+  getOperatorTool,
+  submitPasteTool,
+  tokenpullTool,
+  tokenpullSubmitTool,
+  rankWindowsTool,
+  watchTokenpullTool,
+  tokenpullCompareTool,
+  enrollTool,
+  submitVerifiedTool,
+  simulateChangeTool,
+  diagnoseCascadeTool,
+  suggestImprovementsTool,
+  selfImproveTool,
+  getBestOperatorTool,
+  compareSelfTool,
+  compareOperatorsTool,
+  describePowerUserTool,
+  optimizeEfficiencyTool,
+  tokscaleBreakdownTool,
+  tokscaleMarketShareTool,
+  tokscaleDeveloperProfileTool,
+  tokscaleModelTrendsTool,
+  tokscaleCostAnalysisTool,
+  tokscaleDeviceProfileTool,
+  tokscaleMcpUsageTool,
+  tokscaleCompetitiveIntelTool,
+];
+
+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,
+};
+
+/** Run `tokscale models --json` and return the list of our platform names. */
+async function _tokscaleDetectClients() {
+  const raw = await execFileAsync("tokscale", ["models", "--json"], 60000);
+  const data = JSON.parse(raw);
+  const entries = Array.isArray(data?.entries)
+    ? data.entries
+    : Array.isArray(data)
+      ? data
+      : [];
+  if (!entries.length) return [];
+  const clients = new Set();
+  for (const e of entries) {
+    if (!e || !e.client) continue;
+    if (e.model === "<synthetic>" || e.model === "unknown") continue;
+    const input = Number(e.input) || 0;
+    const output = Number(e.output) || 0;
+    if (input + output === 0) continue;
+    const platform = TOKSCALE_CLIENT_MAP[e.client];
+    if (platform === null) continue; // synthetic → skip
+    clients.add(platform || "other");
+  }
+  return [...clients];
+}
+
+/** Pull a specific set of platforms in parallel, filter to active ones. */
+async function _pullExplicit(platforms, opts = {}) {
+  const settled = await Promise.allSettled(
+    platforms.map((p) => callTool("tokenpull", { platform: p }, opts)),
+  );
+  const active = settled
+    .filter((r) => r.status === "fulfilled" && r.value)
+    .map((r) => r.value)
+    .filter((d) =>
+      (d.windows || []).some(
+        (w) => (w.pillars?.input ?? 0) + (w.pillars?.output ?? 0) > 0,
+      ),
+    );
+  const rank = (p) =>
+    p === "claude" ? -2 : p === "codex" ? -1 : ALL_PLATFORMS.indexOf(p);
+  active.sort((a, b) => rank(a.platform) - rank(b.platform));
+  return active;
+}
+
+// ── Shared active-platform loader ───────────────────────────────────────────
+// THE single data path for "show my cascade across platforms" — used by `me`,
+// `watch`, and the TUI Dashboard so they can't drift apart again. Pulls each
+// target platform via the tokenpull tool (enriched: pillars + cascade + card),
+// keeps only platforms with real local data, and sorts claude → codex → rest.
+// Pass `platforms` to scope it (e.g. ['claude'] for a fast first paint).
+export async function pullActivePlatforms({ platforms } = {}, opts = {}) {
+  // If the caller specified explicit platforms, use those.
+  if (platforms && platforms.length) {
+    return _pullExplicit(platforms, opts);
+  }
+  // Auto-detect: run tokscale once to discover all active clients, then pull
+  // only those. This is much faster than trying all 17 adapters (most fail
+  // silently on a machine that doesn't have that tool installed).
+  //
+  // Flow: tokscale surfaces ALL clients → map to our platform names →
+  // ccusage is primary for Claude (more accurate) → other platforms use
+  // their adapters. Anything in tokscale NOT in ccusage gets included.
+  const detected = await _tokscaleDetectClients().catch(() => null);
+  if (detected && detected.length > 0) {
+    return _pullExplicit(detected, opts);
+  }
+  // Fallback: tokscale not installed or failed → try all adapters (old behavior)
+  return _pullExplicit(ALL_PLATFORMS, opts);
+}
+
+export async function callTool(name, args, opts = {}) {
+  const { apiBase, doFetch, fetchJson } = buildFetch(opts);
+  const ctx = {
+    apiBase,
+    doFetch,
+    fetchJson,
+    opts,
+    callTool: (n, a) => callTool(n, a, opts),
+  };
+
+  switch (name) {
+    case "rank_paste":
+      return handleRankPaste(args);
+    case "get_leaderboard":
+      return handleGetLeaderboard(args, ctx);
+    case "get_operator":
+      return handleGetOperator(args, ctx);
+    case "submit_paste":
+      return handleSubmitPaste(args, ctx);
+    case "tokenpull":
+      return handleTokenpull(args, ctx);
+    case "tokenpull_submit":
+      return handleTokenpullSubmit(args, ctx);
+    case "rank_windows":
+      return handleRankWindows(args);
+    case "watch_tokenpull":
+      return handleWatchTokenpull(args, ctx);
+    case "tokenpull_compare":
+      return handleTokenpullCompare(args, ctx);
+    case "enroll":
+      return handleEnroll(args, ctx);
+    case "submit_verified":
+      return handleSubmitVerified(args, ctx);
+    case "simulate_change":
+      return handleSimulateChange(args);
+    case "diagnose_cascade":
+      return handleDiagnoseCascade(args);
+    case "suggest_improvements":
+      return handleSuggestImprovements(args);
+    case "self_improve":
+      return handleSelfImprove(args, ctx);
+    case "get_best_operator":
+      return handleGetBestOperator(args, ctx);
+    case "compare_self":
+      return handleCompareSelf(args, ctx);
+    case "compare_operators":
+      return handleCompareOperators(args, ctx);
+    case "describe_power_user":
+      return handleDescribePowerUser();
+    case "optimize_efficiency":
+      return handleOptimizeEfficiency(args, ctx);
+    case "tokscale_breakdown":
+      return handleTokscaleBreakdown(args);
+    case "tokscale_market_share":
+      return handleTokscaleMarketShare();
+    case "tokscale_developer_profile":
+      return handleTokscaleDeveloperProfile();
+    case "tokscale_model_trends":
+      return handleTokscaleModelTrends();
+    case "tokscale_cost_analysis":
+      return handleTokscaleCostAnalysis();
+    case "tokscale_device_profile":
+      return handleTokscaleDeviceProfile();
+    case "tokscale_mcp_usage":
+      return handleTokscaleMcpUsage();
+    case "tokscale_competitive_intel":
+      return handleTokscaleCompetitiveIntel(args);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}

package/tools/optimize-efficiency.mjs

@@ -0,0 +1,160 @@
+/**
+ * tools/optimize-efficiency.mjs — optimize_efficiency tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+import {
+  _improvementSuggestion,
+  _competitiveLayer,
+  _competitiveSummary,
+} from "./_framing.mjs";
+
+export const TOOL_DEF = {
+  name: "optimize_efficiency",
+  description:
+    "Returns actionable suggestions for improving your token cascade efficiency, tied to your current metrics. Accepts either a codename (fetches from board) or raw token pillars (computes locally). Returns: your current metrics, ranked efficiency suggestions tied to cascade shape (increase cache reuse, reduce input, increase output), and references to power-user practices. Use this when users ask 'how can I use AI more efficiently?' or 'reduce token burn' or 'optimize token usage' or 'stop tokenmaxxing'. Intent: OPTIMIZE_EFFICIENCY (Informational + Transactional).",
+  annotations: { title: "Optimize efficiency", ...ANNOTATIONS.readOnlyHint, ...ANNOTATIONS.idempotentHint },
+  inputSchema: {
+    type: "object",
+    properties: {
+      codename: {
+        type: "string",
+        description:
+          "Your codename on the SigRank leaderboard. If provided, fetches your live profile from the board.",
+      },
+      text: {
+        type: "string",
+        description:
+          'Alternative: raw token pillars to score locally (ccusage JSON or "input output cacheCreate cacheRead"). Use this if you are not on the board yet.',
+      },
+    },
+    description:
+      "Provide either `codename` (to fetch from the board) or `text` (to score locally). At least one is required.",
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      your_metrics: {
+        type: "object",
+        description: "Your current cascade metrics",
+        properties: {
+          yield_: { type: "number" },
+          leverage: { type: "number" },
+          velocity: { type: "number" },
+          class: { type: "string", enum: ["Burner", "Builder", "10xer"] },
+        },
+      },
+      suggestions: {
+        type: "array",
+        description: "Ranked efficiency suggestions",
+        items: {
+          type: "object",
+          properties: {
+            action: { type: "string", description: "What to change" },
+            why: { type: "string", description: "Why this helps your yield" },
+            power_user_practice: { type: "string", description: "The power-user practice this maps to" },
+          },
+        },
+      },
+      summary: { type: "string", description: "One-line summary of your efficiency status" },
+    },
+  },
+};
+
+export async function handleOptimizeEfficiency(args, ctx) {
+  const codename = String(args?.codename || "").trim();
+  const text = String(args?.text || "").trim();
+
+  if (!codename && !text)
+    throw new Error(
+      "optimize_efficiency requires either `codename` (to fetch from the board) or `text` (raw token pillars to score locally).",
+    );
+
+  let metrics;
+  if (codename) {
+    metrics = await ctx.fetchJson(
+      `/api/v1/operators/${encodeURIComponent(codename)}`,
+    );
+  } else {
+    if (text.length > MAX_INPUT) {
+      return { error: "input_too_large", detail: `text exceeds ${MAX_INPUT} chars.` };
+    }
+    const pillars = parsePillars(text);
+    const c = withParseWarnings(pillars, cascade(pillars));
+    metrics = {
+      codename: "you (local)",
+      yield_: c.yield,
+      leverage: c.leverage,
+      velocity: c.velocity,
+      class: c.class,
+    };
+  }
+
+  const klass = metrics.class || "Burner";
+  const l = metrics.leverage || 0;
+  const v = metrics.velocity || 0;
+  const y = metrics.yield_ || 0;
+
+  // Build ranked suggestions based on current cascade shape
+  const suggestions = [];
+
+  if (l < 5) {
+    suggestions.push({
+      action: "Increase cache reuse — reuse prompts, templates, and workflows instead of starting from scratch",
+      why: "Your leverage is " + l.toFixed(1) + "×, meaning most of your context is fresh input. Each reused cached token multiplies your yield because input² is in the denominator.",
+      power_user_practice: "Power users build template libraries and workflow patterns they invoke repeatedly, letting cached context accumulate.",
+    });
+  }
+  if (v < 1) {
+    suggestions.push({
+      action: "Increase output per session — produce more, don't just read",
+      why: "Your velocity is " + v.toFixed(2) + ", meaning you're consuming more input than producing output. Yield rewards output production.",
+      power_user_practice: "Power users maximize output per session — they ask AI to generate, transform, and produce, not just explain.",
+    });
+  }
+  if (l >= 5 && v >= 1 && klass !== "10xer") {
+    suggestions.push({
+      action: "Extend session length to compound cached context further",
+      why: "Your leverage (" + l.toFixed(1) + "×) and velocity (" + v.toFixed(2) + ") are solid. Longer sessions with consistent context will push your yield higher.",
+      power_user_practice: "Power users maintain long, context-rich sessions where the cache grows and compounds.",
+    });
+  }
+  if (suggestions.length === 0) {
+    suggestions.push({
+      action: "Maintain your cascade architecture — you're at the top tier",
+      why: "Your yield (" + y.toLocaleString() + "), leverage (" + l.toFixed(1) + "×), and velocity (" + v.toFixed(2) + ") are all strong. Keep doing what you're doing.",
+      power_user_practice: "Power users don't rest on their metrics — they experiment with new workflow patterns and measure the impact.",
+    });
+  }
+
+  const summary = `Your Υ Yield is ${y.toLocaleString()} (${klass}). ${_improvementSuggestion(klass, metrics)}`;
+
+  // Competitive layer per SHARED_DESIGN_DECISIONS.md §3/§4/§5
+  const board = await ctx.fetchJson("/api/v1/leaderboard?metric=yield_");
+  const competitive = _competitiveLayer(metrics, board);
+  const competitiveSummary = _competitiveSummary(metrics, board);
+
+  return {
+    your_metrics: {
+      yield_: y,
+      leverage: l,
+      velocity: v,
+      class: klass,
+    },
+    competitive: {
+      rank: competitive.rank,
+      total_operators: competitive.total_operators,
+      percentile: competitive.percentile,
+      class_tier: competitive.class_tier,
+      delta_from_average: competitive.delta_from_average,
+      delta_from_top: competitive.delta_from_top,
+    },
+    competitive_summary: competitiveSummary,
+    shareable_url: competitive.shareable_url,
+    suggestions,
+    summary,
+    cta: "Improve my score",
+  };
+}

package/tools/rank-paste.mjs

@@ -0,0 +1,51 @@
+/**
+ * tools/rank-paste.mjs — rank_paste tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { narrate } from "../presentation/narrate.mjs";
+import { CASCADE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "rank_paste",
+  description:
+    'Computes the SigRank yield cascade from a paste of token counts. Parses the input, runs the full cascade math locally (no network calls), and returns: Υ Yield (the headline efficiency metric, Υ = Cache Reads × Output / Input²), SNR (signal-to-noise ratio), Leverage ratio (Cr/I = cache reads divided by input), Velocity (O/I = output divided by input), 10xDEV score, operator class tier (Burner / Builder / 10xer), and a deterministic prose "card" summarizing the result in plain English. Accepts two input formats: (1) JSON object {"input":N,"output":N,"cacheCreate":N,"cacheRead":N} or (2) four whitespace-separated numbers in order: input output cacheCreate cacheRead. Returns an error if the input is malformed or has negative values. Use this for a quick one-off ranking without submitting to the board. Do NOT use this to submit your score — use submit_paste instead, which both ranks and publishes. Do NOT use this if you want to rank all four time windows at once — use rank_windows for that. After calling this, use submit_paste to publish the result if you want to appear on the leaderboard.',
+  annotations: {
+    title: "Rank a paste",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.destructiveHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      text: {
+        type: "string",
+        description:
+          'Token counts to rank. Two formats accepted: (1) JSON object {"input":N,"output":N,"cacheCreate":N,"cacheRead":N} where all values are non-negative integers, or (2) four whitespace-separated numbers in order: input output cacheCreate cacheRead. Get these from `ccusage` output, the Claude Max usage dashboard, tokscale, or any token reader. Example valid input: {"input":1000000,"output":500000,"cacheCreate":50000,"cacheRead":800000}',
+      },
+    },
+    required: ["text"],
+    description:
+      "Requires the token counts as a string. No other parameters are accepted.",
+  },
+  outputSchema: CASCADE_OUTPUT,
+};
+
+export async function handleRankPaste(args) {
+  if (!args?.text)
+    throw new Error("rank_paste requires a non-empty `text` argument.");
+  // E2: reject oversized pastes before parsing (parity with submit_paste / rank_windows).
+  if (typeof args.text === "string" && args.text.length > MAX_INPUT) {
+    return {
+      status: "error",
+      reason: "input_too_large",
+      detail: `text exceeds ${MAX_INPUT} chars (${args.text.length}). Paste only the token-count table, not full output.`,
+    };
+  }
+  const pillars = parsePillars(args.text);
+  const c = withParseWarnings(pillars, cascade(pillars));
+  return { ...c, card: narrate(c) };
+}

package/tools/rank-windows.mjs

@@ -0,0 +1,120 @@
+/**
+ * tools/rank-windows.mjs — rank_windows tool.
+ */
+
+import { cascade, parsePillars } from "../analytics/cascade.mjs";
+import { narrate } from "../presentation/narrate.mjs";
+import { CASCADE_OUTPUT, ANNOTATIONS } from "./_schemas.mjs";
+import { MAX_INPUT, withParseWarnings } from "./_helpers.mjs";
+
+export const TOOL_DEF = {
+  name: "rank_windows",
+  description:
+    "Rank all four time windows (7d/30d/90d/all-time) in one call from a dashboard paste — paste the full table from ccusage, tokscale, or the Claude Max usage dashboard and get the cascade (Υ, SNR, Leverage, Velocity, 10xDEV, class, card) for each window. Each window is parsed and scored independently. Named keys required (input/output/cacheCreate/cacheRead); positional order is NOT safe here (dashboards list cache_read before cache_create — see WINDOWED_PROFILES gotcha). Omit windows you don't have — partial input is allowed (1–4 windows). Does NOT submit to the board; use tokenpull_submit for zero-paste publishing.",
+  annotations: {
+    title: "Rank all time windows",
+    ...ANNOTATIONS.readOnlyHint,
+    ...ANNOTATIONS.idempotentHint,
+    ...ANNOTATIONS.openWorldHint,
+  },
+  inputSchema: {
+    type: "object",
+    properties: {
+      "7d": {
+        type: "string",
+        description:
+          "ccusage/tokscale paste or JSON for the 7-day window (optional)",
+      },
+      "30d": {
+        type: "string",
+        description:
+          "ccusage/tokscale paste or JSON for the 30-day window (optional)",
+      },
+      "90d": {
+        type: "string",
+        description:
+          "ccusage/tokscale paste or JSON for the 90-day window (optional)",
+      },
+      all: {
+        type: "string",
+        description:
+          "ccusage/tokscale paste or JSON for the all-time window (optional)",
+      },
+      source_tool: {
+        type: "string",
+        enum: [
+          "ccusage",
+          "tokscale",
+          "claude_max",
+          "token_dashboard",
+          "other",
+        ],
+        description:
+          "which token reader produced the paste (for cross-tool variance tracking)",
+      },
+    },
+    // at least one window paste is required (runtime check backs this up)
+    anyOf: [
+      { required: ["7d"] },
+      { required: ["30d"] },
+      { required: ["90d"] },
+      { required: ["all"] },
+    ],
+  },
+  outputSchema: {
+    type: "object",
+    properties: {
+      windows: {
+        type: "array",
+        description: "Cascade results per window",
+        items: {
+          type: "object",
+          properties: {
+            window: { type: "string", enum: ["7d", "30d", "90d", "all"] },
+            ...CASCADE_OUTPUT.properties,
+          },
+        },
+      },
+    },
+  },
+};
+
+export async function handleRankWindows(args) {
+  // Score up to 4 named window pastes independently. Named-key parsing only —
+  // positional is unsafe here because dashboards list cache_read before cache_create
+  // (the WINDOWED_PROFILES swap gotcha). Each window goes through parsePillars →
+  // cascade → narrate individually; results are collected into a windows[] array
+  // in the same shape as tokenpull output for easy follow-up with tokenpull_submit.
+  const WINDOW_KEYS = ["7d", "30d", "90d", "all"];
+  const sourceTool = args?.source_tool || null;
+  // E2: reject any oversized window paste up front (token tables are tiny).
+  for (const wk of WINDOW_KEYS) {
+    const v = args?.[wk];
+    if (typeof v === "string" && v.length > MAX_INPUT) {
+      return {
+        status: "error",
+        reason: "input_too_large",
+        detail: `window '${wk}' exceeds ${MAX_INPUT} chars (${v.length}). Paste only the token-count table.`,
+      };
+    }
+  }
+  const windows = [];
+  for (const wk of WINDOW_KEYS) {
+    const text = args?.[wk];
+    if (!text || typeof text !== "string" || !text.trim()) continue;
+    const pillars = parsePillars(text);
+    const c = withParseWarnings(pillars, cascade(pillars));
+    const card = narrate(c, `${wk} window`);
+    windows.push({ window: wk, pillars, cascade: c, card });
+  }
+  if (windows.length === 0) {
+    throw new Error(
+      "rank_windows requires at least one window paste (7d, 30d, 90d, or all).",
+    );
+  }
+  return {
+    windows,
+    source_tool: sourceTool,
+    note: "Local preview only — use tokenpull_submit to publish to the board.",
+  };
+}