sigrank 0.14.2 → 0.15.0

package/README.md

@@ -1,3 +1,7 @@
+> **🏆 SigRank is live: [signalaf.com](https://signalaf.com)** — the leaderboard for how
+> efficiently you use AI, not how much. See your projected rank in 60 seconds at
+> [signalaf.com/score](https://signalaf.com/score). *Token counts only. Never your prompts.*
+
 <div align="center">
 
 <p><img src="./.github/assets/og-card.png" alt="SigRank — the new standard in AI evaluation &amp; benchmarks" width="800"></p>
@@ -35,9 +39,12 @@ sigrank enroll
 
 # 3. Submit your cascade to the board
 sigrank submit
+
+# (cautious? see exactly what would be sent — four counts + a signature — sending nothing)
+sigrank submit --dry-run
 ```
 
-That's it. The agent reads your local AI session logs on-device, derives your token cascade (Υ Yield, Leverage, Velocity, 10xDEV), and publishes to [signalaf.com](https://signalaf.com). No paste, no transcript content — only the four token counts leave your machine.
+That's it. sigrank reads your local AI session logs on-device, derives your token cascade (Υ Yield, Leverage, Velocity, 10xDEV), and publishes to [signalaf.com](https://signalaf.com). No paste, no transcript content — only the four token counts leave your machine.
 
 Or just explore without signing in:
 
@@ -133,6 +140,7 @@ Six tabs. Keys: `1`-`6` or `←` `→` to switch · `R` refresh · `Q` quit.
 ```bash
 sigrank enroll          # sign in: paste a connect code (get one at signalaf.com → Settings)
 sigrank submit          # publish your verified runs to the board (sign in first)
+sigrank submit --dry-run  # inspect the exact signed payload without sending anything
 ```
 
 Or do it inside the TUI on the **Connect** tab (`6`), then press `[S]` to submit.
@@ -177,7 +185,9 @@ Or if installed globally:
 | `tokenpull_submit(codename, window?)` | `{codename?, window?}` | `tokenpull` → publish to board. Omit codename for preview |
 | `tokenpull_compare(platform?)` | `{platform?}` | All four sources side-by-side: tokenpull + ccusage + token-dash + tokscale. Returns pillars, cascade metrics, and delta % vs tokenpull per window |
 | `rank_windows` | `{platform?, window?}` | Multi-window cascade from local logs |
-| `watch_tokenpull` | `{platform?, interval_s?}` | Streaming cascade snapshots |
+| `watch_tokenpull` | `{platform?, interval_s?}` | One cascade snapshot per call (interval_s advisory) |
+| `submit_verified` | `{window?, platform?, dry_run?}` | THE ranked path: builds + ed25519-signs Schema 1.0 snapshots and POSTs them. `platform:'multi'` sums all active platforms. `dry_run:true` returns the exact payload unsent |
+| `enroll` | `{code, device_label?}` | Bind this device with a connect code from signalaf.com → Settings |
 
 ---
 
@@ -250,7 +260,8 @@ All adapters are token-only (no message content, no cost fields, no credentials)
 - **Token-only, always.** No message content is ever read, logged, or transmitted — only token counts (`input`, `output`, `cache_creation`, `cache_read`), message IDs, and timestamps.
 - **Local by default.** `tokenpull` reads only `~/.claude/projects` (Claude) or `~/.codex` (Codex) on your device. Numbers stay on your machine unless you explicitly submit with a codename.
 - **Background tooling excluded.** Memory plugins, observers, summarizers (e.g. `claude-mem`, `mem0`, `observer-sessions`) are filtered from both Claude and Codex reads. `subagents/` are kept — they represent real operator work.
-- **No auth required.** All board reads and the submit path are anonymous.
+- **Board reads are anonymous.** No account needed to browse, compare, or watch.
+- **Ranked submissions are signed, not trusted.** `sigrank submit` requires a one-time `enroll` (device-bound ed25519 key — the private key never leaves your machine). Verify what's sent with `sigrank submit --dry-run`: the payload is four token counts, ratios, and a signature.
 
 ---
 
@@ -288,7 +299,7 @@ Tests verify (29 assertions):
 | File | Responsibility |
 |---|---|
 | `index.mjs` | Entry point — TTY detection, routes to CLI or MCP server |
-| `cli.mjs` | CLI commands: board, me, compare, watch, enroll, submit, help |
+| `cli.mjs` | CLI commands: board, compare, watch, enroll, submit, help |
 | `tui.mjs` | Full tabbed TUI: Dashboard / Trends / Compare / Board / Watch / Connect |
 | `cascade.mjs` | Pure cascade math (Υ, SNR, leverage, velocity, 10xDEV, class) |
 | `tokenpull.mjs` | On-device log scanner — Claude, Codex, multi-platform |

package/adapters.mjs

@@ -35,10 +35,10 @@
 import { readdir, readFile } from 'node:fs/promises'
 import { join, extname } from 'node:path'
 import { homedir } from 'node:os'
-import { exec as execCb } from 'node:child_process'
+import { execFile as execFileCb } from 'node:child_process'
 import { promisify } from 'node:util'
 
-const exec = promisify(execCb)
+const execFileP = promisify(execFileCb)
 const DAY_MS = 86_400_000 // shared with tokenpull.mjs but kept local to avoid circular import
 
 // ── File-system helpers ───────────────────────────────────────────────────────
@@ -75,10 +75,12 @@ function* parseJsonl(text, filePath) {
   }
 }
 
-/** Shell out to sqlite3 and return parsed JSON rows, or [] on error/unavailability. */
+/** Run sqlite3 -json and return parsed rows, or [] on error/unavailability.
+ *  execFile with an args array — no shell, so dbPath/sql need no quoting/escaping
+ *  (matches the execFile hardening used in tools.mjs / tokenpull.mjs). */
 async function sqliteJson(dbPath, sql) {
   try {
-    const { stdout } = await exec(`sqlite3 -json "${dbPath}" "${sql.replace(/"/g, '\\"')}"`, { timeout: 10_000 })
+    const { stdout } = await execFileP('sqlite3', ['-json', dbPath, sql], { timeout: 10_000 })
     return JSON.parse(stdout || '[]')
   } catch { return [] }
 }

