@bevel-software/platform-core-backend 0.28.1 → 0.30.0

package/src/modules/workflow/git/__tests__/git.service.worktrees.test.ts

@@ -0,0 +1,284 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { NodeFs } from '../../../kb-fs/node-fs.js';
+import { WorkspaceMutex } from '../../../kb-fs/mutex.js';
+import { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { KbRepository, repositoryDirFor } from '../../../workspace/kb-repository.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+import { NodeGitRunner } from '../node-git-runner.js';
+import { workspaceIdForBranch } from '../../../../shared/workspace-id.js';
+import { newWorkspaceService } from '../../../../__tests__/workspace-service.js';
+
+/**
+ * The git layer over a knowledge base of WORKTREES of one repository: the
+ * same answers as over clones of the same remote, two worktrees committing at
+ * once, and a branch deleted while its own worktree is open. Real git.
+ */
+
+const execFileAsync = promisify(execFile);
+const TARGET = 'current-company-state';
+const ALICE: AuthUser = { id: 'u-alice', email: 'alice@example.com', name: 'Alice' };
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+  return stdout.toString();
+}
+
+let root: string;
+let upstream: string;
+let workspacesRoot: string;
+let workspaces: WorkspaceService;
+let gitService: GitService;
+
+beforeEach(async () => {
+  root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-worktrees-'));
+  workspacesRoot = path.join(root, 'workspaces');
+  await fs.mkdir(workspacesRoot, { recursive: true });
+  upstream = path.join(root, 'upstream.git');
+  await git(root, ['init', '--bare', '-b', TARGET, upstream]);
+  const seed = path.join(root, '.seed');
+  await fs.mkdir(seed);
+  await git(seed, ['init', '-b', TARGET]);
+  await fs.writeFile(path.join(seed, 'base.md'), 'base\n');
+  await git(seed, ['add', '-A']);
+  await git(seed, ['commit', '-m', 'init']);
+  for (const draft of ['alice/a', 'bob/b']) {
+    await git(seed, ['checkout', '-q', '-b', draft, TARGET]);
+    await fs.writeFile(path.join(seed, `${draft.split('/')[0]}.md`), `${draft}\n`);
+    await git(seed, ['add', '-A']);
+    await git(seed, ['commit', '-m', `on ${draft}`]);
+  }
+  await git(seed, ['push', '-q', upstream, TARGET, 'alice/a', 'bob/b']);
+
+  const mutex = new WorkspaceMutex();
+  const runner = new NodeGitRunner();
+  const repository = new KbRepository({
+    dir: repositoryDirFor(workspacesRoot, 'knowledge-base'),
+    kbRepoUrl: () => upstream,
+    gitRunner: runner,
+  });
+  workspaces = newWorkspaceService(
+    workspacesRoot, upstream, testKbContext(), new NodeFs(), runner, undefined, undefined, repository,
+  );
+  gitService = new GitService(workspaces, new WorkflowHooks(), testKbContext(), mutex, null, runner);
+});
+
+afterEach(async () => {
+  await fs.rm(root, { recursive: true, force: true });
+});
+
+const id = (branch: string) => workspaceIdForBranch(branch);
+const checkoutOf = (branch: string) => path.join(workspacesRoot, id(branch), 'knowledge-base');
+
+describe('GitService over worktrees', () => {
+  it('lands two commits requested at the same time in two worktrees, and pushes both', async () => {
+    await workspaces.getOrCreateForBranch('alice/a');
+    await workspaces.getOrCreateForBranch('bob/b');
+    await fs.writeFile(path.join(checkoutOf('alice/a'), 'alice.md'), 'alice edits\n');
+    await fs.writeFile(path.join(checkoutOf('bob/b'), 'bob.md'), 'bob edits\n');
+
+    const [a, b] = await Promise.all([
+      gitService.commitFile(id('alice/a'), ALICE, 'knowledge-base/alice.md', 'alice edits'),
+      gitService.commitFile(id('bob/b'), ALICE, 'knowledge-base/bob.md', 'bob edits'),
+    ]);
+    expect(a).not.toBeNull();
+    expect(b).not.toBeNull();
+    await Promise.all([gitService.push(id('alice/a'), ALICE), gitService.push(id('bob/b'), ALICE)]);
+
+    expect(await git(upstream, ['show', 'alice/a:alice.md'])).toBe('alice edits\n');
+    expect(await git(upstream, ['show', 'bob/b:bob.md'])).toBe('bob edits\n');
+    // Each push left its branch tracking its own remote branch.
+    expect((await git(checkoutOf('alice/a'), ['rev-parse', '--abbrev-ref', '@{upstream}'])).trim()).toBe('origin/alice/a');
+    expect((await git(checkoutOf('bob/b'), ['status', '--porcelain'])).trim()).toBe('');
+  });
+
+  it("answers a change request's files and merges it exactly as a clone of the same remote does", async () => {
+    await workspaces.getOrCreateForBranch(TARGET);
+    await workspaces.getOrCreateForBranch('alice/a');
+    const onWorktrees = await gitService.changedFilesForPr(id(TARGET), TARGET, 'alice/a');
+
+    // The same question asked of a full clone of the same remote.
+    const cloneRoot = path.join(root, 'clones');
+    const clone = path.join(cloneRoot, id(TARGET), 'knowledge-base');
+    await fs.mkdir(path.dirname(clone), { recursive: true });
+    await git(root, ['clone', '-q', '-b', TARGET, upstream, clone]);
+    const clones = newWorkspaceService(cloneRoot, upstream, testKbContext(), new NodeFs());
+    const onClones = await new GitService(clones, new WorkflowHooks(), testKbContext()).changedFilesForPr(
+      id(TARGET), TARGET, 'alice/a',
+    );
+    expect(onWorktrees).toEqual(onClones);
+
+    await gitService.mergeChangeRequest(
+      id(TARGET), 'alice/a', TARGET, { subject: 'Merge alice/a (#1)', body: '' }, ALICE,
+    );
+    expect(await git(upstream, ['show', `${TARGET}:alice.md`])).toBe('alice/a\n');
+  });
+
+  it('deletes a branch whose own worktree is open, and removing that workspace takes the worktree and its ref', async () => {
+    await workspaces.getOrCreateForBranch(TARGET);
+    await workspaces.getOrCreateForBranch('alice/a');
+
+    await gitService.deleteBranch(id(TARGET), 'alice/a', ALICE, { systemCleanup: true });
+    await workspaces.deleteWorkspace(id('alice/a'));
+
+    await expect(git(upstream, ['rev-parse', '--verify', 'refs/heads/alice/a'])).rejects.toThrow();
+    await expect(git(workspaces.repository.dir, ['rev-parse', '--verify', 'refs/heads/alice/a'])).rejects.toThrow();
+    await expect(fs.access(checkoutOf('alice/a'))).rejects.toThrow();
+    expect((await git(checkoutOf(TARGET), ['status', '--porcelain'])).trim()).toBe('');
+  });
+
+  it("finishes a branch's first open raced by git operations on that branch, and a fetch joined from inside one", async () => {
+    // The first request for a branch fans out: the page opens the workspace
+    // while the git layer asks for its status — inside the branch's
+    // reservation, resolving the same workspace — and a listing fetches.
+    // The worktree add waits for running git operations, and they wait for
+    // the open: nothing may wait for itself.
+    await workspaces.getOrCreateForBranch(TARGET);
+    const all = Promise.all([
+      workspaces.getOrCreateForBranch('bob/b'),
+      gitService.status(id('bob/b')),
+      gitService.listBranches(id(TARGET), { freshFetch: true }),
+      gitService.status(id('bob/b')),
+    ]);
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    try {
+      await Promise.race([
+        all,
+        new Promise((_, reject) => {
+          timeout = setTimeout(() => reject(new Error('deadlocked')), 20_000);
+        }),
+      ]);
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+    expect((await git(checkoutOf('bob/b'), ['rev-parse', '--abbrev-ref', 'HEAD'])).trim()).toBe('bob/b');
+  });
+
+  it('lists branches from one fetch of the repository, strictly', async () => {
+    await workspaces.getOrCreateForBranch(TARGET);
+    const branches = await gitService.listBranches(id(TARGET), { freshFetch: true, strictFetch: true });
+    expect(branches.map((b) => b.name).sort()).toEqual(['alice/a', 'bob/b', TARGET].sort());
+    expect(gitService.lastRemoteContact()?.ok).toBe(true);
+  });
+
+  it("does not list another worktree's local branch once origin no longer has it, so the orphan sweep can take it", async () => {
+    await workspaces.getOrCreateForBranch(TARGET);
+    await workspaces.getOrCreateForBranch('bob/b');
+    // Deleted on the host while its worktree stays open: the repository
+    // still holds bob/b's local ref, as bob's clone held it.
+    await git(upstream, ['branch', '-D', 'bob/b']);
+
+    const fromTarget = await gitService.listBranches(id(TARGET), { freshFetch: true, strictFetch: true });
+    expect(fromTarget.map((b) => b.name).sort()).toEqual(['alice/a', TARGET].sort());
+    // A clone never saw another branch's local ref either: listed from its
+    // own worktree, a branch is its own.
+    const fromBob = await gitService.listBranches(id('bob/b'), { freshFetch: true });
+    expect(fromBob.find((b) => b.name === 'bob/b')?.hasRemote).toBe(false);
+
+    const { removed } = await workspaces.sweepOrphanedWorkspaces(fromTarget.map((b) => b.name));
+    expect(removed).toEqual([id('bob/b')]);
+    await expect(git(workspaces.repository.dir, ['rev-parse', '--verify', 'refs/heads/bob/b'])).rejects.toThrow();
+  });
+});
+
+describe('GitService and the repository administrator', () => {
+  /** The repository, noting whether its administrator's section is held while git runs. */
+  class RecordingRepository extends KbRepository {
+    depth = 0;
+    override exclusive<T>(fn: () => Promise<T>): Promise<T> {
+      return super.exclusive(async () => {
+        this.depth += 1;
+        try { return await fn(); } finally { this.depth -= 1; }
+      });
+    }
+  }
+
+  it('writes the shared config as the administrator, and runs everything else as itself', async () => {
+    const mutex = new WorkspaceMutex();
+    const runner = new NodeGitRunner();
+    const repository = new RecordingRepository({
+      dir: repositoryDirFor(workspacesRoot, 'knowledge-base'),
+      kbRepoUrl: () => upstream,
+      gitRunner: runner,
+    });
+    const recorded = newWorkspaceService(
+      workspacesRoot, upstream, testKbContext(), new NodeFs(), runner, undefined, undefined, repository,
+    );
+    const calls: { args: string[]; held: boolean }[] = [];
+    const recordingRunner = {
+      defaultTimeoutMs: runner.defaultTimeoutMs,
+      credentials: runner.credentials,
+      run: ((cwd: string, args: string[], opts?: never) => {
+        calls.push({ args, held: repository.depth > 0 });
+        return runner.run(cwd, args, opts);
+      }) as NodeGitRunner['run'],
+    };
+    const service = new GitService(recorded, new WorkflowHooks(), testKbContext(), mutex, null, recordingRunner);
+    await recorded.getOrCreateForBranch(TARGET);
+    await recorded.getOrCreateForBranch('alice/a');
+
+    await service.fetch(id(TARGET));
+    await service.changedFilesForPr(id(TARGET), TARGET, 'alice/a');
+    await fs.writeFile(path.join(checkoutOf('alice/a'), 'alice.md'), 'alice edits\n');
+    await service.commitFile(id('alice/a'), ALICE, 'knowledge-base/alice.md', 'alice edits');
+    await service.push(id('alice/a'), ALICE);
+    await service.status(id('alice/a'));
+    // A merge stamps the committer's name and email into the config.
+    const merged = await service.mergeChangeRequest(
+      id(TARGET), 'alice/a', TARGET, { subject: 'alice edits (#1)', body: '' }, ALICE,
+    );
+    expect(merged.kind).toBe('merged');
+    await service.deleteBranch(id(TARGET), 'alice/a', ALICE, { systemCleanup: true });
+
+    // The subcommand, past leading `-c key=value` / `-C dir` options.
+    const sub = (args: string[]) => {
+      let i = 0;
+      while (args[i] === '-c' || args[i] === '-C') i += 2;
+      return { name: args[i], rest: args.slice(i + 1) };
+    };
+    const of = (pred: (s: { name: string; rest: string[] }) => boolean) => calls.filter((c) => pred(sub(c.args)));
+
+    // The config is the one file git refuses a second writer of: every write
+    // to it (the upstream stamp, the committer's name and email, a branch
+    // delete that drops the branch's section) is the administrator's. The
+    // refs, packed-refs and the objects git locks itself, so a fetch, a
+    // commit, a push, a merge and a read run as any worktree's git would.
+    const configRead = (rest: string[]) => rest.some((a) => /^(--get|--get-all|--get-regexp|--list|-l)$/.test(a));
+    const shared = [
+      ...of((s) => s.name === 'config' && !configRead(s.rest)),
+      ...of((s) => s.name === 'branch' && s.rest.some((a) => a === '-D' || a === '-d')),
+    ];
+    const own = [
+      ...of((s) => s.name === 'fetch'),
+      ...of((s) => s.name === 'commit'),
+      ...of((s) => s.name === 'merge'),
+      ...of((s) => s.name === 'push' && !s.rest.includes('-u')),
+      ...of((s) => s.name === 'status'),
+      ...of((s) => s.name === 'config' && configRead(s.rest)),
+    ];
+    for (const name of ['fetch', 'config', 'commit', 'merge', 'push', 'status']) {
+      expect(calls.some((c) => sub(c.args).name === name), name).toBe(true);
+    }
+    expect(of((s) => s.name === 'config' && s.rest.includes('--replace-all')).length).toBeGreaterThan(0);
+    expect(of((s) => s.name === 'config' && s.rest[0] === 'user.name').length).toBeGreaterThan(0);
+    expect(of((s) => s.name === 'config' && s.rest[0] === 'user.email').length).toBeGreaterThan(0);
+    expect(of((s) => s.name === 'branch' && s.rest.some((a) => a === '-D' || a === '-d')).length).toBeGreaterThan(0);
+    expect(shared.length).toBeGreaterThan(3);
+    for (const c of shared) expect(c.held, c.args.join(' ')).toBe(true);
+    for (const c of own) expect(c.held, c.args.join(' ')).toBe(false);
+  });
+});

package/src/modules/workflow/git/git.service.ts

@@ -25,6 +25,7 @@ import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { isAbsence } from '../../../shared/fs.contract.js';
 import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
+import { readRefSha } from '../../kb-fs/index.js';
 import {
   assertValidBranchName,
   assertValidRelativePath,
@@ -294,6 +295,25 @@ export class GitService implements IGitService {
   // counts, calm under large branch lists.
   private static readonly MAX_AHEAD_BEHIND_CONCURRENCY = 8;
 
+  /**
+   * A change request's changed entries, keyed by the two commits its diff
+   * was read between. Two commits never change, and neither does the
+   * merge-base between them, so the three-dot diff of a pair is a fact: a
+   * push moves a tip, the pair changes, the old entry is simply never asked
+   * for again. No TTL, no invalidation.
+   *
+   * This is what a change-request listing was paying git for on every read:
+   * one `diff` per open request, polled every minute and refetched on every
+   * event, where nothing had moved. Now git is asked once per pair, which is
+   * once per push. Keyed by commits alone, not by workspace: every clone of
+   * the knowledge base holds the same objects, so the answer is the same in
+   * all of them. Bounded FIFO; the bound only caps memory.
+   */
+  private readonly changedEntriesByCommits = new Map<string, NameStatusEntry[]>();
+  /** Diffs being read right now, so concurrent misses on one pair share one `git diff`. */
+  private readonly changedEntriesInFlight = new Map<string, Promise<NameStatusEntry[]>>();
+  private static readonly CHANGED_ENTRIES_MAX = 4096;
+
   constructor(
     private readonly workspaceService: WorkspaceService,
     /**
@@ -378,7 +398,9 @@ export class GitService implements IGitService {
    * above rather than kept separately, so it cannot disagree with it.
    */
   lastRemoteContact(): { at: number; ok: boolean } | null {
-    let latest: { at: number; ok: boolean } | null = null;
+    // The repository's fetches are every worktree's; the per-workspace record
+    // is a full clone's.
+    let latest: { at: number; ok: boolean } | null = this.workspaceService.repository?.lastContact() ?? null;
     for (const [workspaceId, at] of this.lastImplicitFetchAt) {
       if (latest === null || at > latest.at) {
         latest = { at, ok: this.lastImplicitFetchOk.get(workspaceId) ?? false };
@@ -495,12 +517,27 @@ export class GitService implements IGitService {
       // Union local heads with origin's remote-tracking refs: a fresh per-user
       // clone only has one local head (HEAD's default), so without this we'd hide
       // target-company-state and every draft pushed by another user.
+      //
+      // The workspace is a worktree of the one repository, which holds every
+      // OTHER worktree's local branch too. Those are not this workspace's: a
+      // clone never had them. A local head checked out in another worktree
+      // is read as that branch's remote-tracking ref alone (and not at all
+      // once origin no longer has it), so a branch deleted on origin is not
+      // kept alive by its own worktree's local ref — the orphan sweep reads
+      // this list. A branch is checked out in at most one worktree, so "not
+      // this one's HEAD" is "another's".
       const { stdout } = await this.git(cwd, [
         'for-each-ref',
-        '--format=%(refname:short)%09%(refname)',
+        '--format=%(refname:short)%09%(refname)%09%(worktreepath)',
         'refs/heads',
         'refs/remotes/origin',
       ]);
+      const ownBranch = (
+        await this.git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']).then(
+          (r) => r.stdout,
+          () => '',
+        )
+      ).trim();
 
       type Row = { shortName: string; ref: string; hasLocal: boolean; hasRemote: boolean };
       const buckets = new Map<string, Row>();
@@ -510,7 +547,7 @@ export class GitService implements IGitService {
         const tab = trimmed.indexOf('\t');
         if (tab < 0) continue;
         const rawShort = trimmed.slice(0, tab);
-        const ref = trimmed.slice(tab + 1);
+        const [ref = '', worktreePath = ''] = trimmed.slice(tab + 1).split('\t');
         if (!rawShort || !ref) continue;
         // Skip symbolic refs up-front. Different git versions report
         // `refs/remotes/origin/HEAD` as either `origin` (older) or `origin/HEAD`
@@ -521,6 +558,7 @@ export class GitService implements IGitService {
         const isLocal = ref.startsWith('refs/heads/');
         const shortName = isLocal ? rawShort : rawShort.replace(/^origin\//, '');
         if (!shortName) continue;
+        if (isLocal && worktreePath !== '' && shortName !== ownBranch) continue;
         // Final guard: the strip above turns `origin/HEAD` into `HEAD`. Even
         // if a future git version lands us here, don't bucket it as a branch.
         if (shortName === 'HEAD') continue;
@@ -614,6 +652,20 @@ export class GitService implements IGitService {
     workspaceId: string,
     force = false,
   ): Promise<boolean> {
+    // A worktree's remote-tracking refs are the repository's: ONE fetch for
+    // every workspace, throttled, joined and reserved there. The per-workspace
+    // record below is for a full clone from an earlier release, which fetches
+    // on its own until the boot phase converts it.
+    const repository = (await this.workspaceService.repositoryOfCheckout?.(cwd)) ?? null;
+    if (repository) {
+      return repository.fetch({
+        maxAgeMs: GitService.IMPLICIT_FETCH_TTL_MS,
+        // A host that is down is not asked again by every poll inside the
+        // window, as the per-workspace record below stamps a failure too.
+        failureBackoffMs: GitService.IMPLICIT_FETCH_TTL_MS,
+        force,
+      });
+    }
     const last = this.lastImplicitFetchAt.get(workspaceId) ?? 0;
     if (!force && Date.now() - last < GitService.IMPLICIT_FETCH_TTL_MS) {
       return this.lastImplicitFetchOk.get(workspaceId) ?? true;
@@ -692,8 +744,9 @@ export class GitService implements IGitService {
       // navigation to the new draft's URL fails with
       // "Remote branch <name> not found in upstream origin". Roll the local
       // ref back on failure so a retry isn't blocked by "branch already exists".
+      // No `-u`: the local head is dropped right below, and its upstream with it.
       try {
-        await this.git(cwd, ['push', '-u', 'origin', name]);
+        await this.git(cwd, ['push', 'origin', name]);
       } catch (err) {
         await this.git(cwd, ['branch', '-D', name]).catch(() => undefined);
         throw err;
@@ -829,7 +882,14 @@ export class GitService implements IGitService {
       let localTip: string | null = null;
       if (await this.refExists(cwd, `refs/heads/${name}`)) {
         localTip = await this.revParseOrNull(cwd, `refs/heads/${name}`);
-        await this.git(cwd, ['branch', '-D', name]);
+        await this.git(cwd, ['branch', '-D', name]).catch((err: unknown) => {
+          // In a repository of worktrees the branch's local ref is shared, and
+          // git keeps it while the branch's own workspace has it checked out.
+          // Removing that workspace — which the caller does next — takes the
+          // worktree and the ref with it.
+          if (/checked out at|used by worktree/i.test(err instanceof Error ? err.message : String(err))) return;
+          throw err;
+        });
       }
       return { lastCommit: remoteTip ?? localTip };
     });
@@ -1409,7 +1469,14 @@ export class GitService implements IGitService {
         );
       }
 
-      await this.git(cwd, ['push', '-u', 'origin', branch]);
+      // No `-u`: it writes the upstream into the config during the push, and
+      // a worktree's config is the repository's, shared by every workspace —
+      // git refuses a second writer of it rather than waiting. The upstream is
+      // stamped after the push instead, as one short write made as the
+      // repository's administrator (see `git`).
+      await this.git(cwd, ['push', 'origin', branch]);
+      await this.git(cwd, ['config', '--replace-all', `branch.${branch}.remote`, 'origin']);
+      await this.git(cwd, ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`]);
     }
   }
 
@@ -3166,9 +3233,8 @@ export class GitService implements IGitService {
       await this.fetchPrRefs(cwd, baseBranch, headBranch);
     }
     return this.mutex.run(workspaceId, async () => {
-      const baseRef = pinned ? pinned.base : await this.resolvePublishedBranchRef(cwd, baseBranch);
-      const headRef = pinned ? pinned.head : await this.resolvePublishedBranchRef(cwd, headBranch);
-      return this.prChangedPathsAt(cwd, baseRef, headRef, opts);
+      const at = pinned ?? (await this.publishedPrEnds(cwd, baseBranch, headBranch));
+      return flattenChangedPaths(await this.prChangedEntriesBetweenCommits(cwd, at.base, at.head), opts);
     });
   }
 
@@ -3243,13 +3309,51 @@ export class GitService implements IGitService {
       await this.fetchPrRefs(cwd, baseBranch, headBranch);
     }
     return this.mutex.run(workspaceId, async () => {
-      const baseRef = pinned ? pinned.base : await this.resolvePublishedBranchRef(cwd, baseBranch);
-      const headRef = pinned ? pinned.head : await this.resolvePublishedBranchRef(cwd, headBranch);
-      const entries = await this.prChangedEntriesAt(cwd, baseRef, headRef);
+      const at = pinned ?? (await this.publishedPrEnds(cwd, baseBranch, headBranch));
+      const entries = await this.prChangedEntriesBetweenCommits(cwd, at.base, at.head);
       return { paths: flattenChangedPaths(entries, {}), pairs: changedPathPairs(entries) };
     });
   }
 
+  /**
+   * {@link prChangedEntriesAt} for a pair of COMMITS, read once per pair
+   * (see `changedEntriesByCommits`). The caller holds the reservation, as for
+   * `prChangedEntriesAt`; a memo hit holds it for nothing, which is cheaper
+   * than a second code path around the lock.
+   */
+  private async prChangedEntriesBetweenCommits(
+    cwd: string,
+    baseSha: string,
+    headSha: string,
+  ): Promise<NameStatusEntry[]> {
+    const key = `${baseSha}\0${headSha}`;
+    const known = this.changedEntriesByCommits.get(key);
+    if (known) return known;
+    let pending = this.changedEntriesInFlight.get(key);
+    if (!pending) {
+      pending = this.prChangedEntriesAt(cwd, baseSha, headSha)
+        .then((entries) => {
+          if (this.changedEntriesByCommits.size >= GitService.CHANGED_ENTRIES_MAX) {
+            const oldest = this.changedEntriesByCommits.keys().next().value;
+            if (oldest !== undefined) this.changedEntriesByCommits.delete(oldest);
+          }
+          this.changedEntriesByCommits.set(key, entries);
+          return entries;
+        })
+        .finally(() => {
+          if (this.changedEntriesInFlight.get(key) === pending) this.changedEntriesInFlight.delete(key);
+        });
+      // Same bound as the memo: evicting an in-flight entry costs at most one
+      // redundant diff for that pair, never a lost answer.
+      if (this.changedEntriesInFlight.size >= GitService.CHANGED_ENTRIES_MAX) {
+        const oldest = this.changedEntriesInFlight.keys().next().value;
+        if (oldest !== undefined) this.changedEntriesInFlight.delete(oldest);
+      }
+      this.changedEntriesInFlight.set(key, pending);
+    }
+    return pending;
+  }
+
   /**
    * The merge-base commit of a change request's two branches (their origin
    * refs), or null when they share no history. This is the "before" the CR's
@@ -3590,16 +3694,23 @@ export class GitService implements IGitService {
     baseBranch: string,
     headBranch: string,
   ): Promise<{ base: string; head: string } | null> {
-    const shas: string[] = [];
-    for (const branch of [baseBranch, headBranch]) {
-      try {
-        shas.push((await this.resolvePublishedBranch(cwd, branch)).sha);
-      } catch (err) {
-        if (err instanceof WorkflowValidationError) return null;
-        throw err;
-      }
+    try {
+      return await this.publishedPrEnds(cwd, baseBranch, headBranch);
+    } catch (err) {
+      if (err instanceof WorkflowValidationError) return null;
+      throw err;
     }
-    return { base: shas[0], head: shas[1] };
+  }
+
+  /** The two commits a change request is read between, each resolved as {@link resolvePublishedBranch} does. */
+  private async publishedPrEnds(
+    cwd: string,
+    baseBranch: string,
+    headBranch: string,
+  ): Promise<{ base: string; head: string }> {
+    const base = (await this.resolvePublishedBranch(cwd, baseBranch)).sha;
+    const head = (await this.resolvePublishedBranch(cwd, headBranch)).sha;
+    return { base, head };
   }
 
   /**
@@ -3625,6 +3736,13 @@ export class GitService implements IGitService {
     branch: string,
   ): Promise<{ ref: string; sha: string }> {
     for (const ref of [`refs/remotes/origin/${branch}`, `refs/heads/${branch}`]) {
+      // The ref file first (`readRefSha`): no process, same answer, same
+      // freshness. Git is asked only for what the files cannot decide — a
+      // missing ref is decided by the files and the loop moves on; an
+      // unreadable one is git's to answer, as the authority.
+      const fromFiles = await readRefSha(cwd, ref);
+      if (fromFiles === 'missing') continue;
+      if (fromFiles !== 'unreadable') return { ref, sha: fromFiles.sha };
       try {
         const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', ref]);
         return { ref, sha: stdout.trim() };
@@ -4017,6 +4135,29 @@ export class GitService implements IGitService {
     return stdout.split('\0').filter((line) => line.length > 0);
   }
 
+  /**
+   * The commit `ref` names right now, or null when it names none (an unborn
+   * `HEAD`, a ref that does not exist). A caller that reads several things
+   * "at HEAD" pins the commit once with this and asks each read at that
+   * commit, so a commit landing between the reads cannot hand it one
+   * snapshot's files with another's rules.
+   *
+   * Null is ONLY "names no commit": `rev-parse --verify --quiet` says that
+   * with exit status 1 and nothing on stderr. Any other failure — no
+   * repository there, git itself failing, a deadline — is thrown, so a
+   * caller cannot read a broken clone as an empty one.
+   */
+  async commitAtRef(workspaceId: string, ref: string): Promise<string | null> {
+    const cwd = await this.repoDir(workspaceId);
+    try {
+      const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+      return stdout.trim() || null;
+    } catch (err) {
+      if (err instanceof GitRunError && !err.timedOut && err.exitCode === 1 && !(err.stderr ?? '').trim()) return null;
+      throw err;
+    }
+  }
+
   /**
    * A clean `git status` for a path has two honest readings (already
    * committed; a queued re-apply of something that landed) and one dishonest
@@ -4074,7 +4215,7 @@ export class GitService implements IGitService {
    * from a real failure are unaffected.
    */
   private git(cwd: string, args: string[], opts?: Omit<GitRunOptions, 'encoding'>): Promise<GitRunResult> {
-    return this.gitRunner.run(cwd, args, {
+    const run = () => this.gitRunner.run(cwd, args, {
       ...opts,
       // `GIT_LITERAL_PATHSPECS=1` makes git treat every pathspec literally
       // instead of interpreting `[`, `]`, `*`, `?`, `!`, or `:(magic)` as glob
@@ -4089,6 +4230,18 @@ export class GitService implements IGitService {
       // a search for a file literally named that.
       env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
     });
+    // A write to the git config is a write to the ONE file every worktree of
+    // the repository shares, which git refuses a second writer of rather than
+    // waiting: it runs as the repository's administrator. Everything else —
+    // a fetch, a commit, a branch delete — git serializes with its own locks,
+    // as it does for any two worktrees of one repository.
+    return writesSharedConfig(args) ? this.asRepositoryAdministrator(cwd, run) : run();
+  }
+
+  /** `run` as the repository's administrator when `cwd` is a worktree of it; as itself for a full clone. */
+  private async asRepositoryAdministrator<T>(cwd: string, run: () => Promise<T>): Promise<T> {
+    const repository = (await this.workspaceService.repositoryOfCheckout?.(cwd)) ?? null;
+    return repository ? repository.exclusive(run) : run();
   }
 
   /**
@@ -4276,3 +4429,35 @@ export function parseNumstatZ(out: string): NumstatEntry[] {
   }
   return entries;
 }
+
+/**
+ * Whether a git command WRITES the config — the one file every worktree of
+ * the knowledge base's repository shares, which git refuses a second writer
+ * of rather than waiting — and so must run as the repository's administrator
+ * (`IKbRepository.exclusive`): a `config` that sets or unsets, a `remote`
+ * change, a branch rename, delete or upstream change (its config section is
+ * written, or removed with the branch), a push that sets the upstream. Reads
+ * of the config are not writes. Nothing else is: the refs, `packed-refs` and
+ * the object store are locked by git itself, and the worktree list is the
+ * repository's own to serialize (`KbRepository`).
+ *
+ * Leading `-c key=value` / `-C dir` options are skipped to find the subcommand.
+ */
+function writesSharedConfig(args: readonly string[]): boolean {
+  let i = 0;
+  while (i < args.length && (args[i] === '-c' || args[i] === '-C')) i += 2;
+  const sub = args[i];
+  const rest = args.slice(i + 1);
+  switch (sub) {
+    case 'remote':
+      return true;
+    case 'config':
+      return !rest.some((a) => /^(--get|--get-all|--get-regexp|--list|-l|--show-origin)$/.test(a));
+    case 'branch':
+      return rest.some((a) => /^(-d|-D|--delete|-m|-M|--move|-u|--set-upstream-to=.*|--unset-upstream)$/.test(a));
+    case 'push':
+      return rest.some((a) => a === '-u' || a === '--set-upstream');
+    default:
+      return false;
+  }
+}

package/src/modules/workflow/index.ts

@@ -0,0 +1,7 @@
+/**
+ * What the workflow module offers the other modules: the addresses of its
+ * change requests, so a module that lands a proposal can hand back a link
+ * built by the one rule — rather than each spelling the route for itself.
+ * The services are wired by the composition root.
+ */
+export { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from './git/change-request-link.js';