@openparachute/vault 0.6.0 → 0.6.2-rc.1

package/src/mirror-routes.test.ts

@@ -27,6 +27,7 @@ import {
   handleAuthGet,
   handleAuthGithubCreateRepo,
   handleAuthGithubDeviceCode,
+  handleAuthGithubInstallations,
   handleAuthGithubPoll,
   handleAuthGithubRepos,
   handleAuthGithubSelectRepo,
@@ -617,10 +618,12 @@ describe("auth credential routes — device flow", () => {
     delete process.env.PARACHUTE_GITHUB_CLIENT_ID;
   });
 
-  test("device-code returns 503 with placeholder client_id (no env override)", async () => {
+  test("device-code returns 503 when the env override is placeholder-shaped", async () => {
     home = tmp("mirror-auth-placeholder-");
     makeManager(home);
-    delete process.env.PARACHUTE_GITHUB_CLIENT_ID;
+    // A real default ships in the build, so the placeholder guard is only
+    // reachable via a misconfigured PARACHUTE_GITHUB_CLIENT_ID override.
+    process.env.PARACHUTE_GITHUB_CLIENT_ID = "Iv1.PLACEHOLDER_REPLACE_ME_BEFORE_RELEASE";
     const res = await handleAuthGithubDeviceCode();
     expect(res.status).toBe(503);
     const body = (await res.json()) as { error_type: string };
@@ -726,6 +729,12 @@ describe("auth credential routes — device flow", () => {
     expect(saved?.active_method).toBe("github_oauth");
     expect(saved?.github_oauth?.access_token).toBe("gho_real1234567890");
     expect(saved?.github_oauth?.user_login).toBe("aaron");
+    // vault#483: the grant also carries the history-on-link outcome (the
+    // dedicated branches are covered in the "history-on-link" describe).
+    expect("history_enabled" in (grantBody as Record<string, unknown>)).toBe(true);
+    // The grant may have started the mirror lifecycle (history-on-link) —
+    // tear it down so no safety-net timer outlives the test.
+    await manager.stop();
   });
 });
 
@@ -839,6 +848,19 @@ describe("auth credential routes — credential-save side-effects (Cuts 3 + 6)",
       auto_commit: false,
       auto_push: false,
     });
+    // Mirror the in-memory deps config into the REAL per-vault file:
+    // select-repo now runs maybeEnableHistoryOnLink (PR #484 fold), whose
+    // never-configured branch keys off the file's existence — without it
+    // the helper would see "never configured" and clobber this test's
+    // config with defaults.
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+      sync_mode: "manual",
+      auto_commit: false,
+      auto_push: false,
+    });
     await manager.start();
     expect(manager.getConfig().auto_push).toBe(false);
 
@@ -900,6 +922,14 @@ describe("auth credential routes — credential-save side-effects (Cuts 3 + 6)",
       enabled: false,
       auto_push: false,
     });
