prism-mcp-server 20.8.1 → 20.8.2

package/README.md

@@ -116,6 +116,19 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.8.2
+
+- **Skill delivery now admits failure instead of hiding it.** A filesystem
+  permission edge case (a umask stripping the owner-execute bit) could leave
+  skill sync writing nothing while reporting itself current — measured at nine
+  days on a real machine. Broken managed directories are repaired in place,
+  every directory is created umask-proof, and the repair path refuses symlinks
+  via an `O_NOFOLLOW` descriptor.
+- **A stale install tells you at startup.** Prism now tracks the generation
+  that actually reached disk separately from the one the database accepted; if
+  they diverge, the startup banner says so in a warning placed where display
+  truncation cannot cut it. A successful sync clears it automatically.
+
 ## What's New in v20.7 – v20.8.0
 
 - **First run proves the memory instead of describing it** — `session_bootstrap`
@@ -608,10 +621,10 @@ for manual configuration and host-specific paths.
 **Optional — local model fleet** for offline tool-routing. Pull whichever fits your hardware:
 
 ```bash
-ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% routing accuracy)
-ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% accuracy)
-ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% accuracy, Qwen3.5)
-ollama pull dcostenco/prism-coder:27b   # 16 GB  · complex tasks (100% accuracy)
+ollama pull dcostenco/prism-coder:2b    # 2.3 GB · mobile / lightweight (99.1% on our routing suite)
+ollama pull dcostenco/prism-coder:4b    # 3.4 GB · verifier (100% on our routing suite)
+ollama pull dcostenco/prism-coder:9b    # 5.8 GB · default router (100% on our routing suite, Qwen3.5)
+ollama pull dcostenco/prism-coder:27b   # 16 GB  · complex tasks (100% on our routing suite)
 ```
 
 Prism detects both the namespaced (`dcostenco/prism-coder:9b`) and bare (`prism-coder:9b`) Ollama tags automatically.
@@ -632,6 +645,23 @@ Every conversation feeds a persistent store. The next session loads the right co
 
 The dashboard shows your current project state, pending TODOs, intent health, and a neural knowledge graph — all built automatically from your agent sessions.
 
+### Export — read the record outside the agent
+
+`session_export_memory` writes your memory out as plain files you can read,
+diff, and commit. Nothing goes through a model to produce it.
+
+```
+markdown   human-readable — drop it in a PR to show what the agent actually did
+json       machine-readable — import into another Prism instance
+vault      zipped Markdown with YAML frontmatter and [[wikilinks]] (Obsidian, Logseq)
+```
+
+This is the surface to reach for when you want to answer "did the agent verify
+this, or is it claiming it did?" — the export is a record you review after the
+fact, in a diff or a pull request, rather than a live view you have to go and
+open. The same data is available from the dashboard's **Export ZIP** and
+**Export Vault** buttons.
+
 ### Knowledge Graph — semantic + keyword + graph search
 
 Ask "what did I decide about the auth flow last month?" and get an answer with citations, combining vector similarity, full-text search, and graph traversal.
@@ -741,7 +771,7 @@ air-gap. **Enterprise** includes a HIPAA Business Associate Agreement.
 
 ## Models
 
-The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on BFCL function-calling and 100% on an internal 15-problem coding eval at $0 inference cost.
+The `prism-coder` fleet uses Qwen3.5 for MCP tool-routing AND general inference. The 9B and 27B are fine-tuned with LoRA (r=128, all 64 layers including DeltaNet); the 2B and 4B use stock Qwen3.5-4B at different quantization levels. The 27B scored 100% on our internal 115-case tool-routing suite and 100% on an internal 15-problem coding eval, at $0 inference cost. These are self-run evaluations, not [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) leaderboard submissions.
 
 `prism_infer` supports three modes: `route` (tool routing, fast, nothink), `chat` (conversation with thinking), and `code` (code generation with thinking). In chat/code modes, the model uses `<think>` blocks for chain-of-thought reasoning, which are stripped before the response is served. If the local model fails a quality gate (empty, think-only, or truncated), paid tiers automatically escalate to Gemini 3.6 Flash via the Synalux portal.
 
@@ -753,13 +783,17 @@ draft that may need correction—to Synalux for authenticated deterministic
 correction. Advertised custom host tools remain local. Set
 `route_guard: "local"` for a fully on-device route path.
 
