@databricks-solutions/lakebase-scm-utils 0.2.40 → 0.2.42

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.40".length > 0) {
-    cached = "0.2.40";
+  if ("0.2.42".length > 0) {
+    cached = "0.2.42";
     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.40",
+  "version": "0.2.42",
   "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-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

@@ -72,7 +72,16 @@ jobs:
         # the version this project was scaffolded from, when .lakebase/scm-utils-ref is absent.
         run: |
           SCM_UTILS_REF="$(tr -d '[:space:]' < .lakebase/scm-utils-ref 2>/dev/null || true)"
-          echo "SCM_UTILS_REF=${SCM_UTILS_REF:-v{{LAKEBASE_SCM_UTILS_VERSION}}}" >> "$GITHUB_ENV"
+          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).
+          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" ;;
+          esac
 
       - name: Detect project language
         id: detect-lang
@@ -84,7 +93,7 @@ jobs:
         # this project.
         run: |
           LANG="$(npx --yes \
-            --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+            --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-detect-language)"
           echo "lang=$LANG" >> $GITHUB_OUTPUT
           echo "Detected language: $LANG"
@@ -268,7 +277,7 @@ jobs:
           echo "  instance:    $LAKEBASE_PROJECT_ID"
           echo "  source:      $DEFAULT_NAME"
           echo "  backup:      $SNAPSHOT_NAME"
-          if CREATE_OUT="$(npx --yes --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+          if CREATE_OUT="$(npx --yes --package="${SCM_UTILS_NPX_PKG}" \
                               lakebase-cut-backup \
                               --instance "$LAKEBASE_PROJECT_ID" \
                               --source "$DEFAULT_NAME" \
@@ -312,7 +321,7 @@ jobs:
           # is the promotion opt-in (allowTier) + verifies the tier reached head,
           # so a partial promotion fails the job instead of leaving git ahead of
           # the Lakebase schema. Single-tier (default branch) also goes through it.
-          npx --yes --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+          npx --yes --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-schema-migrate apply-tier \
             --instance "$LAKEBASE_PROJECT_ID" \
             --branch "$LAKEBASE_BRANCH_NAME" \
@@ -394,7 +403,7 @@ jobs:
           echo "  substrate ref: ${SCM_UTILS_REF}"
           echo "  instance:    $LAKEBASE_PROJECT_ID"
           echo "  branch:      $LAKEBASE_BRANCH_NAME"
-          npx --yes --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+          npx --yes --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-schema-migrate status \
             --instance "$LAKEBASE_PROJECT_ID" \
             --branch "$LAKEBASE_BRANCH_NAME" \

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

@@ -31,7 +31,16 @@ jobs:
         # the version this project was scaffolded from, when .lakebase/scm-utils-ref is absent.
         run: |
           SCM_UTILS_REF="$(tr -d '[:space:]' < .lakebase/scm-utils-ref 2>/dev/null || true)"
-          echo "SCM_UTILS_REF=${SCM_UTILS_REF:-v{{LAKEBASE_SCM_UTILS_VERSION}}}" >> "$GITHUB_ENV"
+          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).
+          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" ;;
+          esac
 
       - name: Detect project language
         id: detect-lang
@@ -43,7 +52,7 @@ jobs:
         # this project.
         run: |
           LANG="$(npx --yes \
-            --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+            --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-detect-language)"
           echo "lang=$LANG" >> $GITHUB_OUTPUT
           echo "Detected language: $LANG"
@@ -343,7 +352,7 @@ jobs:
           echo "  substrate ref: ${SCM_UTILS_REF}"
           echo "  instance:    $LAKEBASE_PROJECT_ID"
           echo "  branch:      $LAKEBASE_BRANCH_NAME"
-          npx --yes --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+          npx --yes --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-schema-migrate apply \
             --instance "$LAKEBASE_PROJECT_ID" \
             --branch "$LAKEBASE_BRANCH_NAME" \
@@ -469,7 +478,7 @@ jobs:
           # `|| URL=""` clause keeps the workflow green and the env var
           # unset so the downstream Playwright step degrades cleanly.
           URL="$(npx --yes \
-            --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+            --package="${SCM_UTILS_NPX_PKG}" \
             lakebase-ci-app-endpoint \
             --instance "$LAKEBASE_PROJECT_ID" \
             --branch "$CI_BRANCH")" || URL=""
@@ -590,7 +599,7 @@ jobs:
           if [ -n "$PRODUCTION_DATASOURCE_URL" ] && [ -n "$BRANCH" ]; then
             echo "### Schema diff: \`${BRANCH}\` vs parent (\`${PR_BASE_REF}\`)" >> "$MD"
             echo "" >> "$MD"
