@teambit/ci 1.0.495 → 1.0.500

package/dist/{preview-1786461108763.js → preview-1786731350011.js}

@@ -1,5 +1,5 @@
 ;
-import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.git_ci@1.0.495/dist/ci.docs.mdx';
+import * as overview_0 from '/home/circleci/Library/Caches/Bit/capsules/8891be5ad/teambit.git_ci@1.0.500/dist/ci.docs.mdx';
 
 export const compositions = [];
 export const overview = [overview_0];

package/dist/sync/lane-sync-executor.d.ts

@@ -26,6 +26,12 @@ export declare const REFUSED_SUMMARY_PREFIX = "REFUSED";
  * summary just because the ledger push raced.
  */
 export declare function racedLedgerPushSummary(laneName: string, policyClause?: string): string;
+/**
+ * `executeAdoptBranch`'s ledger-commit push lost the race. Unlike the export paths, adoption never
+ * snaps or exports — the LANE is untouched; only the branch's pointer commit failed to land. The next
+ * run re-plans first contact against the winner's tip.
+ */
+export declare function racedAdoptionPushSummary(laneName: string): string;
 export type LaneSyncDeps = {
     lanes: LanesMain;
     /** for snapPrCommit + getDefaultBranchName + switchToLaneForSync */
@@ -131,6 +137,16 @@ export declare class LaneSyncExecutor {
      * resulting `.bitmap` back onto the branch so the next run sees the two sides as converged.
      */
     private executeExportBranch;
+    /**
+     * First contact: the lane exists, the branch maps to it by name, but the branch's committed
+     * `.bitmap` has no state for it (typically `bit ci pr --keep-lane` created the lane from this very
+     * branch without recording the pointer in git). Adoption only ever RECORDS a pointer, never resolves
+     * content: switch onto the lane keeping the branch's files, then ask `bit status` whether anything
+     * differs. Nothing → ledger commit; something → halt, lane untouched. Deliberately a status READ,
+     * never a snap: `snapping.snap()` writes an unexported Version object even under `dryRun`, and that
+     * residue can trip a later lane in the same `--all` run.
+     */
+    private executeAdoptBranch;
     /**
      * Both sides moved since the last sync. Order is load-bearing: (1) merge the lane into the branch's
      * working tree (`bit checkout head`; conflicts halt or auto-resolve per `sync.onConflict`), (2) snap
@@ -141,13 +157,12 @@ export declare class LaneSyncExecutor {
      */
     private executeMergeDiverged;
     /**
-     * Snap the workspace's current tree onto the lane and export it; returns the error so the caller can
-     * halt. Snaps WHATEVER is in the workspace (the switch uses `forceOurs` and never merges files), so
-     * a diverged tree must already hold the merged content. `keepLane` preserves the lane's history,
-     * `skipCleanup` keeps the snap's `.bitmap` for the caller to commit, `noDestructiveRecovery` turns
-     * stale-lane recovery (delete + re-fork the remote lane) into a throw. The lane object must be
-     * imported BEFORE delegating: a switch onto the lane the workspace is already on no-ops before any
-     * fetch, so it never warms a cold scope.
+     * Snap the workspace's current tree onto the lane and export it. Snaps WHATEVER is in the workspace
+     * (the switch uses `forceOurs` and never merges files), so a diverged tree must already hold the
+     * merged content. `keepLane` preserves the lane's history, `skipCleanup` keeps the snap's `.bitmap`
+     * for the caller to commit, `noDestructiveRecovery` turns stale-lane recovery (delete + re-fork the
+     * remote lane) into a throw. The lane object must be imported BEFORE delegating: a switch onto the
+     * lane the workspace is already on no-ops before any fetch, so it never warms a cold scope.
      */
     private snapAndExportOntoLane;
     /**
@@ -155,7 +170,7 @@ export declare class LaneSyncExecutor {
      * so any earlier fingerprint is stale), commit — crucially the `.bitmap` the snap rewrote — and push.
      * `unreadable` means the lane could no longer be read back, in which case the caller halts;
      * `raced` means a concurrent run's push already got there first, in which case the caller reports
-     * a benign noop instead.
+     * a benign noop instead. `adopted` adds the audit-only `ADOPTION_TRAILER`.
      */
     private recordLaneHeadOnBranch;
     /**
@@ -181,6 +196,30 @@ export declare class LaneSyncExecutor {
      * direction: left alone, never retired.
      */
     private assessBranchOwnership;
+    /**
+     * Gates `hasIndependentHistoryBelowStateCommit`'s git call to the one case it can change the outcome
+     * for: an `own-live` claim (the only ownership that would otherwise license an immediate delete) with
+     * a reachable state commit to inspect. Extracted out of `reconcileLane` to keep the branching there.
+     */
+    private computeHasIndependentHistory;
+    /**
+     * Whether the OLDEST commit unique to the branch is NOT bit-authored — durable, ancestry-based proof
+     * a human created the branch before this reconciler touched it (a trailer would not survive later
+     * ledger commits; see `oldestCommitIsNonSync` for the oldest-only rationale). Unreadable answers
+     * `true`: a deletion guard errs toward keeping.
+     */
+    private hasIndependentHistoryBelowStateCommit;
+    /** Gates `differentLaneStillClaims` to the planner's first-contact path, the only one that reads it. */
+    private computeBranchNamesDifferentLane;
+    /**
+     * Whether adoption must refuse `branch` because its `.bitmap` names a DIFFERENT lane's still-live
+     * claim. Blob equality with the fork-point `.bitmap`, not commit reachability: an `own-superseded`
+     * branch is reachable yet still carries live work; only a `.bitmap` the branch never changed proves
+     * the pointer is inherited. Unreadable stays conservative and blocks adoption.
+     */
+    private differentLaneStillClaims;
+    /** Seam over `branchBitmapUnchangedSinceFork`, so `differentLaneStillClaims` is unit-testable without a real remote. */
+    private branchInheritsBitmapFromDefault;
     /**
      * The lane is gone from bit.cloud — close its PR, and retire the branch if the claim on it allows.
      * Deleting the branch is the one irreversible thing this command does; `keepReason` distinguishes
@@ -202,12 +241,15 @@ export declare class LaneSyncExecutor {
      */
     private executeHalt;
     /**
-     * Drive the workspace's filesystem to the remote lane's content; returns the error so the caller can
-     * halt. Two traps make a plain `switchToLane` insufficient: (1) it defaults to `forceOurs`, which
-     * never touches the filesystem — the commit would claim the branch mirrors the lane over the default
-     * branch's files — so `forceOurs` is cleared and `forceTheirs` set; (2) switching onto the lane the
-     * workspace already sits on throws "already checked out", which `switchToLane` swallows as success
-     * and nothing materializes — so step off to main first.
+     * Drive the workspace's filesystem onto the remote lane; returns the error so the caller can halt.
+     * Two traps make a plain `switchToLane` insufficient: (1) its default `forceOurs` never touches the
+     * filesystem, so the caller's commit would misrepresent whichever side it claims mirrors the other;
+     * (2) switching onto the lane the workspace already sits on throws "already checked out", which
+     * `switchToLane` swallows as success and nothing materializes — so step off to main first.
+     *
+     * `theirsWins` picks the direction: `true` (import-lane) checks the lane's files out over the disk;
+     * `false` (adopt-branch) keeps the workspace's files — the branch's content is what the lane is
+     * being asked to reflect.
      */
     private materializeLane;
     private fetchOnce;

package/dist/sync/lane-sync-executor.js

@@ -17,6 +17,7 @@ exports.haltCommentBody = haltCommentBody;
 exports.isProtectedBranch = isProtectedBranch;
 exports.laneHeadFingerprint = laneHeadFingerprint;
 exports.laneSyncPrBody = laneSyncPrBody;
+exports.racedAdoptionPushSummary = racedAdoptionPushSummary;
 exports.racedLedgerPushSummary = racedLedgerPushSummary;
 function _chalk() {
   const data = _interopRequireDefault(require("chalk"));
@@ -137,6 +138,15 @@ function racedBranchPushSummary(laneName) {
 function racedLedgerPushSummary(laneName, policyClause = '') {
   return racedSummary(laneName, `${policyClause}lane updated; branch ledger commit lost the push race — next run re-plans`);
 }
+
+/**
+ * `executeAdoptBranch`'s ledger-commit push lost the race. Unlike the export paths, adoption never
+ * snaps or exports — the LANE is untouched; only the branch's pointer commit failed to land. The next
+ * run re-plans first contact against the winner's tip.
+ */
+function racedAdoptionPushSummary(laneName) {
+  return racedSummary(laneName, 'lane untouched; adoption ledger commit lost the push race — next run re-plans');
+}
 /**
  * Fingerprint of a lane's content — same primitive as `branchStateFingerprint`, so "equal" means
  * exactly "the branch records every lane component at the lane's head".
@@ -261,7 +271,8 @@ function dryRunSummaryLine(laneName, action) {
 const KEPT_BECAUSE = exports.KEPT_BECAUSE = {
   'unmerged-commits': `it carries commits that are not in the default branch`,
   'tip-not-a-sync-commit': `its tip is not one of this reconciler's own commits, so the work in it may exist nowhere else`,
-  'tip-advanced-during-run': `its tip advanced after the ownership evidence was read, so it may carry work this run never saw`
+  'tip-advanced-during-run': `its tip advanced after the ownership evidence was read, so it may carry work this run never saw`,
+  'adopted-branch': `it was adopted from a pre-existing branch, and only merging (not deleting) proves its history is safe to retire`
 };
 class LaneSyncExecutor {
   constructor(deps) {
@@ -438,13 +449,17 @@ class LaneSyncExecutor {
     // `isSyncAuthoredMessage`, NOT `hasSyncMarker`: this feeds a branch deletion, and a message that
     // merely quotes the marker must not read as one we wrote.
     const tipIsSyncCommit = (0, _syncState().isSyncAuthoredMessage)(branchState.tipMessage);
+    const hasIndependentHistory = await this.computeHasIndependentHistory(ownership, branchState.stateCommit, defaultBranch);
+    const branchNamesDifferentLane = await this.computeBranchNamesDifferentLane(lastSyncedHead, branchState.hasDevCommits, mirroredLane, laneIdStr, branch, defaultBranch);
     const action = (0, _syncPlanner().planLaneSync)({
       laneHead,
       branchExists,
       lastSyncedHead,
       hasDevCommits: branchState.hasDevCommits,
       tipIsSyncCommit,
+      hasIndependentHistory,
       conflictLabelPresent,
+      branchNamesDifferentLane,
       ownership
     });
     logger.console(_chalk().default.blue(`${laneName} -> ${action.type} (branch: ${branch}, lane head: ${laneHead?.slice(0, 9) ?? 'none'}, ` + `branch state: ${lastSyncedHead?.slice(0, 9) ?? 'none'}, ` + `dev commits: ${branchState.hasDevCommits}${laneIsGone ? `, branch claim: ${ownership}` : ''})`));
@@ -501,6 +516,14 @@ class LaneSyncExecutor {
           branch,
           defaultBranch
         });
+      case 'adopt-branch':
+        return this.executeAdoptBranch({
+          target,
+          laneIdStr,
+          branch,
+          defaultBranch,
+          pr
+        });
       case 'close-pr':
         return this.executeClosePr({
           laneName,
@@ -513,13 +536,18 @@ class LaneSyncExecutor {
           expectedTipSha: branchState.tipSha
         });
       case 'halt':
-        return this.executeHalt({
-          laneName,
-          laneIdStr,
-          branch,
-          reason: action.reason,
-          pr
-        });
+        {
+          // The planner only has the boolean; the different-lane id and its PR advice live here.
+          const commentNote = branchNamesDifferentLane && mirroredLane ? branchMirrorsOtherLaneNote(mirroredLane, laneIdStr) : undefined;
+          return this.executeHalt({
+            laneName,
+            laneIdStr,
+            branch,
+            reason: action.reason,
+            pr,
+            commentNote
+          });
+        }
       default:
         {
           // exhaustiveness guard
@@ -660,14 +688,14 @@ class LaneSyncExecutor {
     const message = await this.lastNonSyncCommitMessage(branch, defaultBranch);
     await this.checkoutFromRemote(branch, `origin/${branch}`);
     try {
-      const exportErr = await this.snapAndExportOntoLane(laneIdStr, message);
-      if (exportErr) {
+      const exported = await this.snapAndExportOntoLane(laneIdStr, message);
+      if (exported.status === 'error') {
         // Halt rather than propagate: one lane's failed snap/export must not abort the lanes after it.
         return await this.executeHalt({
           laneName,
           laneIdStr,
           branch,
-          reason: `failed to snap and export branch ${branch} onto lane ${laneIdStr}: ${exportErr.message}`,
+          reason: `failed to snap and export branch ${branch} onto lane ${laneIdStr}: ${exported.error.message}`,
           pr: await this.findPr(branch)
         });
       }
@@ -688,6 +716,71 @@ class LaneSyncExecutor {
     }
   }
 
+  /**
+   * First contact: the lane exists, the branch maps to it by name, but the branch's committed
+   * `.bitmap` has no state for it (typically `bit ci pr --keep-lane` created the lane from this very
+   * branch without recording the pointer in git). Adoption only ever RECORDS a pointer, never resolves
+   * content: switch onto the lane keeping the branch's files, then ask `bit status` whether anything
+   * differs. Nothing → ledger commit; something → halt, lane untouched. Deliberately a status READ,
+   * never a snap: `snapping.snap()` writes an unexported Version object even under `dryRun`, and that
+   * residue can trip a later lane in the same `--all` run.
+   */
+  async executeAdoptBranch({
+    target,
+    laneIdStr,
+    branch,
+    defaultBranch,
+    pr
+  }) {
+    const {
+      logger
+    } = this.deps;
+    const laneName = target.name;
+    logger.console((0, _cli().formatWarningSummary)(`Adopting branch ${branch}: lane ${laneIdStr} exists, but the branch's committed .bitmap has no state for it (first contact)`));
+    await this.checkoutFromRemote(branch, `origin/${branch}`);
+    try {
+      const switchErr = await this.materializeLane(laneIdStr, false);
+      if (switchErr) {
+        return await this.executeHalt({
+          laneName,
+          laneIdStr,
+          branch,
+          reason: `failed to check branch ${branch} against lane ${laneIdStr} for adoption: ${switchErr.message}`,
+          pr: pr ?? (await this.findPr(branch))
+        });
+      }
+      const wouldChangeLane = await this.deps.ci.hasUnsyncedWorkChanges();
+      if (wouldChangeLane) {
+        // Nothing was snapped or exported — the lane is untouched.
+        return await this.executeHalt({
+          laneName,
+          laneIdStr,
+          branch,
+          reason: 'branch has commits but its .bitmap records no state for this lane; cannot tell which side is ' + `newer (adopting would change lane ${laneIdStr}'s content, not just record a pointer)`,
+          pr: pr ?? (await this.findPr(branch))
+        });
+      }
+
+      // Branch content already matches the lane — the ledger commit is all that is missing.
+      const recorded = await this.recordLaneHeadOnBranch(target, laneIdStr, branch, {
+        adopted: true
+      });
+      if (recorded.status === 'raced') return racedAdoptionPushSummary(laneName);
+      if (recorded.status === 'unreadable') {
+        return await this.executeHalt({
+          laneName,
+          laneIdStr,
+          branch,
+          reason: `lane ${laneIdStr} could not be read back from the remote after adopting branch ${branch}`,
+          pr: pr ?? (await this.findPr(branch))
+        });
+      }
+      return `${laneName} -> adopt-branch (branch ${branch} had no lane state; adopted onto lane ${laneIdStr} @ ` + `${recorded.laneHead.slice(0, 9)})`;
+    } finally {
+      await this.restoreWorkspace(defaultBranch);
+    }
+  }
+
   /**
    * Both sides moved since the last sync. Order is load-bearing: (1) merge the lane into the branch's
    * working tree (`bit checkout head`; conflicts halt or auto-resolve per `sync.onConflict`), (2) snap
@@ -756,9 +849,9 @@ class LaneSyncExecutor {
       }
 
       // ---- step 2: snap + export the merged tree onto the lane ---------------------------------
-      const exportErr = await this.snapAndExportOntoLane(laneIdStr, `merge remote lane ${laneIdStr} into ${branch} ${_syncState().SYNC_COMMIT_MARKER}`);
-      if (exportErr) {
-        return await halt(`merged lane ${laneIdStr} into branch ${branch} cleanly, but snapping/exporting the merged ` + `result failed: ${exportErr.message}`);
+      const exported = await this.snapAndExportOntoLane(laneIdStr, `merge remote lane ${laneIdStr} into ${branch} ${_syncState().SYNC_COMMIT_MARKER}`);
+      if (exported.status === 'error') {
+        return await halt(`merged lane ${laneIdStr} into branch ${branch} cleanly, but snapping/exporting the merged ` + `result failed: ${exported.error.message}`);
       }
 
       // ---- step 3: record the new lane head on the branch --------------------------------------
@@ -777,18 +870,17 @@ class LaneSyncExecutor {
   }
 
   /**
-   * Snap the workspace's current tree onto the lane and export it; returns the error so the caller can
-   * halt. Snaps WHATEVER is in the workspace (the switch uses `forceOurs` and never merges files), so
-   * a diverged tree must already hold the merged content. `keepLane` preserves the lane's history,
-   * `skipCleanup` keeps the snap's `.bitmap` for the caller to commit, `noDestructiveRecovery` turns
-   * stale-lane recovery (delete + re-fork the remote lane) into a throw. The lane object must be
-   * imported BEFORE delegating: a switch onto the lane the workspace is already on no-ops before any
-   * fetch, so it never warms a cold scope.
+   * Snap the workspace's current tree onto the lane and export it. Snaps WHATEVER is in the workspace
+   * (the switch uses `forceOurs` and never merges files), so a diverged tree must already hold the
+   * merged content. `keepLane` preserves the lane's history, `skipCleanup` keeps the snap's `.bitmap`
+   * for the caller to commit, `noDestructiveRecovery` turns stale-lane recovery (delete + re-fork the
+   * remote lane) into a throw. The lane object must be imported BEFORE delegating: a switch onto the
+   * lane the workspace is already on no-ops before any fetch, so it never warms a cold scope.
    */
   async snapAndExportOntoLane(laneIdStr, message) {
     try {
       await (0, _workspaceLane().ensureCurrentLaneObject)(this.deps.lanes);
-      await this.deps.ci.snapPrCommit({
+      const result = await this.deps.ci.snapPrCommit({
         laneIdStr,
         message,
         build: undefined,
@@ -797,9 +889,17 @@ class LaneSyncExecutor {
         skipCleanup: true,
         noDestructiveRecovery: true
       });
-      return undefined;
+      if (result === _syncState().NO_CHANGES_TO_SNAP) return {
+        status: 'noop'
+      };
+      return {
+        status: 'exported'
+      };
     } catch (e) {
-      return e instanceof Error ? e : new Error(String(e?.message ?? e));
+      return {
+        status: 'error',
+        error: e instanceof Error ? e : new Error(String(e?.message ?? e))
+      };
     }
   }
 
@@ -808,15 +908,15 @@ class LaneSyncExecutor {
    * so any earlier fingerprint is stale), commit — crucially the `.bitmap` the snap rewrote — and push.
    * `unreadable` means the lane could no longer be read back, in which case the caller halts;
    * `raced` means a concurrent run's push already got there first, in which case the caller reports
-   * a benign noop instead.
+   * a benign noop instead. `adopted` adds the audit-only `ADOPTION_TRAILER`.
    */
-  async recordLaneHeadOnBranch(target, laneIdStr, branch) {
+  async recordLaneHeadOnBranch(target, laneIdStr, branch, opts = {}) {
     const remoteLane = await this.getRemoteLane(target);
     if (!remoteLane) return {
       status: 'unreadable'
     };
     const laneHead = laneHeadFingerprint(remoteLane.components);
-    const pushResult = await this.commitAllAndPush(branch, (0, _syncState().buildSyncCommitMessage)(laneIdStr, laneHead));
+    const pushResult = await this.commitAllAndPush(branch, (0, _syncState().buildSyncCommitMessage)(laneIdStr, laneHead, opts));
     if (pushResult.raced) return {
       status: 'raced'
     };
@@ -925,6 +1025,55 @@ class LaneSyncExecutor {
     }
   }
 
+  /**
+   * Gates `hasIndependentHistoryBelowStateCommit`'s git call to the one case it can change the outcome
+   * for: an `own-live` claim (the only ownership that would otherwise license an immediate delete) with
+   * a reachable state commit to inspect. Extracted out of `reconcileLane` to keep the branching there.
+   */
+  async computeHasIndependentHistory(ownership, stateCommit, defaultBranch) {
+    if (ownership !== 'own-live' || !stateCommit) return false;
+    return this.hasIndependentHistoryBelowStateCommit(stateCommit, defaultBranch);
+  }
+
+  /**
+   * Whether the OLDEST commit unique to the branch is NOT bit-authored — durable, ancestry-based proof
+   * a human created the branch before this reconciler touched it (a trailer would not survive later
+   * ledger commits; see `oldestCommitIsNonSync` for the oldest-only rationale). Unreadable answers
+   * `true`: a deletion guard errs toward keeping.
+   */
+  async hasIndependentHistoryBelowStateCommit(stateCommit, defaultBranch) {
+    try {
+      const log = await _git().git.raw(['log', `origin/${defaultBranch}..${stateCommit}`, '--first-parent', '--reverse', '--format=%B%x1e']);
+      return (0, _syncState().oldestCommitIsNonSync)(log);
+    } catch (e) {
+      this.deps.logger.consoleWarning(`Could not read ${stateCommit}'s history against ${defaultBranch} to check for independent, ` + `pre-existing branch history; treating it as present (the branch is kept, not deleted): ${e?.message || e}`);
+      return true;
+    }
+  }
+
+  /** Gates `differentLaneStillClaims` to the planner's first-contact path, the only one that reads it. */
+  async computeBranchNamesDifferentLane(lastSyncedHead, hasDevCommits, mirroredLane, laneIdStr, branch, defaultBranch) {
+    if (lastSyncedHead || !hasDevCommits) return false;
+    return this.differentLaneStillClaims(mirroredLane, laneIdStr, branch, defaultBranch);
+  }
+
+  /**
+   * Whether adoption must refuse `branch` because its `.bitmap` names a DIFFERENT lane's still-live
+   * claim. Blob equality with the fork-point `.bitmap`, not commit reachability: an `own-superseded`
+   * branch is reachable yet still carries live work; only a `.bitmap` the branch never changed proves
+   * the pointer is inherited. Unreadable stays conservative and blocks adoption.
+   */
+  async differentLaneStillClaims(mirroredLane, laneIdStr, branch, defaultBranch) {
+    if (!mirroredLane || mirroredLane === laneIdStr) return false;
+    const inherited = await this.branchInheritsBitmapFromDefault(branch, defaultBranch);
+    return !inherited;
+  }
+
+  /** Seam over `branchBitmapUnchangedSinceFork`, so `differentLaneStillClaims` is unit-testable without a real remote. */
+  branchInheritsBitmapFromDefault(branch, defaultBranch) {
+    return (0, _syncState().branchBitmapUnchangedSinceFork)(branch, defaultBranch);
+  }
+
   /**
    * The lane is gone from bit.cloud — close its PR, and retire the branch if the claim on it allows.
    * Deleting the branch is the one irreversible thing this command does; `keepReason` distinguishes
@@ -1084,14 +1233,17 @@ class LaneSyncExecutor {
   }
 
   /**
-   * Drive the workspace's filesystem to the remote lane's content; returns the error so the caller can
-   * halt. Two traps make a plain `switchToLane` insufficient: (1) it defaults to `forceOurs`, which
-   * never touches the filesystem — the commit would claim the branch mirrors the lane over the default
-   * branch's files — so `forceOurs` is cleared and `forceTheirs` set; (2) switching onto the lane the
-   * workspace already sits on throws "already checked out", which `switchToLane` swallows as success
-   * and nothing materializes — so step off to main first.
+   * Drive the workspace's filesystem onto the remote lane; returns the error so the caller can halt.
+   * Two traps make a plain `switchToLane` insufficient: (1) its default `forceOurs` never touches the
+   * filesystem, so the caller's commit would misrepresent whichever side it claims mirrors the other;
+   * (2) switching onto the lane the workspace already sits on throws "already checked out", which
+   * `switchToLane` swallows as success and nothing materializes — so step off to main first.
+   *
+   * `theirsWins` picks the direction: `true` (import-lane) checks the lane's files out over the disk;
+   * `false` (adopt-branch) keeps the workspace's files — the branch's content is what the lane is
+   * being asked to reflect.
    */
-  async materializeLane(laneIdStr) {
+  async materializeLane(laneIdStr, theirsWins = true) {
     const {
       logger
     } = this.deps;
@@ -1108,9 +1260,16 @@ class LaneSyncExecutor {
       }
     }
     const switchErr = await this.deps.ci.switchToLaneForSync(laneIdStr, {
-      forceOurs: false,
-      forceTheirs: true,
-      writeAdoptedFiles: true
+      forceOurs: !theirsWins,
+      forceTheirs: theirsWins,
+      // The whole lane has to land in the workspace here, including components it has that this
+      // workspace doesn't track yet - materializing the lane is the point of this step. That is the
+      // opposite of `bit ci pr`, where the git checkout is the source of truth and `switchToLane`'s
+      // `workspaceOnly` default keeps the switch from writing lane-only components.
+      workspaceOnly: false,
+      // Follows the direction: in adopt mode the missing-component retry must not write the lane's
+      // files over the branch's — the ledger commit would then push the lane's content onto the branch.
+      writeAdoptedFiles: theirsWins
     });
     if (switchErr) return switchErr;