prism-mcp-server 19.2.9 → 19.3.0

package/dist/boundaries/__tests__/boundaries.test.js

@@ -0,0 +1,58 @@
+/**
+ * boundaries.ts unit tests
+ *
+ * Verifies structural invariants of the operating boundaries export:
+ * - BOUNDARIES_VERSION is present and non-empty
+ * - BOUNDARIES_TEXT covers the five required sections
+ * - Safety-critical concepts are mentioned (so a future edit doesn't silently
+ *   remove them without also bumping the version and updating tests)
+ */
+import { describe, it, expect } from "vitest";
+import { BOUNDARIES_VERSION, BOUNDARIES_TEXT } from "../../boundaries/boundaries.js";
+describe("BOUNDARIES_VERSION", () => {
+    it("is a non-empty string", () => {
+        expect(typeof BOUNDARIES_VERSION).toBe("string");
+        expect(BOUNDARIES_VERSION.length).toBeGreaterThan(0);
+    });
+});
+describe("BOUNDARIES_TEXT structure", () => {
+    it("is a non-empty string", () => {
+        expect(typeof BOUNDARIES_TEXT).toBe("string");
+        expect(BOUNDARIES_TEXT.length).toBeGreaterThan(100);
+    });
+    it("has no leading or trailing whitespace (trim() was applied)", () => {
+        expect(BOUNDARIES_TEXT).toBe(BOUNDARIES_TEXT.trim());
+    });
+    it("contains a safety gates section", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/safety gates/i);
+    });
+    it("contains a BCBA clinical standards section", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/bcba/i);
+    });
+    it("contains a correctness gates section", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/correctness gates/i);
+    });
+    it("contains an inference routing section", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/inference routing/i);
+    });
+    it("contains a host note section", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/host note/i);
+    });
+    it("asserts that enforcement is server-side (not instruction-based)", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/server.*enforc|enforc.*server/i);
+    });
+    it("references the fail-closed rule for reserved + no-cloud", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/fail.?closed|refused/i);
+    });
+    it("states AAC access is never restricted as a consequence", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/AAC access is never restricted/i);
+    });
+    it("references restraint as a RESERVED category", () => {
+        expect(BOUNDARIES_TEXT).toMatch(/restraint/i);
+        expect(BOUNDARIES_TEXT).toMatch(/RESERVED/i);
+    });
+    it("mentions session_save_ledger and session_save_handoff in correctness section", () => {
+        expect(BOUNDARIES_TEXT).toContain("session_save_ledger");
+        expect(BOUNDARIES_TEXT).toContain("session_save_handoff");
+    });
+});

package/dist/boundaries/boundaries.js

@@ -0,0 +1,48 @@
+/**
+ * src/boundaries/boundaries.ts
+ *
+ * Operating boundaries delivered in every session_load_context result.
+ *
+ * These boundaries are enforced server-side in code (prism_infer safety
+ * gates, requireContextLoaded). This text is belt-and-suspenders for a
+ * cooperative host — it cannot be removed to bypass enforcement.
+ *
+ * Update BOUNDARIES_VERSION any time the text changes so session drift
+ * detection can flag stale sessions.
+ */
+export const BOUNDARIES_VERSION = "1";
+export const BOUNDARIES_TEXT = `
+## OPERATING BOUNDARIES — server-enforced, shown for transparency
+
+### 1. Safety gates (unconditional — run before and after every model call)
+- Crisis/self-harm inputs are intercepted before reaching any model.
+- BCBA reserved categories (restraint, seclusion, physical management, dosing) route
+  to cloud or refuse; they NEVER generate locally. Fail-closed: if cloud is unavailable
+  and the prompt is reserved, the request is refused — never downgraded to local.
+- Dangerous output (restraint instructions, overdose methods, self-harm guidance)
+  is blocked regardless of which host requested it.
+
+### 2. BCBA clinical standards
+- Apply ABA principles grounded in the current BACB Ethics Code and Task List (5th Ed).
+- Use evidence-based interventions: FCT, DRA, DRO, NCR, antecedent modifications.
+- Least restrictive, dignity-preserving, trauma-informed procedures always.
+- AAC access is never restricted as a consequence.
+- Physical management / restraint / seclusion are RESERVED — cloud only, with audit.
+
+### 3. Correctness gates (project-scoped write tools)
+- session_save_ledger and session_save_handoff require a loaded project context
+  (conversation_id that called session_load_context successfully).
+- This prevents a non-Claude host from writing state it hasn't confirmed.
+
+### 4. Inference routing
+- Local inference (Ollama) runs ONLY for OBVIOUS_NOT_RESERVED prompts (Layer 1 verdict).
+- RESERVED / UNCERTAIN / classifier errors escalate to cloud. Never downgrade reserved
+  prompts to local — that is exactly what Layer 1 flagged.
+- Cloud must never be reached directly by a host; all cloud inference routes through
+  the Synalux portal for billing, tier-gating, and HIPAA audit.
+
+### 5. Host note
+These boundaries are enforced by the server. They apply identically whether the host
+is Claude Code, Gemini, an autonomous script, or a cron job. A host that does not read
+this text still cannot bypass the enforcement — it is in code, not instructions.
+`.trim();

