prism-mcp-server 20.18.1 → 20.18.2

package/dist/config.js

@@ -8,7 +8,10 @@ import { fileURLToPath } from "node:url";
  * validates required ones, and exports them for use throughout the server.
  *
  * Environment variable guide:
- *   BRAVE_API_KEY          — (required) API key for Brave Search Pro. Get one at https://brave.com/search/api/
+ *   BRAVE_API_KEY          — (required for search) API key for Brave Search Pro, and the only
+ *                            thing search needs in fully-local operation. A configured Synalux
+ *                            account supplies it portal-side instead, so exactly one of the two
+ *                            is needed. Get one at https://brave.com/search/api/
  *   GOOGLE_API_KEY         — (optional) API key for Google AI Studio / Gemini. Enables paper analysis.
  *   BRAVE_ANSWERS_API_KEY  — (optional) API key for Brave Answers (AI grounding). Enables brave_answers tool.
  *   SUPABASE_URL           — (optional) Your Supabase project URL. Enables session memory tools.
@@ -18,9 +21,15 @@ import { fileURLToPath } from "node:url";
  *   VOYAGE_API_KEY         — (optional) Voyage AI API key for embeddings.
  *                            Set embedding_provider=voyage to use. https://dash.voyageai.com
  *
- * If a required key is missing, the process exits immediately.
- * If an optional key is missing, a warning is logged but the server continues
- * with reduced functionality (the corresponding tools will be unavailable).
+ * No key is enforced at startup. Nothing here calls process.exit, so a missing
+ * key never stops the server — it starts with reduced functionality and the
+ * affected tools error when they are actually called. Missing keys log a
+ * warning, except BRAVE_API_KEY, which warns only under PRISM_DEBUG_LOGGING.
+ *
+ * Said plainly because the old wording ("the process exits immediately") was
+ * describing behaviour no key has ever had, and read as a hard startup
+ * dependency on a Brave + Firecrawl pair — see issue #188, filed on exactly
+ * that premise.
  */
 // ─── Server Identity ──────────────────────────────────────────
 function resolveServerVersion() {

package/dist/skillManifestSync.js

@@ -256,6 +256,109 @@ async function listFiles(root, current = root) {
     }
     return files.sort();
 }
