@openparachute/vault 0.6.0-rc.1 → 0.6.0

package/src/live-match.ts

@@ -0,0 +1,310 @@
+/**
+ * In-process query matcher for live subscriptions (live-query SSE — design
+ * `design/2026-06-08-live-query-sse.md`).
+ *
+ * The snapshot path evaluates a `QueryOpts` against the DB via the SQL query
+ * engine (`core/src/notes.ts queryNotes`). The live path can't go back to the
+ * DB for every mutation — the changed note is already in hand from the
+ * post-commit hook — so this module re-implements the *supported subset* of
+ * the query predicate against a single in-memory `Note`.
+ *
+ * **Predicate parity is the contract.** For any supported query, the set of
+ * notes the snapshot SQL returns MUST equal the set this matcher accepts.
+ * `subscribe.test.ts` enforces that over a seeded corpus. Every clause below
+ * is written to mirror the exact SQL semantics in `queryNotes`:
+ *
+ *   - `tags` ("all"/"any") with descendant expansion — mirrors the per-input
+ *     `_tagsExpanded` JOINs (each input tag matches the input OR any declared
+ *     descendant). Expansion is resolved ONCE at subscribe time (see
+ *     `buildLiveMatcher`) and frozen into the matcher, exactly as the engine
+ *     freezes it for the snapshot query.
+ *   - `excludeTags` — raw exact-name match (engine does NOT expand excludes).
+ *   - `path` — case-insensitive exact (engine: `n.path = ? COLLATE NOCASE`).
+ *   - `pathPrefix` — prefix (engine: `n.path LIKE prefix || '%'`).
+ *   - `extension` — lower-cased, default "md" (engine: `LOWER(n.extension)`),
+ *     a note with no extension is treated as "md".
+ *   - `metadata` operator objects (eq/ne/gt/gte/lt/lte/in/not_in/exists) +
+ *     primitive exact-match — mirrors `buildOperatorClause` / the json_extract
+ *     shorthand. NULL-aware exactly like the SQL (`ne`/`not_in` match the
+ *     field-absent row; `eq null` matches absence).
+ *
+ *   - `hasTags` (presence) — `note.tags?.length > 0`, trivial + parity-safe.
+ *
+ * **Unsupported (rejected upstream with 400, never reach the matcher):**
+ * `search` (FTS) and `near` (graph BFS) — not evaluable against a single note;
+ * `hasLinks` — needs the `links` table (not on the in-hand note); date filters
+ * (`dateFrom`/`dateTo`/`dateFilter`) — parity risk + some need indexed columns;
+ * `cursor` — paging is meaningless for a live set. The subscribe route returns
+ * 400 for these BEFORE a subscription is created (see
+ * `unsupportedSubscriptionReason` + the route's raw-param checks).
+ *
+ * **Ignored (irrelevant to set membership):** `orderBy`, `limit`, `offset`,
+ * `ids`. The route strips `limit`/`offset` from the snapshot query so the
+ * snapshot is the COMPLETE matching set (parity with the unbounded matcher).
+ */
+
+import type { Note, QueryOpts, Store } from "../core/src/types.ts";
+import { SUPPORTED_OPS } from "../core/src/query-operators.ts";
+
+const OPS_SET: ReadonlySet<string> = new Set<string>(SUPPORTED_OPS);
+
+/**
+ * Frozen, pre-resolved form of a `QueryOpts` for fast per-note matching.
+ * Tag descendant expansion (a DB read) is done once here, not per event.
+ */
+export interface LiveMatcher {
+  /** The original supported opts (for diagnostics / parity tests). */
+  readonly opts: QueryOpts;
+  /**
+   * Per-input-tag expanded sets: `tagSets[i]` = `{tags[i]} ∪ descendants`.
+   * Mirrors `_tagsExpanded` in the engine. Empty when no `tags` filter.
+   * A note matches under "all" iff it carries ≥1 tag from EACH set; under
+   * "any" iff it carries ≥1 tag from the UNION.
+   */
+  readonly tagSets: string[][];
+  readonly tagMatch: "all" | "any";
+  readonly excludeTags: string[];
+  match(note: Note): boolean;
+}
+
+/**
+ * Query shapes a live subscription can't evaluate against a single note.
+ * The route layer rejects these with 400 before creating a subscription.
+ */
+export function unsupportedSubscriptionReason(opts: QueryOpts): string | null {
+  // `search` / `near` are parsed/handled by the notes route separately; the
+  // subscribe route detects them from raw query params. These guards catch the
+  // remaining shapes that the matcher can't faithfully evaluate against a
+  // single in-hand note (so snapshot and live would disagree).
+  if (opts.cursor) {
+    return "cursor pagination is not supported for live subscriptions";
+  }
+  if (opts.hasLinks !== undefined) {
+    return "has_links is not supported for live subscriptions (requires the links table)";
+  }
+  if (opts.dateFilter || opts.dateFrom || opts.dateTo) {
+    return "date filters are not supported for live subscriptions";
+  }
+  return null;
+}
+
+function metaValue(note: Note, key: string): unknown {
+  const m = note.metadata;
+  if (!m || typeof m !== "object") return undefined;
+  return (m as Record<string, unknown>)[key];
+}
+
+/**
+ * Compare two primitives the way SQLite's generated `meta_<field>` column
+ * would for ordering operators. Values stored via the indexed column are
+ * primitives; we compare numbers numerically and strings lexically, matching
+ * SQLite's type affinity for a column holding the JSON-extracted scalar.
+ */
+function cmp(a: unknown, b: unknown): number | null {
+  if (typeof a === "number" && typeof b === "number") return a < b ? -1 : a > b ? 1 : 0;
+  // Booleans compare as their numeric form (SQLite stores 1/0).
+  const an = typeof a === "boolean" ? (a ? 1 : 0) : a;
+  const bn = typeof b === "boolean" ? (b ? 1 : 0) : b;
+  if (typeof an === "number" && typeof bn === "number") return an < bn ? -1 : an > bn ? 1 : 0;
+  const as = String(an);
+  const bs = String(bn);
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+/** Loose equality mirroring the json_extract shorthand + operator `eq`. */
+function looseEq(actual: unknown, expected: unknown): boolean {
+  if (actual === expected) return true;
+  // Numbers vs numeric strings: the engine's operator path binds the raw
+  // value to an indexed numeric column, so `5` and `5` match; the shorthand
+  // path stringifies. Normalize via string compare as a backstop.
+  if (actual == null || expected == null) return actual === expected;
+  if (typeof actual === "boolean" || typeof expected === "boolean") {
+    return (actual ? 1 : 0) === (expected ? 1 : 0) || String(actual) === String(expected);
+  }
+  return String(actual) === String(expected);
+}
+
+function evalOperatorObject(actual: unknown, opObj: Record<string, unknown>): boolean {
+  for (const [op, expected] of Object.entries(opObj)) {
+    switch (op) {
+      case "eq":
+        if (expected === null) {
+          if (actual !== undefined && actual !== null) return false;
+        } else if (!looseEq(actual, expected)) {
+          return false;
+        }
+        break;
+      case "ne":
+        // SQL: (col IS NULL OR col <> ?) — absent field passes; equal fails.
+        if (expected === null) {
+          if (actual === undefined || actual === null) return false;
+        } else if (actual !== undefined && actual !== null && looseEq(actual, expected)) {
+          return false;
+        }
+        break;
+      case "gt":
+      case "gte":
+      case "lt":
+      case "lte": {
+        // SQL comparison operators yield NULL (→ excluded) when the column
+        // is NULL/absent.
+        if (actual === undefined || actual === null) return false;
+        const c = cmp(actual, expected);
+        if (c === null) return false;
+        if (op === "gt" && !(c > 0)) return false;
+        if (op === "gte" && !(c >= 0)) return false;
+        if (op === "lt" && !(c < 0)) return false;
+        if (op === "lte" && !(c <= 0)) return false;
+        break;
+      }
+      case "in": {
+        if (!Array.isArray(expected)) return false;
+        if (expected.length === 0) return false; // engine emits `0`
+        if (actual === undefined || actual === null) return false;
+        if (!expected.some((v) => looseEq(actual, v))) return false;
+        break;
+      }
+      case "not_in": {
+        if (!Array.isArray(expected)) return false;
+        if (expected.length === 0) break; // engine emits `1` (no-op pass)
+        // SQL: (col IS NULL OR col NOT IN (...)) — absent passes.
+        if (actual === undefined || actual === null) break;
+        if (expected.some((v) => looseEq(actual, v))) return false;
+        break;
+      }
+      case "exists": {
+        const present = actual !== undefined && actual !== null;
+        if (expected === true && !present) return false;
+        if (expected === false && present) return false;
+        break;
+      }
+      default:
+        // Unknown operator — the snapshot path would have thrown
+        // UNKNOWN_OPERATOR at query time, so this never matches.
+        return false;
+    }
+  }
+  return true;
+}
+
+/** True iff every key of `value` is a supported operator (operator-object). */
+function isOperatorObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const keys = Object.keys(value as object);
+  if (keys.length === 0) return false;
+  return keys.every((k) => OPS_SET.has(k));
+}
+
+/**
+ * Resolve a `QueryOpts` into a frozen `LiveMatcher`, expanding tag descendants
+ * once via the store (the same hierarchy the snapshot query uses). Call at
+ * subscribe time; the returned matcher is pure + sync for per-event use.
+ */
+export async function buildLiveMatcher(store: Store, opts: QueryOpts): Promise<LiveMatcher> {
+  const tags = opts.tags ?? [];
+  const tagMatch: "all" | "any" = opts.tagMatch ?? "all";
+  // Per-input expansion along the SAME axis the snapshot query uses
+  // (vault tag `expand` axis). `opts.expand` (default "subtypes") MUST be
+  // threaded through here so the live matcher and the snapshot query engine
+  // lower the IDENTICAL expansion — otherwise a subscription's snapshot and
+  // its live events would disagree on which notes match. `expandTags` already
+  // includes each input tag.
+  const tagSets: string[][] = [];
+  for (const t of tags) {
+    const set = await store.expandTags([t], opts.expand);
+    // Be defensive: ensure the root is present (expandTags always includes it
+    // for non-empty input, but the contract should not rely on it here).
+    set.add(t);
+    tagSets.push(Array.from(set));
+  }
+  const excludeTags = opts.excludeTags ?? [];
+
+  const matcher: LiveMatcher = {
+    opts,
+    tagSets,
+    tagMatch,
+    excludeTags,
+    match(note: Note): boolean {
+      return matchAgainst(note, opts, tagSets, tagMatch, excludeTags);
+    },
+  };
+  return matcher;
+}
+
+function matchAgainst(
+  note: Note,
+  opts: QueryOpts,
+  tagSets: string[][],
+  tagMatch: "all" | "any",
+  excludeTags: string[],
+): boolean {
+  const noteTags = note.tags ?? [];
+
+  // ---- tags ----
+  if (tagSets.length > 0) {
+    if (tagMatch === "any") {
+      const union = new Set(tagSets.flat());
+      if (!noteTags.some((t) => union.has(t))) return false;
+    } else {
+      // "all": for each input tag's expanded set, the note must carry ≥1.
+      for (const set of tagSets) {
+        if (set.length === 0) continue;
+        const s = new Set(set);
+        if (!noteTags.some((t) => s.has(t))) return false;
+      }
+    }
+  }
+
+  // ---- excludeTags (raw exact, no expansion — mirrors engine) ----
+  for (const ex of excludeTags) {
+    if (noteTags.includes(ex)) return false;
+  }
+
+  // ---- hasTags (presence) — ignored by the engine when a `tags` filter is
+  // also set (the tag filter already constrains to tagged notes), so mirror
+  // that: only apply when there's no `tags` filter. See queryNotes
+  // `filterByTags` short-circuit.
+  if (opts.hasTags !== undefined && tagSets.length === 0) {
+    const has = noteTags.length > 0;
+    if (opts.hasTags !== has) return false;
+  }
+
+  // ---- path (case-insensitive exact) ----
+  if (opts.path) {
+    if (!note.path || note.path.toLowerCase() !== opts.path.toLowerCase()) return false;
+  }
+
+  // ---- pathPrefix (case-insensitive — the engine uses `LIKE prefix || '%'`,
+  // and SQLite LIKE is ASCII-case-insensitive by default) ----
+  if (opts.pathPrefix) {
+    if (!note.path || !note.path.toLowerCase().startsWith(opts.pathPrefix.toLowerCase())) return false;
+  }
+
+  // ---- extension (lower-cased; default "md") ----
+  if (opts.extension !== undefined) {
+    const exts = Array.isArray(opts.extension) ? opts.extension : [opts.extension];
+    const cleaned = exts
+      .filter((e): e is string => typeof e === "string" && e.length > 0)
+      .map((e) => e.toLowerCase());
+    if (cleaned.length > 0) {
+      const noteExt = (note.extension ?? "md").toLowerCase();
+      if (!cleaned.includes(noteExt)) return false;
+    }
+  }
+
+  // ---- metadata ----
+  if (opts.metadata) {
+    for (const [key, value] of Object.entries(opts.metadata)) {
+      const actual = metaValue(note, key);
+      if (isOperatorObject(value)) {
+        if (!evalOperatorObject(actual, value)) return false;
+      } else {
+        // Primitive exact-match (json_extract shorthand). The engine compares
+        // the JSON-extracted scalar against the string/JSON form.
+        if (!looseEq(actual, value)) return false;
+      }
+    }
+  }
+
+  return true;
+}

