@openparachute/vault 0.7.0-rc.3 → 0.7.0-rc.5

package/src/routing.ts

@@ -70,6 +70,7 @@ import {
   handleUnresolvedWikilinks,
   handleStorage,
   handleViewNote,
+  handleDoctor,
   type TagScopeCtx,
   type WriteCtx,
 } from "./routes.ts";
@@ -825,6 +826,34 @@ export async function route(
     }
   }
 
+  // /api/doctor — read-only taxonomy/metadata integrity scan (vault#552).
+  // Same "dispatch before the generic read/write gate" shape as /triggers
+  // above, because this is ADMIN-tier regardless of method (GET-only, but
+  // admin — not read — since it's a whole-vault diagnostic, same tier as
+  // the MCP `doctor` tool and `prune-schema`).
+  if (apiMatch[1] === "/doctor") {
+    if (req.method !== "GET") {
+      return Response.json({ error: "Method not allowed", error_type: "method_not_allowed" }, { status: 405 });
+    }
+    if (!hasScopeForVault(auth.scopes, vaultName, "admin")) {
+      return Response.json(
+        {
+          error: "Forbidden",
+          error_type: "insufficient_scope",
+          message: `This endpoint requires the '${SCOPE_ADMIN}' scope (or '${SCOPE_ADMIN.replace("vault:", `vault:${vaultName}:`)}').`,
+          required_scope: SCOPE_ADMIN,
+          granted_scopes: auth.scopes,
+        },
+        { status: 403 },
+      );
+    }
+    const doctorTagScope: TagScopeCtx = {
+      allowed: await expandTokenTagScope(store, auth.scoped_tags),
+      raw: auth.scoped_tags,
+    };
+    return handleDoctor(req, store, doctorTagScope);
+  }
+
   // REST API — scope gate. GET/HEAD/OPTIONS → vault:read,
   // POST/PATCH/PUT/DELETE → vault:write. Inheritance (admin ⊇ write ⊇ read)
   // and the broad-vs-narrowed shape (`vault:<verb>` from pvt_*, or

package/src/tag-field-conflict-scope.test.ts

