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

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);
@@ -271,6 +274,8 @@ export class GitService implements IGitService {
   // worst case for branch-switching UX).
   private readonly fetchLocks = new Map<string, Promise<void>>();
   private readonly lastImplicitFetchAt = new Map<string, number>();
+  /** Whether the last implicit fetch per workspace SUCCEEDED — see `fetchOriginIfStale`. */
+  private readonly lastImplicitFetchOk = new Map<string, boolean>();
   private static readonly IMPLICIT_FETCH_TTL_MS = 5_000;
   // Cap on concurrent `aheadBehindForBranch` calls inside `listBranches`. Each
   // call serializes up to 3 `git rev-list` spawns, so 8 workers ≈ ≤24
@@ -315,6 +320,11 @@ export class GitService implements IGitService {
    */
   noteWorkspaceFetched(workspaceId: string): void {
     this.lastImplicitFetchAt.set(workspaceId, Date.now());
+    // A fresh clone IS a successful fetch. Without this, a workspace
+    // recreated after some earlier failed fetch inherits the stale `false`
+    // under the same id, and a strict listBranches inside the TTL window
+    // refuses a list that is in fact provably fresh.
+    this.lastImplicitFetchOk.set(workspaceId, true);
   }
 
   /**
@@ -399,7 +409,7 @@ export class GitService implements IGitService {
 
   async listBranches(
     workspaceId: string,
-    opts: { freshFetch?: boolean } = {},
+    opts: { freshFetch?: boolean; strictFetch?: boolean } = {},
   ): Promise<BranchInfo[]> {
     const cwd = await this.repoDir(workspaceId);
     // Run the fetch BEFORE entering the mutex so a slow origin can't block
@@ -409,7 +419,18 @@ export class GitService implements IGitService {
     // bypasses the TTL — used for user-initiated refreshes (opening the branch
     // selector) so a draft another workspace just deleted is pruned right away
     // instead of lingering up to one TTL window.
-    await this.fetchOriginIfStale(cwd, workspaceId, opts.freshFetch);
+    const fresh = await this.fetchOriginIfStale(cwd, workspaceId, opts.freshFetch);
+    // `strictFetch` is for callers that USE the list to prove absence — the
+    // deleted-branch sweep closes change requests on it. The degrade-to-stale
+    // behaviour below is right for a UI listing (stale branches beat a 500),
+    // and exactly wrong for an absence proof: a clone that last fetched
+    // before a branch was created reports it missing. Such a caller gets a
+    // thrown error instead of a list it must not trust.
+    if (opts.strictFetch && !fresh) {
+      throw new Error(
+        'the fetch from origin failed, so the branch list cannot prove absence — refusing to serve a stale list to a strict caller',
+      );
+    }
     return this.mutex.run(workspaceId, async () => {
       // 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
@@ -509,7 +530,10 @@ export class GitService implements IGitService {
    * onto a single in-flight fetch instead of each waiting their turn behind
    * the network round-trip. Failures (offline, bad auth, no remote) are
    * logged and swallowed so the branch list still serves stale local data
-   * instead of returning 500.
+   * instead of returning 500 — the RETURN VALUE says whether the refs are
+   * provably fresh (`true`: this call fetched, or shared a fetch, that
+   * succeeded; also `true` on a TTL skip, whose window a recent success
+   * opened). Callers that need proof (strict listing) read it.
    *
    * Safe to keep outside the mutex: fetch only writes remote-tracking refs
    * and the object store, neither of which checkout/status/commit touch.
@@ -518,9 +542,11 @@ export class GitService implements IGitService {
     cwd: string,
     workspaceId: string,
     force = false,
-  ): Promise<void> {
+  ): Promise<boolean> {
     const last = this.lastImplicitFetchAt.get(workspaceId) ?? 0;
-    if (!force && Date.now() - last < GitService.IMPLICIT_FETCH_TTL_MS) return;
+    if (!force && Date.now() - last < GitService.IMPLICIT_FETCH_TTL_MS) {
+      return this.lastImplicitFetchOk.get(workspaceId) ?? true;
+    }
 
     const inFlight = this.fetchLocks.get(workspaceId);
     if (inFlight) {
@@ -529,7 +555,7 @@ export class GitService implements IGitService {
       // the same promise also means subsequent listBranches calls see the
       // newly fetched refs.
       await inFlight;
-      return;
+      return this.lastImplicitFetchOk.get(workspaceId) ?? false;
     }
 
     const runFetch = async (): Promise<void> => {
@@ -546,6 +572,7 @@ export class GitService implements IGitService {
           ...SAFE_IMPLICIT_FETCH_ARGS,
         ]);
         this.lastImplicitFetchAt.set(workspaceId, Date.now());
+        this.lastImplicitFetchOk.set(workspaceId, true);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         console.warn(`[git] implicit fetch failed for workspace ${workspaceId}: ${msg}`);
@@ -553,12 +580,14 @@ export class GitService implements IGitService {
         // every subsequent listBranches retry the (still-failing) fetch and
         // pile up 10s timeouts. Stale local refs are better than spinning.
         this.lastImplicitFetchAt.set(workspaceId, Date.now());
+        this.lastImplicitFetchOk.set(workspaceId, false);
       }
     };
     const p = runFetch();
     this.fetchLocks.set(workspaceId, p);
     try {
       await p;
+      return this.lastImplicitFetchOk.get(workspaceId) ?? false;
     } finally {
       // Drop the lock once the fetch settles so the next caller past the TTL
       // can spawn a fresh one. Compare-and-delete in case a future race
@@ -1520,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 };
     });
   }
 
@@ -1781,17 +1990,46 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // Same per-file rule as the diff endpoints: `git log -- <dir>` lists
+      // every child's commits, and even metadata (subjects, authors, when)
+      // is history the per-file gate never authorized for the children. A
+      // HEAD check alone is not enough — a directory deleted before HEAD is
+      // absent NOW and still traversed by the log — so the proof comes from
+      // what the log itself TOUCHED: `--name-only` lists the paths behind
+      // each listed commit, and any name that is not exactly the requested
+      // path means the pathspec matched a tree somewhere in the range.
+      await this.assertNotTreeAtRef(cwd, 'HEAD', repoRelativePath, relativePath);
       const { stdout } = await this.git(cwd, [
         'log',
         `--max-count=${max}`,
-        '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+        '--name-only',
+        '--pretty=format:%x01%H%x00%an%x00%ae%x00%s%x00%aI',
         '--',
         repoRelativePath,
       ]);
+      for (const chunk of stdout.split('\u0001')) {
+        const lines = chunk.split('\n');
+        for (const nameLine of lines.slice(1)) {
+          // No trim: a tracked name CAN begin or end with whitespace, and
+          // trimming it here would reject that valid file as a directory.
+          // Only the genuinely empty separator lines are skipped.
+          const touched = nameLine.endsWith('\r') ? nameLine.slice(0, -1) : nameLine;
+          if (touched && touched !== repoRelativePath) {
+            throw new WorkflowValidationError(
+              `"${relativePath}" is a directory at that point in history — history is served per file`,
+            );
+          }
+        }
+      }
       return stdout
+        .split('\u0001')
+        .join('')
         .split('\n')
         .map((line) => line.trim())
         .filter(Boolean)
+        // `--name-only` interleaves the touched path under each commit line;
+        // only the field lines carry the NUL separators.
+        .filter((line) => line.includes('\x00'))
         .map((line): CommitAttribution => {
           const [sha, authorName, authorEmail, subject, committedAt] = line.split('\x00');
           return {
@@ -1817,6 +2055,11 @@ export class GitService implements IGitService {
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
       const cwd = await this.repoDir(workspaceId);
+      // BOTH sides: at a commit that DELETES a directory the path is absent
+      // at `sha` but a tree at `sha^` — and the diff of that deletion is
+      // every child's content, exactly what the per-file gate never checked.
+      await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
+      await this.assertNotTreeAtRef(cwd, `${sha}^`, repoRelativePath, relativePath);
       try {
         const { stdout } = await this.git(cwd, [
           'show',
@@ -1862,6 +2105,9 @@ export class GitService implements IGitService {
     }
     const repoRelativePath = this.stripRepoPrefix(relativePath);
     return this.mutex.run(workspaceId, async () => {
+      const cwd = await this.repoDir(workspaceId);
+      await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
+      await this.assertNotTreeAtRef(cwd, `${sha}^`, repoRelativePath, relativePath);
       const current = await this.readFileAtRef(workspaceId, sha, repoRelativePath);
       let baseline: string | null;
       try {
@@ -1898,6 +2144,8 @@ export class GitService implements IGitService {
       const cwd = await this.repoDir(workspaceId);
       const fromRef = await this.resolveBranchRef(cwd, fromBranch);
       const toRef = await this.resolveBranchRef(cwd, toBranch);
+      await this.assertNotTreeAtRef(cwd, fromRef, repoRelativePath, relativePath);
+      await this.assertNotTreeAtRef(cwd, toRef, repoRelativePath, relativePath);
       // When one side is the currently-checked-out branch, diff against the
       // working tree instead of the branch's HEAD commit. Otherwise saves
       // that haven't been committed yet (which is the normal state in the
@@ -2394,6 +2642,49 @@ export class GitService implements IGitService {
    * `showAtRef`) — the caller distinguishes "absent" from "present but empty".
    * Read-only: `git show <ref>:<path>` never mutates the working tree.
    */
+  /**
+   * Refuse a history pathspec that names a TREE at `ref`. The history
+   * surfaces are per-file, and their read gate upstream checked exactly one
+   * path — but `git show/diff -- <dir>` walks every child, and a directory
+   * whose folder chain grants read can hold children whose own frontmatter
+   * denies it. `git show <ref>:<dir>` even prints the tree listing. Absent
+   * at the ref is fine (absent is not a tree — a deleted file's history is
+   * still its own), and an unresolvable ref is left for the actual read to
+   * report in its own words.
+   */
+  private async assertNotTreeAtRef(
+    cwd: string,
+    ref: string,
+    repoRelativePath: string,
+    displayPath: string,
+  ): Promise<void> {
+    let kind: string;
+    try {
+      const { stdout } = await this.git(cwd, ['cat-file', '-t', `${ref}:${repoRelativePath}`]);
+      kind = stdout.trim();
+    } catch (err) {
+      // ONLY proven absence passes: the path missing at the ref, or the ref
+      // itself unresolvable (a root commit's `^`), which the actual read
+      // reports in its own words. Anything else — a locked repo, a corrupt
+      // object, git failing to run — must not be read as "not a tree": a
+      // guard that fails open on its own errors is not a guard.
+      const msg = err instanceof Error ? err.message : String(err);
+      if (
+        /not a valid object name|invalid object name|does not exist in|unknown revision|bad revision|exists on disk, but not in/i.test(
+          msg,
+        )
+      ) {
+        return;
+      }
+      throw err;
+    }
+    if (kind === 'tree') {
+      throw new WorkflowValidationError(
+        `"${displayPath}" is a directory at that point in history — history is served per file`,
+      );
+    }
+  }
+
   async readFileAtRef(
     workspaceId: string,
     ref: string,

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()