prism-mcp-server 20.2.1 → 20.2.2

package/dist/storage/configStorage.js

@@ -15,7 +15,9 @@ const PROTO_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 //   PRISM_STORAGE, PRISM_ENABLE_HIVEMIND) are read only at startup.
 //   Changing them at runtime requires a server restart to take effect.
 //   Runtime-only settings (e.g. dashboard_theme) take effect immediately.
-const CONFIG_PATH = resolve(homedir(), ".prism-mcp", "prism-config.db");
+const CONFIG_PATH = process.env.PRISM_CONFIG_PATH
+    ? resolve(process.env.PRISM_CONFIG_PATH)
+    : resolve(homedir(), ".prism-mcp", "prism-config.db");
 let configClient = null;
 let initialized = false;
 // ─── In-memory settings cache ──────────────────────────────────────
@@ -50,6 +52,15 @@ export async function initConfigStorage() {
         value TEXT NOT NULL,
         updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
       )
+    `);
+        await client.execute(`
+      CREATE TABLE IF NOT EXISTS prism_managed_skills (
+        name TEXT PRIMARY KEY,
+        digest TEXT NOT NULL,
+        generation TEXT NOT NULL,
+        owner TEXT NOT NULL DEFAULT 'prism',
+        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      )
     `);
         // Preload all rows into the cache so subsequent reads are zero-cost.
         const rs = await client.execute("SELECT key, value FROM system_settings");
@@ -71,6 +82,104 @@ export async function initConfigStorage() {
     }
     initialized = true;
 }
+/**
+ * Atomically applies a complete platform-skill snapshot.
+ *
+ * Ownership is recorded separately from the existing `skill:*` namespace so
+ * a tier downgrade can remove only rows previously written by Prism. Role and
+ * user-local skill rows are never inferred to be managed and are never pruned.
+ */
+export async function applyManagedSkillManifest(state) {
+    await initConfigStorage();
+    if (state.skills.length === 0)
+        throw new Error("Refusing to apply an empty skill manifest");
+    const client = getClient();
+    const names = state.skills.map((skill) => skill.name);
+    const placeholders = names.map(() => "?").join(", ");
+    const statements = [];
+    for (const skill of state.skills) {
+        statements.push({
+            sql: `
+        INSERT INTO system_settings (key, value, updated_at)
+        VALUES (?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
+      `,
+            args: [`skill:${skill.name}`, skill.content],
+        });
+    }
+    // Delete content only when the ownership table proves Prism wrote it and
+    // the complete replacement snapshot no longer contains it.
+    statements.push({
+        sql: `
+      DELETE FROM system_settings
+      WHERE key IN (
+        SELECT 'skill:' || name FROM prism_managed_skills
+        WHERE name NOT IN (${placeholders})
+      )
+    `,
+        args: names,
+    });
+    statements.push({
+        sql: `DELETE FROM prism_managed_skills WHERE name NOT IN (${placeholders})`,
+        args: names,
+    });
+    for (const skill of state.skills) {
+        statements.push({
+            sql: `
+        INSERT INTO prism_managed_skills (name, digest, generation, owner, updated_at)
+        VALUES (?, ?, ?, 'prism', CURRENT_TIMESTAMP)
+        ON CONFLICT(name) DO UPDATE SET
+          digest = excluded.digest,
+          generation = excluded.generation,
+          owner = 'prism',
+          updated_at = CURRENT_TIMESTAMP
+      `,
+            args: [skill.name, skill.digest, state.generation],
+        });
+    }
+    for (const [key, value] of [
+        ["skill_manifest:generation", state.generation],
+        ["skill_manifest:tier", state.tier],
+        ["skill_manifest:routing_version", String(state.routingVersion)],
+        ["skill_manifest:owner", "prism"],
+        ["skill_manifest:names", JSON.stringify(names)],
+    ]) {
+        statements.push({
+            sql: `
+        INSERT INTO system_settings (key, value, updated_at)
+        VALUES (?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
+      `,
+            args: [key, value],
+        });
+    }
+    // libSQL batch("write") is one transaction: a failed statement rolls back
+    // content, ownership, digests, and generation together.
+    await client.batch(statements, "write");
+    // Refresh only after commit so synchronous readers never observe a future
+    // generation paired with stale skill content. A cache read failure must not
+    // make callers mistake an already-committed downgrade for a rolled-back DB
+    // write and skip native entitlement cleanup. Session loading refreshes again
+    // before activation and therefore fails closed until the DB is readable.
+    try {
+        await refreshConfigStorageCache();
+    }
+    catch (error) {
+        console.error(`[configStorage] Managed skill manifest committed but cache refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Reload settings written by another Prism process into this process's cache. */
+export async function refreshConfigStorageCache() {
+    await initConfigStorage();
+    const rs = await getClient().execute("SELECT key, value FROM system_settings");
+    const refreshed = Object.create(null);
+    for (const row of rs.rows) {
+        const key = row.key;
+        if (!PROTO_KEYS.has(key))
+            refreshed[key] = row.value;
+    }
+    settingsCache = refreshed;
+}
 /**
  * Synchronous setting read — served from the in-memory cache.
  * Returns defaultValue if the cache hasn't been populated yet (e.g. very

package/dist/storage/index.js

@@ -15,17 +15,18 @@ export function isValidHttpUrl(url) {
  * Probe for synalux credentials: env vars first, then config DB.
  * Returns true if usable credentials are now in process.env.
  */
-async function ensureSynaluxCredentials() {
+export async function ensureSynaluxCredentials() {
     if (SYNALUX_CONFIGURED)
         return true;
     // Re-check process.env directly: SYNALUX_CONFIGURED is captured at module
     // load, so credentials injected later by another caller would be invisible
     // to it. Mirrors ensureSupabaseCredentials below.
-    const envUrl = process.env.PRISM_SYNALUX_BASE_URL?.trim();
+    const envUrl = process.env.PRISM_SYNALUX_BASE_URL?.trim() || process.env.SYNALUX_BASE_URL?.trim();
     const envKey = process.env.PRISM_SYNALUX_API_KEY?.trim();
     if (envUrl && envKey && isValidHttpUrl(envUrl))
         return true;
-    const url = (await getSetting("PRISM_SYNALUX_BASE_URL"))?.trim();
+    const url = (await getSetting("PRISM_SYNALUX_BASE_URL"))?.trim() ||
+        (await getSetting("SYNALUX_BASE_URL"))?.trim();
     const key = (await getSetting("PRISM_SYNALUX_API_KEY"))?.trim();
     if (url && key && isValidHttpUrl(url)) {
         process.env.PRISM_SYNALUX_BASE_URL = url;

package/dist/storage/inferMetricsLedger.js

@@ -38,6 +38,12 @@ let ensured = null;
 let disabled = false;
 let initFailures = 0;
 const MAX_INIT_FAILURES = 3;
+const LEDGER_UNAVAILABLE_ERROR = "Inference metrics ledger is unavailable";
+const INSERT_METRIC_SQL = `INSERT OR IGNORE INTO infer_metrics
+    (ts, caller, mode, backend, model, used_cloud, gate_outcome,
+     refusal_reason, prompt_tokens, completion_tokens, latency_ms, ram_free_mb,
+     source_event_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
 function closeClient(context) {
     const activeClient = client;
     client = null;
@@ -76,9 +82,22 @@ function ensureTable() {
                     prompt_tokens INTEGER,
                     completion_tokens INTEGER,
                     latency_ms INTEGER,
-                    ram_free_mb INTEGER
+                    ram_free_mb INTEGER,
+                    source_event_id TEXT
                 )`);
+            // Existing ledgers predate external panel-spool ingestion. SQLite has
+            // no ADD COLUMN IF NOT EXISTS, so use the repository's established
+            // idempotent migration pattern and reject only unexpected failures.
+            try {
+                await client.execute(`ALTER TABLE infer_metrics ADD COLUMN source_event_id TEXT`);
+            }
+            catch (e) {
+                if (!(e instanceof Error) || !e.message.includes("duplicate column name"))
+                    throw e;
+            }
             await client.execute(`CREATE INDEX IF NOT EXISTS idx_infer_metrics_ts ON infer_metrics (ts)`);
+            await client.execute(`CREATE UNIQUE INDEX IF NOT EXISTS idx_infer_metrics_source_event
+                 ON infer_metrics (source_event_id) WHERE source_event_id IS NOT NULL`);
         })().catch((e) => {
             // Transient failures (missing dir on first run, SQLITE_BUSY) retry on
             // the next append; only repeated failure disables for the process.
@@ -100,23 +119,38 @@ export function appendInferMetric(row) {
         await ensureTable();
         if (disabled || !client)
             return;
-        await client.execute({
-            sql: `INSERT INTO infer_metrics
-                  (ts, caller, mode, backend, model, used_cloud, gate_outcome,
-                   refusal_reason, prompt_tokens, completion_tokens, latency_ms, ram_free_mb)
-                  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-            args: [
-                Date.now(), row.caller ?? "mcp", row.mode ?? null, row.backend,
-                row.model, row.used_cloud ? 1 : 0, row.gate_outcome ?? null,
-                row.refusal_reason ?? null, row.prompt_tokens ?? null,
-                row.completion_tokens ?? null, row.latency_ms ?? null,
-                row.ram_free_mb ?? null,
-            ],
-        });
+        await client.execute({ sql: INSERT_METRIC_SQL, args: metricArgs(row) });
     })().catch((e) => {
         debugLog(`[infer-ledger] append failed: ${e instanceof Error ? e.message : e}`);
     });
 }
+/**
+ * Transactionally append externally-spooled rows and report deduplication.
+ * Unlike appendInferMetric(), this is awaited so the spool owner knows when it
+ * is safe to delete a claimed file.
+ */
+export async function appendInferMetricBatch(rows) {
+    if (rows.length === 0)
+        return { inserted: 0, duplicates: 0 };
+    await ensureTable();
+    if (disabled || !client)
+        throw new Error(LEDGER_UNAVAILABLE_ERROR);
+    const results = await client.batch(rows.map(row => ({ sql: INSERT_METRIC_SQL, args: metricArgs(row) })), "write");
+    const inserted = results.reduce((total, result) => total + result.rowsAffected, 0);
+    return { inserted, duplicates: rows.length - inserted };
+}
+function metricArgs(row) {
+    const timestamp = Number.isFinite(row.ts) && (row.ts ?? 0) > 0
+        ? Math.floor(row.ts)
+        : Date.now();
+    return [
+        timestamp, row.caller ?? "mcp", row.mode ?? null, row.backend,
+        row.model, row.used_cloud ? 1 : 0, row.gate_outcome ?? null,
+        row.refusal_reason ?? null, row.prompt_tokens ?? null,
+        row.completion_tokens ?? null, row.latency_ms ?? null,
+        row.ram_free_mb ?? null, row.source_event_id ?? null,
+    ];
+}
 /** Aggregate all persisted rows (optionally since a timestamp). */
 export async function queryInferMetrics(sinceTs) {
     try {
@@ -140,11 +174,34 @@ export async function queryInferMetrics(sinceTs) {
             sql: `SELECT backend, COUNT(*) AS n FROM infer_metrics ${where} GROUP BY backend`,
             args: whereArgs
         });
+        const byC = await client.execute({
+            sql: `SELECT COALESCE(caller, 'mcp') AS caller,
+                         COUNT(*) AS total,
+                         SUM(CASE WHEN used_cloud = 0 THEN 1 ELSE 0 END) AS local,
+                         SUM(CASE WHEN used_cloud = 1 THEN 1 ELSE 0 END) AS cloud,
+                         COALESCE(SUM(prompt_tokens), 0) AS pt,
+                         COALESCE(SUM(completion_tokens), 0) AS ct,
+                         COALESCE(AVG(latency_ms), 0) AS avg_lat
+                  FROM infer_metrics ${where}
+                  GROUP BY COALESCE(caller, 'mcp')`,
+            args: whereArgs
+        });
         const r = agg.rows[0];
         const by_backend = {};
         for (const row of byB.rows) {
             by_backend[String(row.backend)] = Number(row.n);
         }
+        const by_caller = {};
+        for (const row of byC.rows) {
+            by_caller[String(row.caller)] = {
+                total: Number(row.total ?? 0),
+                local: Number(row.local ?? 0),
+                cloud: Number(row.cloud ?? 0),
+                prompt_tokens: Number(row.pt ?? 0),
+                completion_tokens: Number(row.ct ?? 0),
+                avg_latency_ms: Math.round(Number(row.avg_lat ?? 0)),
+            };
+        }
         return {
             total: Number(r.total ?? 0),
             local: Number(r.local ?? 0),
@@ -155,6 +212,7 @@ export async function queryInferMetrics(sinceTs) {
             first_ts: r.first_ts == null ? null : Number(r.first_ts),
             last_ts: r.last_ts == null ? null : Number(r.last_ts),
             by_backend,
+            by_caller,
         };
     }
     catch (e) {

package/dist/storage/panelMetricsSpool.js

@@ -0,0 +1,324 @@
+/**
+ * Crash-safe ingestion for Synalux VS Code panel inference metrics.
+ *
+ * The extension and MCP server are separate processes, so the extension writes
+ * bounded JSONL records instead of opening Prism's SQLite database. The MCP
+ * process atomically claims the live spool, validates every field, and deletes
+ * a claim only after the ledger transaction succeeds. Stable event IDs make a
+ * replay after a crash idempotent.
+ */
+import { randomUUID } from "node:crypto";
+import { createReadStream, promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { appendInferMetricBatch } from "./inferMetricsLedger.js";
+import { debugLog } from "../utils/logger.js";
+const PANEL_METRICS_FILE = "panel-metrics.jsonl";
+const PANEL_METRICS_DIRECTORY = ".prism-mcp";
+const PANEL_METRICS_PATH_ENV = "PRISM_PANEL_METRICS_PATH";
+const LOCK_SUFFIX = ".lock";
+const LOCK_STALE_MS = 30_000;
+const PROCESSING_STALE_MS = 5 * 60_000;
+const LOCK_RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160];
+const FILE_MODE = 0o600;
+const DIRECTORY_MODE = 0o700;
+const EVENT_VERSION = 1;
+const MAX_CLAIMS_PER_INGEST = 32;
+const MAX_LINE_BYTES = 4 * 1024;
+const BATCH_SIZE = 250;
+const MAX_MODEL_LENGTH = 256;
+const MAX_METRIC_VALUE = 100_000_000;
+const MAX_LATENCY_MS = 24 * 60 * 60 * 1_000;
+const MAX_FUTURE_SKEW_MS = 5 * 60_000;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const PANEL_EVENTS = new Set(["panel_served_local", "panel_escalated"]);
+const PANEL_BACKENDS = new Set(["prism", "local", "cloud", "gemini"]);
+const PANEL_MODES = new Set(["chat", "code"]);
+const LOCAL_BACKENDS = new Set(["prism", "local"]);
+const CLOUD_BACKENDS = new Set(["cloud", "gemini"]);
+const EVENT_KEYS = new Set([
+    "v", "event_id", "ts", "event", "backend", "model", "used_cloud",
+    "mode", "prompt_tokens", "completion_tokens", "latency_ms",
+]);
+const EMPTY_RESULT = {
+    claimed_files: 0,
+    seen: 0,
+    valid: 0,
+    inserted: 0,
+    duplicates: 0,
+    invalid: 0,
+    failed_files: 0,
+};
+export function getPanelMetricsSpoolPath() {
+    const override = process.env[PANEL_METRICS_PATH_ENV]?.trim();
+    if (override)
+        return override;
+    if (process.env.PRISM_DATA_DIR)
+        return resolve(process.env.PRISM_DATA_DIR, PANEL_METRICS_FILE);
+    return resolve(homedir(), PANEL_METRICS_DIRECTORY, PANEL_METRICS_FILE);
+}
+/** Claim and ingest all currently available panel metric files. Never throws. */
+export async function ingestPanelMetrics() {
+    const result = { ...EMPTY_RESULT };
+    let claims;
+    try {
+        claims = await claimAvailableFiles(getPanelMetricsSpoolPath());
+    }
+    catch (error) {
+        result.failed_files++;
+        debugLog(`[panel-metrics] claim failed: ${error instanceof Error ? error.message : error}`);
+        return result;
+    }
+    result.claimed_files = claims.length;
+    for (const claim of claims) {
+        try {
+            const fileResult = await ingestClaim(claim);
+            result.seen += fileResult.seen;
+            result.valid += fileResult.valid;
+            result.inserted += fileResult.inserted;
+            result.duplicates += fileResult.duplicates;
+            result.invalid += fileResult.invalid;
+            await fs.unlink(claim);
+        }
+        catch (error) {
+            result.failed_files++;
+            debugLog(`[panel-metrics] ingest failed: ${error instanceof Error ? error.message : error}`);
+            await returnClaimForRetry(claim).catch(() => undefined);
+        }
+    }
+    return result;
+}
+async function ingestClaim(path) {
+    const result = { ...EMPTY_RESULT, claimed_files: 1 };
+    const input = createReadStream(path, { encoding: "utf8" });
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    let batch = [];
+    const flush = async () => {
+        if (batch.length === 0)
+            return;
+        const batchResult = await appendInferMetricBatch(batch);
+        result.inserted += batchResult.inserted;
+        result.duplicates += batchResult.duplicates;
+        batch = [];
+    };
+    for await (const line of lines) {
+        if (!line.trim())
+            continue;
+        result.seen++;
+        if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+            result.invalid++;
+            continue;
+        }
+        const event = parsePanelMetric(line);
+        if (!event) {
+            result.invalid++;
+            continue;
+        }
+        result.valid++;
+        batch.push(toLedgerRow(event));
+        if (batch.length >= BATCH_SIZE)
+            await flush();
+    }
+    await flush();
+    return result;
+}
+function parsePanelMetric(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || Object.keys(value).some(key => !EVENT_KEYS.has(key)))
+        return null;
+    if (value.v !== EVENT_VERSION)
+        return null;
+    if (typeof value.event_id !== "string" || !UUID_PATTERN.test(value.event_id))
+        return null;
+    if (!isIntegerInRange(value.ts, 1, Date.now() + MAX_FUTURE_SKEW_MS))
+        return null;
+    if (typeof value.event !== "string" || !PANEL_EVENTS.has(value.event))
+        return null;
+    if (typeof value.backend !== "string" || !PANEL_BACKENDS.has(value.backend))
+        return null;
+    if (typeof value.used_cloud !== "boolean")
+        return null;
+    if (typeof value.mode !== "string" || !PANEL_MODES.has(value.mode))
+        return null;
+    if (!isNullableMetric(value.prompt_tokens) || !isNullableMetric(value.completion_tokens))
+        return null;
+    if (!isIntegerInRange(value.latency_ms, 0, MAX_LATENCY_MS))
+        return null;
+    if (value.model !== null && (typeof value.model !== "string" ||
+        value.model.length === 0 ||
+        value.model.length > MAX_MODEL_LENGTH ||
+        CONTROL_CHARACTER_PATTERN.test(value.model)))
+        return null;
+    const isEscalated = value.event === "panel_escalated";
+    if (value.used_cloud !== isEscalated)
+        return null;
+    if (isEscalated ? !CLOUD_BACKENDS.has(value.backend) : !LOCAL_BACKENDS.has(value.backend))
+        return null;
+    return value;
+}
+function toLedgerRow(event) {
+    return {
+        ts: event.ts,
+        caller: "panel",
+        mode: event.mode,
+        backend: event.backend,
+        model: event.model,
+        used_cloud: event.used_cloud,
+        gate_outcome: "success",
+        prompt_tokens: event.prompt_tokens ?? undefined,
+        completion_tokens: event.completion_tokens ?? undefined,
+        latency_ms: event.latency_ms,
+        source_event_id: event.event_id,
+    };
+}
+async function claimAvailableFiles(spoolPath) {
+    const directory = dirname(spoolPath);
+    await fs.mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
+    const lock = await acquireLock(`${spoolPath}${LOCK_SUFFIX}`);
+    if (!lock)
+        throw new Error("panel metrics spool is busy");
+    try {
+        const claims = [];
+        const base = basename(spoolPath);
+        const pendingPrefix = `${base}.pending-`;
+        const processingPrefix = `${base}.processing-`;
+        const names = await fs.readdir(directory).catch(error => {
+            if (hasErrorCode(error, "ENOENT"))
+                return [];
+            throw error;
+        });
+        for (const name of names) {
+            if (claims.length >= MAX_CLAIMS_PER_INGEST || !name.startsWith(pendingPrefix))
+                continue;
+            const claimed = await claimExisting(join(directory, name), spoolPath);
+            if (claimed)
+                claims.push(claimed);
+        }
+        for (const name of names) {
+            if (claims.length >= MAX_CLAIMS_PER_INGEST || !name.startsWith(processingPrefix))
+                continue;
+            const source = join(directory, name);
+            const stat = await fs.stat(source).catch(() => null);
+            if (!stat || Date.now() - stat.mtimeMs <= PROCESSING_STALE_MS)
+                continue;
+            const claimed = await claimExisting(source, spoolPath);
+            if (claimed)
+                claims.push(claimed);
+        }
+        if (claims.length < MAX_CLAIMS_PER_INGEST) {
+            const liveStat = await fs.stat(spoolPath).catch(error => {
+                if (hasErrorCode(error, "ENOENT"))
+                    return null;
+                throw error;
+            });
+            if (liveStat?.isFile() && liveStat.size > 0) {
+                const claim = processingPath(spoolPath);
+                await fs.rename(spoolPath, claim);
+                claims.push(claim);
+            }
+        }
+        return claims;
+    }
+    finally {
+        await releaseLock(lock);
+    }
+}
+async function claimExisting(source, spoolPath) {
+    const target = processingPath(spoolPath);
+    try {
+        await fs.rename(source, target);
+        return target;
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return null;
+        throw error;
+    }
+}
+async function returnClaimForRetry(claim) {
+    const spoolPath = getPanelMetricsSpoolPath();
+    const lock = await acquireLock(`${spoolPath}${LOCK_SUFFIX}`);
+    if (!lock)
+        return;
+    try {
+        const pending = `${spoolPath}.pending-${Date.now()}-${randomUUID()}`;
+        await fs.rename(claim, pending).catch(error => {
+            if (!hasErrorCode(error, "ENOENT"))
+                throw error;
+        });
+    }
+    finally {
+        await releaseLock(lock);
+    }
+}
+function processingPath(spoolPath) {
+    return `${spoolPath}.processing-${process.pid}-${Date.now()}-${randomUUID()}`;
+}
+async function acquireLock(lockPath) {
+    for (let attempt = 0; attempt <= LOCK_RETRY_DELAYS_MS.length; attempt++) {
+        const token = `${process.pid}:${randomUUID()}`;
+        try {
+            const handle = await fs.open(lockPath, "wx", FILE_MODE);
+            await handle.writeFile(token, "utf8");
+            return { path: lockPath, token, handle };
+        }
+        catch (error) {
+            if (!hasErrorCode(error, "EEXIST"))
+                return null;
+            await removeStaleLock(lockPath);
+            const delay = LOCK_RETRY_DELAYS_MS[attempt];
+            if (delay === undefined)
+                return null;
+            await wait(delay);
+        }
+    }
+    return null;
+}
+async function removeStaleLock(lockPath) {
+    try {
+        const stat = await fs.stat(lockPath);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+            await fs.unlink(lockPath).catch(() => undefined);
+        }
+    }
+    catch (error) {
+        if (!hasErrorCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function releaseLock(lock) {
+    await lock.handle.close().catch(() => undefined);
+    try {
+        const owner = await fs.readFile(lock.path, "utf8");
+        if (owner === lock.token)
+            await fs.unlink(lock.path);
+    }
+    catch (error) {
+        if (!hasErrorCode(error, "ENOENT"))
+            throw error;
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNullableMetric(value) {
+    return value === null || isIntegerInRange(value, 0, MAX_METRIC_VALUE);
+}
+function isIntegerInRange(value, minimum, maximum) {
+    return typeof value === "number" && Number.isInteger(value) && value >= minimum && value <= maximum;
+}
+function hasErrorCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error &&
+        error.code === code;
+}
+function wait(ms) {
+    return new Promise(resolvePromise => setTimeout(resolvePromise, ms));
+}

package/dist/storage/synalux.js

@@ -210,7 +210,24 @@ export class SynaluxStorage extends SupabaseStorage {
             user_id: userId,
             role,
         });
-        return (result.context ?? result);
+        // Current portals return the canonical flat `context`. Older deployed
+        // portals returned `{ handoff, recent_sessions }`; normalize that envelope
+        // here so the formatter can still see last_summary, TODOs, version, and
+        // session history during a rolling portal/client upgrade.
+        if (result.context === null)
+            return null;
+        if (result.context && typeof result.context === "object" && !Array.isArray(result.context)) {
+            return result.context;
+        }
+        if (result.handoff === null)
+            return null;
+        if (result.handoff && typeof result.handoff === "object" && !Array.isArray(result.handoff)) {
+            return {
+                ...result.handoff,
+                recent_sessions: Array.isArray(result.recent_sessions) ? result.recent_sessions : [],
+            };
+        }
+        return result;
     }
     // ─── Forget memory (GDPR surgical deletion) ──────────────────
     // Phase 3 Tier A: route both soft and hard delete through the

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

@@ -38,6 +38,7 @@ vi.mock("../../../src/storage/configStorage.js", () => ({
     getAllSettings: vi.fn(() => Promise.resolve({})),
     getSettingSync: vi.fn(() => ""),
     initConfigStorage: vi.fn(),
+    refreshConfigStorageCache: vi.fn(() => Promise.resolve()),
 }));
 vi.mock("../../../src/config.js", () => ({
     PRISM_USER_ID: "test-user-id",
@@ -394,6 +395,18 @@ describe("ledgerHandlers", () => {
             await sessionLoadContextHandler(validArgs);
             expect(storage.loadContext).toHaveBeenCalledWith("test-project", "standard", "test-user-id", undefined);
         });
+        it.each(["quick", "standard", "deep"])("uses dashboard context depth %s when the caller omits level", async (configuredLevel) => {
+            mockGetSetting.mockImplementation(async (key, fallback = "") => key === "default_context_depth" ? configuredLevel : fallback);
+            await sessionLoadContextHandler(validArgs);
+            expect(storage.loadContext).toHaveBeenCalledWith("test-project", configuredLevel, "test-user-id", undefined);
+        });
+        it("lets an explicit level override the dashboard and safely ignores stale invalid dashboard state", async () => {
+            mockGetSetting.mockImplementation(async (key, fallback = "") => key === "default_context_depth" ? "obsolete-depth" : fallback);
+            await sessionLoadContextHandler({ ...validArgs, level: "deep" });
+            expect(storage.loadContext).toHaveBeenLastCalledWith("test-project", "deep", "test-user-id", undefined);
+            await sessionLoadContextHandler(validArgs);
+            expect(storage.loadContext).toHaveBeenLastCalledWith("test-project", "standard", "test-user-id", undefined);
+        });
         it("loads context at 'quick' level", async () => {
             storage.loadContext.mockResolvedValue(null);
             await sessionLoadContextHandler({ project: "test-project", level: "quick" });

package/dist/tools/index.js

@@ -26,9 +26,9 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_BACKFILL_EMBEDDINGS_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs, SESSION_COGNITIVE_ROUTE_TOOL, isSessionCognitiveRouteArgs, SESSION_TASK_ROUTE_TOOL, isSessionTaskRouteArgs, ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABASE_TOOL, CONFIGURE_NOTIFICATIONS_TOOL, QUERY_MEMORY_NATURAL_TOOL } from "./sessionMemoryDefinitions.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, SESSION_BOOTSTRAP_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_BACKFILL_EMBEDDINGS_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs, SESSION_COGNITIVE_ROUTE_TOOL, isSessionCognitiveRouteArgs, SESSION_TASK_ROUTE_TOOL, isSessionTaskRouteArgs, ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABASE_TOOL, CONFIGURE_NOTIFICATIONS_TOOL, QUERY_MEMORY_NATURAL_TOOL } from "./sessionMemoryDefinitions.js";
 // 1. Ledger (Core CRUD & State)
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionSaveExperienceHandler, sessionSaveImageHandler, sessionViewImageHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler } from "./ledgerHandlers.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionSaveExperienceHandler, sessionSaveImageHandler, sessionViewImageHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler } from "./ledgerHandlers.js";
 // 2. Graph (Semantic Search & Weighting)
 export { sessionSearchMemoryHandler, knowledgeSearchHandler, sessionIntuitiveRecallHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeForgetHandler, knowledgeSyncRulesHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler } from "./graphHandlers.js";
 // 3. Hygiene (Maintenance & Integrity)