@openparachute/vault 0.6.1 → 0.6.2-rc.1

package/src/init-summary.ts

@@ -5,13 +5,32 @@
  */
 
 export type InitSummaryInput = {
+  /**
+   * Whether init WROTE the Claude Code MCP config (~/.claude.json) this run.
+   * As of 2026-06-23 this is opt-in (default false) — init's primary job is to
+   * point the operator at the web setup wizard and surface the self-serve
+   * connect info, not to write a config file as a side effect.
+   */
   addMcp: boolean;
   addToken: boolean;
   apiKey: string | undefined;
   configDir: string;
   bindHost: string;
   port: number;
+  /**
+   * The vault's MCP connector URL — `<hub-origin>/vault/<name>/mcp` (hub-origin
+   * / expose-state aware). Surfaced in the summary for self-serve copy-paste:
+   * a ready-to-run `claude mcp add ...` command is built from it so a Claude
+   * Code user can opt in by pasting one line, AND it's printed plain so any
+   * other MCP client can be pointed at it.
+   */
   mcpUrl: string;
+  /**
+   * The web setup wizard URL — `<hub-origin>/admin/setup`. init's primary job
+   * is to get the operator into this wizard, so it's printed prominently at the
+   * top of the summary.
+   */
+  wizardUrl?: string | undefined;
   /**
    * The default vault's name — used to emit the three-segment
    * `vault:<vaultName>:read` scope in the OAuth-first mint-token suggestion
@@ -22,8 +41,8 @@ export type InitSummaryInput = {
   /**
    * Guidance from the bootstrap-credential step when no token could be issued
    * (standalone install, no hub reachable — vault#282 Stage 2). Surfaced when
-   * the operator wanted a token (`addMcp || addToken`) but `apiKey` is
-   * undefined, so they know why and how to make the vault reachable.
+   * the operator wanted a token (`addToken`) but `apiKey` is undefined, so they
+   * know why and how to make the vault reachable.
    */
   noTokenGuidance?: string | undefined;
   /**
@@ -38,54 +57,66 @@ export type InitSummaryInput = {
 };
 
 /**
- * Build the post-install summary lines for `vault init`, branched on the
- * (addMcp, addToken, apiKey) decision matrix.
+ * Build the post-install summary lines for `vault init`.
+ *
+ * 2026-06-23 messaging realignment: the site no longer claims "Claude Code is
+ * auto-configured," and init no longer writes `~/.claude.json` by default.
+ * init's job is to (1) point the operator at the web setup wizard, and
+ * (2) SURFACE the self-serve connect info — the connector URL + a ready-to-paste
+ * `claude mcp add ...` line — so a Claude Code user opts in by copy-paste rather
+ * than a silent side effect.
  *
- * vault#442: the DEFAULT is per-user OAuth — no token is minted, and the
- * Claude Code MCP entry is written without a baked bearer (browser sign-in on
- * first connect). A token is minted only on explicit opt-in (`addToken`), and
- * then scope-narrow. Branches:
+ * The summary is built in three parts:
+ *   1. Wizard hand-off (always) — "finish setup in your browser: <wizardUrl>".
+ *   2. Connect-your-AI block — the connector URL + copy-paste `claude mcp add`,
+ *      branched on whether init wrote the MCP entry / minted a token.
+ *   3. Config / server / next-steps footer.
  *
- *   addMcp,  !apiKey            → OAuth-first: connect, sign in on first use
- *   addMcp,  addToken,  apiKey  → token baked into claude.json + printed
- *   addMcp,  !addToken, apiKey  → token baked into claude.json, hint
- *   !addMcp, addToken,  apiKey  → token printed prominently
- *   !addMcp, addToken,  !apiKey → opted into a token but no hub reachable
- *   !addMcp, !addToken          → OAuth-first: add Claude Code later
+ * vault#442: per-user OAuth is the default — no token is minted unless the
+ * operator opts in (`addToken`), and then it's scope-narrow.
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance, hubPresent } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, wizardUrl, vaultName, noTokenGuidance, hubPresent } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
 
-  if (addMcp && apiKey && addToken) {
+  // 1. Wizard hand-off — the primary purpose of init is to get the operator
+  // into the web setup wizard. Lead with it.
+  if (wizardUrl) {
     lines.push("");
-    lines.push(`Your API token: ${apiKey}`);
-    lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
-    lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
-    lines.push(`  - Won't be shown again — save it now.`);
-  } else if (addMcp && apiKey && !addToken) {
-    lines.push("");
-    lines.push(
-      "Token in ~/.claude.json; run `parachute-vault mcp-install` later if you need one for other clients.",
-    );
-  } else if (addMcp && !apiKey) {
-    // vault#442 default: OAuth-first. The MCP entry is wired without a bearer —
-    // Claude Code signs in via browser OAuth on first connect. No token needed.
-    lines.push("");
-    lines.push("Connect your AI — no token needed, you'll sign in on first use:");
-    lines.push(`  Claude Code is already wired in (~/.claude.json) — just start a session.`);
-    lines.push(`  Other clients: claude mcp add --transport http parachute-vault ${mcpUrl}`);
-    lines.push(`  Need a header-auth token for a script? parachute auth mint-token --scope vault:${vaultName}:read`);
-  } else if (!addMcp && addToken && apiKey) {
+    lines.push("Finish setup in your browser:");
+    lines.push(`  ${wizardUrl}`);
+  }
+
+  // The copy-paste opt-in line for Claude Code (and any client that speaks the
+  // `claude mcp add` form). Built from the connector URL so it's the real
+  // endpoint, hub-origin aware.
+  const claudeAddCmd = `claude mcp add --transport http parachute-vault ${mcpUrl}`;
+
+  // 2. Connect-your-AI — surface the self-serve connect info every time.
+  if (addToken && apiKey) {
+    // Operator opted into a header-auth token AND it was minted. Surface it
+    // prominently (won't be shown again), plus the connector URL.
     lines.push("");
     lines.push(`Your API token: ${apiKey}`);
-    lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
+    if (addMcp) {
+      lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
+    }
+    lines.push(`  - Paste into another MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
-  } else if (!addMcp && addToken && !apiKey) {
+    lines.push("");
+    lines.push("Connector URL (point any MCP client here):");
+    lines.push(`  ${mcpUrl}`);
+    if (!addMcp) {
+      lines.push("");
+      lines.push("Add Claude Code by copy-paste:");
+      lines.push(`  ${claudeAddCmd}`);
+    }
+  } else if (addToken && !apiKey) {
     // Explicitly opted into a token but none was minted (vault#282 Stage 2 —
-    // vault no longer mints local pvt_* tokens). Surface why + recovery.
+    // vault no longer mints local pvt_* tokens). Surface why + recovery, then
+    // still print the self-serve connect info.
     lines.push("");
     lines.push(
       noTokenGuidance ??
@@ -113,15 +144,23 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
         "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
       );
     }
-  } else if (!addMcp && !addToken) {
-    // OAuth-first, but the operator skipped wiring Claude Code too.
     lines.push("");
-    lines.push(
-      "Skipped the Claude Code MCP entry. Add it anytime — it uses per-user OAuth, no token needed:",
-    );
-    lines.push(
-      "  parachute-vault mcp-install",
-    );
+    lines.push("Connect your AI — no token needed, you'll sign in on first use:");
+    lines.push(`  Connector URL:  ${mcpUrl}`);
+    lines.push(`  Claude Code:    ${claudeAddCmd}`);
+  } else {
+    // Default path (no token). Per-user OAuth — sign in on first connect.
+    lines.push("");
+    lines.push("Connect your AI — no token needed, you'll sign in on first use:");
+    lines.push(`  Connector URL:  ${mcpUrl}`);
+    if (addMcp) {
+      lines.push(`  Claude Code is already wired in (~/.claude.json) — just start a session.`);
+      lines.push(`  Other clients: ${claudeAddCmd}`);
+    } else {
+      lines.push(`  Claude Code:    ${claudeAddCmd}`);
+      lines.push(`  Other clients (Codex, Goose, OpenCode, Cursor, Zed, Cline): point them at the connector URL above.`);
+    }
+    lines.push(`  Need a header-auth token for a script? parachute auth mint-token --scope vault:${vaultName}:read`);
   }
 
   lines.push("");
@@ -137,19 +176,15 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
 
   lines.push("");
   lines.push(`Next steps:`);
+  if (wizardUrl) {
+    lines.push(`  - Finish setup in the web wizard:  ${wizardUrl}`);
+  }
   if (addMcp) {
     lines.push(`  - Start a new Claude Code session — your Vault is already wired in. Try:`);
     lines.push(`      claude "Help me set up my parachute vault"`);
-    lines.push(`  - Or point any other local MCP client (Codex, Goose, OpenCode, Cursor,`);
-    lines.push(`    Zed, Cline, your own agent) at:`);
-    lines.push(`      ${mcpUrl}`);
-  } else if (addToken) {
-    lines.push(`  - Point any local MCP client (Codex, Goose, OpenCode, Cursor, Zed,`);
-    lines.push(`    Cline, your own agent) at:`);
-    lines.push(`      ${mcpUrl}`);
-    lines.push(`  - Or add Claude Code back anytime:  parachute-vault mcp-install`);
   } else {
-    lines.push(`  - Add Claude Code:  parachute-vault mcp-install`);
+    lines.push(`  - Wire Claude Code (copy-paste):    ${claudeAddCmd}`);
+    lines.push(`    or run the guided installer:      parachute-vault mcp-install`);
   }
   lines.push(`  - Check status:     parachute-vault status`);
   lines.push(`  - Edit config:      parachute-vault config`);

package/src/init.test.ts

@@ -72,6 +72,134 @@ describe("vault init — --help mentions --vault-name", () => {
     expect(exitCode).toBe(0);
     expect(stdout).toContain("--no-autostart");
   });
+
+  test("usage text documents the opt-in --configure-claude-code flag (2026-06-23)", () => {
+    const { exitCode, stdout } = runCli(["--help"]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("--configure-claude-code");
+  });
+});
+
+/**
+ * 2026-06-23 messaging realignment: writing the Claude Code MCP config
+ * (~/.claude.json) is now OPT-IN. init's default no longer writes it — it
+ * surfaces the connector URL + a copy-paste `claude mcp add` command and points
+ * at the web wizard instead. These run init end-to-end under an isolated HOME /
+ * PARACHUTE_HOME (with --no-autostart --no-token to keep daemon + token side
+ * effects out) and assert the ~/.claude.json side effect on the default vs the
+ * opt-in path. Non-interactive (piped) is the mode these spawned subprocesses
+ * run in, which is exactly the back-compat-sensitive path.
+ */
+describe("vault init — Claude Code MCP config is opt-in (2026-06-23)", () => {
+  test("default (no --mcp flag) does NOT write ~/.claude.json, and surfaces copy-paste connect info", () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-mcp-optin-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const claudeJson = join(sandbox, ".claude.json");
+      const { exitCode, stdout } = runCli(
+        [
+          "init",
+          "--no-autostart",
+          "--no-token",
+          "--vault-name",
+          "mcpoptin",
+        ],
+        { HOME: sandbox, PARACHUTE_HOME: parachuteHome },
+      );
+
+      expect(exitCode).toBe(0);
+      // The headline behavior: no silent ~/.claude.json write.
+      expect(existsSync(claudeJson)).toBe(false);
+      expect(stdout).not.toContain("MCP server added to ~/.claude.json");
+      // But the self-serve connect info IS surfaced for copy-paste.
+      expect(stdout).toContain("claude mcp add --transport http");
+      expect(stdout).toContain("/vault/mcpoptin/mcp");
+      // And the web wizard hand-off is present.
+      expect(stdout).toContain("Finish setup in your browser:");
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+
+  test("--configure-claude-code opts in and writes ~/.claude.json", () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-mcp-optin-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const claudeJson = join(sandbox, ".claude.json");
+      const { exitCode, stdout } = runCli(
+        [
+          "init",
+          "--no-autostart",
+          "--no-token",
+          "--configure-claude-code",
+          "--vault-name",
+          "mcpoptin",
+        ],
+        { HOME: sandbox, PARACHUTE_HOME: parachuteHome },
+      );
+
+      expect(exitCode).toBe(0);
+      expect(existsSync(claudeJson)).toBe(true);
+      const claudeConfig = JSON.parse(readFileSync(claudeJson, "utf-8"));
+      // The user-scope entry is keyed `parachute-vault` under top-level mcpServers.
+      expect(claudeConfig.mcpServers?.["parachute-vault"]?.url).toContain(
+        "/vault/mcpoptin/mcp",
+      );
+      expect(stdout).toContain("MCP server added to ~/.claude.json");
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
+
+  for (const alias of ["--mcp", "--mcp-install"]) {
+    test(`the ${alias} alias still opts in`, () => {
+      const sandbox = mkdtempSync(join(tmpdir(), "vault-init-mcp-optin-"));
+      try {
+        const parachuteHome = join(sandbox, ".parachute");
+        const claudeJson = join(sandbox, ".claude.json");
+        const { exitCode } = runCli(
+          [
+            "init",
+            "--no-autostart",
+            "--no-token",
+            alias,
+            "--vault-name",
+            "mcpoptin",
+          ],
+          { HOME: sandbox, PARACHUTE_HOME: parachuteHome },
+        );
+        expect(exitCode).toBe(0);
+        expect(existsSync(claudeJson)).toBe(true);
+      } finally {
+        rmSync(sandbox, { recursive: true, force: true });
+      }
+    });
+  }
+
+  test("--no-mcp wins over an opt-in alias on the same command line", () => {
+    const sandbox = mkdtempSync(join(tmpdir(), "vault-init-mcp-optin-"));
+    try {
+      const parachuteHome = join(sandbox, ".parachute");
+      const claudeJson = join(sandbox, ".claude.json");
+      const { exitCode } = runCli(
+        [
+          "init",
+          "--no-autostart",
+          "--no-token",
+          "--configure-claude-code",
+          "--no-mcp",
+          "--vault-name",
+          "mcpoptin",
+        ],
+        { HOME: sandbox, PARACHUTE_HOME: parachuteHome },
+      );
+      expect(exitCode).toBe(0);
+      // --no-mcp is the safer default and must win — no file written.
+      expect(existsSync(claudeJson)).toBe(false);
+    } finally {
+      rmSync(sandbox, { recursive: true, force: true });
+    }
+  });
 });
 
 /**

package/src/mirror-remote-guard.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Tests for the cross-vault remote-clobber guard (vault#482).
+ *
+ * Two layers:
+ *   - Pure normalization / equivalence (`normalizeRemoteIdentity`,
+ *     `sameRemoteIdentity`) — https vs ssh vs scp-shorthand vs .git-suffix.
+ *   - `findConflictingVault` against real on-disk vault state under a temp
+ *     PARACHUTE_HOME (no network, no live manager).
+ */
+
+import { describe, test, expect, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  normalizeRemoteIdentity,
+  sameRemoteIdentity,
+  claimedRemoteOf,
+  findConflictingVault,
+} from "./mirror-remote-guard.ts";
+import { writeMirrorConfigForVault, defaultMirrorConfig } from "./mirror-config.ts";
+import { writeCredentials } from "./mirror-credentials.ts";
+
+const ORIG_PARACHUTE_HOME = process.env.PARACHUTE_HOME;
+const ORIG_HOME = process.env.HOME;
+afterEach(() => {
+  if (ORIG_PARACHUTE_HOME === undefined) delete process.env.PARACHUTE_HOME;
+  else process.env.PARACHUTE_HOME = ORIG_PARACHUTE_HOME;
+  if (ORIG_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIG_HOME;
+});
+
+function tmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+/**
+ * Stand up a vault on disk under the active PARACHUTE_HOME so `listVaults()`
+ * sees it: create `data/<name>/vault.yaml`. Optionally seed an enabled
+ * internal mirror config + a mirror-dir `origin` and/or a PAT credential.
+ */
+function seedVault(
+  name: string,
+  opts: {
+    origin?: string;
+    pat?: string;
+    enabledMirror?: boolean;
+  } = {},
+): void {
+  const home = process.env.PARACHUTE_HOME!;
+  const vaultDataDir = path.join(home, "vault", "data", name);
+  fs.mkdirSync(vaultDataDir, { recursive: true });
+  // Minimal vault.yaml so listVaults() recognizes it.
+  fs.writeFileSync(path.join(vaultDataDir, "vault.yaml"), `name: ${name}\n`);
+
+  if (opts.enabledMirror !== false && (opts.origin || opts.pat)) {
+    writeMirrorConfigForVault(name, {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+    });
+  }
+
+  if (opts.origin) {
+    // Write the mirror dir's git config origin straight to disk — no git
+    // spawn needed; the guard reads `.git/config` directly.
+    const mirrorGitDir = path.join(vaultDataDir, "mirror", ".git");
+    fs.mkdirSync(mirrorGitDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(mirrorGitDir, "config"),
+      `[core]\n\trepositoryformatversion = 0\n[remote "origin"]\n\turl = ${opts.origin}\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n`,
+    );
+  }
+
+  if (opts.pat) {
+    writeCredentials(name, {
+      active_method: "pat",
+      github_oauth: null,
+      pat: { token: "ghp_seedtoken1234567890", remote_url: opts.pat, label: "seed" },
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Normalization / equivalence
+// ---------------------------------------------------------------------------
+
+describe("normalizeRemoteIdentity", () => {
+  test("https with and without .git normalize equal", () => {
+    expect(normalizeRemoteIdentity("https://github.com/x/y")).toBe("github.com/x/y");
+    expect(normalizeRemoteIdentity("https://github.com/x/y.git")).toBe("github.com/x/y");
+  });
+
+  test("trailing slash is stripped", () => {
+    expect(normalizeRemoteIdentity("https://github.com/x/y/")).toBe("github.com/x/y");
+    expect(normalizeRemoteIdentity("https://github.com/x/y.git/")).toBe("github.com/x/y");
+  });
+
+  test("host is lower-cased", () => {
+    expect(normalizeRemoteIdentity("https://GitHub.com/x/y")).toBe("github.com/x/y");
+  });
+
+  test("owner/repo is lower-cased too (GitHub is case-insensitive) — the clobber guard", () => {
+    // Aaron/Vault and aaron/vault are the SAME GitHub repo; both must normalize
+    // equal so two vaults with different-case configs are caught, not clobbered.
+    expect(normalizeRemoteIdentity("https://github.com/Aaron/Vault.git")).toBe("github.com/aaron/vault");
+    expect(normalizeRemoteIdentity("git@github.com:Aaron/Vault.git")).toBe("github.com/aaron/vault");
+  });
+
+  test("embedded userinfo (token) is stripped", () => {
+    expect(
+      normalizeRemoteIdentity("https://x-access-token:ghp_secret@github.com/x/y.git"),
+    ).toBe("github.com/x/y");
+  });
+
+  test("scp-style SSH shorthand normalizes to host/path", () => {
+    expect(normalizeRemoteIdentity("git@github.com:x/y.git")).toBe("github.com/x/y");
+  });
+
+  test("ssh:// URL normalizes to host/path", () => {
+    expect(normalizeRemoteIdentity("ssh://git@github.com/x/y.git")).toBe("github.com/x/y");
+  });
+
+  test("empty / whitespace → null", () => {
+    expect(normalizeRemoteIdentity("")).toBeNull();
+    expect(normalizeRemoteIdentity("   ")).toBeNull();
+  });
+});
+
+describe("sameRemoteIdentity — the equivalence the guard keys off", () => {
+  test("https ≡ ssh ≡ scp-shorthand ≡ .git-suffix for the same repo", () => {
+    const variants = [
+      "https://github.com/aaron/my-vault.git",
+      "https://github.com/aaron/my-vault",
+      "git@github.com:aaron/my-vault.git",
+      "ssh://git@github.com/aaron/my-vault",
+      "https://x-access-token:ghp_tok@github.com/aaron/my-vault.git",
+    ];
+    for (const a of variants) {
+      for (const b of variants) {
+        expect(sameRemoteIdentity(a, b)).toBe(true);
+      }
+    }
+  });
+
+  test("case-insensitive owner/repo: Aaron/Vault ≡ aaron/vault (the data-loss gap)", () => {
+    expect(
+      sameRemoteIdentity("https://github.com/Aaron/Vault.git", "https://github.com/aaron/vault"),
+    ).toBe(true);
+  });
+
+  test("different repos are NOT equal", () => {
+    expect(
+      sameRemoteIdentity(
+        "https://github.com/aaron/my-vault.git",
+        "https://github.com/aaron/other-vault.git",
+      ),
+    ).toBe(false);
+  });
+
+  test("different owners are NOT equal (the family-box case)", () => {
+    expect(
+      sameRemoteIdentity(
+        "https://github.com/alice/backup.git",
+        "https://github.com/bob/backup.git",
+      ),
+    ).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// claimedRemoteOf — reads both origin + PAT sources
+// ---------------------------------------------------------------------------
+
+describe("claimedRemoteOf", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("reads the mirror dir origin (covers OAuth-selected repos)", () => {
+    home = tmp("guard-claimed-origin-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", { origin: "https://github.com/aaron/my-vault.git" });
+    expect(claimedRemoteOf("a")).toBe("github.com/aaron/my-vault");
+  });
+
+  test("reads the stored PAT remote_url when no origin on disk", () => {
+    home = tmp("guard-claimed-pat-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", {
+      pat: "https://x-access-token:ghp_x@github.com/aaron/pat-vault.git",
+    });
+    expect(claimedRemoteOf("a")).toBe("github.com/aaron/pat-vault");
+  });
+
+  test("returns null for a vault with no mirror remote", () => {
+    home = tmp("guard-claimed-none-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", {});
+    expect(claimedRemoteOf("a")).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findConflictingVault — the cross-vault scan
+// ---------------------------------------------------------------------------
+
+describe("findConflictingVault", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("detects a sibling vault targeting the same repo (origin source)", () => {
+    home = tmp("guard-conflict-origin-");
+    process.env.PARACHUTE_HOME = home;
+    // Vault "a" already backs up to aaron/shared via its mirror origin.
+    seedVault("a", { origin: "https://github.com/aaron/shared.git" });
+    seedVault("b", {});
+    // Vault "b" tries to bind the SAME repo via a different URL shape.
+    const conflict = findConflictingVault("b", "git@github.com:aaron/shared.git");
+    expect(conflict).not.toBeNull();
+    expect(conflict!.conflictingVault).toBe("a");
+    expect(conflict!.remoteIdentity).toBe("github.com/aaron/shared");
+  });
+
+  test("detects a sibling vault targeting the same repo (PAT source)", () => {
+    home = tmp("guard-conflict-pat-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", {
+      pat: "https://x-access-token:ghp_a@github.com/aaron/shared.git",
+    });
+    seedVault("b", {});
+    const conflict = findConflictingVault(
+      "b",
+      "https://github.com/aaron/shared",
+    );
+    expect(conflict).not.toBeNull();
+    expect(conflict!.conflictingVault).toBe("a");
+  });
+
+  test("excludes the current vault — re-pointing to its OWN remote is allowed", () => {
+    home = tmp("guard-conflict-self-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", { origin: "https://github.com/aaron/shared.git" });
+    // Vault "a" re-binds its OWN repo (token rotation / re-pick) → no conflict.
+    const conflict = findConflictingVault("a", "https://github.com/aaron/shared.git");
+    expect(conflict).toBeNull();
+  });
+
+  test("no false positive when no sibling targets the repo", () => {
+    home = tmp("guard-conflict-clear-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", { origin: "https://github.com/aaron/vault-a.git" });
+    seedVault("b", {});
+    const conflict = findConflictingVault("b", "https://github.com/aaron/vault-b.git");
+    expect(conflict).toBeNull();
+  });
+
+  test("an empty / unparseable candidate never conflicts", () => {
+    home = tmp("guard-conflict-empty-");
+    process.env.PARACHUTE_HOME = home;
+    seedVault("a", { origin: "https://github.com/aaron/shared.git" });
+    expect(findConflictingVault("b", "")).toBeNull();
+    expect(findConflictingVault("b", "   ")).toBeNull();
+  });
+});