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
34.1 KB
Raw Blame
/**
 * `o2b bootstrap` (write-side-trust, Task 14).
 *
 * One command spans the three real install models: adapter targets run
 * the adapter's existing idempotent apply, `generic` is print-and-paste,
 * and plugin runtimes (claude-code, zcode) are verify-only - the plugin
 * registers the server itself, so bootstrap touches nothing but the
 * token and the receipt. The material is printed exactly once with a
 * shown-once notice and never lands in a harness config: the payload env
 * block stays credential-free, because the token reaches the agent
 * through its environment or a `$secret:` reference, never a config file.
 *
 * The codex adapter-probing cases run against the injected runner seams
 * (no `codex` binary, no host probe), so the suite is deterministic and
 * network-free on any machine; they still carry an explicit 20000 ms
 * timeout per the lane rules, because they exercise adapter machinery
 * that shells out on a real host.
 */

import { afterEach, beforeEach, describe, expect, mock, setDefaultTimeout, test } from "bun:test";
import {
  existsSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  readdirSync,
  rmSync,
  utimesSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { runCli } from "../helpers/run-cli.ts";
import { fakeCredential } from "../helpers/fake-credentials.ts";
import {
  resetCodexRunner,
  setCodexRunner,
  type CodexRunner,
} from "../../src/core/install/adapters/codex.ts";
import { resetHostProbeRunner, setHostProbeRunner } from "../../src/core/install/host-probe.ts";
import {
  listAgentTokens,
  resolveAgentForToken,
  revokeAgentToken,
} from "../../src/core/brain/secrets/token-store.ts";
import { startHttp, type HttpServerHandle } from "../../src/mcp/index.ts";
import { JSONRPC_VERSION } from "../../src/mcp/protocol.ts";

// The payload-refusal test below needs buildPayload to throw a PayloadError
// AFTER the mint, on demand and portably (the real builder refuses only on
// an empty vault or a Windows-metacharacter path), so the module is wrapped
// in a forwarding mock (captured before the mock is installed, or the
// forward would recurse) that fails only while a flag is set.
import * as payloadModule from "../../src/core/install/payload.ts";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";

// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

const realBuildPayload = payloadModule.buildPayload;
let failPayloadBuild = false;

mock.module("../../src/core/install/payload.ts", () => ({
  ...payloadModule,
  buildPayload: (
    ...args: Parameters<typeof realBuildPayload>
  ): ReturnType<typeof realBuildPayload> => {
    if (failPayloadBuild) {
      throw new payloadModule.PayloadError("injected: the payload build refused");
    }
    return realBuildPayload(...args);
  },
}));

let tempRoot: string;
let vault: string;
let codexHome: string;
let opencodeHome: string;

beforeEach(() => {
  tempRoot = mkdtempSync(join(tmpdir(), "o2b-bootstrap-"));
  vault = join(tempRoot, "brain vault");
  codexHome = join(tempRoot, "codex-home");
  opencodeHome = join(tempRoot, "opencode-home");
  // A legacy vault: it keeps its machine state (the bootstrap receipt). A
  // vault with no `Brain/` is store-only and keeps it device-local instead.
  mkdirSync(join(vault, "Brain"), { recursive: true });
  // Both subprocess seams are injected for the whole suite: the codex
  // adapter must take its file-fallback path (no binary), and the host
  // probe must report the binary missing (no `codex mcp list` spawn).
  setCodexRunner({
    available: () => false,
    run: () => {
      throw new Error("the codex binary is injected absent in this suite");
    },
  });
  setHostProbeRunner({
    available: () => false,
    run: () => ({ exitCode: 127, stdout: "", stderr: "injected: binary absent" }),
  });
});

afterEach(() => {
  resetCodexRunner();
  resetHostProbeRunner();
  rmSync(tempRoot, { recursive: true, force: true });
});

/** The codex file-fallback config the adapter writes under the injected home. */
function codexConfigPath(): string {
  return join(codexHome, "config.toml");
}

function receiptPath(): string {
  return join(vault, ".open-second-brain", "bootstrap.lock.json");
}

function readReceipt(): Record<string, any> {
  return JSON.parse(readFileSync(receiptPath(), "utf8")) as Record<string, any>;
}

function bytesOf(path: string): string {
  return readFileSync(path, "utf8");
}

function countOccurrences(haystack: string, needle: string): number {
  return haystack.split(needle).length - 1;
}

function custodyAuditActions(): Array<Record<string, any>> {
  const dir = join(vault, "Brain", "log", "secret-custody");
  if (!existsSync(dir)) return [];
  return readdirSync(dir).flatMap((f) =>
    readFileSync(join(dir, f), "utf8")
      .split("\n")
      .filter((line) => line.trim().length > 0)
      .map((line) => JSON.parse(line) as Record<string, any>),
  );
}

/** The bootstrap argv every provisioning case starts from. */
function bootstrapArgs(extra: ReadonlyArray<string>): string[] {
  return ["bootstrap", "--vault", vault, ...extra];
}

/**
 * Real agent identities for the mints. The targets themselves (`codex`,
 * `claude-code`) are PLACEHOLDER_AGENT_VALUES - names the identity layer
 * treats as absent - so a mint under them is refused (see the refusals
 * suite); every provisioning case names its agent explicitly.
 */
const CODEX_AGENT = "codex-workstation";
const CLAUDE_AGENT = "claude-workstation";
const OPENCODE_AGENT = "opencode-workstation";

/** The single osbt-shaped line a mint or rotate prints, trimmed. */
function printedMaterial(stdout: string): string {
  const start = stdout.indexOf("osbt_");
  expect(start).toBeGreaterThanOrEqual(0);
  return stdout.slice(start, stdout.indexOf("\n", start)).trim();
}

/**
 * A `codex` binary that registers like the real one: `mcp add` appends the
 * server's table to `$CODEX_HOME/config.toml` in the host's own layout, so
 * apply takes the subprocess path and `verify` asks the declared host probe.
 * Anything else (the best-effort `mcp remove`) exits non-zero.
 */
function fakeCodexHost(): CodexRunner {
  return {
    available: () => true,
    run(home, args) {
      const [, action, name] = args;
      if (action !== "add" || typeof name !== "string") {
        return { exitCode: 1, stdout: "", stderr: `unknown command: ${args.join(" ")}` };
      }
      mkdirSync(home, { recursive: true });
      writeFileSync(codexConfigPath(), `[mcp_servers.${name}]\ncommand = "o2b"\n`, { flag: "a" });
      return { exitCode: 0, stdout: "", stderr: "" };
    },
  };
}

describe("o2b bootstrap --target codex (adapter model)", () => {
  test("mints the named token, applies the adapter, and prints the material exactly once", async () => {
    const r = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      {
        env: { CODEX_HOME: codexHome },
      },
    );
    expect(r.returncode).toBe(0);

    const store = listAgentTokens(vault);
    expect(store).toHaveLength(1);
    const record = store[0]!;
    expect(record.name).toBe("mcp_token_codex");
    expect(record.agent).toBe(CODEX_AGENT);
    expect(record.status).toBe("active");

    // The material exists in exactly one output channel, once, with the
    // shown-once notice beside it.
    const materialStart = r.stdout.indexOf("osbt_");
    expect(materialStart).toBeGreaterThanOrEqual(0);
    const lineEnd = r.stdout.indexOf("\n", materialStart);
    const tokenMaterial = r.stdout.slice(materialStart, lineEnd).trim();
    expect(countOccurrences(r.stdout, tokenMaterial)).toBe(1);
    expect(r.stdout).toContain("shown exactly once");
    // The credential boundary beside the material: what the token
    // authenticates (hand-configured HTTP clients) and what it does not
    // (the registered stdio harness keeps its config-derived identity).
    expect(r.stdout).toContain("config-derived identity");
    expect(r.stderr).not.toContain(tokenMaterial);

    // The harness config carries the registration and never the
    // credential: the payload env block stays credential-free.
    const configToml = bytesOf(codexConfigPath());
    expect(configToml).toContain("[mcp_servers.open-second-brain]");
    expect(configToml).toContain("[mcp_servers.open-second-brain-writer]");
    expect(configToml).not.toContain("osbt_");
    expect(configToml).not.toContain(tokenMaterial);

    // The receipt: schema 1, owned entries, token name and non-secret
    // prefix, applied_at.
    const receipt = readReceipt();
    expect(receipt["schema_version"]).toBe(1);
    const entry = receipt["entries"]["codex"];
    expect(entry["target"]).toBe("codex");
    expect(entry["config_path"]).toBe(codexConfigPath());
    expect(entry["owned_keys"]).toEqual(["open-second-brain", "open-second-brain-writer"]);
    expect(entry["token"]).toEqual({
      name: "mcp_token_codex",
      prefix: record.token_prefix,
    });
    expect(typeof entry["applied_at"]).toBe("string");
    expect((entry["applied_at"] as string).length).toBeGreaterThan(0);

    // The minted material authenticates, via the same resolution the
    // transport performs per request.
    expect(resolveAgentForToken(vault, tokenMaterial)).toEqual({
      agent: CODEX_AGENT,
      name: "mcp_token_codex",
    });
  }, 20000);

  test("a second identical run is a byte-identical no-op: exit 0, no receipt churn", async () => {
    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);
    const materialStart = first.stdout.indexOf("osbt_");
    const tokenMaterial = first.stdout
      .slice(materialStart, first.stdout.indexOf("\n", materialStart))
      .trim();

    const configBefore = bytesOf(codexConfigPath());
    const receiptBefore = bytesOf(receiptPath());
    const installBefore = bytesOf(join(vault, ".open-second-brain", "install.lock.json"));

    const second = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(second.returncode).toBe(0);
    // No reprint: the material is shown once per mint, never per run.
    expect(second.stdout).not.toContain(tokenMaterial);
    expect(second.stdout).toContain("already provisioned");
    expect(bytesOf(codexConfigPath())).toBe(configBefore);
    expect(bytesOf(receiptPath())).toBe(receiptBefore);
    expect(bytesOf(join(vault, ".open-second-brain", "install.lock.json"))).toBe(installBefore);
    expect(listAgentTokens(vault)).toHaveLength(1);
  }, 20000);

  test("--rotate re-mints under the same name, audits replaced, and the new material authenticates on the next request with no server restart", async () => {
    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    const materialStart = first.stdout.indexOf("osbt_");
    const oldMaterial = first.stdout
      .slice(materialStart, first.stdout.indexOf("\n", materialStart))
      .trim();

    // The server starts BEFORE the rotation and stays up across it: the
    // rotation must land on its next request, not on a restart.
    let handle: HttpServerHandle | null = null;
    try {
      handle = await startHttp({ vault }, { host: "127.0.0.1", port: 0 });
      const rpc = (id: number) =>
        JSON.stringify({
          jsonrpc: JSONRPC_VERSION,
          id,
          method: "tools/call",
          params: { name: "brain_context_pack", arguments: { max_tokens: 2000 } },
        });
      const post = async (material: string): Promise<Response> =>
        fetch(handle!.url, {
          method: "POST",
          headers: {
            "content-type": "application/json",
            accept: "application/json",
            authorization: `Bearer ${material}`,
          },
          body: rpc(1),
        });

      // The old material authenticates before the rotation.
      expect((await post(oldMaterial)).status).toBe(200);

      const rotated = await runCli(bootstrapArgs(["--target", "codex", "--rotate"]), {
        env: { CODEX_HOME: codexHome },
      });
      expect(rotated.returncode).toBe(0);
      const newStart = rotated.stdout.indexOf("osbt_");
      expect(newStart).toBeGreaterThanOrEqual(0);
      const newMaterial = rotated.stdout
        .slice(newStart, rotated.stdout.indexOf("\n", newStart))
        .trim();
      expect(newMaterial).not.toBe(oldMaterial);
      expect(countOccurrences(rotated.stdout, newMaterial)).toBe(1);
      expect(rotated.stdout).toContain("shown exactly once");

      // Same name, new hash; the store audit carries replaced: true.
      const store = listAgentTokens(vault);
      expect(store).toHaveLength(1);
      expect(store[0]!.name).toBe("mcp_token_codex");
      expect(store[0]!.rotated_at).toBeDefined();
      const rotatedRows = custodyAuditActions().filter(
        (row) => row["action"] === "mcp_token_rotated",
      );
      expect(rotatedRows).toHaveLength(1);
      expect(rotatedRows[0]!["details"]["replaced"]).toBe(true);

      // The receipt followed the rotation: same name, new prefix.
      const receipt = readReceipt();
      expect(receipt["entries"]["codex"]["token"]["name"]).toBe("mcp_token_codex");
      expect(receipt["entries"]["codex"]["token"]["prefix"]).toBe(store[0]!.token_prefix);
      expect(receipt["entries"]["codex"]["token"]["prefix"]).not.toBe(
        oldMaterial.slice(0, store[0]!.token_prefix.length),
      );

      // No restart: both materials authenticate on the very next
      // requests of the same server - the new one from here on, the old
      // one through the rotation grace window while the new material is
      // being placed (the store suite walks the window's expiry with an
      // injected clock).
      expect((await post(oldMaterial)).status).toBe(200);
      expect((await post(newMaterial)).status).toBe(200);
      expect(
        resolveAgentForToken(vault, fakeCredential("osbt_", "never-minted-material")),
      ).toBeNull();
    } finally {
      if (handle !== null) await handle.close();
    }
  }, 20000);

  test("--check reports ok after bootstrap, drift after the config is edited, and drift when nothing is provisioned", async () => {
    const fresh = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(fresh.returncode).toBe(3);
    expect(fresh.stdout).toContain("not-installed");

    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);

    const ok = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(ok.returncode).toBe(0);
    expect(ok.stdout).toContain("registration: ok");
    expect(ok.stdout).toContain("mcp_token_codex active");

    // An operator edit the adapter did not write is drift, with the
    // install verb's fix hint named.
    const drifted = bytesOf(codexConfigPath()).replace("mcp", "not-mcp");
    const { writeFileSync } = await import("node:fs");
    writeFileSync(codexConfigPath(), drifted);
    const after = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(after.returncode).toBe(3);
    expect(after.stdout).toContain("registration: drift");
  }, 20000);

  test("--check refuses a revoked or missing token as drift, naming the provisioning command", async () => {
    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);

    const checked = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(checked.returncode).toBe(3);
    expect(checked.stdout).toContain("not active");
    expect(checked.stdout).toContain("--token");
  }, 20000);

  test("a revoked token refuses every provision form instead of a healthy no-op, matching --check", async () => {
    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);

    // The same vault that --check calls drift (exit 3) must not read as
    // healthy to the provision path: the receipt still carries the
    // revoked token's name and prefix, so the no-churn gate would
    // otherwise answer "already provisioned" exit 0.
    const checked = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(checked.returncode).toBe(3);

    const plain = await runCli(bootstrapArgs(["--target", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(plain.returncode).toBe(1);
    expect(plain.stderr).toContain("is revoked");
    expect(plain.stderr).toContain("o2b mcp token mint");
    expect(plain.stdout).not.toContain("already provisioned");

    const withToken = await runCli(bootstrapArgs(["--target", "codex", "--token"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(withToken.returncode).toBe(1);
    expect(withToken.stderr).toContain("is revoked");
  }, 20000);

  test("--check keeps the unreachable verdict when the token half also drifted", async () => {
    setCodexRunner(fakeCodexHost());
    // The host answers the declared probe but names neither OSB server:
    // the configuration is right and the runtime has not loaded it, which
    // is the unreachable verdict, not drift.
    setHostProbeRunner({
      available: () => true,
      run: () => ({ exitCode: 0, stdout: "Name\n", stderr: "" }),
    });

    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);

    const unreachable = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(unreachable.returncode).toBe(5);
    expect(unreachable.stdout).toContain("registration: mcp-unreachable");

    // The token half drifts on top of it. The runtime could not be asked,
    // so the check did not actually run: exit 5 ("could not check")
    // survives, with both findings named on stdout.
    expect(revokeAgentToken(vault, "mcp_token_codex")).toBe(true);
    const after = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(after.returncode).toBe(5);
    expect(after.stdout).toContain("registration: mcp-unreachable");
    expect(after.stdout).toContain("not active");
  }, 20000);

  test("--rotate with nothing to rotate is a runtime error naming the mint command", async () => {
    const r = await runCli(bootstrapArgs(["--target", "codex", "--rotate"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("mcp_token_codex");
  }, 20000);
});

describe("o2b bootstrap --target generic (print-and-paste)", () => {
  test("prints the payload and the manual steps, mints on --token, and never writes a harness config", async () => {
    const r = await runCli(bootstrapArgs(["--target", "generic", "--token"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("mcpServers");
    expect(r.stdout).toContain("second-brain");
    expect(r.stdout).toContain("manual steps");

    const materialStart = r.stdout.indexOf("osbt_");
    const tokenMaterial = r.stdout
      .slice(materialStart, r.stdout.indexOf("\n", materialStart))
      .trim();
    // Exactly one osbt-shaped string on stdout: the minted material.
    // The payload env block stays credential-free.
    expect(countOccurrences(r.stdout, "osbt_")).toBe(1);
    expect(countOccurrences(r.stdout, tokenMaterial)).toBe(1);

    const receipt = readReceipt();
    const entry = receipt["entries"]["generic"];
    expect(entry["mode"]).toBe("print");
    expect(entry["token"]["name"]).toBe("mcp_token_generic");
    expect(resolveAgentForToken(vault, tokenMaterial)).toEqual({
      agent: "generic",
      name: "mcp_token_generic",
    });
    // Print-and-paste wrote no harness config anywhere.
    expect(existsSync(codexConfigPath())).toBe(false);
  }, 20000);
});

describe("o2b bootstrap --target claude-code (plugin verify-only)", () => {
  test("mints and records the token, writes no harness config, and points at the plugin's own verify", async () => {
    const r = await runCli(
      bootstrapArgs(["--target", "claude-code", "--agent", CLAUDE_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("verify only");
    expect(r.stdout).toContain("o2b doctor");

    const materialStart = r.stdout.indexOf("osbt_");
    const tokenMaterial = r.stdout
      .slice(materialStart, r.stdout.indexOf("\n", materialStart))
      .trim();
    expect(countOccurrences(r.stdout, tokenMaterial)).toBe(1);

    const receipt = readReceipt();
    const entry = receipt["entries"]["claude-code"];
    expect(entry["mode"]).toBe("verify-only");
    expect(entry["token"]["name"]).toBe("mcp_token_claude_code");
    expect(existsSync(codexConfigPath())).toBe(false);
    expect(resolveAgentForToken(vault, tokenMaterial)).not.toBeNull();

    const checked = await runCli(bootstrapArgs(["--target", "claude-code", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(checked.returncode).toBe(0);
    expect(checked.stdout).toContain("plugin-managed");
  }, 20000);

  test("without --token it prints the steps and writes no receipt", async () => {
    const r = await runCli(bootstrapArgs(["--target", "zcode"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(0);
    expect(r.stdout).toContain("verify only");
    expect(existsSync(receiptPath())).toBe(false);
    expect(listAgentTokens(vault)).toHaveLength(0);
  });
});

describe("o2b bootstrap refusals", () => {
  test("unsupported and unknown targets are refused with the available list", async () => {
    for (const target of ["cursor", "copilot-cli", "nonsense"]) {
      const r = await runCli(bootstrapArgs(["--target", target]), {
        env: { CODEX_HOME: codexHome },
      });
      expect(r.returncode).toBe(2);
      expect(r.stderr).toContain(target);
      expect(r.stderr).toContain("claude-code, codex, generic, grok, opencode, zcode");
    }
  });

  test("a missing --target is a usage refusal with the same list", async () => {
    const r = await runCli(["bootstrap", "--vault", vault], { env: { CODEX_HOME: codexHome } });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("claude-code, codex, generic, grok, opencode, zcode");
  });

  test("--check combined with --token is a usage refusal", async () => {
    const r = await runCli(bootstrapArgs(["--target", "codex", "--check", "--token"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(2);
  });

  test("an unconfigured vault is the named usage refusal", async () => {
    const r = await runCli(["bootstrap", "--target", "codex", "--token"], {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(2);
    expect(r.stderr).toContain("vault not configured");
  });

  test("positional arguments are a usage refusal", async () => {
    const r = await runCli(bootstrapArgs(["--target", "codex", "extra"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(r.returncode).toBe(2);
  });

  test("a mint under a placeholder agent identity refuses by name; the plain path keeps working", async () => {
    // No --agent at all: the target name itself is the placeholder the
    // identity layer treats as absent, so the mint refuses before
    // anything is written.
    const noAgent = await runCli(bootstrapArgs(["--target", "codex", "--token"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(noAgent.returncode).toBe(2);
    expect(noAgent.stderr).toContain("mcp_token_codex");
    expect(noAgent.stderr).toContain("--agent");
    expect(listAgentTokens(vault)).toHaveLength(0);
    expect(existsSync(codexConfigPath())).toBe(false);

    // An explicit placeholder is the same refusal.
    const explicit = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", "codex", "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(explicit.returncode).toBe(2);
    expect(explicit.stderr).toContain("placeholder");

    // Any target minting under a placeholder name refuses the same way.
    const generic = await runCli(
      bootstrapArgs(["--target", "generic", "--agent", "bot", "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(generic.returncode).toBe(2);
    expect(listAgentTokens(vault)).toHaveLength(0);

    // The plain (no --token) provision path never mints, so it keeps
    // working without --agent.
    const plain = await runCli(bootstrapArgs(["--target", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(plain.returncode).toBe(0);
    expect(existsSync(codexConfigPath())).toBe(true);
    expect(listAgentTokens(vault)).toHaveLength(0);

    // Once a token exists under a real name, a plain re-run adopts the
    // minted identity instead of refusing.
    const minted = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(minted.returncode).toBe(0);
    const rerun = await runCli(bootstrapArgs(["--target", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(rerun.returncode).toBe(0);
    expect(listAgentTokens(vault)).toHaveLength(1);
  }, 20000);

  test("a corrupted receipt refuses --check through the clean error path, not a crash", async () => {
    mkdirSync(join(vault, ".open-second-brain"), { recursive: true });
    writeFileSync(receiptPath(), "{ not json");
    const r = await runCli(bootstrapArgs(["--target", "codex", "--check"]), {
      env: { CODEX_HOME: codexHome },
    });
    // The same named refusal the provision path gives: an exit code and a
    // one-line error, never a raw stack.
    expect(r.returncode).toBe(1);
    expect(r.stderr).toContain("bootstrap receipt is corrupted JSON");
    expect(r.stderr).not.toContain("BootstrapReceiptError");
    expect(r.stderr).not.toMatch(/^\s+at /m);
  }, 20000);
});

describe("o2b bootstrap --remove (receipt-driven teardown)", () => {
  test("revokes the receipt's token, removes the owned registration, drops the receipt entry, and is idempotent", async () => {
    const first = await runCli(
      bootstrapArgs(["--target", "codex", "--agent", CODEX_AGENT, "--token"]),
      { env: { CODEX_HOME: codexHome } },
    );
    expect(first.returncode).toBe(0);
    const material = printedMaterial(first.stdout);
    expect(existsSync(codexConfigPath())).toBe(true);
    expect(readReceipt()["entries"]["codex"]).toBeDefined();

    const removed = await runCli(bootstrapArgs(["--remove", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(removed.returncode).toBe(0);
    // The registration the adapter wrote is gone...
    expect(existsSync(codexConfigPath())).toBe(true);
    expect(bytesOf(codexConfigPath())).not.toContain("mcp_servers.open-second-brain");
    // ...the receipt's token is revoked - immediately, no grace: removal
    // is not a rotation, nobody is placing new material...
    expect(listAgentTokens(vault)[0]!.status).toBe("revoked");
    expect(resolveAgentForToken(vault, material)).toBeNull();
    expect(removed.stdout).toContain("revoked");
    expect(removed.stdout).toContain("removed");
    // ...and the receipt entry is dropped the way the install manifest
    // models removal: the entry goes, the file stays.
    expect(readReceipt()["entries"]["codex"]).toBeUndefined();

    // A second remove finds nothing and exits clean.
    const again = await runCli(bootstrapArgs(["--remove", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(again.returncode).toBe(0);
    expect(again.stdout).toContain("nothing to remove");
    expect(bytesOf(codexConfigPath())).not.toContain("mcp_servers.open-second-brain");
    expect(listAgentTokens(vault)[0]!.status).toBe("revoked");
  }, 20000);

  test("an unknown target and provision-flag combinations are usage refusals", async () => {
    const unknown = await runCli(bootstrapArgs(["--remove", "nonsense"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(unknown.returncode).toBe(2);
    expect(unknown.stderr).toContain("claude-code, codex, generic, grok, opencode, zcode");

    const mixed = await runCli(bootstrapArgs(["--target", "codex", "--remove", "codex"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(mixed.returncode).toBe(2);
    expect(mixed.stderr).toContain("--remove");

    const withToken = await runCli(bootstrapArgs(["--remove", "codex", "--token"]), {
      env: { CODEX_HOME: codexHome },
    });
    expect(withToken.returncode).toBe(2);
  });
});

describe("o2b bootstrap when the adapter apply fails after a mint (opencode)", () => {
  /** `$XDG_CONFIG_HOME/opencode/opencode.json`, the adapter's config. */
  function opencodeConfigPath(): string {
    return join(opencodeHome, "opencode", "opencode.json");
  }

  test("bootstrap --target opencode lands in an existing V2 mcp.servers config", async () => {
    mkdirSync(join(opencodeHome, "opencode"), { recursive: true });
    writeFileSync(opencodeConfigPath(), JSON.stringify({ mcp: { servers: {} } }, null, 2) + "\n");
    const r = await runCli(
      bootstrapArgs(["--target", "opencode", "--agent", OPENCODE_AGENT, "--token"]),
      { env: { XDG_CONFIG_HOME: opencodeHome } },
    );
    expect(r.returncode).toBe(0);
    const parsed = JSON.parse(readFileSync(opencodeConfigPath(), "utf8"));
    expect(parsed.mcp.servers["open-second-brain"]).toBeDefined();
    expect(parsed.mcp.servers["open-second-brain-writer"]).toBeDefined();
    // No shadowing copy under the legacy top-level key.
    expect(parsed.mcp["open-second-brain"]).toBeUndefined();
  }, 20000);

  test("a rotate into a hand-edited config still shows the material exactly once and names the retry path", async () => {
    mkdirSync(opencodeHome, { recursive: true });
    const env = { XDG_CONFIG_HOME: opencodeHome };
    const first = await runCli(
      bootstrapArgs(["--target", "opencode", "--agent", OPENCODE_AGENT, "--token"]),
      { env },
    );
    expect(first.returncode).toBe(0);
    const firstMaterial = printedMaterial(first.stdout);

    // Hand-edit: keep the OSB keys but change a value, and stamp an mtime
    // newer than the manifest's applied_at - exactly what the adapter's
    // user-modified-block safety net refuses to overwrite.
    const edited = bytesOf(opencodeConfigPath()).replace("o2b", "not-o2b");
    writeFileSync(opencodeConfigPath(), edited);
    const future = new Date(Date.now() + 10_000);
    utimesSync(opencodeConfigPath(), future, future);

    const rotated = await runCli(bootstrapArgs(["--target", "opencode", "--rotate"]), { env });
    expect(rotated.returncode).toBe(4);
    expect(rotated.stderr).toContain("hand-edited");

    // The mint happened, so the material prints - exactly once, on
    // stdout, beside the failure notice naming the retry and revoke
    // paths. Losing it silently would orphan a live credential whose
    // name a re-run would refuse to re-mint.
    const newMaterial = printedMaterial(rotated.stdout);
    expect(newMaterial).not.toBe(firstMaterial);
    expect(countOccurrences(rotated.stdout, newMaterial)).toBe(1);
    expect(rotated.stderr).not.toContain(newMaterial);
    expect(rotated.stdout).toContain("live in the store");
    expect(rotated.stdout).toContain("o2b mcp token revoke --name mcp_token_opencode");
    expect(resolveAgentForToken(vault, newMaterial)).toEqual({
      agent: OPENCODE_AGENT,
      name: "mcp_token_opencode",
    });

    // The named retry path finishes the job: a plain re-run (no --token,
    // so nothing re-mints) forced past the hand-edit block applies the
    // registration and the receipt catches up to the rotated token.
    const retry = await runCli(bootstrapArgs(["--target", "opencode", "--force"]), { env });
    expect(retry.returncode).toBe(0);
    expect(retry.stdout).not.toContain(newMaterial);
    const record = listAgentTokens(vault).find((t) => t.name === "mcp_token_opencode")!;
    expect(record.token_prefix).not.toBe(firstMaterial.slice(0, record.token_prefix.length));
    const entry = readReceipt()["entries"]["opencode"];
    expect(entry["token"]).toEqual({ name: "mcp_token_opencode", prefix: record.token_prefix });
    expect(entry["agent"]).toBe(OPENCODE_AGENT);
  }, 20000);
});

/**
 * The payload build refusing AFTER the mint (the run's other pre-apply
 * exit): the material is live in the store and a re-run would never show
 * it, so the rescue print must fire here too - exactly once, on stdout,
 * beside the failure notice - instead of orphaning the credential.
 */
describe("o2b bootstrap when the payload build refuses after a mint (generic)", () => {
  test("a payload refusal after a mint still shows the material exactly once, on stdout only", async () => {
    failPayloadBuild = true;
    try {
      const r = await runCli(
        bootstrapArgs(["--target", "generic", "--agent", OPENCODE_AGENT, "--token"]),
        {},
      );
      expect(r.returncode).toBe(2);
      expect(r.stderr).toContain("injected: the payload build refused");
      // The mint happened, so the material prints - exactly once, on
      // stdout, beside the failure notice naming the retry and revoke
      // paths, with stderr carrying none of it.
      const material = printedMaterial(r.stdout);
      expect(countOccurrences(r.stdout, material)).toBe(1);
      expect(r.stdout).toContain("live in the store");
      expect(r.stdout).toContain("o2b mcp token revoke --name mcp_token_generic");
      expect(r.stderr).not.toContain(material);
      expect(resolveAgentForToken(vault, material)).toEqual({
        agent: OPENCODE_AGENT,
        name: "mcp_token_generic",
      });
    } finally {
      failPayloadBuild = false;
    }
  }, 20000);
});