prism-mcp-server 20.21.17 → 20.21.18

package/README.md

@@ -158,6 +158,14 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.21.18
+
+- Fixed: when a save was refused with `context_not_loaded`, the instructions
+  Prism installs for Claude Code, Codex and Gemini CLI forbade the one call
+  that recovers. The refusal now prints that call, `session_load_context`
+  with the same project and conversation_id, and the installed instructions
+  allow it. First-turn startup is unchanged.
+
 ## What's New in v20.21.17
 
 - Fixed: the on-device screen refused some ordinary coding requests. With a
@@ -1396,7 +1404,7 @@ Prism exposes 40+ MCP tools. The core memory loop:
 | Tool | What it does |
 |---|---|
 | `session_bootstrap` | Hook-free first-turn greeting and dashboard-configured context |
-| `session_load_context` | Explicit project reload or older-server startup fallback |
+| `session_load_context` | Explicit project reload, recovery after a `context_not_loaded` save refusal, or older-server startup fallback |
 | `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 |

package/dist/connect.js

@@ -4,6 +4,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32 as w
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { CONTEXT_RECOVERY_POLICY_LINES } from "./contextRecoveryPolicy.js";
 import { EVIDENCE_WORKFLOW_POLICY_LINES } from "./evidenceWorkflowPolicy.js";
 import { LOCAL_FIRST_POLICY_ID, LOCAL_FIRST_POLICY_LINES } from "./localFirstPolicy.js";
 export const CONNECT_HOSTS = [
@@ -44,11 +45,13 @@ const CODEX_STARTUP_BODY = [
     "reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, stop",
     "after the verbatim startup display. If `session_bootstrap` is deferred, use native tool discovery to load that",
     "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection as",
-    "a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
+    "a substitute, and do not use `session_load_context` in place of it. If discovery or invocation fails, report",
     "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
     "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This hook-free",
     "block is managed by `prism connect`; do not edit it manually.",
     "",
+    ...CONTEXT_RECOVERY_POLICY_LINES,
+    "",
     ...LOCAL_FIRST_POLICY_LINES,
     "",
     ...EVIDENCE_WORKFLOW_POLICY_LINES,
@@ -578,11 +581,13 @@ function serializeClaudeStartupBlock(newline) {
         "content. For a greeting-only prompt, stop after the verbatim startup display. If `session_bootstrap` is",
         "deferred, use native tool discovery/ToolSearch to load that",
         "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection",
-        "as a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
+        "as a substitute, and do not use `session_load_context` in place of it. If discovery or invocation fails, report",
         "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
         "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This block is",
         "managed by `prism connect`; do not edit it manually.",
         "",
+        ...CONTEXT_RECOVERY_POLICY_LINES,
+        "",
         ...LOCAL_FIRST_POLICY_LINES,
         "",
         ...EVIDENCE_WORKFLOW_POLICY_LINES,
@@ -671,10 +676,12 @@ function serializeGeminiStartupBlock(newline) {
         "reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, stop",
         "after the verbatim startup display. If `session_bootstrap` is deferred, use native tool discovery/ToolSearch",
         "to load that exact tool, then invoke it.",
-        "Do not use shell commands, file reads, subagents, or unrelated tool inspection as a substitute. Do not call",
-        "`session_load_context`. If discovery or invocation fails, report `Prism startup failure` and stop. Reuse the",
-        "`conversation_id` returned on the `<prism_session />` line for session_save_ledger, session_save_handoff, and",
-        "session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
+        "Do not use shell commands, file reads, subagents, or unrelated tool inspection as a substitute, and do not use",
+        "`session_load_context` in place of it. If discovery or invocation fails, report `Prism startup failure` and stop.",
+        "Reuse the `conversation_id` returned on the `<prism_session />` line for session_save_ledger, session_save_handoff,",
+        "and session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
+        "",
+        ...CONTEXT_RECOVERY_POLICY_LINES,
         "",
         ...LOCAL_FIRST_POLICY_LINES,
         "",

package/dist/contextRecoveryPolicy.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical context-recovery contract shared by every host instruction file.
+ *
+ * Startup is one `session_bootstrap` call. A later save can still be refused
+ * with `context_not_loaded`, and the refusal names one remedy; the host block
+ * must say the same thing instead of forbidding it. Keep this host-neutral: the
+ * Claude Code, Gemini CLI and Codex blocks splice these lines unchanged, and
+ * the server instructions, tool descriptions and refusal text state the same
+ * rule in their own words (pinned by tests/startup-recovery-contract.test.ts).
+ */
+export const CONTEXT_RECOVERY_POLICY_LINES = [
+    "## Prism context recovery",
+    "Startup is the one turn-one `session_bootstrap` call. Prism can still refuse `session_save_ledger` or",
+    "`session_save_handoff` with `context_not_loaded`: it has no record that this conversation loaded that project",
+    "(after a restart, a long idle gap, or for a project startup did not load). That is a recovery step, not a second",
+    "startup. Call `session_load_context` with the same `project` and the same `conversation_id` as the refused save",
+    "(the refusal prints the exact call; discover the tool the same way if it is deferred), then retry the save once.",
+    "Do not repeat `session_bootstrap` or print a startup display for it. If the reload or the retry fails, tell the",
+    "user; a local note is a fallback after that, never a substitute for the reload.",
+];
+export const CONTEXT_RECOVERY_POLICY_TEXT = CONTEXT_RECOVERY_POLICY_LINES.join(" ");

package/dist/server.js

@@ -361,8 +361,10 @@ export const PRISM_SERVER_INSTRUCTIONS = `Prism MCP — The Mind Palace for AI A
     `Emit no preamble. Print the complete tool result verbatim as the entire first-turn startup display, before any optional ` +
     `answer. Do not summarize, paraphrase, rename headings, reformat, or omit any returned section. Preserve its order and ` +
     `line content. For a greeting-only prompt, stop after the verbatim startup display. ` +