+/**
+ * Artifacts nobody authors. ADMISSION RULE for these lists — an entry must be
+ * (1) machine-generated as a side effect of USING or BROWSING the directory,
+ * (2) regenerated on demand at no cost, and (3) never shippable content. Any
+ * other untracked file is a local edit and must keep conflicting. Do not widen
+ * this into "ignore files we do not recognise".
+ */
+const DERIVED_ARTIFACT_DIRS = new Set(["__pycache__"]);
+/** Compared lowercased: Explorer writes both `Thumbs.db` and `thumbs.db`. */
+const DERIVED_ARTIFACT_FILES = new Set([".ds_store", "thumbs.db", "desktop.ini"]);
+const DERIVED_ARTIFACT_EXT = /\.py[co]$/;
+function isDerivedArtifactFile(name) {
+    const lower = name.toLocaleLowerCase("en-US");
+    return DERIVED_ARTIFACT_FILES.has(lower) || DERIVED_ARTIFACT_EXT.test(lower);
+}
+/**
+ * Remove regenerable junk from a marker-owned skill directory.
+ *
+ * `isPristineMarkedSkill` compares the FULL recursive file list against the
+ * marker's key list, so ONE untracked file classifies the skill as a conflict —
+ * frozen, silently skipped by every later sync. Two ways that happens without
+ * anyone editing anything:
+ *
+ *   - CPython writes `__pycache__/<mod>.cpython-XX.pyc` beside any module it
+ *     IMPORTS (exec'ing a script does not). Observed 2026-09-14:
+ *     dead-link-prevention froze after something imported check_links.py.
+ *   - Finder drops `.DS_Store` into any directory a user OPENS, and Explorer
+ *     drops `Thumbs.db`/`desktop.ini`. Reproduced 2026-09-14: browsing a
+ *     managed skill folder is enough to stop it updating. Windows is a
+ *     supported host, so both families belong here.
+ *
+ * PURGE, never ignore. Exempting these from the integrity walk would turn a
+ * noisy false conflict into a code-execution hole: CPython loads a cached .pyc
+ * in preference to its source whenever the pyc header's recorded source mtime
+ * and size match the .py, and both of those fields live in the attacker-written
+ * pyc. An ignored .pyc is arbitrary bytecode that executes while sync still
+ * reports the skill pristine and keeps updating it. Deleting restores integrity
+ * instead — the next import regenerates the cache from the .py the marker
+ * actually verifies, and any OTHER untracked file still conflicts as before.
+ *
+ * Touches nothing Prism does not own, nothing the manifest shipped, and never
+ * follows a symlink out of the skill root.
+ */
+async function purgeDerivedArtifacts(path) {
+    // Self-guarding, not caller-guarded. Three sites call this now and the
+    // symlink check is the only thing standing between a delete primitive and an
+    // arbitrary target, so it lives HERE — a fourth caller that forgets to lstat
+    // must not be able to reintroduce the escape.
+    let rootStat;
+    try {
+        rootStat = await lstat(path);
+    }
+    catch {
+        return;
+    }
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        return;
+    const marker = await readJson(join(path, MARKER));
+    if (!marker || marker.owner !== OWNER || !marker.files || typeof marker.files !== "object")
+        return;
+    const shipped = new Set(Object.keys(marker.files));
+    const shippedPaths = [...shipped];
+    // BEST EFFORT, always. This runs inside materializeNative's try block before
+    // anything is staged, so letting an EACCES escape would convert one skill's
+    // junk file into a `partial` sync that freezes EVERY other skill — trading a
+    // one-skill problem for the whole-root outage shape this file's header
+    // describes. A delete we cannot do just means the pristine check conflicts
+    // that one skill, exactly as it did before this function existed.
+    const discard = async (child, recursive) => {
+        try {
+            await rm(child, { recursive, force: true });
+        }
+        catch { /* leave it; it conflicts */ }
+    };
+    const walk = async (current) => {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const child = join(current, entry.name);
+            const rel = relative(path, child).split(sep).join("/");
+            // Never follow a symlink out of the skill root; listFiles still rejects it.
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory()) {
+                const shippedUnder = shippedPaths.some((file) => file === rel || file.startsWith(`${rel}/`));
+                if (DERIVED_ARTIFACT_DIRS.has(entry.name) && !shippedUnder) {
+                    await discard(child, true);
+                    continue;
+                }
+                await walk(child);
+            }
+            else if (entry.isFile() && isDerivedArtifactFile(entry.name) && !shipped.has(rel)) {
+                await discard(child, false);
+            }
+        }
+    };
+    await walk(path);
+}
 async function isPristineMarkedSkill(path, generation) {
     const marker = await readJson(join(path, MARKER));
     if (!marker || marker.owner !== OWNER || (generation && marker.generation !== generation) ||
@@ -404,6 +507,12 @@ async function enforceNativeEntitlements(incomingNames, agentsSkillsDir) {
         const target = join(agentsSkillsDir, name);
         if (!(await exists(target)))
             continue;
+        // Same reason as the materialize paths: junk nobody wrote must not make a
+        // clean skill look hand-edited. Here the misread is quieter but permanent —
+        // the skill leaves discovery either way, but a false "locally modified"
+        // parks it in quarantine forever instead of deleting it, and nothing ever
+        // collects that directory.
+        await purgeDerivedArtifacts(target);
         if (await isPristineMarkedSkill(target)) {
             await rm(target, { recursive: true, force: true });
             continue;
@@ -604,6 +713,8 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
             if (!(await exists(target)))
                 continue;
             const stat = await lstat(target);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                await purgeDerivedArtifacts(target);
             const pristine = stat.isDirectory() && !stat.isSymbolicLink() && await isPristineManagedSkill(target, true);
             if (!pristine) {
                 // Preserve locally modified managed content, but quarantine it outside
@@ -659,6 +770,8 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
             }
             const stat = await lstat(target);
             const managedSkill = managedCandidates.has(skill.name);
+            if (stat.isDirectory() && !stat.isSymbolicLink())
+                await purgeDerivedArtifacts(target);
             if (!stat.isDirectory() || stat.isSymbolicLink() || !(await isPristineManagedSkill(target, managedSkill))) {
                 conflicts.push(skill.name);
                 if (managedSkill)

package/dist/tools/ledgerHandlers.js

@@ -496,13 +496,31 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
     const conflictSuffix = snapshot.conflicts.length > 0
         ? ` · ${snapshot.conflicts.length} conflict${snapshot.conflicts.length === 1 ? "" : "s"} — see warning`
         : "";
+    // Name the CONDITION, then hand over the procedure that reveals the cause.
+    // This used to read "local copy has no Prism ownership marker", which is one
+    // of several causes and not the common one. On 2026-09-14 dead-link-prevention
+    // tripped it with a marker that was present and digest-exact; the real cause
+    // was one extra untracked file. The sentence sent the operator to quarantine
+    // the directory and rerun `prism connect` (which rewrites host MCP config and
+    // wants every host closed) when the fix was deleting a regenerable cache dir.
+    // A wrong cause is worse than no cause: it buys a confident wrong repair.
+    //
+    // Deliberately a PROCEDURE, not an enumeration of causes. Listing all of them
+    // is both longer and weaker — a list still leaves the operator guessing, while
+    // the file-list-vs-marker diff names the offender outright. Length is not
+    // cosmetic here: this block renders in the HEAD, which capNativeStartupText
+    // keeps while cutting the tail, so every extra character evicts session
+    // context. An enumerated draft measured 858 chars — 21% of the whole 4,000
+    // quick budget, against 9% for the wrong-but-short original.
     const conflictWarning = snapshot.conflicts.length > 0
-        ? `\n> - ⚠️ **SKILLS NOT UPDATING (local copy has no Prism ownership marker):** ` +
+        ? `\n> - ⚠️ **SKILLS NOT UPDATING (on-disk copy differs from the managed one):** ` +
             `${formatBoundedSkillNames([...snapshot.conflicts].sort(), "blocked")}. ` +
-            `Each named skill is frozen at whatever version is on disk — updates are ` +
-            `withheld to protect local edits. To resume updates: move the skill's ` +
-            `directory out of the native skills folder and rerun \`prism connect\` ` +
-            `(or a session bootstrap) to reinstall the managed copy.`
+            `Each is frozen at whatever version is on disk — updates are withheld to ` +
+            `protect local edits. To see why, compare the directory's file list with ` +
+            `the \`files\` keys in its \`.prism-managed.json\`. An extra file you do ` +
+            `not need? Delete it; the next sync adopts the skill again. A local edit ` +
+            `you want to discard? Move the directory out of the native skills folder ` +
+            `and rerun \`prism connect\` (or a session bootstrap).`
         : "";
     // Durable, not per-run: a later sync reports "unchanged" while the roots stay
     // frozen from an earlier failed materialization. This line is the difference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.18.1",
+  "version": "20.18.2",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",