@kungfu-tech/buildchain 2.11.14-alpha.4 → 2.11.14-alpha.6

package/dist/site/public-surface-audit.json

@@ -413,6 +413,7 @@
           "buildchain-repository",
           "checkout-cache-fallback",
           "checkout-cache-fetch-attempts",
+          "checkout-cache-github-timeout-seconds",
           "checkout-cache-mirror-url-template",
           "checkout-cache-mode",
           "checkout-cache-reference-repository-template",
@@ -443,7 +444,7 @@
           "verify-command",
           "working-directory"
         ],
-        "inputCount": 49
+        "inputCount": 50
       },
       {
         "id": ".bump-minor-version",
@@ -2539,8 +2540,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "3c0729f5351eb82fe26625fa5aabf30903f45f68af2431e02860f85ada468ac9",
-    "workflowRegistryDigest": "7052aa984ab49647ce2c9f96669caa32f92da57d8b2e506ac172089bedd793cf",
-    "pageRegistryDigest": "61593cdf75b8e38e825b78e733d00da0f7ce54d9bbcf2eb646037eaecd42e9c7"
+    "workflowRegistryDigest": "0fc20324b4154e352176378665daecb3cb7a74179796e3777eb2f6fc93a50092",
+    "pageRegistryDigest": "51d61683cd241eb9f5e693dcbff5bb4c7589fba194bc6bf1c8ca550007b561e3"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-10T13:58:52.360Z",
-  "publishedAt": "2026-07-10T13:58:52.360Z",
+  "generatedAt": "2026-07-10T16:41:11.001Z",
+  "publishedAt": "2026-07-10T16:41:11.001Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "94327df75abe657d53fe6b2d1137af68fb37d53c",
+  "sourceRevision": "4bbf92ba595952dbd22f8656829928991e84f448",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.4",
+    "version": "2.11.14-alpha.6",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-model.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-release-model",
   "exactTags": "v-prefixed exact tags are immutable release records.",
-  "floatingTags": "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
+  "floatingTags": "vX, vX-alpha, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions; vX-alpha follows the highest minor in major X with a published alpha.",
   "channelBranches": [
     "dev/vX/vX.Y",
     "alpha/vX/vX.Y",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-10T13:58:52.360Z",
-  "publishedAt": "2026-07-10T13:58:52.360Z",
+  "generatedAt": "2026-07-10T16:41:11.001Z",
+  "publishedAt": "2026-07-10T16:41:11.001Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "94327df75abe657d53fe6b2d1137af68fb37d53c",
+  "sourceRevision": "4bbf92ba595952dbd22f8656829928991e84f448",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.4",
+    "version": "2.11.14-alpha.6",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:7dc5b9adc5f23456ddc3a3f7c46f2cdf3ddd38d9546a45267291ba3fe567e0c9"
+      "digest": "sha256:53b605e57a5ac2b8d4ed911a4fbb4d1a39352db143db183aa551f9226f2d7a6a"
     },
     {
       "id": "install",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4f3699841c5a189d199db045d526b11f76ad0dff1464d6a63ca98ceadf1bb215"
+      "digest": "sha256:b9335434f95e6173f31d50983f8ab492378b065fa203a3b68bee447487883cea"
     },
     {
       "id": "publish-transaction",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:00b5e4c3ffd91d3f050a6e880f76dd36716660a731db029f636b372707ee3910"
+      "digest": "sha256:8a70f9f2699bcec6102164d6ae67f13549f3ef962d12441fbb80f9d49a1cc2e1"
     },
     {
       "id": "release-flow",
@@ -229,7 +229,7 @@
       "path": "docs/release-flow.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:5b855ab3863e197b2ab257536b1f3ff85c79bca1fe962c45089b3f4c5ab81189"
+      "digest": "sha256:c05905de6a905d1ce0dd977986175b8bc1ad908c6c2eee946809693ea2cb91de"
     },
     {
       "id": "runtime-train-validation",

package/dist/site/workflow-registry.json

@@ -27,6 +27,7 @@
         "buildchain-repository",
         "checkout-cache-fallback",
         "checkout-cache-fetch-attempts",
+        "checkout-cache-github-timeout-seconds",
         "checkout-cache-mirror-url-template",
         "checkout-cache-mode",
         "checkout-cache-reference-repository-template",
@@ -57,7 +58,7 @@
         "verify-command",
         "working-directory"
       ],
-      "inputCount": 49,
+      "inputCount": 50,
       "surface": "reusable-workflow",
       "capabilityGroup": "api-cli-reference",
       "status": "active"

package/docs/MAP.md

@@ -111,7 +111,7 @@ replace them.
 
 - **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)
   and [`migration-inventory.md`](migration-inventory.md).
