@applitools/core 4.67.0 → 4.67.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [4.67.1](https://github.com/Applitools-Dev/sdk/compare/js/core@4.67.0...js/core@4.67.1) (2026-07-29)
+
+
+### Bug Fixes
+
+* capture CSS Font Loading API fonts in DOM snapshot | FLD-4754 ([#4024](https://github.com/Applitools-Dev/sdk/issues/4024)) ([3df71ed](https://github.com/Applitools-Dev/sdk/commit/3df71ede021072c7ad249d548465b72776672282))
+* include related branches in git branch-lookup fallback list | AD-15279 ([#4015](https://github.com/Applitools-Dev/sdk/issues/4015)) ([bceb7e1](https://github.com/Applitools-Dev/sdk/commit/bceb7e1bbb98a1138105629eec446f94e328ae30))
+
+
+### Dependencies
+
+* @applitools/dom-snapshot bumped to 4.17.7
+  #### Bug Fixes
+
+  * capture CSS Font Loading API fonts in DOM snapshot | FLD-4754 ([#4024](https://github.com/Applitools-Dev/sdk/issues/4024)) ([3df71ed](https://github.com/Applitools-Dev/sdk/commit/3df71ede021072c7ad249d548465b72776672282))
+
 ## [4.67.0](https://github.com/Applitools-Dev/sdk/compare/js/core@4.66.2...js/core@4.67.0) (2026-07-23)
 
 

package/dist/open-eyes.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleConcurrency = exports.getLatestCommitInfoFromEnvVars = exports.makeOpenEyes = void 0;
+exports.handleConcurrency = exports.getLatestCommitInfoFromEnvVars = exports.makeOpenEyes = exports.sanitizeFinding = void 0;
 const driver_1 = require("@applitools/driver");
 const core_1 = require("./classic/core");
 const core_2 = require("./ufg/core");
@@ -38,6 +38,24 @@ const utils = __importStar(require("@applitools/utils"));
 const core_base_1 = require("@applitools/core-base");
 const extract_git_info_1 = require("./utils/extract-git-info");
 const types_1 = require("./types");
+const reportedScmPreconditionFindings = new Map();
+const scmPreconditionKey = (cwd, gitBranchName) => `${cwd} ${gitBranchName !== null && gitBranchName !== void 0 ? gitBranchName : ''}`;
+const findingsHash = (findings) => findings
+    .map(finding => finding.code)
+    .sort()
+    .join(',');
+const CREDENTIALS_IN_URL = /([a-z][a-z0-9+.-]*:\/\/)[^/@\s]*@/gi;
+const MAX_FINDING_DETAIL_LENGTH = 512;
+// SECURITY: `detail` is `env.reason` / raw git stderr, so it can embed a remote URL with `user:token@` userinfo.
+function sanitizeFinding(finding) {
+    // Pre-slice: CREDENTIALS_IN_URL backtracks quadratically on remote-controlled git stderr (≤1 MB via exec maxBuffer).
+    let detail = finding.detail.slice(0, 4 * MAX_FINDING_DETAIL_LENGTH).replace(CREDENTIALS_IN_URL, '$1***@');
+    if (detail.length > MAX_FINDING_DETAIL_LENGTH) {
+        detail = `${detail.slice(0, MAX_FINDING_DETAIL_LENGTH - 1)}…`;
+    }
+    return { code: finding.code, detail };
+}
+exports.sanitizeFinding = sanitizeFinding;
 function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDuplicateTests, core, cores, spec, environment, logger: mainLogger, asyncCache, concurrency, useServerConcurrency = false, cwd = process.cwd(), }) {
     let shouldPrintConcurrencyWarning = true;
     return async function openEyes({ type = defaultType, settings: openSettings, config, target, logger = mainLogger, }) {
@@ -204,8 +222,9 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
     async function handleBranchFallbackList(account, settings, logger) {
         var _a, _b;
         const scm = getScmSettings(account.scmSettings);
+        const integrationActive = !settings.ignoreGitBranching && scm.lookupFallbackList;
         // Extract gitBranchName (the actual git branch name)
-        if (!settings.ignoreGitBranching && scm.lookupFallbackList) {
+        if (integrationActive) {
             logger.log(`Extracting git branch name, ${cwd}`);
             settings.gitBranchName = await (0, extract_git_info_1.extractGitBranch)({
                 execOptions: { cwd },
@@ -219,17 +238,63 @@ function makeOpenEyes({ type: defaultType = 'classic', clients, batch, removeDup
         else {
             logger.log(`Skipping extraction of git branch name as ignoreGitBranching is set to true`);
         }
-        if (settings.gitBranchName && !settings.ignoreGitBranching && scm.lookupFallbackList) {
+        // No branch name means the extractor never runs, so probe the env here instead.
+        if (integrationActive && !settings.gitBranchName) {
+            const env = await (0, extract_git_info_1.checkGitEnvironment)({ execOptions: { cwd }, logger });
+            reportScmPreconditionFailure({
+                key: scmPreconditionKey(cwd),
+                account,
+                settings,
+                findings: (0, extract_git_info_1.gitEnvironmentFindings)(env),
+                logger,
+            });
+        }
+        if (settings.gitBranchName && integrationActive) {
             logger.log(`Extracting branch lookup fallback list for branch "${settings.gitBranchName}, ${cwd}"`);
-            // add write to coralogix before and after
-            settings.branchLookupFallbackList = await (0, extract_git_info_1.extractBranchLookupFallbackList)({
+            const outcome = await extract_git_info_1.extractBranchLookupFallbackList.withDiagnostics({
                 gitBranchName: `${settings.gitBranchName}`,
                 enableShallowClone: (_b = scm.enableShallowClone) !== null && _b !== void 0 ? _b : false,
                 execOptions: { cwd },
                 logger,
             });
+            settings.branchLookupFallbackList = outcome.list;
+            if (outcome.status === 'precondition-failure') {
+                reportScmPreconditionFailure({
+                    key: scmPreconditionKey(cwd, settings.gitBranchName),
+                    account,
+                    settings,
+                    findings: outcome.diagnostics.findings,
+                    defaultBranch: outcome.diagnostics.defaultBranch,
+                    logger,
+                });
+            }
         }
     }
+    function reportScmPreconditionFailure({ key, account, settings, findings, defaultBranch, logger, }) {
+        const hash = findingsHash(findings);
+        if (reportedScmPreconditionFindings.get(key) === hash)
+            return;
+        reportedScmPreconditionFindings.set(key, hash);
+        emitScmPreconditionFailureEvent({ account, settings, findings, defaultBranch, logger });
+    }
+    function emitScmPreconditionFailureEvent({ account, settings, findings, defaultBranch, logger, }) {
+        var _a;
+        void core.logEvent({
+            settings: {
+                ...account.eyesServer,
+                level: 'Warn',
+                event: {
+                    type: 'scmBranchLookupPreconditionFailure',
+                    gitBranchName: settings.gitBranchName,
+                    defaultBranch,
+                    findings: findings.map(sanitizeFinding),
+                    batchId: (_a = settings.batch) === null || _a === void 0 ? void 0 : _a.id,
+                    userTestId: settings.userTestId,
+                },
+            },
+            logger,
+        });
+    }
 }
 exports.makeOpenEyes = makeOpenEyes;
 function refineMissingApiKeyException(error, sdk) {

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

@@ -26,7 +26,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-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.resolveBranchToLocalRef = 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.gitEnvironmentFindings = exports.checkGitEnvironment = exports.resolveBranchToLocalRef = exports.getPrimaryRemoteName = exports.cacheKey = void 0;
 const utils = __importStar(require("@applitools/utils"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -211,6 +211,17 @@ exports.checkGitEnvironment = utils.general.cachify(async function ({ execOption
         };
     }
 }, 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 }); });
+/** The finding `code`s are a telemetry wire contract — Coralogix dashboards match on them; do not rename. */
+function gitEnvironmentFindings(env) {
+    if (!env.gitInstalled)
+        return [{ code: 'git-not-installed', detail: env.reason }];
+    if (!env.insideRepo)
+        return [{ code: 'not-a-work-tree', detail: env.reason }];
+    if (!env.remoteAccessible)
+        return [{ code: 'remote-unreachable', detail: env.reason }];
+    return [];
+}
+exports.gitEnvironmentFindings = gitEnvironmentFindings;
 /**
  * Grep-friendly env banner. The `APPLITOOLS GIT ENVIRONMENT CHECK` prefix is
  * unique to this codepath, so support can find the full verdict in one line.
@@ -679,26 +690,28 @@ async function parallelWithLimit(items, concurrency, fn) {
     }
     return results;
 }
+// Ranks must stay distinct: sharing one drops the tie through to the alphabetical compare.
+const RELATIONSHIP_RANK = {
+    lineage: 0,
+    'fork-point': 1,
+    'merge-absorbed': 2,
+    'equal-tip': 3,
+    base: 4,
+    unknown: 5,
+};
+function relationshipRank(relationship) {
+    var _a;
+    return (_a = RELATIONSHIP_RANK[relationship]) !== null && _a !== void 0 ? _a : RELATIONSHIP_RANK.unknown;
+}
+// NaN would make the comparator inconsistent and the whole sort undefined, so sink the entry instead.
+function epochOrOldest(timestamp) {
+    const epoch = new Date(timestamp).getTime();
+    return Number.isNaN(epoch) ? -Number.MAX_VALUE : epoch;
+}
 /**
- * Enumerate ancestor branches in MERGE_BASE..gitBranchName by walking each
- * commit in the window and unioning the branches that contain it. Returns a
- * sorted, deduped list (no `refs/` prefix). Never throws — `[]` on git failure.
- *
- * Inclusion contract (fork-depth — shares semantics with
- * {@link getBranchAncestryByLocalBranches}):
- * - `gitBranchName` is **always excluded** by the self check.
- * - `defaultBranch` is **always kept** as the base: it defines the floor
- *   (`merge-base(HEAD, defaultBranch)`), so its own merge-base with HEAD equals
- *   the floor and would fail the strict fork-depth test by construction.
- * - Descendants of HEAD are dropped (built on top of us; cannot be baselines).
- * - A candidate `C` is kept iff it forked from HEAD's history **strictly later**
- *   than the default branch did — i.e. some `merge-base(HEAD, C)` is a strict
- *   descendant of the floor. Cousins that share only the floor (diverged no
- *   later than the default branch) are dropped. This prunes the over-inclusive
- *   candidate seed (the per-commit `--contains` walk pulls in cousins via
- *   criss-cross/ghost merges).
- *
- * Use {@link getBranchAncestryByLocalBranches} if you need both refs pinned.
+ * Enumerate RELATED (parent-shaped) branches in MERGE_BASE..gitBranchName,
+ * classified by keep-class. Returns a sorted, deduped list (no `refs/` prefix).
+ * Never throws — `[]` on git failure.
  */
 async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger = (0, logger_1.makeLogger)(), }) {
     logger = logger.extend({ tags: [`get-branch-ancestry-by-commits-${utils.general.shortid()}`] });
@@ -736,6 +749,24 @@ async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOp
         const mergeBase = mergeBaseResult.stdout.trim();
         if (isDebugMode())
             logger.log(`[byCommits] Merge-base resolved: ${mergeBase}`);
+        // Step 1b: HEAD's first-parent chain (floor, HEAD], plus every criss-cross floor base.
+        // Stays null if listing fails, which makes step 4's strict-lineage filter skip (KEEP).
+        let fpChain = null;
+        const fpChainResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-list', '--first-parent', gitBranchName, `^${mergeBase}`]), { execOptions, logger });
+        if (fpChainResult.code === 0) {
+            fpChain = new Set(fpChainResult.stdout
+                .split('\n')
+                .map(line => line.trim())
+                .filter(Boolean));
+            const floorBases = await runGitContainsWithRetry((0, shell_quote_1.quote)(['git', 'merge-base', '--all', gitBranchName, defaultBranch]), { execOptions, logger });
+            for (const base of floorBases
+                .split('\n')
+                .map(line => line.trim())
+                .filter(Boolean)) {
+                fpChain.add(base);
+            }
+            fpChain.add(mergeBase);
+        }
         // Step 2: enumerate every commit in the window MERGE_BASE..HEAD.
         const logResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'log', '--format=%H', `${mergeBase}..${gitBranchName}`]), {
             execOptions,
@@ -780,30 +811,14 @@ async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOp
         if (isDebugMode()) {
             logger.log(`[byCommits] Unioned candidates before descendant filter (${candidates.size}): ${Array.from(candidates).join(', ')}`);
         }
-        // Step 4: fork-depth filter. `mergeBase` is the floor — the point where HEAD
-        // and the default branch diverged. A candidate is a coherent lineage point
-        // iff it forked from HEAD's history STRICTLY LATER than the default branch
-        // did. Concretely, per candidate C:
-        //   (a) self     — drop C if it normalizes to HEAD.
-        //   default base — always keep the default branch: it defines the floor, so
-        //                  its own merge-base with HEAD equals the floor and fails
-        //                  the strict-descendant test (c) by construction; it is the
-        //                  base and is always kept.
-        //   (b) descendant — drop C if HEAD is its ancestor (built on top of us).
-        //   (c) fork-depth — keep C iff some merge-base(HEAD, C) is a STRICT
-        //                  descendant of the floor. Cousins that share only the floor
-        //                  (diverged no later than the default branch) are dropped.
-        // Criss-cross robustness: `git merge-base` without `--all` returns one
-        // unspecified base, which would make (c) nondeterministic in criss-cross
-        // topologies (e.g. ghost merges). Use `--all` and keep if ANY base is a
-        // strict descendant of the floor.
-        // Error policy throughout: an operational/transient git error → KEEP. A
-        // false-drop loses a real baseline forever; a false-keep is recoverable
-        // downstream.
+        // Step 4: per-candidate keep/drop classifier (`mergeBase` is the floor).
+        // Error policy throughout: transient git error → KEEP. A false-drop loses a baseline forever.
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
         let droppedSelf = 0;
         let droppedDescendants = 0;
         let droppedCousins = 0;
+        let droppedAbsorbedSiblings = 0;
+        let droppedDiverged = 0;
         const finalCandidates = await parallelWithLimit(Array.from(candidates), 10, async (branch) => {
             // `branch` may be local (`staging`) or remote-tracking (`origin/staging`).
             // Use the as-is form for git ops (git resolves both); strip only for the
@@ -812,23 +827,53 @@ async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOp
             const normalizedBranch = branch.replace(new RegExp(`^${remoteName}/`), '');
             if (normalizedBranch === gitBranchName) {
                 droppedSelf++;
-                return null; // self
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] DROP self: ${normalizedBranch} — it is the branch under evaluation, not an ancestor`);
+                }
+                return null;
             }
             // Default branch always kept (see (c)-by-construction note above). Name
             // compare rather than a first-parent check: the default branch is the base.
             if (normalizedBranch === defaultBranch) {
                 if (isDebugMode())
                     logger.log(`[byCommits] KEEP base (default branch): ${normalizedBranch}`);
-                return normalizedBranch;
+                return { name: normalizedBranch, relationship: 'base' };
             }
-            // (b) `git merge-base --is-ancestor HEAD <candidate>` asks "is HEAD an
-            // ancestor of the candidate?" → the candidate is a DESCENDANT of HEAD.
-            // Clean-true → drop. Clean-false / error → fall through to (c).
+            // (b) is HEAD an ancestor of the candidate? Clean-false/error → (c).
             const isDescendant = await runGitPredicateWithRetry((0, shell_quote_1.quote)(['git', 'merge-base', '--is-ancestor', gitBranchName, branch]), { execOptions, logger });
             if (isDescendant === true) {
+                const headShaResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-parse', gitBranchName]), { execOptions, logger });
+                const candShaResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-parse', branch]), { execOptions, logger });
+                const headSha = headShaResult.code === 0 ? headShaResult.stdout.trim() : '';
+                const candSha = candShaResult.code === 0 ? candShaResult.stdout.trim() : '';
+                if (headSha && headSha === candSha) {
+                    if (isDebugMode()) {
+                        logger.log(`[byCommits] KEEP equal-tip parent: ${normalizedBranch} — tips are the same commit ${headSha.slice(0, 9)} (fast-forward merge or fork with no own commits); previously dropped as a descendant`);
+                    }
+                    return { name: normalizedBranch, relationship: 'equal-tip' };
+                }
+                if (headSha) {
+                    // Bound at HEAD~1, not HEAD: `^<sha>` excludes it, and the range must still contain the tip we look for.
+                    let candFpResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-list', '--first-parent', branch, `^${headSha}~1`]), { execOptions, logger });
+                    if (candFpResult.code !== 0) {
+                        // Root-commit edge (no HEAD~1) — fall back to a capped walk.
+                        candFpResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-list', '--first-parent', '-n', '5000', branch]), {
+                            execOptions,
+                            logger,
+                        });
+                    }
+                    const onFirstParentChain = candFpResult.code === 0 && candFpResult.stdout.split('\n').some(line => line.trim() === headSha);
+                    if (!onFirstParentChain) {
+                        if (isDebugMode()) {
+                            logger.log(`[byCommits] KEEP merge-absorbed parent: ${normalizedBranch} — ${gitBranchName} (${headSha.slice(0, 9)}) is reachable from it only via a merge commit's 2nd parent; the candidate merged this branch in, it was not built on top of it`);
+                        }
+                        return { name: normalizedBranch, relationship: 'merge-absorbed' };
+                    }
+                }
                 droppedDescendants++;
-                if (isDebugMode())
-                    logger.log(`[byCommits] DROP descendant: ${normalizedBranch}`);
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] DROP descendant: ${normalizedBranch} — ${gitBranchName} is an ancestor of it (this branch was merged into / built on top of the candidate, so the candidate is downstream, not a parent)`);
+                }
                 return null;
             }
             // (c) fork-depth. Compute ALL merge bases of HEAD and the candidate.
@@ -844,12 +889,16 @@ async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOp
             if (mbCs.length === 0) {
                 if (isDebugMode())
                     logger.log(`[byCommits] KEEP (no merge-base resolved, conservative): ${normalizedBranch}`);
-                return normalizedBranch;
+                return { name: normalizedBranch, relationship: 'lineage' };
+            }
+            const candTipResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'rev-parse', branch]), { execOptions, logger });
+            const candTip = candTipResult.code === 0 ? candTipResult.stdout.trim() : '';
+            if (candTip && candTip === mergeBase) {
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] KEEP fork-point parent: ${normalizedBranch} — its tip IS the fork point ${mergeBase.slice(0, 9)} (the merge-base with ${gitBranchName}); this branch was checked out from it and the parent has not advanced; previously dropped as a cousin`);
+                }
+                return { name: normalizedBranch, relationship: 'fork-point' };
             }
-            // Keep iff ANY base is a STRICT descendant of the floor: base != floor AND
-            // floor is an ancestor of base. A base == floor (or below it) means C
-            // diverged no later than the default branch → cousin for that base. On a
-            // transient error probing a base → treat as strict (conservative keep).
             let anyStrictlyAboveFloor = false;
             for (const mbC of mbCs) {
                 if (mbC === mergeBase)
@@ -859,23 +908,47 @@ async function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOp
                     anyStrictlyAboveFloor = true;
                     break;
                 }
-                // clean-false → mbC is strictly BELOW the floor (older) → not a fork point
-                // via this base; keep checking the remaining bases.
             }
             if (!anyStrictlyAboveFloor) {
                 droppedCousins++;
-                if (isDebugMode())
-                    logger.log(`[byCommits] DROP cousin (shares only the floor): ${normalizedBranch}`);
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] DROP cousin (shares only the floor): ${normalizedBranch} — merge-base(${gitBranchName}, ${normalizedBranch}) = [${mbCs.join(', ')}], none is a strict descendant of floor ${mergeBase} (= merge-base with ${defaultBranch}); the branches only meet on the ${defaultBranch} trunk`);
+                }
+                return null;
+            }
+            if (fpChain && !mbCs.some(mbC => fpChain.has(mbC))) {
+                droppedAbsorbedSiblings++;
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] DROP absorbed-sibling: ${normalizedBranch} — merge-base(s) [${mbCs
+                        .map(mbC => mbC.slice(0, 9))
+                        .join(', ')}] reach ${gitBranchName} only via a merge's 2nd parent (content merged into this branch's ancestry), not via its own first-parent line`);
+                }
+                return null;
+            }
+            if (candTip && !mbCs.includes(candTip)) {
+                droppedDiverged++;
+                if (isDebugMode()) {
+                    logger.log(`[byCommits] DROP diverged sibling: ${normalizedBranch} — has own commits beyond the shared point ${mbCs[0].slice(0, 9)}; a sibling's work, not this branch's ancestry`);
+                }
                 return null;
             }
             if (isDebugMode())
                 logger.log(`[byCommits] KEEP lineage point: ${normalizedBranch}`);
-            return normalizedBranch;
+            return { name: normalizedBranch, relationship: 'lineage' };
         });
-        const finalCleanBranches = finalCandidates.filter((b) => b !== null);
-        const result = Array.from(new Set(finalCleanBranches)).sort();
+        // Dedup by name — the same branch can surface both bare and `origin/`-prefixed.
+        const byName = new Map();
+        for (const entry of finalCandidates) {
+            if (!entry)
+                continue;
+            const existing = byName.get(entry.name);
+            if (!existing || relationshipRank(entry.relationship) < relationshipRank(existing.relationship)) {
+                byName.set(entry.name, entry);
+            }
+        }
+        const result = Array.from(byName.values()).sort((a, b) => a.name.localeCompare(b.name));
         if (isDebugMode()) {
-            logger.log(`[byCommits] Done. dropped(self=${droppedSelf}, descendants=${droppedDescendants}, cousins=${droppedCousins}) → ${result.length} lineage point(s): ${result.join(', ')}`);
+            logger.log(`[byCommits] Done. dropped(self=${droppedSelf}, descendants=${droppedDescendants}, cousins=${droppedCousins}, absorbed-siblings=${droppedAbsorbedSiblings}, diverged=${droppedDiverged}) → ${result.length} related branch(es): ${result.map(entry => `${entry.name}(${entry.relationship})`).join(', ')}`);
         }
         return result;
     }
