sigrank 0.11.4

package/index.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * SigRank MCP server + CLI entry point.
+ *
+ * The TUI is the whole app. Launch it and sign in inside it:
+ *   npx sigrank                 full tabbed TUI (Dashboard / Trends / Compare /
+ *                                   Board / Watch / Connect). Sign in on the Connect
+ *                                   tab (paste a connect code), then [S] submits.
+ *
+ * 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 --help          full reference
+ *
+ * For AI clients (NOT human commands): in a piped/non-TTY context this starts an MCP
+ * stdio server; AI clients call its tools automatically. See ./tools.mjs.
+ *
+ * Pure cascade math: ./cascade.mjs  |  narration card: ./narrate.mjs
+ * Tool table + dispatcher: ./tools.mjs  |  Terminal UI: ./cli.mjs + ./tui.mjs
+ * Token-only — no transcript content.
+ */
+
+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'
+import { runCli } from './cli.mjs'
+import { readFileSync } from 'node:fs'
+
+// FIX K: read the version from package.json (was hardcoded '0.7.0' — drifted from
+// 0.11.0). The MCP server identity now tracks the published package version.
+function serverVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf-8'))
+    return pkg.version || '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+// 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 startMcpServer() {
+  const server = new Server({ name: 'sigrank', version: serverVersion() }, { 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())
+}
+
+// Route:
+//   any CLI command arg  → terminal UI / CLI command
+//   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', 'me', 'compare', 'tui', 'watch', 'enroll', 'submit', 'help', '--help', '-h', '--version', '-v'])
+if (cliArgs.length > 0 && (CLI_COMMANDS.has(cliArgs[0]) || cliArgs[0].startsWith('--'))) {
+  runCli(process.argv)
+} else if (cliArgs.length === 0 && process.stdout.isTTY) {
+  // Interactive terminal — launch the full tabbed TUI
+  const { runTui } = await import('./tui.mjs')
+  runTui()
+} else {
+  startMcpServer()
+}

package/keystore.mjs