package/dist/session/__tests__/sessionContext.test.js

@@ -0,0 +1,133 @@
+/**
+ * sessionContext.ts unit tests
+ *
+ * Covers: markContextLoaded, requireContextLoaded, noteInferenceForSession,
+ * getSessionState, TTL eviction, and fail-closed behaviour for unknown sessions.
+ *
+ * The module uses in-process Map state. Each test imports a fresh module instance
+ * via vi.resetModules() + dynamic re-import so tests are isolated without needing
+ * an exported reset function.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+// Reset module registry before each test so the in-memory Map starts empty.
+let markContextLoaded;
+let requireContextLoaded;
+let noteInferenceForSession;
+let getSessionState;
+beforeEach(async () => {
+    vi.resetModules();
+    const mod = await import("../../session/sessionContext.js");
+    markContextLoaded = mod.markContextLoaded;
+    requireContextLoaded = mod.requireContextLoaded;
+    noteInferenceForSession = mod.noteInferenceForSession;
+    getSessionState = mod.getSessionState;
+});
+describe("requireContextLoaded — fail-closed defaults", () => {
+    it("blocks an unknown conversation (never seen)", () => {
+        const result = requireContextLoaded("never-seen-id");
+        expect(result).not.toBeNull();
+        expect(result.blocked).toBe(true);
+        if (result && result.blocked)
+            expect(result.error).toContain("context_not_loaded");
+    });
+    it("allows (returns null) when conversation_id is undefined — gate is opt-in", () => {
+        // Callers without a conversation_id (auto-push hosts, resource readers,
+        // legacy clients) are not gated — they use the session-agnostic interface.
+        const result = requireContextLoaded(undefined);
+        expect(result).toBeNull();
+    });
+    it("blocks (hard) when conversation_id is empty string — empty string is not opt-in bypass", () => {
+        // "" is not the same as undefined. An empty string means the caller explicitly
+        // provided a conversation_id but it's invalid. The gate should block, not bypass.
+        const result = requireContextLoaded("");
+        expect(result).not.toBeNull();
+        expect(result.blocked).toBe(true);
+        if (result && result.blocked)
+            expect(result.error).toContain("context_not_loaded");
+    });
+    it("blocks a session by unknown id even if noteInference was called for it", () => {
+        // noteInferenceForSession no longer creates stubs, so an unregistered id
+        // is still unknown to the gate.
+        noteInferenceForSession("conv-telemetry-only", { backend: "local", usedCloud: false });
+        const result = requireContextLoaded("conv-telemetry-only");
+        expect(result).not.toBeNull();
+        expect(result.blocked).toBe(true);
+    });
+});
+describe("markContextLoaded → requireContextLoaded lifecycle", () => {
+    it("returns null (pass) after markContextLoaded is called", () => {
+        markContextLoaded("conv-abc", "project-x", "1");
+        expect(requireContextLoaded("conv-abc")).toBeNull();
+    });
+    it("records project and boundariesVersion on the session", () => {
+        markContextLoaded("conv-meta", "my-project", "42");
+        const state = getSessionState("conv-meta");
+        expect(state).not.toBeNull();
+        expect(state.project).toBe("my-project");
+        expect(state.boundariesVersion).toBe("42");
+        expect(state.contextLoaded).toBe(true);
+    });
+    it("is idempotent — calling twice does not break state", () => {
+        // Use the actual BOUNDARIES_VERSION ("1") so no drift warning fires.
+        markContextLoaded("conv-idem", "proj", "1");
+        markContextLoaded("conv-idem", "proj-updated", "1");
+        const state = getSessionState("conv-idem");
+        expect(state.project).toBe("proj-updated");
+        expect(state.boundariesVersion).toBe("1");
+        expect(requireContextLoaded("conv-idem")).toBeNull();
+    });
+    it("isolates sessions — loading one does not unblock another", () => {
+        markContextLoaded("conv-A", "proj", "1");
+        expect(requireContextLoaded("conv-A")).toBeNull();
+        expect(requireContextLoaded("conv-B")).not.toBeNull();
+    });
+});
+describe("noteInferenceForSession", () => {
+    it("increments inferenceCalls on every call", () => {
+        markContextLoaded("conv-inf", "proj", "1");
+        noteInferenceForSession("conv-inf", { backend: "local", usedCloud: false });
+        noteInferenceForSession("conv-inf", { backend: "local", usedCloud: false });
+        const state = getSessionState("conv-inf");
+        expect(state.inferenceCalls).toBe(2);
+    });
+    it("increments usedCloudCalls only for cloud calls", () => {
+        markContextLoaded("conv-cloud", "proj", "1");
+        noteInferenceForSession("conv-cloud", { backend: "cloud", usedCloud: true });
+        noteInferenceForSession("conv-cloud", { backend: "local", usedCloud: false });
+        const state = getSessionState("conv-cloud");
+        expect(state.inferenceCalls).toBe(2);
+        expect(state.usedCloudCalls).toBe(1);
+    });
+    it("does NOT create a ghost stub for an unregistered session — only updates existing sessions", () => {
+        // noteInferenceForSession used to call getOrInit, creating stub entries
+        // with contextLoaded=false for every conversation_id that infers.
+        // Ghost stubs accumulate in the LRU and crowd out real sessions.
+        // The fix: no-op when the session doesn't exist yet.
+        noteInferenceForSession("conv-new-via-note", { backend: "local", usedCloud: false });
+        expect(getSessionState("conv-new-via-note")).toBeNull();
+    });
+});
+describe("getSessionState", () => {
+    it("returns null for an unknown session", () => {
+        expect(getSessionState("does-not-exist")).toBeNull();
+    });
+    it("returns the current state object for a known session", () => {
+        markContextLoaded("conv-get", "proj", "1");
+        const state = getSessionState("conv-get");
+        expect(state).not.toBeNull();
+        expect(state.contextLoaded).toBe(true);
+    });
+});
+describe("lastSeen update", () => {
+    it("updates lastSeen on every requireContextLoaded call", async () => {
+        markContextLoaded("conv-ts", "proj", "1");
+        const before = getSessionState("conv-ts").lastSeen;
+        // Advance time by mocking Date.now via vi.useFakeTimers
+        vi.useFakeTimers();
+        vi.advanceTimersByTime(5000);
+        requireContextLoaded("conv-ts");
+        const after = getSessionState("conv-ts").lastSeen;
+        vi.useRealTimers();
+        expect(after).toBeGreaterThanOrEqual(before);
+    });
+});

package/dist/session/sessionContext.js

@@ -0,0 +1,165 @@
+/**
+ * src/session/sessionContext.ts
+ *
+ * Server-side session state, keyed on conversation_id (the same id threaded
+ * through session_load_context / session_save_ledger / prism_infer).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * On Claude Code, "call session_load_context first" was enforced by the
+ * guard_on_submit hook injecting a MANDATORY STARTUP reminder, and by
+ * mark_loaded.py flipping a pending flag. Neither mechanism runs on a
+ * non-Claude host (Gemini, autonomous script, cron job).
+ *
+ * This module moves that state server-side so any host that calls
+ * session_load_context gets its conversation marked as loaded — regardless
+ * of whether it ran the hook.
+ *
+ * TWO DELIBERATE BOUNDARIES
+ * -------------------------
+ * 1. This is NOT a safety mechanism. prism_infer's input/output safety gates
+ *    run unconditionally before and after every model call. A host that never
+ *    loads context still cannot reach an un-gated model.
+ *
+ * 2. requireContextLoaded gates only CORRECTNESS-requiring, project-scoped
+ *    actions (save_ledger, save_handoff) — tools that act on a specific project
+ *    and produce wrong results if the agent hasn't confirmed its working context.
+ *    Do NOT gate prism_infer on this; a host that never loads context must still
+ *    be able to run inference (safety is already unconditional there).
+ *
+ * Fail-closed: an unknown or expired conversation_id → context not loaded.
+ */
+import { BOUNDARIES_VERSION as CURRENT_BOUNDARIES_VERSION } from "../boundaries/boundaries.js";
+const SESSION_TTL_MS = 6 * 60 * 60 * 1000; // 6 h — conversation-scoped
+const MAX_SESSIONS = 10_000;
+// JS Map preserves insertion order. Touch-on-access (delete + re-insert) keeps
+// the Map ordered LRU-last so eviction can pop the first key in O(1).
+const sessions = new Map();
+function touch(conversationId, s) {
+    // Re-insert to move this entry to the end of insertion order (most-recently-used).
+    sessions.delete(conversationId);
+    s.lastSeen = Date.now();
+    sessions.set(conversationId, s);
+}
+function evictStale() {
+    const cutoff = Date.now() - SESSION_TTL_MS;
+    for (const [k, v] of sessions) {
+        if (v.lastSeen < cutoff)
+            sessions.delete(k);
+    }
+    // Hard cap: evict least-recently-used entries (the ones at the front of the Map,
+    // because touch() always re-inserts accessed entries at the back).
+    // Guard: use !== undefined (not truthy) so an empty-string key doesn't stall the loop.
+    while (sessions.size > MAX_SESSIONS) {
+        const oldest = sessions.keys().next().value;
+        if (oldest !== undefined)
+            sessions.delete(oldest);
+        else
+            break;
+    }
+}
+function getOrInit(conversationId) {
+    let s = sessions.get(conversationId);
+    if (!s) {
+        s = {
+            contextLoaded: false,
+            boundariesVersion: null,
+            project: null,
+            lastSeen: Date.now(),
+            inferenceCalls: 0,
+            usedCloudCalls: 0,
+        };
+        sessions.set(conversationId, s);
+        if (sessions.size > MAX_SESSIONS)
+            evictStale();
+        return s;
+    }
+    // Touch on access — maintains O(1) LRU eviction order in the Map.
+    touch(conversationId, s);
+    return s;
+}
+/**
+ * Called by sessionLoadContextHandler after it successfully assembles context.
+ * Server-side equivalent of mark_loaded.py — fires from the tool handler
+ * itself, so it works for every host, not just Claude Code.
+ */
+export function markContextLoaded(conversationId, project, boundariesVersion) {
+    const s = getOrInit(conversationId);
+    s.contextLoaded = true;
+    s.project = project;
+    s.boundariesVersion = boundariesVersion;
+}
+/**
+ * Soft gate for handlers that need project context to be CORRECT (not safe).
+ *
+ * Returns:
+ *   null                          — OK, proceed
+ *   { blocked: true, error }      — hard block; return the error verbatim to the model
+ *   { blocked: false, warning }   — proceed, but prepend the warning to the response
+ *                                   (emitted when the session was loaded with an older
+ *                                   BOUNDARIES_VERSION — the host should reload context)
+ *
+ * Fail-closed: unknown or expired session → hard block.
+ * Does NOT gate safety. Do not call this from prism_infer.
+ */
+export function requireContextLoaded(conversationId) {
+    // No conversation_id (undefined) means the caller is using the session-agnostic
+    // interface (auto-push host, resource reader, or legacy client). Allow through —
+    // the gate is opt-in when a conversation_id is explicitly provided.
+    // NOTE: use === undefined, not !conversationId, so that an empty-string ""
+    // conversation_id still falls through to the sessions.get() lookup and gets
+    // blocked (hard block) instead of silently bypassing the gate.
+    if (conversationId === undefined)
+        return null;
+    const s = sessions.get(conversationId);
+    // #9: Enforce TTL on reads. A session loaded 6 h+ ago is treated as expired
+    // 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_load_context(project, conversation_id) again to reload context. " +
+                "(Enforced server-side — applies to every host.)",
+        };
+    }
+    if (!s || !s.contextLoaded) {
+        return {
+            blocked: true,
+            error: "context_not_loaded: call 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.)",
+        };
+    }
+    // Touch on valid read — maintains LRU order.
+    touch(conversationId, s);
+    // #15: Soft warning when this session was loaded with an older BOUNDARIES_VERSION.
+    // The server may have been updated mid-session. Don't block writes — that would
+    // be disruptive — but advise the host to reload context to pick up the new boundaries.
+    if (s.boundariesVersion !== null && s.boundariesVersion !== CURRENT_BOUNDARIES_VERSION) {
+        return {
+            blocked: false,
+            warning: `[advisory] Operating boundaries updated (session loaded v${s.boundariesVersion}, ` +
+                `server now at v${CURRENT_BOUNDARIES_VERSION}). Call session_load_context again ` +
+                `to receive the latest boundaries. Proceeding with current write.`,
+        };
+    }
+    return null;
+}
+/** 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
+    // conversations that never called session_load_context. Ghost stubs would
+    // accumulate in the LRU and crowd out legitimate registered sessions.
+    const s = sessions.get(conversationId);
+    if (!s)
+        return;
+    s.inferenceCalls += 1;
+    if (info.usedCloud)
+        s.usedCloudCalls += 1;
+    touch(conversationId, s);
+}
+/** For metrics / session health checks. */
+export function getSessionState(conversationId) {
+    return sessions.get(conversationId) ?? null;
+}

