server-git-and-pull-requests.md

Server: git, worktrees, pull requests, merges, and sync

• src/pull-requests.ts: maps each workspace to its GitHub repository, reads the pull request list with one gh api graphql call per repository, and reads one pull request's details with one more. branchPullRequest asks one gh api graphql call, outside GitHub's search, for the newest open or merged pull request a branch heads, for src/session-facts.ts. mergedPullRequests asks one gh api graphql call for the newest pull request from each of a repository's branches, with one alias per branch, and keeps the merged ones with their merge time, for src/worktrees.ts. loadPullRequestTitle reads only a linked PR's title through a separate 30-second cache, without loading its details. src/github.ts's repoOf keeps each workspace's repository, or its lack of one, for ten minutes in a createCache from src/cache.ts, and runs at most eight git remote lookups at once through a limit gate from src/map-limit.ts. A row's conflicts is true when GraphQL's mergeable is CONFLICTING. The list leaves out a pull request whose own state says closed, which the open searches still return for up to a minute after a close, since GitHub's search index lags it. A row and the details read checks, conflicts, and unresolved from the same GraphQL fields, so readyToMerge in src/shared/moves.ts takes either; the details count unresolved from the threads they keep, so their counts and threads agree. The details also read the last 100 commits with the pull requests GitHub links each to, and keep a commit linked to none or to this one, since a branch that merged its trunk lists the trunk's commits too.
• src/git.ts: the git checkout of a directory, the worktree a directory is in (worktreeAt), the branch a worktree had checked out at a given time (headHistory, branchAt), and the worktree a new session's branch runs in. It also holds the git helpers that src/worktrees.ts shares: git, canonical, commonDir, worktreesOf, which parses git worktree list --porcelain -z, and holderOf, the worktree that has a branch checked out, which the pull request checkout and rebase use too.
• src/worktrees.ts: the worktree inventory and the checks before a checkout is removed; Worktrees.start and Worktrees.remove order starts against removals; removeCheckout removes the linked worktree a directory is in, or returns null for a main checkout or a directory outside git, waiting up to 15 seconds for a session that just ended to leave it: it polls only which live sessions occupy the checkout, then runs the full preview once. releaseBranch removes the linked worktree that has a branch checked out through removeCheckout without that wait, and answers a BranchRelease from src/shared/git.ts, for PUT /api/worktree/release. deleteMergedBranch deletes a local branch only while its commit is the one its pull request merged, or one that commit contains, and no worktree has it checked out, for the cleanup after a merge. inUse names the directories live sessions and the server run in, which keep an isolation sandbox, and beneath tells whether one holds another. The inventory and the snapshot of what uses the checkouts resolve each distinct directory once, and run those realpaths and the per-directory and per-repository git probes PROBE_PARALLEL (16) at a time. The inventory then reads every repository's checkouts from one queue, four at a time, with one git rev-parse for their identity, and previewAll previews several targets from one snapshot of what uses them, four at a time; src/map-limit.ts holds mapLimit, the ordered, bounded Promise.all they share, and limit, a gate that bounds tasks arriving one by one. A preview reports a path that git no longer lists as a worktree with the unregistered blocker, which Worktrees tells apart from other failures by its UnregisteredWorktree error class. The inventory marks each linked checkout's merged: git merge-base --is-ancestor against refs/remotes/origin/HEAD for each distinct commit, then one mergedPullRequests call per repository, through the WorktreesEnv seam that tests fake, for the branches the default branch lacks. A merged pull request counts only when the branch's last commit is no newer than the merge, read with one git log --no-walk call. previewAll(targets, true), for Remove merged, runs the same check and adds the unmerged blocker to each target it cannot show merged; removal needs no second check, since the confirmation pins the branch and commit.
• src/local-file.ts: finds a file that agent text names by absolute path, by the real path's extension and outside the sign-in and config directories in DENIED_DIRS: readTextFile reads a text file for GET /api/file, within the size and encoding that route allows, and findMediaFile an image or video for GET /api/media. src/worktrees-shared.ts holds the shapes the page and the routes share.
• src/changes.ts: the session changes dialog's reads for GET /api/changes and GET /api/changes/file, a session's checkout diff merged with its own changed files, the last scan of each place kept for three seconds so that reading a file does not list every change again, and each session transcript folded into its changed files once, by the lines it gained since; src/shared/changes.ts holds the shapes the page shares, parseFullDiff, which numbers the rows of a whole-file diff, and patchRows, which fills GitHub's patch out to the whole file.
• src/pull-request-files.ts: the Code tab's REST file and blob reads, optional commit scope, and paginated GraphQL viewed-state read. src/pull-request-order.ts orders the list: sources after the files they import, then tests in their sources' order, then generated files. src/pull-request-stack.ts reads the stack for GET /api/pull-request/stack. src/pull-request-edit.ts saves titles, descriptions, labels, review requests, states, branch updates, and conversation changes for PUT /api/pull-request, and viewed files for PUT /api/pull-request/viewed. It also lists picker choices for GET /api/pull-request/options and appends images with attachToPullRequest. src/pull-request-checkout.ts checks out a pull request for PUT /api/pull-request/checkout: with gh pr checkout in a checkout, or on its head branch in a worktree with a new session that the route's starter opens there. src/pull-request-rebase.ts rebases a pull request's branch onto its base for PUT /api/pull-request/rebase, in the worktree that has the branch or a temporary one, and force-pushes it with a lease through the repository's pre-push hook, one repository at a time. Both read the pull request's head and base branches through headOf in src/pull-request-head.ts, and refuse a workspace of another repository through assertWorkspaceOf there. src/pull-request-merge.ts holds GITHUB_MERGES, the merge and its steps, including merge or rebase branch updates, and the status reads. src/pull-requests.ts adds behindBy with one REST base-to-head comparison per detail read. src/pull-request-review.ts holds a review draft's side of GitHub: readReviewTarget, the head and the lines each file's diff shows, the viewer's login, the reviews and their comments a retry compares, and postReview, one POST of the review through ghRestPost in src/github.ts.
• src/github-media.ts: GET /api/github-media, authenticated reads of allowlisted GitHub images and videos with redirect validation, a streamed size cap, and a bounded private cache.
• src/server/merge-queue.ts: MergeQueue, every merge the dashboard makes, kept in merges.json and stepped only by the server that holds the owner lock, nextStep, which picks a merge's next step from where its pull request stands, and stackOrder, which orders a stack of one repository bottom first; src/shared/merge-queue.ts holds QueuedMerge, MergeQueueChange, MergeQueueAnswer, and queuedMergeOf, which the page shares; see Merges, and the cleanup after one.
• src/server/review-drafts.ts: ReviewDrafts, the Review session's save_review_draft host tool, bound to its pull request through join and the Reviewers it keeps, and the preview and post of a draft, which takes a matching review already on GitHub instead of posting twice; src/server/review-drafts-file.ts keeps the drafts and reviewers in review-drafts.json beside the access token; src/shared/review-drafts.ts holds ReviewDraft, ReviewFinding, ReviewDraftEdit, applyReviewDraft, reviewPayload, which builds the review from the accepted findings and the diff's lines, and postRefusal, which the page shares; see Review drafts.
• src/server/merge-cleanup.ts: MergeCleanup, which marks the live sessions linked to a pull request that merged while it watched, and ends each once it is idle and not held for a continue with every pull request merged or closed, with its worktree and its merged branch, trying a failed or refused end again at the next look.
• src/server/isolation-sweep.ts: IsolationSweep, which once a day, on the owner's minute tick, removes each of omp's isolation sandboxes whose omp exited and whose checkout is clean, unlocked, and unused; src/omp/isolation.ts supplies omp's directory, its owner marker and liveness check, and its teardown of a retained mount; see Isolation sandboxes.
• src/source-control.ts: Settings › Source control providers on the server: gh's and gt's sign-in, the automatic pull setting and the cleanup after a merge in source-control.json, and pullDefaultBranch; see HTTP API. src/shared/source-control.ts holds the shapes the page shares, the merge methods and their labels, applySourceControl, and startingMethod, which picks the method the merge button starts with.
• src/settings-sync.ts: Settings › Sync on the server: SettingsSync runs one sync at a time against SyncRepo, readLocal and applyLocal read and write this machine's side, planSync and mergeFile merge three ways, portableText, portablePath, and localPath carry home paths as ~, and sourceControlStore syncs SourceControl's settings through its store; see Settings sync. src/sync-repo.ts holds SyncRepo, the git commands on the bare repository under the data directory, run without prompts; src/shared/settings-sync.ts holds the registry, SYNC_ITEMS and NEVER_SYNCED, the shapes the page shares, and parseSyncSettings.
• src/server/self-update.ts: Update dashboard: SelfUpdate reads the build the server runs at startup, counts origin's new commits for the bell, and fast-forwards the checkout, installs when bun.lock changed, and has the server restart; fastForward refuses rather than stash, reset, or merge; see Updating the dashboard. src/shared/dashboard-update.ts holds what GET and PUT /api/dashboard/update answer.