@@ -0,0 +1,142 @@
+// keystore.mjs — local ed25519 device identity for SigRank signed submit (D7 §4.5).
+//
+// Persists a per-device keypair at ~/.sigrank-mcp/identity.json (dir 0700, file 0600).
+// The PRIVATE key never leaves this machine; only the raw 32-byte public key (as
+// "ed25519:<base64>") is sent to the server at enroll time. The device_id (uuid) is
+// generated once and is the immutable binding target server-side.
+//
+// Public-key export MUST match the server's publicKeyFromAgent: generateKeyPairSync
+// exports SPKI DER with a 12-byte prefix; we strip it to the raw 32 bytes, base64 it,
+// and prefix "ed25519:". The server re-adds the SPKI prefix to verify. Round-trip is
+// locked by sign.test.mjs + the canon-parity fixture.
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync, unlinkSync } from 'node:fs'
+import { generateKeyPairSync, randomUUID } from 'node:crypto'
+
+const DIR = join(homedir(), '.sigrank-mcp')
+const PATH = join(DIR, 'identity.json')
+
+/** 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
+}
+
+/** Read the stored identity, or null if absent/corrupt. */
+export function loadIdentity() {
+  if (!existsSync(PATH)) return null
+  try {
+    return JSON.parse(readFileSync(PATH, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+/** Write the identity with strict perms (dir 0700, file 0600). */
+export function persistIdentity(identity) {
+  mkdirSync(DIR, { recursive: true })
+  try {
+    chmodSync(DIR, 0o700)
+  } catch {
+    /* best-effort on platforms without chmod */
+  }
+  writeFileSync(PATH, `${JSON.stringify(identity, null, 2)}\n`, { mode: 0o600 })
+  try {
+    chmodSync(PATH, 0o600)
+  } catch {
+    /* best-effort */
+  }
+  return identity
+}
+
+/** Build a fresh keypair record (pure — no fs). Exposed for tests. */
+export function generateIdentity({ device_id } = {}) {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+  const spki = publicKey.export({ type: 'spki', format: 'der' })
+  const rawPub = Buffer.from(spki).subarray(SPKI_PREFIX_LEN) // the raw 32 bytes
+  const pkcs8 = privateKey.export({ type: 'pkcs8', format: 'der' })
+  return {
+    device_id: device_id || randomUUID(),
+    codename: null,
+    operator_id: null,
+    public_key: `ed25519:${rawPub.toString('base64')}`,
+    private_key_pkcs8_b64: Buffer.from(pkcs8).toString('base64'),
+    agent_version: agentVersion(),
+    enrolled_at: null,
+  }
+}
+
+/**
+ * Decide the binding (codename/operator_id/enrolled_at) to carry onto a freshly
+ * generated identity. The binding is tied to device_id: if device_id is CHANGING
+ * (a new device, e.g. after a reset/re-enroll where the old file was deleted), the
+ * old binding is INVALIDATED — never preserve a stale codename/operator onto a
+ * different device. That mismatch is the "Frankenstein identity" root cause: a new
+ * device_id + an old codename → the server sees a mismatch → tags submissions
+ * `unverified` → never ranks, yet `isSignedIn` reads the local codename as present.
+ * Only reuse the binding when the SAME device_id is being kept. Pure — exposed for
+ * tests (no fs, so the owner's live identity is never at risk during a test run).
+ */
+export function bindingForFreshIdentity(existing, fresh) {
+  if (!existing) return { codename: null, operator_id: null, enrolled_at: null }
+  if (existing.device_id && fresh.device_id === existing.device_id) {
+    return {
+      codename: existing.codename ?? null,
+      operator_id: existing.operator_id ?? null,
+      enrolled_at: existing.enrolled_at ?? null,
+    }
+  }
+  // device_id changed → the old binding belongs to a different device; drop it.
+  return { codename: null, operator_id: null, enrolled_at: null }
+}
+
+/**
+ * Load the existing identity, or generate + persist a fresh one. Idempotent: a
+ * complete existing identity is returned untouched (never rotates a live key).
+ */
+export function ensureIdentity() {
+  const existing = loadIdentity()
+  if (existing?.private_key_pkcs8_b64 && existing?.public_key && existing?.device_id) {
+    return existing
+  }
+  // Regeneration path: a partial/corrupt record. The binding is tied to device_id —
+  // if a new device_id is generated, the old codename/operator MUST NOT carry over
+  // (bindingForFreshIdentity drops them). Only a reused device_id keeps its binding.
+  const fresh = generateIdentity({ device_id: existing?.device_id })
+  const binding = bindingForFreshIdentity(existing, fresh)
+  fresh.codename = binding.codename
+  fresh.operator_id = binding.operator_id
+  fresh.enrolled_at = binding.enrolled_at
+  return persistIdentity(fresh)
+}
+
+/** Record a successful enrollment (codename/operator_id + enrolled_at) into the keystore. */
+export function recordEnrollment({ codename, operator_id }) {
+  const id = ensureIdentity()
+  // OVERWRITE from the server's enroll response — a new enroll is a new binding, full
+  // stop. Never `??`-preserve a stale codename/operator onto this device (the other
+  // half of the Frankenstein bug: a re-enroll used to keep the old codename when the
+  // new one was absent). A 201 enrolled always carries both.
+  id.codename = codename ?? null
+  id.operator_id = operator_id ?? null
+  id.enrolled_at = new Date().toISOString()
+  return persistIdentity(id)
+}
+
+/** Clear the local identity (sign out). Next enroll provisions a fresh device_id. */
+export function clearIdentity() {
+  try { if (existsSync(PATH)) unlinkSync(PATH) } catch { /* best-effort */ }
+}

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,45 @@
+{
+  "name": "sigrank",
+  "version": "0.11.4",
+  "description": "SigRank MCP server — the yield cascade + live leaderboard as MCP tools any agent can call",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SunrisesIllNeverSee/sigrank-mcp.git"
+  },
+  "homepage": "https://signalaf.com",
+  "bugs": {
+    "url": "https://github.com/SunrisesIllNeverSee/sigrank-mcp/issues"
+  },
+  "bin": {
+    "sigrank": "index.mjs",
+    "sigrank-mcp": "index.mjs"
+  },
+  "main": "index.mjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node index.mjs",
+    "test": "node test.mjs && node sign.test.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "cli.mjs",
+    "tui.mjs",
+    "tools.mjs",
+    "cascade.mjs",
+    "narrate.mjs",
+    "tokenpull.mjs",
+    "adapters.mjs",
+    "sign.mjs",
+    "keystore.mjs",
+    "submit.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  }
+}

package/sign.mjs

@@ -0,0 +1,87 @@
+// sign.mjs — canonical JSON + ed25519 signing for SigRank signed snapshot submit.
+//
+// BYTE-COMPATIBLE PORT of sigrank-app lib/ingest/signature.ts. This is the highest-
+// risk file in the client: the server VERIFIES the signature over ITS recomputation
+// of these exact canonical bytes, so a single divergent byte hard-rejects (422) every
+// verified submission. Keep this a line-for-line mirror of the server canonicalizer:
+//   canonical JSON = recursively sorted keys, compact separators, UTF-8, with the
+//   derived agent.signature + agent.snapshot_hash stripped before serialization.
+//   snapshot_hash = "sha256:" + hex(sha256(canonical_bytes)).
+//   public key    = "ed25519:<base64 of the 32 raw verify-key bytes>".
+//   signature     = base64 of the 64-byte ed25519 signature over canonical_bytes.
+// The canon-parity fixture (tests/fixtures/canon_parity.json) + sign.test.mjs + the
+// sigrank-app canon_parity gate together lock this byte-for-byte.
+
+import { createHash, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto'
+
+/** Agent fields excluded from the canonical (signed/hashed) body — they derive from it. */
+const DERIVED_AGENT_FIELDS = ['signature', 'snapshot_hash']
+
+/** Recursively sort object keys (matches the server's Object.keys(...).sort()); arrays keep order. */
+function sortDeep(v) {
+  if (Array.isArray(v)) return v.map(sortDeep)
+  if (v && typeof v === 'object') {
+    const out = {}
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k])
+    return out
+  }
+  return v
+}
+
+/** Canonical JSON string the agent signs/hashes (derived agent fields stripped). */
+export function canonicalJson(payload) {
+  const clone = JSON.parse(JSON.stringify(payload))
+  const agent = clone.agent
+  if (agent && typeof agent === 'object') {
+    for (const f of DERIVED_AGENT_FIELDS) delete agent[f]
+  }
+  return JSON.stringify(sortDeep(clone))
+}
+
+/** UTF-8 bytes of the canonical JSON — the exact bytes that get signed. */
+export function canonicalBytes(payload) {
+  return Buffer.from(canonicalJson(payload), 'utf-8')
+}
+
+/** "sha256:<hex>" over the canonical bytes (matches the server snapshotHash). */
+export function snapshotHash(payload) {
+  return `sha256:${createHash('sha256').update(canonicalBytes(payload)).digest('hex')}`
+}
+
+/** SPKI DER prefix for a raw 32-byte ed25519 public key. */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex')
+
+/** Build a node KeyObject from an "ed25519:<base64>" (or bare base64) public key, or null. */
+function publicKeyFrom(pk) {
+  try {
+    const body = pk.startsWith('ed25519:') ? pk.slice('ed25519:'.length) : pk
+    const raw = Buffer.from(body, 'base64')
+    if (raw.length !== 32) return null
+    return createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' })
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Sign the payload's canonical bytes with the PKCS8-DER-base64 private key → base64 sig.
+ * The returned string is the X-Agent-Signature header value.
+ */
+export function signPayload(payload, privateKeyPkcs8B64) {
+  const key = createPrivateKey({ key: Buffer.from(privateKeyPkcs8B64, 'base64'), format: 'der', type: 'pkcs8' })
+  return edSign(null, canonicalBytes(payload), key).toString('base64')
+}
+
+/**
+ * Local verify (parity with the server's verifySignature) — used by the self-test
+ * and as a pre-send sanity check. Returns false on any malformation, never throws.
+ */
+export function verifyPayload(payload, signatureB64, publicKey) {
+  const key = publicKeyFrom(publicKey)
+  if (!key) return false
+  try {
+    return edVerify(null, canonicalBytes(payload), key, Buffer.from(signatureB64, 'base64'))
+  } catch {
+    return false
+  }
+}

package/submit.mjs

@@ -0,0 +1,164 @@
+// submit.mjs — build + ed25519-sign a Schema 1.0 snapshot payload and POST it to the
+// VERIFIED ingest endpoint (D7 §5). Requires an enrolled identity (keystore.codename +
+// operator_id + private key). The server re-derives the ranked Υ from the 4 raw pillars,
+// so the core/background metrics here are schema-valid, plausibility-clean DISPLAY inputs.
+//
+// raw_telemetry sessions/turns/active are conservative PROXIES: tokenpull yields the 4
+// pillars + a message count, not session structure. They are chosen to pass the
+// plausibility gate WITHOUT flagging (a flag downgrades verified→flagged → not ranked).
+// TODO(tokenpull): emit real sessions_count / turns_total / active_minutes per window so
+// the display signa_rate reflects true session shape (the ranked Υ is already exact).
+
+import { snapshotHash, signPayload } from './sign.mjs'
+
+const WINDOW_TYPE = { '7d': '7d', '30d': '30d', '90d': '90d', all: 'all_time' }
+const WINDOW_SPAN_DAYS = { '7d': 7, '30d': 30, '90d': 90, all_time: 3650 }
+const PLATFORM_ENUM = new Set(['claude', 'chatgpt', 'gemini', 'pi', 'codex', 'multi', 'other'])
+// Provenance tag only — the board ranks by Υ (no RS.xx weights, §0.1).
+const RULESET_VERSION = 'sigrank-token-1'
+const DAY_MS = 86_400_000
+
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x))
+const round = (n, dp) => {
+  const f = 10 ** dp
+  return Math.round(n * f) / f
+}
+
+/** Map any tokenpull platform to the Schema 1.0 platform.primary enum (others → 'other'). */
+export function toPlatformPrimary(platform) {
+  return PLATFORM_ENUM.has(platform) ? platform : 'other'
+}
+
+/**
+ * buildPayload — Schema 1.0 payload from a tokenpull window + enrolled identity.
+ * Pure (given opts.now); agent.snapshot_hash is computed last (canonical strips it).
+ */
+export function buildPayload(windowKey, pillars, messages, identity, platform, opts = {}) {
+  const windowType = WINDOW_TYPE[windowKey] || windowKey
+  const spanDays = WINDOW_SPAN_DAYS[windowType] || 30
+  const nowMs = opts.now ?? Date.now()
+
+  const input = Math.max(0, Math.round(pillars?.input || 0))
+  const output = Math.max(0, Math.round(pillars?.output || 0))
+  const cacheCreate = Math.max(0, Math.round(pillars?.cacheCreate || 0))
+  const cacheRead = Math.max(0, Math.round(pillars?.cacheRead || 0))
+  const tokensTotal = input + output + cacheCreate + cacheRead
+
+  // Proxies — plausibility-clean (see file header).
+  const msgs = Math.max(0, Math.round(messages || 0))
+  const turnsTotal = Math.max(output > 0 ? 1 : 0, msgs)
+  const sessionsCount = tokensTotal > 0 ? clamp(Math.round(msgs / 8) || 1, 1, Math.max(1, turnsTotal)) : 0
+  const spanMinutes = spanDays * 1440
+  const minActive = Math.ceil(output / 19000) + 1 // keep output/active under the 20k/min flag
+  const activeMinutes = clamp(Math.max(msgs, minActive), 1, Math.max(1, spanMinutes - 1))
+
+  const compressionRatio = input + output > 0 ? clamp(output / (input + output), 0, 1) : 0
+  const sessionDepth = sessionsCount > 0 ? turnsTotal / sessionsCount : 0
+
+  const payload = {
+    schema_version: '1.0',
+    codename: identity.codename,
+    device_id: identity.device_id,
+    submitted_at: new Date(nowMs).toISOString(),
+    window: {
+      type: windowType,
+      start: new Date(nowMs - spanDays * DAY_MS).toISOString(),
+      end: new Date(nowMs).toISOString(),
+    },
+    platform: { primary: toPlatformPrimary(platform), models: [] },
+    core_metrics: {
+      compression_ratio: round(compressionRatio, 4),
+      prompt_complexity: round(clamp(sessionDepth, 0, 100), 2),
+      cross_thread_score: clamp(Math.round(cacheRead / Math.max(cacheCreate, 1)), 0, 100000),
+      session_depth_avg: round(Math.max(0, sessionDepth), 2),
+      // M.05 token_throughput muted 2026-06-26 — word-era metric the web already
+      // mutes (RS01 tt→0) + strips. Send null (RPC p_token_throughput is nullable
+      // DEFAULT NULL). raw_telemetry.tokens_total still carries the raw count.
+      token_throughput: null,
+    },
+    background_metrics: {
+      message_volume: msgs,
+      account_age_days: Math.max(1, Math.round(opts.accountAgeDays ?? 365)),
+      total_messages_lifetime: Math.max(msgs, Math.round(opts.totalMessages ?? msgs)),
+    },
+    raw_telemetry: {
+      sessions_count: sessionsCount,
+      turns_total: turnsTotal,
+      tokens_total: tokensTotal,
+      tokens_input_fresh: input,
+      tokens_output: output,
+      tokens_cache_read: cacheRead,
+      tokens_cache_creation: cacheCreate,
+      active_minutes_est: activeMinutes,
+    },
+    tier: 'free',
+    agent: {
+      version: identity.agent_version,
+      ruleset_version: RULESET_VERSION,
+      snapshot_hash: '',
+      public_key: identity.public_key,
+    },
+  }
+  payload.agent.snapshot_hash = snapshotHash(payload)
+  return payload
+}
+
+/**
+ * submitSignedWindow — build + sign + POST one window to /api/v1/snapshots.
+ * Returns a structured result; never throws on a network error. opts: { apiBase,
+ * fetchImpl, platform, now } (fetchImpl lets the caller inject a timeout-wrapped fetch).
+ */
+export async function submitSignedWindow(windowKey, pillars, messages, identity, opts = {}) {
+  if (!identity?.codename || !identity?.operator_id) {
+    return { status: 'not_enrolled', reason: 'not_enrolled', detail: 'Run `npx sigrank-mcp enroll` to bind this device first.' }
+  }
+  if (!identity?.private_key_pkcs8_b64) {
+    return { status: 'error', reason: 'no_key', detail: 'No local signing key — re-run `npx sigrank-mcp enroll`.' }
+  }
+
+  const apiBase = opts.apiBase || process.env.SIGRANK_API_BASE || 'https://signalaf.com'
+  // FIX M: default a 15s AbortController timeout when the caller doesn't inject a
+  // fetchImpl. The TUI path already wraps fetch (callTool → doFetch, 10s), but the
+  // legacy CLI `watch --submit` + the CLI default-view [S] call submitSignedWindow
+  // with no fetchImpl → bare fetch → a hung POST blocks forever. This default fixes
+  // it everywhere at once. (15s is generous for a signed POST to /api/v1/snapshots.)
+  const fetchImpl = opts.fetchImpl || ((url, init = {}) => {
+    const ctrl = new AbortController()
+    const timer = setTimeout(() => ctrl.abort(), 15_000)
+    return fetch(url, { ...init, signal: init.signal || ctrl.signal }).finally(() => clearTimeout(timer))
+  })
+  const payload = buildPayload(windowKey, pillars, messages, identity, opts.platform || 'claude', opts)
+  const signature = signPayload(payload, identity.private_key_pkcs8_b64)
+
+  let res
+  let ack
+  try {
+    res = await fetchImpl(`${apiBase}/api/v1/snapshots`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        'x-agent-signature': signature,
+      },
+      body: JSON.stringify(payload),
+    })
+    try {
+      ack = await res.json()
+    } catch {
+      ack = {}
+    }
+  } catch (e) {
+    return { status: 'error', reason: 'network', detail: e.message, window: WINDOW_TYPE[windowKey] || windowKey }
+  }
+
+  return {
+    status: res.ok ? ack.status || 'received' : 'error',
+    httpStatus: res.status,
+    window: WINDOW_TYPE[windowKey] || windowKey,
+    verification_tier: ack.verification_tier ?? null,
+    persisted: ack.persisted ?? null,
+    snapshot_hash: payload.agent.snapshot_hash,
+    reason: res.ok ? null : ack.reason || ack.status || `http_${res.status}`,
+    detail: ack.detail ?? null,
+  }
+}