ashlr-plugin 1.36.4

package/scripts/install-status-line.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env bun
+/**
+ * One-shot installer that wires the ashlr status-line script into the user's
+ * Claude Code settings.
+ *
+ * Strategy for safe merging:
+ *   1. Read ~/.claude/settings.json if it exists; parse it as JSON. If the file
+ *      is corrupt, abort loudly — we will not overwrite a file we can't parse.
+ *   2. Take a timestamped backup (settings.json.bak-<epoch>) before writing.
+ *   3. Shallow-merge: set settings.statusLine = { type: "command", command: "..." }
+ *      only if statusLine is missing OR already points at our script. We never
+ *      clobber a custom statusLine the user has configured for something else.
+ *   4. Ensure settings.ashlr defaults exist (statusLine + sub-toggles), again
+ *      only filling in keys that aren't already set.
+ *   5. Write back with 2-space indent, preserving every other top-level key.
+ *
+ * Idempotent: re-running is a no-op aside from refreshing the absolute path
+ * to the script (in case the plugin moved).
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+import { c, sym, box, isColorEnabled, prefix } from "./ui.ts";
+
+interface StatusLineCmd {
+  type: "command";
+  command: string;
+  padding?: number;
+}
+
+interface ClaudeSettings {
+  statusLine?: StatusLineCmd | unknown;
+  ashlr?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+const SCRIPT_PATH = resolve(import.meta.dir, "savings-status-line.ts");
+const SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+const COMMAND = `bun run ${SCRIPT_PATH}`;
+
+function isOurStatusLine(sl: unknown): sl is StatusLineCmd {
+  if (!sl || typeof sl !== "object") return false;
+  const cmd = (sl as { command?: unknown }).command;
+  return typeof cmd === "string" && cmd.includes("savings-status-line");
+}
+
+function main(): void {
+  let settings: ClaudeSettings = {};
+  let existed = false;
+
+  if (existsSync(SETTINGS_PATH)) {
+    existed = true;
+    const raw = readFileSync(SETTINGS_PATH, "utf-8");
+    try {
+      settings = JSON.parse(raw) as ClaudeSettings;
+    } catch (err) {
+      const msg = (err as Error).message;
+      const head = isColorEnabled()
+        ? `${c.red(sym.cross)} ${c.bold("refusing to touch")} ${c.cyan(SETTINGS_PATH)}`
+        : `refusing to touch ${SETTINGS_PATH}`;
+      console.error(`${head}: not valid JSON (${msg})`);
+      process.exit(1);
+    }
+    // Backup before any write.
+    const backup = `${SETTINGS_PATH}.bak-${Date.now()}`;
+    copyFileSync(SETTINGS_PATH, backup);
+  } else {
+    mkdirSync(dirname(SETTINGS_PATH), { recursive: true });
+  }
+
+  const actions: string[] = [];
+
+  // 1. statusLine command
+  const currentSl = settings.statusLine;
+  if (!currentSl) {
+    settings.statusLine = { type: "command", command: COMMAND, padding: 0 };
+    actions.push("added statusLine command");
+  } else if (isOurStatusLine(currentSl)) {
+    if ((currentSl as StatusLineCmd).command !== COMMAND) {
+      (settings.statusLine as StatusLineCmd).command = COMMAND;
+      actions.push("refreshed statusLine command path");
+    } else {
+      actions.push("statusLine already installed (no change)");
+    }
+  } else {
+    const warnHead = isColorEnabled()
+      ? `${c.yellow(sym.warn)} ${c.bold("warning:")}`
+      : "warning:";
+    console.warn(
+      `${warnHead} an existing statusLine is configured and points elsewhere; leaving it alone.`,
+    );
+    const cmd = isColorEnabled() ? c.cyan(COMMAND) : COMMAND;
+    console.warn(`  to use ashlr instead, set statusLine.command to: ${cmd}`);
+  }
+
+  // 2. ashlr defaults
+  const ashlr = (settings.ashlr ??= {}) as Record<string, unknown>;
+  const defaults: Record<string, boolean> = {
+    statusLine: true,
+    statusLineSession: true,
+    statusLineLifetime: true,
+    statusLineTips: true,
+  };
+  let addedDefaults = 0;
+  for (const [k, v] of Object.entries(defaults)) {
+    if (!(k in ashlr)) {
+      ashlr[k] = v;
+      addedDefaults++;
+    }
+  }
+  if (addedDefaults > 0) actions.push(`seeded ${addedDefaults} ashlr default toggle(s)`);
+
+  writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+
+  const verb = existed ? "updated" : "created";
+  const verbColored = isColorEnabled() ? c.brightGreen(c.bold(verb)) : verb;
+  const pathColored = isColorEnabled() ? c.cyan(SETTINGS_PATH) : SETTINGS_PATH;
+  console.log(`${prefix.ok(`${verbColored} ${pathColored}`)}`);
+  for (const a of actions) {
+    const dotGlyph = isColorEnabled() ? c.magenta(sym.bullet) : "-";
+    console.log(`  ${dotGlyph} ${a}`);
+  }
+  const scriptLabel = isColorEnabled() ? c.dim("status-line script:") : "status-line script:";
+  const scriptColored = isColorEnabled() ? c.cyan(SCRIPT_PATH) : SCRIPT_PATH;
+  console.log(`${scriptLabel} ${scriptColored}`);
+
+  // On a TTY, include a small summary box so the install feels complete.
+  if (isColorEnabled()) {
+    const body = [
+      `${prefix.ok("status line wired")}`,
+      `  reload Claude Code to see it`,
+      `  toggle anytime via ${c.cyan("/ashlr-settings")}`,
+    ].join("\n");
+    console.log("");
+    console.log(box(body, { title: "ashlr status line", color: c.green }));
+  }
+}
+
+if (import.meta.main) {
+  try {
+    main();
+  } catch (err) {
+    const head = isColorEnabled()
+      ? `${c.red(sym.cross)} ${c.bold("install-status-line failed:")}`
+      : "install-status-line failed:";
+    console.error(`${head} ${(err as Error).message}`);
+    process.exit(1);
+  }
+}

package/scripts/mcp-entrypoint.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# ashlr-plugin MCP server entrypoint (LEGACY — Unix-only ports).
+#
+# NOTE: Claude Code itself no longer uses this script. As of v1.15 the
+# canonical entrypoint is `scripts/bootstrap.mjs`, which hands off to
+# `scripts/mcp-entrypoint.ts`. Both run on Windows without Git Bash.
+#
+# This `.sh` is retained ONLY for the Unix-only `ports/` distributions
+# (Cursor, Goose — see `ports/cursor/mcp.json` and `ports/README.md`).
+# If you are on Windows and something invoked this file, that is a bug:
+# your plugin config should point at `scripts/bootstrap.mjs` instead.
+#
+# Wraps every MCP server launch with idempotent self-healing:
+#   1. cd to the plugin root
+#   2. if node_modules is missing, run `bun install` (once; subsequent launches skip)
+#   3. opportunistically drop stale sibling versioned cache dirs (best-effort)
+#   4. exec `bun run <server.ts>` with any passed args
+#
+# Usage (ports distributions only):
+#   "command": "bash",
+#   "args": ["${ASHLR_PLUGIN_ROOT}/scripts/mcp-entrypoint.sh", "servers/foo-server.ts"]
+#
+# All output is suppressed to stdout (since stdio is the MCP protocol channel).
+# Logs go to stderr, which Claude Code surfaces in its transcript.
+
+# Hard guard: if somehow invoked on Windows, redirect the caller to the
+# bun/node-native entrypoint. MSYS/MINGW/CYGWIN all set OSTYPE accordingly.
+case "${OSTYPE:-}" in
+  msys*|cygwin*|win32*)
+    echo "[ashlr] mcp-entrypoint.sh is Unix-only." >&2
+    echo "[ashlr] On Windows, point your MCP config at scripts/bootstrap.mjs instead:" >&2
+    echo "[ashlr]   node \"\${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs\" servers/<server>.ts" >&2
+    exit 1
+    ;;
+esac
+
+set -e
+
+# Resolve plugin root from the entrypoint's own path (never trust cwd).
+PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$PLUGIN_ROOT"
+
+# 1. Self-install deps if missing. Idempotent.
+if [ ! -d "node_modules/@modelcontextprotocol/sdk" ]; then
+  echo "[ashlr] first-run: installing dependencies in $PLUGIN_ROOT" >&2
+  if ! bun install --silent >&2 2>&1; then
+    echo "[ashlr] bun install failed. Ensure bun is on PATH and network is available." >&2
+    echo "[ashlr] Manual fix: cd \"$PLUGIN_ROOT\" && bun install" >&2
+    exit 1
+  fi
+fi
+
+# 2. Opportunistically drop stale sibling version caches. Safe: strict semver
+#    guard + skip current dir. Non-version dirs (latest, dev-branch) survive.
+CURRENT_VERSION="$(basename "$PLUGIN_ROOT")"
+PARENT="$(dirname "$PLUGIN_ROOT")"
+if [[ "$CURRENT_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] && [ -d "$PARENT" ] && [[ "$PARENT" == */plugins/cache/* ]]; then
+  for sib in "$PARENT"/*/; do
+    sib="${sib%/}"
+    name="$(basename "$sib")"
+    if [[ "$name" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] && [ "$name" != "$CURRENT_VERSION" ]; then
+      rm -rf "$sib" 2>/dev/null && echo "[ashlr] removed stale cache: $name" >&2 || true
+    fi
+  done
+fi
+
+# 3. Forward Claude Code's session id so MCP servers can attribute savings to
+#    the correct per-session bucket in ~/.ashlr/stats.json. Without this, the
+#    status line's "session +N" number gets clobbered across concurrent
+#    terminals. We export both the canonical name and a mirror so any tool in
+#    the subprocess tree can read it.
+if [ -n "${CLAUDE_SESSION_ID:-}" ]; then
+  export CLAUDE_SESSION_ID
+  export ASHLR_SESSION_ID="$CLAUDE_SESSION_ID"
+fi
+
+# 4. Exec the requested server script with any remaining args.
+exec bun run "$@"

package/scripts/mcp-entrypoint.ts

@@ -0,0 +1,130 @@
+#!/usr/bin/env bun
+/**
+ * Bun-native MCP server entrypoint. Replaces `scripts/mcp-entrypoint.sh`
+ * so the plugin works on Windows without Git Bash.
+ *
+ * Responsibilities (in order):
+ *   1. Resolve PLUGIN_ROOT from __dirname (never trust cwd).
+ *   2. Self-install deps if the MCP SDK cannot be resolved from the plugin.
+ *   3. Opportunistically drop stale sibling versioned cache dirs.
+ *   4. Forward CLAUDE_SESSION_ID so savings bucket to the right session.
+ *   5. Spawn `bun run <server.ts>` as a child and forward stdio 1:1 so the
+ *      MCP protocol continues to own stdin/stdout/stderr.
+ *
+ * Why not `await import()` the server directly? Bun would share the import
+ * cache with this bootstrapping module, which subtly breaks servers that
+ * assume they own `process.argv` or call `process.exit`. A dedicated child
+ * keeps the MCP process cleanly isolated.
+ *
+ * Usage (in .claude-plugin/plugin.json mcpServers entries):
+ *   "command": "bun",
+ *   "args": ["run", "${CLAUDE_PLUGIN_ROOT}/scripts/mcp-entrypoint.ts", "servers/_router.ts"]
+ */
+
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const PLUGIN_ROOT = resolve(dirname(__filename), "..");
+process.chdir(PLUGIN_ROOT);
+
+// 1. Self-install deps if missing. Idempotent — `bun install` is a no-op once
+//    node_modules is populated.
+// npm may hoist dependencies into an ancestor node_modules directory. Resolve
+// the exact SDK modules used by the router, from this plugin's location, rather
+// than treating the absence of a nested directory as a missing dependency.
+// Resolution does not execute third-party code or consult a caller-selected cwd.
+let sdkReady = false;
+try {
+  for (const specifier of [
+    "@modelcontextprotocol/sdk/server/index.js",
+    "@modelcontextprotocol/sdk/server/stdio.js",
+    "@modelcontextprotocol/sdk/types.js",
+  ]) {
+    Bun.resolveSync(specifier, PLUGIN_ROOT);
+  }
+  sdkReady = true;
+} catch {
+  // Preserve the existing first-run recovery for genuinely missing SDK modules.
+}
+if (!sdkReady) {
+  console.error(`[ashlr] first-run: installing dependencies in ${PLUGIN_ROOT}`);
+  const result = Bun.spawnSync(["bun", "install", "--silent"], {
+    cwd: PLUGIN_ROOT,
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  if (!result.success) {
+    console.error(`[ashlr] bun install failed. Ensure bun is on PATH and network is available.`);
+    console.error(`[ashlr] Manual fix: cd "${PLUGIN_ROOT}" && bun install`);
+    process.exit(1);
+  }
+}
+
+// 2. Opportunistically drop stale sibling version caches. Safe: strict semver
+//    guard + skip current dir. Non-version dirs (latest, dev-branch) survive.
+//    Handles both Unix and Windows path separators for the "plugins/cache"
+//    marker so it fires correctly inside %USERPROFILE%\.claude\plugins\cache\.
+const currentVersion = basename(PLUGIN_ROOT);
+const parent = dirname(PLUGIN_ROOT);
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const inCacheDir =
+  parent.includes(`${resolve("/").slice(0, 1)}plugins${resolve("/").slice(0, 1)}cache`) ||
+  parent.includes("/plugins/cache/") ||
+  parent.includes("\\plugins\\cache\\");
+if (SEMVER.test(currentVersion) && existsSync(parent) && inCacheDir) {
+  try {
+    for (const sib of readdirSync(parent)) {
+      if (!SEMVER.test(sib) || sib === currentVersion) continue;
+      const sibPath = resolve(parent, sib);
+      try {
+        if (statSync(sibPath).isDirectory()) {
+          rmSync(sibPath, { recursive: true, force: true });
+          console.error(`[ashlr] removed stale cache: ${sib}`);
+        }
+      } catch {
+        // Best-effort — if a rm fails (permissions, busy files on Windows),
+        // skip it. The cache still works; just keeps a bit of extra disk.
+      }
+    }
+  } catch {
+    // readdirSync of the parent failed — not fatal; proceed.
+  }
+}
+
+// 3. Forward Claude Code's session id so MCP servers attribute savings to the
+//    correct per-session bucket in ~/.ashlr/stats.json. Without this, the
+//    status-line "session +N" number gets clobbered across concurrent
+//    terminals. Mirror under ASHLR_SESSION_ID for subprocesses to read.
+if (process.env["CLAUDE_SESSION_ID"]) {
+  process.env["ASHLR_SESSION_ID"] = process.env["CLAUDE_SESSION_ID"];
+}
+
+// 4. Exec the requested server script. Any remaining argv are passed through
+//    to `bun run <script> [...args]`, preserving compatibility with the bash
+//    entrypoint's `exec bun run "$@"` behavior.
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error(`[ashlr] usage: mcp-entrypoint.ts <server.ts> [...args]`);
+  process.exit(1);
+}
+
+const child = Bun.spawn(["bun", "run", ...args], {
+  cwd: PLUGIN_ROOT,
+  stdio: ["inherit", "inherit", "inherit"],
+  env: process.env,
+});
+
+// Propagate SIGINT/SIGTERM so a plugin reload or shutdown cleans up cleanly.
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    try {
+      child.kill(signal);
+    } catch {
+      // Child may already be gone; ignore.
+    }
+  });
+}
+
+const exitCode = await child.exited;
+process.exit(exitCode);

