fix(kanban): branch dispatched worktrees from fresh remote tip

[Mourey]

Problem

The interactive hermes -w path branches new worktrees from the freshly-fetched remote tip via _resolve_worktree_base (in cli.py), gated by the worktree_sync config (default on), with a fail-soft fallback to local HEAD. The kanban dispatch path never inherited this: _ensure_git_worktree in hermes_cli/kanban_db.py hardcoded "HEAD" for the new-branch case.

The standalone ~/.hermes/hermes-agent clone is updated only by hermes update, not every session, so its local HEAD can lag origin/main by many commits. A dispatched card branched from that stale HEAD roots the new branch on an old merge base. The result, observed in production: a later same-file card branches before its predecessor's PR merges, from a local main that never learned about the merge → textual merge conflicts against a moved origin/main, plus an inflated PR diff. Dispatch ordering can't fix a stale merge base.

Fix

Port the base-freshness logic the interactive path already has into the dispatch path — a narrow divergence fix, not a new feature.

• Extract _resolve_worktree_base from cli.py into a new shared module hermes_cli/worktree_sync.py (verbatim body + its own module logger). kanban_db must not import cli (cli imports kanban_db, not vice-versa), so the helper lives where both can import it. cli.py now imports the symbol from the shared module — behavior and the public name are unchanged.
• _ensure_git_worktree resolves the base ref for the new-branch case (gated by worktree_sync, defensively defaulting to True on a config error) and branches from it. It mirrors the interactive path's fail-soft retry: if worktree add <base_ref> fails and base_ref != "HEAD", it retries once from local HEAD before raising, so a fetch hiccup never hard-fails worktree creation. The existing-branch resume path is unchanged.

Offline / no-remote / detached-HEAD all still work — they fall back to HEAD exactly as before.

Tests

New tests/hermes_cli/test_kanban_worktree_base.py (7 cases) proves, against real scratch git repos:

• a new-branch worktree contains a remote-only commit → it branched from the fetched tip, not stale local HEAD, when worktree_sync is on;
• offline / unusable-ref cases still succeed by falling back to HEAD (mirrors _setup_worktree's retry);
• worktree_sync: false branches from local HEAD;
• the existing-branch resume path is unchanged.

Verified green:

• tests/hermes_cli/test_kanban_worktree_base.py — 7 passed
• tests/cli/test_worktree_sync_base.py (interactive-path regression) — 5 passed
• tests/hermes_cli/test_kanban_cli_dispatch_passthrough.py — 4 passed
• tests/hermes_cli/test_kanban_db.py (the changed module) — 223 passed

🤖 Generated with Claude Code

[teknium1]

Thanks for carrying the interactive worktree-base behavior into Kanban; the current-main premise is confirmed at hermes_cli/kanban_db.py:5416-5419, which hardcodes HEAD for new branches.

Problems

• hermes_cli/worktree_sync.py:54 invokes git fetch without checking its return code and immediately returns the upstream as “fetched” at line 55; the default-branch path repeats this at lines 80-81. With an unreachable remote and an existing stale tracking ref, this does not fall back to HEAD as described.
• tests/hermes_cli/test_kanban_worktree_base.py:125-140 cannot expose that case because the fixture's local HEAD and stale origin/main initially resolve to the same commit.

Suggested changes

• Require a successful fetch before returning either remote base ref; otherwise continue resolution and use HEAD as the final fallback.
• Make the failed-fetch test diverge local HEAD from the stale tracking ref and assert the resulting worktree selects local HEAD.

Automated hermes-sweeper review.

[teknium1]

Please check this fetch result before returning upstream as “(fetched)” on line 55. A nonzero fetch leaves any existing tracking ref usable but stale, so the new Kanban path will not take the advertised HEAD fallback; apply the same check to the default-ref fetch at line 80.

[Mourey]

Rebased onto current main (was ~1500 commits behind; now conflict-free and mergeable).

Only conflict was an import-line adjacency in cli.py — main added CLIBillingMixin where this branch adds worktree_sync; kept both. Diffstat is unchanged from the original commit.

Still needed on current main: _ensure_git_worktree continues to hardcode "HEAD" for the new-branch case (hermes_cli/kanban_db.py:5753), so dispatched worktrees still branch from the standalone clone's stale local HEAD rather than the fetched remote tip.

Verified against current main: tests/hermes_cli/test_kanban_worktree_base.py + tests/tools/test_kanban_tools.py — 121 passed.

[PRATHAMESH75]

This PR fixes #68201 (kanban _ensure_git_worktree bases new worktree branches on a possibly-parked local HEAD, so a primary checkout left on an unmerged branch contaminates worker branches). It ports the interactive hermes -w base-freshness logic into the dispatch path: _resolve_worktree_base is extracted into a shared hermes_cli/worktree_sync.py (so kanban_db need not import cli), and the new-branch case branches from the freshly-resolved remote tip — gated by worktree_sync, defaulting to True on a config error — with a fail-soft retry from HEAD if the resolved base fails once. The existing-branch resume path is unchanged. That directly resolves the issue's root cause.

Note the issue suggested probing origin/HEAD; this PR instead reuses the repo's existing _resolve_worktree_base (fetched remote tip), which gives parity with the interactive path and is config-gated — a better tradeoff than a second bespoke probe. Offline / no-remote / detached-HEAD fall back to HEAD as before, covered by the 7 new cases in test_kanban_worktree_base.py. For context: upstream #50355 fixed only the interactive cli.py path, not this dispatch path, so this remains needed.

[brandonedley]

Independent production corroboration for this, plus a second failure mode that I think strengthens the case.

We hit this on a self-hosted fleet running kanban lanes and shipped a narrower local patch on 2026-07-20 (issue #68201 was my writeup of it). Yours is a superset and I'm dropping mine in favour of it — but the symptom we saw was different from the stale-base ergonomics problem described here, and worse:

Contamination, not just staleness. _ensure_git_worktree basing on HEAD means "whatever branch the primary checkout happens to be parked on." Our primary clone was sitting on an unmerged PR branch, so every worker branch cut during that window was born containing that PR's diff. The workers then opened PRs carrying changes nobody on those tasks had written. That reads as a correctness bug rather than a diff-size annoyance — the resulting PRs looked legitimate and the extra content was only caught downstream.

A gap in my version that yours closes. Mine resolved origin/HEAD via git rev-parse --abbrev-ref origin/HEAD and used it directly. That's a local remote-tracking ref, so with no fetch it can be arbitrarily stale — I fixed the "wrong branch" half and left the "old commit" half open. Your step-1/step-2 fetch is the part I got wrong.

Two details in your patch that look right to me from having run the narrower version in production:

• Applying it to both cli.py:_setup_worktree and kanban_db.py:_ensure_git_worktree — I only patched the kanban path, and the CLI path has the identical exposure.
• The @{upstream} step ordering. A deliberate feature-branch worktree should track its own remote rather than snapping to the default branch, and checking upstream before origin/HEAD is what preserves that.

The fail-soft retry in _ensure_git_worktree (resolved ref fails → retry from local HEAD with a warning) is the detail I'd have gotten wrong; a partial fetch leaving an unusable remote ref is exactly the edge my simpler version would have hard-failed on.

Happy to test this against our fleet's lane provisioning if that's useful — we have the reproducing condition (parked primary checkout + concurrent worker spawns) readily available.