+    // Real file too — select-repo's history-on-link (PR #484 fold) must
+    // see this as an EXPLICIT enabled:false (left_disabled), not as a
+    // never-configured vault it should enable.
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: false,
+      auto_push: false,
+    });
     await manager.start();
     writeCredentials("default", {
       active_method: "github_oauth",
@@ -984,9 +1014,301 @@ describe("auth credential routes — github repos / create-repo", () => {
     expect(res.status).toBe(400);
   });
 
-  test("repos returns list when authed", async () => {
+  test("repos lists from the installation (vault#480) — installed:true + account annotation", async () => {
     home = tmp("mirror-auth-repos-ok-");
     const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: {
+          total_count: 1,
+          installations: [
+            {
+              id: 101,
+              app_slug: "parachute-computer",
+              account: { login: "aaron", type: "User" },
+              repository_selection: "selected",
+            },
+          ],
+        },
+      },
+      {
+        match: (u) => u.includes("/user/installations/101/repositories"),
+        body: {
+          total_count: 1,
+          repositories: [
+            {
+              name: "a",
+              full_name: "aaron/a",
+              private: true,
+              html_url: "https://github.com/aaron/a",
+              description: null,
+              updated_at: "2026-05-28T00:00:00Z",
+              clone_url: "https://github.com/aaron/a.git",
+              owner: { login: "aaron" },
+            },
+          ],
+        },
+      },
+    ]);
+    const res = await handleAuthGithubRepos(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      installed: boolean;
+      truncated: boolean;
+      repos: Array<{ full_name: string; account_login: string; installation_id: number }>;
+    };
+    expect(body.installed).toBe(true);
+    expect(body.truncated).toBe(false);
+    expect(body.repos).toHaveLength(1);
+    expect(body.repos[0]!.full_name).toBe("aaron/a");
+    expect(body.repos[0]!.account_login).toBe("aaron");
+    expect(body.repos[0]!.installation_id).toBe(101);
+  });
+
+  test("repos unions multiple installations (user + org) with per-repo annotation", async () => {
+    // The org-repos blind spot Aaron hit live: GET /user/repos?type=owner
+    // excluded org-owned repos by construction. The installations source
+    // enumerates both.
+    home = tmp("mirror-auth-repos-multi-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const repoItem = (owner: string, name: string) => ({
+      name,
+      full_name: `${owner}/${name}`,
+      private: true,
+      html_url: `https://github.com/${owner}/${name}`,
+      description: null,
+      updated_at: "2026-06-10T00:00:00Z",
+      clone_url: `https://github.com/${owner}/${name}.git`,
+      owner: { login: owner },
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: {
+          total_count: 2,
+          installations: [
+            {
+              id: 101,
+              app_slug: "parachute-computer",
+              account: { login: "aaron", type: "User" },
+              repository_selection: "selected",
+            },
+            {
+              id: 202,
+              app_slug: "parachute-computer",
+              account: { login: "unforced-org", type: "Organization" },
+              repository_selection: "selected",
+            },
+          ],
+        },
+      },
+      {
+        match: (u) => u.includes("/user/installations/101/repositories"),
+        body: { total_count: 1, repositories: [repoItem("aaron", "personal-vault")] },
+      },
+      {
+        match: (u) => u.includes("/user/installations/202/repositories"),
+        body: { total_count: 1, repositories: [repoItem("unforced-org", "team-vault")] },
+      },
+    ]);
+    const res = await handleAuthGithubRepos(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      installed: boolean;
+      repos: Array<{ full_name: string; account_login: string; installation_id: number }>;
+    };
+    expect(body.installed).toBe(true);
+    expect(body.repos).toHaveLength(2);
+    expect(body.repos[0]!.full_name).toBe("aaron/personal-vault");
+    expect(body.repos[0]!.account_login).toBe("aaron");
+    expect(body.repos[0]!.installation_id).toBe(101);
+    expect(body.repos[1]!.full_name).toBe("unforced-org/team-vault");
+    expect(body.repos[1]!.account_login).toBe("unforced-org");
+    expect(body.repos[1]!.installation_id).toBe(202);
+  });
+
+  test("repos are sorted most-recently-updated first within each account group", async () => {
+    // The installation-repositories endpoint has no `sort` param (the old
+    // GET /user/repos?sort=updated source did) — the handler sorts each
+    // group itself so the repo the operator probably wants is near the top.
+    home = tmp("mirror-auth-repos-sorted-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const repoItem = (name: string, updated_at: string) => ({
+      name,
+      full_name: `aaron/${name}`,
+      private: true,
+      html_url: `https://github.com/aaron/${name}`,
+      description: null,
+      updated_at,
+      clone_url: `https://github.com/aaron/${name}.git`,
+      owner: { login: "aaron" },
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: {
+          total_count: 1,
+          installations: [
+            {
+              id: 101,
+              app_slug: "parachute-computer",
+              account: { login: "aaron", type: "User" },
+              repository_selection: "all",
+            },
+          ],
+        },
+      },
+      {
+        match: (u) => u.includes("/user/installations/101/repositories"),
+        body: {
+          total_count: 3,
+          // Alphabetical wire order (GitHub's default) — NOT recency.
+          repositories: [
+            repoItem("alpha", "2026-01-01T00:00:00Z"),
+            repoItem("beta", "2026-06-09T00:00:00Z"),
+            repoItem("gamma", "2026-03-15T00:00:00Z"),
+          ],
+        },
+      },
+    ]);
+    const res = await handleAuthGithubRepos(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { repos: Array<{ name: string }> };
+    expect(body.repos.map((r) => r.name)).toEqual(["beta", "gamma", "alpha"]);
+  });
+
+  test("repos returns the machine-readable not_installed state when authorized but not installed", async () => {
+    home = tmp("mirror-auth-repos-notinstalled-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: { total_count: 0, installations: [] },
+      },
+    ]);
+    const res = await handleAuthGithubRepos(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      installed: boolean;
+      install_url: string;
+      repos: unknown[];
+      truncated: boolean;
+    };
+    expect(body.installed).toBe(false);
+    expect(body.install_url).toBe(
+      "https://github.com/apps/parachute-computer/installations/new",
+    );
+    expect(body.repos).toEqual([]);
+    expect(body.truncated).toBe(false);
+  });
+
+  test("repos carries truncated:true when an installation hits the page cap", async () => {
+    home = tmp("mirror-auth-repos-trunc-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    // The route calls listInstallationRepos with defaults (perPage=100,
+    // maxPages=3): serve 3 FULL pages of 100 so the cap trips.
+    const fullPage = (page: number) => ({
+      total_count: 1000,
+      repositories: Array.from({ length: 100 }, (_, i) => {
+        const n = page * 100 + i;
+        return {
+          name: `r${n}`,
+          full_name: `aaron/r${n}`,
+          private: false,
+          html_url: `https://github.com/aaron/r${n}`,
+          description: null,
+          updated_at: "2026-06-10T00:00:00Z",
+          clone_url: `https://github.com/aaron/r${n}.git`,
+          owner: { login: "aaron" },
+        };
+      }),
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: {
+          total_count: 1,
+          installations: [
+            {
+              id: 101,
+              app_slug: "parachute-computer",
+              account: { login: "aaron", type: "User" },
+              repository_selection: "all",
+            },
+          ],
+        },
+      },
+      { match: (u) => u.includes("/repositories") && u.includes("page=1"), body: fullPage(0) },
+      { match: (u) => u.includes("/repositories") && u.includes("page=2"), body: fullPage(1) },
+      { match: (u) => u.includes("/repositories") && u.includes("page=3"), body: fullPage(2) },
+    ]);
+    const res = await handleAuthGithubRepos(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { installed: boolean; truncated: boolean; repos: unknown[] };
+    expect(body.installed).toBe(true);
+    expect(body.truncated).toBe(true);
+    expect(body.repos).toHaveLength(300);
+  });
+
+  test("create-repo proxies through with mocked fetch", async () => {
+    home = tmp("mirror-auth-create-repo-");
+    const { manager } = makeManager(home);
     writeCredentials("default", {
       active_method: "github_oauth",
       github_oauth: {
@@ -1001,65 +1323,502 @@ describe("auth credential routes — github repos / create-repo", () => {
     const fetcher = buildMockFetch([
       {
         match: (u) => u.includes("/user/repos"),
-        body: [
-          {
-            name: "a",
-            full_name: "aaron/a",
-            private: true,
-            html_url: "https://github.com/aaron/a",
-            description: null,
-            updated_at: "2026-05-28T00:00:00Z",
-            clone_url: "https://github.com/aaron/a.git",
-            owner: { login: "aaron" },
-          },
-        ],
+        status: 201,
+        body: {
+          name: "new-vault",
+          full_name: "aaron/new-vault",
+          private: true,
+          html_url: "https://github.com/aaron/new-vault",
+          description: "x",
+          updated_at: "2026-05-28T00:00:00Z",
+          clone_url: "https://github.com/aaron/new-vault.git",
+          owner: { login: "aaron" },
+        },
       },
     ]);
-    const res = await handleAuthGithubRepos(manager, fetcher);
+    const req = new Request("http://x/create", {
+      method: "POST",
+      body: JSON.stringify({ name: "new-vault" }),
+    });
+    const res = await handleAuthGithubCreateRepo(req, manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { full_name: string };
+    expect(body.full_name).toBe("aaron/new-vault");
+  });
+
+  test("create-repo maps GitHub's 403 to app_lacks_admin_permission + the guided-manual path (vault#480)", async () => {
+    // Expected with the shared Contents-only app: POST /user/repos needs
+    // Administration:write. The response must be actionable + machine-
+    // readable, not a generic 502.
+    home = tmp("mirror-auth-create-repo-403-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "ghu_test1234567890",
+        scope: "",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/repos"),
+        status: 403,
+        body: { message: "Resource not accessible by integration" },
+      },
+    ]);
+    const req = new Request("http://x/create", {
+      method: "POST",
+      body: JSON.stringify({ name: "new-vault" }),
+    });
+    const res = await handleAuthGithubCreateRepo(req, manager, fetcher);
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error_type: string; message: string };
+    expect(body.error_type).toBe("app_lacks_admin_permission");
+    // Names the guided-manual path: create at github.com/new → add to the
+    // installation → refresh.
+    expect(body.message).toContain("github.com/new");
+    expect(body.message).toContain("installation");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// GET /.parachute/mirror/auth/github/installations — install state (vault#480).
+// ---------------------------------------------------------------------------
+
+describe("auth credential routes — install state (GET /auth/github/installations)", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+    delete process.env.PARACHUTE_GITHUB_CLIENT_ID;
+    delete process.env.PARACHUTE_GITHUB_APP_SLUG;
+  });
+
+  const oauthCreds = (): MirrorCredentials => ({
+    active_method: "github_oauth",
+    github_oauth: {
+      access_token: "ghu_test1234567890",
+      scope: "",
+      authorized_at: "2026-06-10T00:00:00.000Z",
+      user_login: "aaron",
+      user_id: 1,
+    },
+    pat: null,
+  });
+
+  test("400 github_not_connected when no github_oauth credential exists", async () => {
+    // 400, not 401, matching the sibling repos handler — a 401 would trip
+    // the SPA's authedFetch token-refresh machinery (clearing a valid
+    // cached admin token) over a condition that isn't an auth failure.
+    home = tmp("mirror-installstate-nocred-");
+    const { manager } = makeManager(home);
+    const res = await handleAuthGithubInstallations(manager);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error_type: string; message: string };
+    expect(body.error_type).toBe("github_not_connected");
+    expect(body.message).toContain("device flow");
+  });
+
+  test("authorized but not installed → installed:false + install_url, empty installations", async () => {
+    home = tmp("mirror-installstate-notinstalled-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", oauthCreds());
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: { total_count: 0, installations: [] },
+      },
+    ]);
+    const res = await handleAuthGithubInstallations(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      app: { client_id: string; slug: string; is_shared_default: boolean };
+      installed: boolean;
+      install_url: string;
+      installations: unknown[];
+    };
+    expect(body.installed).toBe(false);
+    expect(body.installations).toEqual([]);
+    expect(body.install_url).toBe(
+      "https://github.com/apps/parachute-computer/installations/new",
+    );
+    expect(body.app.slug).toBe("parachute-computer");
+    expect(body.app.client_id).toBe("Iv23livaRF4VcvPhu3uB");
+    expect(body.app.is_shared_default).toBe(true);
+  });
+
+  test("installed on a user account AND an org → both surfaced", async () => {
+    home = tmp("mirror-installstate-installed-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", oauthCreds());
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: {
+          total_count: 2,
+          installations: [
+            {
+              id: 101,
+              app_slug: "parachute-computer",
+              account: { login: "aaron", type: "User" },
+              repository_selection: "selected",
+            },
+            {
+              id: 202,
+              app_slug: "parachute-computer",
+              account: { login: "unforced-org", type: "Organization" },
+              repository_selection: "all",
+            },
+          ],
+        },
+      },
+    ]);
+    const res = await handleAuthGithubInstallations(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      installed: boolean;
+      installations: Array<{
+        id: number;
+        account_login: string;
+        account_type: string;
+        repository_selection: string;
+      }>;
+    };
+    expect(body.installed).toBe(true);
+    expect(body.installations).toHaveLength(2);
+    expect(body.installations[0]).toEqual({
+      id: 101,
+      account_login: "aaron",
+      account_type: "User",
+      repository_selection: "selected",
+    });
+    expect(body.installations[1]).toEqual({
+      id: 202,
+      account_login: "unforced-org",
+      account_type: "Organization",
+      repository_selection: "all",
+    });
+  });
+
+  test("BYO-app env overrides are reflected in the app block (is_shared_default false)", async () => {
+    home = tmp("mirror-installstate-byo-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", oauthCreds());
+    process.env.PARACHUTE_GITHUB_CLIENT_ID = "Iv1.byoclient";
+    process.env.PARACHUTE_GITHUB_APP_SLUG = "my-own-app";
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        body: { total_count: 0, installations: [] },
+      },
+    ]);
+    const res = await handleAuthGithubInstallations(manager, fetcher);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      app: { client_id: string; slug: string; is_shared_default: boolean };
+      install_url: string;
+    };
+    expect(body.app.client_id).toBe("Iv1.byoclient");
+    expect(body.app.slug).toBe("my-own-app");
+    expect(body.app.is_shared_default).toBe(false);
+    expect(body.install_url).toBe("https://github.com/apps/my-own-app/installations/new");
+  });
+
+  test("502 when GitHub is unreachable / errors", async () => {
+    home = tmp("mirror-installstate-apierr-");
+    const { manager } = makeManager(home);
+    writeCredentials("default", oauthCreds());
+    const fetcher = buildMockFetch([
+      {
+        match: (u) => u.includes("/user/installations?"),
+        status: 401,
+        body: { message: "Bad credentials" },
+      },
+    ]);
+    const res = await handleAuthGithubInstallations(manager, fetcher);
+    expect(res.status).toBe(502);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toBe("Installation check failed");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// vault#483 fix 1 — history-on-link (credential save enables history for a
+// never-configured vault; explicit operator choices are respected).
+//
+// Managers here are wired to the REAL per-vault mirror-config file (the
+// makeSyncManager pattern) because the never-configured branch keys off the
+// file's existence — the in-memory makeManager deps would diverge from what
+// maybeEnableHistoryOnLink reads.
+// ---------------------------------------------------------------------------
+
+describe("history-on-link (vault#483)", () => {
+  let home: string;
+  let manager: MirrorManager;
+  afterEach(async () => {
+    if (manager) await manager.stop();
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+    _resetDeviceFlowSessionsForTest();
+  });
+
+  /** Run the device flow to `granted` against a mocked GitHub. */
+  async function grantDeviceFlow(mgr: MirrorManager): Promise<{
+    state: string;
+    history_enabled: true | false | "left_disabled";
+  }> {
+    const fetchCode = buildMockFetch([
+      {
+        match: (u) => u.includes("/login/device/code"),
+        body: {
+          device_code: "dev_xyz",
+          user_code: "ABCD-1234",
+          verification_uri: "https://github.com/login/device",
+          expires_in: 900,
+          interval: 5,
+        },
+      },
+    ]);
+    const codeRes = await handleAuthGithubDeviceCode(fetchCode);
+    expect(codeRes.status).toBe(200);
+    const { polling_id } = (await codeRes.json()) as { polling_id: string };
+    const fetchGranted = buildMockFetch([
+      {
+        match: (u) => u.includes("/login/oauth/access_token"),
+        body: { access_token: "ghu_granted1234567890", scope: "", token_type: "bearer" },
+      },
+      {
+        match: (u) => u.includes("/user"),
+        body: { login: "aaron", id: 12345, name: "Aaron G" },
+      },
+    ]);
+    const grantRes = await handleAuthGithubPoll(
+      new Request("http://x/poll", { method: "POST", body: JSON.stringify({ polling_id }) }),
+      mgr,
+      fetchGranted,
+    );
+    expect(grantRes.status).toBe(200);
+    return (await grantRes.json()) as {
+      state: string;
+      history_enabled: true | false | "left_disabled";
+    };
+  }
+
+  test("device-flow grant on a never-configured vault enables history with the standard defaults", async () => {
+    home = tmp("history-link-fresh-");
+    manager = makeSyncManager(home);
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+
+    const body = await grantDeviceFlow(manager);
+    expect(body.state).toBe("granted");
+    expect(body.history_enabled).toBe(true);
+
+    // Config file now exists with the standard internal-mirror defaults.
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(true);
+    expect(cfg?.location).toBe("internal");
+    expect(cfg?.sync_mode).toBe("events");
+    expect(cfg?.auto_commit).toBe(true);
+    // auto_push stays OFF at link time — no repo picked yet; select-repo's
+    // Cut 3 flips it once a remote exists.
+    expect(cfg?.auto_push).toBe(false);
+    // And the mirror actually started.
+    expect(manager.getStatus().enabled).toBe(true);
+  });
+
+  test("device-flow grant does NOT flip an explicitly-disabled mirror; flags left_disabled", async () => {
+    home = tmp("history-link-disabled-");
+    manager = makeSyncManager(home);
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: false,
+    });
+
+    const body = await grantDeviceFlow(manager);
+    expect(body.state).toBe("granted");
+    expect(body.history_enabled).toBe("left_disabled");
+
+    // The operator's explicit choice survives untouched.
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(false);
+    expect(manager.getStatus().enabled).toBe(false);
+  });
+
+  test("device-flow grant leaves an already-enabled mirror untouched (history_enabled true)", async () => {
+    home = tmp("history-link-enabled-");
+    manager = makeSyncManager(home);
+    // Non-default field values so "untouched" is distinguishable from
+    // "rewritten with defaults."
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      sync_mode: "manual",
+      auto_commit: false,
+      safety_net_seconds: 120,
+    });
+
+    const body = await grantDeviceFlow(manager);
+    expect(body.state).toBe("granted");
+    expect(body.history_enabled).toBe(true);
+
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(true);
+    expect(cfg?.sync_mode).toBe("manual");
+    expect(cfg?.auto_commit).toBe(false);
+    expect(cfg?.safety_net_seconds).toBe(120);
+  });
+
+  test("PAT save on a never-configured vault enables history, then Cut 3 flips auto_push (remote known)", async () => {
+    home = tmp("history-link-pat-fresh-");
+    manager = makeSyncManager(home);
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+
+    // probeOverride bypasses the real `git ls-remote`; 127.0.0.1:1 keeps the
+    // post-save initial push hermetic (instant connection refusal — never a
+    // real GitHub round-trip).
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_link_test_token_123",
+          remote_url: "https://127.0.0.1:1/owner/repo.git",
+        }),
+      }),
+      manager,
+      async () => ({ ok: true }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      history_enabled: true | false | "left_disabled";
+      auto_push_enabled: boolean;
+    };
+    expect(body.history_enabled).toBe(true);
+    // PAT carries the remote, so the full chain runs: history on → Cut 3
+    // flips auto_push on the now-enabled mirror.
+    expect(body.auto_push_enabled).toBe(true);
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(true);
+    expect(cfg?.auto_push).toBe(true);
+    // No token leak.
+    expect(JSON.stringify(body)).not.toContain("ghp_link_test_token_123");
+  }, 30_000);
+
+  test("PAT save respects an explicitly-disabled mirror (left_disabled; auto_push untouched)", async () => {
+    home = tmp("history-link-pat-disabled-");
+    manager = makeSyncManager(home);
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: false,
+    });
+
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_link_test_token_456",
+          remote_url: "https://127.0.0.1:1/owner/repo.git",
+        }),
+      }),
+      manager,
+      async () => ({ ok: true }),
+    );
     expect(res.status).toBe(200);