package/scripts/mdx-angle-bracket-lint.ts

@@ -0,0 +1,152 @@
+#!/usr/bin/env bun
+/**
+ * mdx-angle-bracket-lint.ts — flag unbacked `<placeholder>` tokens in body
+ * prose of `commands/*.md` and `site/content/docs/skills/*.mdx`.
+ *
+ * Why: Fumadocs' MDX parser interprets bare angle-bracket tokens
+ * (e.g. `<task>`, `<amount>`, `<level>`) as JSX tags. The Vercel docs build
+ * fails when these appear in prose. The convention is to wrap them in inline
+ * backticks so MDX renders them as literal `<task>` text.
+ *
+ * Strategy:
+ *   - Read every target file
+ *   - Skip code fences (``` ... ```), inline-code spans (`...`), HTML comments
+ *   - Skip frontmatter (--- ... ---) and YAML inside fences
+ *   - For remaining content, flag any `<word-or-placeholder>` not preceded by
+ *     a real-tag whitelist (e.g. `<br>`, `<details>`, `<summary>`, `<a ...>`,
+ *     `<img ...>`, etc.)
+ *
+ * Usage:
+ *   bun run scripts/mdx-angle-bracket-lint.ts                # lint all targets, exit non-zero on fail
+ *   bun run scripts/mdx-angle-bracket-lint.ts <file>...      # lint specific files
+ *   bun run scripts/mdx-angle-bracket-lint.ts --quiet        # exit code only, no per-file output
+ */
+
+import { readFileSync, readdirSync, statSync } from "fs";
+import { join, resolve } from "path";
+
+const KNOWN_HTML_TAGS = new Set([
+  "a", "abbr", "address", "article", "aside", "audio", "b", "blockquote", "br",
+  "button", "canvas", "caption", "code", "col", "colgroup", "data", "datalist",
+  "dd", "del", "details", "dfn", "dialog", "div", "dl", "dt", "em", "embed",
+  "fieldset", "figcaption", "figure", "footer", "form", "h1", "h2", "h3", "h4",
+  "h5", "h6", "head", "header", "hr", "html", "i", "iframe", "img", "input",
+  "ins", "kbd", "label", "legend", "li", "main", "mark", "menu", "meta",
+  "meter", "nav", "noscript", "object", "ol", "optgroup", "option", "output",
+  "p", "param", "picture", "pre", "progress", "q", "rp", "rt", "ruby", "s",
+  "samp", "script", "section", "select", "small", "source", "span", "strong",
+  "style", "sub", "summary", "sup", "svg", "table", "tbody", "td", "template",
+  "textarea", "tfoot", "th", "thead", "time", "title", "tr", "track", "u",
+  "ul", "var", "video", "wbr",
+  // Closing tags appear as </tag>; allow common patterns
+  "br/", "hr/",
+]);
+
+interface LintError {
+  file: string;
+  line: number;
+  col: number;
+  match: string;
+}
+
+/** Strip code fences and inline-code spans from a line array, in-place. */
+export function stripFences(content: string): string {
+  // Remove fenced code blocks first.
+  let out = content.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, " "));
+  // Remove inline code spans `...`
+  out = out.replace(/`[^`\n]+`/g, (m) => m.replace(/[^\n]/g, " "));
+  // Remove HTML comments
+  out = out.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
+  // Strip YAML frontmatter at top of file (--- through ---)
+  out = out.replace(/^---\n[\s\S]*?\n---\n/, (m) => m.replace(/[^\n]/g, " "));
+  return out;
+}
+
+/** Lint a single file's content. Returns array of errors (empty == ok). */
+export function lintContent(file: string, content: string): LintError[] {
+  const stripped = stripFences(content);
+  const errors: LintError[] = [];
+  const lines = stripped.split("\n");
+  // Match `<word>` and `<word>...</word>` opening, but NOT real HTML/JSX tags
+  // (those have attributes or are in known list).
+  // We're conservative: any `<NAME>` where NAME is lowercase letters or has
+  // hyphens but no `=`, no `/`, no spaces, and not in the known tag set.
+  const TOKEN_RE = /<([a-z][a-z0-9_-]*)>/gi;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    let m: RegExpExecArray | null;
+    TOKEN_RE.lastIndex = 0;
+    while ((m = TOKEN_RE.exec(line)) !== null) {
+      const tag = m[1]!.toLowerCase();
+      if (KNOWN_HTML_TAGS.has(tag)) continue;
+      errors.push({ file, line: i + 1, col: m.index + 1, match: m[0] });
+    }
+  }
+  return errors;
+}
+
+function listMdAndMdx(dir: string): string[] {
+  const out: string[] = [];
+  if (!statSafe(dir)) return out;
+  const stack: string[] = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop()!;
+    for (const entry of readdirSync(cur, { withFileTypes: true })) {
+      const full = join(cur, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile() && (full.endsWith(".md") || full.endsWith(".mdx"))) out.push(full);
+    }
+  }
+  return out;
+}
+
+function statSafe(p: string): boolean {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const quiet = args.includes("--quiet");
+  const explicit = args.filter((a) => !a.startsWith("--"));
+
+  const cwd = process.cwd();
+  const targets: string[] = [];
+  if (explicit.length > 0) {
+    for (const t of explicit) targets.push(resolve(cwd, t));
+  } else {
+    targets.push(...listMdAndMdx(join(cwd, "commands")));
+    targets.push(...listMdAndMdx(join(cwd, "site", "content", "docs", "skills")));
+  }
+
+  let totalErrors = 0;
+  const seenFiles = new Set<string>();
+  for (const file of targets) {
+    if (seenFiles.has(file)) continue;
+    seenFiles.add(file);
+    let content: string;
+    try { content = readFileSync(file, "utf-8"); } catch { continue; }
+    const errors = lintContent(file, content);
+    if (errors.length === 0) continue;
+    totalErrors += errors.length;
+    if (!quiet) {
+      for (const e of errors) {
+        process.stderr.write(`${e.file}:${e.line}:${e.col} unwrapped angle-bracket token: ${e.match}\n`);
+      }
+    }
+  }
+
+  if (totalErrors === 0) {
+    if (!quiet) process.stdout.write(`mdx-lint: ok (${seenFiles.size} files scanned)\n`);
+    process.exit(0);
+  }
+  if (!quiet) {
+    process.stderr.write(`\nmdx-lint: ${totalErrors} unwrapped angle-bracket token(s) across ${seenFiles.size} files.\n`);
+    process.stderr.write(`Fix: wrap them in backticks (e.g. \`<level>\`) so MDX renders them as literal text.\n`);
+  }
+  process.exit(1);
+}
+
+if (import.meta.main) {
+  void main();
+}

