prism-mcp-server 20.2.6 → 20.2.7

package/README.md

@@ -57,6 +57,38 @@ features.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.2.7
+
+### Session Saves Survive Agent Restarts
+Prism now remembers that a conversation successfully loaded its project context
+when the MCP server restarts or another Prism process handles the next request.
+`session_save_ledger` and `session_save_handoff` no longer fail with a false
+`context_not_loaded` error in that flow.
+
+The recovery remains fail-closed: authorization is limited to the exact project
+and conversation, expires with the existing context window, and stores no
+plaintext conversation identifier. Cross-project, forged, malformed, expired,
+or future-dated receipts are still rejected. The release also updates PostCSS
+to the patched 8.5.23 release.
+
+---
+
+## What's New in v20.2.6
+
+### Safer Configuration Updates Across Every Agent
+`prism connect` now reads Claude, Cursor, Gemini, and Codex configuration
+through a single verified file snapshot, preventing another process from
+swapping a file between Prism's safety check and its read. Supported symlinked
+dotfiles still work, while dangling or planted symlinks fail loudly instead of
+being followed or overwritten. This release also carries the patched
+dependencies and cross-platform release checks introduced in v20.2.5.
+
+Cloud fallback is now documented consistently as Gemini 3.6 Flash. Plan
+ceilings govern automatic `prism_infer` routing; direct use of any downloaded
+model through local Ollama remains free on every tier.
+
+---
+
 ## What's New in v20.2.4
 
 ### Reliable Session Memory That Shows Work, Not Greetings
@@ -354,7 +386,7 @@ Every `prism_infer` call tracks which model handled it (local Ollama vs cloud) a
     synalux-27b: 2 calls, 1,500 tokens, avg 1,100ms
 ```
 
-**Cloud tokens saved** is the honest routing metric — it accrues only when local Ollama handles a call that would otherwise have gone to Claude or the Synalux portal. A compact version appears inline after every 5th `prism_infer` call: `📊 local 10 (83%) · cloud 2 (17%) · ~11,570 tok · avg 1,240ms · 11,570 cloud tok saved`.
+**Cloud tokens saved** is the honest routing metric — it accrues only when local Ollama handles a call that would otherwise have gone to Synalux cloud inference. A compact version appears inline after every 5th `prism_infer` call: `📊 local 10 (83%) · cloud 2 (17%) · ~11,570 tok · avg 1,240ms · 11,570 cloud tok saved`.
 
 Local calls use actual Ollama token counts (`prompt_eval_count` / `eval_count` from Ollama); cloud calls use char/4 estimates. Metrics are tracked locally — no portal dependency, no env vars, works offline. Per-call data is also forwarded to the Synalux portal as best-effort analytics (independent of the display).
 
@@ -413,7 +445,7 @@ The free tier runs entirely on your machine. Paid tiers add cloud sync through t
 | | Local tier (free) | Cloud tier (paid) |
 |---|---|---|
 | Memory storage | Local SQLite | Synalux portal (Supabase-backed) |
-| Inference | Local Ollama models | Local models + cloud fallback |
+| Inference | Local Ollama models | Local models + Gemini 3.6 Flash fallback |
 | API keys required | None | Synalux subscription key |
 | Web search / scrape | Not included | Via Synalux portal (provider keys server-side) |
 | What leaves your machine | Nothing | Memory text + file paths + search queries, sent to the portal over TLS (PHI-redacted before transit) |
@@ -427,15 +459,19 @@ The free tier runs entirely on your machine. Paid tiers add cloud sync through t
 
 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 BFCL function-calling and 100% on an internal 15-problem coding eval at $0 inference cost.
 
-`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 Claude via the Synalux portal.
+`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.
 
-| Model | Ollama tag | Size | [BFCL](https://gorilla.cs.berkeley.edu/blogs/12_bfcl_v3_multi_turn.html) Accuracy | Role | Tier |
+| Model | Ollama tag | Size | [BFCL](https://gorilla.cs.berkeley.edu/blogs/12_bfcl_v3_multi_turn.html) 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+ |
 
+These tiers control automatic `prism_infer` selection, not Ollama itself. Any
+user can run any downloaded on-device model directly through Ollama on every
+plan.
+
 Weights: [huggingface.co/dcostenco](https://huggingface.co/dcostenco) (public GGUF). Latency depends on model size and hardware — see [Benchmarks](#benchmarks) to measure it on your own machine rather than trusting a printed number.
 
 ### Cascade
@@ -445,7 +481,7 @@ query → prism-coder:9b (local router, default)
       → prism-coder:4b (grounding verifier)
       → prism-coder:2b (iPhone / mobile, auto-selected by RAM)
       → prism-coder:27b (complex tasks, on demand)
-      → cloud fallback (paid tiers, for max quality)
+      → Gemini 3.6 Flash cloud fallback (paid tiers, for max quality)
 ```
 
 ### Multi-Layer Verification
