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

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

@@ -1,18 +1,20 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
+import { logger } from '../../../shared/logging.js';
+import { isFolderPlaceholder } from '@bevel-software/platform-shared';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 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 { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch, isProtectedBranch, PROTECTED_BRANCHES, } from '../../kb-fs/branch-name.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;
-    return token ? msg.replaceAll(token, '***') : msg;
-}
+import { BranchAuthorshipError, WorkflowDomainError, WorkflowValidationError, ProtectedBranchError, PullRebaseConflictError, RemoteBranchGoneError, isMissingRemoteBranchFailure, } from '../../../shared/domain-errors.js';
+import { GitRunError, isGitTimeout, redactGitToken, } from '../../../shared/git.contract.js';
+import { NodeGitRunner } from './node-git-runner.js';
+import { printable } from '../../../shared/printable.js';
+import { sanitizeError } from '../sanitize-error.js';
+const log = logger('git');
+const crLog = logger('cr');
 /**
  * Fallback committer identity. Every workflow commit overrides the author via
  * `--author=…` so the real human shows up in `git log`; this is just the
@@ -196,16 +198,15 @@ async function synthesizeUntrackedSideDiff(cwd, relativePath, direction) {
             : synthesizeDeletedFileDiff(relativePath, text);
     }
     catch (err) {
-        if (err.code === 'ENOENT')
+        if (isAbsence(err))
             return '';
         throw err;
     }
 }
 /**
- * `stat` for the stray check: false only when nothing can be there (ENOENT,
- * or ENOTDIR when a parent segment is a file). Permission and I/O failures
- * propagate: treating them as "absent" would let an unreadable stray pass as
- * committed.
+ * `stat` for the stray check: false only when nothing can be there — the
+ * disk's own definition of absence. Permission and I/O failures propagate:
+ * treating them as "absent" would let an unreadable stray pass as committed.
  */
 async function existsForCommitCheck(absolutePath) {
     try {
@@ -213,8 +214,7 @@ async function existsForCommitCheck(absolutePath) {
         return true;
     }
     catch (err) {
-        const code = err.code;
-        if (code === 'ENOENT' || code === 'ENOTDIR')
+        if (isAbsence(err))
             return false;
         throw err;
     }
@@ -225,6 +225,7 @@ export class GitService {
     kbDirName;
     mutex;
     accessControl;
+    gitRunner;
     // Per-workspace fetch state, kept OUTSIDE the workspace mutex on purpose.
     // `git fetch` only writes `refs/remotes/origin/*` and packs new objects —
     // it doesn't touch HEAD, the index, or the working tree, so it's safe to
@@ -249,12 +250,21 @@ export class GitService {
      * replaced). No hooks registered = no commit-time validation, which is
      * safe because validation is advisory and never blocks a commit.
      */
-    hooks, kbDirName, mutex = new WorkspaceMutex(), accessControl = null) {
+    hooks, kbDirName, mutex = new WorkspaceMutex(), accessControl = null, 
+    /**
+     * How git is actually run — see `shared/git.contract.ts`. The composition
+     * root passes the one runner, carrying the deployment's configured
+     * deadline; the default here is the same runner on its default deadline,
+     * so a directly constructed service (every suite in this module) still has
+     * one rather than none.
+     */
+    gitRunner = new NodeGitRunner()) {
         this.workspaceService = workspaceService;
         this.hooks = hooks;
         this.kbDirName = kbDirName;
         this.mutex = mutex;
         this.accessControl = accessControl;
+        this.gitRunner = gitRunner;
     }
     /**
      * "Does the pending-commits queue hold rows for this workspace?" — used by
@@ -268,6 +278,17 @@ export class GitService {
     setPendingCommitsProbe(probe) {
         this.pendingCommitsProbe = probe;
     }
+    /**
+     * Late-bound by the composition root: notified with the branch names every
+     * `listBranches` returns. A listing is the one moment the platform sees
+     * origin's set of branches, and the workspace layer needs that memory to
+     * tell a branch that was deleted from a name that never existed — see
+     * `WorkspaceService.noteBranchesListed`.
+     */
+    onBranchesListed = null;
+    setBranchesListedListener(listener) {
+        this.onBranchesListed = listener;
+    }
     /**
      * Mark a workspace as freshly fetched. Called by `WorkspaceService` right
      * after a branch's clone is created — `git clone` already downloaded every
@@ -282,6 +303,21 @@ export class GitService {
         // refuses a list that is in fact provably fresh.
         this.lastImplicitFetchOk.set(workspaceId, true);
     }
+    /**
+     * The most recent attempt any workspace made to reach the remote, and
+     * whether it succeeded — for the readiness answer. Null before the first
+     * attempt of this process's life. Read off the per-workspace fetch record
+     * above rather than kept separately, so it cannot disagree with it.
+     */
+    lastRemoteContact() {
+        let latest = null;
+        for (const [workspaceId, at] of this.lastImplicitFetchAt) {
+            if (latest === null || at > latest.at) {
+                latest = { at, ok: this.lastImplicitFetchOk.get(workspaceId) ?? false };
+            }
+        }
+        return latest;
+    }
     /**
      * Run the registered ADVISORY commit-validation hooks at a commit site.
      * Preserves the semantics of the injected validator this replaced: a
@@ -295,12 +331,12 @@ export class GitService {
             try {
                 const report = await hook(ctx);
                 if (report && report.mustFix.length > 0) {
-                    console.warn(formatWarning(report));
+                    log.warn(formatWarning(report));
                 }
             }
             catch (validatorErr) {
                 // Validator failure is non-fatal — advisory only.
-                console.warn('[git] validator crashed (advisory only, ignoring):', validatorErr instanceof Error ? validatorErr.message : validatorErr);
+                log.warn('validator crashed (advisory only, ignoring):', { err: validatorErr });
             }
         }
     }
@@ -453,6 +489,18 @@ export class GitService {
                     };
                 }
             }));
+            // Every name this listing showed — origin's refs and the local heads
+            // alike, since a branch checked out here is one the platform has
+            // plainly heard of. A listener that misbehaves must not turn a good
+            // listing into a failed one.
+            try {
+                this.onBranchesListed?.(infos.map((info) => info.name));
+            }
+            catch (err) {
+                log.error(`branches-listed listener failed for workspace ${workspaceId}:`, {
+                    detail: err instanceof Error ? err.message : String(err),
+                });
+            }
             return infos;
         });
     }
@@ -502,7 +550,7 @@ export class GitService {
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                console.warn(`[git] implicit fetch failed for workspace ${workspaceId}: ${msg}`);
+                log.warn(`implicit fetch failed for workspace ${workspaceId}: ${msg}`);
                 // Stamp the TTL on failure too so a hard-down origin doesn't make
                 // every subsequent listBranches retry the (still-failing) fetch and
                 // pile up 10s timeouts. Stale local refs are better than spinning.
@@ -823,14 +871,14 @@ export class GitService {
             }
             if (trackedAtHead) {
                 await this.git(cwd, ['checkout', 'HEAD', '--', repoRelativePath]).catch((err) => {
-                    console.warn(`[git] discardPath checkout failed for "${repoRelativePath}":`, err instanceof Error ? err.message : err);
+                    log.warn(`discardPath checkout failed for "${repoRelativePath}":`, { err });
                 });
             }
             else {
                 // Untracked new file — remove from working tree.
                 const fileAbs = path.join(cwd, repoRelativePath);
                 await fs.rm(fileAbs, { force: true }).catch((err) => {
-                    console.warn(`[git] discardPath rm failed for "${repoRelativePath}":`, err instanceof Error ? err.message : err);
+                    log.warn(`discardPath rm failed for "${repoRelativePath}":`, { err });
                 });
             }
         });
@@ -839,8 +887,11 @@ export class GitService {
         assertValidRelativePath(relativePath);
         assertValidAuthor(user);
         const repoRelativePath = this.stripRepoPrefix(relativePath);
-        return this.mutex.run(workspaceId, async () => {
-            const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => this.commitFileUnlocked(workspaceId, await this.repoDir(workspaceId), user, relativePath, repoRelativePath, summary, skipValidator));
+    }
+    /** `commitFile`'s body, for a caller that already holds the workspace's reservation. */
+    async commitFileUnlocked(workspaceId, cwd, user, relativePath, repoRelativePath, summary, skipValidator) {
+        {
             const branch = await this.currentBranch(cwd);
             // Path-scoped status — is this specific file dirty? `--porcelain` on
             // a single path returns empty when there's nothing to commit.
@@ -900,7 +951,7 @@ export class GitService {
                 subject: subj ?? subject,
                 committedAt: committedAt?.trim() ?? new Date().toISOString(),
             };
-        });
+        }
     }
     /**
      * Atomic multi-file commit — commits the caller's batch as ONE commit
@@ -1049,8 +1100,11 @@ export class GitService {
         });
     }
     async push(workspaceId, user, opts) {
-        return this.mutex.run(workspaceId, async () => {
-            const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => this.pushUnlocked(workspaceId, await this.repoDir(workspaceId), user, opts));
+    }
+    /** `push`'s body, for a caller that already holds the workspace's reservation. */
+    async pushUnlocked(workspaceId, cwd, user, opts) {
+        {
             const branch = await this.currentBranch(cwd);
             // Access gate fires only when pushing to a protected branch. Pushing
             // a feature/draft branch to its same-named remote can't change
@@ -1072,7 +1126,7 @@ export class GitService {
                 await this.assertCanWriteAtRef(workspaceId, `origin/${branch}`, user.email, touched);
             }
             await this.git(cwd, ['push', '-u', 'origin', branch]);
-        });
+        }
     }
     // `forcePush` method removed. The workflow layer no longer auto-force-pushes
     // as a recovery — when the cooperative `pull --rebase` + retry can't
