prism-mcp-server 20.5.3 → 20.7.0

package/README.md

@@ -56,11 +56,120 @@ Prism works locally without an account, API key, or cloud subscription. Add a
 Synalux subscription when you want cloud memory, paid-tier skills, or team
 features.
 
+### What `prism connect` changes about host subagents
+
+`connect` steers bounded work to `prism_infer` on your machine rather than to
+host-spawned agents. What it writes differs per host, and **it does not disable
+subagents everywhere** — Claude Code keeps them and is pointed at an economy
+model instead. Prism's local workers stay available over MCP in every case.
+
+| Host | Setting written | Effect |
+|---|---|---|
+| Claude Code | `env.CLAUDE_CODE_SUBAGENT_MODEL = "sonnet"` in `~/.claude/settings.json` | Subagents stay **enabled**, pinned to an economy model. Fan-out is discouraged by policy text, not by config |
+| Gemini CLI | `experimental.enableAgents = false` in `~/.gemini/settings.json` | Subagents **off**. Gemini exposes one boolean, so that is all there is to set |
+| Codex | `features.multi_agent = false` in `$CODEX_HOME/config.toml` (default `~/.codex`), plus a bounded fallback: 2 threads, depth 1, cheap subagent model, 900s cap | Subagents **off**, with a bounded profile underneath so a deliberate re-enable lands somewhere sane |
+
+Two things worth knowing:
+
+- **`experimental` is Gemini's namespace, not ours.** Prism is not enabling
+  anything experimental — it writes `false` to a flag Gemini already defines at
+  that path. Writing anywhere else would have no effect.
+- **That namespace is by definition temporary.** If Gemini promotes
+  `enableAgents` out of `experimental`, Prism keeps writing the old path, Gemini
+  reads the new one, and host subagents quietly turn back on. Nothing errors and
+  the settings file still looks correct. If you see host subagents running while
+  `enableAgents` reads `false`, check whether the key has moved before assuming
+  `connect` failed to write it.
+
+Both writes are idempotent in the sense that a host already configured this way
+is left untouched — but they are **re-applied on every `prism connect` run**,
+not only on `--refresh`. If you deliberately re-enable host subagents, the next
+`connect` will turn them off again. Keep them on by not re-running `connect`,
+or by re-enabling after each run.
+
 ---
 
 <details>
 <summary>Release history (optional)</summary>
 
