@pharaoh-so/mcp 0.3.46 → 0.3.49

package/dist/install-skills.js

@@ -5,12 +5,13 @@
  * through `claude plugin`) and OpenClaw skills in ~/.openclaw/skills/. Also
  * merges the Pharaoh MCP server config into the target platform.
  */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { ensurePharaohHome } from "./credentials.js";
 import { claudeCliFor } from "./setup.js";
-import { getPackageVersion } from "./version.js";
+import { getPackageVersion, PACKAGE_NAME, pinnedPackageSpec } from "./version.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the bundled package root (one level up from dist/). */
 const PKG_ROOT = join(__dirname, "..");
@@ -388,34 +389,81 @@ function cleanupRemovedSkills(srcDir, dstDir, oldManifest) {
     return deleted;
 }
 /**
- * Copy bundled slash command templates (`.md` files in the package's
- * `commands/` directory) to `~/.claude/commands/`, unconditionally
- * overwriting any existing file with the same name.
- *
- * Overwriting is intentional: the install contract is "slash commands just
- * work out of the box," so the canonical shipped versions take precedence
- * over user customizations. Users who want custom command behavior should
- * use different filenames.
+ * Marker the installer writes into the front-matter of every command file it
+ * installs, as a YAML comment Claude Code ignores. A file in
+ * `~/.claude/commands/` is rewritten only when it is Pharaoh's: it carries
+ * this marker, or the exact header and `$ARGUMENTS` footer every installer
+ * before the marker shipped. Any other file with the same name is the user's
+ * and is left alone (security review SC-7).
+ */
+export const PHARAOH_COMMAND_MARKER = "# managed-by: pharaoh-mcp";
+/** The full marker line, with the one thing a reader of the file needs to know. */
+const COMMAND_MARKER_LINE = `${PHARAOH_COMMAND_MARKER} (rewritten by npx ${PACKAGE_NAME} on upgrade; rename this file to keep your own version)`;
+/** The front-matter block of a bundled command, `---` to `---` inclusive. */
+function commandHeader(bundled) {
+    const closing = bundled.indexOf("\n---\n", 4);
+    if (!bundled.startsWith("---\n") || closing === -1) {
+        throw new Error("bundled command file has no front-matter — rebuild the package");
+    }
+    return bundled.slice(0, closing + "\n---\n".length);
+}
+/** The bundled command with the marker as the last front-matter line. */
+function markCommand(bundled) {
+    const header = commandHeader(bundled);
+    const closingAt = header.length - "---\n".length;
+    return `${header.slice(0, closingAt)}${COMMAND_MARKER_LINE}\n${header.slice(closingAt)}${bundled.slice(header.length)}`;
+}
+/**
+ * Whether an existing command file is Pharaoh's and may be rewritten: marked
+ * by this installer, or shaped exactly like the file an earlier installer
+ * copied (its header and the `$ARGUMENTS` footer the generator appends).
+ */
+function isPharaohCommand(existing, bundled) {
+    if (existing.includes(PHARAOH_COMMAND_MARKER))
+        return true;
+    return existing.startsWith(commandHeader(bundled)) && existing.trimEnd().endsWith("$ARGUMENTS");
+}
+/**
+ * Install the bundled slash commands (`.md` files in the package's `commands/`
+ * directory) to `~/.claude/commands/`. A destination that is missing or is
+ * Pharaoh's own file is written; anything else (the user's file, or a symlink,
+ * which is never followed) is kept and reported.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns Number of commands installed.
+ * @returns How many commands were written, and the names of the files kept.
  */
 function installClaudeCodeCommands(home) {
+    const result = { installed: 0, kept: [] };
     if (!existsSync(BUNDLED_COMMANDS_DIR))
-        return 0;
+        return result;
     const commandsDst = join(home, ".claude", "commands");
     mkdirSync(commandsDst, { recursive: true });
-    const entries = readdirSync(BUNDLED_COMMANDS_DIR, { withFileTypes: true });
-    let count = 0;
-    for (const entry of entries) {
+    for (const entry of readdirSync(BUNDLED_COMMANDS_DIR, { withFileTypes: true })) {
         if (!entry.isFile() || !entry.name.endsWith(".md"))
             continue;
-        const src = join(BUNDLED_COMMANDS_DIR, entry.name);
+        const bundled = readFileSync(join(BUNDLED_COMMANDS_DIR, entry.name), "utf-8");
         const dst = join(commandsDst, entry.name);
-        cpSync(src, dst, { force: true });
-        count++;
+        const existing = lstatSync(dst, { throwIfNoEntry: false });
+        if (existing &&
+            (!existing.isFile() || !isPharaohCommand(readFileSync(dst, "utf-8"), bundled))) {
+            result.kept.push(entry.name);
+            continue;
+        }
+        writeFileSync(dst, markCommand(bundled));
+        result.installed++;
     }
-    return count;
+    return result;
+}
+/**
+ * The one-line notice for command files the installer left alone, or null
+ * when there were none.
+ *
+ * @param kept - File names from `runInstallSkills().keptCommands`.
+ */
+export function formatKeptCommands(kept) {
+    if (kept.length === 0)
+        return null;
+    return `Pharaoh: kept your own ~/.claude/commands/${kept.join(", ")} (not Pharaoh's file). Delete one and re-run to take Pharaoh's version.`;
 }
 // ── OpenClaw installer ──────────────────────────────────────────────
 /**
@@ -449,12 +497,14 @@ export function installSkills(home = homedir()) {
     return count;
 }
 /**
- * Read ~/.openclaw/openclaw.json, add the Pharaoh MCP server under `mcpServers`,
- * and write it back. Creates the file if it does not exist. Does NOT overwrite
- * an existing `pharaoh` entry — skips if already present.
+ * Read ~/.openclaw/openclaw.json, set the Pharaoh MCP server under `mcpServers`
+ * to `npx @pharaoh-so/mcp@<this version>`, and write it back. Creates the file
+ * if it does not exist. An existing `pharaoh` entry is re-pinned when it is an
+ * `npx @pharaoh-so/mcp` command (extra arguments kept) and left alone when it
+ * is anything else.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns True if the config was written/updated, false if pharaoh was already present.
+ * @returns True if the config was written, false if it was already current or is not ours.
  */
 export function mergeOpenClawConfig(home = homedir()) {
     const configPath = join(home, ".openclaw", "openclaw.json");
@@ -476,74 +526,125 @@ export function mergeOpenClawConfig(home = homedir()) {
     if (!config.mcpServers) {
         config.mcpServers = {};
     }
-    if (config.mcpServers.pharaoh) {
-        return false;
+    const pinned = pinnedPackageSpec();
+    const current = config.mcpServers.pharaoh;
+    if (current) {
+        const spec = Array.isArray(current.args) ? current.args[0] : undefined;
+        const ours = current.command === "npx" &&
+            (spec === PACKAGE_NAME || (spec?.startsWith(`${PACKAGE_NAME}@`) ?? false));
+        if (!ours || spec === pinned)
+            return false;
     }
     config.mcpServers.pharaoh = {
         command: "npx",
-        args: ["@pharaoh-so/mcp"],
+        args: [pinned, ...(current?.args.slice(1) ?? [])],
     };
     writeFileSync(configPath, JSON.stringify(config, null, "\t"));
     return true;
 }
-// ── Claude Code permission auto-configuration ──────────────────────
-/** Permission prefix that matches all mcp__pharaoh__* tools. */
-const PHARAOH_PERMISSION = "mcp__pharaoh";
+// ── Claude Code permissions ─────────────────────────────────────────
+/**
+ * Rules the interactive setup adds to `permissions.allow` in
+ * ~/.claude/settings.json: the six read-only tools and `pharaoh_account`,
+ * each by full name. Never a prefix rule — `mcp__pharaoh` also auto-approves
+ * account deletion and `pharaoh_admin`, so a prompt injection could run them
+ * with no human in the loop (security review SC-6). Those tools keep prompting.
+ */
+export const PHARAOH_ALLOW_RULES = [
+    "mcp__pharaoh__get_codebase_map",
+    "mcp__pharaoh__get_module_context",
+    "mcp__pharaoh__search_functions",
+    "mcp__pharaoh__get_blast_radius",
+    "mcp__pharaoh__get_unused_code",
+    "mcp__pharaoh__pharaoh_recon",
+    "mcp__pharaoh__pharaoh_account",
+];
+/** The prefix rule proxies 0.3.46 and earlier wrote on every start; replaced by the list above. */
+const LEGACY_ALLOW_RULE = "mcp__pharaoh";
 /**
- * Add "mcp__pharaoh" to ~/.claude/settings.json permissions.allow so that
- * Pharaoh MCP tools auto-approve without prompting the user.
+ * Add `PHARAOH_ALLOW_RULES` to `permissions.allow` in ~/.claude/settings.json,
+ * replacing the blanket `mcp__pharaoh` rule an earlier version wrote. Runs
+ * only from the interactive setup, which prints what happened; never on a
+ * proxy start. Never creates the file: with no settings.json the tools
+ * simply prompt on first use.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns "added" if the permission was inserted, "exists" if already present, "error" on failure.
+ * @returns "added" or "migrated" when the file was written, "current" when
+ *   nothing was missing, "no-settings" when there is no file, "error" when
+ *   the file is not valid JSON (left untouched).
  */
-function configureClaudeCodePermissions(home = homedir()) {
+export function allowReadTools(home = homedir()) {
     const settingsPath = join(home, ".claude", "settings.json");
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
-        }
-        catch {
-            return "error";
-        }
-    }
-    if (!settings.permissions) {
-        settings.permissions = {};
-    }
-    if (!Array.isArray(settings.permissions.allow)) {
-        settings.permissions.allow = [];
+    if (!existsSync(settingsPath))
+        return "no-settings";
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
     }
-    if (settings.permissions.allow.includes(PHARAOH_PERMISSION)) {
-        return "exists";
+    catch {
+        // ALLOWED-CATCH: a file we cannot parse is a file we must not rewrite
+        return "error";
     }
-    settings.permissions.allow.push(PHARAOH_PERMISSION);
+    const allow = Array.isArray(settings.permissions?.allow) ? settings.permissions.allow : [];
+    const migrated = allow.includes(LEGACY_ALLOW_RULE);
+    const kept = allow.filter((rule) => rule !== LEGACY_ALLOW_RULE);
+    const next = [...kept, ...PHARAOH_ALLOW_RULES.filter((rule) => !kept.includes(rule))];
+    if (!migrated && next.length === allow.length)
+        return "current";
+    settings.permissions = { ...settings.permissions, allow: next };
     writeFileSync(settingsPath, JSON.stringify(settings, null, "\t"));
-    return "added";
+    return migrated ? "migrated" : "added";
+}
+/**
+ * The line the interactive setup prints for an `allowReadTools` result, so
+ * the user always learns what was done to their settings.
+ *
+ * @param result - What `allowReadTools` returned.
+ */
+export function describeAllowReadTools(result) {
+    const count = PHARAOH_ALLOW_RULES.length;
+    switch (result) {
+        case "added":
+            return `Pharaoh: allowed ${count} tools by name in ~/.claude/settings.json (permissions.allow): the read-only tools and pharaoh_account. Account deletion and pharaoh_admin still prompt.`;
+        case "migrated":
+            return `Pharaoh: replaced the blanket mcp__pharaoh rule in ~/.claude/settings.json with ${count} tools by name. Account deletion and pharaoh_admin prompt again.`;
+        case "current":
+            return `Pharaoh: ~/.claude/settings.json already allows the ${count} read-only and account tools by name.`;
+        case "no-settings":
+            return "Pharaoh: no ~/.claude/settings.json yet, so Pharaoh's tools ask before they run. The rules to allow the read-only tools are in the README (Security).";
+        case "error":
+            return "Pharaoh: ~/.claude/settings.json is not valid JSON; left as is. Pharaoh's tools ask before they run.";
+    }
 }
-// ── Main entry point ────────────────────────────────────────────────
 /**
- * Main entry point for --install-skills.
+ * Main entry point for --install-skills, also run on every proxy start.
  *
  * Detection priority: Claude Code > OpenClaw > manual instructions.
- * Installs to all detected platforms (a user may use both).
+ * Installs to all detected platforms (a user may use both). Never touches
+ * Claude Code permissions: that is `allowReadTools`, interactive setup only.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param options.silent - Print nothing (the interactive setup prints its own summary).
  * @param options.claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ * @returns What was kept, for the caller's own summary.
  */
 export function runInstallSkills(home = homedir(), options) {
     const silent = options?.silent ?? false;
     const hasClaudeCode = detectClaudeCode(home);
     const hasOpenClaw = detectOpenClaw(home);
     let installed = false;
+    const keptCommands = [];
     // ── Claude Code ──
     if (hasClaudeCode) {
+        // The marketplace lives under ~/.pharaoh, which may not exist yet: create
+        // it 0700 (and keep it 0700) before anything is written there.
+        ensurePharaohHome(join(home, ".pharaoh"));
         removeLegacyClaudePlugin(home);
         const skillCount = writeClaudeMarketplace(home);
         const registration = registerClaudePlugin(home, options?.claude ?? claudeCliFor(home));
-        const commandCount = installClaudeCodeCommands(home);
-        // Silently ensure Pharaoh tools auto-approve (no user prompt on first use)
-        configureClaudeCodePermissions(home);
+        const commands = installClaudeCodeCommands(home);
+        keptCommands.push(...commands.kept);
+        const keptLine = formatKeptCommands(commands.kept);
         if (!silent) {
             const registrationLine = {
                 installed: "  → Installed through `claude plugin` — start a new Claude Code session to load it",
@@ -554,11 +655,12 @@ export function runInstallSkills(home = homedir(), options) {
             process.stderr.write([
                 `Pharaoh: Claude Code plugin with ${skillCount} skills and the Grep routing hook`,
                 registrationLine[registration],
-                ...(commandCount > 0
+                ...(commands.installed > 0
                     ? [
-                        `  → Installed ${commandCount} slash command${commandCount === 1 ? "" : "s"} to ~/.claude/commands/`,
+                        `  → Installed ${commands.installed} slash command${commands.installed === 1 ? "" : "s"} to ~/.claude/commands/`,
                     ]
                     : []),
+                ...(keptLine ? [`  → ${keptLine}`] : []),
                 "",
             ].join("\n"));
         }
@@ -595,4 +697,5 @@ export function runInstallSkills(home = homedir(), options) {
             "",
         ].join("\n"));
     }
+    return { keptCommands };
 }

package/dist/proxy-server.d.ts

@@ -34,6 +34,10 @@ export declare class ProxyServer {
     private transport;
     private backend;
     private started;
+    private stopping;
+    private clientCapabilities;
+    private clientInitialized;
+    private capabilityUpdate;
     private transportClosed;
     private transportClosedResolve;
     constructor(initialBackend: Backend);

package/dist/proxy-server.js

@@ -27,6 +27,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { createGateway } from "./gateway.js";
+import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
 /**
  * Stdio MCP server with a swappable backend. The Server instance is
@@ -37,6 +39,10 @@ export class ProxyServer {
     transport = null;
     backend;
     started = false;
+    stopping = false;
+    clientCapabilities = {};
+    clientInitialized = false;
+    capabilityUpdate = Promise.resolve();
     transportClosed;
     transportClosedResolve;
     constructor(initialBackend) {
@@ -53,6 +59,30 @@ export class ProxyServer {
             this.transportClosedResolve = resolve;
         });
         this.registerHandlers();
+        registerTraceResource(this.server);
+        this.server.oninitialized = () => {
+            if (this.clientInitialized)
+                return;
+            this.clientInitialized = true;
+            this.clientCapabilities = this.server.getClientCapabilities() ?? {};
+            const next = this.backend.withClientCapabilities?.(this.clientCapabilities) ?? this.backend;
+            if (next === this.backend)
+                return;
+            // Warm startup happens before the frontend initializes. Replace that
+            // conservative connection only when real UI support is negotiated.
+            this.capabilityUpdate = this.setBackend(next).catch((error) => {
+                if (error instanceof TokenExpiredError || error instanceof TenantSuspendedError)
+                    throw error;
+                // UI negotiation is optional: keep the already-started plain-text
+                // backend healthy when its replacement hits a transient failure.
+                process.stderr.write("Pharaoh: compact UI negotiation unavailable; continuing with text responses.\n");
+            });
+            this.capabilityUpdate.catch(() => {
+                // Tool handlers and waitForLifetime consume this error, including
+                // typed auth failures that must reach the existing recovery loop.
+            });
+            this.backendSwappedSignal();
+        };
     }
     /**
      * Wire up list/call handlers. Each handler reads this.backend fresh at
@@ -61,10 +91,12 @@ export class ProxyServer {
      * makes mutable-backend swaps safe.
      */
     registerHandlers() {
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: await this.backend.listTools(),
-        }));
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            await this.capabilityUpdate;
+            return { tools: await this.backend.listTools() };
+        });
         this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+            await this.capabilityUpdate;
             const { name } = req.params;
             const args = req.params.arguments ?? {};
             const backend = this.backend;
@@ -131,6 +163,9 @@ export class ProxyServer {
                 this.transportClosed.then(() => "closed"),
                 backendExit.then(() => "exit"),
                 swapSignal,
+                // A successful negotiation is not the end of the connection. Its
+                // failure must still reach the supervisor if no tool is in flight.
+                this.capabilityUpdate.then(() => new Promise(() => { })),
             ]);
             if (outcome === "swap")
                 continue; // re-sample waitForExit against the new backend
@@ -151,6 +186,7 @@ export class ProxyServer {
      * to whichever backend is current at dispatch time.
      */
     async setBackend(next) {
+        next = next.withClientCapabilities?.(this.clientCapabilities) ?? next;
         const prev = this.backend;
         // Start the new backend BEFORE swapping the reference. If start() rejects
         // (e.g. SSE connect fails), `prev` stays active — otherwise the proxy
@@ -160,7 +196,12 @@ export class ProxyServer {
         // reference swap and a slow SSE handshake.
         if (next.start)
             await next.start();
+        if (this.stopping) {
+            await next.stop?.();
+            return;
+        }
         this.backend = next;
+        this.capabilityUpdate = Promise.resolve();
         // Fire the notification after the swap so a client that races a list
         // request against it sees the new catalog.
         await this.server.sendToolListChanged();
@@ -179,6 +220,7 @@ export class ProxyServer {
         }
     }
     async stop() {
+        this.stopping = true;
         if (this.backend.stop) {
             await this.backend.stop().catch((err) => {
                 const msg = err instanceof Error ? err.message : String(err);

package/dist/setup.d.ts

@@ -1,3 +1,5 @@
+/** Runs one `claude` CLI command; true on success. */
+export type ClaudeCli = (args: string[]) => boolean;
 /**
  * A `claude` CLI runner for the Claude Code config under `home`: true when the
  * command succeeded, false when it failed or `claude` isn't installed. Another
@@ -5,7 +7,7 @@
  *
  * @param home - Home whose `.claude` config the commands act on.
  */
-export declare function claudeCliFor(home?: string): (args: string[]) => boolean;
+export declare function claudeCliFor(home?: string): ClaudeCli;
 /**
  * Remove all traces of pharaoh from Claude Code's internal config (~/.claude.json).
  *
@@ -18,11 +20,18 @@ export declare function claudeCliFor(home?: string): (args: string[]) => boolean
  */
 export declare function cleanSlate(home?: string): void;
 /**
- * Full automated setup: clean slate removal, register MCP server globally,
- * install skills. Requires valid credentials (caller handles auth first).
+ * Full automated setup: clean slate removal, then register the MCP server
+ * globally as `npx @pharaoh-so/mcp@<this version>`, so a new release on npm
+ * runs only after the user upgrades on purpose (security review SC-2).
+ * Requires valid credentials (caller handles auth first).
  *
- * @returns true if setup succeeded, false if Claude CLI not found.
+ * @param options.silent - Print nothing on success.
+ * @param options.home - Home whose Claude Code config is edited (tests).
+ * @param options.claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ * @returns true if setup succeeded, false if Claude CLI not found or registration failed.
  */
 export declare function runSetup(options?: {
     silent?: boolean;
+    home?: string;
+    claude?: ClaudeCli;
 }): boolean;

package/dist/setup.js

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { NPX_COMMAND, printLines } from "./helpers.js";
+import { pinnedPackageSpec } from "./version.js";
 /** Check if `claude` CLI is available in PATH. */
 function hasClaude() {
     try {
@@ -113,41 +114,40 @@ export function cleanSlate(home = homedir()) {
     }
 }
 /**
- * Full automated setup: clean slate removal, register MCP server globally,
- * install skills. Requires valid credentials (caller handles auth first).
+ * Full automated setup: clean slate removal, then register the MCP server
+ * globally as `npx @pharaoh-so/mcp@<this version>`, so a new release on npm
+ * runs only after the user upgrades on purpose (security review SC-2).
+ * Requires valid credentials (caller handles auth first).
  *
- * @returns true if setup succeeded, false if Claude CLI not found.
+ * @param options.silent - Print nothing on success.
+ * @param options.home - Home whose Claude Code config is edited (tests).
+ * @param options.claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ * @returns true if setup succeeded, false if Claude CLI not found or registration failed.
  */
 export function runSetup(options) {
     const silent = options?.silent ?? false;
-    if (!hasClaude()) {
+    const home = options?.home ?? homedir();
+    if (!options?.claude && !hasClaude()) {
         printLines("Pharaoh: Claude Code CLI not found.", "", "Install Claude Code first: https://claude.ai/download", `Then re-run: ${NPX_COMMAND}`, "");
         return false;
     }
+    const claude = options?.claude ?? claudeCliFor(home);
     if (!silent)
         printLines("Pharaoh: setting up...");
     // Step 1: Clean slate — remove pharaoh from all scopes, disabled lists,
     // and project-scoped configs. Direct file edit handles what CLI cannot.
-    cleanSlate();
+    cleanSlate(home);
     // Step 2: Belt-and-suspenders — also remove via CLI (both scopes)
-    runClaude(["mcp", "remove", "pharaoh", "-s", "user"]);
-    runClaude(["mcp", "remove", "pharaoh", "-s", "project"]);
-    // Step 3: Register as global stdio MCP server
-    const added = runClaude([
-        "mcp",
-        "add",
-        "--scope",
-        "user",
-        "pharaoh",
-        "--",
-        "npx",
-        "@pharaoh-so/mcp",
-    ]);
+    claude(["mcp", "remove", "pharaoh", "-s", "user"]);
+    claude(["mcp", "remove", "pharaoh", "-s", "project"]);
+    // Step 3: Register as global stdio MCP server, pinned to the running version
+    const spec = pinnedPackageSpec();
+    const added = claude(["mcp", "add", "--scope", "user", "pharaoh", "--", "npx", spec]);
     if (!added) {
         printLines("Pharaoh: failed to register MCP server.", `Try manually: ${NPX_COMMAND}`, "");
         return false;
     }
     if (!silent)
-        printLines("Pharaoh: registered as global MCP server (scope: user)");
+        printLines(`Pharaoh: registered as global MCP server (scope: user) running ${spec}`);
     return true;
 }

package/dist/trace-resource.d.ts

@@ -0,0 +1,3 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+export declare const TRACE_MIME_TYPE = "text/html;profile=mcp-app";
+export declare function registerTraceResource(server: Server): void;

package/dist/trace-resource.js

@@ -0,0 +1,41 @@
+/** The bundled, tenant-neutral renderer. Resource reads never touch a backend. */
+import { readFileSync } from "node:fs";
+import { ErrorCode, ListResourcesRequestSchema, McpError, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const TRACE_RESOURCE_URI = "ui://pharaoh/trace/v1.1.html";
+export const TRACE_MIME_TYPE = "text/html;profile=mcp-app";
+const resourceMeta = {
+    ui: {
+        prefersBorder: false,
+        csp: { connectDomains: [], resourceDomains: [], frameDomains: [], baseUriDomains: [] },
+        permissions: {},
+    },
+};
+let html;
+export function registerTraceResource(server) {
+    server.registerCapabilities({ resources: {} });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [
+            {
+                name: "pharaoh-trace",
+                title: "Pharaoh Trace",
+                description: "Compact, expandable evidence from Pharaoh tool results.",
+                uri: TRACE_RESOURCE_URI,
+                mimeType: TRACE_MIME_TYPE,
+                _meta: resourceMeta,
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        if (request.params.uri !== TRACE_RESOURCE_URI) {
+            throw new McpError(ErrorCode.InvalidParams, "Unknown Trace resource");
+        }
+        // Package-root assets are shared by src/ and dist/. The request URI is
+        // never used as a filesystem path or forwarded to the authenticated server.
+        html ??= readFileSync(new URL("../trace-app.html", import.meta.url), "utf8");
+        return {
+            contents: [
+                { uri: TRACE_RESOURCE_URI, mimeType: TRACE_MIME_TYPE, text: html, _meta: resourceMeta },
+            ],
+        };
+    });
+}

package/dist/version.d.ts

@@ -1,2 +1,32 @@
+/** The npm package name, as `npx` resolves it. */
+export declare const PACKAGE_NAME = "@pharaoh-so/mcp";
+/** The deliberate upgrade: re-runs setup with the newest release, which re-pins every registration. */
+export declare const UPGRADE_COMMAND = "npx @pharaoh-so/mcp@latest";
 /** Read the mcp-proxy package version from package.json. */
 export declare function getPackageVersion(): string;
+/**
+ * The package spec a registration runs: this exact version, so a new release
+ * on npm changes nothing on the user's machine until they upgrade on purpose
+ * (security review SC-2). Falls back to the bare name only when the version
+ * is unreadable, which would otherwise pin a version that does not exist.
+ *
+ * @returns `@pharaoh-so/mcp@<version>` as `npx` accepts it.
+ */
+export declare function pinnedPackageSpec(): string;
+/**
+ * Whether `candidate` is a strictly newer release than `current`. Anything
+ * that is not a plain `major.minor.patch` compares as not newer.
+ *
+ * @param candidate - Version reported by the registry.
+ * @param current - Version this process runs.
+ */
+export declare function isNewerVersion(candidate: string, current: string): boolean;
+/**
+ * The newest version on the npm registry, or null when it cannot be learned
+ * (offline, slow, or an unexpected answer). Called only by the interactive
+ * setup, never on a proxy start, and sends nothing but the request itself.
+ *
+ * @param fetchImpl - `fetch` stand-in for tests.
+ * @param timeoutMs - How long to wait for the registry before giving up.
+ */
+export declare function fetchLatestVersion(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;