package/scripts/measure-cold-start.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+/**
+ * measure-cold-start — time how long the ashlr-router takes from process
+ * launch to a valid `initialize` response over stdio.
+ *
+ * Usage:
+ *   bun run scripts/measure-cold-start.ts              # single run, prints ms
+ *   bun run scripts/measure-cold-start.ts --runs 5     # average of N runs
+ *   bun run scripts/measure-cold-start.ts --assert     # exit 1 if p95 >= 100ms
+ *
+ * The measurement starts at spawn() and ends when the first valid JSON line
+ * appears on stdout (the initialize response). This captures the full
+ * cold-start path: Bun startup + module evaluation + handler registration +
+ * MCP stdio handshake.
+ */
+
+import { spawn } from "bun";
+import { resolve } from "path";
+
+const ROUTER = resolve(import.meta.dir, "..", "servers", "_router.ts");
+
+const INIT_REQUEST =
+  JSON.stringify({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "cold-start-measure", version: "1" },
+    },
+  }) + "\n";
+
+/** Measure one cold-start. Returns elapsed milliseconds. */
+async function measureOnce(): Promise<number> {
+  const t0 = performance.now();
+
+  const proc = spawn({
+    cmd: ["bun", "run", ROUTER],
+    cwd: resolve(import.meta.dir, ".."),
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      ASHLR_STATS_SYNC: "1",
+      ASHLR_SESSION_LOG: "0",
+    },
+  });
+
+  proc.stdin.write(INIT_REQUEST);
+  await proc.stdin.end();
+
+  // Read lines until we get the initialize response.
+  const reader = proc.stdout.getReader();
+  let buf = "";
+  let elapsed = -1;
+
+  outer: while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buf += new TextDecoder().decode(value);
+    const lines = buf.split("\n");
+    buf = lines.pop() ?? "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const msg = JSON.parse(line);
+        if (msg?.result?.serverInfo?.name === "ashlr-router") {
+          elapsed = performance.now() - t0;
+          break outer;
+        }
+      } catch {
+        // not JSON yet — keep reading
+      }
+    }
+  }
+
+  reader.cancel();
+  await proc.exited;
+
+  if (elapsed < 0) throw new Error("Router did not emit an initialize response");
+  return elapsed;
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+const runsArg = args.indexOf("--runs");
+const runs = runsArg >= 0 ? parseInt(args[runsArg + 1] ?? "5", 10) : 1;
+const shouldAssert = args.includes("--assert");
+const TARGET_MS = 100;
+
+const samples: number[] = [];
+for (let i = 0; i < runs; i++) {
+  const ms = await measureOnce();
+  samples.push(ms);
+  process.stdout.write(`  run ${i + 1}/${runs}: ${ms.toFixed(1)}ms\n`);
+}
+
+samples.sort((a, b) => a - b);
+const avg = samples.reduce((s, v) => s + v, 0) / samples.length;
+const p50 = samples[Math.floor(samples.length * 0.5)]!;
+const p95 = samples[Math.floor(samples.length * 0.95)]!;
+const max = samples[samples.length - 1]!;
+
+process.stdout.write(
+  `\nashlr-router cold-start (${runs} run${runs === 1 ? "" : "s"})\n` +
+    `  avg  ${avg.toFixed(1)}ms\n` +
+    `  p50  ${p50.toFixed(1)}ms\n` +
+    `  p95  ${p95.toFixed(1)}ms\n` +
+    `  max  ${max.toFixed(1)}ms\n` +
+    `  target: < ${TARGET_MS}ms\n`,
+);
+
+if (shouldAssert) {
+  if (p95 >= TARGET_MS) {
+    process.stderr.write(
+      `[measure-cold-start] FAIL: p95=${p95.toFixed(1)}ms >= ${TARGET_MS}ms target\n`,
+    );
+    process.exit(1);
+  }
+  process.stdout.write(`[measure-cold-start] PASS: p95=${p95.toFixed(1)}ms < ${TARGET_MS}ms\n`);
+}