@@ -466,15 +502,14 @@ Fail-closed on the verified path: when the grounding verifier runs (Standard tie
 
 ## Benchmarks
 
-**Reproduce every number yourself.** All evals are open-source and self-contained:
-
-```bash
-git clone https://github.com/dcostenco/prism-coder && cd prism-coder
-pip install anthropic requests
-python3 tests/benchmarks/prism-routing-100/benchmark.py --models 2b 4b 9b 27b
-```
+Published benchmark numbers are concise summaries of internal deterministic
+evaluation. Evaluators, exhaustive cases, exact tier-routing matrices, and raw
+model outputs stay in the private engineering repository and are not included
+in the npm package or public source tree.
 
-**Routing eval (115 cases, 12 categories, 3-seed mean).** Routing accuracy includes the deterministic L3 correction layer — the same rules that run in production. On this narrow tool-routing task all fleet models achieve near-perfect accuracy. Be honest with yourself about what that means: the eval is **near-saturated** for this taxonomy — it measures whether the right one of a small set of MCP tools is selected, not general capability. The useful takeaway is **offline routing reliability at zero cost**, not that a 2.3 GB model rivals a frontier model in general.
+**Routing evaluation.** On a narrow tool-selection suite, the fleet achieved
+near-saturated results across three seeds. This measures offline MCP routing
+reliability, not general model capability.
 
 | Model | Routing accuracy | Notes |
 |---|---|---|
@@ -484,90 +519,17 @@ python3 tests/benchmarks/prism-routing-100/benchmark.py --models 2b 4b 9b 27b
 
 **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 Quality (27B vs Claude Opus)
+**Code generation evaluation.** In a small July 2026 deterministic execution
+check, the local 9B passed 2/3 tasks; the local 27B and Gemini 3.6 Flash each
+passed 3/3. This is a self-published regression signal, not an independent
+leaderboard or a claim of broad model equivalence.
 
-Three progressively harder Python tasks run through `prism_infer(mode:"code", think:true)` on the local 27B and compared with Claude Opus. Both produce correct, production-quality code. The 27B is slightly more verbose (docstrings, examples); Opus is slightly tighter (`__slots__`, early-exit DFS). On routine coding the 27B at $0 replaces cloud calls entirely.
+### Cloud Escalation (`cloud_fallback: true`)
 
-| Task | Local 27B | Claude Opus | Verdict |
-|------|-----------|-------------|---------|
-| Fibonacci with memoization | `@lru_cache`, ValueError on negative, docstring | Nested `_fib` to keep cache private | Both correct, equivalent |
-| LRU Cache (OrderedDict, O(1)) | `Any` keys, isinstance capacity check, `__repr__` | `Hashable` key type (more precise), same ops | Both correct, Opus marginally tighter |
-| Trie with autocomplete | `.lower()` normalization, collect+sort+slice | `__slots__` on TrieNode, early-exit DFS at limit | Both correct, Opus slightly more optimized |
-
-<details>
-<summary>Local 27B output — Trie with autocomplete (hardest task)</summary>
-
-```python
-class TrieNode:
-    def __init__(self):
-        self.children: dict[str, 'TrieNode'] = {}
-        self.is_end_of_word: bool = False
-
-class Trie:
-    def __init__(self):
-        self.root: TrieNode = TrieNode()
-
-    def insert(self, word: str) -> None:
-        node = self.root
-        for char in word.lower():
-            if char not in node.children:
-                node.children[char] = TrieNode()
-            node = node.children[char]
-        node.is_end_of_word = True
-
-    def search(self, word: str) -> bool:
-        node = self._get_node(word.lower())
-        return node is not None and node.is_end_of_word
-
-    def starts_with(self, prefix: str) -> bool:
-        return self._get_node(prefix.lower()) is not None
-
-    def autocomplete(self, prefix: str, limit: int = 5) -> list[str]:
-        node = self._get_node(prefix.lower())
-        if node is None:
-            return []
-        results: list[str] = []
-        self._collect_words(node, prefix.lower(), results)
-        results.sort()
-        return results[:limit]
-
-    def _get_node(self, key: str) -> 'TrieNode | None':
-        node = self.root
-        for char in key:
-            if char not in node.children:
-                return None
-            node = node.children[char]
-        return node
-
-    def _collect_words(self, node: TrieNode, prefix: str, results: list[str]) -> None:
-        if node.is_end_of_word:
-            results.append(prefix)
-        for char, child in sorted(node.children.items()):
-            self._collect_words(child, prefix + char, results)
-```
-
-</details>
-
-| Metric | Local 27B | Cloud (Opus) |
-|--------|-----------|-------------|
-| Latency (Trie task) | ~30s | ~8s |
-| Cost | $0 | ~$0.05 |
-| Think mode | Enabled (stripped before serving) | N/A |
-| Quality gate | Passed (no escalation needed) | N/A |
-
-### Cloud Escalation in Practice (`cloud_fallback: true`)
-
-The same three tasks with `cloud_fallback: true` — the quality gate decides whether local output is good enough or needs cloud escalation.
-
-| Task | used_cloud | Quality Gate | Latency | What happened |
-|------|:----------:|-------------|---------|---------------|
-| Fibonacci (simple) | **no** | Passed | 11s | 27B served directly, $0 |
-| LRU Cache (medium) | **no** | Passed | 21s | 27B served directly, $0 |
-| Trie (hard) | **yes** | `loop_detected` | 55s | 27B looped → gate caught it → escalated to cloud 27B |
-
-The quality gate detected repeated sentences (≥3 of the same sentence in ≥6 total) in the 27B's Trie output and escalated automatically. The cloud fallback returned clean code. On a second run of the same prompt, the 27B produced clean output without escalation — the loop is stochastic, not systematic.
-
-**Takeaway:** for ~80–90% of coding tasks, the 27B handles everything locally at $0. The quality gate + cloud escalation exists as a safety net for the remaining cases where the local model loops, truncates, or produces empty output. Paid tiers get automatic escalation; free tier gets the local result with a warning.
+Prism always tries an eligible local model first. If the quality gate detects
+an empty, truncated, think-only, or looping response, paid tiers can retry the
+request through Gemini 3.6 Flash. Free-tier routing stays local and reports the
+quality-gate outcome without making a cloud call.
 
 ---
 
@@ -618,17 +580,17 @@ and [Amazon Q Developer](https://aws.amazon.com/q/developer/pricing/).
 
 ## Plans
 
-All on-device models are free to run locally via Ollama on every tier. A subscription gates **cloud** features, higher model ceilings, and increased limits. Local model ceilings are advisory — on-device models run on your Ollama regardless of plan; the ceiling gates cloud inference and `prism_infer` routing.
+All on-device models are free to run locally via Ollama on every tier. A subscription gates **cloud** features, higher automatic-routing ceilings, and increased limits. On-device models run through your Ollama regardless of plan; the ceiling applies only to cloud inference and automatic `prism_infer` routing.
 
 | | **Free** | **Standard** $19/mo | **Advanced** $49/mo | **Enterprise** $99/mo |
 |---|---|---|---|---|
 | Seats | 1 | 1 | up to 5 | up to 25 |
-| Local model ceiling | up to 4b | up to 9b | up to 27b | up to 27b |
+| Automatic `prism_infer` ceiling | up to 4b | up to 9b | up to 27b | up to 27b |
 | Cloud inference | -- | ✅ | ✅ | ✅ (priority) |
 | Cloud Coder (Web IDE) | -- | ✅ | ✅ | ✅ (priority) |
 | Cloud search | -- | ✅ | ✅ | ✅ |
 | Max output tokens | 512 | 1,024 | 2,048 | 4,096 |
-| Cloud fallback | -- | Claude Opus 4.7 | Claude Opus 4.7 | Priority + Opus 4.7 |
+| Cloud fallback | -- | Gemini 3.6 Flash | Gemini 3.6 Flash | Gemini 3.6 Flash (priority) |
 | Grounding verifier (fact-check AI output) | -- | ✅ | ✅ | ✅ |
 | Memory sync (cloud) | -- | ✅ | ✅ | ✅ |
 | Knowledge / session memory | limited | unlimited | unlimited | unlimited |
@@ -650,13 +612,25 @@ Prism exposes 40+ MCP tools. The core memory loop:
 | `session_save_ledger` | Append an immutable session log entry |
 | `session_save_handoff` | Save live state for the next session |
 | `knowledge_search` | Semantic + keyword search over all memories |
-| `query_memory_natural` | Natural-language Q&A over the memory store |
+| `query_memory_natural` | Memory-first Q&A with a grounded live-source fallback on paid tiers |
 | `session_detect_drift` | Detect when a session has drifted from its goal |
 | `verify_behavior` | Pre-edit scenario challenge — catch bad changes before they happen |
 | `knowledge_ingest` | Teach Prism a codebase or document |
 | `prism_infer` | Local-first inference (route/chat/code modes, thinking, cloud escalation) |
 | `inference_metrics` | Session delegation or persisted MCP + VS Code panel local/cloud stats |
 
+### `query_memory_natural` — memory first, current sources when needed
+
+Ask one natural-language question instead of choosing separate memory, search,
+scrape, and inference tools. Prism searches its accumulated project memory
+first. If no useful evidence exists, paid tiers run one bounded Synalux search
+(Firecrawl, Gemini 3.6 Google Search grounding, then legacy Brave fallback),
+resolve and preserve the source URLs, scrape the leading page, and ask a
+RAM-safe local Prism Coder model to answer from that evidence. The paid-tier
+Gemini 3.6 verifier checks the draft before it is served. Reserved or uncertain
+clinical content never enters the web-grounded local path; it follows Prism's
+cloud-or-refuse safety boundary.
+
 ### `prism_infer` — local-first inference with cloud escalation
 
 ```typescript
@@ -667,7 +641,7 @@ prism_infer({
     model_ceiling: "27b", // use the quality tier
 })
 // → 27B generates code locally ($0), with thinking for quality
-// → If quality gate fails + paid tier → auto-escalate to Claude
+// → If quality gate fails + paid tier → auto-escalate to Gemini 3.6 Flash
 ```
 
 | Mode | Think | Model | Use case |
@@ -694,7 +668,7 @@ Call `inference_metrics` anytime mid-session to see how many `prism_infer` calls
 
 The same block also appears automatically in `session_save_ledger` and `session_save_handoff` responses at session end.
 
-**Note:** The default session view tracks this MCP process's `prism_infer` delegation. The all-time view combines persisted MCP calls with Synalux VS Code panel inference. Neither view includes your host model's (Claude's) own token spend; use Claude Code's `/cost` command for that.
+**Note:** The default session view tracks this MCP process's `prism_infer` delegation. The all-time view combines persisted MCP calls with Synalux VS Code panel inference. Neither view includes the host agent's own token spend; use that host's native usage reporting when available.
 
 ### Local-model delegation (default)
 
@@ -883,7 +857,11 @@ ollama pull dcostenco/prism-coder:9b       # default router
 export LOCAL_LLM_URL=http://localhost:11434
 ```
 
-Routing is automatic: `9b → 4b → cloud fallback` on desktop/server, `2b → cloud fallback` on mobile/iPhone. For iOS or another machine on the same network, run `OLLAMA_HOST=0.0.0.0 ollama serve` and point `LOCAL_LLM_URL` at the host's IP.
+Self-hosted routing stays local: `9b → 4b` on desktop/server and `2b` on
+mobile/iPhone, with 27B available when installed and RAM-safe. Synalux-hosted
+paid tiers can use Gemini 3.6 Flash as the cloud fallback. For iOS or another
+machine on the same network, run `OLLAMA_HOST=0.0.0.0 ollama serve` and point
+`LOCAL_LLM_URL` at the host's IP.
 
 ---
 
@@ -934,7 +912,7 @@ It reads `~/.prism-mcp/data.db` and POSTs entries to the portal. Ledger entries
 
 | Feature | Details |
 |---------|---------|
-| Local inference | Ollama via `prism_infer`, capped at the 4B model tier |
+| Local inference | Direct Ollama use is unrestricted; automatic `prism_infer` routing selects up to 4B |
 | Session memory | Persistent sessions, handoffs, ledger — all local SQLite |
 | Knowledge search | Semantic search across session history |
 | Skills | All skills available locally (run `sync-skills.sh` to populate) |
@@ -946,7 +924,7 @@ Everything in Free, plus:
 
 | Feature | Details |
 |---------|---------|
-| Model ceiling | Up to 27B locally + cloud cascade (9B → 27B → Claude) when local is unavailable |
+| Model ceiling | Automatic `prism_infer` routing up to 27B + Gemini 3.6 Flash fallback when local is unavailable |
 | Skill routing | Portal resolves which skills to load based on your project and prompt |
 | Cross-device memory | Supabase cloud sync — sessions survive across machines |
 | Grounding verifier | L3 NLI verification on model outputs |

package/dist/session/sessionContext.js

@@ -1,11 +1,11 @@
 /**
- * Session state tracking — connection-scoped, in-process.
+ * Session state tracking — in-process hot path with a durable local receipt.
  *
  * This is NOT business logic — it's MCP connection lifecycle state.
  * Business logic (skill routing, budget tranching, content resolution)
  * lives in the synalux portal at /api/v1/prism/skills.
  *
- * What stays here (connection-scoped, cannot be portal-side):
+ * What stays here (host lifecycle state, cannot be portal-side):
  *   markContextLoaded / requireContextLoaded — write-gate for session tools
  *   noteInferenceForSession — telemetry counter
  *   drift timer — connection-scoped GATE 5 enforcement
@@ -14,9 +14,12 @@
  *   Skill routing, budget tranching, content loading, phantom detection,
  *   prompt-keyword matching, user-local skill loading, context-discovery.
  */
+import { createHash } from "node:crypto";
 import { BOUNDARIES_VERSION as CURRENT_BOUNDARIES_VERSION } from "../boundaries/boundaries.js";
+import * as configStorage from "../storage/configStorage.js";
 const SESSION_TTL_MS = 6 * 60 * 60 * 1000; // 6 h — conversation-scoped
 const MAX_SESSIONS = 10_000;
+const RECEIPT_CLOCK_SKEW_MS = 60_000;
 /**
  * Connection-scoped fallback: remember the last conversation_id seen via
  * markContextLoaded so that tools which don't carry conversation_id
@@ -81,6 +84,62 @@ export function markContextLoaded(conversationId, project, boundariesVersion) {
     s.boundariesVersion = boundariesVersion;
     lastSeenConversationId = conversationId;
 }
+function contextNotLoadedError(project) {
+    const projectNote = project
+        ? " the requested project was not loaded for this conversation."
+        : "";
+    return {
+        blocked: true,
+        error: "context_not_loaded:" + projectNote + " Call session_bootstrap(conversation_id) or " +
+            "session_load_context(project, conversation_id) " +
+            "before this action. This project-scoped tool needs confirmed working context " +
+            "to act correctly. (Enforced server-side — applies to every host.)",
+    };
+}
+function contextExpiredError() {
+    return {
+        blocked: true,
+        error: "context_not_loaded: session expired (6 h TTL). Call " +
+            "session_bootstrap(conversation_id) or session_load_context(project, conversation_id) again. " +
+            "(Enforced server-side — applies to every host.)",
+    };
+}
+function hashReceiptScope(kind, value) {
+    return createHash("sha256").update(`prism-session-${kind}\0${value}`).digest("hex");
+}
+async function persistContextReceipt(conversationId, project, boundariesVersion, loadedAt) {
+    const now = Date.now();
+    const receipt = {
+        conversationHash: hashReceiptScope("conversation", conversationId),
+        projectHash: hashReceiptScope("project", project),
+        project,
+        boundariesVersion,
+        loadedAt,
+        lastSeen: now,
+    };
+    await configStorage.saveSessionContextReceipt(receipt, now - SESSION_TTL_MS);
+}
+async function persistContextReceiptBestEffort(conversationId, project, boundariesVersion, loadedAt) {
+    try {
+        await persistContextReceipt(conversationId, project, boundariesVersion, loadedAt);
+    }
+    catch (error) {
+        // Keep the established same-process path available on read-only or damaged
+        // config stores, but make degraded restart recovery visible to operators.
+        console.error(`[sessionContext] Durable context receipt unavailable for project "${project}": ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Registers successful context materialization and persists an opaque receipt.
+ * The conversation_id never leaves this process unhashed.
+ */
+export async function registerContextLoaded(conversationId, project, boundariesVersion) {
+    markContextLoaded(conversationId, project, boundariesVersion);
+    noteDriftSessionStart(conversationId);
+    const s = sessions.get(conversationId);
+    await persistContextReceiptBestEffort(conversationId, project, boundariesVersion, s?.driftSessionStart ?? Date.now());
+}
 /**
  * Soft gate for handlers that need project context to be CORRECT (not safe).
  *
@@ -108,21 +167,10 @@ export function requireContextLoaded(conversationId) {
     // even if no write has triggered eviction yet. Evict immediately on detection.
     if (s && (Date.now() - s.lastSeen) > SESSION_TTL_MS) {
         sessions.delete(conversationId);
-        return {
-            blocked: true,
-            error: "context_not_loaded: session expired (6 h TTL). Call " +
-                "session_bootstrap(conversation_id) or session_load_context(project, conversation_id) again. " +
-                "(Enforced server-side — applies to every host.)",
-        };
+        return contextExpiredError();
     }
     if (!s || !s.contextLoaded) {
-        return {
-            blocked: true,
-            error: "context_not_loaded: call session_bootstrap(conversation_id) or " +
-                "session_load_context(project, conversation_id) " +
-                "before this action. This project-scoped tool needs confirmed working context " +
-                "to act correctly. (Enforced server-side — applies to every host.)",
-        };
+        return contextNotLoadedError();
     }
     // Touch on valid read — maintains LRU order.
     touch(conversationId, s);
@@ -139,6 +187,56 @@ export function requireContextLoaded(conversationId) {
     }
     return null;
 }
+/**
+ * Project-scoped durable gate used by ledger and handoff writes.
+ *
+ * The in-memory state remains the hot path. If another MCP process loaded the
+ * requested project, or this process restarted, an unexpired hashed receipt
+ * restores only that exact project. Unknown, malformed, expired, and
+ * cross-project lookups remain fail-closed.
+ */
+export async function requireContextLoadedForProject(conversationId, project) {
+    if (conversationId === undefined)
+        return null;
+    if (!conversationId || !project.trim())
+        return contextNotLoadedError(project || undefined);
+    const memoryGate = requireContextLoaded(conversationId);
+    const memoryState = sessions.get(conversationId);
+    if (memoryState?.contextLoaded && memoryState.project === project &&
+        !(memoryGate && memoryGate.blocked)) {
+        await persistContextReceiptBestEffort(conversationId, project, memoryState.boundariesVersion ?? CURRENT_BOUNDARIES_VERSION, memoryState.driftSessionStart ?? memoryState.lastSeen);
+        return memoryGate;
+    }
+    let receipt = null;
+    try {
+        receipt = await configStorage.getSessionContextReceipt(hashReceiptScope("conversation", conversationId), hashReceiptScope("project", project));
+    }
+    catch (error) {
+        console.error(`[sessionContext] Durable context receipt lookup failed for project "${project}": ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+        return memoryGate && memoryGate.blocked ? memoryGate : contextNotLoadedError(project);
+    }
+    if (!receipt)
+        return memoryGate?.blocked ? memoryGate : contextNotLoadedError(project);
+    const now = Date.now();
+    const invalidReceipt = receipt.project !== project ||
+        !Number.isFinite(receipt.loadedAt) ||
+        !Number.isFinite(receipt.lastSeen) ||
+        receipt.loadedAt <= 0 ||
+        receipt.loadedAt > receipt.lastSeen ||
+        receipt.lastSeen > now + RECEIPT_CLOCK_SKEW_MS;
+    if (invalidReceipt)
+        return contextNotLoadedError(project);
+    if ((now - receipt.lastSeen) > SESSION_TTL_MS)
+        return contextExpiredError();
+    markContextLoaded(conversationId, project, receipt.boundariesVersion);
+    const restored = sessions.get(conversationId);
+    if (restored)
+        restored.driftSessionStart = receipt.loadedAt;
+    const restoredGate = requireContextLoaded(conversationId);
+    await persistContextReceiptBestEffort(conversationId, project, receipt.boundariesVersion, receipt.loadedAt);
+    return restoredGate;
+}
 /** Best-effort telemetry from prism_infer. Never affects a safety decision. */
 export function noteInferenceForSession(conversationId, info) {
     // Only update sessions that already exist — don't create ghost stubs for

package/dist/storage/configStorage.js

@@ -61,6 +61,17 @@ export async function initConfigStorage() {
         owner TEXT NOT NULL DEFAULT 'prism',
         updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
       )
+    `);
+        await client.execute(`
+      CREATE TABLE IF NOT EXISTS session_context_receipts (
+        conversation_hash TEXT NOT NULL,
+        project_hash TEXT NOT NULL,
+        project TEXT NOT NULL,
+        boundaries_version TEXT NOT NULL,
+        loaded_at INTEGER NOT NULL,
+        last_seen INTEGER NOT NULL,
+        PRIMARY KEY (conversation_hash, project_hash)
+      )
     `);
         // Preload all rows into the cache so subsequent reads are zero-cost.
         const rs = await client.execute("SELECT key, value FROM system_settings");
@@ -192,6 +203,95 @@ export function getSettingSync(key, defaultValue = "") {
         return defaultValue;
     return settingsCache[key] ?? defaultValue;
 }
+const SHA256_HEX_RE = /^[a-f0-9]{64}$/;
+function validateSessionContextReceipt(receipt) {
+    if (!SHA256_HEX_RE.test(receipt.conversationHash) ||
+        !SHA256_HEX_RE.test(receipt.projectHash) ||
+        !receipt.project.trim() ||
+        !receipt.boundariesVersion.trim() ||
+        !Number.isFinite(receipt.loadedAt) ||
+        !Number.isFinite(receipt.lastSeen)) {
+        throw new Error("Invalid session context receipt");
+    }
+}
+/**
+ * Persists only hashes of the caller-supplied identifiers. The project name is
+ * retained so recovery can verify that a hash lookup did not cross scopes.
+ * Expired rows are pruned in the same transaction to keep the local table
+ * bounded by active sessions rather than process lifetime.
+ */
+export async function saveSessionContextReceipt(receipt, expiresBefore) {
+    validateSessionContextReceipt(receipt);
+    if (!Number.isFinite(expiresBefore))
+        throw new Error("Invalid session receipt expiry");
+    await initConfigStorage();
+    const client = getClient();
+    await client.batch([
+        {
+            sql: "DELETE FROM session_context_receipts WHERE last_seen < ?",
+            args: [expiresBefore],
+        },
+        {
+            sql: `
+        INSERT INTO session_context_receipts (
+          conversation_hash,
+          project_hash,
+          project,
+          boundaries_version,
+          loaded_at,
+          last_seen
+        )
+        VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(conversation_hash, project_hash) DO UPDATE SET
+          project = excluded.project,
+          boundaries_version = excluded.boundaries_version,
+          loaded_at = excluded.loaded_at,
+          last_seen = excluded.last_seen
+      `,
+            args: [
+                receipt.conversationHash,
+                receipt.projectHash,
+                receipt.project,
+                receipt.boundariesVersion,
+                receipt.loadedAt,
+                receipt.lastSeen,
+            ],
+        },
+    ], "write");
+}
+export async function getSessionContextReceipt(conversationHash, projectHash) {
+    if (!SHA256_HEX_RE.test(conversationHash) || !SHA256_HEX_RE.test(projectHash)) {
+        return null;
+    }
+    await initConfigStorage();
+    const rs = await getClient().execute({
+        sql: `
+      SELECT project, boundaries_version, loaded_at, last_seen
+      FROM session_context_receipts
+      WHERE conversation_hash = ? AND project_hash = ?
+      LIMIT 1
+    `,
+        args: [conversationHash, projectHash],
+    });
+    if (rs.rows.length === 0)
+        return null;
+    const row = rs.rows[0];
+    const receipt = {
+        conversationHash,
+        projectHash,
+        project: String(row.project ?? ""),
+        boundariesVersion: String(row.boundaries_version ?? ""),
+        loadedAt: Number(row.loaded_at),
+        lastSeen: Number(row.last_seen),
+    };
+    try {
+        validateSessionContextReceipt(receipt);
+        return receipt;
+    }
+    catch {
+        return null;
+    }
+}
 export async function getSetting(key, defaultValue = "") {
     await initConfigStorage();
     // Serve from cache when warm (the common case after startup).

package/dist/tools/graphHandlers.js

@@ -63,7 +63,7 @@ export async function knowledgeSearchHandler(args) {
     }
     // Phase 1: destructure enable_trace (defaults to false for backward compat)
     const { project, query, category, limit = 10, enable_trace = false, activation } = args;
-    debugLog(`[knowledge_search] Searching: project=${project || "all"}, query="${query || ""}", category=${category || "any"}, limit=${limit}`);
+    debugLog(`[knowledge_search] Searching: project=${project || "all"}, query_chars=${query?.length || 0}, category=${category || "any"}, limit=${limit}`);
     // Phase 1: Capture total start time for latency measurement
     const totalStart = performance.now();
     const storage = await getStorage();
@@ -89,7 +89,8 @@ export async function knowledgeSearchHandler(args) {
     });
     const storageMs = performance.now() - storageStart;
     const totalMs = performance.now() - totalStart;
-    if (!data) {
+    const resultCount = Array.isArray(data?.results) ? data.results.length : 0;
+    if (!data || resultCount === 0) {
         // Phase 1: Use contentBlocks array instead of inline object
         // so we can conditionally push the trace block at content[1]
         const contentBlocks = [{
@@ -135,14 +136,14 @@ export async function knowledgeSearchHandler(args) {
     // Phase 1: Wrap in contentBlocks array for optional trace attachment
     const contentBlocks = [{
             type: "text",
-            text: `🧠 Found ${data.count} knowledge entries:\n\n${JSON.stringify(data.results || data, null, 2)}`,
+            text: `🧠 Found ${resultCount} knowledge entries:\n\n${JSON.stringify(data.results, null, 2)}`,
         }];
     // Phase 1: Attach MemoryTrace with strategy="keyword" and timing data
     if (enable_trace) {
         const trace = createMemoryTrace({
             strategy: "keyword",
             query: query || "",
-            resultCount: data.count,
+            resultCount,
             topScore: null, // keyword search doesn't produce similarity scores
             threshold: null, // keyword search has no threshold concept
             embeddingMs: 0, // no embedding needed for keyword search

package/dist/tools/handlers.js

@@ -57,7 +57,7 @@ export async function braveWebSearchCodeModeHandler(args) {
         };
     }
     // 1. Fetch raw data
-    debugLog(`Fetching web search for code mode: "${query}"`);
+    debugLog(`Fetching web search for code mode: query_chars=${query.length}`);
     const rawDataStr = await performWebSearchRaw(query, count, offset);
     const beforeSizeKB = (Buffer.byteLength(rawDataStr, 'utf8') / 1024).toFixed(1);
     // 2. Run code mode sandbox
@@ -94,7 +94,7 @@ export async function braveLocalSearchCodeModeHandler(args) {
             isError: true,
         };
     }
-    debugLog(`Fetching local search for code mode: "${query}"`);
+    debugLog(`Fetching local search for code mode: query_chars=${query.length}`);
     const rawDataStr = await performLocalSearchRaw(query, count);
     const beforeSizeKB = (Buffer.byteLength(rawDataStr, "utf8") / 1024).toFixed(1);
     debugLog("Executing local search code mode sandbox...");