-- **v2 / v2.0 / v2.0-alpha / exact tags / floating tags** ->
+- **v2 / v2-alpha / v2.0 / v2.0-alpha / exact tags / floating tags** ->
   [`release-governance.md`](release-governance.md) and
   [`release-flow.md`](release-flow.md).
 - **v2.1 vs v2.2 / when to open a new minor line** ->

package/docs/release-flow.md

@@ -53,6 +53,7 @@ for the versioned policy and evidence contract.
 | Exact alpha tag | `v2.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
 | Exact release tag | `v2.0.2` | immutable | audit ref for one production release |
 | Floating alpha tag | `v2.0-alpha` | moves | latest test channel for a minor line |
+| Floating major alpha tag | `v2-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
 | Floating minor tag | `v2.0` | moves | latest production patch on a minor line |
 | Floating major tag | `v2` | moves | selected stable major entrypoint |
 
@@ -68,8 +69,8 @@ refs/tags/v*.*.*
 ```
 
 Do not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain
-must be able to update floating channel tags such as `v2`, `v2.0`, and
-`v2.0-alpha` after the exact tag and publish evidence are valid. A ruleset that
+must be able to update floating channel tags such as `v2`, `v2.0`, `v2.0-alpha`,
+and `v2-alpha` after the exact tag and publish evidence are valid. A ruleset that
 matches all `v*` tags also matches floating tags, so release finalization can
 fail with GitHub protected-ref errors even though the exact release tag and
 published artifacts are already durable.
@@ -77,7 +78,7 @@ published artifacts are already durable.
 The intended governance split is:
 
 - exact tags such as `v2.0.14` and `v2.0.15-alpha.0` are immutable audit refs;
-- floating tags such as `v2`, `v2.0`, and `v2.0-alpha` are mutable channel refs
+- floating tags such as `v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
@@ -134,6 +135,7 @@ sequenceDiagram
   Promote->>Promote: write and verify version state
   Promote->>Tags: create or reuse vX.Y.Z-alpha.N
   Promote->>Tags: move vX.Y-alpha
+  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor
   Promote->>Alpha: move alpha/vX/vX.Y
   Promote->>Dev: move dev/vX/vX.Y
 ```
@@ -143,6 +145,7 @@ Result:
 ```text
 vX.Y.Z-alpha.N
 vX.Y-alpha
+vX-alpha when X.Y is the highest published alpha minor
 alpha/vX/vX.Y
 dev/vX/vX.Y
 ```
@@ -177,6 +180,7 @@ sequenceDiagram
   Promote->>Promote: prepare vX.Y.(Z+1)-alpha.0
   Promote->>Tags: create or reuse vX.Y.(Z+1)-alpha.0
   Promote->>Tags: move vX.Y-alpha
+  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor
   Promote->>Alpha: move alpha/vX/vX.Y
   Promote->>Dev: move dev/vX/vX.Y
 ```
@@ -195,6 +199,7 @@ point at the production version-state commit, while:
 ```text
 vX.Y.(Z+1)-alpha.0
 vX.Y-alpha
+vX-alpha when X.Y is the highest published alpha minor
 alpha/vX/vX.Y
 dev/vX/vX.Y
 ```
@@ -235,6 +240,7 @@ It should also prepare:
 ```text
 v2.0.3-alpha.0          exact next alpha tag
 v2.0-alpha              floating alpha tag
+v2-alpha                floating major alpha tag when v2.0 is the highest published alpha minor
 alpha/v2/v2.0           alpha channel branch
 dev/v2/v2.0             development channel branch
 ```

