prism-mcp-server 20.12.0 → 20.13.0

package/README.md

@@ -116,6 +116,16 @@ 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
@@ -684,14 +694,20 @@ for manual configuration and host-specific paths.
 **Optional — local model fleet** for offline tool-routing. Pull whichever fits your hardware:
 
 ```bash
-ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% on our routing suite)
-ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% on our routing suite)
-ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% on our routing suite, Qwen3.5)
-ollama pull dcostenco/prism-coder:27b   # 16 GB  · complex tasks (100% on our routing suite)
+ollama pull dcostenco/prism-coder:2b    # 3.3 GB  · on-device / lowest RAM · sees images (100% on our routing suite)
+ollama pull dcostenco/prism-coder:4b    # 3.5 GB  · verifier · sees images (100%)
+ollama pull dcostenco/prism-coder:9b    # 6.7 GB  · default router · sees images (95.7%, reasons before answering)
+ollama pull dcostenco/prism-coder:27b   # 16.8 GB · complex code / quality · text only (100%)
 ```
 
 Prism detects both the namespaced (`dcostenco/prism-coder:9b`) and bare (`prism-coder:9b`) Ollama tags automatically.
 
+The 2b/4b/9b tiers carry a vision tower and accept screenshots through
+`prism_infer({ images: [...] })` — pass absolute paths or base64. Image
+requests are refused rather than answered blind when no tier (or the Layer 1
+safety classifier) can actually see the image, so a text-only model is never
+handed a prompt about a screenshot it never received. The 27b is text only.
+
 ---
 
 ## What it does
@@ -834,9 +850,9 @@ air-gap. **Enterprise** includes a HIPAA Business Associate Agreement.
 
 ## Models
 
-The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on our internal 115-case tool-routing suite and 100% on an internal 15-problem coding eval, at $0 inference cost. These are self-run evaluations, not [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) leaderboard submissions.
+The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned; the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on our internal 115-case tool-routing suite and 100% on an internal 15-problem coding eval, at $0 inference cost. These are self-run evaluations, not [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) leaderboard submissions.
 
-`prism_infer` supports three modes: `route` (tool routing, fast, nothink), `chat` (conversation with thinking), and `code` (code generation with thinking). In chat/code modes, the model uses `<think>` blocks for chain-of-thought reasoning, which are stripped before the response is served. If the local model fails a quality gate (empty, think-only, or truncated), paid tiers automatically escalate to Gemini 3.6 Flash via the Synalux portal.
+`prism_infer` supports three modes: `route` (tool routing, fast), `chat` (conversation) and `code` (code generation). Reasoning is decided by the **tier**, not the mode: a tier carrying `MODEL_TIERS.prefersThinking` also carries a `minLocalTokens` floor so reasoning cannot crowd out the answer, and only those tiers use `<think>` blocks (stripped before the response is served). The 9B does; the 4B and 2B do not, because on those tiers reasoning drew down the same `num_predict` budget the answer needed and returned an empty response. An explicit `think: true` still overrides, for a caller who has sized `max_tokens` for it. If the local model fails a quality gate (empty, think-only, or truncated), paid tiers automatically escalate to Gemini 3.6 Flash via the Synalux portal.
 
 Every route-mode result is parsed locally and checked against `allowed_tools`
 before it reaches the host. Malformed or unadvertised calls become `NO_TOOL`.
@@ -846,16 +862,33 @@ draft that may need correction—to Synalux for authenticated deterministic
 correction. Advertised custom host tools remain local. Set
 `route_guard: "local"` for a fully on-device route path.
 