package/cli.mjs

@@ -1309,7 +1309,7 @@ async function runSubmit({ platform = 'claude', window } = {}) {
 
   let out
   try {
-    out = await callTool('submit_verified', { platform, window: typeof window === 'string' ? window : undefined })
+    out = await callTool('submit_verified', { platform, window: typeof window === 'string' ? window : undefined, dry_run: process.argv.includes('--dry-run') })
   } catch (e) {
     writeln(red(`  ✗ ${e.message}`))
     process.exitCode = 1
@@ -1326,7 +1326,9 @@ async function runSubmit({ platform = 'claude', window } = {}) {
   let anyReceivedNotRanked = false
   for (const w of out.windows || []) {
     const label = String(w.window).padEnd(8)
-    if (w.ranked) {
+    if (w.status === 'dry_run') {
+      writeln(`  ${gold('◇')} ${bold(label)} ${gold('DRY RUN')} ${dim('· nothing sent')}`)
+    } else if (w.ranked) {
       anyRanked = true
       writeln(`  ${green('✓')} ${bold(label)} ${green('RANKED')} ${dim('· live on the board')}`)
     } else if (w.status === 'received') {
@@ -1350,7 +1352,7 @@ export async function runCli(argv) {
 
   // parse --key value AND --key=value flags. E4: validate against the known set and warn
   // (don't crash) on anything unknown, so a typo'd flag is visible instead of silently ignored.
-  const KNOWN_FLAGS = new Set(['window', 'platform', 'refresh', 'once', 'submit', 'compare', 'label'])
+  const KNOWN_FLAGS = new Set(['window', 'platform', 'refresh', 'once', 'submit', 'compare', 'label', 'dry-run'])
   const flags = {}
   for (let i = 1; i < args.length; i++) {
     const a = args[i]
@@ -1412,8 +1414,11 @@ export async function runCli(argv) {
       // default: full unified view
       await runSigRank()
     } else {
-      // unknown command: show help
+      // unknown command: show help + exit non-zero so typos fail loudly (index.mjs now
+      // routes ALL arg'd invocations here instead of falling through to the MCP server)
+      writeln(red(`\n  ✗ unknown command: ${cmd}`))
       await showHelp()
+      process.exit(2)
     }
   } catch (e) {
     write(SHOW_CURSOR)

package/index.mjs

@@ -10,7 +10,7 @@
  * CLI shortcuts (optional — the TUI never needs them):
  *   npx sigrank enroll          sign in: redeem a connect code from signalaf.com
  *   npx sigrank submit          publish your verified runs to the board
- *   npx sigrank board | me | compare | watch    read / publish helpers
+ *   npx sigrank board | compare | watch    read / publish helpers
  *   npx sigrank --help          full reference
  *
  * For AI clients (NOT human commands): in a piped/non-TTY context this starts an MCP
@@ -23,7 +23,7 @@
 
 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 { CallToolRequestSchema, ListToolsRequestSchema, McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'
 import { TOOLS, callTool } from './tools.mjs'
 import { runCli } from './cli.mjs'
 import { readFileSync } from 'node:fs'
@@ -55,6 +55,11 @@ async function startMcpServer() {
   const server = new Server({ name: 'sigrank', version: serverVersion() }, { capabilities: { tools: {} } })
   server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    // Unknown tool name = a client/host bug → JSON-RPC -32602 protocol error, per the MCP
+    // spec. isError results (below) are reserved for tools that ran and failed.
+    if (!TOOLS.some((t) => t.name === req.params.name)) {
+      throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${req.params.name}`)
+    }
     try {
       const out = await callTool(req.params.name, req.params.arguments)
       return { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] }
@@ -66,14 +71,14 @@ async function startMcpServer() {
 }
 
 // Route:
-//   any CLI command arg  → terminal UI / CLI command
+//   any arg              → the CLI (runCli shows help + exits non-zero on unknown commands,
+//                          so a typo never silently starts a hung MCP stdio server on a TTY)
 //   no args + TTY stdout → full tabbed TUI (interactive use)
 //   no args + piped      → MCP stdio server (AI client use)
 const cliArgs = process.argv.slice(2)
-const CLI_COMMANDS = new Set(['board', 'compare', 'tui', 'watch', 'enroll', 'submit', 'help', '--help', '-h', '--version', '-v'])
-if (cliArgs.length > 0 && (CLI_COMMANDS.has(cliArgs[0]) || cliArgs[0].startsWith('--'))) {
+if (cliArgs.length > 0) {
   runCli(process.argv)
-} else if (cliArgs.length === 0 && process.stdout.isTTY) {
+} else if (process.stdout.isTTY) {
   // Interactive terminal — launch the full tabbed TUI
   const { runTui } = await import('./tui.mjs')
   runTui()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigrank",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
   "type": "module",
   "license": "MIT",

package/submit.mjs

@@ -130,6 +130,20 @@ export async function submitSignedWindow(windowKey, pillars, messages, identity,
   const payload = buildPayload(windowKey, pillars, messages, identity, opts.platform || 'claude', opts)
   const signature = signPayload(payload, identity.private_key_pkcs8_b64)
 
+  // Dry run: build + sign exactly as a real publish, then STOP before the POST.
+  // Returns the exact payload that would be sent — the privacy proof ("token
+  // counts only") is inspectable, and nothing touches the network.
+  if (opts.dryRun) {
+    return {
+      status: 'dry_run',
+      window: WINDOW_TYPE[windowKey] || windowKey,
+      would_post: `${apiBase}/api/v1/snapshots`,
+      payload,
+      signature,
+      detail: 'Nothing sent. Re-run without dry_run to publish.',
+    }
+  }
+
   let res
   let ack
   try {

package/tokenpull.mjs

@@ -41,7 +41,9 @@ const _envPath = `${_localBin}${process.env.PATH ? ':' + process.env.PATH : ''}`
 // (ccusage, tokscale) are found even when sigrank isn't globally installed.
 function execFileAsync(cmd, args, timeoutMs) {
   return new Promise((resolve, reject) => {
-    execFile(cmd, args, { timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PATH: _envPath } }, (err, stdout) => {
+    // NOTE: execFile does not accept a `stdio` option (it always pipes + buffers
+    // stdout/stderr against maxBuffer) — a previous `stdio` key here was silently ignored.
+    execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PATH: _envPath } }, (err, stdout) => {
       if (err) reject(err)
       else resolve(stdout.toString())
     })
@@ -347,7 +349,10 @@ async function _freshCcusage(platform = 'claude') {
     }
     let i = 0, o = 0, cw = 0, cr = 0
     for (const r of rows) {
-      i += r.inputTokens ?? 0; o += r.outputTokens ?? 0; cw += r.cacheCreationTokens ?? 0; cr += r.cacheReadTokens ?? 0
+      i  += r.inputTokens         ?? r.input_tokens         ?? 0
+      o  += r.outputTokens        ?? r.output_tokens        ?? 0
+      cw += r.cacheCreationTokens ?? r.cache_create_tokens  ?? 0
+      cr += r.cacheReadTokens     ?? r.cache_read_tokens    ?? 0
     }
     result['all'] = { input: i, output: o, cacheCreate: cw, cacheRead: cr }
     return result

package/tools.mjs

@@ -34,7 +34,9 @@ const _envPath = `${_localBin}${process.env.PATH ? ':' + process.env.PATH : ''}`
 // are found even when sigrank isn't globally installed.
 function execFileAsync(cmd, args, timeoutMs) {
   return new Promise((resolve, reject) => {
-    execFile(cmd, args, { timeout: timeoutMs, stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PATH: _envPath } }, (err, stdout) => {
+    // NOTE: execFile does not accept a `stdio` option (it always pipes + buffers
+    // stdout/stderr against maxBuffer) — a previous `stdio` key here was silently ignored.
+    execFile(cmd, args, { timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024, env: { ...process.env, PATH: _envPath } }, (err, stdout) => {
       if (err) reject(err)
       else resolve(stdout.toString())
     })
@@ -71,7 +73,10 @@ async function _ccusagePillars(platform = 'claude') {
     }
     let i=0,o=0,cw=0,cr=0
     for (const r of rows) {
-      i+=r.inputTokens??0; o+=r.outputTokens??0; cw+=r.cacheCreationTokens??0; cr+=r.cacheReadTokens??0
+      i  += r.inputTokens         ?? r.input_tokens         ?? 0
+      o  += r.outputTokens        ?? r.output_tokens        ?? 0
+      cw += r.cacheCreationTokens ?? r.cache_create_tokens  ?? 0
+      cr += r.cacheReadTokens     ?? r.cache_read_tokens    ?? 0
     }
     result['all'] = { input: i, output: o, cacheCreate: cw, cacheRead: cr }
     return result
@@ -231,17 +236,19 @@ export const TOOLS = [
         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'] }],
     },
   },
   {
     name: 'watch_tokenpull',
     description:
-      'Watch your local token logs and re-derive your cascade whenever new sessions are written — a live tune meter. Polls at a configurable interval (default 60s) and returns the updated cascade. With submit:true (and an enrolled device) it also signs + publishes the watched window to the board each poll; default is preview-only (no submit).',
+      'One poll per call: pulls your local token logs and returns the current cascade for the watched window — the tool never blocks or loops. Re-call at your desired cadence to watch for changes (interval_s is advisory only and echoed back as poll_interval_s). With submit:true (and an enrolled device) each call may also sign + publish the watched window to the board, rate-limited to once per 5 min per platform+window; default is preview-only (no submit).',
     inputSchema: {
       type: 'object',
       properties: {
         platform:    { type: 'string', enum: ALL_PLATFORMS, description: 'platform to watch (default: claude)' },
-        interval_s:  { type: 'number', description: 'poll interval in seconds (default: 60, min: 10)' },
+        interval_s:  { type: 'number', description: 'advisory poll cadence in seconds (default: 60, min: 10) — echoed back as poll_interval_s; does not make the call block or loop' },
         window:      { type: 'string', enum: ['7d', '30d', '90d', 'all'], description: 'which window to watch (default: 7d — most sensitive to recent activity)' },
         submit:      { type: 'boolean', description: 'auto-submit the watched window to the board as a VERIFIED operator each poll (requires `enroll`; default false = preview only)' },
       },
@@ -278,15 +285,41 @@ export const TOOLS = [
   {
     name: 'submit_verified',
     description:
-      'Publish your LOCAL token runs to the SigRank board as a VERIFIED operator — the enrolled, signed path. Reads your pillars (tokenpull), builds the canonical Schema 1.0 snapshot per window, ed25519-signs it with your device key, and POSTs to /api/v1/snapshots. Requires `npx sigrank-mcp enroll` first (a bound device). Only signed submissions from a trusted device rank on the board. Token-only; the private key never leaves your machine.',
+      'Publish your LOCAL token runs to the SigRank board as a VERIFIED operator — the enrolled, signed path. Reads your pillars (tokenpull), builds the canonical Schema 1.0 snapshot per window, ed25519-signs it with your device key, and POSTs to /api/v1/snapshots. Requires `npx sigrank-mcp enroll` first (a bound device). Only signed submissions from a trusted device rank on the board. Token-only; the private key never leaves your machine. Pass dry_run:true to inspect the exact signed payload without publishing.',
     inputSchema: {
       type: 'object',
       properties: {
         window: { type: 'string', enum: ['7d', '30d', '90d', 'all'], description: 'submit only this window (default: all 4)' },
-        platform: { type: 'string', enum: ALL_PLATFORMS, description: 'source platform (default: claude)' },
+        platform: { type: 'string', enum: [...ALL_PLATFORMS, 'multi'], description: "source platform (default: claude). 'multi' = combined cascade summed across all locally-detected platforms (needs 2+ active); empty windows are skipped." },
+        dry_run: { type: 'boolean', description: 'build + sign but do NOT publish — returns the exact payload that would be POSTed (token counts only), so you can inspect before submitting' },
       },
     },
   },
+  {
+    name: 'simulate_change',
+    description:
+      "The first PRESCRIPTIVE SigRank tool — 'what if I changed my token mix?' Takes your current 4 pillars (input/output/cacheCreate/cacheRead) and one or more proposed changes, runs the canonical cascade on BOTH the current and simulated values, and returns the exact Υ Yield delta, class change, and per-metric diffs. This is the 'show me the payoff before I do the work' primitive: no network, no submission, pure local math. Use it to answer 'would increasing my cache-read by 50k tokens actually move my class?' before you change your workflow. Accepts the current pillars as JSON or 4 numbers (same as rank_paste) plus a `changes` object with any of the 4 pillar names mapped to new absolute values OR relative deltas (e.g. {cacheRead: '+50000'} or {input: 800000}).",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'Current token pillars — ccusage JSON or "input output cacheCreate cacheRead" (same format as rank_paste).',
+        },
+        changes: {
+          type: 'object',
+          description: 'Proposed changes to apply. Keys: input, output, cacheCreate, cacheRead. Values are either absolute numbers (replace) or strings starting with +/- for relative deltas (add/subtract). Omitted pillars are unchanged.',
+          properties: {
+            input:       { type: ['number', 'string'], description: 'new input token count (absolute) or "+/-N" for a relative delta' },
+            output:      { type: ['number', 'string'], description: 'new output token count (absolute) or "+/-N" for a relative delta' },
+            cacheCreate: { type: ['number', 'string'], description: 'new cache-create token count (absolute) or "+/-N" for a relative delta' },
+            cacheRead:   { type: ['number', 'string'], description: 'new cache-read token count (absolute) or "+/-N" for a relative delta' },
+          },
+        },
+      },
+      required: ['text', 'changes'],
+    },
+  },
 ]
 
 // tokenpull window key → the board's window_type enum.
@@ -295,7 +328,9 @@ const WINDOW_TYPE = { '7d': '7d', '30d': '30d', '90d': '90d', all: 'all_time' }
 // E3: client-side auto-submit cooldown for watch_tokenpull. The server already dedups
 // identical snapshots (exact hash → 422), but a noisy poll loop with submit:true could still
 // churn the network/board with near-identical rows. Cap auto-submit to once per WATCH_SUBMIT_COOLDOWN_MS
-// per window (in-memory, per process). Keyed by window so different windows don't block each other.
+// per platform+window (in-memory, per process). Keyed by platform:window so different
+// platforms/windows don't block each other, and only armed on a non-error submit so a
+// network failure doesn't lock out retries for 5 minutes.
 const WATCH_SUBMIT_COOLDOWN_MS = 5 * 60 * 1000
 const _lastWatchSubmitAt = new Map()
 
@@ -348,6 +383,10 @@ export async function callTool(name, args, opts = {}) {
 
   if (name === 'rank_paste') {
     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) }
@@ -438,7 +477,7 @@ export async function callTool(name, args, opts = {}) {
           msgs += w.messages || 0
         }
         if (sum.input + sum.output + sum.cacheCreate + sum.cacheRead <= 0) continue // skip empty window
-        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now })
+        const r = await submitSignedWindow(wk, sum, msgs, id, { apiBase, fetchImpl: doFetch, platform: 'multi', now: opts.now, dryRun: !!args?.dry_run })
         out.push({ window: wk, pillars: sum, ...r })
       }
       return { platform: 'multi', codename: id.codename, operator_id: id.operator_id, sources: detected.map((d) => d.platform), windows: out }
@@ -453,6 +492,7 @@ export async function callTool(name, args, opts = {}) {
         fetchImpl: doFetch,
         platform: pulled.platform,
         now: opts.now,
+        dryRun: !!args?.dry_run,
       })
       out.push({ window: w.window, pillars: w.pillars, ...r })
     }
@@ -599,21 +639,23 @@ export async function callTool(name, args, opts = {}) {
     if (args?.submit === true) {
       const id = opts.identity || ensureIdentity()
       if (id.codename && id.operator_id && id.private_key_pkcs8_b64) {
-        // E3: client-side cooldown — at most one auto-submit per window per 5 min. Prevents a
-        // fast poll loop from churning the board even before the server's hash-dedup kicks in.
+        // E3: client-side cooldown — at most one auto-submit per platform+window per 5 min.
+        // Prevents a fast poll loop from churning the board even before the server's
+        // hash-dedup kicks in. Armed only on a non-error outcome so failed submits retry.
         const clockNow = typeof opts.now === 'number' ? opts.now : Date.now()
-        const last = _lastWatchSubmitAt.get(watchWindow)
+        const cdKey = `${pulled.platform}:${watchWindow}`
+        const last = _lastWatchSubmitAt.get(cdKey)
         if (last != null && clockNow - last < WATCH_SUBMIT_COOLDOWN_MS) {
           const waitS = Math.ceil((WATCH_SUBMIT_COOLDOWN_MS - (clockNow - last)) / 1000)
-          auth_submit = { status: 'cooldown', detail: `auto-submit for '${watchWindow}' on cooldown — next in ~${waitS}s (max once / 5 min).`, retry_after_s: waitS }
+          auth_submit = { status: 'cooldown', detail: `auto-submit for '${cdKey}' on cooldown — next in ~${waitS}s (max once / 5 min).`, retry_after_s: waitS }
         } else {
-          _lastWatchSubmitAt.set(watchWindow, clockNow)
           auth_submit = await submitSignedWindow(watchWindow, win.pillars, win.messages, id, {
             apiBase,
             fetchImpl: doFetch,
             platform: pulled.platform,
             now: opts.now,
           })
+          if (auth_submit?.status !== 'error') _lastWatchSubmitAt.set(cdKey, clockNow)
         }
       } else {
         auth_submit = { status: 'not_enrolled', detail: 'Run `npx sigrank-mcp enroll` to auto-submit verified runs.' }
@@ -701,5 +743,116 @@ export async function callTool(name, args, opts = {}) {
     }
   }
 
+  if (name === 'simulate_change') {
+    // The first prescriptive tool — "what if I changed my token mix?"
+    // Pure local math: parse current pillars, apply proposed changes, run the
+    // cascade on both, return the delta. No network, no submission.
+    if (!args?.text) throw new Error('simulate_change requires a non-empty `text` argument (current pillars).')
+    if (typeof args.text === 'string' && args.text.length > MAX_INPUT) {
+      return { status: 'error', reason: 'input_too_large', detail: `text exceeds ${MAX_INPUT} chars.` }
+    }
+    if (!args?.changes || typeof args.changes !== 'object') {
+      throw new Error('simulate_change requires a `changes` object with at least one pillar change.')
+    }
+
+    const currentPillars = parsePillars(args.text)
+    const current = withParseWarnings(currentPillars, cascade(currentPillars))
+
+    // Apply changes: each pillar is either an absolute number (replace) or a
+    // string starting with +/- (relative delta). Omitted pillars are unchanged.
+    const PILLAR_KEYS = ['input', 'output', 'cacheCreate', 'cacheRead']
+    const simulated = { ...currentPillars }
+    const appliedChanges = {}
+
+    for (const key of PILLAR_KEYS) {
+      if (args.changes[key] == null) continue
+      const raw = args.changes[key]
+      let newVal
+
+      if (typeof raw === 'number') {
+        newVal = raw
+      } else if (typeof raw === 'string') {
+        const trimmed = raw.trim()
+        if (trimmed.startsWith('+') || trimmed.startsWith('-')) {
+          // Relative delta: add/subtract from current value
+          const delta = Number(trimmed)
+          if (!Number.isFinite(delta)) {
+            return { status: 'error', reason: 'invalid_change', detail: `changes.${key}: "${raw}" is not a valid relative delta.` }
+          }
+          newVal = currentPillars[key] + delta
+        } else {
+          // Absolute value as a string
+          newVal = Number(trimmed)
+        }
+      } else {
+        return { status: 'error', reason: 'invalid_change', detail: `changes.${key}: expected number or string, got ${typeof raw}.` }
+      }
+
+      if (!Number.isFinite(newVal)) {
+        return { status: 'error', reason: 'invalid_change', detail: `changes.${key}: result is not a finite number.` }
+      }
+      // Clamp to non-negative — token counts can't be negative
+      if (newVal < 0) {
+        return { status: 'error', reason: 'invalid_change', detail: `changes.${key}: result ${newVal} is negative — token counts must be >= 0.` }
+      }
+
+      simulated[key] = newVal
+      appliedChanges[key] = {
+        from: currentPillars[key],
+        to: newVal,
+        delta: newVal - currentPillars[key],
+      }
+    }
+
+    if (Object.keys(appliedChanges).length === 0) {
+      return { status: 'error', reason: 'no_changes', detail: 'No pillar changes specified in the `changes` object.' }
+    }
+
+    const simulatedResult = cascade(simulated)
+
+    // Compute deltas for every cascade metric
+    const metricDelta = (curr, sim) => {
+      if (curr == null && sim == null) return null
+      if (curr == null) return { from: null, to: sim, delta: null }
+      if (sim == null) return { from: curr, to: null, delta: null }
+      return { from: curr, to: sim, delta: Number((sim - curr).toFixed(4)) }
+    }
+
+    const classChanged = current.class !== simulatedResult.class
+
+    return {
+      current: {
+        pillars: currentPillars,
+        yield: current.yield,
+        snr: current.snr,
+        leverage: current.leverage,
+        velocity: current.velocity,
+        dev10x: current.dev10x,
+        class: current.class,
+      },
+      simulated: {
+        pillars: { input: simulated.input, output: simulated.output, cacheCreate: simulated.cacheCreate, cacheRead: simulated.cacheRead },
+        yield: simulatedResult.yield,
+        snr: simulatedResult.snr,
+        leverage: simulatedResult.leverage,
+        velocity: simulatedResult.velocity,
+        dev10x: simulatedResult.dev10x,
+        class: simulatedResult.class,
+      },
+      changes: appliedChanges,
+      deltas: {
+        yield: metricDelta(current.yield, simulatedResult.yield),
+        snr: metricDelta(current.snr, simulatedResult.snr),
+        leverage: metricDelta(current.leverage, simulatedResult.leverage),
+        velocity: metricDelta(current.velocity, simulatedResult.velocity),
+        dev10x: metricDelta(current.dev10x, simulatedResult.dev10x),
+      },
+      class_changed: classChanged,
+      ...(classChanged ? { class_transition: `${current.class} → ${simulatedResult.class}` } : {}),
+      ...(simulatedResult.warnings ? { simulated_warnings: simulatedResult.warnings } : {}),
+      note: 'Local simulation only — no submission. The actual score depends on server-side RS.xx weights and class thresholds.',
+    }
+  }
+
   throw new Error(`Unknown tool: ${name}`)
 }