package/docs/release-governance.md

@@ -128,13 +128,14 @@ This is why Buildchain maintains both exact and floating refs:
 - `v2` is the selected stable major-line entrypoint;
 - `v2.0.3-alpha.0` is immutable alpha evidence;
 - `v2.0-alpha` is the latest test channel for the `2.0` line.
+- `v2-alpha` is the latest test channel on the highest published alpha minor in major `2`.
 
 A release does not mean "minor is complete." It means "this patch on this minor
 line is now production."
 
 GitHub repository rules must preserve that distinction. Exact tags such as
 `v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as
-`v2`, `v2.0`, and `v2.0-alpha` must remain movable by the Buildchain promotion
+`v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` must remain movable by the Buildchain promotion
 token after governance checks and publish evidence pass. A tag ruleset that
 protects every `refs/tags/v*` ref is too broad because it also locks the
 floating channel tags that Buildchain is required to update. Prefer exact-tag
@@ -159,9 +160,12 @@ Buildchain then:
 6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a
    fast-forward update.
 7. Moves `vX.Y-alpha` to the same generated alpha commit.
+8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.
 
 This keeps the test channel self-describing. If a consumer checks out
-`v2.0-alpha`, the manifests and exact alpha tag agree.
+`v2.0-alpha` or `v2-alpha`, the manifests and exact alpha tag agree. The major
+alpha ref removes routine consumer edits when Buildchain opens a newer minor,
+while exact tags and SHAs remain the reproducible audit choice.
 
 If `dev/vX/vX.Y` has already advanced before generated alpha version-state
 bookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the
@@ -201,6 +205,7 @@ Buildchain then:
    `vX.Y.(Z+1)-alpha.0`.
 10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha
     commit.
+11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.
 
 The production channel and the test channel therefore intentionally diverge
 after release: production stays on the release commit, while alpha/dev continue
@@ -513,6 +518,7 @@ When the loop succeeds, maintainers and consumers can rely on these facts:
   not a hidden manual button;
 - every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;
 - every alpha minor line has a floating tag such as `v2.0-alpha`;
+- every major with a published alpha has a cross-minor floating tag such as `v2-alpha`, owned by its highest published alpha minor;
 - version manifests match the tag visible from the same commit;
 - production releases are derived from the alpha tree that was tested;
 - manual non-dry-run promotion cannot bypass PR review and verification;

package/docs/reusable-build-surface.md

@@ -233,6 +233,7 @@ jobs:
       checkout-cache-reference-repository-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE }}
       checkout-cache-fallback: github
       checkout-cache-timeout-seconds: 60
+      checkout-cache-github-timeout-seconds: 600
       checkout-cache-fetch-attempts: 3
 ```
 
