@applitools/core 4.60.0 → 4.61.1-debug.0

package/dist/utils/extract-git-info.js

@@ -26,12 +26,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractBranchLookupFallbackList = exports.isISODate = exports.extractBranchingTimestamp = exports.extractBuildIdFromCI = exports.extractCIBranchName = exports.extractGitRepo = exports.extractGitBranch = exports.extractLatestCommitInfo = exports.getPrimaryRemoteName = exports.cacheKey = void 0;
+exports.extractBranchLookupFallbackList = exports.getBranchAncestryByLocalBranches = exports.getBranchAncestryByCommits = exports.isISODate = exports.extractBranchingTimestamp = exports.extractBuildIdFromCI = exports.extractCIBranchName = exports.extractGitRepo = exports.extractGitBranch = exports.extractLatestCommitInfo = exports.extractDefaultBranch = exports.checkGitEnvironment = exports.getPrimaryRemoteName = exports.cacheKey = void 0;
 const utils = __importStar(require("@applitools/utils"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("@applitools/logger");
-// Check if debug mode is enabled for verbose git info logging
+/**
+ * Gate for verbose, deep-dive diagnostic logging in this file.
+ *
+ * Toggled by GitHub Actions' standard `RUNNER_DEBUG=1` env var (also settable
+ * locally for reproduction). When OFF, only high-signal log lines emit:
+ *   - which fallback path was taken
+ *   - errors and unusual states
+ *   - the final extracted value
+ * When ON, every per-branch / per-commit decision, every retry, and every
+ * `[PERF]` timing is also logged. Use this guard for anything noisy enough
+ * to bury the signal in CI logs.
+ */
 const isDebugMode = () => process.env.RUNNER_DEBUG === '1';
 exports.cacheKey = 'default';
 /**
@@ -54,7 +65,266 @@ exports.getPrimaryRemoteName = utils.general.cachify(async function ({ execOptio
         cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd,
     });
 });
+/**
+ * One-shot, cached probe of the full git environment, staged from cheapest
+ * to most expensive:
+ *   1. is `git` installed and on PATH?                       (`git --version`)
+ *   2. are we inside a git work tree?     (`git rev-parse --is-inside-work-tree`)
+ *   3. is a primary remote configured?                       (`git remote`)
+ *   4. is that remote reachable?                       (`git ls-remote <r> HEAD`)
+ *
+ * Use this as the outermost guard for any code path that shells out to git.
+ * Each step short-circuits later ones: missing binary skips repo/remote
+ * checks; non-repo skips remote checks; no remote configured skips the
+ * reachability probe. Callers should consult `ok` for local-only git
+ * features and `remoteAccessible` for anything that talks to the network.
+ *
+ * Cached per `cwd`. The first invocation emits a clearly-visible banner so
+ * support can grep one distinctive line — `APPLITOOLS GIT ENVIRONMENT CHECK`
+ * — and immediately tell which sub-check failed. Subsequent invocations
+ * return the cached verdict silently.
+ */
+exports.checkGitEnvironment = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)(), }) {
+    // INVARIANT: this function MUST NOT reject. It is cachified, so a rejected
+    // promise would be memoized and every one of the 11 downstream callers
+    // would re-throw on every subsequent call. Every path below either
+    // returns via `finalize()` (which itself can't throw — see below) or is
+    // caught by the outermost safety net at the bottom.
+    var _a, _b, _c, _d, _e, _f;
+    let gitInstalled = false;
+    let insideRepo = false;
+    let remoteAccessible = false;
+    let remoteName;
+    const reasons = [];
+    /**
+     * Build the result, emit the banner, and return. Defensive: even if the
+     * underlying logger throws (e.g. a wrapped transport with a bug), the
+     * banner call is swallowed so this function still returns a usable
+     * `GitEnvironmentResult`.
+     */
+    const finalize = (extraReason) => {
+        if (extraReason)
+            reasons.push(extraReason);
+        const result = {
+            gitInstalled,
+            insideRepo,
+            remoteAccessible,
+            ok: gitInstalled && insideRepo,
+            reason: reasons.length ? reasons.join('; ') : 'ok',
+            remoteName,
+        };
+        try {
+            logGitEnvironmentBanner(logger, result);
+        }
+        catch {
+            // Logger failures must NEVER make the env check itself fail.
+        }
+        return result;
+    };
+    try {
+        try {
+            // 1. Is git itself installed? `git --version` is the cheapest sanity check.
+            //    Non-fatal: any failure here returns via `finalize` with a clean result.
+            const versionResult = await executeWithLog('git --version', { execOptions, logger });
+            if (versionResult.code !== 0) {
+                return finalize(`git binary: ${((_a = versionResult.stderr) === null || _a === void 0 ? void 0 : _a.trim()) || `exit ${versionResult.code} (command not found?)`}`);
+            }
+            gitInstalled = true;
+            // 2. Are we inside a git work tree? Non-fatal — falls through to finalize.
+            const repoResult = await executeWithLog('git rev-parse --is-inside-work-tree', { execOptions, logger });
+            if (repoResult.code !== 0 || repoResult.stdout.trim() !== 'true') {
+                return finalize(`repo: ${((_b = repoResult.stderr) === null || _b === void 0 ? void 0 : _b.trim()) || 'not inside a git work tree'}`);
+            }
+            insideRepo = true;
+            // 3. Is any remote configured? Non-fatal — falls through to finalize.
+            const remotesResult = await executeWithLog('git remote', { execOptions, logger });
+            const remotesText = remotesResult.stdout.trim();
+            if (remotesResult.code !== 0 || !remotesText) {
+                return finalize(`remote: ${((_c = remotesResult.stderr) === null || _c === void 0 ? void 0 : _c.trim()) || 'no remote configured'}`);
+            }
+            const remotes = remotesText.split(/\s+/).filter(Boolean);
+            // `remotes` always has ≥1 element here because `remotesText` is non-empty
+            // and split+filter on a non-empty string yields at least one element.
+            remoteName = remotes.includes('origin') ? 'origin' : remotes[0];
+            // 4. Can we reach the remote? Non-fatal — falls through to finalize.
+            const probe = await executeWithLog(`git ls-remote ${remoteName} HEAD`, { execOptions, logger });
+            if (probe.code !== 0) {
+                return finalize(`remote: ${((_d = probe.stderr) === null || _d === void 0 ? void 0 : _d.trim()) || `ls-remote exit ${probe.code}`}`);
+            }
+            remoteAccessible = true;
+            return finalize();
+        }
+        catch (err) {
+            // Catches `executeWithLog` rejections (e.g. spawn ENOENT when the git
+            // binary is missing entirely). Falls through to a clean finalize.
+            return finalize(`probe threw: ${(_e = err === null || err === void 0 ? void 0 : err.message) !== null && _e !== void 0 ? _e : err}`);
+        }
+    }
+    catch (catastrophic) {
+        // Absolute last-resort safety net. Should never fire — `finalize` is
+        // designed not to throw — but if anything truly unexpected happens
+        // (out-of-memory, logger-throw-past-our-guard, etc.), return a
+        // synthetic "all-failed" result rather than rejecting the promise.
+        return {
+            gitInstalled: false,
+            insideRepo: false,
+            remoteAccessible: false,
+            ok: false,
+            reason: `checkGitEnvironment catastrophic failure: ${(_f = catastrophic === null || catastrophic === void 0 ? void 0 : catastrophic.message) !== null && _f !== void 0 ? _f : catastrophic}`,
+            remoteName: undefined,
+        };
+    }
+}, args => { var _a, _b; return ({ cwd: (_b = (_a = args[0]) === null || _a === void 0 ? void 0 : _a.execOptions) === null || _b === void 0 ? void 0 : _b.cwd }); });
+/**
+ * Unified, grep-friendly banner. The `APPLITOOLS GIT ENVIRONMENT CHECK`
+ * prefix is unique to this codepath, so support can find one line in any
+ * log and read off the entire environment verdict at a glance.
+ */
+function logGitEnvironmentBanner(logger, r) {
+    const sep = '============================================================';
+    const allGood = r.gitInstalled && r.insideRepo && r.remoteAccessible;
+    // Header — names the first failed sub-check (or "all ok").
+    logger.log(sep);
+    if (allGood) {
+        logger.log('APPLITOOLS GIT ENVIRONMENT CHECK ✓ all ok');
+    }
+    else if (!r.gitInstalled) {
+        logger.log('APPLITOOLS GIT ENVIRONMENT CHECK ✗ GIT NOT INSTALLED');
+    }
+    else if (!r.insideRepo) {
+        logger.log('APPLITOOLS GIT ENVIRONMENT CHECK ✗ NOT IN A GIT REPOSITORY');
+    }
+    else if (!r.remoteAccessible) {
+        logger.log('APPLITOOLS GIT ENVIRONMENT CHECK ✗ REMOTE NOT ACCESSIBLE');
+    }
+    // Per-condition status lines — show every sub-check that was reached so
+    // a reader can see at a glance which stage went wrong.
+    logger.log(`  git binary:  ${r.gitInstalled ? '✓ installed' : '✗ NOT FOUND'}`);
+    if (r.gitInstalled) {
+        logger.log(`  repo:        ${r.insideRepo ? '✓ inside work tree' : '✗ NOT INSIDE A WORK TREE'}`);
+    }
+    if (r.gitInstalled && r.insideRepo) {
+        const remoteLine = r.remoteAccessible
+            ? `✓ accessible (${r.remoteName})`
+            : r.remoteName
+                ? `✗ NOT ACCESSIBLE (${r.remoteName})`
+                : '✗ NONE CONFIGURED';
+        logger.log(`  remote:      ${remoteLine}`);
+    }
+    // Reason + remediation hints — only for the failure mode that triggered.
+    if (!allGood) {
+        logger.log(`  reason:      ${r.reason}`);
+        if (!r.gitInstalled) {
+            logger.log('  → All git-based SCM features will be SKIPPED.');
+            logger.log('  → Install git or add it to PATH to enable branch detection and baseline inheritance.');
+        }
+        else if (!r.insideRepo) {
+            logger.log('  → All git-based SCM features will be SKIPPED.');
+            logger.log('  → Run this from inside a git working tree to enable branch detection.');
+        }
+        else if (!r.remoteAccessible) {
+            logger.log('  → All remote-dependent fallbacks will be SKIPPED.');
+            logger.log('  → Branch lookup may be incomplete. Verify network / credentials / remote config.');
+        }
+    }
+    logger.log(sep);
+}
+/**
+ * Programmatically detect the default branch of the current repository.
+ *
+ * Fallback chain (each step short-circuits on success; never throws):
+ *   1. `APPLITOOLS_DEFAULT_BRANCH` env var — explicit user override.
+ *   2. `git symbolic-ref --short refs/remotes/<remote>/HEAD` — authoritative
+ *      source on any clone that has fetched at least once. Returns e.g.
+ *      `origin/master`; the `<remote>/` prefix is stripped.
+ *   3. `git ls-remote --symref <remote> HEAD` — works even when the local
+ *      `refs/remotes/<remote>/HEAD` symref was never set up (single-branch
+ *      clones, older git on CI).
+ *   4. `git config --get init.defaultBranch` — honors a user-global preference
+ *      if everything else fails.
+ *   5. Literal `'main'` — last resort.
+ *
+ * Steps 2 and 3 catch non-standard defaults (e.g. JFrog's
+ * `JFROG/artifactory-mfe/preRelease/jfmfe-1.995.x-rc`). Cached per `cwd`
+ * to match `getPrimaryRemoteName`.
+ */
+exports.extractDefaultBranch = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)() }) {
+    var _a;
+    // 1. Explicit env override — works even without git installed / outside a repo.
+    const envOverride = (_a = process.env.APPLITOOLS_DEFAULT_BRANCH) === null || _a === void 0 ? void 0 : _a.trim();
+    if (envOverride) {
+        logger.log(`extractDefaultBranch: using APPLITOOLS_DEFAULT_BRANCH="${envOverride}"`);
+        return envOverride;
+    }
+    // Function-entry env gate. All remaining steps (2–4) shell out to git;
+    // if git isn't installed or we're not in a repo, skip straight to 'main'.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log("extractDefaultBranch: git environment not ok, falling back to 'main'");
+        return 'main';
+    }
+    const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+    // 2. git symbolic-ref --short refs/remotes/<remote>/HEAD
+    try {
+        const r = await executeWithLog(`git symbolic-ref --short refs/remotes/${remoteName}/HEAD`, {
+            execOptions,
+            logger,
+        });
+        if (!r.stderr && r.stdout.trim()) {
+            const out = r.stdout.trim();
+            const normalized = out.replace(new RegExp(`^${remoteName}/`), '');
+            if (normalized) {
+                logger.log(`extractDefaultBranch: resolved via symbolic-ref -> "${normalized}"`);
+                return normalized;
+            }
+        }
+    }
+    catch (err) {
+        // Expected when the symref isn't set up (e.g. fresh single-branch clone). Verbose-only.
+        if (isDebugMode())
+            logger.log('extractDefaultBranch: symbolic-ref step failed, continuing', err);
+    }
+    // 3. git ls-remote --symref <remote> HEAD
+    try {
+        const r = await executeWithLog(`git ls-remote --symref ${remoteName} HEAD`, { execOptions, logger });
+        if (!r.stderr && r.stdout) {
+            // Output starts with a line like:  "ref: refs/heads/<name>\tHEAD"
+            const match = r.stdout.match(/^ref:\s+refs\/heads\/([^\s]+)\s+HEAD/m);
+            if (match && match[1]) {
+                logger.log(`extractDefaultBranch: resolved via ls-remote --symref -> "${match[1]}"`);
+                return match[1];
+            }
+        }
+    }
+    catch (err) {
+        // Expected on networks without remote access. Verbose-only.
+        if (isDebugMode())
+            logger.log('extractDefaultBranch: ls-remote --symref step failed, continuing', err);
+    }
+    // 4. git config --get init.defaultBranch (user-global preference)
+    try {
+        const r = await executeWithLog('git config --get init.defaultBranch', { execOptions, logger });
+        if (!r.stderr && r.stdout.trim()) {
+            logger.log(`extractDefaultBranch: resolved via init.defaultBranch -> "${r.stdout.trim()}"`);
+            return r.stdout.trim();
+        }
+    }
+    catch (err) {
+        // No user-global preference set — totally normal. Verbose-only.
+        if (isDebugMode())
+            logger.log('extractDefaultBranch: init.defaultBranch step failed, continuing', err);
+    }
+    // 5. Last resort
+    logger.log('extractDefaultBranch: falling back to literal "main"');
+    return 'main';
+}, args => { var _a, _b; return ({ cwd: (_b = (_a = args[0]) === null || _a === void 0 ? void 0 : _a.execOptions) === null || _b === void 0 ? void 0 : _b.cwd }); });
 exports.extractLatestCommitInfo = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)(), }) {
+    // Function-entry env gate. Without git or a repo, there is no commit to extract.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('extractLatestCommitInfo: git environment not ok, skipping');
+        return undefined;
+    }
     let result;
     try {
         const githubPullRequestLastCommitSha = await extractGithubPullRequestLastCommitSha();
@@ -90,11 +360,18 @@ exports.extractLatestCommitInfo = utils.general.cachify(async function ({ execOp
 }, () => exports.cacheKey);
 exports.extractGitBranch = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)() }) {
     // 1. Try CI environment variables first (fast, no subprocess, handles detached HEAD in CI)
+    //    This step works even without git installed / outside a repo.
     const ciBranch = extractCIBranchName();
     if (ciBranch) {
         logger.log(`Extracted branch name from CI environment: "${ciBranch}"`);
         return ciBranch;
     }
+    // Function-entry env gate for the git-using fallback path below.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('extractGitBranch: git environment not ok, no branch name available');
+        return undefined;
+    }
     // 2. Fall back to git command (works when on an actual branch locally)
     const result = await executeWithLog('git branch --show-current', { execOptions, logger });
     if (result.stderr) {
@@ -110,6 +387,12 @@ exports.extractGitBranch = utils.general.cachify(async function ({ execOptions,
     }
 }, args => { var _a, _b, _c; return ({ cwd: (_b = (_a = args[0]) === null || _a === void 0 ? void 0 : _a.execOptions) === null || _b === void 0 ? void 0 : _b.cwd, ignoreGitBranching: (_c = args[0]) === null || _c === void 0 ? void 0 : _c.ignoreGitBranching }); });
 exports.extractGitRepo = utils.general.cachify(async function ({ execOptions, logger = (0, logger_1.makeLogger)() }) {
+    // Function-entry env gate. Without git or a repo, we can't extract a remote URL.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('extractGitRepo: git environment not ok, returning empty repo info');
+        return {};
+    }
     const remotes = await extractRemotes();
     logger.log(`Extracted remotes from git: ${remotes}`);
     const remote = remotes.includes('origin') ? 'origin' : remotes[0];
@@ -160,11 +443,43 @@ async function extractBuildIdFromCI() {
     );
 }
 exports.extractBuildIdFromCI = extractBuildIdFromCI;
+/**
+ * Extract the ISO-8601 timestamp at which `branchName` branched off from
+ * `parentBranchName`.
+ *
+ * Algorithm (each step short-circuits on success; returns `undefined` on
+ * total failure — never throws):
+ *   1. If the repo is a shallow clone, unshallow (or treeless-fetch) so the
+ *      branch topology is visible to `git merge-base`.
+ *   2. `git merge-base <remote>/<branch> <remote>/<parent>` — CI typically
+ *      operates on remote refs only, so try those first.
+ *   3. Fall back to local refs (`git merge-base <branch> <parent>`).
+ *   4. If still no merge-base, see if the parent exists on the remote and,
+ *      if so, fetch it by name (`--filter=tree:0`) and retry. If the parent
+ *      isn't on the remote at all, give up — we can't compute a branching
+ *      point for a branch that doesn't exist anywhere.
+ *   5. Direct-ancestor refinement: if the merge-base equals the parent
+ *      branch's tip, the parent hasn't diverged from `branchName` yet
+ *      (parent is a strict ancestor). The "branching point" is then the
+ *      parent commit of the first child-only commit — not the merge-base
+ *      itself, which would be the parent's tip and produce a too-recent
+ *      timestamp.
+ *   6. Resolve the final hash's committer-date via `git show -s --format=%aI`.
+ *
+ * Cached per (branchName, parentBranchName, cwd).
+ */
 exports.extractBranchingTimestamp = utils.general.cachify(async function ({ branchName, parentBranchName, execOptions, logger = (0, logger_1.makeLogger)(), }) {
-    var _a;
     logger = logger.extend({ tags: [`extract-branching-timestamp-${utils.general.shortid()}`] });
-    // Get the primary remote name (cached)
+    // Function-entry env gate. Without git or a repo, merge-base is impossible.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('extractBranchingTimestamp: git environment not ok, skipping');
+        return undefined;
+    }
+    // Cached lookup — resolves to `origin` on a typical clone.
     const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+    // Step 1: ensure topology is visible. Shallow clones don't have enough
+    // history for merge-base to find a common ancestor.
     const shallowCheckResult = await executeWithLog('git rev-parse --is-shallow-repository', {
         execOptions,
         logger,
@@ -174,53 +489,94 @@ exports.extractBranchingTimestamp = utils.general.cachify(async function ({ bran
         logger.log('extractBranchingTimestamp - Repository is a shallow clone, attempting to unshallow');
         await executeFetchStrategy(isShallow, execOptions, logger);
     }
-    // Step 1: Try with remote refs first (fast path - uses already-fetched remote data)
-    const command = `HASH=$(git merge-base ${branchName} ${parentBranchName}) && git show -q --format=%aI $HASH`;
-    let result = await executeWithLog(command, { execOptions, logger });
-    // Step 2: If remote refs failed, try local refs
-    if (result.stderr) {
-        const commandWithRemoteRefs = `HASH=$(git merge-base ${remoteName}/${branchName} ${remoteName}/${parentBranchName}) && git show -q --format=%aI $HASH`;
-        result = await executeWithLog(commandWithRemoteRefs, { execOptions, logger });
+    // Helper: best common ancestor SHA between two refs, or null on git failure.
+    // `null` is expected during the fallback chain (e.g. first attempt fails
+    // because the remote ref isn't fetched), so the log line is verbose-only.
+    async function getMergeBase(ref1, ref2) {
+        const { stdout, stderr } = await executeWithLog(`git merge-base ${ref1} ${ref2}`, { execOptions, logger });
+        if (stderr) {
+            if (isDebugMode())
+                logger.log(`getMergeBase failed for ${ref1} and ${ref2}: ${stderr}`);
+            return null;
+        }
+        return stdout.trim();
     }
-    // Step 3: Handle missing branches with smart fetch (check remote existence first)
-    // Fetch remote branches list once if there's an error (cached call - virtually free)
-    if (result.stderr) {
+    // Helper: resolve a commit hash to its committer-date in ISO-8601, or
+    // undefined on failure. `%aI` is the author-date in strict ISO format.
+    async function getTimestampForHash(hash) {
+        if (!hash)
+            return undefined;
+        const { stdout, stderr } = await executeWithLog(`git show -s --format=%aI ${hash}`, { execOptions, logger });
+        const timestamp = stdout.trim();
+        if (stderr || !isISODate(timestamp)) {
+            logger.log(`Error extracting timestamp for hash ${hash}: stderr: ${stderr}, stdout: ${stdout}`);
+            return undefined;
+        }
+        return timestamp;
+    }
+    // Steps 2–4: resolve the merge-base, escalating from remote → local → fetch.
+    let mergeBaseHash = null;
+    // Step 2: remote refs (preferred — CI typically has these populated).
+    mergeBaseHash = await getMergeBase(`${remoteName}/${branchName}`, `${remoteName}/${parentBranchName}`);
+    // Step 3: local refs fallback.
+    if (!mergeBaseHash) {
+        mergeBaseHash = await getMergeBase(branchName, parentBranchName);
+    }
+    // Step 4: still no merge-base — fetch the parent by name and retry, but
+    // only if it actually exists on the remote (no point fetching a branch
+    // that was never pushed). `getAllRemoteBranches` is the natural guard
+    // here: when the remote is unreachable it returns an empty set, so the
+    // `.has(parentBranchName)` check falls through to "not on remote".
+    if (!mergeBaseHash) {
         const remoteBranches = await getAllRemoteBranches({ execOptions, logger });
-        // Both parent and current branches could be missing, iterate up to twice
-        for (let i = 0; i < 2; i++) {
-            if (result.stderr) {
-                const [, missingBranch] = (_a = result.stderr.match(/Not a valid object name ([^\s]+)/)) !== null && _a !== void 0 ? _a : [];
-                if (missingBranch) {
-                    // Normalize branch name by removing remote prefix
-                    const normalizedBranchName = missingBranch.replace(new RegExp(`^${remoteName}/`), '');
-                    if (!remoteBranches.has(normalizedBranchName)) {
-                        logger.log(`Branch ${missingBranch} not found on remote, skipping fetch`);
-                        return undefined; // Exit early - no point in fetching non-existent branch
-                    }
-                    // Branch exists on remote, proceed with fetch
-                    logger.log(`Fetching missing branch ${missingBranch} from remote`);
-                    const command = `HASH=$(git merge-base ${branchName} ${parentBranchName}) && git show -q --format=%aI $HASH`;
-                    /*
-                    // --filter=tree:0 creates a treeless clone.
-                    // These clones download all reachable commits while fetching trees and blobs on-demand.
-                    // These clones are best for build environments where the repository will be deleted
-                    // after a single build, but you still need access to commit history.
-                    */
-                    result = await executeWithLog(`git fetch ${remoteName} ${normalizedBranchName}:${normalizedBranchName} --filter=tree:0 && ${command}`, {
-                        execOptions,
-                        logger,
-                    });
-                }
-            }
+        if (remoteBranches.has(parentBranchName)) {
+            logger.log(`Fetching missing branch ${parentBranchName} from remote and retrying merge-base`);
+            await executeWithLog(`git fetch ${remoteName} ${parentBranchName}:${parentBranchName} --filter=tree:0`, {
+                execOptions,
+                logger,
+            });
+            mergeBaseHash = await getMergeBase(branchName, parentBranchName);
+        }
+        else {
+            logger.log(`Parent branch ${parentBranchName} not found on remote, cannot determine branching point.`);
+            return undefined;
         }
     }
-    const timestamp = result.stdout.replace(/\s/g, '');
-    if (isISODate(timestamp)) {
-        logger.log('git branching timestamp successfully extracted', timestamp);
-        return timestamp;
+    if (!mergeBaseHash) {
+        logger.log(`Could not find a merge-base for ${branchName} and ${parentBranchName}.`);
+        return undefined;
     }
-    else {
-        logger.log(`Error during extracting merge timestamp: git branching timestamp is an invalid ISO date string: ${timestamp}. stderr: ${result.stderr}, stdout: ${result.stdout}`);
+    // Step 5: direct-ancestor refinement.
+    // Resolve both branch tips so we can compare against the merge-base.
+    const branchNameSha = (await executeWithLog(`git rev-parse ${branchName}`, { execOptions, logger })).stdout.trim();
+    const parentBranchNameSha = (await executeWithLog(`git rev-parse ${parentBranchName}`, { execOptions, logger })).stdout.trim();
+    let finalHash = mergeBaseHash;
+    // If merge-base == parent's tip, parent is a strict ancestor of branchName
+    // (no divergence yet). Using merge-base directly would return the parent's
+    // tip timestamp; we want the moment of divergence instead.
+    if (mergeBaseHash === parentBranchNameSha && mergeBaseHash !== branchNameSha) {
+        logger.log(`'${parentBranchName}' is a direct ancestor of '${branchName}'. Finding the true branching point.`);
+        // The first child-only commit (oldest commit on branchName not on parent)
+        // — its parent commit IS the divergence point.
+        const firstCommitOnChild = (await executeWithLog(`git rev-list ^${parentBranchName} ${branchName} | tail -n 1`, {
+            execOptions,
+            logger,
+        })).stdout.trim();
+        if (firstCommitOnChild) {
+            const parentOfFirstCommit = (await executeWithLog(`git rev-parse ${firstCommitOnChild}^`, { execOptions, logger })).stdout.trim();
+            if (isDebugMode())
+                logger.log(`Branching point identified as: ${parentOfFirstCommit}`);
+            finalHash = parentOfFirstCommit;
+        }
+        else {
+            logger.log('Could not determine the first commit on the child branch. Using merge-base as fallback.');
+        }
+    }
+    // Step 6: hash -> ISO timestamp.
+    const timestamp = await getTimestampForHash(finalHash);
+    if (timestamp) {
+        logger.log(`git branching timestamp for parent '${parentBranchName}' successfully extracted: ${timestamp}`);
+        return timestamp;
     }
 }, args => {
     var _a;
@@ -261,6 +617,243 @@ async function parallelWithLimit(items, concurrency, fn) {
     }
     return results;
 }
+/**
+ * Enumerate ancestor branches in the window MERGE_BASE..gitBranchName by
+ * walking the commits in that window and asking which branches contain each.
+ *
+ * Mirrors the reference shell algorithm in
+ * `.team-lead/scripts-byCommits.sh`. Returns a sorted, deduplicated list
+ * of branch names (no `refs/` prefix). Never throws — returns `[]` on git
+ * failure. Always includes `defaultBranch` and `gitBranchName`.
+ */
+async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger = (0, logger_1.makeLogger)(), }) {
+    logger = logger.extend({ tags: [`get-branch-ancestry-by-commits-${utils.general.shortid()}`] });
+    if (isDebugMode()) {
+        logger.log(`[byCommits] Start: gitBranchName=${gitBranchName}, defaultBranch=${defaultBranch}`);
+    }
+    // Function-entry env gate.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('[byCommits] git environment not ok, returning []');
+        return [];
+    }
+    try {
+        // Step 1: find MERGE_BASE(HEAD, defaultBranch). This anchors the
+        // "ancestry window" we care about — commits made on the current branch
+        // after this point are uniquely ours.
+        const mergeBaseResult = await executeWithLog(`git merge-base ${gitBranchName} ${defaultBranch}`, {
+            execOptions,
+            logger,
+        });
+        if (mergeBaseResult.stderr || !mergeBaseResult.stdout.trim()) {
+            // Default-on: an empty result without explanation is the worst kind of debugging.
+            logger.log(`[byCommits] ✗ merge-base ${gitBranchName} ${defaultBranch} failed (stderr="${mergeBaseResult.stderr}"), returning []`);
+            return [];
+        }
+        const mergeBase = mergeBaseResult.stdout.trim();
+        if (isDebugMode())
+            logger.log(`[byCommits] Merge-base resolved: ${mergeBase}`);
+        // Step 2: enumerate every commit in the window MERGE_BASE..HEAD.
+        const logResult = await executeWithLog(`git log --format=%H ${mergeBase}..${gitBranchName}`, { execOptions, logger });
+        if (logResult.stderr) {
+            logger.log(`[byCommits] ✗ git log ${mergeBase}..${gitBranchName} failed (stderr="${logResult.stderr}"), returning []`);
+            return [];
+        }
+        const commits = logResult.stdout.trim().split('\n').filter(Boolean);
+        if (isDebugMode())
+            logger.log(`[byCommits] Walking ${commits.length} commit(s) in window ${mergeBase}..${gitBranchName}`);
+        // Step 3: for each commit, ask which branches contain it. The union of
+        // those answers gives us every branch that could be a parent.
+        const candidates = new Set([defaultBranch, gitBranchName]);
+        const containResults = await parallelWithLimit(commits, 10, async (hash) => {
+            const r = await executeWithLog(`git branch -a --contains ${hash} --format='%(refname:short)'`, {
+                execOptions,
+                logger,
+            });
+            if (r.stderr)
+                return [];
+            return r.stdout
+                .split('\n')
+                .map(line => line.trim())
+                .filter(b => b && b !== 'HEAD');
+        });
+        // Verbose: full per-commit dump (can be hundreds of entries on long branches).
+        if (isDebugMode()) {
+            logger.log(`[byCommits] Branches containing commits in ${mergeBase}..${gitBranchName}:`, containResults);
+        }
+        for (const list of containResults)
+            for (const b of list)
+                candidates.add(b);
+        if (isDebugMode()) {
+            logger.log(`[byCommits] Unioned candidates before descendant filter (${candidates.size}): ${Array.from(candidates).join(', ')}`);
+        }
+        // Step 4: filter out descendant branches. A candidate that has
+        // gitBranchName as its ancestor is downstream of us (a feature branch
+        // built ON TOP of this one), not an upstream parent — exclude it.
+        const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+        let droppedSelf = 0;
+        let droppedDescendants = 0;
+        const finalCandidates = await parallelWithLimit(Array.from(candidates), 10, async (branch) => {
+            const normalizedBranch = branch.replace(new RegExp(`^${remoteName}/`), '');
+            if (normalizedBranch === gitBranchName) {
+                droppedSelf++;
+                return null; // Exclude the current branch itself
+            }
+            // `merge-base --is-ancestor` exits 0 when arg1 is an ancestor of arg2.
+            // So exit 0 here means "current branch IS an ancestor of candidate"
+            // → candidate is a descendant → drop it.
+            const isDescendantResult = await executeWithLog(`git merge-base --is-ancestor ${gitBranchName} ${normalizedBranch}`, {
+                execOptions,
+                logger,
+            });
+            if (isDescendantResult.code === 0) {
+                droppedDescendants++;
+                // Verbose: fires once per descendant candidate.
+                if (isDebugMode())
+                    logger.log(`[byCommits] DROP descendant: ${normalizedBranch}`);
+                return null;
+            }
+            if (isDebugMode())
+                logger.log(`[byCommits] KEEP ancestor:  ${normalizedBranch}`);
+            return normalizedBranch;
+        });
+        const finalCleanBranches = finalCandidates.filter((b) => b !== null);
+        const result = Array.from(new Set(finalCleanBranches)).sort();
+        if (isDebugMode()) {
+            logger.log(`[byCommits] Done. dropped(self=${droppedSelf}, descendants=${droppedDescendants}) → ${result.length} ancestor(s): ${result.join(', ')}`);
+        }
+        return result;
+    }
+    catch (err) {
+        logger.log('[byCommits] ✗ ERROR', err);
+        return [];
+    }
+}
+exports.getBranchAncestryByCommits = getBranchAncestryByCommits;
+/**
+ * Enumerate ancestor branches by iterating every branch ref and applying
+ * Rule 1 (the candidate's merge-base with HEAD must not lie before the
+ * primary MERGE_BASE) and Rule 2 (HEAD must not be an ancestor of the
+ * candidate).
+ *
+ * Mirrors the reference shell algorithm in
+ * `.team-lead/scripts-byLocalBranches.sh`, with one deliberate extension:
+ * the shell script reads `refs/heads/` only, but in CI we typically have
+ * exactly one local branch checked out and dozens of remote refs. To make
+ * this method useful in CI we ALSO walk `refs/remotes/<remote>/` and strip
+ * the remote prefix. The function name is preserved for fidelity to the
+ * reference algorithm.
+ *
+ * Returns a sorted, deduplicated list of branch names. Never throws —
+ * returns `[]` on git failure. Always includes `defaultBranch` and
+ * `gitBranchName`.
+ */
+async function getBranchAncestryByLocalBranches({ gitBranchName, defaultBranch, execOptions, logger = (0, logger_1.makeLogger)(), }) {
+    logger = logger.extend({ tags: [`get-branch-ancestry-by-local-branches-${utils.general.shortid()}`] });
+    if (isDebugMode()) {
+        logger.log(`[byLocalBranches] Start: gitBranchName=${gitBranchName}, defaultBranch=${defaultBranch}`);
+    }
+    // Function-entry env gate.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('[byLocalBranches] git environment not ok, returning []');
+        return [];
+    }
+    // Per-rule counters for the final summary — invaluable when debugging
+    // "why did so many branches get filtered out?"
+    let droppedNoMb = 0;
+    let droppedRule1 = 0;
+    let droppedRule2 = 0;
+    let pinned = 0;
+    try {
+        // 1. Merge-base of CURRENT and DEFAULT. This is the "primary MERGE_BASE"
+        //    used by Rule 1 below.
+        const mergeBaseResult = await executeWithLog(`git merge-base ${gitBranchName} ${defaultBranch}`, {
+            execOptions,
+            logger,
+        });
+        if (mergeBaseResult.stderr || !mergeBaseResult.stdout.trim()) {
+            // Default-on: an empty result without explanation is the worst kind of debugging.
+            logger.log(`[byLocalBranches] ✗ merge-base ${gitBranchName} ${defaultBranch} failed (stderr="${mergeBaseResult.stderr}"), returning []`);
+            return [];
+        }
+        const mergeBase = mergeBaseResult.stdout.trim();
+        if (isDebugMode())
+            logger.log(`[byLocalBranches] Primary merge-base: ${mergeBase}`);
+        // 2. Enumerate candidate branches from BOTH local AND remote refs.
+        const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
+        const refsResult = await executeWithLog(`git for-each-ref --format='%(refname:short)' refs/heads/ refs/remotes/${remoteName}/`, { execOptions, logger });
+        if (refsResult.stderr) {
+            logger.log(`[byLocalBranches] ✗ for-each-ref failed (stderr="${refsResult.stderr}"), returning []`);
+            return [];
+        }
+        const candidateBranches = new Set([defaultBranch, gitBranchName]);
+        for (const raw of refsResult.stdout.split('\n')) {
+            const trimmed = raw.trim();
+            if (!trimmed)
+                continue;
+            const normalized = trimmed.replace(new RegExp(`^${remoteName}/`), '');
+            if (normalized && normalized !== 'HEAD')
+                candidateBranches.add(normalized);
+        }
+        if (isDebugMode()) {
+            logger.log(`[byLocalBranches] Enumerated ${candidateBranches.size} candidate(s): ${Array.from(candidateBranches).join(', ')}`);
+        }
+        // 3. Apply Rule 1 and Rule 2 for every non-pinned candidate.
+        //    Pinned = defaultBranch and gitBranchName, which always pass through.
+        const results = await parallelWithLimit(Array.from(candidateBranches), 10, async (branch) => {
+            if (branch === defaultBranch || branch === gitBranchName) {
+                pinned++;
+                if (isDebugMode())
+                    logger.log(`[byLocalBranches] KEEP pinned:     ${branch}`);
+                return branch;
+            }
+            // Rule 1: skip branches whose merge-base with CURRENT is at or before
+            //         MERGE_BASE (they diverged before our window — they're not in
+            //         the current branch's ancestry, they're parallel history).
+            const branchMbR = await executeWithLog(`git merge-base ${branch} ${gitBranchName}`, { execOptions, logger });
+            if (branchMbR.stderr || !branchMbR.stdout.trim()) {
+                droppedNoMb++;
+                if (isDebugMode()) {
+                    logger.log(`[byLocalBranches] DROP no-merge-base: ${branch} (stderr="${branchMbR.stderr}")`);
+                }
+                return null;
+            }
+            const branchMb = branchMbR.stdout.trim().split('\n')[0];
+            const r1 = await executeWithLog(`git merge-base --is-ancestor ${branchMb} ${mergeBase}`, { execOptions, logger });
+            if (r1.code === 0) {
+                droppedRule1++;
+                if (isDebugMode()) {
+                    logger.log(`[byLocalBranches] DROP Rule 1 (diverged before window): ${branch} — its mb=${branchMb} is ancestor of primary ${mergeBase}`);
+                }
+                return null;
+            }
+            // Rule 2: skip branches strictly ahead of CURRENT (HEAD is an ancestor
+            //         of them — they're descendants, not parents).
+            const r2 = await executeWithLog(`git merge-base --is-ancestor ${gitBranchName} ${branch}`, { execOptions, logger });
+            if (r2.code === 0) {
+                droppedRule2++;
+                if (isDebugMode()) {
+                    logger.log(`[byLocalBranches] DROP Rule 2 (descendant): ${branch} — ${gitBranchName} is its ancestor`);
+                }
+                return null;
+            }
+            if (isDebugMode())
+                logger.log(`[byLocalBranches] KEEP ancestor:   ${branch} (mb=${branchMb})`);
+            return branch;
+        });
+        const result = Array.from(new Set(results.filter((b) => b !== null))).sort();
+        if (isDebugMode()) {
+            logger.log(`[byLocalBranches] Done. pinned=${pinned}, dropped(no-mb=${droppedNoMb}, rule1=${droppedRule1}, rule2=${droppedRule2}) → ${result.length} ancestor(s): ${result.join(', ')}`);
+        }
+        return result;
+    }
+    catch (err) {
+        logger.log('[byLocalBranches] ✗ ERROR', err);
+        return [];
+    }
+}
+exports.getBranchAncestryByLocalBranches = getBranchAncestryByLocalBranches;
 /**
  * Get all remote branches from the primary remote (cached for performance)
  * Uses git ls-remote which is fast and doesn't require fetching data
@@ -272,6 +865,13 @@ const getAllRemoteBranches = utils.general.cachify(async function ({ execOptions
         logger.log('[getAllRemoteBranches] Starting git ls-remote to fetch all remote branches...');
         logger.log('[getAllRemoteBranches] execOptions.cwd:', (execOptions === null || execOptions === void 0 ? void 0 : execOptions.cwd) || 'undefined');
     }
+    // Short-circuit when the remote isn't reachable — no point retrying
+    // ls-remote when we know it will fail.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.remoteAccessible) {
+        logger.log('[getAllRemoteBranches] Skipping ls-remote (remote not accessible), returning empty set');
+        return new Set();
+    }
     try {
         // Get the primary remote name (cached)
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
@@ -332,9 +932,15 @@ const getAllRemoteBranches = utils.general.cachify(async function ({ execOptions
 // Custom cache key generator - only cache by cwd, not by logger instance
 args => { var _a; return ({ cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd }); }, 5 * 60 * 1000);
 /**
- * Determine fetch strategy and execute appropriate fetch operation
+ * Determine fetch strategy and execute appropriate fetch operation.
+ * No-op when the remote isn't reachable.
  */
 async function executeFetchStrategy(isShallow, execOptions, logger) {
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.remoteAccessible) {
+        logger.log('executeFetchStrategy: skipping fetch (remote not accessible)');
+        return;
+    }
     const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
     if (isShallow) {
         // Shallow clone needs full unshallow for initial topology discovery
@@ -366,6 +972,13 @@ async function executeFetchStrategy(isShallow, execOptions, logger) {
  * @param logger - Logger instance
  */
 async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions, logger) {
+    // Skip entirely when the remote is unreachable — neither the config rewrite
+    // nor the downstream fetches will do anything useful.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.remoteAccessible) {
+        logger.log('ensureRemoteBranchesAvailable: skipping (remote not accessible)');
+        return;
+    }
     try {
         // Get the primary remote name (cached)
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
@@ -396,12 +1009,17 @@ async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions,
  * Extracts a list of ancestor branches for the given branch, ordered by most recent commit timestamp.
  *
  * Algorithm:
- * 1. Check if shallow clone and should skip (via APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE)
- * 2. Ensure remote branches are available (fetch if needed for single-branch/shallow clones)
- * 3. Use git topology to discover ancestor branches efficiently (O(log N) via --first-parent --simplify-by-decoration)
- * 4. For each discovered branch, extract the branching timestamp (latest viable commit where branch existed)
- * 5. Sort results by timestamp descending (most recent first)
- * 6. Return cached results (5-minute TTL) to avoid redundant git operations
+ * 1. Check if shallow clone and should skip (via APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE).
+ * 2. Ensure remote branches are available (fetch if needed for single-branch/shallow clones).
+ * 3. Detect the repo's actual default branch via `extractDefaultBranch()` (handles non-standard
+ *    defaults like JFrog's `JFROG/.../...-rc`).
+ * 4. Discover ancestor branches using the strategy selected by
+ *    `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY` (`commits` (default) or `local`):
+ *      - `getBranchAncestryByCommits` walks the MERGE_BASE..HEAD commit window;
+ *      - `getBranchAncestryByLocalBranches` iterates `refs/heads/` + `refs/remotes/<remote>/`.
+ * 5. For each discovered branch, extract the branching timestamp.
+ * 6. Sort results by timestamp descending (most recent first), tie-break by branch name.
+ * 7. Root-branch safety net: if nothing survived, fall back to the detected default branch.
  *
  * @param gitBranchName - The branch to analyze
  * @param execOptions - Git execution options (e.g., cwd)
@@ -411,59 +1029,69 @@ async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions,
 exports.extractBranchLookupFallbackList = utils.general.cachify(async function ({ gitBranchName, execOptions, logger = (0, logger_1.makeLogger)(), enableShallowClone = true, }) {
     const functionStartTime = Date.now();
     logger = logger.extend({ tags: [`extract-branch-fallback-list-${utils.general.shortid()}`] });
-    logger.log(`[PERF] extractBranchLookupFallbackList started for branch: ${gitBranchName}`);
+    if (isDebugMode())
+        logger.log(`[PERF] extractBranchLookupFallbackList started for branch: ${gitBranchName}`);
+    // Function-entry env gate. Everything downstream shells out to git.
+    const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
+    if (!env.ok) {
+        logger.log('extractBranchLookupFallbackList: git environment not ok, skipping');
+        return undefined;
+    }
     try {
-        // 1. Check if this is a shallow clone and if we should skip based on env var
-        // add this to control of the user
+        // 1. Shallow-clone gate: APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE
+        // lets users opt out of expensive unshallow-fetches in CI.
         const shallowCheckStartTime = Date.now();
         const shallowCheckResult = await executeWithLog('git rev-parse --is-shallow-repository', {
             execOptions,
             logger,
         });
-        logger.log(`[PERF] Shallow check took ${Date.now() - shallowCheckStartTime}ms`);
+        if (isDebugMode())
+            logger.log(`[PERF] Shallow check took ${Date.now() - shallowCheckStartTime}ms`);
         const isShallow = shallowCheckResult.stdout.trim() === 'true';
         if (!enableShallowClone && isShallow) {
             logger.log('Shallow clone detected and APPLITOOLS_SKIP_BRANCH_LOOKUP_IN_SHALLOW_CLONE is enabled, skipping branch lookup');
             return undefined;
         }
-        // 2. Ensure remote branches are available BEFORE topology discovery
-        // This is necessary for single-branch clones and shallow clones where branches don't exist locally
+        // 2. Ensure topology is fetchable: single-branch / shallow clones don't
+        //    have the other branches' refs locally — fetch them so subsequent
+        //    merge-base calls have something to work with.
         const ensureRemoteStartTime = Date.now();
         await ensureRemoteBranchesAvailable(gitBranchName, isShallow, execOptions, logger);
-        logger.log(`[PERF] ensureRemoteBranchesAvailable took ${Date.now() - ensureRemoteStartTime}ms`);
-        // 3. OPTIMIZATION: Use git topology to discover only ancestor branches (O(log N) instead of O(N))
-        // Instead of listing all remote branches and checking each one, we walk the git graph
-        // only along the current branch's history using --first-parent and --simplify-by-decoration
-        const topologyStartTime = Date.now();
-        logger.log(`Discovering ancestor branches using git topology for ${gitBranchName}...`);
-        // Get the primary remote name (cached)
+        if (isDebugMode())
+            logger.log(`[PERF] ensureRemoteBranchesAvailable took ${Date.now() - ensureRemoteStartTime}ms`);
+        // Cached lookup of the primary remote (typically `origin`).
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
-        const logResult = await executeWithLog(`git log --first-parent --simplify-by-decoration --format="%D" ${gitBranchName}`, { execOptions, logger });
-        const foundBranches = new Set();
-        if (!logResult.stderr && logResult.stdout.trim()) {
-            const rawLines = logResult.stdout.split('\n');
-            for (const line of rawLines) {
-                // Parse refs like: "HEAD -> feat, origin/feat, tag: v1, origin/main"
-                const refs = line.split(',').map(r => r.trim());
-                for (const ref of refs) {
-                    if (ref.includes('tag:'))
-                        continue; // Ignore tags
-                    const cleanRef = ref.replace('HEAD -> ', '').replace(new RegExp(`^${remoteName}/`), ''); // Normalize
-                    if (cleanRef && cleanRef !== gitBranchName && cleanRef !== 'HEAD')
-                        foundBranches.add(cleanRef);
-                }
-            }
+        // 3. Detect the repo's actual default branch (handles JFrog-style non-standard names).
+        const defaultBranch = await (0, exports.extractDefaultBranch)({ execOptions, logger });
+        logger.log(`Default branch detected: ${defaultBranch}`);
+        // 4. Discover ancestor branches using the chosen strategy.
+        //    APPLITOOLS_BRANCH_ANCESTRY_STRATEGY=commits (default) | local
+        const ancestryStrategy = (process.env.APPLITOOLS_BRANCH_ANCESTRY_STRATEGY || 'commits').trim().toLowerCase();
+        const ancestryDriver = ancestryStrategy === 'local' ? getBranchAncestryByLocalBranches : getBranchAncestryByCommits;
+        const ancestryStartTime = Date.now();
+        logger.log(`Discovering ancestor branches via "${ancestryStrategy}" strategy for ${gitBranchName} (default=${defaultBranch})...`);
+        const ancestry = await ancestryDriver({ gitBranchName, defaultBranch, execOptions, logger });
+        if (isDebugMode())
+            logger.log(`[PERF] Ancestry discovery took ${Date.now() - ancestryStartTime}ms`);
+        if (isDebugMode()) {
+            logger.log(`Ancestry discovery found ${ancestry.length} candidate branches: ${ancestry.join(', ')}`);
         }
-        let allBranches = Array.from(foundBranches);
-        logger.log(`[PERF] Topology discovery took ${Date.now() - topologyStartTime}ms`);
+        else {
+            logger.log(`Ancestry discovery found ${ancestry.length} candidate branches`);
+        }
+        // The helpers return defaultBranch + gitBranchName + ancestors; strip current branch
+        // for parity with the rest of the function (caller adds it back via timestamp logic).
+        let allBranches = ancestry.filter(b => b !== gitBranchName);
         if (isDebugMode()) {
-            logger.log(`Topology discovered ${allBranches.length} potential ancestor branches: ${allBranches.join(', ')}`);
+            logger.log(`Ancestry discovered ${allBranches.length} potential ancestor branches: ${allBranches.join(', ')}`);
         }
         else {
-            logger.log(`Topology discovered ${allBranches.length} potential ancestor branches`);
+            logger.log(`Ancestry discovered ${allBranches.length} potential ancestor branches`);
         }
-        // 3. Filter out branches that don't exist on remote (if we can determine remote branches)
-        // This prevents unnecessary ancestor checks and fetch attempts for missing branches
+        // 4b. Drop branches that the ancestry helper found locally but that
+        //     don't exist on the remote — fetching/merge-base'ing against them
+        //     would just waste time and surface confusing errors. Cheap because
+        //     `getAllRemoteBranches` is cached.
         const remoteBranchesStartTime = Date.now();
         if (isDebugMode()) {
             logger.log('[Remote Filtering] ========================================');
@@ -516,51 +1144,15 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
                 logger.log('[Remote Filtering] Continuing with all discovered branches');
             }
         }
-        logger.log(`[Remote Filtering] [PERF] Remote branch filtering took ${Date.now() - remoteBranchesStartTime}ms`);
         if (isDebugMode()) {
+            logger.log(`[Remote Filtering] [PERF] Remote branch filtering took ${Date.now() - remoteBranchesStartTime}ms`);
             logger.log('[Remote Filtering] ========================================');
         }
-        // 4. Filter out sibling branches - keep only TRUE ancestors
-        // A branch is a true ancestor if it's in the ancestry path of the current branch
-        // Use git merge-base --is-ancestor to check if candidate is an ancestor of current branch
-        const filteringStartTime = Date.now();
-        logger.log(`Filtering out sibling branches to keep only true ancestors...`);
-        // PERFORMANCE: Check ancestors in parallel with concurrency limit to avoid overwhelming git
-        const ANCESTOR_CHECK_CONCURRENCY = 10;
-        const ancestorChecks = await parallelWithLimit(allBranches, ANCESTOR_CHECK_CONCURRENCY, async (candidateBranch) => {
-            try {
-                // Check if candidate branch is an ancestor of current branch
-                // git merge-base --is-ancestor <commit> <commit> exits with status 0 if true, 1 if false
-                const isAncestorResult = await executeWithLog(`git merge-base --is-ancestor ${candidateBranch} ${gitBranchName}`, {
-                    execOptions,
-                    logger,
-                });
-                // Exit code 0 means it's an ancestor, exit code 1 means it's not
-                if (isAncestorResult.code === 0) {
-                    logger.log(`✓ ${candidateBranch} is a true ancestor`);
-                    return { branch: candidateBranch, isAncestor: true };
-                }
-                else if (isAncestorResult.code === 1) {
-                    logger.log(`✗ ${candidateBranch} is a sibling, not an ancestor`);
-                    return { branch: candidateBranch, isAncestor: false };
-                }
-                else {
-                    logger.log(`⚠ Could not determine if ${candidateBranch} is an ancestor (exit code: ${isAncestorResult.code}), including it to be safe`);
-                    return { branch: candidateBranch, isAncestor: true };
-                }
-            }
-            catch (err) {
-                logger.log(`Error checking if ${candidateBranch} is a true ancestor:`, err);
-                // If we can't determine, include it to be safe (better to have false positives than miss ancestors)
-                return { branch: candidateBranch, isAncestor: true };
-            }
-        });
-        const trueAncestors = ancestorChecks.filter(result => result.isAncestor).map(result => result.branch);
-        logger.log(`[PERF] Sibling filtering took ${Date.now() - filteringStartTime}ms`);
-        logger.log(`Filtered to ${trueAncestors.length} true ancestors: ${trueAncestors.join(', ')}`);
-        // 5. For each true ancestor branch, calculate the branching timestamp
+        // 5. For each surviving ancestor, compute the branching timestamp in
+        //    parallel. The ancestry helper has already pruned siblings and
+        //    descendants, so every entry here should be a real ancestor.
         const timestampStartTime = Date.now();
-        const branchesWithTimestamps = await Promise.all(trueAncestors.map(async (ancestorBranch) => {
+        const branchesWithTimestamps = await Promise.all(allBranches.map(async (ancestorBranch) => {
             const timestamp = await (0, exports.extractBranchingTimestamp)({
                 branchName: gitBranchName,
                 parentBranchName: ancestorBranch,
@@ -569,7 +1161,8 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
             });
             return timestamp ? { branchName: ancestorBranch, latestViableTimestamp: timestamp } : null;
         }));
-        logger.log(`[PERF] Timestamp extraction took ${Date.now() - timestampStartTime}ms`);
+        if (isDebugMode())
+            logger.log(`[PERF] Timestamp extraction took ${Date.now() - timestampStartTime}ms`);
         // 6. Filter out null results and sort by timestamp (most recent first), then by branch name
         const validBranches = branchesWithTimestamps
             .filter((item) => item !== null)
@@ -613,17 +1206,15 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
                         .map(line => line.trim())
                         .filter(line => line && !line.includes('->') && !line.includes('HEAD'))
                         .map(line => line.replace(new RegExp(`^${remoteName}/`), '').replace(/^\* /, '')); // Remove remote prefix and '* ' prefix
-                    // Try common root branch names first: main, master, develop
-                    const commonRootNames = ['main', 'master', 'develop', 'trunk'];
+                    // Prefer the programmatically-detected default branch (handles non-standard names
+                    // like JFrog's `JFROG/artifactory-mfe/preRelease/jfmfe-1.995.x-rc`) over a hardcoded list.
                     let rootBranch = null;
-                    for (const commonName of commonRootNames) {
-                        if (branchesContainingRoot.includes(commonName)) {
-                            rootBranch = commonName;
-                            logger.log(`Found root branch using common name: ${rootBranch}`);
-                            break;
-                        }
+                    if (branchesContainingRoot.includes(defaultBranch)) {
+                        rootBranch = defaultBranch;
+                        logger.log(`Found root branch via detected defaultBranch: ${rootBranch}`);
                     }
-                    // If no common name found, use the oldest branch (most likely the root)
+                    // If the detected default isn't among the root-containing branches,
+                    // fall back to the oldest branch (most likely the historical root).
                     if (!rootBranch && branchesContainingRoot.length > 0) {
                         // Find the branch with the oldest creation timestamp among those containing root commit
                         const branchTimestamps = await Promise.all(branchesContainingRoot.slice(0, 10).map(async (branch) => {
@@ -696,8 +1287,15 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         catch (err) {
             logger.log('Failed to detect and add root branch, continuing without it', err);
         }
-        logger.log(`[PERF] extractBranchLookupFallbackList completed in ${Date.now() - functionStartTime}ms total`);
-        logger.log('Successfully extracted branch lookup fallback list', JSON.stringify(validBranches));
+        if (isDebugMode()) {
+            logger.log(`[PERF] extractBranchLookupFallbackList completed in ${Date.now() - functionStartTime}ms total`);
+        }
+        if (isDebugMode()) {
+            logger.log(`Successfully extracted branch lookup fallback list (${validBranches.length} entries): ${JSON.stringify(validBranches)}`);
+        }
+        else {
+            logger.log(`Successfully extracted branch lookup fallback list (${validBranches.length} entries)`);
+        }
         return validBranches.length > 0 ? validBranches : undefined;
     }
     catch (err) {