@remixhq/core 0.1.10 → 0.1.12

package/dist/collab.js

@@ -1,10 +1,13 @@
 import {
   getCollabBindingPath,
   readCollabBinding,
+  readCollabBindingState,
   reserveAvailableDirPath,
   reserveDirectory,
-  writeCollabBinding
-} from "./chunk-GEHSFPCD.js";
+  writeCollabBinding,
+  writeCollabBindingSnapshot
+} from "./chunk-IXWQWFYT.js";
+import "./chunk-HZNEDSRS.js";
 import {
   assertRepoSnapshotUnchanged,
   buildRepoFingerprint,
@@ -38,7 +41,7 @@ import {
   summarizeUnifiedDiff,
   validateUnifiedDiff,
   writeTempUnifiedDiffBackup
-} from "./chunk-J3J4PBQ7.js";
+} from "./chunk-RREREIGW.js";
 import {
   REMIX_ERROR_CODES
 } from "./chunk-GC2MOT3U.js";
@@ -55,29 +58,29 @@ function describeBranch(value) {
   const normalized = String(value ?? "").trim();
   return normalized || "(detached)";
 }
-function isPreferredBranchMatch(currentBranch, preferredBranch) {
+function isBoundBranchMatch(currentBranch, branchName) {
   const current = String(currentBranch ?? "").trim();
-  const preferred = String(preferredBranch ?? "").trim();
-  if (!preferred || !current) return true;
-  return current === preferred;
+  const expected = String(branchName ?? "").trim();
+  if (!expected || !current) return true;
+  return current === expected;
 }
-function buildPreferredBranchMismatchHint(params) {
+function buildBranchMismatchHint(params) {
   const overrideFlag = params.overrideFlag?.trim() || "--allow-branch-mismatch";
   return [
     `Current branch: ${describeBranch(params.currentBranch)}`,
-    `Preferred branch: ${describeBranch(params.preferredBranch)}`,
-    `Switch to ${describeBranch(params.preferredBranch)} or rerun with ${overrideFlag} if this is intentional.`
+    `Bound branch: ${describeBranch(params.branchName)}`,
+    `Switch to ${describeBranch(params.branchName)} or rerun with ${overrideFlag} if this is intentional.`
   ].join("\n");
 }
-function assertPreferredBranchMatch(params) {
+function assertBoundBranchMatch(params) {
   if (params.allowBranchMismatch) return;
-  if (isPreferredBranchMatch(params.currentBranch, params.preferredBranch)) return;
-  throw new RemixError(`Current branch does not match this checkout's Remix preferred branch while running ${params.operation}.`, {
+  if (isBoundBranchMatch(params.currentBranch, params.branchName)) return;
+  throw new RemixError(`Current branch does not match this checkout's bound Remix branch while running ${params.operation}.`, {
     code: REMIX_ERROR_CODES.PREFERRED_BRANCH_MISMATCH,
     exitCode: 2,
-    hint: buildPreferredBranchMismatchHint({
+    hint: buildBranchMismatchHint({
       currentBranch: params.currentBranch,
-      preferredBranch: params.preferredBranch,
+      branchName: params.branchName,
       overrideFlag: params.overrideFlag
     })
   });
@@ -141,6 +144,52 @@ function sanitizeCheckoutDirName(value) {
 function buildDashboardAppUrl(appId) {
   return `https://dashboard.remix.one/apps/${encodeURIComponent(appId)}`;
 }
+async function resolveProjectLaneIfAuthoritative(api, params) {
+  const branchName = String(params.branchName ?? "").trim();
+  if (!branchName) return null;
+  if (!params.projectId && !params.repoFingerprint && !params.remoteUrl) return null;
+  const readLane = async () => {
+    const laneResp = await api.resolveProjectLaneBinding({
+      projectId: params.projectId ?? void 0,
+      repoFingerprint: params.repoFingerprint ?? void 0,
+      remoteUrl: params.remoteUrl ?? void 0,
+      defaultBranch: params.defaultBranch ?? void 0,
+      branchName
+    });
+    return unwrapResponseObject(laneResp, "project lane binding");
+  };
+  let lane = await readLane();
+  const shouldRepairResolvedLane = lane.status === "resolved" && Boolean(
+    params.expectedUpstreamAppId && (!lane.upstreamAppId || lane.upstreamAppId !== params.expectedUpstreamAppId)
+  );
+  if (shouldRepairResolvedLane && params.createIfMissing && params.seedAppId) {
+    const ensuredResp = await api.ensureProjectLaneBinding({
+      projectId: params.projectId ?? void 0,
+      repoFingerprint: params.repoFingerprint ?? void 0,
+      remoteUrl: params.remoteUrl ?? void 0,
+      defaultBranch: params.defaultBranch ?? void 0,
+      branchName,
+      seedAppId: params.seedAppId
+    });
+    lane = unwrapResponseObject(ensuredResp, "project lane binding");
+  }
+  if (lane.status !== "resolved" && params.createIfMissing && params.seedAppId) {
+    const ensuredResp = await api.ensureProjectLaneBinding({
+      projectId: params.projectId ?? void 0,
+      repoFingerprint: params.repoFingerprint ?? void 0,
+      remoteUrl: params.remoteUrl ?? void 0,
+      defaultBranch: params.defaultBranch ?? void 0,
+      branchName,
+      seedAppId: params.seedAppId
+    });
+    lane = unwrapResponseObject(ensuredResp, "project lane binding");
+  }
+  if (lane.status !== "resolved") return null;
+  if (params.projectId && lane.projectId && lane.projectId !== params.projectId) return null;
+  if (params.currentAppId && lane.currentAppId && lane.currentAppId !== params.currentAppId) return null;
+  if (params.expectedUpstreamAppId && lane.upstreamAppId && lane.upstreamAppId !== params.expectedUpstreamAppId) return null;
+  return lane;
+}
 async function pollAppReady(api, appId) {
   const started = Date.now();
   let delay = 2e3;
@@ -285,6 +334,239 @@ async function pollMergeRequestCompletion(api, mrId, params) {
   throw new RemixError("Timed out waiting for merge approval to complete.", { exitCode: 1 });
 }
 
+// src/application/collab/laneBindingResolver.ts
+function normalizeBranchName(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized || null;
+}
+function buildBindingFromLane(state, lane) {
+  if (!lane.currentAppId || !lane.upstreamAppId) return null;
+  const resolvedBranch = normalizeBranchName(lane.branchName) ?? state.currentBranch ?? null;
+  const resolvedDefaultBranch = normalizeBranchName(lane.defaultBranch) ?? normalizeBranchName(state.defaultBranch);
+  const explicitRootProjectId = state.explicitRootBinding?.projectId ?? null;
+  const bindingMode = explicitRootProjectId && lane.projectId === explicitRootProjectId && resolvedBranch && resolvedBranch === resolvedDefaultBranch ? "explicit_root" : "lane";
+  return {
+    schemaVersion: 3,
+    projectId: lane.projectId ?? state.projectId,
+    currentAppId: lane.currentAppId,
+    upstreamAppId: lane.upstreamAppId,
+    threadId: lane.threadId ?? null,
+    repoFingerprint: lane.repoFingerprint ?? state.repoFingerprint ?? null,
+    remoteUrl: lane.remoteUrl ?? state.remoteUrl ?? null,
+    defaultBranch: lane.defaultBranch ?? state.defaultBranch ?? null,
+    laneId: lane.laneId ?? null,
+    branchName: resolvedBranch,
+    bindingMode
+  };
+}
+function shouldPersistRemoteLaneMetadata(localBinding, lane) {
+  return Boolean(
+    !localBinding.laneId && lane.laneId || !localBinding.threadId && lane.threadId || !localBinding.repoFingerprint && lane.repoFingerprint || !localBinding.remoteUrl && lane.remoteUrl || !localBinding.defaultBranch && lane.defaultBranch || !localBinding.branchName && lane.branchName
+  );
+}
+function shouldRequireRemoteLaneForCurrentBranch(params) {
+  if (!params.currentBranch) return false;
+  const defaultBranch = normalizeBranchName(params.defaultBranch);
+  if (params.currentBranch === defaultBranch) return false;
+  return !params.binding.laneId || params.binding.currentAppId === params.binding.upstreamAppId;
+}
+async function persistResolvedLane(repoRoot, binding) {
+  await writeCollabBinding(repoRoot, {
+    projectId: binding.projectId,
+    currentAppId: binding.currentAppId,
+    upstreamAppId: binding.upstreamAppId,
+    threadId: binding.threadId,
+    repoFingerprint: binding.repoFingerprint,
+    remoteUrl: binding.remoteUrl,
+    defaultBranch: binding.defaultBranch,
+    laneId: binding.laneId,
+    branchName: binding.branchName,
+    bindingMode: binding.bindingMode
+  });
+  return readCollabBinding(repoRoot);
+}
+function buildAmbiguousResolution(params) {
+  return {
+    status: "ambiguous_family_selection",
+    currentBranch: params.currentBranch,
+    projectIds: Array.isArray(params.lane.projectIds) ? params.lane.projectIds.filter((value) => typeof value === "string" && value.trim().length > 0) : [],
+    repoFingerprint: params.lane.repoFingerprint ?? params.state.repoFingerprint,
+    remoteUrl: params.lane.remoteUrl ?? params.state.remoteUrl,
+    defaultBranch: params.lane.defaultBranch ?? params.state.defaultBranch
+  };
+}
+async function resolveActiveLaneBinding(params) {
+  const state = await readCollabBindingState(params.repoRoot);
+  if (!state) {
+    return { status: "not_bound", currentBranch: null };
+  }
+  const currentBranch = normalizeBranchName(state.currentBranch);
+  const localBinding = state.binding;
+  if (localBinding) {
+    const requireRemoteLane = shouldRequireRemoteLaneForCurrentBranch({
+      binding: localBinding,
+      currentBranch,
+      defaultBranch: state.defaultBranch
+    });
+    if (!params.api || !currentBranch) {
+      return {
+        status: "resolved",
+        source: "local",
+        binding: localBinding,
+        currentBranch
+      };
+    }
+    const laneResp2 = await params.api.resolveProjectLaneBinding({
+      projectId: state.explicitRootBinding?.projectId ?? (requireRemoteLane ? void 0 : localBinding.projectId ?? state.projectId ?? void 0),
+      repoFingerprint: state.repoFingerprint ?? void 0,
+      remoteUrl: state.remoteUrl ?? void 0,
+      defaultBranch: state.defaultBranch ?? void 0,
+      branchName: currentBranch
+    });
+    const lane2 = unwrapResponseObject(laneResp2, "project lane binding");
+    if (lane2.status === "ambiguous_family_selection") {
+      return buildAmbiguousResolution({ state, currentBranch, lane: lane2 });
+    }
+    if (lane2.status === "resolved") {
+      const resolvedBranch = normalizeBranchName(lane2.branchName);
+      const resolvedProjectId = lane2.projectId ?? state.projectId;
+      const branchConflict = Boolean(resolvedBranch && localBinding.branchName && resolvedBranch !== localBinding.branchName);
+      const appConflict = Boolean(lane2.currentAppId && lane2.currentAppId !== localBinding.currentAppId);
+      const upstreamConflict = Boolean(lane2.upstreamAppId && lane2.upstreamAppId !== localBinding.upstreamAppId);
+      const projectConflict = Boolean(resolvedProjectId && localBinding.projectId && resolvedProjectId !== localBinding.projectId);
+      if (branchConflict || appConflict || upstreamConflict || projectConflict) {
+        if (requireRemoteLane) {
+          const binding = buildBindingFromLane(state, lane2);
+          if (binding) {
+            return {
+              status: "resolved",
+              source: "remote",
+              binding,
+              currentBranch
+            };
+          }
+        }
+        return {
+          status: "binding_conflict",
+          binding: localBinding,
+          resolvedLane: lane2,
+          currentBranch
+        };
+      }
+      if (shouldPersistRemoteLaneMetadata(localBinding, lane2)) {
+        const binding = buildBindingFromLane(state, lane2);
+        if (binding) {
+          return {
+            status: "resolved",
+            source: "remote",
+            binding,
+            currentBranch
+          };
+        }
+      }
+    }
+    if (requireRemoteLane) {
+      return {
+        status: "missing_branch_binding",
+        currentBranch,
+        projectId: lane2.projectId ?? state.projectId,
+        repoFingerprint: lane2.repoFingerprint ?? state.repoFingerprint,
+        remoteUrl: lane2.remoteUrl ?? state.remoteUrl,
+        defaultBranch: lane2.defaultBranch ?? state.defaultBranch,
+        upstreamAppId: lane2.upstreamAppId ?? localBinding.upstreamAppId ?? null,
+        threadId: lane2.threadId ?? localBinding.threadId ?? null
+      };
+    }
+    return {
+      status: "resolved",
+      source: "local",
+      binding: localBinding,
+      currentBranch
+    };
+  }
+  if (!params.api || !currentBranch) {
+    return {
+      status: "missing_branch_binding",
+      currentBranch,
+      projectId: state.projectId,
+      repoFingerprint: state.repoFingerprint,
+      remoteUrl: state.remoteUrl,
+      defaultBranch: state.defaultBranch,
+      upstreamAppId: null,
+      threadId: null
+    };
+  }
+  const laneResp = await params.api.resolveProjectLaneBinding({
+    projectId: state.explicitRootBinding?.projectId ?? state.projectId ?? void 0,
+    repoFingerprint: state.repoFingerprint ?? void 0,
+    remoteUrl: state.remoteUrl ?? void 0,
+    defaultBranch: state.defaultBranch ?? void 0,
+    branchName: currentBranch
+  });
+  const lane = unwrapResponseObject(laneResp, "project lane binding");
+  if (lane.status === "ambiguous_family_selection") {
+    return buildAmbiguousResolution({ state, currentBranch, lane });
+  }
+  if (lane.status === "resolved") {
+    const binding = buildBindingFromLane(state, lane);
+    if (binding) {
+      return {
+        status: "resolved",
+        source: "remote",
+        binding,
+        currentBranch
+      };
+    }
+  }
+  return {
+    status: "missing_branch_binding",
+    currentBranch,
+    projectId: lane.projectId ?? state.explicitRootBinding?.projectId ?? state.projectId,
+    repoFingerprint: lane.repoFingerprint ?? state.repoFingerprint,
+    remoteUrl: lane.remoteUrl ?? state.remoteUrl,
+    defaultBranch: lane.defaultBranch ?? state.defaultBranch,
+    upstreamAppId: lane.upstreamAppId ?? state.explicitRootBinding?.upstreamAppId ?? null,
+    threadId: lane.threadId ?? state.explicitRootBinding?.threadId ?? null
+  };
+}
+async function ensureActiveLaneBinding(params) {
+  const resolved = await resolveActiveLaneBinding({
+    repoRoot: params.repoRoot,
+    api: params.api
+  });
+  if (resolved.status === "resolved") {
+    if (resolved.source === "local") {
+      return resolved.binding;
+    }
+    return persistResolvedLane(params.repoRoot, resolved.binding);
+  }
+  if (resolved.status === "binding_conflict") {
+    throw new RemixError("Current branch binding conflicts with the server-resolved Remix lane.", {
+      exitCode: 2,
+      hint: `Local app ${resolved.binding.currentAppId}; server app ${resolved.resolvedLane.currentAppId ?? "(unknown)"}. Repair the branch binding before running ${params.operation ?? "this command"}.`
+    });
+  }
+  if (resolved.status === "ambiguous_family_selection") {
+    throw new RemixError("Multiple canonical Remix families match this repository.", {
+      exitCode: 2,
+      hint: "This checkout is not specific enough to choose a single family for the current branch. Continue from a checkout already bound to the intended family, or run `remix collab init --force-new` to create a new canonical family."
+    });
+  }
+  if (resolved.status === "not_bound") {
+    return null;
+  }
+  if (!resolved.currentBranch) {
+    throw new RemixError("Current branch is not yet bound to a Remix lane.", {
+      exitCode: 2,
+      hint: `Switch to a named branch before running ${params.operation ?? "this command"}.`
+    });
+  }
+  throw new RemixError("Current branch is not yet bound to a Remix lane.", {
+    exitCode: 2,
+    hint: `Run \`remix collab init\` on branch ${resolved.currentBranch} before running ${params.operation ?? "this command"}.`
+  });
+}
+
 // src/application/collab/recordingPreflight.ts
 async function collabRecordingPreflight(params) {
   let repoRoot;
@@ -297,7 +579,7 @@ async function collabRecordingPreflight(params) {
       repoRoot: null,
       appId: null,
       currentBranch: null,
-      preferredBranch: null,
+      branchName: null,
       headCommitHash: null,
       worktreeClean: false,
       syncStatus: null,
@@ -309,14 +591,14 @@ async function collabRecordingPreflight(params) {
       hint: message
     };
   }
-  const binding = await readCollabBinding(repoRoot);
-  if (!binding) {
+  const bindingResolution = await resolveActiveLaneBinding({ repoRoot, api: params.api });
+  if (bindingResolution.status === "not_bound") {
     return {
       status: "not_bound",
       repoRoot,
       appId: null,
       currentBranch: null,
-      preferredBranch: null,
+      branchName: null,
       headCommitHash: null,
       worktreeClean: false,
       syncStatus: null,
@@ -328,19 +610,74 @@ async function collabRecordingPreflight(params) {
       hint: "Run `remix collab init` first."
     };
   }
+  if (bindingResolution.status === "missing_branch_binding") {
+    return {
+      status: "branch_binding_missing",
+      repoRoot,
+      appId: null,
+      currentBranch: bindingResolution.currentBranch,
+      branchName: bindingResolution.currentBranch,
+      headCommitHash: null,
+      worktreeClean: false,
+      syncStatus: null,
+      syncTargetCommitHash: null,
+      syncTargetCommitId: null,
+      reconcileTargetHeadCommitHash: null,
+      reconcileTargetHeadCommitId: null,
+      warnings: [],
+      hint: `Current branch ${bindingResolution.currentBranch ?? "(detached)"} is not yet bound to a Remix lane.`
+    };
+  }
+  if (bindingResolution.status === "ambiguous_family_selection") {
+    return {
+      status: "family_ambiguous",
+      repoRoot,
+      appId: null,
+      currentBranch: bindingResolution.currentBranch,
+      branchName: bindingResolution.currentBranch,
+      headCommitHash: null,
+      worktreeClean: false,
+      syncStatus: null,
+      syncTargetCommitHash: null,
+      syncTargetCommitId: null,
+      reconcileTargetHeadCommitHash: null,
+      reconcileTargetHeadCommitId: null,
+      warnings: [],
+      hint: "Multiple canonical Remix families match this repository. Continue from a checkout already bound to the intended family, or run `remix collab init --force-new` to create a new canonical family."
+    };
+  }
+  if (bindingResolution.status === "binding_conflict") {
+    return {
+      status: "metadata_conflict",
+      repoRoot,
+      appId: bindingResolution.binding.currentAppId,
+      currentBranch: bindingResolution.currentBranch,
+      branchName: bindingResolution.binding.branchName,
+      headCommitHash: null,
+      worktreeClean: false,
+      syncStatus: null,
+      syncTargetCommitHash: null,
+      syncTargetCommitId: null,
+      reconcileTargetHeadCommitHash: null,
+      reconcileTargetHeadCommitId: null,
+      warnings: [],
+      hint: `Local binding for ${bindingResolution.currentBranch ?? "(detached)"} points to app ${bindingResolution.binding.currentAppId}, but the server resolved lane ${bindingResolution.resolvedLane.laneId ?? "(unknown)"} / app ${bindingResolution.resolvedLane.currentAppId ?? "(unknown)"}. Repair the branch binding before recording work.`
+    };
+  }
+  const binding = bindingResolution.binding;
   const [currentBranch, headCommitHash, worktreeStatus] = await Promise.all([
     getCurrentBranch(repoRoot),
     getHeadCommitHash(repoRoot),
     getWorktreeStatus(repoRoot)
   ]);
-  const preferredBranch = binding.preferredBranch ?? null;
+  const branchName = binding.branchName ?? null;
   if (!headCommitHash) {
     return {
       status: "missing_head",
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash: null,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: null,
@@ -352,13 +689,13 @@ async function collabRecordingPreflight(params) {
       hint: "Failed to resolve local HEAD commit."
     };
   }
-  if (!params.allowBranchMismatch && !isPreferredBranchMatch(currentBranch, preferredBranch)) {
+  if (!params.allowBranchMismatch && !isBoundBranchMatch(currentBranch, branchName)) {
     return {
       status: "branch_mismatch",
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: null,
@@ -367,9 +704,9 @@ async function collabRecordingPreflight(params) {
       reconcileTargetHeadCommitHash: null,
       reconcileTargetHeadCommitId: null,
       warnings: [],
-      hint: buildPreferredBranchMismatchHint({
+      hint: buildBranchMismatchHint({
         currentBranch,
-        preferredBranch
+        branchName
       })
     };
   }
@@ -387,7 +724,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -405,7 +742,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -430,7 +767,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -448,7 +785,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -465,7 +802,7 @@ async function collabRecordingPreflight(params) {
     repoRoot,
     appId: binding.currentAppId,
     currentBranch,
-    preferredBranch,
+    branchName,
     headCommitHash,
     worktreeClean: worktreeStatus.isClean,
     syncStatus: sync.status,
@@ -697,7 +1034,11 @@ import os2 from "os";
 import path2 from "path";
 async function collabSync(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab sync`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
@@ -706,9 +1047,9 @@ async function collabSync(params) {
   }
   await ensureCleanWorktree(repoRoot);
   const branch = await requireCurrentBranch(repoRoot);
-  assertPreferredBranchMatch({
+  assertBoundBranchMatch({
     currentBranch: branch,
-    preferredBranch: binding.preferredBranch,
+    branchName: binding.branchName,
     allowBranchMismatch: params.allowBranchMismatch,
     operation: "`remix collab sync`"
   });
@@ -785,9 +1126,9 @@ async function collabSync(params) {
       });
       await ensureCleanWorktree(lockedRepoRoot);
       const lockedBranch = await requireCurrentBranch(lockedRepoRoot);
-      assertPreferredBranchMatch({
+      assertBoundBranchMatch({
         currentBranch: lockedBranch,
-        preferredBranch: binding.preferredBranch,
+        branchName: binding.branchName,
         allowBranchMismatch: params.allowBranchMismatch,
         operation: "`remix collab sync`"
       });
@@ -820,6 +1161,18 @@ function assertSupportedRecordingPreflight(preflight) {
       hint: preflight.hint
     });
   }
+  if (preflight.status === "branch_binding_missing") {
+    throw new RemixError("Current branch is not yet bound to a Remix lane.", {
+      exitCode: 2,
+      hint: preflight.hint
+    });
+  }
+  if (preflight.status === "family_ambiguous") {
+    throw new RemixError("Multiple canonical Remix families match this repository.", {
+      exitCode: 2,
+      hint: preflight.hint
+    });
+  }
   if (preflight.status === "not_git_repo") {
     throw new RemixError(preflight.hint || "Not inside a git repository.", {
       exitCode: 2,
@@ -833,9 +1186,9 @@ function assertSupportedRecordingPreflight(preflight) {
     });
   }
   if (preflight.status === "branch_mismatch") {
-    assertPreferredBranchMatch({
+    assertBoundBranchMatch({
       currentBranch: preflight.currentBranch,
-      preferredBranch: preflight.preferredBranch,
+      branchName: preflight.branchName,
       allowBranchMismatch: false,
       operation: "`remix collab add`"
     });
@@ -855,7 +1208,11 @@ function assertSupportedRecordingPreflight(preflight) {
 }
 async function collabAdd(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab add`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
@@ -876,9 +1233,9 @@ async function collabAdd(params) {
     });
     assertSupportedRecordingPreflight(preflight);
     const branch = preflight.currentBranch;
-    assertPreferredBranchMatch({
+    assertBoundBranchMatch({
       currentBranch: branch,
-      preferredBranch: binding.preferredBranch,
+      branchName: binding.branchName,
       allowBranchMismatch: params.allowBranchMismatch,
       operation: "`remix collab add`"
     });
@@ -1051,6 +1408,7 @@ async function collabAdd(params) {
     });
     const resp = await params.api.createChangeStep(binding.currentAppId, {
       threadId: binding.threadId ?? void 0,
+      collabLaneId: binding.laneId ?? void 0,
       prompt,
       assistantResponse: assistantResponse ?? void 0,
       diff,
@@ -1126,6 +1484,18 @@ function assertSupportedRecordingPreflight2(preflight) {
       hint: preflight.hint
     });
   }
+  if (preflight.status === "branch_binding_missing") {
+    throw new RemixError("Current branch is not yet bound to a Remix lane.", {
+      exitCode: 2,
+      hint: preflight.hint
+    });
+  }
+  if (preflight.status === "family_ambiguous") {
+    throw new RemixError("Multiple canonical Remix families match this repository.", {
+      exitCode: 2,
+      hint: preflight.hint
+    });
+  }
   if (preflight.status === "not_git_repo") {
     throw new RemixError(preflight.hint || "Not inside a git repository.", {
       exitCode: 2,
@@ -1139,9 +1509,9 @@ function assertSupportedRecordingPreflight2(preflight) {
     });
   }
   if (preflight.status === "branch_mismatch") {
-    assertPreferredBranchMatch({
+    assertBoundBranchMatch({
       currentBranch: preflight.currentBranch,
-      preferredBranch: preflight.preferredBranch,
+      branchName: preflight.branchName,
       allowBranchMismatch: false,
       operation: "`remix collab record-turn`"
     });
@@ -1161,7 +1531,11 @@ function assertSupportedRecordingPreflight2(preflight) {
 }
 async function collabRecordTurn(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab record-turn`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
@@ -1193,9 +1567,9 @@ async function collabRecordTurn(params) {
     });
   }
   const branch = await getCurrentBranch(repoRoot);
-  assertPreferredBranchMatch({
+  assertBoundBranchMatch({
     currentBranch: branch,
-    preferredBranch: binding.preferredBranch,
+    branchName: binding.branchName,
     allowBranchMismatch: params.allowBranchMismatch,
     operation: "`remix collab record-turn`"
   });
@@ -1209,6 +1583,7 @@ async function collabRecordTurn(params) {
   });
   const resp = await params.api.createCollabTurn(binding.currentAppId, {
     threadId: binding.threadId ?? void 0,
+    collabLaneId: binding.laneId ?? void 0,
     prompt,
     assistantResponse,
     actor: params.actor,
@@ -1221,7 +1596,8 @@ async function collabRecordTurn(params) {
     },
     idempotencyKey
   });
-  return unwrapResponseObject(resp, "collab turn");
+  const turn = unwrapResponseObject(resp, "collab turn");
+  return turn;
 }
 
 // src/application/collab/collabFinalizeTurn.ts
@@ -1231,7 +1607,11 @@ function collectWarnings(value) {
 }
 async function collabFinalizeTurn(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab finalize-turn`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
@@ -1339,7 +1719,11 @@ async function collabApprove(params) {
         operation: "collabApproveSyncTarget"
       },
       async ({ repoRoot, warnings }) => {
-        const binding = await readCollabBinding(repoRoot);
+        const binding = await ensureActiveLaneBinding({
+          repoRoot,
+          api: params.api,
+          operation: "`remix collab approve --sync-target-repo`"
+        });
         if (!binding) {
           throw new RemixError("Repository is not bound to Remix.", {
             exitCode: 2,
@@ -1348,9 +1732,9 @@ async function collabApprove(params) {
         }
         await ensureCleanWorktree(repoRoot, "`remix collab approve --sync-target-repo`");
         const branch = await requireCurrentBranch(repoRoot);
-        assertPreferredBranchMatch({
+        assertBoundBranchMatch({
           currentBranch: branch,
-          preferredBranch: binding.preferredBranch,
+          branchName: binding.branchName,
           allowBranchMismatch: params.allowBranchMismatch,
           operation: "`remix collab approve --sync-target-repo`"
         });
@@ -1433,10 +1817,6 @@ function isSubpath(parentPath, candidatePath) {
   const relative = path4.relative(parentPath, candidatePath);
   return relative === "" || !relative.startsWith("..") && !path4.isAbsolute(relative);
 }
-function buildPreferredCheckoutBranch(appId) {
-  const normalized = appId.trim().replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-  return `remix/remix/${normalized || "app"}`;
-}
 async function resolveCheckoutDestination(params) {
   if (params.outputDir?.trim()) {
     const preferredRepoRoot = path4.resolve(params.outputDir.trim());
@@ -1501,7 +1881,9 @@ async function materializeAppCheckout(params) {
     const bundle = await params.api.downloadAppBundle(params.appId);
     await fs4.writeFile(bundlePath, bundle.data);
     await cloneGitBundleToDirectory(bundlePath, repoRoot);
-    await checkoutLocalBranch(repoRoot, buildPreferredCheckoutBranch(params.appId));
+    if (params.expectedBranchName?.trim()) {
+      await checkoutLocalBranch(repoRoot, params.expectedBranchName.trim());
+    }
     await ensureGitInfoExcludeEntries(repoRoot, [".remix/"]);
   } catch (err) {
     await fs4.rm(repoRoot, { recursive: true, force: true }).catch(() => {
@@ -1510,15 +1892,15 @@ async function materializeAppCheckout(params) {
   } finally {
     await fs4.rm(bundleTempDir, { recursive: true, force: true });
   }
-  const remoteUrl = normalizeGitRemote(await getRemoteOriginUrl(repoRoot));
-  const defaultBranch = await getDefaultBranch(repoRoot) ?? await getCurrentBranch(repoRoot) ?? null;
-  const preferredBranch = await getCurrentBranch(repoRoot) ?? buildPreferredCheckoutBranch(params.appId);
+  const branchName = await getCurrentBranch(repoRoot) ?? params.expectedBranchName?.trim() ?? null;
+  const remoteUrl = normalizeGitRemote(params.expectedRemoteUrl ?? await getRemoteOriginUrl(repoRoot));
+  const defaultBranch = params.expectedDefaultBranch?.trim() ?? await getDefaultBranch(repoRoot) ?? branchName ?? null;
   const repoFingerprint = remoteUrl ? await buildRepoFingerprint({ gitRoot: repoRoot, remoteUrl, defaultBranch }) : null;
   return {
     repoRoot,
     remoteUrl,
     defaultBranch,
-    preferredBranch,
+    branchName,
     repoFingerprint
   };
 }
@@ -1533,29 +1915,55 @@ async function collabCheckout(params) {
     });
   }
   const app = await pollAppReady(params.api, appId);
+  const collab = app.collab && typeof app.collab === "object" ? app.collab : null;
+  const source = app.source && typeof app.source === "object" ? app.source : null;
+  const authoritativeBranchName = typeof collab?.branchName === "string" && collab.branchName.trim() || typeof source?.branch === "string" && source.branch.trim() || typeof source?.defaultBranch === "string" && source.defaultBranch.trim() || null;
+  const authoritativeRemoteUrl = typeof source?.remoteUrl === "string" && source.remoteUrl.trim() || null;
+  const authoritativeDefaultBranch = typeof source?.defaultBranch === "string" && source.defaultBranch.trim() || null;
   const checkout = await materializeAppCheckout({
     api: params.api,
     cwd: params.cwd,
     appId: String(app.id),
     outputDir: params.outputDir ?? null,
-    defaultDirName: sanitizeCheckoutDirName(String(app.name || app.id))
+    defaultDirName: sanitizeCheckoutDirName(String(app.name || app.id)),
+    expectedBranchName: authoritativeBranchName,
+    expectedRemoteUrl: authoritativeRemoteUrl,
+    expectedDefaultBranch: authoritativeDefaultBranch
   });
   const upstreamAppId = String(app.forkedFromAppId ?? app.id);
-  const bindingPath = await writeCollabBinding(checkout.repoRoot, {
+  const laneId = typeof collab?.laneId === "string" ? collab.laneId : null;
+  const repoFingerprint = typeof source?.repoFingerprint === "string" ? source.repoFingerprint : checkout.repoFingerprint;
+  const remoteUrl = typeof source?.remoteUrl === "string" ? source.remoteUrl : checkout.remoteUrl;
+  const defaultBranch = typeof source?.defaultBranch === "string" ? source.defaultBranch : checkout.defaultBranch;
+  const branchName = authoritativeBranchName ?? checkout.branchName;
+  const authoritativeLane = await resolveProjectLaneIfAuthoritative(params.api, {
     projectId: String(app.projectId),
+    repoFingerprint,
+    remoteUrl,
+    defaultBranch,
+    branchName,
     currentAppId: String(app.id),
-    upstreamAppId,
-    threadId: app.threadId ? String(app.threadId) : null,
-    repoFingerprint: checkout.repoFingerprint,
-    remoteUrl: checkout.remoteUrl,
-    defaultBranch: checkout.defaultBranch,
-    preferredBranch: checkout.preferredBranch
+    expectedUpstreamAppId: upstreamAppId,
+    createIfMissing: true,
+    seedAppId: String(app.id)
+  });
+  const bindingPath = await writeCollabBinding(checkout.repoRoot, {
+    projectId: authoritativeLane?.projectId ?? String(app.projectId),
+    currentAppId: authoritativeLane?.currentAppId ?? String(app.id),
+    upstreamAppId: authoritativeLane?.upstreamAppId ?? upstreamAppId,
+    threadId: authoritativeLane?.threadId ?? (app.threadId ? String(app.threadId) : null),
+    repoFingerprint: authoritativeLane?.repoFingerprint ?? repoFingerprint,
+    remoteUrl: authoritativeLane?.remoteUrl ?? remoteUrl,
+    defaultBranch: authoritativeLane?.defaultBranch ?? defaultBranch,
+    laneId: authoritativeLane?.laneId ?? laneId,
+    branchName: authoritativeLane?.branchName ?? branchName,
+    bindingMode: "lane"
   });
   return {
-    appId: String(app.id),
-    dashboardUrl: buildDashboardAppUrl(String(app.id)),
-    projectId: String(app.projectId),
-    upstreamAppId,
+    appId: authoritativeLane?.currentAppId ?? String(app.id),
+    dashboardUrl: buildDashboardAppUrl(authoritativeLane?.currentAppId ?? String(app.id)),
+    projectId: authoritativeLane?.projectId ?? String(app.projectId),
+    upstreamAppId: authoritativeLane?.upstreamAppId ?? upstreamAppId,
     bindingPath,
     repoRoot: checkout.repoRoot
   };
@@ -1577,14 +1985,32 @@ async function resolveQueueAppId(params) {
     });
   }
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
-  if (!binding) {
+  const bindingResolution = await resolveActiveLaneBinding({ repoRoot });
+  if (bindingResolution.status === "not_bound") {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
       hint: "Bind the repository first or pass `appId` explicitly for the app-scoped merge-request queue."
     });
   }
-  return binding.currentAppId;
+  if (bindingResolution.status === "missing_branch_binding") {
+    throw new RemixError("Current branch is not yet bound to a Remix lane.", {
+      exitCode: 2,
+      hint: `Switch back to a bound branch or create a lane by recording work on ${bindingResolution.currentBranch ?? "this branch"}.`
+    });
+  }
+  if (bindingResolution.status === "binding_conflict") {
+    throw new RemixError("Current branch binding conflicts with the server-resolved Remix lane.", {
+      exitCode: 2,
+      hint: `Local app ${bindingResolution.binding.currentAppId}; server app ${bindingResolution.resolvedLane.currentAppId ?? "(unknown)"}.`
+    });
+  }
+  if (bindingResolution.status === "ambiguous_family_selection") {
+    throw new RemixError("Multiple canonical Remix families match this repository.", {
+      exitCode: 2,
+      hint: "This checkout does not identify a single canonical family. Continue from a checkout already bound to the intended family, or pass `appId` explicitly for the queue request."
+    });
+  }
+  return bindingResolution.binding.currentAppId;
 }
 async function collabListMergeRequests(params) {
   const appId = await resolveQueueAppId({
@@ -1615,12 +2041,38 @@ async function collabListMergeRequests(params) {
 async function resolveScopeTarget(params) {
   if (params.targetId?.trim()) return params.targetId.trim();
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
-  if (!binding) {
+  const bindingResolution = await resolveActiveLaneBinding({ repoRoot, api: params.api });
+  if (bindingResolution.status === "not_bound") {
     throw new RemixError("Repository is not bound to Remix and no explicit target id was provided.", { exitCode: 2 });
   }
-  if (params.scope === "project") return binding.projectId;
+  if (bindingResolution.status === "missing_branch_binding") {
+    throw new RemixError("Current branch is not yet bound to a Remix lane and no explicit target id was provided.", {
+      exitCode: 2
+    });
+  }
+  if (bindingResolution.status === "binding_conflict") {
+    throw new RemixError("Current branch binding conflicts with the server-resolved Remix lane.", {
+      exitCode: 2,
+      hint: `Local app ${bindingResolution.binding.currentAppId}; server app ${bindingResolution.resolvedLane.currentAppId ?? "(unknown)"}.`
+    });
+  }
+  if (bindingResolution.status === "ambiguous_family_selection") {
+    throw new RemixError("Multiple canonical Remix families match this repository and no explicit target id was provided.", {
+      exitCode: 2,
+      hint: "This checkout does not identify a single canonical family. Continue from a checkout already bound to the intended family, or pass `targetId` explicitly."
+    });
+  }
+  const binding = bindingResolution.binding;
+  if (params.scope === "project") {
+    if (!binding.projectId) {
+      throw new RemixError("Could not resolve the project for the current repository binding.", { exitCode: 2 });
+    }
+    return binding.projectId;
+  }
   if (params.scope === "app") return binding.currentAppId;
+  if (!binding.projectId) {
+    throw new RemixError("Could not resolve the project for the current repository binding.", { exitCode: 2 });
+  }
   const project = unwrapResponseObject(await params.api.getProject(binding.projectId), "project");
   const organizationId = typeof project.organizationId === "string" ? project.organizationId : null;
   if (!organizationId) {
@@ -1740,6 +2192,85 @@ ${text}`.trim() || null
 }
 
 // src/application/collab/collabInit.ts
+function requireResolvedLaneBinding(lane, params) {
+  if (lane.status === "resolved" && lane.currentAppId && lane.upstreamAppId) {
+    return lane;
+  }
+  const branchLabel = params.branchName ?? "the current branch";
+  const laneStatus = String(lane.status ?? "");
+  throw new RemixError(`Failed to resolve a Remix lane for ${branchLabel}.`, {
+    exitCode: 1,
+    hint: laneStatus === "binding_not_found" ? `Run ${params.operation} again after the repository has been initialized.` : laneStatus === "ambiguous_family_selection" ? "Multiple canonical Remix families match this repository. Continue from a checkout already bound to the intended family, or rerun with `--force-new` to create a new family." : `Remix did not return complete lane metadata for ${branchLabel}.`
+  });
+}
+function resolveProjectBindingResult(response) {
+  const payload = response?.responseObject;
+  if (!payload || typeof payload !== "object") {
+    return { status: "not_found" };
+  }
+  if (payload.status === "ambiguous_family_selection") {
+    const projectIds = Array.isArray(payload.projectIds) ? payload.projectIds.filter((value) => typeof value === "string" && value.trim().length > 0) : [];
+    return {
+      status: "ambiguous_family_selection",
+      candidateCount: typeof payload.candidateCount === "number" && Number.isFinite(payload.candidateCount) ? payload.candidateCount : projectIds.length,
+      projectIds
+    };
+  }
+  if (payload.projectId && payload.appId) {
+    return {
+      status: "resolved",
+      projectId: String(payload.projectId),
+      appId: String(payload.appId),
+      upstreamAppId: String(payload.upstreamAppId ?? payload.appId),
+      threadId: payload.threadId ? String(payload.threadId) : null
+    };
+  }
+  return { status: "not_found" };
+}
+function throwAmbiguousFamilyError(params) {
+  const familyCount = params.candidateCount || params.projectIds.length;
+  const projectHint = params.projectIds.length > 0 ? ` Matching project ids: ${params.projectIds.join(", ")}.` : "";
+  throw new RemixError("Multiple canonical Remix families already match this repository.", {
+    exitCode: 2,
+    hint: `Plain \`remix collab init\` cannot safely choose among ${familyCount} matching canonical families for repo fingerprint ${params.repoFingerprint}${params.remoteUrl ? ` (${params.remoteUrl})` : ""}.${projectHint} Run \`remix collab init --force-new\` to create a new canonical family, or continue from a checkout already bound to the intended family.`
+  });
+}
+async function resolveOrEnsureLaneBinding(params) {
+  const resolvePayload = {
+    projectId: params.projectId ?? void 0,
+    repoFingerprint: params.repoFingerprint,
+    remoteUrl: params.remoteUrl ?? void 0,
+    defaultBranch: params.defaultBranch ?? void 0,
+    branchName: params.branchName
+  };
+  let lane = unwrapResponseObject(
+    await params.api.resolveProjectLaneBinding(resolvePayload),
+    "project lane binding"
+  );
+  if (lane.status !== "resolved") {
+    lane = unwrapResponseObject(
+      await params.api.ensureProjectLaneBinding({
+        ...resolvePayload,
+        seedAppId: params.seedAppId ?? void 0
+      }),
+      "project lane binding"
+    );
+  }
+  return requireResolvedLaneBinding(lane, {
+    branchName: params.branchName,
+    operation: params.operation
+  });
+}
+function branchBindingFromLane(lane, mode, fallback) {
+  return {
+    projectId: lane.projectId ?? fallback.projectId,
+    currentAppId: lane.currentAppId ?? fallback.currentAppId,
+    upstreamAppId: lane.upstreamAppId ?? fallback.upstreamAppId,
+    threadId: lane.threadId ?? fallback.threadId,
+    laneId: lane.laneId ?? null,
+    bindingMode: mode
+  };
+}
 async function collabInit(params) {
   return withRepoMutationLock(
     {
@@ -1758,38 +2289,220 @@ async function collabInit(params) {
       const remoteUrl = normalizeGitRemote(await getRemoteOriginUrl(repoRoot));
       const currentBranch = await getCurrentBranch(repoRoot);
       const defaultBranch = await getDefaultBranch(repoRoot) ?? currentBranch;
-      const preferredBranch = currentBranch ?? defaultBranch ?? null;
+      const branchName = currentBranch ?? defaultBranch ?? null;
       const repoFingerprint = await buildRepoFingerprint({ gitRoot: repoRoot, remoteUrl, defaultBranch });
       const repoSnapshot = await captureRepoSnapshot(repoRoot);
-      if (!params.forceNew) {
-        const bindingResp = await params.api.resolveProjectBinding({
-          repoFingerprint,
-          remoteUrl: remoteUrl ?? void 0
+      const localBindingState = await readCollabBindingState(repoRoot, { persist: true });
+      if (!params.forceNew && localBindingState?.explicitRootBinding && branchName) {
+        const explicitRoot = localBindingState.explicitRootBinding;
+        const explicitProjectId = explicitRoot.projectId ?? localBindingState.projectId;
+        let canonicalLane2 = null;
+        let boundProjectId2 = explicitProjectId;
+        let boundCurrentAppId2 = explicitRoot.currentAppId;
+        let boundUpstreamAppId2 = explicitRoot.upstreamAppId;
+        let boundThreadId2 = explicitRoot.threadId;
+        let boundLaneId2 = explicitRoot.laneId;
+        if (defaultBranch && branchName !== defaultBranch) {
+          canonicalLane2 = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: explicitProjectId ?? void 0,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName: defaultBranch,
+            operation: "`remix collab init`"
+          });
+          const lane = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: canonicalLane2.projectId ?? explicitProjectId ?? void 0,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName,
+            operation: "`remix collab init`"
+          });
+          boundProjectId2 = lane.projectId ?? boundProjectId2;
+          boundCurrentAppId2 = lane.currentAppId ?? boundCurrentAppId2;
+          boundUpstreamAppId2 = lane.upstreamAppId ?? boundUpstreamAppId2;
+          boundThreadId2 = lane.threadId ?? boundThreadId2;
+          boundLaneId2 = lane.laneId ?? null;
+        } else {
+          canonicalLane2 = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: explicitProjectId ?? void 0,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName,
+            operation: "`remix collab init`"
+          });
+          boundProjectId2 = canonicalLane2.projectId ?? boundProjectId2;
+          boundCurrentAppId2 = canonicalLane2.currentAppId ?? boundCurrentAppId2;
+          boundUpstreamAppId2 = canonicalLane2.upstreamAppId ?? boundUpstreamAppId2;
+          boundThreadId2 = canonicalLane2.threadId ?? boundThreadId2;
+          boundLaneId2 = canonicalLane2.laneId ?? null;
+        }
+        const readyApp = await pollAppReady(params.api, boundCurrentAppId2);
+        boundProjectId2 = String(readyApp.projectId ?? boundProjectId2);
+        boundThreadId2 = readyApp.threadId ? String(readyApp.threadId) : boundThreadId2;
+        await assertRepoSnapshotUnchanged(repoRoot, repoSnapshot, {
+          operation: "`remix collab init`",
+          recoveryHint: "The repository changed while the local binding was being initialized. Review the local changes and rerun `remix collab init`."
+        });
+        await writeCollabBinding(repoRoot, {
+          projectId: canonicalLane2?.projectId ?? explicitProjectId ?? null,
+          currentAppId: canonicalLane2?.currentAppId ?? explicitRoot.currentAppId,
+          upstreamAppId: canonicalLane2?.upstreamAppId ?? canonicalLane2?.currentAppId ?? explicitRoot.upstreamAppId ?? explicitRoot.currentAppId,
+          threadId: canonicalLane2?.threadId ?? explicitRoot.threadId,
+          repoFingerprint: canonicalLane2?.repoFingerprint ?? explicitRoot.repoFingerprint ?? repoFingerprint,
+          remoteUrl: canonicalLane2?.remoteUrl ?? explicitRoot.remoteUrl ?? remoteUrl,
+          defaultBranch: canonicalLane2?.defaultBranch ?? explicitRoot.defaultBranch ?? defaultBranch ?? null,
+          laneId: canonicalLane2?.laneId ?? explicitRoot.laneId,
+          branchName: defaultBranch,
+          bindingMode: "explicit_root"
         });
-        const existing = bindingResp?.responseObject;
-        if (existing?.projectId && existing?.appId) {
+        if (defaultBranch && branchName !== defaultBranch) {
+          await writeCollabBinding(repoRoot, {
+            projectId: boundProjectId2,
+            currentAppId: boundCurrentAppId2,
+            upstreamAppId: boundUpstreamAppId2,
+            threadId: boundThreadId2,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch: defaultBranch ?? null,
+            laneId: boundLaneId2,
+            branchName,
+            bindingMode: "lane"
+          });
+        }
+        return {
+          reused: true,
+          projectId: boundProjectId2 ?? explicitProjectId ?? "",
+          appId: boundCurrentAppId2,
+          dashboardUrl: buildDashboardAppUrl(boundCurrentAppId2),
+          upstreamAppId: boundUpstreamAppId2,
+          bindingPath: path5.join(repoRoot, ".remix", "config.json"),
+          repoRoot,
+          bindingMode: defaultBranch && branchName !== defaultBranch ? "lane" : "explicit_root",
+          createdCanonicalFamily: false,
+          ...warnings.length > 0 ? { warnings } : {}
+        };
+      }
+      if (!params.forceNew) {
+        const bindingResolution = resolveProjectBindingResult(
+          await params.api.resolveProjectBinding({
+            repoFingerprint,
+            remoteUrl: remoteUrl ?? void 0,
+            branchName: branchName ?? void 0
+          })
+        );
+        if (bindingResolution.status === "ambiguous_family_selection") {
+          throwAmbiguousFamilyError({
+            repoFingerprint,
+            remoteUrl,
+            projectIds: bindingResolution.projectIds,
+            candidateCount: bindingResolution.candidateCount
+          });
+        }
+        if (bindingResolution.status === "resolved") {
+          const initialProjectId = bindingResolution.projectId;
+          const initialCurrentAppId = bindingResolution.appId;
+          const initialUpstreamAppId = bindingResolution.upstreamAppId;
+          const initialThreadId = bindingResolution.threadId;
+          let boundProjectId2 = initialProjectId;
+          let boundCurrentAppId2 = initialCurrentAppId;
+          let boundUpstreamAppId2 = initialUpstreamAppId;
+          let boundThreadId2 = initialThreadId;
+          let boundLaneId2 = null;
+          let canonicalLane2 = null;
+          if (branchName) {
+            if (defaultBranch && branchName !== defaultBranch) {
+              canonicalLane2 = await resolveOrEnsureLaneBinding({
+                api: params.api,
+                repoFingerprint,
+                remoteUrl,
+                defaultBranch,
+                branchName: defaultBranch,
+                seedAppId: initialCurrentAppId,
+                operation: "`remix collab init`"
+              });
+              const lane = await resolveOrEnsureLaneBinding({
+                api: params.api,
+                projectId: canonicalLane2.projectId ?? void 0,
+                repoFingerprint,
+                remoteUrl,
+                defaultBranch,
+                branchName,
+                operation: "`remix collab init`"
+              });
+              boundProjectId2 = lane.projectId ?? boundProjectId2;
+              boundCurrentAppId2 = lane.currentAppId ?? boundCurrentAppId2;
+              boundUpstreamAppId2 = lane.upstreamAppId ?? boundUpstreamAppId2;
+              boundThreadId2 = lane.threadId ?? boundThreadId2;
+              boundLaneId2 = lane.laneId ?? null;
+            } else {
+              const lane = await resolveOrEnsureLaneBinding({
+                api: params.api,
+                repoFingerprint,
+                remoteUrl,
+                defaultBranch,
+                branchName,
+                seedAppId: initialCurrentAppId,
+                operation: "`remix collab init`"
+              });
+              canonicalLane2 = lane;
+              boundProjectId2 = lane.projectId ?? boundProjectId2;
+              boundCurrentAppId2 = lane.currentAppId ?? boundCurrentAppId2;
+              boundUpstreamAppId2 = lane.upstreamAppId ?? boundUpstreamAppId2;
+              boundThreadId2 = lane.threadId ?? boundThreadId2;
+              boundLaneId2 = lane.laneId ?? null;
+            }
+          }
+          if (boundCurrentAppId2) {
+            const readyApp = await pollAppReady(params.api, boundCurrentAppId2);
+            boundProjectId2 = String(readyApp.projectId ?? boundProjectId2);
+            boundThreadId2 = readyApp.threadId ? String(readyApp.threadId) : boundThreadId2;
+          }
           await assertRepoSnapshotUnchanged(repoRoot, repoSnapshot, {
             operation: "`remix collab init`",
             recoveryHint: "The repository changed while the local binding was being initialized. Review the local changes and rerun `remix collab init`."
           });
+          if (canonicalLane2 && defaultBranch && branchName && branchName !== defaultBranch) {
+            await writeCollabBinding(repoRoot, {
+              projectId: canonicalLane2.projectId ?? null,
+              currentAppId: canonicalLane2.currentAppId ?? boundCurrentAppId2,
+              upstreamAppId: canonicalLane2.upstreamAppId ?? canonicalLane2.currentAppId ?? boundCurrentAppId2,
+              threadId: canonicalLane2.threadId ?? null,
+              repoFingerprint: canonicalLane2.repoFingerprint ?? repoFingerprint,
+              remoteUrl: canonicalLane2.remoteUrl ?? remoteUrl,
+              defaultBranch: canonicalLane2.defaultBranch ?? defaultBranch,
+              laneId: canonicalLane2.laneId ?? null,
+              branchName: defaultBranch,
+              bindingMode: "lane"
+            });
+          }
           const bindingPath2 = await writeCollabBinding(repoRoot, {
-            projectId: String(existing.projectId),
-            currentAppId: String(existing.appId),
-            upstreamAppId: String(existing.upstreamAppId ?? existing.appId),
-            threadId: existing.threadId ? String(existing.threadId) : null,
+            projectId: boundProjectId2,
+            currentAppId: boundCurrentAppId2,
+            upstreamAppId: boundUpstreamAppId2,
+            threadId: boundThreadId2,
             repoFingerprint,
             remoteUrl,
             defaultBranch: defaultBranch ?? null,
-            preferredBranch
+            laneId: boundLaneId2,
+            branchName,
+            bindingMode: "lane"
           });
           return {
             reused: true,
-            projectId: String(existing.projectId),
-            appId: String(existing.appId),
-            dashboardUrl: buildDashboardAppUrl(String(existing.appId)),
-            upstreamAppId: String(existing.upstreamAppId ?? existing.appId),
+            projectId: boundProjectId2,
+            appId: boundCurrentAppId2,
+            dashboardUrl: buildDashboardAppUrl(boundCurrentAppId2),
+            upstreamAppId: boundUpstreamAppId2,
             bindingPath: bindingPath2,
             repoRoot,
+            bindingMode: "lane",
+            createdCanonicalFamily: false,
             ...warnings.length > 0 ? { warnings } : {}
           };
         }
@@ -1817,6 +2530,7 @@ async function collabInit(params) {
         path: params.path?.trim() || void 0,
         platform: "generic",
         isPublic: false,
+        branch: defaultBranch && branchName && branchName !== defaultBranch ? defaultBranch : currentBranch ?? void 0,
         remoteUrl: remoteUrl ?? void 0,
         defaultBranch: defaultBranch ?? void 0,
         repoFingerprint,
@@ -1824,31 +2538,136 @@ async function collabInit(params) {
       });
       const imported = unwrapResponseObject(importResp, "import");
       const app = await pollAppReady(params.api, String(imported.appId));
+      let boundProjectId = String(app.projectId);
+      let boundCurrentAppId = String(app.id);
+      let boundUpstreamAppId = String(app.id);
+      let boundThreadId = app.threadId ? String(app.threadId) : null;
+      let boundLaneId = null;
+      let canonicalLane = null;
+      if (branchName) {
+        if (defaultBranch && branchName !== defaultBranch) {
+          canonicalLane = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: boundProjectId,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName: defaultBranch,
+            seedAppId: String(app.id),
+            operation: "`remix collab init`"
+          });
+          const lane = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: canonicalLane.projectId ?? boundProjectId,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName,
+            operation: "`remix collab init`"
+          });
+          boundProjectId = lane.projectId ?? boundProjectId;
+          boundCurrentAppId = lane.currentAppId ?? boundCurrentAppId;
+          boundUpstreamAppId = lane.upstreamAppId ?? boundUpstreamAppId;
+          boundThreadId = lane.threadId ?? boundThreadId;
+          boundLaneId = lane.laneId ?? null;
+        } else {
+          const lane = await resolveOrEnsureLaneBinding({
+            api: params.api,
+            projectId: boundProjectId,
+            repoFingerprint,
+            remoteUrl,
+            defaultBranch,
+            branchName,
+            seedAppId: String(app.id),
+            operation: "`remix collab init`"
+          });
+          canonicalLane = lane;
+          boundProjectId = lane.projectId ?? boundProjectId;
+          boundCurrentAppId = lane.currentAppId ?? boundCurrentAppId;
+          boundUpstreamAppId = lane.upstreamAppId ?? boundUpstreamAppId;
+          boundThreadId = lane.threadId ?? boundThreadId;
+          boundLaneId = lane.laneId ?? null;
+        }
+      }
+      if (boundCurrentAppId) {
+        const readyApp = await pollAppReady(params.api, boundCurrentAppId);
+        boundProjectId = String(readyApp.projectId ?? boundProjectId);
+        boundThreadId = readyApp.threadId ? String(readyApp.threadId) : boundThreadId;
+      }
       await assertRepoSnapshotUnchanged(repoRoot, repoSnapshot, {
         operation: "`remix collab init`",
         recoveryHint: "The repository changed before the Remix binding was written. Review the local changes and rerun `remix collab init`."
       });
-      const bindingPath = await writeCollabBinding(repoRoot, {
-        projectId: String(app.projectId),
-        currentAppId: String(app.id),
-        upstreamAppId: String(app.id),
-        threadId: app.threadId ? String(app.threadId) : null,
-        repoFingerprint,
-        remoteUrl,
-        defaultBranch: defaultBranch ?? null,
-        preferredBranch
-      });
+      const bindingMode = params.forceNew && (!defaultBranch || branchName === defaultBranch) ? "explicit_root" : "lane";
+      let bindingPath;
+      if (params.forceNew && defaultBranch && canonicalLane) {
+        const canonicalBinding = branchBindingFromLane(canonicalLane, "explicit_root", {
+          projectId: canonicalLane.projectId ?? boundProjectId,
+          currentAppId: canonicalLane.currentAppId ?? boundCurrentAppId,
+          upstreamAppId: canonicalLane.upstreamAppId ?? canonicalLane.currentAppId ?? boundCurrentAppId,
+          threadId: canonicalLane.threadId ?? boundThreadId
+        });
+        const branchBindings = {
+          [defaultBranch]: canonicalBinding
+        };
+        if (branchName && branchName !== defaultBranch) {
+          branchBindings[branchName] = {
+            projectId: boundProjectId,
+            currentAppId: boundCurrentAppId,
+            upstreamAppId: boundUpstreamAppId,
+            threadId: boundThreadId,
+            laneId: boundLaneId,
+            bindingMode: "lane"
+          };
+        }
+        bindingPath = await writeCollabBindingSnapshot({
+          repoRoot,
+          repoFingerprint,
+          remoteUrl,
+          defaultBranch,
+          branchBindings,
+          explicitRootBinding: canonicalBinding
+        });
+      } else {
+        if (canonicalLane && defaultBranch && branchName && branchName !== defaultBranch) {
+          await writeCollabBinding(repoRoot, {
+            projectId: canonicalLane.projectId ?? null,
+            currentAppId: canonicalLane.currentAppId ?? boundCurrentAppId,
+            upstreamAppId: canonicalLane.upstreamAppId ?? canonicalLane.currentAppId ?? boundCurrentAppId,
+            threadId: canonicalLane.threadId ?? null,
+            repoFingerprint: canonicalLane.repoFingerprint ?? repoFingerprint,
+            remoteUrl: canonicalLane.remoteUrl ?? remoteUrl,
+            defaultBranch: canonicalLane.defaultBranch ?? defaultBranch,
+            laneId: canonicalLane.laneId ?? null,
+            branchName: defaultBranch,
+            bindingMode: params.forceNew ? "explicit_root" : "lane"
+          });
+        }
+        bindingPath = await writeCollabBinding(repoRoot, {
+          projectId: boundProjectId,
+          currentAppId: boundCurrentAppId,
+          upstreamAppId: boundUpstreamAppId,
+          threadId: boundThreadId,
+          repoFingerprint,
+          remoteUrl,
+          defaultBranch: defaultBranch ?? null,
+          laneId: boundLaneId,
+          branchName,
+          bindingMode
+        });
+      }
       return {
         reused: false,
-        projectId: String(app.projectId),
-        appId: String(app.id),
-        dashboardUrl: buildDashboardAppUrl(String(app.id)),
-        upstreamAppId: String(app.id),
+        projectId: boundProjectId,
+        appId: boundCurrentAppId,
+        dashboardUrl: buildDashboardAppUrl(boundCurrentAppId),
+        upstreamAppId: boundUpstreamAppId,
         bindingPath,
         repoRoot,
+        bindingMode,
+        createdCanonicalFamily: Boolean(params.forceNew),
         remoteUrl,
         defaultBranch,
-        preferredBranch,
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
@@ -1903,7 +2722,11 @@ import os4 from "os";
 import path6 from "path";
 async function collabReconcile(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab reconcile`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,
@@ -1912,9 +2735,9 @@ async function collabReconcile(params) {
   }
   await ensureCleanWorktree(repoRoot, "`remix collab reconcile`");
   const branch = await requireCurrentBranch(repoRoot);
-  assertPreferredBranchMatch({
+  assertBoundBranchMatch({
     currentBranch: branch,
-    preferredBranch: binding.preferredBranch,
+    branchName: binding.branchName,
     allowBranchMismatch: params.allowBranchMismatch,
     operation: "`remix collab reconcile`"
   });
@@ -2023,9 +2846,9 @@ async function collabReconcile(params) {
         });
         await ensureCleanWorktree(lockedRepoRoot, "`remix collab reconcile`");
         const lockedBranch = await requireCurrentBranch(lockedRepoRoot);
-        assertPreferredBranchMatch({
+        assertBoundBranchMatch({
           currentBranch: lockedBranch,
-          preferredBranch: binding.preferredBranch,
+          branchName: binding.branchName,
           allowBranchMismatch: params.allowBranchMismatch,
           operation: "`remix collab reconcile`"
         });
@@ -2084,31 +2907,65 @@ async function collabRemix(params) {
       hint: "Pass the source app id to remix."
     });
   }
-  const forkResp = await params.api.forkApp(sourceAppId, { name: params.name?.trim() || void 0, platform: "generic" });
+  const sourceApp = await pollAppReady(params.api, sourceAppId);
+  const sourceCollab = sourceApp.collab && typeof sourceApp.collab === "object" ? sourceApp.collab : null;
+  const sourceSource = sourceApp.source && typeof sourceApp.source === "object" ? sourceApp.source : null;
+  const sourceBranchName = typeof sourceCollab?.branchName === "string" && sourceCollab.branchName.trim() || typeof sourceSource?.branch === "string" && sourceSource.branch.trim() || typeof sourceSource?.defaultBranch === "string" && sourceSource.defaultBranch.trim() || void 0;
+  const forkResp = await params.api.forkApp(sourceAppId, {
+    name: params.name?.trim() || void 0,
+    platform: "generic",
+    branchName: sourceBranchName
+  });
   const forked = unwrapResponseObject(forkResp, "fork");
   const app = await pollAppReady(params.api, String(forked.id));
+  const collab = app.collab && typeof app.collab === "object" ? app.collab : null;
+  const source = app.source && typeof app.source === "object" ? app.source : null;
+  const authoritativeBranchName = typeof collab?.branchName === "string" && collab.branchName.trim() || typeof source?.branch === "string" && source.branch.trim() || typeof source?.defaultBranch === "string" && source.defaultBranch.trim() || sourceBranchName || null;
+  const authoritativeRemoteUrl = typeof source?.remoteUrl === "string" && source.remoteUrl.trim() || null;
+  const authoritativeDefaultBranch = typeof source?.defaultBranch === "string" && source.defaultBranch.trim() || null;
   const checkout = await materializeAppCheckout({
     api: params.api,
     cwd: params.cwd,
     appId: String(app.id),
     outputDir: params.outputDir ?? null,
-    defaultDirName: sanitizeCheckoutDirName(String(params.name?.trim() || app.name || app.id))
+    defaultDirName: sanitizeCheckoutDirName(String(params.name?.trim() || app.name || app.id)),
+    expectedBranchName: authoritativeBranchName,
+    expectedRemoteUrl: authoritativeRemoteUrl,
+    expectedDefaultBranch: authoritativeDefaultBranch
   });
-  const bindingPath = await writeCollabBinding(checkout.repoRoot, {
+  const laneId = typeof collab?.laneId === "string" ? collab.laneId : null;
+  const repoFingerprint = typeof source?.repoFingerprint === "string" ? source.repoFingerprint : checkout.repoFingerprint;
+  const remoteUrl = typeof source?.remoteUrl === "string" ? source.remoteUrl : checkout.remoteUrl;
+  const defaultBranch = typeof source?.defaultBranch === "string" ? source.defaultBranch : checkout.defaultBranch;
+  const branchName = authoritativeBranchName ?? checkout.branchName;
+  const authoritativeLane = await resolveProjectLaneIfAuthoritative(params.api, {
     projectId: String(app.projectId),
+    repoFingerprint,
+    remoteUrl,
+    defaultBranch,
+    branchName,
     currentAppId: String(app.id),
-    upstreamAppId: String(app.forkedFromAppId ?? sourceAppId),
-    threadId: app.threadId ? String(app.threadId) : null,
-    repoFingerprint: checkout.repoFingerprint,
-    remoteUrl: checkout.remoteUrl,
-    defaultBranch: checkout.defaultBranch,
-    preferredBranch: checkout.preferredBranch
+    expectedUpstreamAppId: String(app.forkedFromAppId ?? sourceAppId),
+    createIfMissing: true,
+    seedAppId: String(app.id)
+  });
+  const bindingPath = await writeCollabBinding(checkout.repoRoot, {
+    projectId: authoritativeLane?.projectId ?? String(app.projectId),
+    currentAppId: authoritativeLane?.currentAppId ?? String(app.id),
+    upstreamAppId: authoritativeLane?.upstreamAppId ?? String(app.forkedFromAppId ?? sourceAppId),
+    threadId: authoritativeLane?.threadId ?? (app.threadId ? String(app.threadId) : null),
+    repoFingerprint: authoritativeLane?.repoFingerprint ?? repoFingerprint,
+    remoteUrl: authoritativeLane?.remoteUrl ?? remoteUrl,
+    defaultBranch: authoritativeLane?.defaultBranch ?? defaultBranch,
+    laneId: authoritativeLane?.laneId ?? laneId,
+    branchName: authoritativeLane?.branchName ?? branchName,
+    bindingMode: "lane"
   });
   return {
-    appId: String(app.id),
-    dashboardUrl: buildDashboardAppUrl(String(app.id)),
-    projectId: String(app.projectId),
-    upstreamAppId: String(app.forkedFromAppId ?? sourceAppId),
+    appId: authoritativeLane?.currentAppId ?? String(app.id),
+    dashboardUrl: buildDashboardAppUrl(authoritativeLane?.currentAppId ?? String(app.id)),
+    projectId: authoritativeLane?.projectId ?? String(app.projectId),
+    upstreamAppId: authoritativeLane?.upstreamAppId ?? String(app.forkedFromAppId ?? sourceAppId),
     bindingPath,
     repoRoot: checkout.repoRoot
   };
@@ -2117,7 +2974,11 @@ async function collabRemix(params) {
 // src/application/collab/collabRequestMerge.ts
 async function collabRequestMerge(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab request-merge`"
+  });
   if (!binding) throw new RemixError("Repository is not bound to Remix.", { exitCode: 2 });
   const resp = await params.api.openMergeRequest(binding.currentAppId);
   return unwrapResponseObject(resp, "merge request");
@@ -2152,7 +3013,9 @@ function createBaseStatus() {
       repoFingerprint: null,
       remoteUrl: null,
       defaultBranch: null,
-      preferredBranch: null
+      laneId: null,
+      branchName: null,
+      bindingMode: null
     },
     remote: {
       checked: false,
@@ -2216,12 +3079,13 @@ async function collabStatus(params) {
   }
   status.repo.isGitRepo = true;
   status.repo.repoRoot = repoRoot;
-  const [branch, headCommitHash, worktreeStatus, binding] = await Promise.all([
+  const [branch, initialHeadCommitHash, worktreeStatus, bindingResolution] = await Promise.all([
     getCurrentBranch(repoRoot),
     getHeadCommitHash(repoRoot),
     getWorktreeStatus(repoRoot),
-    readCollabBinding(repoRoot)
+    resolveActiveLaneBinding({ repoRoot, api: params.api ?? void 0 })
   ]);
+  let headCommitHash = initialHeadCommitHash;
   status.repo.branch = branch;
   status.repo.branchMismatch = false;
   status.repo.headCommitHash = headCommitHash;
@@ -2235,13 +3099,61 @@ async function collabStatus(params) {
   if (!status.repo.worktree.isClean) addWarning(status, "Working tree has local changes.");
   if (!branch) addWarning(status, "Repository is in a detached HEAD state.");
   if (!headCommitHash) addWarning(status, "Failed to resolve local HEAD commit.");
-  if (!binding) {
+  if (bindingResolution.status === "not_bound") {
     status.binding.path = null;
     addBlockedReason(status.sync, "not_bound");
     addBlockedReason(status.reconcile, "not_bound");
     status.recommendedAction = "init";
     return status;
   }
+  if (bindingResolution.status === "missing_branch_binding") {
+    status.binding = {
+      isBound: true,
+      path: getCollabBindingPath(repoRoot),
+      projectId: bindingResolution.projectId,
+      currentAppId: null,
+      upstreamAppId: bindingResolution.upstreamAppId,
+      isRemix: null,
+      threadId: bindingResolution.threadId,
+      repoFingerprint: bindingResolution.repoFingerprint,
+      remoteUrl: bindingResolution.remoteUrl,
+      defaultBranch: bindingResolution.defaultBranch,
+      laneId: null,
+      branchName: bindingResolution.currentBranch,
+      bindingMode: "lane"
+    };
+    addBlockedReason(status.sync, "branch_binding_missing");
+    addBlockedReason(status.reconcile, "branch_binding_missing");
+    addWarning(status, `Current branch ${bindingResolution.currentBranch ?? "(detached)"} is not yet bound to a Remix lane.`);
+    status.recommendedAction = "init";
+    return status;
+  }
+  if (bindingResolution.status === "ambiguous_family_selection") {
+    status.binding = {
+      isBound: true,
+      path: getCollabBindingPath(repoRoot),
+      projectId: null,
+      currentAppId: null,
+      upstreamAppId: null,
+      isRemix: null,
+      threadId: null,
+      repoFingerprint: bindingResolution.repoFingerprint,
+      remoteUrl: bindingResolution.remoteUrl,
+      defaultBranch: bindingResolution.defaultBranch,
+      laneId: null,
+      branchName: bindingResolution.currentBranch,
+      bindingMode: null
+    };
+    addBlockedReason(status.sync, "family_ambiguous");
+    addBlockedReason(status.reconcile, "family_ambiguous");
+    addWarning(
+      status,
+      `Multiple canonical Remix families match ${bindingResolution.currentBranch ?? "the current branch"}. Switch to a checkout already bound to the intended family or run \`remix collab init --force-new\`.`
+    );
+    status.recommendedAction = "choose_family";
+    return status;
+  }
+  const binding = bindingResolution.binding;
   status.binding = {
     isBound: true,
     path: getCollabBindingPath(repoRoot),
@@ -2253,13 +3165,21 @@ async function collabStatus(params) {
     repoFingerprint: binding.repoFingerprint,
     remoteUrl: binding.remoteUrl,
     defaultBranch: binding.defaultBranch,
-    preferredBranch: binding.preferredBranch
+    laneId: binding.laneId,
+    branchName: binding.branchName,
+    bindingMode: binding.bindingMode
   };
-  status.repo.branchMismatch = !isPreferredBranchMatch(branch, binding.preferredBranch);
+  status.repo.branchMismatch = !isBoundBranchMatch(branch, binding.branchName);
   if (status.repo.branchMismatch) {
     addWarning(
       status,
-      `Current branch ${branch ?? "(detached)"} does not match preferred branch ${binding.preferredBranch ?? "(unset)"}.`
+      `Current branch ${branch ?? "(detached)"} does not match bound branch ${binding.branchName ?? "(unset)"}.`
+    );
+  }
+  if (bindingResolution.status === "binding_conflict") {
+    addWarning(
+      status,
+      `Local binding app ${binding.currentAppId} conflicts with server-resolved app ${bindingResolution.resolvedLane.currentAppId ?? "(unknown)"} for branch ${bindingResolution.currentBranch ?? "(detached)"}.`
     );
   }
   if (!params.api) {
@@ -2307,8 +3227,14 @@ async function collabStatus(params) {
     const syncResp = syncResult.value;
     if (syncResp) {
       const sync = unwrapResponseObject(syncResp, "sync result");
+      const latestHeadCommitHash = sync.targetCommitHash && sync.status !== "up_to_date" ? await getHeadCommitHash(repoRoot) : headCommitHash;
+      if (latestHeadCommitHash) {
+        headCommitHash = latestHeadCommitHash;
+        status.repo.headCommitHash = latestHeadCommitHash;
+      }
+      const normalizedSyncStatus = headCommitHash && sync.targetCommitHash && headCommitHash === sync.targetCommitHash ? "up_to_date" : sync.status;
       status.sync.checked = true;
-      status.sync.status = sync.status;
+      status.sync.status = normalizedSyncStatus;
       status.sync.warnings = sync.warnings;
       status.sync.targetCommitHash = sync.targetCommitHash;
       status.sync.targetCommitId = sync.targetCommitId;
@@ -2316,9 +3242,9 @@ async function collabStatus(params) {
       if (!status.repo.worktree.isClean) addBlockedReason(status.sync, "dirty_worktree");
       if (!branch) addBlockedReason(status.sync, "detached_head");
       if (status.repo.branchMismatch) addBlockedReason(status.sync, "branch_mismatch");
-      if (sync.status === "conflict_risk") addBlockedReason(status.sync, "metadata_conflict");
+      if (normalizedSyncStatus === "conflict_risk") addBlockedReason(status.sync, "metadata_conflict");
       status.sync.canApply = status.sync.status === "ready_to_fast_forward" && status.repo.worktree.isClean && Boolean(branch) && !status.sync.blockedReasons.includes("metadata_conflict");
-      if (sync.status === "conflict_risk") {
+      if (normalizedSyncStatus === "conflict_risk") {
         status.reconcile.checked = true;
         status.reconcile.status = "metadata_conflict";
         status.reconcile.warnings = sync.warnings;
@@ -2328,7 +3254,7 @@ async function collabStatus(params) {
         if (!status.repo.worktree.isClean) addBlockedReason(status.reconcile, "dirty_worktree");
         if (!branch) addBlockedReason(status.reconcile, "detached_head");
         if (status.repo.branchMismatch) addBlockedReason(status.reconcile, "branch_mismatch");
-      } else if (sync.status === "base_unknown") {
+      } else if (normalizedSyncStatus === "base_unknown") {
         try {
           const preflightResp = await params.api.preflightAppReconcile(binding.currentAppId, {
             localHeadCommitHash: headCommitHash,
@@ -2376,6 +3302,8 @@ async function collabStatus(params) {
     status.recommendedAction = "reconcile";
   } else if ((status.remote.incomingOpenMergeRequestCount ?? 0) > 0) {
     status.recommendedAction = "review_queue";
+  } else if (status.sync.blockedReasons.includes("family_ambiguous") || status.reconcile.blockedReasons.includes("family_ambiguous")) {
+    status.recommendedAction = "choose_family";
   } else {
     status.recommendedAction = "no_action";
   }
@@ -2385,7 +3313,11 @@ async function collabStatus(params) {
 // src/application/collab/collabSyncUpstream.ts
 async function collabSyncUpstream(params) {
   const repoRoot = await findGitRoot(params.cwd);
-  const binding = await readCollabBinding(repoRoot);
+  const binding = await ensureActiveLaneBinding({
+    repoRoot,
+    api: params.api,
+    operation: "`remix collab sync-upstream`"
+  });
   if (!binding) {
     throw new RemixError("Repository is not bound to Remix.", {
       exitCode: 2,