fix(shared): resolve git base branch from origin head

Author: lee-to

docs/configuration.md

@@ -463,6 +463,14 @@ The config is editable via the **Global Settings** dialog in the web UI (gear ic
 | `skip_push_after_commit` | `false`    | Skip push after /aif-commit                     |
 | `strict_base_update`     | `false`    | Hard-fail if `git pull --ff-only` of base fails |
 
+When `config.yaml` is absent, Handoff treats the base branch as repository
+discovery: it first checks the branch pointed to by `refs/remotes/origin/HEAD`,
+then falls back to the legacy `master` branch, and only then to the built-in
+`main` default. When `base_branch` is explicitly configured and still points to
+the default `main`, but the local repository does not have `main`, Handoff uses
+the same `origin/HEAD` then `master` fallback. Explicit non-default base
+branches are strict: if you set `base_branch: develop`, that branch must exist.
+
 #### `skip_push_after_commit` semantics
 
 Controls whether the approve-done auto-commit flow (and any other `/aif-commit` run originating from the API) performs `git push` after creating the commit:

packages/shared/src/__tests__/gitIsolation.test.ts

@@ -232,6 +232,83 @@ describe("gitIsolation", () => {
     GIT_TEST_TIMEOUT_MS,
   );
 
+  it(
+    "falls back to master when the default main base is missing",
+    () => {
+      initRepo(projectRoot);
+      git(projectRoot, ["branch", "-M", "master"]);
+      writeConfig(projectRoot, "git:\n  base_branch: main\n  branch_prefix: feature/\n");
+
+      const result = ensureFeatureBranch({
+        projectRoot,
+        taskId: "task-master",
+        title: "Master default",
+      });
+
+      expect(result.action).toBe("created");
+      expect(result.branchName).toBe("feature/master-default-taskma");
+      expect(getCurrentBranch(projectRoot)).toBe("feature/master-default-taskma");
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "falls back to origin HEAD before legacy master when the default main base is missing",
+    () => {
+      initRepo(projectRoot);
+      git(projectRoot, ["checkout", "-b", "2.x"]);
+      git(projectRoot, ["branch", "master"]);
+      git(projectRoot, ["branch", "-D", "main"]);
+      git(projectRoot, ["update-ref", "refs/remotes/origin/2.x", "2.x"]);
+      git(projectRoot, ["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/2.x"]);
+      writeConfig(projectRoot, "git:\n  base_branch: main\n  branch_prefix: feature/\n");
+
+      const result = ensureFeatureBranch({
+        projectRoot,
+        taskId: "task-origin",
+        title: "Origin default",
+      });
+
+      expect(result.action).toBe("created");
+      expect(result.branchName).toBe("feature/origin-default-taskor");
+      if (!result.branchName) throw new Error("expected branch name");
+      expect(getCurrentBranch(projectRoot)).toBe("feature/origin-default-taskor");
+      const branchHead = git(projectRoot, ["rev-parse", result.branchName]);
+      const expectedHead = git(projectRoot, ["rev-parse", "2.x"]);
+      expect(branchHead).toBe(expectedHead);
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
+  it(
+    "uses origin HEAD before local main when project config is absent",
+    () => {
+      initRepo(projectRoot);
+      git(projectRoot, ["checkout", "-b", "2.x"]);
+      writeFileSync(join(projectRoot, "release.txt"), "2.x\n");
+      git(projectRoot, ["add", "release.txt"]);
+      git(projectRoot, ["commit", "-m", "release branch"]);
+      git(projectRoot, ["checkout", "main"]);
+      git(projectRoot, ["update-ref", "refs/remotes/origin/2.x", "2.x"]);
+      git(projectRoot, ["symbolic-ref", "refs/remotes/origin/HEAD", "refs/remotes/origin/2.x"]);
+
+      const result = ensureFeatureBranch({
+        projectRoot,
+        taskId: "task-no-config",
+        title: "No config",
+      });
+
+      expect(result.action).toBe("created");
+      expect(result.branchName).toBe("feature/no-config-taskno");
+      if (!result.branchName) throw new Error("expected branch name");
+      expect(getCurrentBranch(projectRoot)).toBe("feature/no-config-taskno");
+      const branchHead = git(projectRoot, ["rev-parse", result.branchName]);
+      const expectedHead = git(projectRoot, ["rev-parse", "2.x"]);
+      expect(branchHead).toBe(expectedHead);
+    },
+    GIT_TEST_TIMEOUT_MS,
+  );
+
   it(
     "returns switched when already on the task branch",
     () => {

packages/shared/src/gitIsolation.ts

@@ -129,6 +129,21 @@ export function branchExists(projectRoot: string, branchName: string): boolean {
   return status === 0;
 }
 
+function getOriginHeadBranch(projectRoot: string): string | null {
+  const { stdout, status } = runGit(
+    projectRoot,
+    ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"],
+    {
+      ignoreExit: true,
+    },
+  );
+  if (status !== 0 || !stdout) return null;
+  const prefix = "refs/remotes/origin/";
+  if (!stdout.startsWith(prefix)) return null;
+  const branchName = stdout.slice(prefix.length).trim();
+  return branchName || null;
+}
+
 export function workingTreeClean(projectRoot: string): boolean {
   const { stdout, status } = runGit(projectRoot, ["status", "--porcelain"], { ignoreExit: true });
   return status === 0 && stdout.length === 0;
@@ -208,6 +223,66 @@ function resolveGitConfig(projectRoot: string): AifProjectGit {
   return getProjectConfig(projectRoot).git;
 }
 
+function hasProjectConfigFile(projectRoot: string): boolean {
+  return existsSync(join(projectRoot, ".ai-factory", "config.yaml"));
+}
+
+function resolveGitDefaultBaseBranch(projectRoot: string, fallbackBase: string): string {
+  const originHeadBranch = getOriginHeadBranch(projectRoot);
+  if (originHeadBranch && branchExists(projectRoot, originHeadBranch)) {
+    log.warn(
+      {
+        projectRoot,
+        configuredBase: fallbackBase,
+        resolvedBase: originHeadBranch,
+        source: "origin/HEAD",
+      },
+      "No project git base branch is configured; using origin default branch",
+    );
+    return originHeadBranch;
+  }
+  if (branchExists(projectRoot, "master")) {
+    log.warn(
+      { projectRoot, configuredBase: fallbackBase, resolvedBase: "master" },
+      "No project git base branch is configured; using legacy master branch",
+    );
+    return "master";
+  }
+  return fallbackBase;
+}
+
+function resolveBaseBranch(
+  projectRoot: string,
+  configuredBase: string,
+  configFileExists: boolean,
+): string {
+  if (!configFileExists) {
+    return resolveGitDefaultBaseBranch(projectRoot, configuredBase);
+  }
+  if (branchExists(projectRoot, configuredBase)) {
+    return configuredBase;
+  }
+  if (configuredBase !== "main") {
+    return configuredBase;
+  }
+  const originHeadBranch = getOriginHeadBranch(projectRoot);
+  if (originHeadBranch && branchExists(projectRoot, originHeadBranch)) {
+    log.warn(
+      { projectRoot, configuredBase, resolvedBase: originHeadBranch, source: "origin/HEAD" },
+      "Configured base branch is missing; falling back to origin default branch",
+    );
+    return originHeadBranch;
+  }
+  if (branchExists(projectRoot, "master")) {
+    log.warn(
+      { projectRoot, configuredBase, resolvedBase: "master" },
+      "Configured base branch is missing; falling back to legacy master branch",
+    );
+    return "master";
+  }
+  return configuredBase;
+}
+
 export function projectUsesSharedBranchIsolation(projectRoot: string): boolean {
   const config = resolveGitConfig(projectRoot);
   return config.enabled && config.create_branches && isGitRepo(projectRoot);
@@ -271,8 +346,13 @@ export function ensureFeatureBranch(input: EnsureFeatureBranchInput): EnsureFeat
   // Step 1: ensure HEAD is on the base branch. We need it both as the
   // create-from-target for `git checkout -b` and as the target of the pull
   // policy below.
-  if (current !== config.base_branch) {
-    if (!branchExists(projectRoot, config.base_branch)) {
+  const baseBranch = resolveBaseBranch(
+    projectRoot,
+    config.base_branch,
+    hasProjectConfigFile(projectRoot),
+  );
+  if (current !== baseBranch) {
+    if (!branchExists(projectRoot, baseBranch)) {
       throw new BranchIsolationError(
         "base_branch_unavailable",
         `Base branch ${config.base_branch} does not exist in ${projectRoot}. Cannot create ${branchName} from a known base.`,
@@ -282,13 +362,13 @@ export function ensureFeatureBranch(input: EnsureFeatureBranchInput): EnsureFeat
     }
     const { status: checkoutStatus, stderr: checkoutErr } = runGit(
       projectRoot,
-      ["checkout", config.base_branch],
+      ["checkout", baseBranch],
       { ignoreExit: true },
     );
     if (checkoutStatus !== 0) {
       throw new BranchIsolationError(
         "base_branch_unavailable",
-        `Could not checkout base branch ${config.base_branch}: ${checkoutErr || "unknown error"}`,
+        `Could not checkout base branch ${baseBranch}: ${checkoutErr || "unknown error"}`,
         projectRoot,
         branchName,
       );
@@ -305,14 +385,14 @@ export function ensureFeatureBranch(input: EnsureFeatureBranchInput): EnsureFeat
   // opt into strict mode via `git.strict_base_update: true` — pull failure
   // becomes a hard BranchIsolationError("base_update_failed") classified as
   // blocked_external by the coordinator.
-  const pullResult = runGit(projectRoot, ["pull", "--ff-only", "origin", config.base_branch], {
+  const pullResult = runGit(projectRoot, ["pull", "--ff-only", "origin", baseBranch], {
     ignoreExit: true,
   });
   if (pullResult.status !== 0) {
     if (config.strict_base_update) {
       throw new BranchIsolationError(
         "base_update_failed",
-        `git pull --ff-only origin ${config.base_branch} failed: ${pullResult.stderr || "unknown error"}. ` +
+        `git pull --ff-only origin ${baseBranch} failed: ${pullResult.stderr || "unknown error"}. ` +
           `Project has git.strict_base_update=true; refusing to branch from a stale base.`,
         projectRoot,
         branchName,
@@ -322,7 +402,7 @@ export function ensureFeatureBranch(input: EnsureFeatureBranchInput): EnsureFeat
       {
         projectRoot,
         branchName,
-        baseBranch: config.base_branch,
+        baseBranch,
         stderr: pullResult.stderr,
       },
       "Could not fast-forward base branch before creating feature branch; continuing from local base (git.strict_base_update=false)",