@teambit/ci 1.0.523 → 1.0.524

package/sync/heal-missing-main-files.ts

@@ -0,0 +1,153 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { formatWarningSummary } from '@teambit/cli';
+import type { Logger } from '@teambit/logger';
+import type { Workspace } from '@teambit/workspace';
+import type { ComponentID } from '@teambit/component-id';
+import { ComponentIdList } from '@teambit/component-id';
+import { capEntries } from './lane-sync-executor';
+
+/**
+ * A `.bitmap` entry whose recorded `mainFile` is no longer on disk cannot be loaded at all — the
+ * component loader throws `MainFileRemoved`, and that one entry fails the whole `bit checkout head`
+ * the main-scope reconciler runs, so every scheduled run stays red until a human intervenes.
+ *
+ * The shape is legitimate: a new version moves the component's main file (e.g. an env stops emitting
+ * `dist/`, so main goes from `dist/index.d.ts` back to source), the old path is deleted in git, and
+ * this repository's `.bitmap` still names it.
+ *
+ * Two heals, cheapest first:
+ *   1. RETARGET — the scope's current version names a main file that IS in this repository, so only
+ *      the `.bitmap` pointer is stale. Rewrite it and the component loads; nothing moves on disk.
+ *   2. UNTRACK — the scope's current version was read, and the main file it names is not here
+ *      either. Drop the entry; main sync's `includeNewFromScope` re-imports the component from the
+ *      scope's main. This one writes the component to a fresh directory, so it shows up as a move in
+ *      the sync PR.
+ *
+ * An entry is only ever untracked on a POSITIVE read of the scope's head. A component the scope does
+ * not have, or whose objects could not be read (a failed import, a corrupt object), is left exactly
+ * as it is and reported: a transient remote failure must not delete a `.bitmap` entry, and the run
+ * failing loudly on it is the honest outcome.
+ *
+ * Deliberately ci-local: making the checkout itself tolerate an unloadable component would change
+ * `bit checkout` for every caller passing a "theirs" resolution.
+ */
+export type MainFileHeal = { id: string; retargetedTo?: string };
+
+/**
+ * Fetch the remote head of the stale components. Without it the local scope still holds the version
+ * this repository already had — whose main file is the missing one — and every entry would look
+ * unrepairable. A failure is not fatal on its own (local objects may still answer), but it must
+ * never be mistaken for "the scope says this is gone", and its cause is the first thing an operator
+ * needs when a scheduled run starts leaving entries untouched — so it is carried, not swallowed.
+ */
+async function importHeadsOf(
+  workspace: Workspace,
+  ids: ComponentID[]
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  try {
+    await workspace.scope.legacyScope.scopeImporter.importWithoutDeps(
+      ComponentIdList.fromArray(ids).toVersionLatest(),
+      { cache: false, ignoreMissingHead: true }
+    );
+    return { ok: true };
+  } catch (e: any) {
+    return { ok: false, error: e?.message || String(e) };
+  }
+}
+
+/**
+ * What the scope's current (head) version says the component's main file is. The three outcomes are
+ * deliberately distinct: only `read` licenses a destructive heal.
+ */
+type ScopeMainFile =
+  | { status: 'read'; mainFile: string }
+  /** the scope has no such component, or no head for it — nothing to compare against */
+  | { status: 'absent' }
+  /** objects could not be read (failed import, corrupt object) — the answer is unknown */
+  | { status: 'unreadable'; reason: string };
+
+async function mainFileOnScopeHead(workspace: Workspace, id: ComponentID): Promise<ScopeMainFile> {
+  const legacyScope = workspace.scope.legacyScope;
+  try {
+    const modelComponent = await legacyScope.getModelComponentIfExist(id);
+    const head = modelComponent?.getHeadRegardlessOfLaneAsTagOrHash();
+    if (!modelComponent || !head) return { status: 'absent' };
+    const version = await modelComponent.loadVersion(head, legacyScope.objects);
+    if (!version?.mainFile) return { status: 'absent' };
+    return { status: 'read', mainFile: version.mainFile };
+  } catch (e: any) {
+    return { status: 'unreadable', reason: e?.message || String(e) };
+  }
+}
+
+/**
+ * Heal every `.bitmap` entry whose main file is missing, and persist. Returns what was healed so the
+ * caller can report it; the `.bitmap` change rides the sync commit like any other drift.
+ */
+export async function healMissingMainFiles(workspace: Workspace, logger: Logger): Promise<MainFileHeal[]> {
+  const workspacePath = workspace.path;
+  const { bitMap } = workspace.consumer;
+  const onDisk = (rootDir: string, file: string) => fs.existsSync(path.join(workspacePath, rootDir, file));
+
+  const stale = bitMap.components.filter((componentMap) => {
+    const { rootDir, mainFile } = componentMap;
+    return Boolean(rootDir) && Boolean(mainFile) && !onDisk(rootDir as string, mainFile);
+  });
+  if (!stale.length) return [];
+
+  const headFetch = await importHeadsOf(
+    workspace,
+    stale.map((componentMap) => componentMap.id)
+  );
+
+  const healed: MainFileHeal[] = [];
+  const skipped: string[] = [];
+  for (const componentMap of stale) {
+    const id = componentMap.id.toStringWithoutVersion();
+    const onScope = await mainFileOnScopeHead(workspace, componentMap.id);
+    if (onScope.status === 'read' && onDisk(componentMap.rootDir as string, onScope.mainFile)) {
+      componentMap.mainFile = onScope.mainFile;
+      bitMap.markAsChanged();
+      healed.push({ id, retargetedTo: onScope.mainFile });
+    } else if (onScope.status === 'read') {
+      // Positively read, and the file it names is not here either: the whole component is gone from
+      // this tree, so the entry cannot be repaired in place.
+      bitMap.removeComponent(componentMap.id);
+      healed.push({ id });
+    } else {
+      // Unknown, never assumed: leave the entry and let the checkout fail with its own message.
+      skipped.push(`${id} (${onScope.status === 'absent' ? 'not on the scope' : `unreadable: ${onScope.reason}`})`);
+    }
+  }
+  if (healed.length) await bitMap.write();
+
+  if (skipped.length) {
+    logger.consoleWarning(
+      `Left ${skipped.length} .bitmap entr(ies) with a missing main file untouched — the scope could not ` +
+        `confirm what to repair them to: ${capEntries(skipped).join(', ')}` +
+        (headFetch.ok ? '' : `. Fetching their heads failed first: ${headFetch.error}`)
+    );
+  }
+
+  const retargeted = healed.filter((heal) => heal.retargetedTo);
+  const untracked = healed.filter((heal) => !heal.retargetedTo);
+  if (retargeted.length) {
+    logger.console(
+      formatWarningSummary(
+        `Repointed ${retargeted.length} .bitmap entr(ies) at the main file the scope's current version ` +
+          `records: ${capEntries(retargeted.map((heal) => `${heal.id} -> ${heal.retargetedTo}`)).join(', ')}`
+      )
+    );
+  }
+  if (untracked.length) {
+    logger.console(
+      formatWarningSummary(
+        `Untracked ${untracked.length} component(s) whose recorded main file is gone from this repository, ` +
+          `so the scope's current version can be written in their place: ` +
+          `${capEntries(untracked.map((heal) => heal.id)).join(', ')}`
+      )
+    );
+  }
+  return healed;
+}

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