@@ -0,0 +1,333 @@
+/**
+ * Tag-scope scrub on cross-tag field-conflict errors (vault#554
+ * auth-and-scope review fold, refined by the wire review).
+ *
+ * Core's cross-tag field validation (`collectCrossTagFieldViolations` /
+ * `collectTagFieldViolations`, core/src/tag-schemas.ts) scans EVERY tag's
+ * schema — scope-unaware by architecture — so a tag-scoped caller updating
+ * its own in-scope tag used to receive violations NAMING an out-of-scope
+ * tag and revealing its declared type/indexed flag (proven live on both MCP
+ * and REST during review). The fix keeps the rejection (schema integrity is
+ * scope-independent) but generalizes any violation whose conflicting
+ * declarer is outside the caller's allowlist: no tag name, no declared
+ * type/flag, `other_tag` dropped (`scrubTagFieldViolationsByScope`,
+ * src/tag-scope.ts). In-scope declarers keep full detail; unscoped callers
+ * are untouched.
+ *
+ * The same information leaks through a SECOND door (wire-review
+ * interaction): a BOTH-indexed cross-tag type conflict deliberately
+ * bypasses the 422 pre-check to preserve its pre-existing `declareField` →
+ * 400 `invalid_indexed_field` contract, and declareField's message names
+ * the other declarer tag(s) + their sqlite type. `scrubIndexedFieldConflictError`
+ * generalizes that message for scoped callers — same 400, same error_type,
+ * no leak. Covered on both surfaces below.
+ *
+ * Fixture: PARACHUTE_HOME temp home + hand-built AuthResult, same pattern
+ * as mcp-list-tags-scope.test.ts.
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { handleTags } from "./routes.ts";
+import type { AuthResult } from "./auth.ts";
+import { TagFieldConflictError } from "../core/src/tag-schemas.ts";
+import { IndexedFieldError } from "../core/src/indexed-fields.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-tagconflict-scope-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null): AuthResult {
+  return {
+    permission: "full",
+    scopes: [`vault:${vaultName}:read`, `vault:${vaultName}:write`],
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function updateTagTool(vaultName: string, scopedTags: string[] | null) {
+  const tools = generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags));
+  return tools.find((t) => t.name === "update-tag")!;
+}
+
+/** Everything an agent-facing serialization of the error could carry. */
+function serializeError(err: TagFieldConflictError): string {
+  return JSON.stringify({ message: err.message, tag: err.tag, violations: err.violations });
+}
+
+describe("tag_field_conflict × tag scope — out-of-scope declarers scrubbed (vault#554 fold)", () => {
+  test("MCP: scoped caller + out-of-scope NON-indexed type conflict → still rejected (422 class), but the out-of-scope tag's name and schema appear NOWHERE in the error", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // Out-of-scope declarer with a distinctive name + type (non-indexed —
+    // the both-indexed variant routes through the 400 path, tested below).
+    await store.upsertTagRecord("project-manhattan", {
+      fields: { x: { type: "string" } },
+    });
+    // Caller's own in-scope tag.
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const tool = await updateTagTool("journal", ["mine"]);
+    let caught: unknown;
+    try {
+      await tool.execute({ tag: "mine", fields: { x: { type: "integer" } } });
+    } catch (e) {
+      caught = e;
+    }
+
+    // The write is STILL rejected — integrity is scope-independent.
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(1);
+    expect(err.violations[0]!.field).toBe("x");
+    expect(err.violations[0]!.reason).toBe("type_conflict");
+    expect(err.message).toContain("no changes were applied");
+
+    // The scrub: no tag name, no declared type, no other_tag — anywhere.
+    expect(err.violations[0]!.other_tag).toBeUndefined();
+    const serialized = serializeError(err);
+    expect(serialized).not.toContain("project-manhattan");
+    expect(serialized).not.toContain('declares "string"');
+
+    // Nothing persisted.
+    const mine = await store.getTagRecord("mine");
+    expect(mine?.fields ?? null).toBeFalsy();
+  });
+
+  test("MCP: scoped caller + IN-scope conflict keeps full detail (tag name + declared type + other_tag)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine-too", {
+      fields: { x: { type: "string" } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const tool = await updateTagTool("journal", ["mine", "mine-too"]);
+    let caught: unknown;
+    try {
+      await tool.execute({ tag: "mine", fields: { x: { type: "integer" } } });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(1);
+    expect(err.violations[0]!.other_tag).toBe("mine-too");
+    expect(err.violations[0]!.message).toContain("mine-too");
+    expect(err.violations[0]!.message).toContain('declares "string"');
+  });
+
+  test("REST: scoped caller + out-of-scope NON-indexed type conflict → 422 with generalized violation, out-of-scope tag name nowhere in the body", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project-manhattan", {
+      fields: { x: { type: "string" } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const req = new Request("http://localhost/api/tags/mine", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer" } } }),
+    });
+    const res = await handleTags(req, store, "/mine", {
+      allowed: new Set(["mine"]),
+      raw: ["mine"],
+    });
+
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("tag_field_conflict");
+    expect(body.violations).toHaveLength(1);
+    expect(body.violations[0].field).toBe("x");
+    expect(body.violations[0].reason).toBe("type_conflict");
+    expect(body.violations[0].other_tag).toBeUndefined();
+    expect(body.message).toContain("no changes were applied");
+
+    const serialized = JSON.stringify(body);
+    expect(serialized).not.toContain("project-manhattan");
+    expect(serialized).not.toContain('declares "string"');
+
+    const mine = await store.getTagRecord("mine");
+    expect(mine?.fields ?? null).toBeFalsy();
+  });
+
+  test("REST: scoped caller + IN-scope conflict keeps full detail", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine-too", {
+      fields: { x: { type: "string" } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const req = new Request("http://localhost/api/tags/mine", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer" } } }),
+    });
+    const res = await handleTags(req, store, "/mine", {
+      allowed: new Set(["mine", "mine-too"]),
+      raw: ["mine", "mine-too"],
+    });
+
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.violations).toHaveLength(1);
+    expect(body.violations[0].other_tag).toBe("mine-too");
+    expect(body.violations[0].message).toContain("mine-too");
+    expect(body.violations[0].message).toContain('declares "string"');
+  });
+
+  test("unscoped callers keep full detail everywhere (MCP + REST controls)", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project-manhattan", {
+      fields: { x: { type: "string" } },
+    });
+
+    // MCP — unscoped session: applyTagScopeWrappers never installs, core's
+    // full-detail error passes through untouched.
+    const tool = await updateTagTool("journal", null);
+    let caught: unknown;
+    try {
+      await tool.execute({ tag: "mine", fields: { x: { type: "integer" } } });
+    } catch (e) {
+      caught = e;
+    }
+    const err = caught as TagFieldConflictError;
+    expect(err.violations[0]!.other_tag).toBe("project-manhattan");
+    expect(err.violations[0]!.message).toContain("project-manhattan");
+
+    // REST — unscoped ctx (allowed === null): scrub is a no-op.
+    const req = new Request("http://localhost/api/tags/mine", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer" } } }),
+    });
+    const res = await handleTags(req, store, "/mine");
+    expect(res.status).toBe(422);
+    const body: any = await res.json();
+    expect(body.violations[0].other_tag).toBe("project-manhattan");
+    expect(body.violations[0].message).toContain("project-manhattan");
+  });
+});
+
+describe("invalid_indexed_field × tag scope — the 400 door is scrubbed too (wire-review interaction)", () => {
+  test("REST: scoped caller + BOTH-indexed type conflict vs out-of-scope tag → 400 invalid_indexed_field (status preserved) with a generalized message", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project-manhattan", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const req = new Request("http://localhost/api/tags/mine", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/mine", {
+      allowed: new Set(["mine"]),
+      raw: ["mine"],
+    });
+
+    // Status + error_type are the PRESERVED pre-existing contract; only
+    // the message prose is generalized for the scoped caller.
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+    expect(body.error).toContain('field "x"');
+    expect(body.error).toContain("outside your token's tag scope");
+    const serialized = JSON.stringify(body);
+    expect(serialized).not.toContain("project-manhattan");
+    expect(serialized).not.toContain("TEXT"); // the existing sqlite type stays hidden too
+
+    // Still rejected — nothing persisted.
+    const mine = await store.getTagRecord("mine");
+    expect(mine?.fields ?? null).toBeFalsy();
+  });
+
+  test("MCP: scoped caller + BOTH-indexed type conflict vs out-of-scope tag → IndexedFieldError with a generalized message", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("project-manhattan", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    const tool = await updateTagTool("journal", ["mine"]);
+    let caught: any;
+    try {
+      await tool.execute({ tag: "mine", fields: { x: { type: "integer", indexed: true } } });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(IndexedFieldError);
+    expect(caught.error_type).toBe("invalid_indexed_field");
+    expect(caught.message).toContain("outside your token's tag scope");
+    expect(caught.message).not.toContain("project-manhattan");
+    expect(caught.message).not.toContain("TEXT");
+    // The structured declarer context is dropped from the scrubbed error.
+    expect(caught.declarer_tags).toBeUndefined();
+  });
+
+  test("both-indexed conflict vs an IN-scope tag keeps declareField's full message on both surfaces", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine-too", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+    await store.upsertTagRecord("mine", { description: "in scope" });
+
+    // REST
+    const req = new Request("http://localhost/api/tags/mine", {
+      method: "PUT",
+      body: JSON.stringify({ fields: { x: { type: "integer", indexed: true } } }),
+    });
+    const res = await handleTags(req, store, "/mine", {
+      allowed: new Set(["mine", "mine-too"]),
+      raw: ["mine", "mine-too"],
+    });
+    expect(res.status).toBe(400);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("invalid_indexed_field");
+    expect(body.error).toContain("mine-too");
+
+    // MCP
+    const tool = await updateTagTool("journal", ["mine", "mine-too"]);
+    let caught: any;
+    try {
+      await tool.execute({ tag: "mine", fields: { x: { type: "integer", indexed: true } } });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(IndexedFieldError);
+    expect(caught.message).toContain("mine-too");
+  });
+});