@@ -1188,7 +1242,7 @@ export class GitService {
      *
      * Returns the merge commit SHA, or the conflicting paths.
      */
-    async mergeChangeRequest(baseWorkspaceId, sourceBranch, targetBranch, commit, user) {
+    async mergeChangeRequest(baseWorkspaceId, sourceBranch, targetBranch, commit, user, opts = {}) {
         assertValidBranchName(sourceBranch);
         assertValidBranchName(targetBranch);
         assertValidAuthor(user);
@@ -1201,6 +1255,13 @@ export class GitService {
             // unknown" on a clone that lacks it).
             await this.git(cwd, ['config', 'user.name', BOT_NAME]);
             await this.git(cwd, ['config', 'user.email', BOT_EMAIL]);
+            if (opts.requireCleanTarget) {
+                const { stdout: dirty } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
+                const unpushed = await this.hasUnpushedCommitsAt(cwd);
+                if (parsePorcelainZ(dirty).length > 0 || unpushed) {
+                    throw new WorkflowDomainError(`"${targetBranch}" has edits that are not shared yet. Try the merge again once they are saved.`, 409, { kind: 'merge-target-busy', targetBranch });
+                }
+            }
             for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
                 // Explicit destination refspecs, because the two `origin/<branch>`
                 // reads below MUST see the tips this fetch just retrieved. A bare
@@ -1227,6 +1288,14 @@ export class GitService {
                 // discards a prior attempt's state, never real work.
                 await this.git(cwd, ['checkout', targetBranch]);
                 await this.git(cwd, ['reset', '--hard', `origin/${targetBranch}`]);
+                if (opts.authorize) {
+                    // The tip this attempt merges into, and the paths it writes against
+                    // that tip. Re-read every attempt: a retry happens BECAUSE the
+                    // target moved, which can move its roles and its file set too.
+                    const { stdout: targetSha } = await this.git(cwd, ['rev-parse', `origin/${targetBranch}`]);
+                    const changedPaths = await this.prChangedPathsAt(cwd, `origin/${targetBranch}`, `origin/${sourceBranch}`, { forAccessCheck: true });
+                    await opts.authorize({ sha: targetSha.trim(), changedPaths });
+                }
                 // `--no-commit --no-ff` so we author the merge commit as the human and
                 // never fast-forward past the merge record.
                 try {
@@ -1239,7 +1308,7 @@ export class GitService {
                         return { kind: 'conflicts', paths };
                     // Not a conflict — surface the underlying git error so the real cause
                     // (e.g. missing identity, unrelated histories) is diagnosable.
-                    throw new Error(`git merge failed without detectable conflicts: ${redact(err instanceof Error ? err.message : String(err))}`);
+                    throw new Error(`git merge failed without detectable conflicts: ${redactGitToken(err instanceof Error ? err.message : String(err))}`);
                 }
                 // Nothing staged ⇒ base already contains source (empty CR). The base tip
                 // is the "merged" state; report it without an empty commit.
@@ -1409,7 +1478,10 @@ export class GitService {
             const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', rev]);
             return stdout.trim() || null;
         }
-        catch {
+        catch (err) {
+            // Null is "no such rev"; a deadline is not that answer (see GitRunError).
+            if (isGitTimeout(err))
+                throw err;
             return null;
         }
     }
@@ -1626,18 +1698,97 @@ export class GitService {
      * only ever see settled states.
      */
     async hasUnpushedCommits(workspaceId) {
-        return this.mutex.run(workspaceId, async () => {
-            const cwd = await this.repoDir(workspaceId);
-            const branch = await this.currentBranch(cwd);
+        return this.mutex.run(workspaceId, async () => this.hasUnpushedCommitsAt(await this.repoDir(workspaceId)));
+    }
+    /**
+     * `hasUnpushedCommits` without the workspace reservation — for a caller that
+     * already holds one (`mergeChangeRequest`, which has to ask inside the same
+     * reservation as the reset that would discard the answer). Fails closed: a
+     * question that cannot be answered counts as "yes, unpushed".
+     */
+    async hasUnpushedCommitsAt(cwd) {
+        const branch = await this.currentBranch(cwd);
+        try {
+            const { stdout } = await this.git(cwd, [
+                'rev-list', '--count', `refs/remotes/origin/${branch}..HEAD`,
+            ]);
+            return Number(stdout.trim()) > 0;
+        }
+        catch {
+            return true;
+        }
+    }
+    /**
+     * Revert paths in several workspaces and publish the result as ONE git
+     * operation. Every workspace involved is reserved together (`runAll`), and
+     * reading each HEAD, restoring and committing every path, pushing each
+     * branch and — when a step fails — undoing, all happen inside that single
+     * reservation: no other git operation on those workspaces can land between
+     * the HEAD an undo returns to and the commits it undoes.
+     *
+     * - Each workspace's HEAD is read first; one that can't be read throws
+     *   before anything changes.
+     * - Every path in every workspace is restored from its `ref` and committed
+     *   (`subject`) before anything is pushed. A failed restore or commit
+     *   undoes all of them and rethrows: nothing is pushed.
+     * - Branches are then pushed in order. A failed push undoes that workspace
+     *   and every later one and is reported in `failed`; the earlier pushes
+     *   stand, since a remote can't be un-pushed.
+     *
+     * An undo never rewrites history: each touched path is restored from the
+     * HEAD recorded at the start and committed (`undoSubject`), so unpushed work
+     * the checkout already had stays exactly as it was. Each path is undone on
+     * its own, so one that fails doesn't leave the rest reverted.
+     */
+    async revertPathsAndPush(user, plans) {
+        assertValidAuthor(user);
+        for (const plan of plans)
+            for (const entry of plan.paths)
+                assertValidRelativePath(entry.path);
+        return this.mutex.runAll(plans.map((plan) => plan.workspaceId), async () => {
+            const steps = [];
+            for (const plan of plans) {
+                const cwd = await this.repoDir(plan.workspaceId);
+                const { stdout } = await this.git(cwd, ['rev-parse', '--verify', 'HEAD^{commit}']);
+                steps.push({ workspaceId: plan.workspaceId, cwd, head: stdout.trim(), paths: plan.paths });
+            }
+            const undo = async (unpushed) => {
+                for (const step of unpushed) {
+                    for (const entry of step.paths) {
+                        try {
+                            await this.restorePathUnlocked(step.cwd, step.head, entry.path);
+                            await this.commitFileUnlocked(step.workspaceId, step.cwd, user, entry.path, entry.path, entry.undoSubject, true);
+                        }
+                        catch (err) {
+                            log.warn(`undo of ${printable(entry.path)} failed in workspace ${printable(step.workspaceId)}: ${printable(sanitizeError(err))}`);
+                        }
+                    }
+                }
+            };
             try {
-                const { stdout } = await this.git(cwd, [
-                    'rev-list', '--count', `refs/remotes/origin/${branch}..HEAD`,
-                ]);
-                return Number(stdout.trim()) > 0;
+                for (const step of steps) {
+                    for (const entry of step.paths) {
+                        await this.restorePathUnlocked(step.cwd, entry.ref, entry.path);
+                        await this.commitFileUnlocked(step.workspaceId, step.cwd, user, entry.path, entry.path, entry.subject, true);
+                    }
+                }
             }
-            catch {
-                return true;
+            catch (err) {
+                await undo(steps);
+                throw err;
+            }
+            const pushed = [];
+            for (const [i, step] of steps.entries()) {
+                try {
+                    await this.pushUnlocked(step.workspaceId, step.cwd, user);
+                }
+                catch (error) {
+                    await undo(steps.slice(i));
+                    return { pushed, failed: { workspaceId: step.workspaceId, error } };
+                }
+                pushed.push(step.workspaceId);
             }
+            return { pushed, failed: null };
         });
     }
     /**
@@ -1987,8 +2138,8 @@ export class GitService {
         const cwd = await this.repoDir(workspaceId);
         await this.fetchPrRefs(cwd, baseBranch, headBranch);
         return this.mutex.run(workspaceId, async () => {
-            const baseRef = await this.resolveBranchRef(cwd, baseBranch);
-            const headRef = await this.resolveBranchRef(cwd, headBranch);
+            const baseRef = await this.resolvePublishedBranchRef(cwd, baseBranch);
+            const headRef = await this.resolvePublishedBranchRef(cwd, headBranch);
             const [{ stdout: baseSha }, { stdout: headSha }] = await Promise.all([
                 this.git(cwd, ['rev-parse', baseRef]),
                 this.git(cwd, ['rev-parse', headRef]),
@@ -2032,8 +2183,8 @@ export class GitService {
         if (!opts.at)
             await this.fetchPrRefs(cwd, baseBranch, headBranch);
         return this.mutex.run(workspaceId, async () => {
-            const baseRef = opts.at ? opts.at.baseSha : await this.resolveBranchRef(cwd, baseBranch);
-            const headRef = opts.at ? opts.at.headSha : await this.resolveBranchRef(cwd, headBranch);
+            const baseRef = opts.at ? opts.at.baseSha : await this.resolvePublishedBranchRef(cwd, baseBranch);
+            const headRef = opts.at ? opts.at.headSha : await this.resolvePublishedBranchRef(cwd, headBranch);
             const range = `${baseRef}...${headRef}`; // three-dot = changes on head since merge-base
             const [{ stdout: nameStatusOut }, { stdout: numstatOut }] = await Promise.all([
                 this.git(cwd, ['diff', '-M', '-z', '--name-status', range]),
@@ -2048,8 +2199,17 @@ export class GitService {
             // land. Filter it from the review surface entirely; the neutralisation
             // reads the raw refs itself and is unaffected. Both lists are filtered
             // IN STEP so the index-zip below stays aligned.
-            if (statuses.some((s) => s.path === 'roles.yaml')) {
-                const keep = statuses.map((s) => s.path !== 'roles.yaml');
+            // The empty-folder placeholder is filtered the same way: it is never
+            // content, so it is not a file to review or approve. It still merges
+            // with the rest, and `changedPathsForPr` keeps it, so a request that
+            // only creates a folder is not mistaken for an empty one and closed.
+            // An empty file deleted as its folder gets the (equally empty)
+            // placeholder reads to `-M` as a RENAME onto it; the real side of such
+            // a pair is first made the plain removal (or addition) it is, so
+            // dropping the placeholder never drops the file with it.
+            statuses = statuses.map(withoutPlaceholderRename);
+            if (statuses.some((s) => s.path === 'roles.yaml' || isFolderPlaceholder(s.path))) {
+                const keep = statuses.map((s) => s.path !== 'roles.yaml' && !isFolderPlaceholder(s.path));
                 statuses = statuses.filter((_, i) => keep[i]);
                 if (counts.length === keep.length)
                     counts = counts.filter((_, i) => keep[i]);
@@ -2061,7 +2221,7 @@ export class GitService {
             // +/- to a file.
             const aligned = counts.length === statuses.length;
             if (!aligned) {
-                console.warn(`[cr] diff name-status/numstat length mismatch (${statuses.length} vs ${counts.length}) ` +
+                crLog.warn(`diff name-status/numstat length mismatch (${statuses.length} vs ${counts.length}) ` +
                     `for ${range} — reporting file list without +/- counts`);
             }
             const files = statuses.map((s, i) => {
@@ -2095,29 +2255,77 @@ export class GitService {
      * Just the repo-relative paths changed by a change request (three-dot), no
      * patches — the cheap version used to build CR-list summaries and owner
      * routing. `changedFilesForPr` is the full version with statuses + diffs.
+     *
+     * `fetch: false` skips the per-request ref fetch, for a caller that has
+     * ALREADY refreshed the clone's remote-tracking refs — which is the whole
+     * clone in one round trip, against one per request here. A CR list is
+     * exactly that caller: at five open requests the per-request fetch was
+     * measured at ~0.55s each, and the list is re-read on every proposal and
+     * every 60s poll. Only pass it when a fetch of the clone really has just
+     * happened; the refs are otherwise as old as the last one, and the diff
+     * would describe a stale head.
+     *
+     * It is a skip, not a promise never to fetch: a branch this clone has
+     * never heard of is fetched anyway. That case is not a stale diff, it is
+     * NO diff — an empty touched-path set, which is a change request missing
+     * from its own author's tree. Two local `rev-parse`s are worth not being
+     * that.
      */
-    async changedPathsForPr(workspaceId, baseBranch, headBranch) {
+    async changedPathsForPr(workspaceId, baseBranch, headBranch, opts = {}) {
         assertValidBranchName(baseBranch);
         assertValidBranchName(headBranch);
         // Fetch outside the mutex (network round-trip) so origin latency can't hold
         // the workspace lock; the lock guards only the local diff below.
         const cwd = await this.repoDir(workspaceId);
-        await this.fetchPrRefs(cwd, baseBranch, headBranch);
+        // The skip decision and the diff are ONE reading of the refs, not two.
+        // Both are resolved here, to COMMITS, and the commits are what the diff
+        // below runs on — the same pinning `changedFilesForPr`'s `at` does. A
+        // concurrent `fetch --prune origin` (`ensureRemotesFetched` and
+        // `fetchPrRefs` both run outside this mutex, deliberately) can drop a
+        // remote-tracking ref between the two, and re-resolving inside the mutex
+        // would then throw `WorkflowValidationError` — which `touchedPathsFor`
+        // swallows into an empty touched-path set, i.e. exactly the change
+        // request missing from its own author's tree that the skip is guarded
+        // against. The commits stay readable whatever happens to the ref names.
+        const pinned = opts.fetch === false ? await this.publishedPrCommits(cwd, baseBranch, headBranch) : null;
+        if (!pinned) {
+            await this.fetchPrRefs(cwd, baseBranch, headBranch);
+        }
         return this.mutex.run(workspaceId, async () => {
-            const baseRef = await this.resolveBranchRef(cwd, baseBranch);
-            const headRef = await this.resolveBranchRef(cwd, headBranch);
-            const { stdout } = await this.git(cwd, [
-                'diff', '-M', '--name-only', `${baseRef}...${headRef}`,
-            ]);
-            return (stdout
-                .split('\n')
-                .map((s) => s.trim())
-                .filter(Boolean)
+            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);
+        });
+    }
+    /**
+     * The shaping behind `changedPathsForPr`, without its workspace
+     * reservation: the caller must already hold one. `mergeChangeRequest` reads
+     * the same set inside its OWN reservation, where re-entering this one would
+     * deadlock — and where the refs are the ones the merge is actually built on.
+     */
+    async prChangedPathsAt(cwd, baseRef, headRef, opts = {}) {
+        const { stdout } = await this.git(cwd, [
+            'diff', '-M', '-z', '--name-status', `${baseRef}...${headRef}`,
+        ]);
+        // Deduped: both sides of a rename can collide with another entry's path.
+        return [
+            ...new Set(parseNameStatusZ(stdout)
+                // A rename onto or off the placeholder is a real file removed or
+                // added (see `withoutPlaceholderRename`): both of its paths are
+                // touched, or filtering the placeholder would lose the file.
+                //
+                // Authorizing the change needs both sides of EVERY rename, not just
+                // the placeholder's: git reports a rename under its new name alone,
+                // and the old name is a path the change deletes.
+                .flatMap((s) => s.previousPath &&
+                (opts.forAccessCheck || isFolderPlaceholder(s.path) || isFolderPlaceholder(s.previousPath))
+                ? [s.previousPath, s.path]
+                : [s.path])
                 // Same rule as `changedFilesForPr`: a roles.yaml change never
                 // survives a merge, so it is not a touched path for routing or
                 // summaries either.
-                .filter((p) => p !== 'roles.yaml'));
-        });
+                .filter((p) => opts.forAccessCheck || p !== 'roles.yaml')),
+        ];
     }
     /**
      * The merge-base commit of a change request's two branches (their origin
@@ -2131,8 +2339,8 @@ export class GitService {
         const cwd = await this.repoDir(workspaceId);
         await this.fetchPrRefs(cwd, baseBranch, headBranch);
         return this.mutex.run(workspaceId, async () => {
-            const baseRef = await this.resolveBranchRef(cwd, baseBranch);
-            const headRef = await this.resolveBranchRef(cwd, headBranch);
+            const baseRef = await this.resolvePublishedBranchRef(cwd, baseBranch);
+            const headRef = await this.resolvePublishedBranchRef(cwd, headBranch);
             try {
                 const { stdout } = await this.git(cwd, ['merge-base', baseRef, headRef]);
                 return stdout.trim() || null;
@@ -2146,6 +2354,128 @@ export class GitService {
             }
         });
     }
+    /**
+     * Where a change request forked from its target, and whether the target has
+     * moved on since — for the two commits a detail read has ALREADY resolved
+     * (no fetch, no ref resolution, same contract as `changedFilesForPr`'s `at`).
+     *
+     * `mergeBaseSha` is the "before" every file in the request is read against,
+     * so an edit made on the target after the proposal never shows as something
+     * the proposal deletes. `behind` is true when the target holds commits the
+     * proposal does not (`head..base` is non-empty) — the proposal needs
+     * updating before its diff and its eventual merge describe the same text.
+     * No shared history: `mergeBaseSha: null`, and `behind` stays honest (the
+     * target certainly has commits the proposal lacks).
+     */
+    async forkPointForPr(workspaceId, at) {
+        for (const sha of [at.baseSha, at.headSha]) {
+            if (!/^[0-9a-f]{40,64}$/.test(sha)) {
+                throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+            }
+        }
+        const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => {
+            let mergeBaseSha = null;
+            try {
+                const { stdout } = await this.git(cwd, ['merge-base', at.baseSha, at.headSha]);
+                mergeBaseSha = stdout.trim() || null;
+            }
+            catch (err) {
+                // Exit 1 is git's "no common ancestor"; anything else is infra.
+                if (err.exitCode !== 1)
+                    throw err;
+            }
+            const { stdout: count } = await this.git(cwd, [
+                'rev-list', '--count', `${at.headSha}..${at.baseSha}`,
+            ]);
+            return { mergeBaseSha, behind: Number.parseInt(count.trim(), 10) > 0 };
+        });
+    }
+    /**
+     * Every repo-relative path whose content differs between two commits on a
+     * change request's own branch — what an update from the target actually
+     * CHANGED about the proposal.
+     *
+     * Two-dot, because that is the question: not "what does this request
+     * propose" (three-dot, against the target) but "what did the merge move
+     * under the reviewers who already approved". `--no-renames` is what makes
+     * the answer the conservative one: git detects renames BY DEFAULT
+     * (`diff.renames` has been on since 2.9) and then reports only the new
+     * path, which would leave an approval on the path a merge renamed AWAY
+     * reading as untouched. Switched off, a rename reports as the old path
+     * removed and the new one added, so an approval on either side is correctly
+     * read as touched — a path that appears here loses its approval, and only a
+     * path that does not appear keeps it.
+     */
+    async pathsChangedBetween(workspaceId, fromSha, toSha) {
+        for (const sha of [fromSha, toSha]) {
+            if (!/^[0-9a-f]{40,64}$/.test(sha)) {
+                throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+            }
+        }
+        const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => {
+            const { stdout } = await this.git(cwd, [
+                'diff', '--no-renames', '-z', '--name-only', fromSha, toSha,
+            ]);
+            // `-z` terminates each name with NUL, so the trailing field is empty —
+            // and a tracked name may legally carry leading or trailing spaces, so
+            // nothing is trimmed here.
+            return [...new Set(stdout.split('\0').filter((name) => name !== ''))];
+        });
+    }
+    /**
+     * One file as it stood at a change request's fork point — the "before" side
+     * of the request dialog's diff. `sha` must be a commit on the target
+     * branch's published history (`origin/<baseBranch>`); anything else is
+     * refused, so this can never become a read of an arbitrary commit. `null`
+     * means the path did not exist at the fork point (the request adds it).
+     */
+    async readFileAtForkPoint(workspaceId, baseBranch, sha, relativePath) {
+        assertValidBranchName(baseBranch);
+        assertValidRelativePath(relativePath);
+        if (!/^[0-9a-f]{40,64}$/.test(sha)) {
+            throw new WorkflowValidationError(`invalid commit sha: ${sha}`);
+        }
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const baseRef = await this.resolvePublishedBranchRef(cwd, baseBranch);
+            try {
+                await this.git(cwd, ['merge-base', '--is-ancestor', sha, baseRef]);
+            }
+            catch (err) {
+                if (err.exitCode === 1) {
+                    throw new WorkflowDomainError(`That commit is not part of "${baseBranch}" — it is not this request's fork point.`, 404);
+                }
+                throw err;
+            }
+            await this.assertNotTreeAtRef(cwd, sha, repoRelativePath, relativePath);
+            return this.readFileAtRef(workspaceId, sha, repoRelativePath);
+        });
+    }
+    /**
+     * Whether `repoRelativePath` exists (as a file or tree) at `ref`. ONLY
+     * git's own "that path is not at this ref" answer is false; an unresolvable
+     * ref, a timeout, a locked or corrupt repository PROPAGATE — a revert that
+     * read one of those as "absent" would decide wrongly what to restore.
+     */
+    async pathExistsAtRef(workspaceId, ref, repoRelativePath) {
+        assertValidRelativePath(repoRelativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            try {
+                await this.git(cwd, ['cat-file', '-e', `${ref}:${repoRelativePath}`]);
+                return true;
+            }
+            catch (err) {
+                const stderr = err.stderr ?? (err instanceof Error ? err.message : String(err));
+                if (/does not exist in|exists on disk, but not in/.test(stderr))
+                    return false;
+                throw err;
+            }
+        });
+    }
     /**
      * Restore one path in the working tree (and index) to its content at `ref`;
      * a path ABSENT at `ref` is deleted — the revert of an added file is its
@@ -2155,8 +2485,11 @@ export class GitService {
      */
     async restorePathFromRef(workspaceId, ref, repoRelativePath) {
         assertValidRelativePath(repoRelativePath);
-        return this.mutex.run(workspaceId, async () => {
-            const cwd = await this.repoDir(workspaceId);
+        return this.mutex.run(workspaceId, async () => this.restorePathUnlocked(await this.repoDir(workspaceId), ref, repoRelativePath));
+    }
+    /** `restorePathFromRef`'s body, for a caller that already holds the workspace's reservation. */
+    async restorePathUnlocked(cwd, ref, repoRelativePath) {
+        {
             let existsAtRef = true;
             try {
                 await this.git(cwd, ['cat-file', '-e', `${ref}:${repoRelativePath}`]);
@@ -2180,7 +2513,7 @@ export class GitService {
                 // missing from disk is exactly what `git add` records as deleted.
                 await fs.rm(path.join(cwd, repoRelativePath), { force: true });
             }
-        });
+        }
     }
     /** Fetch the two branches a CR spans so origin refs reflect the latest push. */
     async fetchPrRefs(cwd, baseBranch, headBranch) {
@@ -2242,6 +2575,63 @@ export class GitService {
             ? relativePath.slice(this.kbDirName.length + 1)
             : relativePath;
     }
+    /**
+     * The COMMITS both of a change request's branches point at in this clone
+     * already, or null when either is unknown to it — the question behind
+     * `changedPathsForPr`'s `fetch: false`, answered with the resolution itself
+     * so the caller diffs precisely what it decided on. Only git's own "no such
+     * ref" answers null; every other failure is the caller's to see, and
+     * treating it as "not here" would spend a network fetch on a clone that is
+     * broken for some other reason.
+     */
+    async publishedPrCommits(cwd, baseBranch, headBranch) {
+        const shas = [];
+        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;
+            }
+        }
+        return { base: shas[0], head: shas[1] };
+    }
+    /**
+     * `resolveBranchRef` with the preference reversed: the PUBLISHED ref
+     * (`origin/<branch>`, just fetched by `fetchPrRefs`) before the local head.
+     * A change request is a pair of published branches, and a clone's local
+     * copy of the OTHER branch is whatever it was when the clone last touched
+     * it — in a proposal's own workspace the local target is typically the
+     * target as of the fork. Reading that made every request look up to date
+     * and diffed it against a stale target. A local-only branch still resolves.
+     */
+    async resolvePublishedBranchRef(cwd, branch) {
+        return (await this.resolvePublishedBranch(cwd, branch)).ref;
+    }
+    /**
+     * {@link resolvePublishedBranchRef} with the commit it resolved to — the
+     * `rev-parse` that verifies the ref already prints it, so pinning a diff to
+     * the commit costs nothing over naming the ref.
+     */
+    async resolvePublishedBranch(cwd, branch) {
+        for (const ref of [`refs/remotes/origin/${branch}`, `refs/heads/${branch}`]) {
+            try {
+                const { stdout } = await this.git(cwd, ['rev-parse', '--verify', '--quiet', ref]);
+                return { ref, sha: stdout.trim() };
+            }
+            catch (err) {
+                // Only git's own "no such ref" (exit 1 under --quiet) moves on to the
+                // next candidate. A deadline or any other failure is not that answer:
+                // skipping past it would pick the stale local copy, or call a real
+                // branch unknown.
+                if (!(err instanceof GitRunError) || err.timedOut || err.exitCode !== 1)
+                    throw err;
+            }
+        }
+        throw new WorkflowValidationError(`unknown branch: ${branch}`);
+    }
     /**
      * Resolve a branch name to a concrete ref the local clone knows about.
      * Tries the local head first, falls back to the matching remote-tracking
@@ -2291,12 +2681,12 @@ export class GitService {
             }
             const dirtyList = porcelain.stdout.trim().replace(/\s+/g, ' ');
             if (queueExplainsIt) {
-                console.log(`[git] workspace=${workspaceId} branch=${branch} working tree is dirty while ` +
+                log.info(`workspace=${workspaceId} branch=${branch} working tree is dirty while ` +
                     `pending commits drain (expected — the background worker is catching up). ` +
                     `Files: ${dirtyList}`);
             }
             else {
-                console.warn(`[git] workspace=${workspaceId} branch=${branch} has a non-clean working ` +
+                log.warn(`workspace=${workspaceId} branch=${branch} has a non-clean working ` +
                     `tree under save=share with NO queued pending commits — this should never ` +
                     `happen and likely indicates a missed lock-release commit. Files: ${dirtyList}`);
             }
@@ -2419,6 +2809,34 @@ export class GitService {
             throw err;
         }
     }
+    /**
+     * The commits on `ref` that touched `repoRelativePath`, newest first, at
+     * most `limit` of them. What a skill's `version` is looked up through: each
+     * commit is a copy of the file that may have declared a version. Renames are
+     * not followed — a moved skill's earlier history is the old path's.
+     */
+    async pathHistory(workspaceId, ref, repoRelativePath, limit) {
+        const cwd = await this.repoDir(workspaceId);
+        const { stdout } = await this.git(cwd, [
+            'rev-list',
+            `--max-count=${Math.max(1, Math.trunc(limit))}`,
+            ref,
+            '--',
+            repoRelativePath,
+        ]);
+        return stdout.split('\n').map((line) => line.trim()).filter((line) => line.length > 0);
+    }
+    /**
+     * Every file under `folder` at `ref`, repo-root-relative and in tree order.
+     * A folder that does not exist at that ref lists nothing. NUL-delimited, so
+     * a non-ASCII name comes back as itself rather than C-quoted, and one with
+     * a leading or trailing space keeps it.
+     */
+    async listFilesAtRef(workspaceId, ref, folder) {
+        const cwd = await this.repoDir(workspaceId);
+        const { stdout } = await this.git(cwd, ['ls-tree', '-r', '-z', '--name-only', ref, '--', folder]);
+        return stdout.split('\0').filter((line) => line.length > 0);
+    }
     /**
      * A clean `git status` for a path has two honest readings (already
      * committed; a queued re-apply of something that landed) and one dishonest
@@ -2460,58 +2878,32 @@ export class GitService {
         ]);
         return stdout.trim().length > 0;
     }
-    async git(cwd, args, opts) {
-        try {
-            const pending = execFileAsync('git', args, {
-                cwd,
-                // `GIT_LITERAL_PATHSPECS=1` makes git treat every pathspec literally
-                // instead of interpreting `[`, `]`, `*`, `?`, `!`, or `:(magic)` as
-                // glob / magic syntax. KB files routinely arrive with bracketed
-                // prefixes like `[Approved] foo.docx` or `[Updated 2025] bar.md`; the
-                // upload pipeline (`writeFileBinary` + `releaseLock` + `commitFile`)
-                // passes the relative path straight through to `git add` / `git
-                // checkout -- <path>`, which would otherwise glob and either match the
-                // wrong file or no file at all. Setting it once here covers every git
-                // subprocess this service spawns.
-                //
-                // `LC_ALL=C` / `LANG=C` force git's human-readable output (including
-                // stderr) to stable, English, locale-independent text. Callers that
-                // classify errors by message — e.g. `readFileAtRef` distinguishing a
-                // "path does not exist in <ref>" absence from a hard failure — would
-                // otherwise misread a translated message on a non-English host and, for
-                // the fail-closed roles.yaml preservation path, fail OPEN.
-                env: { ...process.env, GIT_LITERAL_PATHSPECS: '1', LC_ALL: 'C', LANG: 'C' },
-                maxBuffer: 32 * 1024 * 1024,
-            });
-            if (opts?.input !== undefined && pending.child.stdin) {
-                // A dying git can close stdin mid-write; the promise below still
-                // rejects with the exit code, which is the error we want to surface.
-                pending.child.stdin.on('error', () => undefined);
-                pending.child.stdin.write(opts.input);
-                pending.child.stdin.end();
-            }
-            const { stdout, stderr } = await pending;
-            return { stdout: stdout.toString(), stderr: stderr.toString() };
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            // Skip past any leading `-c key=val` pairs so the error names the actual
-            // git subcommand that failed (e.g. "git fetch failed:" not "git -c failed:").
-            let i = 0;
-            while (i < args.length && args[i] === '-c')
-                i += 2;
-            const subcommand = args[i] ?? args[0];
-            const wrapped = new Error(`git ${subcommand} failed: ${redact(msg)}`);
-            // Preserve the underlying exit code / stderr so callers can distinguish
-            // expected non-zero exits (e.g. merge-base exit 1 = no common ancestor)
-            // from infra failures (ENOENT, exit 128) without parsing message strings.
-            const original = err;
-            if (typeof original.code === 'number')
-                wrapped.exitCode = original.code;
-            if (typeof original.stderr === 'string')
-                wrapped.stderr = redact(original.stderr);
-            throw wrapped;
-        }
+    /**
+     * Every git invocation this service makes goes through here, and from here
+     * through the injected runner — which is what puts a deadline on it. The
+     * environment, the buffer ceiling, the stdin handling and the error shape all
+     * live in `NodeGitRunner` now; see `shared/git.contract.ts` for why.
+     *
+     * Errors arrive as `GitRunError`, which still carries `exitCode` and
+     * `stderr`, so the callers that read those to tell an expected non-zero exit
+     * from a real failure are unaffected.
+     */
+    git(cwd, args, opts) {
+        return this.gitRunner.run(cwd, args, {
+            ...opts,
+            // `GIT_LITERAL_PATHSPECS=1` makes git treat every pathspec literally
+            // instead of interpreting `[`, `]`, `*`, `?`, `!`, or `:(magic)` as glob
+            // / magic syntax. KB files routinely arrive with bracketed prefixes like
+            // `[Approved] foo.docx` or `[Updated 2025] bar.md`; the upload pipeline
+            // (`writeFileBinary` + `releaseLock` + `commitFile`) passes the relative
+            // path straight through to `git add` / `git checkout -- <path>`, which
+            // would otherwise glob and either match the wrong file or no file at all.
+            //
+            // THIS service's setting, not the runner's: the startup runner spells its
+            // literal paths as `:(literal)<path>`, which this variable would turn into
+            // a search for a file literally named that.
+            env: { GIT_LITERAL_PATHSPECS: '1', ...opts?.env },
+        });
     }
 }
 /** Map a git status letter (`git diff --name-status`) to the DTO's `PrFileStatus`. */
@@ -2559,6 +2951,24 @@ export function parseNameStatusZ(out) {
     }
     return entries;
 }
+/**
+ * Undo a rename git detected between a real file and the empty-folder
+ * placeholder. Deleting a folder's last file writes the placeholder, and
+ * when that file was empty too, `-M` pairs the two as a 100% rename. The
+ * pair is really a removal (or, the other way round, an addition) plus the
+ * placeholder, which is never reviewed — so the entry becomes the real side
+ * alone, and the caller's placeholder filter has nothing of it to drop.
+ */
+export function withoutPlaceholderRename(entry) {
+    const { previousPath } = entry;
+    if (!previousPath || entry.status !== 'renamed')
+        return entry;
+    const toPlaceholder = isFolderPlaceholder(entry.path);
+    const fromPlaceholder = isFolderPlaceholder(previousPath);
+    if (toPlaceholder === fromPlaceholder)
+        return entry;
+    return toPlaceholder ? { status: 'removed', path: previousPath } : { status: 'added', path: entry.path };
+}
 /**
  * Parse `git diff -M -z --numstat` output, in the SAME file order as
  * `--name-status` (both driven by `-M` over the same range). Each record is