-    const body = (await res.json()) as { repos: Array<{ full_name: string }> };
-    expect(body.repos).toHaveLength(1);
-    expect(body.repos[0]!.full_name).toBe("aaron/a");
+    const body = (await res.json()) as {
+      history_enabled: true | false | "left_disabled";
+      auto_push_enabled: boolean;
+    };
+    expect(body.history_enabled).toBe("left_disabled");
+    expect(body.auto_push_enabled).toBe(false);
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(false);
+    expect(cfg?.auto_push).toBe(false);
   });
 
-  test("create-repo proxies through with mocked fetch", async () => {
-    home = tmp("mirror-auth-create-repo-");
-    const { manager } = makeManager(home);
+  /** Seed a stored github_oauth credential — the select-repo precondition.
+   *  Models a credential saved BEFORE history-on-link existed: the operator
+   *  re-enters via "Choose repository…" without a fresh grant. */
+  function seedOauthCredential(): void {
     writeCredentials("default", {
       active_method: "github_oauth",
       github_oauth: {
-        access_token: "gho_test1234567890",
+        access_token: "gho_selectrepo1234567890",
         scope: "repo",
-        authorized_at: "2026-05-28T03:14:15.000Z",
+        authorized_at: "2026-06-10T00:00:00.000Z",
         user_login: "aaron",
         user_id: 1,
       },
       pat: null,
     });
-    const fetcher = buildMockFetch([
-      {
-        match: (u) => u.includes("/user/repos"),
-        status: 201,
-        body: {
-          name: "new-vault",
-          full_name: "aaron/new-vault",
-          private: true,
-          html_url: "https://github.com/aaron/new-vault",
-          description: "x",
-          updated_at: "2026-05-28T00:00:00Z",
-          clone_url: "https://github.com/aaron/new-vault.git",
-          owner: { login: "aaron" },
-        },
-      },
-    ]);
-    const req = new Request("http://x/create", {
-      method: "POST",
-      body: JSON.stringify({ name: "new-vault" }),
+  }
+
+  test("select-repo on a never-configured vault enables history + carries history_enabled (PR #484 fold)", async () => {
+    // The #483 re-entry gap: a credential saved pre-history-on-link on a
+    // never-configured vault. The grant/PAT paths never ran for this
+    // config, so select-repo is the first linked action — it must wire
+    // history (before auto_push, which no-ops on a disabled mirror).
+    home = tmp("history-link-selectrepo-fresh-");
+    manager = makeSyncManager(home);
+    fs.mkdirSync(path.join(home, "vault", "data", "default"), { recursive: true });
+    seedOauthCredential();
+    expect(readMirrorConfigForVault("default")).toBeUndefined();
+
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "my-vault" }),
+      }),
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      ok: boolean;
+      history_enabled: true | false | "left_disabled";
+      auto_push_enabled: boolean;
+    };
+    expect(body.ok).toBe(true);
+    expect(body.history_enabled).toBe(true);
+    // History first, so the full chain runs: enabled mirror → Cut 3 flips
+    // auto_push (the PAT handler's ordering, mirrored).
+    expect(body.auto_push_enabled).toBe(true);
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(true);
+    expect(cfg?.location).toBe("internal");
+    expect(cfg?.auto_push).toBe(true);
+    expect(manager.getStatus().enabled).toBe(true);
+    // No token leak.
+    expect(JSON.stringify(body)).not.toContain("gho_selectrepo1234567890");
+  }, 30_000);
+
+  test("select-repo respects an explicitly-disabled mirror (left_disabled; stays off)", async () => {
+    home = tmp("history-link-selectrepo-disabled-");
+    manager = makeSyncManager(home);
+    writeMirrorConfigForVault("default", {
+      ...defaultMirrorConfig(),
+      enabled: false,
     });
-    const res = await handleAuthGithubCreateRepo(req, manager, fetcher);
+    seedOauthCredential();
+
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "my-vault" }),
+      }),
+      manager,
+    );
     expect(res.status).toBe(200);