package/src/tag-integrity-mcp.test.ts

@@ -0,0 +1,288 @@
+/**
+ * End-to-end coverage for the vault#552 MCP + REST surface: rename-tag and
+ * merge-tags tool wiring (verb + tag-scope gating), delete-tag's
+ * cascade/detach flags flowing through the MCP wrapper, and the `doctor`
+ * tool/endpoint's admin-gate + tag-scope filtering. Fixture pattern mirrors
+ * tag-field-conflict-scope.test.ts (PARACHUTE_HOME temp home + hand-built
+ * AuthResult).
+ */
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { mkdirSync, rmSync, existsSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { writeVaultConfig } from "./config.ts";
+import { getVaultStore, clearVaultStoreCache } from "./vault-store.ts";
+import { generateScopedMcpTools } from "./mcp-tools.ts";
+import { handleTags, handleDoctor, type TagScopeCtx } from "./routes.ts";
+import type { AuthResult } from "./auth.ts";
+
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(() => {
+  tmpHome = join(tmpdir(), `vault-tag-integrity-mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpHome, "vault", "data"), { recursive: true });
+  prevHome = process.env.PARACHUTE_HOME;
+  process.env.PARACHUTE_HOME = tmpHome;
+  clearVaultStoreCache();
+});
+
+afterEach(() => {
+  clearVaultStoreCache();
+  if (prevHome === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = prevHome;
+  if (existsSync(tmpHome)) rmSync(tmpHome, { recursive: true, force: true });
+});
+
+function seedVault(name: string): void {
+  writeVaultConfig({ name, api_keys: [], created_at: new Date().toISOString() });
+  getVaultStore(name);
+}
+
+function authFor(vaultName: string, scopedTags: string[] | null, verb: "read" | "write" | "admin" = "write"): AuthResult {
+  const verbs = verb === "admin" ? ["read", "write", "admin"] : verb === "write" ? ["read", "write"] : ["read"];
+  return {
+    permission: "full",
+    scopes: verbs.map((v) => `vault:${vaultName}:${v}`),
+    legacyDerived: false,
+    scoped_tags: scopedTags,
+    vault_name: null,
+    caller_jti: null,
+    actor: "test-user",
+    via: "api",
+  };
+}
+
+async function toolsFor(vaultName: string, scopedTags: string[] | null, verb: "read" | "write" | "admin" = "write") {
+  return generateScopedMcpTools(vaultName, authFor(vaultName, scopedTags, verb));
+}
+
+describe("rename-tag / merge-tags — tag-scope gating (vault#552)", () => {
+  test("rename-tag: old_name or new_name outside the allowlist is refused before reaching core", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("theirs", {});
+
+    const tools = await toolsFor("journal", ["mine"]);
+    const renameTag = tools.find((t) => t.name === "rename-tag")!;
+
+    const result = await renameTag.execute({ old_name: "theirs", new_name: "mine2" }) as any;
+    expect(result.error_type).toBe("tag_scope_violation");
+
+    // Untouched.
+    expect(await store.getTagRecord("theirs")).not.toBeNull();
+  });
+
+  test("rename-tag: both names in-scope reaches core (wrapper doesn't spuriously block), which reports target_exists for an already-live target", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("mine-other", {});
+
+    // Both names are directly scoped (each tag is trivially a member of its
+    // own descendant set), so the wrapper's scope check passes and the call
+    // reaches core — which correctly refuses because "mine-other" already
+    // exists (rename never silently overwrites; that's what merge-tags is
+    // for). Proves the wrapper isn't the thing blocking this, core is.
+    const tools = await toolsFor("journal", ["mine", "mine-other"]);
+    const renameTag = tools.find((t) => t.name === "rename-tag")!;
+    let caught: any;
+    try {
+      await renameTag.execute({ old_name: "mine", new_name: "mine-other" });
+    } catch (e) { caught = e; }
+    expect(caught?.error_type).toBe("target_exists");
+  });
+
+  test("merge-tags: a source outside the allowlist is refused before reaching core", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("theirs", {});
+
+    const tools = await toolsFor("journal", ["mine"]);
+    const mergeTags = tools.find((t) => t.name === "merge-tags")!;
+    const result = await mergeTags.execute({ sources: ["theirs"], target: "mine" }) as any;
+    expect(result.error_type).toBe("tag_scope_violation");
+    expect(await store.getTagRecord("theirs")).not.toBeNull();
+  });
+
+  test("merge-tags: a source referenced by a tag-scoped token is refused (409-equivalent), independent of the CALLER's own scope", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", {});
+    await store.upsertTagRecord("locked", {});
+    // A DIFFERENT (vestigial) tag-scoped token row references "locked" —
+    // merging it away would orphan that token's allowlist. Raw INSERT, same
+    // fixture pattern as vault.test.ts's "MCP delete-tag returns
+    // tag_in_use_by_tokens..." — vault no longer mints these post-0.5.0, but
+    // findTokensReferencingTag still guards against leftover rows.
+    store.db
+      .prepare(
+        "INSERT INTO tokens (token_hash, label, permission, scoped_tags, created_at) VALUES (?, ?, ?, ?, ?)",
+      )
+      .run(
+        `sha256:locked-claw-${Math.random().toString(36).slice(2)}`,
+        "locked-claw",
+        "read",
+        JSON.stringify(["locked"]),
+        new Date().toISOString(),
+      );
+
+    const tools = await toolsFor("journal", null); // unscoped caller — still blocked by the token-reference guard
+    const mergeTags = tools.find((t) => t.name === "merge-tags")!;
+    const result = await mergeTags.execute({ sources: ["locked"], target: "mine" }) as any;
+    expect(result.error_type).toBe("tag_in_use_by_tokens");
+    expect(await store.getTagRecord("locked")).not.toBeNull();
+  });
+});
+
+describe("delete-tag cascade/detach — MCP wrapper pass-through (vault#552)", () => {
+  test("cascade:true flows through the tag-scope wrapper to the underlying store call", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine", { description: "root" });
+    await store.upsertTagRecord("mine-child", { parent_names: ["mine"] });
+
+    const tools = await toolsFor("journal", ["mine"]); // "mine-child" is a descendant, also in-scope
+    const deleteTag = tools.find((t) => t.name === "delete-tag")!;
+
+    const refused = await deleteTag.execute({ tag: "mine" }) as any;
+    expect(refused.error).toBe("tag_referenced_as_parent");
+
+    const cascaded = await deleteTag.execute({ tag: "mine", cascade: true }) as any;
+    expect(cascaded.deleted).toBe(true);
+    expect(await store.getTagRecord("mine")).toBeNull();
+  });
+});
+
+describe("doctor — admin gate + tag-scope filtering (vault#552)", () => {
+  test("MCP: doctor is invisible in tools/list to a write-only (non-admin) session, and excluded-tool-called-explicitly still refuses it", async () => {
+    // `generateScopedMcpTools` (the `toolsFor` helper) always returns the
+    // FULL tool set — the `requiredVerb` visibility filter lives one layer
+    // up, in `handleScopedMcp`'s tools/list dispatch (mcp-http.ts). Drive
+    // through that layer, same pattern as vault.test.ts's `listToolNames`.
+    seedVault("journal");
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const listReq = new Request("http://localhost:1940/vault/journal/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
+    });
+    const listRes = await handleScopedMcp(listReq, "journal", authFor("journal", null, "write"));
+    const listBody = await listRes.json() as any;
+    const names: string[] = listBody.result.tools.map((t: any) => t.name);
+    expect(names).not.toContain("doctor");
+
+    // Explicitly calling it anyway is refused, not silently executed.
+    const callReq = new Request("http://localhost:1940/vault/journal/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "doctor", arguments: {} } }),
+    });
+    const callRes = await handleScopedMcp(callReq, "journal", authFor("journal", null, "write"));
+    const callBody = await callRes.json() as any;
+    expect(callBody.result?.isError).toBe(true);
+  });
+
+  test("MCP: doctor is visible + callable for an admin session, and a scoped admin session only reports in-scope findings", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    // In-scope dangling parent_names.
+    await store.upsertTagRecord("mine-broken", { parent_names: ["mine-ghost-parent"] });
+    // Out-of-scope dangling parent_names — must not appear in a scoped report.
+    await store.upsertTagRecord("theirs-broken", { parent_names: ["theirs-ghost-parent"] });
+
+    const unscopedTools = await toolsFor("journal", null, "admin");
+    const unscopedDoctor = unscopedTools.find((t) => t.name === "doctor")!;
+    const unscopedReport = await unscopedDoctor.execute({}) as any;
+    const unscopedSubjects = unscopedReport.findings.map((f: any) => f.subject);
+    expect(unscopedSubjects).toContain("mine-broken");
+    expect(unscopedSubjects).toContain("theirs-broken");
+
+    const scopedTools = await toolsFor("journal", ["mine-broken"], "admin");
+    const scopedDoctor = scopedTools.find((t) => t.name === "doctor")!;
+    const scopedReport = await scopedDoctor.execute({}) as any;
+    const scopedSubjects = scopedReport.findings.map((f: any) => f.subject);
+    expect(scopedSubjects).toContain("mine-broken");
+    expect(scopedSubjects).not.toContain("theirs-broken");
+  });
+
+  test("REST: GET /api/doctor reports findings filtered to the tag-scoped caller's allowlist", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("mine-broken", { parent_names: ["mine-ghost-parent"] });
+    await store.upsertTagRecord("theirs-broken", { parent_names: ["theirs-ghost-parent"] });
+
+    const tagScope: TagScopeCtx = { allowed: new Set(["mine-broken"]), raw: ["mine-broken"] };
+    const res = await handleDoctor(new Request("http://localhost/api/doctor"), store, tagScope);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    const subjects = body.findings.map((f: any) => f.subject);
+    expect(subjects).toContain("mine-broken");
+    expect(subjects).not.toContain("theirs-broken");
+  });
+});
+
+describe("parent_cycle — REST PUT /api/tags/:name surfaces the 409 (vault#552)", () => {
+  test("A→B then B→A is rejected with error_type parent_cycle, naming the cycle", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("b", {});
+    await store.upsertTagRecord("a", { parent_names: ["b"] });
+
+    const req = new Request("http://localhost/api/tags/b", {
+      method: "PUT",
+      body: JSON.stringify({ parent_names: ["a"] }),
+    });
+    const res = await handleTags(req, store, "/b");
+    expect(res.status).toBe(409);
+    const body: any = await res.json();
+    expect(body.error_type).toBe("parent_cycle");
+    expect(body.tag).toBe("b");
+    expect(body.cycle).toContain("a");
+    expect(body.cycle).toContain("b");
+    // MUST-FIX 5 (wire review): a `message` key is load-bearing — the shared
+    // parachute-surface VaultClient 409 handler reads `body.message` (else it
+    // shows a hardcoded "Note was edited elsewhere"). `error` is the short
+    // code, `message` the human sentence — same split every sibling 409 uses.
+    expect(typeof body.message).toBe("string");
+    expect(body.message.length).toBeGreaterThan(0);
+    expect(body.message).toMatch(/cycle/i);
+    expect(body.error).toBe("ParentCycle");
+    expect(body.error).not.toContain(" "); // short code, not the full sentence
+
+    // Nothing persisted.
+    expect((await store.getTagRecord("b"))?.parent_names ?? null).toBeFalsy();
+  });
+});
+
+describe("tag_referenced_as_parent — REST DELETE /api/tags/:name surfaces the 409 + flags (vault#552)", () => {
+  test("refused by default, cascade query param proceeds", async () => {
+    seedVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("root", {});
+    await store.upsertTagRecord("child", { parent_names: ["root"] });
+
+    const refusedRes = await handleTags(new Request("http://localhost/api/tags/root", { method: "DELETE" }), store, "/root");
+    expect(refusedRes.status).toBe(409);
+    const refusedBody: any = await refusedRes.json();
+    expect(refusedBody.error_type).toBe("tag_referenced_as_parent");
+    expect(refusedBody.referencing_tags).toEqual(["child"]);
+    // Same short-code-`error` + human-`message` split as every sibling 409
+    // (wire consistency — parachute-surface reads `body.message`).
+    expect(refusedBody.error).toBe("TagReferencedAsParent");
+    expect(typeof refusedBody.message).toBe("string");
+    expect(refusedBody.message.length).toBeGreaterThan(0);
+
+    const cascadedRes = await handleTags(
+      new Request("http://localhost/api/tags/root?cascade=true", { method: "DELETE" }),
+      store,
+      "/root",
+    );
+    expect(cascadedRes.status).toBe(200);
+    const cascadedBody: any = await cascadedRes.json();
+    expect(cascadedBody.deleted).toBe(true);
+    expect(cascadedBody.parent_refs_detached).toBe(1);
+  });
+});