Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
36.8 KB
Raw Blame
/**
 * Owner-scope isolation regression matrix (context-integrity-gates,
 * Unit A / Task 8).
 *
 * Before this wave, `isOwnerVisible` — the vault's ONLY isolation rule —
 * had two callers, and every other content-returning MCP surface
 * bypassed it. The defect was not any single missing filter; it was that
 * nothing enumerated the surfaces, so each new one silently opted out.
 *
 * This file is that enumeration. Every tool in the table is classified
 * exactly once, and the three buckets are asserted to partition the tool
 * table exactly — in BOTH directions. A new tool therefore fails this
 * test until someone classifies it, and a removed tool fails it until
 * someone deletes the entry. That is the mechanism; the per-surface
 * assertions below are what it protects.
 *
 * ## What the partition was worth on its own (a-label-is-not-a-boundary, U3)
 *
 * Nothing. `SCOPED_SURFACES` carried behavioural tests; the other two
 * buckets carried a name and, in one of them, a prose reason nothing
 * read. A sweep against a two-owner vault under
 * `integrity.owner_scope_delivery: fail` found TEN classified-as-safe
 * tools returning another owner's artifact ids, paths, titles and body
 * prose. A bucket whose membership claim is never executed is a label,
 * and the release this unit belongs to is about what a label is worth.
 *
 * So both unasserted buckets now carry `{name, args, reason}`: the
 * arguments that DRIVE the tool, and a written reason for the
 * classification. `assertProbeEntry` refuses an entry without
 * them at module load, and {@link ProbeEntry} refuses one at
 * `bun run typecheck`, so the bucket cannot regrow as a bare name list.
 * Every entry is then driven against one two-owner fixture and its
 * response — or the message it threw — is asserted to carry no marker
 * unique to the other owner's artifacts.
 */

