@remixhq/core 0.1.10 → 0.1.11

package/dist/collab.js

@@ -1,10 +1,12 @@
 import {
   getCollabBindingPath,
   readCollabBinding,
+  readCollabBindingState,
   reserveAvailableDirPath,
   reserveDirectory,
   writeCollabBinding
-} from "./chunk-GEHSFPCD.js";
+} from "./chunk-4L3ZBZUQ.js";
+import "./chunk-HZNEDSRS.js";
 import {
   assertRepoSnapshotUnchanged,
   buildRepoFingerprint,
@@ -38,7 +40,7 @@ import {
   summarizeUnifiedDiff,
   validateUnifiedDiff,
   writeTempUnifiedDiffBackup
-} from "./chunk-J3J4PBQ7.js";
+} from "./chunk-RREREIGW.js";
 import {
   REMIX_ERROR_CODES
 } from "./chunk-GC2MOT3U.js";
@@ -55,29 +57,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 +143,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 +333,275 @@ 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;
+  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: lane.branchName ?? state.currentBranch ?? null,
+    bindingMode: "lane"
+  };
+}
+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);
+}
+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: 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 === "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: state.projectId,
+        repoFingerprint: state.repoFingerprint,
+        remoteUrl: state.remoteUrl,
+        defaultBranch: state.defaultBranch,
+        upstreamAppId: localBinding.upstreamAppId ?? null,
+        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.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 === "resolved") {
+    const binding = buildBindingFromLane(state, lane);
+    if (binding) {
+      return {
+        status: "resolved",
+        source: "remote",
+        binding,
+        currentBranch
+      };
+    }
+  }
+  if (lane.status === "binding_not_found") {
+    return { status: "not_bound", currentBranch };
+  }
+  return {
+    status: "missing_branch_binding",
+    currentBranch,
+    projectId: lane.projectId ?? state.projectId,
+    repoFingerprint: lane.repoFingerprint ?? state.repoFingerprint,
+    remoteUrl: lane.remoteUrl ?? state.remoteUrl,
+    defaultBranch: lane.defaultBranch ?? state.defaultBranch,
+    upstreamAppId: lane.upstreamAppId ?? null,
+    threadId: lane.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 === "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"}.`
+  });
+}
+async function provisionActiveLaneBinding(params) {
+  const resolved = await resolveActiveLaneBinding(params);
+  if (resolved.status === "resolved") {
+    if (resolved.source === "local") {
+      return { binding: resolved.binding, warnings: [] };
+    }
+    const persisted2 = await persistResolvedLane(params.repoRoot, resolved.binding);
+    return { binding: persisted2, warnings: [] };
+  }
+  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}.`
+    });
+  }
+  if (resolved.status === "not_bound") {
+    return { binding: null, warnings: [] };
+  }
+  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}.`
+    });
+  }
+  let lane;
+  try {
+    const laneResp = await params.api.ensureProjectLaneBinding({
+      projectId: resolved.projectId ?? void 0,
+      repoFingerprint: resolved.repoFingerprint ?? void 0,
+      remoteUrl: resolved.remoteUrl ?? void 0,
+      defaultBranch: resolved.defaultBranch ?? void 0,
+      branchName: resolved.currentBranch
+    });
+    lane = unwrapResponseObject(laneResp, "project lane binding");
+  } catch (error) {
+    throw new RemixError(`Failed to provision a Remix lane for branch ${resolved.currentBranch}.`, {
+      exitCode: error instanceof RemixError ? error.exitCode : 1,
+      hint: formatCliErrorDetail(error) || `Remix could not create or recover the branch lane required before ${params.operation}.`
+    });
+  }
+  const state = await readCollabBindingState(params.repoRoot);
+  if (!state) {
+    return { binding: null, warnings: [] };
+  }
+  const binding = buildBindingFromLane(state, lane);
+  if (!binding) {
+    throw new RemixError(`Failed to provision a Remix lane for branch ${resolved.currentBranch}.`, {
+      exitCode: 1,
+      hint: "The server returned incomplete lane binding metadata."
+    });
+  }
+  const persisted = await persistResolvedLane(params.repoRoot, binding);
+  return {
+    binding: persisted,
+    warnings: [
+      lane.created ? `Provisioned Remix lane for branch ${resolved.currentBranch}.` : `Recovered existing Remix lane binding for branch ${resolved.currentBranch}.`
+    ]
+  };
+}
+
 // src/application/collab/recordingPreflight.ts
 async function collabRecordingPreflight(params) {
   let repoRoot;
@@ -297,7 +614,7 @@ async function collabRecordingPreflight(params) {
       repoRoot: null,
       appId: null,
       currentBranch: null,
-      preferredBranch: null,
+      branchName: null,
       headCommitHash: null,
       worktreeClean: false,
       syncStatus: null,
@@ -309,14 +626,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 +645,56 @@ 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 === "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 +706,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 +721,9 @@ async function collabRecordingPreflight(params) {
       reconcileTargetHeadCommitHash: null,
       reconcileTargetHeadCommitId: null,
       warnings: [],
-      hint: buildPreferredBranchMismatchHint({
+      hint: buildBranchMismatchHint({
         currentBranch,
-        preferredBranch
+        branchName
       })
     };
   }
@@ -387,7 +741,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -405,7 +759,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -430,7 +784,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -448,7 +802,7 @@ async function collabRecordingPreflight(params) {
       repoRoot,
       appId: binding.currentAppId,
       currentBranch,
-      preferredBranch,
+      branchName,
       headCommitHash,
       worktreeClean: worktreeStatus.isClean,
       syncStatus: sync.status,
@@ -465,7 +819,7 @@ async function collabRecordingPreflight(params) {
     repoRoot,
     appId: binding.currentAppId,
     currentBranch,
-    preferredBranch,
+    branchName,
     headCommitHash,
     worktreeClean: worktreeStatus.isClean,
     syncStatus: sync.status,
@@ -697,7 +1051,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 +1064,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 +1143,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 +1178,12 @@ 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 === "not_git_repo") {
     throw new RemixError(preflight.hint || "Not inside a git repository.", {
       exitCode: 2,
@@ -833,9 +1197,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 +1219,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 +1244,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 +1419,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 +1495,12 @@ 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 === "not_git_repo") {
     throw new RemixError(preflight.hint || "Not inside a git repository.", {
       exitCode: 2,
@@ -1139,9 +1514,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 +1536,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 +1572,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 +1588,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 +1601,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 +1612,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 +1724,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 +1737,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 +1822,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 +1886,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 +1897,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 +1920,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 +1990,26 @@ 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)"}.`
+    });
+  }
+  return bindingResolution.binding.currentAppId;
 }
 async function collabListMergeRequests(params) {
   const appId = await resolveQueueAppId({
@@ -1615,12 +2040,32 @@ 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)"}.`
+    });
+  }
+  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) {
@@ -1758,13 +2203,28 @@ 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,
+          branchName: branchName ?? void 0
+        });
+        const existing = bindingResp?.responseObject;
+        if (existing?.projectId && existing?.appId) {
+          throw new RemixError("`remix collab init --force-new` is not allowed for repositories already known to Remix.", {
+            exitCode: 2,
+            hint: "This repository already resolves to an existing Remix lineage. Run `remix collab init` without `--force-new`, or use an explicit checkout/remix flow instead of creating a duplicate imported app."
+          });
+        }
+      }
       if (!params.forceNew) {
         const bindingResp = await params.api.resolveProjectBinding({
           repoFingerprint,
-          remoteUrl: remoteUrl ?? void 0
+          remoteUrl: remoteUrl ?? void 0,
+          branchName: branchName ?? void 0
         });
         const existing = bindingResp?.responseObject;
         if (existing?.projectId && existing?.appId) {
@@ -1772,25 +2232,55 @@ async function collabInit(params) {
             operation: "`remix collab init`",
             recoveryHint: "The repository changed while the local binding was being initialized. Review the local changes and rerun `remix collab init`."
           });
+          const initialProjectId = String(existing.projectId);
+          const initialCurrentAppId = String(existing.appId);
+          const initialUpstreamAppId = String(existing.upstreamAppId ?? existing.appId);
+          const initialThreadId = existing.threadId ? String(existing.threadId) : null;
           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: initialProjectId,
+            currentAppId: initialCurrentAppId,
+            upstreamAppId: initialUpstreamAppId,
+            threadId: initialThreadId,
             repoFingerprint,
             remoteUrl,
             defaultBranch: defaultBranch ?? null,
-            preferredBranch
+            laneId: null,
+            branchName,
+            bindingMode: "lane"
           });