@@ -890,10 +963,7 @@ exports.getBranchAncestryByCommits = getBranchAncestryByCommits;
  * Rule 1 (fork-depth: candidate must have forked from HEAD strictly later than
  * the default branch did — some merge-base with HEAD is a strict descendant of
  * the primary MERGE_BASE) and Rule 2 (HEAD must not be an ancestor of the
- * candidate). Rule 1 shares the fork-depth semantics of
- * {@link getBranchAncestryByCommits}: cousins sharing only the floor are dropped
- * in BOTH strategies, while the default branch and genuine lineage points are
- * kept in both.
+ * candidate).
  *
  * Walks `refs/heads/` AND `refs/remotes/<remote>/` (stripping the prefix), since
  * CI typically has one local branch and dozens of remote refs.
@@ -1139,33 +1209,49 @@ const getAllRemoteBranches = utils.general.cachify(async function ({ execOptions
 // Cache by cwd only, 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.
- * No-op when the remote isn't reachable.
+ * Determine fetch strategy and execute the appropriate fetch. No-op when the remote isn't reachable.
+ * `stillShallow` is re-probed after a failed unshallow, so callers can report an incomplete topology.
  */
 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;
+        return {};
     }
     const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
     if (isShallow) {
         // Shallow clone → unshallow for topology discovery.
         logger.log(`Shallow repository detected, unshallowing to enable topology discovery...`);
-        await executeWithLog((0, shell_quote_1.quote)(['git', 'fetch', remoteName, '--unshallow', '--filter=blob:none']), {
+        const unshallowResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'fetch', remoteName, '--unshallow', '--filter=blob:none']), {
             execOptions,
             logger,
         });
-        logger.log(`Repository unshallowed successfully`);
+        if (unshallowResult.code === 0) {
+            logger.log(`Repository unshallowed successfully`);
+            return {};
+        }
+        logger.log(`Unshallow fetch failed (exit code ${unshallowResult.code})`);
+        const verify = await executeWithLog('git rev-parse --is-shallow-repository', { execOptions, logger });
+        const stillShallow = verify.stdout.trim() === 'true';
+        if (stillShallow) {
+            logger.log(`✗ repository is STILL SHALLOW after the unshallow attempt (exit ${unshallowResult.code}) — topology discovery will be incomplete`);
+        }
+        return { stillShallow };
     }
     else {
         // Single-branch clone → fetch all remote branches for topology discovery.
         logger.log(`Non-shallow clone detected, fetching all remote branches for topology discovery...`);
-        await executeWithLog((0, shell_quote_1.quote)(['git', 'fetch', remoteName, '--filter=tree:0']), {
+        const fetchResult = await executeWithLog((0, shell_quote_1.quote)(['git', 'fetch', remoteName, '--filter=tree:0']), {
             execOptions,
             logger,
         });
-        logger.log(`All remote branches fetched successfully`);
+        if (fetchResult.code === 0) {
+            logger.log(`All remote branches fetched successfully`);
+        }
+        else {
+            logger.log(`All-branches fetch failed (exit code ${fetchResult.code})`);
+        }
+        return {};
     }
 }
 /**
@@ -1177,7 +1263,7 @@ async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions,
     const env = await (0, exports.checkGitEnvironment)({ execOptions, logger });
     if (!env.remoteAccessible) {
         logger.log('ensureRemoteBranchesAvailable: skipping (remote not accessible)');
-        return;
+        return {};
     }
     try {
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
@@ -1188,13 +1274,12 @@ async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions,
         });
         const isRemoteBranch = symbolicResult.stdout.trim().startsWith(`${remoteName}/`);
         if (!isRemoteBranch) {
-            return;
+            return {};
         }
         logger.log(`Detected remote branch scenario, fetching ancestor branches...`);
         // Widen the refspec to fetch all remote branches, then fetch.
         await executeWithLog((0, shell_quote_1.quote)(['git', 'config', `remote.${remoteName}.fetch`, `+refs/heads/*:refs/remotes/${remoteName}/*`]), { execOptions, logger });
-        await executeFetchStrategy(isShallow, execOptions, logger);
-        logger.log(`Remote branches fetched successfully for complete ancestor check`);
+        const fetchOutcome = await executeFetchStrategy(isShallow, execOptions, logger);
         // Single-branch clones / actions/checkout@v4 never write
         // refs/remotes/<remote>/HEAD. Populate it so extractDefaultBranch step 2
         // (symbolic-ref) succeeds. Non-fatal — steps 3-5 still cover us.
@@ -1204,35 +1289,25 @@ async function ensureRemoteBranchesAvailable(branchName, isShallow, execOptions,
         catch (err) {
             logger.log('ensureRemoteBranchesAvailable: remote set-head -a failed (continuing)', err);
         }
+        return fetchOutcome;
     }
     catch (err) {
         logger.log('Note: Could not determine if branch is remote, continuing with topology discovery', err);
+        return {};
     }
 }
-/**
- * List ancestor branches for `gitBranchName`, ordered by most-recent timestamp.
- *
- * 1. Shallow-clone gate (skip via `enableShallowClone`, from server account-info).
- * 2. Fetch remote branches if needed (single-branch/shallow clones).
- * 3. Detect the actual default branch (`extractDefaultBranch` — non-standard names).
- * 4. Discover ancestors via `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY`:
- *    `commits` (default, walks MERGE_BASE..HEAD) | `local` (iterates refs).
- * 5. Extract each branch's branching timestamp.
- * 6. Sort by timestamp desc, tie-break by name.
- * 7. Root-branch safety net: fall back to the detected default branch.
- *
- * @returns ancestor branches with timestamps, or undefined if skipped.
- */
-exports.extractBranchLookupFallbackList = utils.general.cachify(async function ({ gitBranchName, execOptions, logger = (0, logger_1.makeLogger)(), enableShallowClone = true, }) {
+const computeBranchLookupFallbackList = 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()}`] });
     if (isDebugMode())
         logger.log(`[PERF] extractBranchLookupFallbackList started for branch: ${gitBranchName}`);
+    // Findings accumulated en route, attached to whichever terminal failure fires.
+    const findings = [];
     // 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;
+        return { status: 'precondition-failure', diagnostics: { findings: gitEnvironmentFindings(env) } };
     }
     try {
         // 1. Shallow-clone gate: when the caller opted out AND the clone is
@@ -1247,12 +1322,27 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         const isShallow = shallowCheckResult.stdout.trim() === 'true';
         if (!enableShallowClone && isShallow) {
             logger.log('Shallow clone detected and enableShallowClone=false, skipping branch lookup');
-            return undefined;
+            return {
+                status: 'precondition-failure',
+                diagnostics: {
+                    findings: [
+                        { code: 'shallow-skip', detail: 'shallow clone and enableShallowClone=false — branch lookup skipped' },
+                        ...findings,
+                        ...gitEnvironmentFindings(env),
+                    ],
+                },
+            };
         }
         // 2. Fetch the other branches' refs so subsequent merge-base calls work
         //    (single-branch/shallow clones don't have them locally).
         const ensureRemoteStartTime = Date.now();
-        await ensureRemoteBranchesAvailable(gitBranchName, isShallow, execOptions, logger);
+        const remoteAvailability = await ensureRemoteBranchesAvailable(gitBranchName, isShallow, execOptions, logger);
+        if (remoteAvailability.stillShallow) {
+            findings.push({
+                code: 'still-shallow-after-unshallow',
+                detail: 'repository remained shallow after the unshallow attempt — topology discovery incomplete',
+            });
+        }
         if (isDebugMode())
             logger.log(`[PERF] ensureRemoteBranchesAvailable took ${Date.now() - ensureRemoteStartTime}ms`);
         const remoteName = await (0, exports.getPrimaryRemoteName)({ execOptions, logger });
@@ -1270,26 +1360,50 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         });
         if (!resolvedDefaultBranch) {
             logger.log(`extractBranchLookupFallbackList: default branch "${defaultBranch}" not resolvable locally or on remote, skipping ancestry`);
-            return undefined;
+            return {
+                status: 'precondition-failure',
+                diagnostics: {
+                    findings: [
+                        {
+                            code: 'default-branch-unresolvable',
+                            detail: `default branch "${defaultBranch}" not resolvable locally or on the remote`,
+                        },
+                        ...findings,
+                        ...gitEnvironmentFindings(env),
+                    ],
+                    defaultBranch,
+                },
+            };
         }
         // 4. Discover ancestors: APPLITOOLS_BRANCH_ANCESTRY_STRATEGY=commits|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 });
+        const ancestry = ancestryStrategy === 'local'
+            ? (await getBranchAncestryByLocalBranches({ gitBranchName, defaultBranch, execOptions, logger })).map(name => ({
+                name,
+                relationship: 'unknown',
+            }))
+            : await getBranchAncestryByCommits({ 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(', ')}`);
+            logger.log(`Ancestry discovery found ${ancestry.length} candidate branches: ${ancestry
+                .map(entry => entry.name)
+                .join(', ')}`);
         }
         else {
             logger.log(`Ancestry discovery found ${ancestry.length} candidate branches`);
         }
         // Strip the current branch (caller adds it back via timestamp logic).
-        let allBranches = ancestry.filter(b => b !== gitBranchName);
+        let allBranches = ancestry.filter(entry => entry.name !== gitBranchName);
+        if (isDebugMode() && allBranches.length !== ancestry.length) {
+            logger.log(`[FallbackList] DROP self: ${gitBranchName} — stripped from the ancestor list (it is the branch under evaluation)`);
+        }
         if (isDebugMode()) {
-            logger.log(`Ancestry discovered ${allBranches.length} potential ancestor branches: ${allBranches.join(', ')}`);
+            logger.log(`Ancestry discovered ${allBranches.length} potential ancestor branches: ${allBranches
+                .map(entry => entry.name)
+                .join(', ')}`);
         }
         else {
             logger.log(`Ancestry discovered ${allBranches.length} potential ancestor branches`);
@@ -1301,7 +1415,7 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         if (isDebugMode()) {
             logger.log('[Remote Filtering] ========================================');
             logger.log('[Remote Filtering] Starting remote branch filtering...');
-            logger.log('[Remote Filtering] Branches to check:', allBranches.join(', '));
+            logger.log('[Remote Filtering] Branches to check:', allBranches.map(entry => entry.name).join(', '));
             logger.log('[Remote Filtering] Number of branches before filtering:', allBranches.length);
         }
         try {
@@ -1319,15 +1433,20 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
                 const beforeFilter = allBranches.length;
                 if (isDebugMode()) {
                     logger.log('[Remote Filtering] Filtering branches against remote...');
-                    allBranches.forEach(branch => {
-                        const exists = remoteBranches.has(branch);
-                        logger.log(`[Remote Filtering] Branch "${branch}": ${exists ? '✓ EXISTS' : '✗ MISSING'} on remote`);
+                    allBranches.forEach(entry => {
+                        const exists = remoteBranches.has(entry.name);
+                        logger.log(`[Remote Filtering] Branch "${entry.name}": ${exists ? '✓ EXISTS' : '✗ MISSING'} on remote`);
                     });
                 }
-                allBranches = allBranches.filter(branch => remoteBranches.has(branch));
+                if (isDebugMode()) {
+                    for (const entry of allBranches.filter(candidate => !remoteBranches.has(candidate.name))) {
+                        logger.log(`[Remote Filtering] DROP not-on-remote: ${entry.name} — exists locally but has no refs/heads/${entry.name} on the remote (per git ls-remote), so the server could never match a baseline for it`);
+                    }
+                }
+                allBranches = allBranches.filter(entry => remoteBranches.has(entry.name));
                 const filtered = beforeFilter - allBranches.length;
                 if (isDebugMode()) {
-                    logger.log('[Remote Filtering] Branches after filtering:', allBranches.join(', '));
+                    logger.log('[Remote Filtering] Branches after filtering:', allBranches.map(entry => entry.name).join(', '));
                     logger.log('[Remote Filtering] Number of branches after filtering:', allBranches.length);
                 }
                 if (filtered > 0) {
@@ -1354,7 +1473,8 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         }
         // 5. Compute each surviving ancestor's branching timestamp in parallel.
         const timestampStartTime = Date.now();
-        const branchesWithTimestamps = await Promise.all(allBranches.map(async (ancestorBranch) => {
+        const branchesWithTimestamps = await Promise.all(allBranches.map(async (ancestorEntry) => {
+            const ancestorBranch = ancestorEntry.name;
             let timestamp = await (0, exports.extractBranchingTimestamp)({
                 branchName: gitBranchName,
                 parentBranchName: ancestorBranch,
@@ -1386,19 +1506,25 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
                     timestamp = tipTimestamp;
                 }
             }
-            return timestamp ? { branchName: ancestorBranch, latestViableTimestamp: timestamp } : null;
+            if (!timestamp && isDebugMode()) {
+                logger.log(`[Timestamps] DROP no-timestamp: ${ancestorBranch} — no merge-base timestamp after retry AND the tip-commit-date fallback failed (branch unresolvable or non-ISO date); confirmed ancestor is lost from the final list`);
+            }
+            return timestamp
+                ? { branchName: ancestorBranch, latestViableTimestamp: timestamp, relationship: ancestorEntry.relationship }
+                : null;
         }));
         if (isDebugMode())
             logger.log(`[PERF] Timestamp extraction took ${Date.now() - timestampStartTime}ms`);
-        // 6. Drop nulls; sort by timestamp desc, tie-break by branch name.
         const validBranches = branchesWithTimestamps
             .filter((item) => item !== null)
             .sort((a, b) => {
-            const timeDiff = new Date(b.latestViableTimestamp).getTime() - new Date(a.latestViableTimestamp).getTime();
-            if (timeDiff === 0) {
-                return a.branchName.localeCompare(b.branchName);
-            }
-            return timeDiff;
+            const timeDiff = epochOrOldest(b.latestViableTimestamp) - epochOrOldest(a.latestViableTimestamp);
+            if (timeDiff !== 0)
+                return timeDiff;
+            const rankDiff = relationshipRank(a.relationship) - relationshipRank(b.relationship);
+            if (rankDiff !== 0)
+                return rankDiff;
+            return a.branchName.localeCompare(b.branchName);
         });
         // 7. Root-branch safety net (branch containing the repo's first commit).
         try {
@@ -1481,6 +1607,7 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
                                         validBranches.push({
                                             branchName: rootBranch,
                                             latestViableTimestamp: rootTimestamp,
+                                            relationship: 'base',
                                         });
                                         logger.log(`Added root branch ${rootBranch} with timestamp ${rootTimestamp}`);
                                     }
@@ -1507,12 +1634,44 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         if (isDebugMode()) {
             logger.log(`[PERF] extractBranchLookupFallbackList completed in ${Date.now() - functionStartTime}ms total`);
         }
-        logger.log('Successfully extracted branch lookup fallback list', JSON.stringify(validBranches));
-        return validBranches.length > 0 ? validBranches : undefined;
+        // Deliberately not debug-gated: backend-side analysis consumes this line. `relationship` is log-only.
+        logger.log(`Branch lookup fallback branches with relationship: ${validBranches
+            .map(branch => `${branch.branchName}(${branch.relationship})`)
+            .join(', ')}`);
+        const wireList = validBranches.map(({ branchName, latestViableTimestamp }) => ({
+            branchName,
+            latestViableTimestamp,
+        }));
+        logger.log('Successfully extracted branch lookup fallback list', JSON.stringify(wireList));
+        if (wireList.length > 0)
+            return { status: 'ok', list: wireList, diagnostics: { findings } };
+        // The default branch legitimately has no ancestors, so an empty list there is not a failure.
+        if (gitBranchName === defaultBranch)
+            return { status: 'ok', diagnostics: { findings, defaultBranch } };
+        return {
+            status: 'precondition-failure',
+            diagnostics: {
+                findings: [
+                    { code: 'empty-list', detail: `no fallback branches found for "${gitBranchName}"` },
+                    ...findings,
+                    ...gitEnvironmentFindings(env),
+                ],
+                defaultBranch,
+            },
+        };
     }
     catch (err) {
         logger.log('Error during extracting branch lookup fallback list', err);
-        return undefined;
+        return {
+            status: 'precondition-failure',
+            diagnostics: {
+                findings: [
+                    { code: 'extraction-error', detail: err instanceof Error ? err.message : String(err) },
+                    ...findings,
+                    ...gitEnvironmentFindings(env),
+                ],
+            },
+        };
     }
 }, args => {
     var _a;
@@ -1521,3 +1680,26 @@ exports.extractBranchLookupFallbackList = utils.general.cachify(async function (
         cwd: (_a = args[0].execOptions) === null || _a === void 0 ? void 0 : _a.cwd,
     });
 });
+/**
+ * List ancestor branches for `gitBranchName`, ordered by most-recent timestamp.
+ *
+ * 1. Shallow-clone gate (skip via `enableShallowClone`, from server account-info).
+ * 2. Fetch remote branches if needed (single-branch/shallow clones).
+ * 3. Detect the actual default branch (`extractDefaultBranch` — non-standard names).
+ * 4. Discover ancestors via `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY`:
+ *    `commits` (default, walks MERGE_BASE..HEAD, classified) | `local` (iterates refs, unclassified).
+ * 5. Extract each branch's branching timestamp.
+ * 6. Sort by timestamp desc, tie-break by keep-class rank then name.
+ * 7. Root-branch safety net: fall back to the detected default branch.
+ *
+ * For failure diagnostics call {@link extractBranchLookupFallbackList.withDiagnostics} —
+ * it shares this function's cache entry, so it costs no extra git work.
+ *
+ * @returns ancestor branches with timestamps, or undefined if skipped.
+ */
+exports.extractBranchLookupFallbackList = Object.assign(async function (options) {
+    return (await computeBranchLookupFallbackList(options)).list;
+}, {
+    withDiagnostics: (options) => computeBranchLookupFallbackList(options),
+    clearCache: computeBranchLookupFallbackList.clearCache,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/core",
-  "version": "4.67.0",
+  "version": "4.67.1",
   "homepage": "https://applitools.com",
   "bugs": {
     "url": "https://github.com/applitools/eyes.sdk.javascript1/issues"
@@ -63,7 +63,7 @@
   "dependencies": {
     "@applitools/core-base": "1.37.0",
     "@applitools/dom-capture": "11.8.4",
-    "@applitools/dom-snapshot": "4.17.6",
+    "@applitools/dom-snapshot": "4.17.7",
     "@applitools/driver": "1.26.6",
     "@applitools/ec-client": "1.12.39",
     "@applitools/logger": "2.3.0",

package/types/open-eyes.d.ts

@@ -23,6 +23,13 @@ type Options<TSpec extends SpecType, TType extends 'classic' | 'ufg'> = {
     concurrency?: number;
     useServerConcurrency?: boolean;
 };
+export declare function sanitizeFinding(finding: {
+    code: string;
+    detail: string;
+}): {
+    code: string;
+    detail: string;
+};
 export declare function makeOpenEyes<TSpec extends SpecType, TDefaultType extends 'classic' | 'ufg' = 'classic'>({ type: defaultType, clients, batch, removeDuplicateTests, core, cores, spec, environment, logger: mainLogger, asyncCache, concurrency, useServerConcurrency, cwd, }: Options<TSpec, TDefaultType>): <TType extends "classic" | "ufg" = TDefaultType>({ type, settings: openSettings, config, target, logger, }: {
     type?: TType | undefined;
     settings?: Partial<OpenSettings<TDefaultType> & OpenSettings<TType>> | undefined;

package/types/utils/extract-git-info.d.ts

@@ -88,6 +88,8 @@ export declare const checkGitEnvironment: (({ execOptions, logger, }: {
     clearCache(): void;
     TTL?: number | undefined;
 };
+/** The finding `code`s are a telemetry wire contract — Coralogix dashboards match on them; do not rename. */
+export declare function gitEnvironmentFindings(env: GitEnvironmentResult): BranchLookupFinding[];
 /**
  * Detect the repo's default branch. Fallback chain (short-circuits on success;
  * never throws):
@@ -176,37 +178,23 @@ type BranchAncestryOptions = {
     execOptions?: ExecOptions;
     logger?: Logger;
 };
+export type BranchRelationship = 'lineage' | 'fork-point' | 'merge-absorbed' | 'equal-tip' | 'base';
+export type BranchAncestryEntry = {
+    name: string;
+    relationship: BranchRelationship;
+};
 /**
- * Enumerate ancestor branches in MERGE_BASE..gitBranchName by walking each
- * commit in the window and unioning the branches that contain it. Returns a
- * sorted, deduped list (no `refs/` prefix). Never throws — `[]` on git failure.
- *
- * Inclusion contract (fork-depth — shares semantics with
- * {@link getBranchAncestryByLocalBranches}):
- * - `gitBranchName` is **always excluded** by the self check.
- * - `defaultBranch` is **always kept** as the base: it defines the floor
- *   (`merge-base(HEAD, defaultBranch)`), so its own merge-base with HEAD equals
- *   the floor and would fail the strict fork-depth test by construction.
- * - Descendants of HEAD are dropped (built on top of us; cannot be baselines).
- * - A candidate `C` is kept iff it forked from HEAD's history **strictly later**
- *   than the default branch did — i.e. some `merge-base(HEAD, C)` is a strict
- *   descendant of the floor. Cousins that share only the floor (diverged no
- *   later than the default branch) are dropped. This prunes the over-inclusive
- *   candidate seed (the per-commit `--contains` walk pulls in cousins via
- *   criss-cross/ghost merges).
- *
- * Use {@link getBranchAncestryByLocalBranches} if you need both refs pinned.
+ * Enumerate RELATED (parent-shaped) branches in MERGE_BASE..gitBranchName,
+ * classified by keep-class. Returns a sorted, deduped list (no `refs/` prefix).
+ * Never throws — `[]` on git failure.
  */
-export declare function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<string[]>;
+export declare function getBranchAncestryByCommits({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<BranchAncestryEntry[]>;
 /**
  * Enumerate ancestor branches by iterating every branch ref and applying
  * Rule 1 (fork-depth: candidate must have forked from HEAD strictly later than
  * the default branch did — some merge-base with HEAD is a strict descendant of
  * the primary MERGE_BASE) and Rule 2 (HEAD must not be an ancestor of the
- * candidate). Rule 1 shares the fork-depth semantics of
- * {@link getBranchAncestryByCommits}: cousins sharing only the floor are dropped
- * in BOTH strategies, while the default branch and genuine lineage points are
- * kept in both.
+ * candidate).
  *
  * Walks `refs/heads/` AND `refs/remotes/<remote>/` (stripping the prefix), since
  * CI typically has one local branch and dozens of remote refs.
@@ -215,6 +203,33 @@ export declare function getBranchAncestryByCommits({ gitBranchName, defaultBranc
  * includes `defaultBranch` and `gitBranchName`.
  */
 export declare function getBranchAncestryByLocalBranches({ gitBranchName, defaultBranch, execOptions, logger, }: BranchAncestryOptions): Promise<string[]>;
+export type BranchLookupFinding = {
+    code: string;
+    detail: string;
+};
+export type BranchLookupDiagnostics = {
+    findings: BranchLookupFinding[];
+    defaultBranch?: string;
+};
+export type BranchLookupOutcome = {
+    status: 'ok';
+    /** Absent when there are legitimately no ancestors. */
+    list?: Array<{
+        branchName: string;
+        latestViableTimestamp: string;
+    }>;
+    diagnostics: BranchLookupDiagnostics;
+} | {
+    status: 'precondition-failure';
+    list?: undefined;
+    diagnostics: BranchLookupDiagnostics;
+};
+export type BranchLookupFallbackListOptions = {
+    gitBranchName: string;
+    execOptions?: ExecOptions;
+    logger?: Logger;
+    enableShallowClone: boolean;
+};
 /**
  * List ancestor branches for `gitBranchName`, ordered by most-recent timestamp.
  *
@@ -222,31 +237,21 @@ export declare function getBranchAncestryByLocalBranches({ gitBranchName, defaul
  * 2. Fetch remote branches if needed (single-branch/shallow clones).
  * 3. Detect the actual default branch (`extractDefaultBranch` — non-standard names).
  * 4. Discover ancestors via `APPLITOOLS_BRANCH_ANCESTRY_STRATEGY`:
- *    `commits` (default, walks MERGE_BASE..HEAD) | `local` (iterates refs).
+ *    `commits` (default, walks MERGE_BASE..HEAD, classified) | `local` (iterates refs, unclassified).
  * 5. Extract each branch's branching timestamp.
- * 6. Sort by timestamp desc, tie-break by name.
+ * 6. Sort by timestamp desc, tie-break by keep-class rank then name.
  * 7. Root-branch safety net: fall back to the detected default branch.
  *
+ * For failure diagnostics call {@link extractBranchLookupFallbackList.withDiagnostics} —
+ * it shares this function's cache entry, so it costs no extra git work.
+ *
  * @returns ancestor branches with timestamps, or undefined if skipped.
  */
-export declare const extractBranchLookupFallbackList: (({ gitBranchName, execOptions, logger, enableShallowClone, }: {
-    gitBranchName: string;
-    execOptions?: ExecOptions | undefined;
-    logger?: Logger | undefined;
-    enableShallowClone: boolean;
-}) => Promise<Array<{
+export declare const extractBranchLookupFallbackList: ((options: BranchLookupFallbackListOptions) => Promise<Array<{
     branchName: string;
     latestViableTimestamp: string;
 }> | undefined>) & {
-    getCachedValues(): Promise<{
-        branchName: string;
-        latestViableTimestamp: string;
-    }[] | undefined>[];
-    setCachedValue(key: any, value: Promise<{
-        branchName: string;
-        latestViableTimestamp: string;
-    }[] | undefined>): void;
-    clearCache(): void;
-    TTL?: number | undefined;
+    withDiagnostics: (options: BranchLookupFallbackListOptions) => Promise<BranchLookupOutcome>;
+    clearCache: () => void;
 };
 export {};