prism-mcp-server 20.2.8 → 20.3.0

package/README.md

@@ -77,6 +77,21 @@ to the patched 8.5.23 release.
 
 ---
 
+## What's New in v20.3.0
+
+### Hybrid Memory Search (Portal Tier)
+
+`session_search_memory` on Synalux-backed installs now fuses semantic
+similarity with exact-term lexical matching (weighted reciprocal-rank
+fusion). On blind probes against a real 8.5k-entry corpus this lifted
+top-1 retrieval from 45% (semantic alone) to 59%; exact identifiers such
+as TPNs, function names and error strings now rescue queries that
+embeddings blur. Results say how they were found — `hybrid retrieval`
+headers, per-hit `sem#/lex#` arms — and a lexical-only rescue is labelled
+`exact-term match` instead of pretending to a similarity score. Local
+SQLite installs keep pure vector search; hybrid needs the portal's
+lexical index.
+
 ## What's New in v20.2.6
 
 ### Safer Configuration Updates Across Every Agent
@@ -148,13 +163,16 @@ that would require a host lifecycle hook, launcher, extension, or Prism-owned
 panel. Context loading itself remains complete even when a host shortens the
 visible reply.
 
-Free accounts receive the protected 13-skill foundation. It includes
-`current-staging-acceptance`, the strict completion extension of
-`evidence-first-protocol`: agents must use the exact current staging artifact
-and inspect every case and screenshot before reporting acceptance. Paid
-accounts receive the current subscribed routing set. Upgrades install newly
-entitled packages; downgrades remove only Prism-owned packages while preserving
-local skills and locally modified conflicts.
+Free accounts receive only the public hook-free `prism-startup` package; the MCP
+server still supplies a compact, non-proprietary safety and evidence contract.
+Authenticated paid accounts receive the protected behavioral and engineering
+packages plus the current subscribed routing set. The paid
+`evidence-first-protocol` keeps ordinary coding lightweight: one correlated
+reproduction is enough to begin an edit, while strict acceptance starts only
+before a completion claim, push, or release and inspects only the exact artifacts
+used as proof. Upgrades install newly entitled packages; verified downgrades
+remove only Prism-owned packages while preserving local skills and locally
+modified conflicts.
 
 When upgrading an older Claude Code installation, `prism connect` removes only
 the exact Prism-owned startup, skill-sync, handoff, and drift hook actions from

package/dist/cli.js