-            if ! npx --yes --package=github:databricks-solutions/lakebase-scm-utils#"${SCM_UTILS_REF}" \
+            if ! npx --yes --package="${SCM_UTILS_NPX_PKG}" \
                  lakebase-schema-diff \
                  --instance "$LAKEBASE_PROJECT_ID" \
                  --branch "$BRANCH" \

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/lk

@@ -1,9 +1,11 @@
 #!/usr/bin/env bash
 # lk , run a substrate/SCM or SFTDD CLI fast, without the npx tax.
 #
-# `npx --package=github:databricks-solutions/<pkg>#<ref> <bin>` re-resolves the
-# GitHub ref on EVERY call (~3.5s even warm). This shim resolves a package ONCE
-# per ref into a shared cache and runs the bin via `node dist/...` (~0.09s).
+# `npx --package=<pkg>@<version> <bin>` re-resolves on EVERY call (~3.5s even
+# warm). This shim resolves a package ONCE per ref into a shared cache and runs
+# the bin via `node dist/...` (~0.09s). Cold-cache installs pull the published
+# tarball from the npm registry for version-tag refs (seconds; GitHub is the
+# fallback) and clone+install from GitHub for branch/SHA refs (their only source).
 #
 # Two packages back a scaffolded project, and lk routes each bin to its owner so
 # each runs from its OWN dist (no cross-package node_modules paths):
@@ -110,27 +112,20 @@ resolve_pkg() {
     node -e 'const fs=require("fs"),p=require("path"),r=process.argv[1];let b={};try{b=(require(r+"/package.json").bin)||{}}catch(e){process.stderr.write("lk: cannot read package.json at "+r+"\n");process.exit(1)}const m=Object.values(b).filter(x=>!fs.existsSync(p.join(r,x)));if(m.length){process.stderr.write("lk: "+r+" dist is INCOMPLETE , "+m.length+"/"+Object.keys(b).length+" bin(s) have no file (e.g. "+m.slice(0,3).join(", ")+").\n");process.exit(1)}' "$1"
   }
 