+          let boundProjectId2 = initialProjectId;
+          let boundCurrentAppId2 = initialCurrentAppId;
+          let boundUpstreamAppId2 = initialUpstreamAppId;
+          let boundThreadId2 = initialThreadId;
+          let finalWarnings = [...warnings];
+          if (branchName) {
+            const provisioned = await provisionActiveLaneBinding({
+              repoRoot,
+              api: params.api,
+              operation: "`remix collab init`"
+            });
+            if (provisioned.binding) {
+              boundProjectId2 = provisioned.binding.projectId ?? boundProjectId2;
+              boundCurrentAppId2 = provisioned.binding.currentAppId;
+              boundUpstreamAppId2 = provisioned.binding.upstreamAppId;
+              boundThreadId2 = provisioned.binding.threadId;
+            }
+            finalWarnings = [...finalWarnings, ...provisioned.warnings];
+          }
+          if (boundCurrentAppId2) {
+            const readyApp = await pollAppReady(params.api, boundCurrentAppId2);
+            boundProjectId2 = String(readyApp.projectId ?? boundProjectId2);
+            boundThreadId2 = readyApp.threadId ? String(readyApp.threadId) : boundThreadId2;
+          }
           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,
-            ...warnings.length > 0 ? { warnings } : {}
+            ...finalWarnings.length > 0 ? { warnings: finalWarnings } : {}
           };
         }
       }