@@ -15,6 +15,7 @@ import {
   laneHeadFingerprint,
   LaneSyncExecutor,
   laneSyncPrBody,
+  ownLaneComponents,
   racedLedgerPushSummary,
   RUN_SUMMARY_MARKER,
   runSummaryCommentBody,
@@ -102,12 +103,38 @@ describe('foreignLaneComponents', () => {
   });
 });
 
+describe('ownLaneComponents', () => {
+  const DEFAULT_SCOPE = 'acme.shop';
+  const ours = comp('acme.shop/comp1', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1');
+  const theirs = comp('other.scope/comp2', 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb2');
+
+  it('is the exact complement of foreignLaneComponents: together they cover the lane', () => {
+    const own = ownLaneComponents([ours, theirs], DEFAULT_SCOPE);
+    expect(own.map((c) => c.id.toStringWithoutVersion())).to.deep.equal(['acme.shop/comp1']);
+    expect(foreignLaneComponents([ours, theirs], DEFAULT_SCOPE)).to.deep.equal(['other.scope/comp2']);
+  });
+
+  it('fingerprints only the own slice, so a foreign head moving does not read as the lane moving', () => {
+    const theirsMoved = comp('other.scope/comp2', 'cccccccccccccccccccccccccccccccccccccc33');
+    expect(laneHeadFingerprint(ownLaneComponents([ours, theirs], DEFAULT_SCOPE))).to.equal(
+      laneHeadFingerprint(ownLaneComponents([ours, theirsMoved], DEFAULT_SCOPE))
+    );
+  });
+
+  it('an own head moving still reads as the lane moving', () => {
+    const oursMoved = comp('acme.shop/comp1', 'dddddddddddddddddddddddddddddddddddddd44');
+    expect(laneHeadFingerprint(ownLaneComponents([ours, theirs], DEFAULT_SCOPE))).to.not.equal(
+      laneHeadFingerprint(ownLaneComponents([oursMoved, theirs], DEFAULT_SCOPE))
+    );
+  });
+});
+
 describe('crossScopeDescription', () => {
   const DEFAULT_SCOPE = 'acme.shop';
 
   it('names the foreign scopes and this repository scope', () => {
     const description = crossScopeDescription(['other.scope/comp2', 'third.scope/comp3'], DEFAULT_SCOPE);
-    expect(description).to.include('components from scope(s) other.scope, third.scope');
+    expect(description).to.include('every component is from scope(s) other.scope, third.scope');
     expect(description).to.include(`(this repo maps scope ${DEFAULT_SCOPE})`);
     expect(description).to.include('foreign components: other.scope/comp2, third.scope/comp3');
   });
@@ -129,15 +156,21 @@ describe('crossScopeDescription', () => {
 describe('laneSyncPrBody', () => {
   const LANE_HEAD = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1';
 
-  function body(componentCount: number) {
+  function body(componentCount: number, foreignCount = 0) {
     return laneSyncPrBody({
       laneIdStr: 'acme.shop/my-lane',
       laneUrl: 'https://bit.cloud/acme/shop/~lane/my-lane',
       branch: 'my-lane',
       laneHead: LANE_HEAD,
-      components: Array.from({ length: componentCount }, (_, index) =>
-        comp(`acme.shop/namespace/component-with-a-realistic-name-${index}`, `${'0'.repeat(39)}${index % 10}`)
-      ),
+      components: [
+        ...Array.from({ length: componentCount }, (_, index) =>
+          comp(`acme.shop/namespace/component-with-a-realistic-name-${index}`, `${'0'.repeat(39)}${index % 10}`)
+        ),
+        ...Array.from({ length: foreignCount }, (_, index) =>
+          comp(`other.scope/namespace/foreign-component-${index}`, `${'1'.repeat(39)}${index % 10}`)
+        ),
+      ],
+      defaultScope: 'acme.shop',
     });
   }
 
@@ -165,15 +198,43 @@ describe('laneSyncPrBody', () => {
   it('says so explicitly when the lane has no components', () => {
     expect(body(0)).to.include('_none_');
   });
+
+  it('a single-scope lane gets no foreign section and no "N of M" phrasing', () => {
+    const rendered = body(3);
+    expect(rendered).to.include('Components on the lane (3):');
+    expect(rendered).to.not.include('other scopes');
+    expect(rendered).to.not.include(' of ');
+  });
+
+  it('a cross-scope lane lists the mirrored slice and the foreign components separately', () => {
+    const rendered = body(2, 3);
+    expect(rendered).to.include('Components mirrored from the lane (2 of 5):');
+    expect(rendered).to.include('component-with-a-realistic-name-1');
+    expect(rendered).to.include('Also on this lane, from other scopes (3)');
+    expect(rendered).to.include('package dependencies');
+    expect(rendered).to.include('`other.scope/namespace/foreign-component-2`');
+    // The foreign entries must not appear in the mirrored list's id/head format.
+    expect(rendered).to.not.include('`other.scope/namespace/foreign-component-0` @');
+  });
+
+  it('the foreign section is capped like the mirrored list, so the body stays inside the host limit', () => {
+    const rendered = body(2, 100);
+    expect(rendered).to.include('foreign-component-19');
+    expect(rendered).to.not.include('foreign-component-20`');
+    expect(rendered).to.include('and 80 more');
+    expect(body(2000, 3000).length).to.be.below(60000);
+  });
 });
 
+// These outcomes apply ONLY to a lane with no own-scope components at all — a lane that merely
+// includes foreign components is reconciled over its own-scope slice and never reaches them.
 describe('cross-scope outcome messages', () => {
   const DEFAULT_SCOPE = 'acme.shop';
   const FOREIGN = ['other.scope/comp2'];
 
   it('an enumerated lane is SKIPPED, in the vocabulary of a healthy run', () => {
     const summary = crossScopeSkipSummary('my-lane', FOREIGN, DEFAULT_SCOPE);
-    expect(summary).to.match(/^my-lane -> skipped \(cross-scope lane: /);
+    expect(summary).to.match(/^my-lane -> skipped \(nothing to mirror: /);
     expect(summary).to.include('no branch created');
     // A HALTED/REFUSED marker in this line would flip the exit code of a healthy repository.
     expect(summary).to.not.include('HALTED');
@@ -182,8 +243,8 @@ describe('cross-scope outcome messages', () => {
 
   it('an explicitly requested lane is REFUSED, with the reason and the "nothing was written" promise', () => {
     const refusal = crossScopeRefusal(FOREIGN, DEFAULT_SCOPE);
-    expect(refusal).to.include('cross-scope lane: components from scope(s) other.scope');
-    expect(refusal).to.include("not supported yet — see the docs' Cross-scope lanes section");
+    expect(refusal).to.include('nothing to mirror: every component is from scope(s) other.scope');
+    expect(refusal).to.include("See the docs' Cross-scope lanes section");
     expect(refusal).to.include('No branch was created and nothing was written');
   });
 
@@ -193,9 +254,9 @@ describe('cross-scope outcome messages', () => {
     expect(refusal).to.not.include('No branch was created');
   });
 
-  it('a lane that became cross-scope mid-flight names the branch it can no longer converge with', () => {
+  it('a mirrored lane whose own slice emptied names the branch it can no longer converge with', () => {
     const reason = crossScopeMidFlightHaltReason('my-lane', FOREIGN, DEFAULT_SCOPE);
-    expect(reason).to.include('lane became cross-scope after it was mirrored onto my-lane');
+    expect(reason).to.include('every acme.shop component left the lane after it was mirrored onto my-lane');
     expect(reason).to.include('can no longer be reconciled automatically');
   });
 });
@@ -602,6 +663,15 @@ describe('executeExportBranch bails when the lane moved since planning', () => {
     expect(summary).to.include('my-lane -> noop (converged)');
     expect(touched).to.deep.equal(['status']);
   });
+
+  it('a lane whose only movement is a foreign head proceeds — foreign heads are not this mirror to diverge', async () => {
+    const planned = [...L1, comp('other.scope/comp2', 'eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee5')];
+    const current = [...L1, comp('other.scope/comp2', 'fffffffffffffffffffffffffffffffffffffff6')];
+    const { run, touched } = stubExport(current, planned);
+    const summary = await run();
+    expect(summary).to.include('my-lane -> noop (converged)');
+    expect(touched).to.deep.equal(['status']);
+  });
 });
 
 // The merge path snaps whatever the merge produced — which can be nothing new, now routinely: a

package/sync/lane-sync-executor.ts

@@ -135,15 +135,25 @@ function laneComponentIds(components: LaneData['components']): string[] {
 }
 
 /**
- * The lane's components that do not belong to `defaultScope`. A lane may span scopes, and the
- * reconciler acts on a lane whole (fingerprint, materialize, snap, export), so foreign content is
- * refused rather than written into this repository. Soft-deleted components and `updateDependents`
- * entries are deliberately not read — the reconciler never materializes or exports them either.
+ * The lane's components that do not belong to `defaultScope`. A lane may span scopes; this
+ * repository reconciles only its own-scope slice (see `ownLaneComponents`), and the foreign entries
+ * ride along on the lane untouched — sourced in their own scopes' repositories and reachable here
+ * only as package dependencies. Soft-deleted components and `updateDependents` entries are
+ * deliberately not read — the reconciler never materializes or exports them either.
  */
 export function foreignLaneComponents(components: LaneData['components'], defaultScope: string): string[] {
   return components.filter((comp) => comp.id.scope !== defaultScope).map((comp) => comp.id.toStringWithoutVersion());
 }
 
+/**
+ * The slice of the lane this repository mirrors: the components that belong to `defaultScope`.
+ * Every reconciliation act — fingerprint, materialize, snap, export — operates on this slice, so a
+ * foreign component's head moving neither wakes the mirror nor reads as divergence.
+ */
+export function ownLaneComponents(components: LaneData['components'], defaultScope: string): LaneData['components'] {
+  return components.filter((comp) => comp.id.scope === defaultScope);
+}
+
 /** How many foreign component ids a cross-scope message names before it summarizes the rest. */
 const MAX_LISTED_FOREIGN_COMPONENTS = 5;
 
@@ -163,40 +173,45 @@ export function capEntries(entries: string[], overflowPrefix = '', max: number =
   return [...entries.slice(0, max), `${overflowPrefix}…and ${entries.length - max} more`];
 }
 
-/** The shared clause describing why a lane is cross-scope, used by the skip/refusal/halt outcomes. */
+/**
+ * The shared clause describing a lane with nothing of this repository's scope on it, used by the
+ * skip/refusal/halt outcomes. Only such a lane is refused: a lane that merely INCLUDES foreign
+ * components is reconciled over its own-scope slice.
+ */
 export function crossScopeDescription(foreignIds: string[], defaultScope: string): string {
   // The scope is everything before the FIRST '/': a component id is `<scope>/<namespace…>/<name>`.
   const scopes = [...new Set(foreignIds.map((id) => id.split('/', 1)[0]))].sort();
   const sample = capEntries(foreignIds, '', MAX_LISTED_FOREIGN_COMPONENTS).join(', ');
   return (
-    `components from scope(s) ${scopes.join(', ')} (this repo maps scope ${defaultScope}); ` +
+    `every component is from scope(s) ${scopes.join(', ')} (this repo maps scope ${defaultScope}); ` +
     `foreign components: ${sample}`
   );
 }
 
 /**
- * A cross-scope lane that was merely enumerated: a skip, and the run stays green — a standing, valid
- * lane must not turn every scheduled run permanently red.
+ * A lane with no own-scope components that was merely enumerated: a skip, and the run stays green — a
+ * standing, valid lane must not turn every scheduled run permanently red.
  */
 export function crossScopeSkipSummary(laneName: string, foreignIds: string[], defaultScope: string): string {
   return (
-    `${laneName} -> skipped (cross-scope lane: ${crossScopeDescription(foreignIds, defaultScope)} — ` +
+    `${laneName} -> skipped (nothing to mirror: ${crossScopeDescription(foreignIds, defaultScope)} — ` +
     `no branch created; see the docs' Cross-scope lanes section)`
   );
 }
 
 /**
- * A cross-scope lane the user named explicitly: exits non-zero with the explanation. A refusal, not a
- * halt — no PR is labelled, no branch is written. `existingBranch` keeps the closing sentence truthful
- * when a branch of that name already exists.
+ * A lane with no own-scope components that the user named explicitly: exits non-zero with the
+ * explanation. A refusal, not a halt — no PR is labelled, no branch is written. `existingBranch`
+ * keeps the closing sentence truthful when a branch of that name already exists.
  */
 export function crossScopeRefusal(foreignIds: string[], defaultScope: string, existingBranch?: string): string {
   const outcome = existingBranch
     ? `Nothing was written; the existing branch ${existingBranch} was left untouched`
     : 'No branch was created and nothing was written';
   return (
-    `cross-scope lane: ${crossScopeDescription(foreignIds, defaultScope)}; syncing cross-scope lanes is ` +
-    `not supported yet — see the docs' Cross-scope lanes section. ${outcome}`
+    `nothing to mirror: ${crossScopeDescription(foreignIds, defaultScope)} — this repository reconciles ` +
+    `only its own scope's slice of a lane, and this lane has none. See the docs' Cross-scope lanes ` +
+    `section. ${outcome}`
   );
 }
 
@@ -229,13 +244,15 @@ Do NOT run the usual "bit lane import" resolution steps on this branch — they
 }
 
 /**
- * A lane that became cross-scope after this repository had already mirrored it onto a branch — the one
- * cross-scope shape that is a genuine halt: the pair is mid-flight and can no longer converge.
+ * A lane whose own-scope slice emptied out after this repository had already mirrored it onto a
+ * branch — the one cross-scope shape that is a genuine halt: the pair is mid-flight, and an empty
+ * slice fingerprints as a constant, which would read as converged forever over a stale mirror.
  */
 export function crossScopeMidFlightHaltReason(branch: string, foreignIds: string[], defaultScope: string): string {
   return (
-    `lane became cross-scope after it was mirrored onto ${branch}: ${crossScopeDescription(foreignIds, defaultScope)}; ` +
-    `the branch and the lane can no longer be reconciled automatically — see the docs' Cross-scope lanes section`
+    `every ${defaultScope} component left the lane after it was mirrored onto ${branch}: ` +
+    `${crossScopeDescription(foreignIds, defaultScope)}; the branch and the lane can no longer be ` +
+    `reconciled automatically — see the docs' Cross-scope lanes section`
   );
 }
 
@@ -364,7 +381,11 @@ export class LaneSyncExecutor {
 
     const remoteLane = await this.getRemoteLane(target);
 
-    const laneHead = remoteLane ? laneHeadFingerprint(remoteLane.components) : undefined;
+    // The slice of the lane this repository reconciles. Everything below — fingerprint, materialize,
+    // snap, export — acts on it alone: foreign components stay on the lane untouched and reach this
+    // repository only as package dependencies, so a foreign head moving is invisible here.
+    const ownComponents = remoteLane ? ownLaneComponents(remoteLane.components, defaultScope) : [];
+    const laneHead = remoteLane ? laneHeadFingerprint(ownComponents) : undefined;
     const branchExists = await branchExistsOnRemote(branch);
     const branchState: BranchSyncState = branchExists
       ? await readBranchSyncState(branch, defaultBranch, defaultScope)
@@ -410,11 +431,13 @@ export class LaneSyncExecutor {
       });
     }
 
-    // A cross-scope lane cannot be reconciled here — the reconciler acts on a lane whole, so mirroring
-    // one would write another repository's components into this one. The check lives in the executor
-    // because every trigger funnels through here, and it needs the lane's content.
+    // A lane with NO own-scope components cannot be reconciled here — there is nothing to mirror, and
+    // an empty slice fingerprints as a constant, which would read as converged forever. A lane that
+    // merely INCLUDES foreign components proceeds: it is reconciled over its own-scope slice. The
+    // check lives in the executor because every trigger funnels through here, and it needs the lane's
+    // content.
     const foreign = remoteLane ? foreignLaneComponents(remoteLane.components, defaultScope) : [];
-    if (foreign.length) {
+    if (foreign.length && !ownComponents.length) {
       return this.crossScopeOutcome({
         laneName,
         laneIdStr,
@@ -429,16 +452,27 @@ export class LaneSyncExecutor {
         dryRun,
       });
     }
+    if (foreign.length) {
+      logger.console(
+        formatWarningSummary(
+          `${laneName}: cross-scope lane — mirroring its ${ownComponents.length} ${defaultScope} component(s); ` +
+            `${foreign.length} component(s) from other scope(s) stay on the lane as package dependencies ` +
+            `(${capEntries(foreign, '', MAX_LISTED_FOREIGN_COMPONENTS).join(', ')})`
+        )
+      );
+    }
     // Attribution to THIS lane is required: the claim was computed for whichever lane the branch's
     // `.bitmap` names, and a claim on someone else's behalf licenses nothing here.
     const laneIsGone = branchExists && !laneHead;
     const ownership: LaneOwnershipEvidence = laneIsGone && mirroredLane === laneIdStr ? claim : 'inherited-or-none';
 
     // What the branch reflects, read off its own `.bitmap` — only when that `.bitmap` names THIS lane;
-    // otherwise the planner's `!lastSyncedHead` rows handle "no state of ours".
+    // otherwise the planner's `!lastSyncedHead` rows handle "no state of ours". Read over the OWN
+    // slice's ids, the same set `laneHead` fingerprints — a foreign component is never in `.bitmap`
+    // and counting it would read the pair as permanently diverged.
     const lastSyncedHead =
       remoteLane && branchState.bitmap && mirroredLane === laneIdStr
-        ? branchStateFingerprint(branchState.bitmap, laneComponentIds(remoteLane.components))
+        ? branchStateFingerprint(branchState.bitmap, laneComponentIds(ownComponents))
         : undefined;
 
     // `isSyncAuthoredMessage`, NOT `hasSyncMarker`: this feeds a branch deletion, and a message that
@@ -541,10 +575,12 @@ export class LaneSyncExecutor {
   }
 
   /**
-   * What a cross-scope lane means for this repository: a mid-flight halt when the branch is this
-   * lane's live mirror (checked first — the problem is the state of the pair, not the phrasing of the
-   * request); a refusal when the user named the lane explicitly; otherwise an enumerated skip that
-   * stays green — one standing cross-scope lane must not fail every scheduled run forever.
+   * What a lane with NO own-scope components means for this repository (a lane that merely includes
+   * foreign components never reaches here — it is reconciled over its own-scope slice): a mid-flight
+   * halt when the branch is this lane's live mirror (checked first — the problem is the state of the
+   * pair, not the phrasing of the request); a refusal when the user named the lane explicitly;
+   * otherwise an enumerated skip that stays green — one standing foreign lane must not fail every
+   * scheduled run forever.
    */
   private async crossScopeOutcome({
     laneName,
@@ -707,11 +743,13 @@ export class LaneSyncExecutor {
       // moved in between must re-plan (merge-diverged owns that shape): comparing the branch's files
       // with the newer lane would misread the lane's own advance as branch work, and the export would
       // put the older content on top of a concurrent developer's push. The materialize above just
-      // fetched, so this read and the status below see the same lane.
+      // fetched, so this read and the status below see the same lane. Own-slice fingerprints on both
+      // sides: a foreign head moving concurrently is not this pair's divergence.
       if (preExportLane) {
         const laneNow = await this.getRemoteLane(target);
-        const movedTo = laneNow ? laneHeadFingerprint(laneNow.components) : undefined;
-        if (movedTo !== laneHeadFingerprint(preExportLane.components)) {
+        const { defaultScope } = this.deps;
+        const movedTo = laneNow ? laneHeadFingerprint(ownLaneComponents(laneNow.components, defaultScope)) : undefined;
+        if (movedTo !== laneHeadFingerprint(ownLaneComponents(preExportLane.components, defaultScope))) {
           return `${laneName} -> noop (lane ${laneIdStr} moved while this run was planning; the next run re-plans)`;
         }
       }
@@ -890,11 +928,13 @@ export class LaneSyncExecutor {
 
       // Same freshness rule as the export probe: the plan's inputs must still describe the world.
       // A lane that moved since planning re-plans — the next run merges the newer head — rather
-      // than proceeding on a divergence assessment the planner never made.
+      // than proceeding on a divergence assessment the planner never made. Own-slice on both sides,
+      // like every fingerprint here.
       if (preExportLane) {
         const laneNow = await this.getRemoteLane(target);
-        const movedTo = laneNow ? laneHeadFingerprint(laneNow.components) : undefined;
-        if (movedTo !== laneHeadFingerprint(preExportLane.components)) {
+        const { defaultScope } = this.deps;
+        const movedTo = laneNow ? laneHeadFingerprint(ownLaneComponents(laneNow.components, defaultScope)) : undefined;
+        if (movedTo !== laneHeadFingerprint(ownLaneComponents(preExportLane.components, defaultScope))) {
           return `${laneName} -> noop (lane ${laneIdStr} moved while this run was planning; the next run re-plans)`;
         }
       }
@@ -1049,7 +1089,8 @@ export class LaneSyncExecutor {
   > {
     const remoteLane = await this.getRemoteLane(target);
     if (!remoteLane) return { status: 'unreadable' };
-    const laneHead = laneHeadFingerprint(remoteLane.components);
+    // Own-slice, like the planner's `laneHead`: the ledger records what THIS repository mirrors.
+    const laneHead = laneHeadFingerprint(ownLaneComponents(remoteLane.components, this.deps.defaultScope));
     const pushResult = await this.commitAllAndPush(branch, buildSyncCommitMessage(laneIdStr, laneHead, opts));
     if (pushResult.raced) return { status: 'raced' };
     return { status: 'ok', laneHead, remoteLane, branchTipSha: pushResult.pushedSha };
@@ -1101,6 +1142,10 @@ export class LaneSyncExecutor {
         promptMergeOptions: false,
         skipNpmInstall: true,
         workspaceOnly: false,
+        // `workspaceOnly: false` also ADDS lane components the workspace lacks; on a cross-scope lane
+        // that must stop at the own-scope slice — a foreign component merged in here would ride the
+        // sync commit into this repository.
+        restrictToScopes: [this.deps.defaultScope],
       });
 
       let conflictedFileCount = 0;
@@ -1480,6 +1525,10 @@ export class LaneSyncExecutor {
       // 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,
+      // A cross-scope lane's foreign components must never be written into this repository — they are
+      // sourced elsewhere and reach this workspace only as package dependencies. The lane object
+      // itself is still fetched and saved whole, so a later export preserves the foreign entries.
+      restrictToScopes: [this.deps.defaultScope],
       // 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,
@@ -1574,7 +1623,8 @@ export class LaneSyncExecutor {
         branch,
         branchTipSha,
         laneHead,
-        changed: changedLaneComponents(preComponents, postComponents),
+        // Own-slice only: a foreign head that moved concurrently was not snapped by this export.
+        changed: ownLaneComponents(changedLaneComponents(preComponents, postComponents), this.deps.defaultScope),
       });
       await gitHost.upsertComment(pr.number, RUN_SUMMARY_MARKER, body);
     } catch (e: any) {
@@ -1689,7 +1739,14 @@ export class LaneSyncExecutor {
     // `replace('.', '/')` replaces only the first dot, which is correct: a scope id may contain at
     // most one dot (is-valid-scope-name.ts) — the same conversion `ScopeUrl.toPathname` does.
     const laneUrl = `https://${getCloudDomain()}/${target.hostScope.replace('.', '/')}/~lane/${target.name}`;
-    const body = laneSyncPrBody({ laneIdStr, laneUrl, branch, laneHead, components: remoteLane.components });
+    const body = laneSyncPrBody({
+      laneIdStr,
+      laneUrl,
+      branch,
+      laneHead,
+      components: remoteLane.components,
+      defaultScope: this.deps.defaultScope,
+    });
     try {
       const created = await gitHost.createPr({
         head: branch,
@@ -1738,8 +1795,11 @@ function isConflictFileStatus(status: string): boolean {
 }
 
 /**
- * The body of the pull request that mirrors a lane onto a branch. The component list is capped so the
- * body stays inside the git host's size limit however large the lane is; the total is not.
+ * The body of the pull request that mirrors a lane onto a branch. On a cross-scope lane only the
+ * own-scope slice is mirrored, and the foreign components get their own section — the branch's diff
+ * cannot show them, and a reviewer must know the lane carries more than this repository sees. Every
+ * component list is capped so the body stays inside the git host's size limit however large the lane
+ * is; the totals are not.
  */
 export function laneSyncPrBody({
   laneIdStr,
@@ -1747,28 +1807,45 @@ export function laneSyncPrBody({
   branch,
   laneHead,
   components,
+  defaultScope,
 }: {
   laneIdStr: string;
   laneUrl: string;
   branch: string;
   laneHead: string;
   components: LaneData['components'];
+  defaultScope: string;
 }): string {
+  const own = ownLaneComponents(components, defaultScope);
+  const foreignIds = foreignLaneComponents(components, defaultScope);
   const listed = capEntries(
-    components.map((comp) => `- \`${comp.id.toStringWithoutVersion()}\` @ \`${comp.head.slice(0, 9)}\``),
+    own.map((comp) => `- \`${comp.id.toStringWithoutVersion()}\` @ \`${comp.head.slice(0, 9)}\``),
     '- '
   ).join('\n');
-  return [
+  const lines = [
     `Mirrors the Bit lane [\`${laneIdStr}\`](${laneUrl}) onto \`${branch}\`.`,
     '',
     `- lane: ${laneUrl}`,
     `- lane head: \`${laneHead}\``,
     '',
-    `Components on the lane (${components.length}):`,
+    foreignIds.length
+      ? `Components mirrored from the lane (${own.length} of ${components.length}):`
+      : `Components on the lane (${components.length}):`,
     listed || '_none_',
-    '',
-    'This PR is maintained by `bit ci sync` — push to the branch to send changes back to the lane.',
-  ].join('\n');
+  ];
+  if (foreignIds.length) {
+    lines.push(
+      '',
+      `Also on this lane, from other scopes (${foreignIds.length}) — not mirrored into this repository; ` +
+        `this branch consumes them as package dependencies at their lane versions:`,
+      capEntries(
+        foreignIds.map((id) => `- \`${id}\``),
+        '- '
+      ).join('\n')
+    );
+  }
+  lines.push('', 'This PR is maintained by `bit ci sync` — push to the branch to send changes back to the lane.');
+  return lines.join('\n');
 }
 
 /**