-    `Do not substitute session_load_context while session_bootstrap is available; use session_load_context ` +
-    `only for an explicit project reload or as an older-server fallback. ` +
+    `Do not substitute session_load_context for the startup call while session_bootstrap is available. Use ` +
+    `session_load_context to recover when a save is refused with context_not_loaded (pass that save's project ` +
+    `and conversation_id, then retry the save once; recovery is not a second startup), for an explicit project ` +
+    `reload, or as an older-server fallback. ` +
     `Use session_save_ledger to log completed work and session_save_handoff to preserve state for the next session. ` +
     `Reuse the conversation_id from session_bootstrap's <prism_session /> line for those saves and for ` +
     `session_detect_drift, the 60-minute goal-alignment drift check. Do not add the id to the visible greeting.\n\n` +

package/dist/session/sessionContext.js

@@ -84,24 +84,75 @@ export function markContextLoaded(conversationId, project, boundariesVersion) {
     s.boundariesVersion = boundariesVersion;
     lastSeenConversationId = conversationId;
 }
+const ENFORCED = " (Enforced server-side — applies to every host.)";
+/**
+ * The one remedy every refusal names, so the three variants cannot drift apart
+ * and the host instruction blocks (src/contextRecoveryPolicy.ts), the server
+ * instructions and the tool descriptions can say the same thing. A block that
+ * forbids the call a refusal asks for leaves an agent with no way forward
+ * (tests/startup-recovery-contract.test.ts pins every surface).
+ */
+const CONTEXT_RECOVERY = " To recover, call session_load_context with the same project and the same conversation_id you " +
+    "passed to this save, then retry the save once. You do not need to repeat session_bootstrap (it " +
+    "reloads only the dashboard Auto-Load projects and reprints the startup display). A recovery load " +
+    "is not a second startup. If the retry is refused too, stop and tell the user.";
 function contextNotLoadedError(project) {
     const projectNote = project
         ? " the requested project was not loaded for this conversation."
-        : "";
+        : " no context is registered for this conversation.";
+    return {
+        blocked: true,
+        error: "context_not_loaded:" + projectNote + CONTEXT_RECOVERY +
+            " This project-scoped tool needs confirmed working context to act correctly." + ENFORCED,
+    };
+}
+/**
+ * A save whose conversation_id is the empty string can never be recovered by
+ * "the same conversation_id you passed": the load handler registers nothing for
+ * an empty id. Say what is actually wrong and where the real id comes from.
+ */
+function emptyConversationIdError() {
     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.)",
+        error: "context_not_loaded: conversation_id is empty, so no context can be registered for it." +
+            " Pass this conversation's conversation_id (the value on session_bootstrap's <prism_session /> line)," +
+            " call session_load_context with that conversation_id and this project, then retry the save once." +
+            " If the retry is refused too, stop and tell the user." + ENFORCED,
     };
 }
 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.)",
