Finding the Real Checkout Behind a Worktree
Making run identity resolve to the primary checkout no matter where Gantry is invoked
0 milestones 2 sprints 6 agents
2 plan 2 execute 2 review
124k peak context
33m 35s total 12m 18s per sprint
1m 48s plan 8m 50s execute 6m 39s review
12 edits 130 commands
codex harness
Gantry names a run from the plan and the repository root, then uses that identity to find the run worktree, branch, and orchestration directory again. Linked git worktrees broke that assumption: the command could be invoked from a secondary checkout whose top-level directory was not the primary checkout Gantry needed for stable run identity.
This job fixed the repository-location boundary and then audited the command layer that depends on it. The result is a split between the primary checkout used to identify runs and the current checkout used by callers that must read or write the tree they are standing in.
How this walkthrough is structured
Feature
What did the run build and ship?
Run identity now resolves through git's shared common directory, while checkout-local work has an explicit resolver that does not climb out of the invoking worktree.
Build
How did Gantry structure the work?
The run put the shared root resolver ahead of the entrypoint audit, so the caller sweep inherited a proved meaning for the primary checkout and stayed green.
Milestone 1
Linked Worktree Run Location
The live tree still treats linked-worktree invocation as a run-identity problem rather than a command-specific exception. Worktree location, registry enumeration, cleanup target selection, and run locking all route through primary-checkout resolution where the run name is being located. Tests still create linked worktrees and compare the paths reported from the primary checkout and the linked checkout.
The milestone carried the whole linked-worktree correction but kept the boundary narrow: path resolution, run discovery, cleanup targets, launch, and resume could change, while merge behavior and unrelated worktree policy were outside scope. That made the work suitable for a short run because every piece answered the same invariant, not a separate product feature. The run facts show no retries, red gates, or forced re-plans, so the milestone did not expose hidden coupling beyond the planned resolver-to-callers split.
Primary Checkout
The worktree module now has a primary-checkout resolver that asks git for the common directory and derives the root all linked checkouts share. It also keeps a separate current-checkout resolver for code that must operate inside the invoking tree. Worktree location normalizes its input through the primary resolver, and the regression tests still cover both normal checkout invocation and linked-worktree invocation.
This sprint owned the shared invariant before any command surface depended on it. Its brief asked for the repository root used for run identity to resolve to the primary checkout from either invocation point, with regression coverage for the doubled storage directory and linked-basename failure modes. Because the work was centered in the resolver and worktree path derivation, a fresh agent could prove the root cause without auditing every caller at the same time. The boundary held cleanly under the gate.
Run Entrypoint Audit
Registry enumeration now normalizes the repository before it scans active and finished runs, and cleanup target discovery begins from the located worktree's primary repository. Run locks also key their pid file from the primary checkout, so a live run has the same address from the isolated run worktree and from the main checkout. The entrypoint contribution is still visible in user-facing tests for registry and cleanup, while some later callers have grown around the same resolver contract.
The second sprint was an audit over callers rather than another search for the bug. With the resolver already established, the agent could inspect status, enter, cleanup, launch, resume, detach, and assistant-facing paths for whether they were naming a run or touching the current checkout. That distinction kept the work reviewable: run identity should climb to the primary checkout, while local file work should stay where the command was invoked. This sprint also stayed green, so the audit did not require a re-plan.