pi-vault-mind 0.16.28 → 0.16.29

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.16.29 — 2026-08-27
+
+### Fixed
+
+- **Main-terminal identity isolation.** Ambient bundled specialist skills no longer make the interactive Pi session inherit the first matching specialist boundary. Identity injection now defaults to the unrestricted main agent and only activates from an explicit vault or environment selection.
+- **Explicit persona controls.** Added `/vm identity status | set <role> | on | off`, `VAULT_MIND_AGENT_ROLE`, and `VAULT_MIND_IDENTITY_INJECTION`, with canonical persistence under `vaultMind.identities`.
+- **Identity configuration migration and write safety.** Legacy top-level identity settings migrate without losing role allowlists, new scaffolds use the canonical path, and malformed JSON is reported without overwriting the existing vault configuration or leaking an unhandled HTTP rejection.
+
+### Verification
+
+- Root and Obsidian builds passed; full test suite: 899/899 passing.
+- Real-vault startup probe confirmed ambient Broadcaster resources keep the unrestricted main identity while an explicit Broadcaster override activates the boundary.
 
 ## 0.16.28 — 2026-08-09
 

package/README.md

@@ -356,6 +356,7 @@ Edit `<vault>/.vault-mind/vault-mind.config.json` to match your domain:
 | `/vm injector create`        | Interactive wizard to create a new injector                |
 | `/vm context enable \| disable \| status` | Manage pi-context integration              |
 | `/vm embedding status \| use \| model \| models \| pull` | Manage embedding provider |
+| `/vm identity status \| set <role> \| on \| off` | Inspect or explicitly control the interactive agent persona boundary |
 | `/vm remote status \| config \| sync \| jobs \| migrate` | Manage remote embedding + vector sync |
 | `/vm watcher start \| stop \| status` | Manage the passive file watcher                  |
 | `/vm server status` | Show HTTP server status, port, and uptime |

package/dist/src/commands.js

@@ -8,6 +8,8 @@ import { revokeToken, rotateToken } from "./auth.js";
 import { handleDiscoverSchema } from "./discover-schema.js";
 import { writeEnvEntry } from "./embedding-secrets.js";
 import { queryGraph } from "./graph.js";
+import { writeIdentitiesLayer } from "./identities-config.js";
+import { IDENTITY_BOUNDARY_ROLES, resolveIdentityBoundaryRole } from "./identity-injector.js";
 import { runAskIntake } from "./intake.js";
 import { connect, searchFts, searchHybrid, searchHybridRanked } from "./lance.js";
 import { createModalClient, isModalConfigured, MODAL_TOKEN_ENV, modalTokenEnvPath, resolveModalToken, } from "./modal-config.js";
@@ -39,6 +41,9 @@ const VM_USAGE = [
     "  /vm index [--all] [--reembed] [--remote]  Index collections (alias: reindex)",
     "  /vm discover-schema         Infer schema from a JSONL file",
     "  /vm injector create         Create a new injector (wizard)",
+    "  /vm identity status        Show configured and effective persona",
+    "  /vm identity set <role>    Set main|manager|miner|broadcaster|heavy-lifter",
+    "  /vm identity on|off        Enable or disable persona boundary injection",
     "  /vm context enable|disable  Enable/disable pi-context integration",
     "  /vm embedding status        Show embedding config",
     "  /vm remote status          Show remote provider config + health + collections",
@@ -1616,6 +1621,74 @@ const handleToken = (args, ctx) => {
             ctx.ui.notify(`Unknown: ${sub}. Try: show, rotate, revoke`, "error");
     }
 };
