sigrank 0.0.178 → 0.0.180

package/connect.mjs

@@ -1,13 +1 @@
-// connect.mjs — pure predicates for the TUI consolidation (the TUI is the whole app).
-// No fs, no I/O, no side effects — unit-testable in isolation. Used by tui.mjs to
-// decide sign-in state and to classify keystrokes while the Connect code field is focused.
-
-/** True iff this device identity is signed in (bound to an operator). */
-export function isSignedIn(id) {
-  return !!(id && id.codename && id.operator_id);
-}
-
-/** True iff `s` is a single character a connect code can contain ([A-Za-z0-9-]). */
-export function isCodeChar(s) {
-  return typeof s === "string" && /^[A-Za-z0-9-]$/.test(s);
-}
+export * from './identity/connect.mjs';

package/identity/connect.mjs

@@ -0,0 +1,13 @@
+// connect.mjs — pure predicates for the TUI consolidation (the TUI is the whole app).
+// No fs, no I/O, no side effects — unit-testable in isolation. Used by tui.mjs to
+// decide sign-in state and to classify keystrokes while the Connect code field is focused.
+
+/** True iff this device identity is signed in (bound to an operator). */
+export function isSignedIn(id) {
+  return !!(id && id.codename && id.operator_id);
+}
+
+/** True iff `s` is a single character a connect code can contain ([A-Za-z0-9-]). */
+export function isCodeChar(s) {
+  return typeof s === "string" && /^[A-Za-z0-9-]$/.test(s);
+}

package/identity/keystore.mjs

