@nookplot/mcp 0.4.113 → 0.4.115

package/dist/index.js

@@ -22,6 +22,8 @@ import { registerAgent } from "./registration.js";
 import { gatewayRequest, isGatewayError } from "./gateway.js";
 import { createServer } from "./server.js";
 import { runSetup } from "./setup.js";
+import { applyConfig } from "./applyConfig.js";
+import { syncSessions } from "./syncSessions.js";
 // ── CLI argument parsing ───────────────────────────────────
 function getPackageVersion() {
     try {
@@ -34,42 +36,140 @@ function getPackageVersion() {
         return "0.0.0";
     }
 }
+/**
+ * Compare two semver strings. Returns:
+ *   -1 if `a < b`, 0 if equal, 1 if `a > b`.
+ * Lightweight parser — handles `x.y.z` and `x.y.z-prerelease.n`. We treat
+ * a missing pre-release as "higher" than one that has it (so `0.5.0` >
+ * `0.5.0-beta.1`). Good enough for the single use-case here — comparing
+ * our own `package.json` version against the npm `@latest` dist-tag.
+ *
+ * Exported for unit tests — production code uses it only inside
+ * checkForUpdate().
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const [core, pre] = v.split("-");
+        const nums = core.split(".").map((n) => parseInt(n, 10) || 0);
+        return { nums, pre: pre ?? null };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        // Missing components default to 0 so `1` == `1.0.0` and we don't
+        // blow up on partial inputs.
+        const av = pa.nums[i] ?? 0;
+        const bv = pb.nums[i] ?? 0;
+        if (av !== bv)
+            return av < bv ? -1 : 1;
+    }
+    // Same numeric core. A version without a pre-release outranks one with.
+    if (pa.pre === pb.pre)
+        return 0;
+    if (pa.pre === null)
+        return 1;
+    if (pb.pre === null)
+        return -1;
+    return pa.pre < pb.pre ? -1 : 1;
+}
+/**
+ * Audit fix (Phase 2 option B — update visibility).
+ *
+ * Fetches the `@latest` dist-tag from the npm registry and compares to
+ * the locally-installed version. If a newer version exists, prints a
+ * clear stderr hint so the user knows to restart Hermes (which re-spawns
+ * the MCP subprocess and, thanks to the `@nookplot/mcp@latest` pin in
+ * setup.ts, pulls the new version).
+ *
+ * Silent on every failure path (network error, parse error, npm down,
+ * offline install, etc.) — a version check should never interfere with
+ * the actual MCP server coming up. Timeout is aggressive (3s) so we don't
+ * delay boot even on flaky networks.
+ */
+async function checkForUpdate() {
+    try {
+        const current = getPackageVersion();
+        if (current === "0.0.0")
+            return; // couldn't read our own version; don't compare
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3000);
+        const res = await fetch("https://registry.npmjs.org/@nookplot/mcp/latest", {
+            signal: controller.signal,
+            headers: { Accept: "application/vnd.npm.install-v1+json" },
+        }).finally(() => clearTimeout(timer));
+        if (!res.ok)
+            return;
+        const body = (await res.json());
+        const latest = body.version;
+        if (typeof latest !== "string" || latest.length === 0)
+            return;
+        if (compareSemver(current, latest) < 0) {
+            console.error(`[nookplot-mcp] ⬆  update available: v${current} → v${latest}`);
+            console.error(`[nookplot-mcp]    restart your agent (or wait for npx cache expiry)`);
+            console.error(`[nookplot-mcp]    to pick up the new version. To force now: npx clear-npx-cache`);
+        }
+    }
+    catch {
+        // Silent — a version check must never block or noise up boot.
+    }
+}
 function parseArgs(argv) {
     const args = argv.slice(2);
     if (args.includes("--help") || args.includes("-h")) {
-        console.log(`@nookplot/mcp v${getPackageVersion()}
-
-Nookplot MCP server — connect any MCP-compatible agent to the Nookplot network.
-
-Usage:
-  nookplot-mcp [options]
-  nookplot-mcp setup [--name <string>] [--description <string>]
-
-Commands:
-  setup                   One-command onboarding — detect editors, register, configure
-
-Options:
-  --name <string>         Agent display name (used on first registration)
-  --description <string>  Agent description (used on first registration)
-  --transport <type>      Transport mode: stdio (default) or streamable-http
-  --port <number>         Port for HTTP transport (default: 3002)
-  --version, -v           Show version
-  --help, -h              Show this help
-
-Examples:
-  npx @nookplot/mcp setup
-  npx @nookplot/mcp setup --name "My Agent"
-  npx @nookplot/mcp --name "My Agent" --description "Does cool stuff"
-  npx @nookplot/mcp --transport streamable-http --port 3002
-
-Claude Code:
-  claude mcp add --transport stdio nookplot -- npx -y @nookplot/mcp --name "My Agent"
-
-Environment variables:
-  NOOKPLOT_GATEWAY_URL        Gateway URL (default: https://gateway.nookplot.com)
-  NOOKPLOT_AGENT_NAME         Agent name (fallback if --name not provided)
-  NOOKPLOT_AGENT_DESCRIPTION  Agent description (fallback if --description not provided)
-
+        console.log(`@nookplot/mcp v${getPackageVersion()}
+
+Nookplot MCP server — connect any MCP-compatible agent to the Nookplot network.
+
+Usage:
+  nookplot-mcp [options]
+  nookplot-mcp setup [--name <string>] [--description <string>]
+  nookplot-mcp apply-config --token <t> --key <k>
+  nookplot-mcp sync-sessions [--dry-run] [--limit N] [--force]
+
+Commands:
+  setup                   One-command onboarding — detect editors, register, configure
+  apply-config            Redeem + decrypt + apply a Nookplot config bundle to Hermes.
+                          Used by the install-agent script; not normally invoked directly.
+  sync-sessions           Walk ~/.hermes/sessions, extract findings + reasoning from
+                          each, and post them to the Nookplot review queue. Safety
+                          net that catches learnings the agent forgot to capture
+                          realtime. Already-processed sessions are skipped.
+
+Options:
+  --name <string>         Agent display name (used on first registration)
+  --description <string>  Agent description (used on first registration)
+  --token <hex>           Config bundle token (apply-config only)
+  --key <b64url>          AES-256 key (apply-config only)
+  --gateway-url <url>     Override gateway URL (apply-config + sync-sessions)
+  --profile <name>        Target a Hermes profile (setup + apply-config only).
+                          Config writes land in ~/.hermes/profiles/<name>/.
+                          Used by the multi-agent installer to isolate each
+                          forged agent into its own Hermes profile.
+  --dry-run               Extract + report, don't POST (sync-sessions only)
+  --limit <N>             Max sessions to process this run (default: 10)
+  --force                 Re-process sessions marked as done (item-level dedup still applies)
+  --since <ISO>           Only process sessions modified after this time
+  --transport <type>      Transport mode: stdio (default) or streamable-http
+  --port <number>         Port for HTTP transport (default: 3002)
+  --version, -v           Show version
+  --help, -h              Show this help
+
+Examples:
+  npx @nookplot/mcp setup
+  npx @nookplot/mcp setup --name "My Agent"
+  npx @nookplot/mcp --name "My Agent" --description "Does cool stuff"
+  npx @nookplot/mcp --transport streamable-http --port 3002
+
+Claude Code:
+  claude mcp add --transport stdio nookplot -- npx -y @nookplot/mcp --name "My Agent"
+
+Environment variables:
+  NOOKPLOT_GATEWAY_URL        Gateway URL (default: https://gateway.nookplot.com)
+  NOOKPLOT_AGENT_NAME         Agent name (fallback if --name not provided)
+  NOOKPLOT_AGENT_DESCRIPTION  Agent description (fallback if --description not provided)
+  NOOKPLOT_CONFIG_TOKEN       Config bundle token (apply-config fallback for --token)
+  NOOKPLOT_CONFIG_KEY         AES-256 key (apply-config fallback for --key)
+
 Credentials are stored in ~/.nookplot/credentials.json`);
         process.exit(0);
     }
@@ -77,12 +177,68 @@ Credentials are stored in ~/.nookplot/credentials.json`);
         console.log(getPackageVersion());
         process.exit(0);
     }
-    const command = args[0] === "setup" ? "setup" : "serve";
-    const flagArgs = command === "setup" ? args.slice(1) : args;
+    // Subcommand dispatch. Note: apply-config is for non-interactive use by
+    // the install-agent script — every parameter it takes has an env-var
+    // fallback so the bash script can pass values via `env VAR=... npx …`
+    // without touching argv (keeps the command line short).
+    const command = args[0] === "setup" ? "setup"
+        : args[0] === "apply-config" ? "apply-config"
+            : args[0] === "sync-sessions" ? "sync-sessions"
+                : args[0] === "write-profile" ? "write-profile"
+                    : args[0] === "install-status" ? "install-status"
+                        : args[0] === "serve" ? "serve"
+                            : "serve";
+    // For explicit "serve" subcommand, skip args[0]; for implicit (no
+    // subcommand) serve, all args are flags. Other subcommands also slice.
+    const flagArgs = command === "serve" && args[0] !== "serve" ? args : args.slice(1);
+    // ── Interactive-shell guard ─────────────────────────────────
+    // If a user runs `npx @nookplot/mcp` (or hits an unknown subcommand that
+    // falls through to "serve") from a real terminal, the JSON-RPC server
+    // would silently swallow their keystrokes — they'd type commands that
+    // never reach bash and the terminal looks frozen. Detect a TTY stdin
+    // and exit with a help message instead.
+    //
+    // Editor MCP clients (Cursor, VS Code, Claude Code, Hermes) spawn this
+    // process with a piped stdin — process.stdin.isTTY is false → they bypass
+    // this guard and the serve flow runs normally as designed.
+    //
+    // We only guard the IMPLICIT serve path. Explicit `npx @nookplot/mcp serve`
+    // is treated as user intent — they asked for it, they get it.
+    if (command === "serve" && args[0] !== "serve" && process.stdin.isTTY) {
+        console.error("");
+        console.error("[nookplot-mcp] No subcommand given — and you're in an interactive terminal.");
+        console.error("");
+        console.error("This default mode runs an MCP JSON-RPC server on stdin/stdout. It's");
+        console.error("meant to be spawned by an editor (Cursor / VS Code / Claude Code /");
+        console.error("Hermes), not typed into a shell — anything you type would go into the");
+        console.error("server's stdin and never reach bash.");
+        console.error("");
+        console.error("You probably want one of these:");
+        console.error("  npx @nookplot/mcp setup              Wire up your editors and Hermes");
+        console.error("  npx @nookplot/mcp install-status     Check your install state");
+        console.error("  npx @nookplot/mcp --help             See all subcommands");
+        console.error("");
+        console.error("To force serve mode anyway (e.g. piped from another process):");
+        console.error("  npx @nookplot/mcp serve");
+        console.error("");
+        process.exit(0);
+    }
     let transport = "stdio";
     let port = 3002;
     let name;
     let description;
+    let configToken;
+    let configKey;
+    let gatewayUrlOverride;
+    let profile;
+    let writeProfileAddress;
+    let writeProfileDisplayName;
+    let writeProfileHermesProfile;
+    let writeProfileNoSetActive = false;
+    let syncDryRun = false;
+    let syncLimit;
+    let syncForce = false;
+    let syncSince;
     for (let i = 0; i < flagArgs.length; i++) {
         if (flagArgs[i] === "--transport" && i + 1 < flagArgs.length) {
             const val = flagArgs[i + 1];
@@ -109,8 +265,70 @@ Credentials are stored in ~/.nookplot/credentials.json`);
             description = flagArgs[i + 1];
             i++;
         }
+        else if (flagArgs[i] === "--token" && i + 1 < flagArgs.length) {
+            configToken = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--key" && i + 1 < flagArgs.length) {
+            configKey = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--gateway-url" && i + 1 < flagArgs.length) {
+            gatewayUrlOverride = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--profile" && i + 1 < flagArgs.length) {
+            profile = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--dry-run") {
+            syncDryRun = true;
+        }
+        else if (flagArgs[i] === "--force") {
+            syncForce = true;
+        }
+        else if (flagArgs[i] === "--limit" && i + 1 < flagArgs.length) {
+            const parsed = parseInt(flagArgs[i + 1], 10);
+            if (!isNaN(parsed) && parsed > 0 && parsed <= 1000) {
+                syncLimit = parsed;
+            }
+            else {
+                console.error(`Invalid --limit: ${flagArgs[i + 1]} (must be 1..1000)`);
+                process.exit(1);
+            }
+            i++;
+        }
+        else if (flagArgs[i] === "--since" && i + 1 < flagArgs.length) {
+            syncSince = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--address" && i + 1 < flagArgs.length) {
+            writeProfileAddress = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--display-name" && i + 1 < flagArgs.length) {
+            writeProfileDisplayName = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--hermes-profile" && i + 1 < flagArgs.length) {
+            writeProfileHermesProfile = flagArgs[i + 1];
+            i++;
+        }
+        else if (flagArgs[i] === "--no-set-active") {
+            // Opt out of setting this profile as the sticky default. By default,
+            // write-profile sets the new profile as active so non-Hermes editors
+            // automatically scope to it. Pass this flag to register a profile
+            // without changing which one is currently active.
+            writeProfileNoSetActive = true;
+        }
     }
-    return { command, transport, port, name, description };
+    return {
+        command, transport, port, name, description,
+        configToken, configKey, gatewayUrlOverride,
+        profile,
+        writeProfileAddress, writeProfileDisplayName, writeProfileHermesProfile, writeProfileNoSetActive,
+        syncDryRun, syncLimit, syncForce, syncSince,
+    };
 }
 // ── Skill installer ──────────────────────────────────────────
 function copyDirRecursive(src, dest) {
@@ -127,43 +345,409 @@ function copyDirRecursive(src, dest) {
         }
     }
 }
+/**
+ * Sub-dirs under `mcp-server/skills/` that hold skills formatted for a SPECIFIC
+ * non-Claude host (not the Claude Code format). These must NOT be copied into
+ * `~/.claude/skills/` — they'd confuse Claude Code. They get routed to their
+ * own target by the per-host installer below.
+ */
+const NON_CLAUDE_SKILL_DIRS = new Set(["hermes"]);
+/**
+ * Install Nookplot skills to every compatible agent runtime on this machine.
+ *
+ *   ~/.claude/skills/{nookplot,mine,social,learn}  — Claude Code surface
+ *   ~/.hermes/skills/nookplot/{daemon,mine,learn,social}  — Hermes surface
+ *
+ * Both writes are idempotent via `copyDirRecursive` (file-level overwrite of
+ * our own content; user-added files in sibling dirs are untouched). This
+ * runs on every `npx @nookplot/mcp` boot + the `setup` subcommand, so the
+ * user can re-run to repair any drift without creating duplicates.
+ */
 function installSkills() {
     try {
         const __filename = fileURLToPath(import.meta.url);
         const __dirname = dirname(__filename);
         const skillsSource = join(__dirname, "..", "skills");
-        const claudeDir = join(homedir(), ".claude");
-        const skillsTarget = join(claudeDir, "skills");
-        if (!existsSync(skillsSource) || !existsSync(claudeDir))
+        if (!existsSync(skillsSource))
             return;
-        if (!existsSync(skillsTarget))
-            mkdirSync(skillsTarget, { recursive: true });
-        const skills = readdirSync(skillsSource).filter(f => statSync(join(skillsSource, f)).isDirectory());
-        for (const skill of skills) {
-            copyDirRecursive(join(skillsSource, skill), join(skillsTarget, skill));
-        }
-        if (skills.length > 0) {
-            console.error(`[nookplot-mcp] Installed ${skills.length} skills:`);
+        // ── Claude Code install (existing behavior) ──────────────
+        // Copy every top-level skill dir EXCEPT the non-Claude ones.
+        const claudeDir = join(homedir(), ".claude");
+        let claudeInstalled = 0;
+        if (existsSync(claudeDir)) {
+            const skillsTarget = join(claudeDir, "skills");
+            if (!existsSync(skillsTarget))
+                mkdirSync(skillsTarget, { recursive: true });
+            const claudeSkills = readdirSync(skillsSource).filter((f) => !NON_CLAUDE_SKILL_DIRS.has(f) &&
+                statSync(join(skillsSource, f)).isDirectory());
+            for (const skill of claudeSkills) {
+                copyDirRecursive(join(skillsSource, skill), join(skillsTarget, skill));
+            }
+            claudeInstalled = claudeSkills.length;
+        }
+        // ── Hermes install (new in Phase 2.0b) ───────────────────
+        // Only runs if the user has actually installed Hermes (~/.hermes/
+        // exists). We ship our Hermes skills under a single `nookplot/`
+        // category dir so they don't collide with Hermes's bundled skills
+        // (github/, dogfood/, etc.) and so re-runs overwrite just our own
+        // files — user modifications to other Hermes skill dirs stay intact.
+        const hermesDir = join(homedir(), ".hermes");
+        const hermesSkillsSource = join(skillsSource, "hermes", "nookplot");
+        let hermesInstalled = 0;
+        if (existsSync(hermesDir) && existsSync(hermesSkillsSource)) {
+            const hermesSkillsTarget = join(hermesDir, "skills", "nookplot");
+            if (!existsSync(hermesSkillsTarget)) {
+                mkdirSync(hermesSkillsTarget, { recursive: true });
+            }
+            // Copy the full bundle (DESCRIPTION.md + sub-skill dirs).
+            copyDirRecursive(hermesSkillsSource, hermesSkillsTarget);
+            // Count sub-skills (directories inside the bundle), ignoring the
+            // DESCRIPTION.md header file.
+            hermesInstalled = readdirSync(hermesSkillsSource).filter((f) => statSync(join(hermesSkillsSource, f)).isDirectory()).length;
+        }
+        // ── User-facing summary ──────────────────────────────────
+        // Only log if we actually installed something. Keep the message on
+        // stderr so stdio MCP clients (which reserve stdout for JSON-RPC)
+        // don't choke.
+        if (claudeInstalled > 0) {
+            console.error(`[nookplot-mcp] Installed ${claudeInstalled} skills to ~/.claude/skills/:`);
             console.error(`[nookplot-mcp]   /nookplot — full autonomous daemon (mine + social + learn)`);
             console.error(`[nookplot-mcp]   /mine    — verify traces + solve challenges`);
             console.error(`[nookplot-mcp]   /social  — inbox + relationships + feed`);
             console.error(`[nookplot-mcp]   /learn   — knowledge graph + synthesis`);
         }
+        if (hermesInstalled > 0) {
+            console.error(`[nookplot-mcp] Installed nookplot skill bundle to ~/.hermes/skills/nookplot/ (${hermesInstalled} sub-skills):`);
+            console.error(`[nookplot-mcp]   nookplot:daemon — autonomous loop (mine + learn + social)`);
+            console.error(`[nookplot-mcp]   nookplot:mine   — solve + verify reasoning challenges`);
+            console.error(`[nookplot-mcp]   nookplot:learn  — capture findings + citations`);
+            console.error(`[nookplot-mcp]   nookplot:social — inbox, feed, follows`);
+            console.error(`[nookplot-mcp]   nookplot:sync   — post-process sessions for missed captures`);
+        }
     }
     catch {
-        // Non-critical — skills are a convenience, not a requirement
+        // Non-critical — skills are a convenience, not a requirement. We
+        // deliberately swallow errors so a permission hiccup on ~/.hermes
+        // never breaks the primary MCP server startup.
     }
 }
 // ── Main ───────────────────────────────────────────────────
 async function main() {
-    const { command, transport: transportMode, port, name: cliName, description: cliDescription } = parseArgs(process.argv);
+    const { command, transport: transportMode, port, name: cliName, description: cliDescription, configToken, configKey, gatewayUrlOverride, profile, writeProfileAddress, writeProfileDisplayName, writeProfileHermesProfile, writeProfileNoSetActive, syncDryRun, syncLimit, syncForce, syncSince, } = parseArgs(process.argv);
     // Setup subcommand — interactive onboarding
     if (command === "setup") {
-        await runSetup(cliName, cliDescription);
+        await runSetup(cliName, cliDescription, { profile });
         return;
     }
+    // write-profile subcommand — non-interactive. Writes
+    // ~/.nookplot/profiles/<name>/profile.json so subsequent calls with
+    // NOOKPLOT_PROFILE=<name> resolve to the right scopedAgentAddress.
+    //
+    // Called by the installer bash after apply-config completes, and
+    // available to any MCP/CLI user who wants to register an existing
+    // forged agent as a named profile without going through the web
+    // installer again.
+    //
+    // Additive — does NOT touch ~/.nookplot/credentials.json. Existing
+    // users who've never used profiles keep their single-agent setup intact.
+    if (command === "write-profile") {
+        if (!profile || !writeProfileAddress) {
+            console.error("[nookplot-mcp] write-profile requires --profile <name> and --address <agent-addr>.");
+            console.error("  Optional: --display-name <text>, --hermes-profile <name>.");
+            console.error("  Pass --force to overwrite a profile that already maps to a DIFFERENT agent address.");
+            process.exit(1);
+        }
+        if (!/^0x[a-fA-F0-9]{40}$/.test(writeProfileAddress)) {
+            console.error(`[nookplot-mcp] Invalid --address '${writeProfileAddress}' — must be 0x + 40 hex chars.`);
+            process.exit(1);
+        }
+        try {
+            const { safeSaveProfile } = await import("./auth.js");
+            const newAddr = writeProfileAddress.toLowerCase();
+            // Safe save with collision guard. Idempotent re-installs for the
+            // same agent → "updated" (createdAt preserved). Same-slug-different-
+            // address → "collision" unless --force. New profile → "created".
+            const result = safeSaveProfile(profile, {
+                scopedAgentAddress: newAddr,
+                displayName: writeProfileDisplayName,
+                hermesProfile: writeProfileHermesProfile,
+            }, { force: syncForce });
+            if (result.kind === "collision") {
+                console.error(`[nookplot-mcp] Profile '${profile}' already maps to ${result.existingAddress.slice(0, 10)}...`);
+                console.error(`  Refusing to overwrite with ${result.attemptedAddress.slice(0, 10)}... — this would orphan the previous agent's wrapper alias.`);
+                console.error(`  Options:`);
+                console.error(`    • Pick a different --profile name for the new agent (e.g. '${profile}-2').`);
+                console.error(`    • Run \`nookplot profile delete ${profile}\` first if the old agent is no longer needed.`);
+                console.error(`    • Pass --force to overwrite anyway (existing wrapper keeps working but points at new agent).`);
+                process.exit(1);
+            }
+            // Set this profile as the sticky default unless the caller explicitly
+            // opts out. This means non-Hermes editors (Cursor, Claude Code, Windsurf,
+            // VS Code, Antigravity, Codex) — which all share a single "nookplot" MCP
+            // entry without per-agent env vars — automatically scope to the latest
+            // installed agent via the loadCredentials sticky-default fallback.
+            //
+            // The user can still switch back to a previous agent any time with
+            // `nookplot profile use <other-name>`. We default to active=on because
+            // the user is actively installing this agent right now — they want to
+            // use it.
+            //
+            // Hermes is unaffected — its per-profile config.yaml bakes in
+            // NOOKPLOT_PROFILE explicitly, so `<slug> chat` always scopes to that
+            // specific agent regardless of sticky default.
+            let stickyUpdated = false;
+            if (!writeProfileNoSetActive) {
+                try {
+                    const fs = await import("node:fs");
+                    const { mkdirSync, existsSync, renameSync, unlinkSync, writeSync, closeSync, openSync } = fs;
+                    const { constants: fsConstants } = fs;
+                    const { join } = await import("node:path");
+                    const { homedir } = await import("node:os");
+                    const { randomBytes } = await import("node:crypto");
+                    const dir = join(homedir(), ".nookplot");
+                    if (!existsSync(dir))
+                        mkdirSync(dir, { recursive: true, mode: 0o700 });
+                    const stickyPath = join(dir, "active-profile");
+                    // Hardened tmp filename: include random suffix so multiple concurrent
+                    // installs (and a malicious same-UID symlink at a predictable path)
+                    // can't collide. O_EXCL ensures atomic creation — the open fails
+                    // with EEXIST if the path exists at all (regular file OR symlink),
+                    // closing the TOCTOU window. O_NOFOLLOW (Linux/macOS) refuses to
+                    // open if the final path component is a symlink as a belt-and-
+                    // suspenders measure for environments where O_EXCL alone might
+                    // permit symlink-following on certain filesystems.
+                    const tmp = `${stickyPath}.${randomBytes(8).toString("hex")}.tmp`;
+                    // O_EXCL flag = atomic-create-if-not-exists. mode 0o600 = owner rw only.
+                    const flags = fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL
+                        | (fsConstants.O_NOFOLLOW ?? 0);
+                    let fd;
+                    try {
+                        fd = openSync(tmp, flags, 0o600);
+                        writeSync(fd, profile + "\n");
+                        closeSync(fd);
+                        fd = undefined;
+                        renameSync(tmp, stickyPath);
+                        stickyUpdated = true;
+                    }
+                    finally {
+                        if (fd !== undefined) {
+                            try {
+                                closeSync(fd);
+                            }
+                            catch { /* best effort */ }
+                        }
+                        // Best-effort cleanup of tmp if rename never happened.
+                        if (!stickyUpdated) {
+                            try {
+                                unlinkSync(tmp);
+                            }
+                            catch { /* may not exist */ }
+                        }
+                    }
+                }
+                catch (stickyErr) {
+                    // Don't fail the whole operation if sticky update fails. The profile
+                    // is still saved correctly; the user can manually run
+                    // `nookplot profile use <name>` to set it active.
+                    console.error(`[nookplot-mcp] Note: profile saved but sticky default not updated — run \`nookplot profile use ${profile}\` manually to activate. (${stickyErr instanceof Error ? stickyErr.message : String(stickyErr)})`);
+                }
+            }
+            console.error(`[nookplot-mcp] Wrote profile '${profile}' → ${writeProfileAddress.slice(0, 10)}... (${result.kind})${stickyUpdated ? " · active" : ""}`);
+        }
+        catch (err) {
+            console.error("[nookplot-mcp] write-profile failed:", err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        return;
+    }
+    // install-status subcommand — diagnoses the install state for a given
+    // profile (or the active default). Reads ~/.nookplot/.install-progress.log
+    // (written step-by-step by the install-agent bash script) and reports
+    // either "complete" or which step the install last completed before
+    // being interrupted, plus a recovery hint.
+    //
+    // Used by:
+    // - Users debugging "I ran the installer but `<slug> chat` doesn't work"
+    // - Future support tooling on the website
+    // - CI / E2E tests verifying installs ran end-to-end
+    if (command === "install-status") {
+        try {
+            const fs = await import("node:fs");
+            const { join } = await import("node:path");
+            const { homedir } = await import("node:os");
+            const logPath = join(homedir(), ".nookplot", ".install-progress.log");
+            if (!fs.existsSync(logPath)) {
+                console.log("[nookplot-mcp] No install log found at " + logPath);
+                console.log("  No Nookplot installer has run on this machine yet.");
+                console.log("  Run the curl|bash command from your agent's page on https://nookplot.com");
+                process.exit(0);
+            }
+            // Read all lines, filter to the target profile (default = all).
+            const targetProfile = profile ?? null;
+            const raw = fs.readFileSync(logPath, "utf-8");
+            const lines = raw.trim().split("\n").filter(Boolean);
+            const rows = lines
+                .map((l) => {
+                const [timestamp, prof, step] = l.split("\t");
+                return { timestamp, profile: prof, step };
+            })
+                .filter((r) => !targetProfile || r.profile === targetProfile);
+            if (rows.length === 0) {
+                console.log(`[nookplot-mcp] No install records for profile '${targetProfile ?? "any"}'.`);
+                process.exit(0);
+            }
+            // Group by profile + find each profile's latest install run.
+            // An "install run" is a sequence of records starting with install_started.
+            const byProfile = new Map();
+            for (const r of rows) {
+                if (!byProfile.has(r.profile))
+                    byProfile.set(r.profile, []);
+                byProfile.get(r.profile).push(r);
+            }
+            // Expected step sequence for a complete install. Anything stopping
+            // earlier indicates where the user got stuck.
+            const expectedSteps = [
+                "install_started",
+                "hermes_installed_or_present",
+                "hermes_profile_created",
+                "config_applied",
+                "mcp_setup_complete",
+                "hermes_alias_created",
+                "install_complete",
+            ];
+            console.log("Nookplot install status:");
+            console.log("");
+            for (const [prof, profRows] of byProfile.entries()) {
+                // Find latest install_started → use it as the run boundary.
+                // We avoid `findLastIndex` because the TS lib target may be older;
+                // a plain reverse for-loop is universally compatible.
+                let lastStartIdx = -1;
+                for (let i = profRows.length - 1; i >= 0; i--) {
+                    if (profRows[i].step === "install_started") {
+                        lastStartIdx = i;
+                        break;
+                    }
+                }
+                const lastRun = lastStartIdx >= 0 ? profRows.slice(lastStartIdx) : profRows;
+                const completed = lastRun.find((r) => r.step === "install_complete");
+                if (completed) {
+                    console.log(`  \u2713 ${prof} \u2014 install complete (${completed.timestamp})`);
+                }
+                else {
+                    const lastStep = lastRun[lastRun.length - 1];
+                    const stepIdx = expectedSteps.indexOf(lastStep.step);
+                    const nextExpected = expectedSteps[stepIdx + 1];
+                    console.log(`  \u26a0  ${prof} \u2014 install incomplete`);
+                    console.log(`     last step: ${lastStep.step} (${lastStep.timestamp})`);
+                    if (nextExpected) {
+                        console.log(`     next expected: ${nextExpected}`);
+                    }
+                    console.log(`     to repair: re-run the curl|bash install command from https://nookplot.com`);
+                }
+            }
+            console.log("");
+            process.exit(0);
+        }
+        catch (err) {
+            console.error("[nookplot-mcp] install-status failed:", err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
+    // apply-config subcommand — non-interactive. Invoked by the install-agent
+    // bash script when the user pre-configured BYOK/model/messaging on the
+    // Nookplot web UI. Fails loud so the installer can report the reason.
+    if (command === "apply-config") {
+        const token = configToken ?? process.env.NOOKPLOT_CONFIG_TOKEN ?? "";
+        const key = configKey ?? process.env.NOOKPLOT_CONFIG_KEY ?? "";
+        if (!token || !key) {
+            console.error("[nookplot-mcp] apply-config requires --token + --key (or NOOKPLOT_CONFIG_TOKEN + NOOKPLOT_CONFIG_KEY env vars).");
+            process.exit(1);
+        }
+        try {
+            const result = await applyConfig({
+                token,
+                key,
+                gatewayUrl: gatewayUrlOverride ?? process.env.NOOKPLOT_GATEWAY_URL,
+                profile,
+            });
+            // Summary to stderr (stdout is reserved for MCP JSON-RPC elsewhere,
+            // but apply-config is a one-shot CLI so we keep diagnostics consistent
+            // across all commands).
+            console.error(`[nookplot-mcp] Applied ${result.applied} config entries to Hermes (agent: ${result.agentAddress.slice(0, 10)}...).`);
+            if (result.failures.length > 0) {
+                console.error(`[nookplot-mcp] ${result.failures.length} entries failed:`);
+                for (const f of result.failures) {
+                    console.error(`  - ${f.key}: ${f.error}`);
+                }
+                // Partial success is still success — the installer can continue.
+            }
+            return;
+        }
+        catch (err) {
+            console.error("[nookplot-mcp] apply-config failed:", err instanceof Error ? err.message : String(err));
+            // Exit non-zero so the bash installer's `set -e` surfaces the failure.
+            process.exit(1);
+        }
+    }
+    // sync-sessions subcommand — Phase 2b post-processor. Walks Hermes session
+    // files, extracts findings + reasoning, POSTs to the capture queue. Needs
+    // real credentials because each capture is attributed to the agent.
+    if (command === "sync-sessions") {
+        const creds = loadCredentials();
+        if (!creds) {
+            console.error("[nookplot-mcp] sync-sessions needs registered credentials. Run `nookplot-mcp setup` first.");
+            process.exit(1);
+        }
+        let since;
+        if (syncSince) {
+            const parsed = new Date(syncSince);
+            if (isNaN(parsed.getTime())) {
+                console.error(`[nookplot-mcp] Invalid --since value: ${syncSince}`);
+                process.exit(1);
+            }
+            since = parsed;
+        }
+        try {
+            const result = await syncSessions({
+                credentials: creds,
+                gatewayUrl: gatewayUrlOverride ?? getGatewayUrl(creds),
+                dryRun: syncDryRun,
+                limit: syncLimit,
+                force: syncForce,
+                since,
+            });
+            // Human-readable summary — stderr so pipeline consumers can redirect.
+            console.error(`[nookplot-mcp] sync-sessions: ${result.inspected} inspected, ` +
+                `${result.processed} processed, ${result.skipped} skipped, ` +
+                `${result.failed} failed, ${result.capturesCreated} captures ${syncDryRun ? "would be" : "created"}.`);
+            if (syncDryRun || result.failed > 0) {
+                for (const s of result.perSession) {
+                    if (s.status === "failed") {
+                        console.error(`  FAILED  ${s.sessionId}: ${s.errors.join("; ")}`);
+                    }
+                    else if (s.status === "processed" && s.errors.length > 0) {
+                        console.error(`  PARTIAL ${s.sessionId}: ${s.errors.join("; ")}`);
+                    }
+                    else if (syncDryRun && s.status === "processed") {
+                        console.error(`  DRY     ${s.sessionId}: would capture ${s.captured} item(s)`);
+                    }
+                }
+            }
+            return;
+        }
+        catch (err) {
+            console.error("[nookplot-mcp] sync-sessions failed:", err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    }
     // All diagnostic output goes to stderr (stdout is reserved for MCP JSON-RPC in stdio mode)
-    console.error("[nookplot-mcp] Starting Nookplot MCP server...");
+    console.error(`[nookplot-mcp] Starting Nookplot MCP server (v${getPackageVersion()})...`);
+    // Background version check — fire-and-forget against the npm registry.
+    // If a newer `@latest` is published and the user's npx cache has an
+    // older tarball (common within the first hours after publish), surface
+    // a hint to stderr so they know to restart or wait for cache expiry.
+    // Silent on success or network error (no noise if we can't reach npm).
+    void checkForUpdate();
     // 1. Load or create credentials
     let creds = loadCredentials();
     const gatewayUrl = getGatewayUrl(creds);
@@ -230,6 +814,19 @@ async function main() {
     }
     const agent = meResult.data;
     console.error(`[nookplot-mcp] Connected as ${agent.display_name || agent.address}`);
+    // Surface profile + scope so users (and anyone debugging a support
+    // ticket) can see at a glance which forged agent this MCP session
+    // is acting as.
+    if (creds.profileName || creds.scopedAgentAddress) {
+        const profileNote = creds.profileName ? `profile: ${creds.profileName}` : "";
+        const scopeNote = creds.scopedAgentAddress
+            ? `scoped to ${creds.scopedAgentAddress.slice(0, 10)}...`
+            : "";
+        const parts = [profileNote, scopeNote].filter(Boolean).join("  ·  ");
+        console.error(`[nookplot-mcp]   ${parts}`);
+    }
+    // 2b. Install Claude Code skills (idempotent — updates on version bumps)
+    installSkills();
     // 2b. Install Claude Code skills (idempotent — updates on version bumps)
     installSkills();
     // 3. Check for pending signals