prism-mcp-server 20.11.1 → 20.12.1

package/README.md

@@ -116,6 +116,54 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.12.1
+
+- **`prism connect --refresh` now converges every registration it owns**, not
+  just the top-level one — directory-scoped entries could otherwise keep
+  launching an old build indefinitely.
+- **`prism update` checks the installed package**, not the CLI that happens to
+  be running, so it can no longer report "current" while the install is stale.
+- **The opt-in scheduled updater can actually start** — the LaunchAgent now
+  carries a PATH that includes node and npm.
+
+## What's New in v20.12.0
+
+- **Prism now tells you when it's out of date.** Session startup shows a
+  one-line update notice when a newer release exists — cache-backed, at most
+  one registry check per day, silent offline. `PRISM_NO_UPDATE_CHECK=1`
+  opts out.
+- **Hands-free updates, if you want them.** `prism autoupdate enable` sets up
+  a daily `prism update --if-idle`: it updates only the global npm package,
+  defers while any Prism server is running, and never touches host
+  configuration — that stays behind a visible `prism connect`.
+
+## What's New in v20.11.1
+
+- **Saving memory never gets refused.** The save path used to reject
+  `session_save_ledger`/`save_handoff` calls when its path-to-project
+  heuristic disagreed with the project you declared — and the registry the
+  heuristic trusted could contain junk from earlier auto-registration, so
+  legitimate sessions ended unsaved. Your declaration now always wins; the
+  disagreement is returned as an advisory warning, and auto-registration
+  only accepts real repository roots.
+- **Screenshots are evidence again.** `prism browser` captures on macOS were
+  silently *upscaled* to the size cap, so a screenshot no longer showed what
+  actually rendered. Only genuinely oversized captures are resized now, and
+  the cap no longer clips a standard 1920-wide viewport.
+
+## What's New in v20.10.0 – v20.11.0
+
+- **Skill routing now works mid-session.** New prompts are matched on-device
+  as the conversation moves — not just on turn one — and injected within each
+  host's real context limits (Claude Code caps hook output at 10k chars;
+  Codex truncates by default), with pointer-first delivery when a payload
+  can't fit inline.
+- **`prism connect` is a converge command.** It self-updates first, re-execs,
+  then reconciles MCP registration, skills, and hooks — no more
+  "fresh config, stale code" machines.
+- **Scoped skills route on prompts too**, and startup output survives hosts
+  that discard structured tool content.
+
 ## What's New in v20.9.0 – v20.9.3
 
 - **Your skills follow your account.** `skill_save` stores a skill at the

package/dist/autoUpdate.js