package/dist/tools/__tests__/ledgerHandlers.test.js

@@ -121,6 +121,19 @@ vi.mock("../../../src/utils/cognitiveMemory.js", () => ({
     computeEffectiveImportance: vi.fn((imp) => imp),
     recordMemoryAccess: vi.fn(),
 }));
+// Session context gate — default to "pass" (null) so existing tests are unaffected.
+// Gate-blocking behaviour is tested explicitly in the "context gate" sections below.
+vi.mock("../../../src/session/sessionContext.js", () => ({
+    markContextLoaded: vi.fn(),
+    requireContextLoaded: vi.fn(() => null),
+    noteInferenceForSession: vi.fn(),
+    getSessionState: vi.fn(() => null),
+}));
+// Boundaries — return minimal stubs so load-context tests don't depend on exact text.
+vi.mock("../../../src/boundaries/boundaries.js", () => ({
+    BOUNDARIES_VERSION: "test",
+    BOUNDARIES_TEXT: "# BOUNDARIES STUB",
+}));
 vi.mock("../../../src/tools/commonHelpers.js", () => ({
     redactSettings: vi.fn((s) => s),
     toMarkdown: vi.fn(() => "# Markdown Export"),
@@ -133,6 +146,7 @@ vi.mock("../../../src/utils/vaultExporter.js", () => ({
 // ======================================================================
 import { getStorage } from "../../../src/storage/index.js";
 import { getSetting, getAllSettings } from "../../../src/storage/configStorage.js";
+import { requireContextLoaded, markContextLoaded } from "../../../src/session/sessionContext.js";
 import { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler, memoryHistoryHandler, sessionSaveImageHandler, sessionViewImageHandler, sanitizeMemoryInput, } from "../../../src/tools/ledgerHandlers.js";
 const mockGetStorage = vi.mocked(getStorage);
 const mockGetSetting = vi.mocked(getSetting);
@@ -329,6 +343,36 @@ describe("ledgerHandlers", () => {
             storage.saveLedger.mockRejectedValue(new Error("DB write failed"));
             await expect(sessionSaveLedgerHandler(validArgs)).rejects.toThrow("DB write failed");
         });
+        // --- Context gate ---
+        it("blocks save and returns structured error when context not loaded", async () => {
+            vi.mocked(requireContextLoaded).mockReturnValueOnce({
+                blocked: true,
+                error: "context_not_loaded: call session_load_context first.",
+            });
+            const result = await sessionSaveLedgerHandler(validArgs);
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("context_not_loaded");
+            expect(storage.saveLedger).not.toHaveBeenCalled();
+        });
+        it("passes through to storage when context is loaded (gate returns null)", async () => {
+            vi.mocked(requireContextLoaded).mockReturnValueOnce(null);
+            const result = await sessionSaveLedgerHandler(validArgs);
+            expect(result.isError).toBe(false);
+            expect(storage.saveLedger).toHaveBeenCalledTimes(1);
+        });
+        it("proceeds and prepends warning when gate returns { blocked: false, warning } (version drift)", async () => {
+            vi.mocked(requireContextLoaded).mockReturnValueOnce({
+                blocked: false,
+                warning: "[advisory] Operating boundaries updated. Call session_load_context again.",
+            });
+            const result = await sessionSaveLedgerHandler(validArgs);
+            // Must NOT block — write proceeds
+            expect(result.isError).toBe(false);
+            expect(storage.saveLedger).toHaveBeenCalledTimes(1);
+            // Warning is prepended to the success text
+            expect(result.content[0].text).toContain("[advisory] Operating boundaries updated");
+            expect(result.content[0].text).toContain("✅ Session ledger saved");
+        });
     });
     // ====================================================================
     // 3. sessionLoadContextHandler
@@ -473,6 +517,24 @@ describe("ledgerHandlers", () => {
             storage.loadContext.mockRejectedValue(new Error("Connection timeout"));
             await expect(sessionLoadContextHandler(validArgs)).rejects.toThrow("Connection timeout");
         });
+        // --- conversation_id / markContextLoaded ---
+        it("calls markContextLoaded when conversation_id is provided", async () => {
+            storage.loadContext.mockResolvedValue(null);
+            await sessionLoadContextHandler({ project: "test-project", conversation_id: "conv-xyz" });
+            expect(vi.mocked(markContextLoaded)).toHaveBeenCalledWith("conv-xyz", "test-project", "test");
+        });
+        it("does not call markContextLoaded when conversation_id is absent", async () => {
+            storage.loadContext.mockResolvedValue(null);
+            await sessionLoadContextHandler({ project: "test-project" });
+            expect(vi.mocked(markContextLoaded)).not.toHaveBeenCalled();
+        });
+        it("prepends BOUNDARIES header to every response", async () => {
+            storage.loadContext.mockResolvedValue(null);
+            const result = await sessionLoadContextHandler(validArgs);
+            const text = result.content[0].text;
+            expect(text).toContain("OPERATING BOUNDARIES");
+            expect(text).toContain("BOUNDARIES STUB");
+        });
     });
     // ====================================================================
     // 4. sessionSaveHandoffHandler
@@ -606,6 +668,38 @@ describe("ledgerHandlers", () => {
             storage.saveHandoff.mockRejectedValue(new Error("Write conflict"));
             await expect(sessionSaveHandoffHandler(validArgs)).rejects.toThrow("Write conflict");
         });
+        // --- Context gate ---
+        it("blocks handoff save and returns structured error when context not loaded", async () => {
+            vi.mocked(requireContextLoaded).mockReturnValueOnce({
+                blocked: true,
+                error: "context_not_loaded: call session_load_context first.",
+            });
+            const result = await sessionSaveHandoffHandler(validArgs);
+            expect(result.isError).toBe(true);
+            expect(result.content[0].text).toContain("context_not_loaded");
+            expect(storage.saveHandoff).not.toHaveBeenCalled();
+        });
+        it("passes through to storage when context is loaded (gate returns null)", async () => {
+            storage.saveHandoff.mockResolvedValue({ status: "created", version: 1 });
+            vi.mocked(requireContextLoaded).mockReturnValueOnce(null);
+            const result = await sessionSaveHandoffHandler(validArgs);
+            expect(result.isError).toBe(false);
+            expect(storage.saveHandoff).toHaveBeenCalledTimes(1);
+        });
+        it("proceeds and prepends warning when gate returns { blocked: false, warning } (version drift)", async () => {
+            storage.saveHandoff.mockResolvedValue({ status: "created", version: 1 });
+            vi.mocked(requireContextLoaded).mockReturnValueOnce({
+                blocked: false,
+                warning: "[advisory] Operating boundaries updated. Call session_load_context again.",
+            });
+            const result = await sessionSaveHandoffHandler(validArgs);
+            // Must NOT block — write proceeds
+            expect(result.isError).toBe(false);
+            expect(storage.saveHandoff).toHaveBeenCalledTimes(1);
+            // Warning is prepended to the success text
+            expect(result.content[0].text).toContain("[advisory] Operating boundaries updated");
+            expect(result.content[0].text).toContain("✅ Handoff");
+        });
     });
     // ====================================================================
     // 5. memoryHistoryHandler

