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

package/dist/scripts/index.cjs

@@ -88895,8 +88895,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/index.js

@@ -9700,8 +9700,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/ci-resolve-branch.cli.cjs

@@ -79609,8 +79609,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/ci-resolve-branch.cli.js

@@ -701,8 +701,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/collapse-heads.cli.cjs

@@ -79270,8 +79270,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/collapse-heads.cli.js

@@ -373,8 +373,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/detect-language.cli.cjs

@@ -79270,8 +79270,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/detect-language.cli.js

@@ -373,8 +373,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/doctor.cli.cjs

@@ -79362,8 +79362,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/doctor.cli.js

@@ -464,8 +464,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/get-connection.cli.cjs

@@ -79265,8 +79265,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/get-connection.cli.js

@@ -369,8 +369,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/index.cjs

@@ -81566,8 +81566,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/index.js

@@ -2498,8 +2498,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/infra-runner.cli.cjs

@@ -79270,8 +79270,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/infra-runner.cli.js

@@ -373,8 +373,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/new-migration.cli.cjs

@@ -79270,8 +79270,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/new-migration.cli.js

@@ -373,8 +373,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/schema-diff.cli.cjs

@@ -79268,8 +79268,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/schema-diff.cli.js

@@ -369,8 +369,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/schema-migrate.cli.cjs

@@ -79304,8 +79304,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/schema-migrate.cli.js

@@ -407,8 +407,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-claim-feature.cli.cjs

@@ -79763,8 +79763,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/dist/scripts/lakebase/scm-claim-feature.cli.js

@@ -844,8 +844,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -88187,8 +88187,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -9340,8 +9340,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -88153,8 +88153,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -9306,8 +9306,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -79268,8 +79268,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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

@@ -369,8 +369,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.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

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.40".length > 0) {
-    cached = "0.2.40";
+  if ("0.2.41".length > 0) {
+    cached = "0.2.41";
     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.2.40".length > 0) {
-    cached = "0.2.40";
+  if ("0.2.41".length > 0) {
+    cached = "0.2.41";
     return cached;
   }
   cached = "unknown";

package/package.json

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