@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,1987 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { AccessDeniedError } from '../../access/access-errors.js';
+import { WorkspaceMutex } from './mutex.js';
+import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from './clone-config.js';
+import { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isProtectedBranch, PROTECTED_BRANCHES, } from './branch-name.js';
+import { BranchAuthorshipError, WorkflowValidationError, ProtectedBranchError, } from '../workflow.errors.js';
+const execFileAsync = promisify(execFile);
+function redact(msg) {
+    const token = process.env.GITHUB_TOKEN;
+    return token ? msg.replaceAll(token, '***') : msg;
+}
+/**
+ * Fallback committer identity. Every workflow commit overrides the author via
+ * `--author=…` so the real human shows up in `git log`; this is just the
+ * committer git records need. Mirrors the value `WorkspaceService` stamps on
+ * each clone — set again where an operation must not depend on that ambient
+ * config (e.g. the merge below).
+ */
+const BOT_NAME = 'Bevel Workflow';
+const BOT_EMAIL = 'bevel-workflow@bevel.software';
+/**
+ * Git parses `--author="Name <email>"` by scanning for the last `<` and `>` and
+ * taking everything before the `<` as the name. Stray angle brackets, newlines, or
+ * carriage returns in either field break that parser or let a caller forge a
+ * different author line. Reject rather than try to escape.
+ */
+/**
+ * Parse the NUL-delimited output of `git status --porcelain=v1 -z` into a
+ * deduplicated list of paths the next commit would include. For a rename /
+ * copy entry the record spans two NUL-separated fields (new-path, old-path);
+ * we keep the new path and discard the old one.
+ */
+export function parsePorcelainZ(stdout) {
+    const tokens = stdout.split('\0').filter((t) => t.length > 0);
+    const paths = new Set();
+    let i = 0;
+    while (i < tokens.length) {
+        const token = tokens[i];
+        // Every entry is "XY <path>" — 2 status chars, a space, then the path.
+        if (token.length < 4) {
+            i++;
+            continue;
+        }
+        const x = token[0];
+        const y = token[1];
+        paths.add(token.slice(3));
+        // Rename or copy in either the index or worktree position carries an
+        // extra NUL-separated old-path field we must skip.
+        i += (x === 'R' || x === 'C' || y === 'R' || y === 'C') ? 2 : 1;
+    }
+    return Array.from(paths);
+}
+/**
+ * Default commit subject used when a caller (typically `LockingFilesystem`'s
+ * auto-commit on lock release) doesn't supply one. Must stay within the 200-
+ * char subject limit enforced just below — deep KB paths can themselves exceed
+ * 200 chars, so a naive `Update <path>` would trip the validator and the
+ * release would propagate the error back to the agent's tool call. Fall back
+ * to the basename, then hard-truncate as a last resort.
+ */
+function buildDefaultCommitSummary(repoRelativePath) {
+    const full = `Update ${repoRelativePath}`;
+    if (full.length <= 200)
+        return full;
+    const basename = repoRelativePath.split('/').pop() ?? repoRelativePath;
+    const basenameSummary = `Update ${basename}`;
+    if (basenameSummary.length <= 200)
+        return basenameSummary;
+    return basenameSummary.slice(0, 199) + '…';
+}
+function assertValidAuthor(user) {
+    if (!user.name || !user.email) {
+        throw new WorkflowValidationError('commit author name and email are required');
+    }
+    if (/[\r\n<>]/.test(user.name)) {
+        throw new WorkflowValidationError('commit author name contains invalid characters');
+    }
+    if (/[\r\n<>\s]/.test(user.email) || !/^[^@\s]+@[^@\s]+$/.test(user.email)) {
+        throw new WorkflowValidationError('commit author email is not a valid address');
+    }
+}
+/**
+ * Cheap binary heuristic. Git's own `diff` treats a file as binary if it sees a
+ * NUL byte in the first ~8KB, and the same rule works here: text files don't
+ * contain NULs, binary formats almost always do early in the file.
+ */
+function looksBinary(buf) {
+    const sample = buf.subarray(0, Math.min(buf.length, 8192));
+    return sample.indexOf(0) !== -1;
+}
+/**
+ * Matches `git diff`'s output for adding a new binary file — the UI just
+ * echoes the patch text, so this header renders as a neutral "can't preview"
+ * notice without needing special-case rendering in DiffView.
+ */
+function synthesizeBinaryAddDiff(relativePath) {
+    return [
+        `diff --git a/${relativePath} b/${relativePath}`,
+        'new file mode 100644',
+        `Binary files /dev/null and b/${relativePath} differ`,
+        '',
+    ].join('\n');
+}
+/**
+ * Produce a unified diff resembling `git diff --no-index /dev/null <path>` output
+ * so the UI can render an untracked file as "all added" using the same DiffView
+ * it uses for committed changes. No mode detection — new files get 100644.
+ */
+function synthesizeNewFileDiff(relativePath, contents) {
+    const header = [
+        `diff --git a/${relativePath} b/${relativePath}`,
+        'new file mode 100644',
+        '--- /dev/null',
+        `+++ b/${relativePath}`,
+    ].join('\n');
+    if (contents === '')
+        return `${header}\n`;
+    const endsWithNewline = contents.endsWith('\n');
+    // Drop the trailing empty string `split` introduces when the file ends with a newline
+    // so the line count matches what git itself would report in the hunk header.
+    const body = endsWithNewline ? contents.slice(0, -1) : contents;
+    const lines = body.split('\n');
+    const hunk = `@@ -0,0 +1,${lines.length} @@`;
+    const bodyText = lines.map((l) => `+${l}`).join('\n');
+    const trailer = endsWithNewline ? '' : '\n\';
+    return `${header}\n${hunk}\n${bodyText}${trailer}\n`;
+}
+/** Mirror of {@link synthesizeBinaryAddDiff} for the removed direction. */
+function synthesizeBinaryRemoveDiff(relativePath) {
+    return [
+        `diff --git a/${relativePath} b/${relativePath}`,
+        'deleted file mode 100644',
+        `Binary files a/${relativePath} and /dev/null differ`,
+        '',
+    ].join('\n');
+}
+/** Mirror of {@link synthesizeNewFileDiff} for when the working-tree file sits on the "from" side. */
+function synthesizeDeletedFileDiff(relativePath, contents) {
+    const header = [
+        `diff --git a/${relativePath} b/${relativePath}`,
+        'deleted file mode 100644',
+        `--- a/${relativePath}`,
+        '+++ /dev/null',
+    ].join('\n');
+    if (contents === '')
+        return `${header}\n`;
+    const endsWithNewline = contents.endsWith('\n');
+    const body = endsWithNewline ? contents.slice(0, -1) : contents;
+    const lines = body.split('\n');
+    const hunk = `@@ -1,${lines.length} +0,0 @@`;
+    const bodyText = lines.map((l) => `-${l}`).join('\n');
+    const trailer = endsWithNewline ? '' : '\n\';
+    return `${header}\n${hunk}\n${bodyText}${trailer}\n`;
+}
+/**
+ * Synthesize a diff for an untracked working-tree file when the current branch
+ * is one side of a branch-vs-branch comparison. `direction` says which side the
+ * working tree sits on: 'added' = working tree is the "to" side (all `+`),
+ * 'removed' = working tree is the "from" side (all `-`).
+ */
+async function synthesizeUntrackedSideDiff(cwd, relativePath, direction) {
+    try {
+        const buf = await fs.readFile(path.join(cwd, relativePath));
+        if (looksBinary(buf)) {
+            return direction === 'added'
+                ? synthesizeBinaryAddDiff(relativePath)
+                : synthesizeBinaryRemoveDiff(relativePath);
+        }
+        const text = buf.toString('utf8');
+        return direction === 'added'
+            ? synthesizeNewFileDiff(relativePath, text)
+            : synthesizeDeletedFileDiff(relativePath, text);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return '';
+        throw err;
+    }
+}
+export class GitService {
+    workspaceService;
+    hooks;
+    kbDirName;
+    mutex;
+    accessControl;
+    // 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
+    // run alongside checkout/status/commit. Holding the mutex during a network
+    // round-trip used to park every other git op behind a slow origin (the
+    // worst case for branch-switching UX).
+    fetchLocks = new Map();
+    lastImplicitFetchAt = 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
+    // concurrent processes worst case — fast for typical (<8) feature-branch
+    // counts, calm under large branch lists.
+    static MAX_AHEAD_BEHIND_CONCURRENCY = 8;
+    constructor(workspaceService, 
+    /**
+     * Workflow lifecycle hooks. This service only consults the ADVISORY
+     * `commitValidation` hooks (registered by the enterprise kb module in the
+     * composition root — the constructor-injected `IKbValidator` this
+     * 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) {
+        this.workspaceService = workspaceService;
+        this.hooks = hooks;
+        this.kbDirName = kbDirName;
+        this.mutex = mutex;
+        this.accessControl = accessControl;
+    }
+    /**
+     * "Does the pending-commits queue hold rows for this workspace?" — used by
+     * `statusInternal` to tell an expected dirty tree (queued saves still
+     * draining) from a genuinely orphaned one. Injected as a narrow probe via
+     * setter (not constructor) because the queue service is constructed after
+     * this one in the composition root; `null` (e.g. in tests) keeps the old
+     * always-warn behavior.
+     */
+    pendingCommitsProbe = null;
+    setPendingCommitsProbe(probe) {
+        this.pendingCommitsProbe = probe;
+    }
+    /**
+     * Mark a workspace as freshly fetched. Called by `WorkspaceService` right
+     * after a branch's clone is created — `git clone` already downloaded every
+     * ref, so the first `listBranches` can skip the redundant implicit
+     * `git fetch` (see `fetchOriginIfStale`).
+     */
+    noteWorkspaceFetched(workspaceId) {
+        this.lastImplicitFetchAt.set(workspaceId, Date.now());
+    }
+    /**
+     * Run the registered ADVISORY commit-validation hooks at a commit site.
+     * Preserves the semantics of the injected validator this replaced: a
+     * `mustFix` report is logged (via `formatWarning`) but never blocks, and a
+     * hook that throws is caught and logged — we'd rather land the commit than
+     * refuse the save because a validator crashed. Each hook gets its own
+     * try/catch so one crashing hook can't silence another.
+     */
+    async runCommitValidationHooks(ctx, formatWarning) {
+        for (const hook of this.hooks.commitValidationHooks()) {
+            try {
+                const report = await hook(ctx);
+                if (report && report.mustFix.length > 0) {
+                    console.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);
+            }
+        }
+    }
+    /**
+     * Resolve write permission for a list of repo-relative paths against the
+     * access tree at a specific ref. Throws `AccessDeniedError` for the first
+     * path the caller lacks `write` on, with the eligible-roles + users
+     * payload attached so the frontend can render a useful refusal message.
+     *
+     * Always uses an at-ref lookup (never the working tree) so a user can't
+     * grant themselves access by editing `roles.yaml` / `access.md` locally.
+     * Callers pass:
+     *   - `HEAD` for commit / revert gates — the pre-operation state is the
+     *     authoritative source for whether the user can write these paths.
+     *   - `origin/<branch>` for push gates — the published state is the
+     *     authoritative source; local rebases or commit-tree manipulation
+     *     can't slip changes past this check.
+     *
+     * Bootstrap: if the ref doesn't carry usable config (no `roles.yaml` /
+     * malformed / first commit creating the system), `canWriteBatchAtRef`
+     * returns null and we treat that as "no rules in force yet" → allow.
+     * Once config exists at the ref, gating kicks in.
+     *
+     * `accessControl` is optional on the constructor so existing tests that
+     * don't exercise these paths can keep their stub WorkspaceService — when
+     * it's null we skip the check entirely (legacy behaviour, only the
+     * branch-name guards remain). Production wires it up via composition root.
+     */
+    async assertCanWriteAtRef(workspaceId, ref, userEmail, paths) {
+        if (!this.accessControl || paths.length === 0)
+            return;
+        const result = await this.accessControl.canWriteBatchAtRef(workspaceId, ref, userEmail, paths);
+        if (!result)
+            return; // bootstrap: no config at ref → default-allow
+        for (const p of paths) {
+            if (!result.get(p)) {
+                const eligible = await this.accessControl.eligibleWritersAtRef(workspaceId, ref, p);
+                throw new AccessDeniedError({
+                    path: p,
+                    eligibleRoles: eligible?.roles ?? [],
+                    eligibleUsers: eligible?.users ?? [],
+                });
+            }
+        }
+    }
+    async status(workspaceId) {
+        return this.mutex.run(workspaceId, () => this.statusInternal(workspaceId));
+    }
+    async listBranches(workspaceId, opts = {}) {
+        const cwd = await this.repoDir(workspaceId);
+        // Run the fetch BEFORE entering the mutex so a slow origin can't block
+        // local-only git ops (checkout/status) on this workspace. The fetch has
+        // its own per-workspace lock + TTL, so concurrent listBranches callers
+        // share a single in-flight fetch instead of stacking up. `freshFetch`
+        // 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);
+        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
+            // target-company-state and every draft pushed by another user.
+            const { stdout } = await this.git(cwd, [
+                'for-each-ref',
+                '--format=%(refname:short)%09%(refname)',
+                'refs/heads',
+                'refs/remotes/origin',
+            ]);
+            const buckets = new Map();
+            for (const line of stdout.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const tab = trimmed.indexOf('\t');
+                if (tab < 0)
+                    continue;
+                const rawShort = trimmed.slice(0, tab);
+                const ref = trimmed.slice(tab + 1);
+                if (!rawShort || !ref)
+                    continue;
+                // Skip symbolic refs up-front. Different git versions report
+                // `refs/remotes/origin/HEAD` as either `origin` (older) or `origin/HEAD`
+                // (modern) for `refname:short`, and a literal `HEAD` ref can also
+                // appear under `refs/heads/` in pathological repos.
+                if (rawShort === 'HEAD' || rawShort === 'origin' || rawShort === 'origin/HEAD')
+                    continue;
+                const isLocal = ref.startsWith('refs/heads/');
+                const shortName = isLocal ? rawShort : rawShort.replace(/^origin\//, '');
+                if (!shortName)
+                    continue;
+                // Final guard: the strip above turns `origin/HEAD` into `HEAD`. Even
+                // if a future git version lands us here, don't bucket it as a branch.
+                if (shortName === 'HEAD')
+                    continue;
+                const existing = buckets.get(shortName);
+                if (!existing) {
+                    buckets.set(shortName, {
+                        shortName,
+                        ref,
+                        hasLocal: isLocal,
+                        hasRemote: !isLocal,
+                    });
+                    continue;
+                }
+                // Prefer the local entry's ref when both exist — ahead/behind against the
+                // configured upstream is more meaningful than against origin directly.
+                if (isLocal && !existing.hasLocal) {
+                    existing.ref = ref;
+                    existing.hasLocal = true;
+                }
+                else if (!isLocal) {
+                    existing.hasRemote = true;
+                }
+            }
+            const rows = Array.from(buckets.values()).sort((a, b) => {
+                if (a.hasLocal !== b.hasLocal)
+                    return a.hasLocal ? -1 : 1;
+                return a.shortName.localeCompare(b.shortName);
+            });
+            // Compute ahead/behind for every branch with bounded concurrency — each
+            // branch is 1–3 `git rev-list` spawns, and the unbounded `Promise.all`
+            // we used before could put N×3 processes in flight on repos with many
+            // branches. Workers pull indices off a shared counter and write into a
+            // pre-sized array, so input order (and the sort above) is preserved.
+            const infos = new Array(rows.length);
+            let nextIndex = 0;
+            const workerCount = Math.min(GitService.MAX_AHEAD_BEHIND_CONCURRENCY, rows.length);
+            await Promise.all(Array.from({ length: workerCount }, async () => {
+                while (true) {
+                    const i = nextIndex++;
+                    if (i >= rows.length)
+                        return;
+                    const row = rows[i];
+                    const { ahead, behind } = await this.aheadBehindForBranch(cwd, row.shortName, row.ref, row.hasLocal);
+                    infos[i] = {
+                        name: row.shortName,
+                        isProtected: isProtectedBranch(row.shortName),
+                        ahead,
+                        behind,
+                        hasRemote: row.hasRemote,
+                    };
+                }
+            }));
+            return infos;
+        });
+    }
+    /**
+     * Run `git fetch --prune origin` outside the workspace mutex, with a short
+     * TTL so back-to-back callers (mount + dropdown-open + 30s poll) coalesce
+     * 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.
+     *
+     * 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;
+        const inFlight = this.fetchLocks.get(workspaceId);
+        if (inFlight) {
+            // Another caller is already fetching for this workspace — share its
+            // result rather than firing a redundant network round-trip. Awaiting
+            // the same promise also means subsequent listBranches calls see the
+            // newly fetched refs.
+            await inFlight;
+            return;
+        }
+        const runFetch = async () => {
+            try {
+                // http.lowSpeedLimit/Time abort the fetch if the transfer stalls below
+                // 1KB/s for 10 seconds — prevents a hung origin from parking us
+                // forever and starving the TTL refresh.
+                await this.git(cwd, [
+                    '-c', 'http.lowSpeedLimit=1000',
+                    '-c', 'http.lowSpeedTime=10',
+                    // This driver runs OUTSIDE the workspace mutex (see the caller), so
+                    // it may only run the safe implicit-fetch shape — see
+                    // `SAFE_IMPLICIT_FETCH_ARGS` in `clone-config.ts` for the rationale.
+                    ...SAFE_IMPLICIT_FETCH_ARGS,
+                ]);
+                this.lastImplicitFetchAt.set(workspaceId, Date.now());
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.warn(`[git] 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.
+                this.lastImplicitFetchAt.set(workspaceId, Date.now());
+            }
+        };
+        const p = runFetch();
+        this.fetchLocks.set(workspaceId, p);
+        try {
+            await p;
+        }
+        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
+            // somehow swapped a different promise in.
+            if (this.fetchLocks.get(workspaceId) === p) {
+                this.fetchLocks.delete(workspaceId);
+            }
+        }
+    }
+    async createBranch(workspaceId, name, fromBase) {
+        assertValidBranchName(name);
+        if (isProtectedBranch(name)) {
+            throw new ProtectedBranchError(name, 'creating a protected branch');
+        }
+        if (fromBase)
+            assertValidBranchName(fromBase);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // With no fromBase, git branches from HEAD — i.e. whichever branch the
+            // user has currently checked out.
+            const args = fromBase ? ['branch', name, fromBase] : ['branch', name];
+            await this.git(cwd, args);
+            // Publish to origin immediately. The per-branch workspace bootstrap
+            // (`WorkspaceService.getOrCreateForBranch`) shells out to
+            // `git clone -b <name>` against origin — without this push the next
+            // navigation to the new draft's URL fails with
+            // "Remote branch <name> not found in upstream origin". Roll the local
+            // ref back on failure so a retry isn't blocked by "branch already exists".
+            try {
+                await this.git(cwd, ['push', '-u', 'origin', name]);
+            }
+            catch (err) {
+                await this.git(cwd, ['branch', '-D', name]).catch(() => undefined);
+                throw err;
+            }
+            const { ahead, behind } = await this.aheadBehindForBranch(cwd, name, `refs/heads/${name}`, true);
+            // Drop the now-vestigial local head. Under the per-branch workspace model
+            // this clone's identity is its OWN branch; the new draft lives in its own
+            // workspace (cloned from origin on first navigation), so this clone never
+            // checks `name` out again. Leaving a local `refs/heads/<name>` here means
+            // that when the draft is later deleted from a DIFFERENT workspace (which
+            // removes it from origin and from that clone), this clone's local head
+            // survives `fetch --prune` — `prune` only drops remote-tracking refs — and
+            // the draft resurfaces in the picker as a phantom orphan that "won't
+            // delete". Removing it now keeps the draft as a pure remote-tracking ref,
+            // which prune cleans up like any other. The push already published it to
+            // origin, so the BranchInfo below still reports `hasRemote: true`.
+            await this.git(cwd, ['branch', '-D', name]).catch(() => undefined);
+            // `isCurrent` removed from BranchInfo with the per-branch workspace
+            // migration — the workspace's identity IS the current branch, so
+            // consumers derive it from the workspaceId. No need to call
+            // `currentBranch(cwd)` here anymore either.
+            return {
+                name,
+                isProtected: false,
+                ahead,
+                behind,
+                hasRemote: true,
+            };
+        });
+    }
+    // `switchBranch` removed. Under the per-branch workspace model
+    // (`workspaces/<encodeURIComponent(branch)>/`) the active branch IS the
+    // workspace's identity — there is no "check out a different branch on this
+    // workspace's clone" operation. Switching branches in the UI navigates to
+    // a different workspace; the destination workspace's clone is already on
+    // its branch by construction (`WorkspaceService.getOrCreateForBranch`).
+    //
+    // Two consequences:
+    //   - The legacy `DirtyWorkingTreeError` gate this method used to throw
+    //     can no longer surface as a user-facing 409.
+    //   - The diff-backup reseed that used to fire here is unnecessary: a
+    //     fresh per-branch workspace gets its backup seeded by the workspace
+    //     bootstrap path, not by a branch switch on an existing one.
+    async deleteBranch(workspaceId, name, user, opts = {}) {
+        assertValidBranchName(name);
+        if (isProtectedBranch(name)) {
+            throw new ProtectedBranchError(name, 'deleting a protected branch');
+        }
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const current = await this.currentBranch(cwd);
+            if (current === name) {
+                throw new WorkflowValidationError(`Cannot delete "${name}" while it's the checked-out branch.`);
+            }
+            if (opts.onlyIfNoRemote) {
+                // Legacy orphan-cleanup path (PR merged + remote head pruned). Skip
+                // the authorship check — callers prune any orphan they encounter,
+                // not just their own — but keep the "refuse if origin still has the
+                // ref" safety: a present remote means the branch is still live.
+                if (await this.refExists(cwd, `refs/remotes/origin/${name}`)) {
+                    throw new WorkflowValidationError(`Branch "${name}" still exists on origin — refusing to auto-prune.`);
+                }
+            }
+            else {
+                // Authored-or-admin delete path. The branch's author (per the
+                // `<email-localpart>/...` naming convention — see `isBranchAuthoredBy`)
+                // can always delete their own draft. Admins (per the workspace's
+                // `roles.yaml`) can additionally clean up anyone's branch, including
+                // unprefixed CLI branches like `fix/...` that have no recognisable
+                // author. We detect admin via `canWrite(_, _, 'roles.yaml')` because
+                // that predicate is the existing source of truth for `Admin`-role
+                // membership inside the access model — no separate `isAdmin()` plumbing
+                // needed.
+                const isAuthor = isBranchAuthoredBy(name, user.email);
+                const isAdmin = this.accessControl
+                    ? await this.accessControl.canWrite(workspaceId, user.email, 'roles.yaml')
+                    : false;
+                if (!isAuthor && !isAdmin) {
+                    throw new BranchAuthorshipError(name);
+                }
+            }
+            // Local delete. `-D` force-deletes even if the branch isn't "fully
+            // merged" from git's POV — squash-merged PRs leave a local branch whose
+            // commits don't appear on origin/<base> verbatim, but the changes are
+            // in fact merged. Force is the right default for our workflow.
+            //
+            // Skip when no local ref exists — the picker can surface branches that
+            // exist only as `refs/remotes/origin/<name>` (the user hasn't worked on
+            // them locally), and "discard from origin" must still work for those.
+            if (await this.refExists(cwd, `refs/heads/${name}`)) {
+                await this.git(cwd, ['branch', '-D', name]);
+            }
+            // Remote delete. Skip in `onlyIfNoRemote` mode (the contract is
+            // local-only cleanup) and skip when there's no remote ref to delete.
+            // A push failure here surfaces to the caller — the local ref is
+            // already gone, and we don't try to resurrect it because rolling back
+            // a "merged-into-the-deleted-branch" local commit would be even more
+            // confusing than the half-finished state.
+            if (!opts.onlyIfNoRemote
+                && await this.refExists(cwd, `refs/remotes/origin/${name}`)) {
+                await this.git(cwd, ['push', 'origin', '--delete', name]);
+            }
+        });
+    }
+    /**
+     * True iff the given ref (e.g. `refs/heads/foo`, `refs/remotes/origin/foo`)
+     * exists in this workspace's clone. Wraps `git show-ref --verify --quiet`
+     * — exits 0 when the ref is present, 1 with no stderr when it's missing.
+     * Any other exit code / stderr means a real failure and is rethrown so
+     * "ref not found" can't silently mask filesystem / repo corruption.
+     *
+     * `this.git()` wraps execFile failures and stores the original exit code on
+     * `wrapped.exitCode` (not `.code`) — check the wrapped property name, or
+     * the "ref not found" path silently becomes "rethrow every show-ref error".
+     */
+    async refExists(cwd, ref) {
+        try {
+            await this.git(cwd, ['show-ref', '--verify', '--quiet', ref]);
+            return true;
+        }
+        catch (err) {
+            const exitCode = err?.exitCode;
+            const stderr = err?.stderr ?? '';
+            const refNotFound = exitCode === 1 && stderr.trim() === '';
+            if (refNotFound)
+                return false;
+            throw err;
+        }
+    }
+    // `forkCurrentToDraft` removed: under the per-branch workspace model, every
+    // branch IS its own workspace by construction. The "stuck on protected
+    // branch with dirty edits" escape hatch this method implemented can no
+    // longer occur — save=share auto-commits each write, and the user can
+    // never end up with uncommitted work that needs to be carried onto a new
+    // draft. Creating a draft is just `createBranch` + URL navigation to the
+    // new branch's workspace.
+    // `discardChanges` removed: under save=share, the working tree is never
+    // dirty by design — every write goes through `LockingFilesystem`, which
+    // auto-commits on lock release. There's nothing to discard. The method
+    // was only meaningful when users could accumulate uncommitted edits
+    // between explicit save actions.
+    async commit(workspaceId, user, req) {
+        const subject = req.summary?.trim();
+        if (!subject)
+            throw new WorkflowValidationError('commit summary is required');
+        if (subject.length > 200) {
+            throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
+        }
+        if (subject.includes('\n')) {
+            throw new WorkflowValidationError('commit summary must be a single line');
+        }
+        assertValidAuthor(user);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const branch = await this.currentBranch(cwd);
+            // One-change-per-file invariant from PLAN.md: each commit must touch
+            // exactly one path. Empty folders are represented via `.gitkeep`, so
+            // "creating a folder" is also one file. We compute the touched set
+            // unconditionally (the protected-branch gate below reuses it) and
+            // refuse anything other than exactly one path before any access
+            // check runs — keeps the error message stable across permission
+            // outcomes.
+            const { stdout: porcelain } = await this.git(cwd, [
+                'status', '--porcelain=v1', '-z',
+            ]);
+            const touched = parsePorcelainZ(porcelain);
+            if (touched.length === 0) {
+                throw new WorkflowValidationError('No pending changes to commit', {
+                    kind: 'no-pending-changes',
+                });
+            }
+            if (touched.length > 1) {
+                throw new WorkflowValidationError(`Each change must affect exactly one file. ${touched.length} files are currently pending: ${touched.join(', ')}. Commit them one at a time.`, { kind: 'too-many-files-dirty', paths: touched });
+            }
+            // Gate by access-control rules — but ONLY on protected branches.
+            // Feature/draft branches are free-for-all: anyone can commit anything
+            // because nothing canonical changes until a CR merges, and the CR's
+            // approval gate (`origin/<base>` access tree) is the real security
+            // boundary. Without this guard, the standard "fork to draft then
+            // propose" workflow would 403 for non-admins — they can't write
+            // protected, can't write the draft they forked from it either.
+            if (isProtectedBranch(branch)) {
+                // Gate against the access tree as it exists at HEAD — the pre-commit
+                // state. Reading from the working tree would let the user broaden
+                // their own access by editing access.md alongside the change they're
+                // trying to push through.
+                await this.assertCanWriteAtRef(workspaceId, 'HEAD', user.email, touched);
+            }
+            // Validation is **advisory**, not a gate. We still run the registered
+            // commit-validation hooks (the report surfaces in logs + can drive UI
+            // warnings later), but a `mustFix` result no longer blocks the commit —
+            // the user's right to save their work shouldn't depend on the rest of
+            // the KB being clean.
+            await this.runCommitValidationHooks({ workspaceId, branch, paths: touched }, (report) => `[git] commit on workspace=${workspaceId} branch=${branch} landing with ${report.mustFix.length} unresolved KB validator issue(s); the editor surfaces them but commit is no longer blocked.`);
+            await this.git(cwd, ['add', '-A']);
+            const args = [
+                'commit',
+                `--author=${user.name} <${user.email}>`,
+                '-m',
+                subject,
+            ];
+            if (req.description && req.description.trim()) {
+                args.push('-m', req.description.trim());
+            }
+            await this.git(cwd, args);
+            const { stdout } = await this.git(cwd, [
+                'log',
+                '-1',
+                '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+            ]);
+            const [sha, authorName, authorEmail, subj, committedAt] = stdout.split('\x00');
+            // The commit may have changed roles.yaml or access.md — drop cached state.
+            this.accessControl?.invalidate(workspaceId);
+            return {
+                sha: sha?.trim() ?? '',
+                authorName: authorName ?? '',
+                authorEmail: authorEmail ?? '',
+                subject: subj ?? subject,
+                committedAt: committedAt?.trim() ?? new Date().toISOString(),
+            };
+        });
+    }
+    /**
+     * Commit a single path — bypasses the one-file-per-change guard in
+     * `commit()` because the caller has already scoped the change to one
+     * path (typically the lock-release flow, where the lock itself
+     * guarantees the file is the only one whose edits this user owns).
+     *
+     * `git add <path>` then `git commit` — other dirty paths in the working
+     * tree are left alone. Validation + protected-branch access gating still
+     * run, since `path` could itself be `roles.yaml` / `access.md`.
+     *
+     * Returns `null` when the path has nothing to commit (no diff against
+     * HEAD, not untracked) — keeps lock-release idempotent on "I opened the
+     * editor but didn't actually change anything" flows.
+     */
+    /**
+     * Reset the file's working-tree state to HEAD — used when a write
+     * partially completed but the surrounding flow can't commit it
+     * (validator was advisory so this is rare, but op-throws + push-
+     * blocked-by-access-control still hit this path). Tracked files
+     * `git checkout HEAD --` reverts to the committed content; untracked
+     * files (a half-written new file) are deleted outright. Either way
+     * the working tree returns to a clean state so the next acquirer
+     * doesn't inherit half-finished bytes.
+     *
+     * Idempotent: a path that's already clean stays clean. Missing paths
+     * are silently ignored.
+     */
+    async discardPath(workspaceId, relativePath) {
+        assertValidRelativePath(relativePath);
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // Tracked-at-HEAD? `ls-files --error-unmatch` returns 0 if so.
+            let trackedAtHead = false;
+            try {
+                await this.git(cwd, ['ls-files', '--error-unmatch', '--', repoRelativePath]);
+                trackedAtHead = true;
+            }
+            catch {
+                trackedAtHead = false;
+            }
+            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);
+                });
+            }
+            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);
+                });
+            }
+        });
+    }
+    async commitFile(workspaceId, user, relativePath, summary, skipValidator) {
+        assertValidRelativePath(relativePath);
+        assertValidAuthor(user);
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            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.
+            const { stdout: scoped } = await this.git(cwd, [
+                'status', '--porcelain=v1', '--', repoRelativePath,
+            ]);
+            if (!scoped.trim())
+                return null;
+            // **No access check at commit time.** Per the "disk is the source of
+            // truth" rule, by the time content is on disk it must not be rejected.
+            // The permission check that used to live here now runs at lock
+            // acquisition (see `WorkflowService.acquireLock`'s
+            // `assertCanWriteAtPath`), so a user can't even start editing a file
+            // they lack write permission on — they never reach this commit. The
+            // legacy gate could destroy a user's edits when access changed
+            // mid-session; lock-time gating eliminates that destructive window.
+            //
+            // `GitService.commit` (the multi-file variant called by the agent's
+            // `commit_change` tool) still gates at commit time because it's used
+            // for files dirtied OUTSIDE the LockingFilesystem (e.g. agent
+            // manual-merge resolution), where no acquireLock ran.
+            // Validation is advisory; see `commit()` above for full rationale.
+            // `skipValidator` is set by callers that commit content which was
+            // already validated when it was first written — notably the reject
+            // flow, which re-commits a pre-agent baseline. Running the validator
+            // there is pure latency (it parses the whole KB and regenerates
+            // `diagram.md`) for a result that's neither enforced nor surfaced.
+            if (!skipValidator) {
+                await this.runCommitValidationHooks({ workspaceId, branch, paths: [repoRelativePath] }, (report) => `[git] commitFile on workspace=${workspaceId} branch=${branch} path=${repoRelativePath} landing with ${report.mustFix.length} unresolved KB validator issue(s); commit is no longer blocked.`);
+            }
+            await this.git(cwd, ['add', '--', repoRelativePath]);
+            const subject = summary?.trim() || buildDefaultCommitSummary(repoRelativePath);
+            if (subject.length > 200) {
+                throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
+            }
+            if (subject.includes('\n')) {
+                throw new WorkflowValidationError('commit summary must be a single line');
+            }
+            await this.git(cwd, [
+                'commit',
+                `--author=${user.name} <${user.email}>`,
+                '-m', subject,
+            ]);
+            const { stdout } = await this.git(cwd, [
+                'log',
+                '-1',
+                '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+            ]);
+            const [sha, authorName, authorEmail, subj, committedAt] = stdout.split('\x00');
+            this.accessControl?.invalidate(workspaceId);
+            return {
+                sha: sha?.trim() ?? '',
+                authorName: authorName ?? '',
+                authorEmail: authorEmail ?? '',
+                subject: subj ?? subject,
+                committedAt: committedAt?.trim() ?? new Date().toISOString(),
+            };
+        });
+    }
+    /**
+     * Atomic multi-file commit — commits whatever is currently dirty in the
+     * working tree as ONE commit attributed to `user`, then returns its
+     * attribution (or null when the tree is clean — idempotent re-apply). The
+     * multi-file sibling of `commit()`: same `git add -A` + commit, but WITHOUT
+     * the one-file-per-change guard — the caller has assembled + written + validated
+     * a batch (bulk node upload; the role-rename rewrite via `LockingFilesystem`).
+     *
+     * Deliberately does NOT write file content itself — disk writes are the
+     * caller's job. This is the git layer: it only stages + commits what is already
+     * on disk (the working tree is expected otherwise-clean under save=share, so
+     * `git add -A` stages exactly the caller's batch). Caller pushes separately
+     * (mirrors `commitFile` + `push`).
+     */
+    async commitChanges(workspaceId, user, summary) {
+        assertValidAuthor(user);
+        const subject = summary?.trim();
+        if (!subject)
+            throw new WorkflowValidationError('commit summary is required');
+        if (subject.length > 200)
+            throw new WorkflowValidationError('commit summary must be ≤ 200 characters');
+        if (subject.includes('\n'))
+            throw new WorkflowValidationError('commit summary must be a single line');
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const branch = await this.currentBranch(cwd);
+            // Nothing dirty → no-op (idempotent). Compute touched BEFORE `git add` so
+            // the protected-branch gate sees the same path set `commit()` would.
+            const { stdout: porcelain } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
+            const touched = parsePorcelainZ(porcelain);
+            if (touched.length === 0)
+                return null;
+            // Protected-branch access gate (defence in depth — callers already gate at
+            // lock-acquire / upload-mint, but this primitive is generic). Gate every
+            // touched path against the access tree at HEAD, like `commit()`.
+            if (isProtectedBranch(branch)) {
+                await this.assertCanWriteAtRef(workspaceId, 'HEAD', user.email, touched);
+            }
+            await this.git(cwd, ['add', '-A']);
+            await this.git(cwd, ['commit', `--author=${user.name} <${user.email}>`, '-m', subject]);
+            const { stdout } = await this.git(cwd, [
+                'log', '-1', '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+            ]);
+            const [sha, authorName, authorEmail, subj, committedAt] = stdout.split('\x00');
+            this.accessControl?.invalidate(workspaceId);
+            return {
+                sha: sha?.trim() ?? '',
+                authorName: authorName ?? '',
+                authorEmail: authorEmail ?? '',
+                subject: subj ?? subject,
+                committedAt: committedAt?.trim() ?? new Date().toISOString(),
+            };
+        });
+    }
+    async push(workspaceId, user) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            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
+            // canonical state — the PR merge gate (`origin/<base>` access tree)
+            // is the real security boundary. Skipping the check here lets non-
+            // admins push their drafts freely so they can propose changes via
+            // PR. Gate against `origin/<branch>` — the published state — for
+            // protected pushes; that's defence-in-depth against local rebases or
+            // `commit-tree` shenanigans that might bypass the commit-time gate.
+            if (isProtectedBranch(branch)) {
+                const touched = await this.unpushedTouchedPaths(cwd);
+                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
+    // reconcile, we throw `PushNeedsAgentResolutionError` and hand off to the
+    // agent. The agent has git + gh CLI access and can choose to run a raw
+    // `git push --force-with-lease` itself when it has determined that's the
+    // correct call (i.e. it semantically merged + force-pushed, or determined
+    // the displacing commits were spurious). Removing the wrapper method
+    // prevents accidental reintroduction as an "easy fallback" — force-push
+    // belongs in the agent's tool surface (raw CLI), not the system's
+    // automatic-recovery path.
+    /**
+     * Attempt a local merge of `origin/<targetBranch>` into the currently-
+     * checked-out branch. Used by the workflow module to auto-merge target →
+     * source when a change request is opened or refreshed (PLAN §1).
+     *
+     * Two outcomes:
+     *   - `{ kind: 'clean', alreadyUpToDate }` — merge succeeded, possibly as a
+     *     no-op (`alreadyUpToDate: true`) or with a new merge commit attributed
+     *     to `user` with a descriptive subject + body so reviewers can see why
+     *     the merge landed without inspecting the diff.
+     *   - `{ kind: 'conflicts', paths }` — `git merge` reported conflicts. The
+     *     merge is aborted to leave the working tree clean before returning
+     *     the conflicting paths so the caller can route to the agent for
+     *     resolution.
+     *
+     * Requires the source branch to already be checked out and the working
+     * tree clean — both refused with structured errors before any git op runs.
+     */
+    async mergeFromOrigin(workspaceId, sourceBranch, targetBranch, user) {
+        assertValidBranchName(sourceBranch);
+        assertValidBranchName(targetBranch);
+        assertValidAuthor(user);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // Under the per-branch workspace model, the workspace's identity is
+            // the source branch — the legacy "current branch must equal sourceBranch"
+            // guard was an artifact of the single-workspace-many-branches model and
+            // is no longer needed. The legacy dirty-tree refusal is also gone:
+            // save=share guarantees the tree is clean before any auto-merge runs,
+            // and the only way it could be dirty now is an upstream bug, which
+            // `statusInternal` already logs server-side.
+            // Refresh the target ref so we merge against the latest published
+            // state. Failing the fetch here is non-recoverable for this
+            // operation: a stale `origin/<target>` would let us silently miss
+            // conflicts the next push would surface, and the whole point of
+            // `mergeFromOrigin` is to surface those conflicts now. Propagate
+            // the error so the auto-merge aborts cleanly instead of producing
+            // a merge based on a stale ref. Explicit destination refspec for the
+            // same reason as `mergeChangeRequest`: a bare `fetch origin <branch>`
+            // updates `origin/<branch>` only as far as `remote.origin.fetch` allows,
+            // and a drifted refspec would hand this merge the stale ref it is
+            // explicitly trying to avoid.
+            await this.git(cwd, [
+                'fetch', '--no-write-fetch-head', 'origin',
+                `+refs/heads/${targetBranch}:refs/remotes/origin/${targetBranch}`,
+            ]);
+            // `--no-commit --no-ff` so we control the commit (need to override
+            // author) and so we never sneak a fast-forward past the merge-commit
+            // explanation gate.
+            let mergeStdout = '';
+            try {
+                const r = await this.git(cwd, [
+                    'merge', '--no-commit', '--no-ff', `origin/${targetBranch}`,
+                ]);
+                mergeStdout = r.stdout;
+            }
+            catch (err) {
+                // Conflict or other failure. Disambiguate via the shared porcelain parse.
+                const conflictPaths = await this.conflictedPaths(cwd);
+                // Always attempt to abort so a partial merge doesn't poison the tree.
+                try {
+                    await this.git(cwd, ['merge', '--abort']);
+                }
+                catch {
+                    // Already aborted (no MERGE_HEAD) — fine.
+                }
+                if (conflictPaths.length === 0)
+                    throw err;
+                return { kind: 'conflicts', paths: conflictPaths };
+            }
+            // No conflicts. Detect "already up to date" — git prints that exact
+            // phrase and stages nothing. Otherwise the merge is staged and waiting
+            // for the commit we now author as `user`.
+            if (/Already up to date/i.test(mergeStdout)) {
+                return { kind: 'clean', alreadyUpToDate: true };
+            }
+            const subject = `Refresh ${sourceBranch} from ${targetBranch}`;
+            const body = `Workflow auto-merge: incorporates the latest ${targetBranch} into ${sourceBranch} ` +
+                `as part of opening or refreshing a change request. ` +
+                `Conflicts (if any) would have been surfaced to the caller before this commit landed; ` +
+                `none were detected, so the merge applied cleanly.`;
+            await this.git(cwd, [
+                'commit',
+                `--author=${user.name} <${user.email}>`,
+                '-m', subject,
+                '-m', body,
+            ]);
+            this.accessControl?.invalidate(workspaceId);
+            return { kind: 'clean', alreadyUpToDate: false };
+        });
+    }
+    /**
+     * Merge a change request locally and publish it to the target branch — the
+     * provider-agnostic replacement for `gh pr merge`. Runs in the *base* branch's
+     * workspace: reset to the published base tip, merge the source's published
+     * tip as a `--no-ff` commit authored by the human triggerer, and push.
+     *
+     * Serialized per base workspace via the mutex, with a bounded retry: if the
+     * push is rejected because the base advanced (a concurrent merge), we reset to
+     * the new base and re-merge on top of it. Conflicts are deterministic — they
+     * return immediately (no retry) so the caller can route into resolution.
+     *
+     * Returns the merge commit SHA, or the conflicting paths.
+     */
+    async mergeChangeRequest(baseWorkspaceId, sourceBranch, targetBranch, commit, user) {
+        assertValidBranchName(sourceBranch);
+        assertValidBranchName(targetBranch);
+        assertValidAuthor(user);
+        const MAX_ATTEMPTS = 3;
+        return this.mutex.run(baseWorkspaceId, async () => {
+            const cwd = await this.repoDir(baseWorkspaceId);
+            // `git merge`/`git commit` need a committer identity. Prod clones are
+            // stamped by WorkspaceService, but stamp here too so the merge never
+            // depends on that ambient config (it would fail "Committer identity
+            // 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]);
+            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
+                // `fetch origin <branch>` only updates `refs/remotes/origin/<branch>`
+                // *opportunistically* — via whatever `remote.origin.fetch` happens to
+                // say — and this PR exists because that refspec drifts. Narrowed (or
+                // dropped) it leaves `origin/<source>` stale, so the merge below lands
+                // an old source tip on the base and every push attempt burns against
+                // the same stale ref. Naming the destinations removes the dependency
+                // on ambient config; both branches are `assertValidBranchName`-checked
+                // at the top of this method.
+                //
+                // `--no-write-fetch-head`: a multi-ref fetch writes one for-merge
+                // FETCH_HEAD entry PER ref — the exact shape that kills a concurrent
+                // `git pull` in this clone (see `pull`). Only the `origin/<branch>`
+                // refs below are read.
+                await this.git(cwd, [
+                    'fetch', '--no-write-fetch-head', 'origin',
+                    `+refs/heads/${targetBranch}:refs/remotes/origin/${targetBranch}`,
+                    `+refs/heads/${sourceBranch}:refs/remotes/origin/${sourceBranch}`,
+                ]);
+                // Match the published base tip exactly. Protected base branches never
+                // carry local commits (save=share + no direct commits), so this only
+                // discards a prior attempt's state, never real work.
+                await this.git(cwd, ['checkout', targetBranch]);
+                await this.git(cwd, ['reset', '--hard', `origin/${targetBranch}`]);
+                // `--no-commit --no-ff` so we author the merge commit as the human and
+                // never fast-forward past the merge record.
+                try {
+                    await this.git(cwd, ['merge', '--no-commit', '--no-ff', `origin/${sourceBranch}`]);
+                }
+                catch (err) {
+                    const paths = await this.conflictedPaths(cwd);
+                    await this.git(cwd, ['merge', '--abort']).catch(() => undefined);
+                    if (paths.length > 0)
+                        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))}`);
+                }
+                // Nothing staged ⇒ base already contains source (empty CR). The base tip
+                // is the "merged" state; report it without an empty commit.
+                const { stdout: staged } = await this.git(cwd, ['diff', '--cached', '--name-only']);
+                if (staged.trim() === '') {
+                    const { stdout: sha } = await this.git(cwd, ['rev-parse', 'HEAD']);
+                    await this.git(cwd, ['merge', '--abort']).catch(() => undefined);
+                    return { kind: 'merged', sha: sha.trim() };
+                }
+                await this.git(cwd, [
+                    'commit',
+                    `--author=${user.name} <${user.email}>`,
+                    '-m', commit.subject,
+                    '-m', commit.body,
+                ]);
+                const { stdout: sha } = await this.git(cwd, ['rev-parse', 'HEAD']);
+                try {
+                    await this.git(cwd, ['push', 'origin', `HEAD:refs/heads/${targetBranch}`]);
+                    this.accessControl?.invalidate(baseWorkspaceId);
+                    return { kind: 'merged', sha: sha.trim() };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // Base moved under us — reset to the new tip and re-merge next loop.
+                    if (/non-fast-forward|\[rejected\]|fetch first/i.test(msg) && attempt < MAX_ATTEMPTS) {
+                        continue;
+                    }
+                    throw err;
+                }
+            }
+            throw new Error(`merge push to "${targetBranch}" kept being rejected after ${MAX_ATTEMPTS} attempts (base moving concurrently)`);
+        });
+    }
+    /** Conflicted paths from a half-done merge, parsed from porcelain status. */
+    async conflictedPaths(cwd) {
+        const { stdout } = await this.git(cwd, ['status', '--porcelain=v1']);
+        const paths = [];
+        for (const line of stdout.split('\n')) {
+            if (/^(UU|AA|DD|AU|UA|DU|UD) /.test(line))
+                paths.push(line.slice(3));
+        }
+        return paths;
+    }
+    /**
+     * Paths changed in commits that exist locally but not on the upstream ref —
+     * i.e. exactly what the next `push` would publish. Falls back to "every
+     * commit not reachable from any remote ref" when there's no upstream yet
+     * (first push).
+     */
+    async unpushedTouchedPaths(cwd) {
+        let range;
+        try {
+            await this.git(cwd, ['rev-parse', '--verify', '--quiet', '@{u}']);
+            range = ['@{u}..HEAD'];
+        }
+        catch {
+            range = ['HEAD', '--not', '--remotes'];
+        }
+        const { stdout } = await this.git(cwd, [
+            'log', '--name-only', '--pretty=format:', ...range,
+        ]);
+        const set = new Set();
+        for (const line of stdout.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                set.add(trimmed);
+        }
+        return [...set];
+    }
+    async fetch(workspaceId) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // `--no-write-fetch-head`: callers want the remote-tracking refs, not
+            // FETCH_HEAD, and leaving that shared file alone keeps this fetch from
+            // steering a concurrent refresh in the same clone (see `pull`).
+            await this.git(cwd, ['fetch', '--no-write-fetch-head', 'origin']);
+        });
+    }
+    /**
+     * Collapse the clone's drifted tracking config back to one fetch refspec and
+     * one upstream ref, then refresh `refs/remotes/origin/<branch>` through an
+     * explicit refspec — never touching the shared `FETCH_HEAD`. Returns the ref
+     * the caller should operate on.
+     *
+     * Both halves matter, and neither is sufficient alone:
+     *
+     * - The self-heal. A multi-valued `branch.<name>.merge` makes every bare
+     *   fetch in this clone write more than one *for-merge* FETCH_HEAD entry,
+     *   which is the ammunition behind the failure below; a duplicated
+     *   `remote.origin.fetch` refspec is the same class of drift (see
+     *   `clone-config.ts`). `--replace-all` collapses either back to the single
+     *   value the clone was created with. Best effort — the fetch names its refs
+     *   explicitly, so a failure here is harmless.
+     *
+     * - Never reading or writing `FETCH_HEAD`. `git pull` is a two-step
+     *   operation — fetch, then read the rebase target out of `.git/FETCH_HEAD`
+     *   — and `FETCH_HEAD` is a single mutable file shared by every git process
+     *   in the clone. This service is not the only writer: `fetchOriginIfStale`
+     *   (outside the workspace mutex, see `listBranches`) and
+     *   `WorkspaceService.ensureRemotesFetched` (outside it entirely, driven by
+     *   the CR-list poll) both run bare `git fetch --prune origin`, and a bare
+     *   fetch writes one for-merge entry per `branch.<name>.merge` value. Let one
+     *   of those land in the window between the pull's own fetch and its read, on
+     *   a clone whose merge config has drifted to two values, and pull sees two
+     *   merge heads and dies with "Cannot rebase onto multiple branches" — the
+     *   reported failure. (Measured: ~40% of refreshes with one concurrent fetch
+     *   loop. The drifted config alone never breaks it — an explicit
+     *   `pull --rebase origin <branch>` survives every drift shape on its own.)
+     *
+     * So: fetch with an explicit destination refspec, which updates
+     * `refs/remotes/origin/<branch>` regardless of any `remote.origin.fetch`
+     * drift, and let the caller name that ref. `--no-write-fetch-head` (git
+     * 2.29+, asserted at boot by `git-version.ts`) keeps this refresh from
+     * perturbing anyone else's `FETCH_HEAD` in turn. Nothing here reads shared
+     * mutable state, so no concurrent git process can steer or break it.
+     *
+     * Shared by the two refresh paths (`pull`, `resetToRemote`) so they can't
+     * drift apart — which is precisely the failure class this guards against.
+     */
+    async refreshRemoteBranchRef(cwd, branch) {
+        for (const args of cloneTrackingConfigArgs(branch)) {
+            await this.git(cwd, args).catch(() => undefined);
+        }
+        await this.git(cwd, [
+            'fetch', '--no-write-fetch-head', 'origin',
+            `+refs/heads/${branch}:refs/remotes/origin/${branch}`,
+        ]);
+        return `refs/remotes/origin/${branch}`;
+    }
+    async pull(workspaceId) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const branch = await this.currentBranch(cwd);
+            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]);
+            }
+            catch (err) {
+                // 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.
+                await this.git(cwd, ['rebase', '--abort']).catch(() => undefined);
+                throw err;
+            }
+            this.accessControl?.invalidate(workspaceId);
+        });
+    }
+    /**
+     * Hard-reset the workspace's checked-out branch to `origin/<branch>`, fetching
+     * first. This is the break-glass primitive behind roles.yaml recovery: it
+     * makes the local clone EXACTLY match origin, discarding any local divergence
+     * (e.g. a half-finished recovery commit from a prior failed push, or commits
+     * the clone was behind on). The caller then writes its fix on top of the
+     * current origin tip, so the follow-up push fast-forwards instead of being
+     * rejected non-fast-forward.
+     *
+     * Destructive by design and intentionally NOT gated on the protected-branch
+     * rule — it only ever moves the LOCAL ref to match origin (no remote mutation),
+     * and recovery must work precisely on the protected default branch. Under
+     * save=share there is no precious unpushed local work to lose (every save
+     * auto-pushes); the one exception is a failed recovery commit, which the
+     * caller re-creates.
+     */
+    async resetToRemote(workspaceId, branch) {
+        assertValidBranchName(branch);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // Same self-heal + FETCH_HEAD-free refresh as `pull`, then reset to the
+            // remote-tracking ref it returns — never `FETCH_HEAD`. The stakes here
+            // are higher than a failed refresh: this is a hard reset, so a raced
+            // FETCH_HEAD would silently reset the workspace to whatever branch the
+            // other fetch happened to write. Deliberately no rebase — a divergent
+            // local commit can never conflict.
+            const remoteRef = await this.refreshRemoteBranchRef(cwd, branch);
+            await this.git(cwd, ['reset', '--hard', remoteRef]);
+            this.accessControl?.invalidate(workspaceId);
+        });
+    }
+    async resolveForkBase(workspaceId, branch) {
+        assertValidBranchName(branch);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            let best = null;
+            for (const p of PROTECTED_BRANCHES) {
+                if (p === branch)
+                    continue;
+                const res = await this.tryAheadBehind(cwd, branch, `origin/${p}`);
+                if (res && (best === null || res.ahead < best.ahead)) {
+                    best = { base: p, ahead: res.ahead };
+                }
+            }
+            return best?.base ?? null;
+        });
+    }
+    /**
+     * Count commits on `branch` that aren't on `baseBranch`. Identical to the
+     * "ahead" half of `tryAheadBehind` but exposed as a public method because
+     * background callers (the routine runner) need to gate "open a CR or
+     * clean the branch up?" on it. Returns 0 when either ref can't be
+     * resolved — a missing branch can't possibly be ahead of anything, and
+     * misreporting as `> 0` would block legitimate cleanup.
+     */
+    async countCommitsAhead(workspaceId, branch, baseBranch) {
+        assertValidBranchName(branch);
+        assertValidBranchName(baseBranch);
+        if (branch === baseBranch)
+            return 0;
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            // Compare against the *remote* base — the routine flow pushes commits
+            // to origin as they're made, and matching here against the same ref the
+            // CR creator uses (`origin/<base>`) keeps the two readings consistent.
+            const res = await this.tryAheadBehind(cwd, branch, `origin/${baseBranch}`);
+            return res?.ahead ?? 0;
+        });
+    }
+    /**
+     * Whether `head` and `origin/<base>` have any common ancestor. False when
+     * `head` is an orphan branch or was created from an unrelated history —
+     * GitHub refuses PRs in that state with a `no history in common` error,
+     * so PR creation pre-flights this and hands off to the agent on false.
+     */
+    async haveSharedHistory(workspaceId, base, head) {
+        assertValidBranchName(base);
+        assertValidBranchName(head);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            try {
+                const { stdout } = await this.git(cwd, [
+                    'merge-base',
+                    `origin/${base}`,
+                    head,
+                ]);
+                return stdout.trim().length > 0;
+            }
+            catch (err) {
+                // git merge-base exits 1 specifically for "no common ancestor" — the
+                // very condition this method tests for. Any other failure (exit 128
+                // for invalid args / corrupt repo, ENOENT for missing git binary,
+                // etc.) is an infra problem that must bubble up rather than silently
+                // masquerade as "no shared history".
+                const exitCode = err.exitCode;
+                if (exitCode === 1)
+                    return false;
+                throw err;
+            }
+        });
+    }
+    async diffStat(workspaceId, base) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            if (base)
+                assertValidBranchName(base.replace(/^origin\//, ''));
+            const against = base ?? '@{upstream}';
+            try {
+                // `git diff <ref>` (no dots) compares <ref> to the working tree, so
+                // this counts uncommitted + committed changes that would land if the
+                // caller committed and pushed right now — that's what the share
+                // dialog previews. For PR creation the working tree is already clean
+                // (the push just ran), so the answer matches the old three-dot form.
+                const { stdout } = await this.git(cwd, ['diff', '--name-only', against]);
+                return stdout.split('\n').map((l) => l.trim()).filter(Boolean);
+            }
+            catch {
+                // No upstream / unknown base — nothing to diff against.
+                return [];
+            }
+        });
+    }
+    async pendingChanges(workspaceId) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const { stdout } = await this.git(cwd, ['status', '--porcelain=v1', '-z']);
+            return parsePorcelainZ(stdout);
+        });
+    }
+    /**
+     * Repo-relative paths of every VCS-tracked file (NUL-delimited, so paths with
+     * spaces or bracketed prefixes survive intact). Untracked / ignored files are
+     * excluded — the caller gets exactly the working tree's committed contents.
+     */
+    async listTrackedFiles(workspaceId) {
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const { stdout } = await this.git(cwd, ['ls-files', '-z']);
+            return stdout.split('\0').filter(Boolean);
+        });
+    }
+    async revertCommit(workspaceId, user, sha) {
+        if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
+            throw new WorkflowValidationError('invalid commit sha');
+        }
+        assertValidAuthor(user);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const branch = await this.currentBranch(cwd);
+            // Revert creates a new commit reversing `sha`. Same model as commit:
+            // gate only on protected branches; reverts on feature/draft branches
+            // are free (they produce a commit that would still need to merge via
+            // PR to affect canonical state).
+            if (isProtectedBranch(branch)) {
+                const { stdout: diffOut } = await this.git(cwd, [
+                    'diff-tree', '--no-commit-id', '--name-only', '-r', sha,
+                ]);
+                const touched = diffOut.split('\n').map((s) => s.trim()).filter(Boolean);
+                await this.assertCanWriteAtRef(workspaceId, 'HEAD', user.email, touched);
+            }
+            await this.git(cwd, [
+                'revert',
+                '--no-edit',
+                `--author=${user.name} <${user.email}>`,
+                sha,
+            ]);
+            const { stdout } = await this.git(cwd, [
+                'log',
+                '-1',
+                '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+            ]);
+            const [headSha, authorName, authorEmail, subj, committedAt] = stdout.split('\x00');
+            // A revert may have touched roles.yaml or access.md — drop cached
+            // access state so the next gate read reflects the rolled-back tree.
+            // Mirrors the commit / pull paths.
+            this.accessControl?.invalidate(workspaceId);
+            return {
+                sha: headSha?.trim() ?? '',
+                authorName: authorName ?? '',
+                authorEmail: authorEmail ?? '',
+                subject: subj ?? '',
+                committedAt: committedAt?.trim() ?? new Date().toISOString(),
+            };
+        });
+    }
+    async logForFile(workspaceId, relativePath, limit = 20) {
+        assertValidRelativePath(relativePath);
+        const max = Math.max(1, Math.min(limit, 100));
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const { stdout } = await this.git(cwd, [
+                'log',
+                `--max-count=${max}`,
+                '--pretty=format:%H%x00%an%x00%ae%x00%s%x00%aI',
+                '--',
+                repoRelativePath,
+            ]);
+            return stdout
+                .split('\n')
+                .map((line) => line.trim())
+                .filter(Boolean)
+                .map((line) => {
+                const [sha, authorName, authorEmail, subject, committedAt] = line.split('\x00');
+                return {
+                    sha: sha ?? '',
+                    authorName: authorName ?? '',
+                    authorEmail: authorEmail ?? '',
+                    subject: subject ?? '',
+                    committedAt: committedAt ?? '',
+                };
+            });
+        });
+    }
+    async diffFileAtCommit(workspaceId, relativePath, sha) {
+        assertValidRelativePath(relativePath);
+        if (!/^[a-f0-9]{7,40}$/i.test(sha)) {
+            throw new WorkflowValidationError('invalid commit sha');
+        }
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            try {
+                const { stdout } = await this.git(cwd, [
+                    'show',
+                    sha,
+                    '--',
+                    repoRelativePath,
+                ]);
+                return stdout;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Failed to execute git show for "${relativePath}" at "${sha}": ${msg}`, { cause: err });
+            }
+        });
+    }
+    async diffFileBetweenBranches(workspaceId, relativePath, fromBranch, toBranch) {
+        assertValidRelativePath(relativePath);
+        assertValidBranchName(fromBranch);
+        assertValidBranchName(toBranch);
+        if (fromBranch === toBranch) {
+            throw new WorkflowValidationError('from and to branches must differ');
+        }
+        const repoRelativePath = this.stripRepoPrefix(relativePath);
+        return this.mutex.run(workspaceId, async () => {
+            const cwd = await this.repoDir(workspaceId);
+            const fromRef = await this.resolveBranchRef(cwd, fromBranch);
+            const toRef = await this.resolveBranchRef(cwd, toBranch);
+            // 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
+            // share-changes flow) are invisible — the user just edited the file
+            // and would see "identical" if we always compared committed states.
+            const current = await this.currentBranch(cwd);
+            const isToCurrent = toBranch === current;
+            const isFromCurrent = fromBranch === current;
+            // `git diff <ref> -- <path>` ignores untracked working-tree files, so a
+            // brand-new file (created on disk but never committed) renders as
+            // identical between branches. When the current branch is one side and
+            // the path is untracked locally, synthesize an added/removed diff —
+            // same pattern diffFileWorking uses for HEAD-vs-working-tree.
+            if (isToCurrent !== isFromCurrent &&
+                (await this.isPathUntracked(cwd, repoRelativePath))) {
+                return synthesizeUntrackedSideDiff(cwd, repoRelativePath, isToCurrent ? 'added' : 'removed');
+            }
+            const args = ['diff', '--no-color'];
+            if (isToCurrent && !isFromCurrent) {
+                // `git diff <ref>` compares ref → working tree, with the working
+                // tree's contents shown as `+`. That's exactly the +/- direction
+                // we want when "to" is the current branch.
+                args.push(fromRef);
+            }
+            else if (isFromCurrent && !isToCurrent) {
+                // Reverse so the +/- direction matches "from current → to ref":
+                // ref's contents show as `+`, working tree shows as `-`.
+                args.push('-R', toRef);
+            }
+            else {
+                // Neither side is the current branch — pure commit-vs-commit.
+                // Two-dot, not three-dot: three-dot would be merge-base semantics
+                // (PR-style) which would hide changes on the from-side since the
+                // fork point — wrong for "compare these two versions right now".
+                args.push(fromRef, toRef);
+            }
+            args.push('--', repoRelativePath);
+            try {
+                const { stdout } = await this.git(cwd, args);
+                return stdout;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new Error(`Failed to diff "${relativePath}" between "${fromBranch}" and "${toBranch}": ${msg}`, { cause: err });
+            }
+        });
+    }
+    /**
+     * Head/base commit SHAs for a change request, computed locally — no provider
+     * API. `head` is the source branch tip, `base` the target branch tip, both
+     * resolved on `origin/*` after a fetch so a force-push is reflected. These are
+     * what approvals pin against and what the diff range is built from.
+     */
+    async resolvePrShas(workspaceId, baseBranch, headBranch) {
+        assertValidBranchName(baseBranch);
+        assertValidBranchName(headBranch);
+        // Fetch (a network round-trip) BEFORE taking the mutex so a slow origin can't
+        // block unrelated local git ops on this workspace; the lock guards only the
+        // local ref resolution + rev-parse below.
+        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 [{ stdout: baseSha }, { stdout: headSha }] = await Promise.all([
+                this.git(cwd, ['rev-parse', baseRef]),
+                this.git(cwd, ['rev-parse', headRef]),
+            ]);
+            return { baseSha: baseSha.trim(), headSha: headSha.trim() };
+        });
+    }
+    /**
+     * The changed-file list for a change request, computed locally via three-dot
+     * (merge-base) diff — the same semantics a GitHub PR shows. Replaces the
+     * `gh api …/pulls/:n/files` call so any git host works.
+     *
+     * `--name-status` + `--numstat` (both rename-aware via `-M`) drive the file
+     * list, statuses, and +/- counts; per-file patches are generated for up to
+     * `patchCap` files (default 400) — beyond that `patch` is left undefined,
+     * exactly like the old API's binary/oversized files (the UI renders those with
+     * no inline diff). Patch generation is skipped for binary files.
+     */
+    async changedFilesForPr(workspaceId, baseBranch, headBranch, opts = {}) {
+        assertValidBranchName(baseBranch);
+        assertValidBranchName(headBranch);
+        const patchCap = opts.patchCap ?? 400;
+        // Fetch outside the mutex (network round-trip) so origin latency can't hold
+        // the workspace lock; the lock guards only the local diff work below.
+        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 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]),
+                this.git(cwd, ['diff', '-M', '-z', '--numstat', range]),
+            ]);
+            const statuses = parseNameStatusZ(nameStatusOut);
+            const counts = parseNumstatZ(numstatOut);
+            // `--name-status` and `--numstat` enumerate the same files in the same
+            // order (same `-M` over the same range), so we zip by index. If the two
+            // ever disagree in length, the index alignment is unsafe — fall back to
+            // zeroed counts (statuses/paths stay correct) rather than pin the wrong
+            // +/- 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}) ` +
+                    `for ${range} — reporting file list without +/- counts`);
+            }
+            const files = statuses.map((s, i) => {
+                const c = (aligned ? counts[i] : undefined) ?? { additions: 0, deletions: 0, isBinary: false };
+                return {
+                    path: s.path,
+                    previousPath: s.previousPath,
+                    status: s.status,
+                    additions: c.additions,
+                    deletions: c.deletions,
+                    patch: undefined,
+                    isBinary: c.isBinary,
+                    sha: '',
+                    rawUrl: '',
+                };
+            });
+            // Generate per-file patches for the first `patchCap` non-binary files.
+            let generated = 0;
+            for (const f of files) {
+                if (generated >= patchCap)
+                    break;
+                if (f.isBinary)
+                    continue;
+                f.patch = await this.filePatchForPr(cwd, range, f);
+                generated += 1;
+            }
+            return files;
+        });
+    }
+    /**
+     * 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.
+     */
+    async changedPathsForPr(workspaceId, baseBranch, headBranch) {
+        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);
+        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);
+        });
+    }
+    /** Fetch the two branches a CR spans so origin refs reflect the latest push. */
+    async fetchPrRefs(cwd, baseBranch, headBranch) {
+        // Best-effort: a branch may be local-only (rare) or origin briefly
+        // unreachable; `resolveBranchRef` still falls back to whatever is local.
+        // `--no-write-fetch-head` — this runs on the CR-detail path (polled around
+        // every merge) and only the `origin/<branch>` refs are read; writing two
+        // for-merge FETCH_HEAD entries here can break a concurrent refresh in the
+        // same clone (see `pull`).
+        //
+        // Explicit destination refspecs for the same reason as `mergeChangeRequest`:
+        // "reflect the latest push" is exactly what a drifted `remote.origin.fetch`
+        // silently stops delivering, and the CR diff would then be computed against
+        // a stale head. Every caller `assertValidBranchName`s both branches.
+        await this.git(cwd, [
+            'fetch', '--no-write-fetch-head', 'origin',
+            `+refs/heads/${baseBranch}:refs/remotes/origin/${baseBranch}`,
+            `+refs/heads/${headBranch}:refs/remotes/origin/${headBranch}`,
+        ]).catch(() => undefined);
+    }
+    /** Unified-diff patch for one file across the CR range (rename-aware). */
+    async filePatchForPr(cwd, range, file) {
+        // For a rename, pass both endpoints so `-M` renders it as a rename patch;
+        // otherwise the single (destination, or base-side for deletes) path.
+        const pathspec = file.previousPath && file.previousPath !== file.path
+            ? ['--', file.previousPath, file.path]
+            : ['--', file.path];
+        try {
+            const { stdout } = await this.git(cwd, ['diff', '-M', '--no-color', range, ...pathspec]);
+            return stdout.length > 0 ? stdout : undefined;
+        }
+        catch {
+            // A patch failure is cosmetic — the file still shows in the list.
+            return undefined;
+        }
+    }
+    // `workingStatus` + `diffFileWorking` removed: both reported the dirty
+    // state of a workspace's working tree, which under save=share is always
+    // empty. The frontend used these to render a "pending uncommitted edits"
+    // panel and per-file diff — neither has a meaningful state to show
+    // anymore. `diffFileBetweenBranches` + `diffFileAtCommit` still cover
+    // the meaningful diff cases (cross-branch comparisons and history).
+    /**
+     * Strip the `knowledge-base/` prefix from a workspace-relative path so
+     * it lines up with where git actually runs (`cwd = repoDir`, i.e. inside
+     * `knowledge-base/`). The frontend stores `openFilePath` as a
+     * workspace-relative path including that prefix because the file viewer
+     * reads/writes through `WorkspaceService.readFile`, which resolves from
+     * the workspace root. Git pathspecs, on the other hand, are resolved from
+     * cwd — so without this normalization `git diff -- knowledge-base/X`
+     * silently looks for `knowledge-base/knowledge-base/X` and returns
+     * nothing, which the UI renders as "identical".
+     *
+     * No-op for paths already repo-relative (the agent tools and tests pass
+     * those directly).
+     */
+    stripRepoPrefix(relativePath) {
+        return relativePath.startsWith(`${this.kbDirName}/`)
+            ? relativePath.slice(this.kbDirName.length + 1)
+            : relativePath;
+    }
+    /**
+     * 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
+     * ref. The workspace clone fetches all remotes on creation, so protected
+     * branches are reachable through `origin/` even when the user has never
+     * personally checked them out.
+     */
+    async resolveBranchRef(cwd, branch) {
+        for (const ref of [`refs/heads/${branch}`, `refs/remotes/origin/${branch}`]) {
+            try {
+                await this.git(cwd, ['rev-parse', '--verify', '--quiet', ref]);
+                return ref;
+            }
+            catch {
+                // Try the next candidate.
+            }
+        }
+        throw new WorkflowValidationError(`unknown branch: ${branch}`);
+    }
+    // ── internals ──────────────────────────────────────────────────────────
+    async statusInternal(workspaceId) {
+        const cwd = await this.repoDir(workspaceId);
+        const branch = await this.currentBranch(cwd);
+        // Defensive sanity check. Under save=share a dirty working tree has two
+        // very different meanings:
+        //   - Rows exist in `pending_commits` for this workspace → EXPECTED. The
+        //     saves are on disk and their commits are still draining through the
+        //     background worker (a bulk write can queue hundreds of rows, taking
+        //     minutes). Not a bug — log quietly for observability.
+        //   - No queued rows → files are dirty with nothing scheduled to commit
+        //     them: an upstream bug (lock-release crashed mid-write, an external
+        //     `git` invocation left state behind, etc.). Warn loudly.
+        // Either way it's never surfaced to the user: the structured status no
+        // longer carries an isDirty bit, which removes the only path by which a
+        // transient working-tree blip used to leak into a user-facing 409.
+        const porcelain = await this.git(cwd, ['status', '--porcelain=v1']);
+        if (porcelain.stdout.trim().length > 0) {
+            let queueExplainsIt = false;
+            if (this.pendingCommitsProbe) {
+                try {
+                    queueExplainsIt = await this.pendingCommitsProbe(workspaceId);
+                }
+                catch {
+                    // Probe failure (DB blip) must not break status — fall through to
+                    // the loud warning, which is the safe-side default.
+                }
+            }
+            const dirtyList = porcelain.stdout.trim().replace(/\s+/g, ' ');
+            if (queueExplainsIt) {
+                console.log(`[git] 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 ` +
+                    `tree under save=share with NO queued pending commits — this should never ` +
+                    `happen and likely indicates a missed lock-release commit. Files: ${dirtyList}`);
+            }
+        }
+        let hasUpstream = true;
+        let unmergedFromUpstream = false;
+        try {
+            // We don't expose `unpushedCommits` anymore — under save=share every
+            // commit is auto-pushed on lock release, so ahead is always 0. We only
+            // care about "is origin ahead of us?" for the auto-pull driver.
+            const behind = await this.git(cwd, ['rev-list', '--count', 'HEAD..@{u}']);
+            unmergedFromUpstream = (parseInt(behind.stdout.trim(), 10) || 0) > 0;
+        }
+        catch {
+            // Branch has never been published — nothing upstream to compare against.
+            // Surfaces via `hasUpstream` so the UI can flag a never-shared draft.
+            hasUpstream = false;
+        }
+        return { branch, hasUpstream, unmergedFromUpstream };
+    }
+    async currentBranch(cwd) {
+        const { stdout } = await this.git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+        return stdout.trim();
+    }
+    /**
+     * Ahead/behind of `ref` (a full ref like `refs/heads/foo` or
+     * `refs/remotes/origin/foo`). When the branch exists locally (`hasLocal`),
+     * prefer its configured upstream; otherwise — or when no upstream is set —
+     * fall back to the nearest protected branch on origin, picking whichever
+     * minimises "ahead" as a proxy for the fork point.
+     */
+    async aheadBehindForBranch(cwd, shortName, ref, hasLocal) {
+        if (hasLocal) {
+            const upstream = await this.tryAheadBehind(cwd, ref, `${shortName}@{upstream}`);
+            if (upstream)
+                return upstream;
+        }
+        let best = null;
+        for (const p of PROTECTED_BRANCHES) {
+            if (p === shortName)
+                continue;
+            const res = await this.tryAheadBehind(cwd, ref, `refs/remotes/origin/${p}`);
+            if (res && (best === null || res.ahead < best.ahead))
+                best = res;
+        }
+        return best ?? { ahead: null, behind: null };
+    }
+    async tryAheadBehind(cwd, branch, base) {
+        try {
+            const { stdout } = await this.git(cwd, [
+                'rev-list',
+                '--left-right',
+                '--count',
+                `${base}...${branch}`,
+            ]);
+            const [behind, ahead] = stdout.trim().split(/\s+/).map((n) => parseInt(n, 10) || 0);
+            return { ahead, behind };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Read a repo-relative file's contents at an arbitrary git ref (a branch,
+     * `origin/<branch>`, or a sha) WITHOUT checking it out. Returns `null` when
+     * the path does not exist at that ref (mirrors the access resolver's
+     * `showAtRef`) — the caller distinguishes "absent" from "present but empty".
+     * Read-only: `git show <ref>:<path>` never mutates the working tree.
+     */
+    async readFileAtRef(workspaceId, ref, repoRelativePath) {
+        const cwd = await this.repoDir(workspaceId);
+        try {
+            const { stdout } = await this.git(cwd, ['show', `${ref}:${repoRelativePath}`]);
+            return stdout;
+        }
+        catch (err) {
+            // ONLY "the path doesn't exist at this ref" maps to null. `git show
+            // <ref>:<path>` reports that as `fatal: path '<p>' does not exist in
+            // '<ref>'` (or `... exists on disk, but not in '<ref>'`). Any other
+            // failure — an unresolvable ref, a corrupt object, a repo/IO error —
+            // must PROPAGATE, not be misread as "absent": callers like
+            // `preserveBaseRolesYaml` compare base-vs-head content and rely on the
+            // absent/present distinction being truthful, so a swallowed error
+            // (both refs → null → "identical") would fail OPEN. Fail closed instead.
+            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 null;
+            throw err;
+        }
+    }
+    async repoDir(workspaceId) {
+        return path.join(await this.workspaceService.getWorkspacePath(workspaceId), this.kbDirName);
+    }
+    async isPathUntracked(cwd, relativePath) {
+        const { stdout } = await this.git(cwd, [
+            'ls-files',
+            '--others',
+            '--exclude-standard',
+            '--',
+            relativePath,
+        ]);
+        return stdout.trim().length > 0;
+    }
+    async git(cwd, args) {
+        try {
+            const { stdout, stderr } = await 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,
+            });
+            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;
+        }
+    }
+}
+/** Map a git status letter (`git diff --name-status`) to the DTO's `PrFileStatus`. */
+function mapGitStatus(letter) {
+    switch (letter[0]) {
+        case 'A': return 'added';
+        case 'D': return 'removed';
+        case 'R': return 'renamed';
+        case 'C': return 'copied';
+        case 'T': return 'changed'; // type change (e.g. file ↔ symlink)
+        case 'M':
+        default: return 'modified';
+    }
+}
+/**
+ * Parse `git diff -M -z --name-status` output. NUL-separated tokens: each record
+ * is `<statusLetter>\0<path>`, or for a rename/copy `<Rxxx|Cxxx>\0<old>\0<new>`.
+ */
+export function parseNameStatusZ(out) {
+    const tokens = out.split('\0');
+    const entries = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const raw = tokens[i];
+        if (!raw) {
+            i += 1;
+            continue;
+        } // trailing empty token after the final NUL
+        const letter = raw[0];
+        if (letter === 'R' || letter === 'C') {
+            const previousPath = tokens[i + 1];
+            const path = tokens[i + 2];
+            if (path === undefined)
+                break; // malformed tail — stop rather than throw
+            entries.push({ status: mapGitStatus(letter), path, previousPath });
+            i += 3;
+        }
+        else {
+            const path = tokens[i + 1];
+            if (path === undefined)
+                break;
+            entries.push({ status: mapGitStatus(letter), path });
+            i += 2;
+        }
+    }
+    return entries;
+}
+/**
+ * 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
+ * `<add>\t<del>\t<path>` for a normal change, or `<add>\t<del>\t\0<old>\0<new>`
+ * for a rename (empty path segment before the two NUL-separated names). Binary
+ * files report `-` for both counts.
+ */
+export function parseNumstatZ(out) {
+    const tokens = out.split('\0');
+    const entries = [];
+    let i = 0;
+    while (i < tokens.length) {
+        const raw = tokens[i];
+        if (!raw) {
+            i += 1;
+            continue;
+        }
+        const m = raw.match(/^(-|\d+)\t(-|\d+)\t(.*)$/s);
+        if (!m) {
+            i += 1;
+            continue;
+        }
+        const isBinary = m[1] === '-' && m[2] === '-';
+        const entry = {
+            additions: m[1] === '-' ? 0 : Number(m[1]),
+            deletions: m[2] === '-' ? 0 : Number(m[2]),
+            isBinary,
+        };
+        if (m[3] === '') {
+            // Rename: the two names follow as separate NUL-terminated tokens.
+            i += 3;
+        }
+        else {
+            i += 1;
+        }
+        entries.push(entry);
+    }
+    return entries;
+}
+export { PROTECTED_BRANCHES };
+//# sourceMappingURL=git.service.js.map