package/dist/tools/ledgerHandlers.js

@@ -94,6 +94,19 @@ export async function sessionSaveLedgerHandler(args) {
     if (!isSessionSaveLedgerArgs(args)) {
         throw new Error("Invalid arguments for session_save_ledger");
     }
+    // Host-agnostic context gate: any host that calls save_ledger without first
+    // loading context (on any host type) gets a structured error instead of a
+    // silently wrong write. Does NOT gate safety — prism_infer handles that.
+    let _saveLedgerGateWarning;
+    {
+        const { requireContextLoaded } = await import("../session/sessionContext.js");
+        const gate = requireContextLoaded(args.conversation_id);
+        if (gate !== null && gate.blocked) {
+            return { content: [{ type: "text", text: gate.error }], isError: true };
+        }
+        if (gate !== null && !gate.blocked)
+            _saveLedgerGateWarning = gate.warning;
+    }
     // SECURITY: Sanitize all text fields to prevent stored prompt injection
     let project = args.project;
     const conversation_id = args.conversation_id;
@@ -234,7 +247,8 @@ export async function sessionSaveLedgerHandler(args) {
     return {
         content: [{
                 type: "text",
-                text: `✅ Session ledger saved for project "${project}"\n` +
+                text: (_saveLedgerGateWarning ? `⚠️ ${_saveLedgerGateWarning}\n\n` : "") +
+                    `✅ Session ledger saved for project "${project}"\n` +
                     `Summary: ${summary}\n` +
                     (todos?.length ? `TODOs: ${todos.length} items\n` : "") +
                     (files_changed?.length ? `Files changed: ${files_changed.length}\n` : "") +
@@ -250,6 +264,16 @@ export async function sessionSaveHandoffHandler(args, server) {
     if (!isSessionSaveHandoffArgs(args)) {
         throw new Error("Invalid arguments for session_save_handoff");
     }
+    let _saveHandoffGateWarning;
+    {
+        const { requireContextLoaded } = await import("../session/sessionContext.js");
+        const gate = requireContextLoaded(args.conversation_id);
+        if (gate !== null && gate.blocked) {
+            return { content: [{ type: "text", text: gate.error }], isError: true };
+        }
+        if (gate !== null && !gate.blocked)
+            _saveHandoffGateWarning = gate.warning;
+    }
     // SECURITY: Sanitize all text fields to prevent stored prompt injection
     const project = args.project;
     const expected_version = args.expected_version;
@@ -553,22 +577,23 @@ export async function sessionSaveHandoffHandler(args, server) {
     }
     const metricsBlock = formatInferenceMetrics();
     // Build response text based on whether a CRDT merge occurred
-    const responseText = isMerged
-        ? `🔄 Auto-merged conflict for "${project}" (v${expected_version} → v${newVersion})\n` +
-            `Strategy: ${JSON.stringify(mergeStrategy)}\n` +
-            (last_summary ? `Summary: ${last_summary}\n` : "") +
-            metricsBlock +
-            `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
-            `to maintain concurrency control.`
-        : `✅ Handoff ${data.status || "saved"} for project "${project}" ` +
-            `(version: ${newVersion})\n` +
-            (last_summary ? `Last summary: ${last_summary}\n` : "") +
-            (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
-            (active_branch ? `Active branch: ${active_branch}\n` : "") +
-            `📊 Embedding generation queued for semantic search.\n` +
-            metricsBlock +
-            `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
-            `to maintain concurrency control.`;
+    const responseText = (_saveHandoffGateWarning ? `⚠️ ${_saveHandoffGateWarning}\n\n` : "") +
+        (isMerged
+            ? `🔄 Auto-merged conflict for "${project}" (v${expected_version} → v${newVersion})\n` +
+                `Strategy: ${JSON.stringify(mergeStrategy)}\n` +
+                (last_summary ? `Summary: ${last_summary}\n` : "") +
+                metricsBlock +
+                `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
+                `to maintain concurrency control.`
+            : `✅ Handoff ${data.status || "saved"} for project "${project}" ` +
+                `(version: ${newVersion})\n` +
+                (last_summary ? `Last summary: ${last_summary}\n` : "") +
+                (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
+                (active_branch ? `Active branch: ${active_branch}\n` : "") +
+                `📊 Embedding generation queued for semantic search.\n` +
+                metricsBlock +
+                `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
+                `to maintain concurrency control.`);
     return {
         content: [{
                 type: "text",
@@ -587,7 +612,7 @@ export async function sessionLoadContextHandler(args) {
     if (getInferenceSnapshot().totalCalls === 0) {
         resetInferenceMetrics();
     }
-    const { project, level = "standard", role } = args;
+    const { project, level = "standard", role, conversation_id: convId } = args;
     // T6 fix: explicit Number() coercion prevents string "2000" from later concatenating instead of adding
     const _maxTokensArg = Number(args.max_tokens);
     const _maxTokensSetting = parseInt(await getSetting("max_tokens", "0"), 10);
@@ -625,10 +650,21 @@ export async function sessionLoadContextHandler(args) {
         catch {
             debugLog(`[session_load_context] Fresh project skill injection failed — continuing without`);
         }
+        if (convId) {
+            const { markContextLoaded } = await import("../session/sessionContext.js");
+            const { BOUNDARIES_VERSION } = await import("../boundaries/boundaries.js");
+            markContextLoaded(convId, project, BOUNDARIES_VERSION);
+        }
+        const { BOUNDARIES_TEXT: BT0, BOUNDARIES_VERSION: BV0 } = await import("../boundaries/boundaries.js");
+        const boundariesHeader0 = `# OPERATING BOUNDARIES (v${BV0}) — enforced server-side, shown for transparency\n` +
+            BT0 + "\n\n" +
+            `# NOTE FOR NON-CLAUDE HOSTS: these boundaries run in code on every prism_infer call.\n` +
+            `# Reserved-category requests are routed to cloud or refused — not by instruction.\n\n---\n\n`;
         return {
             content: [{
                     type: "text",
-                    text: `No session context found for project "${project}" at level ${level}.\n` +
+                    text: boundariesHeader0 +
+                        `No session context found for project "${project}" at level ${level}.\n` +
                         `This project has no previous session history. Starting fresh.` +
                         freshSkillBlock,
                 }],
@@ -1077,14 +1113,34 @@ export async function sessionLoadContextHandler(args) {
         if (droppedSections.length > 0) {
             responseText += `\n\n[ℹ️ Sections omitted to fit token budget (${maxTokens} tokens): ${droppedSections.join(", ")}. Skills and behavioral rules were preserved.]`;
         }
+        if (convId) {
+            const { markContextLoaded } = await import("../session/sessionContext.js");
+            const { BOUNDARIES_VERSION } = await import("../boundaries/boundaries.js");
+            markContextLoaded(convId, project, BOUNDARIES_VERSION);
+        }
+        const { BOUNDARIES_TEXT, BOUNDARIES_VERSION: BV } = await import("../boundaries/boundaries.js");
+        const boundariesHeader = `# OPERATING BOUNDARIES (v${BV}) — enforced server-side, shown for transparency\n` +
+            BOUNDARIES_TEXT + "\n\n" +
+            `# NOTE FOR NON-CLAUDE HOSTS: these boundaries run in code on every prism_infer call.\n` +
+            `# Reserved-category requests are routed to cloud or refused — not by instruction.\n\n---\n\n`;
         return {
-            content: [{ type: "text", text: responseText + MEMORY_BOUNDARY_SUFFIX }],
+            content: [{ type: "text", text: boundariesHeader + responseText + MEMORY_BOUNDARY_SUFFIX }],
             isError: false,
         };
     }
     let responseText = criticalPrefix + lowerPriority + historySection;
+    if (convId) {
+        const { markContextLoaded } = await import("../session/sessionContext.js");
+        const { BOUNDARIES_VERSION } = await import("../boundaries/boundaries.js");
+        markContextLoaded(convId, project, BOUNDARIES_VERSION);
+    }
+    const { BOUNDARIES_TEXT, BOUNDARIES_VERSION: BV2 } = await import("../boundaries/boundaries.js");
+    const boundariesHeader2 = `# OPERATING BOUNDARIES (v${BV2}) — enforced server-side, shown for transparency\n` +
+        BOUNDARIES_TEXT + "\n\n" +
+        `# NOTE FOR NON-CLAUDE HOSTS: these boundaries run in code on every prism_infer call.\n` +
+        `# Reserved-category requests are routed to cloud or refused — not by instruction.\n\n---\n\n`;
     return {
-        content: [{ type: "text", text: responseText + MEMORY_BOUNDARY_SUFFIX }],
+        content: [{ type: "text", text: boundariesHeader2 + responseText + MEMORY_BOUNDARY_SUFFIX }],
         isError: false,
     };
 }

package/dist/tools/prismInferHandler.js

@@ -149,6 +149,8 @@ export function isPrismInferArgs(args) {
         return false;
     if (a.think !== undefined && typeof a.think !== "boolean")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     if (a.verify !== undefined && typeof a.verify !== "boolean")
         return false;
     if (a.verifier_model !== undefined && typeof a.verifier_model !== "string")
@@ -665,6 +667,17 @@ export async function prismInferHandler(args) {
         // T4: pass prompt_text so recordInference computes submittedEst via
         // estimateTokens() — critical for cloud path where prompt_tokens is unset.
         recordInference({ ...result, prompt_text: args.prompt });
+        // Best-effort session telemetry — records that inference ran for this
+        // conversation. Never affects routing or safety decisions.
+        const _convId = args.conversation_id;
+        if (_convId && result.backend !== "safety_gate") {
+            import("../session/sessionContext.js").then(({ noteInferenceForSession }) => {
+                noteInferenceForSession(_convId, {
+                    backend: result.backend,
+                    usedCloud: result.used_cloud,
+                });
+            }).catch(() => { });
+        }
         // Best-effort portal forwarding (independent analytics stream).
         // safety_gate excluded — logging crisis filter triggers is a HIPAA concern.
         if (result.backend !== "safety_gate") {

package/dist/tools/sessionMemoryDefinitions.js

@@ -99,6 +99,10 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
                 type: "boolean",
                 description: "Set to true to disable automatic CRDT merging and fail strictly on version conflict (original OCC behavior). Default: false.",
             },
+            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.",
+            },
         },
         required: ["project"],
     },
@@ -141,6 +145,10 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
                 type: "string",
                 description: "Brief 2-5 word noun phrase describing what this tool call is about.",
             },
+            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.",
+            },
         },
         required: ["project", "toolAction", "toolSummary"],
     },
@@ -509,6 +517,8 @@ export function isSessionSaveHandoffArgs(args) {
         return false;
     if (a.disable_merge !== undefined && typeof a.disable_merge !== "boolean")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     return true;
 }
 // ─── v0.4.0: Type guard for semantic search ──────────────────
@@ -572,6 +582,8 @@ export function isSessionLoadContextArgs(args) {
         return false;
     if (a.toolSummary !== undefined && typeof a.toolSummary !== "string")
         return false;
+    if (a.conversation_id !== undefined && typeof a.conversation_id !== "string")
+        return false;
     return true;
 }
 // ─── v2.0: Time Travel Tool Definitions ──────────────────────

package/dist/utils/analytics.js

@@ -48,10 +48,15 @@ async function ensureTable() {
     `);
     _tableReady = true;
 }
-/** Reset DB connection (for tests). */
+/** Reset DB connection and in-memory buffer (for tests). */
 export function _resetDb() {
     _db = null;
     _tableReady = false;
+    BUFFER.length = 0;
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
 }
 // ─── In-Memory Buffer ────────────────────────────────────────
 const BUFFER = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "19.2.9",
+  "version": "19.3.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local-first storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",