+const handleIdentity = (args, ctx) => {
+    const parts = args.trim().split(/\s+/g).filter(Boolean);
+    const subcommand = parts[0]?.toLowerCase() || "status";
+    const identities = loadConfig(ctx.cwd).vaultMind.identities;
+    const configuredRole = identities?.activeRole?.trim().toLowerCase() || "main";
+    const updateIdentity = (patch) => {
+        try {
+            writeIdentitiesLayer(ctx.cwd, patch);
+            return true;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.ui.notify(`Failed to update identity config: ${message}`, "error");
+            return false;
+        }
+    };
+    switch (subcommand) {
+        case "status": {
+            const effectiveRole = resolveIdentityBoundaryRole(ctx.cwd);
+            const injectionEnabled = identities?.injectBoundaries !== false;
+            const envRole = process.env.VAULT_MIND_AGENT_ROLE?.trim();
+            const envInjection = process.env.VAULT_MIND_IDENTITY_INJECTION?.trim();
+            ctx.ui.notify([
+                "**Identity Boundary**",
+                `Persona: ${configuredRole}`,
+                `Injection: ${injectionEnabled ? "enabled" : "disabled"}`,
+                `Effective boundary: ${effectiveRole ?? "none (main agent)"}`,
+                ...(envRole ? [`Environment role override: ${envRole}`] : []),
+                ...(envInjection ? [`Environment injection override: ${envInjection}`] : []),
+            ].join("\n"), "info");
+            return;
+        }
+        case "set": {
+            const role = parts[1]?.toLowerCase();
+            const validRole = role === "main" ||
+                (role !== undefined &&
+                    IDENTITY_BOUNDARY_ROLES.includes(role));
+            if (!role || !validRole) {
+                ctx.ui.notify(`Unknown persona: ${role ?? "(missing)"}. Use main, ${IDENTITY_BOUNDARY_ROLES.join(", ")}.`, "error");
+                return;
+            }
+            if (!updateIdentity({
+                activeRole: role,
+                injectBoundaries: true,
+            })) {
+                return;
+            }
+            ctx.ui.notify(`Persona set to ${role}. The boundary applies on the next agent turn.`, "info");
+            return;
+        }
+        case "off":
+        case "disable": {
+            if (!updateIdentity({ injectBoundaries: false }))
+                return;
+            ctx.ui.notify("Identity injection disabled. The main agent remains unrestricted.", "info");
+            return;
+        }
+        case "on":
+        case "enable": {
+            if (!updateIdentity({ injectBoundaries: true }))
+                return;
+            ctx.ui.notify(`Identity injection enabled for ${configuredRole}. The setting applies on the next agent turn.`, "info");
+            return;
+        }
+        default:
+            ctx.ui.notify("Usage: /vm identity status | set <role> | on | off", "error");
+    }
+};
 // ── Main /vm command ───────────────────────────────────────────────────────
 export const registerCommands = (pi) => {
     pi.registerCommand("vm", {
@@ -1633,6 +1706,7 @@ export const registerCommands = (pi) => {
                 "discover-schema",
                 "doctor",
                 "injector",
+                "identity",
                 "context",
                 "embedding",
                 "remote",
@@ -1662,6 +1736,11 @@ export const registerCommands = (pi) => {
                         .filter((c) => c.startsWith(prefix))
                         .map((c) => ({ label: c, value: c, description: `context ${c}` }));
                 }
+                if (subcommand === "identity") {
+                    return ["status", "set", "on", "off", "main", ...IDENTITY_BOUNDARY_ROLES]
+                        .filter((c) => c.startsWith(prefix))
+                        .map((c) => ({ label: c, value: c, description: `identity ${c}` }));
+                }
                 if (subcommand === "discover-schema") {
                     return ["--name", "--sample"]
                         .filter((c) => c.startsWith(prefix))
@@ -1736,6 +1815,8 @@ export const registerCommands = (pi) => {
                     return handleCollection(rest, ctx, pi);
                 case "injector":
                     return handleInjector(rest, ctx);
+                case "identity":
+                    return handleIdentity(rest, ctx);
                 case "context":
                     return handleContext(rest, ctx, pi);
                 case "embedding":

package/dist/src/identities-config.js

@@ -26,11 +26,27 @@ function deepMerge(base, overlay) {
  */
 export function writeIdentitiesLayer(cwd, identities) {
     const configPath = getConfigPath(cwd);
-    const existing = fs.existsSync(configPath)
-        ? JSON.parse(fs.readFileSync(configPath, "utf-8"))
-        : {};
+    let existing = {};
+    if (fs.existsSync(configPath)) {
+        const raw = fs.readFileSync(configPath, "utf-8");
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new TypeError("the root value must be a JSON object");
+            }
+            existing = parsed;
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON in ${configPath}; the file was not changed.`, {
+                cause: error,
+            });
+        }
+    }
     const vaultMind = existing.vaultMind || {};
-    vaultMind.identities = deepMerge(vaultMind.identities || {}, identities);
+    const legacyIdentities = existing.identities || {};
+    const canonicalIdentities = vaultMind.identities || {};
+    vaultMind.identities = deepMerge(deepMerge(legacyIdentities, canonicalIdentities), identities);
+    delete existing.identities;
     existing.vaultMind = vaultMind;
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir))

package/dist/src/identity-injector.d.ts

@@ -6,10 +6,21 @@
  * from pi-guideline-loader (kylebrodeur/pi-guideline-loader, MIT).
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+export declare const IDENTITY_BOUNDARY_ROLES: readonly ["heavy-lifter", "miner", "broadcaster", "manager"];
+export type IdentityBoundaryRole = (typeof IDENTITY_BOUNDARY_ROLES)[number];
+/**
+ * Resolve an explicitly selected specialist persona.
+ *
+ * Specialist skills are ambient resources in every pi session, so their
+ * presence must never select a persona. The environment can override the
+ * vault-local config for launcher/fork use. Unset, "main", "none", and invalid
+ * roles all keep the unrestricted interactive main agent.
+ */
+export declare function resolveIdentityBoundaryRole(cwd: string, env?: NodeJS.ProcessEnv): IdentityBoundaryRole | undefined;
 /**
  * Register the identity injector on a pi ExtensionAPI.
  *
- * On every before_agent_start event, detects the current role and injects
- * the corresponding boundary prompt into the system prompt.
+ * On every before_agent_start event, injects a boundary only when a specialist
+ * persona was selected explicitly through environment or vault config.
  */
 export declare function registerIdentityInjector(pi: ExtensionAPI): void;

package/dist/src/identity-injector.js

@@ -5,7 +5,9 @@
  * per role stating capability boundaries as a contract. Pattern adapted
  * from pi-guideline-loader (kylebrodeur/pi-guideline-loader, MIT).
  */
+import { loadConfig } from "./utils.js";
 // ── Per-role boundary prompts ────────────────────────────────────────────────
+export const IDENTITY_BOUNDARY_ROLES = ["heavy-lifter", "miner", "broadcaster", "manager"];
 const BOUNDARY_PROMPTS = {
     "heavy-lifter": [
         "--- IDENTITY BOUNDARY: Heavy-Lifter ---",
@@ -50,46 +52,58 @@ const BOUNDARY_PROMPTS = {
         "------------------------------------------",
     ].join("\n"),
 };
-// ── Role detection ────────────────────────────────────────────────────────────
+// ── Role resolution ──────────────────────────────────────────────────────────
+const DISABLED_SWITCH_VALUES = {
+    "0": true,
+    false: true,
+    no: true,
+    off: true,
+    disabled: true,
+};
+const ENABLED_SWITCH_VALUES = {
+    "1": true,
+    true: true,
+    yes: true,
+    on: true,
+    enabled: true,
+};
 /**
- * Detect the current agent's role from a before_agent_start event.
- *
- * PRIMARY signal — event.systemPromptOptions.skills:
- *   pi loads `--agent vault-mind-{role}` as a named Skill (Skill.name == "vault-mind-{role}").
- *   Exact name match is structural and immune to prose false-positives.
- *
- * FALLBACK signal — system prompt XML:
- *   Only when no matching skill is present. Matches only the machine-generated
- *   `<name>vault-mind-{role}</name>` element emitted by formatSkillsForPrompt()
- *   inside <available_skills> — not any free-text prose mention of the role name.
+ * Resolve an explicitly selected specialist persona.
  *
- * Returns undefined for any non-vault-mind session; no injection occurs.
+ * Specialist skills are ambient resources in every pi session, so their
+ * presence must never select a persona. The environment can override the
+ * vault-local config for launcher/fork use. Unset, "main", "none", and invalid
+ * roles all keep the unrestricted interactive main agent.
  */
-function detectRole(event) {
-    // PRIMARY: exact skill name match — most reliable, no prose false-positive risk.
-    const skills = event.systemPromptOptions.skills;
-    if (skills) {
-        for (const skill of skills) {
-            const m = skill.name.match(/^vault-mind-(heavy-lifter|miner|broadcaster|manager)$/i);
-            if (m)
-                return m[1].toLowerCase();
-        }
+export function resolveIdentityBoundaryRole(cwd, env = process.env) {
+    const identities = loadConfig(cwd).vaultMind.identities;
+    const injectionOverride = env.VAULT_MIND_IDENTITY_INJECTION?.trim().toLowerCase();
+    if (injectionOverride && DISABLED_SWITCH_VALUES[injectionOverride])
+        return;
+    if ((!injectionOverride || !ENABLED_SWITCH_VALUES[injectionOverride]) &&
+        identities?.injectBoundaries === false) {
+        return;
     }
-    // FALLBACK: only the assembled system prompt is available — match the XML
-    // <name> token produced by formatSkillsForPrompt(), not free prose.
-    const m = event.systemPrompt.match(/<name>vault-mind-(heavy-lifter|miner|broadcaster|manager)<\/name>/i);
-    return m?.[1]?.toLowerCase();
+    const rawRole = Object.hasOwn(env, "VAULT_MIND_AGENT_ROLE")
+        ? env.VAULT_MIND_AGENT_ROLE
+        : identities?.activeRole;
+    const role = rawRole?.trim().toLowerCase();
+    if (!role || role === "main" || role === "none")
+        return;
+    if (!Object.hasOwn(BOUNDARY_PROMPTS, role))
+        return;
+    return role;
 }
 // ── Injector ──────────────────────────────────────────────────────────────────
 /**
  * Register the identity injector on a pi ExtensionAPI.
  *
- * On every before_agent_start event, detects the current role and injects
- * the corresponding boundary prompt into the system prompt.
+ * On every before_agent_start event, injects a boundary only when a specialist
+ * persona was selected explicitly through environment or vault config.
  */
 export function registerIdentityInjector(pi) {
     pi.on("before_agent_start", async (event) => {
-        const role = detectRole(event);
+        const role = resolveIdentityBoundaryRole(event.systemPromptOptions.cwd);
         if (!role)
             return;
         const boundaryPrompt = BOUNDARY_PROMPTS[role];

package/dist/src/scaffold.js

@@ -135,37 +135,37 @@ export const scaffoldVaultConfig = (vaultPath, collectionOverride) => {
             version: 2,
             collections: defaultCollections,
             injectors: defaultInjectors,
-            identities: {
-                roles: {
-                    main: {
-                        allowedTools: [
-                            "read",
-                            "write",
-                            "edit",
-                            "bash",
-                            "grep",
-                            "find",
-                            "ls",
-                            "vm_search",
-                            "vm_query",
-                            "vm_append",
-                            "vm_stats",
-                            "vm_status",
-                            "vm_describe",
-                            "vm_configure",
-                            "vault_read",
-                            "vault_search",
-                            "vault_list",
-                            "vault_tags",
-                            "vm_backlinks",
-                            "vm_related",
-                            "vm_broken_links",
-                            "vm_codegraph_impact",
-                        ],
+            vaultMind: {
+                identities: {
+                    roles: {
+                        main: {
+                            allowedTools: [
+                                "read",
+                                "write",
+                                "edit",
+                                "bash",
+                                "grep",
+                                "find",
+                                "ls",
+                                "vm_search",
+                                "vm_query",
+                                "vm_append",
+                                "vm_stats",
+                                "vm_status",
+                                "vm_describe",
+                                "vm_configure",
+                                "vault_read",
+                                "vault_search",
+                                "vault_list",
+                                "vault_tags",
+                                "vm_backlinks",
+                                "vm_related",
+                                "vm_broken_links",
+                                "vm_codegraph_impact",
+                            ],
+                        },
                     },
                 },
-            },
-            vaultMind: {
                 dataDir: ".vault-mind/.lancedb",
                 ftsEnabled: true,
                 graph: { enabled: true, canvasSync: false },

package/dist/src/server.js

@@ -832,19 +832,28 @@ export function startServer(pi, serverState, watcherState, readinessCallback) {
                         if (parts.length === 5) {
                             const role = parts[3];
                             withAuth(req, res, async () => {
-                                const body = (await readJsonBody(req));
-                                if (!body.allowedTools || !Array.isArray(body.allowedTools)) {
-                                    res.writeHead(400, { "Content-Type": "application/json" });
-                                    res.end(JSON.stringify({ error: "Missing allowedTools array in request body" }));
-                                    return;
+                                try {
+                                    const body = (await readJsonBody(req));
+                                    if (!body.allowedTools || !Array.isArray(body.allowedTools)) {
+                                        res.writeHead(400, { "Content-Type": "application/json" });
+                                        res.end(JSON.stringify({ error: "Missing allowedTools array in request body" }));
+                                        return;
+                                    }
+                                    // writeIdentitiesLayer deep-merges; pass a partial role config
+                                    writeIdentitiesLayer(process.cwd(), {
+                                        roles: { [role]: { allowedTools: body.allowedTools } },
+                                    });
+                                    refreshAgentIdentities([role]);
+                                    res.writeHead(200, { "Content-Type": "application/json" });
+                                    res.end(JSON.stringify({ ok: true, role, allowedTools: body.allowedTools }));
+                                }
+                                catch (error) {
+                                    const message = error instanceof Error ? error.message : String(error);
+                                    res.writeHead(500, { "Content-Type": "application/json" });
+                                    res.end(JSON.stringify({
+                                        error: `Failed to update identity config: ${message}`,
+                                    }));
                                 }
-                                // writeIdentitiesLayer deep-merges; pass a partial role config
-                                writeIdentitiesLayer(process.cwd(), {
-                                    roles: { [role]: { allowedTools: body.allowedTools } },
-                                });
-                                refreshAgentIdentities([role]);
-                                res.writeHead(200, { "Content-Type": "application/json" });
-                                res.end(JSON.stringify({ ok: true, role, allowedTools: body.allowedTools }));
                             }, { requireWrite: true });
                         }
                         else {

package/dist/src/types.d.ts

@@ -203,6 +203,10 @@ export interface VaultMindConfig {
         defaultProfile?: IdentityConfig;
         /** Per-role overrides. */
         roles?: Record<string, IdentityConfig>;
+        /** Master switch for system-prompt identity-boundary injection. */
+        injectBoundaries?: boolean;
+        /** Explicit persona to inject; unset, "main", or "none" keeps the main agent. */
+        activeRole?: string;
     };
     /**
      * Vault folder layout overrides. Each path is vault-relative and joined to
@@ -235,6 +239,10 @@ export interface IdentitiesConfig {
     defaultProfile?: IdentityConfig;
     /** Per-role overrides. */
     roles?: Record<string, IdentityConfig>;
+    /** Master switch for system-prompt identity-boundary injection. */
+    injectBoundaries?: boolean;
+    /** Explicit persona to inject; unset, "main", or "none" keeps the main agent. */
+    activeRole?: string;
 }
 export interface PiContextDef {
     enabled?: boolean;

package/dist/src/utils.js

@@ -89,6 +89,20 @@ const mergeInjectors = (base, layer) => {
 };
 const mergeConfigLayer = (base, layer, cwd) => {
     const rawLayer = layer;
+    const legacyIdentities = rawLayer.identities;
+    const canonicalIdentities = layer.vaultMind?.identities;
+    const mergedIdentities = base.vaultMind.identities || legacyIdentities || canonicalIdentities
+        ? {
+            ...base.vaultMind.identities,
+            ...legacyIdentities,
+            ...canonicalIdentities,
+            roles: {
+                ...base.vaultMind.identities?.roles,
+                ...legacyIdentities?.roles,
+                ...canonicalIdentities?.roles,
+            },
+        }
+        : undefined;
     const merged = {
         version: layer.version ?? base.version,
         collections: { ...base.collections },
@@ -99,6 +113,7 @@ const mergeConfigLayer = (base, layer, cwd) => {
             embedding: { ...base.vaultMind.embedding, ...(layer.vaultMind?.embedding || {}) },
             graph: { ...base.vaultMind.graph, ...(layer.vaultMind?.graph || {}) },
             vaults: { ...base.vaultMind.vaults, ...(layer.vaultMind?.vaults || {}) },
+            identities: mergedIdentities,
         },
         extensionCompatibility: {
             ...base.extensionCompatibility,

package/dist/test/commands.test.js

@@ -157,6 +157,13 @@ describe("CLI command handlers", () => {
         process.chdir(origCwd);
         fs.rmSync(dir, { recursive: true, force: true });
     });
+    describe("scaffoldVaultConfig", () => {
+        it("writes identities only at the canonical vaultMind path", () => {
+            const raw = JSON.parse(fs.readFileSync(getConfigPath(dir), "utf-8"));
+            assert.equal(raw.identities, undefined);
+            assert.ok(raw.vaultMind.identities?.roles?.main);
+        });
+    });
     describe("handleSearch", () => {
         it("returns results in hybrid mode (default)", async () => {
             const vm = getVmHandler();
@@ -288,6 +295,77 @@ describe("CLI command handlers", () => {
             assert.match(last.message, /Unknown: bogus/);
         });
     });
+    describe("handleIdentity", () => {
+        it("reports main as the safe default persona", async () => {
+            const vm = getVmHandler();
+            await vm("identity status", makeCtx(dir, notifies));
+            const last = notifies.at(-1);
+            assert.ok(last, "notify was called");
+            assert.equal(last.level, "info");
+            assert.match(last.message, /Persona: main/);
+            assert.match(last.message, /Injection: enabled/);
+        });
+        it("sets an explicit persona and enables injection", async () => {
+            const vm = getVmHandler();
+            await vm("identity set broadcaster", makeCtx(dir, notifies));
+            const raw = JSON.parse(fs.readFileSync(getConfigPath(dir), "utf-8"));
+            assert.equal(raw.vaultMind.identities.activeRole, "broadcaster");
+            assert.equal(raw.vaultMind.identities.injectBoundaries, true);
+            assert.match(notifies.at(-1)?.message ?? "", /Persona set to broadcaster/);
+        });
+        it("migrates legacy top-level identities when setting a persona", async () => {
+            const configPath = getConfigPath(dir);
+            const legacy = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            legacy.identities = legacy.vaultMind.identities;
+            delete legacy.vaultMind.identities;
+            fs.writeFileSync(configPath, `${JSON.stringify(legacy, null, 2)}\n`, "utf-8");
+            const vm = getVmHandler();
+            await vm("identity set miner", makeCtx(dir, notifies));
+            const migrated = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+            assert.equal(migrated.identities, undefined);
+            assert.ok(migrated.vaultMind.identities.roles.main);
+            assert.equal(migrated.vaultMind.identities.activeRole, "miner");
+        });
+        it("turns injection off without discarding the selected persona", async () => {
+            const vm = getVmHandler();
+            await vm("identity set miner", makeCtx(dir, notifies));
+            await vm("identity off", makeCtx(dir, notifies));
+            const raw = JSON.parse(fs.readFileSync(getConfigPath(dir), "utf-8"));
+            assert.equal(raw.vaultMind.identities.activeRole, "miner");
+            assert.equal(raw.vaultMind.identities.injectBoundaries, false);
+            assert.match(notifies.at(-1)?.message ?? "", /Identity injection disabled/);
+        });
+        it("turns injection back on for the configured persona", async () => {
+            const vm = getVmHandler();
+            await vm("identity set manager", makeCtx(dir, notifies));
+            await vm("identity off", makeCtx(dir, notifies));
+            await vm("identity on", makeCtx(dir, notifies));
+            const raw = JSON.parse(fs.readFileSync(getConfigPath(dir), "utf-8"));
+            assert.equal(raw.vaultMind.identities.activeRole, "manager");
+            assert.equal(raw.vaultMind.identities.injectBoundaries, true);
+            assert.match(notifies.at(-1)?.message ?? "", /Identity injection enabled/);
+        });
+        it("rejects an unknown persona without changing identity config", async () => {
+            const configPath = getConfigPath(dir);
+            const before = JSON.parse(fs.readFileSync(configPath, "utf-8")).vaultMind.identities;
+            const vm = getVmHandler();
+            await vm("identity set reviewer", makeCtx(dir, notifies));
+            const after = JSON.parse(fs.readFileSync(configPath, "utf-8")).vaultMind.identities;
+            assert.deepEqual(after, before);
+            assert.equal(notifies.at(-1)?.level, "error");
+            assert.match(notifies.at(-1)?.message ?? "", /Unknown persona/);
+        });
+        it("reports malformed config without overwriting it", async () => {
+            const configPath = getConfigPath(dir);
+            const malformed = "{ invalid json";
+            fs.writeFileSync(configPath, malformed, "utf-8");
+            const vm = getVmHandler();
+            await assert.doesNotReject(() => vm("identity set miner", makeCtx(dir, notifies)));
+            assert.equal(fs.readFileSync(configPath, "utf-8"), malformed);
+            assert.equal(notifies.at(-1)?.level, "error");
+            assert.match(notifies.at(-1)?.message ?? "", /Failed to update identity config/);
+        });
+    });
     describe("handleWatcher", () => {
         it("status shows watcher stopped by default", async () => {
             const vm = getVmHandler();

package/dist/test/identity-injector.test.js

@@ -1,14 +1,33 @@
 import { strict as assert } from "node:assert";
-import { describe, it } from "node:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
 import { registerIdentityInjector } from "../src/identity-injector.js";
-/** Create a mock pi that captures the before_agent_start handler. */
+const ENV_KEYS = ["VAULT_MIND_AGENT_ROLE", "VAULT_MIND_IDENTITY_INJECTION"];
+const originalEnv = {
+    VAULT_MIND_AGENT_ROLE: process.env.VAULT_MIND_AGENT_ROLE,
+    VAULT_MIND_IDENTITY_INJECTION: process.env.VAULT_MIND_IDENTITY_INJECTION,
+};
+const temporaryDirectories = [];
+afterEach(() => {
+    for (const key of ENV_KEYS) {
+        const value = originalEnv[key];
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    }
+    while (temporaryDirectories.length > 0) {
+        fs.rmSync(temporaryDirectories.pop(), { recursive: true, force: true });
+    }
+});
 function mockPi() {
     const captured = { current: null };
     const pi = {
         on(event, handler) {
-            if (event === "before_agent_start") {
+            if (event === "before_agent_start")
                 captured.current = handler;
-            }
         },
     };
     return {
@@ -18,19 +37,27 @@ function mockPi() {
         },
     };
 }
-/** Build a minimal BeforeAgentStartEvent with optional skills. */
+function temporaryVault(identities) {
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pvm-identity-"));
+    temporaryDirectories.push(cwd);
+    if (identities) {
+        const configDirectory = path.join(cwd, ".vault-mind");
+        fs.mkdirSync(configDirectory, { recursive: true });
+        fs.writeFileSync(path.join(configDirectory, "vault-mind.config.json"), `${JSON.stringify({ version: 2, vaultMind: { identities } }, null, 2)}\n`, "utf-8");
+    }
+    return cwd;
+}
 function makeEvent(opts) {
     return {
         type: "before_agent_start",
         prompt: "test prompt",
         systemPrompt: opts.systemPrompt ?? "base system prompt",
         systemPromptOptions: {
-            cwd: "/test",
+            cwd: opts.cwd,
             skills: opts.skills,
         },
     };
 }
-/** Build a Skill with a given name. */
 function skill(name) {
     return {
         name,
@@ -41,157 +68,68 @@ function skill(name) {
         disableModelInvocation: false,
     };
 }
-// ── Tests ─────────────────────────────────────────────────────────────────────
+async function invoke(event) {
+    const mock = mockPi();
+    registerIdentityInjector(mock.pi);
+    assert.ok(mock.handler, "before_agent_start handler should be registered");
+    return mock.handler(event);
+}
 describe("registerIdentityInjector", () => {
-    it("registers a before_agent_start hook on the pi instance", () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler, "handler should be registered");
-    });
-    it("the hook returns undefined for non-vault-mind sessions (no matching skill)", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("some-other-skill"), skill("another-skill")],
-        });
-        const result = await mock.handler(event);
+    it("does not infer a persona from ambient specialist skills", async () => {
+        const cwd = temporaryVault();
+        const result = await invoke(makeEvent({
+            cwd,
+            skills: [
+                skill("vault-mind-broadcaster"),
+                skill("vault-mind-manager"),
+                skill("vault-mind-miner"),
+            ],
+            systemPrompt: "base prompt\n<available_skills><name>vault-mind-broadcaster</name></available_skills>",
+        }));
         assert.strictEqual(result, undefined);
     });
-    it("the hook returns undefined when skills array is empty", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({ skills: [] });
-        const result = await mock.handler(event);
-        assert.strictEqual(result, undefined);
+    it("injects the persona selected in vault config", async () => {
+        const cwd = temporaryVault({ injectBoundaries: true, activeRole: "broadcaster" });
+        const result = await invoke(makeEvent({ cwd, systemPrompt: "base prompt" }));
+        assert.ok(result?.systemPrompt?.includes("base prompt"));
+        assert.ok(result?.systemPrompt?.includes("IDENTITY BOUNDARY: Broadcaster"));
     });
-    it("the hook returns undefined when skills is undefined (no skills at all)", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({});
-        const result = await mock.handler(event);
-        assert.strictEqual(result, undefined);
+    it("treats main and none as the full-tool main persona", async () => {
+        for (const activeRole of ["main", "none"]) {
+            const cwd = temporaryVault({ injectBoundaries: true, activeRole });
+            const result = await invoke(makeEvent({ cwd, skills: [skill("vault-mind-broadcaster")] }));
+            assert.strictEqual(result, undefined, activeRole);
+        }
     });
-    it("the hook injects boundary prompt for heavy-lifter role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-heavy-lifter")],
-            systemPrompt: "base prompt",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("base prompt"));
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Heavy-Lifter"));
-        assert.ok(result.systemPrompt.includes("durable knowledge store"));
-    });
-    it("the hook injects boundary prompt for miner role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-miner")],
-            systemPrompt: "base prompt",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("base prompt"));
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Miner"));
-        assert.ok(result.systemPrompt.includes("'main' and 'research'"));
-    });
-    it("the hook injects boundary prompt for broadcaster role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-broadcaster")],
-            systemPrompt: "base prompt",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("base prompt"));
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Broadcaster"));
-        assert.ok(result.systemPrompt.includes("Agent/Presentations"));
-    });
-    it("the hook injects boundary prompt for manager role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-manager")],
-            systemPrompt: "base prompt",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("base prompt"));
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Manager"));
-        assert.ok(result.systemPrompt.includes("publish to the human-facing vault"));
-    });
-    // ── Fallback: XML-based role detection ────────────────────────────────────
-    it("detects role via XML fallback when no skills match", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("unrelated-skill")],
-            systemPrompt: "base prompt\n<available_skills>\n<name>vault-mind-miner</name>\n</available_skills>",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Miner"));
+    it("config hard-off suppresses a configured specialist persona", async () => {
+        const cwd = temporaryVault({ injectBoundaries: false, activeRole: "broadcaster" });
+        const result = await invoke(makeEvent({ cwd, skills: [skill("vault-mind-broadcaster")] }));
+        assert.strictEqual(result, undefined);
     });
-    it("detects role via XML fallback when skills is undefined", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            systemPrompt: "base prompt\n<available_skills>\n<name>vault-mind-broadcaster</name>\n</available_skills>",
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Broadcaster"));
+    it("environment role overrides the configured persona", async () => {
+        process.env.VAULT_MIND_AGENT_ROLE = "miner";
+        const cwd = temporaryVault({ injectBoundaries: true, activeRole: "broadcaster" });
+        const result = await invoke(makeEvent({ cwd }));
+        assert.ok(result?.systemPrompt?.includes("IDENTITY BOUNDARY: Miner"));
+        assert.ok(!result?.systemPrompt?.includes("IDENTITY BOUNDARY: Broadcaster"));
     });
-    it("returns undefined when XML fallback has no vault-mind role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            systemPrompt: "base prompt\n<available_skills>\n<name>some-other-skill</name>\n</available_skills>",
-        });
-        const result = await mock.handler(event);
+    it("environment hard-off overrides both environment role and config", async () => {
+        process.env.VAULT_MIND_AGENT_ROLE = "miner";
+        process.env.VAULT_MIND_IDENTITY_INJECTION = "off";
+        const cwd = temporaryVault({ injectBoundaries: true, activeRole: "broadcaster" });
+        const result = await invoke(makeEvent({ cwd, skills: [skill("vault-mind-broadcaster")] }));
         assert.strictEqual(result, undefined);
     });
-    // ── Case insensitivity ────────────────────────────────────────────────────
-    it("matches role case-insensitively (HEAVY-LIFTER)", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-HEAVY-LIFTER")],
-        });
-        const result = await mock.handler(event);
-        assert.ok(result);
-        assert.ok("systemPrompt" in result);
-        assert.ok(result.systemPrompt.includes("IDENTITY BOUNDARY: Heavy-Lifter"));
+    it("normalizes case and whitespace for explicit roles", async () => {
+        process.env.VAULT_MIND_AGENT_ROLE = "  HEAVY-LIFTER  ";
+        const cwd = temporaryVault();
+        const result = await invoke(makeEvent({ cwd }));
+        assert.ok(result?.systemPrompt?.includes("IDENTITY BOUNDARY: Heavy-Lifter"));
     });
-    // ── Unknown role ──────────────────────────────────────────────────────────
-    it("returns undefined for an unknown vault-mind role", async () => {
-        const mock = mockPi();
-        registerIdentityInjector(mock.pi);
-        assert.ok(mock.handler);
-        const event = makeEvent({
-            skills: [skill("vault-mind-unknown-role")],
-        });
-        const result = await mock.handler(event);
+    it("ignores an unknown explicit persona rather than injecting the wrong one", async () => {
+        process.env.VAULT_MIND_AGENT_ROLE = "unknown-role";
+        const cwd = temporaryVault({ injectBoundaries: true, activeRole: "broadcaster" });
+        const result = await invoke(makeEvent({ cwd, skills: [skill("vault-mind-broadcaster")] }));
         assert.strictEqual(result, undefined);
     });
 });

package/dist/test/rest-vm.test.js

@@ -461,4 +461,28 @@ describe("REST vm routes", () => {
         assert.ok(Array.isArray(returned), "GET must return a config with an injectors array");
         assert.ok(!returned.some((ij) => ij.name === "draft-context"), "GET must not resurrect the default injector after an explicit empty patch");
     });
+    it("returns JSON 500 without overwriting a malformed identity config", async () => {
+        const configPath = path.join(vaultPath, ".vault-mind", "vault-mind.config.json");
+        const validConfig = fs.readFileSync(configPath, "utf-8");
+        const malformed = "{ invalid json";
+        fs.writeFileSync(configPath, malformed, "utf-8");
+        try {
+            const response = await fetch(`http://127.0.0.1:${port}/vault-mind/identities/main/allowedTools`, {
+                method: "PUT",
+                headers: {
+                    Authorization: `Bearer ${TEST_TOKEN}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ allowedTools: ["read", "write"] }),
+                signal: AbortSignal.timeout(1000),
+            });
+            const body = (await response.json());
+            assert.equal(response.status, 500);
+            assert.match(String(body.error), /Failed to update identity config/);
+            assert.equal(fs.readFileSync(configPath, "utf-8"), malformed);
+        }
+        finally {
+            fs.writeFileSync(configPath, validConfig, "utf-8");
+        }
+    });
 });

package/dist/test/utils.test.js

@@ -392,6 +392,19 @@ describe("loadConfig", () => {
         // Default embedding.localUrl should still be present from merge
         assert.equal(cfg.vaultMind.embedding.localUrl, "http://127.0.0.1:11434");
     });
+    it("loads legacy top-level identities into the canonical vaultMind identities path", () => {
+        writeConfig(testDir, {
+            identities: {
+                roles: {
+                    main: {
+                        allowedTools: ["read", "bash"],
+                    },
+                },
+            },
+        });
+        const cfg = loadConfig(testDir);
+        assert.deepEqual(cfg.vaultMind.identities?.roles?.main.allowedTools, ["read", "bash"]);
+    });
     it("resolves collection paths relative to cwd", () => {
         writeConfig(testDir, {
             collections: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-vault-mind",
-	"version": "0.16.28",
+	"version": "0.16.29",
 	"description": "Passive Obsidian vault extension for pi. Watches @agent markers, dispatches forked subagents (Miner, Broadcaster, Heavy-Lifter), stores in LanceDB with vector + FTS + graph. Multi-agent 'Drop & Forget' workflow for the pi agent ecosystem.",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/skills/.agents/broadcaster.agent.md

@@ -1,31 +0,0 @@
----
-type: BroadcasterAgent
-role: broadcaster
-capabilities: [read, write, edit]
-allowed_tools: [read, write, edit, vm_search, vm_fts_search]
-write_collections: []
-can_publish: false
-llm_provider: none
-llm_model: none
----
-
-# Broadcaster Agent
-
-Content distribution agent for pi-vault-mind. Creates presentations, summaries,
-and external-facing content from vault knowledge.
-
-## Capability Boundary
-
-- **MAY**: read files, write files, edit files
-- **MAY**: search collections via vm_search, vm_fts_search
-- **MUST NOT**: run bash commands, grep, or find
-- **MUST NOT**: write to the durable knowledge store
-- **MUST NOT**: publish or spawn sub-agents
-- Write output only under Agent/Presentations/
-
-## Tool Calling Convention
-
-When calling pi-vault-mind tools, always include your role:
-```
-vm_search({ query: "...", role: "broadcaster" })
-```

package/skills/.agents/heavy-lifter.agent.md

@@ -1,31 +0,0 @@
----
-type: HeavyLifterAgent
-role: heavy-lifter
-capabilities: [read, write, edit, grep, find, ls, bash]
-allowed_tools: [read, write, edit, grep, find, ls, bash, vm_search, vm_fts_search]
-write_collections: []
-can_publish: false
-llm_provider: none
-llm_model: none
----
-
-# Heavy-Lifter Agent
-
-External CLI execution agent for pi-vault-mind. Runs bash commands in an isolated
-worktree. Cannot write to the durable knowledge store — all findings must be
-routed to the Miner for storage.
-
-## Capability Boundary
-
-- **MAY**: read files, write files, edit files, run bash commands, search with grep/find/ls
-- **MUST NOT**: write to the durable store (vm_append, vm_sync disabled)
-- **MUST NOT**: spawn sub-agents
-- **MUST NOT**: publish to the human-facing vault
-- All bash commands run in an isolated worktree. Do not modify files outside it.
-
-## Tool Calling Convention
-
-When calling pi-vault-mind tools, always include your role:
-```
-vm_search({ query: "...", role: "heavy-lifter" })
-```

package/skills/.agents/manager.agent.md

@@ -1,30 +0,0 @@
----
-type: ManagerAgent
-role: manager
-capabilities: [read, write, edit, grep, find, ls]
-allowed_tools: [read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append, vm_sync, vm_promote, vm_query, vm_configure, vm_describe, vm_stats, vm_export, vm_ingest, vm_status, vm_graph_query]
-write_collections: [main, research, presentations]
-can_publish: true
-llm_provider: none
-llm_model: none
----
-
-# Manager Agent
-
-Final gate and publishing agent for pi-vault-mind. The only role authorized to
-publish to the human-facing vault and dispatch sub-agents.
-
-## Capability Boundary
-
-- **MAY**: all vm_* tools, read, write, edit, grep, find, ls
-- **MAY**: write to any collection
-- **MAY**: publish to the human-facing vault via vm_sync
-- **MAY**: dispatch sub-agents
-- **MUST NOT**: run bash commands
-
-## Tool Calling Convention
-
-When calling pi-vault-mind tools, always include your role:
-```
-vm_sync({ collection: "main", role: "manager" })
-```

package/skills/.agents/miner.agent.md

@@ -1,30 +0,0 @@
----
-type: MinerAgent
-role: miner
-capabilities: [read, write, edit, grep, find, ls]
-allowed_tools: [read, write, edit, grep, find, ls, vm_search, vm_fts_search, vm_append]
-write_collections: [main, research]
-can_publish: false
-llm_provider: none
-llm_model: none
----
-
-# Miner Agent
-
-Knowledge extraction and storage agent for pi-vault-mind. Extracts entities and
-relationships from vault content and stores them in the durable knowledge store.
-
-## Capability Boundary
-
-- **MAY**: read files, write files, edit files, search with grep/find/ls
-- **MAY**: append to collections 'main' and 'research' via vm_append
-- **MUST NOT**: run bash commands
-- **MUST NOT**: publish to the human-facing vault (vm_sync disabled)
-- **MUST NOT**: spawn sub-agents
-
-## Tool Calling Convention
-
-When calling pi-vault-mind tools, always include your role:
-```
-vm_append({ collection: "main", entry: {...}, role: "miner" })
-```