Workflow: new worktrees should start from the latest origin, not whatever I last pulled

[ismatBabirli]

The workflow

I start most work by creating a new worktree workspace off main. Often I haven't pulled in a while, so the agent starts working on history that already trails the remote. I only notice later, when the PR is based on old commits or a rebase turns up conflicts that shouldn't exist.

"Remember to pull first" is the kind of step I will keep forgetting.

What actually happens today

Nothing in the branch-off creation path fetches. resolveBaseBranchForWorktree (packages/server/src/utils/worktree.ts) only runs git rev-parse --verify against refs/heads/<x>, then refs/remotes/origin/<x> — no network. The freshest those refs can be is the daemon's background git fetch origin --prune, which runs on a 180 s interval.

Two things make it easy to miss:

• resolveRepositoryDefaultBranch deliberately prefers the local branch name over the remote-tracking ref, so an unqualified main resolves to your possibly-stale local main.
• createWorktree then stores that resolved ref in the worktree metadata (baseRef: "refs/heads/main"), and getCheckoutStatus compares against exactly that stored ref. So a worktree cut from a 2-commit-stale main reports aheadBehind {ahead: 0, behind: 0}.

Measured on a local repro:

stored metadata     : { "baseRefName": "main", "baseRef": "refs/heads/main" }
status.aheadBehind  : {"ahead":0,"behind":0}
worktree HEAD       : one
origin/main         : three

The workspace is two commits behind the remote and nothing in the UI says so.

public-docs/worktrees.md already documents the manual workaround — "Use origin/main rather than main" — which is good advice nobody remembers to follow, and which doesn't help the New Workspace screen's default path or resolveDefaultBranch.

Proposal

Before git worktree add, refresh the base branch from its remote, then start from the remote tip when the local branch is purely behind it.

• Narrow fetch only: git fetch <remote> <branch> — one branch, never --prune, never the repository-wide refspec. This matters for bug: background fetch can massively inflate partial-clone repositories #3335, where the broad background fetch inflates partial clones.
• Never touches your checkout: no branch moves, no working tree changes, no git pull. That avoids every dirty-tree / diverged / branch-is-checked-out failure mode.
• Strictly-behind only: if the local branch holds commits the remote doesn't, branching off the remote would drop them, so local wins.
• Non-fatal: offline or unreachable remote falls through to today's local resolution rather than failing creation.
• Fork-aware: the remote comes from the ref, so refs/remotes/upstream/main fetches upstream, not origin.
• Opt-out: a "Fetch latest from remote" toggle in the New Workspace ref picker, remembered like the isolation preference, plus fetchBase: false on the create request for anyone whose fetching is managed outside Paseo.

Default on, because branching off a stale base is almost never what you want.

Cost is small: two extra local git commands when there's no remote (one config --get remote.<name>.url, one rev-list), plus one fetch when there is.

Scope

Worktree workspaces only. Local isolation is deliberately untouched — there the workspace is your checkout, and pulling it automatically would mutate your working tree.

I have this implemented and tested and am happy to open the PR, but wanted to check the direction first per CONTRIBUTING. Two things I'd particularly like a call on:

1. Default on or opt-in? I went with on.
2. Where the control lives. I put it in the ref picker's footer as a checkable row, since that's the thing it modifies and it adds no permanent chrome to the create form. A Settings toggle would be more discoverable but further from the action.

[ismatBabirli]

Implemented in #4116 — narrow per-branch fetch, no mutation of the user's checkout, strictly-behind-only fast-forward, opt-out toggle. Tests and before/after evidence are in the PR.

[odoo-mvds]

Adding another occurrence of this, hit today on Paseo 0.7.1 (desktop, macOS 26.6.2, git 2.54.0).

I created a new workspace off origin/main (qualified, so the workaround from public-docs/worktrees.md). Reflog of the resulting worktree branch:

$ git reflog show <branch> --date=iso
0c3e26b <branch>@{2026-09-01 22:16:29 +0200}: merge origin/main: Fast-forward
4053675 <branch>@{2026-09-01 21:07:05 +0200}: branch: Created from refs/remotes/origin/main

4053675 is a commit from 2026-08-30. The two commits it was missing had been on the remote since 15:26 and 19:19 that same day — hours before the workspace was created at 21:07. git ls-remote origin refs/heads/main returned 0c3e26b at the time. Worktree metadata:

"baseRefName": "main",
"baseRef": "refs/remotes/origin/main"

So the cached refs/remotes/origin/main was stale even though the base was qualified; nothing on the branch-off path fetched it, and the daemon had not run its background fetch for that repo (no workspace on it had been open).

If a smaller change is preferred over #4116: I have a server-only version at main...odoo-mvds:paseo:fix/branch-off-fetch-remote-base (16 lines in worktree.ts + 2 tests against real git repos). It fetches only <remote> <branch> when the resolved base is a remote-tracking ref and falls back to the cached ref when the fetch fails, so offline creation keeps working. No protocol or UI change. It does not cover the unqualified stale local main case that #4116 handles. Evidence:

$ npx vitest run src/utils/worktree.test.ts -t "remote-tracking base"     # without the fix
 FAIL  ... fetches origin so the new branch starts at the remote tip, not the cached ref
 AssertionError: expected '69fab7eb…' to be '339f4413…'
      Tests  1 failed | 1 passed | 20 skipped (22)

$ npx vitest run src/utils/worktree.test.ts --bail=1                       # with the fix
      Tests  22 passed (22)
$ npx vitest run src/utils/worktree.posix.test.ts --bail=1
      Tests  46 passed | 1 skipped (47)
$ npm run typecheck && npm run lint && npm run format:check                # all 0

Happy to open it as a PR if that direction is wanted; otherwise +1 to #4116.

[ismatBabirli]

That reflog is better evidence than anything in my write-up, and it corrects something I got wrong.

I claimed in #4116 that staleness is bounded by the 180 s background fetch. It isn't. ensureRepoTarget — which installs the setInterval and fires the immediate runRepoFetch — is only reached from the observed-workspace setup path (workspace-git-service.ts, via ensureRepoTarget at the end of workspace observation). A repo with no observed workspace is never fetched at all, so refs/remotes/origin/main can be arbitrarily old, which is exactly your 21:07-vs-15:26 gap. I'll fix that claim in the PR body.

Your case is already covered by #4116, so I don't think anyone has to choose between the two on that basis. resolveBaseRefFetchTarget reads the remote off the ref, so refs/remotes/origin/main resolves to { remote: "origin", branch: "main" } and gets fetched before the base is resolved. There's a test for exactly that shape against real repos:

it("fetches the branch named by an explicitly qualified remote-tracking base")

The two changes overlap rather than compete — same fix for the qualified base, and #4116 additionally handles the unqualified main case, where resolveRepositoryDefaultBranch deliberately prefers the local branch name and resolveDefaultBranch hands back a bare name for CLI/MCP creation. That path can't be fixed by fetching alone, since the fetch updates a ref the resolver then ignores.

Two things where your version is the better shape and I'd rather adopt them than defend mine:

• Falling back to the cached ref when the fetch fails is what I do too, but you scoped the fetch to "the resolved base is a remote-tracking ref", which is tighter than my "derive a remote from whatever we were given". Mine will attempt git fetch origin feature/x for a purely local branch and swallow the failure — one wasted network call per creation in that case. Worth narrowing.
• No protocol or UI change is genuinely less to review. My opt-out exists because of bug: background fetch can massively inflate partial-clone repositories #3335 (repos whose fetching is managed externally, where any automatic fetch is the bug), but if a maintainer would rather ship the behaviour first and add the control only if someone asks, that's a reasonable call and it drops the protocol field, the feature gate, and nine locale files from the diff.

So: no objection at all to yours going in, and if the preference is the smaller change I'm happy for #4116 to be closed in favour of it, or reduced to just the unqualified-main half on top. Either ordering works. Your call on opening it as a PR — I'd read the two together rather than as alternatives.

[odoo-mvds]

Opened the small version as #4287: server-only, fetches the one remote branch the base resolves to, falls back to the cached ref offline, real-git tests, bot review addressed. 116 lines in 2 files.

So the choice is:

• fix(server): fetch the remote base ref before branching off a new worktree #4287 alone: fixes the qualified origin/<branch> case, no protocol or UI change.
• Start new worktrees from the latest origin #4116: same fix plus the unqualified main case and an opt-out toggle.
• Both: fix(server): fetch the remote base ref before branching off a new worktree #4287 first, Start new worktrees from the latest origin #4116 reduced to the unqualified-main half on top (ismat is fine with either ordering).

Happy with whichever direction you prefer; just need the call.