Sweep orphaned Xata branches in the cleanup cron

The nightly cleanup only deleted branches still tracked by a userBranch
row. Branches orphaned in Xata — delete failures swallowed on the user
path after the row was removed, or a crash between createBranch and the
row insert — were never revisited and lingered indefinitely.

Add an orphan sweep to cleanupIdleBranches: delete any branch that is
not the parent (main), not a tpl-* template, and not referenced by a
userBranch row, with a one-hour createdAt grace period so an in-flight
create is never swept mid-provisioning.

Also make the manual scripts/xata-cleanup.ts keep tpl-* templates
instead of deleting everything except main.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: exekias

lib/branch-manager.ts

@@ -474,6 +474,7 @@ export type CleanupResult = {
   dropped: number;
   errors: { branchId: string; message: string }[];
   templates: { scanned: number; dropped: number };
+  orphans: { scanned: number; dropped: number };
 };
 
 /**
@@ -519,10 +520,57 @@ async function pruneStaleTemplates(
   return { scanned: templates.length, dropped };
 }
 
+// Untracked branches younger than this are skipped: an in-flight
+// ensureBranchForLesson creates the Xata branch up to ~2 minutes before the
+// userBranch row lands, and must not be swept mid-create.
+const ORPHAN_GRACE_MS = 60 * 60 * 1000;
+
+/**
+ * Delete orphaned Xata branches: anything that isn't the parent (`main`), a
+ * `tpl-*` template (owned by pruneStaleTemplates), or referenced by a
+ * `userBranch` row. Orphans accumulate when a delete fails after its row was
+ * removed (delete errors are deliberately swallowed on the user path) or when
+ * a create dies between createBranch and the row insert — the row-driven idle
+ * pass never sees them again.
+ */
+async function sweepOrphanBranches(
+  errors: { branchId: string; message: string }[],
+): Promise<{ scanned: number; dropped: number }> {
+  const parentId = await getParentBranchId();
+  const parentName = process.env.XATA_PARENT_BRANCH ?? "main";
+  const trackedRows = await db
+    .select({ id: userBranch.xataBranchId })
+    .from(userBranch);
+  const tracked = new Set(trackedRows.map((r) => r.id));
+
+  const branches = await listBranches();
+  const cutoff = Date.now() - ORPHAN_GRACE_MS;
+
+  let scanned = 0;
+  let dropped = 0;
+  for (const b of branches) {
+    if (b.id === parentId || b.name === parentName) continue;
+    if (b.name.startsWith("tpl-")) continue;
+    if (tracked.has(b.id)) continue;
+    scanned++;
+    const createdAt = Date.parse(b.createdAt);
+    if (!Number.isFinite(createdAt) || createdAt > cutoff) continue;
+    try {
+      await deleteBranch(b.id);
+      console.log(`[cleanup] dropped orphan branch ${b.id} (${b.name})`);
+      dropped++;
+    } catch (err) {
+      errors.push({ branchId: b.id, message: (err as Error).message });
+    }
+  }
+  return { scanned, dropped };
+}
+
 /**
  * Cron-driven cleanup: drop user branches that haven't been touched in
- * `idleDays`, then prune template branches no longer referenced by any lesson
- * or live user branch.
+ * `idleDays`, prune template branches no longer referenced by any lesson or
+ * live user branch, then sweep orphaned branches Xata knows about but the
+ * local DB doesn't.
  */
 export async function cleanupIdleBranches(
   idleDays = 7,
@@ -538,6 +586,7 @@ export async function cleanupIdleBranches(
     dropped: 0,
     errors: [],
     templates: { scanned: 0, dropped: 0 },
+    orphans: { scanned: 0, dropped: 0 },
   };
 
   for (const row of idle) {
@@ -570,5 +619,14 @@ export async function cleanupIdleBranches(
     });
   }
 
+  try {
+    result.orphans = await sweepOrphanBranches(result.errors);
+  } catch (err) {
+    result.errors.push({
+      branchId: "<orphan-sweep>",
+      message: (err as Error).message,
+    });
+  }
+
   return result;
 }

scripts/xata-cleanup.ts

@@ -4,7 +4,7 @@
  *
  * Usage:
  *   npx tsx scripts/xata-cleanup.ts          # dry-run; lists what would be deleted
- *   npx tsx scripts/xata-cleanup.ts --force  # actually delete every branch except main
+ *   npx tsx scripts/xata-cleanup.ts --force  # delete every branch except main and tpl-* templates
  *
  * Standalone — doesn't import lib/xata.ts (which uses next/server-only and
  * can't be loaded outside the Next build).
@@ -69,12 +69,14 @@ async function main() {
     (noParent.length === 1 ? noParent[0] : undefined) ??
     branches.find((b) => referencedParents.has(b.id));
 
+  const keep = (b: Branch) =>
+    (parent && b.id === parent.id) || b.name.startsWith("tpl-");
+
   console.log(
     `Project ${projectId} has ${branches.length} branch(es).\n`,
   );
   for (const b of branches) {
-    const isParent = parent && b.id === parent.id;
-    const tag = isParent ? "  KEEP" : "DELETE";
+    const tag = keep(b) ? "  KEEP" : "DELETE";
     console.log(
       `  [${tag}] ${b.id}  ${b.name}  parent=${b.parentID ?? "(none)"}`,
     );
@@ -92,7 +94,7 @@ async function main() {
 
   console.log(`\nParent (kept): ${parent.name} [${parent.id}]`);
 
-  const toDelete = branches.filter((b) => b.id !== parent.id);
+  const toDelete = branches.filter((b) => !keep(b));
   if (toDelete.length === 0) {
     console.log("\nNothing to delete.");
     return;