@bevel-software/platform-core-backend 0.14.0 → 0.15.1

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

@@ -0,0 +1,253 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { GitService } from '../git.service.js';
+import { RemoteBranchGoneError } from '../../../../shared/domain-errors.js';
+import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * `syncFromRemote` against real repositories: what it reports about the clone
+ * before and after, the paths it names, an upstream that has no commits yet,
+ * and a branch the host has deleted.
+ */
+const BRANCH = 'target-company-state';
+
+async function bareUpstream(root: string, withCommit: boolean): Promise<string> {
+  const upstream = path.join(root, 'upstream.git');
+  await runGit(root, ['init', '--bare', '-b', BRANCH, upstream]);
+  if (withCommit) {
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(seed, 'a.md'), 'a\n');
+    await fs.writeFile(path.join(seed, 'old name.md'), 'same content that survives a rename\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'init']);
+    await runGit(seed, ['push', 'origin', BRANCH]);
+  }
+  await runGit(upstream, ['symbolic-ref', 'HEAD', `refs/heads/${BRANCH}`]);
+  return upstream;
+}
+
+async function cloneWorkspace(root: string, upstream: string, workspaceId: string, branch = BRANCH) {
+  const workspaceDir = path.join(root, workspaceId);
+  const repo = path.join(workspaceDir, 'knowledge-base');
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await runGit(root, ['-c', 'core.autocrlf=false', 'clone', '-b', branch, upstream, repo]);
+  await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+  await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+  await runGit(repo, ['config', 'core.autocrlf', 'false']);
+  return { workspaceDir, repo };
+}
+
+/** Land one commit on origin from a second clone; returns the paths it touched. */
+async function pushFromElsewhere(root: string, upstream: string, edit: (dir: string) => Promise<void>, branch = BRANCH) {
+  const pusher = path.join(root, `.pusher-${Math.random().toString(36).slice(2)}`);
+  await runGit(root, ['-c', 'core.autocrlf=false', 'clone', '-b', branch, upstream, pusher]);
+  await runGit(pusher, ['config', 'user.email', 'other@bevel.test']);
+  await runGit(pusher, ['config', 'user.name', 'Other']);
+  await edit(pusher);
+  await runGit(pusher, ['add', '-A']);
+  await runGit(pusher, ['commit', '-m', 'from origin']);
+  await runGit(pusher, ['push', 'origin', branch]);
+}
+
+describe('GitService.syncFromRemote', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync-'));
+  });
+
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('reports where HEAD was and is, that the tree changed, and every path including both ends of a rename', async () => {
+    const upstream = await bareUpstream(root, true);
+    const { workspaceDir, repo } = await cloneWorkspace(root, upstream, 'ws');
+    const before = (await gitOut(repo, ['rev-parse', 'HEAD'])).trim();
+    await pushFromElsewhere(root, upstream, async (dir) => {
+      await fs.writeFile(path.join(dir, 'a.md'), 'a changed\n');
+      await fs.writeFile(path.join(dir, 'b.md'), 'b\n');
+      await fs.rename(path.join(dir, 'old name.md'), path.join(dir, 'new name.md'));
+    });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    const r = await git.syncFromRemote('ws');
+    expect(r.before).toBe(before);
+    expect(r.after).toBe((await gitOut(repo, ['rev-parse', 'HEAD'])).trim());
+    expect(r.after).not.toBe(before);
+    expect(r.treeChanged).toBe(true);
+    expect([...r.changedPaths].sort()).toEqual(['a.md', 'b.md', 'new name.md', 'old name.md'].sort());
+
+    // Nothing new: same shas, no change, no paths.
+    const again = await git.syncFromRemote('ws');
+    expect(again).toEqual({ before: r.after, after: r.after, treeChanged: false, changedPaths: [] });
+  });
+
+  it('an unborn clone of an empty upstream is tolerated, and receives its first content as a change from null', async () => {
+    const upstream = await bareUpstream(root, false);
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    // Cloning an empty repository warns but succeeds; HEAD is unborn.
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+    await runGit(repo, ['checkout', '-b', BRANCH]).catch(() => undefined);
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    // Still empty on both sides: nothing to sync, and NOT 'remote gone' — a
+    // fresh deployment nobody has pushed to must never have its clone retired.
+    expect(await git.syncFromRemote('ws')).toEqual({ before: null, after: null, treeChanged: false, changedPaths: [] });
+
+    // Origin gains its first commit.
+    const seed = path.join(root, '.first');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['config', 'user.email', 'other@bevel.test']);
+    await runGit(seed, ['config', 'user.name', 'Other']);
+    await fs.writeFile(path.join(seed, 'README.md'), 'hello\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'first']);
+    await runGit(seed, ['push', upstream, BRANCH]);
+
+    const r = await git.syncFromRemote('ws');
+    expect(r.before).toBeNull();
+    expect(r.after).toMatch(/^[0-9a-f]{40}$/);
+    expect(r.treeChanged).toBe(true);
+    expect(r.changedPaths).toEqual(['README.md']);
+  });
+
+  it('a branch deleted on the host is a typed "remote branch gone", not an unreachable remote', async () => {
+    const upstream = await bareUpstream(root, true);
+    await runGit(upstream, ['branch', 'ali/x', BRANCH]);
+    const { workspaceDir } = await cloneWorkspace(root, upstream, 'ali%2Fx', 'ali/x');
+    await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
+    const git = new GitService(stubWorkspaceService({ 'ali%2Fx': workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    await expect(git.syncFromRemote('ali%2Fx')).rejects.toBeInstanceOf(RemoteBranchGoneError);
+  });
+});
+
+describe('GitService.syncFromRemote — the cases git exits 0 on but should not pass', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync2-'));
+  });
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('an autostashed edit that conflicts on reapply is a typed conflict, the tree is left clean, the edit is kept in stash', async () => {
+    const upstream = await bareUpstream(root, true);
+    const { workspaceDir, repo } = await cloneWorkspace(root, upstream, 'ws');
+    // A tracked edit nobody committed — what a lock-holder's in-progress save looks like.
+    await fs.writeFile(path.join(repo, 'a.md'), 'edited locally\n');
+    await pushFromElsewhere(root, upstream, async (dir) => {
+      await fs.writeFile(path.join(dir, 'a.md'), 'edited on the host\n');
+    });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
+      name: 'PullRebaseConflictError',
+      conflictedPaths: ['a.md'],
+    });
+    // Clean tree at the remote commit; the local edit survives in the stash.
+    expect(await gitOut(repo, ['status', '--porcelain'])).toBe('');
+    expect(await gitOut(repo, ['rev-parse', 'HEAD'])).toBe(await gitOut(repo, ['rev-parse', 'refs/remotes/origin/' + BRANCH]));
+    expect((await gitOut(repo, ['stash', 'list'])).split('\n').filter(Boolean)).toHaveLength(1);
+  });
+
+  it('an unborn clone whose branch was created and deleted on an origin that has other branches is remote gone, not fresh', async () => {
+    const upstream = await bareUpstream(root, true); // origin has BRANCH
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    // An unborn clone checked out on a branch origin does not have.
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['checkout', '--orphan', 'ali/x']);
+    await runGit(repo, ['rm', '-rf', '--cached', '.']).catch(() => undefined);
+    await fs.rm(path.join(repo, 'a.md'), { force: true });
+    await fs.rm(path.join(repo, 'old name.md'), { force: true });
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    await expect(git.syncFromRemote('ws')).rejects.toBeInstanceOf(RemoteBranchGoneError);
+  });
+
+  it('remoteBranchExists answers from origin, not from the clone', async () => {
+    const upstream = await bareUpstream(root, true);
+    await runGit(upstream, ['branch', 'ali/x', BRANCH]);
+    const { workspaceDir } = await cloneWorkspace(root, upstream, 'ws');
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+    expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(true);
+    await runGit(upstream, ['update-ref', '-d', 'refs/heads/ali/x']);
+    expect(await git.remoteBranchExists('ws', 'ali/x')).toBe(false);
+  });
+});
+
+describe('GitService.syncFromRemote — an unborn clone that already holds staged files', () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-git-sync3-'));
+  });
+  afterEach(async () => {
+    for (let i = 0; i < 5; i++) {
+      try {
+        await fs.rm(root, { recursive: true, force: true });
+        return;
+      } catch {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    }
+  });
+
+  it('is refused as a typed conflict naming the staged paths; nothing on disk is touched', async () => {
+    const upstream = await bareUpstream(root, false);
+    const workspaceDir = path.join(root, 'ws');
+    const repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await runGit(root, ['-c', 'core.autocrlf=false', 'clone', upstream, repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+    await runGit(repo, ['checkout', '-b', BRANCH]).catch(() => undefined);
+    // Someone wrote and staged a file before the first commit ever existed —
+    // with a name git's line output would quote ("Entw\\303\\274rfe.md"), so
+    // the outcome has to carry the real spelling.
+    await fs.writeFile(path.join(repo, 'Entwürfe.md'), 'not yet committed\n');
+    await runGit(repo, ['add', 'Entwürfe.md']);
+    // Origin gains its first commit meanwhile.
+    const seed = path.join(root, '.first');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', BRANCH]);
+    await runGit(seed, ['config', 'user.email', 'other@bevel.test']);
+    await runGit(seed, ['config', 'user.name', 'Other']);
+    await fs.writeFile(path.join(seed, 'README.md'), 'hello\n');
+    await runGit(seed, ['add', '.']);
+    await runGit(seed, ['commit', '-m', 'first']);
+    await runGit(seed, ['push', upstream, BRANCH]);
+    const git = new GitService(stubWorkspaceService({ ws: workspaceDir }), stubWorkflowHooks(), 'knowledge-base');
+
+    await expect(git.syncFromRemote('ws')).rejects.toMatchObject({
+      name: 'PullRebaseConflictError',
+      conflictedPaths: ['Entwürfe.md'],
+    });
+    expect(await fs.readFile(path.join(repo, 'Entwürfe.md'), 'utf8')).toBe('not yet committed\n');
+    expect((await gitOut(repo, ['ls-files', '--cached', '-z'])).replace(/\0$/, '')).toBe('Entwürfe.md');
+  });
+});

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

@@ -7,6 +7,7 @@ import type {
   BranchInfo,
   CommitAttribution,
   IGitService,
+  RemoteSyncPullResult,
   PrFileStatus,
   PullRequestFile,
   ShareChangesRequest,
@@ -32,6 +33,8 @@ import {
   WorkflowValidationError,
   ProtectedBranchError,
   PullRebaseConflictError,
+  RemoteBranchGoneError,
+  isMissingRemoteBranchFailure,
 } from '../../../shared/domain-errors.js';
 
 const execFileAsync = promisify(execFile);
@@ -1546,70 +1549,250 @@ export class GitService implements IGitService {
     return `refs/remotes/origin/${branch}`;
   }
 
-  async pull(workspaceId: string): Promise<void> {
+  /** A commit-free tree, for diffing against a HEAD that did not exist yet. */
+  private static readonly EMPTY_TREE_SHA = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+  /**
+   * The checked-out branch by its symbolic ref, which an UNBORN HEAD (a clone
+   * of an empty upstream) still has — `rev-parse --abbrev-ref HEAD` does not
+   * resolve there, so the tolerant tree reads below would never be reached.
+   */
+  private async checkedOutBranch(cwd: string): Promise<string> {
+    const { stdout } = await this.git(cwd, ['symbolic-ref', '--short', 'HEAD']);
+    return stdout.trim();
+  }
+
+  /**
+   * Whether origin still has `branch`. `ls-remote --exit-code` answers with
+   * exit status 2 for "no such ref" — the one failure that is a fact about the
+   * branch rather than about reaching the host, which propagates.
+   */
+  async remoteBranchExists(workspaceId: string, branch: string): Promise<boolean> {
+    assertValidBranchName(branch);
+    const cwd = await this.repoDir(workspaceId);
+    try {
+      await this.git(cwd, ['ls-remote', '--exit-code', '--heads', 'origin', `refs/heads/${branch}`]);
+      return true;
+    } catch (err) {
+      if ((err as { exitCode?: number }).exitCode === 2) return false;
+      throw err;
+    }
+  }
+
+  /** Whether origin has ANY branch — an empty repository has none. */
+  private async remoteHasAnyBranch(cwd: string): Promise<boolean> {
+    const { stdout } = await this.git(cwd, ['ls-remote', '--heads', 'origin']);
+    return stdout.trim().length > 0;
+  }
+
+  /** `git rev-parse --verify` that answers null for a rev that does not resolve (an unborn HEAD). */
+  private async revParseOrNull(cwd: string, rev: string): Promise<string | null> {
+    try {
+      const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', rev]);
+      return stdout.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Refresh `refs/remotes/origin/<branch>` for a sync, naming the one failure
+   * that is not "origin unreachable": the branch no longer exists there.
+   */
+  private async refreshRemoteBranchRefForSync(cwd: string, branch: string): Promise<string> {
+    try {
+      return await this.refreshRemoteBranchRef(cwd, branch);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (isMissingRemoteBranchFailure(msg)) throw new RemoteBranchGoneError(branch);
+      throw err;
+    }
+  }
+
+  /**
+   * Rebase the checked-out branch onto `remoteRef`, turning a content
+   * conflict into the typed error the workflow layer queues recovery for.
+   * Shared by `pull` and `syncFromRemote` so the two cannot drift.
+   */
+  private async rebaseOntoRemote(cwd: string, branch: string, remoteRef: string): Promise<void> {
+    // An UNBORN HEAD (a clone of an upstream that was empty when cloned) has
+    // no commit to replay and `git rebase` refuses to start from it, so the
+    // branch is moved to the remote commit instead. That is only safe while
+    // the index is EMPTY: files staged in an unborn clone are tracked, and a
+    // hard reset would destroy them where the normal path autostashes — and
+    // `git stash` cannot run without an initial commit. So a non-empty index
+    // is refused as a conflict, naming the staged paths, and takes the same
+    // recovery path a rebase conflict does; nothing on disk is touched.
+    if ((await this.revParseOrNull(cwd, 'HEAD')) === null) {
+      // `-z`: NUL-delimited and unquoted. Line output quotes a path with a
+      // non-ASCII or control character ("Entw\303\274rfe.md"), and that
+      // spelling would name a file that does not exist to whoever recovers.
+      const { stdout: stagedOut } = await this.git(cwd, ['ls-files', '--cached', '-z']);
+      const staged = stagedOut.split('\0').filter(Boolean);
+      if (staged.length > 0) {
+        throw new PullRebaseConflictError(
+          branch,
+          staged,
+          'The clone has files staged before its first commit; they cannot be replayed onto the remote branch automatically.',
+        );
+      }
+      await this.git(cwd, ['reset', '--hard', remoteRef]);
+      return;
+    }
+    try {
+      // `--autostash` is load-bearing for the cooperative push recovery.
+      // Under save=share the working tree is *supposed* to stay clean, but
+      // in practice it can carry modified tracked artifacts (e.g. the
+      // validator regenerates a dashboard HTML on every commit) that the
+      // single-file commit didn't pick up. A rebase without it aborts
+      // outright on those — "cannot rebase: You have unstaged
+      // changes" — which is exactly the failure that strands a diverged
+      // branch in an unrecoverable loop (the retry push stays non-fast-
+      // forward forever). Autostash stashes those modifications, rebases
+      // the local commits onto origin, then reapplies them, so the retry
+      // push can fast-forward. Untracked files don't block rebase and are
+      // left untouched.
+      await this.git(cwd, ['rebase', '--autostash', remoteRef]);
+    } catch (err) {
+      // Capture the contested paths BEFORE the abort wipes the rebase
+      // state — `--diff-filter=U` lists exactly the files whose replay
+      // conflicted. Best-effort: an empty list just means this wasn't a
+      // content conflict (or the probe itself failed) and the raw error
+      // is surfaced unchanged.
+      let conflictedPaths: string[] = [];
+      try {
+        const { stdout } = await this.git(cwd, ['diff', '--name-only', '--diff-filter=U']);
+        conflictedPaths = stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+      } catch {
+        // fall through with an empty list
+      }
+      // A failed rebase leaves the repo in a "REBASE_HEAD" / detached-apply state,
+      // which makes every subsequent git command behave unexpectedly. Return the
+      // working tree to a clean state before surfacing the original error.
+      let abortSucceeded = true;
+      await this.git(cwd, ['rebase', '--abort']).catch(() => {
+        abortSucceeded = false;
+      });
+      if (abortSucceeded && conflictedPaths.length > 0) {
+        // Typed so the workflow layer can queue background recovery — this
+        // divergence never resolves on its own (every retry pull hits the
+        // same conflict) and the unpushed local commits are someone's saved
+        // content stuck violating save=share.
+        //
+        // Gated on the abort succeeding: a failed abort means either no
+        // rebase was ever active (the unmerged paths pre-date this pull —
+        // some earlier operation left the index broken) or the clone is in
+        // a state git itself can't unwind. Queueing recovery there would
+        // point the worker's commitFile at a repo mid-conflict, risking a
+        // commit full of conflict markers — surface the raw error instead
+        // and leave diagnosis to a human.
+        throw new PullRebaseConflictError(
+          branch,
+          conflictedPaths,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
+      throw err;
+    }
+    // `--autostash` reapplies the stashed edits AFTER the rebase, and when that
+    // reapply conflicts git exits 0: the clone is left with an unmerged index,
+    // the edits kept in `stash@{0}`, and nothing above has thrown. Read the
+    // index rather than the exit status. The rebase itself landed, so the
+    // branch is at the remote commit; resetting to it drops only the
+    // half-applied stash (still in the stash list) and lets the conflict
+    // travel the same typed path a rebase conflict does.
+    const { stdout: unmergedOut } = await this.git(cwd, ['diff', '--name-only', '--diff-filter=U']);
+    const unmerged = unmergedOut.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (unmerged.length > 0) {
+      await this.git(cwd, ['reset', '--hard', 'HEAD']);
+      throw new PullRebaseConflictError(
+        branch,
+        unmerged,
+        'Reapplying the autostashed working-tree edits conflicted; the edits are kept in git stash.',
+      );
+    }
+  }
+
+  /**
+   * Repo-relative paths whose content differs between two commits. Rename-
+   * aware: a renamed file reports both its old and new path, so a viewer
+   * holding the OLD path learns it is gone. Caller holds the mutex.
+   */
+  private async changedPathsBetween(cwd: string, fromSha: string, toSha: string): Promise<string[]> {
+    const { stdout } = await this.git(cwd, [
+      'diff', '--name-status', '-M', '--no-color', '-z', fromSha, toSha,
+    ]);
+    const fields = stdout.split('\0');
+    const paths = new Set<string>();
+    for (let i = 0; i < fields.length; ) {
+      const status = fields[i];
+      if (!status) break;
+      if (status.startsWith('R') || status.startsWith('C')) {
+        if (fields[i + 1]) paths.add(fields[i + 1]);
+        if (fields[i + 2]) paths.add(fields[i + 2]);
+        i += 3;
+      } else {
+        if (fields[i + 1]) paths.add(fields[i + 1]);
+        i += 2;
+      }
+    }
+    return [...paths];
+  }
+
+  async syncFromRemote(workspaceId: string): Promise<RemoteSyncPullResult> {
+    // ONE mutex section for everything the sync reports about this clone.
+    // Bracketing `pull` with separate HEAD reads and a diff took the hold
+    // four times, and a save landing between any two of them was announced
+    // back to its author as a "Git sync" change with the wrong sha.
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
-      const branch = await this.currentBranch(cwd);
+      const branch = await this.checkedOutBranch(cwd);
+      const before = await this.revParseOrNull(cwd, 'HEAD');
+      const treeBefore = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+      let remoteRef: string;
       try {
-        // Refresh WITHOUT `git pull`, and without touching `FETCH_HEAD` — see
-        // `refreshRemoteBranchRef` for why both halves are load-bearing.
-        //
-        // `--autostash` is load-bearing for the cooperative push recovery.
-        // Under save=share the working tree is *supposed* to stay clean, but
-        // in practice it can carry modified tracked artifacts (e.g. the
-        // validator regenerates a dashboard HTML on every commit) that the
-        // single-file commit didn't pick up. A rebase without it aborts
-        // outright on those — "cannot rebase: You have unstaged
-        // changes" — which is exactly the failure that strands a diverged
-        // branch in an unrecoverable loop (the retry push stays non-fast-
-        // forward forever). Autostash stashes those modifications, rebases
-        // the local commits onto origin, then reapplies them, so the retry
-        // push can fast-forward. Untracked files don't block rebase and are
-        // left untouched.
-        const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
-        await this.git(cwd, ['rebase', '--autostash', remoteRef]);
+        remoteRef = await this.refreshRemoteBranchRefForSync(cwd, branch);
       } catch (err) {
-        // Capture the contested paths BEFORE the abort wipes the rebase
-        // state — `--diff-filter=U` lists exactly the files whose replay
-        // conflicted. Best-effort: an empty list just means this wasn't a
-        // content conflict (or the probe itself failed) and the raw error
-        // is surfaced unchanged.
-        let conflictedPaths: string[] = [];
-        try {
-          const { stdout } = await this.git(cwd, ['diff', '--name-only', '--diff-filter=U']);
-          conflictedPaths = stdout.split('\n').map((s) => s.trim()).filter(Boolean);
-        } catch {
-          // fall through with an empty list
-        }
-        // A failed rebase leaves the repo in a "REBASE_HEAD" / detached-apply state,
-        // which makes every subsequent git command behave unexpectedly. Return the
-        // working tree to a clean state before surfacing the original error.
-        let abortSucceeded = true;
-        await this.git(cwd, ['rebase', '--abort']).catch(() => {
-          abortSucceeded = false;
-        });
-        if (abortSucceeded && conflictedPaths.length > 0) {
-          // Typed so the workflow layer can queue background recovery — this
-          // divergence never resolves on its own (every retry pull hits the
-          // same conflict) and the unpushed local commits are someone's saved
-          // content stuck violating save=share.
-          //
-          // Gated on the abort succeeding: a failed abort means either no
-          // rebase was ever active (the unmerged paths pre-date this pull —
-          // some earlier operation left the index broken) or the clone is in
-          // a state git itself can't unwind. Queueing recovery there would
-          // point the worker's commitFile at a repo mid-conflict, risking a
-          // commit full of conflict markers — surface the raw error instead
-          // and leave diagnosis to a human.
-          throw new PullRebaseConflictError(
-            branch,
-            conflictedPaths,
-            err instanceof Error ? err.message : String(err),
-          );
+        // An unborn clone whose branch origin does not have either: on a FRESH
+        // deployment (origin has no branch at all) nobody has pushed yet —
+        // nothing to sync, nothing to retire. But an origin that does have
+        // branches and lacks this one has had this branch created and deleted
+        // since the clone was made, and the clone is as stale as any other.
+        if (err instanceof RemoteBranchGoneError && before === null && !(await this.remoteHasAnyBranch(cwd))) {
+          return { before: null, after: null, treeChanged: false, changedPaths: [] };
         }
         throw err;
       }
+      await this.rebaseOntoRemote(cwd, branch, remoteRef);
+      this.accessControl?.invalidate(workspaceId);
+      const after = await this.revParseOrNull(cwd, 'HEAD');
+      const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+      const treeChanged = treeAfter !== treeBefore;
+      const changedPaths =
+        treeChanged && after
+          ? await this.changedPathsBetween(cwd, before ?? GitService.EMPTY_TREE_SHA, after)
+          : [];
+      return { before, after, treeChanged, changedPaths };
+    });
+  }
+
+  async pull(workspaceId: string): Promise<{ treeChanged: boolean }> {
+    return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      const branch = await this.checkedOutBranch(cwd);
+      // For `treeChanged` (see IGitService.pull): TREE ids, not commit ids —
+      // a pull that lands only content-identical commits (an empty commit)
+      // must not read as a content change. Tolerant of an unborn HEAD (a
+      // clone of an empty upstream): "" before + a tree after correctly
+      // reads as changed, "" both sides as not.
+      const treeBefore = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+      // Refresh WITHOUT `git pull`, and without touching `FETCH_HEAD` — see
+      // `refreshRemoteBranchRef` for why both halves are load-bearing.
+      const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
+      await this.rebaseOntoRemote(cwd, branch, remoteRef);
       this.accessControl?.invalidate(workspaceId);
+      const treeAfter = (await this.revParseOrNull(cwd, 'HEAD^{tree}')) ?? '';
+      return { treeChanged: treeAfter !== treeBefore };
     });
   }
 

package/src/modules/workflow/git/pull-request.service.ts

@@ -438,6 +438,15 @@ export class PullRequestService implements IPullRequestService {
     this.cachedList.clear();
   }
 
+  /**
+   * Evict the CR-list caches alone. Each list entry carries `touchedNodePaths`
+   * resolved against a workspace's tree at the time; a remote sync that moved
+   * that tree makes them stale without touching any one request.
+   */
+  invalidateListCache(): void {
+    this.cachedList.clear();
+  }
+
   private async findRow(prNumber: number): Promise<ChangeRequestRow | null> {
     const [row] = await this.db
       .select()