@@ -256,10 +257,16 @@ Do not read cache URLs or reference paths from PR-controlled files such as
 `.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org
 variables. Buildchain does not pass GitHub credentials to cache mirrors or
 reference repositories. If it must fall back to GitHub, the workflow token is
-used only for the GitHub fetch path. Retryable timeout and transient network
-failures use the bounded `checkout-cache-fetch-attempts` budget; permanent
-failures stop immediately. Diagnostics record the configured budget and actual
-GitHub fetch attempts before exact HEAD/tree verification.
+used only for the GitHub fetch path. Cache attempts use
+`checkout-cache-timeout-seconds`; the potentially larger GitHub fallback uses
+the independent `checkout-cache-github-timeout-seconds` budget (600 seconds by
+default). Buildchain fetches the advertised source ref before trying an exact
+SHA, so a cache hit or stale-cache seed can contribute objects and the fallback
+does not first waste a full timeout on an unadvertised SHA. Retryable timeout
+and transient network failures use the bounded `checkout-cache-fetch-attempts`
+budget; permanent failures stop immediately. Diagnostics record both timeout
+budgets and the actual GitHub fetch attempts before exact HEAD/tree
+verification.
 
 Each platform diagnostics artifact includes `source-checkout.json` and embeds a
 compact `sourceCheckout` summary in `diagnostics.json`: mode, transport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.14-alpha.4",
+  "version": "2.11.14-alpha.6",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/release-line-dry-run.js

@@ -23,7 +23,7 @@ function parseTags(input) {
     : String(input || "").split(",").map((tag) => tag.trim()).filter(Boolean);
   for (const tag of tags) {
     if (
-      !/^v\d+$|^v\d+\.\d+$|^v\d+\.\d+-alpha$|^v\d+\.\d+\.\d+$|^v\d+\.\d+\.\d+-alpha\.\d+$/.test(tag)
+      !/^v\d+$|^v\d+-alpha$|^v\d+\.\d+$|^v\d+\.\d+-alpha$|^v\d+\.\d+\.\d+$|^v\d+\.\d+\.\d+-alpha\.\d+$/.test(tag)
     ) {
       throw new Error(`Unsupported buildchain dry-run tag: ${tag}`);
     }
@@ -42,6 +42,7 @@ function getPromotionRule(targetRef, sourceRef = "") {
       sourceRef: sourceRef || "release/vN/vN.M",
       releasePrefix: nextMajor ? `v${nextMajor}.0` : "v(N+1).0",
       majorTag: nextMajor ? `v${nextMajor}` : "v(N+1)",
+      majorAlphaTag: nextMajor ? `v${nextMajor}-alpha` : "v(N+1)-alpha",
       minorTag: nextMajor ? `v${nextMajor}.0` : "v(N+1).0",
       alphaTag: nextMajor ? `v${nextMajor}.0-alpha` : "v(N+1).0-alpha",
       exactReleasePattern: nextMajor ? `v${nextMajor}.0.0` : "v(N+1).0.0",
@@ -69,6 +70,7 @@ function getPromotionRule(targetRef, sourceRef = "") {
     minor,
     releasePrefix,
     majorTag: `v${major}`,
+    majorAlphaTag: `v${major}-alpha`,
     minorTag: releasePrefix,
     alphaTag: `${releasePrefix}-alpha`,
     sourceRef: channel === "alpha" ? `dev/v${major}/v${major}.${minor}` : `alpha/v${major}/v${major}.${minor}`,
@@ -193,7 +195,10 @@ function explainReleaseLineDryRun({
       kind: "alpha",
       action: "would create or reuse immutable alpha evidence tag",
     });
-    plan.floatingRefs.push({ ref: rule.alphaTag, kind: "tag", action: "would move to alpha version-state commit" });
+    plan.floatingRefs.push(
+      { ref: rule.alphaTag, kind: "tag", action: "would move to alpha version-state commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move when this is the highest published alpha minor" },
+    );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to alpha version-state commit" },
       { ref: `dev/v${rule.major}/v${rule.major}.${rule.minor}`, action: "would align dev with the published alpha state" },
@@ -211,6 +216,7 @@ function explainReleaseLineDryRun({
       { ref: rule.minorTag, kind: "tag", action: "would move to production release commit" },
       { ref: rule.majorTag, kind: "tag", action: "would move when no newer minor line owns the major tag" },
       { ref: rule.alphaTag, kind: "tag", action: "would move to next alpha version-state commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move when this is the highest published alpha minor" },
     );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to production release commit" },
@@ -234,6 +240,7 @@ function explainReleaseLineDryRun({
       { ref: rule.minorTag, kind: "tag", action: "would move to next-major release commit" },
       { ref: rule.majorTag, kind: "tag", action: "would move to next-major release commit" },
       { ref: rule.alphaTag, kind: "tag", action: "would move to next-major alpha commit" },
+      { ref: rule.majorAlphaTag, kind: "tag", action: "would move to next-major alpha commit" },
     );
     plan.branchUpdates.push(
       { ref: targetRef, action: "would move to next-major release commit" },

package/scripts/generate-site-bundle.mjs

@@ -872,7 +872,7 @@ function buildSiteBundle() {
     schemaVersion: 1,
     contract: "kungfu-buildchain-release-model",
     exactTags: "v-prefixed exact tags are immutable release records.",
-    floatingTags: "vX, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions.",
+    floatingTags: "vX, vX-alpha, vX.Y, and vX.Y-alpha are channel pointers updated by Buildchain transactions; vX-alpha follows the highest minor in major X with a published alpha.",
     channelBranches: ["dev/vX/vX.Y", "alpha/vX/vX.Y", "release/vX/vX.Y", "publish-gate/major"],
     protectedDevelopmentBranches: ["dev/vX/vX.Y"],
     releasePassport: {

package/scripts/locked-source-checkout.mjs

@@ -182,35 +182,64 @@ function checkoutFetchedCommit(targetPath, sha, timeoutMs) {
   git(["checkout", "--force", "--detach", sha], { cwd: targetPath, timeoutMs });
 }
 
-function fetchSha({ targetPath, remoteName, remoteUrl, sha, fetchRef, timeoutMs, env = {} }) {
+function retryableGitFetchError(error) {
+  const code = String(error?.code || "").toUpperCase();
+  if (["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "EPIPE"].includes(code)) return true;
+  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(String(error?.message || error || ""));
+}
+
+export function fetchSourceCommit({
+  targetPath,
+  remoteName,
+  remoteUrl,
+  sha,
+  fetchRef,
+  timeoutMs,
+  env = {},
+  runGit = git,
+  containsCommit = hasCommit,
+}) {
   try {
-    git(["remote", "remove", remoteName], { cwd: targetPath, timeoutMs, stdio: "ignore" });
+    runGit(["remote", "remove", remoteName], { cwd: targetPath, timeoutMs, stdio: "ignore" });
   } catch {
     // The remote is optional; a fresh checkout target will not have it yet.
   }
   try {
-    git(["remote", "add", remoteName, remoteUrl], { cwd: targetPath, timeoutMs });
+    runGit(["remote", "add", remoteName, remoteUrl], { cwd: targetPath, timeoutMs });
   } catch {
-    git(["remote", "set-url", remoteName, remoteUrl], { cwd: targetPath, timeoutMs });
+    runGit(["remote", "set-url", remoteName, remoteUrl], { cwd: targetPath, timeoutMs });
   }
-  const fetchArgs = ["fetch", "--no-tags", "--depth=1", remoteName, `+${sha}:refs/buildchain/source`];
-  try {
-    git(fetchArgs, { cwd: targetPath, timeoutMs, env, stdio: "ignore" });
-    return;
-  } catch (error) {
-    if (!fetchRef) {
-      throw error;
+
+  if (fetchRef) {
+    try {
+      runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${fetchRef}:refs/buildchain/source-ref`], {
+        cwd: targetPath,
+        timeoutMs,
+        env,
+        stdio: "ignore",
+      });
+      if (containsCommit(targetPath, sha, timeoutMs)) {
+        return { selector: "ref" };
+      }
+    } catch (error) {
+      // A retryable transport failure belongs to the bounded outer retry. Do
+      // not immediately spend the same timeout again on an unadvertised SHA.
+      if (retryableGitFetchError(error)) {
+        throw error;
+      }
     }
   }
