prism-mcp-server 20.6.0 → 20.7.1

package/dist/agentManifestSync.js

@@ -0,0 +1,417 @@
+/**
+ * Agent Definition Sync — materializes portal-served agent definitions
+ * (subagent routing policy: model tier, effort cap, tool surface) into
+ * Claude Code's agent root (~/.claude/agents/<name>.md).
+ *
+ * Deliberately separate from skillManifestSync's directory-package engine:
+ * agent definitions are SINGLE FILES, so this module implements file-level
+ * semantics with the same two protective properties the skill engine pins:
+ *
+ *   1. A hand-edited or foreign file is NEVER overwritten or deleted — it is
+ *      reported as a conflict and left byte-identical on disk.
+ *   2. Ownership is provable, not assumed: a file is "ours" only when its
+ *      current content digest matches the digest recorded in the sidecar
+ *      index at the time we last wrote it.
+ *
+ * The server contract (portal /api/v1/prism/skill-manifest) ships agents
+ * under separate `agents` + `agents_generation` fields precisely so that
+ * clients which predate this module ignore them; `generation` remains a
+ * skills-only hash. Do not fold agents into the skills generation on either
+ * side.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const OWNER = "prism-mcp";
+const INDEX = ".prism-agents.json";
+const SAFE_NAME = /^[A-Za-z0-9_-]+$/;
+const SHA256 = /^[a-f0-9]{64}$/i;
+const MAX_AGENTS = 64;
+const MAX_AGENT_BYTES = 256 * 1024;
+export function parseAgentDefinition(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+    if (!match)
+        return { fields: {}, body: content };
+    const fields = {};
+    for (const line of match[1].split("\n")) {
+        const entry = line.match(/^([A-Za-z_-]+):\s*(.*)$/);
+        if (entry)
+            fields[entry[1]] = entry[2].trim();
+    }
+    return { fields, body: content.slice(match[0].length) };
+}
+// ─── Host renderers ──────────────────────────────────────────
+//
+// The canonical format is Claude Code's agent markdown; other hosts receive a
+// translation of the universally-expressible subset. Model tier is
+// DELIBERATELY not translated: model namespaces are host-specific and rotate
+// (gpt-5.6-* today), so foreign hosts keep their own configured defaults
+// (codex: default_subagent_model) and only the proven effort/tool-surface
+// levers travel.
+/** Claude Code: the canonical content verbatim. */
+export const renderClaudeAgent = (agent) => ({
+    file: `${agent.name}.md`,
+    content: agent.content,
+});
+const CODEX_EFFORT = {
+    low: "low", medium: "medium", high: "high", xhigh: "high", max: "high",
+};
+function tomlString(value) {
+    return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`;
+}
+function tomlMultiline(value) {
+    // Escaping every backslash and quote keeps any body (including """ runs)
+    // valid inside a multiline basic string while preserving literal newlines.
+    return `"""\n${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"""`;
+}
+/**
+ * Codex: ~/.codex/agents/<name>.toml. Keys verified against codex 0.146.0:
+ * name, description, developer_instructions, model_reasoning_effort,
+ * sandbox_mode. A Bash-bearing tool surface implies the agent must execute
+ * reproductions, so it gets workspace-write; otherwise read-only.
+ */
+export const renderCodexAgent = (agent) => {
+    const { fields, body } = parseAgentDefinition(agent.content);
+    const effort = CODEX_EFFORT[fields.effort ?? ""];
+    const tools = (fields.tools ?? "").split(",").map((tool) => tool.trim());
+    const sandbox = tools.includes("Bash") ? "workspace-write" : "read-only";
+    const lines = [
+        `name = ${tomlString(agent.name)}`,
+        `description = ${tomlString(fields.description ?? agent.name)}`,
+        ...(effort ? [`model_reasoning_effort = ${tomlString(effort)}`] : []),
+        `sandbox_mode = ${tomlString(sandbox)}`,
+        `developer_instructions = ${tomlMultiline(body)}`,
+    ];
+    return { file: `${agent.name}.toml`, content: `${lines.join("\n")}\n` };
+};
+/**
+ * Gemini CLI: ~/.gemini/agents/<name>.md (verified loadAgentsFromDirectory:
+ * .md files, "_"-prefixed skipped). Frontmatter is reduced to the fields
+ * gemini understands; Claude-specific keys (tools/model/effort) are dropped
+ * rather than risked against a stricter parser. Coexists with the
+ * prism-connect agent policy that owns ~/.gemini/settings.json overrides.
+ */
+export const renderGeminiAgent = (agent) => {
+    const { fields, body } = parseAgentDefinition(agent.content);
+    const frontmatter = [
+        "---",
+        `name: ${agent.name}`,
+        `description: ${fields.description ?? agent.name}`,
+        "---",
+    ].join("\n");
+    return { file: `${agent.name}.md`, content: `${frontmatter}\n\n${body}` };
+};
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/**
+ * Parse the optional agents section of a skill-manifest payload.
+ * Returns null when the server predates agents (fields absent).
+ * Throws on a malformed section — the caller decides whether that is fatal;
+ * it must never be silently treated as "no agents", because that would turn
+ * contract drift into an invisible prune signal.
+ */
+export function validateAgentSection(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload))
+        return null;
+    const value = payload;
+    if (value.agents === undefined && value.agents_generation === undefined)
+        return null;
+    if (!Array.isArray(value.agents) || typeof value.agents_generation !== "string" ||
+        !SHA256.test(value.agents_generation)) {
+        throw new Error("invalid agent section");
+    }
+    if (value.agents.length > MAX_AGENTS)
+        throw new Error("agent section exceeds bounds");
+    const names = new Set();
+    const agents = value.agents.map((raw, index) => {
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            throw new Error(`invalid agent at index ${index}`);
+        const agent = raw;
+        if (typeof agent.name !== "string" || !SAFE_NAME.test(agent.name))
+            throw new Error(`invalid agent name at index ${index}`);
+        const folded = agent.name.toLocaleLowerCase("en-US");
+        if (names.has(folded))
+            throw new Error(`duplicate agent name: ${agent.name}`);
+        names.add(folded);
+        if (typeof agent.content !== "string" || !agent.content.trim())
+            throw new Error(`empty agent content: ${agent.name}`);
+        if (Buffer.byteLength(agent.content, "utf8") > MAX_AGENT_BYTES)
+            throw new Error(`agent definition too large: ${agent.name}`);
+        if (typeof agent.digest !== "string" || !SHA256.test(agent.digest) ||
+            sha256(Buffer.from(agent.content, "utf8")) !== agent.digest.toLowerCase()) {
+            throw new Error(`agent digest mismatch: ${agent.name}`);
+        }
+        return { name: agent.name, content: agent.content, digest: agent.digest.toLowerCase() };
+    });
+    return { agents, generation: value.agents_generation.toLowerCase() };
+}
+/**
+ * Claude Code's agent-definition root, mirroring the skill sync's detection
+ * guard: auto-detect only in the production default configuration so tests
+ * and custom-root callers stay isolated.
+ */
+export async function resolveClaudeAgentsDir(options = {}) {
+    if (options.claudeCodeAgentsDir === false)
+        return null;
+    if (typeof options.claudeCodeAgentsDir === "string")
+        return options.claudeCodeAgentsDir;
+    if (options.agentsSkillsDir !== undefined)
+        return null;
+    const claudeHome = join(options.homeDir ?? homedir(), ".claude");
+    try {
+        const stat = await lstat(claudeHome);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return join(claudeHome, "agents");
+}
+async function detectHostAgentsDir(hostHome) {
+    try {
+        const stat = await lstat(hostHome);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return join(hostHome, "agents");
+}
+/** Codex agent root (~/.codex/agents or $CODEX_HOME/agents), same guards. */
+export async function resolveCodexAgentsDir(options = {}) {
+    if (options.codexAgentsDir === false)
+        return null;
+    if (typeof options.codexAgentsDir === "string")
+        return options.codexAgentsDir;
+    if (options.agentsSkillsDir !== undefined)
+        return null;
+    const configured = (options.env ?? process.env).CODEX_HOME?.trim();
+    const codexHome = configured || join(options.homeDir ?? homedir(), ".codex");
+    return detectHostAgentsDir(codexHome);
+}
+/** Gemini CLI agent root (~/.gemini/agents), same guards. */
+export async function resolveGeminiAgentsDir(options = {}) {
+    if (options.geminiAgentsDir === false)
+        return null;
+    if (typeof options.geminiAgentsDir === "string")
+        return options.geminiAgentsDir;
+    if (options.agentsSkillsDir !== undefined)
+        return null;
+    return detectHostAgentsDir(join(options.homeDir ?? homedir(), ".gemini"));
+}
+const SAFE_FILE = /^[A-Za-z0-9_-]+\.(md|toml)$/;
+async function readIndex(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (parsed?.owner !== OWNER || typeof parsed.files !== "object" || !parsed.files)
+            return null;
+        const files = {};
+        for (const [name, entry] of Object.entries(parsed.files)) {
+            if (!SAFE_NAME.test(name) || !entry || typeof entry !== "object")
+                continue;
+            const { digest, file } = entry;
+            if (typeof digest === "string" && SHA256.test(digest) && typeof file === "string" && SAFE_FILE.test(file)) {
+                files[name] = { digest: digest.toLowerCase(), file };
+            }
+        }
+        return { owner: OWNER, generation: typeof parsed.generation === "string" ? parsed.generation : "", files };
+    }
+    catch {
+        return null;
+    }
+}
+async function currentDigest(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return null;
+        return sha256(await readFile(path));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Exclusive install: hard-link the temp file into place. Unlike rename(2),
+ * link(2) fails with EEXIST instead of overwriting, so a file that appears
+ * between our existence check and the install cannot be clobbered (TOCTOU).
+ * Returns false when the target already exists.
+ */
+async function installExclusive(dir, target, content) {
+    const temp = join(dir, `.prism-agent-${randomUUID()}.tmp`);
+    await writeFile(temp, content, { mode: 0o600 });
+    try {
+        await link(temp, target);
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, "EEXIST"))
+            return false;
+        // Filesystems without hard-link support (exFAT/FAT32, several SMB and
+        // container-volume mounts) reject link(2) outright. Without this fallback
+        // those users receive ZERO agent definitions and only a stderr line —
+        // the exclusivity hardening would have silently disabled the feature.
+        // rename(2) is marginally weaker against a concurrent writer inside the
+        // check→act window; delivering nothing is strictly worse.
+        if (isErrno(error, "EPERM") || isErrno(error, "ENOTSUP") ||
+            isErrno(error, "EOPNOTSUPP") || isErrno(error, "EXDEV")) {
+            if (await currentDigest(target) !== null)
+                return false;
+            await rename(temp, target);
+            return true;
+        }
+        throw error;
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/**
+ * Claim-then-verify mutation: atomically rename the target out of the root,
+ * re-hash the CLAIMED bytes, and only act when they still match the recorded
+ * digest. A mismatch (someone edited the file inside the check→act window)
+ * restores the file byte-identical and reports a conflict. This closes the
+ * check-then-act race CodeQL flags (js/file-system-race): after the rename we
+ * operate on a path no other writer targets, and the decision digest is
+ * computed from those exact bytes.
+ */
+async function claimVerified(dir, target, expectedDigest) {
+    const claimPath = join(dir, `.prism-agent-claim-${randomUUID()}.tmp`);
+    try {
+        await rename(target, claimPath);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            return "gone";
+        throw error;
+    }
+    const bytes = await readFile(claimPath);
+    if (sha256(bytes) !== expectedDigest) {
+        await rename(claimPath, target); // restore byte-identical
+        return "mismatch";
+    }
+    return { claimed: claimPath };
+}
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && "code" in error
+        && error.code === code;
+}
+/**
+ * Apply the agent section to a host agent root. Every write is an atomic
+ * tmp+rename of a single small file; the index commits last, so a crash
+ * 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 });
+    const rootStat = await lstat(targetDir);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
+        throw new Error("agent root must be a real directory");
+    }
+    const indexPath = join(targetDir, INDEX);
+    const index = await readIndex(indexPath);
+    const owned = index?.files ?? {};
+    const incoming = new Map();
+    for (const agent of section.agents) {
+        const rendered = render(agent);
+        if (rendered === null)
+            continue;
+        if (!SAFE_FILE.test(rendered.file))
+            throw new Error(`unsafe rendered agent file: ${rendered.file}`);
+        incoming.set(agent.name, rendered);
+    }
+    const installed = [];
+    const updated = [];
+    const pruned = [];
+    const conflicts = [];
+    const finalFiles = {};
+    // Downgrades first, mirroring the skill engine's ordering: entitlement
+    // removal must not depend on the success of later installs. Deletion is
+    // claim-then-verify: the digest that authorizes the rm is computed from the
+    // bytes AFTER they leave the discovery root, so an edit racing the check
+    // can never be destroyed.
+    for (const [name, entry] of Object.entries(owned)) {
+        if (incoming.has(name))
+            continue;
+        const target = join(targetDir, entry.file);
+        const claim = await claimVerified(targetDir, target, entry.digest);
+        if (claim === "gone")
+            continue; // already gone
+        if (claim === "mismatch") {
+            // Hand-edited content survives; we merely stop claiming it.
+            conflicts.push(name);
+            continue;
+        }
+        await rm(claim.claimed, { force: true });
+        pruned.push(name);
+    }
+    for (const [name, rendered] of incoming) {
+        const target = join(targetDir, rendered.file);
+        const renderedDigest = sha256(Buffer.from(rendered.content, "utf8"));
+        const digestOnDisk = await currentDigest(target);
+        if (digestOnDisk === null) {
+            // Exclusive install: a file appearing inside the window makes link()
+            // fail instead of being overwritten; re-judge it as foreign content.
+            if (await installExclusive(targetDir, target, rendered.content)) {
+                installed.push(name);
+                finalFiles[name] = { digest: renderedDigest, file: rendered.file };
+            }
+            else if (await currentDigest(target) === renderedDigest) {
+                finalFiles[name] = { digest: renderedDigest, file: rendered.file };
+            }
+            else {
+                conflicts.push(name);
+            }
+            continue;
+        }
+        const record = owned[name];
+        const pristine = record !== undefined && record.file === rendered.file && digestOnDisk === record.digest;
+        if (!pristine) {
+            if (digestOnDisk === renderedDigest) {
+                // Byte-identical foreign file: adopt without writing. Content equality
+                // is the strongest ownership evidence available for a single file.
+                finalFiles[name] = { digest: renderedDigest, file: rendered.file };
+            }
+            else {
+                conflicts.push(name);
+            }
+            continue;
+        }
+        if (digestOnDisk === renderedDigest) {
+            finalFiles[name] = { digest: renderedDigest, file: rendered.file };
+            continue;
+        }
+        // Update = claim the old version out (verifying the recorded digest on
+        // the claimed bytes), then exclusively install the new render. A racer
+        // in either window wins the file and we report a conflict instead of
+        // clobbering; the claimed old version is ours and safe to discard.
+        const claim = await claimVerified(targetDir, target, record.digest);
+        if (claim === "mismatch") {
+            conflicts.push(name);
+            continue;
+        }
+        const installedNow = await installExclusive(targetDir, target, rendered.content);
+        if (claim !== "gone")
+            await rm(claim.claimed, { force: true });
+        if (installedNow) {
+            updated.push(name);
+            finalFiles[name] = { digest: renderedDigest, file: rendered.file };
+        }
+        else {
+            conflicts.push(name);
+        }
+    }
+    const nextIndex = { owner: OWNER, generation: section.generation, files: finalFiles };
+    const tempIndex = join(targetDir, `${INDEX}.${randomUUID()}.tmp`);
+    await writeFile(tempIndex, `${JSON.stringify(nextIndex, null, 2)}\n`, { mode: 0o600 });
+    await rename(tempIndex, indexPath);
+    return {
+        installed: installed.sort(),
+        updated: updated.sort(),
+        pruned: pruned.sort(),
+        conflicts: [...new Set(conflicts)].sort(),
+    };
+}

package/dist/skillManifestSync.js

@@ -4,6 +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 { 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";
 const OWNER = "prism-skill-sync-v1";
@@ -763,6 +764,10 @@ async function fetchManifest(options) {
     if (!headers.Authorization && manifest.tier !== "free") {
         throw new Error("unauthenticated skill manifest must be free tier");
     }
+    // Agents ride the same response under separate fields. A malformed section
+    // is contract drift and must fail the fetch loudly — treating it as "no
+    // agents" would convert server corruption into a silent prune signal.
+    manifest.agentSection = validateAgentSection(payload);
     return manifest;
 }
 async function acquireSyncLock(agentsSkillsDir, waitMs = LOCK_WAIT_MS) {
@@ -851,6 +856,35 @@ async function acquireSyncLock(agentsSkillsDir, waitMs = LOCK_WAIT_MS) {
         }
     };
 }
+/**
+ * Converge every detected host's agent root onto the portal-validated agent
+ * section. Prefixed outcomes per host; a failure on one host degrades to a
+ * conflict rather than aborting the others or the skill result.
+ */
+async function materializeAgentsAcrossHosts(section, options) {
+    const result = { installed: [], updated: [], pruned: [], conflicts: [] };
+    const hostTargets = [
+        { prefix: "agent", dir: await resolveClaudeAgentsDir(options), render: renderClaudeAgent },
+        { prefix: "agent-codex", dir: await resolveCodexAgentsDir(options), render: renderCodexAgent },
+        { prefix: "agent-gemini", dir: await resolveGeminiAgentsDir(options), render: renderGeminiAgent },
+    ];
+    for (const host of hostTargets) {
+        if (!host.dir)
+            continue;
+        try {
+            const outcome = await materializeAgentDefinitions(section, host.dir, host.render);
+            result.installed.push(...outcome.installed.map((name) => `${host.prefix}:${name}`));
+            result.updated.push(...outcome.updated.map((name) => `${host.prefix}:${name}`));
+            result.pruned.push(...outcome.pruned.map((name) => `${host.prefix}:${name}`));
+            result.conflicts.push(...outcome.conflicts.map((name) => `${host.prefix}:${name}`));
+        }
+        catch (error) {
+            console.error(`[Prism Skill Sync] ${host.prefix} materialization failed: ${error instanceof Error ? error.message : String(error)}`);
+            result.conflicts.push(`${host.prefix}:sync-failed`);
+        }
+    }
+    return result;
+}
 export async function synchronizeSkillManifest(options = {}) {
     const empty = { installed: [], updated: [], pruned: [], conflicts: [] };
     let nativeSkillsDirs = [];
@@ -890,6 +924,17 @@ export async function synchronizeSkillManifest(options = {}) {
             nativeResults.push(await materializeNative(manifest, nativeSkillsDir, options));
         }
         const native = mergeNativeResults(nativeResults);
+        // Agent definitions are additive: they piggyback on the manifest with
+        // their own generation, and each host's outcome reports under its own
+        // prefix. A failure on one host never rolls back skill state or the
+        // other hosts — it surfaces as a conflict instead.
+        if (manifest.agentSection) {
+            const outcome = await materializeAgentsAcrossHosts(manifest.agentSection, options);
+            native.installed.push(...outcome.installed);
+            native.updated.push(...outcome.updated);
+            native.pruned.push(...outcome.pruned);
+            native.conflicts.push(...outcome.conflicts);
+        }
         const status = native.installed.length || native.updated.length || native.pruned.length ? "applied" : "unchanged";
         return {
             status,
@@ -915,6 +960,19 @@ export async function synchronizeSkillManifest(options = {}) {
                 catch (enforcement) {
                     enforcementErrors.push(`${nativeSkillsDir}: ${enforcement instanceof Error ? enforcement.message : String(enforcement)}`);
                 }
+            // Agent definitions need the SAME downgrade guarantee as skills. Without
+            // this, a tier downgrade whose DB apply throws prunes paid skills but
+            // leaves paid agent definitions in every host root until some later
+            // successful sync — exactly the local-fault-becomes-entitlement-bypass
+            // the skill path above exists to prevent.
+            if (manifest.agentSection) {
+                try {
+                    await materializeAgentsAcrossHosts(manifest.agentSection, options);
+                }
+                catch (enforcement) {
+                    enforcementErrors.push(`agents: ${enforcement instanceof Error ? enforcement.message : String(enforcement)}`);
+                }
+            }
             enforcementError = enforcementErrors.length > 0
                 ? `; entitlement cleanup failed: ${enforcementErrors.join(", ")}`
                 : "";

package/dist/storage/index.js

@@ -158,12 +158,36 @@ export async function getStorage() {
     return storageInstance;
 }
 export async function closeStorage() {
-    if (storageInstance) {
-        await storageInstance.close();
+    if (!storageInstance)
+        return;
+    const closing = storageInstance;
+    // Clear the slot in `finally`: if close() throws, the previous code left a
+    // DEAD instance installed as the singleton, and every later getStorage()
+    // handed that broken connection to callers. An empty slot is strictly
+    // safer — the next getStorage() re-opens cleanly. The error still
+    // propagates, so a caller like restoreFromBackup can abort before swapping
+    // the database file.
+    try {
+        await closing.close();
+    }
+    finally {
         storageInstance = null;
     }
 }
-/** Test-only: inject a pre-initialized storage instance into the singleton slot. */
+/**
+ * Test-only: inject a pre-initialized storage instance into the singleton slot.
+ *
+ * CONTRACT: the CALLER owns the lifecycle of what it injects. This function
+ * deliberately does NOT close the instance it replaces — callers pair the
+ * injection with their own cleanup (see createTestDb().cleanup), so closing
+ * here would double-close a storage the test still owns.
+ *
+ * Worth knowing when auditing handle leaks: an instance dropped without
+ * close() keeps its sqlite lock, and on Windows that lock blocks unlink of
+ * the database file until the process exits (libsql close() does not release
+ * it either — tursodatabase/libsql-js#228 — so closing is hygiene, not a
+ * guarantee).
+ */
 export function _setStorageForTesting(instance) {
     storageInstance = instance;
 }

package/dist/tools/ledgerHandlers.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as nodePath from "node:path";
 import * as os from "node:os";
+import * as http from "node:http";
 import { randomUUID } from "node:crypto";
 import { redactSettings, toMarkdown } from "./commonHelpers.js";
 import { scanAndRedactPHI } from "../utils/phiGuard.js";
@@ -24,11 +25,12 @@ import { buildVaultDirectory } from "../utils/vaultExporter.js";
  * ═══════════════════════════════════════════════════════════════════
  */
 import { debugLog } from "../utils/logger.js";
+import { FREE_ENTITLEMENTS } from "../utils/entitlements.js";
 import { getStorage, activeStorageBackend } from "../storage/index.js";
 import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
 import { getCurrentGitState, getGitDrift } from "../utils/git.js";
-import { getSetting, getAllSettings, refreshConfigStorageCache } from "../storage/configStorage.js";
+import { getSetting, setSetting, getAllSettings, refreshConfigStorageCache } from "../storage/configStorage.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";
@@ -300,7 +302,8 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `> - 🛠️ **Other tier entitlements:** ${formatBoundedSkillNames(otherTierSkills, "entitled")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
             `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · native materialization incomplete${conflictSuffix}` +
-            conflictWarning;
+            conflictWarning +
+            freeTierUpgradeLine(snapshot.tier);
     }
     if (snapshot.source === "tier-fallback") {
         return `> **Prism System Ready**\n>\n` +
@@ -308,7 +311,8 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `> - 🛡️ **Fallback skill names:** ${formatBoundedSkillNames(snapshot.names, "fallback")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
             `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · no committed manifest${conflictSuffix}` +
-            conflictWarning;
+            conflictWarning +
+            freeTierUpgradeLine(snapshot.tier);
     }
     return `> **Prism System Ready**\n>\n` +
         `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
@@ -318,7 +322,62 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
         `> - 🛠️ **Other tier skills provisioned:** ${formatBoundedSkillNames(otherTierSkills, "provisioned")}\n` +
         `> - 🧠 **Context depth:** ${depth}\n` +
         `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · committed manifest${conflictSuffix}` +
-        conflictWarning;
+        conflictWarning +
+        freeTierUpgradeLine(snapshot.tier);
+}
+/**
+ * The paid funnel's one startup line. Before 2026-08-05 the upgrade_url was
+ * surfaced only AFTER a user hit an entitlement gate (sessionDriftHandler,
+ * queryMemoryNaturalHandler); the startup path — the only guaranteed
+ * impression — referenced it zero times.
+ */
+function freeTierUpgradeLine(tier) {
+    if (tier !== "free")
+        return "";
+    return `\n> - 💎 **Free tier:** paid plans unlock the full skill library, ` +
+        `super-skills, and agent routing → ${FREE_ENTITLEMENTS.upgrade_url}`;
+}
+/**
+ * Dashboard URL for startup output. The bound port is announced on stderr
+ * only (MCP stdio owns stdout), so users never saw it; the dashboard also
+ * writes the port to ~/.prism-mcp/dashboard.port — read that, then the env
+ * override, then the default.
+ */
+async function readDashboardUrl() {
+    // Precedence: explicit env override > recorded port file > default. The
+    // file is written by whatever dashboard ran last and persists across boots,
+    // so it must never outrank configuration the operator set for THIS process.
+    let port = (process.env.PRISM_DASHBOARD_PORT || "").trim();
+    if (!port) {
+        try {
+            const recorded = fs.readFileSync(nodePath.join(os.homedir(), ".prism-mcp", "dashboard.port"), "utf8").trim();
+            if (/^\d{2,5}$/.test(recorded))
+                port = recorded;
+        }
+        catch {
+            // port file absent — dashboard not started yet this boot; default holds
+        }
+    }
+    if (!port)
+        port = "3000";
+    // The port file persists across boots and is never cleaned up, so it is
+    // evidence of a PREVIOUS dashboard, not a running one. Advertising a dead
+    // URL as the first-run headline action is worse than omitting it.
+    //
+    // A TCP connect is NOT sufficient: it proves something is listening, not
+    // that it is Prism. The default is 3000 — the single most commonly occupied
+    // port on a developer machine — so a bare liveness check would confidently
+    // point a first-run user at their own dev server. Hit the dashboard's
+    // /api/health instead, so identity is verified rather than assumed.
+    const healthy = await new Promise((resolveProbe) => {
+        const request = http.get({ host: "127.0.0.1", port: Number(port), path: "/api/health", timeout: 300 }, (response) => {
+            response.resume(); // drain so the socket can close
+            resolveProbe(response.statusCode === 200);
+        });
+        request.once("timeout", () => { request.destroy(); resolveProbe(false); });
+        request.once("error", () => resolveProbe(false));
+    });
+    return healthy ? `http://localhost:${port}` : null;
 }
 function capNativeStartupText(text, level, requestedMaxChars, suffix = "") {
     const maxChars = effectiveNativeBudget(level, requestedMaxChars);
@@ -1668,15 +1727,57 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
     const role = sanitizeNativeIdentity(defaultRole) || "global";
     const manifestSnapshot = await resolveNativeSkillManifestSnapshot(skillSyncResult);
     const systemReadyBlock = await buildNativeSystemReadyBlock(manifestSnapshot, depth);
-    const greeting = `👋 Welcome back, ${greetingName}. Prism is loading ${depth} context.`;
+    // First run = the dashboard has never been touched: no agent identity AND no
+    // projects. Measured 2026-08-05: a brand-new free-tier install was greeted
+    // with "Welcome back", three "Not loaded" rows, a warning, and three
+    // statements of what it doesn't have — an all-absence payload with no next
+    // step, no dashboard URL (stderr-only), and no path to the paid tier.
+    // First run must mean NEW, not merely unconfigured: a user with saved
+    // sessions who never set a name or projects would otherwise be told "first
+    // run detected" every single session. A durable marker is written after the
+    // first bootstrap, so this is decisive rather than heuristic.
+    const bootstrapSeen = (await getSetting("first_bootstrap_at", "")).trim();
+    const isFirstRun = projects.length === 0 && !configuredGreetingName && !bootstrapSeen;
+    if (!bootstrapSeen) {
+        try {
+            await setSetting("first_bootstrap_at", new Date().toISOString());
+        }
+        catch {
+            // Marker is an optimization; a write failure must never block startup.
+        }
+    }
+    const greeting = isFirstRun
+        ? `👋 Welcome to Prism — first run detected. Let's get you productive in a few minutes.`
+        : `👋 Welcome back, ${greetingName}. Prism is loading ${depth} context.`;
     const identityBlock = `- 🤖 **Agent Identity:** ${escapeNativeMarkdown(compactWithOmissionCount(role, 80))} — ${greetingName}`;
-    const startupHeader = `${greeting}\n\n${identityBlock}`;
+    const startupHeader = isFirstRun ? greeting : `${greeting}\n\n${identityBlock}`;
     if (projects.length === 0) {
+        const dashboardUrl = await readDashboardUrl();
+        const dashboardLine = dashboardUrl
+            ? `- 🎛️ **Dashboard:** ${dashboardUrl} — configure projects, identity, and context depth`
+            : `- 🎛️ **Dashboard:** not running — start Prism's dashboard to configure projects, identity, and context depth`;
+        if (isFirstRun) {
+            // Action-first instead of absence-first: every line is a capability or
+            // a next step. The wizard exists and is well-built; route to it.
+            const firstRunText = `${greeting}\n\n` +
+                `- 🚀 **Get started:** run the \`onboarding_wizard\` tool (guided setup, ~3 minutes)\n` +
+                `${dashboardLine}\n` +
+                `- 💾 **Already working?** \`session_save_ledger\` records this session; the next one resumes with full context\n\n` +
+                `${systemReadyBlock}`;
+            return {
+                content: [{
+                        type: "text",
+                        text: capNativeStartupText(firstRunText, depth),
+                    }],
+                isError: false,
+                structuredContent: { conversation_id: conversationId, projects: [], depth, first_run: true },
+            };
+        }
         const unconfiguredState = (depth === "quick" ? "" : `\n- 📝 **Last Session Summary:** Not loaded`) +
             `\n- ✅ **Open TODOs:** Not loaded` +
             `\n- 🔄 **Session Version:** Not loaded`;
         const noProjectsText = `${startupHeader}${unconfiguredState}\n\n` +
-            `⚠️ No Auto-Load Projects are configured in the Prism dashboard.\n\n${systemReadyBlock}`;
+            `⚠️ No Auto-Load Projects are configured in the Prism dashboard.\n${dashboardLine}\n\n${systemReadyBlock}`;
         return {
             content: [{
                     type: "text",

package/dist/tools/sessionMemoryDefinitions.js

@@ -1462,8 +1462,8 @@ export const ONBOARDING_WIZARD_TOOL = {
     description: "Interactive setup wizard for new Prism users. Provides a step-by-step " +
         "guided experience to get productive in under 3 minutes.\n\n" +
         "**Actions:**\n" +
-        "- `start` — Begin the wizard from step 1\n" +
-        "- `next` — Advance to the next step\n" +
+        "- `start` (default when omitted) — Begin the wizard from step 1\n" +
+        "- `next` — Advance past `step` (pass the step number you are on)\n" +
         "- `status` — Check current wizard progress\n" +
         "- `skip` — Skip to completion\n\n" +
         "Each step returns instructions, code snippets, and progress percentage.",
@@ -1473,7 +1473,12 @@ export const ONBOARDING_WIZARD_TOOL = {
             action: {
                 type: "string",
                 enum: ["start", "next", "status", "skip"],
-                description: "Wizard action to perform.",
+                description: "Wizard action to perform. Omitted = start.",
+            },
+            step: {
+                type: "integer",
+                minimum: 0,
+                description: "The step_index from the previous response; used by `next` and `status`.",
             },
             project_name: {
                 type: "string",
@@ -1485,16 +1490,21 @@ export const ONBOARDING_WIZARD_TOOL = {
                 description: "IDE client for config generation.",
             },
         },
-        required: ["action"],
     },
 };
 export function isOnboardingWizardArgs(args) {
     if (typeof args !== "object" || args === null)
         return false;
     const a = args;
-    if (typeof a.action !== "string")
-        return false;
-    if (!["start", "next", "status", "skip"].includes(a.action))
+    // A bare call is the front door for brand-new users (the startup greeting
+    // routes here) — it must work, defaulting to `start`. Measured 2026-08-05:
+    // requiring `action` made the tool the first thing a new user touches AND
+    // the first error they see.
+    if (a.action !== undefined &&
+        (typeof a.action !== "string" || !["start", "next", "status", "skip"].includes(a.action))) {
+        return false;
+    }
+    if (a.step !== undefined && (!Number.isInteger(a.step) || a.step < 0))
         return false;
     if (a.project_name !== undefined && typeof a.project_name !== "string")
         return false;

package/dist/tools/v12Handlers.js

@@ -11,7 +11,6 @@
  */
 import { debugLog } from "../utils/logger.js";
 import { isOnboardingWizardArgs, isExtractEntitiesArgs, isBackupDatabaseArgs, isConfigureNotificationsArgs, } from "./sessionMemoryDefinitions.js";
-// ─── Onboarding Wizard Handler ───────────────────────────────
 export async function onboardingWizardHandler(args) {
     if (!isOnboardingWizardArgs(args)) {
         return {
@@ -19,7 +18,18 @@ export async function onboardingWizardHandler(args) {
             isError: true,
         };
     }
-    const { step, responses } = args;
+    // The schema advertises action-based navigation while this handler
+    // historically read `{step, responses}` — fields the validator never
+    // passed, so `next`/`status`/`skip` all silently rendered step 1 and a
+    // bare call was rejected outright (measured 2026-08-05). Map the
+    // advertised contract onto the stateless wizard: the client carries the
+    // step number between calls.
+    const action = args.action ?? "start";
+    const currentStep = typeof args.step === "number" ? args.step : 0;
+    const step = action === "start" ? undefined
+        : action === "next" ? currentStep + 1
+            : action === "status" ? currentStep
+                : Number.MAX_SAFE_INTEGER; // skip → past the final step = completion
     try {
         const wizard = await import("../onboarding/wizard.js");
         if (step === undefined || step === null) {
@@ -32,6 +42,7 @@ export async function onboardingWizardHandler(args) {
                         text: JSON.stringify({
                             status: "in_progress",
                             current_step: state.currentStep,
+                            step_index: 0,
                             total_steps: 8,
                             step: content,
                             summary: wizard.getWizardSummary(state),
@@ -39,12 +50,15 @@ export async function onboardingWizardHandler(args) {
                     }],
             };
         }
-        // Advance to next step
+        // Advance to the requested step position. Wizard steps are NAMED
+        // ("welcome", "storage", …); the numeric step_index in every response
+        // is what clients echo back for `next`/`status`.
         const state = wizard.createWizardState();
-        // Advance to the requested step position
         let currentState = state;
-        for (let i = 0; i < step; i++) {
+        let stepIndex = 0;
+        for (let i = 0; i < step && !wizard.isWizardComplete(currentState); i++) {
             currentState = wizard.advanceWizard(currentState);
+            stepIndex += 1;
         }
         if (wizard.isWizardComplete(currentState)) {
             return {
@@ -66,6 +80,7 @@ export async function onboardingWizardHandler(args) {
                     text: JSON.stringify({
                         status: "in_progress",
                         current_step: currentState.currentStep,
+                        step_index: stepIndex,
                         step: content,
                         summary: wizard.getWizardSummary(currentState),
                     }, null, 2),

package/dist/utils/analytics.js

@@ -50,6 +50,16 @@ async function ensureTable() {
 }
 /** Reset DB connection and in-memory buffer (for tests). */
 export function _resetDb() {
+    // Close before dropping the reference. Nulling alone leaks the underlying
+    // sqlite handle: harmless on POSIX (unlink works on open files), but on
+    // Windows the file stays locked, so a suite that resets between cases
+    // accumulates locks on the analytics DB and cannot clean up its temp dir.
+    try {
+        _db?.close();
+    }
+    catch {
+        // A close failure must never break a test reset.
+    }
     _db = null;
     _tableReady = false;
     BUFFER.length = 0;

package/dist/utils/backup.js

@@ -165,7 +165,24 @@ export async function restoreFromBackup(dbPath, backupPath) {
         // Create pre-restore backup
         const preRestoreResult = await createBackup(dbPath);
         debugLog(`Pre-restore backup: ${preRestoreResult.success ? "OK" : "FAILED"}`);
-        // Copy backup over current database
+        // Release the live connection BEFORE swapping the file underneath it.
+        //
+        // NOT a platform workaround. Measured on windows-x64 (2026-08-05):
+        // overwriting the database while a connection is open SUCCEEDS on
+        // every platform — SQLite shares the file for reading and writing,
+        // and only unlink/rename are blocked. So restore was never broken.
+        //
+        // The reason is correctness: replacing a database file beneath a live
+        // connection leaves that connection pointing at bytes it did not
+        // read, with a stale page cache and a WAL that no longer describes
+        // the file. SQLite documents this as unsafe. closeStorage() makes the
+        // swap atomic from the connection's point of view — the next
+        // getStorage() opens the restored file cleanly.
+        const { closeStorage } = await import("../storage/index.js");
+        await closeStorage();
+        // Copy backup over current database. closeStorage() cleared the
+        // singleton, so the next getStorage() re-opens against the restored
+        // file and no caller retains a handle to the replaced one.
         copyFileSync(backupPath, dbPath);
         return {
             success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.6.0",
+  "version": "20.7.1",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder \u2014 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\u201332B open-weights LLM fleet.",
   "module": "index.ts",