@@ -0,0 +1,242 @@
+// 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,
+  readdirSync,
+  copyFileSync,
+} from "node:fs";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+
+const DIR = join(homedir(), ".sigrank-mcp");
+const PATH = join(DIR, "identity.json");
+const BACKUP_PREFIX = "identity.json.bak-";
+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;
+}
+
+/** 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). Backs up the existing
+ * file before overwriting so a corrupt write or accidental reset can be recovered. */
+export function persistIdentity(identity) {
+  mkdirSync(DIR, { recursive: true });
+  try {
+    chmodSync(DIR, 0o700);
+  } catch {
+    /* best-effort on platforms without chmod */
+  }
+  // Back up the existing identity before overwriting (resilience: if the write
+  // fails or the file is later lost, the backup carries the binding + keys).
+  if (existsSync(PATH)) {
+    try {
+      const stamp = Date.now();
+      copyFileSync(PATH, join(DIR, `${BACKUP_PREFIX}${stamp}`));
+      pruneBackups();
+    } catch {
+      /* best-effort — don't block the write */
+    }
+  }
+  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).
+ * Self-healing: if the identity has keys + device_id but no codename (binding
+ * lost via partial write / version transition), scans backups for a matching
+ * device_id and restores the binding before returning.
+ */
+export function ensureIdentity() {
+  const existing = loadIdentity();
+  if (
+    existing?.private_key_pkcs8_b64 &&
+    existing?.public_key &&
+    existing?.device_id
+  ) {
+    // Self-healing: keys present but binding lost → try to restore from backups.
+    if (!existing.codename || !existing.operator_id) {
+      const restored = restoreBindingFromBackups(existing.device_id);
+      if (restored) {
+        existing.codename = restored.codename;
+        existing.operator_id = restored.operator_id;
+        existing.enrolled_at = restored.enrolled_at;
+        return persistIdentity(existing);
+      }
+    }
+    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 */
+  }
+}
+
+/** Keep at most MAX_BACKUPS backup files (oldest deleted first). */
+function pruneBackups() {
+  try {
+    const files = readdirSync(DIR)
+      .filter((f) => f.startsWith(BACKUP_PREFIX))
+      .sort(); // timestamp-suffixed → lexicographic = chronological
+    while (files.length > MAX_BACKUPS) {
+      unlinkSync(join(DIR, files.shift()));
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Scan backup files for one with the same device_id that carries a codename +
+ * operator_id binding. Returns { codename, operator_id, enrolled_at } or null.
+ * Used by ensureIdentity() to self-heal when the live file lost its binding
+ * (e.g. a partial write or version transition that preserved keys but dropped
+ * the binding metadata). Only restores from a backup with the SAME device_id —
+ * never crosses device boundaries (Frankenstein-identity guard). */
+export function restoreBindingFromBackups(device_id) {
+  if (!device_id) return null;
+  try {
+    const files = readdirSync(DIR)
+      .filter((f) => f.startsWith(BACKUP_PREFIX))
+      .sort()
+      .reverse(); // newest first — prefer the most recent binding
+    for (const f of files) {
+      try {
+        const bak = JSON.parse(readFileSync(join(DIR, f), "utf-8"));
+        if (
+          bak.device_id === device_id &&
+          bak.codename &&
+          bak.operator_id
+        ) {
+          return {
+            codename: bak.codename,
+            operator_id: bak.operator_id,
+            enrolled_at: bak.enrolled_at ?? null,
+          };
+        }
+      } catch {
+        /* skip corrupt backups */
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+  return null;
+}

package/identity/sign.mjs

@@ -0,0 +1,106 @@
+// 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/index.mjs

@@ -138,7 +138,10 @@ async function startMcpServer() {
             role: "user",
             content: {
               type: "text",
-              text: "Pull my local token usage with tokenpull, compute my yield, and then fetch the leaderboard so I can see where I rank. Show me my class tier and my key metrics (Yield, Leverage, Velocity).",
+              text: readFileSync(
+                new URL("./prompts/check-my-efficiency.md", import.meta.url),
+                "utf8",
+              ).trim(),
             },
           },
         ],
@@ -146,13 +149,17 @@ async function startMcpServer() {
     }
     if (name === "simulate-improvement") {
       const change = args.change || "increase cache reads by 50000";
+      const template = readFileSync(
+        new URL("./prompts/simulate-improvement.md", import.meta.url),
+        "utf8",
+      );
       return {
         messages: [
           {
             role: "user",
             content: {
               type: "text",
-              text: `First pull my local token usage with tokenpull to get my current pillars. Then use simulate_change to answer: "what if I ${change}?" Show me the yield delta and whether my class tier would change.`,
+              text: template.replace(/\{\{change\}\}/g, change).trim(),
             },
           },
         ],
@@ -165,7 +172,10 @@ async function startMcpServer() {
             role: "user",
             content: {
               type: "text",
-              text: "Fetch the SigRank leaderboard with get_leaderboard, then pull my local token usage with tokenpull. Compare my yield, leverage, and velocity against the top operator. What's the gap and what would I need to change to close it?",
+              text: readFileSync(
+                new URL("./prompts/compare-with-leader.md", import.meta.url),
+                "utf8",
+              ).trim(),
             },
           },
         ],
@@ -204,156 +214,21 @@ async function startMcpServer() {
         "How SigRank protects user privacy: runs locally, only four token counts (input, output, cacheCreate, cacheRead) leave the machine, ed25519-signed submissions, no prompt content ever transmitted.",
       mimeType: "text/markdown",
     },
+    {
+      uri: "sigrank://data-policy",
+      name: "Data Policy",
+      description:
+        "Summary of SigRank data governance: what we collect, what we do not collect, consent requirements, and how to pause, delete, or export your data.",
+      mimeType: "text/markdown",
+    },
   ];
 
-  const RESOURCE_CONTENT = {
-    "sigrank://scoring-formula": `# SigRank Scoring Formula
-
-## Yield (Υ) — the headline metric
-
-\`\`\`
-Υ = Cache Reads × Output / Input²
-\`\`\`
-
-Yield rewards operators who maximize output while minimizing input — and who build cache to amortize that input across sessions. A high yield means you're getting more done with less, efficiently.
-
-## Derived Metrics
-
-| Metric | Formula | Meaning |
-|--------|---------|---------|
-| **SNR** | Output / (Input + CacheCreate) | Signal-to-noise: how much of your token spend is productive output vs. overhead |
-| **Leverage** | Cache Reads / Input | How well you reuse cached context — higher = better cache utilization |
-| **Velocity** | Output / Input | Raw output efficiency — how much output you generate per token of input |
-| **10xDEV** | Composite score | Weighted blend of yield, leverage, and velocity for cross-platform comparison |
-
-## Class Tier Thresholds
-
-| Tier | Yield Range | Profile |
-|------|-------------|---------|
-| **Burner** | Υ < 1.0 | Raw volume — high input, low cache reuse, brute-force output |
-| **Builder** | 1.0 ≤ Υ < 10.0 | Balanced — moderate cache, decent output efficiency |
-| **10xer** | Υ ≥ 10.0 | Cascade-optimized — high cache reads, minimal input, efficient output |
-
-The formula is deterministic and computed locally. No network calls needed for scoring.
-`,
-
-    "sigrank://class-tiers": `# SigRank Class Tiers
-
-Every operator is classified into one of three tiers based on their Yield (Υ = Cache Reads × Output / Input²).
-
-## Burner (Υ < 1.0)
-- **Profile:** Raw volume operators. High input tokens, low cache reuse.
-- **Behavior:** Brute-force — lots of context fed in, relatively little output back.
-- **Typical:** New AI users, verbose prompters, no session continuity.
-- **Fix:** Build cache across sessions. Stop re-explaining context. Use --continue.
-
-## Builder (1.0 ≤ Υ < 10.0)
-- **Profile:** Balanced operators. Moderate cache, decent output efficiency.
-- **Behavior:** Productive — reasonable input-to-output ratio, some cache leverage.
-- **Typical:** Experienced AI coders who use CLAUDE.md, project context, and session continuity.
-- **Fix:** Increase cache reads by reusing sessions. Reduce input by trimming unnecessary context.
-
-## 10xer (Υ ≥ 10.0)
-- **Profile:** Cascade-optimized operators. High cache reads, minimal input, efficient output.
-- **Behavior:** Surgical — minimal new input, maximum cache reuse, high-yield output.
-- **Typical:** Power users with long-running sessions, tight context windows, and aggressive cache strategies.
-- **Maintain:** Keep cache hit rate high. Avoid context bloat. Monitor with watch_tokenpull.
-
-Tiers are recalculated on every submission. Your tier can change between windows (7d, 30d, 90d, all-time).
-`,
-
-    "sigrank://install-guide": `# SigRank Quick Start
-
-## Install
-
-\`\`\`bash
-npx sigrank
-\`\`\`
-
-No global install needed. The MCP server starts automatically when an AI client (Claude, Cursor, Cline) connects.
-
-## First Submission
-
-1. **Enroll** — register your operator codename:
-   \`\`\`bash
-   npx sigrank enroll
-   \`\`\`
-
-2. **Pull + Submit** — scan your local AI session logs and publish:
-   \`\`\`bash
-   npx sigrank submit
-   \`\`\`
-
-3. **Dry Run** — see exactly what would be sent before publishing:
-   \`\`\`bash
-   npx sigrank submit --dry-run
-   \`\`\`
-
-## Token Pull Sources
-
-SigRank bundles two token readers as npm dependencies:
-- **ccusage** — Claude Code session logs
-- **tokscale** — multi-platform token telemetry
-
-A third source, **token-dashboard**, is read from \`~/.claude/token-dashboard.db\` (SQLite).
-That DB is created by [Nate's token-dashboard](https://github.com/nateherkai/token-dashboard) (Python):
-\`\`\`bash
-git clone https://github.com/nateherkai/token-dashboard.git
-cd token-dashboard
-python3 cli.py dashboard
-\`\`\`
-Run the scan once to create the DB; SigRank reads it directly via sqlite3 after that.
-
-## MCP Client Setup
-
-Add to your MCP client config:
-\`\`\`json
-{
-  "mcpServers": {
-    "sigrank": {
-      "command": "npx",
-      "args": ["sigrank"]
-    }
-  }
-}
-\`\`\`
-
-## Live Board
-
-Visit https://signalaf.com to see the global leaderboard.
-`,
-
-    "sigrank://privacy-model": `# SigRank Privacy Model
-
-## What leaves your machine
-
-**Only four numbers per submission:**
-- Input tokens
-- Output tokens
-- Cache create tokens
-- Cache read tokens
-
-**That's it.** No prompts, no code, no file contents, no conversation text.
-
-## How it works
-
-1. **Local-first:** All token pulling happens on your machine. SigRank reads session logs from ~/.claude, ~/.codex, ~/.local/share/amp, etc.
-2. **Token counts only:** The MCP tools extract integer counts from log metadata. The actual content of your conversations is never read, parsed, or transmitted.
-3. **Signed submission:** Submissions are ed25519-signed. The board verifies authenticity without seeing your data.
-4. **No auth required:** No API keys, no OAuth, no account needed to read the leaderboard. Enrollment only requires a codename.
-
-## What SigRank can NOT see
-
-- Your prompts or messages
-- Your code or file contents
-- Your tool calls or their results
-- Which AI platform you use (beyond token counts)
-- Your identity (only your chosen codename)
-
-## Verification
-
-The submit_verified tool uses ed25519 signing. The board's source_attestations table records the signature for audit. You can verify your own submissions via get_operator.
-`,
+  const RESOURCE_FILES = {
+    "sigrank://scoring-formula": "./resources/scoring-formula.md",
+    "sigrank://class-tiers": "./resources/class-tiers.md",
+    "sigrank://install-guide": "./resources/install-guide.md",
+    "sigrank://privacy-model": "./resources/privacy-model.md",
+    "sigrank://data-policy": "./resources/data-policy.md",
   };
 
   server.setRequestHandler(ListResourcesRequestSchema, async () => ({
@@ -361,10 +236,11 @@ The submit_verified tool uses ed25519 signing. The board's source_attestations t
   }));
   server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
     const uri = req.params.uri;
-    const content = RESOURCE_CONTENT[uri];
-    if (!content) {
+    const file = RESOURCE_FILES[uri];
+    if (!file) {
       throw new McpError(ErrorCode.InvalidParams, `Unknown resource: ${uri}`);
     }
+    const content = readFileSync(new URL(file, import.meta.url), "utf8");
     return {
       contents: [
         {
@@ -380,15 +256,23 @@ The submit_verified tool uses ed25519 signing. The board's source_attestations t
 }
 
 // Route:
-//   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)
+//   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 stdin+stdout → full tabbed TUI (interactive use — needs keyboard input)
+//   no args + piped (either)  → MCP stdio server (AI client / proxy / container use)
+//   SIGRANK_MCP_SERVER=1      → force MCP stdio server (manual override)
+//
+// The stdin check is critical for container/proxy environments (Glama, mcp-proxy,
+// Docker with -t). These may allocate a pseudo-TTY for stdout, but stdin is piped
+// because the proxy writes JSON-RPC messages to it. The TUI needs keyboard input
+// from stdin, so if stdin is piped the TUI would hang — force MCP mode instead.
 const cliArgs = process.argv.slice(2);
 if (cliArgs.length > 0) {
   runCli(process.argv);
-} else if (process.stdout.isTTY) {
-  // Interactive terminal — launch the full tabbed TUI
+} else if (process.env.SIGRANK_MCP_SERVER === "1") {
+  startMcpServer();
+} else if (process.stdout.isTTY && process.stdin.isTTY) {
+  // Interactive terminal with keyboard — launch the full tabbed TUI
   const { runTui } = await import("./tui.mjs");
   runTui();
 } else {