@bevel-software/platform-core-backend 0.1.0

package/dist/modules/workspace/workspace.service.js

@@ -0,0 +1,1221 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import AdmZip from 'adm-zip';
+import { assertValidRelativePath, validateFilename, DEFAULT_BRANCH } from '@bevel-software/platform-shared';
+import { BevelIgnoreStack } from './bevel-ignore.js';
+import { assertValidBranchName } from '../workflow/git/branch-name.js';
+import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../workflow/git/clone-config.js';
+// Zip-bomb guardrails. The upload cap is 50 MB compressed; even a generous
+// 100× expansion ratio still fits inside these limits, so a well-behaved
+// archive will never trip them. They exist so a hostile or malformed zip
+// can't run the container out of disk by inflating to gigabytes.
+const UNZIP_MAX_ENTRIES = 10_000;
+const UNZIP_MAX_ENTRY_BYTES = 100 * 1024 * 1024; // 100 MB per file
+const UNZIP_MAX_TOTAL_BYTES = 500 * 1024 * 1024; // 500 MB across the whole archive
+// Folder-download cap. The whole zip is built in memory by adm-zip (no
+// streaming) so the cap also bounds peak heap usage for one download.
+// Reuses the unzip total as a single "fits in a workspace" budget.
+const ZIP_DOWNLOAD_MAX_BYTES = UNZIP_MAX_TOTAL_BYTES;
+/**
+ * Thrown by `createFolderZip` when the cumulative uncompressed bytes exceed
+ * `ZIP_DOWNLOAD_MAX_BYTES`. Carries a 413-ready message; the route layer
+ * checks `instanceof` and maps it accordingly.
+ */
+export class FolderTooLargeError extends Error {
+    limitBytes;
+    constructor(limitBytes) {
+        super(`Folder exceeds the ${limitBytes}-byte download size limit`);
+        this.limitBytes = limitBytes;
+        this.name = 'FolderTooLargeError';
+    }
+}
+const execFileAsync = promisify(execFile);
+/**
+ * Identity stamped on the per-branch clone's git config. Every workflow
+ * commit overrides this with `--author=…` so the human shows up in
+ * `git log`; this is just the fallback committer identity so plain
+ * git operations have something to attribute to.
+ */
+const BOT_NAME = 'Bevel Workflow';
+const BOT_EMAIL = 'bevel-workflow@bevel.software';
+/** Redact any token that might leak into an error message. */
+function redactError(err) {
+    const token = process.env.GITHUB_TOKEN;
+    const msg = err instanceof Error ? err.message : String(err);
+    return token ? msg.replaceAll(token, '***') : msg;
+}
+const FETCH_CACHE_TTL_MS = 30_000;
+/**
+ * Map a branch name to the directory that contains its workspace clone.
+ * `encodeURIComponent` handles `/` in branch names (e.g. `alice/foo`) by
+ * encoding it to `%2F` — single-segment-safe on every supported filesystem.
+ */
+export function workspaceIdForBranch(branch) {
+    return encodeURIComponent(branch);
+}
+export function branchForWorkspaceId(workspaceId) {
+    return decodeURIComponent(workspaceId);
+}
+export class WorkspaceService {
+    workspacesRoot;
+    kbRepoUrl;
+    kbDirName;
+    gitUsername;
+    /** Maps branch → absolute directory path. Lazily populated. */
+    branchDirs = new Map();
+    /**
+     * In-flight bootstrap promises keyed by branch — concurrent callers for
+     * the same branch share a single clone instead of racing to overwrite
+     * each other's working tree.
+     */
+    inFlightBootstraps = new Map();
+    /** Per-workspace-dir `git fetch origin` timestamp + in-flight tracker. */
+    lastFetchAt = new Map();
+    inFlightFetches = new Map();
+    /**
+     * Late-bound by the composition root — DiffService depends on
+     * WorkspaceService for path resolution.
+     */
+    diffService = null;
+    /**
+     * Late-bound by the composition root. Awaited once before the first per-branch
+     * clone so the KB remote is guaranteed to carry the protected branches + base
+     * scaffolding — a fresh (or partially-populated) remote is seeded rather than
+     * assumed. Null in tests / setups that pre-provision the remote themselves.
+     */
+    seedService = null;
+    /**
+     * Late-bound by the composition root: notified with the workspace id
+     * right after a branch's clone is created. The git layer uses this to
+     * skip the otherwise-redundant implicit `git fetch` on the first
+     * `listBranches` — a fresh clone has already downloaded every ref.
+     */
+    onWorkspaceCloned = null;
+    constructor(workspacesRoot, kbRepoUrl, kbDirName, gitUsername = 'x-access-token') {
+        this.workspacesRoot = workspacesRoot;
+        this.kbRepoUrl = kbRepoUrl;
+        this.kbDirName = kbDirName;
+        this.gitUsername = gitUsername;
+    }
+    setDiffService(diffService) {
+        this.diffService = diffService;
+    }
+    setSeedService(seedService) {
+        this.seedService = seedService;
+    }
+    setWorkspaceClonedListener(listener) {
+        this.onWorkspaceCloned = listener;
+    }
+    /** Build git clone args that inject credentials via -c headers so the token never appears in the repo URL. */
+    gitCloneArgs(targetDir, branch, referenceRepo) {
+        const token = process.env.GITHUB_TOKEN;
+        // core.longpaths=true: KB has paths >260 chars; without this the clone silently drops those files on Windows.
+        const args = ['clone', '-c', 'core.longpaths=true', '-b', branch];
+        // Borrow the object database of an existing sibling clone. Every commit
+        // in the KB is already on disk locally, so object transfer drops to
+        // ~zero and a cold branch switch pays only the ref-negotiation
+        // round-trip instead of a full download. `--dissociate` copies the
+        // borrowed objects into the new repo and drops the alternates link, so
+        // the new clone stays independent even if the sibling is later swept
+        // or gc'd. Still a real clone of the real remote — all `refs/remotes/
+        // origin/*` are populated as usual.
+        if (referenceRepo) {
+            args.push('--reference', referenceRepo, '--dissociate');
+        }
+        if (token) {
+            // The helper script reads from GITHUB_TOKEN at runtime — the token value never appears in args.
+            // Username is provider-specific (GitHub `x-access-token`, GitLab `oauth2`, …); the token is
+            // always the Basic-auth password, which every major host accepts.
+            args.push('-c', `credential.helper=!f() { echo "username=${this.gitUsername}"; echo "password=$GITHUB_TOKEN"; }; f`);
+        }
+        args.push(this.kbRepoUrl, targetDir);
+        return args;
+    }
+    /**
+     * Find an existing workspace clone on disk to use as a `--reference` for
+     * a new clone. Any clone of the KB works — they all share the same object
+     * history. Returns the absolute path to the inner repo dir, or null when
+     * no sibling exists (the first branch after a cold start). Scans disk
+     * rather than the in-memory `branchDirs` map so clones that survived a
+     * process restart are still found.
+     */
+    async findSiblingRepo(excludeBranch) {
+        const excludeId = workspaceIdForBranch(excludeBranch);
+        let entries;
+        try {
+            entries = await fs.readdir(this.workspacesRoot, { withFileTypes: true });
+        }
+        catch {
+            return null;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name === excludeId)
+                continue;
+            const repoDir = path.join(this.workspacesRoot, entry.name, this.kbDirName);
+            try {
+                await fs.access(path.join(repoDir, '.git'));
+                return repoDir;
+            }
+            catch {
+                // No `.git` — half-built or unrelated dir; keep looking.
+            }
+        }
+        return null;
+    }
+    /**
+     * Return the id of any workspace already cloned on disk, or null if none
+     * exists. Every clone tracks the same origin, so for a *repo-global* operation
+     * that doesn't act on a particular draft — listing branches, reading or
+     * merging a change request by number — any existing clone is interchangeable.
+     * Reusing one that's already on disk avoids cloning a branch (or failing when
+     * a conventional default branch isn't on the remote) just to run a global op.
+     * Scans disk rather than the in-memory `branchDirs` map so clones that
+     * survived a process restart are still found.
+     */
+    async findAnyWorkspaceId() {
+        let entries;
+        try {
+            entries = await fs.readdir(this.workspacesRoot, { withFileTypes: true });
+        }
+        catch {
+            return null;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                await fs.access(path.join(this.workspacesRoot, entry.name, this.kbDirName, '.git'));
+                return entry.name;
+            }
+            catch {
+                // No `.git` — half-built or unrelated dir; keep looking.
+            }
+        }
+        return null;
+    }
+    /**
+     * Run the clone. When a `referenceRepo` is supplied and the referenced
+     * clone fails (e.g. the sibling's object store is corrupt or mid-write),
+     * fall back once to a plain network clone so a bad sibling can never
+     * block a new branch from bootstrapping.
+     */
+    async runClone(targetDir, branch, referenceRepo) {
+        if (referenceRepo) {
+            try {
+                await execFileAsync('git', this.gitCloneArgs(targetDir, branch, referenceRepo), {
+                    env: { ...process.env },
+                });
+                return;
+            }
+            catch (err) {
+                console.warn(`[workspace] referenced clone for "${branch}" failed, retrying without reference:`, redactError(err));
+                // Clear any partial output so the retry clones into a clean dir.
+                await fs.rm(targetDir, { recursive: true, force: true }).catch(() => { });
+            }
+        }
+        await execFileAsync('git', this.gitCloneArgs(targetDir, branch), {
+            env: { ...process.env },
+        });
+    }
+    /**
+     * Get-or-create the per-branch workspace. Idempotent — repeat calls for
+     * the same branch reuse the existing clone. Concurrent first-callers
+     * share one bootstrap via `inFlightBootstraps`.
+     */
+    async getOrCreateForBranch(branch) {
+        assertValidBranchName(branch);
+        const id = workspaceIdForBranch(branch);
+        const workspaceDir = path.join(this.workspacesRoot, id);
+        const repoDir = path.join(workspaceDir, this.kbDirName);
+        // Fast path: we've already bootstrapped this branch in this process.
+        // Wait for any in-flight bootstrap before returning so we never hand
+        // back a half-cloned workspace.
+        if (this.branchDirs.has(branch)) {
+            await this.awaitBootstrapOrEvict(branch);
+            return this.buildWorkspaceInfo(branch, workspaceDir);
+        }
+        // If a bootstrap is in flight for this branch, wait it out before
+        // trusting the on-disk check below. `git clone` creates `.git` within
+        // the first few hundred ms of a multi-second clone, well before the
+        // working tree (roles.yaml, access.md, every tracked file) is checked
+        // out — so a naive fs.access(.git) on a mid-clone dir happily hands a
+        // half-cloned workspace to the caller, and the next loadModel /
+        // readFile faceplants with ENOENT and 500s. This mirrors the
+        // single-flight wait the cached fast path already uses.
+        await this.awaitBootstrapOrEvict(branch);
+        if (this.branchDirs.has(branch)) {
+            return this.buildWorkspaceInfo(branch, workspaceDir);
+        }
+        // Check disk — the clone may have been bootstrapped by a previous
+        // process and survived a restart.
+        try {
+            await fs.access(path.join(repoDir, '.git'));
+            // Migration for clones already on disk: re-stamp the tracking config the
+            // first time this process opens them, so a clone whose config drifted
+            // (duplicate fetch refspec / merge ref) is repaired before anything
+            // pulls it. Once per branch per process — the cached paths above return
+            // before reaching here.
+            await this.normalizeCloneTracking(repoDir, branch);
+            this.branchDirs.set(branch, workspaceDir);
+            return this.buildWorkspaceInfo(branch, workspaceDir);
+        }
+        catch {
+            // Not on disk — bootstrap below.
+        }
+        // Single-flight bootstrap. Concurrent callers for the same branch
+        // share the first one's promise instead of stacking clones.
+        let resolveBootstrap;
+        let rejectBootstrap;
+        const bootstrap = new Promise((res, rej) => {
+            resolveBootstrap = res;
+            rejectBootstrap = rej;
+        });
+        bootstrap.catch(() => undefined);
+        const existingBootstrap = this.inFlightBootstraps.get(branch);
+        if (existingBootstrap) {
+            await existingBootstrap;
+            this.branchDirs.set(branch, workspaceDir);
+            return this.buildWorkspaceInfo(branch, workspaceDir);
+        }
+        this.inFlightBootstraps.set(branch, bootstrap);
+        try {
+            // Ensure the remote is seeded before the first clone of any branch. A
+            // clone with `-b <branch>` fails outright on an empty remote, so seeding
+            // must happen ahead of it. The seed service is single-flight, so this is
+            // a cheap already-resolved await on every clone after the first.
+            if (this.seedService) {
+                await this.seedService.ensureRemoteSeeded();
+            }
+            await fs.mkdir(workspaceDir, { recursive: true });
+            await this.cloneProcessMapForBranch(workspaceDir, branch);
+            this.branchDirs.set(branch, workspaceDir);
+            resolveBootstrap();
+        }
+        catch (err) {
+            this.branchDirs.delete(branch);
+            rejectBootstrap(err);
+            throw err;
+        }
+        finally {
+            if (this.inFlightBootstraps.get(branch) === bootstrap) {
+                this.inFlightBootstraps.delete(branch);
+            }
+        }
+        return this.buildWorkspaceInfo(branch, workspaceDir);
+    }
+    /**
+     * Convenience: open-or-create the workspace using the caller's user
+     * record only for typing / auditing context. Used by route handlers
+     * that don't know the target branch up-front (e.g. legacy bootstrap
+     * paths). Always resolves to the default protected branch unless
+     * `branch` is passed.
+     */
+    async getOrCreateForUser(_user, branch) {
+        return this.getOrCreateForBranch(branch ?? DEFAULT_BRANCH);
+    }
+    buildWorkspaceInfo(branch, workspaceDir) {
+        return {
+            id: workspaceIdForBranch(branch),
+            name: `${branch}`,
+            absolutePath: workspaceDir,
+            createdAt: new Date(0).toISOString(),
+            kbDirName: this.kbDirName,
+        };
+    }
+    /**
+     * Await the in-flight bootstrap for a branch (if any). On reject —
+     * meaning the clone rolled back — drop the branch→dir mapping so the
+     * next caller re-bootstraps.
+     */
+    async awaitBootstrapOrEvict(branch) {
+        const pending = this.inFlightBootstraps.get(branch);
+        if (!pending)
+            return;
+        try {
+            await pending;
+        }
+        catch (err) {
+            this.branchDirs.delete(branch);
+            throw err;
+        }
+    }
+    /**
+     * Collapse the clone's tracking config to a single fetch refspec and a single
+     * upstream ref for `branch` (see `workflow/git/clone-config.ts`). A clone that
+     * accumulated a second `remote.origin.fetch` refspec or `branch.<b>.merge`
+     * value makes git refuse to refresh it — "Cannot rebase onto multiple
+     * branches" — which is how a post-merge pull of the target branch fails.
+     *
+     * Never throws: it only ever touches `.git/config`, so a failure leaves the
+     * workspace exactly as usable as it was, and the git layer self-heals the
+     * same keys before it pulls.
+     */
+    async normalizeCloneTracking(repoDir, branch) {
+        try {
+            for (const args of cloneTrackingConfigArgs(branch)) {
+                await execFileAsync('git', ['-C', repoDir, ...args]);
+            }
+        }
+        catch (err) {
+            // One line per branch, not per key: every key writes to the same
+            // `.git/config`, so what fails for one fails for all.
+            console.warn(`[workspace] could not normalize the tracking config of the "${branch}" clone:`, redactError(err));
+        }
+    }
+    async cloneProcessMapForBranch(workspaceDir, branch) {
+        const targetDir = path.join(workspaceDir, this.kbDirName);
+        // Probe whether `targetDir` exists. We split the existence check from
+        // the inner `.git` validation so unexpected errors from EITHER probe
+        // propagate to the caller instead of getting silently swallowed by an
+        // outer catch (the previous shape let an inner rethrow fall through
+        // to a clone-into-non-empty-dir, producing a confusing 500).
+        let targetExists = true;
+        try {
+            await fs.access(targetDir);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                targetExists = false;
+            }
+            else {
+                throw err;
+            }
+        }
+        if (targetExists) {
+            // The directory exists, but a previous bootstrap may have crashed
+            // mid-clone — leaving a directory shell without `.git`. Treat
+            // anything missing `.git` as not-cloned and re-clone. (Can't be
+            // an active workspace either: every cloned repo has `.git` from
+            // step one.)
+            let alreadyCloned = false;
+            try {
+                const dotGit = await fs.stat(path.join(targetDir, '.git'));
+                if (dotGit.isDirectory() || dotGit.isFile()) {
+                    alreadyCloned = true;
+                }
+            }
+            catch (err) {
+                // Only treat "does-not-exist" as "half-built dir, wipe and
+                // re-clone". A transient EACCES / EIO / EBUSY must NOT delete
+                // what might be a perfectly valid repo whose `.git` we couldn't
+                // read this moment — surface the error so the caller can retry.
+                const code = err?.code;
+                if (code !== 'ENOENT' && code !== 'ENOTDIR') {
+                    throw err;
+                }
+            }
+            if (alreadyCloned) {
+                // We don't auto-pull because that could clobber another user's
+                // in-progress lock-held edits. The tracking config IS re-stamped —
+                // it never touches the working tree, and a drifted config is what
+                // breaks the next pull.
+                await this.normalizeCloneTracking(targetDir, branch);
+                return;
+            }
+            // Half-built dir — wipe and re-clone.
+            await fs.rm(targetDir, { recursive: true, force: true });
+        }
+        // Borrow an existing sibling clone's objects to skip the bulk download.
+        // Resolved before the clone so a failure mid-clone still rolls back cleanly.
+        const reference = await this.findSiblingRepo(branch);
+        try {
+            await this.runClone(targetDir, branch, reference);
+            // Persist longpaths in the cloned repo's config so subsequent
+            // checkouts also honor it.
+            await execFileAsync('git', ['-C', targetDir, 'config', 'core.longpaths', 'true']);
+            // Generic bot identity for the clone — every workflow commit
+            // overrides via `--author=…` so the real human shows up in
+            // `git log`. This is purely the fallback committer.
+            await execFileAsync('git', ['-C', targetDir, 'config', 'user.name', BOT_NAME]);
+            await execFileAsync('git', ['-C', targetDir, 'config', 'user.email', BOT_EMAIL]);
+            // Pin the clone to exactly one fetch refspec and one upstream ref for
+            // this branch. `git clone -b` already produces that shape; stamping it
+            // explicitly means the shape is asserted rather than assumed, and the
+            // same call is what repairs an existing clone that drifted.
+            await this.normalizeCloneTracking(targetDir, branch);
+            console.log(`[workspace] Cloned ${this.kbDirName} for branch "${branch}"` +
+                (reference ? ' (referenced a sibling clone)' : ''));
+            // A fresh clone has already downloaded every ref — tell the git layer
+            // so the first `listBranches` skips the redundant implicit `git fetch`.
+            // Isolated from the clone-rollback `catch` below: a misbehaving listener
+            // must not cause a successful clone to be wiped.
+            try {
+                this.onWorkspaceCloned?.(workspaceIdForBranch(branch));
+            }
+            catch (listenerErr) {
+                console.error(`[workspace] onWorkspaceCloned listener failed for branch "${branch}":`, redactError(listenerErr));
+            }
+            // Fill in any base scaffolding this branch is missing, now that it's
+            // freshly checked out. Runs on whichever branch the user loaded (not just
+            // protected ones), only on a fresh clone (this block). Isolated in its own
+            // try/catch — like the onWorkspaceCloned listener above — so even a future
+            // change that lets it throw can never roll back an otherwise-good clone.
+            if (this.seedService) {
+                try {
+                    await this.seedService.topUpWorkspace(targetDir, branch);
+                }
+                catch (topUpErr) {
+                    console.error(`[workspace] scaffolding top-up failed for branch "${branch}" (clone kept):`, redactError(topUpErr));
+                }
+            }
+        }
+        catch (err) {
+            const redacted = redactError(err);
+            console.error(`[workspace] Failed to clone for branch "${branch}":`, redacted);
+            // Roll back partial state so the next bootstrap retries cleanly.
+            await fs.rm(targetDir, { recursive: true, force: true }).catch(() => { });
+            throw new Error(`Failed to clone process map: ${redacted}`);
+        }
+    }
+    async getMetadata(workspaceId) {
+        try {
+            const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+            return this.buildWorkspaceInfo(branchForWorkspaceId(workspaceId), workspaceDir);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Delete a branch's workspace directory entirely. Used when a branch is
+     * deleted upstream — frees the disk used by its clone. The branch's git
+     * history on origin is unaffected.
+     */
+    async deleteWorkspace(workspaceId) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        await fs.rm(workspaceDir, { recursive: true, force: true });
+        const branch = branchForWorkspaceId(workspaceId);
+        this.branchDirs.delete(branch);
+    }
+    async listFiles(workspaceId, readFilter) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        return this.buildFileTree(workspaceDir, workspaceDir, BevelIgnoreStack.empty(), readFilter);
+    }
+    async readFile(workspaceId, relativePath) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        return fs.readFile(absolutePath, 'utf-8');
+    }
+    async readFileBinary(workspaceId, relativePath) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        return fs.readFile(absolutePath);
+    }
+    /**
+     * Read every `.md` file under the KB repo in one disk pass, keyed by
+     * repo-root-relative POSIX path (e.g. `Product/NodeTypes/ServiceCommitment.md`)
+     * — the form `parseGraph` keys its file map on. Respects `.git/` and
+     * `.bevelignore` like the file tree, so the iframe's `buildGraph()` sees the
+     * same set the explorer shows. This exists so the HTML renderer can fetch the
+     * whole KB in a single request instead of one HTTP round-trip per file (the
+     * KB is thousands of files; per-file fetching exhausts the browser's
+     * connection pool).
+     */
+    async readAllKbFiles(workspaceId) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const repoRoot = path.join(workspaceDir, this.kbDirName);
+        const files = {};
+        const walk = async (dir, ignoreStack) => {
+            const nextStack = await ignoreStack.extendedWith(dir);
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.name === '.git' && entry.isDirectory())
+                    continue;
+                const childAbs = path.join(dir, entry.name);
+                if (nextStack.isIgnored(childAbs, entry.isDirectory()))
+                    continue;
+                if (entry.isDirectory()) {
+                    await walk(childAbs, nextStack);
+                    continue;
+                }
+                if (!entry.isFile() || !entry.name.endsWith('.md'))
+                    continue;
+                const repoPath = path.relative(repoRoot, childAbs).replace(/\\/g, '/');
+                files[repoPath] = await fs.readFile(childAbs, 'utf-8');
+            }
+        };
+        await walk(repoRoot, BevelIgnoreStack.empty());
+        return files;
+    }
+    /**
+     * Build a zip archive of the folder at `relativePath` and return it as a
+     * single buffer. Mirrors the file-tree's skip rules — `.git/`, `.gitkeep`,
+     * and `.bevelignore`-excluded paths are omitted so the zip matches what
+     * the user sees in the explorer (and so we don't leak the entire git
+     * object database into a download).
+     *
+     * Entry names inside the zip are prefixed with the folder's own name so
+     * unzipping yields `<folderName>/...` rather than spilling files into the
+     * caller's cwd. Throws `FolderTooLargeError` if cumulative uncompressed
+     * size crosses `ZIP_DOWNLOAD_MAX_BYTES`. Buffered in memory (adm-zip has
+     * no streaming API); the cap therefore doubles as a peak-heap bound.
+     */
+    async createFolderZip(workspaceId, relativePath) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absoluteRoot = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absoluteRoot, workspaceDir);
+        const stat = await fs.stat(absoluteRoot);
+        if (!stat.isDirectory()) {
+            throw new Error('Not a directory');
+        }
+        const zipRoot = path.basename(absoluteRoot) || 'folder';
+        const zip = new AdmZip();
+        let totalBytes = 0;
+        const walk = async (dir, ignoreStack) => {
+            const nextStack = await ignoreStack.extendedWith(dir);
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            entries.sort((a, b) => a.name.localeCompare(b.name));
+            for (const entry of entries) {
+                if (entry.name === '.git' && entry.isDirectory())
+                    continue;
+                if (entry.name === '.gitkeep' && entry.isFile())
+                    continue;
+                const childAbs = path.join(dir, entry.name);
+                if (nextStack.isIgnored(childAbs, entry.isDirectory()))
+                    continue;
+                if (entry.isDirectory()) {
+                    await walk(childAbs, nextStack);
+                    continue;
+                }
+                if (!entry.isFile())
+                    continue; // skip sockets, symlinks, etc.
+                // Check the size cap BEFORE reading the file into memory. Reading
+                // first would let a single hostile 2 GB file allocate the whole
+                // buffer before the throw — defeating the cap as a peak-heap
+                // bound. `stat.size` is an upper bound that we re-verify after
+                // the read in case the file grew between stat and readFile.
+                const stat = await fs.stat(childAbs);
+                if (totalBytes + stat.size > ZIP_DOWNLOAD_MAX_BYTES) {
+                    throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
+                }
+                const data = await fs.readFile(childAbs);
+                if (totalBytes + data.byteLength > ZIP_DOWNLOAD_MAX_BYTES) {
+                    throw new FolderTooLargeError(ZIP_DOWNLOAD_MAX_BYTES);
+                }
+                totalBytes += data.byteLength;
+                // Path inside the archive: <folderName>/<relPathUnderFolder>, POSIX
+                // separators regardless of host OS so the zip extracts cleanly
+                // on Windows/Mac/Linux alike.
+                const relInside = path
+                    .relative(absoluteRoot, childAbs)
+                    .replace(/\\/g, '/');
+                zip.addFile(`${zipRoot}/${relInside}`, data);
+            }
+        };
+        await walk(absoluteRoot, BevelIgnoreStack.empty());
+        return zip.toBuffer();
+    }
+    /**
+     * Read a file's contents as it exists on a specific git ref in the
+     * branch's clone. Returns null when the ref or path doesn't exist on that
+     * ref. `relativePath` is relative to the repo root (e.g. `Knowledge/Foo.md`),
+     * NOT to the workspace dir — the repo sits at `<workspaceDir>/knowledge-base`.
+     */
+    async readFileAtRef(workspaceId, ref, relativePath) {
+        this.assertValidGitRef(ref);
+        this.assertValidRepoRelativePath(relativePath);
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const repoDir = path.join(workspaceDir, this.kbDirName);
+        const candidates = [ref];
+        if (!ref.startsWith('origin/') && !ref.startsWith('refs/')) {
+            candidates.push(`origin/${ref}`);
+        }
+        for (const candidate of candidates) {
+            try {
+                const { stdout } = await execFileAsync('git', ['-C', repoDir, 'show', `${candidate}:${relativePath}`], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+                return stdout;
+            }
+            catch {
+                // Try next candidate.
+            }
+        }
+        return null;
+    }
+    /**
+     * Run `git fetch --prune origin` for this branch's clone. Results are
+     * cached for `FETCH_CACHE_TTL_MS`; concurrent callers share the same
+     * in-flight fetch to avoid fetch storms when e.g. the CR list poll fans out.
+     */
+    async ensureRemotesFetched(workspaceId) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const repoDir = path.join(workspaceDir, this.kbDirName);
+        const now = Date.now();
+        const last = this.lastFetchAt.get(repoDir) ?? 0;
+        if (now - last < FETCH_CACHE_TTL_MS)
+            return;
+        const inFlight = this.inFlightFetches.get(repoDir);
+        if (inFlight)
+            return inFlight;
+        // This driver runs outside the git layer's per-workspace mutex, so it may
+        // only run the safe implicit-fetch shape — see `SAFE_IMPLICIT_FETCH_ARGS`
+        // in `workflow/git/clone-config.ts` for the full rationale.
+        const promise = execFileAsync('git', ['-C', repoDir, ...SAFE_IMPLICIT_FETCH_ARGS], { env: { ...process.env } })
+            .then(() => {
+            this.lastFetchAt.set(repoDir, Date.now());
+        })
+            .catch((err) => {
+            console.warn('[workspace] git fetch origin failed:', redactError(err));
+        })
+            .finally(() => {
+            if (this.inFlightFetches.get(repoDir) === promise) {
+                this.inFlightFetches.delete(repoDir);
+            }
+        });
+        this.inFlightFetches.set(repoDir, promise);
+        return promise;
+    }
+    assertValidGitRef(ref) {
+        if (!ref)
+            throw new Error('Git ref is required');
+        if (ref.startsWith('-') || /[\s\0]/.test(ref)) {
+            throw new Error('Invalid git ref');
+        }
+    }
+    assertValidRepoRelativePath(relativePath) {
+        if (!relativePath)
+            throw new Error('Repo-relative path is required');
+        if (relativePath.startsWith('-') || relativePath.includes('\0')) {
+            throw new Error('Invalid repo-relative path');
+        }
+    }
+    async deleteFile(workspaceId, relativePath) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        await fs.rm(absolutePath, { recursive: true, force: true });
+        await this.diffService?.markUserDeleted(workspaceId, relativePath);
+    }
+    /**
+     * Remove the workspace's `tmp/` directory — transient run artifacts (code-mode
+     * tool-chain spills, staged SharePoint docs) that live at the workspace root,
+     * outside the KB git repo, and are never committed. Computes the path directly
+     * from `workspacesRoot` (no bootstrapping) and force-removes, so it's safe to
+     * call after a run even if the workspace was already torn down — a missing
+     * directory is ignored.
+     */
+    async clearTmp(workspaceId) {
+        // Guard against a malicious/odd workspaceId (e.g. "..") escaping the root
+        // and force-removing an unintended directory.
+        const root = path.resolve(this.workspacesRoot);
+        const tmpDir = path.resolve(root, workspaceId, 'tmp');
+        if (!tmpDir.startsWith(root + path.sep)) {
+            throw new Error(`clearTmp: refusing to remove a path outside the workspaces root (workspaceId="${workspaceId}").`);
+        }
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+    async moveEntry(workspaceId, oldRelativePath, newRelativePath) {
+        assertValidRelativePath(newRelativePath);
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const oldAbsolute = path.resolve(workspaceDir, oldRelativePath);
+        const newAbsolute = path.resolve(workspaceDir, newRelativePath);
+        this.assertWithinWorkspace(oldAbsolute, workspaceDir);
+        this.assertWithinWorkspace(newAbsolute, workspaceDir);
+        await fs.mkdir(path.dirname(newAbsolute), { recursive: true });
+        await fs.rename(oldAbsolute, newAbsolute);
+        if (this.diffService) {
+            await this.diffService.markUserDeleted(workspaceId, oldRelativePath);
+            await this.diffService.syncFromDisk(workspaceId, newRelativePath);
+        }
+    }
+    async writeFile(workspaceId, relativePath, content) {
+        assertValidRelativePath(relativePath);
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, content, 'utf-8');
+        await this.diffService?.syncFromDisk(workspaceId, relativePath);
+    }
+    async createDirectory(workspaceId, relativePath) {
+        assertValidRelativePath(relativePath);
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        await fs.mkdir(absolutePath, { recursive: true });
+        const entries = await fs.readdir(absolutePath);
+        if (entries.length === 0) {
+            await fs.writeFile(path.join(absolutePath, '.gitkeep'), '', 'utf-8');
+        }
+    }
+    async writeFileBinary(workspaceId, relativePath, data) {
+        assertValidRelativePath(relativePath);
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const absolutePath = path.resolve(workspaceDir, relativePath);
+        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+        await fs.writeFile(absolutePath, data);
+        await this.diffService?.syncFromDisk(workspaceId, relativePath);
+    }
+    /**
+     * Extract a `.zip` file already present in the workspace into a destination
+     * directory (defaults to the archive's parent directory — "unzip here").
+     * Validation + zip-bomb guards are identical to the per-user version that
+     * preceded the workspace-per-branch migration.
+     */
+    async unzipFile(workspaceId, zipRelativePath, destDirRelativePath, 
+    /**
+     * Per-extracted-path write guard (ontology-session boundary). Called with
+     * each entry's workspace-relative target before it is written; if it throws,
+     * the entry is skipped (with the thrown message as the reason) rather than
+     * aborting the whole extraction. Omitted by non-agent / human callers.
+     */
+    guardWrite) {
+        const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const zipAbsolute = path.resolve(workspaceDir, zipRelativePath);
+        this.assertWithinWorkspace(zipAbsolute, workspaceDir);
+        if (!zipRelativePath.toLowerCase().endsWith('.zip')) {
+            throw new Error('Only .zip files can be extracted');
+        }
+        const inferredDest = (() => {
+            const d = path.posix.dirname(zipRelativePath.replace(/\\/g, '/'));
+            return d === '.' ? '' : d;
+        })();
+        const destRel = destDirRelativePath ?? inferredDest;
+        if (destRel)
+            assertValidRelativePath(destRel);
+        const destAbsolute = destRel ? path.resolve(workspaceDir, destRel) : workspaceDir;
+        this.assertWithinWorkspace(destAbsolute, workspaceDir);
+        let zip;
+        try {
+            zip = new AdmZip(zipAbsolute);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Could not read zip file: ${msg}`);
+        }
+        // The destination directory is created on demand by the first allowed entry
+        // (each guarded path mkdirs its parents with `recursive: true`). Creating it
+        // up front would leave it behind even when every entry is write-blocked.
+        const extracted = [];
+        const skipped = [];
+        let processedCount = 0;
+        let totalUncompressed = 0;
+        for (const entry of zip.getEntries()) {
+            if (processedCount >= UNZIP_MAX_ENTRIES) {
+                skipped.push({
+                    path: entry.entryName,
+                    reason: `Archive exceeds ${UNZIP_MAX_ENTRIES} entries`,
+                });
+                continue;
+            }
+            processedCount++;
+            const rawName = entry.entryName.replace(/\\/g, '/');
+            if (rawName.startsWith('__MACOSX/') ||
+                rawName === '__MACOSX' ||
+                rawName.endsWith('/.DS_Store') ||
+                rawName === '.DS_Store' ||
+                /(^|\/)\._/.test(rawName)) {
+                continue;
+            }
+            if (!rawName || rawName.startsWith('/') || /(^|\/)\.\.($|\/)/.test(rawName)) {
+                skipped.push({ path: rawName || '(empty)', reason: 'Invalid path' });
+                continue;
+            }
+            const trimmed = rawName.replace(/\/+$/, '');
+            const segments = trimmed.split('/').filter((s) => s.length > 0);
+            let invalidReason = null;
+            for (const segment of segments) {
+                const reason = validateFilename(segment);
+                if (reason) {
+                    invalidReason = reason;
+                    break;
+                }
+            }
+            if (invalidReason) {
+                skipped.push({ path: rawName, reason: invalidReason });
+                continue;
+            }
+            const targetAbsolute = path.resolve(destAbsolute, ...segments);
+            const destRoot = path.resolve(destAbsolute);
+            if (targetAbsolute !== destRoot && !targetAbsolute.startsWith(destRoot + path.sep)) {
+                skipped.push({ path: rawName, reason: 'Path escapes destination' });
+                continue;
+            }
+            const relForReport = path
+                .relative(workspaceDir, targetAbsolute)
+                .replace(/\\/g, '/');
+            // Ontology-session boundary: a write-blocked (or cross-ontology) entry is
+            // skipped, not extracted, so an archive can't be a write path around it.
+            // Runs before any filesystem side effect — including directory creation —
+            // so a blocked entry leaves nothing behind on disk.
+            const allowEntry = async () => {
+                if (!guardWrite)
+                    return true;
+                try {
+                    await guardWrite(relForReport);
+                    return true;
+                }
+                catch (err) {
+                    skipped.push({ path: rawName, reason: err instanceof Error ? err.message : 'Blocked by the ontology-session boundary' });
+                    return false;
+                }
+            };
+            if (entry.isDirectory) {
+                if (!(await allowEntry()))
+                    continue;
+                await fs.mkdir(targetAbsolute, { recursive: true });
+                continue;
+            }
+            const declaredSize = entry.header?.size ?? 0;
+            if (declaredSize > UNZIP_MAX_ENTRY_BYTES) {
+                skipped.push({
+                    path: rawName,
+                    reason: `Entry exceeds ${UNZIP_MAX_ENTRY_BYTES} byte per-file limit`,
+                });
+                continue;
+            }
+            if (totalUncompressed + declaredSize > UNZIP_MAX_TOTAL_BYTES) {
+                skipped.push({
+                    path: rawName,
+                    reason: `Archive exceeds ${UNZIP_MAX_TOTAL_BYTES} byte total uncompressed limit`,
+                });
+                continue;
+            }
+            const data = entry.getData();
+            if (data.byteLength > UNZIP_MAX_ENTRY_BYTES) {
+                skipped.push({
+                    path: rawName,
+                    reason: `Entry exceeds ${UNZIP_MAX_ENTRY_BYTES} byte per-file limit`,
+                });
+                continue;
+            }
+            if (totalUncompressed + data.byteLength > UNZIP_MAX_TOTAL_BYTES) {
+                skipped.push({
+                    path: rawName,
+                    reason: `Archive exceeds ${UNZIP_MAX_TOTAL_BYTES} byte total uncompressed limit`,
+                });
+                continue;
+            }
+            if (!(await allowEntry()))
+                continue;
+            await fs.mkdir(path.dirname(targetAbsolute), { recursive: true });
+            await fs.writeFile(targetAbsolute, data);
+            totalUncompressed += data.byteLength;
+            extracted.push(relForReport);
+            await this.diffService?.syncFromDisk(workspaceId, relForReport);
+        }
+        return {
+            destination: path.relative(workspaceDir, destAbsolute).replace(/\\/g, '/') || '.',
+            extracted,
+            skipped,
+        };
+    }
+    async getWorkspacePath(workspaceId) {
+        return this.resolveWorkspaceDir(workspaceId);
+    }
+    /**
+     * True when `workspaceId` already has a bootstrapped clone — either in the
+     * in-process cache or persisted on disk — WITHOUT triggering the lazy
+     * bootstrap that `resolveWorkspaceDir` does. Lets best-effort callers
+     * (e.g. chat-upload staging) refuse to clone an arbitrary branch supplied
+     * in a request body. Per-branch access itself is open by design, so this is
+     * an IO guard, not an ownership check.
+     */
+    async hasBootstrappedWorkspace(workspaceId) {
+        if (!workspaceId)
+            return false;
+        let branch;
+        try {
+            branch = branchForWorkspaceId(workspaceId);
+        }
+        catch {
+            return false;
+        }
+        if (this.branchDirs.has(branch))
+            return true;
+        let workspaceDir;
+        try {
+            workspaceDir = this.workspaceDirWithinRoot(workspaceId);
+        }
+        catch {
+            return false;
+        }
+        try {
+            await fs.access(path.join(workspaceDir, this.kbDirName, '.git'));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Enumerate every branch this process has bootstrapped a workspace for.
+     * Used by the `PendingCommitsWorker` to know which workspaces to poll
+     * and by `startupReconcile` to know which workspaces to scan for
+     * orphan files. The returned descriptors match the worker's
+     * `WorkspaceProvider` contract — id + branch in one struct, no need
+     * for the caller to re-encode.
+     *
+     * The cache is populated lazily as `getOrCreateForBranch` resolves, so
+     * a freshly-touched branch shows up here within the same poll cycle
+     * that resolved its bootstrap.
+     */
+    knownWorkspaces() {
+        return Array.from(this.branchDirs.keys()).map((branch) => ({
+            id: workspaceIdForBranch(branch),
+            branch,
+        }));
+    }
+    /**
+     * Walk the working tree of `workspaceId`'s clone and return every
+     * path `git status --porcelain=v1` reports as dirty (untracked,
+     * modified, or staged). Used by `PendingCommitsService.startupReconcile`
+     * to enqueue commits for files left orphaned by a prior process
+     * crash — under save=share + the pending-commits queue the working
+     * tree should never be dirty in steady state, so anything reported
+     * here is recovery material.
+     *
+     * Paths are workspace-relative (`<kbDirName>/<repo-relative>`), matching
+     * the form `releaseLock` expects.
+     *
+     * Returns an empty array if the workspace dir isn't yet bootstrapped
+     * or the repo dir is missing; the worker treats that as "nothing to
+     * recover here" and moves on.
+     */
+    async scanOrphanedPaths(workspaceId) {
+        let repoDir;
+        try {
+            const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+            repoDir = path.join(workspaceDir, this.kbDirName);
+            // Confirm the inner repo dir actually exists — getOrCreateForBranch
+            // may have failed mid-bootstrap and we'd otherwise hit a confusing
+            // git error here.
+            await fs.access(path.join(repoDir, '.git'));
+        }
+        catch {
+            return [];
+        }
+        let stdout;
+        try {
+            ({ stdout } = await execFileAsync('git', ['-C', repoDir, 'status', '--porcelain=v1', '-z'], {
+                encoding: 'utf-8',
+                maxBuffer: 16 * 1024 * 1024,
+            }));
+        }
+        catch (err) {
+            console.warn(`[workspace] orphan scan via git status failed for ${workspaceId}:`, err instanceof Error ? err.message : err);
+            return [];
+        }
+        if (!stdout.trim())
+            return [];
+        // `-z` separates entries with NUL and skips quoting; renames use a
+        // second NUL-terminated field for the original path which we ignore.
+        const entries = stdout.split('\0').filter((s) => s.length > 0);
+        const out = [];
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            // First 3 chars are status codes; the rest is the path.
+            if (entry.length < 4)
+                continue;
+            const code = entry.slice(0, 2);
+            const repoRelative = entry.slice(3);
+            // Renames + copies carry the original path as the next NUL-separated
+            // field. Skip it — we want the new path only.
+            if (code[0] === 'R' || code[0] === 'C') {
+                i += 1;
+            }
+            out.push({ path: `${this.kbDirName}/${repoRelative}` });
+        }
+        return out;
+    }
+    /**
+     * Remove on-disk workspace dirs whose branches aren't in `knownBranches`.
+     * Handles two drift sources:
+     *   - Branch deleted on origin while the backend was offline (no live
+     *     `deleteBranch` call ran, so the clone wasn't cleaned up).
+     *   - Local-only experimentation (a branch that never made it to origin).
+     *
+     * `knownBranches` is the set of branch names the caller considers
+     * authoritative — typically the union of local + remote branches from
+     * a recent `git for-each-ref` against one of the live clones.
+     *
+     * Best-effort: removal failures are logged and swallowed so one stuck
+     * directory doesn't poison the whole sweep. Returns the set of removed
+     * workspace ids so callers can log / report cleanup activity.
+     */
+    async sweepOrphanedWorkspaces(knownBranches) {
+        const validIds = new Set();
+        for (const b of knownBranches)
+            validIds.add(workspaceIdForBranch(b));
+        let entries;
+        try {
+            entries = await fs.readdir(this.workspacesRoot, { withFileTypes: true });
+        }
+        catch {
+            return { removed: [] };
+        }
+        const removed = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (validIds.has(entry.name))
+                continue;
+            // Skip dirs that don't look like an encoded workspace id — third-
+            // party tooling sometimes drops scratch dirs alongside ours.
+            try {
+                decodeURIComponent(entry.name);
+            }
+            catch {
+                continue;
+            }
+            const dir = path.join(this.workspacesRoot, entry.name);
+            try {
+                await fs.rm(dir, { recursive: true, force: true });
+                this.branchDirs.delete(branchForWorkspaceId(entry.name));
+                removed.push(entry.name);
+            }
+            catch (err) {
+                console.warn(`[workspace] sweep failed for ${entry.name}:`, err instanceof Error ? err.message : err);
+            }
+        }
+        return { removed };
+    }
+    /**
+     * Resolve a workspace id to its on-disk directory. `workspaceId` is
+     * `encodeURIComponent(branch)` — the decoded branch is the in-memory
+     * cache key, the encoded form is the disk directory name.
+     *
+     * Resolution order:
+     *   1. In-process cache (`branchDirs`) — bootstrap completed earlier this
+     *      run, or a prior `resolveWorkspaceDir` populated it from disk.
+     *   2. On-disk lookup — the directory may persist across container
+     *      restarts; if `<id>/<kbDirName>/.git` is there, register and return.
+     *   3. **Lazy bootstrap** — clone the branch on demand via
+     *      `getOrCreateForBranch`. Without this, any frontend route that
+     *      hits `/api/workspace/:id/workflow/...` for a branch the user
+     *      hasn't explicitly bootstrapped via `GET /api/workspace?branch=…`
+     *      would 500 with "Invalid workspace ID" (real symptom in dev:
+     *      `listBranches` / `branch-status` failing right after container
+     *      start because the frontend's parallel calls race the initial
+     *      bootstrap). Bootstrap is single-flight so concurrent racers
+     *      share one clone. A bogus branch name surfaces the underlying
+     *      `BranchNameError` / clone failure verbatim — much more useful
+     *      than the old generic "Invalid workspace ID".
+     *
+     * Cold-cache cost: a mid-request clone is multi-second. Subsequent
+     * requests use the cache. Acceptable since it only happens once per
+     * branch per container lifetime.
+     */
+    /**
+     * Resolve `<workspacesRoot>/<workspaceId>` and assert it stays under the
+     * root. `workspaceId` is expected to be `encodeURIComponent(branch)`, but a
+     * malformed caller value (e.g. `..`) could otherwise escape the root before
+     * the `.git` probe runs. Mirrors `clearTmp`'s containment guard.
+     */
+    workspaceDirWithinRoot(workspaceId) {
+        const root = path.resolve(this.workspacesRoot);
+        const dir = path.resolve(root, workspaceId);
+        if (dir !== root && !dir.startsWith(root + path.sep)) {
+            throw new Error(`Invalid workspace ID "${workspaceId}": path escapes the workspaces root.`);
+        }
+        return dir;
+    }
+    async resolveWorkspaceDir(workspaceId) {
+        if (!workspaceId)
+            throw new Error('Invalid workspace ID');
+        const branch = branchForWorkspaceId(workspaceId);
+        if (this.branchDirs.has(branch)) {
+            return this.branchDirs.get(branch);
+        }
+        // Wait for any in-flight bootstrap before trusting the on-disk check.
+        // `git clone` creates `.git` early in a multi-second clone, before the
+        // working tree files (roles.yaml, etc.) are checked out — so a naive
+        // fs.access(.git) on a mid-clone dir returns "ready" and the caller's
+        // next readFile faceplants with ENOENT and a 500. Mirrors the
+        // single-flight wait inside `getOrCreateForBranch`.
+        await this.awaitBootstrapOrEvict(branch).catch(() => undefined);
+        if (this.branchDirs.has(branch)) {
+            return this.branchDirs.get(branch);
+        }
+        const workspaceDir = this.workspaceDirWithinRoot(workspaceId);
+        try {
+            await fs.access(path.join(workspaceDir, this.kbDirName, '.git'));
+            this.branchDirs.set(branch, workspaceDir);
+            return workspaceDir;
+        }
+        catch {
+            // Fall through to lazy bootstrap.
+        }
+        try {
+            await this.getOrCreateForBranch(branch);
+            const dir = this.branchDirs.get(branch);
+            if (dir)
+                return dir;
+            // Bootstrap reported success but didn't register — defensive fallback.
+            return workspaceDir;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new Error(`Invalid workspace ID "${workspaceId}": ${reason}`);
+        }
+    }
+    assertWithinWorkspace(absolutePath, workspaceDir) {
+        const resolved = path.resolve(absolutePath);
+        const root = path.resolve(workspaceDir);
+        if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+            throw new Error('Path traversal detected');
+        }
+    }
+    async buildFileTree(dir, workspaceRoot, parentIgnore, readFilter) {
+        const name = path.basename(dir);
+        const relativePath = path.relative(workspaceRoot, dir).replace(/\\/g, '/');
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        const ignoreStack = await parentIgnore.extendedWith(dir);
+        // First pass: the entries surviving `.git`/`.gitkeep` + `.bevelignore`.
+        const candidates = [];
+        for (const entry of entries) {
+            // `.git/` is never user content and listing it would blow up the
+            // tree response. `.gitkeep` is the empty-folder placeholder — not
+            // worth surfacing in the file list.
+            if (entry.name === '.git' && entry.isDirectory())
+                continue;
+            if (entry.name === '.gitkeep' && entry.isFile())
+                continue;
+            const entryPath = path.join(dir, entry.name);
+            if (ignoreStack.isIgnored(entryPath, entry.isDirectory()))
+                continue;
+            candidates.push({
+                entry,
+                entryPath,
+                rel: path.relative(workspaceRoot, entryPath).replace(/\\/g, '/'),
+            });
+        }
+        // Read-permission filter: ONE batched check per directory. Drops files AND
+        // directories the caller can't read; a hidden directory's subtree is never
+        // walked (skip-and-don't-recurse). A readable directory left empty after
+        // filtering stays visible (the folder itself is readable). Fail-closed:
+        // anything not explicitly readable is dropped. No filter → identical to the
+        // pre-feature tree (regression-safe).
+        let visible = candidates;
+        if (readFilter && candidates.length > 0) {
+            const verdict = await readFilter(candidates.map((c) => c.rel));
+            visible = candidates.filter((c) => verdict.get(c.rel) === true);
+        }
+        const children = [];
+        for (const { entry, entryPath, rel } of visible) {
+            if (entry.isDirectory()) {
+                children.push(await this.buildFileTree(entryPath, workspaceRoot, ignoreStack, readFilter));
+            }
+            else {
+                children.push({ name: entry.name, relativePath: rel, type: 'file' });
+            }
+        }
+        children.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type === 'directory' ? -1 : 1;
+            return a.name.localeCompare(b.name);
+        });
+        return {
+            name,
+            relativePath: relativePath || '.',
+            type: 'directory',
+            children,
+        };
+    }
+}
+//# sourceMappingURL=workspace.service.js.map