Tracks #1.
Summary
Build versioned Repository/Worktree snapshots, hybrid local refresh, operation coordination, and reconciliation primitives that remain correct while Codex tasks and external Git processes modify the same Repository.
Scope
- Add coherent
repositoryRevision, topologyRevision, refsRevision, and independent worktreeRevision values.
- Preserve the last successful snapshot with explicit stale/error state when a refresh fails.
- Refresh on open, focus, Current Project change, filesystem/Git metadata invalidation, manual request, and every operation outcome.
- Observe the selected Worktree and resolved Git metadata on macOS, with debouncing, selected-first refresh, staggered non-selected polling, and a full-discovery fallback poll.
- Bound Git-read concurrency, deduplicate equivalent reads, and discard late results from superseded refresh generations.
- Implement one local mutation lane per Worktree, one Repository Branch-switch lane, and one Repository remote-operation lane.
- Return typed
BUSY results instead of silently queuing mutations.
- Add operation IDs, cancellation state, idempotency, and reconciliation hooks for Succeeded, Rejected, FailedKnown, PartialSuccess, and UnknownOutcome.
- Never contact a Remote during local Refresh and never remove external Git locks.
Acceptance criteria
- Independent Worktree lanes may run concurrently; two Branch switches or two remote operations may not.
- An unrelated local mutation does not invalidate another Worktree's evidence axis unnecessarily.
- External file, Index, HEAD, ref, Worktree registration, and lock changes become visible through a new revision.
- A failed refresh retains and marks prior data rather than rendering false Clean/empty state.
- Late old reads cannot overwrite a newer snapshot.
- Cancelled or timed-out operations enter reconciliation before retry is enabled.
- The selected Worktree is observed within the PRD's 2-second visible-change target under the supported fixture.
Out of scope
- Specific Stage, Commit, Branch, or remote Git commands.
Dependencies
PRD coverage
- FR8; concurrency/recovery foundations for AC-08, AC-10, and AC-19–22.
Verification
- Deterministic scheduler tests, real Git external-mutation tests, watcher/poll fallback tests, and race tests with intentionally delayed reads.
Tracks #1.
Summary
Build versioned Repository/Worktree snapshots, hybrid local refresh, operation coordination, and reconciliation primitives that remain correct while Codex tasks and external Git processes modify the same Repository.
Scope
repositoryRevision,topologyRevision,refsRevision, and independentworktreeRevisionvalues.BUSYresults instead of silently queuing mutations.Acceptance criteria
Out of scope
Dependencies
PRD coverage
Verification