+## What's New in v20.6.0
+
+### Delivery Is Not a Suggestion
+
+An audit of a real incident (an agent wiped demo data after *announcing* the
+wipe — with the ask-first rule committed, bundled, and absent from what any
+agent actually received) found the protected floor had outgrown every delivery
+budget: "unprotected" had quietly come to mean "never delivered".
+
+- **`ask-first` and `feature-preservation` join the protected floor** (14 → 16).
+  Protected skills are always inlined; these two now reach every session.
+- **Sync conflicts are loud and named.** Startup used to say "· 2 local
+  conflicts preserved" while safety skills sat months stale; it now names each
+  frozen skill and states how to resume updates.
+- **`--storage` accepts `auto` and `synalux`** — the CLI rejected its own
+  documented default and the production backend.
+- **Disclosure:** skill delivery informs; it does not gate. A live probe showed
+  a host agent still edit unverified source with the rule loaded. If your
+  threat model includes an agent acting against a loaded rule under task
+  pressure, pair this package with mechanical gates (hooks, permissions,
+  least-privilege roles). True of every prior release; stated from this one.
+
+## What's New in v20.5.3
+
+### Grounding Evidence Carries Its Age
+
+Memory-grounded answers labelled their sources but never dated them, so a
+two-year-old note and yesterday's reached the model identically. Nothing in the
+evidence let it discount the stale one. Prompted by an external review naming
+the right risk for local-first memory: *the data stays local, but bad grounding
+becomes permanent* — storing everything on your machine removes the outside
+pressure that would otherwise surface a stale note.
+
+Evidence now reads:
+
+```
+[SOURCE 1: ledger:8286581d (recorded 2025-05-29, 431 days ago)]
+```
+
+The date already existed in storage and was being dropped at the snippet layer,
+so this is plumbing rather than new data collection. Zone-less SQLite
+timestamps are normalised to UTC — read as local, a ten-minute-old record
+parsed hours into the future and its age was suppressed entirely, meaning the
+feature silently did nothing on the freshest memories. An absent or unparseable
+date renders as nothing rather than defaulting to now; defaulting would make
+the oldest memories, the ones most likely to be stale, appear freshest.
+
+`tests/integration/grounding-staleness.test.ts` runs the reviewer's own probe —
+seed a deliberately outdated note beside a contradicting fresh one and assert
+the model receives both, visibly dated. Anyone can run it.
+
+**Not solved, and not claimed:** retrieval does not weight recency. A stale note
+shown *beside* a fresh one is the easy case — the model sees both dates and can
+weigh them. The hard case is a stale note retrieved *alone*, because ranking is
+by keyword match and an old store returns old results; then the age label is the
+only defence and there is no fresher record to compare against. Tracked as
+`TECH_DEBT.md` #4.
+
+## What's New in v20.5.0 – v20.5.2
+
+### The First Message Never Leaves Your Machine
+
+Symptom-triggered skills — the rules that fire on "can't see X", "no rows",
+"the list is empty" — are meant to load on the turn an incident report arrives.
+They never did: every host template called `session_bootstrap` with `{}`, so
+there was no prompt to match against.
+
+Fixing that raised the question of where matching happens. It now happens
+locally. The 28 keyword rules are already public, so there was nothing a local
+match could not compute, and `callPortal()` has no `prompt` parameter at all —
+the guarantee is structural, not a promise. The portal request carries the
+project and role only.
+
+A matched rule now arrives as **content**, not as a name. Native hosts outside
+the skill-file mirror had no way to read a rule they were only told about, so
+the rule body is inlined into the startup display, bounded and sized against
+the real per-project budget.
+
 ## What's New in v20.4.0
 
 ### An Explicitly Named Cloud Backend Fails Loud

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/cli.js