-| Model | Ollama tag | Size | [BFCL](https://gorilla.cs.berkeley.edu/leaderboard.html) Accuracy | Role | Automatic routing tier |
+| Model | Ollama tag | Size | Routing accuracy¹ | Role | Automatic routing tier |
 |---|---|---|---|---|---|
 | Qwen3.5-4B Q3_K_M | `prism-coder:2b` | 2.3 GB | 99.1% × 3 seeds | iPhone / mobile first gate | Free |
 | Qwen3.5-4B Q4_K_M | `prism-coder:4b` | 3.4 GB | 100% × 3 seeds | Verifier | Free |
 | Qwen3.5-9B (LoRA) | `prism-coder:9b` | 5.8 GB | 100% × 3 seeds | Default router | Standard+ |
 | Qwen3.5-27B (LoRA) | `prism-coder:27b` | 16 GB | 100% × 3 seeds | Quality tier (DeltaNet, 28.5 tok/s) | Advanced+ |
 
+¹ Self-run on a narrow 115-case MCP tool-selection suite, 3 seeds. It says these
+models pick the right tool on our own eval, nothing more — not a general capability
+measure, and not an independent benchmark result. Full methodology caveats below.
+
 These tiers control automatic `prism_infer` selection, not Ollama itself. Any
 user can run any downloaded on-device model directly through Ollama on every
 plan.

package/dist/agentManifestSync.js

@@ -20,7 +20,8 @@
  * side.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdirUsable, repairOwnerAccess } from "./utils/usableDirectory.js";