@@ -12,6 +12,7 @@ import { configureClaudeAgentPolicy, configureClaudeNativeStartup, configureCode
 import { runBrowserCli } from './browserCli.js';
 import { filterPrismMemoryContext } from './utils/memoryQuality.js';
 import { isRecoverableStartupStorageError } from './utils/startupRecovery.js';
+import { verifyBehaviorHandler } from './tools/behavioralVerifierHandler.js';
 const program = new Command();
 /** Build the stable `prism load --json` envelope from depth-specific context. */
 export function buildLoadJsonOutput(project, data, level, metadata) {
@@ -111,6 +112,50 @@ program
     .command('bootstrap')
     .description('Print the canonical dashboard-configured first-turn Prism greeting')
     .action(runBootstrapCommand);
+/**
+ * One-shot fallback for hosts whose long-lived MCP transport has closed.
+ * This calls the canonical handler, including its authenticated portal path
+ * and fail-closed offline scenario; it never asks the host to invent one.
+ */
+export async function runVerifyBehaviorCommand(options) {
+    try {
+        const baseUrl = process.env.PRISM_SYNALUX_BASE_URL?.trim() ||
+            process.env.SYNALUX_BASE_URL?.trim() ||
+            (await getSetting('PRISM_SYNALUX_BASE_URL', '')).trim() ||
+            (await getSetting('SYNALUX_BASE_URL', '')).trim() ||
+            'https://synalux.ai';
+        const apiKey = process.env.PRISM_SYNALUX_API_KEY?.trim() ||
+            (await getSetting('PRISM_SYNALUX_API_KEY', '')).trim();
+        process.env.PRISM_SYNALUX_BASE_URL = baseUrl.replace(/\/+$/, '');
+        if (apiKey)
+            process.env.PRISM_SYNALUX_API_KEY = apiKey;
+        const result = await verifyBehaviorHandler({
+            file_path: options.file,
+            change_summary: options.summary,
+            ...(options.project ? { project: options.project } : {}),
+            ...(options.workspaceId ? { workspace_id: options.workspaceId } : {}),
+        });
+        const output = result.content
+            ?.map((part) => part?.text)
+            .filter(Boolean)
+            .join('\n') || '';
+        if (!output)
+            throw new Error('verify_behavior returned no scenario');
+        console.log(output);
+    }
+    catch (err) {
+        console.error(`Behavioral verification failed: ${err instanceof Error ? err.message : String(err)}`);
+        process.exitCode = 1;
+    }
+}
+program
+    .command('verify-behavior')
+    .description('Get the behavioral edit scenario when an MCP transport is unavailable')
+    .requiredOption('--file <path>', 'Path of the file about to be edited')
+    .requiredOption('--summary <text>', 'Brief description of the intended change')
+    .option('--project <project>', 'Project identifier for workspace-scoped scenarios')
+    .option('--workspace-id <id>', 'Workspace ID for custom scenarios')
+    .action(runVerifyBehaviorCommand);
 // Parsed by the direct dispatch at the bottom so all Python CLI flags pass
 // through unchanged. Registering it here keeps the command visible in help.
 program

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 { EVIDENCE_WORKFLOW_POLICY_LINES } from "./evidenceWorkflowPolicy.js";
 import { LOCAL_FIRST_POLICY_ID, LOCAL_FIRST_POLICY_LINES } from "./localFirstPolicy.js";
 export const CONNECT_HOSTS = [
     "claude-code",
@@ -46,6 +47,8 @@ const CODEX_STARTUP_BODY = [
     "block is managed by `prism connect`; do not edit it manually.",
     "",
     ...LOCAL_FIRST_POLICY_LINES,
+    "",
+    ...EVIDENCE_WORKFLOW_POLICY_LINES,
 ];
 const CONNECT_STORAGE_BACKENDS = ["auto", "local", "synalux", "supabase"];
 const LEGACY_CLAUDE_PROJECT_PRISM_ENTRY = {
@@ -542,6 +545,8 @@ function serializeClaudeStartupBlock(newline) {
         "managed by `prism connect`; do not edit it manually.",
         "",
         ...LOCAL_FIRST_POLICY_LINES,
+        "",
+        ...EVIDENCE_WORKFLOW_POLICY_LINES,
         CLAUDE_STARTUP_MANAGED_END,
         "",
     ].join(newline);
@@ -617,6 +622,8 @@ function serializeGeminiStartupBlock(newline) {
         "session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
         "",
         ...LOCAL_FIRST_POLICY_LINES,
+        "",
+        ...EVIDENCE_WORKFLOW_POLICY_LINES,
         GEMINI_STARTUP_MANAGED_END,
         "",
     ].join(newline);

package/dist/evidenceWorkflowPolicy.js

@@ -0,0 +1,19 @@
+/**
+ * Minimum evidence contract shared by every MCP host.
+ *
+ * Native-skill hosts also receive the full evidence-first protocol. Keep this
+ * compact copy in MCP initialize instructions so hosts without a filesystem
+ * skill surface, including Claude Desktop, still follow the same workflow.
+ */
+export const EVIDENCE_WORKFLOW_POLICY_LINES = [
+    "## Prism evidence workflow",
+    "During diagnosis and editing, one trustworthy correlated reproduction is enough; do not block coding on",
+    "inspecting unrelated diagnostic screenshots, trace frames, or abandoned attempts.",
+    "Before a completion claim, push, or release, exercise the corrected path with fresh evidence from the current",
+    "build and bind stateful proof to the exact run and entity. Inspect every artifact used to support the claim.",
+    "When a screenshot is requested or used as proof, the active agent must open it and compare its visible state",
+    "with the issue's expected and forbidden states. Complete that review yourself; do not ask the user to verify it.",
+    "A screenshot is an observation, not absolute truth. Reject stale, wrong-run, wrong-entity, or visibly failing",
+    "evidence even when its metadata says passed.",
+];
+export const EVIDENCE_WORKFLOW_POLICY_TEXT = EVIDENCE_WORKFLOW_POLICY_LINES.join(" ");

package/dist/mcpTransportHealth.js

@@ -28,8 +28,16 @@ export function monitorMcpTransport(server, options) {
         options.onFailure(reason, error);
     };
     const handleClose = () => {
-        previousOnClose?.();
-        fail("MCP_TRANSPORT_CLOSED");
+        let closeError;
+        try {
+            previousOnClose?.();
+        }
+        catch (error) {
+            closeError = error instanceof Error ? error : new Error(String(error));
+        }
+        finally {
+            fail("MCP_TRANSPORT_CLOSED", closeError);
+        }
     };
     server.onclose = handleClose;
     const check = async () => {

package/dist/server.js

@@ -85,6 +85,7 @@ import { inferenceMetricsHandler } from "./utils/inferenceMetrics.js";
 import { recordInvocation } from "./utils/analytics.js";
 import { BOUNDARIES_TEXT } from "./boundaries/boundaries.js";
 import { triggerSkillManifestSync } from "./skillManifestSync.js";
+import { EVIDENCE_WORKFLOW_POLICY_TEXT } from "./evidenceWorkflowPolicy.js";
 import { LOCAL_FIRST_POLICY_TEXT } from "./localFirstPolicy.js";
 // ─── Import Tool Definitions (schemas) and Handlers (implementations) ─────
 import { WEB_SEARCH_TOOL, BRAVE_WEB_SEARCH_CODE_MODE_TOOL, LOCAL_SEARCH_TOOL, BRAVE_LOCAL_SEARCH_CODE_MODE_TOOL, CODE_MODE_TRANSFORM_TOOL, BRAVE_ANSWERS_TOOL, RESEARCH_PAPER_ANALYSIS_TOOL, webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, braveLocalSearchCodeModeHandler, codeModeTransformHandler, braveAnswersHandler, researchPaperAnalysisHandler, } from "./tools/index.js";
@@ -328,6 +329,7 @@ export const PRISM_SERVER_INSTRUCTIONS = `Prism MCP — The Mind Palace for AI A
     `Reuse the conversation_id returned by session_bootstrap in structuredContent 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` +
     `${LOCAL_FIRST_POLICY_TEXT}\n\n` +
+    `${EVIDENCE_WORKFLOW_POLICY_TEXT}\n\n` +
     `Architecture: session_save_ledger and session_save_handoff require context loaded by session_bootstrap ` +
     `or session_load_context when a conversation_id is supplied. ${BOUNDARIES_TEXT} ` +
     `All cloud inference routes through the Synalux portal for billing, tier-gating, and audit.`;

package/dist/skillManifestSync.js

@@ -4,7 +4,7 @@ import { access, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realp
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { applyManagedSkillManifest, getSetting, refreshConfigStorageCache, } from "./storage/configStorage.js";
-import { REQUIRED_NATIVE_SKILL_NAMES } from "./tools/skillRouting.js";
+import { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } from "./tools/skillRouting.js";
 import { getSynaluxJwt, invalidateSynaluxJwt } from "./utils/synaluxJwt.js";
 const OWNER = "prism-skill-sync-v1";
 const MARKER = ".prism-managed.json";
@@ -181,17 +181,20 @@ export function validateSkillManifest(payload) {
             }
         }
     }
-    const requiredNames = new Set(REQUIRED_NATIVE_SKILL_NAMES);
-    for (const required of REQUIRED_NATIVE_SKILL_NAMES) {
+    const requiredForTier = value.tier === "free"
+        ? FREE_NATIVE_SKILL_NAMES
+        : REQUIRED_NATIVE_SKILL_NAMES;
+    const requiredNames = new Set(requiredForTier);
+    for (const required of requiredForTier) {
         const requiredSkill = skills.find((skill) => skill.name === required);
         if (!requiredSkill)
-            throw new Error(`manifest is missing required protected skill: ${required}`);
+            throw new Error(`manifest is missing required native skill: ${required}`);
         if (!requiredSkill.metadata.protected || !requiredSkill.metadata.categories.includes("universal")) {
-            throw new Error(`required skill is not protected universal: ${required}`);
+            throw new Error(`required native skill is not protected universal: ${required}`);
         }
     }
     if (value.tier === "free" && (skills.length !== requiredNames.size || skills.some((skill) => !requiredNames.has(skill.name)))) {
-        throw new Error("free manifest must contain exactly the protected skill floor");
+        throw new Error("free manifest must contain exactly the public startup package");
     }
     const normalized = {
         schema_version: 1,

package/dist/storage/portalContracts.js

@@ -39,4 +39,8 @@ export const KnowledgeSearchResponseSchema = z.object({
     action: z.literal("knowledge_search"),
     count: z.number(),
     results: z.array(z.record(z.string(), z.unknown())),
+    /** How the portal matched. Optional so an older portal deployment that
+     *  predates the ranked search RPC still validates. When present and
+     *  'relaxed', callers MUST NOT present the rows as exact hits. */
+    match_mode: z.enum(["strict", "relaxed", "unfiltered", "none"]).optional(),
 });

package/dist/storage/synalux.js

@@ -20,21 +20,35 @@
  *   Methods migrated to portal:
  *     - saveLedger        → POST /api/v1/prism/memory  action=save_ledger
  *     - saveHandoff       → POST /api/v1/prism/memory  action=save_handoff
+ *     - saveHistorySnapshot → POST /api/v1/prism/memory  action=save_history_snapshot
  *     - loadContext       → POST /api/v1/prism/memory  action=load_context
  *     - searchKnowledge   → POST /api/v1/prism/memory  action=search
  *     - softDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
  *     - hardDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
+ *     - searchMemory      → POST /api/v1/prism/memory  action=search_memory
+ *     - getHistory        → POST /api/v1/prism/memory  action=memory_history
+ *     - patchLedger       → POST /api/v1/prism/memory  action=save_embedding
+ *     - getEntriesMissingEmbeddings → POST /api/v1/prism/memory  action=list_missing_embeddings
  *
  *   Methods still falling through to SupabaseStorage (Phase 3 Tier B+):
- *   semantic searchMemory, save_experience direct entrypoint,
- *   compactLedger, image ops, history, hivemind, etc.
+ *   save_experience direct entrypoint, compactLedger, image ops,
+ *   hivemind, etc. Anything in this group requires a direct SUPABASE_URL
+ *   and therefore does NOT work on paid-tier installs — that is precisely
+ *   how embedding writes failed silently: patchLedger was inherited, threw
+ *   against a URL that is not configured, and the caller swallowed it.
+ *   Before relying on an inherited method, check it is actually reachable.
+ *
+ *   NOTE: this list was previously wrong — it named searchMemory and
+ *   history as falling through when both had already been overridden.
+ *   A stale routing map here sends the next reader down the wrong path,
+ *   so amend it in the same commit that moves a method.
  *   See portal/docs/PHASE_3_PORTAL_ENDPOINTS.md for the full catalog.
  * ═══════════════════════════════════════════════════════════════════
  */
 import { SupabaseStorage } from "./supabase.js";
 import { debugLog } from "../utils/logger.js";
 import { PRISM_SYNALUX_BASE_URL, PRISM_SYNALUX_API_KEY } from "../config.js";
-import { KnowledgeSearchRequestSchema } from "./portalContracts.js";
+import { KnowledgeSearchRequestSchema, KnowledgeSearchResponseSchema } from "./portalContracts.js";
 function resolveKnowledgeScope(callerScope) {
     if (callerScope === "user" || callerScope === "workspace") {
         return callerScope;
@@ -203,7 +217,46 @@ export class SynaluxStorage extends SupabaseStorage {
             role: handoff.role,
             expected_version: expectedVersion ?? undefined,
         });
-        return (result.handoff ?? result);
+        const candidate = Object.prototype.hasOwnProperty.call(result, "result")
+            ? result.result
+            : Object.prototype.hasOwnProperty.call(result, "handoff")
+                ? result.handoff
+                : result;
+        if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+            throw new Error("[SynaluxStorage] Invalid save_handoff response: missing result");
+        }
+        const value = candidate;
+        if (value.status === "conflict" && Number.isSafeInteger(value.current_version)) {
+            return {
+                status: "conflict",
+                current_version: value.current_version,
+            };
+        }
+        if ((value.status === "created" || value.status === "updated")
+            && Number.isSafeInteger(value.version)) {
+            return {
+                status: value.status,
+                version: value.version,
+            };
+        }
+        // Older portal RPC wrappers returned only the new version. Preserve that
+        // rolling-upgrade contract without accepting an unversioned success.
+        if (value.status === undefined && Number.isSafeInteger(value.version)) {
+            return {
+                status: "updated",
+                version: value.version,
+            };
+        }
+        throw new Error("[SynaluxStorage] Invalid save_handoff response: malformed OCC result");
+    }
+    async saveHistorySnapshot(handoff, branch = "main") {
+        await this.portalPost("/api/v1/prism/memory", {
+            action: "save_history_snapshot",
+            project: handoff.project,
+            version: handoff.version,
+            snapshot: handoff,
+            branch,
+        });
     }
     // ─── Context ─────────────────────────────────────────────────
     async loadContext(project, level, userId, role) {
@@ -290,6 +343,8 @@ export class SynaluxStorage extends SupabaseStorage {
         const result = await this.portalPost("/api/v1/prism/memory", {
             action: "search_memory",
             project: params.project ?? undefined,
+            // Enables the portal's hybrid lexical+semantic fusion (see interface).
+            query: params.queryText || undefined,
             query_embedding: parsed,
             similarity_threshold: params.similarityThreshold,
             limit: params.limit,
@@ -318,9 +373,81 @@ export class SynaluxStorage extends SupabaseStorage {
             scope: resolveKnowledgeScope(params.scope),
         });
         const result = await this.portalPost("/api/v1/prism/memory", wireBody);
+        // Validate the RESPONSE against the shared contract, not just the request.
+        // Before this, only the outgoing shape was checked — so a portal-side
+        // field rename would have gone unnoticed on both sides, which is exactly
+        // the 2026-05-24 class of incident this file exists to prevent.
+        // safeParse (not parse) on purpose: drift must be loud, but it must not
+        // take knowledge_search offline. The build-time contract test is what
+        // fails hard; at runtime we log and degrade to lenient extraction.
+        const validated = KnowledgeSearchResponseSchema.safeParse(result);
+        if (!validated.success) {
+            console.error("[synalux] knowledge_search response failed contract validation — " +
+                "portal and client may have drifted: " +
+                JSON.stringify(validated.error.issues.map(i => ({ path: i.path, code: i.code }))));
+        }
         const count = typeof result.count === "number" ? result.count : 0;
         const results = Array.isArray(result.results) ? result.results : [];
-        return { count, results };
+        const matchMode = validated.success ? validated.data.match_mode : undefined;
+        return { count, results, match_mode: matchMode };
+    }
+    /**
+     * Persist embedding data for an already-saved entry.
+     *
+     * MUST be overridden here. SupabaseStorage.patchLedger writes straight to
+     * Supabase via supabasePatch, which needs a direct SUPABASE_URL — not
+     * configured for paid-tier installs. Inheriting it meant every embedding
+     * write threw, and session_save_ledger's fire-and-forget catch swallowed
+     * the error while still reporting "Embedding generation queued". The
+     * result was 0 of 8,560 rows carrying an embedding and semantic search
+     * silently returning nothing.
+     *
+     * Only the vector is sent. embedding_compressed / embedding_format /
+     * embedding_turbo_radius are local-SQLite columns that do not exist on the
+     * portal schema; forwarding them would fail the whole write for fields the
+     * server has nowhere to put.
+     */
+    async patchLedger(id, data) {
+        const raw = data.embedding;
+        if (raw === undefined || raw === null)
+            return;
+        // ledgerHandlers JSON-stringifies the vector before patching; accept both.
+        let vector = raw;
+        if (typeof raw === "string") {
+            try {
+                vector = JSON.parse(raw);
+            }
+            catch {
+                throw new Error("patchLedger: embedding string is not valid JSON");
+            }
+        }
+        if (!Array.isArray(vector)) {
+            throw new Error("patchLedger: embedding must be an array");
+        }
+        await this.portalPost("/api/v1/prism/memory", {
+            action: "save_embedding",
+            memory_id: id,
+            embedding: vector,
+        });
+    }
+    /**
+     * Rows semantic search cannot find, read through the portal.
+     *
+     * The backfill tool used to reach these via inherited getLedgerEntries —
+     * a direct Supabase read paid-tier installs cannot make (NXDOMAIN), so the
+     * repair tool could never see what needed repairing. The portal endpoint
+     * ignores cursorId (it always returns the oldest missing rows, and rows
+     * gain embeddings as the backfill proceeds, so the frontier advances by
+     * itself); it is accepted here to satisfy the shared signature.
+     */
+    async getEntriesMissingEmbeddings(params) {
+        const result = await this.portalPost("/api/v1/prism/memory", {
+            action: "list_missing_embeddings",
+            limit: params.limit,
+            ...(params.project ? { project: params.project } : {}),
+        });
+        const entries = Array.isArray(result.entries) ? result.entries : [];
+        return entries;
     }
     // ─── Time Travel ─────────────────────────────────────────────
     // Phase 3 Tier B: route memory_history through portal instead of
@@ -357,8 +484,15 @@ export class SynaluxStorage extends SupabaseStorage {
             const inventory = result.inventory;
             const totalActiveEntries = typeof inventory?.ledger_entries === "number" ? inventory.ledger_entries : 0;
             const totalHandoffs = typeof inventory?.active_projects === "number" ? inventory.active_projects : 0;
+            // Hardcoding 0 here certified a 100%-missing-embeddings outage as
+            // "HEALTHY — all clean". Use the portal's real count; if the portal
+            // predates the field, report -1 so healthCheck can say "unknown"
+            // instead of lying in either direction.
+            const missingEmbeddings = typeof inventory?.ledger_missing_embeddings === "number"
+                ? inventory.ledger_missing_embeddings
+                : -1;
             return {
-                missingEmbeddings: 0,
+                missingEmbeddings,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,
@@ -371,7 +505,9 @@ export class SynaluxStorage extends SupabaseStorage {
         catch (e) {
             debugLog("[SynaluxStorage] getHealthStats failed: " + (e instanceof Error ? e.message : String(e)));
             return {
-                missingEmbeddings: 0,
+                // Portal unreachable: coverage is UNKNOWN, not zero. -1 makes the
+                // health check say so rather than certify blind.
+                missingEmbeddings: -1,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,

package/dist/tools/behavioralVerifierHandler.js

@@ -8,7 +8,7 @@
  * FAIL-CLOSED: if the portal is unreachable, returns a generic
  * verification challenge rather than skipping verification.
  */
-import { PRISM_SYNALUX_BASE_URL, SYNALUX_CONFIGURED } from "../config.js";
+import { PRISM_SYNALUX_BASE_URL } from "../config.js";
 import { getSynaluxJwt } from "../utils/synaluxJwt.js";
 const FALLBACK_SCENARIO = [
     "⚠️ BEHAVIORAL VERIFICATION (OFFLINE MODE)",
@@ -33,7 +33,13 @@ export async function verifyBehaviorHandler(args) {
     return { content: [{ type: "text", text: await buildScenarioText(args) }] };
 }
 async function buildScenarioText(args) {
-    if (!SYNALUX_CONFIGURED || !PRISM_SYNALUX_BASE_URL) {
+    const baseUrl = process.env.PRISM_SYNALUX_BASE_URL?.trim() ||
+        process.env.SYNALUX_BASE_URL?.trim() ||
+        PRISM_SYNALUX_BASE_URL;
+    // OAuth/JWT-backed installs intentionally do not copy a long-lived API key
+    // into host configuration. A valid portal URL is enough to attempt the
+    // short-lived JWT flow; getSynaluxJwt() remains the fail-closed auth gate.
+    if (!baseUrl) {
         return FALLBACK_SCENARIO;
     }
     const jwt = await getSynaluxJwt();
@@ -42,7 +48,7 @@ async function buildScenarioText(args) {
         return FALLBACK_SCENARIO;
     }
     try {
-        const url = `${PRISM_SYNALUX_BASE_URL}/api/v1/prism/verify-behavior`;
+        const url = `${baseUrl.replace(/\/+$/, "")}/api/v1/prism/verify-behavior`;
         const res = await fetch(url, {
             method: "POST",
             headers: {
@@ -60,7 +66,11 @@ async function buildScenarioText(args) {
             console.error(`[verify-behavior] ⚠️ portal returned ${res.status} — fail-closed. URL: ${url}`);
             return FALLBACK_SCENARIO;
         }
-        const data = (await res.json());
+        const data = await res.json();
+        if (!isVerifyBehaviorResult(data)) {
+            console.error("[verify-behavior] ⚠️ portal returned a malformed response — fail-closed");
+            return FALLBACK_SCENARIO;
+        }
         return formatResult(data);
     }
     catch (err) {
@@ -68,6 +78,12 @@ async function buildScenarioText(args) {
         return FALLBACK_SCENARIO;
     }
 }
+function isVerifyBehaviorResult(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        typeof value.requires_verification === "boolean";
+}
 function formatResult(data) {
     if (!data.requires_verification) {
         return JSON.stringify({ requires_verification: false, reason: data.reason || "non-behavioral file" });

package/dist/tools/graphHandlers.js

@@ -57,6 +57,56 @@ import { ConceptDictionary } from "../sdm/conceptDictionary.js";
 import { PolicyGateway } from "../sdm/policyGateway.js";
 import { getSdmEngine } from "../sdm/sdmEngine.js";
 import { PRISM_HDC_ENABLED, PRISM_HDC_EXPLAINABILITY_ENABLED, PRISM_HDC_POLICY_FALLBACK_THRESHOLD, PRISM_HDC_POLICY_CLARIFY_THRESHOLD, } from "../config.js";
+/**
+ * Header line for knowledge_search results.
+ *
+ * A 'relaxed' match_mode means no entry matched every query term — the portal
+ * widened the search and returned the closest entries. Wording those the same
+ * as an exact hit is how a best-effort guess gets read as a confirmed answer,
+ * so the distinction is stated in the text the agent actually sees.
+ *
+ * Exported so the wording is covered by a test that exercises this function
+ * rather than a copy of it.
+ */
+export function formatKnowledgeHeader(resultCount, matchMode) {
+    if (matchMode === "relaxed") {
+        return `🧠 No exact match. ${resultCount} closest ${resultCount === 1 ? "entry" : "entries"} ` +
+            `(widened search — treat as leads, not confirmed answers):`;
+    }
+    return `🧠 Found ${resultCount} knowledge entries:`;
+}
+/**
+ * Header + per-hit scoring for session_search_memory results.
+ *
+ * Exported so wording is covered by tests that call the shipped functions —
+ * a lesson from the knowledge_search match_mode fix, whose first tests
+ * mirrored the logic and would have passed while the handler regressed.
+ *
+ * Hybrid detection is per-row: portal fusion (weighted RRF, measured 59%
+ * blind hit@1 vs 45% semantic-only) annotates each row with semantic_rank /
+ * lexical_rank. Any row carrying lexical_rank means the lexical arm ran, so
+ * calling the results "semantically similar" would misstate how they were
+ * found — and a lexical-only rescue has NO similarity score at all, which
+ * previously rendered as "N/A similar".
+ */
+export function isHybridSearchResults(results) {
+    return results.some((r) => r?.lexical_rank !== undefined && r?.lexical_rank !== null);
+}
+export function searchResultsHeader(count, hybrid) {
+    return hybrid
+        ? `🧠 Found ${count} matching sessions (hybrid retrieval — semantic meaning + exact terms):`
+        : `🧠 Found ${count} semantically similar sessions:`;
+}
+export function formatHitScore(r) {
+    const sim = typeof r.similarity === "number" ? `${(r.similarity * 100).toFixed(1)}% similar` : null;
+    const sem = r.semantic_rank !== undefined && r.semantic_rank !== null ? `sem#${r.semantic_rank + 1}` : null;
+    const lex = r.lexical_rank !== undefined && r.lexical_rank !== null ? `lex#${r.lexical_rank + 1}` : null;
+    if (sem || lex) {
+        const arms = [sem, lex].filter(Boolean).join(" + ");
+        return sim ? `${sim} (${arms})` : `exact-term match (${arms})`;
+    }
+    return sim ?? "N/A similar";
+}
 export async function knowledgeSearchHandler(args) {
     if (!isKnowledgeSearchArgs(args)) {
         throw new Error("Invalid arguments for knowledge_search");
@@ -136,7 +186,7 @@ export async function knowledgeSearchHandler(args) {
     // Phase 1: Wrap in contentBlocks array for optional trace attachment
     const contentBlocks = [{
             type: "text",
-            text: `🧠 Found ${resultCount} knowledge entries:\n\n${JSON.stringify(data.results, null, 2)}`,
+            text: `${formatKnowledgeHeader(resultCount, data.match_mode)}\n\n${JSON.stringify(data.results, null, 2)}`,
         }];
     // Phase 1: Attach MemoryTrace with strategy="keyword" and timing data
     if (enable_trace) {
@@ -377,6 +427,8 @@ export async function sessionSearchMemoryHandler(args) {
             : Math.min(limit, 20);
         const results = await storage.searchMemory({
             queryEmbedding: JSON.stringify(queryEmbedding),
+            // Portal-backed installs fuse this with lexical search (weighted RRF).
+            queryText: query,
             project: project || null,
             limit: candidateLimit,
             similarityThreshold: similarity_threshold,
@@ -516,9 +568,7 @@ export async function sessionSearchMemoryHandler(args) {
         }
         // Format results with similarity scores + effective importance + ACT-R
         const formatted = results.map((r, i) => {
-            const simScore = typeof r.similarity === "number"
-                ? `${(r.similarity * 100).toFixed(1)}%`
-                : "N/A";
+            const simScore = formatHitScore(r);
             // Dynamic importance decay (uses ACT-R internally when enabled)
             const baseImportance = r.importance ?? 0;
             const effectiveImportance = computeEffectiveImportance(baseImportance, r.last_accessed_at, r.created_at, Boolean(r.is_rollup));
@@ -529,7 +579,7 @@ export async function sessionSearchMemoryHandler(args) {
             const actrStr = r._actr_composite !== undefined
                 ? `  ACT-R: composite=${r._actr_composite.toFixed(3)} (B=${r._actr_Bi?.toFixed(2)}, S=${r._actr_Si?.toFixed(3)})\n`
                 : "";
-            return `[${i + 1}] ${simScore} similar — ${r.session_date || "unknown date"}\n` +
+            return `[${i + 1}] ${simScore} — ${r.session_date || "unknown date"}\n` +
                 `  Project: ${r.project}\n` +
                 `  Summary: ${r.summary}\n` +
                 importanceStr +
@@ -540,7 +590,7 @@ export async function sessionSearchMemoryHandler(args) {
         // Phase 1: content[0] = human-readable results (unchanged from pre-Phase 1)
         const contentBlocks = [{
                 type: "text",
-                text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
+                text: `${searchResultsHeader(results.length, isHybridSearchResults(results))}\n\n${formatted}`,
             }];
         // Phase 1: content[1] = machine-readable MemoryTrace (only when enable_trace=true)
         // topScore is read from results[0].similarity — this is the cosine distance

package/dist/tools/hygieneHandlers.js

@@ -60,22 +60,36 @@ export async function backfillEmbeddingsHandler(args) {
     debugLog(`[backfill_embeddings] ${dry_run ? "DRY RUN: " : ""}` +
         `project=${project || "all"}, limit=${safeLimit}`);
     const storage = await getStorage();
-    // Find entries missing embeddings
-    const params = {
-        "embedding": "is.null",
-        "archived_at": "is.null",
-        user_id: `eq.${PRISM_USER_ID}`,
-        order: "id.asc",
-        limit: String(safeLimit),
-        select: "id,summary,decisions,project",
-    };
-    if (args._cursor_id) {
-        params.id = `gt.${args._cursor_id}`;
+    // Find entries missing embeddings. Prefer the dedicated method: the old
+    // PostgREST-param path below goes through getLedgerEntries, which
+    // SynaluxStorage inherits as a DIRECT Supabase read — paid-tier installs
+    // have no SUPABASE_URL, so that read dies with NXDOMAIN and this tool
+    // could never see what it was supposed to repair.
+    let entries;
+    if (typeof storage.getEntriesMissingEmbeddings === "function") {
+        entries = await storage.getEntriesMissingEmbeddings({
+            limit: safeLimit,
+            ...(project ? { project } : {}),
+            ...(args._cursor_id ? { cursorId: args._cursor_id } : {}),
+        });
     }
-    if (project) {
-        params.project = `eq.${project}`;
+    else {
+        const params = {
+            "embedding": "is.null",
+            "archived_at": "is.null",
+            user_id: `eq.${PRISM_USER_ID}`,
+            order: "id.asc",
+            limit: String(safeLimit),
+            select: "id,summary,decisions,project",
+        };
+        if (args._cursor_id) {
+            params.id = `gt.${args._cursor_id}`;
+        }
+        if (project) {
+            params.project = `eq.${project}`;
+        }
+        entries = await storage.getLedgerEntries(params);
     }
-    const entries = await storage.getLedgerEntries(params);
     if (entries.length === 0) {
         return {
             content: [{

package/dist/tools/ledgerHandlers.js

@@ -142,29 +142,42 @@ function parseNativeSkillNames(value) {
     }
 }
 async function resolveNativeSkillManifestSnapshot(syncResult) {
-    const { REQUIRED_NATIVE_SKILL_NAMES } = await import("./skillRouting.js");
+    const { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } = await import("./skillRouting.js");
     const [storedNamesValue, storedTierValue] = await Promise.all([
         getSetting("skill_manifest:names", "[]"),
         getSetting("skill_manifest:tier", ""),
     ]);
-    const partialNames = syncResult.status === "partial" && Array.isArray(syncResult.entitledNames)
-        ? syncResult.entitledNames.filter((name) => typeof name === "string" && NATIVE_SKILL_NAME.test(name))
+    const partialNamesInput = syncResult.status === "partial" && Array.isArray(syncResult.entitledNames)
+        ? syncResult.entitledNames
+        : null;
+    const partialProvided = partialNamesInput !== null;
+    const partialNames = partialNamesInput
+        ? partialNamesInput.filter((name) => typeof name === "string" && NATIVE_SKILL_NAME.test(name))
         : [];
     const storedNames = parseNativeSkillNames(storedNamesValue);
-    const names = partialNames.length > 0
-        ? [...new Set(partialNames)]
-        : storedNames.length > 0
-            ? storedNames
-            : [...REQUIRED_NATIVE_SKILL_NAMES];
-    const source = partialNames.length > 0
-        ? "validated-partial"
-        : storedNames.length > 0
-            ? "committed"
-            : "protected-fallback";
     const candidateTier = syncResult.status === "partial" ? syncResult.tier : storedTierValue || syncResult.tier;
     const tier = typeof candidateTier === "string" && SYNALUX_TIERS.has(candidateTier)
         ? candidateTier
         : "free";
+    const tierFallbackNames = tier === "free"
+        ? FREE_NATIVE_SKILL_NAMES
+        : REQUIRED_NATIVE_SKILL_NAMES;
+    const freeNames = new Set(FREE_NATIVE_SKILL_NAMES);
+    const namesForTier = (names) => tier === "free"
+        ? names.filter((name) => freeNames.has(name))
+        : names;
+    const entitledPartialNames = namesForTier([...new Set(partialNames)]);
+    const entitledStoredNames = namesForTier(storedNames);
+    const names = partialProvided
+        ? entitledPartialNames.length > 0 ? entitledPartialNames : [...tierFallbackNames]
+        : entitledStoredNames.length > 0
+            ? entitledStoredNames
+            : [...tierFallbackNames];
+    const source = partialProvided
+        ? "validated-partial"
+        : entitledStoredNames.length > 0
+            ? "committed"
+            : "tier-fallback";
     return {
         names,
         tier,
@@ -216,10 +229,10 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `> - 🧠 **Context depth:** ${depth}\n` +
             `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · native materialization incomplete${conflictSuffix}`;
     }
-    if (snapshot.source === "protected-fallback") {
+    if (snapshot.source === "tier-fallback") {
         return `> **Prism System Ready**\n>\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
-            `> - 🛡️ **Protected fallback names:** ${formatBoundedSkillNames(coreSkills, "fallback")}\n` +
+            `> - 🛡️ **Fallback skill names:** ${formatBoundedSkillNames(snapshot.names, "fallback")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
             `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · no committed manifest${conflictSuffix}`;
     }
@@ -341,38 +354,46 @@ export async function sessionSaveLedgerHandler(args) {
         role: effectiveRole, // v3.0: Hivemind role scoping (dashboard fallback)
     });
     // ─── Fire-and-forget embedding generation ───
+    let embeddingQueued = false;
     if (result) {
         const embeddingText = [summary, ...(decisions || [])].join("\n");
         const savedEntry = Array.isArray(result) ? result[0] : result;
         const entryId = savedEntry?.id;
         if (entryId) {
-            getLLMProvider().generateEmbedding(embeddingText)
-                .then(async (embedding) => {
-                // Build atomic patch — float32 + TurboQuant in ONE DB update
-                const patchData = {
-                    embedding: JSON.stringify(embedding),
-                };
-                // TurboQuant: compress alongside float32 (non-fatal)
-                try {
-                    const { getDefaultCompressor, serialize } = await import("../utils/turboquant.js");
-                    const compressor = getDefaultCompressor();
-                    const compressed = compressor.compress(embedding);
-                    const buf = serialize(compressed);
-                    patchData.embedding_compressed = buf.toString("base64");
-                    patchData.embedding_format = `turbo${compressor.bits}`;
-                    patchData.embedding_turbo_radius = compressed.radius;
-                    debugLog(`[session_save_ledger] TurboQuant compressed: ${buf.length} bytes (${(3072 / buf.length).toFixed(1)}× ratio)`);
-                }
-                catch (turboErr) {
-                    console.error(`[session_save_ledger] TurboQuant compression failed (non-fatal): ${turboErr.message}`);
-                }
-                // Single atomic DB update for all embedding data
-                await storage.patchLedger(entryId, patchData);
-                debugLog(`[session_save_ledger] Embedding saved for entry ${entryId}`);
-            })
-                .catch((err) => {
-                console.error(`[session_save_ledger] Embedding generation failed (non-fatal): ${err.message}`);
-            });
+            try {
+                const embeddingPromise = getLLMProvider().generateEmbedding(embeddingText);
+                embeddingQueued = true;
+                embeddingPromise
+                    .then(async (embedding) => {
+                    // Build atomic patch — float32 + TurboQuant in ONE DB update
+                    const patchData = {
+                        embedding: JSON.stringify(embedding),
+                    };
+                    // TurboQuant: compress alongside float32 (non-fatal)
+                    try {
+                        const { getDefaultCompressor, serialize } = await import("../utils/turboquant.js");
+                        const compressor = getDefaultCompressor();
+                        const compressed = compressor.compress(embedding);
+                        const buf = serialize(compressed);
+                        patchData.embedding_compressed = buf.toString("base64");
+                        patchData.embedding_format = `turbo${compressor.bits}`;
+                        patchData.embedding_turbo_radius = compressed.radius;
+                        debugLog(`[session_save_ledger] TurboQuant compressed: ${buf.length} bytes (${(3072 / buf.length).toFixed(1)}× ratio)`);
+                    }
+                    catch (turboErr) {
+                        console.error(`[session_save_ledger] TurboQuant compression failed (non-fatal): ${turboErr.message}`);
+                    }
+                    // Single atomic DB update for all embedding data
+                    await storage.patchLedger(entryId, patchData);
+                    debugLog(`[session_save_ledger] Embedding saved for entry ${entryId}`);
+                })
+                    .catch((err) => {
+                    console.error(`[session_save_ledger] Embedding generation failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+            catch (err) {
+                console.error(`[session_save_ledger] Embedding provider initialization failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     // ─── v6.0 Phase 3: Fire-and-forget auto-linking ────────────
@@ -439,7 +460,9 @@ export async function sessionSaveLedgerHandler(args) {
                     (todos?.length ? `TODOs: ${todos.length} items\n` : "") +
                     (files_changed?.length ? `Files changed: ${files_changed.length}\n` : "") +
                     (decisions?.length ? `Decisions: ${decisions.length}\n` : "") +
-                    `📊 Embedding generation queued for semantic search.` +
+                    (embeddingQueued
+                        ? `📊 Embedding generation queued for semantic search.`
+                        : `📊 Primary history saved; optional semantic indexing was not queued.`) +
                     metricsBlock +
                     resolverNote,
             }],
@@ -599,9 +622,12 @@ export async function sessionSaveHandoffHandler(args, server) {
     }
     // ─── Success: handoff created or updated ───
     const newVersion = data.version;
-    // ─── TIME MACHINE: Auto-snapshot for time travel (fire-and-forget) ───
+    // ─── TIME MACHINE: Auto-snapshot for time travel ───
     // Every successful save creates a snapshot so the user can revert later.
-    // We don't await — this should never block the success response.
+    // Await the attempt so short-lived CLI/MCP transports cannot exit before the
+    // snapshot reaches storage. Failure stays non-fatal because the primary
+    // handoff has already been durably saved.
+    let historySnapshotSaved = false;
     if (data.status === "created" || data.status === "updated") {
         const snapshotEntry = {
             project,
@@ -612,11 +638,19 @@ export async function sessionSaveHandoffHandler(args, server) {
             keywords: keywords ?? null,
             key_context: key_context ?? null,
             active_branch: active_branch ?? null,
+            role: effectiveRole,
             version: newVersion,
         };
-        storage.saveHistorySnapshot(snapshotEntry).catch(err => console.error(`[session_save_handoff] History snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`));
+        try {
+            await storage.saveHistorySnapshot(snapshotEntry, active_branch ?? "main");
+            historySnapshotSaved = true;
+        }
+        catch (err) {
+            console.error(`[session_save_handoff] History snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     // ─── Fire-and-forget embedding generation (enables semantic search on handoffs) ───
+    let embeddingQueued = false;
     if (data.status === "created" || data.status === "updated") {
         const embeddingText = [
             last_summary || "",
@@ -624,30 +658,37 @@ export async function sessionSaveHandoffHandler(args, server) {
             ...(open_todos || []),
         ].filter(Boolean).join("\n");
         if (embeddingText.trim()) {
-            getLLMProvider().generateEmbedding(embeddingText)
-                .then(async (embedding) => {
-                const patchData = {
-                    embedding: JSON.stringify(embedding),
-                };
-                try {
-                    const { getDefaultCompressor, serialize } = await import("../utils/turboquant.js");
-                    const compressor = getDefaultCompressor();
-                    const compressed = compressor.compress(embedding);
-                    const buf = serialize(compressed);
-                    patchData.embedding_compressed = buf.toString("base64");
-                    patchData.embedding_format = `turbo${compressor.bits}`;
-                    patchData.embedding_turbo_radius = compressed.radius;
-                    debugLog(`[session_save_handoff] TurboQuant compressed: ${buf.length} bytes`);
-                }
-                catch (turboErr) {
-                    console.error(`[session_save_handoff] TurboQuant compression failed (non-fatal): ${turboErr.message}`);
-                }
-                await storage.patchHandoff(project, PRISM_USER_ID, patchData);
-                debugLog(`[session_save_handoff] Embedding saved for project "${project}"`);
-            })
-                .catch((err) => {
-                console.error(`[session_save_handoff] Embedding generation failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
-            });
+            try {
+                const embeddingPromise = getLLMProvider().generateEmbedding(embeddingText);
+                embeddingQueued = true;
+                embeddingPromise
+                    .then(async (embedding) => {
+                    const patchData = {
+                        embedding: JSON.stringify(embedding),
+                    };
+                    try {
+                        const { getDefaultCompressor, serialize } = await import("../utils/turboquant.js");
+                        const compressor = getDefaultCompressor();
+                        const compressed = compressor.compress(embedding);
+                        const buf = serialize(compressed);
+                        patchData.embedding_compressed = buf.toString("base64");
+                        patchData.embedding_format = `turbo${compressor.bits}`;
+                        patchData.embedding_turbo_radius = compressed.radius;
+                        debugLog(`[session_save_handoff] TurboQuant compressed: ${buf.length} bytes`);
+                    }
+                    catch (turboErr) {
+                        console.error(`[session_save_handoff] TurboQuant compression failed (non-fatal): ${turboErr.message}`);
+                    }
+                    await storage.patchHandoff(project, PRISM_USER_ID, patchData);
+                    debugLog(`[session_save_handoff] Embedding saved for project "${project}"`);
+                })
+                    .catch((err) => {
+                    console.error(`[session_save_handoff] Embedding generation failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+            catch (err) {
+                console.error(`[session_save_handoff] Embedding provider initialization failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     // ─── Trigger resource subscription notification ───
@@ -762,12 +803,16 @@ export async function sessionSaveHandoffHandler(args, server) {
         console.error("[FactMerger] Module load failed (non-fatal): " + err));
     }
     const metricsBlock = formatInferenceMetrics();
+    const historySnapshotLine = historySnapshotSaved
+        ? `🕘 Versioned history snapshot saved.\n`
+        : `⚠️ Primary handoff saved, but its versioned history snapshot was not saved. Check memory_history before relying on time travel.\n`;
     // Build response text based on whether a CRDT merge occurred
     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` : "") +
+                historySnapshotLine +
                 metricsBlock +
                 `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
                 `to maintain concurrency control.`
@@ -776,7 +821,10 @@ export async function sessionSaveHandoffHandler(args, server) {
                 (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` +
+                historySnapshotLine +
+                (embeddingQueued
+                    ? `📊 Embedding generation queued for semantic search.\n`
+                    : `📊 Primary history saved; optional semantic indexing was not queued.\n`) +
                 metricsBlock +
                 `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
                 `to maintain concurrency control.`);
@@ -1961,16 +2009,21 @@ export async function sessionSaveExperienceHandler(args) {
         const savedEntry = Array.isArray(result) ? result[0] : result;
         const entryId = savedEntry?.id;
         if (entryId) {
-            getLLMProvider().generateEmbedding(embeddingText)
-                .then(async (embedding) => {
-                await storage.patchLedger(entryId, {
-                    embedding: JSON.stringify(embedding),
+            try {
+                getLLMProvider().generateEmbedding(embeddingText)
+                    .then(async (embedding) => {
+                    await storage.patchLedger(entryId, {
+                        embedding: JSON.stringify(embedding),
+                    });
+                    debugLog(`[session_save_experience] Embedding saved for entry ${entryId}`);
+                })
+                    .catch((err) => {
+                    console.error(`[session_save_experience] Embedding failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
                 });
-                debugLog(`[session_save_experience] Embedding saved for entry ${entryId}`);
-            })
-                .catch((err) => {
-                console.error(`[session_save_experience] Embedding failed (non-fatal): ${err.message}`);
-            });
+            }
+            catch (err) {
+                console.error(`[session_save_experience] Embedding provider initialization failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
     }
     return {

package/dist/tools/sessionMemoryDefinitions.js

@@ -1839,7 +1839,8 @@ export const VERIFY_BEHAVIOR_TOOL = {
     description: "Call BEFORE editing behavioral source files (API routes, ordering logic, billing, auth, migrations). " +
         "Returns a domain-specific scenario you must answer to demonstrate understanding of the end-user impact. " +
         "Example: editing a KDS route returns 'A cook has a 3-item ticket. One item is voided. What should the cook see?' " +
-        "Answer the scenario concretely before proceeding with the edit.",
+        "Answer the scenario concretely before proceeding with the edit. If the MCP transport is unavailable, use the " +
+        "packaged `prism verify-behavior` CLI fallback; never fabricate a replacement scenario.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/skillRouting.js

@@ -22,11 +22,10 @@ export const REQUIRED_PROTECTED_SKILL_NAMES = [
     'pre-commit-protocol',
     'pre-push-audit',
     'implementation-integrity-audit',
-    'current-staging-acceptance',
     'local-inference-first',
 ];
 /**
- * Native skills that every subscription tier receives through `prism connect`.
+ * Native skills that paid subscription tiers receive through `prism connect`.
  *
  * `prism-startup` is deliberately not part of OFFLINE_FALLBACK: it tells the
  * host to call session_load_context, so injecting it back into that tool's
@@ -37,6 +36,8 @@ export const REQUIRED_NATIVE_SKILL_NAMES = [
     ...REQUIRED_PROTECTED_SKILL_NAMES,
     'prism-startup',
 ];
+/** Public hook-free bootstrap package available without a paid entitlement. */
+export const FREE_NATIVE_SKILL_NAMES = ['prism-startup'];
 export const OFFLINE_FALLBACK = {
     version: 1,
     universal: REQUIRED_PROTECTED_SKILL_NAMES.map((name, priority) => ({ name, priority, protected: true })),

package/dist/utils/codingQualityPolicy.js

@@ -41,7 +41,9 @@ const UNFENCED_PYTHON_START_RE = /^\s*(?:from\s+\S+\s+import|import\s+\S+|(?:asy
 const TRAILING_PROSE_LINE_RE = /^(?!(?:async\s+def|def|class|from|import|return|raise|yield|assert|del|global|nonlocal|if|elif|else|for|while|try|except|finally|with|match|case)\b)(?![A-Za-z_]\w*\s*=)[A-Za-z][A-Za-z'’-]*:?(?:\s+(?:[A-Za-z][A-Za-z'’+/-]*|`[^`\r\n]+`|https?:\/\/\S+|\d[\w.,%()+\-]*|[+*=<>-])){2,}[.!?]$/;
 const TRAILING_URL_LINE_RE = /^https?:\/\/\S+$/i;
 const PYTHON_INVALID_DEF_RE = /(?:^|\n)\s*(?:async\s+)?def\s+[A-Za-z_]\w*\s*:/m;
-const PYTHON_AST_SCRIPT = "import ast,sys; tree=ast.parse(sys.stdin.read()); compile(tree, '<prism-coding-gate>', 'exec')";
+const PYTHON_READY_SENTINEL = "PRISM_PYTHON_READY";
+const PYTHON_AST_SCRIPT = `import ast,sys; print('${PYTHON_READY_SENTINEL}', flush=True); ` +
+    "tree=ast.parse(sys.stdin.read()); compile(tree, '<prism-coding-gate>', 'exec')";
 const PYTHON_COMMANDS = ["python3", "python"];
 const PYTHON_CHILDREN_KEYS_UNPACK_RE = /\bfor\s+[A-Za-z_]\w*\s*,\s*child(?:_node)?\s+in\s+(?:sorted\(\s*)?[A-Za-z_][\w.]*\.children\.keys\(\)\s*\)?\s*:/;
 function extractUnfencedPythonCode(output) {
@@ -279,6 +281,12 @@ function pythonSyntaxFailure(code) {
         if (parsed.error && parsed.error.code === "ENOENT") {
             continue;
         }
+        const parserStarted = parsed.stdout
+            ?.split(/\r?\n/)
+            .includes(PYTHON_READY_SENTINEL) === true;
+        if (!parserStarted) {
+            continue;
+        }
         return parsed.status === 0 ? undefined : "python_syntax_error";
     }
     return undefined;

package/dist/utils/healthCheck.js

@@ -217,7 +217,21 @@ export function runHealthCheck(stats) {
             severity: stats.missingEmbeddings > 10 ? "error" : "warning", // >10 = critical
             message: `${stats.missingEmbeddings} ledger entries have no embedding vector`,
             count: stats.missingEmbeddings, // how many are affected
-            suggestion: "Run session_health_check(auto_fix: true) to generate missing embeddings automatically",
+            suggestion: "Run session_backfill_embeddings to generate the missing vectors",
+        });
+    }
+    else if (stats.missingEmbeddings < 0) {
+        // -1 = coverage is UNKNOWN (portal unreachable, or a portal that predates
+        // the ledger_missing_embeddings field). Saying nothing here is how a
+        // 100%-missing outage was certified "HEALTHY — all clean": the storage
+        // layer hardcoded 0 and this check had no way to distinguish "verified
+        // zero" from "never looked".
+        issues.push({
+            check: "missing_embeddings",
+            severity: "warning",
+            message: "Embedding coverage could not be verified (portal did not report a count)",
+            count: 0,
+            suggestion: "Update the Synalux portal, or check connectivity, then re-run session_health_check",
         });
     }
     // ── Check 2: Duplicate Entries ─────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.2.8",
+  "version": "20.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 or subscription-gated Synalux storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "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": "npm run build",
+    "prepublishOnly": "node scripts/check-publish-clean.mjs && npm run build",
     "lint:dashboard": "node scripts/lint-dashboard-es5.cjs",
     "start": "node dist/server.js",
     "test": "vitest run",