@databricks-solutions/lakebase-scm-utils 0.3.10 → 0.3.12

package/dist/scripts/lakebase/scm-reconcile-tier.cli.js

@@ -389,8 +389,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.12".length > 0) {
+    cached = "0.3.12";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.cjs

@@ -1667,8 +1667,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.12".length > 0) {
+    cached = "0.3.12";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/util/index.js

@@ -1630,8 +1630,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.3.10".length > 0) {
-    cached = "0.3.10";
+  if ("0.3.12".length > 0) {
+    cached = "0.3.12";
     return cached;
   }
   cached = "unknown";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.3.10",
+  "version": "0.3.12",
   "description": "Lakebase SCM + substrate engine: database branching, paired-branch SCM workflows, connection/credential minting, schema migration, project scaffold + deploy primitives, and the git/github utility layer. Extracted from consort for portable, standalone consumption by lakebase-scm-extension and the SFTDD orchestration.",
   "type": "module",
   "private": false,

package/scripts/git/commit-push.ts

@@ -45,24 +45,70 @@ export class WorkflowScopeError extends Error {
  * For non-initial-commit flows, prefer the primitives in ./commits.ts.
  */
 export async function commitAndPush(args: CommitAndPushArgs): Promise<void> {
-  await exec("git add -A", { cwd: args.projectDir });
-  await exec(`git commit -m ${JSON.stringify(args.message)}`, {
-    cwd: args.projectDir,
+  await commitInitial(args.projectDir, args.message);
+  if (args.push === false) return;
+  await pushInitial({ projectDir: args.projectDir, remote: args.remote, branch: args.branch });
+}
+
+/** Stage everything and make the initial commit (no push). */
+export async function commitInitial(projectDir: string, message: string): Promise<void> {
+  await exec("git add -A", { cwd: projectDir });
+  await exec(`git commit -m ${JSON.stringify(message)}`, {
+    cwd: projectDir,
     timeout: 30_000,
   });
-  if (args.push === false) return;
+}
+
+export interface PushInitialArgs {
+  projectDir: string;
+  /** Remote name. Default: "origin". */
+  remote?: string;
+  /** Branch name. Default: "main". */
+  branch?: string;
+  /**
+   * Total push attempts (>= 1). Default 1 (preserves commitAndPush's behavior).
+   * The create flow passes 2: the FIRST push fires the project's pre-push hook,
+   * which triggers the one-time cold download of the Consort toolkit — that race
+   * can fail the push, but the toolkit is CACHED afterward, so a single retry then
+   * sails through (the cold-download incident). A `workflow`-scope rejection is a
+   * real auth gap, never retried.
+   */
+  attempts?: number;
+  /** Delay between attempts (ms). Default 1500. Injected in tests. */
+  delayMs?: number;
+  /** Injectable sleep (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable runner (tests); defaults to the real `git push`. */
+  run?: (cmd: string, cwd: string) => Promise<void>;
+}
+
+/**
+ * Push the initial branch with `-u`, retrying a transient failure up to
+ * `attempts` times. Maps the GitHub `workflow`-scope rejection to
+ * {@link WorkflowScopeError} (thrown immediately, never retried). Throws the last
+ * error after the final attempt.
+ */
+export async function pushInitial(args: PushInitialArgs): Promise<void> {
   const remote = args.remote ?? "origin";
   const branch = args.branch ?? "main";
-  try {
-    await exec(`git push -u ${remote} ${branch}`, {
-      cwd: args.projectDir,
-      timeout: 30_000,
-    });
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
-      throw new WorkflowScopeError(args.projectDir);
+  const attempts = Math.max(1, args.attempts ?? 1);
+  const sleep = args.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const run =
+    args.run ??
+    ((cmd: string, cwd: string) => exec(cmd, { cwd, timeout: 30_000 }).then(() => undefined));
+  let lastErr: unknown;
+  for (let i = 1; i <= attempts; i++) {
+    try {
+      await run(`git push -u ${remote} ${branch}`, args.projectDir);
+      return;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (/without `?workflow`? scope|workflow scope/i.test(msg)) {
+        throw new WorkflowScopeError(args.projectDir);
+      }
+      lastErr = err;
+      if (i < attempts) await sleep(args.delayMs ?? 1500);
     }
-    throw err;
   }
+  throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
 }

package/scripts/lakebase/create-preflight.ts

@@ -19,7 +19,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { deleteLakebaseProject } from "./lakebase-project.js";
 import { runDatabricks } from "./databricks-cli.js";
-import { checkGitHubScopes } from "../github/repo.js";
+import { checkGitHubScopes, getCurrentUser, repoExists, type GitHubScopeStatus } from "../github/repo.js";
 
 export interface PreflightResult {
   ok: boolean;
@@ -145,6 +145,134 @@ export async function checkGitHubWorkflowScope(
   }
 }
 
+export interface GitHubPreflightInput {
+  /** Target repo owner (user or org). */
+  owner: string;
+  /** Bare repo name (the project name). */
+  repoName: string;
+  /** Scopes whose absence BLOCKS the happy path (create + push). Default ["repo","workflow"]. */
+  hardScopes?: readonly string[];
+  /** Scopes whose absence only WARNS (e.g. delete_repo, needed for rollback repo-delete). Default ["delete_repo"]. */
+  advisoryScopes?: readonly string[];
+  /** Injected probes (default to the real GitHub reads). */
+  currentUser?: () => Promise<string>;
+  scopes?: (required: readonly string[]) => Promise<GitHubScopeStatus>;
+  repoExists?: (fullName: string) => Promise<boolean>;
+}
+
+export interface GitHubPreflightResult extends PreflightResult {
+  /** Non-blocking notes (org/owner mismatch, missing advisory scope, invisible scopes). */
+  warnings: string[];
+  /** The resolved authenticated login, when B1 succeeded. */
+  activeUser?: string;
+}
+
+/**
+ * One up-front GitHub preflight run BEFORE any repo / Lakebase project is created,
+ * so a missing requisite fails in seconds with a fix instead of mid-create (where
+ * it orphans partially-created artifacts). Supersedes the workflow-only check:
+ *
+ *   B1  active account   getCurrentUser() must resolve (a valid token) — else a
+ *                        wrong/absent token otherwise 403s LATE at the push.
+ *   B2  scope set        checkGitHubScopes([...hard, ...advisory]): a missing HARD
+ *                        scope (repo/workflow) fails; a missing ADVISORY scope
+ *                        (delete_repo) warns (rollback repo-delete unavailable);
+ *                        granted null (fine-grained PAT / App) can't be asserted.
+ *   B3  name availability  repoExists(owner/name) → fail before anything exists.
+ *   B4  owner note       login != owner ⇒ creating under an org/other account —
+ *                        surfaced (createRepo enforces the real org-create right).
+ *
+ * CONSERVATIVE: hard-fails ONLY on the clear blockers (invalid token, missing
+ * happy-path scope, name taken); every other uncertainty is a warning, never a
+ * false block (same ethos as checkGitHubWorkflowScope). All probes injected, so
+ * this is unit-testable with no network.
+ */
+export async function checkGitHubPreflight(input: GitHubPreflightInput): Promise<GitHubPreflightResult> {
+  const warnings: string[] = [];
+  const hard = input.hardScopes ?? ["repo", "workflow"];
+  const advisory = input.advisoryScopes ?? ["delete_repo"];
+  const currentUserProbe = input.currentUser ?? getCurrentUser;
+  const scopesProbe = input.scopes ?? ((req: readonly string[]) => checkGitHubScopes(req));
+  const repoExistsProbe = input.repoExists ?? repoExists;
+
+  // B1: active account — a valid token. Hard blocker; nothing downstream works without it.
+  let activeUser: string;
+  try {
+    activeUser = await currentUserProbe();
+  } catch (err) {
+    return {
+      ok: false,
+      warnings,
+      reason:
+        `GitHub authentication failed: ${err instanceof Error ? err.message : String(err)}. ` +
+        "Sign in with `gh auth login`, or set GITHUB_TOKEN to a valid token, then re-run.",
+    };
+  }
+
+  // B4 (note): a login different from the owner means an org (or another account).
+  // Not a hard block — createRepo surfaces the real org-create permission — but
+  // surface it so a wrong active account is visible BEFORE the push's late 403.
+  if (activeUser.toLowerCase() !== input.owner.toLowerCase()) {
+    warnings.push(
+      `Signed in to GitHub as "${activeUser}" but creating under "${input.owner}" (an org or another account); ` +
+        `ensure "${activeUser}" can create repositories there.`,
+    );
+  }
+
+  // B2: the full required scope set — not just `workflow`.
+  try {
+    const { granted, missing } = await scopesProbe([...hard, ...advisory]);
+    if (granted !== null) {
+      const missingHard = missing.filter((s) => hard.includes(s));
+      const missingAdvisory = missing.filter((s) => advisory.includes(s));
+      if (missingHard.length > 0) {
+        return {
+          ok: false,
+          warnings,
+          activeUser,
+          reason:
+            `GitHub token missing required scope(s): ${missingHard.join(", ")} ` +
+            `(grants [${granted.join(", ") || "none"}]). Fix: gh auth refresh -h github.com -s ${[...hard].join(",")}`,
+        };
+      }
+      if (missingAdvisory.length > 0) {
+        warnings.push(
+          `GitHub token missing the ${missingAdvisory.join(", ")} scope — automatic rollback of the repo on a failed ` +
+            "create is unavailable (you would delete it by hand). Grant it with: gh auth refresh -h github.com -s delete_repo",
+        );
+      }
+    } else {
+      warnings.push(
+        "GitHub token scopes are not visible (fine-grained PAT or App token); cannot pre-verify repo/workflow access , " +
+          "the create will surface any gap when it pushes.",
+      );
+    }
+  } catch {
+    warnings.push("Could not read GitHub token scopes (probe error); skipping the scope pre-check.");
+  }
+
+  // B3: name availability — fail before anything is created.
+  try {
+    if (await repoExistsProbe(`${input.owner}/${input.repoName}`)) {
+      return {
+        ok: false,
+        warnings,
+        activeUser,
+        reason:
+          `GitHub repo "${input.owner}/${input.repoName}" already exists. ` +
+          "Pick a different project name, or delete the existing repo first.",
+      };
+    }
+  } catch {
+    warnings.push(
+      `Could not check whether "${input.owner}/${input.repoName}" already exists (probe error); ` +
+        "the create will fail clearly if it does.",
+    );
+  }
+
+  return { ok: true, warnings, activeUser };
+}
+
 /** The actionable prereq message for a GitHub token missing the `workflow` scope. */
 export function githubWorkflowScopePrereqMessage(reason?: string): string {
   return (
@@ -258,3 +386,87 @@ export async function withLakebaseRollback<T>(opts: RollbackOptions, fn: () => P
     throw wrapped;
   }
 }
+
+export interface RollbackStep {
+  label: string;
+  undo: () => Promise<void> | void;
+}
+
+export interface RollbackLedger {
+  /** Record a teardown for a resource the moment it is created. */
+  register(label: string, undo: () => Promise<void> | void): void;
+  /** The steps, in registration order (teardown runs them REVERSED). */
+  steps(): readonly RollbackStep[];
+}
+
+/** A created-resources ledger for the full create flow (A3). */
+export function createRollbackLedger(): RollbackLedger {
+  const steps: RollbackStep[] = [];
+  return {
+    register: (label, undo) => {
+      steps.push({ label, undo });
+    },
+    steps: () => steps,
+  };
+}
+
+export interface CreateRollbackOptions {
+  report?: (step: string, detail?: string) => void;
+}
+
+/**
+ * A3: run `fn`; on a throw, tear down EVERY resource the ledger recorded, in
+ * REVERSE order (last-created first), then rethrow with a summary of what was
+ * and wasn't cleaned up.
+ *
+ * Unlike {@link withLakebaseRollback} (Lakebase project only), this undoes the
+ * GitHub repo, the self-hosted runner, the local dir, AND the Lakebase project
+ * together — so a genuine provisioning fault leaves a clean "name is free" state
+ * instead of orphaning three of the four artifacts (the exact 4-artifact manual
+ * cleanup the cold-download incident caused). A step's own failure is captured +
+ * reported, never thrown, so one stuck teardown can't block the others; a
+ * "not found" teardown counts as already-gone. The caller registers a step the
+ * instant each resource is created, so a failure anywhere inside `fn` rolls back
+ * exactly what existed at that point.
+ */
+export async function withCreateRollback<T>(
+  ledger: RollbackLedger,
+  opts: CreateRollbackOptions,
+  fn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    const report = opts.report ?? (() => {});
+    const steps = [...ledger.steps()].reverse();
+    const rolledBack: string[] = [];
+    const failed: string[] = [];
+    if (steps.length > 0) report(`Create failed; rolling back ${steps.length} created resource(s)...`);
+    for (const s of steps) {
+      try {
+        report(`  rolling back: ${s.label}`);
+        await s.undo();
+        rolledBack.push(s.label);
+      } catch (e) {
+        const m = e instanceof Error ? e.message : String(e);
+        if (/not.?found/i.test(m)) {
+          rolledBack.push(s.label);
+          continue;
+        }
+        failed.push(`${s.label} (${m})`);
+      }
+    }
+    const base = err instanceof Error ? err.message : String(err);
+    const parts: string[] = [];
+    if (rolledBack.length) parts.push(`rolled back: ${rolledBack.join(", ")}`);
+    if (failed.length) {
+      parts.push(
+        `COULD NOT roll back: ${failed.join("; ")} , clean these up by hand before retrying the same name`,
+      );
+    }
+    const suffix = parts.length ? ` (${parts.join("; ")})` : "";
+    const wrapped = err instanceof Error ? err : new Error(base);
+    wrapped.message = `${base}${suffix}`;
+    throw wrapped;
+  }
+}

package/scripts/lakebase/create-project.ts

@@ -9,20 +9,23 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { writeEnvFile } from "./env-file.js";
 import { verifyProject, verifyHooks, verifyWorkflows } from "./project-verify.js";
-import { createRepo, getRepoFullName, getCurrentUser } from "../github/repo.js";
+import { createRepo, getRepoFullName, getCurrentUser, deleteRepo } from "../github/repo.js";
 import { cloneRepo } from "../git/clone.js";
 import { gitInit } from "../git/init.js";
-import { commitAndPush } from "../git/commit-push.js";
+import { commitInitial, pushInitial, WorkflowScopeError } from "../git/commit-push.js";
 import {
   createLakebaseProject,
   getDefaultBranchId,
+  deleteLakebaseProject,
 } from "./lakebase-project.js";
 import {
   checkDatabricksAuth,
   databricksAuthPrereqMessage,
-  checkGitHubWorkflowScope,
-  githubWorkflowScopePrereqMessage,
-  withLakebaseRollback,
+  checkGitHubPreflight,
+  warmAndVerifyKit,
+  kitWarmWarning,
+  createRollbackLedger,
+  withCreateRollback,
   validateCreateInputs,
   dirIsEmpty,
 } from "./create-preflight.js";
@@ -32,7 +35,7 @@ import { createLongRunningBranch } from "./long-running-branch.js";
 import { enableE2eForProject } from "./enable-e2e.js";
 import { ensureClientLockfile } from "./client-lockfile.js";
 import { enableInfraForProject } from "./enable-infra.js";
-import { setupRunner } from "./runner-setup.js";
+import { setupRunner, removeRunner } from "./runner-setup.js";
 import { syncCiSecrets, missingCiSecrets } from "../util/ci-secrets.js";
 import { delay } from "../util/delay.js";
 import {
@@ -291,19 +294,33 @@ export async function createProject(
     throw new Error(databricksAuthPrereqMessage(host, auth.reason));
   }
 
-  // ── GitHub token `workflow` scope precondition ────────────────
-  // The scaffold's final push commits .github/workflows/*, which GitHub rejects
-  // unless the token carries the `workflow` OAuth scope. Check it HERE, before any
-  // GitHub repo or Lakebase project exists, so a missing scope fails in seconds with
-  // a fix instead of at the final push after all provisioning (which then rolls back).
+  // ── GitHub account + requisites precondition (B) ──────────────
+  // ONE up-front GitHub preflight, BEFORE any repo / Lakebase project exists, so a
+  // missing requisite fails in seconds with a fix instead of mid-create (where it
+  // orphans partial artifacts): the active account resolves (else a wrong/absent
+  // token 403s LATE at the push), the full required scope set is present (repo +
+  // workflow — not just workflow), and the repo name is free. Conservative: notes
+  // (owner/org mismatch, invisible/advisory scopes) are surfaced but never block.
   if (useGithub) {
-    report("Checking GitHub token scopes...");
-    const scope = await checkGitHubWorkflowScope();
-    if (!scope.ok) {
-      throw new Error(githubWorkflowScopePrereqMessage(scope.reason));
+    report("Checking GitHub account + token requisites...");
+    const gh = await checkGitHubPreflight({ owner: input.githubOwner!, repoName: input.projectName });
+    for (const w of gh.warnings) {
+      warnings.push(w);
+      report(`Note: ${w}`);
     }
+    if (!gh.ok) throw new Error(gh.reason);
   }
 
+  // The created-resources ledger (A3): each resource registers its teardown the
+  // moment it is created, and a genuine provisioning throw inside the wrapper below
+  // rolls back ALL of them in reverse — the GitHub repo, the runner, the local dir,
+  // AND the Lakebase project together — leaving a clean "name is free" state (not
+  // the old 4-artifact orphan where only the Lakebase project was undone). A
+  // push-only failure is caught locally below and is NOT a provisioning throw, so
+  // it never triggers a rollback.
+  const rollback = createRollbackLedger();
+  return await withCreateRollback(rollback, { report }, async (): Promise<CreateProjectResult> => {
+
   // ── Step 1+2: GitHub repo + clone, OR local-only setup ────────
   if (useGithub) {
     report("Creating GitHub repository...", fullRepoName);
@@ -311,6 +328,7 @@ export async function createProject(
       private: input.privateRepo !== false,
       description: `Lakebase project: ${input.projectName}`,
     });
+    rollback.register(`GitHub repo ${fullRepoName}`, () => deleteRepo(fullRepoName));
 
     report("Waiting for GitHub repo to be visible...", fullRepoName);
     const probeDelays = [1000, 2000, 3000, 5000, 8000];
@@ -349,25 +367,23 @@ export async function createProject(
       repoUrl: `https://github.com/${fullRepoName}.git`,
       parentDir: input.parentDir,
     });
+    rollback.register(`local project dir ${projectDir}`, () => fs.rmSync(projectDir, { recursive: true, force: true }));
   } else {
     report("Creating local project directory...", projectDir);
     // A pre-existing EMPTY dir is accepted (validated up front); mkdir with
     // recursive is a no-op on it. A non-empty dir was already rejected.
     fs.mkdirSync(projectDir, { recursive: true });
     await gitInit(projectDir);
+    rollback.register(`local project dir ${projectDir}`, () => fs.rmSync(projectDir, { recursive: true, force: true }));
   }
 
   // ── Step 3: Lakebase project ──────────────────────────────────
   report("Creating Lakebase database (provisioning Postgres)...", lakebaseProjectId);
   await createLakebaseProject({ projectId: lakebaseProjectId, host });
-
-  // From here on the Lakebase project EXISTS. If any later step throws, roll it
-  // back (W9) so the slug isn't orphaned , a retry with the same name would
-  // otherwise collide with the reserved/soft-deleted slug. The wrapper rethrows
-  // with rollback context.
-  return await withLakebaseRollback(
-    { projectId: lakebaseProjectId, host, report },
-    async (): Promise<CreateProjectResult> => {
+  // From here on the Lakebase project EXISTS; register its teardown so a later
+  // provisioning throw rolls it back (W9) alongside the repo + dir above — a retry
+  // with the same name would otherwise collide with the reserved/soft-deleted slug.
+  rollback.register(`Lakebase project ${lakebaseProjectId}`, () => deleteLakebaseProject({ projectId: lakebaseProjectId, host }));
 
   // ── Step 4: Default branch lookup (non-fatal if not ready yet) ─
   report("Resolving database endpoint...");
@@ -481,6 +497,11 @@ export async function createProject(
         projectName: input.projectName,
         report: (m) => report(m),
       });
+      // Registered only after a SUCCESSFUL setup, so a provisioning throw later
+      // tears the runner down (stop + deregister + rm dir) alongside the rest.
+      rollback.register(`self-hosted runner ${input.projectName}`, () =>
+        removeRunner({ fullRepoName, projectName: input.projectName }),
+      );
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       warnings.push(`Runner setup failed: ${msg}`);
@@ -594,6 +615,25 @@ export async function createProject(
     );
   }
 
+  // ── Step 7g: pre-warm the toolkit so the first push doesn't cold-download mid-hook (A1) ──
+  // The scaffolded project's pre-push hook runs `./scripts/lk`, which triggers the
+  // one-time cold download of the Consort toolkit (hundreds of npm fetches). If that
+  // very first `lk` is the PUSH's hook, the heavy download races the push and the push
+  // fails (the cold-download incident). Warming HERE — after the scaffold laid down
+  // scripts/lk, before the push — makes the hook find a populated cache. Best-effort
+  // with ONE retry: if warming still fails we do NOT block create (the push then
+  // cold-downloads itself, exactly as before, and the retriable push below absorbs it).
+  if (enableSftdd && useGithub) {
+    report("Warming the Consort toolkit (so the first push doesn't cold-download mid-hook)...");
+    let warm = warmAndVerifyKit(projectDir);
+    if (!warm.ok) warm = warmAndVerifyKit(projectDir);
+    if (!warm.ok) {
+      const m = kitWarmWarning(projectDir, warm.reason);
+      warnings.push(m);
+      report(`Note: ${m}`);
+    }
+  }
+
   // ── Step 8: Initial commit (+ push when GitHub configured) ────
   const langLabels: Record<string, string> = {
     java: "Java/Spring Boot",
@@ -622,11 +662,29 @@ export async function createProject(
   }
 
   report("Creating initial commit...");
-  await commitAndPush({
-    projectDir,
-    message: `Initial project scaffold (${langLabel} + Lakebase)`,
-    push: useGithub,
-  });
+  await commitInitial(projectDir, `Initial project scaffold (${langLabel} + Lakebase)`);
+  // The commit is now LOCAL on disk. A push failure after this point is RETRIABLE,
+  // NOT a provisioning fault (A2): repo + Lakebase + runner + scaffold all succeeded,
+  // so tearing them down for a transient first-push cold download is wrong. Push with
+  // ONE retry (the toolkit is cached after the warm above / the first hook run); if it
+  // STILL fails, leave every resource intact and print the one-line resume — do NOT
+  // throw (which would fire the rollback ledger). A real `workflow`-scope rejection is
+  // not transient and IS surfaced as a hard error.
+  let pushLanded = !useGithub; // local-only: nothing to push → treat as landed
+  if (useGithub) {
+    try {
+      await pushInitial({ projectDir, attempts: 2 });
+      pushLanded = true;
+    } catch (err) {
+      if (err instanceof WorkflowScopeError) throw err;
+      const msg = err instanceof Error ? err.message : String(err);
+      const m =
+        `Provisioning is complete, but the initial push did not land after a retry: ${msg}. ` +
+        `The project on disk is fine , finish it with: cd ${projectDir} && git push -u origin main`;
+      warnings.push(m);
+      report(`WARNING: ${m}`);
+    }
+  }
 
   // ── Step 8b: Long-running tier setup (architectural choice) ───
   // Tier semantics (features are NOT tiers, they are short-lived branches):
@@ -644,7 +702,17 @@ export async function createProject(
   // origin to already have the parent ref (e.g. main, staging).
   // tiers 2/3 with --no-github is rejected up front by validateCreateInputs, so
   // by here useGithub is guaranteed true for any tiers>1 request.
-  if (tiers === 2 || tiers === 3) {
+  // Skip cleanly when the initial push did NOT land (A2): createLongRunningBranch
+  // forks off origin/main, which does not exist yet — cutting a tier now would fail.
+  // Surface the deferral so the user cuts the tiers after finishing the push.
+  if ((tiers === 2 || tiers === 3) && !pushLanded) {
+    const m =
+      `INCOMPLETE TIERS: you requested ${tiers} tiers, but the initial push hasn't landed, so the ` +
+      `tier branches can't fork off origin yet. After you finish the push (above), cut them with ` +
+      `\`./scripts/lk lakebase-cut-tier --name staging --fork-from main\`${tiers === 3 ? " and \`--name dev --fork-from staging\`" : ""}.`;
+    warnings.push(m);
+    report(`WARNING: ${m}`);
+  } else if (tiers === 2 || tiers === 3) {
     report(`Cutting staging tier (tiers=${tiers}) via createLongRunningBranch...`);
     try {
       await createLongRunningBranch({
@@ -712,7 +780,7 @@ export async function createProject(
     warnings,
   };
 
-    } // end withLakebaseRollback closure
+    } // end withCreateRollback closure
   );
 }
 

package/scripts/lakebase/scaffold.ts

@@ -517,6 +517,39 @@ export async function deployVscodeSettings(targetDir: string, opts?: ScaffoldOpt
   fs.copyFileSync(src, path.join(destDir, "settings.json"));
 }
 
+/**
+ * The per-test capture modules that live at the PROJECT ROOT. They are a pair:
+ * `consort-test-reporter.ts` imports `./consort-capture`, and the client's test
+ * surface reaches up to them from `client/` — `client/vite.config.ts` wires
+ * `setupFiles: "./tests/setup.ts"` + `reporters: […, "./consort-vitest-reporter.ts"]`,
+ * both of which `import … from "../../consort-capture"` / `"../consort-capture"`,
+ * and `client/playwright.config.ts` (and the Node-backend root `playwright.config.ts`)
+ * name `../consort-test-reporter.ts` / `./consort-test-reporter.ts` as a reporter.
+ * Without these two files at the root, `vitest run` can't start and Playwright
+ * can't load. They ship in `templates/project/common/` but are NOT part of the
+ * file-by-file static copy above, so they must be deployed explicitly.
+ */
+export const TEST_CAPTURE_ROOT_FILES = ["consort-capture.ts", "consort-test-reporter.ts"] as const;
+
+/**
+ * Deploy the root test-capture modules (TEST_CAPTURE_ROOT_FILES) from
+ * `common/` to the project root. Throws if a source template is missing (a
+ * kit packaging bug, not a user error). Returns the relative paths written.
+ */
+export function deployTestCaptureRoot(targetDir: string, opts?: ScaffoldOptions): string[] {
+  const src = commonDir(opts);
+  const written: string[] = [];
+  for (const rel of TEST_CAPTURE_ROOT_FILES) {
+    const from = path.join(src, rel);
+    if (!fs.existsSync(from)) {
+      throw new Error(`Kit template missing: ${from}`);
+    }
+    fs.copyFileSync(from, path.join(targetDir, rel));
+    written.push(rel);
+  }
+  return written;
+}
+
 /** Deploy .gitignore: common/.gitignore.base + <language>/.gitignore.extra. */
 export async function deployGitignore(
   targetDir: string,
@@ -675,6 +708,10 @@ export interface ScaffoldStaticAllResult {
   /** `client/*` files written when the React SPA client was scaffolded
    *  (clientFramework="react"); empty/omitted otherwise. */
   client?: string[];
+  /** Root per-test capture modules (consort-capture.ts, consort-test-reporter.ts)
+   *  written for a Node-flavored test surface (React client or Node backend);
+   *  empty/omitted for Python/Java backends with no React client. */
+  testCapture?: string[];
 }
 
 /**
@@ -795,5 +832,18 @@ export async function scaffoldAll(args: ScaffoldAllArgs): Promise<ScaffoldStatic
     if (client.length > 0) staticResult.client = client;
   }
 
+  // Root per-test capture modules (consort-capture.ts + consort-test-reporter.ts).
+  // A Node-flavored test surface reaches up to these at the project root: the
+  // React client's vitest reporter + setup + playwright config, and the Node
+  // backend's root playwright config. Without them `vitest run` / Playwright
+  // fail to load (the scaffold-defect halt). Python/Java backends with no React
+  // client use conftest.py and never import the .ts pair, so skip them.
+  if (args.clientFramework === "react" || language === "nodejs") {
+    report("Deploying root test-capture modules");
+    staticResult.testCapture = deployTestCaptureRoot(args.targetDir, {
+      templatesDir: args.templatesDir,
+    });
+  }
+
   return staticResult;
 }