@@ -393,7 +393,11 @@ program
         // v9.2.2: --storage flag overrides PRISM_STORAGE env var to prevent
         // split-brain when CLI environment differs from MCP server config.
         if (storage) {
-            const validStorages = ['local', 'supabase'];
+            // Must mirror the PRISM_STORAGE union in config.ts. This list shipped
+            // as ['local','supabase'] — rejecting 'auto' (the documented default in
+            // this very command's --storage help text) and 'synalux' (the actual
+            // production backend). Found 2026-08-03; the config type is the truth.
+            const validStorages = ['auto', 'local', 'supabase', 'synalux'];
             if (!validStorages.includes(storage)) {
                 console.error(`Error: Invalid storage "${storage}". Must be one of: ${validStorages.join(', ')}`);
                 process.exit(1);
@@ -512,7 +516,11 @@ saveCmd
     try {
         // Storage override
         if (options.storage) {
-            const validStorages = ['local', 'supabase'];
+            // Must mirror the PRISM_STORAGE union in config.ts. This list shipped
+            // as ['local','supabase'] — rejecting 'auto' (the documented default in
+            // this very command's --storage help text) and 'synalux' (the actual
+            // production backend). Found 2026-08-03; the config type is the truth.
+            const validStorages = ['auto', 'local', 'supabase', 'synalux'];
             if (!validStorages.includes(options.storage)) {
                 console.error(`Error: Invalid storage "${options.storage}". Must be one of: ${validStorages.join(', ')}`);
                 process.exit(1);
@@ -565,7 +573,11 @@ saveCmd
     try {
         // Storage override
         if (options.storage) {
-            const validStorages = ['local', 'supabase'];
+            // Must mirror the PRISM_STORAGE union in config.ts. This list shipped
+            // as ['local','supabase'] — rejecting 'auto' (the documented default in
+            // this very command's --storage help text) and 'synalux' (the actual
+            // production backend). Found 2026-08-03; the config type is the truth.
+            const validStorages = ['auto', 'local', 'supabase', 'synalux'];
             if (!validStorages.includes(options.storage)) {
                 console.error(`Error: Invalid storage "${options.storage}". Must be one of: ${validStorages.join(', ')}`);
                 process.exit(1);

package/dist/connect.js

@@ -60,15 +60,48 @@ const LEGACY_CLAUDE_PROJECT_PRISM_ENTRY = {
 };
 const INSTALLATION_RECEIPT_SCHEMA_VERSION = 1;
 const INSTALLATION_RECEIPT_OWNER = "prism-connect";
+/**
+ * Economy subagent model per host.
+ *
+ * The local-first policy already permits exactly this — "a host-native subagent
+ * is a last resort: at most one, no nesting, using the configured economy
+ * model" — but only Claude was configured that way. Gemini and Codex banned
+ * subagents outright, which is stricter than the policy Prism publishes.
+ *
+ * The stated reason for Gemini was "native/remote subagents". That does not
+ * survive checking: Gemini CLI subagents execute locally, in-process, with
+ * optional local container sandboxes. The model is remote, which is equally
+ * true of Claude and Codex. There was no egress difference to justify the
+ * asymmetry.
+ *
+ * Cursor is deliberately absent. Its Background Agents really do run in remote
+ * cloud sandboxes with repository access — a different risk class — and no
+ * subagent-model setting was found for it.
+ */
 const CLAUDE_FALLBACK_SUBAGENT_MODEL = "sonnet";
+/** Fastest tier of the GPT-5.6 line (Sol > Terra > Luna) for simple work. */
+const CODEX_ECONOMY_SUBAGENT_MODEL = "gpt-5.6-luna";
+/**
+ * Gemini's speed tier for agentic work.
+ *
+ * Confirmed working in practice. An earlier revision changed this to
+ * `gemini-3-flash-preview` because `gemini-3.6-flash` appears in none of the
+ * 116 files of gemini-cli 0.49.0 — but the CLI does not validate Gemini model
+ * names at all. Its only ALLOWED_MODELS list gates Whisper speech binaries.
+ * Model names are passed through to the API, so absence from the bundle says
+ * nothing about resolvability. That reversion was a regression to an older ID.
+ */
+const GEMINI_ECONOMY_SUBAGENT_MODEL = "gemini-3.6-flash";
 const CODEX_LOCAL_FIRST_POLICY = {
     features: {
-        multi_agent: false,
+        // Subagents permitted, but bounded: the ceiling below is what keeps this
+        // from becoming fan-out. Previously false, which contradicted the policy.
+        multi_agent: true,
     },
     agents: {
-        max_threads: 2,
-        max_depth: 1,
-        default_subagent_model: "gpt-5.6-terra",
+        max_threads: 1, // "at most one" — was 2
+        max_depth: 1, // "no nesting"
+        default_subagent_model: CODEX_ECONOMY_SUBAGENT_MODEL,
         default_subagent_reasoning_effort: "low",
         job_max_runtime_seconds: 900,
     },
@@ -827,7 +860,21 @@ export function configureClaudeAgentPolicy(homeDir = homedir(), dryRun = false,
         return true;
     }, dryRun, beforeCommit);
 }
-/** Disable Gemini's native/remote subagents; Prism local workers remain available over MCP. */
+/**
+ * Pin Gemini's subagents to the economy model rather than banning them.
+ *
+ * Previously this wrote `enableAgents = false`, which is stricter than the
+ * local-first policy Prism publishes — that policy allows "at most one, no
+ * nesting, using the configured economy model", and Claude was configured
+ * exactly that way. The stated reason was "native/remote subagents", which does
+ * not hold: Gemini CLI subagents execute locally, in-process, with optional
+ * local container sandboxes. Only the model is remote, as it is for every host.
+ *
+ * `agents.overrides.<name>.modelConfig.model` is the documented shape. Only
+ * `codebase_investigator` is pinned: it is the built-in whose name is published,
+ * and inventing names for the others would write dead config. Unpinned
+ * subagents inherit the session model, which is the pre-existing behaviour.
+ */
 export function configureGeminiAgentPolicy(homeDir = homedir(), dryRun = false, beforeCommit) {
     const configPath = join(homeDir, ".gemini", "settings.json");
     return configureJsonAgentPolicy(configPath, "Gemini agent settings", (config) => {
@@ -835,11 +882,42 @@ export function configureGeminiAgentPolicy(homeDir = homedir(), dryRun = false,
         if (currentExperimental !== undefined && !isJsonObject(currentExperimental)) {
             throw new Error('"experimental" must be a JSON object');
         }
+        const currentAgents = config.agents;
+        if (currentAgents !== undefined && !isJsonObject(currentAgents)) {
+            throw new Error('"agents" must be a JSON object');
+        }
         const experimental = (currentExperimental ?? {});
-        if (experimental.enableAgents === false)
+        const agents = (currentAgents ?? {});
+        const currentOverrides = agents.overrides;
+        if (currentOverrides !== undefined && !isJsonObject(currentOverrides)) {
+            throw new Error('"agents.overrides" must be a JSON object');
+        }
+        const overrides = (currentOverrides ?? {});
+        const investigator = (isJsonObject(overrides.codebase_investigator)
+            ? overrides.codebase_investigator
+            : {});
+        const modelConfig = (isJsonObject(investigator.modelConfig)
+            ? investigator.modelConfig
+            : {});
+        // Respect a deliberate opt-out. Prism previously forced enableAgents=false
+        // on every run; flipping that to an unconditional `true` would repeat the
+        // same mistake pointing the other way, and switching something ON that a
+        // user turned OFF is the more intrusive direction. Only enable when the
+        // key is absent — pin the model either way, so a user who keeps subagents
+        // off still gets the economy default if they later turn them on.
+        const userDisabledDeliberately = experimental.enableAgents === false;
+        const alreadyApplied = (userDisabledDeliberately || experimental.enableAgents === true)
+            && modelConfig.model === GEMINI_ECONOMY_SUBAGENT_MODEL;
+        if (alreadyApplied)
             return false;
-        experimental.enableAgents = false;
+        if (!userDisabledDeliberately)
+            experimental.enableAgents = true;
+        modelConfig.model = GEMINI_ECONOMY_SUBAGENT_MODEL;
+        investigator.modelConfig = modelConfig;
+        overrides.codebase_investigator = investigator;
+        agents.overrides = overrides;
         config.experimental = experimental;
+        config.agents = agents;
         return true;
     }, dryRun, beforeCommit);
 }
@@ -933,7 +1011,12 @@ export function configureCodexAgentPolicy(homeDir, dryRun = false, beforeCommit,
         : undefined;
     if (!parsedFeatures
         || !parsedAgents
-        || !isDeepStrictEqual(parsedFeatures.multi_agent, false)
+        // Validate against the declared policy, not a literal. Hardcoding `false`
+        // here meant the guard rejected any change to CODEX_LOCAL_FIRST_POLICY
+        // rather than verifying the write matched it — a guard pinned to a value
+        // instead of to the invariant it exists to protect.
+        || !Object.entries(CODEX_LOCAL_FIRST_POLICY.features)
+            .every(([key, value]) => isDeepStrictEqual(parsedFeatures[key], value))
         || !Object.entries(CODEX_LOCAL_FIRST_POLICY.agents)
             .every(([key, value]) => isDeepStrictEqual(parsedAgents[key], value))) {
         throw new Error("Generated Codex local-first policy failed validation");

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/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";
@@ -276,8 +278,20 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
     const superSkills = snapshot.names.filter((name) => name.endsWith("-super-skill"));
     const superSkillAliases = superSkills.map((name) => `${name.slice(0, -"-super-skill".length)} (${name})`);
     const otherTierSkills = snapshot.names.filter((name) => !coreSkillSet.has(name) && !name.endsWith("-super-skill"));
+    // Conflicts must be LOUD, named, and actionable. This used to render as
+    // "· 2 local conflicts preserved" — a count with benign phrasing, so two
+    // safety skills (ask-first among them) sat 4 months stale on disk while
+    // every sync silently skipped them and nobody was ever told which ones.
     const conflictSuffix = snapshot.conflicts.length > 0
-        ? ` · ${snapshot.conflicts.length} local conflict${snapshot.conflicts.length === 1 ? "" : "s"} preserved`
+        ? ` · ${snapshot.conflicts.length} conflict${snapshot.conflicts.length === 1 ? "" : "s"} — see warning`
+        : "";
+    const conflictWarning = snapshot.conflicts.length > 0
+        ? `\n> - ⚠️ **SKILLS NOT UPDATING (local copy has no Prism ownership marker):** ` +
+            `${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.`
         : "";
     if (snapshot.source === "validated-partial") {
         return `> **Prism System Ready**\n>\n` +
@@ -287,14 +301,18 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
             `> - 🧩 **Super-skill entitlements:** ${formatBoundedSkillNames(superSkillAliases, "entitled")}\n` +
             `> - 🛠️ **Other tier entitlements:** ${formatBoundedSkillNames(otherTierSkills, "entitled")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
-            `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · native materialization incomplete${conflictSuffix}`;
+            `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · native materialization incomplete${conflictSuffix}` +
+            conflictWarning +
+            freeTierUpgradeLine(snapshot.tier);
     }
     if (snapshot.source === "tier-fallback") {
         return `> **Prism System Ready**\n>\n` +
             `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
             `> - 🛡️ **Fallback skill names:** ${formatBoundedSkillNames(snapshot.names, "fallback")}\n` +
             `> - 🧠 **Context depth:** ${depth}\n` +
-            `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · no committed manifest${conflictSuffix}`;
+            `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · no committed manifest${conflictSuffix}` +
+            conflictWarning +
+            freeTierUpgradeLine(snapshot.tier);
     }
     return `> **Prism System Ready**\n>\n` +
         `> - 🪪 **Subscription tier:** ${snapshot.tier}\n` +
@@ -303,7 +321,63 @@ async function buildNativeSystemReadyBlock(snapshot, depth) {
         `> - 🧩 **Super-skills provisioned:** ${formatBoundedSkillNames(superSkillAliases, "provisioned")}\n` +
         `> - 🛠️ **Other tier skills provisioned:** ${formatBoundedSkillNames(otherTierSkills, "provisioned")}\n` +
         `> - 🧠 **Context depth:** ${depth}\n` +
-        `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · committed manifest${conflictSuffix}`;
+        `> - 🔄 **Skill sync:** ${SKILL_SYNC_STATUS_LABELS[snapshot.syncStatus]} · committed manifest${conflictSuffix}` +
+        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);
@@ -1653,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/skillRouting.js

@@ -46,6 +46,13 @@ export const REQUIRED_PROTECTED_SKILL_NAMES = [
     // so the two sources disagreed. A portal test now asserts they match.
     'data-before-code',
     'critical-thinking-debug',
+    // Added 2026-08-03. The floor had grown past every budget tranche, so an
+    // unprotected universal skill could NEVER inline — including the destruction
+    // gate, during the very audit of a demo-venue wipe it should have prevented.
+    // If these two are absent, nothing tells the agent that announcing a wipe is
+    // not the same as being allowed to run it.
+    'ask-first',
+    'feature-preservation',
 ];
 /**
  * Native skills that paid subscription tiers receive through `prism connect`.

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/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.5.3",
+  "version": "20.7.0",
   "mcpName": "io.github.dcostenco/prism-coder",
-  "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local or subscription-gated Synalux storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
+  "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",
   "type": "module",
   "main": "dist/server.js",