Support HEAD as upstream merge base

script/upstream/README.md

@@ -204,7 +204,7 @@ The only remaining conflicts are files with **actual code differences** - files
 Options:
   --version <version>    Target upstream version (e.g., v1.1.49)
   --commit <hash>        Target upstream commit hash
-  --base-branch <name>   Base branch to merge into (default: main)
+  --base-branch <name>   Base branch to merge into; use HEAD for current branch (default: main)
   --dry-run              Preview changes without applying them
   --no-push              Don't push branches to remote
   --no-worktrees         Don't create reference worktrees
@@ -305,6 +305,8 @@ Tighten the blast radius with `--review-limit 0` (only `markers-only` and `cosme
 
 By default, upstream merges start from the `main` branch. However, you can use `--base-branch` to start from a different branch. This is useful for:
 
+Passing `--base-branch HEAD` targets the currently checked-out branch without typing its full name.
+
 ### Incremental Merges
 
 When working on multiple upstream versions, you can create a chain of merge PRs:

script/upstream/merge.ts

@@ -10,7 +10,7 @@
  * Options:
  *   --version <version>  Target upstream version (e.g., v1.1.49)
  *   --commit <hash>      Target upstream commit hash
- *   --base-branch <name> Base branch to merge into (default: main)
+ *   --base-branch <name> Base branch to merge into, or HEAD for current branch (default: main)
  *   --dry-run            Preview changes without applying them
  *   --no-push            Don't push branches to remote
  *   --no-worktrees       Don't create reference worktrees for manual resolution
@@ -25,7 +25,7 @@ import * as logger from "./utils/logger"
 import * as version from "./utils/version"
 import * as report from "./utils/report"
 import * as worktree from "./utils/worktree"
-import { loadConfig } from "./utils/config"
+import { loadConfig, resolveBaseBranch } from "./utils/config"
 import { transformAll as transformPackageNames } from "./transforms/package-names"
 import { preserveAllVersions } from "./transforms/preserve-versions"
 import { keepOursFiles, resetToOurs } from "./transforms/keep-ours"
@@ -219,7 +219,6 @@ async function main() {
   process.chdir((await $`git rev-parse --show-toplevel`.text()).trim())
 
   const options = parseArgs()
-  const config = loadConfig(options.baseBranch ? { baseBranch: options.baseBranch } : undefined)
 
   if (options.verbose) {
     logger.setVerbose(true)
@@ -248,6 +247,12 @@ async function main() {
   const currentBranch = await git.getCurrentBranch()
   logger.info(`Current branch: ${currentBranch}`)
 
+  const base = resolveBaseBranch(options.baseBranch, currentBranch)
+  const config = loadConfig(base ? { baseBranch: base } : undefined)
+  if (options.baseBranch === "HEAD") {
+    logger.info(`Resolved --base-branch HEAD to current branch: ${config.baseBranch}`)
+  }
+
   // Enable git rerere so conflict resolutions are recorded and reused across merges
   if (!options.dryRun) {
     await git.ensureRerere()

script/upstream/utils/config.test.ts

@@ -0,0 +1,15 @@
+import { expect, test } from "bun:test"
+import { resolveBaseBranch } from "./config"
+
+test("resolves HEAD to the current branch", () => {
+  expect(resolveBaseBranch("HEAD", "session/agent-123")).toBe("session/agent-123")
+})
+
+test("keeps explicit base branch names", () => {
+  expect(resolveBaseBranch("main", "session/agent-123")).toBe("main")
+  expect(resolveBaseBranch(undefined, "session/agent-123")).toBeUndefined()
+})
+
+test("rejects HEAD when detached", () => {
+  expect(() => resolveBaseBranch("HEAD", "HEAD")).toThrow("--base-branch HEAD requires a named branch")
+})

script/upstream/utils/config.ts

@@ -231,3 +231,9 @@ export const defaultConfig: MergeConfig = {
 export function loadConfig(overrides?: Partial<MergeConfig>): MergeConfig {
   return { ...defaultConfig, ...overrides }
 }
+
+export function resolveBaseBranch(base: string | undefined, current: string): string | undefined {
+  if (base !== "HEAD") return base
+  if (current === "HEAD") throw new Error("--base-branch HEAD requires a named branch, but git is in detached HEAD")
+  return current
+}