msd-core/docs/how-to/fix-worktree-base-mismatch.md

How to fix the worktree base-mismatch (exit 42) error

Goal: Understand why /gsd-execute-phase or /gsd-quick halts with FATAL: worktree base mismatch / exit 42 when your branch is ahead of the default branch, and choose the right fix to restore normal — or parallel — execution.

Prerequisites: GSD Core is installed and you have an active project. You have run /gsd-execute-phase or /gsd-quick and either seen the exit-42 error or the one-line ⚠ Worktree base mismatch warning.

---

What you will see

When you run /gsd-execute-phase or /gsd-quick on a branch that is ahead of the repository's default branch (for example, an unmerged milestone branch, a long-lived feature branch, or a branch with commits not yet in origin/HEAD), you may see one of two messages:

Automatic-degrade warning (phase or quick task still completes):

⚠ Worktree base mismatch: HEAD (abc12345) differs from origin/HEAD (def67890).
Running this phase sequentially on the main working tree. Parallel worktrees
return once HEAD is merged/pushed so origin/HEAD matches it, or set
worktree.baseRef:"head" to fork worktrees from HEAD instead (honored by
GSD-created worktrees and by the Claude Code harness; #683, #4588).

The phase or quick task runs to completion sequentially; nothing is blocked. This is the runtime mitigation (/gsd-execute-phase: #683/#1369; /gsd-quick: #1941).

Exit-42 halt (older installs or misconfigured environments):

FATAL: worktree base mismatch

All worktree-isolated executors halt immediately. Zero progress is made.

---

Why this happens

Unless worktree.baseRef is set to "head", Claude Code's isolation="worktree" forks executor worktrees from the repository's default branch (origin/HEAD), not from your current HEAD. When your branch contains commits that origin/HEAD does not have — plan files, new source files, anything added since the branch diverged — those files are absent inside each worktree. GSD's worktree-branch-check safety guard correctly refuses to act on a worktree that does not match the orchestrator's state, and exits with code 42.

This is the guard working as designed: it prevents silent data loss or phantom edits in the wrong tree. The error is a branch-state condition, not an OS-specific or hardware issue.

---

Option 1 — Do nothing (you are already unblocked)

If you saw the ⚠ Worktree base mismatch warning rather than an exit-42 halt, GSD has already automatically degraded to sequential execution on the main working tree for this run. The phase will complete. No action is required.

Use this option when:

• You are on a diverged branch temporarily
• You do not care about parallel execution for this phase
• You want to merge back to the default branch soon

---

Option 2 — Set worktree.baseRef: "head" (restores parallel execution on a diverged branch)

What this setting does (#3659, #4588): it makes new worktrees fork from your current HEAD instead of origin/HEAD, so the files your branch added are present inside each executor worktree and the wave can run in parallel. It is honored by GSD-created worktrees by construction and, as measured, by Claude Code's harness:

• Runtimes where GSD itself runs git worktree add <path> <start-point> (Codex, OpenCode, Kimi, Kimi Code) — by construction; the check suppresses on it (reason: "baseref-head").
• Claude Code's Agent(isolation="worktree") — because the harness reads the setting and forks from HEAD. This was measured on current Claude Code from the project-local, project-shared and user/global settings layers on macOS, Windows and Linux (#4588). Cursor, the other runtime whose harness creates the worktree, has not been measured — see below. An earlier finding that the harness did not read it (#48, verified against the Claude Code of the time; upstream claude-code#44965) was fixed upstream in claude-code#54940, but until #4588 GSD's pre-dispatch check still assumed it and degraded every wave on an unmerged branch regardless of the setting — the baseref-head-ignored-by-harness reason you may have seen on older installs.

Run the convenience command from your project root:

node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" worktree set-baseref

This writes worktree.baseRef: "head" into .claude/settings.local.json in your project root. It is no-clobber: if you already have an explicit baseRef set to something else, it leaves your value in place and tells you.

To verify the result, pass the dispatch mode the runtime uses:

node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" worktree base-check --mode harness-worktree

The output is JSON. With the setting in place expect shouldDegrade: false with reason: "baseref-head" in either mode — the check does not compare HEAD against origin/HEAD when the fork base is HEAD by configuration. Without the setting, on a diverged branch, expect shouldDegrade: true with reason: "head-diverged-from-fork".

If you configure a Claude Code WorktreeCreate hook, the setting does not reach the worktrees Claude Code dispatches: the hook creates them from the directory it emits, and Claude Code does not apply worktree.baseRef on that path. The check looks for such a hook in the same three settings files it reads worktree.baseRef from. When it finds one, or when one of those files does not parse, it compares HEAD against origin/HEAD as if the setting were absent, and a mismatch returns shouldDegrade: true with reason: "baseref-head-bypassed-by-hook" and a message naming the file (#4588). That fallback is the comparison the check makes without the setting, and it does not know where your hook forks either: when HEAD matches origin/HEAD the check does not degrade, and the exit-42 guard below still catches a hook that forks elsewhere. A hook cannot prove itself by leaving a worktree behind: the #4868 observation looks for a clean agent worktree under .claude/worktrees/ sitting at the current HEAD, but nothing on disk records which creator left it there, so one the plain harness created before you configured the hook — with HEAD unmoved since — would read as evidence for the hook. The check therefore does not consult that observation once a hook is in the path (#4881). To get a trusted verdict, pass the commit a hook-created worktree starts at as --observed-fork-base (described next), or remove the hook. Hooks from managed policy settings, a --settings file, plugins, agent frontmatter or SDK registrations are not visible to the check; there the exit-42 guard below is the backstop.

If you have a real measurement of what a worktree on this host forked from (git rev-parse HEAD inside a freshly created isolated worktree, before any commit — the full sha, not an abbreviation), pass it and the check evaluates that instead of inferring:

node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" worktree base-check --observed-fork-base <sha>

A match returns reason: "observed-fork-matches-head"; a mismatch with "head" set returns reason: "baseref-head-ignored-by-harness" — that worktree was not forked from HEAD despite the setting — and the run degrades to sequential as before.

Measured on Claude Code only. Cursor also declares harness-created worktrees; whether it honors worktree.baseRef has not been measured. There the pre-dispatch check trusts the setting the same way, and a host that does not honor it is caught by the exit-42 guard below. If you are on Cursor and see exit 42 with the setting in place, the SHA the halted executor prints is exactly the observation to pass here, and worth reporting.

Alternatively, set the value by hand in .claude/settings.local.json:

{
  "worktree": {
    "baseRef": "head"
  }
}

Note: Fresh installs and upgrades of GSD Core both set worktree.baseRef:"head" automatically in .claude/settings.local.json (no-clobber) when workflow.use_worktrees is enabled (the default). If you see the degrade warning on a fresh install, check that the key is still present — a hand-edited settings.local.json is the usual reason it is not.

Use this option when:

• You regularly work on long-lived or milestone branches, on any worktree-capable runtime
• You want parallel phase execution there (faster, lower context-window pressure)

---

Option 3 — Fallback: disable worktrees entirely

If worktrees are causing persistent problems beyond the base-mismatch (for example, your environment does not support them), disable them permanently for this project:

Add or edit .planning/config.json:

{
  "workflow": {
    "use_worktrees": false
  }
}

All executor agents will then run sequentially on the main working tree for every phase. This is equivalent to what the automatic degrade does, but permanent.

Use this option when:

• Worktrees are consistently problematic in your environment
• You prefer sequential execution for auditability or tooling reasons
• You are on a platform or CI setup that does not support git worktrees

See also: workflow.use_worktrees in the configuration reference.

---

The exit-42 backstop

The worktree-branch-check guard (exit 42) remains active in all execution modes as a safety backstop. It fires only when an executor worktree's branch does not match the expected orchestrator state — a condition that should not arise once you have applied one of the options above. It is also the observation-based check behind Option 2: with worktree.baseRef: "head" set, the pre-dispatch check trusts the setting and does not compare, so a host that does not honor it is caught here — the mismatched executors of that dispatch halt (every one of them, in a concurrent wave), and nothing is merged. If you continue to see exit 42 after setting worktree.baseRef: "head", your runtime is forking from somewhere other than HEAD; run /gsd-forensics to investigate, and pass the SHA the halted executor printed as --observed-fork-base to worktree base-check to see the verdict GSD would reach with that measurement.

---

Summary

Situation	Recommended action
Saw the warning, phase completed	Nothing — degrade handled it automatically
Regularly on diverged branches, want parallel execution	worktree set-baseref (Option 2)
Worktrees consistently problematic	Set workflow.use_worktrees: false (Option 3)
Still seeing exit 42 after fixes	Run /gsd-forensics "exit 42 after fix"

---

Related

• Recover and troubleshoot
• Debug a failed execution
• Configuration reference — workflow toggles
• CLI Tools reference — worktree commands
• docs index