@@ -1817,6 +2307,7 @@ async function collabInit(params) {
         path: params.path?.trim() || void 0,
         platform: "generic",
         isPublic: false,
+        branch: currentBranch ?? void 0,
         remoteUrl: remoteUrl ?? void 0,
         defaultBranch: defaultBranch ?? void 0,
         repoFingerprint,
@@ -1824,31 +2315,65 @@ 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;
+      if (branchName) {
+        const laneResp = defaultBranch && branchName !== defaultBranch ? await params.api.bootstrapFreshProjectLane({
+          projectId: boundProjectId,
+          repoFingerprint,
+          remoteUrl: remoteUrl ?? void 0,
+          defaultBranch: defaultBranch ?? void 0,
+          branchName,
+          seedAppId: String(app.id)
+        }) : await params.api.ensureProjectLaneBinding({
+          projectId: boundProjectId,
+          repoFingerprint,
+          remoteUrl: remoteUrl ?? void 0,
+          defaultBranch: defaultBranch ?? void 0,
+          branchName,
+          seedAppId: String(app.id)
+        });
+        const lane = unwrapResponseObject(laneResp, "project lane binding");
+        boundProjectId = typeof lane.projectId === "string" && lane.projectId ? lane.projectId : boundProjectId;
+        boundCurrentAppId = typeof lane.currentAppId === "string" && lane.currentAppId ? lane.currentAppId : boundCurrentAppId;
+        boundUpstreamAppId = typeof lane.upstreamAppId === "string" && lane.upstreamAppId ? lane.upstreamAppId : boundUpstreamAppId;
+        boundThreadId = typeof lane.threadId === "string" && lane.threadId ? lane.threadId : boundThreadId;
+        boundLaneId = typeof lane.laneId === "string" && lane.laneId ? 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,
+        projectId: boundProjectId,
+        currentAppId: boundCurrentAppId,
+        upstreamAppId: boundUpstreamAppId,
+        threadId: boundThreadId,
         repoFingerprint,
         remoteUrl,
         defaultBranch: defaultBranch ?? null,
-        preferredBranch
+        laneId: boundLaneId,
+        branchName,
+        bindingMode: "lane"
       });
       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,
         remoteUrl,
         defaultBranch,
-        preferredBranch,
         ...warnings.length > 0 ? { warnings } : {}
       };
     }
@@ -1903,7 +2428,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 +2441,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 +2552,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 +2613,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 +2680,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 +2719,9 @@ function createBaseStatus() {
       repoFingerprint: null,
       remoteUrl: null,
       defaultBranch: null,
-      preferredBranch: null
+      laneId: null,
+      branchName: null,
+      bindingMode: null
     },
     remote: {
       checked: false,
@@ -2216,12 +2785,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 +2805,36 @@ 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 = "no_action";
+    return status;
+  }
+  const binding = bindingResolution.binding;
   status.binding = {
     isBound: true,
     path: getCollabBindingPath(repoRoot),
@@ -2253,13 +2846,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 +2908,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 +2923,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 +2935,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,
@@ -2385,7 +2992,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,