Source control and reviews
Source control connects the selected Git worktree to local change management and hosted code review. It lets an engineer inspect work, make guarded Git changes, compare a branch with its base, and create or follow a pull request or merge request. See Git operations and status for Git operation rules and Source-control AI workflows for AI-assisted actions.
System purpose
The source-control system keeps Git state, branch analysis, and hosted review in one worktree context. A worktree is the checkout and branch that the engineer is using. The same context can run on a local machine, in WSL, or on a remote host without changing the user-facing flow.
Worktree context
The source-control panel is scoped to one registered repository and one worktree. It uses that context for status, file changes, branch comparison, review links, and mutations. A folder without confirmed Git state does not expose source-control actions.
The system keeps repository identity, worktree identity, and execution-host identity with reads and writes. This prevents a same-path checkout or a workspace switch from receiving stale status or review data. It treats confirmed absence differently from a probe that could not answer.
References: src/…/use-worktree-context.ts• L19-143 src/…/status-read.ts• L40-67 src/…/hosted-review.ts• L49-100
Execution hosts
The worktree identifies the checkout. The repository owner identifies where Git must run. This separation lets the interface work when the checkout is local, in WSL, or on a remote host.
Read work avoids waking a stopped WSL host. An explicit user action can wake it when needed. Git execution uses bounded output, deadlines, admission limits, cancellation, and process cleanup so an incomplete or late process cannot change the next source-control decision. On Windows, process creation and tree cleanup can run away from the main loop. A write keeps its operation lifetime until the child process and its descendants have ended.
The command boundary also prevents unattended credential prompts and keeps parsed Git messages stable across locales. Network Git reads can apply the configured SSH policy without turning shell output into Git data. GitHub CLI work adds host-and-runtime-scoped rate-limit gates, safe retries for read-only calls, and a fallback between native and WSL execution when the CLI is missing.
References: src/…/git-exec-file.ts• L40-203 src/…/git-stream-stdout.ts• L41-50 src/…/git-stream-child-spawn.ts• L13-59 src/…/git-writer-lifetime.ts• L3-24 src/…/git-ssh-policy-env.ts• L19-77 src/…/gh-exec-file.ts• L99-123 src/…/gh-exec-file.ts• L243-299
Worktree lifecycle
Worktree actions create, prepare, move, and remove linked checkouts while preserving branch and base identity. Preparation first creates a hidden checkout with an ownership lock. This separates slow materialization from the final move and lets cleanup remove only a checkout that the current operation created.
Creation materializes a known base and checks that base again before finalization. The preparation has a time limit and can be handed to a later finalization step. If setup fails, expires, or loses its lock owner, the system waits for active Git work and retries cleanup only while ownership remains clear. Removal protects unmerged local commits and handles worktree records that one Git environment cannot read from another.
Worktree paths are compared by their path syntax and host rules. This keeps POSIX, Windows, and WSL aliases from merging distinct checkouts or creating duplicate operation lanes. A pending removal also blocks a new checkout that would reuse its path or branch until cleanup settles.
References: src/…/worktree-create-preparation.ts• L33-109 src/…/worktree-preparation-operation.ts• L17-321 src/…/worktree-preparation-lock-real-git.test.ts• L68-204 src/…/worktree-path-comparison.ts• L7-111 src/…/worktree-add-pending-removal.test.ts• L59-83 src/…/worktree-removal-real-git.test.ts• L73-148
Branch naming
First-work branch naming turns an eligible auto-generated branch into a readable local name after enough work context exists. It protects branches that already have an upstream and treats an uncertain upstream check as retryable, so a published branch is not stranded by an automatic rename.
The rename checks the branch again after name generation. It stops if the branch or publication state changed, chooses a free name when a collision exists, and updates the worktree display when that display still has an auto-generated value.
References: src/…/branch-rename.ts• L12-69 src/…/first-work-branch-rename.ts• L187-220 src/…/first-work-branch-rename.ts• L251-329
Branch switching
Branch switching is a guarded checkout action. It checks the live worktree before moving HEAD, then serializes concurrent switches so two clients cannot both act on the same old state.
The action refuses dirty, conflicted, detached, busy, or agent-owned worktrees. If Git moves the branch but cannot replace an open file or a hook reports an error, the UI reports a warning about the landed switch instead of claiming that the switch failed.
References: src/…/branch-switch.ts• L62-95 src/…/branch-switch.ts• L164-214 src/…/branch-switch.ts• L216-255 src/…/checkout-skipped-paths.ts• L1-7
Source-control surface
The source-control surface moves from change inspection to the next repository action. Its file area explains local work. Its action area explains whether the next step is staging, committing, publishing, syncing, or opening a review.
Change listing
The file area separates staged, unstaged, untracked, branch-level, and conflict work. It supports filtering and list or tree views. The same source tree supplies selection and bulk actions so the visible layout does not change the action scope.
Large repositories can return a capped status result. The panel marks that result as partial instead of treating visible rows as the whole worktree. A filter changes what the engineer sees. It does not silently narrow a bulk operation.
Submodule entries remain tied to the submodule repository. The panel loads inner status when the entry expands. The listing also links a changed path to the editor, file browser, diff viewer, and review-note context.
References: src/…/use-file-projection.ts• L75-158 src/…/use-file-projection.ts• L187-257 src/…/source-control-tree.ts• L110-184 src/…/panel-content.tsx• L91-223
Commit actions
The commit area turns staged work into a commit and then offers the next branch action. The primary action reflects current state. It can ask the engineer to stage, commit, publish, push, sync, or create a review.
The action model gives conflicts, active remote work, missing upstream, and review eligibility priority over a new commit or review. After a mutation, source control refreshes the state that the next decision depends on.
Discard treats tracked and untracked work differently. Tracked edits return to committed content. Untracked content is removed only through the discard safety path. Bulk actions use the full requested scope rather than the current filtered or capped list.
References: src/…/use-action-model.ts• L16-135 src/…/commit-area.tsx• L115-167 src/…/staging.ts• L23-191 src/…/discard-changes.ts• L17-58 src/…/discard-changes.ts• L91-149
Conflict state
Merge, rebase, cherry-pick, and revert are active Git operations with a recovery path. The panel shows unresolved paths and the matching abort or completion action. It also shows an operation banner when Git is paused between steps but no path is currently unresolved.
Resolved paths can be staged. Unresolved paths are excluded from bulk stage and discard because those actions could lose the resolution or recreate the conflict. Hosted conflict state remains separate from local file state because a provider can report a conflict before the local checkout can list it.
References: src/…/content-status.tsx• L65-99 src/…/panel-content.tsx• L93-131 src/…/staging.ts• L40-85
Git history
History explains commit order and branch context after status and comparison establish the current worktree state. It loads only when the history view is visible, keeps results per worktree, and drops a result that belongs to an older request or owner host.
Opening history or an explicit refresh is a user action that may wake a stopped WSL host. Background refresh does not wake that host. A branch or comparison-base change causes history to follow the new context.
References: src/…/use-git-history.ts• L15-49 src/…/use-git-history.ts• L75-137 src/…/use-git-history.ts• L156-187
Git state and change analysis
Source control answers two related questions: what is not committed in the worktree, and what committed work differs from a chosen base. Status answers the first question. Branch comparison, diffs, and history answer the second.
Working-tree state
Working-tree status reports the current branch and commit with file rows, upstream state, conflicts, and optional line totals. It can be partial when the repository has too many changes to read safely. The UI keeps partial, empty, unavailable, and clean results separate.
Status reads share identical work while a request is in flight. A mutation invalidates older reads. Line totals use the same worktree and execution host as the status read, and incomplete scans do not claim complete totals. Upstream state also distinguishes no upstream from an upstream probe that failed. When Git reports an ambiguous remote name, source control resolves the effective published branch before it shows ahead and behind counts.
Status refresh ordering gives a strict user refresh priority over an older automatic result. A later failed automatic refresh does not erase a valid result that is still settling.
References: src/…/status-read.ts• L40-67 src/…/status-read.ts• L114-177 src/…/status-upstream-ambiguous-ref-real-git.test.ts• L18-50 src/…/effective-upstream-status-probe.ts• L31-77 src/…/git-effective-upstream.ts• L112-183 src/…/git-effective-upstream.ts• L185-237
Branch comparison
Branch comparison shows committed files and commits ahead of a selected base ref. A base ref is the branch or ref used as the comparison or review target. The result includes the merge base and ahead or behind counts.
The result has a clear state for an invalid base, an unborn head, a missing merge base, an empty comparison, or an unavailable read. Base selection checks exact refs and remote-tracking refs without treating an uncertain probe as proof that a base is absent.
Base search is bounded and filters unsafe refs and direct remote-head entries before applying the result limit. It supports slash-separated queries and qualified names without hiding valid refs behind duplicate selectors. A branch snapshot can serve several searches while ref changes invalidate older generations.
References: src/…/branch-diff.ts• L9-71 src/…/status-branch-compare.test.ts• L83-181 src/…/hosted-review-creation-git-state.ts• L127-190 src/…/repo-ref-search-command.ts• L42-147 src/…/repo-legacy-ref-search.ts• L42-132 src/…/branch-ref-snapshot-data.ts• L101-145 src/…/branch-ref-snapshot-store.test.ts• L77-110
Diff and history
Diffs explain one file or a complete change set. They can compare working-tree content, staged content, committed content, or a branch against its merge base. History adds commit order and branch context, then lets the engineer inspect files changed by one commit.
Diff reads handle text, binary, large, renamed, and submodule content. A failed read is not treated as an empty file or a proven deletion. A configured text conversion can shape a read-only preview, while an editable restore view keeps the bytes that checkout would write.
Submodule paths use the submodule repository's state. A root path shows a pointer change. When the pointer moves, an inner path can show the committed range between the old and new submodule commits.
References: src/…/file-diff.ts• L32-224 src/…/git-blob-read.ts• L13-125 src/…/submodule-diff.ts• L13-89 src/…/textconv-driver.ts• L9-43 src/…/commit-diff.ts• L43-63
Git mutations
Source-control mutations change the selected worktree through one Git boundary. They include staging, unstaging, discard, commit, checkout, fetch, pull, rebase, publish, push, and worktree actions. The view refreshes after each action so the next decision uses current state.
Mutations preserve literal paths and carry repository-owner and worktree identity. Bulk commands use bounded input handling. A mutation remains active until its process ends, even if the caller already received cancellation or a timeout. Worktree and fetch operations also serialize access to shared Git state and can retry a narrow remote-reference race without replaying a pull.
Checkout and remote actions use non-interactive Git. Push honors the worktree's configured target, while pull and fetch resolve the effective upstream and preserve the conflict flow. Fetch repairs only a confirmed stale fork refspec before retrying; other fetch errors pass through.
For command routing, path rules, host ownership, and process lifetime, see Git operations and status. This page treats Git commands as product actions rather than command syntax.
References: src/…/git-exec-file.ts• L217-247 src/…/staging.ts• L119-191 src/…/remote.ts• L28-175 src/…/git-operation-lock.ts• L38-67 src/…/git-fetch-head-lock.ts• L166-175 src/…/git-fetch-ref-race.ts• L48-95 src/…/fork-remote-stale-branch-refspec.test.ts• L14-79
Hosted source links
Source-control links can take a file location or commit from a local remote and open the matching hosted page. The link builder understands common GitHub, GitLab, and Bitbucket URL forms, including SSH-style remotes, and encodes repository, branch, path, and line data before building the URL.
Remote discovery uses a bounded probe. A cached remote name list is trusted only while the local Git configuration stays unchanged, and a timeout or transport failure remains unknown instead of becoming proof that the remote is absent.
References: src/…/hosted-remote-url.ts• L19-89 src/…/hosted-remote-url.ts• L105-154 src/…/remote-name-listing.ts• L71-123 src/…/remote-url-probe.ts• L62-123
Worktree push targets
Worktree push targets connect a checkout to the remote branch that should receive its commits. A target may reuse a matching remote or create a dedicated fork remote, but it tracks only the needed branch range.
The system records creation ownership before it can remove a generated remote. It narrows legacy broad fetch settings and periodically reclaims generated remotes only when no live worktree or preserved branch still uses them. A missing branch ref can be repaired without removing unrelated remote settings. A stale branch refspec is removed only when the failed fetch names a ref that the target actually tracks.
References: src/…/worktree-push-target-setup.ts• L73-160 src/…/fork-remote-refspec.ts• L72-97 src/…/fork-remote-stale-branch-refspec.test.ts• L30-79 src/…/worktree-push-target-refspec-migration.ts• L84-137 src/…/worktree-push-target-reconciliation.ts• L74-91 src/…/fork-remote-stale-branch-refspec.ts• L1-100
Hosted review providers
A hosted review is a pull request or merge request stored by a code-hosting service. Source control detects the service from repository identity and remotes, finds the review for the selected branch, and maps provider data into one review model.
Provider model
The provider model hides service differences while preserving each service's review term and limits. Supported providers are GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea. An unsupported result remains possible when a remote cannot be matched or verified.
| Provider | Review term | Main review scope |
|---|---|---|
| GitHub | Pull request | Branch, checks, merge state, reviewers, comments, viewed files, and draft state |
| GitLab | Merge request | Branch, pipelines, reviewers, comments, discussions, and merge state |
| Bitbucket | Pull request | Branch, builds, and review state |
| Azure DevOps | Pull request | Branch, checks, and merge state |
| Gitea | Pull request | Branch, commit status, and merge state |
Provider identity depends on the remote host and matching authentication. Bitbucket credentials are checked against the service before they are saved. A rejected credential and an unreachable service remain different outcomes. A failed probe does not silently select another provider. Self-hosted GitHub and GitLab keep the verified host with the review request.
The provider boundary also keeps Git reads on the selected execution host while provider API or CLI work runs through its matching service connection. This prevents a local process from reading a remote checkout or using the wrong account.
References: src/…/forge-provider.ts• L48-126 src/…/forge-provider.ts• L132-207 src/…/forge-provider.ts• L209-316 src/…/hosted-review-creation-provider.ts• L22-139 src/…/task-repository-eligibility.ts• L14-63 src/…/remote-url-probe.ts• L125-138 src/…/user-request.ts• L12-64 src/…/credential-connection.ts• L41-105 src/…/github-enterprise-repository.ts• L129-192
Review discovery
Review discovery links the current branch to its hosted review by provider, branch identity, and any durable review number stored with the worktree. A durable link still works when branch names or fork ownership no longer give a unique match.
The lookup first resolves the repository identity. It then checks the linked review and branch candidates. Fork reviews require the head repository to match the tracked fork or the explicit link. GitHub lookup can also use tracked upstream information and the current head commit to avoid showing a stale merged review.
The lookup path first normalizes the branch and skips branch search for a detached HEAD unless an exact review link exists. It resolves the provider and GitHub account within the selected execution host, then uses the repository and account identity as part of the cache scope. If provider detection cannot decide, a remote reachability probe prevents a transient timeout or relay loss from becoming a cached “no review” result. A manual refresh also clears stale Gitea review reads before it asks the provider again. (src/…/hosted-review.ts• L49-149)
A failed or rate-limited lookup is unavailable, not proof that no review exists. Review reads are cached by repository, branch, provider host, execution host, and relevant head state. A successful review mutation invalidates the matching lookup. A short-lived, full lookup may also serve a matching phone read when the review is still open and its head commit is unchanged.
References: src/…/hosted-review.ts• L49-149 src/…/branch-lookup-resolution.ts• L35-65 src/…/branch-lookup-resolution.ts• L131-297 src/…/pr-for-branch-outcome.ts• L82-155 src/…/pr-last-outcome.ts• L21-69 src/…/repo-slug-upstream.ts• L45-153 src/…/remote-name-listing.ts• L71-123 src/…/remote-url-probe.ts• L94-123 src/…/pr-result-cache.ts• L162-280
Review state and actions
The shared review model carries open, draft, closed, or merged state. It can also carry checks, merge readiness, review decisions, conflicts, auto-merge, reviewers, comments, and target branch data. The UI uses this state to show the next provider action.
Depending on provider and review state, an engineer can merge, enable auto-merge, close or reopen a review, mark a draft ready, manage reviewers, refresh checks, mark files viewed, and resolve supported discussions. Actions with lasting effects stay bound to the resolved review repository.
Review data can also resolve linked GitHub or GitLab issues. When a workspace issue link has no title, a background read fills the title on the owning host and publishes only that workspace's metadata. It does not wake a stopped WSL host.
References: src/…/forge-provider.ts• L69-85 src/…/use-action-model.ts• L138-270 src/…/pull-request-execution.ts• L1-20 src/…/pull-request-linked-issue.ts• L17-80 src/…/github-issue-link-title-fill.ts• L41-166 src/…/github-issue-link-title-wiring.ts• L32-103
Review checks
Checks describe whether a review head is ready for merge. GitHub combines check runs, legacy commit statuses, and approval blockers. When a token cannot read check runs, Actions jobs and workflow runs provide the compatible check view. A provider response with no checks is different from a failed check read.
Check reads stay tied to the review repository and head commit. The interface supports refresh, rerun, and an optional AI action that starts a fix workspace for broken checks. Context and request identities prevent an older review or head from changing the current result.
Large check details load in bounded stages. The read can include annotations, workflow jobs, and failed-log tails. A host deadline or caller cancellation ends the request without presenting partial failure as a clean result.
Cached check status is used only when its head and time range match the review. A complete or trusted check observation takes priority over an older cache value.
References: src/…/get-pr-checks.ts• L32-269 src/…/get-pr-check-details.ts• L27-177 src/…/rest-pr-check-pages.ts• L41-93 src/…/rest-pr-check-pages.ts• L144-264 src/…/checks-tab-actions.ts• L48-219 src/…/github-checks-tab-state.ts• L28-135 src/…/pr-check-status-cache.ts• L13-95 src/…/pr-result-cache.ts• L162-280
Review workflows
Review work moves from current branch state to eligibility, preparation, creation, and follow-up. Each stage uses the selected worktree and execution host so a review does not describe stale files or target a different branch.
Review eligibility
Creation eligibility checks the branch, worktree, upstream, base, provider, authentication, and existing review. A detached branch or default branch is blocked. Uncommitted work must be committed first. A branch without an upstream must be published before creation.
The base must be usable on a remote because providers receive the submitted base as written. The result includes a blocker and a next action. The next action can be commit, publish, push, sync, authenticate, or open an existing review. A failed review lookup stays unavailable and cannot make creation look safe.
Provider authentication is checked on the execution host that owns the review. GitHub Enterprise host checks use verified authentication inventory rather than treating an unknown custom host as another provider. Repeated refresh validation denials use a short backoff so a stale or mismatched checkout does not create a request storm.
References: src/…/hosted-review-creation.ts• L46-101 src/…/hosted-review-creation.ts• L105-241 src/…/hosted-review-creation-git-state.ts• L114-195 src/…/hosted-review-creation-provider.ts• L117-139 src/…/exact-ref-probe.performance.test.ts• L65-92 src/…/github-enterprise-repository.ts• L183-264 src/…/pr-refresh-validation-backoff.ts• L75-103
Review preparation
The review composer prepares the base branch, title, description, and draft state. It starts from eligibility and keeps the selected branch as the review head. Templates and provider-specific labels can shape the prepared fields.
AI generation is optional. It proposes review fields from the repository and review context. The engineer can edit the result before creation. A later generated result does not replace fields that the engineer changed.
References: src/…/use-hosted-review-creation.ts• L78-149 src/…/use-create-pr-intent-review.ts• L69-169
Review creation
Creation submits prepared fields to the detected provider after a final eligibility gate. The gate rechecks the branch, worktree, user changes, upstream, base, provider, authentication, and existing review on the owning execution host.
Provider writes are not retried automatically. If the result says that a review already exists or completion is unknown, the system finds the review before offering another creation. If provider creation succeeds but later linking fails, the review is linked before the error is shown.
The creation flow is:
flowchart TD
A[Selected worktree] --> B[Read status and branch comparison]
B --> C[Detect provider and find existing review]
C --> D{Eligible?}
D -->|No| E[Show blocker and next action]
D -->|Yes| F[Prepare base title body and draft state]
F --> G[Create pull request or merge request]
G --> H{Provider result}
H -->|Created| I[Link review to worktree]
H -->|Already exists or unknown completion| I
I --> J[Refresh review and checks]
References: src/…/hosted-review-creation.ts• L252-294 src/…/use-hosted-review-creation.ts• L139-229 src/…/use-create-pr-intent-review.ts• L193-280
One-click review intent
The Create PR intent combines commit, push, and review creation in one guarded run. It reads status, upstream, branch comparison, and eligibility between steps instead of trusting an older panel render.
The run is pinned to the worktree, branch, and host that started it. If the engineer changes the target or the branch changes during generation, the run stops before it acts on the wrong checkout. It can generate review details and apply supported Jira title rules before creation.
References: src/…/use-create-pr-intent-review.ts• L69-93 src/…/use-create-pr-intent-review.ts• L111-280 src/…/use-action-model.ts• L207-270
Review inspection
Review inspection gives the engineer the context needed to act without leaving source control. It combines the review description, branch relation, changed files, diffs, checks, conflicts, reviewers, comments, and review decision.
Large details load in stages. Files and checks can load on demand. Results are bounded and late responses are dropped when the review repository, head commit, or request context changes. Manual refresh first checks the local branch identity so old review data does not survive a branch switch.
References: src/…/use-checks-panel-manual-refresh.tsx• L72-315 src/…/hosted-review-manual-refresh.ts• L66-123
Review refresh
GitHub review refresh keeps visible work current without making every checkout poll at once. It coalesces equivalent branch or review reads, gives selected and manual reads higher priority, and delays background work when the provider rate limit or the local budget is low.
The queue validates each candidate again before Git or GitHub work starts. It skips stale, detached, archived, disconnected, or stopped-WSL candidates. A failed read keeps its retry state and cached answer separate from a confirmed no-review result.
Every completed read reaches registered observers. A change event is published only when the review number, state, head, update time, or usable check status changes for a worktree. This lets several worktrees linked to one review share one provider read without sending duplicate UI events.
References: src/…/pr-refresh-coordinator.ts• L53-132 src/…/pr-refresh-coordinator.ts• L178-284 src/…/pr-refresh-candidate-policy.ts• L22-125 src/…/pr-refresh-queue-drainer.ts• L153-291 src/…/pr-refresh-event-publisher.ts• L21-85 src/…/pull-request-changed-events.ts• L16-63
Change checklist
When these files or sections are changed, remember to consider these:
- Keep repository detection, worktree identity, status, branch comparison, review lookup, and review creation scoped to the same repository, worktree, owner host, and execution host.
- Preserve the difference between confirmed absence, an empty result, and an unavailable or indeterminate probe for repositories, refs, remotes, providers, and reviews.
- Keep local Git routing aligned with linked-worktree ownership, WSL read and wake rules, host-path conversion, and process-group cleanup.
- Keep command deadlines, output limits, admission release, cancellation, worker loss, mutation lifetime, GitHub CLI rate-limit scope, and safe retry rules aligned across native, WSL, and remote execution.
- Keep capped status actions, literal path handling, staged-index authority, shared-link exclusion, conflict exclusion, submodule scope, and post-mutation refresh aligned.
- Keep branch switching checks, checkout locks, landed-switch warnings, skipped-path reporting, and branch identity aligned after a switch.
- Keep status, upstream state, base selection, branch comparison, primary-action decisions, and branch identity aligned after checkout, commit, fetch, pull, push, rebase, and worktree changes.
- Keep effective-upstream resolution aligned with ambiguous remote names, configured push targets, remote-tracking refs, cache generations, and status ahead or behind counts.
- Keep base-ref search identity, namespace qualification, remote-head filtering, query token rules, deduplication, bounded scans, and result limits aligned so a base picker does not return an ambiguous or hidden target.
- Keep branch snapshots and remote-name caches invalidated by ref or config changes, and do not retain a late read after its owner or generation is stale.
- Keep worktree preparation and removal ownership, target-commit checks, preparation expiry, branch preservation, foreign-link protection, cleanup settlement, path canonicalization, and cache invalidation aligned.
- Keep generated fork remotes bounded to needed branches and reclaimable only with creation provenance and no remaining worktree or branch owner.
- Keep stale fork-refspec repair limited to confirmed tracked refs and never turn unrelated fetch errors into configuration changes.
- Keep repository ref maintenance paused around fetch, pull, and other writers. Do not force-kill pack or index writers before their locks are released.
- Keep hosted source-link parsing aligned with remote aliases, provider path rules, branch encoding, line ranges, and commit URL shapes.
- Keep provider detection, self-hosted host identity, execution-host routing, provider authentication, and Bitbucket rejected-versus-unreachable results aligned.
- Keep review lookup branch normalization, detached-head exact-link behavior, provider account resolution, reachability probes, Gitea refresh invalidation, and cache identity aligned with the selected execution host.
- Keep review eligibility and final creation checks aligned with clean work, remote base validation, provider authentication, duplicate recovery, unknown completion, and fork head identity.
- Keep one-click review intent tokens tied to the starting worktree, branch, host, status, comparison, commit, push, Jira context, and generated fields.
- Keep review details and checks tied to repository identity, head commit, request order, lazy loading, cache freshness, permission fallbacks, and failure state.
- Keep GitHub refresh candidates, queue pacing, rate-limit gates, stopped-WSL rules, validation backoff, observer delivery, and changed-review event suppression aligned.
- Keep issue-link title fills tied to the owning worktree host and current metadata instance. Do not turn a background title read into a workspace-wide refresh.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A repository, remote, ref, provider, or review probe cannot answer | The UI can show confirmed absence for state that is only unavailable | Keep unknown and unavailable results separate from confirmed absence |
| A Git or GitHub CLI process times out, loses its worker, or exceeds an output limit while descendants still run | A later action can race a live process or use incomplete output | Bound output, stop the whole command tree, and hold admission or mutation state until termination is proven |
| Windows process creation or cleanup blocks the main loop | Git or review actions can freeze the UI or release capacity too early | Use worker-hosted process creation and await child or tree termination for writes |
| A background WSL or GitHub refresh sees a stopped distro | Polling can start a distro or report the wrong host failure | Gate background work and let only a user action wake the distro |
| A GitHub CLI API bucket is rate-limited | Repeated reads can spend the remaining quota and hide a valid cached review | Scope the breaker by host and runtime, pause queued work, and retry only safe reads |
| A capped or filtered status list drives Stage all | Hidden changes remain unstaged or the wrong scope changes | Resolve the full requested worktree scope and exclude only confirmed protected paths |
| A diff read fails or exceeds its limit | A failed read can look like an empty or deleted file | Return bounded or unavailable metadata and keep deletion proof explicit |
| A base search short name hides a slash-named local or collides with another ref namespace | The review or comparison can use the wrong base or omit a valid base | Preserve qualified refs when needed, filter invalid entries before the limit, and deduplicate selectors |
| A branch snapshot or remote-name read finishes after a ref or config change | A picker can show stale branches or use a remote that no longer exists | Scope cached data to repository identity and invalidate it by ref or config generation |
| A branch switch races another switch or a first-work rename | The check can apply to one branch while checkout moves another | Serialize the check-and-switch operation per worktree |
Checkout moves HEAD but an open file or hook prevents a clean result | The UI can claim that the switch failed even though the branch changed | Re-read the branch and report a landed-switch warning with skipped paths |
| Sparse or prepared worktree setup fails after creation | A partial checkout or new branch can remain behind | Verify ownership before cleanup and roll back only owned resources |
| A prepared checkout expires while a writer or finalization move still runs | Cleanup can race the writer or remove a checkout after ownership changed | Retire the operation, wait for physical settlement, and stop after ownership loss or bounded retries |
| A pending removal shares a path or branch with a new worktree request | Git can receive a conflicting add while cleanup still owns the checkout | Reject the add until the pending removal settles |
| Automatic branch renaming sees a published branch or an uncertain upstream result | A remote branch or linked review can be stranded | Stop for a confirmed upstream and retry when the probe cannot answer |
| A generated fork remote keeps a broad fetch refspec | Fetch imports unrelated branches or cleanup removes a remote still needed by a sibling | Narrow tracking by branch and require provenance plus live-owner checks before cleanup |
| A stale-refspec repair treats an authentication or unrelated fetch error as a missing branch | Remote configuration can be changed for the wrong failure | Repair only a ref named by Git that is present in the target refspec |
| A dirty or conflicted worktree starts review creation | The review omits work or hides an unresolved operation | Block creation until the work is committed and conflicts are resolved |
| The submitted base exists only locally | The provider can create a review against an invalid target or reject the request late | Verify the base on the executing host before creation |
| The branch or base changes during review creation | The provider can create a review for a different target | Recheck all creation inputs on the owning host |
| A provider write reaches the service but its response is lost | Retrying can create a duplicate review | Reconcile by finding the existing review instead of auto-retrying |
| Bitbucket credentials are rejected or the service is unreachable | The user can see the wrong authentication state or save unusable credentials | Verify credentials before saving and report rejection separately from reachability failure |
| A self-hosted GitHub host cannot be verified | The system can misclassify another forge or use an ambient account | Use authenticated host inventory and keep unresolved identity indeterminate |
| A detached branch has no exact review link | The system cannot safely infer a branch review | Return no linked review without performing branch lookup |
| Provider detection cannot decide during a transient remote failure | The system can cache “no review” and hide an existing review | Probe remote reachability before caching definitive absence |
| A manual Gitea refresh uses stale cached reads | The UI can show an old pull request after the user asks for current data | Forget the relevant Gitea reads before provider lookup |
| A fork review is matched only by local branch name | The UI can show the wrong review or miss the real one | Match head repository identity and tracked fork information |
| A check request uses an old review head or lacks permission for check runs | Checks describe an earlier revision or appear missing after a push | Bind reads to the current head and use the Actions fallback when permissions deny check runs |
| A one-click review run outlives a worktree switch | Commit, push, or review creation can target the new worktree | Pin each step to a run token and stop when its target is stale |
| A background refresh sees a transient error or validation mismatch | The queue can retry too often or overwrite a good cached answer | Use candidate validation, short denial backoff, paced retries, and publish errors without treating them as no review |
| A title-fill read completes after its workspace link was removed or changed | Metadata can gain a title on the wrong link or host | Recheck worktree instance and link identity before writing, then publish only the owning workspace |
Key files
| File | Why to read it |
|---|---|
| src/…/use-worktree-context.ts | Resolves the active worktree, repository owner, execution target, Git state, and review context. |
| src/…/panel-content.tsx | Connects status, file changes, conflicts, commit actions, branch comparison, and history. |
| src/…/source-control-tree.ts | Defines the shared file-tree model used by source-control views and selection. |
| src/…/git-exec-file.ts | Shows the boundary for host, WSL, admission, timeout, output, fallback, and child-process lifetime. |
| src/…/git-stream-stdout.ts | Shows bounded streaming reads and early parser-driven stop behavior. |
| src/…/gh-exec-file.ts | Shows GitHub CLI host routing, account binding, rate-limit gates, fallback, and safe retry rules. |
| src/…/spawned-command-tree-kill.ts | Shows how canceled or abandoned command trees are stopped without releasing write ownership too early. |
| src/…/git-writer-lifetime.ts | Shows how Windows write lifetimes remain active after caller cancellation. |
| src/…/status-read.ts | Turns Git status into bounded worktree state with upstream, conflict, line-total, and partial-result rules. |
| src/…/effective-upstream-status-probe.ts | Keeps upstream status aligned with the current branch and remote-tracking state. |
| src/…/staging.ts | Defines single-file, bulk, full-scope, and conflict-resolution staging. |
| src/…/branch-switch.ts | Defines safe local branch switching and the distinction between refusal and a landed warning. |
| src/…/discard-changes.ts | Defines tracked and untracked discard with path safety. |
| src/…/file-diff.ts | Joins working-tree, index, commit, binary, large-file, and submodule diff sources. |
| src/…/hosted-remote-url.ts | Defines hosted file and commit links from Git remotes. |
| src/…/remote-name-listing.ts | Defines bounded remote discovery and config-aware cache validity. |
| src/…/remote-url-probe.ts | Defines shared remote URL reads and the difference between missing and unavailable remotes. |
| src/…/repo-ref-search-command.ts | Defines bounded base-ref search and remote-head filtering. |
| src/…/repo-legacy-ref-search.ts | Defines search result parsing, namespace filtering, and deduplication. |
| src/…/branch-ref-snapshot-data.ts | Defines branch snapshot records and branch-name projection. |
| src/…/fork-remote-stale-branch-refspec.ts | Defines safe repair of stale fork remote tracking. |
| src/…/worktree-path-comparison.ts | Keeps worktree identity stable across POSIX, Windows, and WSL path forms. |
| src/…/worktree-create-preparation.ts | Defines guarded preparation, base verification, finalization, and cleanup boundaries. |
| src/…/worktree-preparation-operation.ts | Coordinates preparation lifetime, cancellation, ownership, writer settlement, and discard. |
| src/…/worktree-preparation-disposal.ts | Defines bounded cleanup retries and the terminal states for failed preparation. |
| src/…/worktree-removal.ts | Defines safe checkout removal and branch cleanup. |
| src/…/worktree-prune-guard.ts | Protects worktree records that foreign Git environments cannot read. |
| src/…/worktree-push-target-setup.ts | Defines bounded remote targets for worktrees and upstream restoration. |
| src/…/worktree-push-target-reconciliation.ts | Defines safe reclamation of orphaned generated remotes. |
| src/…/forge-provider.ts | Defines hosted-review provider detection, execution routing, and the provider-neutral boundary. |
| src/…/hosted-review.ts | Connects branch lookup, durable review links, provider state, execution identity, reachability checks, and caching. |
| src/…/hosted-review-creation.ts | Defines review creation eligibility, remote-base checks, and final checks. |
| src/…/hosted-review-creation-provider.ts | Defines provider authentication and provider-specific review terms. |
| src/…/user-request.ts | Distinguishes accepted, rejected, and unreachable Bitbucket credential checks. |
| src/…/github-enterprise-repository.ts | Resolves and verifies self-hosted GitHub identities without ambient host confusion. |
| src/…/branch-lookup-resolution.ts | Shows GitHub branch, fork, tracked-upstream, and current-head review resolution. |
| src/…/pr-for-branch-outcome.ts | Coordinates coalesced branch review reads and execution-scoped outcomes. |
| src/…/get-pr-check-details.ts | Shows bounded review check detail reads, permission fallback, cancellation, and deadlines. |
| src/…/rest-pr-check-pages.ts | Shows paged checks, statuses, suites, and the Actions fallback. |
| src/…/pr-refresh-coordinator.ts | Coordinates manual, visible, watch, and post-push review refreshes. |
| src/…/pr-refresh-queue-drainer.ts | Applies candidate validation, pacing, rate limits, WSL gates, retries, and event delivery. |
| src/…/pull-request-changed-events.ts | Suppresses unchanged review events while preserving meaningful state changes. |
| src/…/github-issue-link-title-fill.ts | Fills untitled workspace issue links on the correct host and worktree. |
| src/…/use-create-pr-intent-review.ts | Coordinates guarded one-click review preparation and creation. |
| src/…/use-hosted-review-creation.ts | Submits prepared review fields and reconciles existing or partially created reviews. |
| src/…/checks-tab-actions.ts | Coordinates refresh, rerun, and AI-assisted repair actions for review checks. |
| src/…/pr-refresh-event-publisher.ts | Publishes ordered refresh events and sends one read to all linked observers. |
| src/…/pr-refresh-validation-backoff.ts | Limits repeated refresh validation denials. |
| src/…/pr-last-outcome.ts | Defines safe short-lived reuse of a recent open-review lookup. |
| src/…/pr-result-cache.ts | Keeps hosted-review and check results aligned with request ownership and current review state. |