+import { link, lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 const OWNER = "prism-mcp";
@@ -306,11 +307,14 @@ function isErrno(error, code) {
  * mid-run leaves files that the next run re-proves ownership of by digest.
  */
 export async function materializeAgentDefinitions(section, targetDir, render = renderClaudeAgent) {
-    await mkdir(targetDir, { recursive: true, mode: 0o700 });
+    // Same umask trap as the skill roots: a masked mkdir leaves a directory
+    // nothing can enter, and every write below it then fails.
+    await mkdirUsable(targetDir);
     const rootStat = await lstat(targetDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
         throw new Error("agent root must be a real directory");
     }
+    await repairOwnerAccess(targetDir, rootStat.mode);
     const indexPath = join(targetDir, INDEX);
     const index = await readIndex(indexPath);
     const owned = index?.files ?? {};

package/dist/skillManifestSync.js

@@ -1,12 +1,23 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { access, lstat, mkdtemp, open, readFile, readdir, readlink, realpath, rename, rm, writeFile, } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { applyManagedSkillManifest, getSetting, refreshConfigStorageCache, } from "./storage/configStorage.js";
+import { applyManagedSkillManifest, getSetting, refreshConfigStorageCache, setSetting, } from "./storage/configStorage.js";
 import { materializeAgentDefinitions, renderClaudeAgent, renderCodexAgent, renderGeminiAgent, resolveClaudeAgentsDir, resolveCodexAgentsDir, resolveGeminiAgentsDir, validateAgentSection, } from "./agentManifestSync.js";
 import { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } from "./tools/skillRouting.js";
 import { getSynaluxJwt, invalidateSynaluxJwt } from "./utils/synaluxJwt.js";
+import { mkdirUsable, repairOwnerAccess } from "./utils/usableDirectory.js";
+/**
+ * Generation whose files actually reached disk, as opposed to the generation
+ * the config DB accepted. They diverge exactly when materialization fails, and
+ * that divergence is what made the 2026-08-10 outage invisible: the DB half
+ * commits first (deliberately -- committed names are what let a crashed run
+ * prune obsolete skills offline on restart), so the client reported the new
+ * generation while every managed root stayed frozen for nine days. Only a
+ * completed materialization advances this key.
+ */
+export const MATERIALIZED_GENERATION_KEY = "skill_manifest:materialized_generation";
 const OWNER = "prism-skill-sync-v1";
 const MARKER = ".prism-managed.json";
 const INDEX = ".prism-managed-skills.json";
@@ -279,13 +290,13 @@ async function matchesIncomingSkill(path, skill) {
 }
 async function stageSkill(root, skill, generation) {
     const target = join(root, skill.name);
-    await mkdir(target, { recursive: true, mode: 0o700 });
+    await mkdirUsable(target);
     const digests = Object.create(null);
     for (const [file, encoded] of Object.entries(skill.files)) {
         const path = resolve(target, file);
         if (!path.startsWith(`${target}${sep}`))
             throw new Error(`unsafe resolved path: ${file}`);
-        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await mkdirUsable(dirname(path));
         await writeFile(path, decodeFile(encoded), { mode: 0o600 });
         digests[file] = encoded.digest;
     }
@@ -295,10 +306,23 @@ async function stageSkill(root, skill, generation) {
 }
 async function ensureRealDirectory(path) {
     if (!(await exists(path)))
-        await mkdir(path, { recursive: true, mode: 0o700 });
+        await mkdirUsable(path);
     const stat = await lstat(path);
     if (!stat.isDirectory() || stat.isSymbolicLink())
         throw new Error(`managed path must be a real directory: ${path}`);
+    // Existing-but-unusable is the failure this repairs. mkdir's mode is masked
+    // by the creating process's umask, so a umask carrying the owner-execute bit
+    // (0o100) yields drw------- — a directory nothing can enter. Every later
+    // mkdtemp then throws EACCES, materialization aborts, and the run reports
+    // "partial" to stderr the host does not surface.
+    //
+    // Measured 2026-08-10: this exact directory sat at 0o600 for NINE days.
+    // The config DB half of each sync committed the new generation and digests
+    // while the file half never ran, so the client reported itself current while
+    // every managed skill root stayed frozen at its 2026-08-01 content. Checking
+    // "is a real directory" without checking "can I use it" made the outage
+    // permanent — nothing in the loop ever repaired the mode.
+    await repairOwnerAccess(path, stat.mode);
 }
 async function removeExpiredTransactions(base) {
     const cutoff = Date.now() - TRANSACTION_RETENTION_MS;
@@ -517,10 +541,12 @@ async function readCommittedManifestNames() {
     }
 }
 async function materializeNative(manifest, agentsSkillsDir, hooks) {
-    await mkdir(agentsSkillsDir, { recursive: true, mode: 0o700 });
+    await mkdirUsable(agentsSkillsDir);
     const rootStat = await lstat(agentsSkillsDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
         throw new Error("native skills root must be a real directory");
+    // The readdir immediately below is the first thing an unusable root breaks.
+    await repairOwnerAccess(agentsSkillsDir, rootStat.mode);
     await quarantineLegacyDiscoveryArtifacts(agentsSkillsDir);
     // Transaction content must remain outside the native discovery root: some
     // hosts recursively scan it and would otherwise discover staged/pruned paid
@@ -529,6 +555,10 @@ async function materializeNative(manifest, agentsSkillsDir, hooks) {
     await ensureRealDirectory(transactionBase);
     await removeExpiredTransactions(transactionBase);
     const transactionRoot = await mkdtemp(join(transactionBase, "txn-"));
+    // mkdtemp is umask-masked too, and nothing else revisits this path. A
+    // persistent restrictive umask therefore produced a REPAIRED base holding a
+    // brand-new unusable txn-* directory -- the original outage one level deeper.
+    await repairOwnerAccess(transactionRoot, (await lstat(transactionRoot)).mode);
     const stageRoot = join(transactionRoot, "stage");
     const backupRoot = join(transactionRoot, "backup");
     await ensureRealDirectory(stageRoot);
@@ -771,10 +801,15 @@ async function fetchManifest(options) {
     return manifest;
 }
 async function acquireSyncLock(agentsSkillsDir, waitMs = LOCK_WAIT_MS) {
-    await mkdir(agentsSkillsDir, { recursive: true, mode: 0o700 });
+    await mkdirUsable(agentsSkillsDir);
     const rootStat = await lstat(agentsSkillsDir);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
         throw new Error("native skills root must be a real directory");
+    // Same repair as ensureRealDirectory. This site takes the lock before any
+    // materialization, so a root that exists without owner rwx fails here first —
+    // mkdir no-ops on an existing directory and every open below throws EACCES,
+    // with nothing in the loop restoring the mode.
+    await repairOwnerAccess(agentsSkillsDir, rootStat.mode);
     const lockPath = join(agentsSkillsDir, ".prism-sync.lock");
     const deadline = Date.now() + Math.max(0, waitMs);
     const token = randomUUID();
@@ -936,6 +971,10 @@ export async function synchronizeSkillManifest(options = {}) {
             native.conflicts.push(...outcome.conflicts);
         }
         const status = native.installed.length || native.updated.length || native.pruned.length ? "applied" : "unchanged";
+        // Reached only when every native root materialized. A failure above throws
+        // past this point, leaving the previous value so the mismatch persists and
+        // stays visible until a sync genuinely succeeds.
+        await setSetting(MATERIALIZED_GENERATION_KEY, manifest.generation);
         return {
             status,
             tier: manifest.tier,

package/dist/storage/configStorage.js

@@ -1,7 +1,8 @@
 import { createClient } from "@libsql/client";
 import { resolve, dirname } from "path";
 import { homedir } from "os";
-import { existsSync, mkdirSync } from "fs";
+import { existsSync } from "fs";
+import { mkdirUsableSync } from "../utils/usableDirectory.js";
 const PROTO_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 // We use a small, dedicated DB just for configuration settings.
 // This solves the chicken-and-egg problem: we need to know WHICH
@@ -33,7 +34,10 @@ function getClient() {
         // and libSQL throws SQLITE_CANTOPEN (error 14) without it.
         const dir = dirname(CONFIG_PATH);
         if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
+            // Not plain mkdirSync: recursive creation is umask-masked at every level,
+            // and this directory holds the entitlement snapshot, so it must be private
+            // and enterable regardless of the umask Prism happens to inherit.
+            mkdirUsableSync(dir);
         }
         configClient = createClient({
             url: `file:${CONFIG_PATH}`,

package/dist/tools/ledgerHandlers.js

@@ -31,6 +31,7 @@ import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
 import { getSetting, setSetting, getAllSettings, refreshConfigStorageCache } from "../storage/configStorage.js";
+import { MATERIALIZED_GENERATION_KEY } from "../skillManifestSync.js";
 import { mergeHandoff, dbToHandoffSchema, sanitizeForMerge } from "../utils/crdtMerge.js";
 import { resolveProject } from "../utils/projectResolver.js";
 import { isRecoverableStartupStorageError, LOCAL_STARTUP_FALLBACK_NOTICE, } from "../utils/startupRecovery.js";
@@ -205,10 +206,34 @@ function parseNativeSkillNames(value) {
 }
 async function resolveNativeSkillManifestSnapshot(syncResult) {
     const { FREE_NATIVE_SKILL_NAMES, REQUIRED_NATIVE_SKILL_NAMES } = await import("./skillRouting.js");
-    const [storedNamesValue, storedTierValue] = await Promise.all([
+    const [storedNamesValue, storedTierValue, committedGeneration, materializedGeneration] = await Promise.all([
         getSetting("skill_manifest:names", "[]"),
         getSetting("skill_manifest:tier", ""),
+        getSetting("skill_manifest:generation", ""),
+        // The exported constant, not a copied literal: a key rename on either
+        // side would otherwise leave this read returning "" forever -- warning
+        // permanently silent -- with both sides' tests still green, because each
+        // asserts against its own copy of the string.
+        getSetting(MATERIALIZED_GENERATION_KEY, ""),
     ]);
+    // The DB half of a sync commits before files are written, by design: the
+    // committed names are what let a crashed run prune obsolete skills offline on
+    // restart. The cost is that this snapshot can describe an entitlement whose
+    // files never landed. A DIVERGENCE here is that exact state, and it persists
+    // across sessions -- a later sync reports "unchanged" because nothing needed
+    // writing, while the roots agents actually read stay frozen. Unreported, it
+    // ran for nine days on 2026-08-10.
+    // An EMPTY marker is "never recorded", not "never delivered": every install
+    // that predates the marker has a committed generation and no marker at all,
+    // and an offline user's failed fetch must not scream STALE at them on
+    // upgrade day. A false alarm here trains people to ignore the line, which is
+    // how the real one gets waved through. The fresh-install failure case is
+    // still covered -- that run's own syncStatus is "partial" and the
+    // validated-partial branch already reports materialization incomplete.
+    const undeliveredGeneration = Boolean(committedGeneration) && Boolean(materializedGeneration) &&
+        committedGeneration !== materializedGeneration
+        ? committedGeneration
+        : "";
     const partialNamesInput = syncResult.status === "partial" && Array.isArray(syncResult.entitledNames)
         ? syncResult.entitledNames
         : null;
@@ -245,6 +270,7 @@ async function resolveNativeSkillManifestSnapshot(syncResult) {
         tier,
         source,
         syncStatus: syncResult.status,
+        undeliveredGeneration,
         conflicts: [...new Set(syncResult.conflicts)],
     };
 }
@@ -293,8 +319,24 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `directory out of the native skills folder and rerun \`prism connect\` ` +
             `(or a session bootstrap) to reinstall the managed copy.`
         : "";
+    // Durable, not per-run: a later sync reports "unchanged" while the roots stay
+    // frozen from an earlier failed materialization. This line is the difference
+    // between that outage being visible on the next startup and it running for
+    // nine days.
+    //
+    // Rendered directly UNDER the header, never appended at the tail:
+    // capNativeStartupText keeps the head and cuts the tail, so a tail-placed
+    // warning is the first thing truncated at capped depths -- observed live in
+    // the divergence simulation (STALE was line 19 of 20). The most important
+    // line goes where truncation cannot reach it.
+    const undeliveredWarning = snapshot.undeliveredGeneration
+        ? `\n> - ⚠️ **Skill files are STALE:** the entitlement DB is at generation ` +
+            `\`${snapshot.undeliveredGeneration.slice(0, 12)}…\` but its files never finished ` +
+            `reaching the skill roots. Agents are reading older skills. Run a sync ` +
+            `(restart the host or \`prism connect\`) and report this if it persists.`
+        : "";
     if (snapshot.source === "validated-partial") {
-        return `> **Prism System Ready**\n>\n` +
+        return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
             `> - 📦 **Entitled skills (materialization incomplete):** ${snapshot.names.length}\n` +
             `> - 📚 **Core/protected entitlements:** ${formatBoundedSkillNames(coreSkills, "entitled")}\n` +
@@ -306,7 +348,7 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             freeTierUpgradeLine(snapshot.tier);
     }
     if (snapshot.source === "tier-fallback") {
-        return `> **Prism System Ready**\n>\n` +
+        return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
             `> - 🛡️ **Fallback skill names:** ${formatBoundedSkillNames(snapshot.names, "fallback")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
@@ -314,7 +356,7 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             conflictWarning +
             freeTierUpgradeLine(snapshot.tier);
     }
-    return `> **Prism System Ready**\n>\n` +
+    return `> **Prism System Ready**\n>` + undeliveredWarning + `\n` +
         `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
         `> - 📦 **Provisioned skills:** ${snapshot.names.length}\n` +
         `> - 📚 **Core/protected skills provisioned:** ${formatBoundedSkillNames(coreSkills, "provisioned")}\n` +

package/dist/utils/usableDirectory.js

@@ -0,0 +1,150 @@
+/**
+ * Directory creation and repair that a restrictive umask cannot defeat.
+ *
+ * WHY THIS EXISTS (2026-08-10)
+ * Skill delivery died silently for nine days. `.prism-skill-transactions` had
+ * been created with `mkdir(..., { mode: 0o700 })`, but mkdir's mode is masked by
+ * the process umask: a umask carrying the owner-execute bit yields drw-------,
+ * a directory that can be read and written but never entered. Every subsequent
+ * mkdtemp threw EACCES, materialization aborted, and — because the config DB
+ * half of a sync commits before the file half — the client went on reporting the
+ * new generation while every managed skill root stayed frozen at older content.
+ *
+ * The first fix repaired a directory that was already broken and left the cause
+ * alone: a umask that is still restrictive masks every directory created after
+ * it, so a repaired base simply gained a brand-new unusable child. Node exposes
+ * no per-call umask, so the only portable defeat is to create one level at a
+ * time and repair what we just made.
+ *
+ * These helpers are shared rather than duplicated because the same trap exists
+ * anywhere Prism creates a private directory — skill roots, agent roots, and the
+ * config DB's parent — and a guard applied at two of three sites is not a guard.
+ */
+import { constants as fsConstants, chmodSync, lstatSync, mkdirSync } from "node:fs";
+import { chmod, lstat, mkdir, open } from "node:fs/promises";
+import { isAbsolute, sep } from "node:path";
+/** Mode every Prism-managed directory is created with and repaired to. */
+export const MANAGED_DIR_MODE = 0o700;
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && "code" in error
+        && error.code === code;
+}
+/**
+ * Restore owner rwx on a managed directory that exists but cannot be entered.
+ *
+ * Restores 0o700 EXACTLY rather than OR-ing owner bits onto whatever is there.
+ * These directories hold entitled skill content and pre-rollback backups;
+ * repairing 0o066 to 0o766 would "fix" an outage by leaving them world-readable.
+ *
+ * Prism-managed directories REQUIRE owner rwx, so a deliberate sharing mode that
+ * withholds it — 0o670, say — is discarded rather than preserved. Conventional
+ * sharing is unaffected: this only fires on a directory the owner cannot use,
+ * which is broken by any definition. A 0o770 directory is left untouched.
+ *
+ * Applies the change through an open descriptor, not the pathname. A pathname
+ * chmod re-resolves the path, so a process able to swap the directory for a
+ * symlink between the check and the change could redirect the permission change
+ * somewhere else entirely. fchmod acts on the object already opened.
+ *
+ * POSIX only. On Windows chmod maps to the read-only attribute alone and lstat
+ * reports 0o666 for every writable directory, so the condition can never be
+ * satisfied and the failure being repaired has no analogue there.
+ */
+export async function repairOwnerAccess(path, mode) {
+    if (process.platform === "win32")
+        return;
+    if ((mode & MANAGED_DIR_MODE) === MANAGED_DIR_MODE)
+        return;
+    let handle;
+    try {
+        // O_NOFOLLOW: a symlink at this path must fail the open rather than hand us
+        // a descriptor to whatever it points at.
+        handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    }
+    catch {
+        // Opening a directory needs owner-read, so the very modes this exists to
+        // repair (0o000, 0o300) land here — as does any symlink, via O_NOFOLLOW.
+        // An unguarded pathname chmod at this point re-opens the symlink hole: a
+        // link to an UNREADABLE file skipped the descriptor path entirely and got
+        // its target chmodded to 0o700. Proven with a live attack against the
+        // built helper during review, not hypothesized. lstat separates the two
+        // cases; the remaining lstat→chmod race is confined to unreadable real
+        // directories inside the user's own home.
+        const entry = await lstat(path);
+        if (!entry.isDirectory() || entry.isSymbolicLink()) {
+            throw new Error(`managed path is not a directory: ${path}`);
+        }
+        await chmod(path, MANAGED_DIR_MODE);
+        return;
+    }
+    try {
+        const opened = await handle.stat();
+        if (!opened.isDirectory())
+            throw new Error(`managed path is not a directory: ${path}`);
+        await handle.chmod(MANAGED_DIR_MODE);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Create a directory, and any missing ancestors, that the owner can enter.
+ *
+ * `recursive: true` applies the same masked mode to every level it creates, so
+ * under a hostile umask the first new ancestor is already untraversable and the
+ * call fails partway with EACCES before anything can repair it.
+ *
+ * Repairs ONLY directories this call creates. A pre-existing ancestor — $HOME
+ * and everything above it — keeps exactly the mode the user configured; silently
+ * widening those would be a worse bug than the one being fixed.
+ */
+export async function mkdirUsable(target) {
+    if (process.platform === "win32") {
+        await mkdir(target, { recursive: true, mode: MANAGED_DIR_MODE });
+        return;
+    }
+    const segments = target.split(sep).filter(Boolean);
+    let current = isAbsolute(target) ? "" : ".";
+    for (const segment of segments) {
+        current = current === "" ? `${sep}${segment}` : `${current}${sep}${segment}`;
+        try {
+            await mkdir(current, { mode: MANAGED_DIR_MODE });
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST"))
+                continue; // not ours — do not touch its mode
+            throw error;
+        }
+        await repairOwnerAccess(current, (await lstat(current)).mode);
+    }
+}
+/**
+ * Synchronous twin of {@link mkdirUsable}, for callers on a sync path.
+ *
+ * The config DB's parent is created before any await is possible, and it holds
+ * the entitlement snapshot, so it needs the same umask defeat and the same
+ * private mode. Kept beside the async version deliberately: two implementations
+ * of this rule in different files is how one of them ends up wrong.
+ */
+export function mkdirUsableSync(target) {
+    if (process.platform === "win32") {
+        mkdirSync(target, { recursive: true, mode: MANAGED_DIR_MODE });
+        return;
+    }
+    const segments = target.split(sep).filter(Boolean);
+    let current = isAbsolute(target) ? "" : ".";
+    for (const segment of segments) {
+        current = current === "" ? `${sep}${segment}` : `${current}${sep}${segment}`;
+        try {
+            mkdirSync(current, { mode: MANAGED_DIR_MODE });
+        }
+        catch (error) {
+            if (isErrno(error, "EEXIST"))
+                continue; // not ours — do not touch its mode
+            throw error;
+        }
+        if ((lstatSync(current).mode & MANAGED_DIR_MODE) !== MANAGED_DIR_MODE) {
+            chmodSync(current, MANAGED_DIR_MODE);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.8.1",
+  "version": "20.8.2",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Persistent session memory for AI coding agents that never leaves your machine \u2014 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",
@@ -82,7 +82,8 @@
     "ip-address": "^10.2.0",
     "protobufjs": "^7.6.5",
     "sharp": "^0.35.0",
-    "tar": "^7.5.19"
+    "tar": "^7.5.19",
+    "nanoid": "^3.3.17"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.92.0",