-| Model | Ollama tag | Size | Routing accuracy¹ | Role | Automatic routing tier |
-|---|---|---|---|---|---|
-| Qwen3.5-4B Q3_K_M | `prism-coder:2b` | 2.3 GB | 99.1% × 3 seeds | iPhone / mobile first gate | Free |
-| Qwen3.5-4B Q4_K_M | `prism-coder:4b` | 3.4 GB | 100% × 3 seeds | Verifier | Free |
-| Qwen3.5-9B (LoRA) | `prism-coder:9b` | 5.8 GB | 100% × 3 seeds | Default router | Standard+ |
-| Qwen3.5-27B (LoRA) | `prism-coder:27b` | 16 GB | 100% × 3 seeds | Quality tier (DeltaNet, 28.5 tok/s) | Advanced+ |
-
-¹ Self-run on a narrow 115-case MCP tool-selection suite, 3 seeds. It says these
-models pick the right tool on our own eval, nothing more — not a general capability
-measure, and not an independent benchmark result. Full methodology caveats below.
+| Model | Ollama tag | Size | Vision | Routing accuracy¹ | Role | Automatic routing tier |
+|---|---|---|---|---|---|---|
+| Qwen3.5-4B Q4_K_S | `prism-coder:2b` | 3.3 GB | ✅ | 100% | On-device / lowest RAM (4.5 GiB free) | Free |
+| Qwen3.5-4B Q4_K_M | `prism-coder:4b` | 3.5 GB | ✅ | 100% | Verifier (5.2 GiB free) | Free |
+| Qwen3.5-9B (LoRA) | `prism-coder:9b` | 6.7 GB | ✅ | 95.7%² | Default router / workhorse (9 GiB free) | Standard+ |
+| Qwen3.5-27B (LoRA) | `prism-coder:27b` | 16.8 GB | — | 100% | Complex code / quality (21 GiB free) | Advanced+ |
+
+¹ Self-run on a narrow 115-case MCP tool-selection suite, `temperature: 0`,
+measured through the call path `prism_infer` actually uses (`/api/chat`, each
+model's own template). It says these models pick the right tool on our own eval,
+nothing more — not a general capability measure, and not an independent
+benchmark result. Earlier revisions of this table quoted 99.1–100% from a
+harness that hand-rolled a ChatML prompt with `raw: true`, bypassing the
+template; those numbers described a path no caller exercises. Full methodology
+caveats below.
+
+² The 9B is the one tier that reasons before answering, and it is measured with
+reasoning enabled: 95.7% with thinking, 83.5% without. `prism_infer` sets this
+per-tier (`MODEL_TIERS.prefersThinking`), so callers get the 95.7% path by
+default. Reasoning costs roughly 600 tokens, which is why the 9B also carries a
+2,048-token local floor.
+
+**Vision.** The 2B/4B/9B tags ship a separate `projector` layer (0.68–0.92 GB)
+and read images; the 27B is text-only. `prism_infer` probes for that layer and
+skips a tier with no vision rather than sending it an image — asked directly, a
+text-only model will still answer confidently about pixels it never received.
+Exercised against the real models in `tests/integration/visionScreenshot.test.ts`.
 
 These tiers control automatic `prism_infer` selection, not Ollama itself. Any
 user can run any downloaded on-device model directly through Ollama on every
@@ -910,10 +943,17 @@ reliability, not general model capability.
 
 | Model | Routing accuracy | Notes |
 |---|---|---|
-| prism-coder:2b (Q3_K_M) | 99.1% × 3 seeds | 1 failure: regex→knowledge_search |
-| prism-coder:4b / 9b / 27b | 100% × 3 seeds | Perfect on all 115 cases |
+| prism-coder:2b (Q4_K_S) | 100% | The 2B was requantised when vision shipped; the old 99.1% was Q3_K_M |
+| prism-coder:4b | 100% | |
+| prism-coder:9b | 95.7% with reasoning | 83.5% without — the only tier where this differs |
+| prism-coder:27b | 100% | |
 | Claude (frontier, same eval) | ~98% | Stronger everywhere outside this narrow task |
 
+Measured through `/api/chat` with each model's own template — the path
+`prism_infer` uses. `temperature: 0`, so the three seeds only reshuffle case
+order and cannot disagree; earlier revisions cited that agreement as
+confirmation, which it never was.
+
 **Memory uplift (LoCoMo-Plus, self-published).** A separate long-context dialogue benchmark ([dcostenco/Locomo-Plus](https://github.com/dcostenco/Locomo-Plus)) measures how much structured memory helps a base model retain multi-day context. Results show large gains when a model is paired with Prism memory versus running raw. Note this benchmark is authored, run, and LLM-judged by this project — treat it as a reproducible demonstration, not an independent third-party result, and run it yourself with the commands in that repo.
 
 **Code generation evaluation.** In a small July 2026 deterministic execution
@@ -1043,9 +1083,14 @@ prism_infer({
 
 | Mode | Think | Model | Use case |
 |------|-------|-------|----------|
-| `route` | Off (fast) | 9B default | MCP tool routing |
-| `chat` | On | 27B preferred | Conversation, reasoning |
-| `code` | On | 27B preferred | Code generation, debugging |
+| `route` | Off (fast) — except a tier that reasons better, e.g. 9B | 9B default | MCP tool routing |
+| `chat` | Per tier: on for 9B, off for 4B/2B | 27B preferred | Conversation, reasoning |
+| `code` | Per tier: on for 9B, off for 4B/2B | 27B preferred | Code generation, debugging |
+
+Think is a **tier** property, not a mode property. Tiers with
+`prefersThinking` also declare a `minLocalTokens` floor that reserves budget for
+the answer; tiers without it spend the whole `num_predict` allowance inside
+`<think>` and return nothing. Pass `think` explicitly to override either way.
 
 Full TypeScript signatures live in [`src/tools/`](src/tools/); architecture in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
 

package/dist/autoUpdate.js

@@ -31,6 +31,22 @@ function defaultFetchLatest() {
         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",
@@ -95,9 +111,6 @@ export function runPackageUpdate(deps) {
     if ((env.VITEST || env.NODE_ENV === "test") && !deps.fetchLatest) {
         return { action: "skipped", detail: "test environment" };
     }
-    if (deps.currentVersion.includes("-")) {
-        return { action: "skipped", detail: `dev build ${deps.currentVersion} — not touching it` };
-    }
     if (deps.ifIdle) {
         let running;
         try {
@@ -116,6 +129,28 @@ export function runPackageUpdate(deps) {
             };
         }
     }
+    // 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" };
@@ -131,10 +166,10 @@ export function runPackageUpdate(deps) {
         if (!SEMVER.test(latest)) {
             return { action: "failed", detail: `registry returned unexpected version "${latest}"` };
         }
-        if (!isNewer(deps.currentVersion, latest)) {
-            return { action: "current", detail: `${deps.currentVersion} is current`, latest };
+        if (!isNewer(targetVersion, latest)) {
+            return { action: "current", detail: `installed package ${targetVersion} is current`, latest };
         }
-        log(`prism ${deps.currentVersion} → ${latest}: updating the global package …`);
+        log(`prism ${targetVersion} → ${latest}: updating the global package …`);
         try {
             (deps.install ?? defaultInstall)(latest);
         }
@@ -151,8 +186,27 @@ export function runPackageUpdate(deps) {
 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) {
+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">
@@ -160,10 +214,14 @@ export function buildAutoupdatePlist(prismBin) {
   <key>Label</key><string>${AUTOUPDATE_LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${prismBin}</string>
+    <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>
@@ -181,28 +239,62 @@ export function autoupdateStatus() {
         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: enabled ? `enabled — daily 03:30, log: /tmp/${AUTOUPDATE_LABEL}.log` : "disabled",
+        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",
     };
 }
-/** Resolve the `prism` bin the LaunchAgent should run. Warns (does not
- *  refuse) when it resolves outside node_modules — a checkout CLI still
- *  updates the global package, but the operator should know which code
- *  their scheduler runs. */
-export function resolvePrismBin(log) {
-    const bin = execFileSync("which", ["prism"], { encoding: "utf8", timeout: 5_000 }).trim();
-    if (!bin)
-        throw new Error("`prism` not found on PATH — install with: npm install -g prism-mcp-server");
+export function resolvePrismBin(log, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    let globalBin;
     try {
-        const real = execFileSync("readlink", ["-f", bin], { encoding: "utf8", timeout: 5_000 }).trim();
-        if (real && !real.includes("node_modules")) {
-            log(`⚠ ${bin} resolves to a source checkout (${real}); the scheduled update will run that CLI (it still updates only the global package)`);
+        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 { /* readlink unavailable — proceed with the raw path */ }
+    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) {

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';
@@ -261,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/tools/compactionHandler.js

@@ -9,7 +9,7 @@
 import { getStorage } from "../storage/index.js";
 import { PRISM_USER_ID } from "../config.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
-import { callLocalLlm } from "../utils/localLlm.js";
+import { inferText } from "./prismInferHandler.js";
 import { PRISM_LOCAL_LLM_ENABLED, PRISM_STRICT_LOCAL_MODE } from "../config.js";
 import { debugLog } from "../utils/logger.js";
 // ─── Constants ────────────────────────────────────────────────
@@ -111,7 +111,10 @@ async function summarizeEntries(entries) {
     // ── Path 1: Local LLM (prism-coder:9b) ───────────────────────────
     if (PRISM_LOCAL_LLM_ENABLED) {
         debugLog(`[compact_ledger] Attempting local LLM summarization (${entries.length} entries)`);
-        const localResponse = await callLocalLlm(prompt);
+        // Ledger content goes through the full ladder so Layer 1 screening, the
+        // quality gate and the entitlement ceiling all apply — this summarises
+        // session records that may carry sensitive material.
+        const localResponse = await inferText(prompt, { mode: "chat" });
         if (localResponse) {
             debugLog(`[compact_ledger] Local LLM summarization succeeded`);
             return parseCompactionResponse(localResponse, "local-llm");

package/dist/tools/ingestHandler.js

@@ -54,50 +54,60 @@ function chunkSource(content, chunkSize, source) {
         totalChars: content.length,
     };
 }
-// ─── Q&A Generator (Claude Haiku) ───────────────────────────────
+// ─── Q&A Generator (via prism_infer) ────────────────────────────
+/**
+ * Generate training Q&A pairs for a chunk.
+ *
+ * This used to POST straight to api.anthropic.com with a key read from
+ * ANTHROPIC_API_KEY **or ~/.anthropic_key**. That is an ambient-credential
+ * path: any process with the variable set bills the owner, which is how a
+ * local test run once burned ~$500 against a key exported in a shell profile.
+ * It also sat outside every gate prism applies to model calls.
+ *
+ * Ingest is training-data generation rather than user-facing inference, which
+ * is why it was left alone at first — but "not inference" does not make a raw
+ * billing surface a good idea, and prism_infer already offers the same
+ * capability local-first with an entitlement-gated cloud fallback. So it goes
+ * through the ladder like everything else, and prism no longer reads a
+ * provider key from the environment at all.
+ *
+ * PHI redaction still runs BEFORE the model sees anything: a chunk may carry
+ * client names in file paths, inline identifiers, or clinical notes, and the
+ * local tier is not a licence to skip that.
+ */
 async function generateQAPairs(chunk, source) {
-    const apiKey = process.env.ANTHROPIC_API_KEY ||
-        (existsSync(`${process.env.HOME}/.anthropic_key`)
-            ? readFileSync(`${process.env.HOME}/.anthropic_key`, "utf-8").trim()
-            : null);
-    if (!apiKey) {
-        debugLog("[ingest] No ANTHROPIC_API_KEY — skipping Q&A generation, storing raw chunks");
-        return [{ prompt: `What does this ${source} code do?`, response: chunk.slice(0, 500) }];
-    }
-    // PHI redaction BEFORE sending to cloud LLM — the chunk may contain
-    // client names in file paths, inline identifiers, or clinical notes.
+    const fallback = [{ prompt: `What does this ${source} code do?`, response: chunk.slice(0, 500) }];
     const { scanAndRedactPHI } = await import("../utils/phiGuard.js");
     const redactedChunk = scanAndRedactPHI(chunk).redacted;
+    const { inferText } = await import("./prismInferHandler.js");
+    const text = await inferText(`Source: ${source}\n\`\`\`\n${redactedChunk.slice(0, 5000)}\n\`\`\``, {
+        system: 'Generate 3 Q&A training pairs as JSON array: [{"prompt":"...","response":"..."}]. Focus on what the code does, how it works, and key patterns.',
+        mode: "chat",
+        maxTokens: 2048,
+    });
+    if (!text) {
+        debugLog("[ingest] no model output — storing raw chunk");
+        return fallback;
+    }
     try {
-        const res = await fetch("https://api.anthropic.com/v1/messages", {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                "x-api-key": apiKey,
-                "anthropic-version": "2023-06-01",
-            },
-            body: JSON.stringify({
-                model: "claude-haiku-4-5-20251001",
-                max_tokens: 2048,
-                system: 'Generate 3 Q&A training pairs as JSON array: [{"prompt":"...","response":"..."}]. Focus on what the code does, how it works, and key patterns.',
-                messages: [{ role: "user", content: `Source: ${source}\n\`\`\`\n${redactedChunk.slice(0, 5000)}\n\`\`\`` }],
-            }),
-        });
-        if (!res.ok) {
-            debugLog(`[ingest] Claude API error: ${res.status}`);
-            return [];
-        }
-        const data = await res.json();
-        const text = data.content?.[0]?.text || "";
         const match = text.match(/\[.*\]/s);
-        if (match) {
-            return JSON.parse(match[0]);
+        if (!match) {
+            debugLog("[ingest] model output had no JSON array — storing raw chunk");
+            return fallback;
         }
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed))
+            return fallback;
+        // Only keep well-formed pairs; a malformed element must not reach storage
+        // as an undefined prompt/response.
+        const pairs = parsed.filter((p) => !!p && typeof p.prompt === "string"
+            && typeof p.response === "string");
+        return pairs.length > 0 ? pairs : fallback;
     }
     catch (err) {
-        debugLog(`[ingest] Q&A generation error: ${err}`);
+        debugLog(`[ingest] Q&A parse error: ${err}`);
+        return fallback;
     }
-    return [];
 }
 // ─── Main Ingest Pipeline ───────────────────────────────────────
 export async function ingestKnowledge(args) {