@teambit/ci 1.0.495 → 1.0.500

package/sync/lane-sync-executor.spec.ts

@@ -15,6 +15,7 @@ import {
   laneSyncPrBody,
   racedLedgerPushSummary,
 } from './lane-sync-executor';
+import type { LaneOwnershipEvidence } from './sync-planner';
 import { resolveSyncConfig } from './sync-config';
 
 /**
@@ -387,6 +388,87 @@ describe('close-pr re-verifies the tip before retiring a branch', () => {
   });
 });
 
+describe('differentLaneStillClaims uses .bitmap blob equality, not commit reachability', () => {
+  function executorWithInheritance(inherited: boolean) {
+    const executor = new LaneSyncExecutor({
+      lanes: {} as any,
+      ci: {} as any,
+      logger: { console: () => {}, consoleWarning: () => {}, error: () => {} } as any,
+      gitHost: undefined,
+      cfg: resolveSyncConfig({}),
+      defaultScope: 'acme.shop',
+    });
+    (executor as any).branchInheritsBitmapFromDefault = async () => inherited;
+    return (mirroredLane: string | undefined, laneIdStr: string) =>
+      (executor as any).differentLaneStillClaims(mirroredLane, laneIdStr, 'my-branch', 'main') as Promise<boolean>;
+  }
+
+  it('does not claim when there is no mirrored lane pointer at all — never even checks the blob', async () => {
+    const differentLaneStillClaims = executorWithInheritance(true);
+    expect(await differentLaneStillClaims(undefined, 'acme.shop/my-lane')).to.equal(false);
+  });
+
+  it("does not claim for this lane's own pointer — never even checks the blob", async () => {
+    const differentLaneStillClaims = executorWithInheritance(true);
+    expect(await differentLaneStillClaims('acme.shop/my-lane', 'acme.shop/my-lane')).to.equal(false);
+  });
+
+  it("does not claim when the different-lane .bitmap is byte-identical to the default branch's — inherited", async () => {
+    const differentLaneStillClaims = executorWithInheritance(true);
+    expect(await differentLaneStillClaims('acme.shop/other-lane', 'acme.shop/my-lane')).to.equal(false);
+  });
+
+  it("STILL claims when the different-lane .bitmap has diverged from the default branch's — halt, not adopt", async () => {
+    const differentLaneStillClaims = executorWithInheritance(false);
+    expect(await differentLaneStillClaims('acme.shop/other-lane', 'acme.shop/my-lane')).to.equal(true);
+  });
+});
+
+describe('computeHasIndependentHistory gates the ancestry check to own-live claims with a state commit', () => {
+  function executorWithAncestryResult(result: boolean) {
+    const calls: Array<[string, string]> = [];
+    const executor = new LaneSyncExecutor({
+      lanes: {} as any,
+      ci: {} as any,
+      logger: { console: () => {}, consoleWarning: () => {}, error: () => {} } as any,
+      gitHost: undefined,
+      cfg: resolveSyncConfig({}),
+      defaultScope: 'acme.shop',
+    });
+    (executor as any).hasIndependentHistoryBelowStateCommit = async (stateCommit: string, defaultBranch: string) => {
+      calls.push([stateCommit, defaultBranch]);
+      return result;
+    };
+    const compute = (ownership: LaneOwnershipEvidence, stateCommit: string | undefined, defaultBranch: string) =>
+      (executor as any).computeHasIndependentHistory(ownership, stateCommit, defaultBranch) as Promise<boolean>;
+    return { compute, calls };
+  }
+
+  it('skips the ancestry check entirely for a reachable claim (own-merged)', async () => {
+    const { compute, calls } = executorWithAncestryResult(true);
+    expect(await compute('own-merged', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', 'main')).to.equal(false);
+    expect(calls).to.deep.equal([]);
+  });
+
+  it('skips the ancestry check entirely for own-superseded too', async () => {
+    const { compute, calls } = executorWithAncestryResult(true);
+    expect(await compute('own-superseded', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', 'main')).to.equal(false);
+    expect(calls).to.deep.equal([]);
+  });
+
+  it('skips the check when there is no state commit to inspect, even for an own-live claim', async () => {
+    const { compute, calls } = executorWithAncestryResult(true);
+    expect(await compute('own-live', undefined, 'main')).to.equal(false);
+    expect(calls).to.deep.equal([]);
+  });
+
+  it('defers to the ancestry check for an own-live claim with a state commit', async () => {
+    const { compute, calls } = executorWithAncestryResult(true);
+    expect(await compute('own-live', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', 'main')).to.equal(true);
+    expect(calls).to.deep.equal([['aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1', 'main']]);
+  });
+});
+
 describe('classifyPushRejection confirms a race before calling it one', () => {
   const BASE_SHA = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1';
   const MOVED_SHA = 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb2';
@@ -446,9 +528,8 @@ describe('executeExportBranch reports the ledger-race wording when only the ledg
     (executor as any).lastNonSyncCommitMessage = async () => 'feat: some change';
     (executor as any).checkoutFromRemote = async () => {};
     (executor as any).restoreWorkspace = async () => {};
-    // The export half already succeeded (undefined = no error, matching this file's `Error | undefined`
-    // contract for `snapAndExportOntoLane`); only the ledger commit that follows raced.
-    (executor as any).snapAndExportOntoLane = async () => undefined;
+    // The export half already succeeded; only the ledger commit that follows raced.
+    (executor as any).snapAndExportOntoLane = async () => ({ status: 'exported' });
     (executor as any).recordLaneHeadOnBranch = async () => ({ status: 'raced' });
 
     const summary = await (executor as any).executeExportBranch({
@@ -465,6 +546,32 @@ describe('executeExportBranch reports the ledger-race wording when only the ledg
   });
 });
 
+// Adoption never snaps or exports, so its raced line must NOT claim the lane was updated — the lane
+// is untouched and only the branch's pointer commit lost the race.
+describe('executeAdoptBranch reports a lane-untouched race when its ledger push races', () => {
+  it('surfaces "lane untouched; adoption ledger commit lost the push race" without halting', async () => {
+    const { executor } = stubExecutor();
+    (executor as any).deps.ci = { hasUnsyncedWorkChanges: async () => false };
+    (executor as any).checkoutFromRemote = async () => {};
+    (executor as any).restoreWorkspace = async () => {};
+    (executor as any).materializeLane = async () => undefined;
+    (executor as any).recordLaneHeadOnBranch = async () => ({ status: 'raced' });
+
+    const summary = await (executor as any).executeAdoptBranch({
+      target: { hostScope: 'acme.shop', name: 'my-lane' },
+      laneIdStr: 'acme.shop/my-lane',
+      branch: 'my-lane',
+      defaultBranch: 'main',
+    });
+
+    expect(summary).to.equal(
+      'my-lane -> raced (lane untouched; adoption ledger commit lost the push race — next run re-plans)'
+    );
+    expect(summary).to.not.include('lane updated');
+    expect(summary).to.not.include('HALTED');
+  });
+});
+
 // A destructive auto-resolution (onConflict git-wins/lane-wins) that already exported must not vanish
 // from the summary just because the ledger push raced.
 describe('racedLedgerPushSummary keeps the conflict-policy clause', () => {

package/sync/lane-sync-executor.ts

@@ -12,11 +12,14 @@ import { laneNameToBranch } from './sync-config';
 import type { BranchSyncState } from './sync-state';
 import {
   CONFLICT_LABEL,
+  NO_CHANGES_TO_SNAP,
   SYNC_COMMIT_MARKER,
+  branchBitmapUnchangedSinceFork,
   branchStateFingerprint,
   buildSyncCommitMessage,
   fingerprintIdVersions,
   readBranchSyncState,
+  oldestCommitIsNonSync,
   hasSyncMarker,
   isSyncAuthoredMessage,
 } from './sync-state';
@@ -89,6 +92,15 @@ export function racedLedgerPushSummary(laneName: string, policyClause = ''): str
   );
 }
 
+/**
+ * `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 function racedAdoptionPushSummary(laneName: string): string {
+  return racedSummary(laneName, 'lane untouched; adoption ledger commit lost the push race — next run re-plans');
+}
+
 export type LaneSyncDeps = {
   lanes: LanesMain;
   /** for snapPrCommit + getDefaultBranchName + switchToLaneForSync */
