@databricks-solutions/lakebase-scm-utils 0.2.41 → 0.2.43

package/dist/scripts/lakebase/scm-recover-orphans.cli.js

@@ -288,7 +288,9 @@ function resolveProfile(opts) {
 function buildInvocation(args, opts) {
   const base = opts.env ?? process.env;
   const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
-  const env = trimmedHost ? { ...base, DATABRICKS_HOST: trimmedHost } : base;
+  const env = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  delete env.DATABRICKS_WORKSPACE_ID;
   const profile = resolveProfile(opts);
   const argv = profile && !opts.noProfile && !args.includes("--profile") ? [...args, "--profile", profile] : args;
   return { argv, env, profile };
@@ -1159,6 +1161,39 @@ async function listLocalBranches(args) {
 // scripts/lakebase/scm-workflow-state.ts
 import * as fs5 from "fs";
 import * as path4 from "path";
+import { execFileSync as execFileSync4 } from "child_process";
+function isGitTracked(projectDir, rel) {
+  try {
+    execFileSync4("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ensureWorkflowStateUntracked(projectDir) {
+  const rel = ".lakebase/workflow-state.json";
+  try {
+    if (isGitTracked(projectDir, rel)) {
+      execFileSync4("git", ["rm", "--cached", "--quiet", "--ignore-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    }
+  } catch {
+  }
+  try {
+    const gitignore = path4.join(projectDir, ".gitignore");
+    const existing = fs5.existsSync(gitignore) ? fs5.readFileSync(gitignore, "utf8") : "";
+    if (!existing.split("\n").some((l) => l.trim() === rel)) {
+      const sep = existing === "" || existing.endsWith("\n") ? "" : "\n";
+      fs5.appendFileSync(
+        gitignore,
+        `${sep}# Runtime SCM claim state (per working tree): a branch checkout must never restore
+# a stale committed claim over the live one (issue #203 / Finding 28).
+${rel}
+`
+      );
+    }
+  } catch {
+  }
+}
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",
@@ -1205,6 +1240,7 @@ function writeWorkflowState(projectDir, state) {
     throw new Error(`Refusing to write invalid SCM state:
 ${summary}`);
   }
+  ensureWorkflowStateUntracked(projectDir);
   const dir = path4.join(projectDir, ".lakebase");
   fs5.mkdirSync(dir, { recursive: true });
   const target = stateFilePath(projectDir);

package/dist/scripts/lakebase/scm-state.cli.cjs

@@ -77545,6 +77545,7 @@ function isCliEntry(importMetaUrl2) {
 init_cjs_shims();
 var fs = __toESM(require("fs"), 1);
 var path = __toESM(require("path"), 1);
+var import_node_child_process = require("child_process");
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",
@@ -77821,21 +77822,21 @@ var KIT_REGISTRIES = {
 init_cjs_shims();
 var fs6 = __toESM(require("fs"), 1);
 var path4 = __toESM(require("path"), 1);
-var import_node_child_process3 = require("child_process");
+var import_node_child_process4 = require("child_process");
 
 // scripts/lakebase/branch-create.ts
 init_cjs_shims();
 
 // scripts/lakebase/databricks-cli.ts
 init_cjs_shims();
-var import_node_child_process2 = require("child_process");
+var import_node_child_process3 = require("child_process");
 var import_node_util = require("util");
 var import_node_path = require("path");
 
 // scripts/lakebase/databricks-profile.ts
 init_cjs_shims();
 var fs2 = __toESM(require("fs"), 1);
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 
 // scripts/util/exec.ts
 init_cjs_shims();
@@ -77847,7 +77848,7 @@ var fs3 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
 
 // scripts/lakebase/databricks-cli.ts
-var execFileP = (0, import_node_util.promisify)(import_node_child_process2.execFile);
+var execFileP = (0, import_node_util.promisify)(import_node_child_process3.execFile);
 
 // scripts/util/poll-until.ts
 init_cjs_shims();

package/dist/scripts/lakebase/scm-state.cli.js

@@ -27,6 +27,7 @@ function isCliEntry(importMetaUrl) {
 // scripts/lakebase/scm-workflow-state.ts
 import * as fs from "fs";
 import * as path from "path";
+import { execFileSync } from "child_process";
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",
@@ -297,16 +298,16 @@ var KIT_REGISTRIES = {
 // scripts/lakebase/paired-branch.ts
 import * as fs5 from "fs";
 import * as path4 from "path";
-import { execFileSync as execFileSync3 } from "child_process";
+import { execFileSync as execFileSync4 } from "child_process";
 
 // scripts/lakebase/databricks-cli.ts
-import { execFile, execFileSync as execFileSync2 } from "child_process";
+import { execFile, execFileSync as execFileSync3 } from "child_process";
 import { promisify } from "util";
 import { join as join3 } from "path";
 
 // scripts/lakebase/databricks-profile.ts
 import * as fs2 from "fs";
-import { execFileSync } from "child_process";
+import { execFileSync as execFileSync2 } from "child_process";
 
 // scripts/util/exec.ts
 import * as cp from "child_process";

package/dist/scripts/lakebase/scm-wait-ci.cli.cjs

@@ -8351,6 +8351,39 @@ async function pollUntil(args) {
 init_cjs_shims();
 var fs3 = __toESM(require("fs"), 1);
 var path2 = __toESM(require("path"), 1);
+var import_node_child_process4 = require("child_process");
+function isGitTracked(projectDir, rel) {
+  try {
+    (0, import_node_child_process4.execFileSync)("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ensureWorkflowStateUntracked(projectDir) {
+  const rel = ".lakebase/workflow-state.json";
+  try {
+    if (isGitTracked(projectDir, rel)) {
+      (0, import_node_child_process4.execFileSync)("git", ["rm", "--cached", "--quiet", "--ignore-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    }
+  } catch {
+  }
+  try {
+    const gitignore = path2.join(projectDir, ".gitignore");
+    const existing = fs3.existsSync(gitignore) ? fs3.readFileSync(gitignore, "utf8") : "";
+    if (!existing.split("\n").some((l) => l.trim() === rel)) {
+      const sep2 = existing === "" || existing.endsWith("\n") ? "" : "\n";
+      fs3.appendFileSync(
+        gitignore,
+        `${sep2}# Runtime SCM claim state (per working tree): a branch checkout must never restore
+# a stale committed claim over the live one (issue #203 / Finding 28).
+${rel}
+`
+      );
+    }
+  } catch {
+  }
+}
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",
@@ -8397,6 +8430,7 @@ function writeWorkflowState(projectDir, state) {
     throw new Error(`Refusing to write invalid SCM state:
 ${summary}`);
   }
+  ensureWorkflowStateUntracked(projectDir);
   const dir = path2.join(projectDir, ".lakebase");
   fs3.mkdirSync(dir, { recursive: true });
   const target = stateFilePath(projectDir);

package/dist/scripts/lakebase/scm-wait-ci.cli.js

@@ -8339,6 +8339,39 @@ async function pollUntil(args) {
 init_esm_shims();
 import * as fs3 from "fs";
 import * as path3 from "path";
+import { execFileSync as execFileSync4 } from "child_process";
+function isGitTracked(projectDir, rel) {
+  try {
+    execFileSync4("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function ensureWorkflowStateUntracked(projectDir) {
+  const rel = ".lakebase/workflow-state.json";
+  try {
+    if (isGitTracked(projectDir, rel)) {
+      execFileSync4("git", ["rm", "--cached", "--quiet", "--ignore-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    }
+  } catch {
+  }
+  try {
+    const gitignore = path3.join(projectDir, ".gitignore");
+    const existing = fs3.existsSync(gitignore) ? fs3.readFileSync(gitignore, "utf8") : "";
+    if (!existing.split("\n").some((l) => l.trim() === rel)) {
+      const sep2 = existing === "" || existing.endsWith("\n") ? "" : "\n";
+      fs3.appendFileSync(
+        gitignore,
+        `${sep2}# Runtime SCM claim state (per working tree): a branch checkout must never restore
+# a stale committed claim over the live one (issue #203 / Finding 28).
+${rel}
+`
+      );
+    }
+  } catch {
+  }
+}
 var SCM_STATES = [
   "scaffold-complete",
   "feature-claimed",
@@ -8385,6 +8418,7 @@ function writeWorkflowState(projectDir, state) {
     throw new Error(`Refusing to write invalid SCM state:
 ${summary}`);
   }
+  ensureWorkflowStateUntracked(projectDir);
   const dir = path3.join(projectDir, ".lakebase");
   fs3.mkdirSync(dir, { recursive: true });
   const target = stateFilePath(projectDir);

package/dist/scripts/util/index.cjs

@@ -1659,8 +1659,8 @@ var PKG_NAME = "@databricks-solutions/lakebase-scm-utils";
 var cached;
 function substrateSelfVersion() {
   if (cached !== void 0) return cached;
-  if ("0.2.41".length > 0) {
-    cached = "0.2.41";
+  if ("0.2.43".length > 0) {
+    cached = "0.2.43";
     return cached;
   }
   cached = "unknown";
@@ -1895,7 +1895,9 @@ function resolveProfile(opts) {
 function buildInvocation(args, opts) {
   const base = opts.env ?? process.env;
   const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
-  const env = trimmedHost ? { ...base, DATABRICKS_HOST: trimmedHost } : base;
+  const env = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  delete env.DATABRICKS_WORKSPACE_ID;
   const profile = resolveProfile(opts);
   const argv = profile && !opts.noProfile && !args.includes("--profile") ? [...args, "--profile", profile] : args;
   return { argv, env, profile };

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.2.41".length > 0) {
-    cached = "0.2.41";
+  if ("0.2.43".length > 0) {
+    cached = "0.2.43";
     return cached;
   }
   cached = "unknown";
@@ -1866,7 +1866,9 @@ function resolveProfile(opts) {
 function buildInvocation(args, opts) {
   const base = opts.env ?? process.env;
   const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
-  const env = trimmedHost ? { ...base, DATABRICKS_HOST: trimmedHost } : base;
+  const env = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  delete env.DATABRICKS_WORKSPACE_ID;
   const profile = resolveProfile(opts);
   const argv = profile && !opts.noProfile && !args.includes("--profile") ? [...args, "--profile", profile] : args;
   return { argv, env, profile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@databricks-solutions/lakebase-scm-utils",
-  "version": "0.2.41",
+  "version": "0.2.43",
   "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/lakebase/databricks-cli.ts

@@ -149,7 +149,13 @@ export function buildInvocation(args: string[], opts: DatabricksCliOptions): {
   // so an in-project call pins the project workspace rather than the DEFAULT
   // profile's default host. Trailing slash stripped for a stable value.
   const trimmedHost = effectiveHost(opts)?.replace(/\/+$/, "");
-  const env: NodeJS.ProcessEnv = trimmedHost ? { ...base, DATABRICKS_HOST: trimmedHost } : base;
+  const env: NodeJS.ProcessEnv = { ...base };
+  if (trimmedHost) env.DATABRICKS_HOST = trimmedHost;
+  // A stray DATABRICKS_WORKSPACE_ID (a bare numeric workspace ID, never a URL)
+  // makes the CLI's unified-host path dial https://<id> (issue #204.1). The
+  // workspace always resolves via the profile/host chain above, so scrub the
+  // stray var from the child env (the documented workaround, centralized).
+  delete env.DATABRICKS_WORKSPACE_ID;
   const profile = resolveProfile(opts);
   const argv =
     profile && !opts.noProfile && !args.includes("--profile")

package/scripts/lakebase/enable-e2e.ts

@@ -225,12 +225,27 @@ function runTestsE2eBlock(): string {
     '  export VITE_PROXY_TARGET="http://127.0.0.1:${E2E_BACKEND_PORT}"',
     '  echo "Local E2E free-port: backend :$E2E_BACKEND_PORT / client :$E2E_CLIENT_PORT"',
     'fi',
+    // Stale-server hygiene (issue #197): CI=1 on the Playwright invocations below
+    // forces EVERY config vintage's reuseExistingServer guard OFF (old `!CI` and
+    // new `!!BASE_URL` alike), so the verify never reuses a stale server bound to
+    // an unmigrated branch (the false-500 misdiagnosis). A lingering uvicorn/vite
+    // on the conventional default ports still serves STALE schema to anything
+    // that reaches it, so clear it (TERM, not KILL) before the boot - never when
+    // the caller pre-set the ports (the deploy gate owns that server; BASE_URL).
+    'if [ -z "${BASE_URL:-}" ] && command -v lsof >/dev/null 2>&1; then',
+    '  for p in "${E2E_BACKEND_PORT:-8000}" "${E2E_CLIENT_PORT:-5173}"; do',
+    '    if lsof -iTCP:"$p" -sTCP:LISTEN -n -P >/dev/null 2>&1; then',
+    '      echo "Local E2E: clearing a stale listener on :$p before the webServer boot"',
+    '      lsof -ti tcp:"$p" 2>/dev/null | xargs kill 2>/dev/null || true',
+    '    fi',
+    '  done',
+    'fi',
     'if [ -f "$REPO_ROOT/playwright.config.ts" ] || [ -f "$REPO_ROOT/playwright.config.js" ]; then',
     '  echo "Running Playwright E2E tests..."',
     '  if [ -f "$REPO_ROOT/package.json" ] && command -v npm >/dev/null 2>&1; then',
-    '    (cd "$REPO_ROOT" && npm run test:e2e)',
+    '    (cd "$REPO_ROOT" && CI=1 npm run test:e2e)',
     "  else",
-    '    (cd "$REPO_ROOT" && npx --yes playwright test)',
+    '    (cd "$REPO_ROOT" && CI=1 npx --yes playwright test)',
     "  fi",
     // Python E2E: pytest-playwright + the shipped tests/e2e/conftest.py
     // (live_server). Gated on the conftest + pyproject so it only fires for a
@@ -269,7 +284,8 @@ function runTestsE2eBlock(): string {
     'if [ -f "$REPO_ROOT/client/playwright.config.ts" ] || [ -f "$REPO_ROOT/client/playwright.config.js" ] || [ -f "$REPO_ROOT/client/playwright.config.mjs" ]; then',
     '  echo "Running client Playwright E2E tests..."',
     '  (cd "$REPO_ROOT/client" && npx --yes playwright install chromium)',
-    '  (cd "$REPO_ROOT/client" && npx --yes playwright test --pass-with-no-tests)',
+    // CI=1: no server reuse on any config vintage (see the stale-server note above).
+    '  (cd "$REPO_ROOT/client" && CI=1 npx --yes playwright test --pass-with-no-tests)',
     "fi",
     "",
   ].join("\n");

package/scripts/lakebase/scm-doctor.ts

@@ -9,7 +9,6 @@
 // an error rather than performing a related-but-different remediation.
 
 import * as fs from "node:fs";
-import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import {
   getBranchByName,
@@ -25,6 +24,7 @@ import { recoverOrphans } from "./scm-recover-orphans.js";
 import { abandonFeatureBranch } from "./scm-abandon-feature.js";
 import {
   readWorkflowState,
+  isGitTracked,
   type ScmWorkflowState,
   type TierTopology,
 } from "./scm-workflow-state.js";
@@ -106,17 +106,6 @@ function leafOf(b: LakebaseBranchInfo): string {
   return b.name.split("/").pop() ?? b.name;
 }
 
-/** True iff `rel` (repo-relative) is git-tracked in projectDir. Best-effort: no
- *  git / not a repo -> false. */
-function isGitTracked(projectDir: string, rel: string): boolean {
-  try {
-    execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function worstOf(a: DoctorSeverity, b: DoctorSeverity): DoctorSeverity {
   const order: DoctorSeverity[] = ["ok", "warn", "fail"];
   return order[Math.max(order.indexOf(a), order.indexOf(b))] as DoctorSeverity;

package/scripts/lakebase/scm-merge.ts

@@ -21,6 +21,35 @@ import { pollUntil } from "../util/poll-until.js";
 import { exec } from "../util/exec.js";
 import { getCurrentBranch } from "../git/inspect.js";
 import { resolveGitBase } from "./scm-git-base.js";
+
+/**
+ * Fast-forward the local tier ref to origin/<tier> after a remote merge, WITHOUT
+ * needing a checkout. A promote interrupted after the remote merge (e.g. a
+ * downstream migrate failure) otherwise leaves the local tier BEHIND, so the
+ * next sprint plans on stale code and the next push rejects non-fast-forward.
+ * Mechanism by head position: when HEAD IS the tier, `git pull --ff-only` syncs
+ * ref + working tree; otherwise `git fetch origin <tier>:<tier>` fast-forwards
+ * the local ref in place (git refuses fetch-into-current-branch, hence the
+ * split). Returns null on success; a warning string when the sync fails (e.g.
+ * not a fast-forward because the local tier has its own commits), never throws.
+ */
+export async function reconcileTierToOrigin(args: { cwd: string; tier: string }): Promise<string | null> {
+  const { cwd, tier } = args;
+  try {
+    const head = await getCurrentBranch({ cwd });
+    if (head === tier) {
+      await exec(`git pull --ff-only`, { cwd, timeout: 30_000 });
+    } else {
+      await exec(`git fetch origin ${shellEscape(`${tier}:${tier}`)}`, { cwd, timeout: 30_000 });
+    }
+    return null;
+  } catch (err) {
+    return (
+      `local reconcile of ${tier} to origin/${tier} failed: ${err instanceof Error ? err.message : String(err)}. ` +
+      `Reconcile it by hand (git checkout ${tier} && git pull --ff-only).`
+    );
+  }
+}
 import {
   readWorkflowState,
   writeWorkflowState,
@@ -328,6 +357,13 @@ export async function mergeFeature(args: MergeArgs): Promise<MergeResult> {
       }
     } else {
       headAfter = head || current.branch;
+      // HEAD isn't the feature branch, so the checkout+ff path above didn't run.
+      // Reconcile the local tier ref to origin anyway (no checkout needed): a
+      // promote interrupted after the remote merge must not leave the tier behind
+      // (the stockflow F1 case: local staging missed the merge, the next push
+      // rejected non-fast-forward). Best-effort; a failure is a warning, not a throw.
+      const reconcileWarning = await reconcileTierToOrigin({ cwd: args.projectDir, tier: switchTo });
+      if (reconcileWarning) warnings.push(reconcileWarning);
     }
     if (headAfter !== current.branch) {
       try {

package/scripts/lakebase/scm-workflow-state.ts

@@ -13,6 +13,52 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+
+/** True iff `rel` (repo-relative) is git-tracked in projectDir. Best-effort: no
+ *  git / not a repo -> false. Shared home (scm-doctor's Finding-28 check reads
+ *  the same predicate). */
+export function isGitTracked(projectDir: string, rel: string): boolean {
+  try {
+    execFileSync("git", ["ls-files", "--error-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Ensure the runtime SCM claim state is NOT git-tracked (issue #203 / Finding 28):
+ *  a tracked .lakebase/workflow-state.json gets a branch-COMMITTED stale claim
+ *  restored over the live one by every branch checkout / `git reset --hard
+ *  origin/<tier>`, which then blocks the next feature's claim
+ *  ("already-claimed-other") until a manual abandon+reclaim. Untrack it
+ *  (index-only; the working file stays) and cover it in .gitignore, so the live
+ *  claim survives checkouts. The committed .lakebase/kit-ref + scm-utils-ref stay
+ *  tracked deliberately (CI resolves them). Idempotent + best-effort (non-git
+ *  dirs / unwritable .gitignore skip silently – the state write itself still lands). */
+function ensureWorkflowStateUntracked(projectDir: string): void {
+  const rel = ".lakebase/workflow-state.json";
+  try {
+    if (isGitTracked(projectDir, rel)) {
+      execFileSync("git", ["rm", "--cached", "--quiet", "--ignore-unmatch", "--", rel], { cwd: projectDir, stdio: "ignore" });
+    }
+  } catch {
+    /* best-effort */
+  }
+  try {
+    const gitignore = path.join(projectDir, ".gitignore");
+    const existing = fs.existsSync(gitignore) ? fs.readFileSync(gitignore, "utf8") : "";
+    if (!existing.split("\n").some((l) => l.trim() === rel)) {
+      const sep = existing === "" || existing.endsWith("\n") ? "" : "\n";
+      fs.appendFileSync(
+        gitignore,
+        `${sep}# Runtime SCM claim state (per working tree): a branch checkout must never restore\n# a stale committed claim over the live one (issue #203 / Finding 28).\n${rel}\n`,
+      );
+    }
+  } catch {
+    /* best-effort */
+  }
+}
 
 /** All SCM states, in canonical progression order. */
 export const SCM_STATES = [
@@ -133,6 +179,9 @@ export function writeWorkflowState(
       .join("\n");
     throw new Error(`Refusing to write invalid SCM state:\n${summary}`);
   }
+  // Self-heal on every write (issue #203): the live claim survives checkouts
+  // only while the state file is untracked.
+  ensureWorkflowStateUntracked(projectDir);
   const dir = path.join(projectDir, ".lakebase");
   fs.mkdirSync(dir, { recursive: true });
   const target = stateFilePath(projectDir);

package/templates/project/common/.github/workflows/merge.yml

@@ -74,14 +74,25 @@ jobs:
           SCM_UTILS_REF="$(tr -d '[:space:]' < .lakebase/scm-utils-ref 2>/dev/null || true)"
           SCM_UTILS_REF="${SCM_UTILS_REF:-v{{LAKEBASE_SCM_UTILS_VERSION}}}"
           echo "SCM_UTILS_REF=${SCM_UTILS_REF}" >> "$GITHUB_ENV"
-          # Registry-first: version-tag refs install the published tarball from the
-          # npm registry (seconds); branch/SHA refs keep the GitHub source form
-          # (their only source).
+          # Registry-first for version tags, with a GitHub fallback when the registry
+          # cannot serve the tarball yet: a freshly-published version is blocked by
+          # the proxy's same-day security screen for ~24h (a staging merge then fails
+          # on npx ETARGET), and a branch/SHA ref only ever has GitHub. Probe the
+          # tarball URL once and pick the source that actually serves it, so a
+          # same-day publish never stalls CI.
+          SPEC=""
           case "$SCM_UTILS_REF" in
-            v[0-9]*) echo "SCM_UTILS_NPX_PKG=@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF#v}" >> "$GITHUB_ENV" ;;
-            [0-9]*)  echo "SCM_UTILS_NPX_PKG=@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF}" >> "$GITHUB_ENV" ;;
-            *)       echo "SCM_UTILS_NPX_PKG=github:databricks-solutions/lakebase-scm-utils#${SCM_UTILS_REF}" >> "$GITHUB_ENV" ;;
+            v[0-9]*|[0-9]*) SPEC="@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF#v}" ;;
           esac
+          if [ -n "$SPEC" ]; then
+            TARBALL_URL="$(npm view "${SPEC}" dist.tarball 2>/dev/null || true)"
+            if [ -z "$TARBALL_URL" ] || ! curl -fsSI --max-time 15 "$TARBALL_URL" >/dev/null 2>&1; then
+              echo "resolve-substrate: registry cannot serve ${SPEC} yet (same-day publish screen); falling back to GitHub."
+              SPEC=""
+            fi
+          fi
+          [ -z "$SPEC" ] && SPEC="github:databricks-solutions/lakebase-scm-utils#${SCM_UTILS_REF}"
+          echo "SCM_UTILS_NPX_PKG=${SPEC}" >> "$GITHUB_ENV"
 
       - name: Detect project language
         id: detect-lang

package/templates/project/common/.github/workflows/pr.yml

@@ -33,14 +33,25 @@ jobs:
           SCM_UTILS_REF="$(tr -d '[:space:]' < .lakebase/scm-utils-ref 2>/dev/null || true)"
           SCM_UTILS_REF="${SCM_UTILS_REF:-v{{LAKEBASE_SCM_UTILS_VERSION}}}"
           echo "SCM_UTILS_REF=${SCM_UTILS_REF}" >> "$GITHUB_ENV"
-          # Registry-first: version-tag refs install the published tarball from the
-          # npm registry (seconds); branch/SHA refs keep the GitHub source form
-          # (their only source).
+          # Registry-first for version tags, with a GitHub fallback when the registry
+          # cannot serve the tarball yet: a freshly-published version is blocked by
+          # the proxy's same-day security screen for ~24h (a staging merge then fails
+          # on npx ETARGET), and a branch/SHA ref only ever has GitHub. Probe the
+          # tarball URL once and pick the source that actually serves it, so a
+          # same-day publish never stalls CI.
+          SPEC=""
           case "$SCM_UTILS_REF" in
-            v[0-9]*) echo "SCM_UTILS_NPX_PKG=@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF#v}" >> "$GITHUB_ENV" ;;
-            [0-9]*)  echo "SCM_UTILS_NPX_PKG=@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF}" >> "$GITHUB_ENV" ;;
-            *)       echo "SCM_UTILS_NPX_PKG=github:databricks-solutions/lakebase-scm-utils#${SCM_UTILS_REF}" >> "$GITHUB_ENV" ;;
+            v[0-9]*|[0-9]*) SPEC="@databricks-solutions/lakebase-scm-utils@${SCM_UTILS_REF#v}" ;;
           esac
+          if [ -n "$SPEC" ]; then
+            TARBALL_URL="$(npm view "${SPEC}" dist.tarball 2>/dev/null || true)"
+            if [ -z "$TARBALL_URL" ] || ! curl -fsSI --max-time 15 "$TARBALL_URL" >/dev/null 2>&1; then
+              echo "resolve-substrate: registry cannot serve ${SPEC} yet (same-day publish screen); falling back to GitHub."
+              SPEC=""
+            fi
+          fi
+          [ -z "$SPEC" ] && SPEC="github:databricks-solutions/lakebase-scm-utils#${SCM_UTILS_REF}"
+          echo "SCM_UTILS_NPX_PKG=${SPEC}" >> "$GITHUB_ENV"
 
       - name: Detect project language
         id: detect-lang

package/templates/project/common/.gitignore.base

@@ -58,6 +58,14 @@ application-local.properties
 .lakebase/kit-ref.local
 .lakebase/scm-utils-ref.local
 
+# The runtime SCM CLAIM state: per working tree, rewritten by every SCM transition
+# (claim / pr-ready / ci-green / merged). If it is git-tracked, a branch checkout
+# or `git reset --hard origin/<tier>` restores a branch-COMMITTED stale claim over
+# the live one, and the next feature's claim then refuses "already-claimed-other"
+# until a manual abandon+reclaim (issue #203 / Finding 28). Never track it; the
+# committed kit-ref / scm-utils-ref pins above stay tracked deliberately.
+.lakebase/workflow-state.json
+
 # Per-agent local memory: each role subagent (memory: project) persists its own
 # learnings here mid-run. It is local + churny (re-written every run), not feature
 # code, so it must never be committed nor count as a dirty working tree , an

package/templates/project/common/scripts/run-tests.sh

@@ -213,6 +213,20 @@ ensure_local_e2e_ports() {
     export VITE_PROXY_TARGET="http://127.0.0.1:${E2E_BACKEND_PORT}"
     echo "Local E2E free-port: backend :$E2E_BACKEND_PORT / client :$E2E_CLIENT_PORT"
   fi
+  # Stale-server hygiene (issue #197): CI=1 (on the Playwright invocation below)
+  # means the webServer never REUSES a stale app, and free_port moved us off any
+  # collision - but a lingering uvicorn/vite on the conventional default ports (a
+  # prior E2E run, or a deploy whose teardown missed) still serves STALE schema to
+  # anything that reaches it. Clear it (TERM, not KILL) before the boot. Never
+  # when the caller pre-set the ports (the deploy gate owns that server).
+  if [ -z "${BASE_URL:-}" ] && command -v lsof >/dev/null 2>&1; then
+    for p in "${E2E_BACKEND_PORT:-8000}" "${E2E_CLIENT_PORT:-5173}"; do
+      if lsof -iTCP:"$p" -sTCP:LISTEN -n -P >/dev/null 2>&1; then
+        echo "Local E2E: clearing a stale listener on :$p before the webServer boot"
+        lsof -ti tcp:"$p" 2>/dev/null | xargs kill 2>/dev/null || true
+      fi
+    done
+  fi
 }
 
 if [ "$#" -eq 0 ] && [ -d "$REPO_ROOT/client/tests/e2e" ] \
@@ -240,8 +254,11 @@ if [ "$#" -eq 0 ] && [ -d "$REPO_ROOT/client/tests/e2e" ] \
     # Use the client's OWN playwright bin (guaranteed present by the check/install above), not npx,
     # so browser install + the run are deterministic under the deploy gate. install chromium first
     # (playwright test does not auto-install browsers); a failing E2E fails the run (set -e).
+    # CI=1: force EVERY playwright.config vintage's reuseExistingServer guard OFF
+    # (old `!CI` and new `!!BASE_URL` alike) so the verify never reuses a stale
+    # server bound to an unmigrated branch (issue #197's false-500 misdiagnosis).
     ensure_local_e2e_ports
-    ( cd "$REPO_ROOT/client" && ./node_modules/.bin/playwright install chromium && npm run test:e2e )
+    ( cd "$REPO_ROOT/client" && ./node_modules/.bin/playwright install chromium && CI=1 npm run test:e2e )
   fi
 fi
 

package/templates/project/python/tests/conftest.py

@@ -41,9 +41,16 @@ def _restore_migration_head_after_each_test():
 
         from alembic import command
         from alembic.config import Config
+        from alembic.util.exc import CommandError
+        from sqlalchemy.exc import OperationalError
 
         ini = str(Path(__file__).resolve().parent.parent / "alembic.ini")
         command.upgrade(Config(ini), "head")
-    except Exception:
-        # Best-effort isolation; never fail a test on teardown restoration.
-        pass
+    except (CommandError, OperationalError) as exc:
+        # Best-effort isolation, but never SILENT and never an umbrella swallow:
+        # surface a restore failure instead of hiding it (a broken migration must
+        # be visible, not masked as routine teardown noise). CommandError wraps
+        # alembic's own failures; OperationalError covers DBAPI/connection errors.
+        # Everything else (a real schema error) propagates and fails loudly, which
+        # is the correct behavior for a genuinely broken restore.
+        print(f"WARNING: migration-head restore failed during teardown: {exc}")