-  install_pkg() {
-    local committish="$1" sha="$2" tmp
-    mkdir -p "$cache_root"
-    tmp="$(mktemp -d "${cache_root}/.tmp.XXXXXX")"
-    # Tell the consumer what is happening: this is a full npm install from git and
-    # takes a couple minutes over the network the FIRST time a ref is cached (the
-    # kit + its runtime deps). Without this, a silent multi-minute install looks
-    # hung. `--omit=dev` skips the build-toolchain devDeps (tsup/vitest/typescript/
-    # esbuild) , the kit ships prebuilt dist/, so consumers never build; `--no-audit
-    # --no-fund` drop registry round-trips. npm's own progress goes to stderr (>&2)
-    # so an interactive warm/rewarm narrates instead of going dark.
-    echo "lk: Downloading the Consort toolkit (${pkg}@${committish}) , one-time for this version, ~1-2 min (kit + its dependencies). Later commands are instant." >&2
-    # SHOW WHAT IS BEING INSTALLED , not just a clock. npm's progress bar is TTY-only
-    # (silent when piped to a log for the relay), but `--loglevel=http` prints one line
-    # per package fetched (`npm http fetch GET 200 …/<pkg>/-/<pkg>-<ver>.tgz`) , exactly
-    # "what is being installed". We run npm to a temp log and FORWARD its new lines
-    # (prefixed `lk:` so the narrator relays them) every few seconds as they land; only
-    # when npm is briefly between fetches (e.g. the initial git clone) do we print an
-    # elapsed-time line. So the relay never goes silent and never looks like a timeout.
+  # npm_install_with_progress <spec>: install <spec> into $tmp in the background
+  # while narrating. `--omit=dev` skips the build-toolchain devDeps (tsup/vitest/
+  # typescript/esbuild) , the kit ships prebuilt dist/, so consumers never build;
+  # `--no-audit --no-fund` drop registry round-trips. SHOW WHAT IS BEING INSTALLED,
+  # not just a clock: npm's progress bar is TTY-only (silent when piped to a log
+  # for the relay), but `--loglevel=http` prints one line per package fetched, so
+  # we FORWARD its new lines (prefixed `lk:`) every few seconds as they land; only
+  # when npm is briefly between fetches (e.g. a git clone) do we print an elapsed
+  # line. The relay never goes silent and never looks like a timeout. Returns
+  # npm's exit status.
+  npm_install_with_progress() {
+    local spec="$1"
     local npmlog; npmlog="$(mktemp)"
-    npm install --loglevel=http --no-save --prefer-online --omit=dev --no-audit --no-fund --prefix "$tmp" "${gh}#${committish}" > "$npmlog" 2>&1 &
+    npm install --loglevel=http --no-save --prefer-online --omit=dev --no-audit --no-fund --prefix "$tmp" "$spec" > "$npmlog" 2>&1 &
     local npm_pid=$! start last cur
     start=$(date +%s); last=0
     while kill -0 "$npm_pid" 2>/dev/null; do
@@ -140,22 +135,60 @@ resolve_pkg() {
         tail -c "+$((last + 1))" "$npmlog" | sed 's/^/lk: /' >&2   # forward the real npm progress
         last="$cur"
       else
-        echo "lk: … still installing the Consort TOOLKIT itself (the kit — one-time per version, cached + reused across projects) ($(( $(date +%s) - start ))s elapsed; ~1-2 min typical)…" >&2
+        echo "lk: … still installing the Consort TOOLKIT itself (the kit — one-time per version, cached + reused across projects) ($(( $(date +%s) - start ))s elapsed)…" >&2
       fi
     done
-    # Flush any final lines npm wrote between the last poll and exit, then drop the log
-    # (all branches below are covered , no leaked temp on success OR failure).
+    # Flush any final lines npm wrote between the last poll and exit, then drop the
+    # log (all branches below are covered , no leaked temp on success OR failure).
     cur=$(wc -c < "$npmlog" 2>/dev/null || echo 0)
     [ "$cur" -gt "$last" ] && tail -c "+$((last + 1))" "$npmlog" | sed 's/^/lk: /' >&2
     rm -f "$npmlog"
-    if wait "$npm_pid" && [ -d "${tmp}/node_modules/${pkg}/dist" ]; then
-      rm -rf "$cache"
-      if mv "$tmp" "$cache" 2>/dev/null; then
-        [ -n "$sha" ] && printf '%s\n' "$sha" > "${cache}/.pkg-sha" 2>/dev/null || true
-        echo "lk: Consort toolkit ready (${pkg}@${committish}; subsequent commands are instant)." >&2
-        return 0
+    wait "$npm_pid"
+  }
+
+  # finalize_install <committish> <sha>: promote a completed $tmp install into the
+  # version-keyed cache slot.
+  finalize_install() {
+    local committish="$1" sha="$2"
+    rm -rf "$cache"
+    if mv "$tmp" "$cache" 2>/dev/null; then
+      [ -n "$sha" ] && printf '%s\n' "$sha" > "${cache}/.pkg-sha" 2>/dev/null || true
+      echo "lk: Consort toolkit ready (${pkg}@${committish}; subsequent commands are instant)." >&2
+      return 0
+    fi
+    rm -rf "$tmp"; return 1
+  }
+
+  install_pkg() {
+    local committish="$1" sha="$2" tmp
+    mkdir -p "$cache_root"
+    tmp="$(mktemp -d "${cache_root}/.tmp.XXXXXX")"
+    # Tell the consumer what is happening: without narration a cold-cache install
+    # looks hung (a GitHub install takes a couple of minutes the FIRST time a ref
+    # is cached; a registry install is seconds).
+    echo "lk: Downloading the Consort toolkit (${pkg}@${committish}) , one-time for this version. Later commands are instant." >&2
+    # Registry-first for immutable version tags (v0.2.40 -> ${pkg}@0.2.40): a
+    # registry tarball lands in seconds (no git clone, no build). GitHub stays the
+    # fallback (e.g. a tag not yet published) and is the only path for branch/SHA
+    # refs, which the registry never has.
+    local ver=""
+    if [ "$is_sha" -eq 0 ]; then
+      case "$ref" in
+        v[0-9]*) ver="${ref#v}" ;;
+        [0-9]*)  ver="$ref" ;;
+      esac
+    fi
+    if [ -n "$ver" ]; then
+      if npm_install_with_progress "${pkg}@${ver}" && [ -d "${tmp}/node_modules/${pkg}/dist" ]; then
+        finalize_install "$committish" "$sha"
+        return $?
       fi
-      rm -rf "$tmp"; return 1
+      echo "lk: registry install of ${pkg}@${ver} did not complete; falling back to GitHub (${gh}#${committish})." >&2
+      rm -rf "$tmp"; tmp="$(mktemp -d "${cache_root}/.tmp.XXXXXX")"
+    fi
+    if npm_install_with_progress "${gh}#${committish}" && [ -d "${tmp}/node_modules/${pkg}/dist" ]; then
+      finalize_install "$committish" "$sha"
+      return $?
     fi
     rm -rf "$tmp"; return 1
   }

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