-  git(["fetch", "--no-tags", "--depth=1", remoteName, `+${fetchRef}:refs/buildchain/source-ref`], {
+
+  runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${sha}:refs/buildchain/source`], {
     cwd: targetPath,
     timeoutMs,
     env,
     stdio: "ignore",
   });
-  if (!hasCommit(targetPath, sha, timeoutMs)) {
-    throw new Error(`fetched ${fetchRef}, but ${sha} is not available`);
+  if (!containsCommit(targetPath, sha, timeoutMs)) {
+    throw new Error(`fetched ${fetchRef || sha}, but ${sha} is not available`);
   }
+  return { selector: "sha" };
 }
 
 export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onRetry = () => {}, shouldRetry = () => true }) {
@@ -232,12 +261,6 @@ export function runBoundedFetch({ attempts = 1, fetch, onAttempt = () => {}, onR
   throw lastError;
 }
 
-function retryableGitFetchError(error) {
-  const code = String(error?.code || "").toUpperCase();
-  if (["ETIMEDOUT", "ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "ENETUNREACH", "EPIPE"].includes(code)) return true;
-  return /timed?\s*out|timeout|connection (?:reset|refused)|remote end hung up|early eof|rpc failed|http (?:429|5\d\d)|temporary failure|network is unreachable/i.test(String(error?.message || error || ""));
-}
-
 function githubRemoteUrl({ repository, serverUrl = "https://github.com" }) {
   const base = String(serverUrl || "https://github.com").replace(/\/+$/, "");
   return `${base}/${repository}.git`;
@@ -277,6 +300,7 @@ export function lockedSourceCheckout({
   referenceRepositoryTemplate = readEnv("BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE"),
   fallback = readEnv("BUILDCHAIN_CHECKOUT_CACHE_FALLBACK", "github"),
   timeoutSeconds = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_TIMEOUT_SECONDS", "60") || 60),
+  githubTimeoutSeconds = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_GITHUB_TIMEOUT_SECONDS", "600") || 600),
   fetchAttempts = Number(readEnv("BUILDCHAIN_CHECKOUT_CACHE_FETCH_ATTEMPTS", "3") || 3),
   diagnosticsPath = readEnv("BUILDCHAIN_SOURCE_CHECKOUT_DIAGNOSTICS_PATH", ".buildchain/diagnostics/source-checkout.json"),
   githubToken = readEnv("GITHUB_TOKEN"),
@@ -291,6 +315,7 @@ export function lockedSourceCheckout({
   const treeSha = sourceTreeSha ? assertSha(sourceTreeSha, "sourceTreeSha") : "";
   const repoParts = splitRepository(repository);
   const timeoutMs = Math.max(1, Number(timeoutSeconds || 60)) * 1000;
+  const githubTimeoutMs = Math.max(1, Number(githubTimeoutSeconds || 600)) * 1000;
   const normalizedFetchAttempts = Math.max(1, Math.floor(Number(fetchAttempts) || 3));
   const targetPath = ensureCheckoutTarget(checkoutPath, workspace);
   git(["init"], { cwd: targetPath, timeoutMs });
@@ -312,6 +337,7 @@ export function lockedSourceCheckout({
       mode: normalizedMode,
       fallback: normalizedFallback,
       timeoutSeconds: Math.max(1, Number(timeoutSeconds || 60)),
+      githubTimeoutSeconds: Math.max(1, Number(githubTimeoutSeconds || 600)),
       fetchAttempts: normalizedFetchAttempts,
       mirror: sanitizeIdentity(renderedMirrorUrl),
       referenceRepository: sanitizeIdentity(renderedReferenceRepository),
@@ -348,7 +374,7 @@ export function lockedSourceCheckout({
         checkoutFetchedCommit(targetPath, sha, timeoutMs);
       } else if (renderedMirrorUrl) {
         evidence.cache.transport = "mirror-url";
-        fetchSha({
+        fetchSourceCommit({
           targetPath,
           remoteName: "buildchain-cache",
           remoteUrl: renderedMirrorUrl,
@@ -384,7 +410,15 @@ export function lockedSourceCheckout({
     try {
       const fetchResult = runBoundedFetch({
         attempts: normalizedFetchAttempts,
-        fetch: () => fetchSha({ targetPath, remoteName: "origin", remoteUrl, sha, fetchRef, timeoutMs, env: githubAuthEnv(githubToken) }),
+        fetch: () => fetchSourceCommit({
+          targetPath,
+          remoteName: "origin",
+          remoteUrl,
+          sha,
+          fetchRef,
+          timeoutMs: githubTimeoutMs,
+          env: githubAuthEnv(githubToken),
+        }),
         onAttempt: ({ attempt }) => { evidence.cache.githubFetchAttempts = attempt; },
         onRetry: ({ attempt, limit, error }) => console.log(`buildchain: GitHub source fetch failed, retry ${attempt + 1}/${limit}: ${error.message}`),
         shouldRetry: retryableGitFetchError,