package/src/mcp-install.test.ts

@@ -23,7 +23,9 @@ import {
   buildMcpEntryPlan,
   chooseHubOrigin,
   chooseMcpUrl,
+  detectHubPresence,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -315,6 +317,97 @@ describe("readOperatorToken", () => {
   });
 });
 
+describe("detectHubPresence", () => {
+  let origHome: string | undefined;
+  let tmpHome: string;
+
+  beforeEach(() => {
+    origHome = process.env.PARACHUTE_HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "vault-hub-presence-"));
+    process.env.PARACHUTE_HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  test("a configured non-loopback hub origin counts as present (no probe)", async () => {
+    let probed = false;
+    const mockFetch: typeof fetch = async () => {
+      probed = true;
+      return new Response(null, { status: 500 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_ORIGIN: "https://hub.example" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(probed).toBe(false); // configured origin short-circuits the probe
+  });
+
+  test("loopback + healthy hub (2xx /health) → present", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(true);
+    expect(calls).toHaveLength(1);
+    // Probes the hub's fixed loopback port (1939), not vault's listen port.
+    expect(calls[0]).toBe("http://127.0.0.1:1939/health");
+  });
+
+  test("loopback + no hub answering (fetch throws) → absent", async () => {
+    const mockFetch: typeof fetch = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("loopback + hub answers non-2xx → absent", async () => {
+    const mockFetch: typeof fetch = async () => new Response("nope", { status: 503 });
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("$PARACHUTE_HUB_PORT overrides the probed port (deterministic for tests)", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_PORT: "59399" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(calls[0]).toBe("http://127.0.0.1:59399/health");
+  });
+});
+
+describe("noOperatorTokenGuidance (#445)", () => {
+  test("hub present → non-circular 'finish in the wizard' copy", () => {
+    const msg = noOperatorTokenGuidance(true);
+    // Does NOT tell the operator to install the hub (circular — this flow ran
+    // *under* the hub).
+    expect(msg).not.toContain("Install the hub");
+    expect(msg).not.toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("admin wizard mints");
+    expect(msg).toContain("Nothing to do here");
+  });
+
+  test("hub absent → keeps the standalone install-the-hub advice", () => {
+    const msg = noOperatorTokenGuidance(false);
+    expect(msg).toContain("Install the hub");
+    expect(msg).toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("VAULT_AUTH_TOKEN");
+  });
+});
+
 describe("resolveInstallTarget", () => {
   test("user scope → ~/.claude.json", () => {
     const res = resolveInstallTarget("user");

package/src/mcp-install.ts

@@ -216,6 +216,112 @@ export function readOperatorToken(env: NodeJS.ProcessEnv = process.env): string
   }
 }
 
+// ---------------------------------------------------------------------------
+// Hub-presence probe
+// ---------------------------------------------------------------------------
+
+/**
+ * Default loopback port the hub binds. Mirrors `hub-jwt.ts`'s
+ * `DEFAULT_HUB_LOOPBACK` (`http://127.0.0.1:1939`). When no hub origin is
+ * configured (the common fresh-box case), this is where a co-located hub
+ * answers.
+ */
+export const DEFAULT_HUB_LOOPBACK_PORT = 1939;
+
+/**
+ * Best-effort: is a hub actually present on this host *right now*?
+ *
+ * This is distinct from {@link InstallContext.hubReachable}, which only asks
+ * "is a non-loopback hub *origin* configured?" (env / expose-state). On a fresh
+ * box the hub is installed and running on loopback, but no origin is configured
+ * and the operator token isn't minted yet (hub mints it only when the first
+ * admin user is created in the web wizard). The stale standalone-era copy
+ * ("install the hub …") fires off `operatorTokenPresent === false` and so
+ * misreads that fresh-box state as "no hub". This probe lets the copy branch on
+ * whether a hub is genuinely absent vs. merely not-yet-bootstrapped.
+ *
+ * Signals, cheapest-first:
+ *   1. A configured non-loopback hub origin (`PARACHUTE_HUB_ORIGIN` /
+ *      expose-state) → a hub origin exists, treat as present without a probe.
+ *   2. A live `GET http://127.0.0.1:<hubPort>/health` returning a 2xx. The
+ *      hub binds its own fixed loopback port (1939 by default), independent of
+ *      the vault's listen port — so the probe always targets the hub port, not
+ *      `chooseHubOrigin`'s vault-loopback fallback. Short timeout; any error →
+ *      not present.
+ *
+ * `port` is the hub's loopback port (defaults to `$PARACHUTE_HUB_PORT`, else
+ * 1939). `fetchImpl` is an injectable test seam; `timeoutMs` keeps a dead port
+ * from stalling init. Never throws — returns `false` on any failure.
+ */
+export async function detectHubPresence(opts: {
+  port?: number;
+  env?: { PARACHUTE_HUB_ORIGIN?: string | undefined; PARACHUTE_HUB_PORT?: string | undefined };
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+} = {}): Promise<boolean> {
+  const env =
+    opts.env ?? (process.env as { PARACHUTE_HUB_ORIGIN?: string; PARACHUTE_HUB_PORT?: string });
+  // Port precedence: explicit arg → `$PARACHUTE_HUB_PORT` → 1939. The env
+  // override keeps the probe deterministic for tests + non-default-port hubs,
+  // so it never accidentally hits an unrelated hub on the host's 1939.
+  const envPort = env.PARACHUTE_HUB_PORT ? Number(env.PARACHUTE_HUB_PORT) : undefined;
+  const hubPort =
+    opts.port ?? (envPort !== undefined && Number.isFinite(envPort) ? envPort : DEFAULT_HUB_LOOPBACK_PORT);
+  // 1. A configured hub origin (env / expose-state) is itself a present-hub
+  //    signal — no need to probe. We pass `hubPort` purely as the loopback
+  //    fallback arg; its only role here is the source discriminator.
+  const configured = chooseHubOrigin(hubPort, env);
+  // A stale expose-state (or a leftover PARACHUTE_HUB_ORIGIN) can
+  // false-positive here. Originally this only selected guidance copy, but as
+  // of hub#580 it ALSO gates `vault init`'s daemon registration default
+  // (hub present → skip autostart). The false-positive failure mode is
+  // therefore: a genuinely hubless box with stale hub-origin state runs init
+  // without a flag and silently skips registering a daemon. Narrow + accepted
+  // — the operator can re-run with `--autostart`, and any explicit flag or a
+  // persisted `config.autostart` short-circuits the probe entirely. See the
+  // call site in cli.ts for the persisted-value guard.
+  if (configured.source !== "loopback") return true;
+
+  // 2. Live health probe against the hub's fixed loopback port.
+  const origin = `http://127.0.0.1:${hubPort}`;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 800;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${origin}/health`, { signal: controller.signal });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Pick the operator-facing guidance for the "no operator.token present" case,
+ * branched on whether a hub is genuinely absent vs. merely not-yet-bootstrapped
+ * (#445). Extracted as a pure function so the copy is unit-testable without
+ * importing cli.ts (which dispatches on import).
+ *
+ *   hubPresent === true  → a hub is running; the operator token just hasn't
+ *                          been minted yet (it's minted when the first admin
+ *                          user is created in the hub's web wizard). The old
+ *                          "install the hub …" advice is circular here — this
+ *                          flow was spawned *by* the hub. Tell them there's
+ *                          nothing to do and to finish in the wizard.
+ *   hubPresent === false → genuinely standalone. Keep the original advice.
+ */
+export function noOperatorTokenGuidance(hubPresent: boolean): string {
+  return hubPresent
+    ? "No token yet — the hub's admin wizard mints the operator token when you " +
+        "create the first admin user. Nothing to do here; finish setup in the wizard, " +
+        "then run `parachute-vault mcp-install` if you want a header-auth token for scripts."
+    : "No token issued — no hub operator token at ~/.parachute/operator.token. " +
+        "Install the hub (`bun add -g @openparachute/hub` + `parachute init`) and re-run, " +
+        "or set VAULT_AUTH_TOKEN for an operator-channel bearer.";
+}
+
 // ---------------------------------------------------------------------------
 // Hub mint-token client
 // ---------------------------------------------------------------------------

package/src/mcp-tools.ts

@@ -7,6 +7,8 @@
 
 import { generateMcpTools } from "../core/src/mcp.ts";
 import type { McpToolDef } from "../core/src/mcp.ts";
+import { getNoteTags } from "../core/src/notes.ts";
+import type { Note } from "../core/src/types.ts";
 import {
   buildVaultProjection,
   projectionToMarkdown,
@@ -18,6 +20,7 @@ import { hasScopeForVault, parseScopes, validateMintedScopes } from "./scopes.ts
 import type { AuthResult } from "./auth.ts";
 import {
   expandTokenTagScope,
+  filterHydratedLinksByTagScope,
   noteWithinTagScope,
   tagsWithinScope,
 } from "./tag-scope.ts";
@@ -117,11 +120,48 @@ export function generateScopedMcpTools(
   callerBearer?: string | null,
 ): McpToolDef[] {
   const store = getVaultStore(vaultName);
-  const tools = generateMcpTools(store);
+
+  // Tag-scope confidentiality (security review): when the session is
+  // tag-scoped, build an expand-visibility predicate so `query-notes`'s
+  // `expand_links` inlining can't embed out-of-scope note content. The
+  // predicate reads from a SHARED holder that `applyTagScopeWrappers`
+  // populates with the resolved allowlist before core's execute runs the
+  // (synchronous) expansion — so by the time core calls `isVisible(note)`
+  // the allowlist is ready. Core stays scope-unaware: it only receives the
+  // plain closure. Unscoped sessions pass no predicate (unchanged path).
+  const scoped = Boolean(auth?.scoped_tags && auth.scoped_tags.length > 0);
+  const allowedHolder: { value: Set<string> | null } = { value: null };
+  const rawTags = scoped ? auth!.scoped_tags : null;
+  const expandVisibility = scoped
+    ? (note: Note) => noteWithinTagScope(note, allowedHolder.value, rawTags)
+    : undefined;
+
+  // Tag-scope hop-guard for `near[]` (vault#439): a per-note predicate the
+  // core BFS consults so it refuses to traverse THROUGH out-of-scope notes —
+  // symmetric with find-path. Reads from the SAME shared `allowedHolder` the
+  // result-filter populates; the query-notes wrapper `await getAllowed()`s
+  // (which fills the holder) before core's execute runs the BFS, so the
+  // allowlist is ready by the time this fires. Looks up each candidate note's
+  // tags by id (sync, core-native). Unscoped sessions install no predicate.
+  const nearTraversable = scoped
+    ? (noteId: string) =>
+        noteWithinTagScope(
+          { id: noteId, tags: getNoteTags(store.db, noteId) } as Note,
+          allowedHolder.value,
+          rawTags,
+        )
+    : undefined;
+
+  const tools = generateMcpTools(
+    store,
+    expandVisibility || nearTraversable
+      ? { ...(expandVisibility ? { expandVisibility } : {}), ...(nearTraversable ? { nearTraversable } : {}) }
+      : undefined,
+  );
 
   overrideVaultInfo(tools, vaultName, auth);
   applyTagDependencyGuards(tools, vaultName);
-  applyTagScopeWrappers(tools, vaultName, auth);
+  applyTagScopeWrappers(tools, vaultName, auth, allowedHolder);
 
   // manage-token is server-only (needs token-store + auth context), so it
   // lives here rather than in core. Always appended to the surface; the
@@ -181,6 +221,7 @@ function applyTagScopeWrappers(
   tools: McpToolDef[],
   vaultName: string,
   auth: AuthResult | undefined,
+  allowedHolder?: { value: Set<string> | null },
 ): void {
   if (!auth || !auth.scoped_tags || auth.scoped_tags.length === 0) return;
   const store = getVaultStore(vaultName);
@@ -188,12 +229,40 @@ function applyTagScopeWrappers(
   let allowedPromise: Promise<Set<string> | null> | null = null;
   const getAllowed = (): Promise<Set<string> | null> => {
     if (!allowedPromise) {
-      allowedPromise = expandTokenTagScope(store, auth.scoped_tags);
+      allowedPromise = expandTokenTagScope(store, auth.scoped_tags).then((a) => {
+        // Publish the resolved allowlist into the shared holder so the
+        // expand-visibility predicate (wired in generateScopedMcpTools and
+        // baked into the query-notes expand context) sees the same set.
+        // The query-notes wrapper awaits getAllowed() before calling the
+        // core execute that runs expansion, so the holder is populated in
+        // time. Security review: closes the expand_links content leak.
+        if (allowedHolder) allowedHolder.value = a;
+        return a;
+      });
     }
     return allowedPromise;
   };
   const rawTags = auth.scoped_tags;
 
+  // Scrub a returned note's hydrated `links` array (present when the caller
+  // set `include_links`) so out-of-scope NEIGHBOR summaries (id/path/tags)
+  // don't leak — symmetric with the REST `include_links` fix. Mutates in
+  // place and returns the note for chaining. No-op when `links` is absent.
+  //
+  // Ordering invariant: reading `allowedHolder.value` here is safe ONLY
+  // because every wrapper that calls scrubNoteLinks first does
+  // `await getAllowed()` (which populates the holder) before `orig(params)`
+  // and before this scrub runs. So by the time we read `holder.value` it is
+  // the resolved allowlist, never the initial `null`. The `?? null` fallback
+  // is the unscoped/holder-absent path; `filterHydratedLinksByTagScope` then
+  // keys off `rawTags` (non-null here) for the actual scope check.
+  const scrubNoteLinks = (n: any): any => {
+    if (n && Array.isArray(n.links)) {
+      n.links = filterHydratedLinksByTagScope(n.links, allowedHolder?.value ?? null, rawTags);
+    }
+    return n;
+  };
+
   wrapReadTool(tools, "query-notes", async (orig, params) => {
     const allowed = await getAllowed();
     const result = await orig(params);
@@ -203,7 +272,9 @@ function applyTagScopeWrappers(
     //   - `{notes, next_cursor}` (cursor mode, vault#313)
     //   - `{...note}` with `id`+`tags` (single-note by id)
     if (Array.isArray(result)) {
-      return result.filter((n: any) => noteWithinTagScope(n, allowed, rawTags));
+      return result
+        .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+        .map(scrubNoteLinks);
     }
     if (
       result &&
@@ -214,13 +285,15 @@ function applyTagScopeWrappers(
     ) {
       const r = result as { notes: any[]; next_cursor: string | null };
       return {
-        notes: r.notes.filter((n: any) => noteWithinTagScope(n, allowed, rawTags)),
+        notes: r.notes
+          .filter((n: any) => noteWithinTagScope(n, allowed, rawTags))
+          .map(scrubNoteLinks),
         next_cursor: r.next_cursor,
       };
     }
     if (result && typeof result === "object" && "id" in result && "tags" in result) {
       return noteWithinTagScope(result as any, allowed, rawTags)
-        ? result
+        ? scrubNoteLinks(result)
         : { error: "Note not found", id: (result as any).id };
     }
     return result;
@@ -463,7 +536,7 @@ function resolveHubOrigin(): { url: string; source: string } {
  *
  * After the auth-unification arc (vault#403, MGT) the tool is a thin proxy to
  * hub's mint-token attenuation endpoint: it mints short-TTL HUB JWTs. The
- * `pvt_*` vault-DB mint infra it replaced was removed at 0.6.0 (vault#282
+ * `pvt_*` vault-DB mint infra it replaced was removed at 0.5.0 (vault#282
  * Stage 2 — vault is a pure hub resource-server).
  *
  * Closure-captured context: