fix(oauth): register legacy recovery backups for owned cleanup

src/oauth/store.ts

@@ -437,6 +437,12 @@ function backupLegacyOnce(): void {
   try {
     copyFileSync(path, backup);
     try { chmodSync(backup, 0o600); } catch { /* best-effort */ }
+    try {
+      // Register only the copy we just created. An unowned home still needs downgrade recovery.
+      recordOwnedConfigPath(getConfigDir(), backup);
+    } catch {
+      console.warn("[oauth] Recovery backup created, but uninstall ownership registration failed.");
+    }
   } catch { /* best-effort */ }
 }
 

structure/config.md

@@ -244,6 +244,16 @@ and removes only normalized manifest entries. Manifest-owned directory links are
 traversing their targets. Unknown files remain in place and make the command report a partial
 uninstall with their exact paths.
 
+The newly created OAuth downgrade copy is registered after copying, so owned uninstall
+includes it. Invalid-config recovery copies are deliberately NOT registered: their names carry
+a timestamp, so one entry per invalid load would grow the uninstall manifest without bound, and
+the manifest stops validating past its path ceiling. A manifest that stops validating makes
+uninstall refuse outright, which would leave credentials on disk. Sweeping those copies by name
+pattern at removal time is the shape that fits; it is not in this change. Registration is best-effort: an intentionally
+unowned legacy home or a metadata-write failure must not suppress the recovery copy. Existing
+OAuth downgrade copies are neither rewritten nor retroactively claimed. Unregistered copies
+remain subject to the existing partial/refused uninstall result.
+
 Legacy nonempty config directories are deliberately not retroactively claimed. If either ownership
 file is missing, malformed, or bound to another root, uninstall refuses config deletion and reports
 the residual directory for manual review; there is no recursive-delete fallback.

structure/overview.md

@@ -47,7 +47,8 @@ preserves saved user model selections and historical usage. See the bounded
 installed service resolve it the same way (`src/config.ts`). Ownership inside that root is tracked
 by the uninstall manifest in `src/lib/config-ownership.ts`, which starts from a declared path list
 and grows as opencodex claims further paths at runtime — so the manifest, not this table, is what
-bounds uninstall. This table groups the state by purpose; it is not an exhaustive file list, and
+bounds uninstall. Newly generated recovery backups follow the [backup ownership contract](config.md#restore)
+without suppressing recovery when registration is unavailable. This table groups state by purpose; it is not an exhaustive file list, and
 derived files such as `auth.json.pre-multiauth` are covered by the group they belong to.
 
 `$CODEX_HOME` is a separate root with a separate owner, and opencodex writes there too: removing the

structure/providers/xai-grok.md

@@ -38,6 +38,8 @@ The shared Responses path follows the [bounded multipart recovery contract](../s
   `auth.json` load-merge-persist (`src/oauth/store.ts`); generation-guarded persist
   (`expectedGeneration` → superseded adoption), conditional `needsReauth`, bounded jittered
   retry for transient token-endpoint failures.
+  Newly created legacy-store recovery copies follow the [backup ownership contract](../config.md#restore);
+  an ownership-registration failure does not discard downgrade recovery.
 - **Reactive 401 replay:** both the adapter recovery loop and native Responses passthrough branch
   force-refresh once (singleflight, generation-checked) and replay OAuth-backed xAI requests
   exactly once with a re-resolved transport; API-key/BYOK paths are excluded

tests/oauth/oauth-store-multi.test.ts

@@ -36,6 +36,7 @@ import {
 } from "../../src/oauth/store";
 import type { OAuthCredentials } from "../../src/oauth/types";
 import { removeTreeWithRetry } from "../helpers/remove-tree";
+import { recordOwnedConfigPath, removeOwnedConfigState } from "../../src/lib/config-ownership";
 
 const TEST_DIR = join(import.meta.dir, ".tmp-oauth-store-multi-test");
 let previousOpencodexHome: string | undefined;
@@ -152,6 +153,41 @@ describe("multi-account auth store", () => {
     expect(existsSync(`${authPath}.pre-multiauth`)).toBe(true);
   });
 
+  test("uninstall removes a legacy recovery backup from an owned home", async () => {
+    const dir = join(TEST_DIR, "owned");
+    const path = join(dir, "auth.json");
+    process.env.OPENCODEX_HOME = dir;
+    try {
+      expect(recordOwnedConfigPath(dir, path)).toBe(true);
+      const original = JSON.stringify({ xai: cred({ email: "old@example.test" }) });
+      writeFileSync(path, original);
+      await saveCredential("xai", cred({ email: "old@example.test", access: "new-access" }));
+      expect(readFileSync(`${path}.pre-multiauth`, "utf8")).toBe(original);
+      await flushConfigDirHardeningForTests();
+      expect(removeOwnedConfigState(dir).status).toBe("removed");
+      expect(existsSync(`${path}.pre-multiauth`)).toBe(false);
+    } finally {
+      process.env.OPENCODEX_HOME = TEST_DIR;
+    }
+  });
+
+  test("migration leaves a pre-existing unregistered backup unchanged and unclaimed", async () => {
+    const dir = join(TEST_DIR, "existing-backup");
+    const path = join(dir, "auth.json");
+    process.env.OPENCODEX_HOME = dir;
+    try {
+      expect(recordOwnedConfigPath(dir, path)).toBe(true);
+      writeFileSync(path, JSON.stringify({ xai: cred({ email: "old@example.test" }) }));
+      writeFileSync(`${path}.pre-multiauth`, "prior-recovery-fixture");
+      await saveCredential("xai", cred({ email: "old@example.test" }));
+      await flushConfigDirHardeningForTests();
+      expect(removeOwnedConfigState(dir).status).toBe("partial");
+      expect(readFileSync(`${path}.pre-multiauth`, "utf8")).toBe("prior-recovery-fixture");
+    } finally {
+      process.env.OPENCODEX_HOME = TEST_DIR;
+    }
+  });
+
   test("legacy credential WITHOUT identity gets a deterministic account id across loads", async () => {
     // Legacy stores are re-normalized on EVERY load without being persisted, so the
     // derived id must be stable: a time-salted id would make getAccountSet and