@@ -245,6 +257,7 @@ export const KEPT_BECAUSE: Record<BranchKeepReason, string> = {
   '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`,
+  'adopted-branch': `it was adopted from a pre-existing branch, and only merging (not deleting) proves its history is safe to retire`,
 };
 
 export class LaneSyncExecutor {
@@ -423,6 +436,20 @@ export 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 = 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 = planLaneSync({
       laneHead,
@@ -430,7 +457,9 @@ export class LaneSyncExecutor {
       lastSyncedHead,
       hasDevCommits: branchState.hasDevCommits,
       tipIsSyncCommit,
+      hasIndependentHistory,
       conflictLabelPresent,
+      branchNamesDifferentLane,
       ownership,
     });
 
@@ -497,6 +526,8 @@ export class LaneSyncExecutor {
         return this.executeExportBranch({ target, laneIdStr, branch, defaultBranch });
       case 'merge-diverged':
         return this.executeMergeDiverged({ target, laneIdStr, branch, defaultBranch });
+      case 'adopt-branch':
+        return this.executeAdoptBranch({ target, laneIdStr, branch, defaultBranch, pr });
       case 'close-pr':
         return this.executeClosePr({
           laneName,
@@ -508,8 +539,12 @@ export class LaneSyncExecutor {
           keepReason: action.deleteBranch ? undefined : action.keepReason,
           expectedTipSha: branchState.tipSha,
         });
-      case 'halt':
-        return this.executeHalt({ laneName, laneIdStr, branch, reason: action.reason, pr });
+      case 'halt': {
+        // 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
         const unhandled: never = action;
@@ -665,14 +700,14 @@ export class LaneSyncExecutor {
     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),
         });
       }
@@ -697,6 +732,85 @@ export 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.
+   */
+  private async executeAdoptBranch({
+    target,
+    laneIdStr,
+    branch,
+    defaultBranch,
+    pr,
+  }: {
+    target: LaneTarget;
+    laneIdStr: string;
+    branch: string;
+    defaultBranch: string;
+    pr?: PrInfo;
+  }): Promise<string> {
+    const { logger } = this.deps;
+    const laneName = target.name;
+    logger.console(
+      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
@@ -787,14 +901,14 @@ export class LaneSyncExecutor {
       }
 
       // ---- step 2: snap + export the merged tree onto the lane ---------------------------------
-      const exportErr = await this.snapAndExportOntoLane(
+      const exported = await this.snapAndExportOntoLane(
         laneIdStr,
         `merge remote lane ${laneIdStr} into ${branch} ${SYNC_COMMIT_MARKER}`
       );
-      if (exportErr) {
+      if (exported.status === 'error') {
         return await halt(
           `merged lane ${laneIdStr} into branch ${branch} cleanly, but snapping/exporting the merged ` +
-            `result failed: ${exportErr.message}`
+            `result failed: ${exported.error.message}`
         );
       }
 
@@ -819,18 +933,20 @@ export 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.
    */
-  private async snapAndExportOntoLane(laneIdStr: string, message: string): Promise<Error | undefined> {
+  private async snapAndExportOntoLane(
+    laneIdStr: string,
+    message: string
+  ): Promise<{ status: 'noop' | 'exported' } | { status: 'error'; error: Error }> {
     try {
       await ensureCurrentLaneObject(this.deps.lanes);
-      await this.deps.ci.snapPrCommit({
+      const result = await this.deps.ci.snapPrCommit({
         laneIdStr,
         message,
         build: undefined,
@@ -839,9 +955,10 @@ export class LaneSyncExecutor {
         skipCleanup: true,
         noDestructiveRecovery: true,
       });
-      return undefined;
+      if (result === NO_CHANGES_TO_SNAP) return { status: 'noop' };
+      return { status: 'exported' };
     } catch (e: any) {
-      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)) };
     }
   }
 
@@ -850,17 +967,18 @@ export 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 async recordLaneHeadOnBranch(
     target: LaneTarget,
     laneIdStr: string,
-    branch: string
+    branch: string,
+    opts: { adopted?: boolean } = {}
   ): Promise<{ status: 'unreadable' } | { status: 'raced' } | { status: 'ok'; laneHead: string }> {
     const remoteLane = await this.getRemoteLane(target);
     if (!remoteLane) return { status: 'unreadable' };
     const laneHead = laneHeadFingerprint(remoteLane.components);
-    const pushResult = await this.commitAllAndPush(branch, buildSyncCommitMessage(laneIdStr, laneHead));
+    const pushResult = await this.commitAllAndPush(branch, buildSyncCommitMessage(laneIdStr, laneHead, opts));
     if (pushResult.raced) return { status: 'raced' };
     return { status: 'ok', laneHead };
   }
@@ -977,6 +1095,80 @@ export 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.
+   */
+  private async computeHasIndependentHistory(
+    ownership: LaneOwnershipEvidence,
+    stateCommit: string | undefined,
+    defaultBranch: string
+  ): Promise<boolean> {
+    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.
+   */
+  private async hasIndependentHistoryBelowStateCommit(stateCommit: string, defaultBranch: string): Promise<boolean> {
+    try {
+      const log = await git.raw([
+        'log',
+        `origin/${defaultBranch}..${stateCommit}`,
+        '--first-parent',
+        '--reverse',
+        '--format=%B%x1e',
+      ]);
+      return oldestCommitIsNonSync(log);
+    } catch (e: any) {
+      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. */
+  private async computeBranchNamesDifferentLane(
+    lastSyncedHead: string | undefined,
+    hasDevCommits: boolean,
+    mirroredLane: string | undefined,
+    laneIdStr: string,
+    branch: string,
+    defaultBranch: string
+  ): Promise<boolean> {
+    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.
+   */
+  private async differentLaneStillClaims(
+    mirroredLane: string | undefined,
+    laneIdStr: string,
+    branch: string,
+    defaultBranch: string
+  ): Promise<boolean> {
+    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. */
+  private branchInheritsBitmapFromDefault(branch: string, defaultBranch: string): Promise<boolean> {
+    return 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
@@ -1178,14 +1370,17 @@ export 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.
    */
-  private async materializeLane(laneIdStr: string): Promise<Error | undefined> {
+  private async materializeLane(laneIdStr: string, theirsWins = true): Promise<Error | undefined> {
     const { logger } = this.deps;
     const target = await this.deps.lanes.parseLaneId(laneIdStr);
     // Compares name AND scope, and reads from `.bitmap`, not the scope's lane object — the object read
@@ -1206,9 +1401,16 @@ export 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;
 

package/sync/sync-planner.spec.ts

@@ -62,6 +62,13 @@ const table: Array<{
     type: 'close-pr',
     action: { type: 'close-pr', deleteBranch: false, keepReason: 'unmerged-commits' },
   },
+  {
+    // Adoption proved content matched, never that the branch's pre-existing history is disposable.
+    name: 'own-live, no dev commits, OUR tip, but it is the adoption ledger commit -> KEEP, never delete',
+    input: { ...laneGone('own-live'), hasIndependentHistory: true },
+    type: 'close-pr',
+    action: { type: 'close-pr', deleteBranch: false, keepReason: 'adopted-branch' },
+  },
   {
     name: 'own-merged (branch tip already in the default branch) -> close-pr AND delete',
     input: laneGone('own-merged'),
@@ -75,6 +82,12 @@ const table: Array<{
     type: 'close-pr',
     action: { type: 'close-pr', deleteBranch: true },
   },
+  {
+    name: 'own-merged deletes even when the tip is the adoption ledger commit — reachability is enough',
+    input: { ...laneGone('own-merged'), hasIndependentHistory: true },
+    type: 'close-pr',
+    action: { type: 'close-pr', deleteBranch: true },
+  },
   {
     name: 'own-superseded (PR merged, then more commits pushed) -> close-pr but KEEP the branch',
     input: laneGone('own-superseded'),
@@ -108,9 +121,31 @@ const table: Array<{
     type: 'import-lane',
   },
   {
-    name: 'existing branch, never synced, has dev commits, lane EXISTS -> halt (ambiguous)',
+    name: 'existing branch, never synced, has dev commits, lane EXISTS -> adopt-branch (first contact)',
     input: { lastSyncedHead: undefined, ownership: 'inherited-or-none', hasDevCommits: true },
+    type: 'adopt-branch',
+  },
+  {
+    name: 'existing branch, never synced, has dev commits, but .bitmap names a DIFFERENT lane -> halt',
+    input: {
+      lastSyncedHead: undefined,
+      ownership: 'inherited-or-none',
+      hasDevCommits: true,
+      branchNamesDifferentLane: true,
+    },
     type: 'halt',
+    reason: 'names a different lane',
+  },
+  {
+    // The executor resolves an inherited (merged) different-lane pointer to `false` — history, not a claim.
+    name: 'existing branch, has dev commits, .bitmap names a MERGED-AND-INHERITED different lane -> adopt-branch',
+    input: {
+      lastSyncedHead: undefined,
+      ownership: 'inherited-or-none',
+      hasDevCommits: true,
+      branchNamesDifferentLane: false,
+    },
+    type: 'adopt-branch',
   },
 ];