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

package/dist/modules/workflow/git/git.service.js

@@ -7,7 +7,7 @@ import { WorkspaceMutex } from '../../kb-fs/mutex.js';
 import { assertInsideRepo } from '../../kb-fs/repo-path.js';
 import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
 import { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch, isProtectedBranch, PROTECTED_BRANCHES, } from '../../kb-fs/branch-name.js';
-import { BranchAuthorshipError, WorkflowValidationError, ProtectedBranchError, PullRebaseConflictError, } from '../../../shared/domain-errors.js';
+import { BranchAuthorshipError, WorkflowValidationError, ProtectedBranchError, PullRebaseConflictError, RemoteBranchGoneError, isMissingRemoteBranchFailure, } from '../../../shared/domain-errors.js';
 const execFileAsync = promisify(execFile);
 function redact(msg) {
     const token = process.env.GITHUB_TOKEN;
@@ -233,6 +233,8 @@ export class GitService {
     // worst case for branch-switching UX).
     fetchLocks = new Map();
     lastImplicitFetchAt = new Map();
+    /** Whether the last implicit fetch per workspace SUCCEEDED — see `fetchOriginIfStale`. */
+    lastImplicitFetchOk = new Map();
     static 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
@@ -274,6 +276,11 @@ export class GitService {
      */
     noteWorkspaceFetched(workspaceId) {
         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);
     }
     /**
      * Run the registered ADVISORY commit-validation hooks at a commit site.
@@ -351,7 +358,16 @@ export class GitService {
         // 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
@@ -446,15 +462,19 @@ export class GitService {
      * 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.
      */
     async fetchOriginIfStale(cwd, workspaceId, force = false) {
         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) {
             // Another caller is already fetching for this workspace — share its
@@ -462,7 +482,7 @@ export class GitService {
             // 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 () => {
             try {
@@ -478,6 +498,7 @@ export class GitService {
                     ...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);
@@ -486,12 +507,14 @@ export class GitService {
                 // 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
@@ -1346,68 +1369,241 @@ export class GitService {
         ]);
         return `refs/remotes/origin/${branch}`;
     }
-    async pull(workspaceId) {
+    /** A commit-free tree, for diffing against a HEAD that did not exist yet. */
+    static 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.
+     */
+    async checkedOutBranch(cwd) {
+        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, branch) {
+        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.exitCode === 2)
+                return false;
+            throw err;
+        }
+    }
+    /** Whether origin has ANY branch — an empty repository has none. */
+    async remoteHasAnyBranch(cwd) {
+        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). */
+    async revParseOrNull(cwd, rev) {
+        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.
+     */
+    async refreshRemoteBranchRefForSync(cwd, branch) {
+        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.
+     */
+    async rebaseOntoRemote(cwd, branch, remoteRef) {
+        // 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 = [];
+            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.
+     */
+    async changedPathsBetween(cwd, fromSha, toSha) {
+        const { stdout } = await this.git(cwd, [
+            'diff', '--name-status', '-M', '--no-color', '-z', fromSha, toSha,
+        ]);
+        const fields = stdout.split('\0');
+        const paths = new Set();
+        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) {
+        // 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;
             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 = [];
-                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) {
+        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 };
         });
     }
     /**
@@ -1591,17 +1787,44 @@ export class GitService {
         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) => {
                 const [sha, authorName, authorEmail, subject, committedAt] = line.split('\x00');
                 return {
@@ -1622,6 +1845,11 @@ export class GitService {
         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',
@@ -1660,6 +1888,9 @@ export class GitService {
         }
         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;
             try {
@@ -1692,6 +1923,8 @@ export class GitService {
             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
@@ -2133,6 +2366,38 @@ export class GitService {
      * `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.
+     */
+    async assertNotTreeAtRef(cwd, ref, repoRelativePath, displayPath) {
+        let kind;
+        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, ref, repoRelativePath) {
         const cwd = await this.repoDir(workspaceId);
         try {