import { afterAll, afterEach, beforeEach, expect, test } from "bun:test";
import {
  chmodSync,
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { atomicWriteFileSync } from "../../src/core/fs-atomic.ts";
import { indexVault, resolveSearchConfig, search } from "../../src/core/search/index.ts";
import { GATE_MODE } from "../../src/core/integrity/stamp.ts";
import { brainActivePath, brainConfigPath, brainDirs } from "../../src/core/brain/paths.ts";
import { regenerateActive } from "../../src/core/brain/active.ts";
import { appendLogEvent } from "../../src/core/brain/log.ts";
import { writePreference } from "../../src/core/brain/preference.ts";
import { runHygieneScan } from "../../src/core/brain/hygiene/scan.ts";
import { writeSignal } from "../../src/core/brain/signal.ts";
import {
  BRAIN_CONFIDENCE,
  BRAIN_LOG_EVENT_KIND,
  BRAIN_PREFERENCE_STATUS,
} from "../../src/core/brain/types.ts";
import { OWNER_SCOPE_REFUSAL } from "../../src/mcp/owner-scope-refusal.ts";
import {
  CROSS_OWNER_MARKER,
  HUB_ID,
  LOG_EVENT_DATE,
  NEUTRAL_SIGNAL_SLUG,
  OWNER_A,
  OWNER_B,
  PROBE,
  PROBE_ENTRIES,
  PROBE_ENTRY_COUNT,
  PROBE_RECIPE_COUNT,
  PROBE_TERMS,
  PROBE_TWO_SIDED_COUNT,
  QUERY,
  REASONS_REACHING_OWNER_CONTENT,
  SCOPE_SOURCE,
  SCOPED_SURFACES,
  SHARED_ID,
  SHARED_TITLE,
  SHARED_TOPIC,
  probeLabel,
  type ProbeCall,
} from "../helpers/tool-probe-catalogue.ts";
import { CHMOD_CANNOT_DENY } from "../helpers/platform.ts";
import { buildToolTable } from "../../src/mcp/tools.ts";
import type { ServerContext, ToolDefinition } from "../../src/mcp/tool-contract.ts";
import type { TransportReach } from "../../src/core/graph/transport-reach.ts";

/**
 * HOME is pinned for THIS file, and nothing pins it globally.
 *
 * `resolveDeviceId`, `resolveAgentName` and the profile writer all fall
 * back to the operator's real `~/.config/open-second-brain/config.yaml`
 * when a call supplies no explicit config path, and the isolation probe
 * below drives every writer in the tool table. A global pin would hide
 * the config-reading behaviour other suites exist to exercise, so the
 * file that needs the pin sets it - at module scope, which runs before
 * any test body and before any of these tools is ever called.
 */
const SAVED_HOME = process.env["HOME"];
const PINNED_HOME = mkdtempSync(join(tmpdir(), "o2b-scope-matrix-home-"));
process.env["HOME"] = PINNED_HOME;
afterAll(() => {
  // Bun runs many files in one process: hand HOME back and drop the pin.
  if (SAVED_HOME === undefined) delete process.env["HOME"];
  else process.env["HOME"] = SAVED_HOME;
  rmSync(PINNED_HOME, { recursive: true, force: true });
});

const TOOLS = buildToolTable("full");
const tool = (name: string): ToolDefinition => {
  const found = TOOLS.find((t) => t.name === name);
  expect(found, `no such tool: ${name}`).toBeDefined();
  return found!;
};

let vault: string;
let configHome: string;
let ctx: ServerContext;

beforeEach(async () => {
  vault = mkdtempSync(join(tmpdir(), "o2b-scope-matrix-vault-"));
  configHome = mkdtempSync(join(tmpdir(), "o2b-scope-matrix-cfg-"));
  const configPath = join(configHome, "config.yaml");
  atomicWriteFileSync(configPath, `vault: ${vault}\nagent_name: ${OWNER_B}\n`);
  for (const sub of ["preferences", "retired", "inbox", "log"]) {
    mkdirSync(join(vault, "Brain", sub), { recursive: true });
  }
  mkdirSync(join(vault, "notes"), { recursive: true });
  writeFileSync(
    join(vault, "notes", "owned-a.md"),
    `---\nowner: ${OWNER_A}\n---\n\n${QUERY} ${PROBE_TERMS} owned by a\n`,
  );
  writeFileSync(join(vault, "notes", "shared.md"), `# Shared\n\n${QUERY} ${PROBE_TERMS} shared\n`);
  makePref("shared");
  makePref("owned-by-a", OWNER_A);
  ctx = { vault, configPath, repoRoot: null, agentName: OWNER_B };
  await indexVault(resolveSearchConfig({ vault, configPath }), {});
});

afterEach(() => {
  rmSync(vault, { recursive: true, force: true });
  rmSync(configHome, { recursive: true, force: true });
});

function setGate(mode: string | null): void {
  const body = mode === null ? "" : `integrity:\n  owner_scope_delivery: ${mode}\n`;
  writeFileSync(brainConfigPath(vault), `schema_version: 1\n${body}`);
}

function makePref(
  slug: string,
  owner?: string,
  overrides: Partial<Parameters<typeof writePreference>[1]> = {},
): void {
  writePreference(vault, {
    slug,
    topic: slug,
    principle: `principle for ${slug}`,
    created_at: "2026-05-01T00:00:00Z",
    unconfirmed_until: "2026-05-08T00:00:00Z",
    status: BRAIN_PREFERENCE_STATUS.confirmed,
    evidenced_by: [`[[sig-2026-05-01-${slug}]]`],
    confirmed_at: "2026-05-02T00:00:00Z",
    applied_count: 1,
    violated_count: 0,
    last_evidence_at: "2026-05-02T00:00:00Z",
    confidence: BRAIN_CONFIDENCE.high,
    confidence_value: 0.8,
    ...(owner !== undefined ? { owner } : {}),
    ...overrides,
  });
}

/**
 * Invoke a tool AS `agentName`. Argument-scoped surfaces read the scope
 * from `args`; `brain_context` takes no arguments and can only read the
 * server identity, so the identity is varied alongside the argument and
 * each surface picks up whichever source it declares.
 */
async function call(
  name: string,
  args: Record<string, unknown>,
  agentName: string = OWNER_B,
  reach?: TransportReach,
): Promise<string> {
  const callCtx = reach === undefined ? { ...ctx, agentName } : { ...ctx, agentName, reach };
  return JSON.stringify(await tool(name).handler(callCtx, args));
}

/** Vault-relative paths a listing surface returned. */
function pagePaths(result: { pages: Array<{ path: string }> }): string[] {
  return result.pages.map((p) => p.path);
}

/** Entry ids a source-trace surface returned. */
function entryIds(result: { entries: Array<{ id: string }> }): string[] {
  return result.entries.map((e) => e.id);
}

/** Contribution ids a provenance surface returned, sorted. */
function contributionIds(result: { contributions: Array<{ id: string }> }): string[] {
  return result.contributions.map((c) => c.id).toSorted();
}

// ----- the mechanism --------------------------------------------------------

test("the matrix classifies every tool exactly once", () => {
  const classified = [...SCOPED_SURFACES.map((s) => s.name), ...PROBE_ENTRIES.map((s) => s.name)];
  expect(new Set(classified).size).toBe(classified.length);

  const actual = TOOLS.map((t) => t.name).toSorted();
  // Both directions: a NEW tool fails until it is classified, and a
  // REMOVED tool fails until its entry is deleted. The set equality
  // also pins the surface population - a count would only be weaker.
  expect(classified.toSorted()).toEqual(actual);
});

test("every argument-scoped surface declares agent_scope in its input schema", () => {
  for (const surface of SCOPED_SURFACES) {
    const schema = tool(surface.name).inputSchema as {
      properties?: Record<string, unknown>;
    };
    const declared = Object.keys(schema.properties ?? {});
    if (surface.source === SCOPE_SOURCE.argument) {
      expect(declared, `${surface.name} must accept agent_scope`).toContain("agent_scope");
    } else {
      expect(declared, `${surface.name} takes no arguments`).toEqual([]);
    }
  }
});

test("brain_context keeps its no-argument contract and reads the server identity", () => {
  const schema = tool("brain_context").inputSchema as Record<string, unknown>;
  expect(schema["additionalProperties"]).toBe(false);
  expect(Object.keys((schema["properties"] ?? {}) as Record<string, unknown>)).toEqual([]);
});

// ----- gated preference-backed surfaces -------------------------------------

const GATED_CALLS: ReadonlyArray<{
  readonly name: string;
  readonly args: (scope: string | null) => Record<string, unknown>;
}> = [
  { name: "brain_context", args: () => ({}) },
  {
    name: "brain_context_pack",
    args: (s) => ({ max_tokens: 4000, ...(s === null ? {} : { agent_scope: s }) }),
  },
  {
    name: "brain_pre_compress_pack",
    args: (s) => ({ top_k: 10, ...(s === null ? {} : { agent_scope: s }) }),
  },
  {
    name: "brain_brief",
    args: (s) => ({ view: "morning", ...(s === null ? {} : { agent_scope: s }) }),
  },
  {
    name: "brain_anticipatory_context",
    args: (s) => ({ session_id: "sess-1", ...(s === null ? {} : { agent_scope: s }) }),
  },
];

for (const surface of GATED_CALLS) {
  test(`${surface.name}: gate off delivers every owner's memory`, async () => {
    setGate(GATE_MODE.off);
    expect(await call(surface.name, surface.args(OWNER_B), OWNER_B)).toContain("owned-by-a");
  });

  test(`${surface.name}: gate fail withholds another owner's memory`, async () => {
    setGate(GATE_MODE.fail);
    const out = await call(surface.name, surface.args(OWNER_B), OWNER_B);
    expect(out).not.toContain("owned-by-a");
    expect(out).toContain("shared");
  });

  test(`${surface.name}: gate fail keeps the owner's own memory`, async () => {
    setGate(GATE_MODE.fail);
    expect(await call(surface.name, surface.args(OWNER_A), OWNER_A)).toContain("owned-by-a");
  });
}

/**
 * A3: a per-request visibility filter must never drive a shared write.
 *
 * `brain_context` used to reach `regenerateActive(vault, { agentScope })`,
 * and `regenerateActive` WRITES `Brain/active.md`. Under `fail` a call from
 * agent-b therefore rewrote the shared file without agent-a's memories -
 * and `hooks/active-inject.ts` injects that same file into every agent's
 * SessionStart, while `resources.ts` regenerates it unscoped. The file
 * thrashed and an agent could lose its own memories from session start.
 */
test("brain_context scopes what it returns without narrowing active.md", async () => {
  setGate(GATE_MODE.fail);
  regenerateActive(vault);
  const activePath = brainActivePath(vault);
  const before = readFileSync(activePath, "utf8");
  expect(before).toContain("owned-by-a");

  const out = await call("brain_context", {}, OWNER_B);
  expect(out).not.toContain("owned-by-a");
  expect(out).toContain("shared");

  // The SHARED file is untouched: same bytes, still carrying every owner.
  expect(readFileSync(activePath, "utf8")).toBe(before);
});

test("brain_context creates active.md unscoped on a vault that has none", async () => {
  setGate(GATE_MODE.fail);
  const activePath = brainActivePath(vault);
  rmSync(activePath, { force: true });

  await call("brain_context", {}, OWNER_B);
  expect(readFileSync(activePath, "utf8")).toContain("owned-by-a");
});

/**
 * A6: `agent_scope` is declared once for the whole `brain_brief` tool, but
 * only two of its seven views thread it. The other five returned
 * preference ids (`weekly.retired[].prefId`, the operator dashboard's
 * ranked actions) to a caller that believed it was scoped. An argument a
 * tool accepts and silently ignores is exactly the failure mode this wave
 * exists to remove, so those views refuse it.
 */
test("brain_brief refuses agent_scope on the views that cannot honour it", async () => {
  const views = ["daily", "weekly", "monthly", "operator", "today"];
  const outcomes = await Promise.all(
    views.map((view) =>
      call("brain_brief", { view, agent_scope: OWNER_B }).then(
        () => null,
        (e: unknown) => (e as Error).message,
      ),
    ),
  );
  for (const [i, message] of outcomes.entries()) {
    expect(message, `view=${views[i]}`).toContain(
      `brain_brief view=${views[i]} cannot honour 'agent_scope'`,
    );
  }
});

test("brain_brief still serves those views without the argument", async () => {
  const served = await Promise.all(
    ["daily", "weekly", "monthly", "today"].map((view) => call("brain_brief", { view })),
  );
  for (const out of served) expect(typeof out).toBe("string");
});

/**
 * This test used to drive the same tool twice from ONE caller - `agent-b`
 * - naming `agent-a` once and itself once, and asserted that naming
 * `agent-a` returned MORE items. It passed, and what it pinned was the
 * leak: under `fail` the gate enforced the scope the caller asked for,
 * so a caller selected which owner's private memory it received
 * (a-label-is-not-a-boundary, U2). The count difference is still the
 * measurement, but each caller now names only itself, and the crossing
 * call is refused by name rather than counted.
 */
test("brain_retrieval_plan counts only the memories its caller may see", async () => {
  setGate(GATE_MODE.fail);
  const asA = JSON.parse(
    await call("brain_retrieval_plan", { question: QUERY, agent_scope: OWNER_A }, OWNER_A),
  );
  const asB = JSON.parse(
    await call("brain_retrieval_plan", { question: QUERY, agent_scope: OWNER_B }, OWNER_B),
  );
  expect(asA.allocation.item_count).toBeGreaterThan(asB.allocation.item_count);
});

test("brain_retrieval_plan refuses a caller that names another owner", async () => {
  setGate(GATE_MODE.fail);
  await expect(
    call("brain_retrieval_plan", { question: QUERY, agent_scope: OWNER_A }, OWNER_B),
  ).rejects.toThrow(OWNER_SCOPE_REFUSAL.foreignOwner);
});

// ----- ungated search-backed surfaces ---------------------------------------

test("brain_search_expand refuses another owner's chunk as if it were absent", async () => {
  const config = resolveSearchConfig({ vault, configPath: ctx.configPath ?? undefined });
  const hit = (await search(config, { query: QUERY, limit: 20 })).results.find(
    (r) => r.path === "notes/owned-a.md",
  );
  expect(hit).toBeDefined();

  expect(await call("brain_search_expand", { chunk_id: hit!.chunkId })).toContain(
    "notes/owned-a.md",
  );
  await expect(
    call("brain_search_expand", { chunk_id: hit!.chunkId, agent_scope: OWNER_B }),
  ).rejects.toThrow(`chunk not found: ${hit!.chunkId}`);
});

test("second_brain_query excludes another owner's pages from the listing", async () => {
  const unscoped = JSON.parse(await call("second_brain_query", { limit: 500 }));
  const scoped = JSON.parse(await call("second_brain_query", { limit: 500, agent_scope: OWNER_B }));
  expect(pagePaths(unscoped)).toContain("notes/owned-a.md");
  expect(pagePaths(unscoped)).toContain("Brain/preferences/pref-owned-by-a.md");
  expect(pagePaths(scoped)).not.toContain("notes/owned-a.md");
  expect(pagePaths(scoped)).not.toContain("Brain/preferences/pref-owned-by-a.md");
  // The shared pages survive, and the reported total is the visible one -
  // a count that still included the hidden pages would leak their number.
  expect(pagePaths(scoped)).toContain("notes/shared.md");
  expect(scoped.total_pages).toBe(scoped.pages.length);
  expect(scoped.total_pages).toBeLessThan(unscoped.total_pages);
});

/**
 * A5/A8: the listing must fail CLOSED on an unreadable page, matching
 * `brain_search_by_source` and the ranked search path. Empty frontmatter
 * from a failed read is byte-indistinguishable from a genuinely ownerless
 * page, so without the walk's diagnostic sink an owner-tagged page becomes
 * shared the moment its file stops being readable.
 */
// chmod cannot deny access on Windows or as root (tests/helpers/platform.ts).
test.skipIf(CHMOD_CANNOT_DENY)(
  "second_brain_query hides a page it cannot read from a scoped caller",
  async () => {
    const target = join(vault, "notes", "owned-a.md");
    chmodSync(target, 0o000);
    try {
      const scoped = JSON.parse(
        await call("second_brain_query", { limit: 500, agent_scope: OWNER_B }),
      );
      expect(pagePaths(scoped)).not.toContain("notes/owned-a.md");
      expect(pagePaths(scoped)).toContain("notes/shared.md");
    } finally {
      chmodSync(target, 0o644);
    }
  },
);

test("brain_search_by_source excludes another owner's derived pages", async () => {
  const sourceFile = "sources/paper.md";
  const derived = join(vault, "Brain", "sources");
  mkdirSync(derived, { recursive: true });
  writeFileSync(
    join(derived, "src-owned-a.md"),
    `---\nid: src-owned-a\nowner: ${OWNER_A}\nsource_path: ${sourceFile}\n---\n\nderived for a\n`,
  );
  writeFileSync(
    join(derived, "src-shared.md"),
    `---\nid: src-shared\nsource_path: ${sourceFile}\n---\n\nderived for everyone\n`,
  );

  const unscoped = JSON.parse(await call("brain_search_by_source", { source_file: sourceFile }));
  const scoped = JSON.parse(
    await call("brain_search_by_source", { source_file: sourceFile, agent_scope: OWNER_B }),
  );
  expect(entryIds(unscoped).toSorted()).toEqual(["src-owned-a", "src-shared"]);
  expect(entryIds(scoped)).toEqual(["src-shared"]);
  expect(scoped.total).toBe(1);
});

test("brain_agent_query excludes another owner's preference contributions", async () => {
  // A preference contribution only surfaces once its evidence signals
  // exist, because the contribution's agents are read from them.
  for (const slug of ["shared", "owned-by-a"]) {
    writeSignal(vault, {
      topic: slug,
      signal: "positive",
      agent: "agent-x",
      principle: `principle for ${slug}`,
      created_at: "2026-05-01T00:00:00Z",
      date: "2026-05-01",
      slug,
    });
  }

  const unscoped = JSON.parse(await call("brain_agent_query", { kind: "preference" }));
  const scoped = JSON.parse(
    await call("brain_agent_query", { kind: "preference", agent_scope: OWNER_B }),
  );
  expect(contributionIds(unscoped)).toEqual(["pref-owned-by-a", "pref-shared"]);
  expect(contributionIds(scoped)).toEqual(["pref-shared"]);
  expect(scoped.total_matched).toBe(1);
});

/**
 * A5: the roster must be folded from the SAME filtered set the
 * contributions are. Built independently of the owner filter it reported
 * a correct `total_matched` beside an `available_agents` entry naming the
 * withheld preference's topic verbatim and counting it - which is the
 * existence leak the boundary exists to prevent.
 *
 * The evidence signal carries a DIFFERENT topic from the preference it
 * evidences, so the preference's topic can only reach the roster through
 * the preference contribution itself.
 */
test("brain_agent_query's roster names only what the caller may see", async () => {
  writeSignal(vault, {
    topic: "neutral-topic",
    signal: "positive",
    agent: "agent-y",
    principle: "principle for the neutral signal",
    created_at: "2026-05-01T00:00:00Z",
    date: "2026-05-01",
    slug: "secret-pref",
  });
  makePref("secret-pref", OWNER_A);

  const rosterFor = (result: {
    available_agents: Array<{ id: string; topics: string[]; contribution_count: number }>;
  }): { topics: string[]; contribution_count: number } => {
    const entry = result.available_agents.find((a) => a.id === "agent-y");
    expect(entry).toBeDefined();
    return entry!;
  };

  const unscoped = rosterFor(JSON.parse(await call("brain_agent_query", {})));
  expect(unscoped.topics).toEqual(["neutral-topic", "secret-pref"]);
  expect(unscoped.contribution_count).toBe(2);

  const scoped = rosterFor(JSON.parse(await call("brain_agent_query", { agent_scope: OWNER_B })));
  expect(scoped.topics).toEqual(["neutral-topic"]);
  expect(scoped.contribution_count).toBe(1);
});

test("brain_file_context and brain_deep_synthesis exclude another owner's page", async () => {
  const cases = [
    { name: "brain_file_context", args: { file_path: join(vault, "notes", PROBE), min_bytes: 0 } },
    { name: "brain_deep_synthesis", args: { topic: QUERY } },
  ];
  // Both calls per case are issued together: they share no state, and a
  // sequential await here is only a slower way to reach the same result.
  const outcomes = await Promise.all(
    cases.map(async ({ name, args }) => ({
      name,
      unscoped: await call(name, args),
      scoped: await call(name, { ...args, agent_scope: OWNER_B }),
    })),
  );
  for (const { name, unscoped, scoped } of outcomes) {
    expect(unscoped, `${name} unscoped`).toContain("notes/owned-a.md");
    expect(scoped, `${name} scoped`).not.toContain("notes/owned-a.md");
    expect(scoped, `${name} scoped`).toContain("notes/shared.md");
  }
});

// ----- the isolation probe --------------------------------------------------

/**
 * Insert extra frontmatter lines and extra body text into an artifact the
 * shipped writer produced.
 *
 * The writers accept no `title` and no body, and the probe needs both: a
 * title is the only term `findUnlinkedMentions` matches on, and a body is
 * where `auditMoc` reads a hub's outbound cluster from. Patching the
 * writer's own output keeps every schema-owned field exactly as the
 * writer spelled it.
 */
function patchArtifact(rel: string, frontmatter: ReadonlyArray<string>, body: string): void {
  const abs = join(vault, rel);
  const text = readFileSync(abs, "utf8");
  const close = text.indexOf("\n---\n", "---\n".length);
  expect(close, `${rel} has no frontmatter block`).toBeGreaterThan(0);
  const head = frontmatter.length === 0 ? "" : `\n${frontmatter.join("\n")}`;
  const tail = body.length === 0 ? "" : `\n${body}\n`;
  writeFileSync(abs, text.slice(0, close) + head + text.slice(close) + tail);
}

/**
 * The two-owner fixture every {@link PROBE_ENTRIES} entry is driven
 * against.
 *
 * Additive to `beforeEach`, not a replacement for it: the per-surface
 * tests above pin exact ids and exact counts over the smaller vault, and
 * a fixture that grew under them would move those numbers for reasons
 * that have nothing to do with what they assert.
 *
 * Every artifact seeded here that belongs to {@link OWNER_A} carries
 * {@link CROSS_OWNER_MARKER} in its id, so a surface that names one -
 * as an id, a path, a topic, a title or a line of prose - fails the
 * probe without the probe having to know which field it used.
 *
 * The forced full index at the end is a precondition, not a habit:
 * `brain_scaffold_stub action=list` refuses on an incrementally-indexed
 * vault (`notes/scaffold-stub.ts` `partial_resolution`) and returns no
 * targets at all, which would read as a clean probe over a surface that
 * never ran.
 */
async function seedTwoOwnerFixture(): Promise<void> {
  const ownedPref = `${CROSS_OWNER_MARKER}-a`;
  const ownedPref2 = `${CROSS_OWNER_MARKER}-a2`;
  const ownedPrefOnSharedTopic = `${CROSS_OWNER_MARKER}-a3`;
  const ownedPrefDuplicate = `${CROSS_OWNER_MARKER}-a4`;

  // The evidence signal is deliberately NEUTRAL-named and ownerless: a
  // signal carries no `owner:` anywhere in this product (`signal.ts` has
  // no such field), so a marker inside one would be a marker inside a
  // SHARED artifact and every `not.toContain` below would be asserting
  // against something the caller is entitled to read.
  writeSignal(vault, {
    topic: NEUTRAL_SIGNAL_SLUG,
    signal: "positive",
    agent: OWNER_A,
    principle: "principle for the neutral evidence signal",
    created_at: "2026-05-01T00:00:00Z",
    date: "2026-05-01",
    slug: NEUTRAL_SIGNAL_SLUG,
    source: [`[[${SHARED_ID}]]`],
  });

  // `applied_count: 0` is what the hygiene scan's usefulness detector
  // measures, and the finding it emits names the preference by id.
  const unused = { evidenced_by: [`[[sig-2026-05-01-${NEUTRAL_SIGNAL_SLUG}]]`], applied_count: 0 };
  makePref(ownedPref, OWNER_A, unused);
  makePref(ownedPref2, OWNER_A, { applied_count: 0 });
  // A THIRD owner-A preference carrying `ownedPref2`'s principle
  // verbatim, so the dedup detector nominates that pair for a MERGE -
  // the one hygiene action with an applier behind it. Without an
  // applicable finding, `mode=apply` returns nothing but opaque hashes
  // and the probe cannot see whether it wrote across the boundary.
  // Same TOPIC as well as the same principle: `findMergeCandidates`
  // buckets by `(topic, scope)` and only compares inside a bucket, so a
  // duplicate principle under a different topic is never nominated.
  makePref(ownedPrefDuplicate, OWNER_A, {
    applied_count: 0,
    topic: ownedPref2,
    principle: `principle for ${ownedPref2}`,
  });
  // Owner-A's preference on the SHARED topic: the artifact a topic
  // fan-out reaches without the caller ever naming it.
  makePref(ownedPrefOnSharedTopic, OWNER_A, { topic: SHARED_TOPIC });
  makePref("hub");

  // The shared preference gains the title the mention scanner matches on;
  // the owner-A preference gains a body that spells that title in raw
  // prose, which is the unlinked mention that must not cross.
  patchArtifact(`Brain/preferences/${SHARED_ID}.md`, [`title: ${SHARED_TITLE}`], "");
  patchArtifact(
    `Brain/preferences/pref-${ownedPref}.md`,
    [`supersedes: "[[${SHARED_ID}]]"`],
    `See [[${SHARED_ID}]]. Also ${SHARED_TITLE} ${CROSS_OWNER_MARKER} here.`,
  );
  // A shared hub whose outbound cluster names both owner-A members plus a
  // target that does not exist: `wellCovered`/`fragile` classify the two
  // that resolve, `candidateMissing` names the one that does not.
  patchArtifact(
    `Brain/preferences/${HUB_ID}.md`,
    [],
    `Hub. [[pref-${ownedPref}]] [[pref-${ownedPref2}]] [[${SHARED_ID}]] [[missing-shared-member]]`,
  );

  writeFileSync(
    join(brainDirs(vault).retired, `ret-${CROSS_OWNER_MARKER}-a.md`),
    [
      "---",
      "kind: brain-retired",
      `id: ret-${CROSS_OWNER_MARKER}-a`,
      `owner: ${OWNER_A}`,
      "created_at: 2026-05-01T00:00:00Z",
      "tags: []",
      `topic: ${CROSS_OWNER_MARKER}-a`,
      "principle: retired principle",
      "provenance: observed",
      "retired_at: 2026-05-03T00:00:00Z",
      `retired_by: "[[${SHARED_ID}]]"`,
      "retired_reason: superseded-by-context",
      "_status: retired",
      "_evidenced_by: []",
      "---",
      "",
      `See [[${SHARED_ID}]] and ${SHARED_TITLE} ${CROSS_OWNER_MARKER}.`,
      "",
    ].join("\n"),
  );

  writeFileSync(
    join(vault, "notes", `${CROSS_OWNER_MARKER}-a.md`),
    `---\nowner: ${OWNER_A}\n---\n\n${QUERY} ${PROBE_TERMS} [[missing-${CROSS_OWNER_MARKER}-target]]\n`,
  );

  for (const slug of [ownedPref, ownedPrefOnSharedTopic]) {
    appendLogEvent(
      vault,
      {
        timestamp: `${LOG_EVENT_DATE}T00:00:00Z`,
        eventType: BRAIN_LOG_EVENT_KIND.applyEvidence,
        body: {
          path: `Brain/preferences/pref-${slug}.md`,
          preference: `[[pref-${slug}]]`,
          result: "applied",
        },
      },
      { deviceId: "" },
    );
  }

  await indexVault(resolveSearchConfig({ vault, configPath: ctx.configPath ?? undefined }), {
    force: true,
  });
}

/**
 * Drive one recipe and return everything the caller would see.
 *
 * A thrown message counts: a refusal that quotes the artifact it choked
 * on discloses exactly as much as a successful response would, and this
 * repository has already shipped one of those (`schema_inspect view=lint`
 * naming a host path in its parse error).
 */
async function probeResponse(
  name: string,
  args: Record<string, unknown>,
  reach?: TransportReach,
): Promise<string> {
  try {
    return await call(name, args, OWNER_B, reach);
  } catch (err) {
    return `threw: ${err instanceof Error ? err.message : String(err)}`;
  }
}

/** Resolve a recipe's arguments against the seeded fixture. */
function probeArgs(recipe: ProbeCall): Record<string, unknown> {
  return typeof recipe.args === "function" ? recipe.args(vault) : recipe.args;
}

test("the probe's own fixture puts the marker in front of an unscoped caller", async () => {
  setGate(GATE_MODE.off);
  await seedTwoOwnerFixture();
  // Without this, every `not.toContain` below would pass on a fixture that
  // simply never produced the rows - the failure mode recon named when it
  // said several clean sweeps were clean because the fixture was empty.
  expect(await probeResponse("brain_backlinks", { id: SHARED_ID })).toContain(CROSS_OWNER_MARKER);
});

/**
 * Wall-clock ceiling for one probe.
 *
 * Above bun's 5s default because two entries do real work before they can
 * answer - `brain_codegraph_report` walks the in-scope project and
 * `brain_review_candidates` runs a full dry-run consolidation pass - and
 * a probe that times out reports a leak that is not there.
 */
const PROBE_TIMEOUT_MS = 30_000;

/**
 * The differential: gate OFF versus gate FAIL, per recipe.
 *
 * A one-sided probe cannot fail. `off` discloses a SUPERSET of what
 * `fail` discloses, so a recipe that does not surface the marker
 * unscoped can never surface it scoped either - and a sweep of the
 * previous, one-recipe-per-tool version found 81 of 96 entries in
 * exactly that state, naming artifacts the fixture never created or
 * driving an empty lane. Every one of them read as a clean isolation
 * result over a call that was never isolating anything.
 *
 * So both directions are asserted, and which direction depends on the
 * recipe's own reason:
 *
 *   - `REASON.ownerFiltered` claims the call REACHES owner-taggable
 *     artifacts and filters them. Both halves are executed: the marker
 *     MUST appear with the gate off, and MUST NOT with the gate on. The
 *     first half is what stops the second from being vacuous.
 *   - every other reason in `REASON` claims the call cannot name
 *     an owner-private artifact at all - a session lane, an ownerless
 *     lane, a catalog, a caller-named artifact, a writer's echo, an
 *     aggregate with no per-artifact identity. That claim is executed
 *     directly: the marker must be absent even with the gate OFF, where
 *     nothing is hidden. A recipe that surfaces it there has a FALSE
 *     reason, and the fix is to filter the surface and move it to
 *     `ownerFiltered` - never to widen the reason.
 *
 * The exemption from the two-sided form is therefore an explicit,
 * enumerated set ({@link REASONS_REACHING_OWNER_CONTENT}) read off the
 * classification each recipe already carries, not a silence.
 *
 * `fail` runs FIRST so the isolation assertion sees the pristine
 * fixture: several recipes are writers, and the reachability half must
 * not be what decides whether the boundary held.
 */
for (const entry of PROBE_ENTRIES) {
  for (const [index, recipe] of entry.calls.entries()) {
    const label = probeLabel(entry.name, recipe, index);
    const reaches = REASONS_REACHING_OWNER_CONTENT.has(recipe.reason);
    test(
      `${label}: ${reaches ? "reaches owner content and withholds it" : "reaches no owner content"}`,
      async () => {
        await seedTwoOwnerFixture();

        setGate(GATE_MODE.fail);
        const scoped = await probeResponse(entry.name, probeArgs(recipe), recipe.reach);
        expect(scoped, `${label} under fail\n${recipe.reason}`).not.toContain(CROSS_OWNER_MARKER);

        setGate(GATE_MODE.off);
        const unscoped = await probeResponse(entry.name, probeArgs(recipe), recipe.reach);
        if (reaches) {
          expect(unscoped, `${label} under off\n${recipe.reason}`).toContain(CROSS_OWNER_MARKER);
        } else {
          expect(unscoped, `${label} under off\n${recipe.reason}`).not.toContain(
            CROSS_OWNER_MARKER,
          );
        }
      },
      PROBE_TIMEOUT_MS,
    );
  }
}

/**
 * F1: `apply` planned against the UNFILTERED report.
 *
 * The probe above catches the disclosure - the applier's `detail` names
 * both merged ids - but not the WRITE, which is the worse half: a caller
 * whose scan correctly returned nothing could still retire another
 * owner's preference by handing `apply` an id it had never been shown.
 * Finding ids are `sha256(sorted targets).slice(0, 12)`, so they are
 * derivable rather than secret and withholding them was never the
 * boundary.
 */
test("brain_hygiene apply cannot execute a finding the same caller's scan withheld", async () => {
  await seedTwoOwnerFixture();
  setGate(GATE_MODE.fail);

  const hidden = runHygieneScan(vault, { now: new Date() }).findings.filter((f) =>
    f.targets.some((t) => t.includes(CROSS_OWNER_MARKER)),
  );
  expect(hidden.length, "the fixture must produce findings over owner-A artifacts").toBeGreaterThan(
    0,
  );
  const ids = hidden.map((f) => f.id);

  const scan = JSON.parse(await call("brain_hygiene", { mode: "scan" }, OWNER_B));
  expect(JSON.stringify(scan)).not.toContain(CROSS_OWNER_MARKER);

  const applied = JSON.parse(await call("brain_hygiene", { mode: "apply", ids }, OWNER_B));
  expect(applied.applied).toEqual([]);
  expect(applied.changed).toBe(0);

  // The artifacts are still on disk, still owned, still unmerged.
  for (const slug of [`${CROSS_OWNER_MARKER}-a2`, `${CROSS_OWNER_MARKER}-a4`]) {
    expect(existsSync(join(vault, "Brain", "preferences", `pref-${slug}.md`))).toBe(true);
  }
});

/**
 * F1, second half: the dry run was an existence oracle.
 *
 * A hidden finding came back as `excluded_review:[id]` and an id nobody
 * ever issued came back as `unknown_ids:[id]`, so a caller could
 * enumerate the hidden population one derived id at a time without ever
 * being shown a finding. IDENTICAL TO ABSENT is the convention
 * `preferences-collect.ts` states; this is it, executed.
 */
test("a withheld hygiene finding id answers exactly as an id nobody issued", async () => {
  await seedTwoOwnerFixture();
  setGate(GATE_MODE.fail);

  const hiddenId = runHygieneScan(vault, { now: new Date() }).findings.find((f) =>
    f.targets.some((t) => t.includes(CROSS_OWNER_MARKER)),
  )!.id;
  const inventedId = "dedup:000000000000";

  const withheld = JSON.parse(
    await call("brain_hygiene", { mode: "apply", ids: [hiddenId], dry_run: true }, OWNER_B),
  );
  const absent = JSON.parse(
    await call("brain_hygiene", { mode: "apply", ids: [inventedId], dry_run: true }, OWNER_B),
  );

  expect(withheld.unknown_ids).toEqual([hiddenId]);
  expect(withheld.excluded_review).toEqual([]);
  // Same shape, same fields, same emptiness - only the echoed id differs.
  expect({ ...withheld, unknown_ids: [] }).toEqual({ ...absent, unknown_ids: [] });
});

/**
 * F3: the verdict was folded over findings the arrays no longer carried.
 *
 * `verdict: watch` beside four empty arrays tells the caller that a
 * hidden artifact tripped a detector - the existence leak with the
 * evidence removed.
 */
test("brain_health's verdict is folded over the findings it actually returns", async () => {
  await seedTwoOwnerFixture();

  setGate(GATE_MODE.off);
  const unscoped = JSON.parse(await call("brain_health", {}, OWNER_B));
  expect(unscoped.verdict).not.toBe("clean");
  expect(JSON.stringify(unscoped)).toContain(CROSS_OWNER_MARKER);

  setGate(GATE_MODE.fail);
  const scoped = JSON.parse(await call("brain_health", {}, OWNER_B));
  const named =
    scoped.contradictions.length + scoped.stale_claims.length + scoped.batch_inflation.length;
  if (named === 0 && scoped.concept_gaps.length === 0) {
    expect(scoped.verdict).toBe("clean");
  }
  expect(JSON.stringify(scoped)).not.toContain(CROSS_OWNER_MARKER);
});

/**
 * The probe's own shape, pinned as equalities.
 *
 * Three numbers are quoted outside this file - `docs/architecture.md`,
 * `docs/mcp.md` and the release notes all state how much of the tool
 * surface is really driven - and a number quoted in prose with nothing
 * keeping it true is the defect this whole release is about. The
 * two-sided count is the load-bearing one: it is how many recipes prove
 * their own reachability before asserting withholding, and the release
 * before this one shipped a probe where that number was effectively one.
 *
 * Raising any of these is ordinary; lowering the two-sided count means a
 * surface stopped being exercised, which is exactly the regression a
 * floor would have let through.
 */
test("the probe's population and its two-sided share are what the docs say", () => {
  const recipes = PROBE_ENTRIES.flatMap((entry) => entry.calls);
  const twoSided = recipes.filter((r) => REASONS_REACHING_OWNER_CONTENT.has(r.reason));
  expect(PROBE_ENTRIES.length).toBe(PROBE_ENTRY_COUNT);
  expect(recipes.length).toBe(PROBE_RECIPE_COUNT);
  expect(twoSided.length).toBe(PROBE_TWO_SIDED_COUNT);
});