+        error: "context_not_loaded: session expired (6 h TTL)." + CONTEXT_RECOVERY + ENFORCED,
+    };
+}
+/**
+ * Longest project or conversation_id a refusal echoes back. A longer value gets
+ * the remedy without a literal call: a clipped value would register the wrong
+ * project, and the retry would be refused again.
+ */
+const MAX_ECHOED_VALUE = 200;
+/**
+ * Print the literal recovery call, built from the arguments the refused save
+ * used, so "the same project and conversation_id" cannot be mistyped or
+ * replaced by a host session id. Values are JSON-escaped and echoed whole, only
+ * to the caller that just sent them; a value too long to echo gets no call.
+ */
+function withExactCall(gate, conversationId, project) {
+    if (!gate || !gate.blocked || !conversationId || !project.trim() || !gate.error.endsWith(ENFORCED)) {
+        return gate;
+    }
+    if (project.length > MAX_ECHOED_VALUE || conversationId.length > MAX_ECHOED_VALUE)
+        return gate;
+    const call = JSON.stringify({
+        project,
+        conversation_id: conversationId,
+        toolAction: "Reload context",
+        toolSummary: "Recover from context_not_loaded",
+    });
+    return {
+        blocked: true,
+        error: gate.error.slice(0, -ENFORCED.length) + ` Exact call: session_load_context(${call}).` + ENFORCED,
     };
 }
 function hashReceiptScope(kind, value) {
@@ -196,9 +247,15 @@ export function requireContextLoaded(conversationId) {
  * cross-project lookups remain fail-closed.
  */
 export async function requireContextLoadedForProject(conversationId, project) {
+    const gate = await evaluateContextGateForProject(conversationId, project);
+    return conversationId === undefined ? gate : withExactCall(gate, conversationId, project);
+}
+async function evaluateContextGateForProject(conversationId, project) {
     if (conversationId === undefined)
         return null;
-    if (!conversationId || !project.trim())
+    if (!conversationId)
+        return emptyConversationIdError();
+    if (!project.trim())
         return contextNotLoadedError(project || undefined);
     const memoryGate = requireContextLoaded(conversationId);
     const memoryState = sessions.get(conversationId);

package/dist/tools/prismInferHandler.js

@@ -256,7 +256,7 @@ export function _resetLayer1HistoryCacheForTest() { layer1HistoryCache.clear();
  *    probe and read races the time left, and no clearance is accepted after it. */
 export const LAYER1_SECOND_READ_MAX_CALLS = 48;
 export const LAYER1_SECOND_READ_DEADLINE_MS = 30_000;
-/** Reads in flight at once: ONE (owner decision 2026-09-26, after review).
+/** Reads in flight at once: ONE.
  *  Two at once made each classifier read about twice as slow and some reads
  *  abort at the classifier's first-attempt timeout (an aborted read keeps the
  *  hedge: refusal or cloud), for little clearance time gained. The per-read
@@ -1498,8 +1498,8 @@ function makeReservedRefusal(verdict, attempts, category = null, cloudWasAllowed
     });
     return new ReservedRefusalError(verdict, attempts, category, cloudWasAllowed);
 }
-/** Portal cap on the flattened conversation (`ROLE: content` lines) — see
- *  portal/src/app/api/v1/prism/inference/route.ts MAX_PROMPT_BYTES. */
+/** Server cap on the flattened conversation (`ROLE: content` lines): the
+ *  Synalux inference endpoint enforces the same limit. */
 export const CLOUD_HISTORY_CAP_BYTES = 32 * 1024;
 /** Exported for tests: the cap check must be provable without a portal. */
 export async function callSynaluxInference(prompt, maxTokens, timeoutMs, opts) {

package/dist/tools/sessionMemoryDefinitions.js

@@ -4,7 +4,10 @@ export const SESSION_SAVE_LEDGER_TOOL = {
     description: "Save an immutable session log entry to the session ledger. " +
         "Use this at the END of each work session to record what was accomplished. " +
         "The ledger is append-only — entries cannot be updated or deleted. " +
-        "This creates a permanent audit trail of all agent work sessions.",
+        "This creates a permanent audit trail of all agent work sessions. " +
+        "The save is refused with context_not_loaded until session_bootstrap or session_load_context has loaded " +
+        "this exact project for this conversation_id; on that refusal call session_load_context with the same " +
+        "project and conversation_id, then retry the save once.",
     inputSchema: {
         type: "object",
         properties: {
@@ -60,7 +63,11 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
         "Pass expected_version to enable concurrency control.\n\n" +
         "**v0.4.0 OCC**: If you received a version number from session_load_context, " +
         "/resume_session prompt, or memory resource attachment, you MUST pass it as " +
-        "expected_version to prevent overwriting another session's changes.",
+        "expected_version to prevent overwriting another session's changes.\n\n" +
+        "Pass the same conversation_id as session_save_ledger: the save is refused with context_not_loaded until " +
+        "session_bootstrap or session_load_context has loaded this exact project for it; on that refusal call " +
+        "session_load_context with the same project and conversation_id, then retry the save once, passing the " +
+        "version it shows as expected_version.",
     inputSchema: {
         type: "object",
         properties: {
@@ -101,7 +108,7 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
             },
             conversation_id: {
                 type: "string",
-                description: "Optional. Session key for this conversation (same id used in session_load_context). When provided, the server verifies that session_load_context was called for this conversation before accepting the write.",
+                description: "Optional. Session key for this conversation (same id used in session_load_context). When provided, the server verifies that session_bootstrap or session_load_context loaded this exact project for this conversation before accepting the write.",
             },
         },
         required: ["project"],
@@ -111,7 +118,9 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
 export const SESSION_LOAD_CONTEXT_TOOL = {
     name: "session_load_context",
     description: "Load session context for a project using progressive context loading. " +
-        "Use this for an explicit project reload, or as a startup fallback only when session_bootstrap is unavailable. " +
+        "Use this to recover when session_save_ledger or session_save_handoff is refused with context_not_loaded " +
+        "(pass that save's project and the same conversation_id, then retry the save once; a recovery load is not a " +
+        "second startup), for an explicit project reload, or as a startup fallback only when session_bootstrap is unavailable. " +
         "When session_bootstrap is available, do not substitute this tool for the first-turn bootstrap. " +
         "Three levels available:\n" +
         "- **quick**: Just the latest project state — keywords and open TODOs (~50 tokens)\n" +
@@ -148,7 +157,7 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
             },
             conversation_id: {
                 type: "string",
-                description: "Optional. Session key for this conversation (same id used in session_save_ledger). When provided, marks the session as context-loaded server-side so project-scoped tools can verify working context without relying on hook-based enforcement. Required on non-Claude hosts.",
+                description: "Optional for a plain read. Pass it whenever this load is meant to unlock saves (startup fallback, or recovery from context_not_loaded), using the same conversation_id as the refused or upcoming save. When provided, marks this project as context-loaded server-side so project-scoped saves are accepted; without it nothing is registered.",
             },
             prompt: {
                 type: "string",
@@ -209,7 +218,7 @@ export const SESSION_BOOTSTRAP_TOOL = {
         "before any user-facing response, passing the user's verbatim first message as {prompt: \"<first user message>\"}. " +
         "The prompt is matched against prompt_keywords ON-DEVICE to load symptom-triggered skills on turn one; it is used " +
         "for routing only and never leaves the machine. Pass {} only when there is no user message. " +
-        "Do not substitute session_load_context when this tool is available. " +
+        "Do not substitute session_load_context for this startup call. " +
         "This starts a Prism-backed conversation without host hooks. " +
         "Prism reads the dashboard's Auto-Load Projects, Context Depth (quick/standard/deep), developer name, and default role, " +
         "then returns the greeting and correctly scoped prior-session context. Emit no preamble. Print the complete tool result " +
@@ -217,7 +226,10 @@ export const SESSION_BOOTSTRAP_TOOL = {
         "headings, reformat, or omit any returned section. Preserve its order and line content. For a greeting-only prompt, " +
         "stop after the verbatim startup display. Do not guess or pass a project or depth. Prism returns a stable " +
         "conversation_id on the trailing <prism_session /> line; reuse it for session_save_ledger, session_save_handoff, and " +
-        "session_detect_drift throughout this conversation without adding it to the visible greeting.",
+        "session_detect_drift throughout this conversation without adding it to the visible greeting. " +
+        "This is the first-turn startup call only: if a later save is refused with context_not_loaded, recover with " +
+        "session_load_context for that save's project and conversation_id, then retry the save once, rather than " +
+        "repeating this startup display.",
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,

package/dist/tools/skillRouting.js

@@ -13,8 +13,8 @@
  * regexes match, and the regexes are already public. Sending the raw first
  * message bought nothing a local match could not compute — and free-tier
  * callers paid that privacy cost for literally zero routing benefit, since
- * the portal gates them to an empty set (resolve/route.ts: `tier === 'paid' ?
- * resolved : []`). Paid skill CONTENT stays gated server-side at
+ * the server returns no prompt-matched skills to the free tier. Paid skill
+ * CONTENT stays gated server-side at
  * /api/v1/prism/skill-manifest, which this change does not touch.
  *
  * Cache: portal keyed on (project,role) — no longer per-prompt, which never
@@ -464,8 +464,8 @@ export function stripQuotedEvidenceForRouting(prompt, promptKeywords = {}) {
     return units.join('');
 }
 /**
- * Verbatim port of portal resolve/route.ts prompt-matching block + the sort
- * that follows it. Parity is the whole point: any divergence silently changes
+ * Port of the server resolver's prompt-matching step and the sort that
+ * follows it. Parity is the whole point: any divergence silently changes
  * which skills load. Do not "improve" this — the reference implementation and
  * a scenario-level parity test both pin it.
  *

package/dist/utils/entitlements.js

@@ -14,9 +14,9 @@ import { debugLog } from "./logger.js";
 import { resolvePortalBaseUrl, usablePortalKey } from "./synaluxSearch.js";
 /** What a host with NO portal (unconfigured), a portal that says nothing
  *  (older deployment), or an assumed-free fallback gets: OFF. Multi-turn
- *  needs a Synalux account, and a free one is enough (owner decision
- *  2026-09-26): the answer check it depends on is served per account. The
- *  caps here are what an account gets when the portal omits them. */
+ *  needs a Synalux account, and a free one is enough: the answer check it
+ *  depends on is served per account. The caps here are what an account gets
+ *  when the portal omits them. */
 export const DEFAULT_MULTI_TURN = { enabled: false, max_turns: 12, max_chars: 32_000 };
 /** Structural ceiling no plan can exceed: the portal's own inference route
  *  takes at most 50 messages INCLUDING the current turn appended on
@@ -38,9 +38,8 @@ export function multiTurnPolicy(ent) {
 }
 // ── Free-tier defaults (no auth) ──────────────────────────────────
 /** No account: everything local, with no cap on the model the user's own
- *  machine can run (owner decision 2026-09-26). Anything that needs Synalux
- *  (multi-turn with the answer check, cloud answers) needs an account; a free
- *  one is enough. */
+ *  machine can run. Anything that needs Synalux (multi-turn with the answer
+ *  check, cloud answers) needs an account; a free one is enough. */
 export const FREE_ENTITLEMENTS = {
     plan: "free",
     model_ceiling: "27b",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.21.17",
+  "version": "20.21.18",
   "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",
@@ -22,7 +22,7 @@
     "prebuild": "npm run clean",
     "build": "tsc && npm run chmod-bins",
     "chmod-bins": "node -e \"['dist/cli.js','dist/server.js','dist/utils/universalImporter.js'].forEach(f => { try { require('fs').chmodSync(f, 0o755); } catch (e) { console.warn('chmod skipped', f, e.message); } })\"",
-    "prepublishOnly": "node scripts/check-no-private-content.mjs && node scripts/check-publish-clean.mjs && npm run build",
+    "prepublishOnly": "node scripts/check-no-private-content.mjs && node scripts/private-identifier-scan.mjs && node scripts/check-publish-clean.mjs && npm run build",
     "lint:dashboard": "node scripts/lint-dashboard-es5.cjs",
     "check:lockfile": "node scripts/check-lockfile-drift.mjs",
     "start": "node dist/server.js",
@@ -79,7 +79,7 @@
   "overrides": {
     "@hono/node-server": "^2.0.5",
     "body-parser": "^2.3.0",
-    "fast-uri": "^3.1.6",
+    "fast-uri": "^3.1.8",
     "hono": "^4.13.5",
     "ip-address": "^10.2.0",
     "protobufjs": "^7.6.5",