@@ -0,0 +1,325 @@
+/**
+ * `prism update` / `prism autoupdate` — unattended-safe package updates.
+ *
+ * Why this is NOT `prism connect` on a timer (design review 2026-08-14):
+ * connect writes host configuration and expects hosts to be closed — a
+ * condition no scheduler can guarantee. This module's whole authority is
+ * `npm install -g prism-mcp-server@<latest>`:
+ *   - host configuration, hooks, and hook trust are untouchable from here —
+ *     there is no code path to them;
+ *   - running server processes keep the code they booted with; the next
+ *     process start picks up the new release (global registrations resolve
+ *     through the bin symlink);
+ *   - `--if-idle` defers entirely while any Prism MCP server process is
+ *     alive, and an UNVERIFIABLE process list counts as busy — fail safe;
+ *   - a single-instance lock prevents overlapping npm runs (a scheduler
+ *     firing while an operator updates by hand).
+ *
+ * Configuration migrations stay behind a visible `prism connect` run.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, openSync, closeSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isNewer } from "./selfUpdate.js";
+const PACKAGE = "prism-mcp-server";
+const SEMVER = /^\d+\.\d+\.\d+$/;
+export const AUTOUPDATE_LABEL = "com.synalux.prism.autoupdate";
+function defaultFetchLatest() {
+    return execFileSync("npm", ["view", PACKAGE, "version"], {
+        encoding: "utf8",
+        timeout: 15_000,
+    }).trim();
+}
+/** Read the version of the globally installed package. npm puts it under
+ *  <prefix>/lib/node_modules on POSIX and <prefix>/node_modules on Windows. */
+function defaultInstalledVersion() {
+    const prefix = execFileSync("npm", ["prefix", "-g"], { encoding: "utf8", timeout: 15_000 }).trim();
+    for (const candidate of [
+        join(prefix, "lib", "node_modules", PACKAGE, "package.json"),
+        join(prefix, "node_modules", PACKAGE, "package.json"),
+    ]) {
+        if (existsSync(candidate)) {
+            const version = JSON.parse(readFileSync(candidate, "utf8"))?.version;
+            if (typeof version === "string" && version.trim())
+                return version.trim();
+        }
+    }
+    return "";
+}
+function defaultInstall(version) {
+    execFileSync("npm", ["install", "-g", `${PACKAGE}@${version}`], {
+        stdio: "inherit",
+        timeout: 300_000,
+    });
+}
+/** Lines for live Prism MCP server processes. Throws when `ps` is unusable —
+ *  the caller treats that as busy, never as idle. */
+export function defaultListPrismProcesses() {
+    const out = execFileSync("ps", ["-axo", "pid=,command="], {
+        encoding: "utf8",
+        timeout: 10_000,
+    });
+    return out
+        .split("\n")
+        .filter((line) => /server\.js/.test(line) && /prism/i.test(line))
+        .map((line) => line.trim());
+}
+const LOCK_DIR = () => join(homedir(), ".prism-mcp");
+const LOCK_FILE = () => join(LOCK_DIR(), "update.lock");
+/** O_EXCL lockfile with stale-holder recovery (dead pid → reclaim once). */
+export function defaultAcquireLock() {
+    mkdirSync(LOCK_DIR(), { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(LOCK_FILE(), "wx");
+            writeFileSync(fd, String(process.pid));
+            closeSync(fd);
+            return () => { try {
+                rmSync(LOCK_FILE(), { force: true });
+            }
+            catch { /* released is released */ } };
+        }
+        catch {
+            try {
+                const holder = parseInt(readFileSync(LOCK_FILE(), "utf8").trim(), 10);
+                if (Number.isInteger(holder)) {
+                    try {
+                        process.kill(holder, 0); // alive → genuinely locked
+                        return null;
+                    }
+                    catch {
+                        rmSync(LOCK_FILE(), { force: true }); // stale → reclaim and retry
+                        continue;
+                    }
+                }
+                rmSync(LOCK_FILE(), { force: true }); // unreadable holder → reclaim
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+export function runPackageUpdate(deps) {
+    const env = deps.env ?? process.env;
+    const log = deps.log ?? (() => { });
+    if (env.PRISM_NO_SELF_UPDATE === "1") {
+        return { action: "skipped", detail: "PRISM_NO_SELF_UPDATE=1" };
+    }
+    if ((env.VITEST || env.NODE_ENV === "test") && !deps.fetchLatest) {
+        return { action: "skipped", detail: "test environment" };
+    }
+    if (deps.ifIdle) {
+        let running;
+        try {
+            running = (deps.listPrismProcesses ?? defaultListPrismProcesses)();
+        }
+        catch (error) {
+            return {
+                action: "deferred",
+                detail: `cannot verify idleness (${error instanceof Error ? error.message.split("\n")[0] : String(error)}) — deferring`,
+            };
+        }
+        if (running.length > 0) {
+            return {
+                action: "deferred",
+                detail: `${running.length} Prism MCP process(es) running — deferred until idle`,
+            };
+        }
+    }
+    // The version that matters is the INSTALLED one; the running CLI may be a
+    // checkout, a shim, or an older global. Probing shells out to npm, so tests
+    // reach it only through an injected dep.
+    let targetVersion = deps.currentVersion;
+    // Test detection must read the REAL process env: suites pass env: {} to
+    // exercise the policy guards, and that would otherwise let this probe shell
+    // out to npm from inside the test run (caught by a 57ms test that suddenly
+    // consulted the machine's actual install).
+    const inTest = Boolean(env.VITEST || env.NODE_ENV === "test" ||
+        process.env.VITEST || process.env.NODE_ENV === "test");
+    const mayProbe = Boolean(deps.installedVersion) || !inTest;
+    if (mayProbe) {
+        try {
+            const installed = (deps.installedVersion ?? defaultInstalledVersion)().trim();
+            if (installed)
+                targetVersion = installed;
+        }
+        catch { /* not installed / npm unavailable — compare the running version */ }
+    }
+    if (targetVersion.includes("-")) {
+        return { action: "skipped", detail: `dev build ${targetVersion} — not touching it` };
+    }
+    const release = (deps.acquireLock ?? defaultAcquireLock)();
+    if (!release) {
+        return { action: "locked", detail: "another prism update is already running" };
+    }
+    try {
+        let latest;
+        try {
+            latest = (deps.fetchLatest ?? defaultFetchLatest)();
+        }
+        catch (error) {
+            return { action: "failed", detail: `registry unreachable (${error instanceof Error ? error.message.split("\n")[0] : String(error)})` };
+        }
+        if (!SEMVER.test(latest)) {
+            return { action: "failed", detail: `registry returned unexpected version "${latest}"` };
+        }
+        if (!isNewer(targetVersion, latest)) {
+            return { action: "current", detail: `installed package ${targetVersion} is current`, latest };
+        }
+        log(`prism ${targetVersion} → ${latest}: updating the global package …`);
+        try {
+            (deps.install ?? defaultInstall)(latest);
+        }
+        catch (error) {
+            return { action: "failed", detail: `npm install -g failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)})`, latest };
+        }
+        return { action: "updated", detail: `global package now ${latest}; running servers pick it up on their next start`, latest };
+    }
+    finally {
+        release();
+    }
+}
+// ─── LaunchAgent (macOS) scheduling ──────────────────────────────
+export function autoupdatePlistPath() {
+    return join(homedir(), "Library", "LaunchAgents", `${AUTOUPDATE_LABEL}.plist`);
+}
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/** The PATH a scheduled run needs. launchd hands an agent a minimal
+ *  PATH (/usr/bin:/bin:/usr/sbin:/sbin) that excludes /usr/local/bin and
+ *  /opt/homebrew/bin — where node and npm live on a standard macOS install.
+ *  Measured 2026-08-14: without this the agent died at `env: node: No such
+ *  file or directory` before running a single line of Prism. The directory
+ *  of the interpreter running this code leads, because that is provably the
+ *  node the operator uses. */
+export function schedulerPath(execPath = process.execPath) {
+    const lastSlash = execPath.lastIndexOf("/");
+    const nodeDir = lastSlash > 0 ? execPath.slice(0, lastSlash) : "/usr/local/bin";
+    const defaults = ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/usr/sbin", "/sbin"];
+    return [nodeDir, ...defaults.filter((dir) => dir !== nodeDir)].join(":");
+}
+/** Daily 03:30 local, catch-up on wake (LaunchAgents coalesce missed runs). */
+export function buildAutoupdatePlist(prismBin, pathEnv = schedulerPath()) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${AUTOUPDATE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xmlEscape(prismBin)}</string>
+    <string>update</string>
+    <string>--if-idle</string>
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key><string>${xmlEscape(pathEnv)}</string>
+  </dict>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Hour</key><integer>3</integer>
+    <key>Minute</key><integer>30</integer>
+  </dict>
+  <key>StandardOutPath</key><string>/tmp/${AUTOUPDATE_LABEL}.log</string>
+  <key>StandardErrorPath</key><string>/tmp/${AUTOUPDATE_LABEL}.log</string>
+</dict>
+</plist>
+`;
+}
+export function autoupdateStatus() {
+    const plistPath = autoupdatePlistPath();
+    if (process.platform !== "darwin") {
+        return { supported: false, enabled: false, plistPath, detail: "scheduled updates are macOS-only for now (LaunchAgent)" };
+    }
+    const enabled = existsSync(plistPath);
+    if (!enabled) {
+        return { supported: true, enabled, plistPath, detail: "disabled" };
+    }
+    // 20.12.0 wrote a plist with no PATH. launchd hands an agent
+    // /usr/bin:/bin:/usr/sbin:/sbin, which excludes the directories holding node
+    // and npm on a standard macOS install, so that generation could never run —
+    // and it failed into a log file nobody reads. Say so instead of reporting a
+    // confident "enabled".
+    let healthy = false;
+    try {
+        healthy = readFileSync(plistPath, "utf8").includes("<key>PATH</key>");
+    }
+    catch { /* unreadable — treat as needing repair */ }
+    return {
+        supported: true,
+        enabled,
+        plistPath,
+        detail: healthy
+            ? `enabled — daily 03:30, log: /tmp/${AUTOUPDATE_LABEL}.log`
+            // Deliberately "may not run", not "cannot": launchd's default PATH does
+            // contain /usr/bin, so an operator whose node lives there is fine. On a
+            // standard install (Homebrew, /usr/local) it never runs. Claiming a
+            // certain failure we have not measured on THIS machine would be the same
+            // overclaim in the other direction.
+            : "enabled, but this agent predates the PATH fix and may not run (launchd's default PATH omits /usr/local/bin and /opt/homebrew/bin) — re-run `prism autoupdate enable` to repair",
+    };
+}
+export function resolvePrismBin(log, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    let globalBin;
+    try {
+        const prefix = (deps.npmPrefix ?? (() => execFileSync("npm", ["prefix", "-g"], { encoding: "utf8", timeout: 15_000 })))().trim();
+        if (prefix) {
+            const candidate = join(prefix, "bin", "prism");
+            if (exists(candidate))
+                globalBin = candidate;
+        }
+    }
+    catch { /* npm unavailable — fall back to PATH lookup */ }
+    if (globalBin)
+        return globalBin;
+    let bin = "";
+    try {
+        bin = (deps.whichPrism ?? (() => execFileSync("which", ["prism"], { encoding: "utf8", timeout: 5_000 })))().trim();
+    }
+    catch { /* not on PATH */ }
+    if (!bin)
+        throw new Error("`prism` not found — install it with: npm install -g prism-mcp-server");
+    let real = bin;
+    try {
+        real = (deps.readlink ?? ((p) => execFileSync("readlink", ["-f", p], { encoding: "utf8", timeout: 5_000 })))(bin).trim() || bin;
+    }
+    catch { /* keep bin */ }
+    if (!real.includes("node_modules") && /\/dist\/[^/]+$/.test(real)) {
+        log(`⚠ ${bin} resolves to a source checkout (${real}); the scheduled job will run that CLI — it still updates only the global package`);
+    }
+    return bin;
+}
+export function enableAutoupdate(log) {
+    if (process.platform !== "darwin")
+        return autoupdateStatus();
+    const plistPath = autoupdatePlistPath();
+    const bin = resolvePrismBin(log);
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    writeFileSync(plistPath, buildAutoupdatePlist(bin));
+    // Reload cleanly whether or not a previous generation was loaded.
+    try {
+        execFileSync("launchctl", ["unload", plistPath], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch { /* not loaded */ }
+    execFileSync("launchctl", ["load", "-w", plistPath], { timeout: 10_000 });
+    return autoupdateStatus();
+}
+export function disableAutoupdate() {
+    if (process.platform !== "darwin")
+        return autoupdateStatus();
+    const plistPath = autoupdatePlistPath();
+    try {
+        execFileSync("launchctl", ["unload", plistPath], { timeout: 10_000, stdio: "ignore" });
+    }
+    catch { /* not loaded */ }
+    rmSync(plistPath, { force: true });
+    return autoupdateStatus();
+}

package/dist/cli.js

@@ -11,7 +11,7 @@ import { getSetting } from './storage/configStorage.js';
 import { PRISM_USER_ID, SERVER_CONFIG } from './config.js';
 import { getCurrentGitState } from './utils/git.js';
 import { sessionBootstrapHandler, sessionLoadContextHandler, sessionSaveLedgerHandler, sessionSaveHandoffHandler, } from './tools/ledgerHandlers.js';
-import { configureClaudeAgentPolicy, configureClaudeNativeStartup, configureCodexAgentPolicy, configureCodexNativeStartup, configureGeminiAgentPolicy, configureGeminiNativeStartup, connectHosts, migrateLegacyClaudeHooks, migrateLegacyClaudeInstructions, migrateLegacyClaudeManagedStartup, migrateLegacyClaudeProjectMcp, normalizeHostName, } from './connect.js';
+import { configureClaudeAgentPolicy, configureClaudeNativeStartup, configureCodexAgentPolicy, configureCodexNativeStartup, configureGeminiAgentPolicy, configureGeminiNativeStartup, connectHosts, migrateLegacyClaudeHooks, migrateLegacyClaudeInstructions, migrateLegacyClaudeManagedStartup, migrateLegacyClaudeProjectMcp, connectResultLine, normalizeHostName, } from './connect.js';
 import { runBrowserCli } from './browserCli.js';
 import { filterPrismMemoryContext } from './utils/memoryQuality.js';
 import { isRecoverableStartupStorageError } from './utils/startupRecovery.js';
@@ -164,6 +164,51 @@ program
 program
     .command('browser')
     .description('Run the packaged local Prism Browser automation CLI');
+// ─── prism update / prism autoupdate ──────────────────────────
+// Unattended-safe package updates. Deliberately NOT connect-on-a-timer:
+// connect writes host configuration and expects hosts to be closed, which
+// a scheduler cannot guarantee. `update` touches only the global npm
+// package; running servers pick the release up on their next start.
+program
+    .command('update')
+    .description('Update the global prism-mcp-server package (never touches host configuration)')
+    .option('--if-idle', 'Only update while no Prism MCP server process is running (scheduler-safe)')
+    .action(async (options) => {
+    const { runPackageUpdate } = await import('./autoUpdate.js');
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+    const result = runPackageUpdate({
+        currentVersion: pkg.version,
+        ifIdle: options.ifIdle,
+        log: (l) => console.log(l),
+    });
+    console.log(`${result.action}: ${result.detail}`);
+    process.exit(result.action === 'failed' ? 1 : 0);
+});
+program
+    .command('autoupdate <action>')
+    .description('Scheduled daily `prism update --if-idle` — enable | disable | status (opt-in, macOS)')
+    .action(async (action) => {
+    const { enableAutoupdate, disableAutoupdate, autoupdateStatus } = await import('./autoUpdate.js');
+    const log = (l) => console.log(l);
+    let status;
+    if (action === 'enable')
+        status = enableAutoupdate(log);
+    else if (action === 'disable')
+        status = disableAutoupdate();
+    else if (action === 'status')
+        status = autoupdateStatus();
+    else {
+        console.error(`unknown action "${action}" — use enable, disable, or status`);
+        process.exit(1);
+    }
+    if (!status.supported) {
+        console.log(`− ${status.detail}`);
+        process.exit(action === 'status' ? 0 : 1);
+    }
+    console.log(status.enabled
+        ? `✓ autoupdate ${status.detail}\n  agent: ${status.plistPath}`
+        : `− autoupdate ${status.detail}`);
+});
 // ─── prism connect ────────────────────────────────────────────
 // Registers this installed package with supported MCP hosts. The
 // merge is additive: an existing `prism` or `prism-mcp` entry is
@@ -216,24 +261,12 @@ program
             return;
         }
         for (const result of summary.results) {
-            if (result.status === 'registered') {
-                console.log(`✓ ${result.label}: registered (${result.path})`);
-            }
-            else if (result.status === 'would-register') {
-                console.log(`• ${result.label}: would register (${result.path})`);
-            }
-            else if (result.status === 'refreshed') {
-                console.log(`✓ ${result.label}: Prism-managed entry refreshed (${result.path})`);
-            }
-            else if (result.status === 'would-refresh') {
-                console.log(`• ${result.label}: would refresh Prism-managed entry (${result.path})`);
-            }
-            else if (result.status === 'existing') {
-                console.log(`− ${result.label}: already registered — untouched (${result.path})`);
+            if (result.status === 'error') {
+                console.error(connectResultLine(result));
+                process.exitCode = 1;
             }
             else {
-                console.error(`✗ ${result.label}: ${result.message || 'registration failed'} (${result.path})`);
-                process.exitCode = 1;
+                console.log(connectResultLine(result));
             }
         }
         const connectedClaude = summary.results.some((result) => result.host === 'claude-code' && result.status !== 'error' && result.startupCompatible);

package/dist/connect.js

@@ -1220,36 +1220,63 @@ function registerJsonHost(definition, entry, dryRun, refresh, beforeCommit) {
         : Object.prototype.hasOwnProperty.call(mcpServers, "prism")
             ? "prism"
             : undefined;
+    // Claude Code keeps ADDITIONAL, directory-scoped registrations under
+    // projects["<dir>"].mcpServers, and the scoped one wins for sessions started
+    // in that directory. Refreshing only the top-level entry left those pinned to
+    // a stale server path forever — measured live 2026-08-14 on a machine
+    // carrying three registrations, where `--refresh` converged exactly one and
+    // two directories kept launching an old build indefinitely. Only entries
+    // Prism itself created are eligible, and only under --refresh, so this
+    // cannot reach a hand-rolled entry. Hosts without a `projects` map are
+    // unaffected: the collector returns nothing.
+    const pendingProjects = refresh ? collectProjectScopedRefreshes(config, entry) : [];
+    const scopedCount = pendingProjects.length;
+    const scopedNoun = `${scopedCount} project-scoped ${scopedCount === 1 ? "entry" : "entries"}`;
+    const writeConfig = (status, message, compatible) => {
+        try {
+            writeTextAtomically(writePath, `${JSON.stringify(config, null, 2)}\n`, originalText, beforeCommit, symlinkPath);
+            return result(definition, status, message, compatible);
+        }
+        catch (error) {
+            return result(definition, "error", error instanceof Error ? error.message : String(error));
+        }
+    };
     if (existingKey) {
         const existingEntry = mcpServers[existingKey];
         const startupCompatible = existingKey === "prism-mcp"
             && isManagedPrismEntry(existingEntry)
             && isDeepStrictEqual(refreshManagedEntry(existingEntry, entry), existingEntry);
         if (!refresh || existingKey !== "prism-mcp" || !isManagedPrismEntry(existingEntry)) {
-            return result(definition, "existing", "Prism is already registered; existing entry left untouched", startupCompatible);
+            if (scopedCount === 0) {
+                return result(definition, "existing", "Prism is already registered; existing entry left untouched", startupCompatible);
+            }
+            if (dryRun) {
+                return result(definition, "would-refresh", `top-level entry left untouched; would refresh ${scopedNoun}`, startupCompatible);
+            }
+            applyProjectScopedRefreshes(config, pendingProjects);
+            return writeConfig("refreshed", `top-level entry left untouched; refreshed ${scopedNoun}`, startupCompatible);
         }
         const refreshedEntry = refreshManagedEntry(existingEntry, entry);
-        if (JSON.stringify(refreshedEntry) === JSON.stringify(existingEntry)) {
+        const topLevelStale = JSON.stringify(refreshedEntry) !== JSON.stringify(existingEntry);
+        if (!topLevelStale && scopedCount === 0) {
             return result(definition, "existing", "Prism-managed entry is already current", true);
         }
         if (dryRun) {
-            return result(definition, "would-refresh", undefined, true);
+            return result(definition, "would-refresh", scopedCount > 0 ? `also ${scopedNoun}` : undefined, true);
         }
-        mcpServers[existingKey] = refreshedEntry;
-        config.mcpServers = mcpServers;
-        try {
-            writeTextAtomically(writePath, `${JSON.stringify(config, null, 2)}\n`, originalText, beforeCommit, symlinkPath);
-            return result(definition, "refreshed", undefined, true);
-        }
-        catch (error) {
-            return result(definition, "error", error instanceof Error ? error.message : String(error));
+        if (topLevelStale) {
+            mcpServers[existingKey] = refreshedEntry;
+            config.mcpServers = mcpServers;
         }
+        applyProjectScopedRefreshes(config, pendingProjects);
+        return writeConfig("refreshed", scopedCount > 0 ? `also refreshed ${scopedNoun}` : undefined, true);
     }
     if (dryRun) {
-        return result(definition, "would-register", undefined, true);
+        return result(definition, "would-register", scopedCount > 0 ? `also ${scopedNoun}` : undefined, true);
     }
     mcpServers["prism-mcp"] = entry;
     config.mcpServers = mcpServers;
+    applyProjectScopedRefreshes(config, pendingProjects);
     try {
         writeTextAtomically(writePath, `${JSON.stringify(config, null, 2)}\n`, originalText, beforeCommit, symlinkPath);
         return result(definition, "registered", undefined, true);
@@ -1563,6 +1590,22 @@ function result(definition, status, message, startupCompatible = false) {
         message,
     };
 }
+/** One operator-facing line per host result.
+ *  The `message` a host writer attaches (e.g. "also refreshed 2 project-scoped
+ *  entries") MUST survive to stdout: the earlier printer used canned per-status
+ *  text and dropped it, so a converged directory-scoped registration was
+ *  invisible to the person who asked for it. */
+export function connectResultLine(result) {
+    const detail = result.message ? ` — ${result.message}` : "";
+    switch (result.status) {
+        case "registered": return `✓ ${result.label}: registered${detail} (${result.path})`;
+        case "would-register": return `• ${result.label}: would register${detail} (${result.path})`;
+        case "refreshed": return `✓ ${result.label}: Prism-managed entry refreshed${detail} (${result.path})`;
+        case "would-refresh": return `• ${result.label}: would refresh Prism-managed entry${detail} (${result.path})`;
+        case "existing": return `− ${result.label}: already registered — untouched (${result.path})`;
+        default: return `✗ ${result.label}: ${result.message || "registration failed"} (${result.path})`;
+    }
+}
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1576,6 +1619,46 @@ function isManagedPrismEntry(value) {
         && isJsonObject(value.env)
         && value.env.PRISM_INSTANCE === "prism-mcp";
 }
+/** Prism-managed, directory-scoped registrations that are out of date.
+ *  Claude Code stores these under projects["<dir>"].mcpServers; other hosts
+ *  have no `projects` map, so this returns nothing for them. */
+function collectProjectScopedRefreshes(config, desired) {
+    const projects = config.projects;
+    if (!isJsonObject(projects))
+        return [];
+    const pending = [];
+    for (const [project, projectConfig] of Object.entries(projects)) {
+        if (!isJsonObject(projectConfig))
+            continue;
+        const servers = projectConfig.mcpServers;
+        if (!isJsonObject(servers))
+            continue;
+        const existing = servers["prism-mcp"];
+        if (!isManagedPrismEntry(existing))
+            continue; // hand-rolled entries stay untouched
+        const refreshed = refreshManagedEntry(existing, desired);
+        if (JSON.stringify(refreshed) !== JSON.stringify(existing)) {
+            pending.push({ project, entry: refreshed });
+        }
+    }
+    return pending;
+}
+function applyProjectScopedRefreshes(config, pending) {
+    if (pending.length === 0)
+        return;
+    const projects = config.projects;
+    if (!isJsonObject(projects))
+        return;
+    for (const { project, entry } of pending) {
+        const projectConfig = projects[project];
+        if (!isJsonObject(projectConfig))
+            continue;
+        const servers = projectConfig.mcpServers;
+        if (!isJsonObject(servers))
+            continue;
+        servers["prism-mcp"] = entry;
+    }
+}
 function refreshManagedEntry(existing, desired) {
     const existingEnv = isJsonObject(existing.env) ? existing.env : {};
     const desiredEnv = isJsonObject(desired.env) ? desired.env : {};

package/dist/server.js

@@ -1293,6 +1293,21 @@ export async function startServer() {
     runSkillManifestSync();
     const skillManifestRefresh = setInterval(runSkillManifestSync, 5 * 60 * 1000);
     skillManifestRefresh.unref();
+    // Update-check refresh: 30s AFTER startup on an unref'd timer, so the
+    // registry ping is never on the prompt-critical path and never interleaves
+    // with first-boot storage initialization (a boot-time kick raced the
+    // first-run demo seed on CI — same-instant sqlite init from two paths).
+    // Short-lived spawns (codex exec) exit before the timer fires and never
+    // ping npm; long-lived hosts refresh 30s in, ample for a 24h TTL.
+    // session_bootstrap renders from the persisted cache only.
+    const updateCheckTimer = setTimeout(() => {
+        void (async () => {
+            const { refreshUpdateCache } = await import("./updateNotice.js");
+            const { getSetting, setSetting } = await import("./storage/configStorage.js");
+            await refreshUpdateCache({ getSetting, setSetting });
+        })().catch(() => { });
+    }, 30_000);
+    updateCheckTimer.unref();
     // Register graceful shutdown handlers (SIGTERM, SIGINT, SIGHUP, stdin close).
     // The stdin close handler is critical — when MCP clients disconnect, they
     // often just close the pipe without sending a signal, leaving zombie processes.

package/dist/tools/ledgerHandlers.js

@@ -34,6 +34,18 @@ import { getSetting, setSetting, getAllSettings, refreshConfigStorageCache } fro
 import { MATERIALIZED_GENERATION_KEY } from "../skillManifestSync.js";
 import { mergeHandoff, dbToHandoffSchema, sanitizeForMerge } from "../utils/crdtMerge.js";
 import { resolveProject } from "../utils/projectResolver.js";
+import { getUpdateNotice } from "../updateNotice.js";
+// The running server's own version, for the update-available notice. A read
+// failure must never affect startup: an empty string fails the notice's
+// semver gate, so no notice renders rather than a bogus "running 0.0.0".
+const SERVER_PACKAGE_VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version ?? "";
+    }
+    catch {
+        return "";
+    }
+})();
 import { isRecoverableStartupStorageError, LOCAL_STARTUP_FALLBACK_NOTICE, } from "../utils/startupRecovery.js";
 import { PRISM_USER_ID, PRISM_AUTO_CAPTURE, PRISM_CAPTURE_PORTS } from "../config.js";
 import { captureLocalEnvironment } from "../utils/autoCapture.js";
@@ -2026,7 +2038,17 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
         ? `👋 Welcome to Prism — first run detected. Let's get you productive in a few minutes.`
         : `👋 Welcome back, ${greetingName}. Prism is loading ${depth} context.`;
     const identityBlock = `- 🤖 **Agent Identity:** ${escapeNativeMarkdown(compactWithOmissionCount(role, 80))} — ${greetingName}`;
-    const startupHeader = isFirstRun ? greeting : `${greeting}\n\n${identityBlock}`;
+    // Cache-only by contract: server startup refreshes the cache asynchronously;
+    // this call never touches the npm registry. First run skips the notice — a
+    // just-installed machine is current, and that screen is action-first.
+    const updateNotice = isFirstRun ? "" : await getUpdateNotice({
+        currentVersion: SERVER_PACKAGE_VERSION,
+        getSetting,
+        runningFrom: process.argv[1],
+    });
+    const startupHeader = isFirstRun
+        ? greeting
+        : `${greeting}\n\n${identityBlock}${updateNotice ? `\n${updateNotice}` : ""}`;
     if (projects.length === 0) {
         const dashboardUrl = await readDashboardUrl();
         const dashboardLine = dashboardUrl

package/dist/updateNotice.js

@@ -0,0 +1,104 @@
+/**
+ * Update-available notice — the trigger half of self-update.
+ *
+ * `prism connect` can converge a machine to the latest release, but nothing
+ * ever *ran* it: no launch agent, cron, or background updater exists, so
+ * releases only reached machines whose operator happened to re-run connect.
+ * The notice closes that gap at the only place every user reliably looks —
+ * the first turn of a session.
+ *
+ * Split enforced by design review (2026-08-14):
+ *  - `getUpdateNotice` is CACHE-ONLY. It runs on the prompt-critical path
+ *    (session_bootstrap) and must never touch the npm registry.
+ *  - `refreshUpdateCache` is the async half. Server startup kicks it
+ *    fire-and-forget after initialization; it respects a 24-hour TTL so a
+ *    machine pings the registry at most once a day no matter how many
+ *    short-lived server processes spawn (codex exec starts one per run).
+ *  - Offline is silent. A registry answer that is not plain semver is
+ *    discarded, never cached, never rendered — the cached value ends up
+ *    inside model-facing markdown, so it is validated on write AND on read.
+ */
+import { execFile } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { isNewer } from "./selfUpdate.js";
+export const UPDATE_CHECK_KEY = "update_check";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+const PACKAGE = "prism-mcp-server";
+async function readCache(getSetting) {
+    try {
+        const parsed = JSON.parse(await getSetting(UPDATE_CHECK_KEY, "{}"));
+        return typeof parsed === "object" && parsed !== null ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function cacheIsFresh(cache, now) {
+    return typeof cache.checked_at === "number" &&
+        now() - cache.checked_at < CACHE_TTL_MS &&
+        now() - cache.checked_at >= 0; // a future timestamp is corruption, not freshness
+}
+/** Cache-only: renders the notice line, or "" — never touches the network. */
+export async function getUpdateNotice(deps) {
+    const env = deps.env ?? process.env;
+    if (env.PRISM_NO_UPDATE_CHECK === "1")
+        return "";
+    // A caller that could not determine its own version renders nothing —
+    // a comparison against "" or "0.0.0" would call every release an update.
+    if (!SEMVER.test(deps.currentVersion))
+        return "";
+    const now = deps.now ?? Date.now;
+    const cache = await readCache(deps.getSetting);
+    if (!cacheIsFresh(cache, now))
+        return "";
+    const latest = typeof cache.latest === "string" && SEMVER.test(cache.latest) ? cache.latest : "";
+    if (!latest || !isNewer(deps.currentVersion, latest))
+        return "";
+    let fromCheckout = false;
+    if (deps.runningFrom) {
+        let resolved = deps.runningFrom;
+        try {
+            resolved = realpathSync(deps.runningFrom);
+        }
+        catch { /* keep raw */ }
+        fromCheckout = !resolved.includes("node_modules");
+    }
+    const command = fromCheckout ? "prism connect --refresh" : "prism connect";
+    return `- ⬆️ **Update available:** Prism ${latest} (running ${deps.currentVersion}) — run \`${command}\``;
+}
+function defaultFetchLatest() {
+    return new Promise((resolve, reject) => {
+        const child = execFile("npm", ["view", PACKAGE, "version"], { encoding: "utf8", timeout: 10_000 }, (error, stdout) => (error ? reject(error) : resolve(stdout.trim())));
+        // A short-lived server process (codex exec) must be able to exit without
+        // waiting on this check.
+        child.unref?.();
+    });
+}
+/** Async half: refresh the persisted cache when the TTL has lapsed.
+ *  Never throws — offline machines boot silently. */
+export async function refreshUpdateCache(deps) {
+    const env = deps.env ?? process.env;
+    if (env.PRISM_NO_UPDATE_CHECK === "1")
+        return;
+    if (env.VITEST || env.NODE_ENV === "test") {
+        // Test runners never reach the network — same rule as self-update —
+        // EXCEPT through an explicitly injected fetcher, which is the test.
+        if (!deps.fetchLatest)
+            return;
+    }
+    const now = deps.now ?? Date.now;
+    try {
+        const cache = await readCache(deps.getSetting);
+        if (cacheIsFresh(cache, now))
+            return;
+        const latest = (await (deps.fetchLatest ?? defaultFetchLatest)()).trim();
+        if (!SEMVER.test(latest))
+            return;
+        await deps.setSetting(UPDATE_CHECK_KEY, JSON.stringify({ checked_at: now(), latest }));
+    }
+    catch {
+        // Offline, registry down, npm missing: silence. The notice simply
+        // does not render until a later successful check.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.11.1",
+  "version": "20.12.1",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",