-    const body = (await res.json()) as { full_name: string };
-    expect(body.full_name).toBe("aaron/new-vault");
+    const body = (await res.json()) as {
+      history_enabled: true | false | "left_disabled";
+      auto_push_enabled: boolean;
+    };
+    // The operator's explicit choice survives — the UI gets the one-click
+    // "Turn on history now?" offer instead of a silent flip.
+    expect(body.history_enabled).toBe("left_disabled");
+    expect(body.auto_push_enabled).toBe(false);
+    const cfg = readMirrorConfigForVault("default");
+    expect(cfg?.enabled).toBe(false);
+    expect(cfg?.auto_push).toBe(false);
   });
 });
 
@@ -1636,6 +2395,108 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
     expect(creds?.pat?.remote_url).toContain("OTHER-repo.git");
   });
 
+  test("vault#482: import-sync to a repo a SIBLING vault already backs up → import succeeds but sync declined + conflict warning", async () => {
+    home = tmp("import-sync-cross-vault-");
+    await bootstrapVault(home); // creates vault "default"
+    fixture = await buildExportFixture();
+    manager = makeSyncManager(home);
+
+    // Sibling vault "family" already syncs to the repo we're importing.
+    const sibDataDir = path.join(home, "vault", "data", "family");
+    fs.mkdirSync(sibDataDir, { recursive: true });
+    fs.writeFileSync(path.join(sibDataDir, "vault.yaml"), "name: family\n");
+    writeMirrorConfigForVault("family", {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+    });
+    const sibGitDir = path.join(sibDataDir, "mirror", ".git");
+    fs.mkdirSync(sibGitDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(sibGitDir, "config"),
+      '[remote "origin"]\n\turl = https://github.com/aaron/my-vault.git\n',
+    );
+
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/aaron/my-vault.git",
+        mode: "merge",
+        credentials: { kind: "pat", token: "ghp_import_token_abc" },
+        enable_sync: true,
+      }),
+    });
+    const res = await handleMirrorImport(
+      req,
+      "default",
+      spawnCloneSuccess(fixture),
+      undefined,
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      notes_imported: number;
+      sync_enabled: boolean;
+      sync_warning?: string;
+    };
+    // Import itself never fails on the conflict.
+    expect(body.notes_imported).toBe(2);
+    // ...but sync is declined + the warning names the sibling vault + repo.
+    expect(body.sync_enabled).toBe(false);
+    expect(body.sync_warning).toContain("family");
+    expect(body.sync_warning).toContain("github.com/aaron/my-vault");
+
+    // No sync config / credential got persisted for "default".
+    expect(readMirrorConfigForVault("default")).toBeUndefined();
+    expect(readCredentials("default")).toBeNull();
+  });
+
+  test("vault#482: import-sync with override=true binds anyway despite a sibling on the same repo", async () => {
+    home = tmp("import-sync-cross-override-");
+    await bootstrapVault(home);
+    fixture = await buildExportFixture();
+    manager = makeSyncManager(home);
+
+    const sibDataDir = path.join(home, "vault", "data", "family");
+    fs.mkdirSync(sibDataDir, { recursive: true });
+    fs.writeFileSync(path.join(sibDataDir, "vault.yaml"), "name: family\n");
+    writeMirrorConfigForVault("family", {
+      ...defaultMirrorConfig(),
+      enabled: true,
+      location: "internal",
+    });
+    const sibGitDir = path.join(sibDataDir, "mirror", ".git");
+    fs.mkdirSync(sibGitDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(sibGitDir, "config"),
+      '[remote "origin"]\n\turl = https://github.com/aaron/my-vault.git\n',
+    );
+
+    const req = new Request("http://x/import", {
+      method: "POST",
+      body: JSON.stringify({
+        remote_url: "https://github.com/aaron/my-vault.git",
+        mode: "merge",
+        credentials: { kind: "pat", token: "ghp_import_token_abc" },
+        enable_sync: true,
+        override: true,
+      }),
+    });
+    const res = await handleMirrorImport(
+      req,
+      "default",
+      spawnCloneSuccess(fixture),
+      undefined,
+      manager,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { sync_enabled: boolean };
+    expect(body.sync_enabled).toBe(true);
+    // Sync config + credential persisted for "default" despite the sibling.
+    expect(readMirrorConfigForVault("default")?.auto_push).toBe(true);
+    expect(readCredentials("default")?.pat?.token).toBe("ghp_import_token_abc");
+  });
+
   test("existing mirror to the SAME remote → no-op success (sync_enabled true)", async () => {
     home = tmp("import-sync-same-");
     await bootstrapVault(home);
@@ -1796,3 +2657,214 @@ describe("handleMirrorImport — auto-enable sync (vault#416)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// vault#482 — cross-vault remote-clobber guard at the ROUTE level.
+//
+// Two vaults on one server pointing their mirror at the same repo force-push
+// over each other's backups (silent data loss). The guard refuses a bind
+// (PAT save / OAuth repo pick / import-then-sync) when a SIBLING vault already
+// claims the same normalized remote, unless `override: true`. Re-binding a
+// vault to its OWN remote is always allowed (no false positive).
+// ---------------------------------------------------------------------------
+
+/**
+ * Seed a sibling vault on disk under the active PARACHUTE_HOME so
+ * `listVaults()` sees it, with an enabled internal mirror whose `origin`
+ * points at `originUrl`. No git spawn — we write `.git/config` directly,
+ * exactly what the guard reads.
+ */
+function seedSiblingVault(name: string, originUrl: string): void {
+  const home = process.env.PARACHUTE_HOME!;
+  const dataDir = path.join(home, "vault", "data", name);
+  fs.mkdirSync(dataDir, { recursive: true });
+  fs.writeFileSync(path.join(dataDir, "vault.yaml"), `name: ${name}\n`);
+  writeMirrorConfigForVault(name, {
+    ...defaultMirrorConfig(),
+    enabled: true,
+    location: "internal",
+  });
+  const mirrorGitDir = path.join(dataDir, "mirror", ".git");
+  fs.mkdirSync(mirrorGitDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(mirrorGitDir, "config"),
+    `[remote "origin"]\n\turl = ${originUrl}\n`,
+  );
+}
+
+describe("cross-vault remote-clobber guard (vault#482)", () => {
+  let home: string;
+  afterEach(() => {
+    if (home) fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  test("PAT: a second vault targeting a sibling's repo is refused with 409 + helpful error", async () => {
+    home = tmp("guard-pat-refuse-");
+    const { manager } = makeManager(home); // vault "default"
+    // Sibling vault "family" already backs up to aaron/shared.
+    seedSiblingVault("family", "https://github.com/aaron/shared.git");
+
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_newtoken1234567890",
+          remote_url: "https://github.com/aaron/shared.git",
+        }),
+      }),
+      manager,
+      // Probe stub — the conflict guard runs AFTER the probe, so the probe
+      // must pass for us to reach (and assert on) the guard.
+      async () => ({ ok: true }),
+    );
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as {
+      error_type: string;
+      conflicting_vault: string;
+      remote: string;
+      message: string;
+    };
+    expect(body.error_type).toBe("remote_conflict");
+    expect(body.conflicting_vault).toBe("family");
+    expect(body.remote).toBe("github.com/aaron/shared");
+    // Names the vault + repo + tells the operator how to proceed.
+    expect(body.message).toContain("family");
+    expect(body.message).toContain("github.com/aaron/shared");
+    expect(body.message).toContain("override");
+    // Nothing got persisted for the refused vault.
+    expect(readCredentials("default")).toBeNull();
+  });
+
+  test("PAT: URL-normalization — sibling stored as scp-shorthand, candidate https → recognized as same repo", async () => {
+    home = tmp("guard-pat-norm-");
+    const { manager } = makeManager(home);
+    // Sibling stored its origin as SSH scp-shorthand.
+    seedSiblingVault("family", "git@github.com:aaron/shared.git");
+
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_newtoken1234567890",
+          // ...candidate arrives as HTTPS without .git.
+          remote_url: "https://github.com/aaron/shared",
+        }),
+      }),
+      manager,
+      async () => ({ ok: true }),
+    );
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { conflicting_vault: string };
+    expect(body.conflicting_vault).toBe("family");
+  });
+
+  test("PAT: re-pointing the SAME vault at its OWN remote is allowed (no false positive)", async () => {
+    home = tmp("guard-pat-self-");
+    const { manager } = makeManager(home); // vault "default"
+    // "default" already targets aaron/mine (its own origin) + a sibling
+    // targets a DIFFERENT repo — neither should block a self re-bind.
+    seedSiblingVault("default", "https://github.com/aaron/mine.git");
+    seedSiblingVault("family", "https://github.com/aaron/theirs.git");
+
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_rotated1234567890",
+          // Same repo "default" already points at — token rotation.
+          remote_url: "https://github.com/aaron/mine.git",
+        }),
+      }),
+      manager,
+      async () => ({ ok: true }),
+    );
+    expect(res.status).toBe(200);
+    const creds = readCredentials("default");
+    expect(creds?.active_method).toBe("pat");
+    expect(creds?.pat?.remote_url).toContain("github.com/aaron/mine.git");
+  });
+
+  test("PAT: override=true bypasses the guard and saves anyway", async () => {
+    home = tmp("guard-pat-override-");
+    const { manager } = makeManager(home);
+    seedSiblingVault("family", "https://github.com/aaron/shared.git");
+
+    const res = await handleAuthPat(
+      new Request("http://x/pat", {
+        method: "POST",
+        body: JSON.stringify({
+          token: "ghp_newtoken1234567890",
+          remote_url: "https://github.com/aaron/shared.git",
+          override: true,
+        }),
+      }),
+      manager,
+      async () => ({ ok: true }),
+    );
+    expect(res.status).toBe(200);
+    expect(readCredentials("default")?.active_method).toBe("pat");
+  });
+
+  test("select-repo: picking a sibling's repo is refused with 409", async () => {
+    home = tmp("guard-selectrepo-refuse-");
+    const { manager } = makeManager(home);
+    seedSiblingVault("family", "https://github.com/aaron/shared.git");
+    // "default" has an OAuth credential (select-repo requires one).
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_fake1234567890abcd",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "shared" }),
+      }),
+      manager,
+    );
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as {
+      error_type: string;
+      conflicting_vault: string;
+    };
+    expect(body.error_type).toBe("remote_conflict");
+    expect(body.conflicting_vault).toBe("family");
+  });
+
+  test("select-repo: override=true bypasses the guard", async () => {
+    home = tmp("guard-selectrepo-override-");
+    const { manager } = makeManager(home);
+    seedSiblingVault("family", "https://github.com/aaron/shared.git");
+    writeCredentials("default", {
+      active_method: "github_oauth",
+      github_oauth: {
+        access_token: "gho_fake1234567890abcd",
+        scope: "repo",
+        authorized_at: "2026-05-28T03:14:15.000Z",
+        user_login: "aaron",
+        user_id: 1,
+      },
+      pat: null,
+    });
+    const res = await handleAuthGithubSelectRepo(
+      new Request("http://x/select", {
+        method: "POST",
+        body: JSON.stringify({ owner: "aaron", name: "shared", override: true }),
+      }),
+      manager,
+    );
+    // 200 (or any non-409) — the guard didn't block it. (mirror_path is
+    // unresolved since the manager never started, so it stores creds + returns
+    // ok without applying to a remote.)
+    expect(res.status).not.toBe(409);
+    const body = (await res.json()) as { ok?: boolean };
+    expect(body.ok).toBe(true);
+  });
+});
+